@relaybus/core 0.3.0 → 0.4.0

package/dist/internal/index.d.cts

@@ -1,4 +1,4 @@
-import { a as EventHeaders, E as EventEnvelope, C as Clock } from '../event-DCRTuYKI.cjs';
+import { EventHeaders, EventEnvelope, Clock, LeaseReference, ErrorInfo, ClaimRequest, ClaimedDelivery, Transport, TransportMessageHandler, TransportSubscriptionHooks, CloseOptions, Duration } from '../index.cjs';
 
 /** Returns `value` when it is an integer of at least 1, else throws a {@link ConfigurationError} naming the option. */
 declare function assertPositiveInteger(value: number, name: string): number;
@@ -82,21 +82,46 @@ type WireField = BodyField | HeaderField;
 type FixedType = {
     readonly fixed: string;
 };
+/**
+ * How `occurredAt` travels: RFC 3339 text (default), or whole epoch milliseconds or seconds, a
+ * number in the body and decimal text in a header. Epoch seconds drop the milliseconds.
+ */
+type TimeFormat = 'rfc3339' | 'epoch-millis' | 'epoch-seconds';
+/** Where the event time lives, and in which format. */
+type TimeField<TField extends WireField> = TField & {
+    readonly format?: TimeFormat;
+};
+/** A JSON value written as it is. */
+type JsonConstant = string | number | boolean | null | readonly JsonConstant[] | {
+    readonly [name: string]: JsonConstant;
+};
+/** A value written with every message: a constant, or derived from the event. */
+type ExtraValue<TValue> = TValue | ((envelope: EventEnvelope) => TValue);
+/** Extra message headers, by name. */
+type ExtraHeaders = Readonly<Record<string, ExtraValue<string>>>;
+/** Extra body values, by dotted path. */
+type ExtraBody = Readonly<Record<string, ExtraValue<JsonConstant>>>;
 type MappingFields<TField extends WireField, TTransportId extends string> = {
     /** Where the event type lives, or the one type of the route. Required. */
     readonly type: TField | FixedType;
     /**
      * Where the event id lives, or the transport's own message identity (see the transport's
      * mapping type). Required, so the inbox dedup key is always a deliberate choice. A message
-     * whose mapped id is missing is malformed.
+     * whose mapped id is missing is malformed, unless `whenMissing` names the transport's own id
+     * to use instead: `{ body: 'id', whenMissing: 'record-position' }`.
      */
-    readonly id: TField | TTransportId;
+    readonly id: TField | TTransportId | (TField & {
+        readonly whenMissing: TTransportId;
+    });
     /** Ordering key. Default: the transport's own (the Kafka record key; none on RabbitMQ). */
     readonly key?: TField;
     /** Producing service. Default: the transport's own (Kafka topic; RabbitMQ `appId`, else the routing key). */
     readonly source?: TField;
-    /** RFC 3339 time. Default: the transport's own (Kafka record timestamp; RabbitMQ `timestamp`, seconds). */
-    readonly occurredAt?: TField;
+    /**
+     * Event time, RFC 3339 unless `format` says otherwise. Default: the transport's own (Kafka
+     * record timestamp; RabbitMQ `timestamp`, seconds).
+     */
+    readonly occurredAt?: TimeField<TField>;
     readonly correlationId?: TField;
     readonly causationId?: TField;
     /** Media type written with the message. Default `application/json`. Not checked on read. */
@@ -111,10 +136,25 @@ type BodyEnvelopeMapping<TTransportId extends string> = MappingFields<WireField,
     /** Body path of the payload. Required. */
     readonly payload: BodyField;
     /**
-     * Event headers: a body path holding an object of strings, or `'message-headers'` (default),
-     * every message header that no other field maps.
+     * Event headers: a body path holding an object of strings, `'message-headers'` (default),
+     * every message header that no other field maps, or `'top-level-fields'`, spread over the top
+     * level of the body: every top-level text field that no other value uses is read as one.
+     */
+    readonly headers?: BodyField | 'message-headers' | 'top-level-fields';
+    /**
+     * Values written with every message besides the mapped ones, such as a constant
+     * `provider: 'orders-api'` or a second copy of the time. They are never read; extra headers
+     * are left out of the event headers on read.
+     */
+    readonly extra?: {
+        readonly body?: ExtraBody;
+        readonly headers?: ExtraHeaders;
+    };
+    /**
+     * Top-level body fields to write first, in this order; the others follow in the order they
+     * are written. Only the bytes change, for formats compared byte for byte.
      */
-    readonly headers?: BodyField | 'message-headers';
+    readonly bodyOrder?: readonly string[];
 };
 /**
  * The body is the payload itself, as a plain JSON producer writes it; every other value lives in
@@ -124,6 +164,10 @@ type PayloadOnlyMapping<TTransportId extends string> = MappingFields<HeaderField
     readonly payload: 'whole-body';
     /** Event headers: every message header that no other field maps. */
     readonly headers?: 'message-headers';
