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

package/src/CredentialStore.ts

@@ -0,0 +1,152 @@
+/**
+ * Browser-safe persistence port for encrypted credential material.
+ *
+ * The store only ever sees a {@link SealedRecord}: an opaque connection name
+ * plus ciphertext. Plaintext never reaches this boundary, so an adapter can be
+ * backed by anything — SQL, Web Storage, a remote vault — without becoming a
+ * place a secret can leak from.
+ *
+ * Writes are compare-and-set on `version`. A writer that read version *n*
+ * commits version *n + 1*; a concurrent writer that read the same *n* is
+ * refused with {@link ControlError.CredentialConflict} rather than silently
+ * overwriting the winner.
+ *
+ * @since 0.1.0
+ */
+
+import { Context, Effect, Layer, Option } from "effect"
+import { CredentialConflict, Unavailable } from "./ControlError.ts"
+
+/**
+ * One credential at rest: opaque metadata plus the sealed secret.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface SealedRecord {
+  readonly id: string
+  readonly name: string
+  /** Base64 ciphertext produced by a `CredentialCipher`. */
+  readonly ciphertext: string
+  /** Base64 per-record nonce. Never reused across versions. */
+  readonly nonce: string
+  /** Monotonic write counter; 1 for a freshly created credential. */
+  readonly version: number
+  readonly updatedAtMs: number
+}
+
+/**
+ * The persistence operations `Credential` needs.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface Service {
+  readonly list: () => Effect.Effect<ReadonlyArray<SealedRecord>, Unavailable>
+  readonly read: (id: string) => Effect.Effect<Option.Option<SealedRecord>, Unavailable>
+  /** Commits `record` only if the stored version is `record.version - 1`. */
+  readonly write: (record: SealedRecord) => Effect.Effect<void, Unavailable | CredentialConflict>
+  readonly remove: (id: string) => Effect.Effect<void, Unavailable>
+}
+
+/**
+ * Service key for encrypted credential persistence.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class CredentialStore extends Context.Service<CredentialStore, Service>()(
+  "/control/CredentialStore"
+) {}
+
+/**
+ * Constructs a store from an implementation record.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (implementation: Service): Service => CredentialStore.of(implementation)
+
+const unavailable = (): Unavailable =>
+  new Unavailable({
+    feature: "credential storage",
+    ticket: "control-credential-storage"
+  })
+
+/**
+ * A store that reports unavailable persistence for every operation.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeNoop = (overrides: Partial<Service> = {}): Service =>
+  make({
+    list: Effect.fn("CredentialStore.list")(() => Effect.fail(unavailable())),
+    read: Effect.fn("CredentialStore.read")(() => Effect.fail(unavailable())),
+    write: Effect.fn("CredentialStore.write")(() => Effect.fail(unavailable())),
+    remove: Effect.fn("CredentialStore.remove")(() => Effect.fail(unavailable())),
+    ...overrides
+  })
+
+/**
+ * Provides a store that reports unavailable persistence.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = (overrides: Partial<Service> = {}): Layer.Layer<CredentialStore> =>
+  Layer.succeed(CredentialStore)(makeNoop(overrides))
+
+/**
+ * Constructs a process-local store.
+ *
+ * Browser-safe and durable for the lifetime of the process only; it exists so
+ * the credential contract can be exercised without a host adapter, and as the
+ * fallback a short-lived worker can use.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeMemory = (): Service => {
+  const records = new Map<string, SealedRecord>()
+  // SQL adapters serialize each row on both sides of storage. Copying here
+  // keeps the in-memory double from granting callers mutable access to state a
+  // durable store would have isolated.
+  const copy = (record: SealedRecord): SealedRecord => structuredClone(record)
+  return make({
+    list: Effect.fn("CredentialStore.list")(() => Effect.sync(() => Array.from(records.values(), copy))),
+    read: Effect.fn("CredentialStore.read")((id) =>
+      Effect.sync(() => Option.map(Option.fromNullishOr(records.get(id)), copy))
+    ),
+    write: Effect.fn("CredentialStore.write")((record) =>
+      Effect.suspend(() => {
+        const current = records.get(record.id)
+        const actual = current?.version ?? 0
+        if (actual !== record.version - 1) {
+          return Effect.fail(
+            new CredentialConflict({
+              id: record.id,
+              expectedVersion: record.version - 1,
+              actualVersion: actual
+            })
+          )
+        }
+        records.set(record.id, copy(record))
+        return Effect.void
+      })
+    ),
+    remove: Effect.fn("CredentialStore.remove")((id) =>
+      Effect.sync(() => {
+        records.delete(id)
+      })
+    )
+  })
+}
+
+/**
+ * Provides a process-local store.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerMemory: Layer.Layer<CredentialStore> = Layer.sync(CredentialStore)(makeMemory)

package/src/DispatchReader.ts

@@ -0,0 +1,122 @@
+/**
+ * Read port from the control plane into a trigger store.
+ *
+ * `Control.list` answers `{ _tag: "triggers" }` and `{ _tag: "fires" }` through
+ * this port. The port lives here rather than in `@smthrs/triggers` because that
+ * package already depends on this one (its scheduler launches runs through
+ * `Control`), so the adapter over a real `TriggerStore` is composed by the host
+ * and the plane only ever sees the interface.
+ *
+ * A composition that provides no reader, or provides {@link layerNone}, makes
+ * `Control.list` refuse the two variants with a typed `InvalidInput` naming the
+ * gap. It never answers an empty page: an empty page means "this host has no
+ * triggers", and a host that cannot read its store has no grounds to say so.
+ *
+ * @since 1.0.0
+ */
+
+import { Context, Effect, Layer } from "effect"
+import type { ControlError } from "./ControlError.ts"
+import { InvalidInput } from "./ControlError.ts"
+import type { FireSummary, ListRequest, TriggerSummary } from "./ControlSchema.ts"
+
+/**
+ * The `triggers` listing request as the port receives it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type TriggersRequest = Extract<ListRequest, { readonly _tag: "triggers" }>
+
+/**
+ * The `fires` listing request as the port receives it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type FiresRequest = Extract<ListRequest, { readonly _tag: "fires" }>
+
+/**
+ * The reader `Control.list` pages trigger and fire rows from.
+ *
+ * Each method receives the whole request and answers every row it has for it,
+ * newest fire first. A reader may narrow by the request's `filters` (a SQL
+ * adapter pushes them into the query); `Control.list` applies the same filters
+ * again and pages the rows with `cursor` and `limit`, so a reader that returns
+ * every row is still correct. Paging stays in the plane so both variants page
+ * exactly as `flows` and `runs` do.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export interface Service {
+  readonly list: (request: TriggersRequest) => Effect.Effect<ReadonlyArray<TriggerSummary>, ControlError>
+  readonly fires: (request: FiresRequest) => Effect.Effect<ReadonlyArray<FireSummary>, ControlError>
+}
+
+/**
+ * The {@link Service} tag.
+ *
+ * @category services
+ * @since 1.0.0
+ */
+export class DispatchReader extends Context.Service<DispatchReader, Service>()(
+  "/control/DispatchReader"
+) {}
+
+/**
+ * The refusal a host without a trigger store answers both variants with.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const noStoreIssue = "this host serves no trigger store"
+
+/**
+ * The typed refusal for a host without a trigger store: `InvalidInput` with
+ * code `invalid_input` and {@link noStoreIssue} as the issue, the same shape
+ * `Control.list` refuses an unsupported run filter with.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const refuse = (): InvalidInput => new InvalidInput({ issue: noStoreIssue })
+
+/**
+ * Builds a {@link Service} from an implementation of its methods.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (implementation: Service): Service => DispatchReader.of(implementation)
+
+/**
+ * A {@link Service} that serves no trigger store: both methods fail with
+ * {@link refuse}.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeNone = (): Service =>
+  make({
+    list: Effect.fn("DispatchReader.list")(() => Effect.fail(refuse())),
+    fires: Effect.fn("DispatchReader.fires")(() => Effect.fail(refuse()))
+  })
+
+/**
+ * Provides {@link DispatchReader} from an implementation.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layer = (implementation: Service): Layer.Layer<DispatchReader> =>
+  Layer.succeed(DispatchReader)(make(implementation))
+
+/**
+ * Provides {@link makeNone}: a reader that refuses both listings because this
+ * host serves no trigger store.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerNone: Layer.Layer<DispatchReader> = Layer.succeed(DispatchReader)(makeNone())