@takosjp/yurucommu-core 4.0.0 → 4.1.1

package/src/backend/runtime/lane.ts

@@ -0,0 +1,309 @@
+/**
+ * Which runtime the Worker was published onto, and the bindings that follow.
+ *
+ * The same bundle runs on two backends that look identical from inside:
+ *
+ *   `cloudflare`  — RAW Cloudflare bindings. `env.DB` is a `D1Database`,
+ *                   `env.KV` a `KVNamespace`, `env.MEDIA` an `R2Bucket`,
+ *                   `env.DELIVERY_QUEUE` a `Queue`. This is a Worker deployed
+ *                   straight to Cloudflare, and equally an ordinary-Workers
+ *                   Takoserver backend, which projects those same raw bindings.
+ *   `portable`    — the PORTABLE FACADES. A wrapper host — a self-hosted
+ *                   Takoserver, or a managed Workers-for-Platforms backend —
+ *                   replaces `env` before the module sees it, and each binding
+ *                   is the facade its Interface names: `edge.sql`, `edge.kv`,
+ *                   `edge.objects`, `edge.queue`.
+ *
+ * THE LANE NAMES THE BINDING SHAPE, not the tool that published the Worker. A
+ * deployment authored in Takoform lands on either one depending on the host it
+ * targets, so the lane cannot be inferred from the IaC that produced it.
+ *
+ * THE LANE IS DECLARED, NOT SNIFFED. Two of the bindings cannot be told apart
+ * by shape at all — `edge.kv` and `KVNamespace` expose the same five method
+ * names, and both queue producers are `send`/`sendBatch`. A Worker that guessed
+ * would call `kv.get(key, {type:"json"})` on a facade that ignores the second
+ * argument and returns bytes, and the failure would surface much later as a
+ * corrupt session or a rate-limit that never trips.
+ *
+ * So the lane comes from `YURUCOMMU_RUNTIME_LANE`, which a self-host or managed
+ * Workers-for-Platforms deployment sets to `portable` and every raw-binding
+ * deployment leaves unset (or `cloudflare`). The declaration is then
+ * cross-checked against the ONE binding that is decisive — `DB`. A
+ * disagreement refuses to start.
+ *
+ * `MEDIA` is NOT decisive and must never be cross-checked. Takoserver's
+ * `edge.objects@1.0.0` facade is method-for-method a bucket: `head`, `get`,
+ * `put`, `delete`, `list`, `createMultipartUpload`, `uploadPart`,
+ * `completeMultipartUpload`, `abortMultipartUpload` — the same names, the same
+ * option keys, deliberately, so that an app written against R2 ports over
+ * unchanged (ADR 0005/0007). 4.1.0 read that identity backwards and refused the
+ * portable lane whenever `MEDIA` looked R2-shaped, which is to say always: a
+ * self-hosted Yurucommu Worker could not boot on the lane its own README
+ * documents. The declaration decides `MEDIA`.
+ */
+
+import type {
+  D1Database,
+  Fetcher,
+  KVNamespace,
+  MessageBatch,
+  Queue,
+  R2Bucket,
+} from "@cloudflare/workers-types";
+
+import type { Database } from "../../db/index.ts";
+import {
+  isEdgeObjectsBinding,
+  isEdgeQueueBatch,
+  isEdgeSqlBinding,
+  isNativeD1Database,
+  type EdgeKvBinding,
+  type EdgeObjectsBinding,
+  type EdgeQueueBatch,
+  type EdgeQueueBinding,
+  type EdgeSqlBinding,
+} from "./edge-facades.ts";
+import { createEdgeSqlDatabase } from "./edge-sql.ts";
+import { wrapEdgeKv } from "./edge-kv.ts";
+import { wrapEdgeMessageBatch, wrapEdgeQueue } from "./edge-queue.ts";
+import { wrapEdgeObjects } from "./edge-objects.ts";
+import {
+  wrapCloudflareBindings,
+  wrapCloudflareMessageBatch,
+} from "./cloudflare.ts";
+import type { IKeyValueStore, IStaticAssets, ObjectStore } from "./types.ts";
+import type { IQueueBatch, IQueueProducer } from "./queue.ts";
+
+/** The variable that names the lane. Set it in the deployment's plain vars. */
+export const RUNTIME_LANE_VAR = "YURUCOMMU_RUNTIME_LANE";
+
+/** Every lane this build knows how to run on. */
+export const RUNTIME_LANES = ["cloudflare", "portable"] as const;
+
+export type RuntimeLane = (typeof RUNTIME_LANES)[number];
+
+/** The lane when the variable is absent: a plain Cloudflare Worker. */
+export const DEFAULT_RUNTIME_LANE: RuntimeLane = "cloudflare";
+
+/** The declared lane is unknown, or disagrees with the bindings that arrived. */
+export class RuntimeLaneError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RuntimeLaneError";
+  }
+}
+
+/**
+ * Read the declared lane.
+ *
+ * An unset variable is the Cloudflare lane, because that is what a Worker
+ * deployed without Takoform is. An UNRECOGNISED value is refused rather than
+ * defaulted: a future Host that names a lane this build has never heard of must
+ * not be served by guessing that its bindings are Cloudflare's.
+ */
+export function resolveRuntimeLane(declared: unknown): RuntimeLane {
+  if (declared === undefined || declared === null || declared === "") {
+    return DEFAULT_RUNTIME_LANE;
+  }
+  if (typeof declared !== "string") {
+    throw new RuntimeLaneError(
+      `${RUNTIME_LANE_VAR} must be a string; received ${typeof declared}`,
+    );
+  }
+  const lane = declared.trim();
+  if ((RUNTIME_LANES as readonly string[]).includes(lane)) {
+    return lane as RuntimeLane;
+  }
+  throw new RuntimeLaneError(
+    `${RUNTIME_LANE_VAR}="${declared}" is not a runtime lane this build ` +
+      `supports (${RUNTIME_LANES.join(", ")}). Refusing to start rather than ` +
+      `assume a binding shape.`,
+  );
+}
+
+interface LaneBindings {
+  readonly DB?: unknown;
+  /**
+   * Accepted so a caller can pass the whole `env`, and deliberately not read:
+   * the bucket binding carries no evidence about the lane. See
+   * {@link assertRuntimeLaneBindings}.
+   */
+  readonly MEDIA?: unknown;
+}
+
+/**
+ * Prove the declared lane against the ONE binding that can be identified.
+ *
+ * `DB` is decisive in both directions: `execute`/`query`/`transaction` and
+ * `prepare`/`batch` are disjoint method sets, so a Worker that was handed the
+ * wrong one would fail at its first query anyway and is better stopped here
+ * with a message that names the variable to fix.
+ *
+ * `MEDIA` is checked against NOTHING. The portable `edge.objects@1.0.0` facade
+ * is intentionally indistinguishable from an `R2Bucket` — that identity is the
+ * point of the Interface — so a shape test on it can only produce false
+ * refusals. On `portable` the bucket is wrapped as the facade, on `cloudflare`
+ * as native R2, and the declaration is the whole of the evidence. Getting it
+ * wrong is loud and immediate (the first `MEDIA` call throws), not the silent
+ * misread that `KV`'s ambiguity would cause.
+ */
+export function assertRuntimeLaneBindings(
+  lane: RuntimeLane,
+  bindings: LaneBindings,
+): void {
+  const { DB } = bindings;
+  if (lane === "portable") {
+    if (isNativeD1Database(DB)) {
+      throw new RuntimeLaneError(
+        `${RUNTIME_LANE_VAR}="portable" declares the portable-facade lane, ` +
+          `but env.DB is a native D1Database (prepare/batch). A host that ` +
+          `projects raw Cloudflare bindings — including an ordinary-Workers ` +
+          `Takoserver backend — is the cloudflare lane; leave the variable ` +
+          `unset there.`,
+      );
+    }
+    if (!isEdgeSqlBinding(DB)) {
+      throw new RuntimeLaneError(
+        `${RUNTIME_LANE_VAR}="portable" requires env.DB to be the ` +
+          `edge.sql@1.0.0 facade (execute/query/transaction); it exposes ` +
+          `neither that nor D1's prepare/batch.`,
+      );
+    }
+    return;
+  }
+  if (isEdgeSqlBinding(DB)) {
+    throw new RuntimeLaneError(
+      `env.DB is the edge.sql@1.0.0 facade (execute/query/transaction), but ` +
+        `${RUNTIME_LANE_VAR} does not declare the portable lane. A Worker on a ` +
+        `wrapper host must declare it; without that this build would hand the ` +
+        `facade to drizzle-orm/d1 and every query would fail at the first ` +
+        `prepare().`,
+    );
+  }
+  if (!isNativeD1Database(DB)) {
+    throw new RuntimeLaneError(
+      `env.DB is neither a D1Database nor the edge.sql@1.0.0 facade; the ` +
+        `Cloudflare lane cannot build a database client from it.`,
+    );
+  }
+}
+
+/** Bindings a Worker receives from a host that projects portable facades. */
+export interface PortableWorkerBindings {
+  DB: EdgeSqlBinding;
+  KV: EdgeKvBinding;
+  MEDIA?: EdgeObjectsBinding;
+  ASSETS?: IStaticAssets;
+  DELIVERY_QUEUE?: EdgeQueueBinding;
+  DELIVERY_DLQ?: EdgeQueueBinding;
+}
+
+/** Bindings a Worker deployed straight to Cloudflare receives. */
+export interface CloudflareWorkerBindings {
+  DB: D1Database;
+  KV: KVNamespace;
+  MEDIA?: R2Bucket;
+  ASSETS?: Fetcher;
+  DELIVERY_QUEUE?: Queue<unknown>;
+  DELIVERY_DLQ?: Queue<unknown>;
+}
+
+type WrappedRuntime<T> = Omit<
+  T,
+  "DB" | "MEDIA" | "KV" | "ASSETS" | "DELIVERY_QUEUE" | "DELIVERY_DLQ"
+> & {
+  DB_INSTANCE: Database;
+  MEDIA?: ObjectStore;
+  KV: IKeyValueStore;
+  ASSETS?: IStaticAssets;
+  DELIVERY_QUEUE?: IQueueProducer<unknown>;
+  DELIVERY_DLQ?: IQueueProducer<unknown>;
+};
+
+/**
+ * Wrap the portable facades into the runtime ports the app speaks.
+ *
+ * `ASSETS` passes through: a Takoform `external_services` entry is projected as
+ * a `{fetch}` adapter, which is already the port's whole surface.
+ */
+export function wrapPortableBindings<T extends PortableWorkerBindings>(
+  bindings: T,
+): WrappedRuntime<T> {
+  const { DB, MEDIA, KV, ASSETS, DELIVERY_QUEUE, DELIVERY_DLQ, ...rest } =
+    bindings;
+  return {
+    ...rest,
+    DB_INSTANCE: createEdgeSqlDatabase(DB),
+    MEDIA: MEDIA ? wrapEdgeObjects(MEDIA) : undefined,
+    KV: wrapEdgeKv(KV),
+    ASSETS,
+    DELIVERY_QUEUE: DELIVERY_QUEUE ? wrapEdgeQueue(DELIVERY_QUEUE) : undefined,
+    DELIVERY_DLQ: DELIVERY_DLQ ? wrapEdgeQueue(DELIVERY_DLQ) : undefined,
+  } as unknown as WrappedRuntime<T>;
+}
+
+/**
+ * The single entry point a Worker should call.
+ *
+ * Reads {@link RUNTIME_LANE_VAR} off the bindings themselves — on both lanes it
+ * is an ordinary plain-text variable that arrives alongside them — proves the
+ * lane against the decisive bindings, and then wraps.
+ */
+export function wrapRuntimeBindings<
+  // Deliberately structural. Which of the two binding sets this actually is,
+  // is the runtime question this function answers; a static union here would
+  // only force every caller to assert the answer before asking it.
+  T extends { DB: unknown; KV: unknown },
+>(bindings: T): WrappedRuntime<T> {
+  const lane = resolveRuntimeLane(
+    (bindings as Record<string, unknown>)[RUNTIME_LANE_VAR],
+  );
+  assertRuntimeLaneBindings(lane, bindings as LaneBindings);
+  return lane === "portable"
+    ? (wrapPortableBindings(
+        bindings as unknown as PortableWorkerBindings,
+      ) as unknown as WrappedRuntime<T>)
+    : (wrapCloudflareBindings(
+        bindings as unknown as CloudflareWorkerBindings & {
+          DB: D1Database;
+          KV: KVNamespace;
+        },
+      ) as unknown as WrappedRuntime<T>);
+}
+
+/**
+ * Adapt one consumer batch for whichever lane produced it.
+ *
+ * A queue batch IS decisive — the facade settles with `acknowledgeAll`, the
+ * Cloudflare `MessageBatch` with `ackAll` — so the shape is checked against the
+ * declared lane rather than trusted on its own.
+ */
+export function wrapRuntimeMessageBatch<T>(
+  batch: MessageBatch<T> | EdgeQueueBatch,
+  lane: RuntimeLane = DEFAULT_RUNTIME_LANE,
+): IQueueBatch<T> {
+  const isFacade = isEdgeQueueBatch(batch);
+  if (lane === "portable") {
+    if (!isFacade) {
+      throw new RuntimeLaneError(
+        `${RUNTIME_LANE_VAR}="portable" declares the portable-facade lane, ` +
+          `but the queue event is a Cloudflare MessageBatch (ackAll).`,
+      );
+    }
+    return wrapEdgeMessageBatch<T>(batch);
+  }
+  if (isFacade) {
+    throw new RuntimeLaneError(
+      `The queue event is a portable-facade batch (acknowledgeAll), but ` +
+        `${RUNTIME_LANE_VAR} does not declare the portable lane.`,
+    );
+  }
+  return wrapCloudflareMessageBatch(batch as MessageBatch<T>);
+}
+
+/**
+ * Re-exported so a Worker entry can assert that SOMETHING bucket-shaped
+ * arrived without importing internals. It does not identify the lane — a
+ * native `R2Bucket` satisfies it too — so never branch on it.
+ */
+export { isEdgeObjectsBinding };

