@smthrs/triggers 0.0.0-stage → 1.0.0-rc.3

package/src/Webhook.ts

@@ -0,0 +1,270 @@
+/**
+ * Verified webhook ingestion through the authoritative Control boundary.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ * @since 0.1.0
+ */
+
+import * as ControlChannels from "@smthrs/control/Channels"
+import type { ControlError } from "@smthrs/control/ControlError"
+import { InvalidInput, Unauthorized } from "@smthrs/control/ControlError"
+import type { Receipt, RunSummary } from "@smthrs/control/ControlSchema"
+import type { CredentialRef } from "@smthrs/control/Credential"
+import * as ControlWebhook from "@smthrs/control/WebhookChannel"
+import * as Effect from "effect/Effect"
+import type * as Redacted from "effect/Redacted"
+import * as Schema from "effect/Schema"
+import type * as Channel from "./Channel.ts"
+import { TriggerError } from "./TriggerError.ts"
+
+/**
+ * Compares a supplied byte string against the expected one without returning
+ * early on a mismatch.
+ *
+ * The loop runs exactly `expected.length` times, so its iteration count is
+ * fixed by the secret side of the comparison and never by the caller's. Reading
+ * the longer of the two instead let a caller lengthen its input until the work
+ * stopped growing, which reports the expected signature's length. The length
+ * difference is folded into the result, so inputs of unequal length always
+ * disagree.
+ *
+ * @category verification
+ * @since 0.1.0
+ */
+export const constantTimeEqual = (expected: Uint8Array, supplied: Uint8Array): boolean => {
+  let difference = expected.length ^ supplied.length
+  for (const [index, byte] of expected.entries()) {
+    difference |= byte ^ (supplied[index] ?? 0)
+  }
+  return difference === 0
+}
+
+/**
+ * Configuration for a raw-byte signature verifier.
+ *
+ * `expected` receives a private copy of the request bytes and the redacted
+ * credential reference the channel was declared with, and answers with the
+ * signature bytes the request must carry in `header`. It returns an Effect so
+ * the secret is resolved through the host's resolver per request rather than
+ * captured in a closure at declaration time, and so a resolution or HMAC
+ * failure arrives as a typed `verification_failed` instead of a defect that
+ * kills the fiber.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface SignatureConfig {
+  readonly header: string
+  readonly expected: (
+    body: Uint8Array,
+    credential: Redacted.Redacted<CredentialRef>
+  ) => Effect.Effect<Uint8Array, TriggerError>
+}
+
+/**
+ * Copies request bytes into memory nobody else holds.
+ *
+ * `body.slice()` is not enough: a Node `Buffer` is a `Uint8Array` whose
+ * `slice` is an alias of `subarray` and answers with a view over the same
+ * memory, so a caller that reused its `Buffer` after handing it over changed
+ * what got verified, and a verifier that edited the bytes it was handed edited
+ * the caller's. `Uint8Array.from` always allocates, and it copies only the
+ * viewed range of an offset view and only a snapshot of a `SharedArrayBuffer`.
+ */
+const ownedCopy = (body: Uint8Array): Uint8Array => Uint8Array.from(body)
+
+/**
+ * Builds a verifier that compares a signature header in constant time.
+ *
+ * An absent or empty header is refused before `expected` runs, and an
+ * `expected` that answers with zero bytes is refused after it. Neither is a
+ * comparison the constant-time equality can decide: it agrees on two empty
+ * byte strings, so a request carrying no signature at all would have
+ * authenticated against a secret that resolved to the empty string. A
+ * zero-length expected signature is a misconfigured credential, never a valid
+ * one, so the door stays closed instead of opening for everyone.
+ *
+ * Every refusal carries the same message, `webhook signature in <header> did
+ * not verify`, whatever the reason. A failure raised by `expected` is kept in
+ * `cause` only: its message names the credential reference or the resolver
+ * that could not produce a secret, which is a host detail, and the refusal
+ * that answers a bad signature answers a broken resolver the same way.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeSignatureVerifier = (config: SignatureConfig): Channel.Verify => (raw, credential) => {
+  const refuse = (cause?: TriggerError) =>
+    Effect.fail(
+      new TriggerError({
+        code: "verification_failed",
+        message: `webhook signature in ${config.header} did not verify`,
+        ...(cause === undefined ? {} : { cause })
+      })
+    )
+  return Effect.suspend(() => {
+    const supplied = raw.headers[config.header.toLowerCase()] ?? raw.headers[config.header]
+    if (supplied === undefined || supplied.length === 0) {
+      return refuse()
+    }
+    const actual = new TextEncoder().encode(supplied)
+    // The verifier gets its own copy: nothing it does to these bytes can reach
+    // the buffer that is about to be fingerprinted and decoded.
+    return config.expected(ownedCopy(raw.body), credential).pipe(
+      Effect.matchEffect({
+        onFailure: (error) => refuse(error),
+        onSuccess: (expected) =>
+          expected.length > 0 && constantTimeEqual(expected, actual)
+            ? Effect.void
+            : refuse()
+      })
+    )
+  })
+}
+
+/**
+ * Webhook declaration configuration.
+ *
+ * `credential` is required. It used to default to a reference named after the
+ * channel, so a webhook declared without one verified against whatever
+ * credential happened to share its name instead of being refused, and two
+ * declarations differing only in credential verified identically.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Config<Payload, Outbound = never> extends Channel.Config<Payload, RunSummary, Outbound> {
+  readonly credential: Redacted.Redacted<CredentialRef>
+}
+
+/**
+ * A webhook door that can only ingest through `Channels` and `Control`.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface Webhook {
+  readonly name: string
+  readonly register: Effect.Effect<void, never, ControlChannels.Channels>
+  readonly ingest: (
+    raw: Channel.RawInbound
+  ) => Effect.Effect<Receipt, ControlError | TriggerError, ControlChannels.Channels>
+}
+
+const invalidInput = (issue: string): InvalidInput => new InvalidInput({ issue })
+
+const toControlChannel = <Payload, Outbound>(
+  config: Config<Payload, Outbound>
+): ControlChannels.Channel<Payload> => {
+  const channel = ControlWebhook.make({
+    name: config.name,
+    schema: config.schema,
+    credential: config.credential,
+    // The message is fixed here rather than forwarded from the verifier: a
+    // custom `verify` may say why it refused, and that reason travels toward
+    // the unauthenticated sender on the same error that answers a bad
+    // signature. `Unauthorized` carries no cause, so nothing else survives
+    // the crossing.
+    verify: (raw, credential) =>
+      config.verify(raw, credential).pipe(
+        Effect.mapError(() => new Unauthorized({ message: `webhook ${config.name} did not verify the request` }))
+      ),
+    map: (payload) => {
+      const inbound = config.inbound(payload)
+      if ("start" in inbound) {
+        return Effect.succeed({
+          _tag: "Start" as const,
+          flowId: inbound.start.flowId,
+          input: inbound.start.input
+        })
+      }
+      return Schema.decodeUnknownEffect(Schema.Json)(inbound.signal.value).pipe(
+        Effect.map(
+          (value) => ({
+            _tag: "Signal" as const,
+            runId: inbound.signal.runId,
+            signal: {
+              name: inbound.signal.stepId,
+              payload: value
+            }
+          })
+        ),
+        Effect.mapError((error) => invalidInput(String(error)))
+      )
+    },
+    project: (run) => {
+      if (config.outbound === undefined) {
+        return {
+          cursor: String(run.updatedAt),
+          operation: "noop" as const,
+          message: null
+        }
+      }
+      return {
+        cursor: String(run.updatedAt),
+        operation: "post" as const,
+        message: config.outbound(run)
+      }
+    }
+  })
+  return channel
+}
+
+/**
+ * Builds a webhook door whose only dispatch path is the Control channel
+ * coordinator.
+ *
+ * Verification occurs inside `Channels.ingest` before the adapter's JSON or
+ * schema decoder and before any Control operation.
+ *
+ * `ingest` does not register: a channel is registered once, deliberately,
+ * through {@link Webhook.register}, so traffic to an unregistered channel is
+ * reported as unavailable rather than silently self-registering the door it
+ * arrived at.
+ *
+ * `ingest` also copies `body`, `headers`, and `idempotencyKey` before anything
+ * reads them. Verification, delivery fingerprinting, and decoding then all see
+ * one private snapshot, so a verifier that edits the bytes it was handed, or a
+ * caller that mutates its own object between building this Effect and running
+ * it, cannot authenticate one payload and have another decoded. A
+ * `SharedArrayBuffer`-backed view is copied out of shared memory by the same
+ * step.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = <Payload, Outbound = never>(
+  config: Config<Payload, Outbound>
+): Webhook => {
+  const channel = toControlChannel(config)
+  const register = Effect.flatMap(ControlChannels.Channels, (channels) => channels.register(channel))
+  return {
+    name: config.name,
+    register,
+    ingest: (raw) => {
+      // Copied here rather than inside the Effect: the copy has to happen when
+      // the caller hands the request over, not when the returned Effect
+      // eventually runs, or a caller that reuses its own buffer in between
+      // changes what gets authenticated.
+      const snapshot: Channel.RawInbound = {
+        body: ownedCopy(raw.body),
+        headers: { ...raw.headers },
+        idempotencyKey: raw.idempotencyKey
+      }
+      return Effect.gen(function*() {
+        const channels = yield* ControlChannels.Channels
+        return yield* channels.ingest({ channel: config.name, raw: snapshot })
+      }).pipe(
+        Effect.mapError((error) =>
+          error instanceof Unauthorized
+            ? new TriggerError({
+              code: "verification_failed",
+              message: `webhook ${config.name} did not verify the request`,
+              cause: error
+            })
+            : error
+        )
+      )
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * `/triggers` — durable schedules and verified inbound channels.
+ *
+ * @since 0.1.0
+ */
+
+/** @category errors @since 0.1.0 */
+export * as TriggerError from "./TriggerError.ts"
+/** @category schedules @since 0.1.0 */
+export * as Cron from "./Cron.ts"
+/** @category declarations @since 0.1.0 */
+export * as Trigger from "./Trigger.ts"
+/** @category declarations @since 0.1.0 */
+export * as Schedule from "./Schedule.ts"
+/** @category policies @since 0.1.0 */
+export * as Overlap from "./Overlap.ts"
+/** @category policies @since 0.1.0 */
+export * as CatchUp from "./CatchUp.ts"
+/** @category services @since 0.1.0 */
+export * as TriggerStore from "./TriggerStore.ts"
+/** @category services @since 0.1.0 */
+export * as SqlTriggerStore from "./SqlTriggerStore.ts"
+/** @category scheduling @since 0.1.0 */
+export * as Scheduler from "./Scheduler.ts"
+/** @category services @since 1.0.0-rc.0 */
+export * as DispatchReader from "./DispatchReader.ts"
+/** @category channels @since 0.1.0 */
+export * as Channel from "./Channel.ts"
+/** @category webhooks @since 0.1.0 */
+export * as Webhook from "./Webhook.ts"

