Reading

How a reader resolves a ref, checks a version and attaches its catalog, and what may be cached.

Steps

A reader that does not know which ref to ask for may read refs.json to find the names (see Refs).

1. Read HEAD, or the ref asked for. If the content starts with ref: , read the ref it names
2. Read versions/<ID>/version.json for the ID found. Check that its id matches and that the reader knows its fdl major version
3. If versions/<ID>/expired.json exists, stop: the version is past retention or withdrawn
4. Open versions/<ID>/ducklake.duckdb, or a catalogs/ file the reader can open, read-only

ATTACH 'ducklake:https://example.org/lake/versions/019a3c4e-…/ducklake.duckdb' AS lake (
  DATA_PATH 'https://example.org/lake/data/', OVERRIDE_DATA_PATH true, READ_ONLY
);

Signatures

A version may carry versions/<ID>/version.json.sig: an SSH signature of the bytes of version.json, made with ssh-keygen -Y sign -n fdl. The signature covers the record, and the record covers the catalog through catalog.sha256.

ssh-keygen -Y verify -f allowed_signers -I alice@example.org -n fdl \
  -s version.json.sig < version.json

• Signing is optional. A reader that does not check signatures reads a signed version as any other
• A reader that checks verifies the signature against keys it trusts, gets the catalog and checks its sha256 against catalog.sha256
• Keys come from the origin, not from the repository being read. signers in fdl.json only says which keys to expect

Data path

The catalog’s data_path is the absolute URL of the data folder where the writer published. A reader must pass DATA_PATH '<root><data_dir>' and OVERRIDE_DATA_PATH true, where <root> is wherever it reads the repository from. The statement is then the same at the origin and at a mirror, and a repository copied to another host is read without changing its catalogs.

Caching

• A version’s files never change except as described in Versions, so its catalog may be cached forever
• HEAD, refs/ and refs.json must not be cached
• expired.json may appear later. A cache of a version folder should be dropped when it does

Over HTTP, HEAD and refs/ are served as Content-Type: text/plain; charset=utf-8 with Cache-Control: no-store.

A catalog at a fixed URL

A host may serve the catalog of the version HEAD holds at <root>/ducklake.duckdb, for readers that do not know FDL. It must then send the version ID in an FDL-Version response header. This catalog is served, not stored: the store holds no catalog outside versions/.