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

main
ts 522 lines 17.3 KB
Raw
1 import type { IPAssignment as FlyIPAssignment } from "@distilled.cloud/fly-io/machines";
2 import * as machines from "@distilled.cloud/fly-io/machines";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import * as Schedule from "effect/Schedule";
9 import { listOwnedApps } from "./App.ts";
10 import type { App } from "./App.ts";
11 import type { Providers } from "./Providers.ts";
12
13 /**
14 * A resource-valued prop: the resource itself, or an Effect that produces
15 * it (so `yield* App(...)` and `App(...)` both type-check).
16 */
17 type Ref<T> = T | Effect.Effect<T, never, Providers>;
18
19 /**
20 * Fly IP family allocated onto an App. Dedicated `v4` is billed and may
21 * be rejected when the org has no IPv4 quota. Prefer `v6` (free) or
22 * `shared_v4` (free) in tests. `private_v6` is a Flycast address: it is
23 * reachable only from the organization's private network.
24 */
25 export type IpAssignmentType = "v4" | "v6" | "shared_v4" | "private_v6";
26
27 export interface IpAssignmentProps {
28 /**
29 * Parent Fly App. Accepts a `Fly.App` resource or an Effect that
30 * produces one. Changing the App replaces the assignment.
31 */
32 app: Ref<App>;
33 /**
34 * Address family to allocate. `v6` is a dedicated IPv6 (free).
35 * `shared_v4` is a shared Anycast IPv4 (free). `v4` is a dedicated
36 * IPv4 (billed; may 400 when the org is over quota). `private_v6` is
37 * a Flycast IPv6 (free) that Fly's proxy serves only inside the
38 * private network. Changing type replaces the assignment.
39 */
40 type: IpAssignmentType;
41 /**
42 * Region for a dedicated address. Changing it replaces the assignment.
43 */
44 region?: string;
45 /**
46 * Private network a `private_v6` address is reachable from. Defaults
47 * to the organization's network. Create-only; changing it replaces.
48 */
49 network?: string;
50 /**
51 * Organization slug. Defaults to the current token's org. Not a
52 * replacement key.
53 */
54 orgSlug?: string;
55 /**
56 * Fly proxy service this address is bound to. Changing it replaces
57 * the assignment.
58 */
59 serviceName?: string;
60 }
61
62 export type IpAssignment = Resource<
63 "Fly.IpAssignment",
64 IpAssignmentProps,
65 {
66 /** Physical Fly App name the address is assigned to. */
67 appName: string;
68 /** Allocated address. Identity of the assignment. */
69 ip: string;
70 /** Observed address family. */
71 type: IpAssignmentType;
72 /** Region for a dedicated address, if set. */
73 region: string | undefined;
74 /** Fly proxy service this address is bound to, if set. */
75 serviceName: string | undefined;
76 /** Whether the address is a shared Anycast IPv4. */
77 shared: boolean;
78 /**
79 * Named private network a `private_v6` address is reachable from.
80 * `undefined` for the organization's default network and for public
81 * addresses.
82 */
83 network: string | undefined;
84 /** RFC3339 creation timestamp, if the API returned one. */
85 createdAt: string | undefined;
86 },
87 never,
88 Providers
89 >;
90
91 const resolveIpAssignmentProps = (
92 props: IpAssignmentProps | Effect.Effect<IpAssignmentProps, never, Providers>,
93 ): Effect.Effect<IpAssignmentProps, never, Providers> =>
94 Effect.gen(function* () {
95 const resolved = Effect.isEffect(props) ? yield* props : props;
96 if (globalThis.__ALCHEMY_RUNTIME__) return resolved;
97 const app = Effect.isEffect(resolved.app)
98 ? yield* resolved.app as Effect.Effect<App, never, Providers>
99 : resolved.app;
100 return { ...resolved, app };
101 });
102
103 const IpAssignmentResource = Resource<IpAssignment>("Fly.IpAssignment");
104
105 /**
106 * A Fly.IpAssignment is an address on an {@link App}. A {@link Service}
107 * publishes ports. Fly's proxy load-balances `{app}.fly.dev` across
108 * Machines that publish a proxy service.
109 *
110 * Identity is the allocated `ip`. There is no in-place update.
111 *
112 * @see https://fly.io/docs/networking/services/
113 *
114 * ### Shared IPv4
115 * `shared_v4` is a shared Anycast IPv4. It is free. This is what you
116 * want for fly.dev over IPv4. Yield it next to the Service.
117 *
118 * **Example:** Allocate shared_v4
119 * ```typescript
120 * export const PublicIp = Fly.IpAssignment("Shared", {
121 * app: Site,
122 * type: "shared_v4",
123 * });
124 * ```
125 *
126 * :::caution[Changing `type` or `app` replaces the assignment]
127 * A new address is allocated. The old one is released.
128 * :::
129 *
130 * ### Dedicated IPv6
131 * `v6` is a dedicated IPv6. It is free.
132 *
133 * **Example:** Allocate v6
134 * ```typescript
135 * export const V6 = Fly.IpAssignment("V6", {
136 * app: Site,
137 * type: "v6",
138 * });
139 * ```
140 *
141 * ### Dedicated IPv4
142 * `v4` is a billed dedicated IPv4. It may 400 if the org has no
143 * quota. Prefer `shared_v4` or `v6` in tests.
144 *
145 * **Example:** Allocate v4
146 * ```typescript
147 * export const Dedicated = Fly.IpAssignment("Dedicated", {
148 * app: Site,
149 * type: "v4",
150 * });
151 * ```
152 *
153 * ### Flycast (private IPv6)
154 * `private_v6` is a Flycast address. Fly's proxy serves it only inside
155 * the organization's private network, at `{app}.flycast`. It is free.
156 * Use it for a backend that another App calls and the internet must
157 * not reach. Requests still go through the proxy, so blue/green
158 * cordoning, `autostart`, and `autostop` keep working. Allocate no
159 * public address on the same App.
160 *
161 * **Example:** Allocate private_v6
162 * ```typescript
163 * export const Private = Fly.IpAssignment("Private", {
164 * app: Backend,
165 * type: "private_v6",
166 * });
167 * ```
168 *
169 * ### Region
170 * `region` pins a dedicated address. Shared Anycast ignores it. See
171 * [Regions](/fly/compute/regions) for the list of codes.
172 *
173 * **Example:** Dedicated IPv4 in iad
174 * ```typescript
175 * export const Dedicated = Fly.IpAssignment("Dedicated", {
176 * app: Site,
177 * type: "v4",
178 * region: "iad",
179 * });
180 * ```
181 *
182 * :::caution[Changing `region` replaces the assignment]
183 * A new address is allocated in the new region.
184 * :::
185 *
186 * ### Service name
187 * `serviceName` binds the address to a Fly proxy service. Changing it
188 * replaces the assignment.
189 *
190 * **Example:** Bind to a named service
191 * ```typescript
192 * export const PublicIp = Fly.IpAssignment("Shared", {
193 * app: Site,
194 * type: "shared_v4",
195 * serviceName: "http",
196 * });
197 * ```
198 *
199 * :::caution[Changing `serviceName` replaces the assignment]
200 * A new address is allocated bound to the new service.
201 * :::
202 *
203 * ### Isolated network
204 * `network` names the private network a `private_v6` address is
205 * reachable from. Create-only.
206 *
207 * **Example:** Custom network
208 * ```typescript
209 * export const Private = Fly.IpAssignment("Private", {
210 * app: Backend,
211 * type: "private_v6",
212 * network: "tenant-a",
213 * });
214 * ```
215 *
216 * :::caution[Changing `network` replaces the assignment]
217 * A new address is allocated on the new network.
218 * :::
219 *
220 * ### Organization
221 * `orgSlug` defaults to the current token's org. It is not a
222 * replacement key.
223 *
224 * **Example:** Pin an org
225 * ```typescript
226 * export const PublicIp = Fly.IpAssignment("Shared", {
227 * app: Site,
228 * type: "shared_v4",
229 * orgSlug: "my-org",
230 * });
231 * ```
232 *
233 * ### Yield with a Service
234 * Allocate the address on the same App as the Service. `api.url` is
235 * `https://{appName}.fly.dev`.
236 *
237 * **Example:** Stack outputs
238 * ```typescript
239 * export default Alchemy.Stack(
240 * "MyApp",
241 * { providers: Fly.providers(), state: Alchemy.localState() },
242 * Effect.gen(function* () {
243 * const api = yield* Api;
244 * const ip = yield* PublicIp;
245 * return { url: api.url, ip: ip.ip };
246 * }),
247 * );
248 * ```
249 *
250 * @resource
251 * @product App
252 */
253 export const IpAssignment: typeof IpAssignmentResource = Object.assign(
254 (id: string, props: IpAssignmentProps | Effect.Effect<IpAssignmentProps, never, Providers>) =>
255 IpAssignmentResource(id, resolveIpAssignmentProps(props)),
256 IpAssignmentResource,
257 );
258
259 export class IpAssignmentNotCreated extends Data.TaggedError("Fly.IpAssignmentNotCreated")<{
260 appName: string;
261 type: IpAssignmentType;
262 }> {}
263
264 export class IpAssignmentAppMissing extends Data.TaggedError("Fly.IpAssignmentAppMissing")<{
265 type: IpAssignmentType;
266 }> {}
267
268 const appNameOf = (value: unknown): string | undefined => {
269 if (value === null || typeof value !== "object") return undefined;
270 const rec = value as { appName?: unknown; name?: unknown };
271 if (typeof rec.appName === "string" && rec.appName.length > 0) {
272 return rec.appName;
273 }
274 if (typeof rec.name === "string" && rec.name.length > 0) {
275 return rec.name;
276 }
277 return undefined;
278 };
279
280 const asType = (value: string | undefined): IpAssignmentType | undefined =>
281 value === "v4" || value === "v6" || value === "shared_v4" || value === "private_v6"
282 ? value
283 : undefined;
284
285 /**
286 * Fly omits `type` from IP assignment responses. Only Flycast addresses carry
287 * a `network` (its name is empty for the organization's default network).
288 */
289 const isFlycast = (assignment: FlyIPAssignment) =>
290 assignment.network !== undefined && assignment.network !== null;
291
292 const networkOf = (assignment: FlyIPAssignment) => assignment.network?.name || undefined;
293
294 const inferType = (assignment: FlyIPAssignment, fallback?: IpAssignmentType): IpAssignmentType => {
295 const wire = asType(assignment.type);
296 if (wire !== undefined) return wire;
297 if (assignment.shared === true) return "shared_v4";
298 if (isFlycast(assignment)) return "private_v6";
299 const ip = assignment.ip ?? "";
300 if (ip.includes(":")) return "v6";
301 if (fallback !== undefined) return fallback;
302 return ip.length > 0 ? "v4" : (fallback ?? "v4");
303 };
304
305 const toAttrs = (
306 appName: string,
307 assignment: FlyIPAssignment,
308 fallbackType?: IpAssignmentType,
309 ): IpAssignment["Attributes"] => {
310 const type = inferType(assignment, fallbackType);
311 return {
312 appName,
313 ip: assignment.ip ?? "",
314 type,
315 region: assignment.region,
316 serviceName: assignment.service_name,
317 shared: type === "shared_v4" || assignment.shared === true,
318 network: networkOf(assignment),
319 createdAt: assignment.created_at,
320 };
321 };
322
323 const matchesDesired = (
324 assignment: FlyIPAssignment,
325 news: Pick<IpAssignmentProps, "type" | "region" | "serviceName" | "network">,
326 ): boolean => {
327 if (inferType(assignment, news.type) !== news.type) return false;
328 if (news.type === "private_v6" && networkOf(assignment) !== news.network) return false;
329 if (news.region !== undefined && assignment.region !== news.region) {
330 return false;
331 }
332 if (news.serviceName !== undefined && assignment.service_name !== news.serviceName) {
333 return false;
334 }
335 return true;
336 };
337
338 const listAssignments = (appName: string) =>
339 machines.listAppIPAssignments({ app_name: appName }).pipe(
340 Effect.map((res) => res.ips ?? []),
341 Effect.catchTag(["NotFound", "Forbidden"], () => Effect.succeed([] as FlyIPAssignment[])),
342 );
343
344 const findByIp = (appName: string, ip: string) =>
345 listAssignments(appName).pipe(Effect.map((ips) => ips.find((item) => item.ip === ip)));
346
347 const findMatching = (
348 appName: string,
349 news: Pick<IpAssignmentProps, "type" | "region" | "serviceName" | "network">,
350 ) =>
351 listAssignments(appName).pipe(
352 Effect.map((ips) => ips.find((item) => matchesDesired(item, news))),
353 );
354
355 const waitUntilGone = (appName: string, ip: string) =>
356 findByIp(appName, ip).pipe(
357 Effect.map((found) => found === undefined),
358 Effect.repeat({ schedule: Schedule.spaced("1 second"), until: (gone) => gone, times: 8 }),
359 );
360
361 /** Whether the App has any address reachable from the internet. */
362 export const hasPublicAddress = (appName: string) =>
363 listAssignments(appName).pipe(
364 Effect.map((ips) => ips.some((item) => inferType(item) !== "private_v6")),
365 );
366
367 /**
368 * Converge the addresses of an App a {@link Service} owns. Every owned App
369 * gets a Flycast address on its private network (the organization's
370 * default network when `network` is omitted). A public App also gets a
371 * shared IPv4 and an IPv6; a private one has every public address
372 * released. All three types are free.
373 */
374 export const syncOwnedAppAddresses = Effect.fn(function* (
375 appName: string,
376 isPublic: boolean,
377 network?: string,
378 ) {
379 const observed = yield* listAssignments(appName);
380 const isDesiredFlycast = (item: FlyIPAssignment) =>
381 inferType(item) === "private_v6" && networkOf(item) === network;
382 if (!observed.some(isDesiredFlycast)) {
383 yield* machines
384 .createAppIPAssignment({ app_name: appName, type: "private_v6", network })
385 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
386 }
387 if (isPublic) {
388 for (const type of ["shared_v4", "v6"] as const) {
389 if (observed.some((item) => inferType(item) === type)) continue;
390 yield* machines
391 .createAppIPAssignment({ app_name: appName, type })
392 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
393 }
394 }
395 // Release public addresses of a private Service and Flycast addresses
396 // on any other network.
397 for (const item of observed) {
398 if (item.ip === undefined || isDesiredFlycast(item)) continue;
399 if (isPublic && inferType(item) !== "private_v6") continue;
400 yield* machines
401 .deleteAppIPAssignment({ app_name: appName, ip: item.ip })
402 .pipe(Effect.catchTag("NotFound", () => Effect.void));
403 yield* waitUntilGone(appName, item.ip);
404 }
405 });
406
407 /**
408 * Add a Flycast address on `network` to an App a {@link Service} shares,
409 * so bound callers can reach it. Only ever adds; the address is removed
410 * with the App.
411 */
412 export const ensureFlycastAddress = Effect.fn(function* (appName: string, network?: string) {
413 const observed = yield* listAssignments(appName);
414 if (observed.some((item) => inferType(item) === "private_v6" && networkOf(item) === network))
415 return;
416 yield* machines
417 .createAppIPAssignment({ app_name: appName, type: "private_v6", network })
418 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
419 });
420
421 export const IpAssignmentProvider = () =>
422 Provider.succeed(IpAssignment, {
423 stables: ["ip", "appName", "type", "region"],
424 nuke: { dependsOn: ["Fly.App"] },
425
426 diff: Effect.fn(function* ({ news, olds, output }) {
427 if (news === undefined || !isResolved(news)) return undefined;
428 if (output === undefined) return undefined;
429 const appName = appNameOf(news.app);
430 const appChanged = appName !== undefined && appName !== output.appName;
431 const typeChanged = news.type !== output.type;
432 const regionChanged = news.region !== undefined && news.region !== output.region;
433 const serviceChanged =
434 news.serviceName !== undefined && news.serviceName !== output.serviceName;
435 const networkChanged = news.network !== (olds !== undefined ? olds.network : output.network);
436 if (appChanged || typeChanged || regionChanged || serviceChanged || networkChanged) {
437 return { action: "replace" as const };
438 }
439 return undefined;
440 }),
441
442 read: Effect.fn(function* ({ olds, output }) {
443 const appName = output?.appName ?? appNameOf(olds?.app);
444 if (appName === undefined) return undefined;
445 const found =
446 output?.ip !== undefined && output.ip.length > 0
447 ? yield* findByIp(appName, output.ip)
448 : olds !== undefined
449 ? yield* findMatching(appName, olds)
450 : undefined;
451 if (found === undefined || found.ip === undefined) return undefined;
452 return toAttrs(appName, found, output?.type ?? olds?.type);
453 }),
454
455 list: Effect.fn(function* () {
456 const apps = yield* listOwnedApps();
457 const rows = yield* Effect.forEach(
458 apps,
459 (app) =>
460 listAssignments(app.appName).pipe(
461 Effect.map((ips) =>
462 ips
463 .filter((item) => item.ip !== undefined && item.ip.length > 0)
464 .map((item) => toAttrs(app.appName, item)),
465 ),
466 ),
467 { concurrency: 8 },
468 );
469 return rows.flat();
470 }),
471
472 reconcile: Effect.fn(function* ({ news, output }) {
473 const props = news ?? ({} as IpAssignmentProps);
474 const appName = appNameOf(props.app) ?? output?.appName;
475 if (appName === undefined) {
476 return yield* new IpAssignmentAppMissing({ type: props.type });
477 }
478
479 // Observe by cached ip, then by desired type/region/service.
480 let current =
481 output?.ip !== undefined && output.ip.length > 0
482 ? yield* findByIp(appName, output.ip)
483 : undefined;
484 if (current === undefined) {
485 current = yield* findMatching(appName, props);
486 }
487
488 if (current === undefined) {
489 const created = yield* machines
490 .createAppIPAssignment({
491 app_name: appName,
492 type: props.type,
493 region: props.region,
494 network: props.network,
495 org_slug: props.orgSlug,
496 service_name: props.serviceName,
497 })
498 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
499 if (created !== undefined && created.ip !== undefined) {
500 current = created;
501 } else {
502 current = yield* findMatching(appName, props);
503 }
504 }
505
506 if (current === undefined || current.ip === undefined) {
507 return yield* new IpAssignmentNotCreated({ appName, type: props.type });
508 }
509
510 return toAttrs(appName, current, props.type);
511 }),
512
513 delete: Effect.fn(function* ({ output }) {
514 const appName = output.appName;
515 const ip = output.ip;
516 if (appName.length === 0 || ip.length === 0) return;
517 yield* machines
518 .deleteAppIPAssignment({ app_name: appName, ip })
519 .pipe(Effect.catchTag("NotFound", () => Effect.void));
520 yield* waitUntilGone(appName, ip);
521 }),
522 });