package/src/internal/ActiveRuns.ts

@@ -0,0 +1,83 @@
+/**
+ * What one scheduler process knows about the run each trigger owns.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as Effect from "effect/Effect"
+import type * as Fiber from "effect/Fiber"
+import * as Ref from "effect/Ref"
+
+/**
+ * What this process knows about the run one trigger currently owns: which
+ * occurrence claimed it, the reservation or run id the store holds for it, and
+ * the monitor fiber when this process is the one watching it.
+ *
+ * `runId` is always known. A claim that hands out work names the reservation it
+ * wrote, and a recovered entry is read back from the store, so an entry with
+ * nothing to release cannot be constructed.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export interface Active {
+  readonly occurrence: number
+  readonly runId: string
+  readonly fiber?: Fiber.Fiber<void> | undefined
+}
+
+/**
+ * The entries of one scheduler, keyed by trigger id.
+ *
+ * `take` is the only unfenced write: an occurrence that claimed the trigger,
+ * or a run recovered from the store, replaces whatever entry was there. Every
+ * later write is fenced on the occurrence that took the entry, so one guard
+ * states the rule once: a launch that has been superseded, or whose run
+ * already settled, no longer owns the entry and must not write to it. Spelling
+ * the fence out at each site is how the three copies of it drifted apart.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export interface ActiveRuns {
+  readonly get: (triggerId: string) => Effect.Effect<Active | undefined>
+  readonly take: (triggerId: string, entry: Active) => Effect.Effect<void>
+  readonly update: (
+    triggerId: string,
+    occurrence: number,
+    change: (entry: Active) => Active
+  ) => Effect.Effect<void>
+  readonly remove: (triggerId: string, occurrence: number) => Effect.Effect<void>
+}
+
+/**
+ * Allocates an empty set of entries.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const make: Effect.Effect<ActiveRuns> = Effect.map(
+  Ref.make<ReadonlyMap<string, Active>>(new Map()),
+  (entries) => {
+    const fenced = (
+      triggerId: string,
+      occurrence: number,
+      change: (entry: Active) => Active | undefined
+    ): Effect.Effect<void> =>
+      Ref.update(entries, (current) => {
+        const entry = current.get(triggerId)
+        if (entry?.occurrence !== occurrence) return current
+        const next = new Map(current)
+        const updated = change(entry)
+        if (updated === undefined) next.delete(triggerId)
+        else next.set(triggerId, updated)
+        return next
+      })
+    return {
+      get: (triggerId) => Effect.map(Ref.get(entries), (current) => current.get(triggerId)),
+      take: (triggerId, entry) => Ref.update(entries, (current) => new Map(current).set(triggerId, entry)),
+      update: fenced,
+      remove: (triggerId, occurrence) => fenced(triggerId, occurrence, () => undefined)
+    }
+  }
+)

package/src/internal/DueOccurrences.ts

@@ -0,0 +1,101 @@
+/**
+ * Which occurrences one scheduler tick owes a trigger.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as CatchUp from "../CatchUp.ts"
+import * as Cron from "../Cron.ts"
+import type { TriggerError } from "../TriggerError.ts"
+import type { Registered } from "../TriggerStore.ts"
+
+/**
+ * The occurrences to claim, oldest first, and the watermark that stands once
+ * every one of them has been dispatched.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export interface Due {
+  readonly occurrences: ReadonlyArray<number>
+  readonly watermark: number
+}
+
+// A bound the declaration cannot honour is a statement about how much history
+// to replay, not a reason to stop scheduling: the backlog beyond the bound is
+// abandoned, loudly, and the current occurrence still fires.
+const withinBound = (
+  triggerId: string,
+  owed: Effect.Effect<ReadonlyArray<Date>, TriggerError>
+): Effect.Effect<ReadonlyArray<Date>, TriggerError> =>
+  Effect.catch(owed, (error) =>
+    error.code === "catch_up_bound_exceeded"
+      ? Effect.as(
+        Effect.annotateLogs(
+          Effect.logWarning("A trigger abandoned catch-up work beyond its bound", error),
+          { triggerId }
+        ),
+        [] as ReadonlyArray<Date>
+      )
+      : Effect.fail(error))
+
+/**
+ * Computes what a trigger owes at `now`, given the watermark this process has
+ * already dispatched through, or `undefined` on first sight of the trigger.
+ *
+ * The answer depends on nothing but its arguments. The watermark is the
+ * caller's to keep: it only moves forward, and only past occurrences the
+ * caller finished dispatching.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const compute = (
+  trigger: Registered,
+  now: number,
+  observed: number | undefined
+): Effect.Effect<Due, TriggerError> =>
+  Effect.gen(function*() {
+    const cron = yield* Cron.parse(trigger.cron, trigger.timezone)
+    const current = (yield* Cron.previousAtOrBefore(cron, new Date(now))).getTime()
+    if (observed === undefined) {
+      // First sight of this trigger in this process. A trigger that has never
+      // fired starts from here rather than from whatever occurrence last
+      // passed: registering a weekly trigger on a Sunday evening owes nothing
+      // for the Monday six days gone, which is what `catchUp` says.
+      if (trigger.lastFiredAt === undefined) return { occurrences: [], watermark: current }
+      if (current <= trigger.lastFiredAt) return { occurrences: [], watermark: current }
+      const owed = yield* withinBound(
+        trigger.id,
+        CatchUp.occurrences(
+          trigger.catchUp,
+          trigger.maxCatchUp,
+          new Date(trigger.lastFiredAt),
+          new Date(now),
+          cron
+        )
+      )
+      // The current boundary is owed whatever the policy says about the
+      // backlog, exactly as on every later poll. Under `none`, or once the
+      // bound abandoned the backlog, a restart used to skip it.
+      const occurrences = owed.map((occurrence) => occurrence.getTime())
+      if (occurrences.at(-1) !== current) occurrences.push(current)
+      return { occurrences, watermark: current }
+    }
+    if (current <= observed) return { occurrences: [], watermark: observed }
+    const backlog = yield* withinBound(
+      trigger.id,
+      CatchUp.occurrences(
+        trigger.catchUp,
+        trigger.maxCatchUp,
+        new Date(observed),
+        new Date(current - 1),
+        cron
+      )
+    )
+    return {
+      occurrences: [...backlog.map((occurrence) => occurrence.getTime()), current],
+      watermark: current
+    }
+  })

package/src/internal/WallClock.ts

@@ -0,0 +1,172 @@
+/**
+ * Wall-clock cron occurrences in a time zone, daylight saving included.
+ *
+ * A cron expression names wall-clock times. Searching those times with a UTC
+ * cron is exact, so the zone only matters when a wall time is turned into an
+ * instant:
+ *
+ * - A wall time that exists once is that instant.
+ * - A wall time inside a spring-forward gap fires at the instant it would have
+ *   had on the old offset: a daily 02:30 fires at 03:30 daylight time.
+ * - A wall time repeated by fall back fires once, at its first instant. An
+ *   expression whose hour field is every hour fires in both passes instead, so
+ *   an hourly or minutely schedule keeps running through the repeated hour.
+ *
+ * Instants are whole seconds in UTC, so millisecond zeroing never reads the
+ * host's zone.
+ *
+ * @since 1.0.0-rc.1
+ */
+
+import * as EffectCron from "effect/Cron"
+import * as DateTime from "effect/DateTime"
+import * as Option from "effect/Option"
+
+const day = 86_400_000
+const second = 1_000
+
+/** The zone's wall clock minus UTC at an instant, in milliseconds. */
+type Offset = (instant: number) => number
+
+const formatters = new Map<string, Intl.DateTimeFormat>()
+
+const formatter = (timeZone: string): Intl.DateTimeFormat => {
+  let format = formatters.get(timeZone)
+  if (format === undefined) {
+    format = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      hour: "numeric",
+      minute: "numeric",
+      second: "numeric",
+      hourCycle: "h23"
+    })
+    formatters.set(timeZone, format)
+  }
+  return format
+}
+
+const named = (timeZone: string): Offset => (instant) => {
+  const whole = Math.floor(instant / second) * second
+  const fields = { year: 0, month: 1, day: 1, hour: 0, minute: 0, second: 0 }
+  for (const part of formatter(timeZone).formatToParts(whole)) {
+    if (part.type in fields) fields[part.type as keyof typeof fields] = Number(part.value)
+  }
+  const wall = Date.UTC(fields.year, fields.month - 1, fields.day, fields.hour, fields.minute, fields.second)
+  return wall - whole
+}
+
+// Read on every call, so a host whose `TZ` changes is followed.
+const host: Offset = (instant) => -new Date(instant).getTimezoneOffset() * 60_000
+
+const offsetOf = (zone: Option.Option<DateTime.TimeZone>): Offset => {
+  if (Option.isNone(zone)) return host
+  const value = zone.value
+  if (DateTime.isTimeZoneOffset(value)) return () => value.offset
+  return named(value.id)
+}
+
+/**
+ * A cron compiled for wall-clock search.
+ *
+ * @private
+ * @since 1.0.0-rc.1
+ */
+export interface WallCron {
+  readonly wall: EffectCron.Cron
+  readonly offset: Offset
+  readonly everyHour: boolean
+}
+
+const compiled = new WeakMap<EffectCron.Cron, WallCron>()
+
+/**
+ * Compiles an Effect cron once: its fields as a UTC cron over wall-clock
+ * times, and its zone's offset.
+ *
+ * @private
+ * @since 1.0.0-rc.1
+ */
+export const compile = (cron: EffectCron.Cron): WallCron => {
+  let wallCron = compiled.get(cron)
+  if (wallCron === undefined) {
+    wallCron = {
+      wall: EffectCron.make({
+        seconds: cron.seconds,
+        minutes: cron.minutes,
+        hours: cron.hours,
+        days: cron.days,
+        months: cron.months,
+        weekdays: cron.weekdays,
+        // Whether day of month and weekday must both match. Effect keeps the
+        // flag off its public type, but `make` takes it and every cron has it.
+        and: (cron as EffectCron.Cron & { readonly and: boolean }).and,
+        tz: DateTime.zoneMakeNamedUnsafe("UTC")
+      }),
+      offset: offsetOf(cron.tz),
+      everyHour: cron.hours.size === 0 || cron.hours.size === 24
+    }
+    compiled.set(cron, wallCron)
+  }
+  return wallCron
+}
+
+/** The offsets in force from a day before an instant to a day after it. */
+const near = (cron: WallCron, instant: number): ReadonlyArray<number> => [
+  cron.offset(instant - day),
+  cron.offset(instant),
+  cron.offset(instant + day)
+]
+
+/** The instants one matching wall time fires at, earliest first. */
+const resolve = (cron: WallCron, wall: number): ReadonlyArray<number> => {
+  const before = cron.offset(wall - day)
+  const after = cron.offset(wall + day)
+  const candidates = before === after ? [before] : [before, after]
+  const valid = candidates.map((offset) => wall - offset).filter((instant) => cron.offset(instant) === wall - instant)
+  // No offset reads this wall time back: it is inside a gap.
+  if (valid.length === 0) return [wall - before]
+  valid.sort((left, right) => left - right)
+  return cron.everyHour ? valid : valid.slice(0, 1)
+}
+
+/**
+ * The first occurrence strictly after `from`. Throws when the wall-clock search
+ * is exhausted.
+ *
+ * @private
+ * @since 1.0.0-rc.1
+ */
+export const next = (cron: WallCron, from: number): number => {
+  // Every wall time that can fire after `from` lies after `from` plus the
+  // smallest nearby offset.
+  let wall = from + Math.min(...near(cron, from))
+  let best = Number.POSITIVE_INFINITY
+  for (;;) {
+    wall = EffectCron.next(cron.wall, wall).getTime()
+    if (wall - Math.max(...near(cron, wall)) >= best) return best
+    for (const instant of resolve(cron, wall)) if (instant > from && instant < best) best = instant
+  }
+}
+
+/**
+ * The latest occurrence at or before `at`, in whole seconds. Throws when the
+ * wall-clock search is exhausted.
+ *
+ * @private
+ * @since 1.0.0-rc.1
+ */
+export const previousAtOrBefore = (cron: WallCron, at: number): number => {
+  const until = Math.floor(at / second) * second
+  // Every wall time that can fire at or before `until` lies at or before
+  // `until` plus the largest nearby offset.
+  let wall = until + Math.max(...near(cron, until)) + second
+  let best = Number.NEGATIVE_INFINITY
+  for (;;) {
+    wall = EffectCron.prev(cron.wall, wall).getTime()
+    if (wall - Math.min(...near(cron, wall)) <= best) return best
+    for (const instant of resolve(cron, wall)) if (instant <= until && instant > best) best = instant
+  }
+}