@fabrika/daemon-kit 0.8.2 → 0.9.0-cloudflare.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/daemon-kit",
-	"version": "0.8.2",
+	"version": "0.9.0-cloudflare.1",
 	"type": "module",
 	"description": "Bun daemon lifecycle, HTTP routing, WebSocket channels and CLI waiters.",
 	"license": "MIT",
@@ -15,12 +15,13 @@
 	"files": [
 		"index.ts",
 		"src",
-		"!src/**/*.test.ts"
+		"!src/**/*.test.ts",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./index.ts",
-			"types": "./index.ts",
+			"types": "./types/index.d.ts",
 			"default": "./index.ts"
 		}
 	},

package/types/index.d.ts

@@ -0,0 +1,9 @@
+export { browserFrame, createNotificationChannel } from './src/channel';
+export type { BrowserFrameHandler, ChannelRole, ChannelSocket, NotificationChannel, NotificationChannelOptions, RelayOptions, TopicChannel, } from './src/channel';
+export { corsHeaders, jsonResponse } from './src/http-utils';
+export { createDaemonLifecycle, DaemonStartError, DaemonStopError } from './src/lifecycle';
+export type { DaemonEvent, DaemonHealth, DaemonHealthDown, DaemonHealthUp, DaemonLifecycle, DaemonLifecycleConfig, DaemonPid, DaemonStopReason, DaemonStopResult, DaemonTimeouts, } from './src/lifecycle';
+export { dispatch } from './src/router';
+export type { Route, RouteHandler } from './src/router';
+export { WaitError, waitForEvent } from './src/waiter';
+export type { WaiterSocket, WaitFailure, WaitMessages, WaitOptions, WaitVerdict } from './src/waiter';

package/types/src/channel.d.ts

@@ -0,0 +1,74 @@
+export type ChannelRole = 'browser' | 'wait';
+/** The minimum a host socket must offer; `Bun.ServerWebSocket` satisfies it. */
+export interface ChannelSocket {
+    send(message: string): unknown;
+    close(): void;
+    ping(): unknown;
+}
+export interface RelayOptions {
+    /**
+     * Close every waiter the message was handed to and drop the topic's waiter
+     * set. Defaults to the channel's `waiterPolicy`.
+     */
+    close?: boolean;
+}
+/** Channel operations bound to one topic. */
+export interface TopicChannel {
+    readonly topic: string;
+    /** Send to every browser on the topic. */
+    broadcast(message: unknown): void;
+    /** Send to every waiter on the topic; `false` when there was none. */
+    relayToWaiters(message: unknown, options?: RelayOptions): boolean;
+    hasWaiter(): boolean;
+    /** Announce current waiter presence to the topic's browsers. */
+    broadcastPresence(): void;
+}
+export interface BrowserFrameHandler {
+    /** The bound work when the frame is this handler's, `undefined` otherwise. */
+    bind(frame: unknown, channel: TopicChannel): (() => void | Promise<void>) | undefined;
+}
+/**
+ * Register one frame of a host's vocabulary. Matching is synchronous so the
+ * socket's `message` handler stays synchronous; handling may be async.
+ */
+export declare function browserFrame<T>(match: (frame: unknown) => frame is T, handle: (frame: T, channel: TopicChannel) => void | Promise<void>): BrowserFrameHandler;
+export interface NotificationChannelOptions<S extends ChannelSocket> {
+    /** Which registry a socket belongs to. */
+    roleOf(socket: S): ChannelRole;
+    /** The socket's routing key — a canvas session id, a Figma file key, … */
+    topicOf(socket: S): string;
+    /** The host's browser-frame vocabulary, tried in order; first match wins. */
+    frames?: readonly BrowserFrameHandler[];
+    /** Builds the presence frame. Presence is not announced when omitted. */
+    presenceFrame?(hasWaiter: boolean, topic: string): unknown;
+    /** What a relay does to the waiters it reached. Default `"keep-open"`. */
+    waiterPolicy?: 'close-on-delivery' | 'keep-open';
+    /**
+     * Runs after a waiter is registered and before presence is announced, so a
+     * host that buffers events for an absent waiter can flush them here.
+     */
+    onWaiterOpen?(channel: TopicChannel): void;
+    /** Frame handler failures. Dropped when omitted. */
+    onError?(error: unknown): void;
+    /** Liveness sweep period; `false` leaves the sweep to the host. */
+    pingIntervalMs?: number | false;
+}
+export interface NotificationChannel<S extends ChannelSocket> {
+    handlers: {
+        open(socket: S): void;
+        message(socket: S, message: string | Buffer): void;
+        pong(socket: S): void;
+        close(socket: S): void;
+    };
+    broadcast(topic: string, message: unknown): void;
+    relayToWaiters(topic: string, message: unknown, options?: RelayOptions): boolean;
+    hasWaiter(topic: string): boolean;
+    broadcastPresence(topic: string): void;
+    /** The topic-bound view handed to frame handlers. */
+    topic(topic: string): TopicChannel;
+    /** One liveness sweep — ping live waiters, evict the ones that never ponged. */
+    pingWaiters(): void;
+    /** Stop the liveness timer. */
+    stop(): void;
+}
+export declare function createNotificationChannel<S extends ChannelSocket>(options: NotificationChannelOptions<S>): NotificationChannel<S>;

