oblien 2.2.36 → 2.2.38

package/dist/runtime/proxy.js

@@ -0,0 +1,79 @@
+/**
+ * A handle to a single loopback port inside the workspace, obtained via
+ * {@link Runtime.proxy}. Requests are forwarded by the runtime's `/proxy`
+ * endpoint to `127.0.0.1:<port>` inside the VM — headers, streaming/SSE, and
+ * WebSocket upgrades pass through near-natively. Only loopback ports are
+ * reachable; the proxy cannot reach the VM's network or the internet.
+ *
+ * ```ts
+ * const rt = await client.workspaces.runtime('ws_abc');
+ *
+ * // HTTP — returns a raw fetch Response
+ * const res = await rt.proxy(3000).fetch('/api/users');
+ * const users = await res.json();
+ *
+ * // Streaming (SSE) passes through
+ * const stream = await rt.proxy(3000).fetch('/events');
+ * for await (const chunk of stream.body!) { /* ... *\/ }
+ *
+ * // WebSocket
+ * const ws = rt.proxy(3000).ws('/socket');
+ * ws.onmessage = (e) => console.log(e.data);
+ * ```
+ */
+export class RuntimeProxy {
+    _httpBase;
+    _wsBase;
+    _token;
+    _target;
+    constructor(options, port, host) {
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new Error(`invalid proxy port: ${port} (must be 1-65535)`);
+        }
+        const base = (options.baseUrl ?? 'https://workspace.oblien.com').replace(/\/$/, '');
+        this._httpBase = base;
+        this._wsBase = base.replace(/^http/, 'ws');
+        this._token = options.token;
+        this._target = host ? `${host}:${port}` : String(port);
+    }
+    /**
+     * Make an HTTP request to the loopback service and return the raw `Response`.
+     * The path is passed through untouched (e.g. `/api/users?limit=10`). The
+     * runtime connection token is sent via the `Authorization` header and is
+     * stripped before the request reaches the in-VM app.
+     */
+    fetch(path, init = {}) {
+        const headers = new Headers(init.headers);
+        headers.set('Authorization', `Bearer ${this._token}`);
+        headers.set('X-Oblien-Proxy-Target', this._target);
+        return fetch(this._url(this._httpBase, path), {
+            method: init.method ?? 'GET',
+            headers,
+            body: init.body ?? null,
+            signal: init.signal,
+            redirect: init.redirect,
+        });
+    }
+    /**
+     * Open a WebSocket to the loopback service. Auth and target are passed as
+     * query params (`token`, `x_oblien_target`) because the browser WebSocket API
+     * cannot set request headers.
+     */
+    ws(path = '/', protocols) {
+        const url = this._url(this._wsBase, path, {
+            token: this._token,
+            x_oblien_target: this._target,
+        });
+        return new WebSocket(url, protocols);
+    }
+    _url(base, path, extraQuery) {
+        const p = path.startsWith('/') ? path : `/${path}`;
+        const u = new URL(base + '/proxy' + p);
+        if (extraQuery) {
+            for (const [k, v] of Object.entries(extraQuery))
+                u.searchParams.set(k, v);
+        }
+        return u.toString();
+    }
+}
+//# sourceMappingURL=proxy.js.map

package/dist/runtime/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../../src/runtime/proxy.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,YAAY;IACN,SAAS,CAAS;IAClB,OAAO,CAAS;IAChB,MAAM,CAAS;IACf,OAAO,CAAS;IAEjC,YAAY,OAAuB,EAAE,IAAY,EAAE,IAAa;QAC9D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,oBAAoB,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,8BAA8B,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACpF,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAY,EAAE,OAAuB,EAAE;QAC3C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE;YAC5C,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK;YAC5B,OAAO;YACP,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,EAAE,CAAC,IAAI,GAAG,GAAG,EAAE,SAA6B;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE;YACxC,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,eAAe,EAAE,IAAI,CAAC,OAAO;SAC9B,CAAC,CAAC;QACH,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,SAAiC,CAAC,CAAC;IAC/D,CAAC;IAEO,IAAI,CAAC,IAAY,EAAE,IAAY,EAAE,UAAmC;QAC1E,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;QACnD,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC;QACvC,IAAI,UAAU,EAAE,CAAC;YACf,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;gBAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IACtB,CAAC;CACF"}

package/dist/runtime.d.ts

