@pattern-js/runtime-node 0.2.0

package/dist/filesystem.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @pattern-js/runtime-node — storage layer (admin-spec P1/§3), backed by **flystorage**.
+ *
+ * `boundary.http.app` serves static assets and the admin's `WorkflowStore`
+ * persists workflow JSON — both over flystorage's `FileStorage`, the universal
+ * interface across adapters. Today we ship local-fs and in-memory; swapping in
+ * S3 / GCS / Azure later is a one-line adapter change with no consumer edits.
+ *
+ * Filesystems are registered on the engine as a named service (a
+ * `FilesystemRegistry` under the `"filesystems"` service key) so the HTTP host
+ * and any mod (the admin) resolve them by name and share one instance.
+ */
+import { FileStorage } from "@flystorage/file-storage";
+import type { Engine } from "@pattern-js/core";
+export { FileStorage } from "@flystorage/file-storage";
+export type { StatEntry, FileInfo } from "@flystorage/file-storage";
+/** The storage handle consumers depend on (flystorage's `FileStorage`). */
+export type Filesystem = FileStorage;
+/** A `FileStorage` rooted at a local directory (local-fs adapter). */
+export declare function localFs(rootDir: string): FileStorage;
+/** An ephemeral in-memory `FileStorage` (tests, placeholder assets). */
+export declare function memoryFs(): FileStorage;
+/** Coerce a `Filesystem | string` (dir path) into a `FileStorage`. */
+export declare function toFilesystem(fs: FileStorage | string): FileStorage;
+/** A named collection of filesystems shared via the engine's service bag. */
+export declare class FilesystemRegistry {
+    private map;
+    set(name: string, fs: FileStorage): void;
+    get(name: string): FileStorage | undefined;
+    names(): string[];
+}
+/** The service key the filesystem registry is registered under. */
+export declare const FILESYSTEMS_SERVICE = "filesystems";
+/** Get (or lazily create + register) the engine's filesystem registry. */
+export declare function filesystems(engine: Engine): FilesystemRegistry;
+/** Register a named filesystem on the engine (shared by the app boundary + mods). */
+export declare function provideFilesystem(engine: Engine, name: string, fs: FileStorage): void;
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../src/filesystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpE,2EAA2E;AAC3E,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC;AAErC,sEAAsE;AACtE,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAEpD;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,IAAI,WAAW,CAEtC;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,GAAG,WAAW,CAElE;AAID,6EAA6E;AAC7E,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,GAAG,CAAkC;IAC7C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI;IAGxC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAG1C,KAAK,IAAI,MAAM,EAAE;CAGlB;AAED,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAO9D;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,CAErF"}

package/dist/filesystem.js

@@ -0,0 +1,59 @@
+/**
+ * @pattern-js/runtime-node — storage layer (admin-spec P1/§3), backed by **flystorage**.
+ *
+ * `boundary.http.app` serves static assets and the admin's `WorkflowStore`
+ * persists workflow JSON — both over flystorage's `FileStorage`, the universal
+ * interface across adapters. Today we ship local-fs and in-memory; swapping in
+ * S3 / GCS / Azure later is a one-line adapter change with no consumer edits.
+ *
+ * Filesystems are registered on the engine as a named service (a
+ * `FilesystemRegistry` under the `"filesystems"` service key) so the HTTP host
+ * and any mod (the admin) resolve them by name and share one instance.
+ */
+import { resolve } from "node:path";
+import { FileStorage } from "@flystorage/file-storage";
+import { LocalStorageAdapter } from "@flystorage/local-fs";
+import { InMemoryStorageAdapter } from "@flystorage/in-memory";
+export { FileStorage } from "@flystorage/file-storage";
+/** A `FileStorage` rooted at a local directory (local-fs adapter). */
+export function localFs(rootDir) {
+    return new FileStorage(new LocalStorageAdapter(resolve(rootDir)));
+}
+/** An ephemeral in-memory `FileStorage` (tests, placeholder assets). */
+export function memoryFs() {
+    return new FileStorage(new InMemoryStorageAdapter());
+}
+/** Coerce a `Filesystem | string` (dir path) into a `FileStorage`. */
+export function toFilesystem(fs) {
+    return typeof fs === "string" ? localFs(fs) : fs;
+}
+// ── Engine service registry ──
+/** A named collection of filesystems shared via the engine's service bag. */
+export class FilesystemRegistry {
+    map = new Map();
+    set(name, fs) {
+        this.map.set(name, fs);
+    }
+    get(name) {
+        return this.map.get(name);
+    }
+    names() {
+        return [...this.map.keys()];
+    }
+}
+/** The service key the filesystem registry is registered under. */
+export const FILESYSTEMS_SERVICE = "filesystems";
+/** Get (or lazily create + register) the engine's filesystem registry. */
+export function filesystems(engine) {
+    let reg = engine.service(FILESYSTEMS_SERVICE);
+    if (!reg) {
+        reg = new FilesystemRegistry();
+        engine.provideService(FILESYSTEMS_SERVICE, reg);
+    }
+    return reg;
+}
+/** Register a named filesystem on the engine (shared by the app boundary + mods). */
+export function provideFilesystem(engine, name, fs) {
+    filesystems(engine).set(name, fs);
+}
+//# sourceMappingURL=filesystem.js.map

