@nifrajs/core 3.1.0 → 3.2.0

package/src/edge-kit.ts

@@ -16,12 +16,12 @@
  * or app state. It is the interface, not the framework.
  */
 
+export { readBodyFramed } from "./server/body-lane.ts"
 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"
+export { plainValidationError } from "./server/validation.ts"

package/src/index.ts

@@ -3,6 +3,12 @@
  *
  * Nifra 2.0 keeps the package root intentionally lean. Optional systems live at documented
  * subpaths so importing the root cannot activate unrelated runtimes.
+ *
+ * Every named export below is re-exported in a SINGLE hop from the module that defines it -
+ * deliberately not `export * from "./server.ts"`. A root binding that travels through a chained
+ * barrel can be dropped by a bundler that rewrites module loads (the single-copy plugin does
+ * exactly that), which surfaces as a runtime `ReferenceError` only in bundled output. The list
+ * must stay identical to `./server.ts`; `server-entry.test.ts` enforces the parity.
  */
 
 /**
@@ -10,8 +16,129 @@
  * 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 = "3.1.0" as const
+export const VERSION = "3.2.0" as const
 
 export type Version = typeof VERSION
 
-export * from "./server.ts"
+export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
+export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
+export { isSameOriginRequest } from "./internal/same-origin.ts"
+export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"
+export type {
+  InferInput,
+  InferOutput,
+  StandardIssue,
+  StandardResult,
+  StandardSchemaV1,
+  StandardTypes,
+  ValidationOutcome,
+} from "./schema/standard.ts"
+export type {
+  Context,
+  Params,
+  Platform,
+  Prettify,
+  ResponseControls,
+  RouteSchema,
+} from "./server/context.ts"
+export {
+  type CookieOptions,
+  type CookieSecret,
+  cookieNamePrefix,
+  parseCookies,
+  serializeCookie,
+  signValue,
+  unsignValue,
+} from "./server/cookies.ts"
+export {
+  type DurableObjectNamespaceLike,
+  type ExecutionContext,
+  type ScheduledController,
+  type ScheduledHandler,
+  toFetchHandler,
+} from "./server/edge.ts"
+export { isSameOriginPath, pathnameOf, type UrlParts, urlPartsOf } from "./server/http.ts"
+export {
+  commonSecretPatterns,
+  jsonLogger,
+  type LogFields,
+  type Logger,
+  type RedactOptions,
+  redactLogFields,
+  silentLogger,
+} from "./server/logger.ts"
+export {
+  type FetchApp,
+  type LambdaEvent,
+  type LambdaHandler,
+  type LambdaResponse,
+  type LambdaV1Event,
+  type LambdaV2Event,
+  type NetlifyEvent,
+  type NetlifyHandler,
+  type PlatformResponse,
+  toLambdaHandler,
+  toNetlifyHandler,
+  toVercelHandler,
+  type VercelHandler,
+} from "./server/platform-adapters.ts"
+export type { Registry, ResponseMapFor, RouteInfo, RouteInfoFor } from "./server/registry.ts"
+export {
+  type PlainRender,
+  type ResponseResult,
+  type StatusResponse,
+  status,
+} from "./server/runtime-core.ts"
+export {
+  type AdmissionController,
+  type AdmissionDecision,
+  type AnyServer,
+  type ContextPlugin,
+  type DefinePluginResult,
+  defineContextPlugin,
+  defineIdentityPlugin,
+  definePlugin,
+  defineRouterPlugin,
+  type Handler,
+  type IdentityPlugin,
+  type McpPromptDescriptor,
+  type McpResourceDescriptor,
+  type Middleware,
+  type NifraFeatureVersion,
+  type NifraPlugin,
+  type NodeRequestContext,
+  type NodeRequestHook,
+  type NodeResponseContext,
+  type NodeResponseHook,
+  type NodeServeOutcome,
+  type OnRequestResult,
+  type PluginTypeCollapsed,
+  type PromptArgument,
+  type PromptMessage,
+  type ResponseBodyHook,
+  type ResponseBodyReplacement,
+  type ResponseFinalization,
+  type ResponseHeadersHook,
+  type ResponseHeadersView,
+  type RouteDescriptor,
+  type RunningServer,
+  Server,
+  type ServerOptions,
+  server,
+  type ToolAnnotations,
+} from "./server/server.ts"
+export type {
+  SSEContext,
+  SSEInit,
+  SSEMessage,
+  SSEStream,
+  TypedSSEStream,
+} from "./server/sse.ts"
+export type {
+  NifraWebSocket,
+  StandardWebSocket,
+  WebSocketContext,
+  WebSocketData,
+  WebSocketHandler,
+  WebSocketUpgradeOutcome,
+} from "./server/websocket.ts"

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

@@ -1,4 +1,4 @@
-import type { ApprovalConsumeResult, ApprovalRecord, ApprovalStore } from "../durable-execution.ts"
+import type { ApprovalConsumeResult, ApprovalRecord, ApprovalStore } from "./durable-types.ts"
 import { safeEqual } from "./safe-equal.ts"
 
 export type DurableApprovalDecisionInput = Parameters<ApprovalStore["decide"]>[0]

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

@@ -1,4 +1,4 @@
-import type { DurableEffectRecord, DurableEffectState } from "../durable-execution.ts"
+import type { DurableEffectRecord, DurableEffectState } from "./durable-types.ts"
 
 export interface DurableEffectTransitionInput {
   readonly effectId: string

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

@@ -1,4 +1,4 @@
-import type { SagaRecord, SagaState, SagaStepRecord, SagaStore } from "../durable-execution.ts"
+import type { SagaRecord, SagaState, SagaStepRecord, SagaStore } from "./durable-types.ts"
 
 export type DurableSagaTransitionInput = Parameters<SagaStore["compareAndSet"]>[0]
 

package/src/internal/durable-shared.ts

@@ -0,0 +1,157 @@
+import type { ReconciliationScanOptions, ReconciliationScanPage } from "./durable-types.ts"
+
+export const TOKEN = /^[!-~]+$/
+export const ERROR_CODE = /^[a-z][a-z0-9_.-]{0,63}$/
+export const encoder = new TextEncoder()
+
+export function assertToken(value: string, label: string, maxLength = 255): void {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > maxLength ||
+    !TOKEN.test(value)
+  ) {
+    throw new TypeError(`${label} must be a bounded printable token`)
+  }
+}
+
+export function assertPositiveMs(value: number, label: string): void {
+  if (!Number.isSafeInteger(value) || value < 1)
+    throw new RangeError(`${label} must be a positive safe integer`)
+}
+
+export function assertTimestamp(value: number, label: string): void {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new RangeError(`${label} must be a non-negative safe integer timestamp`)
+}
+
+export function readClock(clock: () => number, label: string): number {
+  const value = clock()
+  assertTimestamp(value, label)
+  return value
+}
+
+export function addDuration(timestamp: number, duration: number, label: string): number {
+  const result = timestamp + duration
+  assertTimestamp(result, label)
+  return result
+}
+
+export function bytesToBase64Url(bytes: Uint8Array): string {
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "")
+}
+
+export async function sha256(value: string): Promise<string> {
+  return bytesToBase64Url(
+    new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value))),
+  )
+}
+
+export function cloneValue<T>(value: T): T {
+  return structuredClone(value)
+}
+
+export const DEFAULT_RECONCILIATION_LIMIT = 100
+export const MAX_RECONCILIATION_LIMIT = 1_000
+
+export function reconciliationLimit(value = DEFAULT_RECONCILIATION_LIMIT): number {
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_RECONCILIATION_LIMIT) {
+    throw new RangeError(`reconciliation limit must be between 1 and ${MAX_RECONCILIATION_LIMIT}`)
+  }
+  return value
+}
+
+export function cursorOffset(cursor?: string): number {
+  if (cursor === undefined) return 0
+  if (!/^(?:0|[1-9][0-9]*)$/u.test(cursor)) throw new TypeError("invalid reconciliation cursor")
+  const offset = Number(cursor)
+  if (!Number.isSafeInteger(offset)) throw new TypeError("invalid reconciliation cursor")
+  return offset
+}
+
+export function memoryScan<
+  Record extends { readonly state: State; readonly updatedAt: number },
+  State extends string,
+>(
+  source: Iterable<Record>,
+  input: ReconciliationScanOptions<State>,
+): ReconciliationScanPage<Record> {
+  const states = new Set(input.states)
+  const offset = cursorOffset(input.cursor)
+  const end = offset + input.limit
+  const records: Record[] = []
+  let seen = 0
+  let more = false
+  for (const record of source) {
+    if (!states.has(record.state)) continue
+    if (input.updatedBefore !== undefined && record.updatedAt > input.updatedBefore) continue
+    if (seen >= end) {
+      more = true
+      break
+    }
+    if (seen >= offset) records.push(cloneValue(record))
+    seen++
+  }
+  return Object.freeze({
+    records: Object.freeze(records),
+    ...(more ? { cursor: String(offset + records.length) } : {}),
+  })
+}
+
+export function bucketAdd<State extends string>(
+  byState: Map<State, Set<string>>,
+  state: State,
+  id: string,
+): void {
+  let bucket = byState.get(state)
+  if (bucket === undefined) {
+    bucket = new Set()
+    byState.set(state, bucket)
+  }
+  bucket.add(id)
+}
+
+export function bucketMove<State extends string>(
+  byState: Map<State, Set<string>>,
+  from: State,
+  to: State,
+  id: string,
+): void {
+  if (from === to) return
+  byState.get(from)?.delete(id)
+  bucketAdd(byState, to, id)
+}
+
+export function indexedScan<Record extends { readonly updatedAt: number }, State extends string>(
+  byState: Map<State, Set<string>>,
+  resolve: (id: string) => Record | undefined,
+  input: ReconciliationScanOptions<State>,
+): ReconciliationScanPage<Record> {
+  const offset = cursorOffset(input.cursor)
+  const end = offset + input.limit
+  const records: Record[] = []
+  let seen = 0
+  let more = false
+  for (const state of new Set(input.states)) {
+    if (more) break
+    const bucket = byState.get(state)
+    if (bucket === undefined) continue
+    for (const id of bucket) {
+      const record = resolve(id)
+      if (record === undefined) continue
+      if (input.updatedBefore !== undefined && record.updatedAt > input.updatedBefore) continue
+      if (seen >= end) {
+        more = true
+        break
+      }
+      if (seen >= offset) records.push(cloneValue(record))
+      seen++
+    }
+  }
+  return Object.freeze({
+    records: Object.freeze(records),
+    ...(more ? { cursor: String(offset + records.length) } : {}),
+  })
+}

package/src/internal/durable-types.ts

@@ -0,0 +1,194 @@
+/** Type-only records and transition contracts shared by durable execution domains. */
+export type DurableEffectState = "admission" | "executing" | "committed" | "failed" | "unknown"
+
+export interface ReconciliationScanOptions<State extends string> {
+  readonly states: readonly State[]
+  readonly updatedBefore?: number
+  readonly cursor?: string
+  readonly limit: number
+}
+
+export interface ReconciliationScanPage<Record> {
+  readonly records: readonly Record[]
+  readonly cursor?: string
+}
+
+export interface ReconciliationPage<Finding> {
+  readonly findings: readonly Finding[]
+  readonly cursor?: string
+}
+
+export interface DurableEffectRecord {
+  readonly effectId: string
+  readonly capability: string
+  readonly target?: string
+  readonly digest?: string
+  readonly tenantId?: string
+  readonly principalId?: string
+  readonly state: DurableEffectState
+  readonly createdAt: number
+  readonly updatedAt: number
+  readonly errorCode?: string
+  readonly version: number
+}
+
+export interface DurableEffectStore {
+  readonly durability?: "memory" | "durable"
+  create(record: DurableEffectRecord): boolean | Promise<boolean>
+  get(effectId: string): DurableEffectRecord | undefined | Promise<DurableEffectRecord | undefined>
+  /** Atomic compare-and-set; exactly one caller may advance the supplied `version` and `from` state. */
+  transition(input: {
+    readonly effectId: string
+    readonly version: number
+    readonly from: DurableEffectState
+    readonly to: DurableEffectState
+    readonly updatedAt: number
+    readonly errorCode?: string
+  }): boolean | Promise<boolean>
+  /** Bounded operational scan. Transition-only stores do not need to implement reconciliation. */
+  scan?(
+    input: ReconciliationScanOptions<DurableEffectState>,
+  ):
+    | ReconciliationScanPage<DurableEffectRecord>
+    | Promise<ReconciliationScanPage<DurableEffectRecord>>
+  /** @deprecated Compatibility fallback; production reconciliation should implement `scan`. */
+  list?(): readonly DurableEffectRecord[] | Promise<readonly DurableEffectRecord[]>
+}
+
+export type ApprovalState = "pending" | "approved" | "denied" | "consumed" | "expired"
+
+export interface ApprovalRecord {
+  readonly approvalId: string
+  readonly effectId: string
+  readonly capability: string
+  readonly target?: string
+  readonly digest?: string
+  readonly tenantId: string
+  readonly principalId: string
+  readonly tokenHash: string
+  readonly state: ApprovalState
+  readonly createdAt: number
+  readonly expiresAt: number
+  readonly updatedAt: number
+  readonly decidedBy?: string
+  readonly version: number
+}
+
+export type ApprovalConsumeResult =
+  | { readonly state: "consumed" }
+  | {
+      readonly state: "missing" | "pending" | "denied" | "expired" | "replay" | "binding" | "token"
+    }
+
+export interface ApprovalStore {
+  readonly durability?: "memory" | "durable"
+  create(record: ApprovalRecord): boolean | Promise<boolean>
+  get(approvalId: string): ApprovalRecord | undefined | Promise<ApprovalRecord | undefined>
+  decide(input: {
+    readonly approvalId: string
+    readonly tenantId: string
+    readonly decision: "approved" | "denied"
+    readonly decidedBy: string
+    readonly now: number
+  }): boolean | Promise<boolean>
+  /**
+   * Atomically validate binding/token/state and change `approved` to `consumed`. Two concurrent
+   * callers with one token must yield exactly one `consumed` and one `replay` result.
+   */
+  consume(input: {
+    readonly approvalId: string
+    readonly tenantId: string
+    readonly principalId: string
+    readonly capability: string
+    readonly target?: string
+    readonly digest?: string
+    readonly tokenHash: string
+    readonly now: number
+  }): ApprovalConsumeResult | Promise<ApprovalConsumeResult>
+}
+
+export type SagaState = "running" | "compensating" | "completed" | "compensated" | "manual-review"
+export type SagaStepState =
+  | "executing"
+  | "committed"
+  | "failed"
+  | "ambiguous"
+  | "compensating"
+  | "compensation-failed"
+  | "compensated"
+
+export interface SagaStepRecord {
+  readonly name: string
+  readonly effectId: string
+  readonly compensationEffectId: string
+  readonly state: SagaStepState
+  readonly compensationArgs: unknown
+  readonly result?: unknown
+  readonly attempts: number
+  readonly nextAttemptAt?: number
+  readonly errorCode?: string
+}
+
+export interface SagaRecord {
+  readonly sagaId: string
+  readonly definition: string
+  readonly state: SagaState
+  readonly input: unknown
+  readonly steps: readonly SagaStepRecord[]
+  readonly createdAt: number
+  readonly updatedAt: number
+  readonly version: number
+}
+
+export interface SagaStore {
+  readonly durability?: "memory" | "durable"
+  create(record: SagaRecord): boolean | Promise<boolean>
+  get(sagaId: string): SagaRecord | undefined | Promise<SagaRecord | undefined>
+  /** Atomic version compare-and-set; this is the saga engine's crash/concurrency boundary. */
+  compareAndSet(input: {
+    readonly sagaId: string
+    readonly version: number
+    readonly record: SagaRecord
+  }): boolean | Promise<boolean>
+  /** Bounded operational scan. Transition-only stores do not need to implement reconciliation. */
+  scan?(
+    input: ReconciliationScanOptions<SagaState>,
+  ): ReconciliationScanPage<SagaRecord> | Promise<ReconciliationScanPage<SagaRecord>>
+  /** @deprecated Compatibility fallback; production reconciliation should implement `scan`. */
+  list?(): readonly SagaRecord[] | Promise<readonly SagaRecord[]>
+}
+
+export interface SagaStepExecutionContext {
+  readonly effectId: string
+  readonly signal: AbortSignal
+}
+export interface SagaCompensationContext {
+  readonly effectId: string
+  readonly sagaId: string
+  readonly attempt: number
+  readonly signal: AbortSignal
+}
+
+export interface SagaRunContext<C extends Record<string, unknown>> {
+  step<K extends keyof C & string, T>(
+    name: K,
+    compensationArgs: C[K],
+    execute: (context: SagaStepExecutionContext) => T | PromiseLike<T>,
+  ): Promise<T>
+}
+
+export interface SagaDefinition<I, C extends Record<string, unknown>> {
+  readonly name: string
+  readonly capability?: string
+  readonly run: (context: SagaRunContext<C>, input: I) => void | PromiseLike<void>
+  readonly compensators: {
+    readonly [K in keyof C]: (
+      args: C[K],
+      context: SagaCompensationContext,
+    ) => void | PromiseLike<void>
+  }
+  readonly retry?: {
+    readonly maxAttempts?: number
+    readonly backoffMs?: (attempt: number) => number
+  }
+}