@ewhauser/world-celld 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+import { CreateEventRequest, Event, Hook, RunCreatedEventRequest, Step, ValidQueueName, WorkflowRun, World } from "@workflow/world";
+//#region src/apply-event.d.ts
+interface ApplyEventRequest {
+  /** The effective run id (already resolved / generated by the caller). */
+  runId: string;
+  data: CreateEventRequest | RunCreatedEventRequest;
+  /**
+   * Current holder of the hook token per the global KV token index
+   * (hook_created only). `null` means the token is unclaimed.
+   */
+  tokenHolder?: {
+    runId: string;
+    hookId: string;
+  } | null;
+}
+type ApplyEventErrorCode = 'RUN_NOT_FOUND' | 'STEP_NOT_FOUND' | 'HOOK_NOT_FOUND' | 'ENTITY_CONFLICT' | 'RUN_EXPIRED' | 'TOO_EARLY' | 'RUN_NOT_SUPPORTED' | 'LEGACY_RUN_NOT_SUPPORTED';
+interface ApplyEventFailure {
+  ok: false;
+  code: ApplyEventErrorCode;
+  message: string;
+  /** Seconds until retry is allowed (TOO_EARLY only). */
+  retryAfterSeconds?: number;
+  /** The run's spec version (RUN_NOT_SUPPORTED only). */
+  runSpecVersion?: number;
+}
+interface ApplyEventSuccess {
+  ok: true;
+  /** Absent for idempotent replays that record no new event. */
+  event?: Event;
+  run?: WorkflowRun;
+  step?: Step;
+  hook?: Hook;
+  /** Hooks whose tokens must be released from the global KV index. */
+  releasedHooks: Array<{
+    hookId: string;
+    token: string;
+  }>;
+  /** Set when a run entity was created (run_created or resilient bootstrap). */
+  runCreated?: {
+    workflowName: string;
+    createdAt: Date;
+  };
+  /** Set when the global KV hook index must be (re)written. */
+  hookToIndex?: Hook;
+  /** All events (ascending), preloaded for run_started responses. */
+  events?: Event[];
+}
+type ApplyEventOutcome = ApplyEventSuccess | ApplyEventFailure;
+//#endregion
+//#region src/storage.d.ts
+/**
+ * RPC surface of WorkflowRunDO used by the storage layer. Declared
+ * structurally to avoid a circular type reference on the DO class.
+ */
+interface WorkflowRunDOStub {
+  applyEvent(request: ApplyEventRequest): Promise<ApplyEventOutcome>;
+  getRun(): Promise<WorkflowRun | null>;
+  getStep(stepId: string): Promise<Step | null>;
+  getEvent(eventId: string): Promise<Event | null>;
+  listEvents(params?: {
+    limit?: number;
+    cursor?: string;
+    sortOrder?: 'asc' | 'desc';
+  }): Promise<{
+    data: Event[];
+    cursor: string | null;
+    hasMore: boolean;
+  }>;
+  listSteps(params?: {
+    limit?: number;
+    cursor?: string;
+    sortOrder?: 'asc' | 'desc';
+  }): Promise<{
+    data: Step[];
+    cursor: string | null;
+    hasMore: boolean;
+  }>;
+  listHooks(params?: {
+    limit?: number;
+    cursor?: string;
+    sortOrder?: 'asc' | 'desc';
+  }): Promise<{
+    data: Hook[];
+    cursor: string | null;
+    hasMore: boolean;
+  }>;
+}
+interface WorkflowRunDONamespace {
+  idFromName(name: string): DurableObjectIdLike;
+  get(id: DurableObjectIdLike): WorkflowRunDOStub;
+}
+interface DurableObjectIdLike {
+  toString(): string;
+}
+//#endregion
+//#region src/streamer.d.ts
+/**
+ * RPC surface of StreamDO (see durable-objects/StreamDO.ts). The streamer
+ * talks to the DO exclusively via these methods — there is no fetch()
+ * protocol.
+ */
+interface StreamDOStub {
+  writeChunk(data: Uint8Array): Promise<number>;
+  closeStream(): Promise<void>;
+  getChunks(params: {
+    startIndex: number;
+    limit: number;
+  }): Promise<{
+    chunks: Uint8Array[];
+    done: boolean;
+    tailIndex: number;
+  }>;
+  getInfo(): Promise<{
+    tailIndex: number;
+    done: boolean;
+  }>;
+  registerStream(name: string): Promise<void>;
+  listStreams(): Promise<string[]>;
+}
+interface StreamDONamespace {
+  idFromName(name: string): StreamDOId;
+  get(id: StreamDOId): StreamDOStub;
+}
+interface StreamDOId {
+  toString(): string;
+}
+//#endregion
+//#region src/queue.d.ts
+type Pathname = 'flow' | 'step';
+/**
+ * Enqueue request accepted by a QueueDO cell. The message payload travels
+ * pre-encoded with the shared tagged-JSON codec (`body`), so the cell can
+ * forward it byte-identical to the app's queue handler without re-encoding.
+ */
+interface EnqueueRequest {
+  messageId: string;
+  queueName: ValidQueueName;
+  pathname: Pathname;
+  /** `stringify(message)` — the exact bytes POSTed to the app on delivery. */
+  body: string;
+  idempotencyKey?: string;
+  delaySeconds?: number;
+  /**
+   * Delivery configuration. The cell pins this from its first enqueue (the
+   * eve-ambient pattern); a later mismatch is rejected as CONFIG_MISMATCH.
+   */
+  config: QueueCellConfig;
+}
+interface QueueCellConfig {
+  /** Base URL of the app; deliveries POST to `${baseUrl}/.well-known/workflow/v1/{flow|step}`. */
+  targetBaseUrl: string;
+  queueShards: number;
+}
+type EnqueueOutcome = {
+  ok: true;
+  messageId: string;
+  deduped: boolean;
+} | {
+  ok: false;
+  code: 'CONFIG_MISMATCH';
+  message: string;
+};
+/** RPC surface of QueueDO used by the queue producer. */
+interface QueueCellStub {
+  enqueue(request: EnqueueRequest): Promise<EnqueueOutcome>;
+}
+interface QueueCellNamespace {
+  idFromName(name: string): {
+    toString(): string;
+  };
+  get(id: {
+    toString(): string;
+  }): QueueCellStub;
+}
+//#endregion
+//#region src/config.d.ts
+/** Storage-layer KV interface (satisfied by IndexDO over HTTP, or a mock). */
+interface IndexNamespace {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(options?: {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+    reverse?: boolean;
+  }): Promise<{
+    keys: Array<{
+      name: string;
+    }>;
+    list_complete: boolean;
+    cursor?: string;
+  }>;
+  reserveHookToken(token: string, owner: HookTokenOwner): Promise<{
+    claimed: boolean;
+    holder?: HookTokenOwner;
+  }>;
+  finalizeHookIndexes(token: string, hookId: string, serializedHook: string, owner: HookTokenOwner): Promise<void>;
+  releaseHookToken(token: string, owner: HookTokenOwner): Promise<void>;
+  deleteHookIndexes(token: string, hookId: string, owner: HookTokenOwner): Promise<void>;
+}
+interface HookTokenOwner {
+  runId: string;
+  hookId: string;
+}
+interface CelldWorldEnv {
+  WORKFLOW_DB: WorkflowRunDONamespace;
+  WORKFLOW_INDEX: IndexNamespace;
+  WORKFLOW_QUEUE: QueueCellNamespace;
+  WORKFLOW_STREAMS: StreamDONamespace;
+}
+interface CelldWorldConfig {
+  /**
+   * Base URL of any celld fleet node's public listener (e.g.
+   * `http://fleet.internal:8080`). Requests are routed to the deployed
+   * world-celld worker, which forwards them to the owning cells.
+   * Default: process.env.CELLD_FLEET_URL
+   */
+  fleetUrl?: string;
+  /**
+   * Bearer secret shared with the worker (its WORLD_SECRET var).
+   * Default: process.env.CELLD_WORLD_SECRET
+   */
+  secret?: string;
+  /**
+   * Pre-built namespaces (used by tests and the in-process harness). When
+   * provided, fleetUrl/secret are not used.
+   */
+  env?: CelldWorldEnv;
+  /** Default: process.env.CELLD_DEPLOYMENT_ID || 'celld-default' */
+  deploymentId?: string;
+  /**
+   * Base URL the app's workflow endpoints are mounted on; QueueDO cells
+   * deliver to `${baseUrl}/.well-known/workflow/v1/{flow|step}`.
+   * Default: process.env.WORKFLOW_BASE_URL || `http://localhost:${PORT ?? 3000}`
+   */
+  baseUrl?: string;
+  /** Number of queue cells to spread enqueues over. Default: 1 */
+  queueShards?: number;
+  /** Poll interval (ms) while waiting for new chunks on a live stream. Default: 250 */
+  readPollMs?: number;
+  /** Per-attempt fleet RPC deadline in milliseconds. Default: 30000 */
+  rpcTimeoutMs?: number;
+}
+//#endregion
+//#region src/index.d.ts
+declare function createCelldWorld(config?: CelldWorldConfig): World;
+//#endregion
+export { type CelldWorldConfig, type CelldWorldEnv, type EnqueueOutcome, type EnqueueRequest, type IndexNamespace, type QueueCellConfig, type QueueCellNamespace, type QueueCellStub, type StreamDONamespace, type StreamDOStub, type WorkflowRunDONamespace, type WorkflowRunDOStub, createCelldWorld, createCelldWorld as createWorld };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/apply-event.ts","../src/storage.ts","../src/streamer.ts","../src/queue.ts","../src/config.ts","../src/index.ts"],"mappings":";;UAsFiB;;EAEf;EACA,MAAM,qBAAqB;;;;;EAK3B;IAAgB;IAAe;;;KAGrB;UAUK;EACf;EACA,MAAM;EACN;;EAEA;;EAEA;;UAGe;EACf;;EAEA,QAAQ;EACR,MAAM;EACN,OAAO;EACP,OAAO;;EAEP,eAAe;IAAQ;IAAgB;;;EAEvC;IAAe;IAAsB,WAAW;;;EAEhD,cAAc;;EAEd,SAAS;;KAGC,oBAAoB,oBAAoB;;;;;;;UCrFnC;EACf,WAAW,SAAS,oBAAoB,QAAQ;EAChD,UAAU,QAAQ;EAClB,QAAQ,iBAAiB,QAAQ;EACjC,SAAS,kBAAkB,QAAQ;EACnC,WAAW;IACT;IACA;IACA;MACE;IAAU,MAAM;IAAS;IAAuB;;EACpD,UAAU;IACR;IACA;IACA;MACE;IAAU,MAAM;IAAQ;IAAuB;;EACnD,UAAU;IACR;IACA;IACA;MACE;IAAU,MAAM;IAAQ;IAAuB;;;UAGpC;EACf,WAAW,eAAe;EAC1B,IAAI,IAAI,sBAAsB;;UAGf;EACf;;;;;;;;;UCpDe;EACf,WAAW,MAAM,aAAa;EAC9B,eAAe;EACf,UAAU;IACR;IACA;MACE;IAAU,QAAQ;IAAc;IAAe;;EACnD,WAAW;IAAU;IAAmB;;EACxC,eAAe,eAAe;EAC9B,eAAe;;UAGA;EACf,WAAW,eAAe;EAC1B,IAAI,IAAI,aAAa;;UAGN;EACf;;;;KCYG;;;;;;UAoBY;EACf;EACA,WAAW;EACX,UAAU;;EAEV;EACA;EACA;;;;;EAKA,QAAQ;;UAGO;;EAEf;EACA;;KAGU;EACN;EAAU;EAAmB;;EAC7B;EAAW;EAAyB;;;UAGzB;EACf,QAAQ,SAAS,iBAAiB,QAAQ;;UAG3B;EACf,WAAW;IAAiB;;EAC5B,IAAI;IAAM;MAAuB;;;;;UCtGlB;EACf,IAAI,cAAc;EAClB,IAAI,aAAa,gBAAgB;EACjC,OAAO,cAAc;EACrB,KAAK;IAAY;IAAiB;IAAiB;IAAgB;MAAsB;IACvF,MAAM;MAAQ;;IACd;IACA;;EAEF,iBACE,eACA,OAAO,iBACN;IAAU;IAAkB,SAAS;;EACxC,oBACE,eACA,gBACA,wBACA,OAAO,iBACN;EACH,iBAAiB,eAAe,OAAO,iBAAiB;EACxD,kBAAkB,eAAe,gBAAgB,OAAO,iBAAiB;;UAG1D;EACf;EACA;;UAGe;EACf,aAAa;EACb,gBAAgB;EAChB,gBAAgB;EAChB,kBAAkB;;UAGH;;;;;;;EAOf;;;;;EAKA;;;;;EAKA,MAAM;;EAEN;;;;;;EAMA;;EAEA;;EAEA;;EAEA;;;;iBChDc,iBAAiB,SAAS,mBAAmB"}