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

import * as LocalFlagship from "@alchemy.run/cloudflare-runtime/core/bindings/flagship";
import * as flagship from "@distilled.cloud/cloudflare/flagship";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { isResourceOfType, Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import { localAccountId } from "../LocalAccount.ts";
import { generateLocalId } from "../LocalRuntime.ts";
import type { Providers } from "../Providers.ts";
import { localFlagshipStore } from "./Flag.ts";

const TypeId = "Cloudflare.Flagship.App" as const;
type TypeId = typeof TypeId;

export type AppProps = {
  /**
   * Human readable app name. Apps group flags by project or service. If
   * omitted, a unique name is generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
};

export type AppAttributes = {
  /**
   * Server-generated app identifier. Stable across updates; used as the
   * `appId` for flags, the Worker binding, and all evaluation calls.
   */
  appId: string;
  /**
   * The Cloudflare account the app belongs to.
   */
  accountId: string;
  /**
   * Human readable app name.
   */
  name: string;
  /**
   * When the app was created.
   */
  createdAt: string;
  /**
   * When the app was last modified.
   */
  updatedAt: string;
  /**
   * Email of the actor who last modified the app, or `edge-gateway` for
   * gateway-authenticated changes.
   */
  updatedBy: string;
};

export type App = Resource<TypeId, AppProps, AppAttributes, never, Providers>;

/**
 * A Cloudflare Flagship app — a container for feature flags.
 *
 * Flagship is Cloudflare's feature flag service. Flags are organized into
 * apps that map to your projects or services; the app's `appId` is what a
 * Worker's `Flagship` binding points at and what every evaluation call is
 * scoped to. The name is mutable in place; the app id never changes.
 * ### Creating an App
 * **Example:** App with a generated name
 * ```typescript
 * const app = yield* Cloudflare.Flagship.App("Flags", {});
 * ```
 *
 * **Example:** App with an explicit name
 * ```typescript
 * const app = yield* Cloudflare.Flagship.App("Flags", {
 *   name: "my-service-flags",
 * });
 * ```
 *
 * ### Using the App
 * **Example:** Define flags in the app
 * ```typescript
 * const app = yield* Cloudflare.Flagship.App("Flags", {});
 *
 * const flag = yield* Cloudflare.Flagship.Flag("NewCheckout", {
 *   appId: app.appId,
 *   key: "new-checkout",
 *   defaultVariation: "off",
 *   variations: { off: false, on: true },
 * });
 * ```
 *
 * ### Binding to a Worker
 * **Example:** Effect-style Worker (recommended)
 * `Cloudflare.Flagship.ReadFlags(app)` attaches the binding to the surrounding
 * Worker and returns the runtime client for evaluating flags. Every `Flagship`
 * method is mirrored as an Effect, so no `Effect.tryPromise` wrapping is needed.
 * ```typescript
 * export const App = Cloudflare.Flagship.App("Flags", {});
 *
 * Cloudflare.Worker(
 *   "FlagsWorker",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const flags = yield* Cloudflare.Flagship.ReadFlags(App);
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const enabled = yield* flags.getBooleanValue("new-checkout", false, {
 *           userId: "user-42",
 *         });
 *         return HttpServerResponse.text(enabled ? "on" : "off");
 *       }),
 *     };
 *   }).pipe(Effect.provide(Cloudflare.Flagship.ReadFlagsBinding)),
 * );
 * ```
 *
 * **Example:** Declare the binding on `env`
 * Declaring the app on a Worker's `env` maps it to the native `Flagship`
 * runtime binding via `InferEnv`.
 * ```typescript
 * export const App = Cloudflare.Flagship.App("Flags", {});
 *
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: { FLAGS: App },
 * });
 *
 * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
 * //   { FLAGS: Flagship }
 * ```
 *
 * **Example:** Async-style worker with the raw runtime binding
 * ```typescript
 * import type { WorkerEnv } from "../alchemy.run.ts";
 *
 * export default {
 *   async fetch(request: Request, env: WorkerEnv) {
 *     const enabled = await env.FLAGS.getBooleanValue("new-checkout", false, {
 *       userId: "user-42",
 *     });
 *     return new Response(enabled ? "on" : "off");
 *   },
 * };
 * ```
 *
 * ### Local Development
 * **Example:** Flags evaluate locally under `alchemy dev`
 * In `alchemy dev` the app and its flags are emulated on your machine: no
 * Cloudflare API calls, and the Worker's binding evaluates flags locally with
 * the same targeting rules, rollouts, and evaluation reasons. Changing a flag
 * and saving applies to the running Worker without a restart.
 * ```typescript
 * const app = yield* Cloudflare.Flagship.App("Flags", {});
 *
 * yield* Cloudflare.Flagship.Flag("NewCheckout", {
 *   appId: app.appId,
 *   key: "new-checkout",
 *   defaultVariation: "off",
 *   variations: { off: false, on: true },
 *   rules: [
 *     {
 *       priority: 1,
 *       conditions: [{ attribute: "country", operator: "equals", value: "US" }],
 *       serveVariation: "on",
 *     },
 *   ],
 * });
 *
 * yield* Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: { FLAGS: app },
 * });
 * ```
 *
 * **Example:** Use the real app during `alchemy dev`
 * Pipe the app and its flags through `Alchemy.remote()` to create them on
 * Cloudflare; the local Worker's binding then evaluates the live flags.
 * ```typescript
 * const app = yield* Cloudflare.Flagship.App("Flags", {}).pipe(Alchemy.remote());
 *
 * yield* Cloudflare.Flagship.Flag("NewCheckout", {
 *   appId: app.appId,
 *   key: "new-checkout",
 *   defaultVariation: "off",
 *   variations: { off: false, on: true },
 * }).pipe(Alchemy.remote());
 * ```
 *
 * @see https://developers.cloudflare.com/flagship/
 * @see https://developers.cloudflare.com/api/resources/flagship/
 *
 * @resource
 * @product Flagship
 * @category Developer Platform
 */
export const App = Resource<App>(TypeId);

/**
 * Returns true if the given value is a Flagship App resource.
 */
export const isApp = (value: unknown): value is App => isResourceOfType(value, TypeId);

export const AppProviderLive = () =>
  Provider.succeed(App, {
    stables: ["appId", "accountId", "createdAt"],
    diff: Effect.fn(function* ({ output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ id, olds, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      if (output?.appId) {
        const observed = yield* getApp(acct, output.appId);
        return observed ? toAttributes(observed, acct) : undefined;
      }
      // Cold read — recover from lost state by matching the deterministic
      // physical name. App names are not unique on Cloudflare's side; an
      // exact match on our generated/explicit name is the best identity we
      // have. Pick the oldest match for determinism.
      const name = yield* createAppName(id, olds?.name);
      const match = yield* findByName(acct, name);
      return match ? toAttributes(match, acct) : undefined;
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createAppName(id, news.name);

      // Observe — the appId cached on `output` is a hint, not a guarantee:
      // a missing app falls through and we recreate.
      const observed = output?.appId
        ? yield* getApp(output.accountId ?? accountId, output.appId)
        : undefined;

      if (!observed) {
        // Ensure — greenfield (or out-of-band delete). App names are not
        // unique so there is no AlreadyExists race to tolerate.
        const created = yield* flagship.createApp({ accountId, name });
        return toAttributes(created, accountId);
      }

      // Sync — the only mutable aspect is the name; skip the API on a no-op.
      if (observed.name === name) {
        return toAttributes(observed, accountId);
      }
      const updated = yield* flagship.updateApp({
        accountId,
        appId: observed.id,
        name,
      });
      return toAttributes(updated, accountId);
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* flagship
        .deleteApp({ accountId: output.accountId, appId: output.appId })
        .pipe(Effect.catchTag("FlagshipAppNotFound", () => Effect.void));
    }),
    // Account-scoped collection (pattern b): enumerate every app in the
    // ambient account via the paginated listApps op. Cloudflare's list
    // index can contain ghost rows — apps that were deleted but survive in
    // the listing while GET/DELETE both return "App not found" — so each
    // row is validated via getApp and ghosts are dropped (otherwise census
    // tooling re-discovers an undeletable app forever).
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const listed = yield* flagship.listApps.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.result ?? [])),
      );
      const rows = yield* Effect.forEach(
        listed,
        (app) =>
          getApp(accountId, app.id).pipe(
            Effect.map((observed) => (observed ? toAttributes(observed, accountId) : undefined)),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is AppAttributes => row !== undefined);
    }),
  });

