@takosjp/yurucommu-core 4.1.4 → 4.1.5

package/package.json

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

package/packages/api/package.json

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

package/src/backend/lib/conditional-request.ts

@@ -0,0 +1,87 @@
+/**
+ * `If-None-Match` evaluation (RFC 9110 §8.8.3, §13.1.2).
+ *
+ * Two rules from the RFC are easy to get wrong and are both pinned here.
+ *
+ * The FIELD IS A LIST, and a comma is not a separator it can be split on.
+ * `etagc` admits every VCHAR except DQUOTE, so `","` is a legal opaque-tag and
+ * `header.split(",")` would tear one in half. The scan below reads a tag at a
+ * time — an optional `W/`, an opening DQUOTE, then everything up to the next
+ * DQUOTE, which is unambiguous precisely because the tag body cannot contain
+ * one.
+ *
+ * The COMPARISON IS WEAK. §13.1.2 evaluates `If-None-Match` with the weak
+ * comparison function, so the weakness marker is ignored on both sides and only
+ * the quoted opaque-tags are compared, character for character. (The strong
+ * function is for `If-Match` and `If-Range`, where a weak validator may not be
+ * used to reassemble a representation.)
+ *
+ * A field value the grammar does not admit yields no tags at all and therefore
+ * no match: §13.1 says to ignore a condition that cannot be evaluated, which
+ * for a cache validator means serving the full representation.
+ */
+
+/**
+ * Would the client's cached copy still be valid — i.e. should the caller answer
+ * `304 Not Modified` instead of the representation?
+ *
+ * `httpEtag` must be the SAME value the response emits in `ETag`: the quoted,
+ * header-safe spelling. A bare backend etag never matches anything a client
+ * echoes back, which is the whole reason this takes the header form.
+ *
+ * Call this only once the requested representation is known to exist and the
+ * requester is known to be allowed to read it. `*` matches whenever there is a
+ * current representation, and answering 304 to someone who may not read the
+ * object would leak its existence.
+ */
+export function ifNoneMatchIsFresh(
+  header: string | undefined | null,
+  httpEtag: string | undefined,
+): boolean {
+  if (!header || !httpEtag) return false;
+  const field = header.trim();
+  // `If-None-Match = "*" / 1#entity-tag`: the wildcard is the WHOLE field, not
+  // a member of the list, and it matches because a representation exists.
+  if (field === "*") return true;
+  const target = opaqueTagOf(httpEtag);
+  if (target === null) return false;
+  return entityTags(field).includes(target);
+}
+
+/** One entity-tag reduced to its quoted opaque-tag, or `null` if malformed. */
+function opaqueTagOf(tag: string): string | null {
+  const bare = tag.startsWith("W/") ? tag.slice(2) : tag;
+  if (bare.length < 2 || !bare.startsWith('"') || !bare.endsWith('"')) {
+    return null;
+  }
+  return bare;
+}
+
+/** Every entity-tag in a list field value, or none at all if it is malformed. */
+function entityTags(field: string): string[] {
+  const tags: string[] = [];
+  let index = 0;
+  while (index < field.length) {
+    const char = field[index];
+    if (char === "," || char === " " || char === "\t") {
+      index += 1;
+      continue;
+    }
+    // The weakness marker is consumed and discarded: the weak comparison
+    // function does not distinguish `W/"x"` from `"x"`.
+    if (field.startsWith("W/", index)) index += 2;
+    if (field[index] !== '"') return [];
+    const end = field.indexOf('"', index + 1);
+    if (end === -1) return [];
+    tags.push(field.slice(index, end + 1));
+    index = end + 1;
+    while (index < field.length) {
+      const next = field[index];
+      if (next !== " " && next !== "\t") break;
+      index += 1;
+    }
+    // Nothing but a comma may follow an entity-tag.
+    if (index < field.length && field[index] !== ",") return [];
+  }
+  return tags;
+}

package/src/backend/middleware/cache.ts

@@ -15,6 +15,7 @@
 import type { Context, MiddlewareHandler, Next } from "hono";
 import type { Env, Variables } from "../types.ts";
 import { logger } from "../lib/logger.ts";
