@ontrails/cloudflare 0.2.0

package/src/env.ts

@@ -0,0 +1,309 @@
+/**
+ * The Cloudflare env bridge.
+ *
+ * Worker bindings (KV, D1, R2, queues) arrive per-request on the `env`
+ * argument of the Worker `fetch` handler. Trails resources are authored as
+ * ordinary `resource()` definitions, so this module provides the seam that
+ * connects the two: a subpath registers an {@link EnvBindingSpec} for each
+ * resource definition it authors, and the Workers materializer resolves those
+ * specs against the live `env` into per-materialization resource overrides.
+ *
+ * Overrides are re-resolved whenever a new `env` object arrives, and core
+ * resolves overrides before its singleton resource cache, so no resource
+ * instance can capture a stale env. Every Cloudflare service subpath consumes
+ * this one seam.
+ */
+
+import {
+  InternalError,
+  matchesTrailPattern,
+  Result,
+  filterSurfaceTrails,
+  isLiveTrailVersionEntry,
+} from '@ontrails/core';
+import type {
+  AnyResource,
+  BaseSurfaceOptions,
+  ResourceOverrideMap,
+  Topo,
+  Trail,
+} from '@ontrails/core';
+
+/**
+ * The ambient Worker environment: bindings keyed by their wrangler-configured
+ * names. Values are runtime binding objects (KV namespaces, D1 databases,
+ * R2 buckets, queues), so they are typed as `unknown` and narrowed by each
+ * subpath.
+ */
+export type WorkersEnv = Readonly<Record<string, unknown>>;
+
+/**
+ * How a resource definition materializes from the Worker env.
+ *
+ * `fromEnv` receives the raw binding value found at `env[binding]` and either
+ * narrows it into the resource instance or explains why the binding does not
+ * match the resource's expectations.
+ */
+export interface EnvBindingSpec {
+  /** The wrangler binding name to read from the Worker env. */
+  readonly binding: string;
+  /** Narrow the raw binding value into the resource instance. */
+  readonly fromEnv: (value: unknown) => Result<unknown, Error>;
+}
+
+const envBindings = new WeakMap<AnyResource, EnvBindingSpec>();
+
+/**
+ * Register an env binding for a resource definition.
+ *
+ * Called by Cloudflare subpaths (and available to apps authoring their own
+ * env-bound resources) so the Workers materializer knows how to build the
+ * resource instance from the per-request env.
+ *
+ * @example
+ * ```ts
+ * import { resource, Result } from '@ontrails/core';
+ * import { registerEnvBinding } from '@ontrails/cloudflare/workers';
+ *
+ * const queue = resource<{ send(body: string): Promise<void> }>('outbox', {
+ *   create: () => Result.err(new Error('outbox is only available on Workers')),
+ *   mock: () => ({ send: () => Promise.resolve() }),
+ * });
+ * registerEnvBinding(queue, {
+ *   binding: 'OUTBOX',
+ *   fromEnv: (value) => Result.ok(value),
+ * });
+ * ```
+ */
+export const registerEnvBinding = (
+  resourceDefinition: AnyResource,
+  spec: EnvBindingSpec
+): void => {
+  envBindings.set(resourceDefinition, spec);
+};
+
+/**
+ * Read the env binding registered for a resource definition, if any.
+ *
+ * @example
+ * ```ts
+ * import { getEnvBinding } from '@ontrails/cloudflare/workers';
+ * import { cloudflareKv } from '@ontrails/cloudflare/kv';
+ *
+ * const flags = cloudflareKv('flags', { binding: 'FLAGS' });
+ * getEnvBinding(flags)?.binding; // 'FLAGS'
+ * ```
+ */
+export const getEnvBinding = (
+  resourceDefinition: AnyResource
+): EnvBindingSpec | undefined => envBindings.get(resourceDefinition);
+
+/**
+ * Options for {@link buildEnvResourceOverrides}.
+ *
+ * `exclude`/`include`/`intent` mirror the fetch kernel's surface selection so
+ * env resolution only considers trails the surface actually exposes — a
+ * filtered-out trail's bindings are never required. `except` names resource
+ * IDs already provided explicitly, which skip env resolution entirely.
+ */
+export interface BuildEnvResourceOverridesOptions extends Pick<
+  BaseSurfaceOptions,
+  'exclude' | 'include' | 'intent'
+> {
+  /** Resource IDs already provided explicitly; env resolution skips them. */
+  readonly except?: readonly string[] | undefined;
+  /** Worker entrypoint whose reachable resources should be materialized. */
+  readonly entrypoint?: 'fetch' | 'queue' | undefined;
+  /** Physical queue delivered to the current queue entrypoint. */
+  readonly queue?: string | undefined;
+}
+
+const isInternalTrail = (
+  graphTrail: Trail<unknown, unknown, unknown>
+): boolean =>
+  graphTrail.visibility === 'internal' ||
+  graphTrail.meta?.['internal'] === true;
+
+const matchesAnyPattern = (
+  trailId: string,
+  patterns: readonly string[] | undefined
+): boolean =>
+  patterns !== undefined &&
+  patterns.some((pattern) => matchesTrailPattern(trailId, pattern));
+
+const passesIncludeFilter = (
+  trailId: string,
+  include: readonly string[] | undefined
+): boolean =>
+  include === undefined ||
+  include.length === 0 ||
+  matchesAnyPattern(trailId, include);
+
+/**
+ * Mirror of Worker activation eligibility for one entrypoint. Activation
+ * consumers are skipped by `filterSurfaceTrails`, so the bridge selects them
+ * explicitly without making fetch depend on queue-only resources.
+ */
+const isEligibleWorkerActivationTrail = (
+  graphTrail: Trail<unknown, unknown, unknown>,
+  options: BuildEnvResourceOverridesOptions
+): boolean => {
+  const activationKind =
+    (options.entrypoint ?? 'fetch') === 'queue' ? 'queue' : 'webhook';
+  const hasWorkerActivationSource = graphTrail.activationSources.some(
+    (activation) =>
+      activation.source.kind === activationKind &&
+      (activationKind !== 'queue' ||
+        options.queue === undefined ||
+        (typeof activation.source.queue === 'string' &&
+          activation.source.queue.trim() === options.queue))
+  );
+  if (!hasWorkerActivationSource) {
+    return false;
+  }
+  if (
+    isInternalTrail(graphTrail) &&
+    !options.include?.includes(graphTrail.id)
+  ) {
+    return false;
+  }
+  if (matchesAnyPattern(graphTrail.id, options.exclude)) {
+    return false;
+  }
+  if (!passesIncludeFilter(graphTrail.id, options.include)) {
+    return false;
+  }
+  return (
+    options.intent === undefined ||
+    options.intent.length === 0 ||
+    options.intent.includes(graphTrail.intent)
+  );
+};
+
+const collectSurfaceEligibleTrails = (
+  graph: Topo,
+  options: BuildEnvResourceOverridesOptions
+): readonly Trail<unknown, unknown, unknown>[] => {
+  const trails = graph.list();
+  const eligible = new Map<string, Trail<unknown, unknown, unknown>>();
+  if ((options.entrypoint ?? 'fetch') === 'fetch') {
+    const filtered = filterSurfaceTrails(trails, {
+      exclude: options.exclude,
+      include: options.include,
+      intent: options.intent,
+    });
+    for (const graphTrail of filtered) {
+      eligible.set(graphTrail.id, graphTrail);
+    }
+  }
+  for (const graphTrail of trails) {
+    if (
+      !eligible.has(graphTrail.id) &&
+      isEligibleWorkerActivationTrail(graphTrail, options)
+    ) {
+      eligible.set(graphTrail.id, graphTrail);
+    }
+  }
+  const byId = new Map(trails.map((graphTrail) => [graphTrail.id, graphTrail]));
+  const pending = [...eligible.values()];
+  for (const graphTrail of pending) {
+    const composedIds = [
+      ...graphTrail.composes,
+      ...Object.values(graphTrail.versions ?? {})
+        .filter(isLiveTrailVersionEntry)
+        .flatMap((entry) => entry.composes ?? []),
+    ];
+    for (const reference of composedIds) {
+      const composedId =
+        typeof reference === 'string' ? reference : reference.id;
+      const composed = byId.get(composedId);
+      if (composed !== undefined && !eligible.has(composed.id)) {
+        eligible.set(composed.id, composed);
+        pending.push(composed);
+      }
+    }
+  }
+  return [...eligible.values()];
+};
+
+/**
+ * All resources a trail can execute with: the current contract's declarations
+ * plus any live fork version entry's own `resources`, since core runs
+ * supported historical forks with the entry's resource set.
+ */
+const declaredTrailResources = (
+  graphTrail: Trail<unknown, unknown, unknown>
+): readonly AnyResource[] => [
+  ...graphTrail.resources,
+  ...Object.values(graphTrail.versions ?? {})
+    .filter(isLiveTrailVersionEntry)
+    .flatMap((entry) => entry.resources ?? []),
+];
+
+const collectEnvBoundResources = (
+  graph: Topo,
+  options: BuildEnvResourceOverridesOptions
+): readonly AnyResource[] => {
+  const except = new Set(options.except);
+  const collected = new Map<string, AnyResource>();
+  for (const graphTrail of collectSurfaceEligibleTrails(graph, options)) {
+    for (const declared of declaredTrailResources(graphTrail)) {
+      if (
+        !collected.has(declared.id) &&
+        !except.has(declared.id) &&
+        envBindings.has(declared)
+      ) {
+        collected.set(declared.id, declared);
+      }
+    }
+  }
+  return [...collected.values()];
+};
+
+/**
+ * Resolve every env-bound resource declared by the topo's surface-eligible
+ * trails (including live fork-version resources) into a resource override map
+ * for one Worker env.
+ *
+ * Returns `Result.err` when a required binding is missing from the env or a
+ * binding value fails the resource's narrowing check. Trails filtered off the
+ * surface by `exclude`/`include`/`intent` never require their bindings, and
+ * resource IDs listed in `except` are skipped because the caller already
+ * provides them.
+ *
+ * @example
+ * ```ts
+ * import { buildEnvResourceOverrides } from '@ontrails/cloudflare/workers';
+ *
+ * const overrides = buildEnvResourceOverrides(graph, env);
+ * if (overrides.isErr()) throw overrides.error;
+ * ```
+ */
+export const buildEnvResourceOverrides = (
+  graph: Topo,
+  env: WorkersEnv,
+  options: BuildEnvResourceOverridesOptions = {}
+): Result<ResourceOverrideMap, Error> => {
+  const overrides: Record<string, unknown> = {};
+  for (const declared of collectEnvBoundResources(graph, options)) {
+    const spec = envBindings.get(declared);
+    if (spec === undefined) {
+      continue;
+    }
+    const value = env[spec.binding];
+    if (value === undefined) {
+      return Result.err(
+        new InternalError(
+          `Worker env is missing binding "${spec.binding}" required by resource "${declared.id}". Declare the binding in your wrangler configuration (for example kv_namespaces, d1_databases, r2_buckets, or queues) or provide an explicit resource override.`,
+          { context: { binding: spec.binding, resourceId: declared.id } }
+        )
+      );
+    }
+    const instance = spec.fromEnv(value);
+    if (instance.isErr()) {
+      return instance;
+    }
+    overrides[declared.id] = instance.value;
+  }
+  return Result.ok(overrides);
+};

