@nifrajs/core 2.13.0 → 3.1.0

package/src/binary.ts

@@ -34,6 +34,23 @@ export const NIFRA_BINARY_HEADER = "x-nifra-binary"
 /** A `Response` a route declared as binary. `Jsonify` maps this to `Blob`. */
 export type BinaryResponse = Response & { readonly [NIFRA_BYTES]: true }
 
+/**
+ * Marker on a raw response's TYPE carrying the payload it serializes to. Like {@link NIFRA_BYTES} it is
+ * a unique symbol declared *required*, so an ordinary `Response` cannot satisfy it by accident - an
+ * optional brand would be met by every `Response`, and every raw-response route would wrongly claim a
+ * typed body.
+ */
+declare const NIFRA_RAW: unique symbol
+
+/**
+ * A raw `Response` whose JSON body a route declared as `T`. Returning a bare `Response` drops a route
+ * out of the typed contract - the client reads its `data` as `never`, since a `Response`'s own
+ * properties say nothing about the payload. {@link raw} brands the `Response` with the shape it
+ * actually serializes, so `Jsonify` answers `Jsonify<T>` and the route stays inside the typed client.
+ * The brand is a phantom: nothing is added at runtime.
+ */
+export type RawResponse<T> = Response & { readonly [NIFRA_RAW]: T }
+
 /** What can be sent as bytes without being re-encoded on the way out. */
 export type BinaryBody = ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array>
 
@@ -126,3 +143,21 @@ export function bytes(body: BinaryBody, options: BytesOptions = {}): BinaryRespo
     headers,
   }) as BinaryResponse
 }
+
+/**
+ * Brand a hand-built `Response` with the payload type `T` its body serializes to, so a route that must
+ * return a `Response` directly still types `res.data` as `Jsonify<T>` on the client instead of `never`.
+ * Use it for the endpoints that build their own `Response` - a token minted by a third-party SDK, a
+ * redirect that also carries a JSON body, a hand-tuned cache header - but should still be part of the
+ * contract. Purely a type assertion: the `Response` is returned unchanged, nothing is added at runtime.
+ *
+ *     app.get("/livekit-token", async (c) =>
+ *       raw<{ token: string }>(Response.json({ token: await mint(c) })))
+ *     // client: res.data is typed { token: string }
+ *
+ * The payload `T` is the type the body serializes to - it is not validated, so it is a promise the route
+ * must keep. For bytes prefer {@link bytes}, which also sets the media-type headers.
+ */
+export function raw<T>(response: Response): RawResponse<T> {
+  return response as RawResponse<T>
+}

package/src/durable-adapters.ts

@@ -13,6 +13,9 @@ import type {
   SagaRecord,
   SagaStore,
 } from "./durable-execution.ts"
+import { durableApprovalProtocol } from "./internal/durable-approval-protocol.ts"
+import { durableEffectProtocol } from "./internal/durable-effect-protocol.ts"
+import { durableSagaProtocol } from "./internal/durable-saga-protocol.ts"
 import { safeEqual } from "./internal/safe-equal.ts"
 import type { ReconciliationLease, ReconciliationLeaseStore } from "./reconciliation-worker.ts"
 import { parse as parseWire, stringify as stringifyWire } from "./wire.ts"
