@structured-id/ui-core 4.9.0 → 4.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-id/ui-core",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "type": "module",
   "publishConfig": {
     "access": "public",

package/src/composables/operationKey.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi } from "vitest";
+import type { MethodInfo, RpcOptions } from "@protobuf-ts/runtime-rpc";
+import { OPERATION_KEY, operationKey } from "./operationKey";
+
+/** The options a unary call reaches the transport with. */
+function sent(
+  idempotency: MethodInfo["idempotency"],
+  options: RpcOptions = {},
+) {
+  const next = vi.fn((_m, _i, o: RpcOptions) => o);
+  const method = { idempotency } as unknown as MethodInfo;
+  operationKey.interceptUnary!(next as never, method, {}, options);
+  return next.mock.calls[0][2] as RpcOptions;
+}
+
+describe("operationKey", () => {
+  // A state-changing call is named by a key, so SID can answer its retry
+  // with the recorded result instead of applying it again.
+  it("adds a key to a call that changes state", () => {
+    expect(sent(undefined).meta?.[OPERATION_KEY]).toMatch(/^[0-9a-f-]{36}$/);
+    expect(sent("IDEMPOTENT").meta?.[OPERATION_KEY]).toMatch(/^[0-9a-f-]{36}$/);
+  });
+
+  it("adds no key to a read", () => {
+    expect(sent("NO_SIDE_EFFECTS").meta?.[OPERATION_KEY]).toBeUndefined();
+  });
+
+  // A caller retrying one command passes the same key every time.
+  it("keeps a key the caller passed", () => {
+    const options = { meta: { [OPERATION_KEY]: "mine", other: "x" } };
+    expect(sent(undefined, options).meta).toEqual(options.meta);
+  });
+
+  it("gives every call its own key", () => {
+    expect(sent(undefined).meta?.[OPERATION_KEY]).not.toBe(
+      sent(undefined).meta?.[OPERATION_KEY],
+    );
+  });
+});

package/src/composables/operationKey.ts

@@ -0,0 +1,40 @@
+/**
+ * The operation key of state-changing 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.
+ */
+import type { RpcInterceptor, RpcOptions } from "@protobuf-ts/runtime-rpc";
+
+/** The metadata entry carrying the key (the `Idempotency-Key` header). */
+export const OPERATION_KEY = "idempotency-key";
+
+/**
+ * `options` with an operation key: the caller's own when it passed one (a
+ * caller retrying one command passes the same key every time), a new one
+ * otherwise.
+ */
+export function withOperationKey(options: RpcOptions): RpcOptions {
+  if (options.meta?.[OPERATION_KEY]) {
+    return options;
+  }
+  return {
+    ...options,
+    meta: { ...options.meta, [OPERATION_KEY]: crypto.randomUUID() },
+  };
+}
+
+/**
+ * Adds an operation key to every unary call of a method not declared free of
+ * side effects; reads carry none.
+ */
+export const operationKey: RpcInterceptor = {
+  interceptUnary(next, method, input, options) {
+    return next(
+      method,
+      input,
+      method.idempotency === "NO_SIDE_EFFECTS"
+        ? options
+        : withOperationKey(options),
+    );
+  },
+};

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 { operationKey } from "./operationKey";
 
 /** Where the account API is reached. */
 export interface AccountApiConfig {
@@ -49,7 +50,7 @@ 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],
+    interceptors: [csrf, operationKey],
   });
 }
 

package/src/composables/useGrpc.test.ts

@@ -14,6 +14,7 @@ vi.mock("@protobuf-ts/grpcweb-transport", () => ({
 // Import AFTER mocks
 import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
 import { initGrpc, getTransport, closeTransport, useGrpc } from "./useGrpc";
+import { operationKey } from "./operationKey";
 import type { GrpcConfig } from "../types/auth";
 
 // ---------------------------------------------------------------------------
@@ -28,7 +29,7 @@ describe("useGrpc", () => {
 
   describe("initGrpc", () => {
     // The BFF session cookie rides on every call, so credentials are always
-    // included; nothing else configures the transport.
+    // included; state-changing calls carry an operation key.
     it("creates GrpcWebFetchTransport with baseUrl and credentials", () => {
       const config: GrpcConfig = { baseUrl: "https://api.sid.example.com" };
       initGrpc(config);
@@ -36,6 +37,7 @@ describe("useGrpc", () => {
       expect(GrpcWebFetchTransport).toHaveBeenCalledWith({
         baseUrl: "https://api.sid.example.com",
         fetchInit: { credentials: "include" },
+        interceptors: [operationKey],
       });
     });
   });

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 { operationKey } from "./operationKey";
 
 /** 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: [operationKey],
   });
 }