package/src/facts.ts

@@ -0,0 +1,112 @@
+/**
+ * Cloudflare lock facts.
+ *
+ * The adapter's `trails.lock` overlay overlay: `derive` derives the
+ * topo's env-bound resources (resources with a registered
+ * {@link EnvBindingSpec | env binding}, such as every `cloudflareKv`
+ * definition) into `overlays.cloudflare`, listing the wrangler binding name
+ * each resource resolves from. The import from `@ontrails/adapter-kit` is
+ * type-only — the adapter never depends on the adapter kit at runtime.
+ */
+
+import type { Overlay } from '@ontrails/adapter-kit';
+import type { AnyResource, Topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { getEnvBinding } from './env.js';
+import type { EnvBindingSpec } from './env.js';
+
+const cloudflareFactsSchema = z
+  .object({
+    bindings: z.array(
+      z
+        .object({
+          binding: z.string(),
+          resourceId: z.string(),
+        })
+        .strict()
+    ),
+  })
+  .strict();
+
+/**
+ * The facts embedded at `overlays.cloudflare` in `trails.lock`: one entry
+ * per env-bound resource, pairing the resource ID with its wrangler binding
+ * name.
+ */
+export type CloudflareLockFacts = z.infer<typeof cloudflareFactsSchema>;
+
+/**
+ * Every resource visible on the topo: module-registered resources plus
+ * resources declared on trail contracts (including fork version entries),
+ * which core executes with but `topo()` does not auto-register.
+ */
+const collectTopoResources = (graph: Topo): readonly AnyResource[] => {
+  const collected = new Map<string, AnyResource>();
+  for (const definition of graph.listResources()) {
+    collected.set(definition.id, definition);
+  }
+  for (const graphTrail of graph.list()) {
+    const declared = [
+      ...graphTrail.resources,
+      ...Object.values(graphTrail.versions ?? {}).flatMap(
+        (entry) => entry.resources ?? []
+      ),
+    ];
+    for (const definition of declared) {
+      if (!collected.has(definition.id)) {
+        collected.set(definition.id, definition);
+      }
+    }
+  }
+  return [...collected.values()];
+};
+
+const derive = (graph: Topo): CloudflareLockFacts => {
+  const bindings = collectTopoResources(graph)
+    .map((definition) => ({
+      definition,
+      spec: getEnvBinding(definition),
+    }))
+    .filter(
+      (entry): entry is { definition: AnyResource; spec: EnvBindingSpec } =>
+        entry.spec !== undefined
+    )
+    .map((entry) => ({
+      binding: entry.spec.binding,
+      resourceId: entry.definition.id,
+    }))
+    .toSorted(
+      (a, b) =>
+        a.resourceId.localeCompare(b.resourceId) ||
+        a.binding.localeCompare(b.binding)
+    );
+  return { bindings };
+};
+
+/**
+ * The Cloudflare adapter's `trails.lock` overlay overlay.
+ *
+ * An app opts in by exporting `trailsOverlays` next to its topo export;
+ * `trails compile` then validates `derive(topo)` against the facts schema
+ * and embeds the result as `overlays.cloudflare`, listing every env-bound
+ * resource's wrangler binding. Derivation is deterministic: the same topo
+ * always yields the same facts, sorted by resource ID then binding.
+ *
+ * @example
+ * ```ts
+ * import { cloudflareOverlay, cloudflareKv } from '@ontrails/cloudflare';
+ * import { topo } from '@ontrails/core';
+ *
+ * export const flags = cloudflareKv('flags', { binding: 'FLAGS' });
+ * export const app = topo('my-worker', { flags });
+ * export const trailsOverlays = [cloudflareOverlay];
+ * // `trails compile` embeds overlays.cloudflare:
+ * // { bindings: [{ binding: 'FLAGS', resourceId: 'flags' }] }
+ * ```
+ */
+export const cloudflareOverlay = {
+  derive,
+  namespace: 'cloudflare',
+  schema: cloudflareFactsSchema,
+} satisfies Overlay;

package/src/index.ts

@@ -0,0 +1,96 @@
+/**
+ * `@ontrails/cloudflare` — the Cloudflare adapter collection.
+ *
+ * Service subpaths are the primary entry points:
+ * - `@ontrails/cloudflare/workers` — HTTP surface materializer (fetch handler)
+ * - `@ontrails/cloudflare/kv` — key-value resource
+ * - `@ontrails/cloudflare/d1` — D1-backed store resource
+ * - `@ontrails/cloudflare/r2` — R2 blob/object resource
+ * - `@ontrails/cloudflare/queues` — Queue producer resource and consumer
+ *   materializer
+ *
+ * The root export re-exports the subpaths for convenience and adapter
+ * tooling, and owns the adapter's `trails.lock` overlay overlay
+ * (`cloudflareOverlay`).
+ */
+
+export { cloudflareOverlay } from './facts.js';
+export type { CloudflareLockFacts } from './facts.js';
+export { cloudflareD1, connectD1 } from './d1/index.js';
+export type {
+  CloudflareD1AllResult,
+  CloudflareD1Connection,
+  CloudflareD1Database,
+  CloudflareD1Options,
+  CloudflareD1PreparedStatement,
+  CloudflareD1Resource,
+  CloudflareD1RunResult,
+  ConnectD1Options,
+} from './d1/index.js';
+export {
+  buildEnvResourceOverrides,
+  getEnvBinding,
+  registerEnvBinding,
+} from './env.js';
+export type {
+  BuildEnvResourceOverridesOptions,
+  EnvBindingSpec,
+  WorkersEnv,
+} from './env.js';
+export { cloudflareKv, createMemoryKv } from './kv/index.js';
+export type {
+  CloudflareKv,
+  CloudflareKvListKey,
+  CloudflareKvListOptions,
+  CloudflareKvListResult,
+  CloudflareKvOptions,
+  CloudflareKvPutOptions,
+  CreateMemoryKvOptions,
+} from './kv/index.js';
+export { cloudflareR2, createMemoryR2, r2ObjectToBlobRef } from './r2/index.js';
+export type {
+  CloudflareR2Bucket,
+  CloudflareR2Conditional,
+  CloudflareR2GetOptions,
+  CloudflareR2HttpMetadata,
+  CloudflareR2ListOptions,
+  CloudflareR2Object,
+  CloudflareR2ObjectBody,
+  CloudflareR2Objects,
+  CloudflareR2Options,
+  CloudflareR2PutBody,
+  CloudflareR2PutOptions,
+  CloudflareR2Range,
+  CloudflareR2StorageClass,
+  MemoryCloudflareR2Bucket,
+  R2ObjectToBlobRefOptions,
+} from './r2/index.js';
+export {
+  cloudflareQueue,
+  createMemoryQueue,
+  createQueueHandler,
+} from './queues/index.js';
+export type {
+  CloudflareQueue,
+  CloudflareQueueBatch,
+  CloudflareQueueHandler,
+  CloudflareQueueMessage,
+  CloudflareQueueMetrics,
+  CloudflareQueueOptions,
+  CloudflareQueueRetryOptions,
+  CloudflareQueueSendBatchOptions,
+  CloudflareQueueSendOptions,
+  CloudflareQueueSendRequest,
+  CloudflareQueueSendResult,
+  CloudflareQueuesContentType,
+  CreateQueueHandlerOptions,
+  MemoryCloudflareQueue,
+  MemoryQueueMessage,
+} from './queues/index.js';
+export { createWorkersHandler } from './workers/index.js';
+export type {
+  CloudflareWorker,
+  CreateWorkersHandlerOptions,
+  WorkersExecutionContext,
+  WorkersResourceOverrides,
+} from './workers/index.js';