experimental-a2 0.3.0 → 0.5.0

package/dist/http.d.ts

@@ -1,37 +1,40 @@
-import { a as Event } from "./log-ldf5g8Cx.js";
-import { PushedEvent } from "./server.js";
-import { t as A2Error } from "./errors-xL_JTXsY.js";
-//#region src/http.d.ts
-/** The push envelope: what a client POSTs to append events. */
-type PushBody = {
-  sessionId: string;
-  /** Branded: `session.append` accepts these directly (the push route
-   * path); schema validation still happens inside `append`. */
-  events: PushedEvent[];
-};
+import { a as EventDefs, o as PresenceDefs, r as ContractEvent } from "./contract-jIfaR085.js";
+import { f as PushedEvent, i as DrainableServer, n as A2Server, p as PushedPresence } from "./server-DUF9pjsx.js";
+import { t as A2Error } from "./errors-W6nwJ-fm.js";
+//#region src/session-socket.d.ts
 /**
- * Validate the push envelope — `{ sessionId, events }` — throwing
- * `INVALID_PAYLOAD` on a malformed body. Payload validation against the
- * machine's schemas happens in `append`, not here.
+ * The structural socket `sessionsSocket` speaks against — satisfied
+ * by `ws` and by `@vercel/functions`' upgraded socket alike, so the
+ * platform upgrade API stays out of the library. `message` data
+ * arrives as whatever the platform delivers (string, Buffer,
+ * ArrayBuffer, or fragments); the handler normalizes defensively.
  */
-declare function parsePushBody(req: Request): Promise<PushBody>;
+type A2Socket = {
+  send(data: string): void;
+  on(event: "message", listener: (data: unknown) => void): void;
+  on(event: "close", listener: () => void): void;
+  on(event: "error", listener: (error: unknown) => void): void;
+  close(code?: number, reason?: string): void;
+  /** Bytes queued but not yet transmitted — when exposed, the down
+   * pump uses it for backpressure (`SOCKET_TIMINGS`). */
+  bufferedAmount?: number;
+};
+//#endregion
+//#region src/http.d.ts
 /**
- * Pipe a live event iterable into an SSE `Response`. Each event is one
- * frame — `id:` carries the log index, `data:` the JSON event. A
- * disconnecting client cancels the stream, which closes the underlying
- * subscription. Two kinds of comment frames ride along: a `: connected`
- * prelude that flushes headers immediately, and a `: ping` heartbeat
- * every 15 seconds so clients (and proxies) can tell a quiet stream
- * from a dead connection — the session client's stall watchdog counts
- * on it.
+ * Create one scheduler callback route for servers sharing the same configured
+ * scheduler. Configuration mistakes throw immediately while the route module
+ * is evaluated, before a delivery can be acknowledged by the wrong adapter.
  */
-declare function sseResponse(iterable: AsyncIterable<Event>): Response;
+declare function schedulerHandler(firstServer: DrainableServer, ...servers: DrainableServer[]): (req: Request) => Promise<Response>;
 /**
  * Serialize an error into the documented wire shape,
  * `{ error: { code, message, details } }`, with the mapped status
- * (400 for caller bugs, 503 for LOG_UNAVAILABLE). Non-A2Errors become a
- * 503 LOG_UNAVAILABLE — from the client's perspective an unknown server
- * failure is retryable-once, not a protocol contract.
+ * (400 for caller bugs, 503 for STORE_UNAVAILABLE). Non-A2Errors become a
+ * 503 STORE_UNAVAILABLE — from the client's perspective an unknown server
+ * failure is retryable-once, not a protocol contract. The natural
+ * return value of a `before` hook that wants the wire's own error
+ * shapes.
  */
 declare function errorResponse(error: unknown): Response;
 /**
@@ -40,5 +43,109 @@ declare function errorResponse(error: unknown): Response;
  * sides branch on identical codes.
  */
 declare function deserializeError(body: unknown): A2Error | null;
