The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as LocalFlagship from "@alchemy.run/cloudflare-runtime/core/bindings/flagship"; |
| 2 | import type { AlchemyContext } from "alchemy/AlchemyContext"; |
| 3 | import type * as Context from "effect/Context"; |
| 4 | import * as Effect from "effect/Effect"; |
| 5 | import type * as FileSystem from "effect/FileSystem"; |
| 6 | import type * as HttpClient from "effect/http/HttpClient"; |
| 7 | import * as Layer from "effect/Layer"; |
| 8 | import type * as Path from "effect/Path"; |
| 9 | import { CloudflareEnvironment } from "../CloudflareEnvironment.ts"; |
| 10 | import type { Credentials } from "../Credentials.ts"; |
| 11 | import { dispatchByMode } from "../LocalGateway.ts"; |
| 12 | import type { App } from "./App.ts"; |
| 13 | import { localFlagshipStore } from "./Flag.ts"; |
| 14 | import { |
| 15 | type EvaluationContext, |
| 16 | type EvaluationDetails, |
| 17 | FlagshipError, |
| 18 | ReadFlags, |
| 19 | type ReadFlagsClient, |
| 20 | } from "./ReadFlags.ts"; |
| 21 | import { type FlagshipAuth, makeHttpFlagshipClient } from "./ReadFlagsHttpClient.ts"; |
| 22 | |
| 23 | /** |
| 24 | * Local implementation of the {@link ReadFlags} binding — evaluates Flagship |
| 25 | * feature flags over the Cloudflare HTTP API (`GET .../flagship/apps/{appId}/evaluate`) |
| 26 | * using the **current credentials** instead of a native Worker binding |
| 27 | * ({@link ReadFlagsBinding}). |
| 28 | * |
| 29 | * Provide it on an {@link Action} (or any deploy-time Effect) so you can read |
| 30 | * flag values with the same `getBooleanValue`/`getStringValue`/… client you'd |
| 31 | * use inside a Worker: |
| 32 | * |
| 33 | * @example Reading a flag from an Action |
| 34 | * ```typescript |
| 35 | * const CheckFlag = Alchemy.Action( |
| 36 | * "CheckFlag", |
| 37 | * Effect.gen(function* () { |
| 38 | * const flags = yield* Cloudflare.Flagship.ReadFlags(app); |
| 39 | * return Effect.fn(function* () { |
| 40 | * return yield* flags.getBooleanValue("new-checkout", false); |
| 41 | * }); |
| 42 | * }).pipe(Effect.provide(Cloudflare.Flagship.ReadFlagsLocal)), |
| 43 | * ); |
| 44 | * ``` |
| 45 | * |
| 46 | * The app id is resolved at apply time through the ambient {@link RuntimeContext} |
| 47 | * (in an Action, that's the resolve context the engine provides around the |
| 48 | * body), so `ReadFlags(app)` works even though the app is created in the same |
| 49 | * deploy. |
| 50 | * |
| 51 | * Under `alchemy dev`, a locally-emulated app (a `dev:` app id) is evaluated |
| 52 | * against the local Flagship simulator's definitions with the same rules a |
| 53 | * dev Worker's binding applies, so the full evaluation context is honored. |
| 54 | * |
| 55 | * Limitations vs. the Worker binding for a live app: the HTTP evaluate |
| 56 | * endpoint only accepts a single `targetingKey` (read from |
| 57 | * `context.targetingKey`), so attribute-based targeting rules that key off |
| 58 | * other context fields cannot be exercised. The `raw` runtime binding has no |
| 59 | * HTTP equivalent and dies if used — see {@link makeHttpFlagshipClient}. |
| 60 | */ |
| 61 | export const ReadFlagsLocal = Layer.effect( |
| 62 | ReadFlags, |
| 63 | Effect.gen(function* () { |
| 64 | // Capture the account resolver without authenticating — only the HTTP |
| 65 | // branch evaluates it. Credentials are ambient during stack-eval (the |
| 66 | // stack's providers layer); capture the full context so the evaluate op |
| 67 | // runs with the current credentials — no `host.bind`, no minted token. |
| 68 | const environment = yield* CloudflareEnvironment; |
| 69 | const context = yield* Effect.context<Credentials | HttpClient.HttpClient>(); |
| 70 | // Local evaluation reads the simulator's files. |
| 71 | const platform = yield* Effect.context<FileSystem.FileSystem | Path.Path | AlchemyContext>(); |
| 72 | const auth: FlagshipAuth = { |
| 73 | authorize: (eff) => eff.pipe(Effect.provideContext(context)), |
| 74 | accountId: Effect.map(environment, (env) => env.accountId), |
| 75 | }; |
| 76 | |
| 77 | return Effect.fn(function* (app: App) { |
| 78 | // Deferred accessor — resolves the appId against the tracker at apply |
| 79 | // time (in an Action, that's the engine's resolve context). |
| 80 | const appId = yield* app.appId; |
| 81 | return dispatchByMode(appId, makeHttpFlagshipClient(auth, appId), (id) => |
| 82 | makeLocalFlagshipClient(id, platform), |
| 83 | ); |
| 84 | }); |
| 85 | }), |
| 86 | ); |
| 87 | |
| 88 | /** |
| 89 | * A client over the local Flagship simulator for a `dev:` app: evaluates the |
| 90 | * app's flag definitions in-process with the same rules a dev Worker's |
| 91 | * binding applies. `raw` cannot be satisfied — there is no native binding |
| 92 | * outside a Worker — so it dies with guidance. |
| 93 | */ |
| 94 | const makeLocalFlagshipClient = ( |
| 95 | appId: string, |
| 96 | platform: Context.Context<FileSystem.FileSystem | Path.Path | AlchemyContext>, |
| 97 | ): ReadFlagsClient => { |
| 98 | const details = <T>( |
| 99 | flagKey: string, |
| 100 | defaultValue: T, |
| 101 | expectedType: LocalFlagship.FlagshipValueType | undefined, |
| 102 | context: EvaluationContext | undefined, |
| 103 | ) => |
| 104 | localFlagshipStore(appId).pipe( |
| 105 | Effect.flatMap((store) => |
| 106 | LocalFlagship.evaluate(store, { flagKey, defaultValue, expectedType, context }), |
| 107 | ), |
| 108 | Effect.map((d) => d as EvaluationDetails<T>), |
| 109 | Effect.mapError( |
| 110 | (cause) => new FlagshipError({ message: "Local Flagship evaluation failed", cause }), |
| 111 | ), |
| 112 | Effect.provideContext(platform), |
| 113 | ); |
| 114 | const value = <T>( |
| 115 | flagKey: string, |
| 116 | defaultValue: T, |
| 117 | expectedType: LocalFlagship.FlagshipValueType | undefined, |
| 118 | context: EvaluationContext | undefined, |
| 119 | ) => Effect.map(details(flagKey, defaultValue, expectedType, context), (d) => d.value); |
| 120 | |
| 121 | return { |
| 122 | raw: Effect.die( |
| 123 | new FlagshipError({ |
| 124 | message: |
| 125 | "A locally-emulated Flagship app has no native binding outside a Worker; use the evaluation methods.", |
| 126 | cause: undefined, |
| 127 | }), |
| 128 | ), |
| 129 | get: (flagKey, defaultValue, context) => value(flagKey, defaultValue, undefined, context), |
| 130 | getBooleanValue: (flagKey, defaultValue, context) => |
| 131 | value(flagKey, defaultValue, "boolean", context), |
| 132 | getStringValue: (flagKey, defaultValue, context) => |
| 133 | value(flagKey, defaultValue, "string", context), |
| 134 | getNumberValue: (flagKey, defaultValue, context) => |
| 135 | value(flagKey, defaultValue, "number", context), |
| 136 | getObjectValue: (flagKey, defaultValue, context) => |
| 137 | value(flagKey, defaultValue, "object", context), |
| 138 | getBooleanDetails: (flagKey, defaultValue, context) => |
| 139 | details(flagKey, defaultValue, "boolean", context), |
| 140 | getStringDetails: (flagKey, defaultValue, context) => |
| 141 | details(flagKey, defaultValue, "string", context), |
| 142 | getNumberDetails: (flagKey, defaultValue, context) => |
| 143 | details(flagKey, defaultValue, "number", context), |
| 144 | getObjectDetails: (flagKey, defaultValue, context) => |
| 145 | details(flagKey, defaultValue, "object", context), |
| 146 | }; |
| 147 | }; |