+    /** Message headers written with every message; never read, and left out of the event headers. */
+    readonly extra?: {
+        readonly headers?: ExtraHeaders;
+    };
 };
 /** Where every envelope value lives in a JSON message. `type`, `id` and `payload` are required. */
 type JsonEnvelopeMapping<TTransportId extends string> = BodyEnvelopeMapping<TTransportId> | PayloadOnlyMapping<TTransportId>;
@@ -168,4 +212,272 @@ declare function createJsonEnvelopeFormat(mapping: JsonEnvelopeMapping<string>,
     readonly failures: JsonEnvelopeFailures;
 }): JsonEnvelopeFormat;
 
-export { type BodyEnvelopeMapping, type BodyField, type CancelTimer, type CloudEventReaders, type FixedType, type HeaderField, type JsonEnvelopeFailures, type JsonEnvelopeFields, type JsonEnvelopeFormat, type JsonEnvelopeMapping, type JsonWireMessage, type PayloadOnlyMapping, type ScheduledTask, type WireField, assertPositiveInteger, createCloudEventReaders, createJsonEnvelopeFormat, fromHeader, fromPayloadField, isJsonObject, mediaTypeOf, schedule, sleep, writeStructuredCloudEvent };
+/** What a ledger remembers of a claim: at least who it was handed to and which delivery. */
+interface HandedOutEntry {
+    readonly owner: string;
+    readonly deliveryId: string;
+}
+/**
+ * The claims a store instance handed out and has not seen settled, keyed by
+ * {@link DeliveryLeaseIdentity} (delivery id and exact lease token). After a failed claim the
+ * store keeps exactly these listed as running and gives the rest back.
+ */
+declare class HandedOutLedger<TEntry extends HandedOutEntry> {
+    #private;
+    register(lease: LeaseReference, entry: TEntry): void;
+    /** Whether the claim with this identity ({@link DeliveryLeaseIdentity.of}) is handed out. */
+    has(identity: string): boolean;
+    forget(lease: LeaseReference): void;
+    /** Forgets every entry `settled` says is settled. */
+    forgetWhere(settled: (entry: TEntry, identity: string) => boolean): void;
+    /** The entries handed out to `owner`. */
+    entriesOf(owner: string): TEntry[];
+}
+
+/** How a claim ends without completing: retried later, given back, or dead-lettered. */
+type SettlementChange = {
+    readonly kind: 'reschedule';
+    readonly availableAt: Date;
+    readonly error: ErrorInfo;
+    readonly now: Date;
+} | {
+    readonly kind: 'release';
+    readonly now: Date;
+} | {
+    readonly kind: 'bury';
+    readonly error: ErrorInfo;
+    readonly now: Date;
+};
+/** A change of the claim a lease names. */
+type LeaseChange = {
+    readonly lease: LeaseReference;
+    readonly change: SettlementChange;
+};
+/** A lease renewal; `now` for a store that records when it happened. */
+type LeaseExtension = {
+    readonly lease: LeaseReference;
+    readonly leaseExpiresAt: Date;
+    readonly now?: Date;
+};
+/**
+ * What a store answers about a lease: at once when it answers from memory, later when it asks a
+ * database. Answering at once keeps the in-memory store as fast (in microtasks) as it always was.
+ */
+type StoreAnswer = boolean | Promise<boolean>;
+/**
+ * The fenced settlement skeleton every event store shares: find the claim a lease names (a lease
+ * this store cannot have issued, or whose claim ended, is not held and changes nothing), apply the
+ * change fenced by the lease, then forget the lease as handed out once the store answered.
+ * A store supplies only how it finds a held claim, how it writes a change and a renewal, and its
+ * bookkeeping of handed-out leases.
+ */
+declare abstract class LeaseSettlement<THeld> {
+    #private;
+    /** Renews the lease when it is still held; false otherwise. */
+    extendLease(extension: LeaseExtension): StoreAnswer;
+    /**
+     * Applies `change` when the lease is still held. Once the store answered (either way) the lease
+     * is forgotten as handed out; when the write throws it stays registered, since the caller may
+     * retry with the same lease.
+     */
+    changeClaim(request: LeaseChange): StoreAnswer;
+    /** The claim `lease` names, when this store issued the lease; undefined otherwise. */
+    protected abstract findHeld(lease: LeaseReference): THeld | undefined;
+    protected abstract writeChange(held: THeld, request: LeaseChange): StoreAnswer;
+    protected abstract writeExtension(held: THeld, extension: LeaseExtension): StoreAnswer;
+    /** Drops `lease` from the store's handed-out bookkeeping; nothing for a store that keeps none. */
+    protected abstract forgetHandedOut(lease: LeaseReference): void;
+}
+
+/**
+ * The claim skeleton of the database stores: a request for no handlers or no deliveries claims
+ * nothing, and the claims of one owner run one after the other. Claims of one owner read the same
+ * held lanes and the same bookkeeping of what was handed out, so they must not overlap (the
+ * dispatcher claims one batch at a time anyway; `runOnce` next to a running dispatcher is what
+ * this guards against). A store supplies only {@link OwnerSerializedClaims.claimInTurn}.
+ */
+declare abstract class OwnerSerializedClaims {
+    #private;
+    claim(request: ClaimRequest): Promise<ClaimedDelivery[]>;
+    /** Whether the request cannot claim anything: no handlers, or a limit that is not above 0. */
+    protected claimsNothing(request: ClaimRequest): boolean;
+    /** Claims for `request` once the earlier claims of its owner settled. */
+    protected abstract claimInTurn(request: ClaimRequest): Promise<ClaimedDelivery[]>;
+}
+
+/** The event a transport's decoder extracted from a message; see the transport's `DecodedEvent`. */
+interface DecodedEventFields {
+    readonly id: string;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly source?: string;
+    readonly key?: string | null;
+    readonly headers?: EventHeaders;
+    readonly correlationId?: string | null;
+    readonly causationId?: string | null;
+    readonly occurredAt?: Date;
+}
+/** A fixed value, or an extractor that reads it from a plain message. */
+type TextOption<TPlain, TValue extends string | null> = TValue | ((message: TPlain) => TValue | undefined) | undefined;
+/**
+ * Observes the rejection of a promise an async decoder or extractor returned by
+ * mistake: the value is refused as malformed, and an unobserved rejection would
+ * otherwise crash the process.
+ */
+declare function observeRejection(value: unknown): void;
+/**
+ * The inbound plumbing a transport shares with every other: completing what a user decoder
+ * returned and reading the extractor options of a plain JSON decoder. A transport supplies only its
+ * malformed-message error and the defaults its messages carry (source, key, time).
+ */
+declare abstract class DecodedEventReader<TMessage, TPlain> {
+    /**
+     * Fills the fields a decoder left out and guards against a decoder that returned no object,
+     * which would otherwise surface as a retried `TypeError` instead of a malformed message.
+     */
+    complete(decoded: unknown, message: TMessage): EventEnvelope;
+    /** The text an option gives for `plain`; undefined when it gives none or `''`. */
+    text<TValue extends string | null>(option: TextOption<TPlain, TValue>, { plain, name }: {
+        readonly plain: TPlain;
+        readonly name: string;
+    }): string | undefined;
+    /** The error of a malformed message, which the transport dead-letters instead of retrying. */
+    abstract invalid(reason: string): Error;
+    protected abstract defaultSource(message: TMessage): string;
+    protected abstract defaultKey(message: TMessage): string | null;
+    protected abstract defaultTime(message: TMessage): Date;
+}
+
+/** One subscription of a transport: what it consumes and where the messages go. */
+interface TransportSubscription {
+    readonly destinations: readonly string[];
+    readonly onMessage: TransportMessageHandler;
+    readonly hooks: TransportSubscriptionHooks | undefined;
+}
+/**
+ * The skeleton of a broker transport that publishes and subscribes: the {@link Transport} port
+ * with its subscribe signature in one place. A transport supplies how it publishes, opens its one
+ * subscription, reports readiness and closes.
+ */
+declare abstract class SubscribingTransport implements Transport {
+    abstract readonly name: string;
+    abstract readonly system: string;
+    /**
+     * Subscribes to `destinations`. Not async itself: the subscription's own promise is returned
+     * as it is, so its checks reject rather than throw.
+     */
+    subscribe(destinations: readonly string[], onMessage: TransportMessageHandler, hooks?: TransportSubscriptionHooks): Promise<void>;
+    abstract publish(envelope: EventEnvelope, destination: string): Promise<void>;
+    abstract isReady(): boolean;
+    abstract close(options?: CloseOptions): Promise<void>;
+    /** Opens the transport's one subscription; rejects when it cannot. */
+    protected abstract openSubscription(subscription: TransportSubscription): Promise<void>;
+}
+
+/**
+ * Two identifiers joined into one map or set key, such as an event id and a handler id, or a
+ * handler id and an ordering key. The NUL separator keeps `('a:b', 'c')` and `('a', 'b:c')` apart.
+ * Keys are plain strings, so they cost nothing more than the template literal they replace.
+ */
+declare abstract class CompositeKey {
+    static of(first: string, second: string): string;
+    /** The start every key of `first` shares, to find them all by prefix. */
+    static startOf(first: string): string;
+}
+
+/** The range a {@link BoundedInteger} option allows. */
+interface IntegerBounds {
+    readonly name: string;
+    readonly minimum: number;
+    readonly maximum: number;
+}
+/** An integer option with fixed lower and upper bounds. */
+declare abstract class BoundedInteger {
+    /** Returns `value` when it is an integer within the bounds, else throws a {@link ConfigurationError}. */
+    static of(value: number, { name, minimum, maximum }: IntegerBounds): number;
+}
+
+/**
+ * Identifies one claim of a delivery: the delivery id with the exact lease token it was handed out
+ * with. Two claims of the same delivery (an expired one and the current one) have different
+ * identities, so bookkeeping of the older can never replace or remove the newer one's.
+ */
+declare abstract class DeliveryLeaseIdentity {
+    static of(deliveryId: string, leaseToken: string): string;
+    /** The start of the identity of every claim of `deliveryId`. */
+    static prefixOf(deliveryId: string): string;
+}
+
+/**
+ * Delays that double with every attempt, from `initialMs` up to `maxMs`: the first retry waits
+ * `initialMs`, the second twice that, and so on. Without jitter, for in-process retries.
+ */
+declare class ExponentialBackoff {
+    readonly initialMs: number;
+    readonly maxMs: number;
+    constructor({ initialMs, maxMs }: {
+        readonly initialMs: number;
+        readonly maxMs: number;
+    });
+    /** The delay after failed attempt `attempt` (1-based). */
+    delayFor(attempt: number): number;
+}
+
+/** The claim a lane lease token names, as written in the token. */
+interface LaneLeaseTokenParts {
+    readonly lane: number;
+    /** The lane's epoch, as decimal text: PostgreSQL epochs exceed the safe integers. */
+    readonly epoch: string;
+    /** The claim generation of the delivery. */
+    readonly claims: number;
+}
+/** How many digits each part of a token may have, and how many lanes there are. */
+interface LaneLeaseTokenLimits {
+    readonly laneCount: number;
+    readonly epochDigits: number;
+    readonly claimsDigits: number;
+}
+/**
+ * The fencing token of a claim in a lane-leased store: `<lane>:<epoch>:<claims>`. Every state
+ * change checks the lane epoch and the delivery's claim generation it names. A store creates one
+ * format with its own digit limits and parses only the tokens it can have issued.
+ */
+declare class LaneLeaseTokenFormat {
+    #private;
+    constructor(limits: LaneLeaseTokenLimits);
+    format(lane: number, { epoch, claims }: {
+        readonly epoch: string | number;
+        readonly claims: number;
+    }): string;
+    /** The parts of `token`; undefined when the store cannot have issued it. */
+    parse(token: string): LaneLeaseTokenParts | undefined;
+}
+
+/**
+ * A configured length of time, converted once from a {@link Duration} option. Each factory names
+ * the option, so its refusal says which one was wrong.
+ */
+declare abstract class Milliseconds {
+    /** Zero or more milliseconds. */
+    static of(value: Duration, name: string): number;
+    /** More than zero milliseconds: a wait, a timeout or an age that must pass at all. */
+    static positive(value: Duration, name: string): number;
+    /** A duration that drives a timer: more than zero, and no longer than timers can represent. */
+    static forTimer(value: Duration, name: string): number;
+}
+
+/** A text option that must not be empty: a name, an exchange, a queue. */
+declare abstract class NonEmptyText {
+    static of(value: string, name: string): string;
+    /** Like {@link NonEmptyText.of}, for an option that may be left out. */
+    static optional(value: string | undefined, name: string): string | undefined;
+}
+
+/** A count option that must be a whole number of at least 1: a batch size, attempts, a limit. */
+declare abstract class PositiveInteger {
+    /** Returns `value` when it is an integer of at least 1, else throws a {@link ConfigurationError} naming the option. */
+    static of(value: number, name: string): number;
+}
+
+export { BoundedInteger, CompositeKey, DecodedEventReader, DeliveryLeaseIdentity, ExponentialBackoff, HandedOutLedger, LaneLeaseTokenFormat, LeaseSettlement, Milliseconds, NonEmptyText, OwnerSerializedClaims, PositiveInteger, SubscribingTransport, assertPositiveInteger, createCloudEventReaders, createJsonEnvelopeFormat, fromHeader, fromPayloadField, isJsonObject, mediaTypeOf, observeRejection, schedule, sleep, writeStructuredCloudEvent };
+export type { BodyEnvelopeMapping, BodyField, CancelTimer, CloudEventReaders, DecodedEventFields, ExtraBody, ExtraHeaders, ExtraValue, FixedType, HandedOutEntry, HeaderField, IntegerBounds, JsonConstant, JsonEnvelopeFailures, JsonEnvelopeFields, JsonEnvelopeFormat, JsonEnvelopeMapping, JsonWireMessage, LaneLeaseTokenLimits, LaneLeaseTokenParts, LeaseChange, LeaseExtension, PayloadOnlyMapping, ScheduledTask, SettlementChange, TextOption, TimeField, TimeFormat, TransportSubscription, WireField };