@takosjp/yurucommu-core 4.1.2 → 4.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-core",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "license": "AGPL-3.0-only",
   "type": "module",
   "workspaces": [

package/packages/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-api",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "description": "Typed client SDK and public API contract for yurucommu-server clients.",
   "license": "AGPL-3.0-only",
   "type": "module",

package/src/backend/index.ts

@@ -9,7 +9,6 @@ import {
   wrapRuntimeBindings,
   wrapRuntimeMessageBatch,
   type PortableWorkerBindings,
-  type RuntimeLane,
 } from "./runtime/lane.ts";
 import {
   configuredAppUrl,
@@ -939,20 +938,28 @@ function mountStaticFallback(app: YurucommuApp): void {
  * a readiness probe that reported `APP_URL` missing on a Worker whose origin
  * only its own traffic can reveal would never go ready.
  *
- * It runs on the `portable` lane alone. There, a wrapper host routes by
- * hostname and delivers the request it received on the Worker's public
- * endpoint, so the request URL IS the assigned origin (see
- * runtime/public-origin.ts). A Worker deployed straight to Cloudflare answers
- * on workers.dev, on every custom domain, and on every route pattern its
- * account holds, so the same inference there would let whichever hostname
- * happened to arrive first name the instance for good; that lane keeps
- * requiring an explicit `APP_URL` exactly as before.
+ * It runs on EVERY lane, because the lane names the SHAPE OF THE BINDINGS and
+ * not who chose the endpoint. A Takoform-hosted Worker on the production
+ * Takoserver receives raw Cloudflare bindings — the `cloudflare` lane — and its
+ * origin is still allocated by a `WorkerEndpoint` after the `WorkerVersion`
+ * that would have carried `APP_URL` was sealed, and the Takoform module passes
+ * no `APP_URL` either. Gating the inference on the lane left exactly that
+ * install unable to ever name itself, and so never ready.
+ *
+ * What makes the request URL trustworthy is a property of the runtime rather
+ * than of the binding shape: the origin on the request is the origin the
+ * request actually arrived on, and no forwarded header is ever consulted (see
+ * runtime/public-origin.ts). The remaining risk on a Worker deployed straight
+ * to Cloudflare — it also answers on workers.dev and on every custom domain and
+ * route pattern its account holds, so the first hostname to arrive would name
+ * the instance for good — is answered the same way it always was: an operator
+ * who owns more than one of those hostnames sets `APP_URL`, which always wins.
  *
  * It never fails a request. When no origin can be established — the request is
- * plain http, KV is unbound, an operator hand-wrote the pin — `APP_URL` simply
- * stays unset, which `/readyz` already reports as a hard missing binding.
- * Turning that into a 500 would take the readiness probe down with it and
- * replace a precise answer with a generic one.
+ * plain http on a routable host, KV is unbound, an operator hand-wrote the pin
+ * — `APP_URL` simply stays unset, which `/readyz` already reports as a hard
+ * missing binding. Turning that into a 500 would take the readiness probe down
+ * with it and replace a precise answer with a generic one.
  */
 function publicOriginMiddleware() {
   let warned = false;
@@ -961,16 +968,6 @@ function publicOriginMiddleware() {
     next: Next,
   ) => {
     if (configuredAppUrl(c.env) !== null) return next();
-    // An unrecognised lane declaration is refused at the binding boundary by
-    // wrapRuntimeBindings. Reaching here with one means the app was composed
-    // directly, and the safe reading of "not a lane I know" is "do not infer".
-    let lane: RuntimeLane;
-    try {
-      lane = resolveRuntimeLane(c.env.YURUCOMMU_RUNTIME_LANE);
-    } catch {
-      return next();
-    }
-    if (lane !== "portable") return next();
     try {
       const origin = await establishRequestPublicOrigin(c.env, c.req.raw);
       c.env = { ...c.env, APP_URL: origin };

package/src/backend/public.ts

@@ -108,8 +108,17 @@ export {
 } from "./runtime/edge-queue.ts";
 export {
   EdgeObjectStorage,
+  EdgeObjectsBucket,
   EdgeObjectsShapeError,
+  type EdgeObjectHttpMetadata,
+  type EdgeObjectRange,
+  type EdgeObjectsGetOptions,
+  type EdgeObjectsListOptions,
+  type EdgeR2Object,
+  type EdgeR2ObjectBody,
+  type EdgeR2Objects,
   wrapEdgeObjects,
+  wrapEdgeObjectsAsBucket,
 } from "./runtime/edge-objects.ts";
 export type {
   IKeyValueStore,

package/src/backend/runtime/edge-objects.ts

@@ -1,14 +1,60 @@
 /**
- * `edge.objects@1.0.0` → {@link ObjectStore}.
+ * `edge.objects@1.0.0` → an R2-shaped bucket, and → {@link ObjectStore}.
  *
- * The facade is deliberately narrower than R2, and the narrow spots are the
- * interesting ones:
+ * ## What the Host hands over, and what R2 hands over
+ *
+ * Takoserver's facade is method-for-method a bucket (`head`, `get`, `put`,
+ * `delete`, `list`, plus the four multipart calls), which is the whole point of
+ * the Interface: an app written against R2 is supposed to port over unchanged.
+ * The RESULT objects were not: the facade's `get()` answers with a plain record
+ * of `{etag, size, contentType?, body, partial, range?}`, while a native
+ * `R2ObjectBody` also carries `text()`, `json()`, `arrayBuffer()`, `blob()`,
+ * `key`, `httpEtag`, `uploaded`, `httpMetadata` and `writeHttpMetadata()`. So
+ * the facade WAS distinguishable from R2 — by exactly the members an app is
+ * most likely to reach for. `await (await env.MEDIA.get(k)).text()`, which is
+ * legal R2, threw `o.text is not a function` on the portable lane.
+ *
+ * The wire contract is Takoserver's (ADR 0005) and does not move. This module
+ * closes the gap on THIS side: {@link EdgeObjectsBucket} wraps the binding and
+ * returns objects that carry R2's members, so R2-shaped app code compiles and
+ * runs against either host.
+ *
+ * ## The parity rule
+ *
+ * PROVIDED, with R2's names and R2's semantics: `key`, `size`, `etag`,
+ * `httpEtag`, `httpMetadata`, `customMetadata`, `range`, `writeHttpMetadata()`,
+ * and on a body answer `body`, `bodyUsed`, `arrayBuffer()`, `text()`, `json()`,
+ * `blob()`. The four body helpers and `bodyUsed` are a real `Response`'s, so a
+ * second read REJECTS with a `TypeError` exactly as R2's do rather than
+ * replaying a cached value, and reading `body` directly also marks the object
+ * used. `blob()` answers with the bytes and no `type`; the stored content type
+ * is read from `httpMetadata` / `writeHttpMetadata()`, which is where R2 keeps
+ * it too.
+ *
+ * BEST EFFORT: `uploaded`. The Host's `head` and `list` carry
+ * `uploadedAtMillis`, so it is a `Date` there. Its `get` and `put` do NOT —
+ * both Takoserver wrapper backends build their answer without it on purpose —
+ * so it is `undefined` there rather than invented. It is `Date | undefined`
+ * everywhere so one type describes all four.
+ *
+ * NOT PROVIDED, because the wire carries nothing to derive them from:
+ * `version`, `checksums`, `storageClass`. `customMetadata` is present and
+ * always `undefined`: ADR 0005 gives `edge.objects` no custom metadata at all,
+ * so "absent" is the true answer rather than a missing member.
+ *
+ * `etag` is the Host's etag VERBATIM and is opaque: the self-host wrapper sends
+ * a bare hex digest (R2's unquoted `etag` spelling) and the managed wrapper
+ * forwards R2's quoted `httpEtag`. This facade does not rewrite it, because
+ * that value is what every conditional request on either host must echo back.
+ * `httpEtag` is derived: the same value, quoted when it was not already, which
+ * is the header-safe spelling R2 guarantees.
+ *
+ * ## The narrow spots of the facade itself, which parity does not widen
  *
  *  - NO CUSTOM METADATA. Only `contentType` survives a round trip, which is
  *    also all the provider-neutral {@link ObjectStorePutOptions} carries.
- *  - FIXED ARITIES. The Host counts `arguments.length`, so `get` and `put` are
- *    always called with their full argument list even when the options are
- *    absent.
+ *  - FIXED ARITIES. The Host counts `arguments.length`, so every call passes
+ *    its full argument list even when the options slot is absent.
  *  - A STREAMING `put` NEEDS `contentLength`. ADR 0005 is explicit that a Host
  *    enforces the declared count while streaming and never buffers a body to
  *    discover its size. Every body shape but a bare `ReadableStream` already
@@ -16,10 +62,12 @@
  *    `ArrayBuffer`, a string — so the length is declared and the bytes stream
  *    through. A stream that arrives without a knowable length is buffered
  *    HERE, in the Worker, which is the honest cost of not knowing the size.
- *  - `delete` TAKES ONE KEY. The port's array form becomes a sequence of calls,
- *    which is not atomic — the same as R2's, which also has no transaction.
- *  - NO ENUMERATION OR HEAD. The port does not carry them, so neither does the
- *    adapter, even though the Host projects both.
+ *  - `delete` TAKES ONE KEY. The bucket's array form becomes a sequence of
+ *    calls, which is not atomic — the same as R2's, which also has no
+ *    transaction.
+ *  - AN UNRANGED `get` MUST NOT BE PARTIAL. A truncated body served as a whole
+ *    object is a silent corruption, so the bytes are dropped and the call
+ *    throws.
  *
  * AVAILABILITY: BOTH wrapper backends project `edge.objects`. The managed
  * Cloudflare backend does it over provider-private R2
@@ -37,7 +85,11 @@ import type {
   ObjectStoreObject,
   ObjectStorePutOptions,
 } from "./types.ts";
-import type { EdgeObjectsBinding } from "./edge-facades.ts";
+import type {
+  EdgeObjectBody,
+  EdgeObjectMetadata,
+  EdgeObjectsBinding,
+} from "./edge-facades.ts";
 import { readStream } from "./shared.ts";
 
 /** A request or response the facade cannot express. */
@@ -48,6 +100,198 @@ export class EdgeObjectsShapeError extends TypeError {
   }
 }
 
+/**
+ * R2's `R2HTTPMetadata`, restricted to the one field `edge.objects` carries.
+ *
+ * The other five R2 fields (`contentLanguage`, `contentDisposition`,
+ * `contentEncoding`, `cacheControl`, `cacheExpiry`) are absent on every answer
+ * because the Interface never accepted them on `put`.
+ */
+export interface EdgeObjectHttpMetadata {
+  readonly contentType?: string;
+}
+
+/** A byte range the Host actually served, in R2's `R2Range` spelling. */
+export interface EdgeObjectRange {
+  readonly offset: number;
+  readonly length: number;
+}
+
+/**
+ * R2's `R2Object` over `edge.objects@1.0.0`: what `head`, `put` and a `list`
+ * entry answer with.
+ */
+export interface EdgeR2Object {
+  readonly key: string;
+  readonly size: number;
+  /** The Host's etag verbatim. Opaque; quoting differs by backend. */
+  readonly etag: string;
+  /** The same etag in R2's header-safe quoted spelling. */
+  readonly httpEtag: string;
+  /** A `Date` on `head` and `list`; `undefined` on `get` and `put`. */
+  readonly uploaded: Date | undefined;
+  readonly httpMetadata: EdgeObjectHttpMetadata;
+  /** Always `undefined`: `edge.objects` has no custom metadata (ADR 0005). */
+  readonly customMetadata: undefined;
+  /** Present only on a ranged `get`. */
+  readonly range?: EdgeObjectRange;
+  /** Writes the metadata this object carries onto response headers. */
+  writeHttpMetadata(headers: Headers): void;
+}
+
+/** R2's `R2ObjectBody`: an {@link EdgeR2Object} whose bytes came with it. */
+export interface EdgeR2ObjectBody extends EdgeR2Object {
+  readonly body: ReadableStream<Uint8Array>;
+  readonly bodyUsed: boolean;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+  blob(): Promise<Blob>;
+}
+
+/** R2's `R2Objects`: one page of {@link EdgeObjectsBucket.list}. */
+export interface EdgeR2Objects {
+  readonly objects: readonly EdgeR2Object[];
+  readonly truncated: boolean;
+  readonly cursor?: string;
+  /** R2's name for the common prefixes a `delimiter` collapsed. */
+  readonly delimitedPrefixes: readonly string[];
+}
+
+export interface EdgeObjectsGetOptions {
+  readonly range?: { readonly offset: number; readonly length?: number };
+}
+
+export interface EdgeObjectsListOptions {
+  readonly prefix?: string;
+  readonly delimiter?: string;
+  readonly cursor?: string;
+  readonly limit?: number;
+}
+
+/** R2 quotes its `httpEtag`; the Host's etag may or may not already be quoted. */
+function httpEtagOf(etag: string): string {
+  if (etag.length >= 2 && etag.startsWith('"') && etag.endsWith('"')) {
+    return etag;
+  }
+  return `"${etag}"`;
+}
+
+function writeContentType(
+  contentType: string | undefined,
+  headers: Headers,
+): void {
+  // R2 writes only the fields its `httpMetadata` actually holds, so an object
+  // stored without a content type leaves the caller's headers alone.
+  if (contentType !== undefined) headers.set("content-type", contentType);
+}
+
+/**
+ * R2's `R2Object`. Metadata only: `head`, `put` and every `list` entry.
+ */
+class EdgeR2ObjectMetadata implements EdgeR2Object {
+  readonly key: string;
+  readonly size: number;
+  readonly etag: string;
+  readonly httpEtag: string;
+  readonly uploaded: Date | undefined;
+  readonly httpMetadata: EdgeObjectHttpMetadata;
+  readonly customMetadata: undefined = undefined;
+  readonly range?: EdgeObjectRange;
+
+  constructor(
+    key: string,
+    metadata: {
+      readonly etag: string;
+      readonly size: number;
+      readonly contentType?: string;
+      readonly uploadedAtMillis?: number;
+    },
+    range?: EdgeObjectRange,
+  ) {
+    this.key = key;
+    this.size = metadata.size;
+    this.etag = metadata.etag;
+    this.httpEtag = httpEtagOf(metadata.etag);
+    this.uploaded =
+      metadata.uploadedAtMillis === undefined
+        ? undefined
+        : new Date(metadata.uploadedAtMillis);
+    this.httpMetadata =
+      metadata.contentType === undefined
+        ? {}
+        : { contentType: metadata.contentType };
+    if (range !== undefined) this.range = range;
+  }
+
+  writeHttpMetadata(headers: Headers): void {
+    writeContentType(this.httpMetadata.contentType, headers);
+  }
+}
+
+/**
+ * R2's `R2ObjectBody`.
+ *
+ * The bytes are held in a `Response`, which is where the body semantics come
+ * from rather than being re-implemented: `bodyUsed` flips the moment the stream
+ * is disturbed — including by a caller that read `body` itself — and a second
+ * `text()` / `json()` / `arrayBuffer()` / `blob()` REJECTS with a `TypeError`
+ * instead of replaying the first read. That is R2's own behaviour (workerd's
+ * `R2ObjectBody` refuses a disturbed body the same way the `Body` mixin does),
+ * so a caller cannot tell the two apart by consuming twice.
+ */
+class EdgeR2ObjectWithBody
+  extends EdgeR2ObjectMetadata
+  implements EdgeR2ObjectBody
+{
+  readonly #response: Response;
+
+  constructor(
+    key: string,
+    metadata: {
+      readonly etag: string;
+      readonly size: number;
+      readonly contentType?: string;
+      readonly uploadedAtMillis?: number;
+    },
+    body: ReadableStream<Uint8Array>,
+    range?: EdgeObjectRange,
+  ) {
+    super(key, metadata, range);
+    // Bytes only, with no content type attached: a `Response` normalises the
+    // header it is given (appending `;charset=utf-8` to a text type, for one),
+    // and that normalisation would show up on `blob().type` as a value the Host
+    // never stored. The stored content type is read where R2 puts it —
+    // `httpMetadata` and `writeHttpMetadata()`.
+    this.#response = new Response(body as unknown as BodyInit);
+  }
+
+  get body(): ReadableStream<Uint8Array> {
+    // A `Response` built from a stream always has one.
+    return this.#response.body as ReadableStream<Uint8Array>;
+  }
+
+  get bodyUsed(): boolean {
+    return this.#response.bodyUsed;
+  }
+
+  arrayBuffer(): Promise<ArrayBuffer> {
+    return this.#response.arrayBuffer();
+  }
+
+  text(): Promise<string> {
+    return this.#response.text();
+  }
+
+  json<T = unknown>(): Promise<T> {
+    return this.#response.json() as Promise<T>;
+  }
+
+  blob(): Promise<Blob> {
+    return this.#response.blob();
+  }
+}
+
 /**
  * The byte length of a body the Host can be told up front, or `undefined` for
  * a bare stream whose size only the producer knows.
@@ -61,14 +305,57 @@ function knownBodyLength(value: ObjectStoreBody): number | undefined {
   return undefined;
 }
 
-export class EdgeObjectStorage implements ObjectStore {
-  constructor(private readonly bucket: EdgeObjectsBinding) {}
+/**
+ * `edge.objects@1.0.0` as a bucket whose answers are R2's.
+ *
+ * The calls are the facade's (its option names, its ceilings, its error
+ * vocabulary); the results are R2-shaped, so app code written against
+ * `R2Bucket` reads them unchanged. See the parity rule at the top of this file
+ * for what is provided, what is best effort, and what the wire cannot supply.
+ */
+export class EdgeObjectsBucket {
+  constructor(private readonly binding: EdgeObjectsBinding) {}
+
+  async head(key: string): Promise<EdgeR2Object | null> {
+    const found: EdgeObjectMetadata | null = await this.binding.head(key);
+    if (!found) return null;
+    return new EdgeR2ObjectMetadata(key, found);
+  }
+
+  async get(
+    key: string,
+    options?: EdgeObjectsGetOptions,
+  ): Promise<EdgeR2ObjectBody | null> {
+    const range = options?.range;
+    // Fixed arity: the Host counts `arguments.length`, so the options slot is
+    // always passed, even when it is empty.
+    const found: EdgeObjectBody | null = await this.binding.get(
+      key,
+      range === undefined ? undefined : { range },
+    );
+    if (!found) return null;
+    if (found.partial && range === undefined) {
+      // No range was asked for, so a partial body would be a truncated object
+      // served as if it were whole. Refuse rather than hand the caller bytes
+      // that do not add up to the object.
+      await found.body.cancel().catch(() => undefined);
+      throw new EdgeObjectsShapeError(
+        "edge.objects: the Host returned a partial body for an unranged get",
+      );
+    }
+    return new EdgeR2ObjectWithBody(
+      key,
+      found,
+      found.body as ReadableStream<Uint8Array>,
+      found.range,
+    );
+  }
 
   async put(
     key: string,
     value: ObjectStoreBody,
     options?: ObjectStorePutOptions,
-  ): Promise<void> {
+  ): Promise<EdgeR2Object> {
     const contentType = options?.contentType;
     let contentLength = knownBodyLength(value);
     // The facade's body slot has no `Blob`. A Blob's stream carries the same
@@ -84,41 +371,89 @@ export class EdgeObjectStorage implements ObjectStore {
       body = buffered;
       contentLength = buffered.byteLength;
     }
-    await this.bucket.put(key, body, {
+    const stored = await this.binding.put(key, body, {
       contentLength,
       ...(contentType === undefined ? {} : { contentType }),
     });
+    // The Host's `put` answers with `{etag, size}` and nothing else, so the
+    // returned object's `uploaded` is absent — see the parity rule above.
+    return new EdgeR2ObjectMetadata(key, {
+      etag: stored.etag,
+      size: stored.size,
+      ...(contentType === undefined ? {} : { contentType }),
+    });
+  }
+
+  async delete(key: string | readonly string[]): Promise<void> {
+    const keys = typeof key === "string" ? [key] : [...new Set(key)];
+    for (const one of keys) await this.binding.delete(one);
+  }
+
+  async list(options?: EdgeObjectsListOptions): Promise<EdgeR2Objects> {
+    const page = await this.binding.list(options);
+    return {
+      objects: page.objects.map(
+        (entry) => new EdgeR2ObjectMetadata(entry.key, entry),
+      ),
+      truncated: page.truncated,
+      ...(page.cursor === undefined ? {} : { cursor: page.cursor }),
+      // R2 calls the common prefixes a delimiter collapsed `delimitedPrefixes`.
+      delimitedPrefixes: page.prefixes,
+    };
+  }
+}
+
+/**
+ * The provider-neutral {@link ObjectStore} over the same bucket.
+ *
+ * This is the port the core's own routes speak, and it stays deliberately
+ * narrower than R2 — flat metadata, no enumeration, no separate head — so app
+ * code does not grow a dependency on a vendor object shape. Code that WANTS R2
+ * takes {@link EdgeObjectsBucket} instead; both run the same adapter, so the
+ * media path proves it.
+ */
+export class EdgeObjectStorage implements ObjectStore {
+  readonly #bucket: EdgeObjectsBucket;
+
+  constructor(bucket: EdgeObjectsBinding) {
+    this.#bucket = new EdgeObjectsBucket(bucket);
+  }
+
+  async put(
+    key: string,
+    value: ObjectStoreBody,
+    options?: ObjectStorePutOptions,
+  ): Promise<void> {
+    await this.#bucket.put(key, value, options);
   }
 
   async get(key: string): Promise<ObjectStoreObject | null> {
-    const found = await this.bucket.get(key, undefined);
+    const found = await this.#bucket.get(key);
     if (!found) return null;
-    if (found.partial) {
-      // No range was asked for, so a partial body would be a truncated object
-      // served as if it were whole. Refuse rather than hand the caller bytes
-      // that do not add up to the object.
-      await found.body.cancel().catch(() => undefined);
-      throw new EdgeObjectsShapeError(
-        "edge.objects: the Host returned a partial body for an unranged get",
-      );
-    }
     return {
-      key,
-      body: found.body as ReadableStream<Uint8Array>,
-      ...(found.contentType === undefined
+      key: found.key,
+      body: found.body,
+      ...(found.httpMetadata.contentType === undefined
         ? {}
-        : { contentType: found.contentType }),
+        : { contentType: found.httpMetadata.contentType }),
       etag: found.etag,
       byteLength: found.size,
     };
   }
 
   async delete(key: string | readonly string[]): Promise<void> {
-    const keys = typeof key === "string" ? [key] : [...new Set(key)];
-    for (const one of keys) await this.bucket.delete(one);
+    await this.#bucket.delete(key);
   }
 }
 
+/** Wrap an `edge.objects@1.0.0` binding as an R2-shaped bucket. */
+export function wrapEdgeObjectsAsBucket(
+  bucket: EdgeObjectsBinding,
+): EdgeObjectsBucket {
+  return new EdgeObjectsBucket(bucket);
+}
+
+/** Wrap an `edge.objects@1.0.0` binding as the provider-neutral port. */
 export function wrapEdgeObjects(bucket: EdgeObjectsBinding): ObjectStore {
   return new EdgeObjectStorage(bucket);
 }

package/src/backend/runtime/public-origin.ts

@@ -8,15 +8,20 @@
  * are all `${APP_URL}/…`, and a wrong one is not a broken page — it is a
  * permanent, federated wrong answer that remote servers have already cached.
  *
- * `APP_URL` is a plain variable, and on a wrapper host it cannot always be one.
- * A Takoform `WorkerEndpoint` allocates the Worker's public origin AFTER the
- * `WorkerVersion` that would have carried the variable is already immutable, so
- * the deployer does not know the value at apply time and there is no second
- * apply that could inject it. The origin exists, but only the Host knows it,
- * and the only place it is ever spoken is on the requests the Host routes here.
+ * `APP_URL` is a plain variable, and on a Host-assigned endpoint it cannot
+ * always be one. A Takoform `WorkerEndpoint` allocates the Worker's public
+ * origin AFTER the `WorkerVersion` that would have carried the variable is
+ * already immutable, so the deployer does not know the value at apply time and
+ * there is no second apply that could inject it. The origin exists, but only
+ * the Host knows it, and the only place it is ever spoken is on the requests
+ * the Host routes here.
  *
- * So on the `portable` lane an unset `APP_URL` is answered by OBSERVING one
- * request and PINNING what it observed:
+ * This has nothing to do with the runtime lane. The lane names the SHAPE OF THE
+ * BINDINGS; a Takoform-hosted Worker on the production Takoserver runs on raw
+ * Cloudflare bindings — the `cloudflare` lane — and is in exactly the same
+ * position, because the Takoform module passes no `APP_URL` there either. So on
+ * EVERY lane an unset `APP_URL` is answered by OBSERVING one request and
+ * PINNING what it observed:
  *
  *   1. `APP_URL` is authoritative whenever it is set. It is used exactly as the
  *      operator wrote it and is never validated, cached, or persisted here —
@@ -32,27 +37,38 @@
  *
  * WHAT IS TRUSTED. The request URL as the runtime delivers it, and only that.
  * Not `X-Forwarded-Host`, not `X-Forwarded-Proto`, not `Host` read out of the
- * headers — nothing a client can write. Both wrapper hosts route by hostname
- * and deliver the request they received on the Worker's own public endpoint:
- * Takoserver's managed Workers-for-Platforms gateway looks up a host route for
- * `new URL(request.url).hostname` and dispatches the SAME `Request` object, and
- * the self-host workerd router picks a service from a table keyed by hostname
- * and forwards unchanged. A hostname nobody published for this Worker is a 404
- * before any of this code runs, so the origin on the request is one the Host
- * assigned — which is exactly the value that could not be delivered as a var.
+ * headers — nothing a client can write. That URL is the endpoint the request
+ * genuinely arrived on, under every host this bundle runs on. Cloudflare
+ * Workers build `request.url` from the connection the edge terminated. Both
+ * wrapper hosts route by hostname and hand over the request they received on
+ * the Worker's own public endpoint: Takoserver's managed Workers-for-Platforms
+ * gateway looks up a host route for `new URL(request.url).hostname` and
+ * dispatches the SAME `Request` object, and the self-host workerd router picks
+ * a service from a table keyed by hostname and forwards unchanged. A hostname
+ * nobody published for this Worker is a 404 before any of this code runs, so
+ * the origin on the request is one the Host assigned — which is exactly the
+ * value that could not be delivered as a var.
  *
- * WHY HTTPS. A public fediverse origin is https, and Takoserver's own
- * `WorkerEndpoint` can only ever assign an https origin. Requiring it here
- * means an http request cannot pin an origin that would then sign deliveries
- * and mint actor ids. Loopback http is the one exception, because `localhost`
- * is not routable and is the origin a developer actually serves on.
+ * WHAT THIS DOES NOT DECIDE. A Worker published straight to Cloudflare by an
+ * operator who holds several hostnames answers on all of them, and first writer
+ * wins means the first one to arrive names the instance. That operator knows
+ * their hostnames and sets `APP_URL`, which always wins and is never pinned.
+ * Inference is the answer for the deployment that CANNOT be told its origin,
+ * not a preference over being told.
  *
- * A wrapper host that terminates TLS in FRONT of workerd and speaks plain http
- * to it therefore establishes nothing: `request.url` is `http://…` and the
- * derivation refuses. That deployment must set `APP_URL`, which it can, because
- * an operator who terminates TLS chose the hostname themselves. Refusing is the
- * point — the alternative is trusting a forwarded-proto header that the same
- * proxy may or may not be the only writer of.
+ * WHY HTTPS. A public fediverse origin is https; Cloudflare terminates TLS in
+ * front of a Worker on a public hostname, and Takoserver's own `WorkerEndpoint`
+ * can only ever assign an https origin. Requiring it here means an http request
+ * cannot pin an origin that would then sign deliveries and mint actor ids.
+ * Loopback http is the one exception, because `localhost` is not routable and
+ * is the origin a developer actually serves on — `wrangler dev` included.
+ *
+ * A host that terminates TLS in FRONT of the runtime and speaks plain http to
+ * it therefore establishes nothing: `request.url` is `http://…` on a routable
+ * name and the derivation refuses. That deployment must set `APP_URL`, which it
+ * can, because an operator who terminates TLS chose the hostname themselves.
+ * Refusing is the point — the alternative is trusting a forwarded-proto header
+ * that the same proxy may or may not be the only writer of.
  */
 
 import type { Env, EnvVars } from "../types.ts";