@c9up/ream 0.2.4 → 0.2.6

package/src/native/generated.ts

@@ -0,0 +1,291 @@
+// GENERATED FROM THE RUST — do not edit.
+//
+// Produced by scripts/generate-napi-types.mjs from napi-derive's type-def
+// output. Editing this file by hand puts it back where it started: a
+// description that can disagree with the code it describes.
+
+/**
+ * Typed response object crossing the TS→NAPI→Rust boundary.
+ *
+ * Using `#[napi(object)]` (instead of `String` carrying JSON) means napi-rs
+ * walks the JS object tree directly into Rust fields — zero JSON parse overhead.
+ *
+ * When `stream_id` is set, `body` is ignored and the hyper response is fed
+ * from the matching entry in the shared `StreamRegistry`. The handler must
+ * have called [`HyperServer::register_stream`] with that id BEFORE
+ * returning, otherwise the response collapses to a 500 (E_STREAM_UNKNOWN).
+ */
+
+export interface NapiResponse {
+  status: number
+  headers: Record<string, string>
+  body: string
+  streamId?: string
+}
+
+/**
+ * Configuration for the wire-level shield filter. Mirrors the Rust
+ * `ShieldConfig` shape; the JS layer constructs it from `ShieldMiddleware`
+ * options at boot and hands it off to `HyperServer.configureShield`.
+ */
+
+export interface NapiShieldConfig {
+  pathTraversal: boolean
+  paramPollution: boolean
+}
+
+/**
+ * Configuration for the wire-level rate limiter. `windowSecs` is the size
+ * of the fixed window in seconds; `max` is the request budget per key
+ * (resolved client IP) per window.
+ */
+
+export interface NapiRateLimitConfig {
+  max: number
+  windowSecs: number
+}
+
+/**
+ * NAPI-exposed event bus.
+ * Uses shared Tokio runtime (no per-instance runtime).
+ */
+
+export declare class EventBus {
+  constructor(requestHandlerTimeoutMs?: number | undefined | null)
+  /** Emit an event (async — does NOT block Node.js thread). */
+  emit(name: string, data: string): Promise<string>
+  /**
+   * Subscribe to events matching a pattern. Callback receives event JSON string.
+   * Returns subscription ID.
+   *
+   * NOTE: This is `pub fn` (sync) — napi-rs cannot make `async fn` capture
+   * `JsFunction` because JsFunction isn't Send. The block_on here runs on the
+   * JS thread (no async context above), so it doesn't deadlock the runtime.
+   */
+  subscribe(pattern: string, callback: (eventJson: string) => void): number
+  /** Unsubscribe by subscription ID. */
+  unsubscribe(subId: number): Promise<void>
+  /** Register a request handler. */
+  onRequest(
+    name: string,
+    callback: (eventJson: string, reply: (response: string) => void) => void,
+  ): void
+  /** Send a request and get a response (async with timeout). */
+  request(name: string, data: string, timeoutMs?: number | undefined | null): Promise<string>
+  /** Check if a pattern matches an event name (wildcard matching via Rust). */
+  matchesWildcard(pattern: string, eventName: string): boolean
+  /** Get subscription count. */
+  subscriptionCount(): Promise<number>
+}
+
+/** NAPI-exposed Hyper HTTP server. */
+
+export declare class HyperServer {
+  /**
+   * `host` is the bind address: an IPv4 literal (`0.0.0.0` to accept from
+   * every interface) or the `localhost` alias. Omitted → loopback only,
+   * the safe default for a dev machine.
+   */
+  constructor(port?: number | undefined | null, host?: string | undefined | null)
+  /** Register the request handler. Callback receives JSON request string, must return JSON response string. */
+  onRequest(callback: (request: string) => Promise<string> | string): void
+  /**
+   * Configure the trusted-proxy CIDR list used by `request.ip` resolution.
+   * Must be called BEFORE `listen()`. Empty list = legacy permissive mode
+   * (any peer can populate `X-Forwarded-For`).
+   */
+  configureTrustedProxies(cidrs: Array<string>): void
+  /**
+   * Install (or replace) the wire-level rate limiter. Pass `None` to
+   * disable. Must be called BEFORE `listen()`.
+   */
+  configureRateLimit(config?: NapiRateLimitConfig | undefined | null): void
+  /**
+   * Configure the wire-level security shield. Must be called BEFORE
+   * `listen()` — the configuration is captured into the security filter
+   * when the server starts. Calling after `listen()` has no effect.
+   */
+  configureShield(config: NapiShieldConfig): void
+  /** Start the HTTP server. */
+  listen(): Promise<void>
+  /** Get the actual bound port. */
+  port(): Promise<number>
+  /**
+   * Shut down the server and release the handles that keep the host's event
+   * loop alive.
+   *
+   * `listen()` registers the JS callback as a `ThreadsafeFunction` (which
+   * holds a libuv ref so `ream start` stays alive). Three `Arc` clones of the
+   * request handler capture it: this struct's `self.handler`, the inner
+   * `ReamServer.handler`, and the accept-loop task's clone. ALL three must
+   * drop for napi-rs to release the tsfn on `Drop` (refcount → 0). The old
+   * `close()` only signalled shutdown, leaving every clone alive — so an
+   * in-process host (test harness) leaked the handle and never drained.
+   */
+  close(): Promise<void>
+  /**
+   * Reserve a slot in the stream registry. Returns `false` if the id
+   * already exists (caller picked a colliding UUID). Always returns
+   * before `listen()` need have run.
+   */
+  registerStream(streamId: string): Promise<boolean>
+  /**
+   * Push a chunk onto a registered stream. Returns `false` when the
+   * stream has already finished (receiver dropped — client gone or
+   * `closeStream` called) so the caller can bail out of its push
+   * loop. Backpressure is handled silently: a full buffer drops the
+   * frame rather than awaiting — SSE is fire-and-forget by design.
+   */
+  writeStream(streamId: string, chunk: string): Promise<boolean>
+  /**
+   * Push a BINARY chunk onto a registered stream, waiting for room.
+   *
+   * The counterpart of [`write_stream`](Self::write_stream) for a body the
+   * client reassembles — a file, an export, an archive. Two differences,
+   * both required there and both wrong for SSE:
+   *
+   * * it takes bytes, not a `String`, so a payload that is not valid UTF-8
+   *   survives the crossing intact;
+   * * it AWAITS when the channel is full instead of dropping the frame, so
+   *   a slow client slows the producer rather than silently receiving a
+   *   truncated file.
+   *
+   * Returns `false` when the receiver is gone (client disconnected or the
+   * stream was closed), so the caller can stop reading its source.
+   */
+  writeStreamBytes(streamId: string, chunk: Uint8Array): Promise<boolean>
+  /**
+  * Close a stream from the server side. The matching response body
+  * finishes cleanly (hyper writes the final chunk + `0
+  
+  ` for
+  * HTTP/1.1 chunked encoding). Idempotent.
+  */
+  closeStream(streamId: string): Promise<boolean>
+  /**
+   * Install a one-shot callback fired the moment the matching stream
+   * receiver is dropped — i.e. the client disconnected or
+   * `closeStream` was called. Used by the JS SDK to drop subscription
+   * bookkeeping when an SSE viewer leaves.
+   *
+   * The callback runs on the libuv loop via the threadsafe-function
+   * machinery, so JS code in the callback uses regular await /
+   * reentrant container calls without crossing-thread surprises.
+   */
+  onStreamDisconnect(streamId: string, callback: (streamId: string) => void): void
+}
+
+/**
+ * Scheduler instance exposed to TypeScript.
+ *
+ * Usage (from TS):
+ * ```ignore
+ * const scheduler = new RustScheduler();
+ * scheduler.register('cleanup', '0 *\/5 * * *', (payload) => { ... });
+ * scheduler.start();
+ * // later
+ * scheduler.stop();
+ * ```
+ */
+
+export declare class RustScheduler {
+  constructor()
+  /**
+   * Register a task. `cronExpr` is a standard 5-field cron expression
+   * evaluated in UTC.
+   *
+   * Throws with `DUPLICATE_TASK` if `name` already exists, or
+   * `INVALID_CRON` if the expression is malformed.
+   */
+  register(
+    name: string,
+    cronExpr: string,
+    callback: (invocation: { taskName: string; scheduledForMs: number }) => void,
+  ): void
+  /** Remove a task. Idempotent — unknown names are not an error. */
+  unregister(name: string): void
+  /** Launch the tick loop on the shared Tokio runtime. Idempotent. */
+  start(): void
+  /** Cancel the tick loop. Safe to call even if not running. */
+  stop(): void
+  /** Return the next fire time in ms epoch, or `null` if the task is unknown. */
+  nextRun(name: string): number | null
+}
+
+/**
+ * Sign a JWT payload with HMAC-SHA256 (Rust-native).
+ * Returns the complete JWT token string.
+ */
+
+export declare function jwtSign(payload: string, secret: string): string
+
+/**
+ * Verify a JWT token and return the decoded payload JSON string.
+ * Validates signature (constant-time), exp, and nbf claims.
+ */
+
+export declare function jwtVerify(token: string, secret: string): string
+
+/**
+ * Hash a password with Argon2id (Rust-native).
+ * Returns the PHC-formatted hash string.
+ */
+
+export declare function argon2Hash(password: string): string
+
+/** Verify a password against an Argon2id hash. */
+
+export declare function argon2Verify(password: string, hash: string): boolean
+
+/**
+ * Hash a password with bcrypt (Rust-native).
+ * `rounds` defaults to 12 when not supplied — matches the previous
+ * warden-engine default and the OWASP-recommended cost floor enforced
+ * by `sigil-engine`.
+ */
+
+export declare function bcryptHash(password: string, rounds?: number | undefined | null): string
+
+/** Verify a password against a bcrypt hash. */
+
+export declare function bcryptVerify(password: string, hash: string): boolean
+
+/** Constant-time string comparison. */
+
+export declare function constantTimeEq(a: string, b: string): boolean
+
+/** HMAC-SHA256 sign. Returns base64url signature. */
+
+export declare function hmacSign(data: string, secret: string): string
+
+/** HMAC-SHA256 verify (constant-time). */
+
+export declare function hmacVerify(data: string, signature: string, secret: string): boolean
+
+/** Generate cryptographically secure random bytes as base64url. */
+
+export declare function randomBytesBase64(len: number): string
+
+/** Generate cryptographically secure random bytes as hex. */
+
+export declare function randomHex(len: number): string
+
+/**
+ * Parse a GraphQL query using the Rust graphql-parser crate.
+ * Returns JSON: { operationType, operationName, fields: [...], errors: [...] }
+ * Invalid queries are rejected here — they never reach the TypeScript resolver layer.
+ */
+
+export declare function graphqlParse(query: string): string
+
+/** Validate a GraphQL query string. Returns JSON array of error strings (empty = valid). */
+
+export declare function graphqlValidate(query: string): string
+
+/**
+ * Extract argument scalar types from a GraphQL SDL schema.
+ * Returns JSON: `{ "Type.field": { "argName": "ScalarType" } }` for argument
+ * coercion in the TypeScript engine.
+ */
+
+export declare function graphqlSchemaArgTypes(sdl: string): string

