The best way to control Claude Code, Codex and more from any computer or phone

main
ts 408 lines 15 KB
Raw
1 import * as managedTransforms from "@distilled.cloud/cloudflare/managed-transforms";
2 import * as Provider from "alchemy/Provider";
3 import { Resource } from "alchemy/Resource";
4 import * as Effect from "effect/Effect";
5 import * as Predicate from "effect/Predicate";
6 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
7 import type { Providers } from "../Providers.ts";
8 import { listAllZones } from "../Zone/lookup.ts";
9
10 const TypeId = "Cloudflare.ManagedTransforms.ManagedTransforms" as const;
11 type TypeId = typeof TypeId;
12
13 /**
14 * Identifier of a Cloudflare managed request transform — the built-in
15 * request-header transforms Cloudflare offers on
16 * `/zones/{zone_id}/managed_headers`. The open `(string & {})` tail keeps
17 * the type forward-compatible with transforms Cloudflare adds later.
18 */
19 export type ManagedRequestTransformId =
20 | "add_bot_protection_headers"
21 | "add_client_certificate_headers"
22 | "add_true_client_ip_headers"
23 | "add_visitor_location_headers"
24 | "add_waf_credential_check_status_header"
25 | "remove_visitor_ip_headers"
26 | (string & {});
27
28 /**
29 * Identifier of a Cloudflare managed response transform — the built-in
30 * response-header transforms Cloudflare offers on
31 * `/zones/{zone_id}/managed_headers`. The open `(string & {})` tail keeps
32 * the type forward-compatible with transforms Cloudflare adds later.
33 */
34 export type ManagedResponseTransformId =
35 | "add_security_headers"
36 | "remove_x-powered-by_header"
37 | (string & {});
38
39 export interface Props {
40 /**
41 * Zone whose managed transforms are managed. Stable — changing the zone
42 * triggers a replacement (the old zone's managed transforms are restored
43 * to the enabled states they had before Alchemy managed them).
44 */
45 zoneId: string;
46 /**
47 * Desired enabled state per managed **request** transform id (e.g.
48 * `{ add_visitor_location_headers: true }`). Only the ids you name here
49 * are managed — every other transform on the zone is left untouched.
50 *
51 * Mutable — patched in place.
52 *
53 * @default {}
54 */
55 requestHeaders?: Partial<Record<ManagedRequestTransformId, boolean>>;
56 /**
57 * Desired enabled state per managed **response** transform id (e.g.
58 * `{ "remove_x-powered-by_header": true }`). Only the ids you name here
59 * are managed — every other transform on the zone is left untouched.
60 *
61 * Mutable — patched in place.
62 *
63 * @default {}
64 */
65 responseHeaders?: Partial<Record<ManagedResponseTransformId, boolean>>;
66 }
67
68 /**
69 * Observed state of a single managed transform on the zone.
70 */
71 export interface ManagedTransformState {
72 /** The transform's identifier (e.g. `add_visitor_location_headers`). */
73 id: string;
74 /** Whether the transform is currently enabled on the zone. */
75 enabled: boolean;
76 /** Whether the transform conflicts with another enabled feature. */
77 hasConflict: boolean;
78 /** Ids of the transforms this one conflicts with, when Cloudflare reports them. */
79 conflictsWith: string[] | undefined;
80 }
81
82 export interface Attributes {
83 /** Zone that owns these managed transforms. */
84 zoneId: string;
85 /** Observed state of every managed request transform on the zone. */
86 requestHeaders: ManagedTransformState[];
87 /** Observed state of every managed response transform on the zone. */
88 responseHeaders: ManagedTransformState[];
89 /**
90 * Snapshot of every request transform's enabled state observed **before**
91 * this resource first wrote to the zone. `delete` restores the ids this
92 * resource managed to these values.
93 */
94 initialRequestHeaders: Record<string, boolean>;
95 /**
96 * Snapshot of every response transform's enabled state observed
97 * **before** this resource first wrote to the zone. `delete` restores the
98 * ids this resource managed to these values.
99 */
100 initialResponseHeaders: Record<string, boolean>;
101 }
102
103 export type ManagedTransforms = Resource<TypeId, Props, Attributes, never, Providers>;
104
105 /**
106 * The managed request/response header transforms of a Cloudflare zone
107 * (`/zones/{zone_id}/managed_headers`) — a zone-scoped **singleton**: every
108 * zone always carries the full catalog of managed transforms (each with an
109 * enabled flag), so there is no create or delete on the Cloudflare side.
110 *
111 * Reconciling this resource adopts the singleton and patches **only the
112 * transform ids you name** in `requestHeaders` / `responseHeaders` — every
113 * other transform is left exactly as found (dashboard- or otherwise-managed
114 * toggles are never clobbered).
115 *
116 * On destroy, the resource restores the ids it managed to the enabled
117 * states observed before its first write (the `initialRequestHeaders` /
118 * `initialResponseHeaders` snapshots). Transforms that were never named are
119 * not touched.
120 *
121 * Some transforms are plan-gated (e.g. `add_bot_protection_headers`
122 * requires Bot Management) — enabling those fails server-side on
123 * unentitled zones.
124 * ### Request transforms
125 * **Example:** Add visitor location headers
126 * ```typescript
127 * yield* Cloudflare.ManagedTransforms.ManagedTransforms("Transforms", {
128 * zoneId: zone.zoneId,
129 * requestHeaders: { add_visitor_location_headers: true },
130 * });
131 * ```
132 *
133 * **Example:** Remove visitor IP headers
134 * ```typescript
135 * yield* Cloudflare.ManagedTransforms.ManagedTransforms("Transforms", {
136 * zoneId: zone.zoneId,
137 * requestHeaders: { remove_visitor_ip_headers: true },
138 * });
139 * ```
140 *
141 * ### Response transforms
142 * **Example:** Harden responses
143 * ```typescript
144 * yield* Cloudflare.ManagedTransforms.ManagedTransforms("Transforms", {
145 * zoneId: zone.zoneId,
146 * responseHeaders: {
147 * add_security_headers: true,
148 * "remove_x-powered-by_header": true,
149 * },
150 * });
151 * ```
152 *
153 * ### Mixed
154 * **Example:** Manage request and response transforms together
155 * ```typescript
156 * yield* Cloudflare.ManagedTransforms.ManagedTransforms("Transforms", {
157 * zoneId: zone.zoneId,
158 * requestHeaders: { add_true_client_ip_headers: true },
159 * responseHeaders: { "remove_x-powered-by_header": false },
160 * });
161 * ```
162 *
163 * @see https://developers.cloudflare.com/rules/transform/managed-transforms/
164 *
165 * @resource
166 * @product Managed Transforms
167 * @category Rules & Configuration
168 */
169 export const ManagedTransforms = Resource<ManagedTransforms>(TypeId, {
170 aliases: ["Cloudflare.ManagedTransforms"],
171 });
172
173 /**
174 * Returns true if the given value is a ManagedTransforms resource.
175 */
176 export const isManagedTransforms = (value: unknown): value is ManagedTransforms =>
177 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
178
179 export const ManagedTransformsProvider = () =>
180 Provider.succeed(ManagedTransforms, {
181 nuke: { singleton: true },
182 stables: ["zoneId", "initialRequestHeaders", "initialResponseHeaders"],
183
184 list: Effect.fn(function* () {
185 const { accountId } = yield* yield* CloudflareEnvironment;
186 // The managed-transforms catalog is a per-zone singleton with no
187 // account-wide list — enumerate every zone and read its catalog.
188 const allZones = yield* listAllZones(accountId);
189 const rows = yield* Effect.forEach(
190 allZones.map((zone) => zone.id),
191 (zoneId) =>
192 observe(zoneId).pipe(
193 Effect.map((observed) =>
194 observed === undefined
195 ? undefined
196 : // Cold enumeration adopts the singleton freely — the
197 // observed enabled states become the snapshot baseline,
198 // matching the `read` cold-adopt path.
199 toAttributes(
200 zoneId,
201 observed,
202 snapshot(observed.managedRequestHeaders),
203 snapshot(observed.managedResponseHeaders),
204 ),
205 ),
206 ),
207 { concurrency: 10 },
208 );
209 return rows.filter((row): row is Attributes => row !== undefined);
210 }),
211
212 diff: Effect.fn(function* ({ olds = {}, news, output }) {
213 const o = olds as Props;
214 const n = news as Props;
215 // zoneId is Input<string>; compare only when both sides are concrete.
216 const oldZone = output?.zoneId ?? o.zoneId;
217 if (typeof oldZone === "string" && typeof n.zoneId === "string" && oldZone !== n.zoneId) {
218 return { action: "replace" } as const;
219 }
220 }),
221
222 read: Effect.fn(function* ({ output, olds }) {
223 // The transform catalog is a singleton — it exists iff the zone does.
224 const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
225 if (!zoneId) return undefined;
226 const observed = yield* observe(zoneId);
227 if (!observed) return undefined;
228 // Singletons always exist with Cloudflare defaults — there is nothing
229 // to "own", so a cold read adopts freely (never `Unowned`). The
230 // enabled states observed at adoption time become the snapshot
231 // restored on destroy.
232 return toAttributes(
233 zoneId,
234 observed,
235 output?.initialRequestHeaders ?? snapshot(observed.managedRequestHeaders),
236 output?.initialResponseHeaders ?? snapshot(observed.managedResponseHeaders),
237 );
238 }),
239
240 reconcile: Effect.fn(function* ({ news, output }) {
241 // Inputs are resolved to concrete strings by Plan.
242 const zoneId = news.zoneId as string;
243
244 // 1. Observe — the singleton always exists for a live zone.
245 let observed = normalize(yield* managedTransforms.listManagedTransforms({ zoneId }));
246
247 // 2. Snapshot — capture pre-management enabled states once; `output`
248 // acts as the cache that keeps the very first observation sticky.
249 const initialRequestHeaders =
250 output?.initialRequestHeaders ?? snapshot(observed.managedRequestHeaders);
251 const initialResponseHeaders =
252 output?.initialResponseHeaders ?? snapshot(observed.managedResponseHeaders);
253
254 // 3. Sync — diff the managed ids' desired enabled flags against the
255 // observed states and PATCH only the deltas. Unnamed transforms
256 // are never sent, so they stay exactly as found.
257 const requestDelta = delta(news.requestHeaders ?? {}, observed.managedRequestHeaders);
258 const responseDelta = delta(news.responseHeaders ?? {}, observed.managedResponseHeaders);
259 if (requestDelta.length > 0 || responseDelta.length > 0) {
260 observed = normalize(
261 yield* managedTransforms.patchManagedTransform({
262 zoneId,
263 managedRequestHeaders: requestDelta,
264 managedResponseHeaders: responseDelta,
265 }),
266 );
267 }
268
269 // 4. Return fresh attributes.
270 return toAttributes(zoneId, observed, initialRequestHeaders, initialResponseHeaders);
271 }),
272
273 delete: Effect.fn(function* ({ output, olds }) {
274 // Singleton — nothing to delete on the Cloudflare side. Restore the
275 // ids this resource managed (i.e. the ones named in the last-applied
276 // props) to their pre-management snapshot values. Ids missing from
277 // the snapshot (added by Cloudflare after adoption) are left as-is.
278 const observed = yield* observe(output.zoneId);
279 if (!observed) return; // zone is gone — nothing to restore
280 const o = (olds ?? {}) as Props;
281 const requestRestore = restoreDelta(
282 o.requestHeaders ?? {},
283 output.initialRequestHeaders ?? {},
284 observed.managedRequestHeaders,
285 );
286 const responseRestore = restoreDelta(
287 o.responseHeaders ?? {},
288 output.initialResponseHeaders ?? {},
289 observed.managedResponseHeaders,
290 );
291 if (requestRestore.length > 0 || responseRestore.length > 0) {
292 yield* managedTransforms
293 .patchManagedTransform({
294 zoneId: output.zoneId,
295 managedRequestHeaders: requestRestore,
296 managedResponseHeaders: responseRestore,
297 })
298 .pipe(Effect.catchTag("InvalidRoute", () => Effect.void));
299 }
300 }),
301 });
302
303 interface ObservedTransform {
304 id: string;
305 enabled: boolean;
306 hasConflict: boolean;
307 conflictsWith?: string[] | null;
308 }
309
310 interface ObservedTransforms {
311 managedRequestHeaders: readonly ObservedTransform[];
312 managedResponseHeaders: readonly ObservedTransform[];
313 }
314
315 /**
316 * Cloudflare returns `null` (not `[]`) for a transform list when the zone's
317 * plan offers no transforms of that kind (e.g. all managed request
318 * transforms are plan-gated on free zones). Normalize to empty arrays so the
319 * rest of the provider only deals in lists.
320 */
321 const normalize = (
322 response:
323 | managedTransforms.ListManagedTransformsResponse
324 | managedTransforms.PatchManagedTransformResponse,
325 ): ObservedTransforms => ({
326 managedRequestHeaders: response.managedRequestHeaders ?? [],
327 managedResponseHeaders: response.managedResponseHeaders ?? [],
328 });
329
330 /**
331 * Read the zone's managed transforms, mapping a dead zone (`InvalidRoute`,
332 * Cloudflare code 7003) to `undefined`.
333 */
334 const observe = (zoneId: string) =>
335 managedTransforms.listManagedTransforms({ zoneId }).pipe(
336 Effect.map(normalize),
337 Effect.catchTag("InvalidRoute", () => Effect.undefined),
338 );
339
340 /**
341 * Project an observed transform list onto an id → enabled snapshot map.
342 */
343 const snapshot = (transforms: readonly ObservedTransform[]): Record<string, boolean> => {
344 const out: Record<string, boolean> = {};
345 for (const t of transforms) out[t.id] = t.enabled;
346 return out;
347 };
348
349 /**
350 * The PATCH entries needed to bring the managed ids to their desired
351 * enabled states — only ids whose observed state differs are included, so
352 * a no-op reconcile sends nothing.
353 */
354 const delta = (
355 desired: Partial<Record<string, boolean>>,
356 observed: readonly ObservedTransform[],
357 ): { id: string; enabled: boolean }[] => {
358 const current = snapshot(observed);
359 const out: { id: string; enabled: boolean }[] = [];
360 for (const [id, enabled] of Object.entries(desired)) {
361 if (enabled !== undefined && current[id] !== enabled) {
362 out.push({ id, enabled });
363 }
364 }
365 return out;
366 };
367
368 /**
369 * The PATCH entries needed to restore the managed ids to their snapshot
370 * values — only ids that were managed, have a snapshot value, and currently
371 * differ from it are included (idempotent re-delete after a crashed run).
372 */
373 const restoreDelta = (
374 managed: Partial<Record<string, boolean>>,
375 initial: Record<string, boolean>,
376 observed: readonly ObservedTransform[],
377 ): { id: string; enabled: boolean }[] => {
378 const current = snapshot(observed);
379 const out: { id: string; enabled: boolean }[] = [];
380 for (const id of Object.keys(managed)) {
381 if (managed[id] === undefined) continue;
382 const original = initial[id];
383 if (original !== undefined && current[id] !== original) {
384 out.push({ id, enabled: original });
385 }
386 }
387 return out;
388 };
389
390 const toState = (t: ObservedTransform): ManagedTransformState => ({
391 id: t.id,
392 enabled: t.enabled,
393 hasConflict: t.hasConflict,
394 conflictsWith: t.conflictsWith == null ? undefined : [...t.conflictsWith],
395 });
396
397 const toAttributes = (
398 zoneId: string,
399 observed: ObservedTransforms,
400 initialRequestHeaders: Record<string, boolean>,
401 initialResponseHeaders: Record<string, boolean>,
402 ): Attributes => ({
403 zoneId,
404 requestHeaders: observed.managedRequestHeaders.map(toState),
405 responseHeaders: observed.managedResponseHeaders.map(toState),
406 initialRequestHeaders,
407 initialResponseHeaders,
408 });