@nimbus-sh/worker 0.5.0 → 0.7.0

package/dist/session/port-capability.d.ts

@@ -55,24 +55,42 @@ declare const PortVisibilitySchema: z.ZodEnum<{
     public: "public";
 }>;
 export type PortVisibility = z.infer<typeof PortVisibilitySchema>;
+/**
+ * The optional name alias a reservation may carry: one DNS label, so it can
+ * stand where the port stands in a preview host (`<name>--<sid>`). Never
+ * purely numeric — a numeric middle label IS a port. No `--`: that is the
+ * host-label separator. No 24 lowercase hex: that is ambiguous with a
+ * capability label, so parsing could mistake a name for a bearer.
+ */
+export declare const APP_NAME_RE: RegExp;
+export declare function isValidAppName(name: string): boolean;
 export declare const PortRecordSchema: z.ZodObject<{
+    kind: z.ZodDefault<z.ZodEnum<{
+        explicit: "explicit";
+        derived: "derived";
+    }>>;
     capability: z.ZodNullable<z.ZodString>;
     owner: z.ZodNullable<z.ZodString>;
     visibility: z.ZodOptional<z.ZodEnum<{
         scoped: "scoped";
         public: "public";
     }>>;
+    name: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export interface PortExposure {
     readonly capability: string;
     readonly owner: string | null;
     readonly visibility: PortVisibility;
+    readonly name?: string;
 }
 /** The per-port record as stored: a bare reservation has no capability yet. */
 export interface PortReservation {
+    readonly kind: 'explicit' | 'derived';
     readonly owner: string | null;
     readonly capability: string | null;
     readonly visibility: PortVisibility;
+    /** The reservation's name alias, when one was given at expose time. */
+    readonly name?: string;
 }
 export declare function portRecordKey(port: number): string;
 /** Read the raw per-port record: a reservation, an exposure, or nothing. */
@@ -81,6 +99,24 @@ export declare function readPortReservation(ctx: {
 }, port: number): Promise<PortReservation | null>;
 /** Read retained exposure metadata without starting a session or restoring a listener. */
 export declare function readPortExposure(ctx: PortCapabilityHost['ctx'], port: number): Promise<PortExposure | null>;
+/** Every stored port record, keyed by port — the scan `apps.list` and the name lookups read. */
+export declare function listPortReservations(ctx: {
+    storage: PortReservationTransaction;
+}): Promise<Map<number, PortReservation>>;
+/** The port a name alias resolves to inside this session, or null. */
+export declare function readPortReservationByName(ctx: {
+    storage: PortReservationTransaction;
+}, name: string): Promise<{
+    port: number;
+    reservation: PortReservation;
+} | null>;
+/** The port an owner holds, or null when the owner has no reservation. */
+export declare function readPortReservationByOwner(ctx: {
+    storage: PortReservationTransaction;
+}, owner: string): Promise<{
+    port: number;
+    reservation: PortReservation;
+} | null>;
 /**
  * Hold a port for `owner` across instances. The owner's existing port is
  * answered again; otherwise the preferred port is claimed, or the lowest
@@ -97,9 +133,12 @@ export declare function readPortExposure(ctx: PortCapabilityHost['ctx'], port: n
 export declare function reservePort(ctx: PortReservationHost['ctx'], input: {
     owner: string;
     preferredPort?: number;
+    kind?: 'explicit' | 'derived';
     occupiedPorts: ReadonlySet<number>;
     capability?: string;
     visibility?: PortVisibility;
+    /** A name alias for the reservation — unique per session, DNS-label-safe. */
+    name?: string;
 }): Promise<number>;
 /** End an owner's hold on a port. Another owner's record is left alone and refused. */
 export declare function releasePortReservation(ctx: PortReservationHost['ctx'], input: {
@@ -120,11 +159,62 @@ export declare function restorePortCapability(self: PortCapabilityHost, port: nu
  */
 export declare function restoreReservedPortCapability(self: PortCapabilityHost, port: number, owner: string): Promise<string | null>;
 export declare function persistPortCapability(self: PortCapabilityHost, port: number, capability: string): Promise<void>;
+/**
+ * Replace the port's capability with a freshly minted one, in place: owner,
+ * visibility and name stay, every URL built on the old value stops
+ * resolving. Answers the new capability, or null when no record exists —
+ * there is nothing to rotate on a port nobody has reserved or exposed.
+ */
+export declare function rotatePortCapability(self: PortCapabilityHost, port: number, capability: string): Promise<string | null>;
 /**
  * Retire the durable capability for a port. Called before every registration
  * that is not a restore, so a token handed out for the previous occupant of a
  * port cannot reach the next one. An owner's reservation survives it.
  */
 export declare function clearPortCapability(self: PortCapabilityHost, port: number): Promise<void>;
+/** The host surface `routeToSessionPort` actually reads — the narrowest shape that serves every port-addressed route. */
+export interface SessionPortHost {
+    ctx: DurableObjectState;
+    portRegistry: PortRegistry;
+    ensureDurableAppOnPort?: (port: number) => Promise<'absent' | 'started' | 'failed'>;
+    _viteShimPort?: number | null;
+    viteDevServer?: {
+        isRunning: boolean;
+        handleRequest(request: Request, innerPath: string, mountBase: string): Promise<Response>;
+    } | null;
+    cirrusReal?: {
+        isRunning: boolean;
+    } | null;
+    restorePersistedDevServer?: (onlyPort?: number) => Promise<void>;
+    acceptCirrusHmrWs?: (request: Request) => Response;
+}
+export declare function normalizeForwardedHttpPath(path: string): string;
+/** True if `innerPath` targets the cirrus-real HMR socket, under any mount base. */
+export declare function isCirrusHmrPath(innerPath: string): boolean;
+/**
+ * Re-adopt a preview capability the embedder already holds, after a restore
+ * re-registered the port under a freshly minted one.
+ */
+export declare function readoptCapability(self: PortCapabilityHost, port: number, capability: string | null): Promise<void>;
+/**
+ * Route a request to whatever is listening on a session port.
+ *
+ * The one implementation behind every port-addressed surface: `/port/<n>/`,
+ * `/preview/?port=N`, the `<port>--<sid>` preview hostname (which the router
+ * forwards as `/port/<n>/`), and the embedder's capability route. They
+ * differ only in how the port and the inner path are spelled, so they must
+ * not differ in what answers.
+ *
+ * `mountBase` is the public URL prefix the served app is mounted at for THIS
+ * request — '' for a root-mounted `<port>--<sid>` host, '/s/<sid>/preview' for
+ * the preview path. The in-process Cirrus dev server rewrites base-relative
+ * URLs (module URLs, <base href>, BASE_URL, router basename), so it is handed
+ * the base directly: the generic port proxy strips the Nimbus base header at
+ * the untrusted-code boundary and cannot carry it, and a plain user server on
+ * any other port is mounted at root and needs no rewriting.
+ */
+export declare function routeToSessionPort(self: SessionPortHost, port: number, request: Request, innerPath: string, mountBase: string, capability?: string): Promise<Response>;
+/** Route a capability-authenticated embedder request to a guest HTTP server. */
+export declare function routeCapabilityPort(self: SessionPortHost, port: number, capability: string, request: Request, innerPath: string): Promise<Response>;
 export {};
 //# sourceMappingURL=port-capability.d.ts.map

package/dist/session/port-capability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"port-capability.d.ts","sourceRoot":"","sources":["../../src/session/port-capability.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"port-capability.d.ts","sourceRoot":"","sources":["../../src/session/port-capability.ts"],"names":[],"mappings":"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"}

package/dist/session/port-capability.js

@@ -23,15 +23,31 @@
  * keeps the owner's reservation; only `releasePortReservation` ends it.
  */
 import { z } from 'zod/v4';
+import { PUBLIC_BEARER_HEADER, renderSessionStatusPage } from '../_shared/session-router.js';
 import { PORT_CAPABILITY_KEY_PREFIX } from './keys.js';
 /** The shape `createPortCapability` mints: 12 random bytes, hex. */
 const PortCapabilitySchema = z.string().regex(/^[a-f0-9]{24}$/);
 /** 'scoped' is the default: capability-checked but never the public bearer. */
 const PortVisibilitySchema = z.enum(['scoped', 'public']);
+/**
+ * The optional name alias a reservation may carry: one DNS label, so it can
+ * stand where the port stands in a preview host (`<name>--<sid>`). Never
+ * purely numeric — a numeric middle label IS a port. No `--`: that is the
+ * host-label separator. No 24 lowercase hex: that is ambiguous with a
+ * capability label, so parsing could mistake a name for a bearer.
+ */
+export const APP_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+export function isValidAppName(name) {
+    return APP_NAME_RE.test(name) && !name.includes('--')
+        && !/^\d+$/.test(name) && !/^[a-f0-9]{24}$/.test(name);
+}
+const AppNameSchema = z.string().refine(isValidAppName, 'app name must be a DNS label: no --, not numeric, not 24 lowercase hex');
 export const PortRecordSchema = z.object({
+    kind: z.enum(['explicit', 'derived']).default('explicit'),
     capability: PortCapabilitySchema.nullable(),
     owner: z.string().nullable(),
     visibility: PortVisibilitySchema.optional(),
+    name: AppNameSchema.optional(),
 });
 const RESERVATION_FIRST_PORT = 20000;
 const RESERVATION_LAST_PORT = 65535;
@@ -52,9 +68,43 @@ export async function readPortReservation(ctx, port) {
 export async function readPortExposure(ctx, port) {
     const stored = await readPortReservation(ctx, port);
     return stored !== null && stored.capability !== null
-        ? { capability: stored.capability, owner: stored.owner, visibility: stored.visibility }
+        ? {
+            capability: stored.capability, owner: stored.owner, visibility: stored.visibility,
+            ...(stored.name !== undefined ? { name: stored.name } : {}),
+        }
         : null;
 }
+/** Every stored port record, keyed by port — the scan `apps.list` and the name lookups read. */
+export async function listPortReservations(ctx) {
+    const rows = await ctx.storage.list({ prefix: PORT_CAPABILITY_KEY_PREFIX });
+    const out = new Map();
+    for (const [key, value] of rows) {
+        const port = Number(key.slice(PORT_CAPABILITY_KEY_PREFIX.length));
+        const parsed = PortRecordSchema.safeParse(value);
+        if (!Number.isInteger(port) || !parsed.success)
+            continue;
+        out.set(port, { ...parsed.data, visibility: parsed.data.visibility ?? 'scoped' });
+    }
+    return out;
+}
+/** The port a name alias resolves to inside this session, or null. */
+export async function readPortReservationByName(ctx, name) {
+    if (!isValidAppName(name))
+        return null;
+    for (const [port, reservation] of await listPortReservations(ctx)) {
+        if (reservation.name === name)
+            return { port, reservation };
+    }
+    return null;
+}
+/** The port an owner holds, or null when the owner has no reservation. */
+export async function readPortReservationByOwner(ctx, owner) {
+    for (const [port, reservation] of await listPortReservations(ctx)) {
+        if (reservation.owner === owner)
+            return { port, reservation };
+    }
+    return null;
+}
 /**
  * Hold a port for `owner` across instances. The owner's existing port is
  * answered again; otherwise the preferred port is claimed, or the lowest
@@ -69,32 +119,52 @@ export async function readPortExposure(ctx, port) {
  * capability is never rotated, a URL already handed out stays good.
  */
 export async function reservePort(ctx, input) {
+    if (input.name !== undefined && !isValidAppName(input.name)) {
+        throw conflict(`'${input.name}' is not a valid app name (one DNS label, not numeric, not 24 hex)`);
+    }
     const claim = async (txn) => {
         const records = await txn.list({ prefix: PORT_CAPABILITY_KEY_PREFIX });
         const taken = new Set(input.occupiedPorts);
+        const unowned = new Map();
         let held = null;
         for (const [storedKey, value] of records) {
             const port = Number(storedKey.slice(PORT_CAPABILITY_KEY_PREFIX.length));
             if (!Number.isInteger(port))
                 continue;
-            taken.add(port);
             const parsed = PortRecordSchema.safeParse(value);
-            if (parsed.success && parsed.data.owner === input.owner) {
+            // listPorts may already have persisted the live capability without an
+            // owner. That is an exposure to adopt, not somebody else's reservation.
+            if (parsed.success && parsed.data.owner === null)
+                unowned.set(port, parsed.data);
+            else
+                taken.add(port);
+            if (!parsed.success)
+                continue;
+            if (parsed.data.owner === input.owner) {
                 held = { port, stored: parsed.data };
             }
+            else if (input.name !== undefined && parsed.data.name === input.name
+                && !(parsed.data.owner === null && port === input.preferredPort)) {
+                throw conflict(`name '${input.name}' is already taken by another app on port ${port}`);
+            }
         }
         const preferred = input.preferredPort;
         if (held !== null) {
             if (preferred !== undefined && preferred !== held.port) {
                 throw conflict(`owner already holds port ${held.port}, cannot reserve ${preferred}`);
             }
-            // Upgrade in place: adopt a caller-supplied capability the row lacks
-            // and/or apply the caller's visibility — never rotate an existing one.
+            // Upgrade in place: adopt a caller-supplied capability the row lacks,
+            // apply the caller's visibility and/or name — never rotate an existing
+            // capability.
             const stored = held.stored;
             const capability = stored?.capability ?? input.capability ?? null;
             const visibility = input.visibility ?? stored?.visibility ?? 'scoped';
-            if (stored === null || capability !== stored.capability || visibility !== (stored.visibility ?? 'scoped')) {
-                await txn.put(portRecordKey(held.port), { owner: input.owner, capability, visibility });
+            const name = input.name ?? stored?.name;
+            if (stored === null || capability !== stored.capability
+                || visibility !== (stored.visibility ?? 'scoped') || name !== stored.name) {
+                await txn.put(portRecordKey(held.port), {
+                    owner: input.owner, kind: stored?.kind ?? input.kind ?? 'explicit', capability, visibility, ...(name !== undefined ? { name } : {}),
+                });
             }
             return held.port;
         }
@@ -114,10 +184,14 @@ export async function reservePort(ctx, input) {
             if (port > RESERVATION_LAST_PORT)
                 throw conflict('no free port left to reserve');
         }
+        const exposure = unowned.get(port);
+        const name = input.name ?? exposure?.name;
         await txn.put(portRecordKey(port), {
             owner: input.owner,
-            capability: input.capability ?? null,
-            visibility: input.visibility ?? 'scoped',
+            kind: input.kind ?? 'explicit',
+            capability: exposure?.capability ?? input.capability ?? null,
+            visibility: input.visibility ?? exposure?.visibility ?? 'scoped',
+            ...(name !== undefined ? { name } : {}),
         });
         return port;
     };
@@ -178,12 +252,37 @@ export async function persistPortCapability(self, port, capability) {
         await txn.put(portRecordKey(port), {
             capability: PortCapabilitySchema.parse(capability),
             owner: parsed.success ? parsed.data.owner : null,
+            kind: parsed.success ? parsed.data.kind : 'explicit',
             ...(parsed.success && parsed.data.visibility !== undefined
                 ? { visibility: parsed.data.visibility }
                 : {}),
+            ...(parsed.success && parsed.data.name !== undefined
+                ? { name: parsed.data.name }
+                : {}),
         });
     });
 }
+/**
+ * Replace the port's capability with a freshly minted one, in place: owner,
+ * visibility and name stay, every URL built on the old value stops
+ * resolving. Answers the new capability, or null when no record exists —
+ * there is nothing to rotate on a port nobody has reserved or exposed.
+ */
+export async function rotatePortCapability(self, port, capability) {
+    const rotated = await self.ctx.storage.transaction(async (txn) => {
+        const parsed = PortRecordSchema.safeParse(await txn.get(portRecordKey(port)));
+        if (!parsed.success)
+            return null;
+        await txn.put(portRecordKey(port), {
+            ...parsed.data,
+            capability: PortCapabilitySchema.parse(capability),
+        });
+        return capability;
+    });
+    // Registry adoption belongs to the caller, after a fresh serving-owner
+    // check: the storage await above may have allowed a new listener to bind.
+    return rotated;
+}
 /**
  * Retire the durable capability for a port. Called before every registration
  * that is not a restore, so a token handed out for the previous occupant of a
@@ -196,11 +295,122 @@ export async function clearPortCapability(self, port) {
         if (record !== null && record.owner !== null) {
             await txn.put(portRecordKey(port), {
                 owner: record.owner,
+                kind: record.kind,
                 capability: null,
                 ...(record.visibility !== undefined ? { visibility: record.visibility } : {}),
+                ...(record.name !== undefined ? { name: record.name } : {}),
             });
             return;
         }
         await txn.delete(portRecordKey(port));
     });
 }
+export function normalizeForwardedHttpPath(path) {
+    const text = path || '/';
+    return '/' + text.replace(/^\/+/, '');
+}
+/** True if `innerPath` targets the cirrus-real HMR socket, under any mount base. */
+export function isCirrusHmrPath(innerPath) {
+    const p = innerPath.split('?')[0];
+    return p === '/__nimbus_hmr' || p.endsWith('/__nimbus_hmr');
+}
+/** The "durable application is (re)starting" 503 page — self-refreshing. */
+function renderPortStartingHtml(port) {
+    return renderSessionStatusPage({
+        title: 'Starting',
+        heading: 'Starting&hellip;',
+        body: `The application on port <code>${port}</code> is restarting.<br>This page refreshes itself.`,
+        metaRefreshSeconds: 3,
+    });
+}
+/**
+ * Re-adopt a preview capability the embedder already holds, after a restore
+ * re-registered the port under a freshly minted one.
+ */
+export async function readoptCapability(self, port, capability) {
+    if (!capability)
+        return;
+    if (self.portRegistry.restoreCapability(port, capability)) {
+        await persistPortCapability(self, port, capability);
+    }
+}
+/**
+ * Route a request to whatever is listening on a session port.
+ *
+ * The one implementation behind every port-addressed surface: `/port/<n>/`,
+ * `/preview/?port=N`, the `<port>--<sid>` preview hostname (which the router
+ * forwards as `/port/<n>/`), and the embedder's capability route. They
+ * differ only in how the port and the inner path are spelled, so they must
+ * not differ in what answers.
+ *
+ * `mountBase` is the public URL prefix the served app is mounted at for THIS
+ * request — '' for a root-mounted `<port>--<sid>` host, '/s/<sid>/preview' for
+ * the preview path. The in-process Cirrus dev server rewrites base-relative
+ * URLs (module URLs, <base href>, BASE_URL, router basename), so it is handed
+ * the base directly: the generic port proxy strips the Nimbus base header at
+ * the untrusted-code boundary and cannot carry it, and a plain user server on
+ * any other port is mounted at root and needs no rewriting.
+ */
+export async function routeToSessionPort(self, port, request, innerPath, mountBase, capability) {
+    await self.restorePersistedDevServer?.(port);
+    // The durable seam: a request on a port nothing is serving may be a
+    // durable application a reset left dead — the alarm pump would re-drive
+    // it eventually, but a URL in someone's hands cannot wait for eventually.
+    // 'absent' falls through to the honest 502 unchanged; 'started' continues
+    // to normal routing with the port freshly bound; 'failed' is mid-launch
+    // or a lost boot, so the page re-asks on its own timer.
+    if (self.ensureDurableAppOnPort !== undefined) {
+        const durable = await self.ensureDurableAppOnPort(port);
+        if (durable === 'failed') {
+            return new Response(renderPortStartingHtml(port), {
+                status: 503,
+                headers: {
+                    'Content-Type': 'text/html; charset=utf-8',
+                    'Cache-Control': 'no-store',
+                    'Retry-After': '3',
+                },
+            });
+        }
+    }
+    if (capability !== undefined) {
+        // A rebuilt supervisor holds a capability nobody was handed; the durable
+        // one is the value in circulation, so it wins before the check.
+        await restorePortCapability(self, port);
+        if (!self.portRegistry.hasCapability(port, capability)) {
+            // 404, not 403: a wrong capability must not confirm that the port is
+            // listening at all.
+            return new Response('Not found', { status: 404 });
+        }
+        // The public bearer form arrived without a session attach: the
+        // capability is real, but it authorises this route only for a port the
+        // owner deliberately exposed — the stored visibility is the gate.
+        if (request.headers.get(PUBLIC_BEARER_HEADER) !== null) {
+            const reservation = await readPortReservation(self.ctx, port);
+            if (reservation === null || reservation.visibility !== 'public') {
+                return new Response('Not found', { status: 404 });
+            }
+        }
+    }
+    if (port === self._viteShimPort) {
+        // The preview HMR WebSocket can't cross the port-registry RPC, so it is
+        // accepted in-DO for both dev servers — the same handling `/preview/` uses.
+        if (self.cirrusReal?.isRunning && self.acceptCirrusHmrWs && isCirrusHmrPath(innerPath)) {
+            return self.acceptCirrusHmrWs(request);
+        }
+        // The Cirrus dev server rewrites base-relative URLs per request and the
+        // generic proxy strips the base header, so hand it the request directly.
+        if (self.viteDevServer?.isRunning) {
+            return self.viteDevServer.handleRequest(request, innerPath, mountBase);
+        }
+    }
+    const proxied = capability === undefined
+        ? await self.portRegistry.routeRequest(port, request, innerPath)
+        : await self.portRegistry.routeCapabilityRequest(port, capability, request, innerPath);
+    if (proxied)
+        return proxied;
+    return new Response(`No process listening on port ${port}`, { status: 502 });
+}
+/** Route a capability-authenticated embedder request to a guest HTTP server. */
+export function routeCapabilityPort(self, port, capability, request, innerPath) {
+    return routeToSessionPort(self, port, request, normalizeForwardedHttpPath(innerPath), '', capability);
+}