package/dist/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","sourceRoot":"","sources":["../src/filesystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAG/D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAMvD,sEAAsE;AACtE,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,IAAI,WAAW,CAAC,IAAI,mBAAmB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,QAAQ;IACtB,OAAO,IAAI,WAAW,CAAC,IAAI,sBAAsB,EAAE,CAAC,CAAC;AACvD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,YAAY,CAAC,EAAwB;IACnD,OAAO,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACnD,CAAC;AAED,gCAAgC;AAEhC,6EAA6E;AAC7E,MAAM,OAAO,kBAAkB;IACrB,GAAG,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC7C,GAAG,CAAC,IAAY,EAAE,EAAe;QAC/B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACzB,CAAC;IACD,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,KAAK;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9B,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,IAAI,GAAG,GAAG,MAAM,CAAC,OAAO,CAAqB,mBAAmB,CAAC,CAAC;IAClE,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAI,kBAAkB,EAAE,CAAC;QAC/B,MAAM,CAAC,cAAc,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,IAAY,EAAE,EAAe;IAC7E,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @pattern-js/runtime-node — HTTP host (§6, §7).
+ *
+ * Routing is **declarative**: the host derives its routes from the
+ * `boundary.http.request` nodes of the workflows registered on the engine. Each
+ * node's config carries the method, path, port, CORS policy, and JSON-Schema
+ * validation for body/query — there is no programmatic route table. When
+ * workflows change at runtime (e.g. loaded/updated from a DB), the host
+ * re-derives its routes live, opening/closing servers per declared port.
+ *
+ * Response modes: `buffered`, `sse` (Server-Sent Events), `chunked`.
+ */
+import { type Server } from "node:http";
+import { type Engine } from "@pattern-js/core";
+export interface HttpHostOptions {
+    /**
+     * Default port for routes that don't declare their own `port`. If omitted,
+     * the host uses the `PORT` env var, then falls back to 3000.
+     */
+    defaultPort?: number;
+    /** Interface to bind. Default all interfaces. */
+    host?: string;
+    /**
+     * Max buffered request-body size in bytes (413 beyond it). Default 10 MiB.
+     * Routes with `bodyMode: "stream"` are exempt — they never buffer.
+     */
+    maxBodyBytes?: number;
+}
+export declare class HttpHost {
+    private readonly engine;
+    private readonly opts;
+    private servers;
+    /** Live sockets per server, so shutdown can force-close lingering connections
+     *  (e.g. an open SSE stream that would otherwise keep `close()` pending). */
+    private sockets;
+    private routes;
+    private apps;
+    private unsubscribe?;
+    private readonly defaultPort;
+    private readonly serverListeners;
+    constructor(engine: Engine, opts?: HttpHostOptions);
+    /** Derive routes from registered workflows, open servers, and watch for changes. */
+    start(): Promise<{
+        ports: number[];
+        close: () => Promise<void>;
+    }>;
+    /**
+     * Loud, honest signal: with NO auth provider installed, any route that
+     * *declares* `requireAuth` can't be enforced (nobody can authenticate) — the
+     * engine serves it open (advisory). Say so plainly at boot so it's never a
+     * silent surprise. Add a provider and the same declarations are enforced.
+     */
+    private warnIfUnenforceableAuth;
+    /** Tail of the rebuild queue — see `rebuild()`. */
+    private rebuilding;
+    /**
+     * Scan workflows for `boundary.http.request` routes and reconcile servers.
+     * Rebuilds are serialized: workflow-change events can fire in rapid bursts
+     * (project load, admin batch deploys), and two interleaved reconciles would
+     * race `openServer` on the same port into EADDRINUSE.
+     */
+    private rebuild;
+    private rebuildNow;
+    /** Close one server, destroying any lingering sockets first. */
+    private closeServer;
+    private scanRoutes;
+    /**
+     * Scan workflows for `boundary.http.app` mounts (admin-spec P1). The trigger
+     * declares the HTTP side (mount/port/cors/auth); the app itself is *resolved
+     * by running the workflow once* — the run flows trigger → app op (e.g.
+     * `core.app.static`, `admin.app`) → the `boundary.http.app.serve` out-gate,
+     * whose captured `app` descriptor tells the host what to serve.
+     */
+    private scanApps;
+    /** The first app mount on `port` whose prefix matches `pathname`. */
+    private matchApp;
+    private openServer;
+    /** The live http.Server for `port`, if open (e.g. to attach a WS host). */
+    server(port: number): Server | undefined;
+    /**
+     * Run `cb` for every open server, now and as new ports open (route
+     * reconciliation opens/closes servers live) — the WS auto-wiring seam.
+     */
+    onServer(cb: (server: Server, port: number) => void): () => void;
+    private match;
+    private handle;
+    /** Serve a static asset (or SPA fallback) for an app mount (admin-spec P1). */
+    private serveApp;
+    private preflight;
+    close(): Promise<void>;
+}
+/** Create an HTTP host that derives its routes from the engine's workflows. */
+export declare function createHttpHost(engine: Engine, opts?: HttpHostOptions): HttpHost;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAIjG,OAAO,EAKL,KAAK,MAAM,EAMZ,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA+KD,qBAAa,QAAQ;IAYjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAZvB,OAAO,CAAC,OAAO,CAA6B;IAC5C;iFAC6E;IAC7E,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,IAAI,CAAkB;IAC9B,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqD;gBAGlE,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,eAAoB;IAQ7C,oFAAoF;IAC9E,KAAK,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IASvE;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAY/B,mDAAmD;IACnD,OAAO,CAAC,UAAU,CAAoC;IAEtD;;;;;OAKG;IACH,OAAO,CAAC,OAAO;YAOD,UAAU;IAexB,gEAAgE;IAChE,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,UAAU;IAgClB;;;;;;OAMG;YACW,QAAQ;IAuCtB,qEAAqE;IACrE,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAoClB,2EAA2E;IAC3E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAMhE,OAAO,CAAC,KAAK;YAaC,MAAM;IAyIpB,+EAA+E;YACjE,QAAQ;IAgFtB,OAAO,CAAC,SAAS;IAYX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B;AAsLD,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,QAAQ,CAE/E"}