Something went wrong. Try again.
A URI parser and formatter for Zig, modelled on Python's hyperlink package, with LDAP URLs, file: URIs and sdns:// DNS stamps beside it.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! `data:` URLs (RFC 2397).//!//! A data URL carries a document in the URL itself: `data:image/png;base64,//! iVBORw0KGgo...` is a PNG. It has no hierarchy -- no authority, no path//! segments -- and its body is whatever bytes the document is, which in base64//! are full of `/` and `+`. `Uri.parse` reads it as a URI like any other and//! so splits a base64 body into path segments at every `/`; this is a parser//! of its own that sees the structure RFC 2397 gives it instead.//!//! ```zig//! const url = try uri.data.Url.parse(alloc, "data:text/plain;charset=utf-8;base64,aMOpbGxv");//! defer url.deinit();//!//! url.media_type.? // "text/plain"//! url.parameter("charset").? // "utf-8"//! url.base64 // true//! url.data // "héllo", decoded//! ```//!//! The grammar, from RFC 2397 §3://!//! ```text//! dataurl := "data:" [ mediatype ] [ ";base64" ] "," data//! mediatype := [ type "/" subtype ] *( ";" parameter )//! data := *urlchar//! parameter := attribute "=" value//! ```//!//! Every piece but the comma is optional. With no media type the default is//! `text/plain;charset=US-ASCII`, which `effectiveMediaType` and//! `effectiveCharset` apply; the fields hold exactly what was written.//!//! As elsewhere in this library, what is stored is decoded -- `data` is the//! document itself, percent-decoding and then base64 undone -- and writing//! encodes again. Splitting happens before decoding, so a `%2C` in a//! parameter's value is a comma in the value rather than the end of the//! header.
const std = @import("std");
const parse_mod = @import("parse.zig");const percent = @import("percent.zig");
const Allocator = std.mem.Allocator;const Writer = std.Io.Writer;
pub const Error = error{ /// The text does not begin with the `data:` scheme. NotADataUrl, /// There is no `,` ending the header, and so no data at all. MissingComma, /// A parameter has no `=`, as in `data:text/plain;charset,hi`. InvalidParameter, /// The URL says `;base64` and its data is not base64. InvalidBase64,} || percent.Error || Allocator.Error;
/// One `attribute=value` of the media type, both decoded.pub const Parameter = struct { name: []const u8, value: []const u8,
pub fn eql(a: Parameter, b: Parameter) bool { return std.ascii.eqlIgnoreCase(a.name, b.name) and std.mem.eql(u8, a.value, b.value); }};
/// A parsed data URL.////// Owns an arena holding all of its strings, so every accessor is/// allocation-free; `deinit` frees the lot.pub const Url = struct { arena: *std.heap.ArenaAllocator,
/// `type/subtype`, as written. Null when none was written, which means /// `text/plain`. media_type: ?[]const u8 = null, /// The media type's parameters, in order. parameters: []const Parameter = &.{}, /// Whether the data was written in base64. base64: bool = false, /// The document: the data, percent-decoded, and base64-decoded if /// `base64`. data: []const u8 = "", /// What followed a `#`, decoded, if anything did. A data URL is a URI and /// may have one, though RFC 2397 says nothing of what it would mean. fragment: ?[]const u8 = null,
pub const ParseOptions = parse_mod.Options;
// -- construction ------------------------------------------------------
pub fn parse(alloc: Allocator, text: []const u8) Error!Url { return parseOpts(alloc, text, .{}); }
pub fn parseOpts(alloc: Allocator, text: []const u8, opts: ParseOptions) Error!Url { const arena = try alloc.create(std.heap.ArenaAllocator); arena.* = .init(alloc); errdefer destroyArena(arena); return parseInto(arena, text, opts); }
pub fn deinit(self: Url) void { destroyArena(self.arena); }
// -- inspection --------------------------------------------------------
/// The media type, defaulting to `text/plain` (RFC 2397 §2). pub fn effectiveMediaType(self: Url) []const u8 { return self.media_type orelse "text/plain"; }
/// The first parameter named `name`, matched case-insensitively as MIME /// parameter names are (RFC 2045 §5.1). pub fn parameter(self: Url, name: []const u8) ?[]const u8 { for (self.parameters) |p| { if (std.ascii.eqlIgnoreCase(p.name, name)) return p.value; } return null; }
/// The character set, when the media type is text: the `charset` /// parameter, defaulting to `US-ASCII` when no media type was written at /// all (RFC 2397 §2). Null for a media type that names none. pub fn effectiveCharset(self: Url) ?[]const u8 { if (self.parameter("charset")) |c| return c; return if (self.media_type == null) "US-ASCII" else null; }
pub fn eql(self: Url, other: Url) bool { if (!optEqlStrIgnoreCase(self.media_type, other.media_type)) return false; if (self.parameters.len != other.parameters.len) return false; for (self.parameters, other.parameters) |a, b| { if (!a.eql(b)) return false; } if (self.base64 != other.base64) return false; if (!std.mem.eql(u8, self.data, other.data)) return false; if ((self.fragment == null) != (other.fragment == null)) return false; if (self.fragment) |f| if (!std.mem.eql(u8, f, other.fragment.?)) return false; return true; }
// -- text --------------------------------------------------------------
/// Write the URL to `w`: the data base64-encoded again if it was, and /// percent-encoded as little as it can be otherwise. pub fn write(self: Url, w: *Writer) Writer.Error!void { try w.writeAll("data:"); if (self.media_type) |m| try percent.encode(w, m, &media_type_set); for (self.parameters) |p| { try w.writeByte(';'); try percent.encode(w, p.name, ¶meter_set); try w.writeByte('='); try percent.encode(w, p.value, ¶meter_set); } if (self.base64) try w.writeAll(";base64"); try w.writeByte(','); if (self.base64) { try std.base64.standard.Encoder.encodeWriter(w, self.data); } else { try percent.encode(w, self.data, &data_set); } if (self.fragment) |f| { try w.writeByte('#'); try percent.encode(w, f, &percent.fragment); } }
/// Render to a fresh slice owned by the caller. pub fn toText(self: Url, alloc: Allocator) Allocator.Error![]u8 { var aw: Writer.Allocating = .init(alloc); errdefer aw.deinit(); self.write(&aw.writer) catch |err| switch (err) { error.WriteFailed => return error.OutOfMemory, }; return aw.toOwnedSlice(); }
/// `std.fmt` support: `{f}` renders the URL. pub fn format(self: Url, w: *Writer) Writer.Error!void { return self.write(w); }};
// -- character sets --------------------------------------------------------
/// `;` starts a parameter and `,` ends the header; `/` stays, between type/// and subtype.const media_type_set: percent.CharSet = percent.charSet(.{ .add = percent.unreserved_punct ++ percent.sub_delims ++ ":@/+", .sub = ";," });
/// `=` splits a parameter as well.const parameter_set: percent.CharSet = percent.charSet(.{ .add = percent.unreserved_punct ++ percent.sub_delims ++ ":@/", .sub = ";,=" });
/// Anything a fragment may hold: after the header's `,` nothing but `#` ends/// the data.const data_set: percent.CharSet = percent.fragment;
// -- internals -------------------------------------------------------------
fn destroyArena(arena: *std.heap.ArenaAllocator) void { const alloc = arena.child_allocator; arena.deinit(); alloc.destroy(arena);}
fn optEqlStrIgnoreCase(a: ?[]const u8, b: ?[]const u8) bool { if (a == null or b == null) return (a == null) == (b == null); return std.ascii.eqlIgnoreCase(a.?, b.?);}
fn parseInto(arena: *std.heap.ArenaAllocator, text: []const u8, opts: Url.ParseOptions) Error!Url { const alloc = arena.allocator(); const scheme = "data:"; if (text.len < scheme.len or !std.ascii.eqlIgnoreCase(text[0..scheme.len], scheme)) return error.NotADataUrl; var rest = text[scheme.len..];
var url: Url = .{ .arena = arena }; if (std.mem.findScalar(u8, rest, '#')) |hash| { url.fragment = try percent.decode(alloc, rest[hash + 1 ..], opts.strict_percent); rest = rest[0..hash]; }
const comma = std.mem.findScalar(u8, rest, ',') orelse return error.MissingComma; const header = rest[0..comma]; const body = rest[comma + 1 ..];
// The header's sections, split before anything is decoded: the media // type first, if it is one, then parameters, and last, perhaps, `base64`. var sections: std.ArrayList([]const u8) = .empty; var it = std.mem.splitScalar(u8, header, ';'); while (it.next()) |s| try sections.append(alloc, s); var list = sections.items; if (list.len > 1 and std.ascii.eqlIgnoreCase(list[list.len - 1], "base64")) { url.base64 = true; list = list[0 .. list.len - 1]; } if (list.len > 0) { if (list[0].len > 0) url.media_type = try percent.decode(alloc, list[0], opts.strict_percent); list = list[1..]; } var params: std.ArrayList(Parameter) = .empty; for (list) |s| { const eq = std.mem.findScalar(u8, s, '=') orelse return error.InvalidParameter; if (eq == 0) return error.InvalidParameter; try params.append(alloc, .{ .name = try percent.decode(alloc, s[0..eq], opts.strict_percent), .value = try percent.decode(alloc, s[eq + 1 ..], opts.strict_percent), }); } url.parameters = params.items;
const decoded = try percent.decode(alloc, body, opts.strict_percent); url.data = if (url.base64) try base64Decode(alloc, decoded) else decoded; return url;}
/// Standard base64, with or without its padding, and ignoring the line/// breaks and spaces that a data URL copied out of a document picks up.fn base64Decode(alloc: Allocator, text: []const u8) Error![]const u8 { var compact: std.ArrayList(u8) = try .initCapacity(alloc, text.len); for (text) |c| switch (c) { ' ', '\t', '\r', '\n' => {}, else => compact.appendAssumeCapacity(c), }; const clean = compact.items; const decoder = if (clean.len % 4 == 0) std.base64.standard.Decoder else std.base64.standard_no_pad.Decoder; const len = decoder.calcSizeForSlice(clean) catch return error.InvalidBase64; const out = try alloc.alloc(u8, len); decoder.decode(out, clean) catch return error.InvalidBase64; return out;}
const testing = std.testing;
test "the example of RFC 2397 section 4" { const url = try Url.parse(testing.allocator, "data:,A%20brief%20note"); defer url.deinit(); try testing.expectEqual(@as(?[]const u8, null), url.media_type); try testing.expectEqualStrings("text/plain", url.effectiveMediaType()); try testing.expectEqualStrings("US-ASCII", url.effectiveCharset().?); try testing.expect(!url.base64); try testing.expectEqualStrings("A brief note", url.data);}
test "a media type with parameters, in base64 with slashes of its own" { // 0xff 0xfe 0xfd is "//79": slashes a generic parser would split at. const url = try Url.parse(testing.allocator, "data:application/octet-stream;name=blob;base64,//79"); defer url.deinit(); try testing.expectEqualStrings("application/octet-stream", url.media_type.?); try testing.expectEqualStrings("blob", url.parameter("NAME").?); try testing.expectEqual(@as(?[]const u8, null), url.effectiveCharset()); try testing.expect(url.base64); try testing.expectEqualSlices(u8, &.{ 0xff, 0xfe, 0xfd }, url.data);}
test "parameters with no media type, and a comma kept by escaping" { const url = try Url.parse(testing.allocator, "data:;charset=utf-8;note=a%2Cb,h%C3%A9"); defer url.deinit(); try testing.expectEqual(@as(?[]const u8, null), url.media_type); try testing.expectEqualStrings("utf-8", url.effectiveCharset().?); try testing.expectEqualStrings("a,b", url.parameter("note").?); try testing.expectEqualStrings("h\u{e9}", url.data);}
test "base64 without padding, broken over lines" { const url = try Url.parse(testing.allocator, "data:text/plain;base64,aGVs\nbG8"); defer url.deinit(); try testing.expectEqualStrings("hello", url.data);}
test "the scheme is matched without regard to case, and a fragment is kept" { const url = try Url.parse(testing.allocator, "DATA:text/plain,hi#top"); defer url.deinit(); try testing.expectEqualStrings("hi", url.data); try testing.expectEqualStrings("top", url.fragment.?);}
test "what is not a data URL" { try testing.expectError(error.NotADataUrl, Url.parse(testing.allocator, "https://example.com/a.png")); try testing.expectError(error.MissingComma, Url.parse(testing.allocator, "data:text/plain;base64")); try testing.expectError(error.InvalidParameter, Url.parse(testing.allocator, "data:text/plain;charset,hi")); try testing.expectError(error.InvalidBase64, Url.parse(testing.allocator, "data:;base64,!!!!"));}
test "written back, and read again, a data URL is the same" { const cases = [_][]const u8{ "data:,A%20brief%20note", "data:image/svg+xml;base64,PHN2Zy8+", "data:;charset=utf-8;note=a%2Cb,h%C3%A9", "data:application/octet-stream;base64,//79#frag", }; for (cases) |text| { const url = try Url.parse(testing.allocator, text); defer url.deinit(); const again_text = try url.toText(testing.allocator); defer testing.allocator.free(again_text); const again = try Url.parse(testing.allocator, again_text); defer again.deinit(); try testing.expect(url.eql(again)); }}