sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ RuntimeContext.ts

import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import type { CallbackFactory } from "./Callback.ts";
import type { HttpEffect } from "./Http.ts";
import type { Output } from "./Output.ts";

export interface BaseRuntimeContext {
  Type: string;
  id: string;
  env: Record<string, any>;
  /**
   * Read a value by its (already-canonical) key. The key is used verbatim;
   * callers must {@link sanitizeKey} first. See {@link sanitizeKey}.
   */
  get<T>(key: string): Effect.Effect<T | undefined>;
  /**
   * Store an output under the given (already-canonical) key, returning the key.
   * The key is used verbatim; callers must {@link sanitizeKey} first.
   */
  set(id: string, output: Output): Effect.Effect<string>;
  exports?: Effect.Effect<Record<string, any>>;
  /** Register a durable callback in the current host instance, when supported. */
  makeCallback?: CallbackFactory;
  serve?<Req = never>(
    handler: HttpEffect<Req>,
    options?: { shape?: Record<string, unknown> },
  ): Effect.Effect<void, never, Req>;
  shape?: () => Record<string, unknown>;
  /** additional services to provide to the plan  */
  planServices?: Layer.Layer<any>;
  /**
   * Services the host provides its init in every phase, built over the
   * instance (e.g. a Cloudflare Worker's `WebhookHost`), so user code
   * doesn't provide them itself.
   */
  hostServices?: Layer.Layer<any, never, any>;
  /**
   * Telemetry exporter Layer registered during init via
   * `Telemetry.layer(...)` / `Telemetry.layerOtlp(...)` (see Telemetry.ts).
   * The runtime bridges build it into every event's request scope,
   * overriding the env-driven default.
   */
  telemetry?: Layer.Layer<never, any, any>;
}

/**
 * Keys a Platform's Init captured through {@link BaseRuntimeContext.set}
 * (`yield* Config.x(...)`, `yield* output`). `Platform.make` attaches the
 * runtime context to the resource and merges these values into its
 * `props.env`.
 */
export const capturedEnvKeys = (resource: unknown): string[] => {
  const ctx = (resource as { RuntimeContext?: Partial<BaseRuntimeContext> })?.RuntimeContext;
  return ctx?.env ? Object.keys(ctx.env) : [];
};

/**
 * Canonicalize a logical key into a key that is safe to use as the name of an
 * environment variable / binding (`[a-zA-Z][a-zA-Z0-9_]*`).
 *
 * `RuntimeContext.set`/`get` are dumb key/value stores: they read and write the
 * key **verbatim**. It is the *caller's* responsibility to hand them a
 * canonical key, since the caller is the one that knows the logical key may
 * contain `.`/`-` (e.g. a dotted config name from `Platform`, or an
 * `Output.toString()` like `"QueueSinkQueue.queueUrl"`). Callers run the key
 * through this before calling `set`/`get` so both sides agree.
 */
export const sanitizeKey = (key: string): string => key.replaceAll(/[^a-zA-Z0-9]/g, "_");

/**
 * The wire format `RuntimeContext.set`/`get` use to carry a `Redacted` value
 * through an environment variable. `JSON.stringify(Redacted)` emits the
 * literal string `"<redacted>"` and loses the value, so secrets are
 * serialized as this marker and the runtime `get` path rebuilds the wrapper.
 */
export interface RedactedMarker {
  readonly _tag: "Redacted";
  readonly value: unknown;
}

/**
 * Detect the (already JSON-parsed) {@link RedactedMarker} shape. After
 * `JSON.parse` the marker is a plain object — `Redacted.isRedacted` is
 * always `false` on it — so detection is structural.
 */
export const isRedactedMarker = (value: unknown): value is RedactedMarker =>
  typeof value === "object" &&
  value !== null &&
  (value as { _tag?: unknown })._tag === "Redacted" &&
  "value" in value;

