@volter/world-core 3.0.29 → 3.0.31

package/dist/src/browser.js

@@ -0,0 +1,135 @@
+import { BrowserCookieJar } from "./browser-cookie-jar.js";
+import { assertBrowserName, browserOrigin, validateBrowserState } from "./browser-state.js";
+import { nodeBuiltin } from "./serve-http.js";
+import { worldNow } from "./world-clock.js";
+export { cookieMatchesHost } from "./browser-state.js";
+/** A seed's named browser. Every state write goes through the World's single HTTP loader. */
+export async function browser(name) {
+    assertBrowserName(name);
+    const door = process.env.VOLTER_WORLD_BROWSER_DOOR;
+    const token = process.env.VOLTER_WORLD_BROWSER_TOKEN;
+    if (!process.env.VOLTER_WORLD || !door || !token)
+        throw new Error('browser(name) runs in a World seed, with its browsers door and credential');
+    const require = nodeBuiltin('module').createRequire(import.meta.url);
+    const routing = require('../vendor-hosts.cjs');
+    const { packs } = require('../pack-facts.cjs').packFacts();
+    const resolve = async (url) => {
+        const map = routing.twinOrigins(process.env);
+        const declared = routing.resolveTwinHost(url.hostname, map, url.pathname);
+        if (declared)
+            return declared;
+        const claimed = {};
+        for (const [vendor, facts] of Object.entries(packs)) {
+            const origin = map[vendor] ?? process.env[`${routing.twinEnvStem(vendor)}_TWIN_URL`];
+            if (!origin || !facts.hostsClaimed)
+                continue;
+            map[vendor] = origin;
+            const headers = new Headers({ 'x-volter-read-only': '1' });
+            if (process.env.VOLTER_TWINS_KEY)
+                headers.set('x-twins-key', process.env.VOLTER_TWINS_KEY);
+            const listed = await fetch(`${origin}${facts.hostsClaimed.door}`, { headers })
+                .then(r => r.ok ? r.json() : null).catch(() => null);
+            claimed[vendor] = new Set(Array.isArray(listed?.hosts) ? listed.hosts.map(h => String(h).toLowerCase()) : []);
+        }
+        return routing.resolveTwinHost(url.hostname, map, url.pathname, claimed);
+    };
+    const initial = await fetch(`${door}/${name}`, { headers: { 'x-volter-token': token } });
+    if (!initial.ok && initial.status !== 404)
+        throw new Error(`browser ${name}: ${initial.status} ${await initial.text()}`);
+    const stored = initial.ok ? validateBrowserState(await initial.json()) : { cookies: [], origins: [] };
+    const jar = new BrowserCookieJar(stored.cookies);
+    const origins = structuredClone(stored.origins);
+    let queue = Promise.resolve();
+    const serial = (fn) => { const next = queue.then(fn); queue = next.then(() => undefined, () => undefined); return next; };
+    const snapshot = () => {
+        const now = new Date(worldNow()).getTime();
+        const cookies = jar.snapshot(now);
+        return validateBrowserState({ cookies, origins: structuredClone(origins) });
+    };
+    const save = async () => {
+        const response = await fetch(`${door}/${name}`, { method: 'PUT', headers: { 'content-type': 'application/json', 'x-volter-token': token }, body: JSON.stringify(snapshot()) });
+        if (!response.ok)
+            throw new Error(`browser ${name}: ${response.status} ${await response.text()}`);
+    };
+    if (initial.status === 404)
+        await save();
+    return {
+        state: () => serial(async () => snapshot()),
+        storage(origin) {
+            browserOrigin(origin);
+            const change = (key, value) => serial(async () => {
+                if (typeof key !== 'string' || (value !== undefined && typeof value !== 'string'))
+                    throw new Error('browser storage: string keys and values');
+                const before = JSON.stringify(origins);
+                let entry = origins.find(o => o.origin === origin);
+                if (!entry && value !== undefined) {
+                    entry = { origin, localStorage: [] };
+                    origins.push(entry);
+                }
+                if (entry) {
+                    entry.localStorage = entry.localStorage.filter(v => v.name !== key);
+                    if (value !== undefined)
+                        entry.localStorage.push({ name: key, value });
+                }
+                if (JSON.stringify(origins) !== before)
+                    await save();
+            });
+            return { set: (key, value) => change(key, value), remove: key => change(key) };
+        },
+        fetch: (input, init) => serial(async () => {
+            const request = new Request(input, init);
+            let url = new URL(request.url);
+            let method = request.method;
+            let body = request.body ? await request.arrayBuffer() : undefined;
+            const headers = new Headers(request.headers);
+            if (headers.has('cookie'))
+                throw new Error('browser.fetch carries its own cookie jar');
+            for (let redirects = 0;; redirects++) {
+                if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+                    throw new Error('browser.fetch takes an http or https vendor URL');
+                const target = await resolve(url);
+                if (!target || target.vendor === 'app')
+                    throw new Error(`browser ${name}: no twin in this World serves ${url.hostname}${url.pathname}`);
+                const at = new URL(target.origin);
+                at.pathname = `${at.pathname.replace(/\/$/, '')}${url.pathname}`;
+                at.search = url.search;
+                const sent = new Headers(headers);
+                const cookies = jar.header(url, new Date(worldNow()).getTime());
+                if (cookies)
+                    sent.set('cookie', cookies);
+                sent.set('host', new URL(target.origin).pathname.replace(/\/$/, '') ? at.host : url.host);
+                sent.set('x-volter-twin-original-host', url.host);
+                sent.set('x-forwarded-host', url.host);
+                sent.set('x-forwarded-proto', url.protocol.slice(0, -1));
+                if (process.env.VOLTER_TWINS_KEY)
+                    sent.set('x-twins-key', process.env.VOLTER_TWINS_KEY);
+                const before = JSON.stringify(snapshot());
+                const response = await fetch(at, { method, headers: sent, body, redirect: 'manual', signal: request.signal });
+                for (const cookie of response.headers.getSetCookie())
+                    jar.set(cookie, url, new Date(worldNow()).getTime());
+                if (JSON.stringify(snapshot()) !== before)
+                    await save();
+                const location = response.headers.get('location');
+                if (!location || ![301, 302, 303, 307, 308].includes(response.status) || request.redirect === 'manual')
+                    return response;
+                if (request.redirect === 'error')
+                    throw new Error('browser.fetch refused a redirect');
+                if (redirects >= 20)
+                    throw new Error('browser.fetch exceeded the fetch redirect limit');
+                await response.body?.cancel();
+                const next = new URL(location, url);
+                if (next.origin !== url.origin) {
+                    headers.delete('authorization');
+                    headers.delete('proxy-authorization');
+                }
+                if ((response.status === 303 && method !== 'HEAD') || ([301, 302].includes(response.status) && method === 'POST')) {
+                    method = 'GET';
+                    body = undefined;
+                    for (const key of ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location'])
+                        headers.delete(key);
+                }
+                url = next;
+            }
+        }),
+    };
+}

package/dist/src/derived-core.d.ts

@@ -683,8 +683,10 @@ export declare function render(r: TwinResource): Record<string, unknown>;
  *  a caller that pins an instant passes its own). */
 /** One call of a protocol-3 pack's default data (`src/semantics/seed.ts` exports `seed: SeedCall[]`): a request to the
  *  vendor's own operation (or the pack's door), made in order against the twin by the runner `volter-world init` writes
- *  beside the copied data. */
+ *  beside the copied data. An ordinary path is relative to the twin base. A call naming a browser uses the
+ *  vendor's absolute URL and is exported separately as `browserSeed`, after the ordinary `seed` calls. */
 export type SeedCall = {
+    browser?: string;
     method: string;
     path: string;
     body?: unknown;

package/dist/src/derived-core.js

@@ -1166,7 +1166,6 @@ export async function contextFor(m, call, scope) {
         body,
         text,
         root,
-        occurredAt: at,
         publicBase: twinPublicBase(call.request),
         scenario: scenarioDecisionOf(call.request),
         deliver: (url, init) => deliverToApplication(url, init),
@@ -1204,7 +1203,33 @@ export async function contextFor(m, call, scope) {
             }
             return id;
         },
+        occurredAt: at,
         secret: async (label) => hmac(await worldSeed(m.service, root, at), label, 'base64url'),
+        record: async (type, fields, id) => {
+            if (!type.startsWith('_'))
+                throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
+            if (id !== undefined) {
+                await applyTwinWrite(m.service, { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: id, fields, occurredAt: at, actor: { kind: 'system' } }, root);
+                return id;
+            }
+            const { value } = await applyTwinWriteAtomic(m.service, (resources) => {
+                // Allocate and append under the same state lock: concurrent sign-ins must never share an issue id.
+                const subject = (() => {
+                    const prefix = `${type.slice(1)}_`;
+                    let max = 0;
+                    for (const r of resources) {
+                        if (r.type !== type)
+                            continue;
+                        const n = r.id.startsWith(prefix) ? Number(r.id.slice(prefix.length)) : NaN;
+                        if (Number.isInteger(n) && n > max)
+                            max = n;
+                    }
+                    return `${prefix}${max + 1}`;
+                })();
+                return { kind: 'write', value: subject, write: { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } } };
+            }, root, () => resourcesOfType(m.service, type, root));
+            return value;
+        },
         get machines() {
             const enrolled = resourcesOfType(m.service, MACHINE_POOL, root).find((r) => r.id === 'pool');
             return poolFor(m.service, root, enrolled?.kind ?? 'none');
@@ -1237,24 +1262,6 @@ export async function contextFor(m, call, scope) {
         rowsRaw: (resource, opts) => stored(m, resource, root, opts),
         tree: () => twinResources(m.service, root),
         history: (resource, id) => subjectHistory(m.service, { type: storedType(m, resource), id }, root).map((e) => ({ ...(e.operation ? { operation: e.operation } : {}), ...(e.fields ? { fields: e.fields } : {}), ...(e.occurredAt ? { occurredAt: e.occurredAt } : {}) })),
-        record: async (type, fields, id) => {
-            if (!type.startsWith('_'))
-                throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
-            // an id the caller does not give is the next past every one of this type the tree holds (as `{n}` ids are minted),
-            // never a count of the rows, which a removed row would make repeat
-            const subject = id ?? (() => {
-                const prefix = `${type.slice(1)}_`;
-                let max = 0;
-                for (const r of resourcesOfType(m.service, type, root)) {
-                    const n = r.id.startsWith(prefix) ? Number(r.id.slice(prefix.length)) : NaN;
-                    if (Number.isInteger(n) && n > max)
-                        max = n;
-                }
-                return `${prefix}${max + 1}`;
-            })();
-            await applyTwinWrite(m.service, { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } }, root);
-            return subject;
-        },
         raw: (body, init = {}) => new Response(body, { status: init.status ?? 200, headers: init.headers ?? {} }),
         atomically: async (decide) => {
             const { value } = await applyTwinWriteAtomic(m.service, (resources) => {

package/dist/src/derived.d.ts

@@ -125,6 +125,7 @@ export type DerivedFetch = ((request: Request) => Promise<Response>) & {
 export type Workspace = {
     id: string;
     path: string;
+    host?: string;
 };
 /** A page of the World's board (architecture, "The board"): a page there is to see at the vendor, a record's own (an
  *  account's profile, each of its posts, a site and each page it serves), as the vendor's pack lists them from its state

package/dist/src/index.d.ts

@@ -64,3 +64,5 @@ export * as redis from './redis/index.js';
 export * as git from './git/index.js';
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.js';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';
+export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.js';
+export { assertBrowserName, browserOrigin, validateBrowserState, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserIndexedDB } from './browser-state.js';

package/dist/src/index.js

@@ -59,3 +59,5 @@ export * as redis from "./redis/index.js";
 export * as git from "./git/index.js";
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";
+export { browserSessionToken, startBrowserSession, endBrowserSession } from "./browser-session.js";
+export { assertBrowserName, browserOrigin, validateBrowserState, cookieMatchesHost } from "./browser-state.js";

package/dist/src/pack-fetch.js

@@ -19,7 +19,7 @@ import { deferPerform, performRequestGroup, RefusedWriteError, VendorWriteError
 import { withCors } from "./cors.js";
 import { contentAddressOf } from "./content-route.js";
 import { getPack } from "./packRegistry.js";
-import { hostRules } from '../vendor-hosts.cjs';
+import { hostRules } from '../host-routing.cjs';
 import { socketUpgrade } from "./sockets.js";
 import { MACHINE_POOL, POOL_KINDS } from "./machines.js";
 import { applyTwinWrite } from "./serve.js";
@@ -220,7 +220,7 @@ export function createPackFetch(parts, options = {}) {
     });
     // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path, the pack's own
     // and its lanes'
-    const workspaces = () => [...(m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path })), ...lanesWorkspaces(parts.lanes ?? {})];
+    const workspaces = () => [...(m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path, host: s.host })), ...lanesWorkspaces(parts.lanes ?? {})];
     /** Whether a built screen a person views (a workspace or a flow, never content an API client reads) draws a url: its host
      *  one the screen names, its path the screen's or under it (a root screen draws its root alone). */
     // by what the pack declares built (a screen drawn by another's handler, as X's profile is by its web pages, is built)