@takosjp/yurucommu-core 3.4.5 → 4.1.0

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

@@ -0,0 +1,120 @@
+/**
+ * `edge.objects@1.0.0` → {@link ObjectStore}.
+ *
+ * The facade is deliberately narrower than R2, and the narrow spots are the
+ * interesting ones:
+ *
+ *  - 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.
+ *  - 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
+ *    knows its length — a `Blob` (the shape media uploads hand over), an
+ *    `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.
+ *
+ * AVAILABILITY: `edge.objects` is projected by the managed Cloudflare backend
+ * (`createEdgeObjectsR2Adapter`). The self-host backend projects only
+ * `edge.kv` and `edge.sql`, so a self-hosted Worker has no object binding and
+ * the core's existing "object storage unavailable" behaviour applies.
+ */
+
+import type {
+  ObjectStore,
+  ObjectStoreBody,
+  ObjectStoreObject,
+  ObjectStorePutOptions,
+} from "./types.ts";
+import type { EdgeObjectsBinding } from "./edge-facades.ts";
+import { readStream } from "./shared.ts";
+
+/** A request or response the facade cannot express. */
+export class EdgeObjectsShapeError extends TypeError {
+  constructor(message: string) {
+    super(message);
+    this.name = "EdgeObjectsShapeError";
+  }
+}
+
+/**
+ * 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.
+ */
+function knownBodyLength(value: ObjectStoreBody): number | undefined {
+  if (value instanceof Blob) return value.size;
+  if (value instanceof ArrayBuffer) return value.byteLength;
+  if (typeof value === "string") {
+    return new TextEncoder().encode(value).byteLength;
+  }
+  return undefined;
+}
+
+export class EdgeObjectStorage implements ObjectStore {
+  constructor(private readonly bucket: EdgeObjectsBinding) {}
+
+  async put(
+    key: string,
+    value: ObjectStoreBody,
+    options?: ObjectStorePutOptions,
+  ): Promise<void> {
+    const contentType = options?.contentType;
+    let contentLength = knownBodyLength(value);
+    // The facade's body slot has no `Blob`. A Blob's stream carries the same
+    // bytes and its size is already known, so it goes over as a declared-length
+    // stream rather than being buffered.
+    let body: string | ArrayBuffer | Uint8Array | ReadableStream =
+      value instanceof Blob ? value.stream() : value;
+    if (contentLength === undefined) {
+      // No knowable length and a stream: the size has to come from somewhere,
+      // and the Host will not discover it. Buffering is the only remaining
+      // option, so it happens where the memory cost is visible.
+      const buffered = await readStream(body as ReadableStream<Uint8Array>);
+      body = buffered;
+      contentLength = buffered.byteLength;
+    }
+    await this.bucket.put(key, body, {
+      contentLength,
+      ...(contentType === undefined ? {} : { contentType }),
+    });
+  }
+
+  async get(key: string): Promise<ObjectStoreObject | null> {
+    const found = await this.bucket.get(key, undefined);
+    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
+        ? {}
+        : { contentType: found.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);
+  }
+}
+
+export function wrapEdgeObjects(bucket: EdgeObjectsBinding): ObjectStore {
+  return new EdgeObjectStorage(bucket);
+}

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

