@spine-event-engine/server 2.0.0-snapshot.11

package/dist/delivery/delivery.d.ts

@@ -0,0 +1,236 @@
+import { type WorkerId } from "@spine-event-engine/proto/delivery";
+import type { StorageContext, StorageFactory } from "@spine-event-engine/storage";
+import type { DeliveryControlledRun } from "./delivery-run-control.js";
+import { DeliveryMonitor } from "./delivery-monitor.js";
+import type { DeliveryInbox, DeliveryWorkRegistry } from "./delivery-ports.js";
+import { type InboxMessage } from "./inbox.js";
+import { ShardIndex } from "./shard-index.js";
+import type { DeliveryResult, DeliveryRunOptions, DeliveryStrategy } from "./delivery-builder.js";
+/**
+ * Describes an endpoint snapshot supplied for direct Inbox delivery.
+ */
+export type DeliveryEndpointMessage = InboxMessage;
+/**
+ * Dispatches one persisted Inbox message to an endpoint.
+ *
+ * @param message The message to dispatch.
+ * @returns A promise that settles when endpoint dispatch completes.
+ */
+export type OnDeliveryMessage = (message: DeliveryEndpointMessage) => void | Promise<void>;
+type DirectDrainRequest = OnDeliveryMessage | {
+    readonly node?: string;
+    readonly onMessage: OnDeliveryMessage;
+    readonly onDelivered?: (message: InboxMessage) => void;
+    readonly onDuplicateRemoved?: (message: InboxMessage) => void;
+    readonly acceptMessage?: (message: InboxMessage) => boolean;
+};
+/**
+ * Reports one direct drain and whether it durably resolved the selected message.
+ *
+ * @internal
+ */
+export interface DeliveryDirectRun {
+    /**
+     * Contains the terminal shard-drain outcome.
+     */
+    readonly run: DeliveryRun;
+    /**
+     * Indicates whether this drain marked the selected message delivered or
+     * removed it as a duplicate.
+     */
+    readonly acknowledged: boolean;
+}
+/**
+ * Summarizes one finite direct delivery run.
+ */
+export interface DeliveryRun {
+    /**
+     * Identifies the terminal delivery outcome.
+     */
+    readonly status: "DRAINED" | "SKIPPED" | "FAILED" | "STOPPED";
+    /**
+     * Counts messages considered for dispatch.
+     */
+    readonly processed: number;
+    /**
+     * Counts messages admitted to the endpoint.
+     */
+    readonly accepted: number;
+    /**
+     * Counts messages durably acknowledged as delivered.
+     */
+    readonly delivered: number;
+    /**
+     * Counts dispatch or acknowledgement failures.
+     */
+    readonly failed: number;
+    /**
+     * Lists ephemeral delivery failures.
+     */
+    readonly failures: readonly DeliveryFailure[];
+}
+/**
+ * Describes ephemeral delivery failure evidence that is never persisted.
+ */
+export interface DeliveryFailure {
+    /**
+     * Identifies the message associated with the failure.
+     */
+    readonly message: InboxMessage;
+    /**
+     * Supplies the observed failure.
+     */
+    readonly error: unknown;
+}
+/**
+ * Executes direct Inbox delivery for one complete worker identity.
+ */
+export declare class Delivery {
+    #private;
+    /**
+     * Identifies the immutable storage namespace.
+     */
+    readonly context: StorageContext;
+    /**
+     * Supplies durable record storage.
+     */
+    readonly storageFactory: StorageFactory;
+    /**
+     * Maps targets to delivery shards.
+     */
+    readonly strategy: DeliveryStrategy;
+    /**
+     * Identifies this worker's opaque durable ownership identity.
+     */
+    readonly worker: WorkerId;
+    /**
+     * Names the worker node for compatibility integrations.
+     */
+    readonly node: string;
+    /**
+     * Bounds each direct Inbox read.
+     */
+    readonly pageSize: number;
+    /**
+     * Reads and acknowledges direct Inbox rows.
+     */
+    readonly inbox: DeliveryInbox;
+    /**
+     * Acquires and releases direct shard ownership.
+     */
+    readonly shards: DeliveryWorkRegistry;
+    /**
+     * Creates direct delivery from immutable options.
+     *
+     * @param options The delivery configuration.
+     */
+    constructor(options: DeliveryOptions);
+    /**
+     * Executes one finite shard delivery.
+     *
+     * @param options The selected shard and endpoint callback.
+     * @returns The terminal public delivery result.
+     */
+    run(options: DeliveryRunOptions): Promise<DeliveryResult>;
+    /**
+     * Executes one finite shard delivery under an operation signal.
+     *
+     * @param options The controlled shard, endpoint, and cancellation signal.
+     * @returns The terminal public delivery result.
+     */
+    runControlled(options: DeliveryControlledRun): Promise<DeliveryResult>;
+    /**
+     * Delivers the selected message's shard for local handoff integration.
+     *
+     * @param message The message selecting the shard to drain.
+     * @param input The endpoint callback or callback configuration.
+     * @returns The terminal direct-delivery result.
+     */
+    drainMessage(message: InboxMessage, input: DirectDrainRequest): Promise<DeliveryDirectRun>;
+    /**
+     * Executes one owned shard drain while containing monitor and endpoint failures.
+     *
+     * @param shard The shard to acquire and drain.
+     * @param options The endpoint and optional operation signal.
+     * @returns The terminal direct-delivery result.
+     */
+    drain(shard: ShardIndex, options: DeliveryDrainOptions): Promise<DeliveryRun>;
+}
+/**
+ * Configures one direct delivery owner.
+ */
+export interface DeliveryOptions {
+    /**
+     * Identifies the storage namespace.
+     */
+    readonly context: StorageContext;
+    /**
+     * Supplies durable record storage.
+     */
+    readonly storageFactory: StorageFactory;
+    /**
+     * Supplies direct shard ownership when customized.
+     */
+    readonly workRegistry?: DeliveryWorkRegistry;
+    /**
+     * Supplies direct Inbox access when customized.
+     */
+    readonly inbox?: DeliveryInbox;
+    /**
+     * Maps targets to shards when customized.
+     */
+    readonly strategy?: DeliveryStrategy;
+    /**
+     * Supplies delivery lifecycle and failure policy hooks.
+     */
+    readonly monitor?: DeliveryMonitor;
+    /**
+     * Supplies a complete opaque worker identity.
+     */
+    readonly worker?: WorkerId;
+    /**
+     * Names the node used to derive a default worker identity.
+     */
+    readonly node?: string;
+    /**
+     * Bounds each direct Inbox read.
+     */
+    readonly pageSize?: number;
+}
+/**
+ * Configures one direct shard drain.
+ */
+export interface DeliveryDrainOptions {
+    /**
+     * Dispatches supported Inbox messages.
+     */
+    readonly onMessage: OnDeliveryMessage;
+    /**
+     * Observes a durable delivered transition.
+     *
+     * @param message Contains the acknowledged Inbox message.
+     * @internal
+     */
+    readonly onDelivered?: (message: InboxMessage) => void;
+    /**
+     * Observes successful removal of a duplicate Inbox message.
+     *
+     * @param message Contains the removed duplicate.
+     * @internal
+     */
+    readonly onDuplicateRemoved?: (message: InboxMessage) => void;
+    /**
+     * Determines whether this drain callback owns a message.
+     *
+     * @param message Contains a pending Inbox message.
+     * @returns `true` when the callback owns the message.
+     * @internal
+     */
+    readonly acceptMessage?: (message: InboxMessage) => boolean;
+    /**
+     * Propagates cancellation through the drain.
+     */
+    readonly operation?: import("./delivery-ports.js").DeliveryOperationOptions;
+}
+export {};
+//# sourceMappingURL=delivery.d.ts.map

package/dist/delivery/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery.ts"],"names":[],"mappings":"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"}