Crate catalog_reader 

The catalog pack, and the reader that serves it — dependency-free on purpose (C-537).

The pack is one file compiled by flux-connectors build from the canonical per-provider documents (catalog/<name>.catalog.json, C-536): every provider’s complete published surface, concatenated behind an offset index, fronted by a versioned header and a content digest. This crate embeds that file and answers the four catalogue questions over it — providers, provider, operation, operations_of — without touching the network, walking a filesystem, or parsing a byte of JSON at query time. A host that wants a newer catalogue than it was built with loads one from a path with Pack::load, which refuses a wrong format version, schema version or digest before serving a single record.

Zero non-optional dependencies is the contract, not a habit. The point of the pack is that catalogue data stops riding code releases; the point of this crate is that reading it costs a consumer nothing but the crate itself. The digest is SHA-256 — the one hash spelling this repository records anywhere — so the check is vendored ([sha256]) rather than imported.

The format (container version 1)

flux-connectors-catalog-pack 1                    ← magic + container format version
digest sha256 <64 lowercase hex>                  ← over every byte after this line
schema <n>                                        ← the documents' schema_version
providers <n>
operations <m>
p <id> <start> <len>                              ← one per provider, ordered by id
o <id> <provider> <service> <start> <len>         ← one per operation, ordered by id
payload <len>
<the canonical documents, concatenated in provider-id order>

Offsets are decimal byte offsets into the payload. A provider’s span is its canonical document, byte for byte; an operation’s span slices that operation’s own JSON record out of the owning document. The whole file is UTF-8 text — documents are JSON — so a record is handed out as &str and a consumer brings whatever JSON parser it already has.

Forward compatibility, stated once

• A newer container format is refused by name: the version is the first line, checked before anything else is believed.
• A newer document schema is refused by name: the header’s schema line is checked against SUPPORTED_SCHEMA before any record is served, because a record this reader hands out is one a consumer will act on.
• Additive growth does not break this reader: an unknown header line or an unknown index row kind is skipped, so a future pack that adds a record family still serves everything a version-1 consumer asks for. Anything a reader must not ignore is a format bump.

What this crate is not

Not a document model — records are canonical JSON text, and interpreting them is the resolver’s job (C-538). Not the legacy catalog API — codewandler-connector-catalog remains the typed &'static surface and re-exports this crate as catalog::reader. And not an authentication boundary: the digest catches corruption and truncation, not an author who can rewrite both the payload and the digest line above it.

Structs

Operation

One operation served from a pack: its index facts and its record.

Pack

A parsed, digest-verified pack.

Provider

One provider served from a pack: its id and its canonical document.

Enums

Error

Why a byte sequence is not a pack this reader will serve.

Constants

FORMAT_VERSION

The container format version this reader understands. A pack declaring a higher one is refused by name — see Error::UnsupportedFormat.

SUPPORTED_SCHEMA

The canonical-document schema version this reader serves. A pack carrying a different one is refused before any record is served — see Error::UnsupportedSchema.

Functions

embedded

The pack this crate embeds, parsed and digest-verified once per process.

operation

One operation of the embedded pack, by id.

operations_of

Every operation of one provider in the embedded pack, in id order.

provider

One provider of the embedded pack, by id.

providers

Every provider in the embedded pack, in id order.