package/src/backend/runtime/managed-relational.ts

@@ -5,6 +5,7 @@ import {
   parseManagedRelationalBatchResponse,
   type ManagedRelationalMethod,
   type ManagedRelationalParameter,
+  type ManagedRelationalStatement,
 } from "@takosjp/takosumi-contract/managed-relational-runtime";
 import { parseManagedRuntimeConnectionMaterialization } from "@takosjp/takosumi-contract/managed-runtime-connections";
 import {
@@ -16,9 +17,17 @@ import {
 import * as schema from "../../db/schema.ts";
 import { ManagedRuntimeGatewayError } from "./managed-runtime.ts";
 import type { ManagedRuntimeGateway } from "./managed-runtime.ts";
+import {
+  positionalRow,
+  rewriteProjection,
+  type ProjectedStatement,
+} from "./sqlite-proxy-rows.ts";
 
 const DEFAULT_MAX_RELATIONAL_RESPONSE_BYTES = 8 * 1024 * 1024;
 
+/** The lane name a row-shape refusal reports. */
+const LANE = "managed relational";
+
 export interface ManagedRelationalDatabaseOptions {
   readonly materialization: unknown;
   readonly gateway: ManagedRuntimeGateway;
@@ -33,6 +42,11 @@ export interface ManagedRelationalDatabaseOptions {
  * Every callback is one bounded prepared statement. Drizzle `batch()` maps to
  * one ordered-atomic host call; transaction-control and migration SQL are
  * deliberately unavailable on this request path.
+ *
+ * Row shape is shared with the `edge.sql` lane (`sqlite-proxy-rows.ts`): the
+ * projection list is rewritten so no two result columns share a name, the
+ * column count that comes back is checked against the count that went out, and
+ * the row Drizzle indexes positionally also answers to its column names.
  */
 export function createManagedRelationalDatabase(
   options: ManagedRelationalDatabaseOptions,
@@ -64,13 +78,9 @@ export function createManagedRelationalDatabase(
       readonly method: ManagedRelationalMethod;
     }[],
   ) => {
-    const canonical = statements.map((statement) => ({
-      sql: statement.sql,
-      params: statement.params.map(relationalParameter),
-      method: statement.method,
-    }));
+    const prepared = statements.map(prepare);
     const request = managedRelationalBatchGatewayRequest(connection.authority, {
-      statements: canonical,
+      statements: prepared.map((entry) => entry.statement),
       idempotencyKey: idempotencyKey(),
     });
     const response = await boundedResponse(
@@ -91,40 +101,77 @@ export function createManagedRelationalDatabase(
     }
     const value = parseManagedRelationalBatchResponse(
       await response.json(),
-      canonical.length,
+      prepared.length,
+    );
+    return value.results.map((result, index) =>
+      drizzleResult(result, prepared[index]!),
     );
-    return value.results;
   };
 
   const callback: AsyncRemoteCallback = async (sql, params, method) => {
     const [result] = await execute([{ sql, params, method }]);
     if (!result) throw new Error("managed_relational_result_missing");
-    return drizzleResult(result, method);
-  };
-  const batchCallback: AsyncBatchRemoteCallback = async (batch) => {
-    const results = await execute(batch);
-    return results.map((result, index) =>
-      drizzleResult(result, batch[index]!.method),
-    );
+    return result;
   };
+  const batchCallback: AsyncBatchRemoteCallback = async (batch) =>
+    await execute(batch);
 
   return drizzleProxy(callback, batchCallback, { schema });
 }
 
+interface PreparedStatement {
+  readonly statement: ManagedRelationalStatement;
+  readonly projection: ProjectedStatement;
+}
+
+/**
+ * Trim first, then give every projected column a distinct name.
+ *
+ * The runtime contract refuses a statement whose text is not already trimmed,
+ * and Drizzle does not trim the raw `sql` template a call site wrote across
+ * several lines — so the personal block and mute gates' own statements would
+ * never reach the host at all.
+ */
+function prepare(statement: {
+  readonly sql: string;
+  readonly params: readonly unknown[];
+  readonly method: ManagedRelationalMethod;
+}): PreparedStatement {
+  const source = statement.sql.trim();
+  const rewritten = rewriteProjection(source);
+  return {
+    statement: {
+      sql: rewritten.sql,
+      params: statement.params.map(relationalParameter),
+      method: statement.method,
+    },
+    projection: { lane: LANE, sql: source, columns: rewritten.columns },
+  };
+}
+
+/**
+ * `sqlite-proxy` wants a flat row for `get` and an array of rows otherwise.
+ *
+ * A `get` that matched nothing must yield `undefined`, not an empty array:
+ * Drizzle's `mapGetResult` short-circuits on a FALSY row, and `[]` is truthy,
+ * so an empty array is mapped into an object whose every field is `undefined` —
+ * a "row" for a query that found none, which `if (exact) return true` in the
+ * personal block gate reads as a hit.
+ */
 function drizzleResult(
   result: Awaited<
     ReturnType<typeof parseManagedRelationalBatchResponse>
   >["results"][number],
-  method: ManagedRelationalMethod,
+  prepared: PreparedStatement,
 ) {
+  // sqlite-proxy exposes mutable `any[]` at this boundary even though the
+  // public runtime contract is intentionally immutable. `positionalRow` copies,
+  // so the provider-neutral contract never leaks a mutable result reference.
+  const rows = result.rows.map((row) =>
+    positionalRow(prepared.projection, result.columns, row),
+  );
   return {
-    // sqlite-proxy exposes mutable `any[]` at this boundary even though the
-    // public runtime contract is intentionally immutable. Copy here so the
-    // provider-neutral contract never leaks a mutable result reference.
-    rows:
-      method === "get"
-        ? [...(result.rows[0] ?? [])]
-        : result.rows.map((row) => [...row]),
+    rows: (prepared.statement.method === "get" ? rows[0] : rows) as unknown[],
     meta: result.meta,
   };
 }

package/src/backend/runtime/node-paths.ts

@@ -0,0 +1,79 @@
+/**
+ * Filesystem path containment for the Bun/Node runtime ONLY.
+ *
+ * These helpers need `node:path`, so they live apart from `shared.ts`. That
+ * separation is load-bearing rather than tidy: `shared.ts` is reached from
+ * `edge-kv.ts` and `edge-objects.ts`, which are on the portable Worker's
+ * import path. A `node:` specifier anywhere in that graph survives bundling as
+ * a real static import, and a wrapper host (self-hosted Takoserver, managed
+ * Workers-for-Platforms) runs the Worker with no `nodejs_compat` flag — the
+ * portable `WorkerVersion` form has nowhere to ask for one — so the module
+ * fails to load with `No such module "node:path"` before a single request is
+ * served. Nothing in this file may be imported from a module the Worker
+ * bundle reaches; `scripts/check-worker-bundle-portable.mjs` enforces that.
+ */
+
+import path from "node:path";
+
+import { hasNulByte } from "./shared.ts";
+
+export function isPathWithinBasePath(
+  basePath: string,
+  candidatePath: string,
+): boolean {
+  const relative = path.relative(basePath, candidatePath);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+export function resolvePathWithinBasePath(
+  basePath: string,
+  key: string,
+): string {
+  if (hasNulByte(key)) {
+    throw new Error("Invalid path");
+  }
+  const resolvedPath = path.resolve(basePath, key);
+  if (!isPathWithinBasePath(basePath, resolvedPath)) {
+    throw new Error("Path escapes base directory");
+  }
+  return resolvedPath;
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+export async function assertPathChainWithinBasePath(
+  basePath: string,
+  targetPath: string,
+  realpath: (path: string) => Promise<string>,
+): Promise<void> {
+  let currentPath = targetPath;
+
+  while (true) {
+    try {
+      const realCurrentPath = await realpath(currentPath);
+      if (!isPathWithinBasePath(basePath, realCurrentPath)) {
+        throw new Error("Path escapes base directory");
+      }
+      return;
+    } catch (error) {
+      if (!isNotFoundError(error)) {
+        throw error;
+      }
+      const parentPath = path.dirname(currentPath);
+      if (parentPath === currentPath) {
+        throw error;
+      }
+      currentPath = parentPath;
+    }
+  }
+}

package/src/backend/runtime/shared.ts

@@ -1,4 +1,12 @@
-import path from "node:path";
+/**
+ * Runtime helpers shared by EVERY lane, including the portable Worker.
+ *
+ * `edge-kv.ts` and `edge-objects.ts` import this module, so it is part of the
+ * bundle a wrapper host loads with no `nodejs_compat` flag. It must therefore
+ * stay free of `node:` specifiers; the filesystem path helpers that need
+ * `node:path` live in `node-paths.ts`, which only the Bun/Node runtime
+ * imports.
+ */
 
 export const DEFAULT_LIST_LIMIT = 1000;
 
@@ -35,67 +43,6 @@ export function hasNulByte(value: string): boolean {
   return value.includes("\0");
 }
 
-export function isPathWithinBasePath(
-  basePath: string,
-  candidatePath: string,
-): boolean {
-  const relative = path.relative(basePath, candidatePath);
-  return (
-    relative === "" ||
-    (!relative.startsWith("..") && !path.isAbsolute(relative))
-  );
-}
-
-export function resolvePathWithinBasePath(
-  basePath: string,
-  key: string,
-): string {
-  if (hasNulByte(key)) {
-    throw new Error("Invalid path");
-  }
-  const resolvedPath = path.resolve(basePath, key);
-  if (!isPathWithinBasePath(basePath, resolvedPath)) {
-    throw new Error("Path escapes base directory");
-  }
-  return resolvedPath;
-}
-
-function isNotFoundError(error: unknown): boolean {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    "code" in error &&
-    (error as { code?: unknown }).code === "ENOENT"
-  );
-}
-
-export async function assertPathChainWithinBasePath(
-  basePath: string,
-  targetPath: string,
-  realpath: (path: string) => Promise<string>,
-): Promise<void> {
-  let currentPath = targetPath;
-
-  while (true) {
-    try {
-      const realCurrentPath = await realpath(currentPath);
-      if (!isPathWithinBasePath(basePath, realCurrentPath)) {
-        throw new Error("Path escapes base directory");
-      }
-      return;
-    } catch (error) {
-      if (!isNotFoundError(error)) {
-        throw error;
-      }
-      const parentPath = path.dirname(currentPath);
-      if (parentPath === currentPath) {
-        throw error;
-      }
-      currentPath = parentPath;
-    }
-  }
-}
-
 export async function readStream(
   stream: ReadableStream<Uint8Array>,
 ): Promise<Uint8Array> {