/**
 * Returns true when {@link unpackEnvValue}'s `JSON.parse` would reinterpret
 * the raw string as something other than itself — a number (`"123"`), a
 * boolean, `null`, or a JSON document. Such strings must stay
 * `JSON.stringify`-packed; everything else round-trips verbatim through the
 * parse-failure fallback.
 */
const parsesAsJson = (value: string): boolean => {
  try {
    JSON.parse(value);
    return true;
  } catch {
    return false;
  }
};

/**
 * Serialize a binding value for an env var: `Redacted` values are packed as
 * a {@link RedactedMarker}, non-string values as JSON.
 *
 * A plain string is stored **verbatim** whenever `JSON.parse` would reject
 * it — which is almost every real-world string (names, URLs, ids). Packing
 * those too would put `"my-queue"` (quote characters included) on the wire,
 * where anything that consumes the raw binding without going through
 * {@link unpackEnvValue} — the Cloudflare dashboard, a hand-written env
 * read, a queue-name comparison against `MessageBatch.queue` — sees the
 * quoted form and mismatches (#1243). Only ambiguous strings (`"123"`,
 * `"null"`, JSON documents) keep the pack so the read side can't
 * reinterpret them.
 */
export const packEnvValue = (value: unknown): string =>
  Redacted.isRedacted(value)
    ? JSON.stringify({
        _tag: "Redacted",
        value: Redacted.value(value),
      } satisfies RedactedMarker)
    : typeof value === "string" && !parsesAsJson(value)
      ? value
      : JSON.stringify(value);

/**
 * Like {@link packEnvValue}, but a `Redacted` input keeps its `Redacted`
 * wrapper on the *outside* of the packed string, so deploy-time code can
 * route secrets through a dedicated channel (Cloudflare `secret_text`,
 * Secrets Store) instead of leaking them as plain env vars. The inner
 * payload still carries the marker for the runtime `get` accessor.
 */
export const packEnvValueKeepRedacted = (value: unknown): string | Redacted.Redacted<string> =>
  Redacted.isRedacted(value) ? value.pipe(packEnvValue, Redacted.make) : packEnvValue(value);

// Only JSON's four whitespace characters may precede a valid JSON value.
const possibleJson = /^[\x20\t\r\n]*["{[0-9tfn-]/;

/**
 * Parse an env-var string produced by {@link packEnvValue} back into its
 * value: rebuild `Redacted` from the marker, return other JSON values
 * as-is, and fall back to the raw string for non-JSON input (a verbatim
 * string from `packEnvValue`, or an env var the user set directly).
 * `undefined` passes through.
 *
 * Runtime `get` accessors MUST feed this from the raw environment
 * (`process.env[key]` / the platform env object) — never through
 * `Config.String`: the ambient runtime `ConfigProvider` reifies bound
 * values (unwrapping the marker before it could be detected here), and
 * during init the ambient provider is the interceptor installed in
 * `Platform.ts`, whose runtime branch calls back into `ctx.get(key)` —
 * resolving through `Config` would re-enter it for the same key and
 * recurse forever.
 */
export const unpackEnvValue = <T>(raw: string | undefined): T | undefined => {
  if (raw === undefined) {
    return undefined;
  }
  if (typeof raw === "string" && !possibleJson.test(raw)) {
    return raw as unknown as T;
  }
  try {
    const parsed: unknown = JSON.parse(raw);
    if (isRedactedMarker(parsed)) {
      return Redacted.make(parsed.value) as unknown as T;
    }
    return parsed as T;
  } catch {
    return raw as unknown as T; // assume it's just a string
  }
};

/**
 * Context of the runtime environment.
 *
 * E.g. the context of a running Worker, Task, Process, Function
 */
export class RuntimeContext extends Context.Service<RuntimeContext, BaseRuntimeContext>()(
  "RuntimeContext",
) {
  static phantom = Layer.empty as Layer.Layer<RuntimeContext>;
}

export const CurrentRuntimeContext = Effect.serviceOption(RuntimeContext).pipe(
  Effect.map(Option.getOrUndefined),
);