@smthrs/control 0.0.0-stage → 1.0.0-rc.4

package/src/WebhookChannel.ts

@@ -0,0 +1,166 @@
+/**
+ * Webhook channel construction over Effect's transport-neutral HTTP request.
+ *
+ * @since 0.1.0
+ */
+
+import { Effect, type Redacted, Schema, Stream } from "effect"
+import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest"
+import { type Channel, Channels, type InboundResult, type RawInbound } from "./Channels.ts"
+import { InvalidInput, type Unauthorized } from "./ControlError.ts"
+import type { IdempotencyKey } from "./ControlSchema.ts"
+import type { CredentialRef } from "./Credential.ts"
+
+/**
+ * Signature verifier injected by a webhook transport.
+ *
+ * The credential is intentionally a redacted reference. Resolution belongs at
+ * the host adapter boundary, never in webhook input or its persisted record.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SignatureVerifier = (
+  raw: RawInbound,
+  credential: Redacted.Redacted<CredentialRef>
+) => Effect.Effect<void, Unauthorized>
+
+/**
+ * Configuration for a schema-declared webhook channel.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Config<A> {
+  readonly name: string
+  readonly schema: Schema.Schema<A>
+  readonly credential: Redacted.Redacted<CredentialRef>
+  readonly fingerprintHeaders?: Channel<A>["fingerprintHeaders"]
+  readonly verify: SignatureVerifier
+  readonly map: (payload: A) => Effect.Effect<InboundResult, InvalidInput>
+  readonly project: Channel<A>["project"]
+}
+
+const invalidInput = (issue: string): InvalidInput => new InvalidInput({ issue })
+
+/**
+ * Largest webhook request body one mount reads by default, in bytes.
+ *
+ * A webhook is the one control-plane ingress a bearer holder reaches with an
+ * arbitrary payload, and `handler` used to materialize whatever arrived before
+ * anything looked at its size. The default is deliberately smaller than the
+ * 4 MiB mutation-identity budget in `internal/mutationBoundary.ts`: a body that
+ * cannot become a durable mutation is refused at the door rather than copied,
+ * decoded, and refused later.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const maximumBodyBytes = 1024 * 1024
+
+/**
+ * Per-mount overrides for the webhook request handler.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface HandlerOptions {
+  /** Body ceiling for this mount. Defaults to `maximumBodyBytes`. */
+  readonly maximumBodyBytes?: number | undefined
+}
+
+/**
+ * The declared body length, when the caller stated one this host can trust.
+ *
+ * Header names arrive lower-cased from Effect's HTTP layer, but a hand-built
+ * request is not obliged to, so the lookup folds case itself. An absent,
+ * non-numeric, fractional, or negative declaration is not evidence of
+ * anything: it falls through to the streaming measurement rather than being
+ * treated as zero.
+ */
+const declaredLength = (headers: Readonly<Record<string, string | undefined>>): number | undefined => {
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() !== "content-length" || value === undefined) continue
+    const parsed = Number(value.trim())
+    return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : undefined
+  }
+  return undefined
+}
+
+/**
+ * Builds a webhook channel. Verification receives raw bytes and headers before
+ * JSON parsing and schema decoding.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = <A>(config: Config<A>): Channel<A> => {
+  const decode = Schema.decodeUnknownEffect(config.schema)
+  return {
+    name: config.name,
+    schema: config.schema,
+    ...(config.fingerprintHeaders === undefined ? {} : { fingerprintHeaders: config.fingerprintHeaders }),
+    verify: Effect.fn("WebhookChannel.verify")((raw) => config.verify(raw, config.credential)),
+    decode: Effect.fn("WebhookChannel.decode")((raw) =>
+      Effect.try({
+        try: () => JSON.parse(new TextDecoder().decode(raw.body)),
+        catch: () => invalidInput("invalid webhook JSON")
+      }).pipe(
+        Effect.flatMap((json) => decode(json)),
+        Effect.mapError((cause) => cause instanceof InvalidInput ? cause : invalidInput(String(cause)))
+      ) as Effect.Effect<A, InvalidInput>
+    ),
+    map: Effect.fn("WebhookChannel.map")((payload) => config.map(payload)),
+    project: config.project
+  }
+}
+
+/**
+ * Reads an abstract Effect HTTP request and dispatches it through Channels.
+ * This is mountable by any Effect HTTP host; it contains no Node transport
+ * dependencies.
+ *
+ * The body is bounded twice. A `content-length` over the limit is refused
+ * before the body is read at all, so a declared flood costs nothing; the
+ * measured length is checked before retaining each streamed chunk. Reading
+ * stops at the first chunk exceeding the limit, including when the caller
+ * understates or omits the length. Both refusals are `InvalidInput` naming the
+ * two byte counts and no body content.
+ *
+ * @category handlers
+ * @since 0.1.0
+ */
+export const handler = (
+  channel: string,
+  idempotencyKey: IdempotencyKey,
+  options?: HandlerOptions | undefined
+) =>
+  Effect.gen(function*() {
+    const limit = options?.maximumBodyBytes ?? maximumBodyBytes
+    const request = yield* HttpServerRequest.HttpServerRequest
+    const declared = declaredLength(request.headers)
+    if (declared !== undefined && declared > limit) {
+      return yield* invalidInput(`webhook body: declared ${declared} bytes exceeds the ${limit} byte limit`)
+    }
+    const chunks: Array<Uint8Array> = []
+    let size = 0
+    yield* Stream.runForEach(request.stream, (chunk) =>
+      Effect.gen(function*() {
+        size += chunk.byteLength
+        if (size > limit) {
+          return yield* invalidInput(`webhook body: ${size} bytes exceeds the ${limit} byte limit`)
+        }
+        if (chunk.byteLength > 0) chunks.push(chunk.slice())
+      }))
+    const body = new Uint8Array(size)
+    let offset = 0
+    for (const chunk of chunks) {
+      body.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+    const channels = yield* Channels
+    return yield* channels.ingest({
+      channel,
+      raw: { body, headers: request.headers, idempotencyKey }
+    })
+  })

package/src/index.ts

@@ -0,0 +1,188 @@
+/**
+ * Control-plane contracts and projections for the Smithers harness.
+ *
+ * This is the public surface of the control plane: the transport-independent
+ * `Control` service, the `ControlRuntime` port it writes through, the
+ * projections it reads back, and the durable adapter that binds both to a real
+ * database.
+ *
+ * `Control` is authority, not execution. Every mutation it accepts is
+ * idempotent, principal-stamped, and recorded in the journal beside the state
+ * change it caused, so "who asked for this, and when did it take effect?" is
+ * answered from persisted evidence rather than from a log line.
+ *
+ * @since 0.1.0
+ */
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as Control from "./Control.ts"
+
+/**
+ * @category services
+ * @since 1.0.0
+ */
+export * as ApprovalAuthority from "./ApprovalAuthority.ts"
+
+/**
+ * @category errors
+ * @since 0.1.0
+ */
+export * as ControlError from "./ControlError.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as ControlSchema from "./ControlSchema.ts"
+
+/**
+ * @category projections
+ * @since 0.1.0
+ */
+export * as Cancellation from "./Cancellation.ts"
+
+/**
+ * @category projections
+ * @since 0.1.0
+ */
+export * as Lineage from "./Lineage.ts"
+
+/**
+ * @category projections
+ * @since 0.1.0
+ */
+export * as Monitor from "./Monitor.ts"
+
+/**
+ * @category projections
+ * @since 0.1.0
+ */
+export * as Steering from "./Steering.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as ControlRuntime from "./ControlRuntime.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as ControlExecutor from "./ControlExecutor.ts"
+
+/**
+ * @category services
+ * @since 1.0.0
+ */
+export * as DispatchReader from "./DispatchReader.ts"
+
+/**
+ * @category layers
+ * @since 0.1.0
+ */
+export * as ControlLive from "./ControlLive.ts"
+
+/**
+ * @category models
+ * @since 0.1.0
+ */
+export * as SystemFlows from "./SystemFlows.ts"
+
+/**
+ * @category rpc
+ * @since 0.1.0
+ */
+export * as ControlRpcs from "./ControlRpcs.ts"
+
+/**
+ * @category layers
+ * @since 0.1.0
+ */
+export * as ControlServer from "./ControlServer.ts"
+
+/**
+ * @category layers
+ * @since 0.1.0
+ */
+export * as ControlClient from "./ControlClient.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as Channels from "./Channels.ts"
+
+/**
+ * @category channels
+ * @since 0.1.0
+ */
+export * as WebhookChannel from "./WebhookChannel.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as Credential from "./Credential.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as CredentialCipher from "./CredentialCipher.ts"
+
+/**
+ * @category services
+ * @since 0.1.0
+ */
+export * as CredentialStore from "./CredentialStore.ts"
+
+/**
+ * @category layers
+ * @since 0.1.0
+ */
+export * as SqlCredentialStore from "./SqlCredentialStore.ts"
+
+/**
+ * @category layers
+ * @since 0.1.0
+ */
+export * as WebCryptoCipher from "./WebCryptoCipher.ts"
+
+/**
+ * @category layers
+ * @since 0.1.0
+ */
+export * as SqlControlRuntime from "./SqlControlRuntime.ts"
+
+/**
+ * @category authentication
+ * @since 1.0.0
+ */
+export * as ScopedToken from "./ScopedToken.ts"
+
+/**
+ * @category migrations
+ * @since 0.1.0
+ */
+export * as Migrations from "./Migrations.ts"
+
+/**
+ * Observational health contracts.
+ * @category health
+ * @since 1.0.0
+ */
+export * as Health from "./Health.ts"
+
+/**
+ * The Jev-decided session checker a host binds as `jev.session`.
+ * @category health
+ * @since 1.0.0
+ */
+export * as JevSessionChecker from "./JevSessionChecker.ts"
+
+/** Versioned control lifecycle producer and projection contract. */
+export * as ControlFacts from "./ControlFacts.ts"

package/src/internal/MutationBoundary.ts

@@ -0,0 +1,46 @@
+/**
+ * Bounded inert JSON admission for control mutations.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+
+import * as BoundedJson from "@smthrs/canonical/BoundedJson"
+
+/** Limits and diagnostic precedence of the control mutation boundary. */
+const limits = {
+  maxBytes: 4 * 1024 * 1024,
+  maxStringBytes: 4 * 1024 * 1024,
+  maxKeyBytes: 4 * 1024 * 1024,
+  maxDepth: 128,
+  maxNodes: 100_000,
+  maxMembers: 100_000,
+  maxTotalMembers: 100_000
+} satisfies BoundedJson.Limits
+
+/** Result of admitting an unknown mutation value. */
+type Result =
+  | { readonly ok: true; readonly value: BoundedJson.Json }
+  | { readonly ok: false; readonly complaint: string }
+
+/**
+ * Copies one mutation without invoking getters or `toJSON`.
+ *
+ * `bounds` defaults to the control mutation limits. Tests pass smaller ones to
+ * reach a byte-exact boundary without building multi-megabyte values.
+ *
+ * @since 1.0.0-rc.0
+ * @private
+ */
+export const admit = (input: unknown, bounds: BoundedJson.Limits = limits): Result => {
+  const result = BoundedJson.admit(input, bounds, { preflightObjects: false })
+  if (result.ok) return { ok: true, value: result.value }
+  const complaint = result.code === "members"
+    ? `contains more than ${bounds.maxTotalMembers} JSON members`
+    : result.code === "string"
+    ? "contains oversized or ill-formed text"
+    : result.code === "key"
+    ? "contains an oversized or ill-formed object key"
+    : result.complaint
+  return { ok: false, complaint }
+}

package/src/internal/activeFibers.ts

@@ -0,0 +1,22 @@
+/**
+ * Completion-aware, replacement-safe ownership of live fibers.
+ * @since 1.0.0
+ */
+
+import type * as Fiber from "effect/Fiber"
+
+/**
+ * A completed predecessor must never unregister its replacement.
+ * @category registration
+ * @since 1.0.0
+ */
+export const register = <K>(
+  fibers: Map<K, Fiber.Fiber<unknown, unknown>>,
+  key: K,
+  fiber: Fiber.Fiber<unknown, unknown>
+): void => {
+  fibers.set(key, fiber)
+  fiber.addObserver(() => {
+    if (fibers.get(key) === fiber) fibers.delete(key)
+  })
+}

package/src/internal/issues.ts

@@ -0,0 +1,40 @@
+/**
+ * Bounded diagnostics for failures that cross the control wire boundary.
+ *
+ * @since 0.1.0
+ */
+
+import { CanonicalError } from "@smthrs/canonical"
+
+const maximumIssueLength = 512
+
+/**
+ * Joins a stable location and reason without allowing an RPC error to grow
+ * without bound.
+ *
+ * @private
+ * @since 0.1.0
+ */
+export const cappedIssue = (path: string, reason: string): string => {
+  const issue = `${path}: ${reason}`
+  return issue.length <= maximumIssueLength ? issue : `${issue.slice(0, maximumIssueLength - 3)}...`
+}
+
+/**
+ * Renders canonical's stable located failure without copying its rejected
+ * value or a nested cause message into an RPC error.
+ *
+ * @private
+ * @since 0.1.0
+ */
+export const canonicalIssue = (cause: unknown): string =>
+  cause instanceof CanonicalError
+    ? cappedIssue(cause.path, cause.code)
+    : cappedIssue("$", "canonicalization failed")
+
+/**
+ * Finds the first rejected field without rendering its value.
+ * @private
+ * @since 0.1.0
+ */
+export { firstPath as schemaIssuePath } from "@smthrs/canonical/IssuePath"