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

main
ts 272 lines 9.47 KB
Raw
1 import * as addressing from "@distilled.cloud/cloudflare/addressing";
2 import { isResolved } from "alchemy/Diff";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import * as Effect from "effect/Effect";
6 import * as Predicate from "effect/Predicate";
7 import * as Stream from "effect/Stream";
8 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
9 import type { Providers } from "../Providers.ts";
10
11 const TypeId = "Cloudflare.Addressing.Prefix" as const;
12 type TypeId = typeof TypeId;
13
14 export interface PrefixProps {
15 /**
16 * IP Prefix in Classless Inter-Domain Routing format (e.g.
17 * `192.0.2.0/24`). Immutable — changing it forces a replacement.
18 */
19 cidr: string;
20 /**
21 * Autonomous System Number (ASN) the prefix will be advertised under.
22 * Immutable — changing it forces a replacement.
23 */
24 asn: number;
25 /**
26 * Description of the prefix. The only mutable field — patched in place
27 * via `patchPrefix`.
28 */
29 description?: string;
30 /**
31 * Identifier for an uploaded LOA (Letter of Authorization) document.
32 * Create-only — changing it forces a replacement.
33 */
34 loaDocumentId?: string;
35 /**
36 * Whether Cloudflare is allowed to generate the LOA document on behalf of
37 * the prefix owner. Create-only — changing it forces a replacement.
38 * @default false
39 */
40 delegateLoaCreation?: boolean;
41 }
42
43 export interface PrefixAttributes {
44 /** Cloudflare-assigned identifier of the IP Prefix. */
45 prefixId: string;
46 /** The Cloudflare account the prefix belongs to. */
47 accountId: string;
48 /** IP Prefix in CIDR format. */
49 cidr: string;
50 /** ASN the prefix is advertised under. */
51 asn: number;
52 /** Approval state of the prefix (`P` = pending, `V` = active). */
53 approved: string | undefined;
54 /** State of the ownership validation for the prefix. */
55 ownershipValidationState: string | undefined;
56 /** Token provided to demonstrate ownership of the prefix. */
57 ownershipValidationToken: string | undefined;
58 /** State of the IRR validation for the prefix. */
59 irrValidationState: string | undefined;
60 /** State of the RPKI validation for the prefix. */
61 rpkiValidationState: string | undefined;
62 /** Identifier of the uploaded LOA document, if any. */
63 loaDocumentId: string | undefined;
64 /** The prefix description, if set. */
65 description: string | undefined;
66 /** ISO8601 creation timestamp. */
67 createdAt: string | undefined;
68 /** ISO8601 last-modified timestamp. */
69 modifiedAt: string | undefined;
70 }
71
72 export type Prefix = Resource<TypeId, PrefixProps, PrefixAttributes, never, Providers>;
73
74 /**
75 * A BYOIP (Bring Your Own IP) prefix onboarded to Cloudflare's network.
76 *
77 * Requires the BYOIP enterprise add-on; onboarding a prefix is a contract
78 * process (LOA, IRR/RPKI validation, manual approval) — `approved` flips
79 * from `"P"` (pending) to `"V"` (active) on Cloudflare's side and is never
80 * waited on by this resource.
81 *
82 * Only `description` is mutable; `cidr`, `asn`, and the LOA settings force
83 * a replacement.
84 * ### Creating a Prefix
85 * **Example:** Onboard a prefix with a pre-uploaded LOA
86 * ```typescript
87 * const prefix = yield* Cloudflare.Addressing.Prefix("byoip", {
88 * cidr: "192.0.2.0/24",
89 * asn: 64496,
90 * description: "production ingress",
91 * loaDocumentId: loa.id,
92 * });
93 * ```
94 *
95 * **Example:** Delegate LOA creation to Cloudflare
96 * ```typescript
97 * const prefix = yield* Cloudflare.Addressing.Prefix("byoip", {
98 * cidr: "192.0.2.0/24",
99 * asn: 64496,
100 * delegateLoaCreation: true,
101 * });
102 * ```
103 *
104 * ### Advertising the Prefix
105 * **Example:** Advertise via a BGP prefix
106 * ```typescript
107 * const bgp = yield* Cloudflare.Addressing.BgpPrefix("advertise", {
108 * prefixId: prefix.prefixId,
109 * cidr: prefix.cidr,
110 * advertised: true,
111 * });
112 * ```
113 *
114 * @see https://developers.cloudflare.com/byoip/
115 *
116 * @resource
117 * @product Addressing
118 * @category Network
119 */
120 export const Prefix = Resource<Prefix>(TypeId);
121
122 /**
123 * Returns true if the given value is an Prefix resource.
124 */
125 export const isPrefix = (value: unknown): value is Prefix =>
126 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
127
128 export const PrefixProvider = () =>
129 Provider.succeed(Prefix, {
130 stables: ["prefixId", "accountId", "cidr", "asn", "ownershipValidationToken", "createdAt"],
131
132 diff: Effect.fn(function* ({ olds, news, output }) {
133 if (olds === undefined) return undefined;
134 if (!isResolved(news) || !isResolved(olds)) return undefined;
135 // cidr / asn / LOA settings are create-only.
136 if (news.cidr !== (output?.cidr ?? olds.cidr)) {
137 return { action: "replace" } as const;
138 }
139 if (news.asn !== (output?.asn ?? olds.asn)) {
140 return { action: "replace" } as const;
141 }
142 if (
143 typeof news.loaDocumentId === "string" &&
144 typeof olds.loaDocumentId === "string" &&
145 news.loaDocumentId !== olds.loaDocumentId
146 ) {
147 return { action: "replace" } as const;
148 }
149 if ((news.delegateLoaCreation ?? false) !== (olds.delegateLoaCreation ?? false)) {
150 return { action: "replace" } as const;
151 }
152 return undefined;
153 }),
154
155 // BYOIP prefixes are account-scoped; the catalog list endpoint returns
156 // the full prefix object per item, so each row hydrates directly into the
157 // same `Attributes` shape `read` produces — no per-item fetch needed.
158 list: Effect.fn(function* () {
159 const { accountId } = yield* yield* CloudflareEnvironment;
160 return yield* addressing.listPrefixes.pages({ accountId }).pipe(
161 Stream.runCollect,
162 Effect.map((chunk) =>
163 Array.from(chunk).flatMap((page) =>
164 (page.result ?? []).map((p) => toAttributes(p, accountId)),
165 ),
166 ),
167 );
168 }),
169
170 read: Effect.fn(function* ({ output, olds }) {
171 const { accountId } = yield* yield* CloudflareEnvironment;
172 const acct = output?.accountId ?? accountId;
173
174 if (output?.prefixId) {
175 const observed = yield* getPrefix(acct, output.prefixId);
176 return observed ? toAttributes(observed, acct) : undefined;
177 }
178 // Cold read — a CIDR is unique per account, so match on it.
179 const cidr = output?.cidr ?? olds?.cidr;
180 if (typeof cidr !== "string") return undefined;
181 const match = yield* findByCidr(acct, cidr);
182 return match ? toAttributes(match, acct) : undefined;
183 }),
184
185 reconcile: Effect.fn(function* ({ news, output }) {
186 const { accountId } = yield* yield* CloudflareEnvironment;
187 const acct = output?.accountId ?? accountId;
188
189 // 1. Observe — the prefix id on `output` is a hint; a missing prefix
190 // falls through to the by-CIDR lookup and then to create.
191 let observed = output?.prefixId ? yield* getPrefix(acct, output.prefixId) : undefined;
192 if (!observed) {
193 observed = yield* findByCidr(acct, news.cidr);
194 }
195
196 // 2. Ensure — create the prefix if it is missing.
197 if (!observed) {
198 const created = yield* addressing.createPrefix({
199 accountId: acct,
200 cidr: news.cidr,
201 asn: news.asn,
202 description: news.description,
203 loaDocumentId: news.loaDocumentId as string | undefined,
204 delegateLoaCreation: news.delegateLoaCreation,
205 });
206 return toAttributes(created, acct);
207 }
208
209 // 3. Sync — `description` is the only mutable field; skip the PATCH
210 // entirely on a no-op.
211 const desiredDescription = news.description ?? "";
212 if ((observed.description ?? "") !== desiredDescription) {
213 const patched = yield* addressing.patchPrefix({
214 accountId: acct,
215 prefixId: observed.id ?? "",
216 description: desiredDescription,
217 });
218 return toAttributes(patched, acct);
219 }
220
221 return toAttributes(observed, acct);
222 }),
223
224 delete: Effect.fn(function* ({ output }) {
225 // Deleting an onboarded prefix can be rejected while service bindings
226 // or BGP advertisements still exist — children delete first; the
227 // engine orders dependencies, so a hard failure here is genuine.
228 yield* addressing
229 .deletePrefix({
230 accountId: output.accountId,
231 prefixId: output.prefixId,
232 })
233 .pipe(Effect.catchTag("PrefixNotFound", () => Effect.void));
234 }),
235 });
236
237 /**
238 * Read a prefix by id, mapping "gone" (`PrefixNotFound`, Cloudflare error
239 * code 1000 `not_found`) to `undefined`.
240 */
241 const getPrefix = (accountId: string, prefixId: string) =>
242 addressing
243 .getPrefix({ accountId, prefixId })
244 .pipe(Effect.catchTag("PrefixNotFound", () => Effect.undefined));
245
246 /**
247 * Find a prefix by exact CIDR — unique per account.
248 */
249 const findByCidr = (accountId: string, cidr: string) =>
250 addressing.listPrefixes.items({ accountId }).pipe(
251 Stream.runCollect,
252 Effect.map((chunk) => Array.from(chunk).find((p) => p.cidr === cidr)),
253 );
254
255 const toAttributes = (
256 prefix: addressing.GetPrefixResponse,
257 accountId: string,
258 ): PrefixAttributes => ({
259 prefixId: prefix.id ?? "",
260 accountId,
261 cidr: prefix.cidr ?? "",
262 asn: prefix.asn ?? 0,
263 approved: prefix.approved ?? undefined,
264 ownershipValidationState: prefix.ownershipValidationState ?? undefined,
265 ownershipValidationToken: prefix.ownershipValidationToken ?? undefined,
266 irrValidationState: prefix.irrValidationState ?? undefined,
267 rpkiValidationState: prefix.rpkiValidationState ?? undefined,
268 loaDocumentId: prefix.loaDocumentId ?? undefined,
269 description: prefix.description ?? undefined,
270 createdAt: prefix.createdAt ?? undefined,
271 modifiedAt: prefix.modifiedAt ?? undefined,
272 });