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

main
ts 307 lines 10.1 KB
Raw
1 import * as magicTransit from "@distilled.cloud/cloudflare/magic-transit";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import * as Effect from "effect/Effect";
8 import * as Predicate from "effect/Predicate";
9 import * as Stream from "effect/Stream";
10 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
11 import type { Providers } from "../Providers.ts";
12
13 const TypeId = "Cloudflare.MagicTransit.Site" as const;
14 type TypeId = typeof TypeId;
15
16 /**
17 * Geographic location of a Magic WAN site.
18 */
19 export interface MagicSiteLocation {
20 /** Latitude of the site. */
21 lat?: string;
22 /** Longitude of the site. */
23 lon?: string;
24 }
25
26 export interface MagicSiteProps {
27 /**
28 * The name of the site. If omitted, a unique name is generated from the
29 * app, stage, and logical ID.
30 * @default ${app}-${stage}-${id}
31 */
32 name?: string;
33 /**
34 * An optional description of the site.
35 */
36 description?: string;
37 /**
38 * Magic WAN Connector identifier tag to associate with this site.
39 */
40 connectorId?: string;
41 /**
42 * Secondary Magic WAN Connector identifier tag. Used when high
43 * availability mode is on.
44 */
45 secondaryConnectorId?: string;
46 /**
47 * Site high availability mode. If true, the site can have two connectors
48 * and runs in high availability mode. Create-only — changing it triggers
49 * a replacement.
50 * @default false
51 */
52 haMode?: boolean;
53 /**
54 * Location of the site in latitude and longitude.
55 */
56 location?: MagicSiteLocation;
57 }
58
59 export interface MagicSiteAttributes {
60 /** Cloudflare-assigned identifier of the site. */
61 siteId: string;
62 /** The Cloudflare account the site belongs to. */
63 accountId: string;
64 /** The name of the site. */
65 name: string;
66 /** The site description, if set. */
67 description: string | undefined;
68 /** The associated connector id, if set. */
69 connectorId: string | undefined;
70 /** The associated secondary connector id, if set. */
71 secondaryConnectorId: string | undefined;
72 /** Whether the site runs in high availability mode. */
73 haMode: boolean | undefined;
74 /** Location of the site, if set. */
75 location: MagicSiteLocation | undefined;
76 }
77
78 export type MagicSite = Resource<TypeId, MagicSiteProps, MagicSiteAttributes, never, Providers>;
79
80 /**
81 * A Magic WAN site — represents a physical or logical network location
82 * (typically backed by a Magic WAN Connector appliance) under which LANs,
83 * WANs, and ACLs are configured.
84 *
85 * Requires a Magic WAN subscription — accounts without it receive a typed
86 * `MagicWanUnauthorized` error (Cloudflare code 1025) or `MagicWanNotEnabled`
87 * (code 1101, "forbidden: feature not enabled").
88 *
89 * `haMode` is create-only — changing it triggers a replacement. Everything
90 * else is updated in place.
91 * ### Creating a site
92 * **Example:** Basic site
93 * ```typescript
94 * const site = yield* Cloudflare.MagicTransit.MagicSite("hq", {
95 * description: "Headquarters",
96 * location: { lat: "37.7749", lon: "-122.4194" },
97 * });
98 * ```
99 *
100 * **Example:** Site with LAN and WAN
101 * ```typescript
102 * const site = yield* Cloudflare.MagicTransit.MagicSite("hq", {});
103 *
104 * const wan = yield* Cloudflare.MagicTransit.MagicSiteWan("hq-wan", {
105 * siteId: site.siteId,
106 * physport: 1,
107 * });
108 *
109 * const lan = yield* Cloudflare.MagicTransit.MagicSiteLan("hq-lan", {
110 * siteId: site.siteId,
111 * physport: 2,
112 * vlanTag: 0,
113 * });
114 * ```
115 *
116 * @see https://developers.cloudflare.com/magic-wan/configuration/connector/
117 *
118 * @resource
119 * @product Magic Transit
120 * @category Network
121 */
122 export const MagicSite = Resource<MagicSite>(TypeId);
123
124 /**
125 * Returns true if the given value is a MagicSite resource.
126 */
127 export const isMagicSite = (value: unknown): value is MagicSite =>
128 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
129
130 export const MagicSiteProvider = () =>
131 Provider.succeed(MagicSite, {
132 stables: ["siteId", "accountId", "haMode"],
133
134 // Account collection — Magic WAN sites are account-scoped and enumerated
135 // via the paginated list API. Accounts without a Magic WAN subscription
136 // reject with the typed `MagicWanUnauthorized` (code 1025) or
137 // `MagicWanNotEnabled` (code 1101) → return [].
138
139 list: Effect.fn(function* () {
140 const { accountId } = yield* yield* CloudflareEnvironment;
141 return yield* magicTransit.listSites.pages({ accountId }).pipe(
142 Stream.runCollect,
143 Effect.map((chunk) =>
144 Array.from(chunk).flatMap((page) =>
145 (page.result ?? []).map((site) => toAttributes(site, accountId)),
146 ),
147 ),
148 Effect.catchTag(["MagicWanUnauthorized", "MagicWanNotEnabled"], () =>
149 Effect.succeed<MagicSiteAttributes[]>([]),
150 ),
151 );
152 }),
153
154 diff: Effect.fn(function* ({ olds, news }) {
155 if (!isResolved(news)) return undefined;
156 if (olds === undefined) return undefined;
157 // haMode is create-only — the update API has no such field.
158 if ((olds.haMode ?? false) !== (news.haMode ?? false)) {
159 return { action: "replace" } as const;
160 }
161 return undefined;
162 }),
163
164 read: Effect.fn(function* ({ id, output, olds }) {
165 const { accountId } = yield* yield* CloudflareEnvironment;
166 const acct = output?.accountId ?? accountId;
167
168 if (output?.siteId) {
169 const observed = yield* getSite(acct, output.siteId);
170 if (observed) return toAttributes(observed, acct);
171 }
172 // Cold read — recover from lost state by matching the deterministic
173 // physical name. Sites carry no ownership markers; report as
174 // Unowned so takeover is gated behind the adopt policy.
175 const name = yield* createSiteName(id, olds?.name);
176 const observed = yield* findByName(acct, name);
177 if (observed) return Unowned(toAttributes(observed, acct));
178 return undefined;
179 }),
180
181 reconcile: Effect.fn(function* ({ id, news, output }) {
182 const { accountId } = yield* yield* CloudflareEnvironment;
183 const name = yield* createSiteName(id, news.name);
184 // Inputs have been resolved to concrete strings by Plan.
185 const connectorId = news.connectorId as string | undefined;
186 const secondaryConnectorId = news.secondaryConnectorId as string | undefined;
187
188 // Observe — the id on `output` is a hint; fall back to a name scan.
189 let observed = output?.siteId ? yield* getSite(accountId, output.siteId) : undefined;
190 if (!observed) {
191 observed = yield* findByName(accountId, name);
192 }
193
194 // Ensure — create when missing.
195 if (!observed) {
196 const created = yield* magicTransit.createSite({
197 accountId,
198 name,
199 description: news.description,
200 connectorId,
201 secondaryConnectorId,
202 haMode: news.haMode,
203 location: news.location,
204 });
205 return toAttributes({ ...created, id: created.id ?? undefined }, accountId);
206 }
207
208 // Sync — diff observed cloud state against desired; skip on no-op.
209 const dirty =
210 (observed.name ?? undefined) !== name ||
211 (news.description !== undefined &&
212 (observed.description ?? undefined) !== news.description) ||
213 (connectorId !== undefined && (observed.connectorId ?? undefined) !== connectorId) ||
214 (secondaryConnectorId !== undefined &&
215 (observed.secondaryConnectorId ?? undefined) !== secondaryConnectorId) ||
216 locationDirty(observed.location, news.location);
217 if (dirty) {
218 const updated = yield* magicTransit.updateSite({
219 accountId,
220 siteId: observed.id!,
221 name,
222 description: news.description,
223 connectorId,
224 secondaryConnectorId,
225 location: news.location,
226 });
227 observed = { ...updated, id: updated.id ?? observed.id };
228 }
229
230 return toAttributes(observed, accountId);
231 }),
232
233 delete: Effect.fn(function* ({ output }) {
234 yield* magicTransit
235 .deleteSite({
236 accountId: output.accountId,
237 siteId: output.siteId,
238 })
239 .pipe(Effect.catchTag("SiteNotFound", () => Effect.void));
240 }),
241 });
242
243 interface ObservedSite {
244 id?: string | null;
245 name?: string | null;
246 description?: string | null;
247 connectorId?: string | null;
248 secondaryConnectorId?: string | null;
249 haMode?: boolean | null;
250 location?: { lat?: string | null; lon?: string | null } | null;
251 }
252
253 /**
254 * Read a site by id, mapping "gone" (`SiteNotFound`, HTTP 404) to
255 * `undefined`.
256 */
257 const getSite = (accountId: string, siteId: string) =>
258 magicTransit.getSite({ accountId, siteId }).pipe(
259 Effect.map((s): ObservedSite | undefined => s),
260 Effect.catchTag("SiteNotFound", () => Effect.undefined),
261 );
262
263 /**
264 * Find a site by exact name. Site names are not enforced unique on
265 * Cloudflare's side, so pick the first match deterministically by id.
266 */
267 const findByName = (accountId: string, name: string) =>
268 magicTransit.listSites({ accountId }).pipe(
269 Effect.map((r): ObservedSite | undefined =>
270 r.result
271 .filter((s) => s.name === name)
272 .sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""))
273 .at(0),
274 ),
275 );
276
277 const createSiteName = (id: string, name: string | undefined) =>
278 Effect.gen(function* () {
279 return name ?? (yield* createPhysicalName({ id, lowercase: true }));
280 });
281
282 const locationDirty = (
283 observed: ObservedSite["location"],
284 desired: MagicSiteLocation | undefined,
285 ): boolean => {
286 if (desired === undefined) return false;
287 return (
288 (desired.lat !== undefined && (observed?.lat ?? undefined) !== desired.lat) ||
289 (desired.lon !== undefined && (observed?.lon ?? undefined) !== desired.lon)
290 );
291 };
292
293 const toAttributes = (site: ObservedSite, accountId: string): MagicSiteAttributes => ({
294 siteId: site.id ?? "",
295 accountId,
296 name: site.name ?? "",
297 description: site.description ?? undefined,
298 connectorId: site.connectorId ?? undefined,
299 secondaryConnectorId: site.secondaryConnectorId ?? undefined,
300 haMode: site.haMode ?? undefined,
301 location: site.location
302 ? {
303 lat: site.location.lat ?? undefined,
304 lon: site.location.lon ?? undefined,
305 }
306 : undefined,
307 });