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

main
ts 211 lines 8.17 KB
Raw
1 import * as cache from "@distilled.cloud/cloudflare/cache";
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.Cache.SmartTieredCache" as const;
11 type TypeId = typeof TypeId;
12
13 export interface SmartTieredCacheProps {
14 /**
15 * Zone whose Smart Tiered Cache setting is managed. Stable — changing
16 * the zone triggers a replacement (the old zone's setting is restored
17 * to the value it had before Alchemy managed it).
18 */
19 zoneId: string;
20 /**
21 * Whether Smart Tiered Cache is enabled on the zone (`value: "on"`)
22 * or disabled (`value: "off"`). Mutable — patched in place.
23 * @default true
24 */
25 enabled?: boolean;
26 }
27
28 export interface SmartTieredCacheAttributes {
29 /** Zone the setting belongs to. */
30 zoneId: string;
31 /** Resolved current value of the setting (`"on"` or `"off"`). */
32 value: string;
33 /**
34 * Whether the setting can be modified on the zone's current plan
35 * (`false` means the setting is plan-gated).
36 */
37 editable: boolean;
38 /** When the setting was last modified, if Cloudflare reports it. */
39 modifiedOn: string | undefined;
40 /**
41 * The value the setting had before Alchemy first patched it. Restored
42 * on destroy, so deleting the resource puts the zone back the way it
43 * was found.
44 */
45 initialValue: string;
46 }
47
48 export type SmartTieredCache = Resource<
49 TypeId,
50 SmartTieredCacheProps,
51 SmartTieredCacheAttributes,
52 never,
53 Providers
54 >;
55
56 /**
57 * The Smart Tiered Cache setting of a Cloudflare zone
58 * (`/zones/{zone_id}/cache/tiered_cache_smart_topology_enable`).
59 *
60 * Smart Tiered Cache dynamically selects the single best upper-tier data
61 * center for each origin, reducing requests that reach the origin. The
62 * setting is a zone **singleton** — it always exists on every zone (default
63 * `off`), so this resource never creates or deletes anything physical.
64 * Reconcile patches the setting when the observed value differs from the
65 * desired one; destroy restores the value the setting had before Alchemy
66 * first managed it (captured as `initialValue`).
67 *
68 * Only one `SmartTieredCache` resource per zone makes sense — two instances
69 * managing the same zone would fight over the singleton.
70 * ### Managing Smart Tiered Cache
71 * **Example:** Enable Smart Tiered Cache on a zone
72 * ```typescript
73 * const zone = yield* Cloudflare.Zone.Zone("Site", { name: "example.com" });
74 *
75 * yield* Cloudflare.Cache.SmartTieredCache("SmartCache", {
76 * zoneId: zone.zoneId,
77 * });
78 * ```
79 *
80 * **Example:** Explicitly disable Smart Tiered Cache
81 * ```typescript
82 * yield* Cloudflare.Cache.SmartTieredCache("SmartCache", {
83 * zoneId: zone.zoneId,
84 * enabled: false,
85 * });
86 * ```
87 *
88 * @see https://developers.cloudflare.com/cache/how-to/tiered-cache/
89 *
90 * @resource
91 * @product Cache
92 * @category Performance & Reliability
93 */
94 export const SmartTieredCache = Resource<SmartTieredCache>(TypeId);
95
96 /**
97 * Returns true if the given value is a SmartTieredCache resource.
98 */
99 export const isSmartTieredCache = (value: unknown): value is SmartTieredCache =>
100 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
101
102 const desiredValue = (props: SmartTieredCacheProps): "on" | "off" =>
103 (props.enabled ?? true) ? "on" : "off";
104
105 export const SmartTieredCacheProvider = () =>
106 Provider.succeed(SmartTieredCache, {
107 nuke: { singleton: true },
108 stables: ["zoneId", "initialValue"],
109
110 list: Effect.fn(function* () {
111 const { accountId } = yield* yield* CloudflareEnvironment;
112 // No account-wide API for this zone singleton — enumerate every
113 // zone in the account and read its setting (every zone has one).
114 const allZones = yield* listAllZones(accountId);
115 const rows = yield* Effect.forEach(
116 allZones.map((zone) => zone.id),
117 (zoneId) =>
118 cache.getSmartTieredCache({ zoneId }).pipe(
119 Effect.map((observed) => toAttributes(zoneId, observed, observed.value)),
120 // Smart Tiered Cache is an Enterprise feature. When enumerating
121 // every zone in the account, zones that aren't entitled reject the
122 // read — as `InvalidRoute`, or as a persistent `Forbidden`/
123 // `Unauthorized` ("Access denied") on the gated route. These are
124 // not the transient code-10000 auth blips the global policy
125 // retries; the zone simply has no readable setting, so skip it.
126 Effect.catchTag(["InvalidRoute", "Forbidden", "Unauthorized"], () => Effect.undefined),
127 ),
128 { concurrency: 10 },
129 );
130 return rows.filter((row): row is SmartTieredCacheAttributes => row !== undefined);
131 }),
132
133 diff: Effect.fn(function* ({ olds = {}, news, output }) {
134 const o = olds as SmartTieredCacheProps;
135 const n = news as SmartTieredCacheProps;
136 // zoneId is Input<string>; compare only once both sides are concrete.
137 const oldZoneId = output?.zoneId ?? (typeof o.zoneId === "string" ? o.zoneId : undefined);
138 if (oldZoneId !== undefined && typeof n.zoneId === "string" && oldZoneId !== n.zoneId) {
139 return { action: "replace" } as const;
140 }
141 return undefined;
142 }),
143
144 read: Effect.fn(function* ({ output, olds }) {
145 const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
146 if (!zoneId) return undefined;
147 const observed = yield* cache.getSmartTieredCache({ zoneId }).pipe(
148 // Zone deleted out-of-band — the setting is gone with it.
149 Effect.catchTag("InvalidRoute", () => Effect.undefined),
150 );
151 if (observed === undefined) return undefined;
152 // The setting is a singleton that always exists with a Cloudflare
153 // default — there is nothing to "own", so a cold read adopts
154 // freely (never `Unowned`). The observed value at adoption time
155 // becomes the `initialValue` restored on destroy.
156 const initialValue = output !== undefined ? output.initialValue : observed.value;
157 return toAttributes(zoneId, observed, initialValue);
158 }),
159
160 reconcile: Effect.fn(function* ({ news, output }) {
161 // Inputs have been resolved to concrete strings by Plan.
162 const zoneId = news.zoneId as string;
163
164 // 1. Observe — the setting always exists; read its live value.
165 const observed = yield* cache.getSmartTieredCache({ zoneId });
166
167 // 2. Capture — the pre-management value, restored on destroy.
168 // `output` (including an adoption read) already carries it;
169 // otherwise this is our first touch and the observed value is
170 // the zone's original.
171 const initialValue = output !== undefined ? output.initialValue : observed.value;
172
173 // 3. Sync — patch only when the observed value differs.
174 const desired = desiredValue(news);
175 if (observed.value === desired) {
176 return toAttributes(zoneId, observed, initialValue);
177 }
178 const patched = yield* cache.patchSmartTieredCache({
179 zoneId,
180 value: desired,
181 });
182 return toAttributes(zoneId, patched, initialValue);
183 }),
184
185 delete: Effect.fn(function* ({ output }) {
186 const { zoneId, initialValue } = output;
187 // Observe — if the zone itself is gone, so is the setting.
188 const observed = yield* cache
189 .getSmartTieredCache({ zoneId })
190 .pipe(Effect.catchTag("InvalidRoute", () => Effect.undefined));
191 if (observed === undefined) return;
192 // Restore the pre-management value; skip the call when it already
193 // matches (idempotent re-delete after a crashed run).
194 if (observed.value === initialValue) return;
195 yield* cache
196 .patchSmartTieredCache({ zoneId, value: initialValue })
197 .pipe(Effect.catchTag("InvalidRoute", () => Effect.void));
198 }),
199 });
200
201 const toAttributes = (
202 zoneId: string,
203 setting: cache.GetSmartTieredCacheResponse | cache.PatchSmartTieredCacheResponse,
204 initialValue: string,
205 ): SmartTieredCacheAttributes => ({
206 zoneId,
207 value: setting.value,
208 editable: setting.editable,
209 modifiedOn: setting.modifiedOn ?? undefined,
210 initialValue,
211 });