+/**
+ * What a request (or socket frame) asks of a session, parsed — the
+ * argument policy hooks branch on. `stream` covers the SSE GET and the
+ * socket's subscribe frames; `push` covers the HTTP POST and the
+ * socket's push frames; `history` is the bounded cold read the
+ * client's `loadHistory` rides; `ws-upgrade` is the upgrade GET before
+ * any frame flows.
+ */
+type A2Intent<D extends EventDefs = EventDefs> = {
+  type: "ws-upgrade";
+} | {
+  type: "stream";
+  sessionId: string;
+  startAfter: number;
+  transport: "sse" | "ws";
+} | {
+  type: "history";
+  sessionId: string;
+  gte: number;
+  lte: number;
+} | {
+  type: "push";
+  sessionId: string;
+  /** Parsed and branded, payloads not yet validated — `type`
+   * autocompletes the contract's names but is any string off the
+   * wire; `append` rejects unknown types after the hooks run. */
+  events: Array<PushedEvent & {
+    type: SuggestedEventType<D>;
+  }>;
+  presence?: PushedPresence;
+  transport: "http" | "ws";
+};
+/** The contract's event names for editor completion, without excluding
+ * the wire's reality (any string can arrive; validation is later). */
+type SuggestedEventType<D extends EventDefs> = (keyof D & string) | (string & Record<never, never>);
+/** What the library did with an allowed intent — `after`'s view.
+ * `covered` = the closed range is fully present (an immutable slice of
+ * the append-only log), the one caching-relevant fact the library
+ * owns; policy over it belongs to the app's `after`. */
+type A2Outcome<D extends EventDefs = EventDefs> = {
+  type: "stream";
+} | {
+  type: "history";
+  covered: boolean;
+  events: ContractEvent<D>[];
+} | {
+  type: "push";
+  appended: ContractEvent<D>[];
+};
+/**
+ * The platform's socket-upgrade seam: given the attach callback, return
+ * the 101 response. On Vercel:
+ * `upgrade: (attach) => experimental_upgradeWebSocket(attach)`.
+ */
+type UpgradeFn = (attach: (socket: A2Socket) => void) => Response | Promise<Response>;
+/** One bag: the policy hooks and the capability options — the names
+ * distinguish them, so `handle(server, { presence: true })` and
+ * `handle(server, { before, upgrade })` both read naturally. */
+type HandleOptions<D extends EventDefs = EventDefs> = {
+  /** Return a Response to deny; thrown errors are treated as
+   * infrastructure failures and answer with the retryable wire shape. */
+  before?(args: {
+    request: Request;
+    intent: A2Intent<D>;
+  }): Response | undefined | void | Promise<Response | undefined | void>;
+  after?(args: {
+    request: Request;
+    intent: A2Intent<D>;
+    outcome: A2Outcome<D>;
+    response: Response;
+  }): Response | undefined | void | Promise<Response | undefined | void>;
+  upgrade?: UpgradeFn;
+  presence?: boolean;
+  deadline?: number;
+};
+/**
+ * The session route pair as one call: `export const { GET, POST } =
+ * handle(server, options?)` serves the live stream (SSE GET, resumed
+ * at `index`), the history slice (GET with `gte`/`lte`), the push
+ * envelope (POST), and — with `options.upgrade` — the multiplexed
+ * WebSocket, all through one pair of policy hooks.
+ *
+ * Parsing is protocol, hooks are policy: a request that fails to parse
+ * (missing sessionId, malformed bounds, bad push envelope) answers
+ * INVALID_PAYLOAD on the wire before any hook runs. `before` sees
+ * every parsed intent — HTTP requests and socket frames alike, with
+ * `request` always the original (for socket frames: upgrade) Request —
+ * and short-circuits by returning a Response: over HTTP it is the
+ * response verbatim; over the socket it is translated to the wire's
+ * own vocabulary (subscribe → `unsubscribed { reason: 'subscribe
+ * rejected' }`, push → an INVALID_PAYLOAD error ack), because a
+ * Response body cannot cross a socket. `after` runs only where the
+ * library produced an HTTP response — never after a short-circuit,
+ * never for socket frames — and may mutate `response.headers` in place
+ * or return a replacement (history caching policy lives here, on
+ * `outcome.covered`). `options.deadline` (epoch ms) closes sockets
+ * cleanly ahead of a known platform deadline, so clients reconnect on
+ * our schedule.
+ */
+declare function handle<D extends EventDefs, P extends PresenceDefs = Record<never, never>>(server: A2Server<D, P>, options?: HandleOptions<D>): {
+  GET(req: Request): Promise<Response>;
+  POST(req: Request): Promise<Response>;
+};
 //#endregion
-export { PushBody, deserializeError, errorResponse, parsePushBody, sseResponse };
+export { A2Intent, A2Outcome, type A2Socket, HandleOptions, UpgradeFn, deserializeError, errorResponse, handle, schedulerHandler };
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","names":[],"sources":["../src/session-socket.ts","../src/http.ts"],"mappings":";;;;;;;;;;;KAkCY;EACV,KAAK;EACL,GAAG,kBAAkB,WAAW;EAChC,GAAG,gBAAgB;EACnB,GAAG,gBAAgB,WAAW;EAC9B,MAAM,eAAe;;;EAGrB;;;;;;;;;iBCUc,iBACd,aAAa,oBACV,SAAS,qBACV,KAAK,YAAY,QAAQ;;;;;;;;;;iBAoBb,cAAc,iBAAiB;;;;;;iBAY/B,iBAAiB,gBAAgB;;;;;;;;;KAcrC,SAAS,UAAU,YAAY;EACrC;;EAEA;EACA;EACA;EACA;;EAEA;EAAiB;EAAmB;EAAa;;EAEjD;EACA;;;;EAIA,QAAQ,MAAM;IAAgB,MAAM,mBAAmB;;EACvD,WAAW;EACX;;;;KAKD,mBAAmB,UAAU,oBACzB,wBAAwB;;;;;KAMrB,UAAU,UAAU,YAAY;EACtC;;EACA;EAAiB;EAAkB,QAAQ,cAAc;;EACzD;EAAc,UAAU,cAAc;;;;;;;KAOhC,aACV,SAAS,QAAQ,sBACd,WAAW,QAAQ;;;;KA6CZ,cAAc,UAAU,YAAY;;;EAG9C,QAAQ;IACN,SAAS;IACT,QAAQ,SAAS;MACf,8BAA8B,QAAQ;EAC1C,OAAO;IACL,SAAS;IACT,QAAQ,SAAS;IACjB,SAAS,UAAU;IACnB,UAAU;MACR,8BAA8B,QAAQ;EAC1C,UAAU;EACV;EACA;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2Bc,OACd,UAAU,WACV,UAAU,eAAe,sBAEzB,QAAQ,SAAS,GAAG,IACpB,UAAU,cAAc;EAExB,IAAI,KAAK,UAAU,QAAQ;EAC3B,KAAK,KAAK,UAAU,QAAQ"}