+import { ifNoneMatchIsFresh } from "../lib/conditional-request.ts";
 import { bytesToHex } from "../lib/hex.ts";
 
 const log = logger.child({ component: "middleware.cache" });
@@ -224,8 +225,11 @@ function isConditionalHit(
   etag: string | null,
   lastModified: string | null,
 ): boolean {
-  const ifNoneMatch = c.req.header("If-None-Match");
-  if (ifNoneMatch && etag && ifNoneMatch === etag) {
+  // One `If-None-Match` reading for the whole backend. String equality was not
+  // one: the field is a LIST, `W/"x"` is a match for `"x"` under §13.1.2's weak
+  // comparison, and `*` matches any existing representation. `generateETag`
+  // already emits the quoted form these are compared against.
+  if (ifNoneMatchIsFresh(c.req.header("If-None-Match"), etag ?? undefined)) {
     return true;
   }
 

package/src/backend/routes/apps.ts

@@ -282,7 +282,10 @@ appsServeRoutes.get("/:clientId/:appName/*", async (c) => {
       filePath.includes("/assets/")
         ? "public, max-age=31536000, immutable"
         : "public, max-age=3600",
-      object.etag,
+      // The quoted entity-tag, never the port's verbatim `etag`: that one is a
+      // bare hex digest on the portable lane and is not a valid `ETag` field
+      // value (RFC 9110 §8.8.3).
+      object.httpEtag,
     );
     return new Response(object.body, { headers });
   }
@@ -295,7 +298,7 @@ appsServeRoutes.get("/:clientId/:appName/*", async (c) => {
       const headers = createHostedHeaders(
         "text/html; charset=utf-8",
         "no-cache",
-        indexObject.etag,
+        indexObject.httpEtag,
       );
       return new Response(indexObject.body, { headers });
     }

package/src/backend/routes/media.ts

@@ -11,6 +11,7 @@ import {
 } from "../../db/index.ts";
 import { generateId } from "../federation-helpers.ts";
 import { canViewerReadObject } from "../lib/community-visibility.ts";
+import { ifNoneMatchIsFresh } from "../lib/conditional-request.ts";
 import { canViewerReadObjectFull } from "../lib/post-visibility.ts";
 import { stripImageMetadata } from "../lib/strip-image-metadata.ts";
 import { logger } from "../lib/logger.ts";
@@ -588,18 +589,44 @@ async function serveMediaByR2Key(c: MediaContext, r2Key: string) {
     const maxAge = contentType.startsWith("video/")
       ? CACHE_MAX_AGE_VIDEO
       : CACHE_MAX_AGE_IMAGE;
-    const etag = object.etag;
+    const cacheControl = `${cacheScope}, max-age=${maxAge}`;
+    // The HEADER form, not `object.etag`. An `ETag` field value is an
+    // entity-tag and an entity-tag's opaque-tag is always quoted (RFC 9110
+    // §8.8.3); the port's `etag` is the backend's verbatim spelling, which on
+    // the portable lane is a BARE hex digest. Serving that produced a field no
+    // cache could match and no client could echo back — media was effectively
+    // uncacheable on self-host. `httpEtag` is the quoted form on every lane.
+    const etag = object.httpEtag;
+
+    // §13.1.2 evaluates `If-None-Match` with the WEAK comparison function, so
+    // `W/"x"` from the client matches the `"x"` we sent; only the opaque-tags
+    // are compared. The validator on both sides of that comparison is the one
+    // we emitted, which is why it reads `httpEtag` and not `etag`. Reached only
+    // after the authorization gate above: `*` matches any representation that
+    // exists, so answering 304 earlier would disclose that a private object is
+    // there.
+    if (etag && ifNoneMatchIsFresh(c.req.header("If-None-Match"), etag)) {
+      // The port has no `head`, so the bytes were already fetched; a 304 must
+      // not carry them (§15.4.5), and dropping the stream unread would leak it.
+      await object.body?.cancel().catch(() => undefined);
+      // §15.4.5 also asks a 304 to carry the header fields a 200 would have
+      // sent that guide cache behaviour — here, the validator and the policy.
+      return c.body(null, 304, {
+        "Cache-Control": cacheControl,
+        ETag: etag,
+      });
+    }
 
     if (!object.body) {
       return c.body(null, 200, {
         "Content-Type": contentType,
-        "Cache-Control": `${cacheScope}, max-age=${maxAge}`,
+        "Cache-Control": cacheControl,
         ...(etag ? { ETag: etag } : {}),
       });
     }
     return c.body(object.body, 200, {
       "Content-Type": contentType,
-      "Cache-Control": `${cacheScope}, max-age=${maxAge}`,
+      "Cache-Control": cacheControl,
       ...(etag ? { ETag: etag } : {}),
     });
   } catch (error) {

package/src/backend/runtime/cloudflare.ts

@@ -56,7 +56,14 @@ class CloudflareStorage implements ObjectStore {
       key,
       body: obj.body as unknown as ReadableStream,
       contentType: obj.httpMetadata?.contentType,
+      // R2 spells the same validator twice: `etag` bare, `httpEtag` quoted.
+      // This adapter has always handed the quoted one over as the port's
+      // opaque `etag`, and that stays — narrowing a published field to R2's
+      // bare spelling would silently change what every existing reader sees.
+      // `httpEtag` names the header-safe form explicitly, which on this lane is
+      // the same string.
       etag: obj.httpEtag,
+      httpEtag: obj.httpEtag,
       byteLength: obj.size,
     };
   }

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

@@ -8,10 +8,10 @@
  * 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
+ * `R2ObjectBody` also carries `text()`, `json()`, `arrayBuffer()`, `bytes()`,
+ * `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
@@ -23,13 +23,13 @@
  *
  * 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.
+ * and on a body answer `body`, `bodyUsed`, `arrayBuffer()`, `bytes()`, `text()`,
+ * `json()`, `blob()`. The five 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 —
@@ -44,10 +44,12 @@
  *
  * `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.
+ * forwards R2's quoted `httpEtag`. This facade does not rewrite it: it is the
+ * Host's own identity for those bytes, and R2 does not rewrite its `etag`
+ * either. `httpEtag` is derived — the same value, quoted when it was not
+ * already — and THAT is the one a response emits, because a bare digest is not
+ * an entity-tag (RFC 9110 §8.8.3) and no cache can match one. The
+ * provider-neutral {@link ObjectStore} answer carries both for the same reason.
  *
  * ## The narrow spots of the facade itself, which parity does not widen
  *
@@ -90,7 +92,7 @@ import type {
   EdgeObjectMetadata,
   EdgeObjectsBinding,
 } from "./edge-facades.ts";
-import { readStream } from "./shared.ts";
+import { httpEtagOf, readStream } from "./shared.ts";
 
 /** A request or response the facade cannot express. */
 export class EdgeObjectsShapeError extends TypeError {
@@ -144,6 +146,7 @@ export interface EdgeR2ObjectBody extends EdgeR2Object {
   readonly body: ReadableStream<Uint8Array>;
   readonly bodyUsed: boolean;
   arrayBuffer(): Promise<ArrayBuffer>;
+  bytes(): Promise<Uint8Array>;
   text(): Promise<string>;
   json<T = unknown>(): Promise<T>;
   blob(): Promise<Blob>;
@@ -169,14 +172,6 @@ export interface EdgeObjectsListOptions {
   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,
@@ -279,6 +274,13 @@ class EdgeR2ObjectWithBody
     return this.#response.arrayBuffer();
   }
 
+  async bytes(): Promise<Uint8Array> {
+    // Built on `arrayBuffer()` rather than `Response.bytes()`, which this repo
+    // cannot name while type-checking against the DOM lib. It is the same read,
+    // so the once-only semantics are the same: a second call rejects.
+    return new Uint8Array(await this.#response.arrayBuffer());
+  }
+
   text(): Promise<string> {
     return this.#response.text();
   }
@@ -437,6 +439,7 @@ export class EdgeObjectStorage implements ObjectStore {
         ? {}
         : { contentType: found.httpMetadata.contentType }),
       etag: found.etag,
+      httpEtag: found.httpEtag,
       byteLength: found.size,
     };
   }

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

@@ -13,6 +13,7 @@ import {
   type ManagedRuntimeConnectionMaterialization,
 } from "@takosjp/takosumi-contract/managed-runtime-connections";
 
+import { httpEtagOf } from "./shared.ts";
 import type {
   IKeyValueStore,
   ObjectStore,
@@ -401,6 +402,16 @@ class ManagedRuntimeStorageObject implements ObjectStoreObject {
     return this.response.headers.get("etag") ?? undefined;
   }
 
+  /**
+   * The gateway forwards R2's quoted `httpEtag`, so this is normally the same
+   * string as `etag`. It is derived rather than assumed: the port's contract is
+   * that `httpEtag` is always an entity-tag a header may carry.
+   */
+  get httpEtag(): string | undefined {
+    const etag = this.etag;
+    return etag === undefined ? undefined : httpEtagOf(etag);
+  }
+
   get byteLength(): number | undefined {
     return parseContentLength(this.response.headers.get("content-length"));
   }

package/src/backend/runtime/s3-fetch.ts

@@ -1,3 +1,4 @@
+import { httpEtagOf } from "./shared.ts";
 import type {
   ObjectStore,
   ObjectStoreBody,
@@ -135,7 +136,10 @@ class S3FetchObjectStore implements ObjectStore {
           ? null
           : boundedBody(response.body, this.maxObjectBytes, "get"),
       ...(contentType === undefined ? {} : { contentType }),
-      ...(etag === undefined ? {} : { etag }),
+      // S3 answers with a quoted entity-tag, so the derivation is a no-op here
+      // — but the port promises `httpEtag` on every backend, and deriving it
+      // is what makes that true without trusting one server's spelling.
+      ...(etag === undefined ? {} : { etag, httpEtag: httpEtagOf(etag) }),
       ...(byteLength === undefined ? {} : { byteLength }),
     };
   }

package/src/backend/runtime/shared.ts

@@ -39,6 +39,28 @@ export function nowSeconds(): number {
   return Date.now() / 1000;
 }
 
+/**
+ * One backend etag in the spelling an `ETag` header may actually carry.
+ *
+ * RFC 9110 §8.8.3 defines an entity-tag as an optional `W/` marker followed by
+ * a QUOTED opaque-tag, so a bare digest is not a valid field value and no cache
+ * can match one. Backends do not agree on the spelling they hand over: R2 keeps
+ * `etag` bare and `httpEtag` quoted, the `edge.objects` self-host wrapper sends
+ * the raw hex digest, and S3 and the managed gateway forward an already-quoted
+ * one. Every object seam therefore carries the derived, header-safe form beside
+ * the verbatim one, and it is the derived form that reaches a response.
+ *
+ * A value that is already an entity-tag — quoted, weak or strong — is returned
+ * unchanged; anything else is quoted.
+ */
+export function httpEtagOf(etag: string): string {
+  const bare = etag.startsWith("W/") ? etag.slice(2) : etag;
+  if (bare.length >= 2 && bare.startsWith('"') && bare.endsWith('"')) {
+    return etag;
+  }
+  return `"${etag}"`;
+}
+
 export function hasNulByte(value: string): boolean {
   return value.includes("\0");
 }

package/src/backend/runtime/types.ts

@@ -81,7 +81,19 @@ export interface ObjectStoreObject {
   key: string;
   body: ReadableStream<Uint8Array> | null;
   contentType?: string;
+  /**
+   * The backend's etag VERBATIM, and opaque. Backends disagree on the spelling:
+   * some hand over a bare digest, others an already-quoted tag. So this is a
+   * value to compare and to store, never one to put in a header.
+   */
   etag?: string;
+  /**
+   * The same etag as an entity-tag: quoted, and safe to emit (RFC 9110 §8.8.3).
+   * Present exactly when `etag` is. This is the value a response carries in
+   * `ETag` and the value a client echoes back in `If-None-Match`, so a
+   * conditional request is evaluated against this one, not against `etag`.
+   */
+  httpEtag?: string;
   byteLength?: number;
 }