@@ -93,20 +96,8 @@ export function createDurableExecutionAdapter(
     get: (effectId) => backend.get<DurableEffectRecord>("effect", effectId),
     async transition(input) {
       const current = await backend.get<DurableEffectRecord>("effect", input.effectId)
-      if (
-        current === undefined ||
-        current.version !== input.version ||
-        current.state !== input.from
-      ) {
-        return false
-      }
-      const next: DurableEffectRecord = {
-        ...current,
-        state: input.to,
-        updatedAt: input.updatedAt,
-        version: current.version + 1,
-        ...(input.errorCode === undefined ? {} : { errorCode: input.errorCode }),
-      }
+      const next = durableEffectProtocol.transition(current, input)
+      if (next === undefined) return false
       return await backend.compareAndSet("effect", input.effectId, input.version, next)
     },
     scan: (input) =>
@@ -119,46 +110,26 @@ export function createDurableExecutionAdapter(
     get: (approvalId) => backend.get<ApprovalRecord>("approval", approvalId),
     async decide(input) {
       const current = await backend.get<ApprovalRecord>("approval", input.approvalId)
-      if (
-        current === undefined ||
-        current.tenantId !== input.tenantId ||
-        current.state !== "pending" ||
-        current.expiresAt <= input.now
-      ) {
-        return false
-      }
-      const decided: ApprovalRecord = {
-        ...current,
-        state: input.decision,
-        decidedBy: input.decidedBy,
-        updatedAt: input.now,
-        version: current.version + 1,
-      }
-      return await backend.compareAndSet("approval", input.approvalId, current.version, decided)
+      const next = durableApprovalProtocol.decide(current, input)
+      if (current === undefined || next === undefined) return false
+      return await backend.compareAndSet("approval", input.approvalId, current.version, next)
     },
     async consume(input): Promise<ApprovalConsumeResult> {
       const current = await backend.get<ApprovalRecord>("approval", input.approvalId)
-      if (current === undefined) return { state: "missing" }
-      if (current.tenantId !== input.tenantId || current.principalId !== input.principalId)
-        return { state: "binding" }
+      const transition = durableApprovalProtocol.consume(current, input)
       if (
-        current.capability !== input.capability ||
-        current.target !== input.target ||
-        !safeEqual(current.digest, input.digest)
+        current === undefined ||
+        transition.result.state !== "consumed" ||
+        transition.next === undefined
       )
-        return { state: "binding" }
-      if (!safeEqual(current.tokenHash, input.tokenHash)) return { state: "token" }
-      if (current.state === "consumed") return { state: "replay" }
-      if (current.state === "denied") return { state: "denied" }
-      if (current.state === "pending") return { state: "pending" }
-      if (current.state === "expired" || current.expiresAt <= input.now) return { state: "expired" }
-      const consumed = await backend.compareAndSet("approval", input.approvalId, current.version, {
-        ...current,
-        state: "consumed",
-        updatedAt: input.now,
-        version: current.version + 1,
-      })
-      return consumed ? { state: "consumed" } : { state: "replay" }
+        return transition.result
+      const consumed = await backend.compareAndSet(
+        "approval",
+        input.approvalId,
+        current.version,
+        transition.next,
+      )
+      return consumed ? transition.result : { state: "replay" }
     },
   }
 
@@ -166,8 +137,12 @@ export function createDurableExecutionAdapter(
     durability: "durable",
     create: (record) => backend.create("saga", record.sagaId, clone(record)),
     get: (sagaId) => backend.get<SagaRecord>("saga", sagaId),
-    compareAndSet: (input) =>
-      backend.compareAndSet("saga", input.sagaId, input.version, clone(input.record)),
+    compareAndSet: (input) => {
+      const next = durableSagaProtocol.transition(undefined, input)
+      return next === undefined
+        ? false
+        : backend.compareAndSet("saga", input.sagaId, input.version, clone(next))
+    },
     scan: (input) => backend.scan<SagaRecord>("saga", input as ReconciliationScanOptions<string>),
   }
 

package/src/durable-execution.ts

@@ -13,7 +13,9 @@ import type {
   CapabilityExecutionJournal,
 } from "./internal/capability-runtime.ts"
 import { validCapabilityId } from "./internal/capability-runtime.ts"
-import { safeEqual } from "./internal/safe-equal.ts"
+import { durableApprovalProtocol } from "./internal/durable-approval-protocol.ts"
+import { durableEffectProtocol } from "./internal/durable-effect-protocol.ts"
+import { durableSagaProtocol } from "./internal/durable-saga-protocol.ts"
 
 export type { CapabilityApprovalGate, CapabilityExecutionIdentity, CapabilityExecutionJournal }
 
@@ -208,8 +210,7 @@ export function createDurableEffectJournal(
     errorCode?: string,
   ): Promise<void> => {
     const record = await current(effectId)
-    if (record.state !== from) throw new DurableEffectTransitionError(effectId, `${from}->${to}`)
-    const accepted = await options.store.transition({
+    const next = durableEffectProtocol.transition(record, {
       effectId,
       version: record.version,
       from,
@@ -217,6 +218,15 @@ export function createDurableEffectJournal(
       updatedAt: now(),
       ...(errorCode === undefined ? {} : { errorCode }),
     })
+    if (next === undefined) throw new DurableEffectTransitionError(effectId, `${from}->${to}`)
+    const accepted = await options.store.transition({
+      effectId,
+      version: record.version,
+      from,
+      to,
+      updatedAt: next.updatedAt,
+      ...(errorCode === undefined ? {} : { errorCode }),
+    })
     if (!accepted) throw new DurableEffectTransitionError(effectId, `${from}->${to}`)
   }
 
@@ -261,7 +271,7 @@ export function createDurableEffectJournal(
         throw new TypeError("durable effect errorCode is invalid")
       const record = await current(effectId)
       const to = input.began ? "unknown" : "failed"
-      const accepted = await options.store.transition({
+      const next = durableEffectProtocol.transition(record, {
         effectId,
         version: record.version,
         from: record.state,
@@ -269,6 +279,16 @@ export function createDurableEffectJournal(
         updatedAt: now(),
         errorCode: input.errorCode,
       })
+      if (next === undefined)
+        throw new DurableEffectTransitionError(effectId, `${record.state}->${to}`)
+      const accepted = await options.store.transition({
+        effectId,
+        version: record.version,
+        from: record.state,
+        to,
+        updatedAt: next.updatedAt,
+        errorCode: input.errorCode,
+      })
       if (!accepted) throw new DurableEffectTransitionError(effectId, `${record.state}->${to}`)
     },
   }
@@ -296,18 +316,10 @@ export class MemoryDurableEffectStore implements DurableEffectStore {
 
   transition(input: Parameters<DurableEffectStore["transition"]>[0]): boolean {
     const current = this.records.get(input.effectId)
-    if (current === undefined || current.version !== input.version || current.state !== input.from)
-      return false
-    this.records.set(
-      input.effectId,
-      Object.freeze({
-        ...current,
-        state: input.to,
-        updatedAt: input.updatedAt,
-        version: current.version + 1,
-        ...(input.errorCode === undefined ? {} : { errorCode: input.errorCode }),
-      }),
-    )
+    const next = durableEffectProtocol.transition(current, input)
+    if (next === undefined) return false
+    if (current === undefined) return false
+    this.records.set(input.effectId, Object.freeze(next))
     bucketMove(this.byState, current.state, input.to, input.effectId)
     return true
   }
@@ -801,64 +813,17 @@ export class MemoryApprovalStore implements ApprovalStore {
   }
   decide(input: Parameters<ApprovalStore["decide"]>[0]): boolean {
     const record = this.records.get(input.approvalId)
-    if (
-      record === undefined ||
-      record.tenantId !== input.tenantId ||
-      record.state !== "pending" ||
-      record.expiresAt <= input.now
-    )
-      return false
-    this.records.set(
-      input.approvalId,
-      Object.freeze({
-        ...record,
-        state: input.decision,
-        decidedBy: input.decidedBy,
-        updatedAt: input.now,
-        version: record.version + 1,
-      }),
-    )
+    const next = durableApprovalProtocol.decide(record, input)
+    if (next === undefined) return false
+    this.records.set(input.approvalId, Object.freeze(next))
     return true
   }
   consume(input: Parameters<ApprovalStore["consume"]>[0]): ApprovalConsumeResult {
     const record = this.records.get(input.approvalId)
-    if (record === undefined) return { state: "missing" }
-    if (
-      record.tenantId !== input.tenantId ||
-      record.principalId !== input.principalId ||
-      record.capability !== input.capability ||
-      record.target !== input.target ||
-      !safeEqual(record.digest, input.digest)
-    )
-      return { state: "binding" }
-    if (!safeEqual(record.tokenHash, input.tokenHash)) return { state: "token" }
-    if (record.state === "consumed") return { state: "replay" }
-    if (record.expiresAt <= input.now || record.state === "expired") {
-      if (record.state !== "expired")
-        this.records.set(
-          input.approvalId,
-          Object.freeze({
-            ...record,
-            state: "expired",
-            updatedAt: input.now,
-            version: record.version + 1,
-          }),
-        )
-      return { state: "expired" }
-    }
-    if (record.state === "pending") return { state: "pending" }
-    if (record.state === "denied") return { state: "denied" }
-    if (record.state !== "approved") return { state: "token" }
-    this.records.set(
-      input.approvalId,
-      Object.freeze({
-        ...record,
-        state: "consumed",
-        updatedAt: input.now,
-        version: record.version + 1,
-      }),
-    )
-    return { state: "consumed" }
+    const transition = durableApprovalProtocol.consume(record, input)
+    if (transition.next !== undefined)
+      this.records.set(input.approvalId, Object.freeze(transition.next))
+    return transition.result
   }
   list(): readonly ApprovalRecord[] {
     return Object.freeze(
@@ -1174,7 +1139,12 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     current: SagaRecord,
     update: Omit<SagaRecord, "version">,
   ): Promise<SagaRecord> => {
-    const next = Object.freeze({ ...update, version: current.version + 1 })
+    const next = durableSagaProtocol.transition(current, {
+      sagaId: current.sagaId,
+      version: current.version,
+      record: Object.freeze({ ...update, version: current.version + 1 }),
+    })
+    if (next === undefined) throw new SagaConcurrencyError(current.sagaId)
     if (
       !(await options.store.compareAndSet({
         sagaId: current.sagaId,
@@ -1190,16 +1160,7 @@ export function createSagaEngine(options: SagaEngineOptions): SagaEngine {
     index: number,
     step: SagaStepRecord,
     state = record.state,
-  ): Omit<SagaRecord, "version"> => ({
-    ...record,
-    state,
-    steps: Object.freeze(
-      record.steps.map((candidate, candidateIndex) =>
-        candidateIndex === index ? Object.freeze(step) : candidate,
-      ),
-    ),
-    updatedAt: now(),
-  })
+  ): Omit<SagaRecord, "version"> => durableSagaProtocol.withStep(record, index, step, state, now())
   const effectScope = createEffectScope({
     ...(observer === undefined ? {} : { observers: [observer] }),
   })
@@ -1569,13 +1530,10 @@ export class MemorySagaStore implements SagaStore {
   }
   compareAndSet(input: Parameters<SagaStore["compareAndSet"]>[0]): boolean {
     const current = this.records.get(input.sagaId)
-    if (
-      current === undefined ||
-      current.version !== input.version ||
-      input.record.version !== input.version + 1
-    )
-      return false
-    this.records.set(input.sagaId, Object.freeze(cloneValue(input.record)))
+    const next = durableSagaProtocol.transition(current, input)
+    if (next === undefined) return false
+    if (current === undefined) return false
+    this.records.set(input.sagaId, Object.freeze(next))
     bucketMove(this.byState, current.state, input.record.state, input.sagaId)
     return true
   }

package/src/edge-kit.ts

@@ -0,0 +1,27 @@
+/**
+ * Edge kit - the moat-neutral free functions a compact fetch-handler server needs to enforce the
+ * SAME request trust boundary the full `Server` does, without pulling in the full builder.
+ *
+ * A minimal edge entrypoint (`@nifrajs/edge`) is not allowed to re-derive the body lane: the assembly
+ * order of the content-type dispatch, the bounded read, the Content-Length pre-reject, and the
+ * prototype-poisoning guard is a security contract, and a second copy of it would drift. This subpath
+ * exposes the one lane the fused body runner already calls, so a compact server reuses it verbatim:
+ *
+ *   - {@link readBodyFramed}   read + cap + proto-guard + content-type framing (JSON / urlencoded / 415)
+ *   - {@link toResponse}       render a {@link ResponseResult} (e.g. a 413 / 415 rejection) to a `Response`
+ *   - {@link plainError}       the structured rejection envelope the lane returns
+ *   - {@link queryObjectOf} / {@link searchOf}   query parse without a full WHATWG URL construction
+ *
+ * Everything here carries only structure - bytes, guards, and envelopes - never routing, lifecycle,
+ * or app state. It is the interface, not the framework.
+ */
+
+export { plainError } from "./server/http.ts"
+export type { ProtoPoisoning } from "./server/proto-guard.ts"
+export { type QueryValue, queryObjectOf, searchOf } from "./server/query.ts"
+export { readBodyFramed } from "./server/request-context.ts"
+export { toResponse } from "./server/respond.ts"
+export type { ResponseResult } from "./server/runtime-core.ts"
+export { EMPTY_RESPONSE_CONTROLS } from "./server/runtime-core.ts"
+export type { CtxSet, MaybePromise, RequestSource } from "./server/server.ts"
+export { plainValidationError } from "./server/server.ts"

package/src/errors.ts

@@ -26,6 +26,7 @@ export type RouteConfigErrorCode =
   | "INVALID_METHOD"
   | "INVALID_ASSURANCE"
   | "INVALID_IDEMPOTENCY"
+  | "INVALID_WS_SEND_VALIDATION"
   | "INVALID_BODY_LIMIT"
 
 /**

package/src/index.ts

@@ -10,7 +10,7 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "2.13.0" as const
+export const VERSION = "3.1.0" as const
 
 export type Version = typeof VERSION
 

package/src/internal/durable-approval-protocol.ts

@@ -0,0 +1,92 @@
+import type { ApprovalConsumeResult, ApprovalRecord, ApprovalStore } from "../durable-execution.ts"
+import { safeEqual } from "./safe-equal.ts"
+
+export type DurableApprovalDecisionInput = Parameters<ApprovalStore["decide"]>[0]
+export type DurableApprovalConsumeInput = Parameters<ApprovalStore["consume"]>[0]
+
+export interface DurableApprovalConsumeTransition {
+  readonly result: ApprovalConsumeResult
+  readonly next?: ApprovalRecord
+}
+
+export interface DurableApprovalProtocol {
+  decide(
+    current: ApprovalRecord | undefined,
+    input: DurableApprovalDecisionInput,
+  ): ApprovalRecord | undefined
+  consume(
+    current: ApprovalRecord | undefined,
+    input: DurableApprovalConsumeInput,
+  ): DurableApprovalConsumeTransition
+}
+
+function decideApproval(
+  current: ApprovalRecord | undefined,
+  input: DurableApprovalDecisionInput,
+): ApprovalRecord | undefined {
+  if (
+    current === undefined ||
+    current.tenantId !== input.tenantId ||
+    current.state !== "pending" ||
+    current.expiresAt <= input.now
+  ) {
+    return undefined
+  }
+  return Object.freeze({
+    ...current,
+    state: input.decision,
+    decidedBy: input.decidedBy,
+    updatedAt: input.now,
+    version: current.version + 1,
+  })
+}
+
+function consumeApproval(
+  current: ApprovalRecord | undefined,
+  input: DurableApprovalConsumeInput,
+): DurableApprovalConsumeTransition {
+  if (current === undefined) return { result: { state: "missing" } }
+  if (
+    current.tenantId !== input.tenantId ||
+    current.principalId !== input.principalId ||
+    current.capability !== input.capability ||
+    current.target !== input.target ||
+    !safeEqual(current.digest, input.digest)
+  ) {
+    return { result: { state: "binding" } }
+  }
+  if (!safeEqual(current.tokenHash, input.tokenHash)) return { result: { state: "token" } }
+  if (current.state === "consumed") return { result: { state: "replay" } }
+  if (current.state === "denied") return { result: { state: "denied" } }
+  if (current.state === "pending") return { result: { state: "pending" } }
+  if (current.state === "expired" || current.expiresAt <= input.now) {
+    return {
+      result: { state: "expired" },
+      ...(current.state === "expired"
+        ? {}
+        : {
+            next: Object.freeze({
+              ...current,
+              state: "expired" as const,
+              updatedAt: input.now,
+              version: current.version + 1,
+            }),
+          }),
+    }
+  }
+  if (current.state !== "approved") return { result: { state: "token" } }
+  return {
+    result: { state: "consumed" },
+    next: Object.freeze({
+      ...current,
+      state: "consumed" as const,
+      updatedAt: input.now,
+      version: current.version + 1,
+    }),
+  }
+}
+
+export const durableApprovalProtocol: DurableApprovalProtocol = Object.freeze({
+  decide: decideApproval,
+  consume: consumeApproval,
+})

package/src/internal/durable-effect-protocol.ts

@@ -0,0 +1,37 @@
+import type { DurableEffectRecord, DurableEffectState } from "../durable-execution.ts"
+
+export interface DurableEffectTransitionInput {
+  readonly effectId: string
+  readonly version: number
+  readonly from: DurableEffectState
+  readonly to: DurableEffectState
+  readonly updatedAt: number
+  readonly errorCode?: string
+}
+
+export interface DurableEffectProtocol {
+  transition(
+    current: DurableEffectRecord | undefined,
+    input: DurableEffectTransitionInput,
+  ): DurableEffectRecord | undefined
+}
+
+function transitionEffect(
+  current: DurableEffectRecord | undefined,
+  input: DurableEffectTransitionInput,
+): DurableEffectRecord | undefined {
+  if (current === undefined || current.version !== input.version || current.state !== input.from) {
+    return undefined
+  }
+  return Object.freeze({
+    ...current,
+    state: input.to,
+    updatedAt: input.updatedAt,
+    version: current.version + 1,
+    ...(input.errorCode === undefined ? {} : { errorCode: input.errorCode }),
+  })
+}
+
+export const durableEffectProtocol: DurableEffectProtocol = Object.freeze({
+  transition: transitionEffect,
+})

package/src/internal/durable-saga-protocol.ts

@@ -0,0 +1,55 @@
+import type { SagaRecord, SagaState, SagaStepRecord, SagaStore } from "../durable-execution.ts"
+
+export type DurableSagaTransitionInput = Parameters<SagaStore["compareAndSet"]>[0]
+
+export interface DurableSagaProtocol {
+  transition(
+    current: SagaRecord | undefined,
+    input: DurableSagaTransitionInput,
+  ): SagaRecord | undefined
+  withStep(
+    record: SagaRecord,
+    index: number,
+    step: SagaStepRecord,
+    state: SagaState,
+    updatedAt: number,
+  ): Omit<SagaRecord, "version">
+}
+
+function transitionSaga(
+  current: SagaRecord | undefined,
+  input: DurableSagaTransitionInput,
+): SagaRecord | undefined {
+  if (
+    input.record.version !== input.version + 1 ||
+    (current !== undefined &&
+      (current.sagaId !== input.sagaId || current.version !== input.version))
+  ) {
+    return undefined
+  }
+  return Object.freeze({ ...input.record })
+}
+
+function withSagaStep(
+  record: SagaRecord,
+  index: number,
+  step: SagaStepRecord,
+  state: SagaState,
+  updatedAt: number,
+): Omit<SagaRecord, "version"> {
+  return {
+    ...record,
+    state,
+    steps: Object.freeze(
+      record.steps.map((candidate, candidateIndex) =>
+        candidateIndex === index ? Object.freeze(step) : candidate,
+      ),
+    ),
+    updatedAt,
+  }
+}
+
+export const durableSagaProtocol: DurableSagaProtocol = Object.freeze({
+  transition: transitionSaga,
+  withStep: withSagaStep,
+})

package/src/internal/route-catalog.ts

@@ -80,6 +80,12 @@ export class RouteCatalog {
     return this.records
   }
 
+  /** Number of registered routes. Read at hook push time and at seal to detect an order-scoped hook
+   * that captured no route (see `Server.sealConfiguration`). */
+  get size(): number {
+    return this.records.length
+  }
+
   routeDescriptors(): ReadonlyArray<RouteDescriptor> {
     return this.descriptors
   }