Skip to Content
Reference@streamsy/serve

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.

ReasonMeaning
invalid-offsetThe offset is malformed, or the read rejects it
history-unavailableThe stream to resume does not exist or was deleted
contract-changedThe 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.

On this page