sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Flagship/ ReadFlagsLocal.ts

import * as LocalFlagship from "@alchemy.run/cloudflare-runtime/core/bindings/flagship";
import type { AlchemyContext } from "alchemy/AlchemyContext";
import type * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import type * as FileSystem from "effect/FileSystem";
import type * as HttpClient from "effect/http/HttpClient";
import * as Layer from "effect/Layer";
import type * as Path from "effect/Path";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Credentials } from "../Credentials.ts";
import { dispatchByMode } from "../LocalGateway.ts";
import type { App } from "./App.ts";
import { localFlagshipStore } from "./Flag.ts";
import {
  type EvaluationContext,
  type EvaluationDetails,
  FlagshipError,
  ReadFlags,
  type ReadFlagsClient,
} from "./ReadFlags.ts";
import { type FlagshipAuth, makeHttpFlagshipClient } from "./ReadFlagsHttpClient.ts";

/**
 * Local implementation of the {@link ReadFlags} binding — evaluates Flagship
 * feature flags over the Cloudflare HTTP API (`GET .../flagship/apps/{appId}/evaluate`)
 * using the **current credentials** instead of a native Worker binding
 * ({@link ReadFlagsBinding}).
 *
 * Provide it on an {@link Action} (or any deploy-time Effect) so you can read
 * flag values with the same `getBooleanValue`/`getStringValue`/… client you'd
 * use inside a Worker:
 *
 * @example Reading a flag from an Action
 * ```typescript
 * const CheckFlag = Alchemy.Action(
 *   "CheckFlag",
 *   Effect.gen(function* () {
 *     const flags = yield* Cloudflare.Flagship.ReadFlags(app);
 *     return Effect.fn(function* () {
 *       return yield* flags.getBooleanValue("new-checkout", false);
 *     });
 *   }).pipe(Effect.provide(Cloudflare.Flagship.ReadFlagsLocal)),
 * );
 * ```
 *
 * The app id is resolved at apply time through the ambient {@link RuntimeContext}
 * (in an Action, that's the resolve context the engine provides around the
 * body), so `ReadFlags(app)` works even though the app is created in the same
 * deploy.
 *
 * Under `alchemy dev`, a locally-emulated app (a `dev:` app id) is evaluated
 * against the local Flagship simulator's definitions with the same rules a
 * dev Worker's binding applies, so the full evaluation context is honored.
 *
 * Limitations vs. the Worker binding for a live app: the HTTP evaluate
 * endpoint only accepts a single `targetingKey` (read from
 * `context.targetingKey`), so attribute-based targeting rules that key off
 * other context fields cannot be exercised. The `raw` runtime binding has no
 * HTTP equivalent and dies if used — see {@link makeHttpFlagshipClient}.
 */
export const ReadFlagsLocal = Layer.effect(
  ReadFlags,
  Effect.gen(function* () {
    // Capture the account resolver without authenticating — only the HTTP
    // branch evaluates it. Credentials are ambient during stack-eval (the
    // stack's providers layer); capture the full context so the evaluate op
    // runs with the current credentials — no `host.bind`, no minted token.
    const environment = yield* CloudflareEnvironment;
    const context = yield* Effect.context<Credentials | HttpClient.HttpClient>();
    // Local evaluation reads the simulator's files.
    const platform = yield* Effect.context<FileSystem.FileSystem | Path.Path | AlchemyContext>();
    const auth: FlagshipAuth = {
      authorize: (eff) => eff.pipe(Effect.provideContext(context)),
      accountId: Effect.map(environment, (env) => env.accountId),
    };

    return Effect.fn(function* (app: App) {
      // Deferred accessor — resolves the appId against the tracker at apply
      // time (in an Action, that's the engine's resolve context).
      const appId = yield* app.appId;
      return dispatchByMode(appId, makeHttpFlagshipClient(auth, appId), (id) =>
        makeLocalFlagshipClient(id, platform),
      );
    });
  }),
);

/**
 * A client over the local Flagship simulator for a `dev:` app: evaluates the
 * app's flag definitions in-process with the same rules a dev Worker's
 * binding applies. `raw` cannot be satisfied — there is no native binding
 * outside a Worker — so it dies with guidance.
 */
const makeLocalFlagshipClient = (
  appId: string,
  platform: Context.Context<FileSystem.FileSystem | Path.Path | AlchemyContext>,
): ReadFlagsClient => {
  const details = <T>(
    flagKey: string,
    defaultValue: T,
    expectedType: LocalFlagship.FlagshipValueType | undefined,
    context: EvaluationContext | undefined,
  ) =>
    localFlagshipStore(appId).pipe(
      Effect.flatMap((store) =>
        LocalFlagship.evaluate(store, { flagKey, defaultValue, expectedType, context }),
      ),
      Effect.map((d) => d as EvaluationDetails<T>),
      Effect.mapError(
        (cause) => new FlagshipError({ message: "Local Flagship evaluation failed", cause }),
      ),
      Effect.provideContext(platform),
    );
  const value = <T>(
    flagKey: string,
    defaultValue: T,
    expectedType: LocalFlagship.FlagshipValueType | undefined,
    context: EvaluationContext | undefined,
  ) => Effect.map(details(flagKey, defaultValue, expectedType, context), (d) => d.value);

  return {
    raw: Effect.die(
      new FlagshipError({
        message:
          "A locally-emulated Flagship app has no native binding outside a Worker; use the evaluation methods.",
        cause: undefined,
      }),
    ),
    get: (flagKey, defaultValue, context) => value(flagKey, defaultValue, undefined, context),
    getBooleanValue: (flagKey, defaultValue, context) =>
      value(flagKey, defaultValue, "boolean", context),
    getStringValue: (flagKey, defaultValue, context) =>
      value(flagKey, defaultValue, "string", context),
    getNumberValue: (flagKey, defaultValue, context) =>
      value(flagKey, defaultValue, "number", context),
    getObjectValue: (flagKey, defaultValue, context) =>
      value(flagKey, defaultValue, "object", context),
    getBooleanDetails: (flagKey, defaultValue, context) =>
      details(flagKey, defaultValue, "boolean", context),
    getStringDetails: (flagKey, defaultValue, context) =>
      details(flagKey, defaultValue, "string", context),
    getNumberDetails: (flagKey, defaultValue, context) =>
      details(flagKey, defaultValue, "number", context),
    getObjectDetails: (flagKey, defaultValue, context) =>
      details(flagKey, defaultValue, "object", context),
  };
};