package/src/rpc/RpcRouter.ts

@@ -20,7 +20,7 @@ import {
 } from '@c9up/comet'
 import type { HttpContext } from '../http/HttpContext.js'
 import type { MiddlewareRegistry, RuntimeValidator } from '../middleware/Pipeline.js'
-import { compose, runValidator } from '../middleware/Pipeline.js'
+import { composeMiddleware, runValidator } from '../middleware/Pipeline.js'
 
 export type RpcHandler = (ctx: HttpContext, params: unknown) => Promise<unknown> | unknown
 
@@ -252,7 +252,7 @@ export class RpcRouter {
       }
       return mw
     })
-    await compose(fns)(ctx, async () => {})
+    await composeMiddleware(fns)(ctx, async () => {})
   }
 
   async #processOne(ctx: HttpContext, request: unknown): Promise<unknown> {

package/src/services/app.ts

@@ -26,6 +26,15 @@ export function clearApp(app: Application): void {
   if (instance === app) instance = undefined
 }
 
+/**
+ * @internal Get the app instance directly. Used by the accessors that stand in
+ * for something the app OWNS (`services/config` is `app.config`), so they read
+ * through here instead of keeping a second copy that a re-boot could desync.
+ */
+export function getApp(): Application | undefined {
+  return instance
+}
+
 const app: Application = createServiceProxy<Application>(
   () => instance,
   'Application accessed before initialization. ' +

package/src/services/config.ts

@@ -0,0 +1,24 @@
+/**
+ * Config store singleton service.
+ *
+ * Usage:
+ *   import config from '@c9up/ream/services/config'
+ *   const port = config.get<number>('app.port', 3333)
+ *
+ * Unlike the other accessors this one keeps no instance of its own: the store
+ * IS `app.config`, so it reads through the app locator. One source of truth
+ * means the two can never point at different stores after a re-boot.
+ */
+
+import type { ConfigStore } from '../ConfigLoader.js'
+import { getApp } from './app.js'
+import { createServiceProxy } from './createServiceProxy.js'
+
+const config: ConfigStore = createServiceProxy<ConfigStore>(
+  () => getApp()?.config,
+  'Config accessed before initialization. ' +
+    'The store is built during the boot phase — read it from inside a provider, ' +
+    'a preload, or a request, not at module top level.',
+)
+
+export default config

package/src/services/encryption.ts

@@ -0,0 +1,42 @@
+/**
+ * Cookie/value signing singleton service.
+ *
+ * Usage:
+ *   import encryption from '@c9up/ream/services/encryption'
+ *   const signed = encryption.sign('payload')
+ *
+ * Registered only when `APP_KEY` is set — there is nothing to sign with
+ * otherwise — so the not-ready message names that rather than the boot phase.
+ */
+
+import type { CookieSigner } from '../security/CookieSigner.js'
+import { createServiceProxy } from './createServiceProxy.js'
+
+let instance: CookieSigner | undefined
+
+/** @internal Set the signer (called by Ignitor once APP_KEY is validated). */
+export function setEncryption(signer: CookieSigner): void {
+  instance = signer
+}
+
+/**
+ * @internal Unset the locator IF it still points at `signer` (called by
+ * Ignitor.stop()). Ownership-guarded — see services/app.ts.
+ */
+export function clearEncryption(signer: CookieSigner): void {
+  if (instance === signer) instance = undefined
+}
+
+/** @internal Get the signer directly. */
+export function getEncryption(): CookieSigner | undefined {
+  return instance
+}
+
+const encryption: CookieSigner = createServiceProxy<CookieSigner>(
+  () => instance,
+  '[E_MISSING_APP_KEY] Encryption accessed before it was registered. ' +
+    'It exists only when APP_KEY is set (>= 16 characters) — check the ' +
+    'environment before reaching for it, or you are reading it before boot.',
+)
+
+export default encryption

package/src/services/urlBuilder.ts

@@ -0,0 +1,41 @@
+/**
+ * Named-route URL helpers, as free functions.
+ *
+ * Usage:
+ *   import { urlFor, signedUrlFor } from '@c9up/ream/services/urlBuilder'
+ *   const href = urlFor('users.show', { id: '42' })
+ *   const link = signedUrlFor('email.verify', { id: '42' }, { expiresIn: '1h' })
+ *
+ * Both delegate to the router — the same code `router.urlFor` /
+ * `router.makeSignedUrl` run — so a route renamed in one place cannot mean two
+ * things. They exist as functions rather than as another proxy object because
+ * that is all there is to the URL builder: two calls, no state.
+ *
+ * `signedUrlFor` needs an APP_KEY-backed signer and says so if there is none.
+ */
+
+import type { SignedUrlOptions } from '../router/Router.js'
+import { getRouter } from './router.js'
+
+const NOT_READY =
+  'URL builder used before initialization. ' +
+  'Routes are registered during the boot phase — build URLs from inside a ' +
+  'controller, a view, or a preload, not at module top level.'
+
+/** Generate a URL from a named route, filling `:param` placeholders. */
+export function urlFor(name: string, params?: Record<string, string>): string {
+  const router = getRouter()
+  if (!router) throw new Error(NOT_READY)
+  return router.urlFor(name, params)
+}
+
+/** Generate a tamper-proof signed URL for a named route. */
+export function signedUrlFor(
+  name: string,
+  params?: Record<string, string>,
+  options?: SignedUrlOptions,
+): string {
+  const router = getRouter()
+  if (!router) throw new Error(NOT_READY)
+  return router.makeSignedUrl(name, params, options)
+}

package/src/session/drivers/CookieDriver.ts

@@ -7,7 +7,7 @@ import type { SessionDriver } from '../Session.js'
  * Requires a secret for encryption.
  */
 export class CookieDriver implements SessionDriver {
-  private signer: CookieSigner
+  #signer: CookieSigner
 
   constructor(secret: string) {
     if (!secret) {
@@ -15,12 +15,12 @@ export class CookieDriver implements SessionDriver {
         'CookieDriver requires a secret for session encryption. Set session.secret in your config.',
       )
     }
-    this.signer = new CookieSigner(secret)
+    this.#signer = new CookieSigner(secret)
   }
 
   async read(sessionId: string): Promise<Record<string, unknown> | null> {
     if (!sessionId) return null
-    const decrypted = this.signer.decrypt(sessionId)
+    const decrypted = this.#signer.decrypt(sessionId)
     if (!decrypted) return null
     try {
       return JSON.parse(decrypted)
@@ -43,6 +43,6 @@ export class CookieDriver implements SessionDriver {
 
   /** Encode session data for cookie storage (encrypted). */
   encode(data: Record<string, unknown>): string {
-    return this.signer.encrypt(JSON.stringify(data))
+    return this.#signer.encrypt(JSON.stringify(data))
   }
 }