@structured-id/ui-core 4.9.0 → 4.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-id/ui-core",
-  "version": "4.9.0",
+  "version": "4.11.0",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -42,13 +42,14 @@
     "@protobuf-ts/grpcweb-transport": "^2.11.1",
     "@protobuf-ts/runtime": "^2.11.1",
     "@protobuf-ts/runtime-rpc": "^2.11.1",
-    "@structured-id/proto": "^0.8.0",
+    "@structured-id/proto": "^0.9.0",
     "@structured-world/structured-email-address-ts": "^0.0.22",
     "@structured-world/structured-public-domains": "0.0.x",
     "libphonenumber-js": "^1.13.15"
   },
   "devDependencies": {
     "@types/node": "^26",
+    "@typescript/native": "npm:typescript@^7.0.2",
     "@vitejs/plugin-vue": "^6.0.9",
     "@vue/compiler-dom": "^3.5.43",
     "@vue/devtools-api": "^8.2.1",
@@ -57,7 +58,7 @@
     "jsdom": "^30.1.2",
     "pinia": "^4.0.3",
     "prettier": "^3.9.9",
-    "typescript": "^6.0.3",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-eslint": "^8.71.1",
     "vite": "^8.3.4",
     "vitest": "^5.0.3",

package/src/composables/operationContext.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect, vi } from "vitest";
+import type { MethodInfo, RpcOptions } from "@protobuf-ts/runtime-rpc";
+import { OperationService } from "@structured-id/proto/sid/v1/common/operation";
+import {
+  OPERATION_KEY,
+  OPERATION_PERIOD,
+  encodeOperationKey,
+  isKeyed,
+  operationContext,
+} from "./operationContext";
+
+const KEYED = {
+  name: "CreateProject",
+  options: { "sid.v1.common.retry": { keyed: true } },
+} as unknown as MethodInfo;
+const CEREMONY = {
+  name: "RegisterClient",
+  options: { "sid.v1.common.retry": { ceremony: "RFC 7591 §3" } },
+} as unknown as MethodInfo;
+const READ = { name: "GetProject", options: {} } as unknown as MethodInfo;
+
+/**
+ * A chain answering the period read with `period` until `untilMs`; with
+ * `refused`, a command's response is refused while its headers, status and
+ * trailers arrive, as a non-OK gRPC answer does.
+ */
+function chain(
+  period: bigint,
+  untilMs = Date.now() + 3_600_000,
+  refused = false,
+) {
+  const sent: Array<{ method: MethodInfo; options: RpcOptions }> = [];
+  const next = vi.fn(
+    (method: MethodInfo, _input: object, options: RpcOptions) => {
+      sent.push({ method, options });
+      const read = method.name === OperationService.methods[0].name;
+      const response = read
+        ? Promise.resolve({
+            period,
+            acceptedUntil: {
+              seconds: BigInt(Math.floor(untilMs / 1000)),
+              nanos: 0,
+            },
+          })
+        : refused
+          ? Promise.reject(new Error("refused"))
+          : Promise.resolve({});
+      response.catch(() => {});
+      const status = Promise.resolve({
+        code: refused && !read ? "FAILED_PRECONDITION" : "OK",
+        detail: "",
+      });
+      return {
+        headers: Promise.resolve({ answered: "yes" }),
+        response,
+        status,
+        trailers: Promise.resolve({}),
+        then: (f: (v: unknown) => unknown, r?: (e: unknown) => unknown) =>
+          response.then(f, r),
+      } as never;
+    },
+  );
+  return { next, sent };
+}
+
+/** The options the keyed (or other) call reached the transport with. */
+async function call(
+  interceptor = operationContext(),
+  c = chain(7n),
+  method = KEYED,
+  options: RpcOptions = {},
+) {
+  const answered = interceptor.interceptUnary!(
+    c.next as never,
+    method,
+    {},
+    options,
+  );
+  await answered.response;
+  return c.sent.filter((s) => s.method.name === method.name).at(-1)!.options;
+}
+
+describe("operation context", () => {
+  // The retry rule declared on the method decides, not its idempotency
+  // level: a ceremony or a read carries no context.
+  it("names only keyed methods", () => {
+    expect(isKeyed(KEYED)).toBe(true);
+    expect(isKeyed(CEREMONY)).toBe(false);
+    expect(isKeyed(READ)).toBe(false);
+  });
+
+  // A new keyed command goes out with a fresh Structured Field String key
+  // and the period the server issued.
+  it("names a new command by a key and the server's period", async () => {
+    const meta = (await call()).meta!;
+    expect(meta[OPERATION_KEY]).toMatch(/^"[0-9a-f-]{36}"$/);
+    expect(meta[OPERATION_PERIOD]).toBe("7");
+  });
+
+  it("adds nothing to a call that is not keyed", async () => {
+    const c = chain(7n);
+    const options = await call(operationContext(), c, CEREMONY, {
+      meta: { other: "x" },
+    });
+    expect(options.meta).toEqual({ other: "x" });
+    expect(c.sent).toHaveLength(1);
+  });
+
+  // A retry of one command repeats the context it was first sent with: the
+  // server finds the recorded result only under the same key and period.
+  it("keeps the context a retrying caller passes", async () => {
+    const c = chain(9n);
+    const given = { [OPERATION_KEY]: '"mine"', [OPERATION_PERIOD]: "3" };
+    const options = await call(operationContext(), c, KEYED, { meta: given });
+    expect(options.meta).toEqual(given);
+    expect(c.sent).toHaveLength(1);
+  });
+
+  // One period serves many commands: it is read once, not per call, and
+  // concurrent first calls share that read.
+  it("reads the period once for many commands", async () => {
+    const interceptor = operationContext();
+    const c = chain(7n);
+    await Promise.all([call(interceptor, c), call(interceptor, c)]);
+    await call(interceptor, c);
+    const reads = c.sent.filter(
+      (s) => s.method.name === OperationService.methods[0].name,
+    );
+    expect(reads).toHaveLength(1);
+  });
+
+  // A period about to stop being admitted is replaced before a new command
+  // is named with it.
+  it("reads a new period when the current one is about to expire", async () => {
+    const interceptor = operationContext();
+    const c = chain(7n, Date.now() + 1_000);
+    await call(interceptor, c);
+    await call(interceptor, c);
+    const reads = c.sent.filter(
+      (s) => s.method.name === OperationService.methods[0].name,
+    );
+    expect(reads).toHaveLength(2);
+  });
+
+  // The period read is not itself a keyed command.
+  it("sends the period read without the call's key", async () => {
+    const c = chain(7n);
+    await call(operationContext(), c, KEYED, {
+      meta: { [OPERATION_KEY]: '"mine"', other: "x" },
+    });
+    const read = c.sent.find(
+      (s) => s.method.name === OperationService.methods[0].name,
+    )!;
+    expect(read.options.meta).toEqual({ other: "x" });
+  });
+
+  it("gives every command its own key", async () => {
+    const interceptor = operationContext();
+    const c = chain(7n);
+    const a = (await call(interceptor, c)).meta![OPERATION_KEY];
+    const b = (await call(interceptor, c)).meta![OPERATION_KEY];
+    expect(a).not.toBe(b);
+  });
+
+  // A caller keeping the call's request headers retries the same command:
+  // they hold the key and the period the command was actually sent with.
+  it("shows the context it sent in the call's request headers", async () => {
+    const c = chain(7n);
+    const answered = operationContext().interceptUnary!(
+      c.next as never,
+      KEYED,
+      {},
+      {},
+    );
+    await answered.response;
+    const sent = c.sent.find((s) => s.method.name === KEYED.name)!.options;
+    expect(answered.requestHeaders[OPERATION_KEY]).toBe(
+      sent.meta![OPERATION_KEY],
+    );
+    expect(answered.requestHeaders[OPERATION_PERIOD]).toBe("7");
+  });
+
+  // A refused command still has its own headers, status and trailers: the
+  // wrapper forwards each, rather than failing them all with the response.
+  it("keeps a refused command's status and headers", async () => {
+    const answered = operationContext().interceptUnary!(
+      chain(7n, undefined, true).next as never,
+      KEYED,
+      {},
+      {},
+    );
+    await expect(answered.response).rejects.toThrow("refused");
+    expect((await answered.status).code).toBe("FAILED_PRECONDITION");
+    expect(await answered.headers).toEqual({ answered: "yes" });
+  });
+
+  // The period read is shared by concurrent commands: one caller's
+  // cancellation or deadline is not passed to it, so the others go on.
+  it("does not give the shared period read one caller's cancellation", async () => {
+    const interceptor = operationContext();
+    const c = chain(7n);
+    const cancelled = new AbortController();
+    const first = interceptor.interceptUnary!(
+      c.next as never,
+      KEYED,
+      {},
+      {
+        abort: cancelled.signal,
+        timeout: 5,
+      },
+    );
+    const second = interceptor.interceptUnary!(c.next as never, KEYED, {}, {});
+    cancelled.abort();
+    await second.response;
+    first.response.catch(() => {});
+    const read = c.sent.find(
+      (s) => s.method.name === OperationService.methods[0].name,
+    )!;
+    expect(read.options.abort).toBeUndefined();
+    // Its own deadline, not the first caller's.
+    expect(read.options.timeout).not.toBe(5);
+  });
+
+  // A period read that stalls does not hold a caller past its own
+  // cancellation or deadline, and the shared read has a deadline of its own.
+  it("ends a caller's wait for the period at its own cancellation or deadline", async () => {
+    const sent: RpcOptions[] = [];
+    const stalled = vi.fn((_m: MethodInfo, _i: object, options: RpcOptions) => {
+      sent.push(options);
+      const never = new Promise<never>(() => {});
+      return {
+        headers: never,
+        response: never,
+        status: never,
+        trailers: never,
+      } as never;
+    });
+    const interceptor = operationContext();
+    const cancelled = new AbortController();
+    const aborted = interceptor.interceptUnary!(
+      stalled as never,
+      KEYED,
+      {},
+      {
+        abort: cancelled.signal,
+      },
+    );
+    cancelled.abort();
+    await expect(aborted.response).rejects.toMatchObject({ code: "CANCELLED" });
+
+    const late = interceptor.interceptUnary!(
+      stalled as never,
+      KEYED,
+      {},
+      {
+        timeout: 5,
+      },
+    );
+    await expect(late.response).rejects.toMatchObject({
+      code: "DEADLINE_EXCEEDED",
+    });
+    expect(typeof sent[0].timeout).toBe("number");
+  });
+
+  // RFC 9651 §3.3.3: a String escapes DQUOTE and backslash and holds
+  // printable ASCII only.
+  it("encodes a key as a Structured Field String", () => {
+    expect(encodeOperationKey('a"b\\c')).toBe('"a\\"b\\\\c"');
+    expect(() => encodeOperationKey("é")).toThrow(RangeError);
+    expect(() => encodeOperationKey("")).toThrow(RangeError);
+  });
+});

