// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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)); } }