castrum 0.7.0 → 0.9.1

package/src/ingress/decode/fast-result.ts

@@ -0,0 +1,160 @@
+// src/ingress/decode/fast-result.ts — Zero-alloc result decoder (fast path).
+//
+// Decodes the native Ingress packed output (OUT_* layout in ./constants.ts)
+// lazily: slices are stored, strings are decoded only on demand via
+// cookiesJson()/queryJson()/bodyJson().
+//
+// NOTE: this is the fast-path decoder ({"error":{...}} wire format). The
+// pre-baked path has its own decoder (./baked-result.ts) with a different
+// wire format and status normalization — do not unify them (see AGENTS.md).
+// The two decoders DO share their section/rate-limit plumbing via
+// ./result-base.ts.
+
+import { viewForArrayBuffer } from '../../shared/bytes'
+import {
+  OUT_VERDICT,
+  OUT_ERROR_CODE,
+  OUT_STATUS,
+  OUT_FLAGS,
+  OUT_RATE_LIMIT,
+  OUT_RATE_REMAINING,
+  OUT_COOKIES_JSON_LEN,
+  OUT_QUERY_JSON_LEN,
+  OUT_HEADER_VARIANT,
+  OUT_BODY_JSON_LEN,
+  OUT_DATA_START,
+  FLAG_HAS_COOKIES,
+  FLAG_HAS_QUERY,
+  FLAG_BODY_VALID_JSON,
+  FLAG_SCHEMA_VALID,
+  FLAG_CORS_ALLOWED,
+  FLAG_IS_PREFLIGHT,
+  FLAG_RATE_LIMITED,
+  FLAG_HTTPS,
+  FLAG_TRUSTED_PROXY,
+  FLAG_BODY_TRUNCATED,
+  ERR_CODE_INTERNAL,
+} from '../constants'
+import { normalizeResponseStatus } from '../status'
+import { sectionLayout } from './packed-sections'
+import { IngressResultBase } from './result-base'
+
+/** Zero-alloc, lazy-decoding view over a native Ingress output buffer. */
+export class FastIngressResult extends IngressResultBase {
+  // Fast path's empty state is an internal-error shape (500 / verdict 1 /
+  // internal error-code). The baked decoder's empty state is neutral (0/0/0).
+  override status = 500
+  override verdict = 1
+  override errorCode = ERR_CODE_INTERNAL
+  flags = 0
+  https = false
+  hasCookies = false
+  hasQuery = false
+  rateLimit = 0
+  requestId = ''
+
+  refresh(buf: Uint8Array, body: Uint8Array, requestId: string): void {
+    // Defensive: the native core always writes the full fixed header
+    // (>= OUT_DATA_START bytes) before returning `written`. The cached
+    // whole-buffer DataView below would otherwise decode stale bytes if this
+    // contract is ever violated — treat it as an internal error instead.
+    if (buf.byteLength < OUT_DATA_START) {
+      this.setInternalError(requestId)
+      return
+    }
+    this._buf = buf
+    this.body = body
+    this.requestId = requestId
+
+    // Cached per-ArrayBuffer DataView (respects the subarray byteOffset): no
+    // per-request view alloc on the offset-0 production buffers.
+    const dv = viewForArrayBuffer(buf.buffer, buf.byteOffset)
+
+    const rawVerdict = dv.getUint8(OUT_VERDICT)
+    const rawErrorCode = dv.getUint8(OUT_ERROR_CODE)
+    const rawStatus = dv.getUint16(OUT_STATUS, true)
+    const flags = dv.getUint32(OUT_FLAGS, true)
+
+    const rateLimit = dv.getUint32(OUT_RATE_LIMIT, true)
+    const rateRemaining = dv.getUint32(OUT_RATE_REMAINING, true)
+
+    const cookiesJsonLen = dv.getUint32(OUT_COOKIES_JSON_LEN, true)
+    const queryJsonLen = dv.getUint32(OUT_QUERY_JSON_LEN, true)
+
+    const headerVariant = dv.getUint8(OUT_HEADER_VARIANT)
+    const bodyJsonLen = dv.getUint32(OUT_BODY_JSON_LEN, true)
+
+    const preflightAllowed = (flags & FLAG_IS_PREFLIGHT) !== 0 && (flags & FLAG_CORS_ALLOWED) !== 0
+
+    const normalizedStatus = normalizeResponseStatus(rawStatus, rawErrorCode, preflightAllowed)
+
+    const uninitialized = rawVerdict === 0 && rawErrorCode === 0 && rawStatus === 0 && flags === 0
+
+    if (uninitialized) {
+      this.status = 500
+      this.verdict = 1
+      this.errorCode = ERR_CODE_INTERNAL
+    } else {
+      this.status = normalizedStatus
+      this.verdict = rawVerdict
+      this.errorCode = rawErrorCode
+    }
+
+    this.flags = flags
+    this.rateLimit = rateLimit
+    this.rateRemaining = rateRemaining
+
+    this.setRateWindow(rateLimit, (flags & FLAG_RATE_LIMITED) !== 0, dv)
+
+    this.headerVariant = headerVariant
+
+    this.updateOkTerminal()
+
+    this.https = (flags & FLAG_HTTPS) !== 0
+    this.trustedProxy = (flags & FLAG_TRUSTED_PROXY) !== 0
+    this.hasCookies = (flags & FLAG_HAS_COOKIES) !== 0
+    this.hasQuery = (flags & FLAG_HAS_QUERY) !== 0
+    this.bodyValidJson = (flags & FLAG_BODY_VALID_JSON) !== 0
+    this.schemaValid = (flags & FLAG_SCHEMA_VALID) !== 0
+    this.corsAllowed = (flags & FLAG_CORS_ALLOWED) !== 0
+    this.isPreflight = (flags & FLAG_IS_PREFLIGHT) !== 0
+    this.rateLimited = (flags & FLAG_RATE_LIMITED) !== 0
+
+    // Bounds-checked section offsets shared with the pre-baked decoder: a
+    // malformed/truncated buffer can never produce slices past its end.
+    const layout = sectionLayout(buf.byteLength, cookiesJsonLen, queryJsonLen, bodyJsonLen)
+
+    // Store slices for lazy decode instead of eagerly decoding strings. The
+    // fast path trusts the RAW declared body length and re-checks bounds on
+    // read (bodyJson()), so pass the raw declared length here.
+    this.setSections(buf, layout, bodyJsonLen)
+
+    // Parity with the baked decoder: any declared section (cookies, query,
+    // OR body) that overran the buffer counts as truncated.
+    this.bodyTruncated = (flags & FLAG_BODY_TRUNCATED) !== 0 || layout.truncated
+  }
+
+  invalidate(): void {
+    this.resetShared()
+    // Fast path's empty state is an internal-error shape (500/1/internal).
+    this.status = 500
+    this.verdict = 1
+    this.errorCode = ERR_CODE_INTERNAL
+    this.flags = 0
+    this.https = false
+    this.hasCookies = false
+    this.hasQuery = false
+    this.rateLimit = 0
+    this.requestId = ''
+  }
+
+  setInternalError(requestId: string): void {
+    this.invalidate()
+    this.requestId = requestId
+  }
+
+  /** Bounds-checked body-JSON section, or an empty view when absent. */
+  bodyJson(): Uint8Array {
+    return this.bodyJsonSlice()
+  }
+}