package/src/composables/operationContext.ts

@@ -0,0 +1,202 @@
+/**
+ * The operation context of keyed calls: SID answers a retried command with
+ * its recorded result only when the call names it by a key the caller
+ * created before sending it and the server-issued period it was created
+ * under. Which methods are keyed is the method's own retry rule.
+ */
+import {
+  RpcError,
+  UnaryCall,
+  type MethodInfo,
+  type RpcInterceptor,
+  type RpcMetadata,
+} from "@protobuf-ts/runtime-rpc";
+import {
+  GetOperationPeriodRequest,
+  OperationService,
+  type OperationPeriod,
+} from "@structured-id/proto/sid/v1/common/operation";
+
+/** The metadata entry carrying the key (the `Idempotency-Key` header). */
+export const OPERATION_KEY = "idempotency-key";
+
+/** The metadata entry carrying the period (the `SID-Operation-Period` header). */
+export const OPERATION_PERIOD = "sid-operation-period";
+
+/** The method option holding a method's retry rule. */
+const RETRY_RULE = "sid.v1.common.retry";
+
+/** A period is fetched again this long before the server stops admitting it. */
+const PERIOD_MARGIN_MS = 60_000;
+
+/** The shared period read's own deadline: a stalled read is not kept. */
+const PERIOD_READ_TIMEOUT_MS = 10_000;
+
+/**
+ * `waited`, ended by the caller's own cancellation or deadline as a call
+ * would end: CANCELLED or DEADLINE_EXCEEDED.
+ */
+function within<T>(
+  waited: Promise<T>,
+  abort: AbortSignal | undefined,
+  deadline: Date | undefined,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const cancelled = () =>
+      reject(new RpcError("the call was cancelled", "CANCELLED"));
+    if (abort?.aborted) {
+      cancelled();
+      return;
+    }
+    abort?.addEventListener("abort", cancelled, { once: true });
+    const timer =
+      deadline === undefined
+        ? undefined
+        : setTimeout(
+            () =>
+              reject(
+                new RpcError("the call's deadline passed", "DEADLINE_EXCEEDED"),
+              ),
+            Math.max(0, deadline.getTime() - Date.now()),
+          );
+    const settle = () => {
+      abort?.removeEventListener("abort", cancelled);
+      clearTimeout(timer);
+    };
+    waited.then(
+      (value) => {
+        settle();
+        resolve(value);
+      },
+      (error: unknown) => {
+        settle();
+        reject(error);
+      },
+    );
+  });
+}
+
+/** Whether `method` takes an operation context: its retry rule says keyed. */
+export function isKeyed(method: MethodInfo): boolean {
+  const rule = (method.options as Record<string, unknown> | undefined)?.[
+    RETRY_RULE
+  ] as { keyed?: boolean } | undefined;
+  return rule?.keyed === true;
+}
+
+/**
+ * `key` as the header value: a Structured Field String (RFC 9651 §3.3.3,
+ * required by draft-ietf-httpapi-idempotency-key-header-08 §2.1), the same
+ * encoded value in gRPC metadata and HTTP.
+ */
+export function encodeOperationKey(key: string): string {
+  // RFC 9651 §3.3.3: a String holds printable ASCII only.
+  if (!/^[\x20-\x7e]+$/.test(key)) {
+    throw new RangeError("an operation key is printable ASCII");
+  }
+  return `"${key.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
+}
+
+/**
+ * An interceptor naming every new keyed command by a fresh key and the
+ * current period; other calls pass untouched. A caller retrying one command
+ * passes the key and period it first sent, and they are kept. The period is
+ * read from the server the calls go to, once, and again only when it is
+ * about to stop being admitted.
+ */
+export function operationContext(): RpcInterceptor {
+  let current: { period: string; until: number } | null = null;
+  let pending: Promise<string> | null = null;
+
+  function period(fetch: () => Promise<OperationPeriod>): Promise<string> {
+    if (current && Date.now() < current.until) {
+      return Promise.resolve(current.period);
+    }
+    // Concurrent first calls share one read.
+    pending ??= fetch()
+      .then((answer) => {
+        const until = answer.acceptedUntil
+          ? Number(answer.acceptedUntil.seconds) * 1000 +
+            Math.floor(answer.acceptedUntil.nanos / 1e6)
+          : 0;
+        current = {
+          period: answer.period.toString(),
+          until: until - PERIOD_MARGIN_MS,
+        };
+        return current.period;
+      })
+      .finally(() => {
+        pending = null;
+      });
+    return pending;
+  }
+
+  return {
+    interceptUnary(next, method, input, options) {
+      if (!isKeyed(method)) {
+        return next(method, input, options);
+      }
+      const meta = options.meta ?? {};
+      // The headers the command is sent with; the call shows them, so a
+      // caller keeping them retries the same command.
+      const sent: RpcMetadata = {
+        ...meta,
+        [OPERATION_KEY]:
+          meta[OPERATION_KEY] ?? encodeOperationKey(crypto.randomUUID()),
+      };
+      const given = meta[OPERATION_PERIOD];
+      if (typeof given === "string") {
+        return next(method, input, { ...options, meta: sent });
+      }
+      // The period read goes through the same chain, without this call's
+      // context, and is shared by concurrent commands: no one caller's
+      // cancellation or deadline is given to it, it has its own.
+      const plain: RpcMetadata = { ...meta };
+      delete plain[OPERATION_KEY];
+      const { abort, timeout, ...shared } = options;
+      // The caller's deadline covers the wait for the period and the
+      // command together.
+      const deadline =
+        typeof timeout === "number" ? new Date(Date.now() + timeout) : timeout;
+      // The underlying call is held in a box: a UnaryCall is thenable, and
+      // a promise resolving to it would wait for its whole response.
+      const call = within(
+        period(
+          () =>
+            next(
+              OperationService.methods[0] as MethodInfo,
+              GetOperationPeriodRequest.create(),
+              { ...shared, meta: plain, timeout: PERIOD_READ_TIMEOUT_MS },
+            ).response as Promise<OperationPeriod>,
+        ),
+        abort,
+        deadline,
+      ).then((p) => {
+        sent[OPERATION_PERIOD] = p;
+        return {
+          inner: next(method, input, {
+            ...options,
+            timeout: deadline,
+            meta: sent,
+          }),
+        };
+      });
+      // A caller awaits only the parts it needs; a failed period read fails
+      // each part without an unhandled rejection, as the transport's own do.
+      const part = <T>(pick: (c: Awaited<typeof call>) => Promise<T>) => {
+        const promise = call.then(pick);
+        promise.catch(() => {});
+        return promise;
+      };
+      return new UnaryCall(
+        method,
+        sent,
+        input,
+        part((c) => c.inner.headers),
+        part((c) => c.inner.response),
+        part((c) => c.inner.status),
+        part((c) => c.inner.trailers),
+      );
+    },
+  };
+}

package/src/composables/useAccountTransport.ts

@@ -10,6 +10,7 @@
 import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
 import type { RpcInterceptor, RpcTransport } from "@protobuf-ts/runtime-rpc";
 import { bffCsrfToken } from "./useBffAuth";
+import { operationContext } from "./operationContext";
 
 /** Where the account API is reached. */
 export interface AccountApiConfig {
@@ -49,7 +50,8 @@ export function initAccountApi(config: AccountApiConfig): void {
     baseUrl: config.baseUrl,
     // The BFF is on this origin; its cookie must not travel anywhere else.
     fetchInit: { credentials: "same-origin" },
-    interceptors: [csrf],
+    // The period read passes the CSRF interceptor too: it is the next link.
+    interceptors: [csrf, operationContext()],
   });
 }
 

package/src/composables/useGrpc.test.ts

@@ -28,7 +28,7 @@ describe("useGrpc", () => {
 
   describe("initGrpc", () => {
     // The BFF session cookie rides on every call, so credentials are always
-    // included; nothing else configures the transport.
+    // included; keyed calls carry an operation context.
     it("creates GrpcWebFetchTransport with baseUrl and credentials", () => {
       const config: GrpcConfig = { baseUrl: "https://api.sid.example.com" };
       initGrpc(config);
@@ -36,6 +36,9 @@ describe("useGrpc", () => {
       expect(GrpcWebFetchTransport).toHaveBeenCalledWith({
         baseUrl: "https://api.sid.example.com",
         fetchInit: { credentials: "include" },
+        interceptors: [
+          expect.objectContaining({ interceptUnary: expect.any(Function) }),
+        ],
       });
     });
   });

package/src/composables/useGrpc.ts

@@ -2,6 +2,7 @@ import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
 import type { RpcTransport } from "@protobuf-ts/runtime-rpc";
 import { ref, type Ref } from "vue";
 import type { GrpcConfig } from "../types/auth";
+import { operationContext } from "./operationContext";
 
 /** Shared gRPC-web transport instance. */
 let _transport: RpcTransport | null = null;
@@ -23,6 +24,7 @@ export function initGrpc(config: GrpcConfig): void {
     // The BFF proxy exchanges the session cookie for a Bearer token
     // server-side.
     fetchInit: { credentials: "include" },
+    interceptors: [operationContext()],
   });
 }