/**
 * Local (dev) provider — the app is purely virtual: a `dev:` id keyed into
 * the local workerd Flagship simulator. The local `Flag` provider seeds
 * definitions under that id, and `toRuntimeBinding` lowers a `flagship`
 * binding whose app id is `dev:`-prefixed onto the local evaluator; data
 * persists under `.alchemy/local/flagship`.
 */
export const AppProviderLocal = () =>
  Provider.succeed(App, {
    stables: ["appId", "accountId", "createdAt"],
    diff: Effect.fn(function* ({ output }) {
      if (!output?.appId) return { action: "update" } as const;
      if (output.accountId !== (yield* localAccountId)) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ output }) {
      // Purely virtual — the persisted state row is the source of truth.
      return output ?? undefined;
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const now = yield* Effect.sync(() => new Date().toISOString());
      return {
        appId: output?.appId ?? generateLocalId(),
        accountId: output?.accountId ?? (yield* localAccountId),
        name: yield* createAppName(id, news.name),
        createdAt: output?.createdAt ?? now,
        updatedAt: now,
        updatedBy: "local",
      };
    }),
    delete: Effect.fn(function* ({ output }) {
      // Flags delete their own definitions first; this sweeps anything left
      // in the app's store (idempotent).
      yield* LocalFlagship.deleteApp(yield* localFlagshipStore(output.appId));
    }),
  });

export const AppProvider = () =>
  ProviderLayer.dual(App, {
    local: () => AppProviderLocal(),
    live: () => AppProviderLive(),
  });

/**
 * Read an app by id, mapping "gone" (`FlagshipAppNotFound`) to `undefined`.
 */
const getApp = (accountId: string, appId: string) =>
  flagship
    .getApp({ accountId, appId })
    .pipe(Effect.catchTag("FlagshipAppNotFound", () => Effect.undefined));

/**
 * Find an app by exact name. If several apps carry the same name, pick the
 * oldest for determinism.
 */
const findByName = (accountId: string, name: string) =>
  flagship.listApps.items({ accountId }).pipe(
    Stream.filter((a) => a.name === name),
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
        .at(0),
    ),
  );

const createAppName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true }));
  });

const toAttributes = (
  app: flagship.GetAppResponse | flagship.CreateAppResponse | flagship.UpdateAppResponse,
  accountId: string,
): AppAttributes => ({
  appId: app.id,
  accountId,
  name: app.name,
  createdAt: app.createdAt,
  updatedAt: app.updatedAt,
  updatedBy: app.updatedBy,
});