package/types/src/http-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function jsonResponse(data: unknown, status?: number): Response;
+export declare function corsHeaders(port: number): Record<string, string>;

package/types/src/lifecycle.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Daemon process lifecycle: is it up, start it, stop it, keep it in step with
+ * the CLI that talks to it.
+ *
+ * The kernel owns the algorithm — health probing, the concurrent-start race,
+ * which pid may be signalled — and the host owns every location: base URL, pid
+ * file, spawn argv, log file, health shape, timeouts.
+ *
+ * The daemon's own pid, reported through `/health`, is the only pid this module
+ * will signal. A pid file is written at spawn and read only to notice that
+ * *someone* is already booting a daemon; a stale file or a reused pid must
+ * never let the CLI kill an unrelated process.
+ */
+/** Every host health shape must carry the daemon's own pid. */
+export interface DaemonPid {
+    pid: number;
+}
+export type DaemonHealthUp<H extends DaemonPid> = {
+    status: 'up';
+    ok: true;
+    url: string;
+} & H;
+export interface DaemonHealthDown {
+    status: 'down';
+    ok: false;
+    url: string;
+    error?: string;
+}
+export type DaemonHealth<H extends DaemonPid> = DaemonHealthUp<H> | DaemonHealthDown;
+export type DaemonStopReason = 'stopped' | 'not-running'
+/** Nothing was running; a pid file left behind was cleaned up. */
+ | 'stale-pid'
+/** A daemon answered `/health`, but signalling its pid failed. */
+ | 'signal-failed' | 'refused-self';
+export interface DaemonStopResult {
+    stopped: boolean;
+    /** The daemon's own pid, or the stale pid-file value that was cleaned up. */
+    pid?: number;
+    reason: DaemonStopReason;
+    message: string;
+}
+/** Progress worth telling a user about; the host writes the words. */
+export type DaemonEvent = {
+    type: 'version-mismatch';
+    running: string;
+    expected: string;
+} | {
+    type: 'starting';
+    command: readonly string[];
+} | {
+    type: 'started';
+    pid: number;
+} | {
+    type: 'stopped';
+    pid: number;
+};
+export interface DaemonTimeouts {
+    /** Per `/health` request. Default 1000. */
+    health?: number;
+    /** Wait for a daemon this process spawned. Default 3000. */
+    start?: number;
+    /** Wait for a daemon another process is already starting. Default 1000. */
+    concurrentStart?: number;
+    /** Wait for a signalled daemon to go down. Default 2000. */
+    stop?: number;
+}
+export interface DaemonLifecycleConfig<H extends DaemonPid> {
+    /** Daemon origin, e.g. `http://localhost:19400`. */
+    baseUrl: string;
+    /** Health endpoint path. Default `/health`. */
+    healthPath?: string;
+    /** Narrows the `/health` body; `undefined` means "not a daemon we can talk to". */
+    parseHealth(body: unknown): H | undefined;
+    /** Written at spawn, so a concurrent start can see a daemon that is still booting. */
+    pidFile: string;
+    /** argv of the daemon process, e.g. `[process.execPath, entry, "serve"]`. */
+    command: readonly string[];
+    /** Working directory of the spawned daemon. Defaults to the current one. */
+    cwd?: string;
+    /** File the daemon's stdout and stderr are appended to. */
+    logFile: string;
+    /** Restart the daemon when its version differs from this CLI's. Off when omitted. */
+    versionCheck?: {
+        expected: string;
+        of(health: H): string | undefined;
+    };
+    /** Removed with the pid file when the daemon stops (auth tokens, sockets, …). */
+    cleanupFiles?: readonly string[];
+    timeouts?: DaemonTimeouts;
+    onEvent?(event: DaemonEvent): void;
+}
+export declare class DaemonStartError extends Error {
+    readonly logFile: string;
+    readonly logTail: string;
+    constructor(message: string, logFile: string, logTail: string);
+}
+/** A daemon of the wrong version still answers after `stop()`, so no second one is spawned onto its port. */
+export declare class DaemonStopError extends Error {
+    readonly pid: number;
+    constructor(message: string, pid: number);
+}
+export interface DaemonLifecycle<H extends DaemonPid> {
+    health(timeoutMs?: number): Promise<DaemonHealth<H>>;
+    isRunning(): Promise<boolean>;
+    start(): Promise<DaemonHealthUp<H>>;
+    /**
+     * A healthy daemon of the expected version, starting or restarting one if needed.
+     * Throws `DaemonStopError` when a daemon of another version cannot be stopped.
+     */
+    ensure(): Promise<DaemonHealthUp<H>>;
+    stop(): Promise<DaemonStopResult>;
+    restart(): Promise<DaemonHealthUp<H>>;
+}
+export declare function createDaemonLifecycle<H extends DaemonPid>(config: DaemonLifecycleConfig<H>): DaemonLifecycle<H>;

