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

package/dist/server/environment-attachment.d.ts

@@ -0,0 +1,356 @@
+import type { ContextDeliveryDescriptor } from "../context/bounded-context.js";
+import type { DeliveryReady } from "../context/local-inbox-handoff.js";
+import type { EnvironmentDeliveryPorts } from "../context/local-inbox-handoff.js";
+import { type DeliveryRunScope, type DeliveryRunSettlement } from "../delivery/delivery-run-coordinator.js";
+import { ParkedDeliveryObligations, type ParkedDeliveryObligationRecord } from "../delivery/parked-delivery-obligations.js";
+import { type EnvironmentGenerationWorker } from "./environment-delivery-worker.js";
+import type { ILogLayer } from "loglayer";
+export type { EnvironmentGenerationWorker } from "./environment-delivery-worker.js";
+/**
+ * Identifies whether a caller or server owns an environment registration.
+ *
+ * @internal
+ */
+export type EnvironmentOwnership = "caller" | "server";
+/**
+ * Represents one current, non-retired environment generation.
+ *
+ * @internal
+ */
+export interface EnvironmentGeneration {
+    /**
+     * Marks values that represent an environment generation.
+     */
+    readonly generation: true;
+}
+/**
+ * Represents one environment attachment reservation.
+ *
+ * @internal
+ */
+export interface EnvironmentRegistrationClaim {
+    /**
+     * Identifies the reservation within its generation.
+     */
+    readonly token: string;
+    /**
+     * Identifies the generation that owns the reservation.
+     */
+    readonly generation: EnvironmentGeneration;
+}
+/**
+ * Defines the ownership and descriptors needed to attach an environment.
+ *
+ * @internal
+ */
+export interface EnvironmentAttachOptions {
+    /**
+     * Selects caller or server ownership.
+     */
+    readonly ownership: EnvironmentOwnership;
+    /**
+     * Lists context delivery descriptors to attach.
+     */
+    readonly descriptors: readonly ContextDeliveryDescriptor[];
+}
+declare class AttachedEnvironmentRegistration implements EnvironmentRegistrationClaim {
+    #private;
+    readonly startup: DeliveryRunSettlement;
+    readonly token: string;
+    constructor(claim: EnvironmentRegistrationClaim, binding: RegistrationBinding, startup: DeliveryRunSettlement, records: () => readonly ParkedDeliveryObligationRecord[]);
+    get generation(): EnvironmentGeneration;
+    records(): readonly ParkedDeliveryObligationRecord[];
+}
+/**
+ * Identifies a successfully attached environment registration.
+ *
+ * @internal
+ */
+export type EnvironmentAttachmentHandle = AttachedEnvironmentRegistration;
+/**
+ * Defines construction seams for deterministic lifecycle tests.
+ *
+ * @internal
+ */
+export interface EnvironmentAttachmentsOptions {
+    /**
+     * Creates a generation worker when an attachment opens a generation.
+     *
+     * @returns The worker for the new generation.
+     */
+    readonly createWorker?: () => EnvironmentGenerationWorker;
+    /**
+     * Immutable environment logger child propagated to each delivery runtime.
+     */
+    readonly logger?: ILogLayer;
+    /**
+     * Resolves the environment-owned delivery ports after its facility opens.
+     *
+     * @returns The selected remote ports, or `undefined` for local delivery.
+     */
+    readonly deliveryPorts?: () => EnvironmentDeliveryPorts | undefined;
+    /**
+     * Calls the retained lifecycle failure reporter.
+     *
+     * @param causes Lists the failures to report.
+     * @returns A promise that settles after the failures are reported.
+     */
+    readonly report?: (causes: readonly unknown[]) => Promise<void>;
+    /**
+     * Injects transition faults used by lifecycle tests.
+     */
+    readonly transitionFaults?: {
+        readonly onRoutePrepare?: (descriptor: ContextDeliveryDescriptor) => void;
+        readonly onScopeTransfer?: (descriptor: ContextDeliveryDescriptor, sources: readonly TransitionScopeSource[]) => void;
+    };
+}
+/**
+ * Tracks registration ownership and generations for one server environment.
+ *
+ * @internal
+ */
+export declare class EnvironmentRegistrations {
+    #private;
+    /**
+     * Returns the number of active claims.
+     *
+     * @returns The active claim count.
+     */
+    get count(): number;
+    /**
+     * Returns the active generation, if any.
+     *
+     * @returns The current generation or `undefined`.
+     */
+    get generation(): EnvironmentGeneration | undefined;
+    /**
+     * Sets the current generation during a safe handoff.
+     *
+     * @param generation Supplies the replacement generation.
+     * @returns The retired generation.
+     */
+    replace(generation: EnvironmentGeneration): EnvironmentGeneration;
+    /**
+     * Creates a registration claim in the current generation.
+     *
+     * @param ownership Selects caller or server ownership.
+     * @returns The new opaque registration claim.
+     */
+    claim(ownership: EnvironmentOwnership): EnvironmentRegistrationClaim;
+    /**
+     * Removes one failed attachment without disturbing sibling claims.
+     *
+     * @internal
+     * @param token Identifies the claim.
+     * @returns The remaining claim count.
+     */
+    remove(token: string): number;
+    /**
+     * Clears an empty generation after its retirement is safe.
+     *
+     * @internal
+     * @param generation Identifies the generation to clear.
+     */
+    clear(generation: EnvironmentGeneration): void;
+}
+/**
+ * Coordinates generation attachment, detachment, recovery, and retirement for one environment.
+ *
+ * @internal
+ */
+export declare class EnvironmentAttachments {
+    #private;
+    /**
+     * Creates an attachment owner.
+     * @param options Optionally supplies lifecycle test seams.
+     */
+    constructor(options?: EnvironmentAttachmentsOptions);
+    /**
+     * Returns the number of bounded unresolved diagnostics.
+     *
+     * @internal
+     * @returns The unresolved count.
+     */
+    get unresolvedReportedDomainCount(): number;
+    /**
+     * Returns the number of live registrations.
+     *
+     * @internal
+     * @returns The active registration count.
+     */
+    get activeRegistrationCount(): number;
+    /**
+     * Returns the number of configured delivery owners.
+     *
+     * @internal
+     * @returns The configured owner count.
+     */
+    get configuredOwnerCount(): number;
+    /**
+     * Returns the number of configured delivery scopes.
+     *
+     * @internal
+     * @returns The configured scope count.
+     */
+    get configuredScopeCount(): number;
+    /**
+     * Checks whether a failed attachment owns unfinished rollback.
+     *
+     * @internal
+     * @returns Whether rollback remains.
+     */
+    get failedStartPending(): boolean;
+    /**
+     * Checks whether a rejection owns failed-start rollback retry.
+     *
+     * @internal
+     * @param error Supplies the rejection.
+     * @returns Whether retry is required.
+     */
+    failedStartRetryPending(error: unknown): boolean;
+    /**
+     * Checks whether detachment made an endpoint safe.
+     *
+     * @internal
+     * @param attachment Identifies the attachment.
+     * @returns Whether the endpoint is safe.
+     */
+    endpointSafe(attachment: EnvironmentAttachmentHandle): boolean;
+    /**
+     * Checks whether an attachment owns rejected detach work.
+     *
+     * @internal
+     * @param attachment Identifies the attachment.
+     * @returns Whether detach retry is pending.
+     */
+    detachRetryPending(attachment: EnvironmentAttachmentHandle): boolean;
+    /**
+     * Attaches configured descriptors to an environment generation.
+     *
+     * @param options Supplies ownership and descriptors.
+     * @returns The successful attachment handle.
+     */
+    attach(options: EnvironmentAttachOptions): Promise<EnvironmentAttachmentHandle>;
+    /**
+     * Stops delivery work while preserving a retryable failed stop.
+     *
+     * @returns A promise that settles after delivery work stops.
+     */
+    stopDelivery(): Promise<void>;
+    /**
+     * Retries a previously rejected delivery stop.
+     *
+     * @returns A promise that settles after the stop retry completes.
+     */
+    retryDeliveryStop(): Promise<void>;
+    /**
+     * Accepts permanent close after all active registrations retire.
+     *
+     * @internal
+     * @returns A promise that resolves after permanent close is admitted.
+     */
+    admitPermanentClose(): Promise<void>;
+    /**
+     * Removes one attached registration.
+     *
+     * @param attachment Identifies the attachment to detach.
+     * @returns A promise that settles after the attachment detaches.
+     */
+    detach(attachment: EnvironmentAttachmentHandle): Promise<void>;
+    /**
+     * Retries rejected detachment for one attachment.
+     *
+     * @param attachment Identifies the attachment to retry.
+     * @returns A promise that settles after the detach retry completes.
+     */
+    retryDetach(attachment: EnvironmentAttachmentHandle): Promise<void>;
+    /**
+     * Retries rollback following a rejected attachment start.
+     *
+     * @returns A promise that settles after failed-start rollback retries.
+     */
+    retryFailedStart(): Promise<void>;
+}
+interface RegistrationBinding {
+    generation: EnvironmentGeneration;
+}
+type TransitionScopeSource = "configured" | "startup" | "buffered" | "retained";
+/**
+ * Buffers descriptor readiness while one attachment transitions between generations.
+ *
+ * @internal
+ */
+export declare class RegistrationReadiness {
+    #private;
+    /**
+     * Creates readiness buffering for configured descriptors.
+     *
+     * @param descriptors Supplies descriptors and their initial scopes.
+     * @param onPrepare Converts a readiness notification into a scope.
+     * @param onNotify Delivers an opened scope to its generation.
+     */
+    constructor(descriptors: readonly {
+        readonly descriptor: ContextDeliveryDescriptor;
+        readonly scopes: readonly DeliveryRunScope[];
+    }[], onPrepare: (descriptor: ContextDeliveryDescriptor, ready: DeliveryReady) => DeliveryRunScope, onNotify: (scope: DeliveryRunScope) => void);
+    /**
+     * Records or forwards one endpoint readiness notification.
+     *
+     * @param descriptor Identifies the reporting descriptor.
+     * @param ready Supplies the ready endpoint.
+     */
+    notify(descriptor: ContextDeliveryDescriptor, ready: DeliveryReady): void;
+    /**
+     * Clears readiness and discards buffered notifications.
+     */
+    fail(): void;
+    /**
+     * Prepares notification buffering for a generation transition.
+     *
+     * @param onBuffered Receives notifications buffered during the transition.
+     */
+    prepareTransition(onBuffered: (descriptor: ContextDeliveryDescriptor, ready: DeliveryReady) => void): void;
+    /**
+     * Updates every descriptor for a replacement generation.
+     *
+     * @param onPrepare Converts readiness into replacement scopes.
+     * @param onNotify Delivers opened replacement scopes.
+     */
+    rebind(onPrepare: (descriptor: ContextDeliveryDescriptor, ready: DeliveryReady) => DeliveryRunScope, onNotify: (scope: DeliveryRunScope) => void): void;
+    /**
+     * Updates one descriptor for a replacement generation.
+     *
+     * @param descriptor Identifies the descriptor to rebind.
+     * @param onPrepare Converts readiness into replacement scopes.
+     * @param onNotify Delivers opened replacement scopes.
+     */
+    rebindDescriptor(descriptor: ContextDeliveryDescriptor, onPrepare: (descriptor: ContextDeliveryDescriptor, ready: DeliveryReady) => DeliveryRunScope, onNotify: (scope: DeliveryRunScope) => void): void;
+    /**
+     * Opens readiness and returns initial plus buffered scopes.
+     *
+     * @param startup Supplies scopes recovered during startup.
+     * @returns Immutable scopes to run or notify.
+     */
+    open(startup: readonly DeliveryRunScope[]): readonly DeliveryRunScope[];
+}
+/**
+ * Exposes the registration-assembly evidence seam used by direct server tests.
+ * @internal
+ */
+export interface EnvironmentAttachmentAccess {
+    /**
+     * Converts a finite startup settlement into registration-scoped parked evidence.
+     *
+     * @param token Identifies the registration.
+     * @param scopes Supplies configured startup scopes.
+     * @param settlement Supplies the finite recovery settlement.
+     * @returns Parked-obligation evidence for the registration.
+     */
+    startupObligations(token: string, scopes: readonly DeliveryRunScope[], settlement: DeliveryRunSettlement): ParkedDeliveryObligations;
+}
+/**
+ * Exposes owner-bound registration-assembly test operations.
+ * @internal
+ */
+export declare const EnvironmentAttachmentAccess: Readonly<EnvironmentAttachmentAccess>;
+//# sourceMappingURL=environment-attachment.d.ts.map

package/dist/server/environment-attachment.d.ts.map

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