diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-09-25 22:57:24 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-02 21:38:24 -0400 |
| commit | 483c14bf6cc284710e06c9d27747e1ecf5d9466b (patch) | |
| tree | 7ff1513f2e0db2312e131dfb2899a99a3a347634 /dlang | |
| parent | test: the fixture indented its property lines, so none were read (diff) | |
a third input form: the abstraction out of a pod archive
A pod built with --pod2 carries the abstraction inside it, at
media/abstraction/<uid>.<lang>.ssp. So ocda.load gains .sisupod and .zip,
and because the dispatch is in one place a writer over the library gained
a third input form without being touched.
Over the reference collection a .sisupod gives the same model as the .ssp
beside it: 36 of 36 document-languages, byte identical dumps. And the
text writer, unchanged, renders a document from its .sisupod byte
identically to spine --text, 36 of 36.
Two small readers, neither of them a library: ocda.zstd declares the four
libzstd entry points needed to unwrap a frame, as ocda.sqlite declares
sqlite3; ocda.zip reads a central directory and one stored entry. Deflate
is refused rather than mishandled, since spine writes stored entries and
a library that says it read what it skipped is worse than one that says
it cannot. A frame that declares an expansion over 512 MiB is refused
before anything is allocated: a reader of an artefact it did not make
declines to be told how much memory to take.
The Gleam library reads the zip and not the frame. The only zstd on the
BEAM is a NIF that clones zstd from github in its own build, so it cannot
be built sandboxed without patching it. A .zip pod is read in both
languages, a .sisupod in D only, and the Gleam refusal says why and says
"zstd -d" rather than claiming the file is malformed. It is a packaging
limit, not anything about the format, and the only place the two
libraries differ in what they accept.
A pod without an abstraction is refused with a message naming the flag
that puts one in, because that is a fact about the pod.
(assisted by Claude-Code)
Diffstat (limited to 'dlang')
| -rw-r--r-- | dlang/dub.json | 2 | ||||
| -rw-r--r-- | dlang/flake.nix | 6 | ||||
| -rw-r--r-- | dlang/src/ocda/load.d | 17 | ||||
| -rw-r--r-- | dlang/src/ocda/load_pod.d | 115 | ||||
| -rw-r--r-- | dlang/src/ocda/zip.d | 115 | ||||
| -rw-r--r-- | dlang/src/ocda/zstd.d | 79 |
6 files changed, 327 insertions, 7 deletions
diff --git a/dlang/dub.json b/dlang/dub.json index f49ef85..373e5bd 100644 --- a/dlang/dub.json +++ b/dlang/dub.json @@ -9,5 +9,5 @@ "targetType": "library", "sourcePaths": [ "./src" ], "importPaths": [ "./src" ], - "libs": [ "sqlite3" ] + "libs": [ "sqlite3", "zstd" ] } diff --git a/dlang/flake.nix b/dlang/flake.nix index 26dbe2d..2ad3b1c 100644 --- a/dlang/flake.nix +++ b/dlang/flake.nix @@ -21,11 +21,11 @@ version = "0.1.0"; src = self; nativeBuildInputs = [ compiler ]; - buildInputs = [ pkgs.sqlite ]; + buildInputs = [ pkgs.sqlite pkgs.zstd ]; buildPhase = '' runHook preBuild export HOME=$TMPDIR - ${compilerBin} -I=src -of=${tool} src/ocda/*.d test/${tool}.d -L-lsqlite3 + ${compilerBin} -I=src -of=${tool} src/ocda/*.d test/${tool}.d -L-lsqlite3 -L-lzstd runHook postBuild ''; installPhase = '' @@ -57,7 +57,7 @@ }; devShells.${system}.default = pkgs.mkShell { - packages = [ pkgs.ldc pkgs.dub pkgs.dtools pkgs.sqlite ]; + packages = [ pkgs.ldc pkgs.dub pkgs.dtools pkgs.sqlite pkgs.zstd ]; }; }; } diff --git a/dlang/src/ocda/load.d b/dlang/src/ocda/load.d index 0f630bc..89c8dcc 100644 --- a/dlang/src/ocda/load.d +++ b/dlang/src/ocda/load.d @@ -17,16 +17,24 @@ import std.algorithm : endsWith; import ocda.model; import ocda.load_ssp; import ocda.load_db; +import ocda.load_pod; enum Source { ssp, // .ssp, the abstraction as text ocda_db, // .ocda.db, the abstraction as sqlite + pod, // .sisupod or .zip, an archive carrying a .ssp unknown, } Source sourceOf(string path) { if (path.endsWith(".ocda.db")) { return Source.ocda_db; } if (path.endsWith(".ssp")) { return Source.ssp; } + /+ ↓ .sisupod is the archive spine writes now; .zip is what it wrote + before, and every pod already published carries that name, so both + are read. What is inside decides how it is opened, not the name. + +/ + if (path.endsWith(".sisupod")) { return Source.pod; } + if (path.endsWith(".zip")) { return Source.pod; } if (path.endsWith(".db")) { return Source.ocda_db; } return Source.unknown; } @@ -35,6 +43,7 @@ string sourceName(Source s) { final switch (s) { case Source.ssp: return ".ssp (the abstraction as text)"; case Source.ocda_db: return ".ocda.db (the abstraction as sqlite)"; + case Source.pod: return "a pod archive carrying a .ssp"; case Source.unknown: return "not an abstraction this library reads"; } } @@ -44,15 +53,17 @@ class OcdaLoadError : Exception { } /+ ↓ load whatever the path is into the model. - lang applies only to a .ocda.db, which holds every language of its - document; a .ssp is one language and the argument is ignored. + lang names which language to take from a .ocda.db, which holds + every language of its document, and from a pod, which may carry more + than one .ssp. A .ssp is one language by construction and ignores it. +/ OcdaDocument load(string path, string lang = "", bool any_version = false) { final switch (sourceOf(path)) { case Source.ssp: return parseSspFile(path); case Source.ocda_db: return loadDbFile(path, lang, any_version); + case Source.pod: return loadPodFile(path, lang); case Source.unknown: throw new OcdaLoadError(path ~ ": " ~ sourceName(Source.unknown) - ~ " (expected .ssp or .ocda.db)"); + ~ " (expected .ssp, .ocda.db, .sisupod or .zip)"); } } diff --git a/dlang/src/ocda/load_pod.d b/dlang/src/ocda/load_pod.d new file mode 100644 index 0000000..75993be --- /dev/null +++ b/dlang/src/ocda/load_pod.d @@ -0,0 +1,115 @@ +module ocda.load_pod; + +/+ ↓ the abstraction out of a pod archive. + . + A .sisupod is one zstd frame wrapping a stored zip; a .zip is the same + archive unwrapped, which is what spine published before it wrapped them. + Either way, a pod built with --pod2 carries the abstraction inside it, + at media/abstraction/<uid>.<lang>.ssp, and that is what is read. + . + So this is a third input form and *not* a third model: the .ssp inside + is parsed by ocda.load_ssp and comes back as the same value. A writer + over the library gains .sisupod without being touched, which is the + whole reason the dispatch is in one place. + . + A pod built without --pod2 carries markup and no abstraction. That is + refused, and the refusal says which flag makes a pod this reader can + read, because "no abstraction in it" is a fact about the pod rather + than about the reader. ++/ + +import std.algorithm : endsWith, sort; +import std.array : array; +import std.file : read; +import std.string : indexOf; +import ocda.model; +import ocda.load_ssp; +import ocda.zip; +import ocda.zstd; + +/+ ↓ a limit on what a frame may expand to. + A reader of an artefact it did not make declines to be told how much + memory to allocate. 512 MiB is far above the largest pod in the + reference collection (4 MiB) and far below anything that matters. ++/ +enum size_t max_pod_size = 512 * 1024 * 1024; + +class OcdaPodError : Exception { + this(string msg) { super(msg); } +} + +/+ ↓ which languages of the abstraction the pod carries, in sorted order +/ +string[] podLanguages(string path) { + auto bytes = archiveBytes(path); + string[] out_; + foreach (e; zipFindSuffix(zipEntries(bytes), ".ssp")) { + string lang = langOfSspName(e.name); + if (lang.length > 0) { out_ ~= lang; } + } + return out_.sort.array; +} + +/+ ↓ load one language of the abstraction a pod carries. + lang == "" takes the only one there is, and where there is a choice it + says so rather than choosing, as the .ocda.db loader does. ++/ +OcdaDocument loadPodFile(string path, string lang = "") { + auto bytes = archiveBytes(path); + auto entries = zipEntries(bytes); + auto ssps = zipFindSuffix(entries, ".ssp"); + if (ssps.length == 0) { + throw new OcdaPodError(path ~ ": carries no .ssp." + ~ " A pod carries the abstraction only when spine was asked for it:" + ~ " spine --pod2 puts it in, spine --source does not."); + } + ZipEntry chosen = ssps[0]; + if (lang.length > 0) { + bool found = false; + foreach (e; ssps) { + if (langOfSspName(e.name) == lang) { chosen = e; found = true; break; } + } + if (!found) { + string have; + foreach (i, e; ssps) { + have ~= (i > 0 ? " " : "") ~ langOfSspName(e.name); + } + throw new OcdaPodError(path ~ ": no language '" ~ lang + ~ "'; it holds: " ~ have); + } + } else if (ssps.length > 1) { + string have; + foreach (i, e; ssps) { + have ~= (i > 0 ? " " : "") ~ langOfSspName(e.name); + } + throw new OcdaPodError(path ~ ": holds more than one language (" + ~ have ~ "); name the one wanted"); + } + auto ssp = zipRead(bytes, chosen); + return parseSsp(cast(string) ssp.idup); +} + +/+ ↓ the archive, unwrapped if it was wrapped. + The bytes decide, not the name: a .sisupod is a zstd frame and a .zip + is not, and a file misnamed either way still reads. ++/ +private ubyte[] archiveBytes(string path) { + auto bytes = cast(ubyte[]) read(path); + return zstdIsFrame(bytes) + ? zstdDecompress(bytes, max_pod_size) + : bytes; +} + +/+ ↓ <uid>.<lang>.ssp -> <lang> +/ +private string langOfSspName(string name) { + if (!name.endsWith(".ssp")) { return ""; } + string stem = name[0 .. $ - 4]; + auto dot = stem.lastIndexOf('.'); + return (dot > 0) ? stem[dot + 1 .. $] : ""; +} + +private ptrdiff_t lastIndexOf(string s, char c) { + for (ptrdiff_t i = s.length - 1; i >= 0; i--) { + if (s[i] == c) { return i; } + } + return -1; +} diff --git a/dlang/src/ocda/zip.d b/dlang/src/ocda/zip.d new file mode 100644 index 0000000..9dff6f4 --- /dev/null +++ b/dlang/src/ocda/zip.d @@ -0,0 +1,115 @@ +module ocda.zip; + +/+ ↓ enough of the zip format to find one file in a pod and read it. + . + Not a zip library. A pod archive holds a handful of entries, spine + writes them **stored** (uncompressed) so that the outer zstd frame does + the compressing once over the whole thing, and what is wanted from it + here is one named entry. So: read the central directory, find the + entry, return its bytes. + . + Deflate is *refused rather than mishandled*. Phobos can inflate, but a + library that says it read an entry it in fact skipped is worse than one + that says it cannot, and spine's own archives do not need it. ++/ + +import std.algorithm : endsWith; +import std.conv : to; + +class OcdaZipError : Exception { + this(string msg) { super(msg); } +} + +struct ZipEntry { + string name; + uint method; // 0 stored, 8 deflate + uint compressed; + uint uncompressed; + uint local_offset; +} + +/+ ↓ the entries, from the central directory at the end of the file +/ +ZipEntry[] zipEntries(const(ubyte)[] bytes) { + enum uint eocd_sig = 0x06054b50; + enum uint cd_sig = 0x02014b50; + if (bytes.length < 22) { + throw new OcdaZipError("too short to be a zip archive"); + } + /+ ↓ the end of central directory record is last, and may be followed by a + comment of up to 65535 bytes, so it is searched for backwards +/ + ptrdiff_t eocd = -1; + ptrdiff_t lowest = bytes.length > (22 + 65535) ? bytes.length - (22 + 65535) : 0; + for (ptrdiff_t i = bytes.length - 22; i >= lowest; i--) { + if (u32(bytes, i) == eocd_sig) { eocd = i; break; } + } + if (eocd < 0) { + throw new OcdaZipError("no end of central directory record;" + ~ " it does not look like a zip archive"); + } + uint count = u16(bytes, eocd + 10); + uint offset = u32(bytes, eocd + 16); + ZipEntry[] out_; + size_t p = offset; + foreach (_; 0 .. count) { + if (p + 46 > bytes.length || u32(bytes, p) != cd_sig) { + throw new OcdaZipError("central directory entry " + ~ out_.length.to!string ~ " is malformed"); + } + ZipEntry e; + e.method = u16(bytes, p + 10); + e.compressed = u32(bytes, p + 20); + e.uncompressed = u32(bytes, p + 24); + uint name_len = u16(bytes, p + 28); + uint extra_len = u16(bytes, p + 30); + uint cmnt_len = u16(bytes, p + 32); + e.local_offset = u32(bytes, p + 42); + e.name = cast(string) bytes[p + 46 .. p + 46 + name_len].idup; + out_ ~= e; + p += 46 + name_len + extra_len + cmnt_len; + } + return out_; +} + +/+ ↓ one entry's bytes, from its local header +/ +ubyte[] zipRead(const(ubyte)[] bytes, ZipEntry e) { + enum uint local_sig = 0x04034b50; + size_t p = e.local_offset; + if (p + 30 > bytes.length || u32(bytes, p) != local_sig) { + throw new OcdaZipError(e.name ~ ": local header is malformed"); + } + uint name_len = u16(bytes, p + 26); + uint extra_len = u16(bytes, p + 28); + size_t start = p + 30 + name_len + extra_len; + size_t end = start + e.compressed; + if (end > bytes.length) { + throw new OcdaZipError(e.name ~ ": runs past the end of the archive"); + } + if (e.method != 0) { + throw new OcdaZipError(e.name ~ ": compression method " + ~ e.method.to!string ~ "; this reader takes only stored entries," + ~ " which is what spine writes"); + } + return bytes[start .. end].dup; +} + +/+ ↓ the first entry whose name ends this way, or none. + Used to find media/abstraction/<uid>.<lang>.ssp without knowing the uid. ++/ +ZipEntry[] zipFindSuffix(ZipEntry[] entries, string suffix) { + ZipEntry[] out_; + foreach (e; entries) { + if (e.name.endsWith(suffix)) { out_ ~= e; } + } + return out_; +} + +private uint u16(const(ubyte)[] b, size_t i) { + return cast(uint) b[i] | (cast(uint) b[i + 1] << 8); +} + +private uint u32(const(ubyte)[] b, size_t i) { + return cast(uint) b[i] + | (cast(uint) b[i + 1] << 8) + | (cast(uint) b[i + 2] << 16) + | (cast(uint) b[i + 3] << 24); +} diff --git a/dlang/src/ocda/zstd.d b/dlang/src/ocda/zstd.d new file mode 100644 index 0000000..401f1a3 --- /dev/null +++ b/dlang/src/ocda/zstd.d @@ -0,0 +1,79 @@ +module ocda.zstd; + +/+ ↓ libzstd, declared rather than bound. + . + A .sisupod is one zstd frame wrapping a zip archive, so reading one + needs exactly two things from the library: is this a frame, and what is + in it. Both are declared here and the C library is linked, which is the + same arrangement ocda.sqlite uses: no vendored tree, no generated + header, and the prototypes say what is being called. ++/ + +extern (C) @nogc nothrow private { + size_t ZSTD_decompress(void* dst, size_t dstCapacity, + const(void)* src, size_t compressedSize); + ulong ZSTD_getFrameContentSize(const(void)* src, size_t srcSize); + uint ZSTD_isError(size_t code); + const(char)* ZSTD_getErrorName(size_t code); +} + +/+ ↓ the two values ZSTD_getFrameContentSize returns in place of a size +/ +private enum ulong contentSizeUnknown = ulong.max; +private enum ulong contentSizeError = ulong.max - 1; + +/+ ↓ the magic number of a zstd frame, little endian 0xFD2FB528 +/ +private static immutable ubyte[4] zstd_magic = [0x28, 0xB5, 0x2F, 0xFD]; + +class OcdaZstdError : Exception { + this(string msg) { super(msg); } +} + +/+ ↓ does this begin with a zstd frame? + Asked of the bytes rather than of the filename, because what is inside + decides how a thing is opened. A .sisupod is a frame; a .zip published + before spine wrapped them is not, and both are read. ++/ +bool zstdIsFrame(const(ubyte)[] bytes) { + if (bytes.length < zstd_magic.length) { return false; } + foreach (i, b; zstd_magic) { + if (bytes[i] != b) { return false; } + } + return true; +} + +/+ ↓ one frame in, its contents out. + max_size is a refusal rather than a buffer size: a frame declares how + much it expands to, and a frame that claims more than the caller is + willing to hold is not decompressed at all. A reader of an artefact it + did not make wants that limit. ++/ +ubyte[] zstdDecompress(const(ubyte)[] bytes, size_t max_size) { + if (!zstdIsFrame(bytes)) { + throw new OcdaZstdError("not a zstd frame"); + } + ulong declared = ZSTD_getFrameContentSize(bytes.ptr, bytes.length); + if (declared == contentSizeError) { + throw new OcdaZstdError("zstd frame: could not read its content size"); + } + if (declared == contentSizeUnknown) { + throw new OcdaZstdError("zstd frame declares no content size;" + ~ " this reader takes only frames that do"); + } + if (declared > max_size) { + import std.conv : to; + throw new OcdaZstdError("zstd frame expands to " ~ declared.to!string + ~ " bytes, over the " ~ max_size.to!string ~ " byte limit"); + } + auto out_ = new ubyte[](cast(size_t) declared); + size_t got = ZSTD_decompress(out_.ptr, out_.length, bytes.ptr, bytes.length); + if (ZSTD_isError(got)) { + import std.string : fromStringz; + throw new OcdaZstdError("zstd: " + ~ ZSTD_getErrorName(got).fromStringz.idup); + } + if (got != declared) { + throw new OcdaZstdError("zstd frame expanded to a different size" + ~ " than it declared"); + } + return out_; +} |