package/types/src/router.d.ts

@@ -0,0 +1,7 @@
+export type RouteHandler = (req: Request, url: URL, match: URLPatternResult) => Response | Promise<Response>;
+export interface Route {
+    method: string;
+    pattern: URLPattern;
+    handler: RouteHandler;
+}
+export declare function dispatch(routes: Route[], req: Request, url: URL): Response | Promise<Response> | null;

package/types/src/waiter.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The CLI half of the notification channel: connect to a daemon's wait socket
+ * and block until the host says the wait is over.
+ *
+ * What settles the wait is a host predicate, so one helper covers "feedback
+ * arrived", "screens confirmed" and "a run was requested". The socket factory
+ * is injectable, which is what makes the retry and settle logic testable
+ * without a live daemon.
+ */
+/** The slice of `WebSocket` a waiter uses; a real `WebSocket` satisfies it. */
+export interface WaiterSocket {
+    close(): void;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+}
+/** What a frame means to the waiter; `undefined` means "not mine, keep waiting". */
+export type WaitVerdict<T> = {
+    type: 'settle';
+    value: T;
+} | {
+    type: 'fail';
+    error: Error;
+}
+/** Wake the probe — the frame announces state the waiter has to read back. */
+ | {
+    type: 'recheck';
+};
+export interface WaitMessages {
+    /** Deadline passed. Default: "Timed out waiting." */
+    timeout?: string;
+    /** Socket closed before the wait settled. Default: "Connection closed before the wait settled." */
+    closed?: string;
+    /** The socket errored. Default: "WebSocket connection failed." */
+    connectionFailed?: string;
+    /**
+     * `createSocket` threw, so no socket ever existed; the factory's own message
+     * is appended after a colon. Default: "Could not create the WebSocket".
+     */
+    socketCreateFailed?: string;
+}
+export interface WaitOptions<T> {
+    /** The daemon's wait socket, e.g. `ws://localhost:19400/ws/wait/<topic>`. */
+    url: string;
+    /** Reads a frame; returns how it settles the wait, if at all. */
+    onFrame(frame: unknown): WaitVerdict<T> | undefined;
+    /**
+     * Fast path against server state. Runs before connecting (unless the caller
+     * already did that read — see `alreadyProbed`), again once the socket opens —
+     * closing the race where the event lands between the two — and whenever a
+     * frame asks for a recheck. A probe that rejects is dropped: the socket, not
+     * the probe, is what the wait ultimately hangs on.
+     */
+    probe?(): Promise<{
+        value: T;
+    } | undefined>;
+    /**
+     * The caller has already made the probe's read itself and it came up empty,
+     * so the wait starts at the socket. Set it when that read is the caller's own
+     * error channel — a probe that rejects is dropped here, so a caller that must
+     * report *why* the read failed has to make it before calling. The on-open
+     * re-read still runs; it is what closes the subscribe race.
+     */
+    alreadyProbed?: boolean;
+    createSocket?(url: string): WaiterSocket;
+    /** Deadline for the whole wait, spanning reconnects. */
+    timeoutMs: number;
+    reconnect?: {
+        /** Reconnects after a dropped connection. Default 0. */
+        attempts?: number;
+        /** Delay before a reconnect, capped by the remaining deadline. Default 1000. */
+        delayMs?: number;
+    };
+    messages?: WaitMessages;
+}
+/** Why the wait ended without an answer; hosts map these onto their own errors. */
+export type WaitFailure = 'timeout' | 'closed'
+/** The socket was created, then errored. */
+ | 'connection-failed'
+/** `createSocket` threw — nothing was ever connected to. */
+ | 'socket-create-failed';
+export declare class WaitError extends Error {
+    readonly reason: WaitFailure;
+    readonly retryable: boolean;
+    constructor(message: string, reason: WaitFailure, retryable: boolean, options?: ErrorOptions);
+}
+export declare function waitForEvent<T>(options: WaitOptions<T>): Promise<T>;