Contract
Reference for the contract exports in @streamsy/serve/contract. They define canonical JSON, change validators, header names, and public error bodies.
import {
canonicalJson,
contractFingerprint,
valueEtag,
decodePublicError,
STATE_VERSION_HEADER,
STATE_CONTRACT_HEADER,
STREAM_VERSION_HEADER,
STREAM_CONTRACT_HEADER,
VALUE_CONTRACT_HEADER,
DURABLE_STATE_PROTOCOL,
PUBLIC_ERROR_TAGS,
type CanonicalValue,
type ReplayRecovery,
type ResumeRejectedReason,
type PublicError,
type PublicErrorTag,
} from "@streamsy/serve/contract";@streamsy/serve/contract holds the header names, the JSON encoding, and the error bodies that a Serve route and its clients share. See Browser clients and CORS.
canonicalJson
declare function canonicalJson(value: CanonicalValue): string;
canonicalJson encodes a value as JSON with the keys of every object sorted and the order of every array kept. A null value remains null. A non-finite number throws a TypeError when the encoder visits it.
Pass ordinary objects. An object with a null prototype fails the instanceof Object test, so canonicalJson encodes it with JSON.stringify: it does not sort its keys, and it writes a non-finite number in it as null.
The type excludes undefined. When an object member is undefined at run time, canonicalJson leaves it out.
contractFingerprint
declare function contractFingerprint(value: CanonicalValue): string;
contractFingerprint returns eight lowercase hexadecimal characters: an FNV-1a hash of the UTF-16 code units of canonicalJson(value). Two ordinary objects that differ only in property order have the same fingerprint. The fingerprint detects a change. It is not a cryptographic hash.
valueEtag
declare function valueEtag(canonical: string): string;
valueEtag returns a strong ETag: sixteen lowercase hexadecimal characters inside double quotes. It concatenates two FNV-1a hashes of canonical with different seeds. To tag a JSON value, pass the result of canonicalJson. Like the fingerprint, the ETag is not a cryptographic hash.
decodePublicError
declare function decodePublicError(value: unknown): PublicError;
decodePublicError validates an untrusted error object and returns a new PublicError without the unknown fields. It throws a TypeError when the body is not valid or its tag is unknown.
decodePublicError reads each required field only as an own data property, so it never calls a getter. It rejects an inherited field, an accessor, a boxed string, an array, an object with a null prototype, and null.
CanonicalValue
type CanonicalValue =
| string
| number
| boolean
| null
| readonly CanonicalValue[]
| { readonly [key: string]: CanonicalValue };
CanonicalValue is the type of a JSON value: a string, a number, a boolean, null, a readonly array, or an object with string keys. The compiler accepts NaN and Infinity as a number, but canonicalJson throws on them.
ReplayRecovery
type ReplayRecovery = "replay-from-start";
ReplayRecovery is the recovery value of the stream and state errors. On "replay-from-start", a state client clears its local rows and reads again from offset -1.
ResumeRejectedReason
type ResumeRejectedReason = "invalid-offset" | "history-unavailable" | "contract-changed";
ResumeRejectedReason is the reason of a ResumeRejected error.
| Reason | Meaning |
|---|---|
invalid-offset | The offset is malformed, or the read rejects it |
history-unavailable | The stream to resume does not exist or was deleted |
contract-changed | The contract fingerprint of the request differs from the current one |
PublicError
type PublicError =
| {
readonly _tag: "InvalidParams";
readonly route: string;
readonly parameter: string;
readonly detail: string;
}
| {
readonly _tag: "ProtocolVersionUnsupported";
readonly route: string;
readonly supported: 1;
readonly received: string;
readonly recovery: ReplayRecovery;
}
| {
readonly _tag: "ResumeRejected";
readonly route: string;
readonly reason: ResumeRejectedReason;
readonly recovery: ReplayRecovery;
}
| { readonly _tag: "ContractChanged"; readonly route: string; readonly recovery: "refetch" }
| {
readonly _tag: "TransportUnavailable" | "WireEncodeFailed";
readonly route: string;
readonly detail: string;
};
PublicError is the type of the JSON body of a Serve error. route is the matched route pattern. In a body from Serve, parameter is always "params". detail describes the failure of InvalidParams, TransportUnavailable, or WireEncodeFailed.
recovery tells the client what to do next: "replay-from-start" for the stream and state errors, and "refetch" for ContractChanged. For the fields and the HTTP status of each error, see Serve errors.
STATE_VERSION_HEADER
declare const STATE_VERSION_HEADER: "x-streamsy-state-version";
STATE_VERSION_HEADER is the name of the Durable State version header. Serve sends "1", and treats a request without the header as version "1".
STATE_CONTRACT_HEADER
declare const STATE_CONTRACT_HEADER: "x-streamsy-state-contract";
STATE_CONTRACT_HEADER is the name of the Durable State contract fingerprint header. When a request sends a different fingerprint in it, state fails with ResumeRejected and reason "contract-changed".
STREAM_VERSION_HEADER
declare const STREAM_VERSION_HEADER: "x-streamsy-stream-version";
STREAM_VERSION_HEADER is the name of the Durable Streams version header. Serve sends "1", and treats a request without the header as version "1".
STREAM_CONTRACT_HEADER
declare const STREAM_CONTRACT_HEADER: "x-streamsy-stream-contract";
STREAM_CONTRACT_HEADER is the name of the Durable Streams contract fingerprint header. When a request sends a different fingerprint in it, stream fails with ResumeRejected and reason "contract-changed".
VALUE_CONTRACT_HEADER
declare const VALUE_CONTRACT_HEADER: "x-streamsy-value-contract";
VALUE_CONTRACT_HEADER is the name of the contract fingerprint header of a computed value. When a request sends a different fingerprint in it, value fails with ContractChanged.
DURABLE_STATE_PROTOCOL
declare const DURABLE_STATE_PROTOCOL: "https://durable-streams.dev/state-protocol/v1";
DURABLE_STATE_PROTOCOL is the URI of version 1 of the Durable State protocol.
PUBLIC_ERROR_TAGS
declare const PUBLIC_ERROR_TAGS: readonly [
"InvalidParams",
"ProtocolVersionUnsupported",
"ResumeRejected",
"ContractChanged",
"TransportUnavailable",
"WireEncodeFailed",
];
PUBLIC_ERROR_TAGS lists the six public error tags in the order that PublicError declares them.
PublicErrorTag
type PublicErrorTag = PublicError["_tag"];
PublicErrorTag is the union of the _tag values of PublicError, which are the entries of PUBLIC_ERROR_TAGS.