server

README

fabula Server

URL scheme

E.g. https://fabulalog.io/v1/at/123456/: all regional/prefix digests as of t=123456

/: Documentation

/v1: version 1 of API

Time-based URL prefixes

Reading frmo the log always occurs as of a specific timestamp. If the request is permitted, the log guarantees to reflect all entries with timestamps less than or equal to the requested timestamp.

<ts> is always UTC Unix nanoseconds as an integer.

Version and region portions of the URL described above are omitted here.

.../at/<ts>/...: Timestamp query. If <ts> is more recent than the client is allowed to request, return 403 forbidden.

TODO: does this match the desired semantics? It is "403 Forbidden for now"... Client can wait a few seconds and it would then be permitted...

.../ago/<duration>/...: Staleness query uses server clocks to redirect to an appropriate /at/<ts>/... URL. This is mostly as a convenience for humans querying the log. As a result, <duration> is specified as a human-readable string (e.g. "100ms" or "10s"). Queries generated by automation should typically be precise /at/ queries based on the known timestamp of the entry being requested.

Region-based URL prefixes

Following the time-based URL prefix, regions can be specified:

.../: all regions (for digests)

.../r/<region>: a specific region

.../r/auto: region selected by infrastructure (used only when logging a new entry or looking up a DataSHA3512 without specifying a region)

.../r/global: the global region (auto will never select the global region, it must be explicitly requested when logging a new entry)

Logging

.../new: POST requests to this path create a new log entry. Requests post 0-64 bytes of user-defined binary data. The response includes Region, DataSHA3512, Salt (if >0 bytes of user data is provided), Timestamp, and Signature.

POSTs redirect (via 303 See Other) to GETs on the canonical page for the new entry and that entry's timestamp.

POSTs are not idempotent (which is why they are not PUTs). Posting the same data multiple times will result in multiple independent entries with unique hashes, salts, signatures, and possibly unique timestamps (if the requests are sufficiently spread out in time so as to be possibly causal).

Entries

.../e/<hash>: Lookup a DataSHA3512, returns Region, Timestamp, and Signature. Looking up a DataSHA3512 with the correct region is faster than looking it up with the auto region.

.../e/<hash>/proof: Inclusion proof of entry up to its region+prefix digest (as of the timestamp specified in the url). Returns Region, Timestamp, Signature, and pre- and post-entry hashes.

Digests

.../digests/: Digest of all regions and prefix chains

.../p/<prefix>: Digest of a single prefix chain

Single prefix chains can be validated back to some timestamp in the past:

.../p/<prefix>/proof/from/<prev_ts>: Proof from to <prev_ts> of specified single prefix chain

TODO: How are these validated?

Formats

?format=html: The default; style is same as text, but hashes are links to their canonical pages

?format=text: A more raw text form.

?format=json: JSON

Proofs

TBD.

.../p/<prefix>/proof?from=<ts2>: Proof hashes from ts to ts2 (TBD)