package/src/ingress/decode/packed-sections.ts

@@ -0,0 +1,56 @@
+// src/ingress/decode/packed-sections.ts — Shared bounds-checked section layout.
+//
+// Both decoders (fast-result.ts and baked-result.ts) walk the same OUT_* data
+// region: [cookies JSON][query JSON][body JSON], each u32-length-prefixed in
+// the fixed header. This helper centralizes the bounds-checked offset math so
+// a malformed/truncated buffer can never produce slices past its end.
+
+import { OUT_DATA_START } from '../constants'
+
+/** Bounds-checked section offsets for one ingress output buffer. */
+export interface PackedSectionLayout {
+  /** Cookie-JSON length clamped to the buffer (0 if none / out of range). */
+  safeCookiesLen: number
+  /** Byte offset where the query-JSON section begins. */
+  queryStart: number
+  /** Query-JSON length clamped to the buffer (0 if none / out of range). */
+  safeQueryLen: number
+  /** Byte offset where the body-JSON section begins. */
+  bodyJsonStart: number
+  /** Body-JSON length clamped to the buffer (0 if none / out of range). */
+  safeBodyJsonLen: number
+  /** Whether any declared section length overran the buffer. */
+  truncated: boolean
+}
+
+/**
+ * Compute bounds-checked section offsets for an ingress output buffer.
+ *
+ * Given the raw u32 section lengths (already read from the fixed header) and
+ * the actual buffer length, returns safe (clamped-to-buffer) lengths and the
+ * body-JSON start offset. Any length that would run past the end of the
+ * buffer is clamped to 0 and reported via `truncated`, so callers never read
+ * stale or out-of-bounds bytes.
+ */
+export function sectionLayout(
+  bufLen: number,
+  cookiesLen: number,
+  queryLen: number,
+  bodyLen: number,
+): PackedSectionLayout {
+  const safeCookiesLen = cookiesLen > 0 && OUT_DATA_START + cookiesLen <= bufLen ? cookiesLen : 0
+  const queryStart = OUT_DATA_START + safeCookiesLen
+  const safeQueryLen = queryLen > 0 && queryStart + queryLen <= bufLen ? queryLen : 0
+  const bodyJsonStart = queryStart + safeQueryLen
+  const safeBodyJsonLen = bodyLen > 0 && bodyJsonStart + bodyLen <= bufLen ? bodyLen : 0
+
+  return {
+    safeCookiesLen,
+    queryStart,
+    safeQueryLen,
+    bodyJsonStart,
+    safeBodyJsonLen,
+    truncated:
+      safeCookiesLen !== cookiesLen || safeQueryLen !== queryLen || safeBodyJsonLen !== bodyLen,
+  }
+}