@@ -0,0 +1,135 @@
+/**
+ * `edge.queue@1.0.0` → {@link IQueueProducer} / {@link IQueueBatch}.
+ *
+ * Two differences from Cloudflare Queues, both of which would otherwise be
+ * discovered in production:
+ *
+ *  - BODIES ARE BYTES. `queue.send(object)` works on Cloudflare because the
+ *    runtime structured-clones the value. The facade runs the body through a
+ *    bytes projection and rejects anything that is not a string, ArrayBuffer,
+ *    or view, so a delivery message has to be serialized. JSON is the encoding
+ *    on both ends, and the consumer side undoes it.
+ *  - THE CONSUMER BATCH IS A DIFFERENT OBJECT. It is `acknowledge` /
+ *    `acknowledgeAll` / `timestampMillis`, not `ack` / `ackAll` / `timestamp`,
+ *    and the body arrives as `{encoding:"base64", data}`. `retry` also refuses
+ *    `delaySeconds: 0`, which Cloudflare accepts as "no delay".
+ *
+ * AVAILABILITY: the managed Cloudflare backend projects queue bindings; the
+ * self-host backend projects only `edge.kv` and `edge.sql` today (see
+ * takoserver `selfhost-worker-wrapper.ts` `projectEnv`). A self-hosted Worker
+ * therefore has no queue binding at all, and the core's existing behaviour for
+ * an unbound `DELIVERY_QUEUE` — synchronous fallback delivery, reported by the
+ * readiness surface — is what applies there.
+ */
+
+import {
+  EDGE_QUEUE_MAX_MESSAGES,
+  decodeEdgeBytes,
+  type EdgeQueueBatch,
+  type EdgeQueueBinding,
+} from "./edge-facades.ts";
+import type {
+  IQueueBatch,
+  IQueueMessage,
+  IQueueProducer,
+  QueueBatchItem,
+  QueueSendOptions,
+} from "./queue.ts";
+
+/** A message cannot be carried over the facade. */
+export class EdgeQueueShapeError extends TypeError {
+  constructor(message: string) {
+    super(message);
+    this.name = "EdgeQueueShapeError";
+  }
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function encodeBody(body: unknown): Uint8Array {
+  let json: string;
+  try {
+    json = JSON.stringify(body);
+  } catch (error) {
+    throw new EdgeQueueShapeError(
+      `edge.queue: the message body is not JSON-serializable: ${String(error)}`,
+    );
+  }
+  if (json === undefined) {
+    throw new EdgeQueueShapeError(
+      "edge.queue: the message body serialized to nothing",
+    );
+  }
+  return encoder.encode(json);
+}
+
+/**
+ * The facade takes `delaySeconds` only as a positive whole number; Cloudflare's
+ * `0` means the same as omitting it, so it is omitted.
+ */
+function delayOption(
+  delaySeconds: number | undefined,
+): { delaySeconds: number } | Record<string, never> {
+  if (delaySeconds === undefined || delaySeconds <= 0) return {};
+  return { delaySeconds: Math.ceil(delaySeconds) };
+}
+
+class EdgeQueueProducer<T> implements IQueueProducer<T> {
+  constructor(private readonly queue: EdgeQueueBinding) {}
+
+  async send(body: T, options?: QueueSendOptions): Promise<void> {
+    await this.queue.send(encodeBody(body), delayOption(options?.delaySeconds));
+  }
+
+  async sendBatch(
+    messages: readonly QueueBatchItem<T>[],
+    options?: QueueSendOptions,
+  ): Promise<void> {
+    if (messages.length === 0) return;
+    if (messages.length > EDGE_QUEUE_MAX_MESSAGES) {
+      throw new EdgeQueueShapeError(
+        `edge.queue: ${messages.length} messages exceed the facade limit of ` +
+          `${EDGE_QUEUE_MAX_MESSAGES}`,
+      );
+    }
+    // `sendBatch` takes no batch-wide options, so a shared default delay is
+    // pushed down onto each message that did not set its own.
+    await this.queue.sendBatch(
+      messages.map(({ body, delaySeconds }) => ({
+        body: encodeBody(body),
+        ...delayOption(delaySeconds ?? options?.delaySeconds),
+      })),
+    );
+  }
+}
+
+export function wrapEdgeQueue<T>(queue: EdgeQueueBinding): IQueueProducer<T> {
+  return new EdgeQueueProducer<T>(queue);
+}
+
+/**
+ * Adapt one consumer batch. The body is decoded with the same JSON encoding
+ * {@link wrapEdgeQueue} writes, so a producer and consumer on this lane agree
+ * even though the Host only ever sees opaque bytes.
+ */
+export function wrapEdgeMessageBatch<T>(batch: EdgeQueueBatch): IQueueBatch<T> {
+  const messages: readonly IQueueMessage<T>[] = batch.messages.map(
+    (message) => ({
+      id: message.id,
+      timestamp: new Date(message.timestampMillis),
+      body: JSON.parse(decoder.decode(decodeEdgeBytes(message.body))) as T,
+      attempts: message.attempts,
+      ack: () => message.acknowledge(),
+      // The facade rejects `delaySeconds: 0` on a retry; omitting it is the
+      // same request.
+      retry: (options) => message.retry(delayOption(options?.delaySeconds)),
+    }),
+  );
+  return {
+    queue: batch.queue,
+    messages,
+    ackAll: () => batch.acknowledgeAll(),
+    retryAll: (options) => batch.retryAll(delayOption(options?.delaySeconds)),
+  };
+}

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

@@ -0,0 +1,207 @@
+/**
+ * `edge.sql@1.0.0` → Drizzle, through `drizzle-orm/sqlite-proxy`.
+ *
+ * Same seam as `managed-relational.ts`: one bounded prepared statement per
+ * callback, `batch()` as one ordered-atomic Host call. What is different is the
+ * ROW SHAPE. D1 hands Drizzle positional arrays (`stmt.raw()`) and
+ * `sqlite-proxy` maps `rows[i][j]` positionally onto the fields it compiled;
+ * `edge.sql` returns RECORDS keyed by result-column name, and a record cannot
+ * represent the duplicate names Drizzle's join SQL produces.
+ *
+ * The projection rewrite that makes those names distinct, the guard that
+ * refuses a row whose column count disagrees with the statement, and the row
+ * that answers to both positional and named reads all live in
+ * `sqlite-proxy-rows.ts`, shared with the managed relational lane. What is left
+ * here is the `edge.sql` value vocabulary and its request limits.
+ */
+
+import {
+  drizzle as drizzleProxy,
+  type AsyncBatchRemoteCallback,
+  type AsyncRemoteCallback,
+} from "drizzle-orm/sqlite-proxy";
+
+import * as schema from "../../db/schema.ts";
+import {
+  EDGE_SQL_MAX_PARAMETERS,
+  EDGE_SQL_MAX_STATEMENTS,
+  decodeEdgeBytes,
+  encodeEdgeBytes,
+  isEdgeEncodedBytes,
+  type EdgeSqlBinding,
+  type EdgeSqlResult,
+  type EdgeSqlValue,
+} from "./edge-facades.ts";
+import {
+  ProxyColumnMismatchError,
+  positionalRow,
+  rewriteProjection,
+  type ProjectedStatement,
+} from "./sqlite-proxy-rows.ts";
+
+/** The lane name a row-shape refusal reports. */
+const LANE = "edge.sql";
+
+/** The statement, or a value in it, cannot be expressed over `edge.sql`. */
+export class EdgeSqlShapeError extends TypeError {
+  constructor(message: string) {
+    super(message);
+    this.name = "EdgeSqlShapeError";
+  }
+}
+
+/** Project one bound parameter into the facade's closed value vocabulary. */
+export function toEdgeSqlValue(value: unknown): EdgeSqlValue {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || Math.abs(value) > Number.MAX_SAFE_INTEGER) {
+      throw new EdgeSqlShapeError(
+        `edge.sql: ${value} is outside the range the facade carries`,
+      );
+    }
+    return value;
+  }
+  if (typeof value === "bigint") {
+    if (
+      value > BigInt(Number.MAX_SAFE_INTEGER) ||
+      value < BigInt(Number.MIN_SAFE_INTEGER)
+    ) {
+      throw new EdgeSqlShapeError(
+        `edge.sql: bigint ${value} is outside the safe-integer range`,
+      );
+    }
+    return Number(value);
+  }
+  if (value instanceof ArrayBuffer)
+    return encodeEdgeBytes(new Uint8Array(value));
+  if (ArrayBuffer.isView(value)) {
+    const view = value as ArrayBufferView;
+    return encodeEdgeBytes(
+      new Uint8Array(view.buffer, view.byteOffset, view.byteLength),
+    );
+  }
+  throw new EdgeSqlShapeError(
+    `edge.sql: a ${typeof value} parameter has no portable encoding`,
+  );
+}
+
+/** Turn a returned value back into what the D1 driver would have produced. */
+function fromEdgeSqlValue(value: EdgeSqlValue): unknown {
+  return isEdgeEncodedBytes(value) ? decodeEdgeBytes(value) : value;
+}
+
+function projectRows(
+  result: EdgeSqlResult,
+  projection: ProjectedStatement,
+): unknown[][] {
+  return result.rows.map((row) => {
+    const keys = Object.keys(row);
+    return positionalRow(
+      projection,
+      keys,
+      keys.map((key) => fromEdgeSqlValue(row[key]!)),
+    );
+  });
+}
+
+const TRANSACTION_CONTROL =
+  /^\s*(begin|commit|end|rollback|savepoint|release)\b/i;
+
+interface PreparedStatement {
+  readonly sql: string;
+  readonly params: readonly EdgeSqlValue[];
+  readonly projection: ProjectedStatement;
+}
+
+function prepare(sql: string, params: readonly unknown[]): PreparedStatement {
+  if (TRANSACTION_CONTROL.test(sql)) {
+    throw new EdgeSqlShapeError(
+      `edge.sql: transaction control ("${sql.trim()}") is not on this request ` +
+        `path. Use db.batch([...]) — the facade's transaction() commits it ` +
+        `all-or-none in one Host call.`,
+    );
+  }
+  if (params.length > EDGE_SQL_MAX_PARAMETERS) {
+    throw new EdgeSqlShapeError(
+      `edge.sql: ${params.length} bound parameters exceed the facade limit of ` +
+        `${EDGE_SQL_MAX_PARAMETERS}; chunk the write (see src/db/d1-write.ts)`,
+    );
+  }
+  const rewritten = rewriteProjection(sql);
+  return {
+    sql: rewritten.sql,
+    params: params.map(toEdgeSqlValue),
+    projection: { lane: LANE, sql, columns: rewritten.columns },
+  };
+}
+
+/**
+ * Every statement goes through `execute`, never `query`.
+ *
+ * `query` is `execute` with an added refusal when the statement wrote anything,
+ * and Drizzle's read methods do not mean "reads nothing": an
+ * `insert ... returning` is compiled with method `all`. Choosing the method
+ * from Drizzle's would reject a legitimate write.
+ */
+export function createEdgeSqlDatabase(binding: EdgeSqlBinding) {
+  const one = async (
+    statement: PreparedStatement,
+    method: "run" | "all" | "values" | "get",
+  ) => {
+    const result = await binding.execute(statement.sql, statement.params);
+    return shape(result, statement, method);
+  };
+
+  const callback: AsyncRemoteCallback = async (sql, params, method) =>
+    await one(prepare(sql, params), method);
+
+  const batchCallback: AsyncBatchRemoteCallback = async (batch) => {
+    if (batch.length > EDGE_SQL_MAX_STATEMENTS) {
+      throw new EdgeSqlShapeError(
+        `edge.sql: a batch of ${batch.length} statements exceeds the facade ` +
+          `limit of ${EDGE_SQL_MAX_STATEMENTS}`,
+      );
+    }
+    const prepared = batch.map((entry) => prepare(entry.sql, entry.params));
+    const results = await binding.transaction(
+      prepared.map((entry) => ({ sql: entry.sql, params: entry.params })),
+    );
+    if (results.length !== prepared.length) {
+      throw new ProxyColumnMismatchError(
+        `edge.sql: transaction returned ${results.length} results for ` +
+          `${prepared.length} statements`,
+      );
+    }
+    return results.map((result, index) =>
+      shape(result, prepared[index]!, batch[index]!.method),
+    );
+  };
+
+  return drizzleProxy(callback, batchCallback, { schema });
+}
+
+/**
+ * `sqlite-proxy` wants a flat row for `get` and an array of rows otherwise, and
+ * reads `run`'s result straight back to the caller — which is where
+ * `affectedRowCount` looks for `meta.changes`.
+ *
+ * A `get` that matched nothing must yield `undefined`, not an empty array:
+ * Drizzle's `mapGetResult` short-circuits on a falsy row, and an empty array is
+ * truthy, so `[]` would be mapped into an object whose every field is
+ * `undefined` — a "row" for a query that found none.
+ */
+function shape(
+  result: EdgeSqlResult,
+  statement: PreparedStatement,
+  method: "run" | "all" | "values" | "get",
+): { rows: unknown[]; meta: { changes: number } } {
+  const rows = projectRows(result, statement.projection);
+  return {
+    rows: (method === "get" ? rows[0] : rows) as unknown[],
+    meta: { changes: result.rowsWritten },
+  };
+}
+
+export type EdgeSqlDatabase = ReturnType<typeof createEdgeSqlDatabase>;