@@ -6,6 +6,7 @@ import { TerminalResource } from './runtime/terminal.js';
 import { WatcherResource } from './runtime/watcher.js';
 import { TransferResource } from './runtime/transfer.js';
 import { RuntimeWebSocket } from './runtime/ws.js';
+import { RuntimeProxy } from './runtime/proxy.js';
 import type { RuntimeOptions, WSOptions } from './types/runtime.js';
 /**
  * Workspace Runtime - the data-plane client for interacting with a
@@ -76,5 +77,20 @@ export declare class Runtime {
      * ```
      */
     ws(options?: WSOptions): RuntimeWebSocket;
+    /**
+     * Reverse-proxy HTTP/WebSocket requests to a service listening on a loopback
+     * port inside the workspace (e.g. a dev server on `127.0.0.1:3000`). Requests
+     * are forwarded near-natively — headers, streaming/SSE, and WebSocket upgrades
+     * pass through. Only loopback ports are reachable.
+     *
+     * ```ts
+     * const res = await rt.proxy(3000).fetch('/api/users');
+     * const ws  = rt.proxy(3000).ws('/socket');
+     * ```
+     *
+     * @param port Loopback port inside the workspace (1-65535).
+     * @param host Optional loopback host override (defaults to 127.0.0.1).
+     */
+    proxy(port: number, host?: string): RuntimeProxy;
 }
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,OAAO;IAClB,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAElC,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAE1C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAE9B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAE5B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAEpC,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;gBAExB,OAAO,EAAE,cAAc;IAWnC,uEAAuE;IACjE,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAYhC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,EAAE,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,gBAAgB;CAG1C"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,OAAO;IAClB,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAElC,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAE1C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAE9B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAE5B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAEpC,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;gBAExB,OAAO,EAAE,cAAc;IAWnC,uEAAuE;IACjE,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAYhC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,EAAE,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,gBAAgB;IAIzC;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY;CAGjD"}

package/dist/runtime.js

@@ -6,6 +6,7 @@ import { TerminalResource } from './runtime/terminal.js';
 import { WatcherResource } from './runtime/watcher.js';
 import { TransferResource } from './runtime/transfer.js';
 import { RuntimeWebSocket } from './runtime/ws.js';
+import { RuntimeProxy } from './runtime/proxy.js';
 /**
  * Workspace Runtime - the data-plane client for interacting with a
  * running workspace's filesystem, terminal, commands, and file watchers.
@@ -97,5 +98,22 @@ export class Runtime {
     ws(options) {
         return new RuntimeWebSocket(this._options, options);
     }
+    /**
+     * Reverse-proxy HTTP/WebSocket requests to a service listening on a loopback
+     * port inside the workspace (e.g. a dev server on `127.0.0.1:3000`). Requests
+     * are forwarded near-natively — headers, streaming/SSE, and WebSocket upgrades
+     * pass through. Only loopback ports are reachable.
+     *
+     * ```ts
+     * const res = await rt.proxy(3000).fetch('/api/users');
+     * const ws  = rt.proxy(3000).ws('/socket');
+     * ```
+     *
+     * @param port Loopback port inside the workspace (1-65535).
+     * @param host Optional loopback host override (defaults to 127.0.0.1).
+     */
+    proxy(port, host) {
+        return new RuntimeProxy(this._options, port, host);
+    }
 }
 //# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,OAAO;IAClB,gBAAgB;IACP,KAAK,CAAoB;IAElC,gBAAgB;IACC,QAAQ,CAAiB;IAE1C,wEAAwE;IAC/D,KAAK,CAAgB;IAE9B,oDAAoD;IAC3C,MAAM,CAAiB;IAEhC,0DAA0D;IACjD,IAAI,CAAe;IAE5B,uEAAuE;IAC9D,QAAQ,CAAmB;IAEpC,4CAA4C;IACnC,OAAO,CAAkB;IAElC,iEAAiE;IACxD,QAAQ,CAAmB;IAEpC,YAAY,OAAuB;QACjC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,MAAM;QACV,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAqB;gBACvD,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,SAAS;aAChB,CAAC,CAAC;YACH,OAAO,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,EAAE,CAAC,OAAmB;QACpB,OAAO,IAAI,gBAAgB,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;CACF"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,OAAO;IAClB,gBAAgB;IACP,KAAK,CAAoB;IAElC,gBAAgB;IACC,QAAQ,CAAiB;IAE1C,wEAAwE;IAC/D,KAAK,CAAgB;IAE9B,oDAAoD;IAC3C,MAAM,CAAiB;IAEhC,0DAA0D;IACjD,IAAI,CAAe;IAE5B,uEAAuE;IAC9D,QAAQ,CAAmB;IAEpC,4CAA4C;IACnC,OAAO,CAAkB;IAElC,iEAAiE;IACxD,QAAQ,CAAmB;IAEpC,YAAY,OAAuB;QACjC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC;IAED,uEAAuE;IACvE,KAAK,CAAC,MAAM;QACV,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAqB;gBACvD,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,SAAS;aAChB,CAAC,CAAC;YACH,OAAO,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,EAAE,CAAC,OAAmB;QACpB,OAAO,IAAI,gBAAgB,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,IAAY,EAAE,IAAa;QAC/B,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACrD,CAAC;CACF"}