package/src/ingress/decode/result-base.ts

@@ -0,0 +1,172 @@
+// src/ingress/decode/result-base.ts — Shared zero-alloc decoder plumbing.
+//
+// Both ingress result decoders (fast-result.ts, baked-result.ts) walk the SAME
+// native OUT_* layout and share: lazy cookie/query JSON section decoding, the
+// bounds-checked body-JSON slice, the rate-limit window fields, and the
+// flag-derived booleans. This base holds that identical plumbing so the two
+// paths cannot drift on section handling.
+//
+// The WIRE FORMAT and STATUS NORMALIZATION intentionally differ between the
+// two decoders ({"error":{...}} fast path vs {"ok":false,...} baked path) —
+// those stay in the subclasses (see AGENTS.md; do not unify them).
+
+import { decoder } from '../../shared/bytes'
+import { OUT_DATA_START, OUT_RATE_RESET, OUT_RETRY_AFTER } from '../constants'
+import type { PackedSectionLayout } from './packed-sections'
+
+const EMPTY_BODY = new Uint8Array(0)
+
+/**
+ * Zero-alloc, reusable result decoder shared base.
+ *
+ * Holds the fields and lazy-decoding helpers that both the fast-path
+ * (`FastIngressResult`) and pre-baked (`BakedIngressResult`) decoders consume
+ * identically from the native OUT_* output buffer. Concrete subclasses own the
+ * status normalization, the exposed extras (requestId, flags, ...) and the
+ * wire-format-specific body/error accessors.
+ */
+export abstract class IngressResultBase {
+  /** Raw native verdict byte (0 = accepted). */
+  verdict = 0
+  /** Raw native error-code byte. */
+  errorCode = 0
+  /** Normalized HTTP status. */
+  status = 0
+  /** Header template variant byte emitted by the native core. */
+  headerVariant = 0
+  /** Remaining rate-limit budget (count). */
+  rateRemaining = 0
+  /** Rate-limit window reset (ms epoch). */
+  rateResetMs = 0
+  /** Retry-After value (ms). */
+  retryAfterMs = 0
+  /** True when the pipeline returned a terminal (error) verdict. */
+  terminal = true
+  /** True when the pipeline accepted the request (verdict 0 + 2xx/3xx). */
+  ok = false
+  /** True when the request was a CORS preflight. */
+  isPreflight = false
+  /** True when the CORS engine allowed the request origin. */
+  corsAllowed = false
+  /** True when the request was rate-limited. */
+  rateLimited = false
+  /** True when the request came from a trusted proxy. */
+  trustedProxy = false
+  /** True when the request body parsed as valid JSON. */
+  bodyValidJson = false
+  /** True when the request body validated against the ingress schema. */
+  schemaValid = false
+  /** True when a declared output section overran the buffer. */
+  bodyTruncated = false
+  /** Request body bytes (may be an empty view). */
+  body: Uint8Array = EMPTY_BODY
+
+  protected _buf: Uint8Array = EMPTY_BODY
+  protected _bodyJsonStart = OUT_DATA_START
+  protected _bodyJsonLen = 0
+  private _cookiesBuf: Uint8Array | null = null
+  private _queryBuf: Uint8Array | null = null
+  private _cookiesDecoded: string | null = null
+  private _queryDecoded: string | null = null
+
+  /** Reset the shared fields to their empty state (call from subclass `invalidate`). */
+  protected resetShared(): void {
+    this.verdict = 0
+    this.errorCode = 0
+    this.status = 0
+    this.headerVariant = 0
+    this.rateRemaining = 0
+    this.rateResetMs = 0
+    this.retryAfterMs = 0
+    this.terminal = true
+    this.ok = false
+    this.isPreflight = false
+    this.corsAllowed = false
+    this.rateLimited = false
+    this.trustedProxy = false
+    this.bodyValidJson = false
+    this.schemaValid = false
+    this.bodyTruncated = false
+    this.body = EMPTY_BODY
+    this._buf = EMPTY_BODY
+    this._bodyJsonStart = OUT_DATA_START
+    this._bodyJsonLen = 0
+    this._cookiesBuf = null
+    this._queryBuf = null
+    this._cookiesDecoded = null
+    this._queryDecoded = null
+  }
+
+  /** Recompute `terminal`/`ok` from the (subclass-set) verdict + status. */
+  protected updateOkTerminal(): void {
+    this.terminal = this.verdict !== 0 || this.status >= 400
+    this.ok = this.verdict === 0 && this.status >= 200 && this.status < 400
+  }
+
+  /**
+   * Store the rate-limit window fields. Both decoders read the same OUT_*
+   * slots and gate them on the same conditions (a positive budget OR the
+   * rate-limited flag), so the read cannot drift between paths.
+   */
+  protected setRateWindow(rateLimit: number, rateLimited: boolean, view: DataView): void {
+    if (rateLimit > 0 || rateLimited) {
+      this.rateResetMs = Number(view.getBigUint64(OUT_RATE_RESET, true))
+      this.retryAfterMs = Number(view.getBigUint64(OUT_RETRY_AFTER, true))
+    } else {
+      this.rateResetMs = 0
+      this.retryAfterMs = 0
+    }
+  }
+
+  /**
+   * Store the bounds-checked cookie/query/body JSON sections from `layout`.
+   *
+   * `bodyJsonLen` is the body-JSON length to trust for `bodyJson()`: the fast
+   * path passes the RAW declared length (it re-checks bounds on read), the
+   * baked path passes the already-clamped `layout.safeBodyJsonLen`. Sections
+   * are stored as slices and decoded lazily by `cookiesJson()`/`queryJson()`.
+   */
+  protected setSections(buf: Uint8Array, layout: PackedSectionLayout, bodyJsonLen: number): void {
+    this._buf = buf
+    this._bodyJsonStart = layout.bodyJsonStart
+    this._bodyJsonLen = bodyJsonLen
+    this._cookiesBuf =
+      layout.safeCookiesLen > 0
+        ? buf.subarray(OUT_DATA_START, OUT_DATA_START + layout.safeCookiesLen)
+        : null
+    this._cookiesDecoded = null
+    this._queryBuf =
+      layout.safeQueryLen > 0
+        ? buf.subarray(layout.queryStart, layout.queryStart + layout.safeQueryLen)
+        : null
+    this._queryDecoded = null
+  }
+
+  /** Decoded cookies-JSON section, or `"{}"` when absent. */
+  cookiesJson(): string {
+    if (this._cookiesDecoded !== null) return this._cookiesDecoded
+    if (this._cookiesBuf !== null) {
+      this._cookiesDecoded = decoder.decode(this._cookiesBuf)
+      return this._cookiesDecoded
+    }
+    return '{}'
+  }
+
+  /** Decoded query-JSON section, or `"{}"` when absent. */
+  queryJson(): string {
+    if (this._queryDecoded !== null) return this._queryDecoded
+    if (this._queryBuf !== null) {
+      this._queryDecoded = decoder.decode(this._queryBuf)
+      return this._queryDecoded
+    }
+    return '{}'
+  }
+
+  /** Bounds-checked body-JSON slice (empty when absent / out of range). */
+  protected bodyJsonSlice(): Uint8Array {
+    if (this._bodyJsonLen === 0) return EMPTY_BODY
+    const end = this._bodyJsonStart + this._bodyJsonLen
+    if (end > this._buf.byteLength) return EMPTY_BODY
+    return this._buf.subarray(this._bodyJsonStart, end)
+  }
+}

package/src/ingress/errors.ts

@@ -0,0 +1,72 @@
+// src/ingress/errors.ts — Fast-path error-code → name/message mapping.
+//
+// The pre-baked path keeps its own error bodies in ./response/error-bodies.ts
+// because it emits a different wire format ({"ok":false,"error":{...}}), so
+// the two mappings are intentionally not unified (see AGENTS.md).
+
+import {
+  ERR_CODE_NONE,
+  ERR_CODE_CORS_PREFLIGHT,
+  ERR_CODE_RATE_LIMITED,
+  ERR_CODE_BODY_TOO_LARGE,
+  ERR_CODE_INVALID_JSON,
+  ERR_CODE_SCHEMA_VALIDATION,
+  ERR_CODE_BAD_REQUEST,
+  ERR_CODE_REQUEST_TOO_LARGE,
+  ERR_CODE_REQUEST_TIMEOUT,
+  ERR_CODE_INTERNAL,
+} from './constants'
+
+/** Map a native error code to its stable string name. */
+export function errorCodeName(code: number): string {
+  switch (code) {
+    case ERR_CODE_NONE:
+      return 'none'
+    case ERR_CODE_CORS_PREFLIGHT:
+      return 'cors_preflight'
+    case ERR_CODE_RATE_LIMITED:
+      return 'rate_limited'
+    case ERR_CODE_BODY_TOO_LARGE:
+      return 'body_too_large'
+    case ERR_CODE_INVALID_JSON:
+      return 'invalid_json'
+    case ERR_CODE_SCHEMA_VALIDATION:
+      return 'schema_validation'
+    case ERR_CODE_BAD_REQUEST:
+      return 'bad_request'
+    case ERR_CODE_REQUEST_TOO_LARGE:
+      return 'request_too_large'
+    case ERR_CODE_REQUEST_TIMEOUT:
+      return 'request_timeout'
+    case ERR_CODE_INTERNAL:
+      return 'internal'
+    default:
+      return 'unknown'
+  }
+}
+
+/** Map a native error code (plus status context) to a human message. */
+export function errorMessage(status: number, code: number): string {
+  switch (code) {
+    case ERR_CODE_CORS_PREFLIGHT:
+      return 'CORS preflight rejected'
+    case ERR_CODE_RATE_LIMITED:
+      return 'Too many requests'
+    case ERR_CODE_BODY_TOO_LARGE:
+      return 'Request body too large'
+    case ERR_CODE_INVALID_JSON:
+      return 'Invalid JSON body'
+    case ERR_CODE_SCHEMA_VALIDATION:
+      return 'JSON schema validation failed'
+    case ERR_CODE_BAD_REQUEST:
+      return 'Bad request'
+    case ERR_CODE_REQUEST_TOO_LARGE:
+      return 'Request too large'
+    case ERR_CODE_REQUEST_TIMEOUT:
+      return 'Request body read timed out'
+    case ERR_CODE_INTERNAL:
+      return 'Internal server error'
+    default:
+      return status >= 500 ? 'Internal server error' : 'Request rejected'
+  }
+}