package/dist/server/static.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Static file server — a small, dependency-free HTTP server for a folder.
+ *
+ * Built entirely on Node's `http`/`fs`/`path`, so it adds nothing to the SDK's
+ * dependency tree. Pair it with the {@link TunnelClient} (or `oblien serve`) to
+ * put a folder on the public internet in one step.
+ *
+ * ```ts
+ * import { startStaticServer } from 'oblien';
+ *
+ * const site = await startStaticServer({ root: './public', spa: true });
+ * console.log(`serving on ${site.url}`);
+ * // ... later
+ * await site.close();
+ * ```
+ *
+ * Features: streamed responses (memory-safe for large files), correct MIME
+ * types, `Range` requests (media seeking), `ETag`/`Last-Modified` revalidation
+ * (`304`), directory `index.html`, optional directory listings, optional SPA
+ * fallback, and strict path-traversal protection.
+ */
+import { type Server, type IncomingMessage, type ServerResponse } from 'node:http';
+export interface StaticServerOptions {
+    /** Directory to serve. Resolved against the current working directory. */
+    root: string;
+    /** Interface to bind. Defaults to `127.0.0.1` (loopback only). */
+    host?: string;
+    /** Port to listen on. Defaults to `0` — the OS picks a free port. */
+    port?: number;
+    /** Filename served for directory requests. Defaults to `index.html`. */
+    index?: string;
+    /** Render an auto-generated listing when a directory has no index. Defaults to `true`. */
+    listing?: boolean;
+    /**
+     * Single-page-app mode: serve the root `index` for any path that doesn't map
+     * to a real file, so client-side routing works. Defaults to `false`.
+     */
+    spa?: boolean;
+    /**
+     * Serve dotfiles and dot-directories (`.git`, `.env`, …). Defaults to `false`
+     * — they're denied with `404`, since this server is often exposed publicly and
+     * such files (git internals, secrets) are rarely meant to be shared. The
+     * `.well-known/` directory is always allowed.
+     */
+    allowDotfiles?: boolean;
+    /** Called for each served request (after the response status is known). */
+    onRequest?: (info: {
+        method: string;
+        path: string;
+        status: number;
+    }) => void;
+}
+export interface StaticServerHandle {
+    /** The port the server is actually listening on (resolved even when `port: 0`). */
+    port: number;
+    /** The host the server is bound to. */
+    host: string;
+    /** Convenience `http://host:port` origin. */
+    url: string;
+    /** The underlying Node HTTP server. */
+    server: Server;
+    /** Stop accepting connections and resolve once fully closed. */
+    close(): Promise<void>;
+}
+/**
+ * Build the request handler for a static root. Exposed so callers can mount it
+ * on an existing server if they prefer; most callers want {@link startStaticServer}.
+ */
+export declare function createStaticHandler(options: StaticServerOptions): (req: IncomingMessage, res: ServerResponse) => void;
+/**
+ * Create (but do not start) a static HTTP server for `options.root`.
+ * Call `.listen()` yourself, or use {@link startStaticServer} to listen and get
+ * a resolved {@link StaticServerHandle}.
+ */
+export declare function createStaticServer(options: StaticServerOptions): Server;
+/**
+ * Start a static server and resolve once it's listening. When `port` is omitted
+ * or `0`, the OS assigns a free port and the resolved handle reports it.
+ */
+export declare function startStaticServer(options: StaticServerOptions): Promise<StaticServerHandle>;
+//# sourceMappingURL=static.d.ts.map

package/dist/server/static.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static.d.ts","sourceRoot":"","sources":["../../src/server/static.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAgB,KAAK,MAAM,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAMjG,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC9E;AAED,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAmJD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,mBAAmB,GAC3B,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,CAmFrD;AA+MD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAEvE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA8B3F"}