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

main
ts 673 lines 20.5 KB
Raw
1 import type { SpriteResponse as FlySprite } from "@distilled.cloud/fly-io/sprites";
2 import * as sprites from "@distilled.cloud/fly-io/sprites";
3 import { Unowned } from "alchemy/AdoptPolicy";
4 import * as Bundle from "alchemy/Bundle/Bundle";
5 import { isResolved } from "alchemy/Diff";
6 import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
7 import * as Provider from "alchemy/Provider";
8 import type { Resource, ResourceBinding } from "alchemy/Resource";
9 import type { ServerHost } from "alchemy/Runtime/Process";
10 import { Stack } from "alchemy/Stack";
11 import { createInternalTags } from "alchemy/Tags";
12 import * as Data from "effect/Data";
13 import * as Duration from "effect/Duration";
14 import * as Effect from "effect/Effect";
15 import * as Redacted from "effect/Redacted";
16 import * as Schedule from "effect/Schedule";
17 import * as Stream from "effect/Stream";
18 import {
19 createFlyHostRuntimeContext,
20 createSpriteHostedSupport,
21 DEFAULT_PORT,
22 type FlyHostRuntimeContext,
23 type HostedProgramProps,
24 } from "./hosted.ts";
25 import {
26 createFlyResourceName,
27 matchesAlchemyPhysicalName,
28 sanitizeFlyAppName,
29 } from "./Metadata.ts";
30 import type { Providers } from "./Providers.ts";
31
32 const DEFAULT_URL_AUTH: UrlAuth = "public";
33 const APP_DIR = "/home/sprite/alchemy";
34 const BUN_BIN = "/home/sprite/.bun/bin/bun";
35 const SERVICE_NAME = "alchemy";
36 const OWNER_LABEL = "alchemy.type=Fly.Sprite";
37
38 const backoff = Schedule.min([
39 Schedule.exponential(Duration.millis(500), 1.5),
40 Schedule.spaced(Duration.seconds(5)),
41 ]);
42
43 export type UrlAuth = "public" | "sprite";
44
45 export type SpriteStatus = "cold" | "warm" | "running";
46
47 export interface SpriteProps extends PlatformProps {
48 /**
49 * Module entrypoint bundled with rolldown and written onto the Sprite.
50 * Typically `import.meta.url`. A content-hash change updates in place.
51 */
52 main: string;
53 /**
54 * Sprite name. Unique per organization. If omitted, a unique name is
55 * generated from the stack, stage and logical ID. Changing it replaces
56 * the Sprite.
57 */
58 name?: string;
59 /**
60 * Who can hit {@link Sprite} `url`. `public` is open. `sprite` requires
61 * Sprites auth.
62 *
63 * @default "public"
64 */
65 urlAuth?: UrlAuth;
66 /**
67 * Port the hosted HTTP server listens on. Written to `PORT` and used
68 * as the Sprite service `http_port`.
69 *
70 * @default 3000
71 */
72 port?: number;
73 /**
74 * Named export to load from `main`.
75 *
76 * @default "default"
77 */
78 handler?: string;
79 /**
80 * Additional environment variables for the hosted process. Merged
81 * after binding-injected `env`.
82 */
83 env?: Record<string, any>;
84 /**
85 * Bundler configuration for `main`: rolldown `input`/`output`
86 * overrides plus pure-annotation options (`pure`).
87 */
88 build?: Bundle.BundleConfig;
89 }
90
91 /**
92 * Binding contract accepted by {@link Sprite} for injected env.
93 */
94 export interface SpriteBinding {
95 env?: Record<string, any>;
96 }
97
98 export type Sprite = Resource<
99 "Fly.Sprite",
100 SpriteProps,
101 {
102 /** Fly Sprite id. */
103 spriteId: string;
104 /** Physical Sprite name (unique per org). */
105 name: string;
106 /**
107 * Public Sprite URL (`https://{name}-….sprites.app`).
108 */
109 url: string;
110 /** Observed runtime status. Hibernates to `cold` when idle. */
111 status: SpriteStatus;
112 /** Observed URL auth setting. */
113 urlAuth: UrlAuth;
114 /** Organization slug, if the API returned one. */
115 orgSlug: string | undefined;
116 /** Content hash of the bundled program. */
117 code: {
118 hash: string;
119 };
120 },
121 SpriteBinding,
122 Providers
123 >;
124
125 export const isSprite = (value: unknown): value is Sprite =>
126 typeof value === "object" && value !== null && (value as { Type?: string }).Type === "Fly.Sprite";
127
128 export type SpriteServices = ServerHost;
129
130 export type SpriteShape = Main<SpriteServices>;
131
132 export type SpriteRuntimeContext = FlyHostRuntimeContext;
133
134 /**
135 * A Sprite is an Effect program running in a Fly.io Sprite. Sprites
136 * are org-scoped Linux sandboxes. They hibernate when idle and wake
137 * on demand. There is no parent {@link App}. Unlike a {@link Service},
138 * Alchemy does not build a Docker image.
139 *
140 * @see https://sprites.dev/api/sprites
141 *
142 * ### Declare a Sprite
143 * A Sprite is a class. Props describe the sandbox. The Effect is the
144 * program that runs on it. There is no parent App.
145 *
146 * `main: import.meta.url` is the bundle entrypoint. Alchemy bundles
147 * this file with Rolldown, writes it onto the Sprite, and runs it as
148 * a Sprite service on {@link port}. Auth is `FLY_API_TOKEN`.
149 *
150 * **Example:** Class + main
151 * ```typescript
152 * export default class Box extends Fly.Sprite<Box>()(
153 * "Box",
154 * { main: import.meta.url },
155 * Effect.gen(function* () {
156 * return {};
157 * }),
158 * ) {}
159 * ```
160 *
161 * ### Serve HTTP with fetch
162 * Return `fetch` from the init Effect to boot an HTTP server. The
163 * Sprite URL proxies to {@link port}.
164 *
165 * **Example:** Hello
166 * ```typescript
167 * export default class Box extends Fly.Sprite<Box>()(
168 * "Box",
169 * { main: import.meta.url },
170 * Effect.gen(function* () {
171 * return {
172 * fetch: Effect.succeed(HttpServerResponse.text("hello")),
173 * };
174 * }),
175 * ) {}
176 * ```
177 *
178 * ### The public URL
179 * Yield the Sprite in the Stack. `box.url` is
180 * `https://{name}-….sprites.app`.
181 *
182 * **Example:** Stack output
183 * ```typescript
184 * export default Alchemy.Stack(
185 * "MyApp",
186 * { providers: Fly.providers(), state: Alchemy.localState() },
187 * Effect.gen(function* () {
188 * const box = yield* Box;
189 * return { url: box.url };
190 * }),
191 * );
192 * ```
193 *
194 * ### URL auth
195 * `urlAuth` is `public` or `sprite`. Default is `public` so `url`
196 * answers without a Sprites token.
197 *
198 * **Example:** Sprite-auth URL
199 * ```typescript
200 * export default class Box extends Fly.Sprite<Box>()(
201 * "Box",
202 * { main: import.meta.url, urlAuth: "sprite" },
203 * Effect.gen(function* () {
204 * return {
205 * fetch: Effect.succeed(HttpServerResponse.text("hello")),
206 * };
207 * }),
208 * ) {}
209 * ```
210 *
211 * :::note[Default is public]
212 * Fly's API default is `sprite`. Alchemy defaults to `public` so a
213 * `fetch` handler is reachable.
214 * :::
215 *
216 * ### Config
217 * Yield `Config` in init. Alchemy reads the value from the env of
218 * whoever deploys and writes it onto the Sprite. Do not pass
219 * `env: { ... }` on a Sprite.
220 *
221 * Yield `FileSystem.FileSystem` in init, never inside `fetch`.
222 *
223 * **Example:** Config.Redacted
224 * ```typescript
225 * import * as Config from "effect/Config";
226 * import * as FileSystem from "effect/FileSystem";
227 * import * as Redacted from "effect/Redacted";
228 *
229 * export default class Box extends Fly.Sprite<Box>()(
230 * "Box",
231 * { main: import.meta.url },
232 * Effect.gen(function* () {
233 * const apiKey = yield* Config.Redacted("API_KEY");
234 * const fs = yield* FileSystem.FileSystem;
235 * yield* fs.makeDirectory("/tmp", { recursive: true });
236 *
237 * return {
238 * fetch: Effect.gen(function* () {
239 * const token = Redacted.value(apiKey);
240 * return HttpServerResponse.text("ok");
241 * }),
242 * };
243 * }),
244 * ) {}
245 * ```
246 *
247 * ### Exec
248 * {@link Exec} runs a command on the Sprite. Provide {@link ExecHttp}.
249 *
250 * **Example:** ls
251 * ```typescript
252 * const exec = yield* Fly.Exec(Box);
253 * const result = yield* exec({ cmd: ["ls", "-la"] });
254 * ```
255 *
256 * ### Checkpoint
257 * {@link Checkpoint} snapshots and restores the Sprite disk. Provide
258 * {@link CheckpointHttp}.
259 *
260 * **Example:** Create and restore
261 * ```typescript
262 * const checkpoint = yield* Fly.Checkpoint(Box);
263 * yield* checkpoint.create({ comment: "before" });
264 * yield* checkpoint.restore("v1");
265 * ```
266 *
267 * :::caution[Restore is destructive]
268 * The disk rewinds. Later writes are gone.
269 * :::
270 *
271 * ### A stable name
272 * Omit `name` and Alchemy generates one from the stack, stage, and
273 * logical ID.
274 *
275 * **Example:** Explicit name
276 * ```typescript
277 * export default class Box extends Fly.Sprite<Box>()(
278 * "Box",
279 * { main: import.meta.url, name: "box" },
280 * Effect.gen(function* () {
281 * return {
282 * fetch: Effect.succeed(HttpServerResponse.text("hello")),
283 * };
284 * }),
285 * ) {}
286 * ```
287 *
288 * :::caution[Changing `name` replaces the Sprite]
289 * Fly cannot rename a Sprite. Alchemy creates the new name, then
290 * deletes the old one.
291 * :::
292 *
293 * ### Named export
294 * `handler` is the named export to load from `main`. Default is
295 * `"default"`.
296 *
297 * **Example:** Custom handler
298 * ```typescript
299 * export default class Box extends Fly.Sprite<Box>()(
300 * "Box",
301 * { main: import.meta.url, handler: "box" },
302 * Effect.gen(function* () {
303 * return {
304 * fetch: Effect.succeed(HttpServerResponse.text("hello")),
305 * };
306 * }),
307 * ) {}
308 * ```
309 *
310 * @resource
311 * @product Sprite
312 */
313 export const Sprite: Platform<Sprite, SpriteServices, SpriteShape, SpriteRuntimeContext> = Platform(
314 "Fly.Sprite",
315 {
316 createRuntimeContext: createFlyHostRuntimeContext("Fly.Sprite"),
317 },
318 );
319
320 export class SpriteNotCreated extends Data.TaggedError("Fly.SpriteNotCreated")<{
321 resourceName: string;
322 }> {}
323
324 export class SpriteExecFailed extends Data.TaggedError("Fly.SpriteExecFailed")<{
325 resourceName: string;
326 cmd: string;
327 exitCode: number | undefined;
328 stderr: string | undefined;
329 }> {}
330
331 class SpritePending extends Data.TaggedError("Fly.SpritePending")<{
332 resourceName: string;
333 }> {}
334
335 const toStatus = (status: string | undefined): SpriteStatus =>
336 status === "warm" || status === "running" || status === "cold" ? status : "cold";
337
338 const toUrlAuth = (auth: string | undefined): UrlAuth => (auth === "sprite" ? "sprite" : "public");
339
340 const toAttrs = (sprite: FlySprite, name: string, codeHash: string): Sprite["Attributes"] => ({
341 spriteId: sprite.id ?? name,
342 name: sprite.name ?? name,
343 url: sprite.url ?? `https://${name}.sprites.app`,
344 status: toStatus(sprite.status),
345 urlAuth: toUrlAuth(sprite.url_settings?.auth),
346 orgSlug: sprite.organization,
347 code: { hash: codeHash },
348 });
349
350 const isOwnedSprite = (sprite: FlySprite): boolean => {
351 const labels = sprite.labels ?? [];
352 if (labels.includes(OWNER_LABEL)) return true;
353 if (labels.some((label) => label.startsWith("alchemy.type="))) return true;
354 return matchesAlchemyPhysicalName(sprite.name);
355 };
356
357 const resolveSpriteName = (id: string, name: string | undefined, existing?: string) =>
358 Effect.gen(function* () {
359 if (name !== undefined) return sanitizeFlyAppName(name);
360 if (existing !== undefined) return existing;
361 return yield* createFlyResourceName(id);
362 });
363
364 const ownershipLabels = (id: string) =>
365 Effect.gen(function* () {
366 const tags = yield* createInternalTags(id);
367 return [...Object.entries(tags).map(([key, value]) => `${key}=${value}`), OWNER_LABEL];
368 });
369
370 const getByName = (name: string) =>
371 sprites.getSprite({ name }).pipe(Effect.catchTag("NotFound", () => Effect.undefined));
372
373 const waitForSprite = (name: string) =>
374 getByName(name).pipe(
375 Effect.flatMap((found) =>
376 found !== undefined
377 ? Effect.succeed(found)
378 : Effect.fail(new SpritePending({ resourceName: name })),
379 ),
380 Effect.retry({
381 while: (e) => e._tag === "Fly.SpritePending",
382 times: 8,
383 schedule: backoff,
384 }),
385 );
386
387 const isTransient = (e: { readonly _tag: string }) =>
388 e._tag === "NotFound" ||
389 e._tag === "TooManyRequests" ||
390 e._tag === "ServiceUnavailable" ||
391 e._tag === "BadGateway" ||
392 e._tag === "GatewayTimeout";
393
394 const retryTransient = <A, E extends { readonly _tag: string }, R>(
395 effect: Effect.Effect<A, E, R>,
396 ) =>
397 effect.pipe(
398 Effect.retry({
399 while: isTransient,
400 times: 8,
401 schedule: backoff,
402 }),
403 );
404
405 const toEnv = (env: Record<string, any> | undefined): Record<string, string> =>
406 Object.fromEntries(
407 Object.entries(env ?? {}).flatMap(([key, value]) => {
408 if (value === undefined || value === null) return [];
409 const raw = Redacted.isRedacted(value) ? Redacted.value(value) : value;
410 return [[key, String(raw)]];
411 }),
412 );
413
414 const collectBindingEnv = (bindings: readonly ResourceBinding<SpriteBinding>[]) => {
415 const active = bindings.filter(
416 (binding: ResourceBinding<SpriteBinding> & { action?: string }) => binding.action !== "delete",
417 );
418 return active
419 .map((binding) => binding?.data?.env)
420 .reduce<Record<string, any>>((acc, value) => ({ ...acc, ...value }), {});
421 };
422
423 const desiredEnv = (
424 props: SpriteProps,
425 bindingEnv: Record<string, any>,
426 alchemyEnv: Record<string, string>,
427 port: number,
428 ): Record<string, string> => ({
429 ...toEnv(bindingEnv),
430 ...alchemyEnv,
431 PORT: String(port),
432 ...toEnv(props.env),
433 });
434
435 const renderEnvFile = (env: Record<string, string>) =>
436 `${Object.entries(env)
437 .sort(([left], [right]) => left.localeCompare(right))
438 .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
439 .join("\n")}\n`;
440
441 const writeRemoteFile = (input: { name: string; path: string; body: Uint8Array }) =>
442 retryTransient(
443 sprites.writeFile({
444 name: input.name,
445 path: input.path,
446 workingDir: "/",
447 mkdir: true,
448 body: input.body,
449 }),
450 );
451
452 const runExec = (input: { name: string; cmd: string[]; env?: string[] }) =>
453 Effect.gen(function* () {
454 const result = yield* retryTransient(
455 sprites.execCommand({
456 name: input.name,
457 cmd: input.cmd,
458 env: input.env,
459 }),
460 );
461 if ((result.exit_code ?? 0) !== 0) {
462 return yield* new SpriteExecFailed({
463 resourceName: input.name,
464 cmd: input.cmd.join(" "),
465 exitCode: result.exit_code,
466 stderr: result.stderr,
467 });
468 }
469 return result;
470 });
471
472 const ensureBun = (name: string) =>
473 runExec({
474 name,
475 cmd: [
476 "bash",
477 "-lc",
478 [
479 "set -euo pipefail",
480 "export HOME=/home/sprite",
481 "export BUN_INSTALL=/home/sprite/.bun",
482 'export PATH="$BUN_INSTALL/bin:$PATH"',
483 'if [ ! -x "$BUN_INSTALL/bin/bun" ]; then',
484 " curl -fsSL https://bun.sh/install | bash",
485 "fi",
486 `test -x ${BUN_BIN}`,
487 ].join("\n"),
488 ],
489 });
490
491 const putAlchemyService = (input: { name: string; port: number }) =>
492 retryTransient(
493 sprites.putService({
494 name: input.name,
495 service_name: SERVICE_NAME,
496 cmd: "bash",
497 args: [
498 "-lc",
499 `set -a; [ -f ${APP_DIR}/env ] && . ${APP_DIR}/env; set +a; exec ${BUN_BIN} --no-install ${APP_DIR}/index.mjs`,
500 ],
501 dir: APP_DIR,
502 http_port: input.port,
503 }),
504 ).pipe(Effect.catchTag("NotFound", () => Effect.void));
505
506 const deployProgram = Effect.fn(function* (input: {
507 name: string;
508 files: ReadonlyArray<{ path: string; content: Uint8Array }>;
509 env: Record<string, string>;
510 port: number;
511 session?: { note: (message: string) => Effect.Effect<void> };
512 }) {
513 const note = input.session?.note ?? ((_message: string) => Effect.void);
514 yield* note(`Writing ${input.name} program onto the Sprite...`);
515 for (const file of input.files) {
516 const rel = file.path.replace(/^\/+/, "");
517 yield* writeRemoteFile({
518 name: input.name,
519 path: `${APP_DIR}/${rel}`,
520 body: file.content,
521 });
522 }
523 yield* writeRemoteFile({
524 name: input.name,
525 path: `${APP_DIR}/env`,
526 body: new TextEncoder().encode(renderEnvFile(input.env)),
527 });
528 yield* note(`Installing bun on ${input.name}...`);
529 yield* ensureBun(input.name);
530 yield* note(`Starting ${input.name} service...`);
531 yield* putAlchemyService({ name: input.name, port: input.port });
532 });
533
534 export const SpriteProvider = () =>
535 Provider.effect(
536 Sprite,
537 Effect.gen(function* () {
538 const stack = yield* Stack;
539 const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
540 const hosted = createSpriteHostedSupport({
541 stackName: stack.name,
542 stage: stack.stage,
543 virtualEntryPlugin,
544 });
545
546 return Sprite.Provider.of({
547 stables: ["spriteId", "name"],
548
549 diff: Effect.fn(function* ({ news, output }) {
550 if (news === undefined || output === undefined) return undefined;
551 if (isResolved(news)) {
552 const desiredName =
553 news.name !== undefined ? sanitizeFlyAppName(news.name) : output.name;
554 if (desiredName !== output.name) {
555 return { action: "replace" as const };
556 }
557 const desiredAuth = news.urlAuth ?? DEFAULT_URL_AUTH;
558 if (desiredAuth !== output.urlAuth) {
559 return { action: "update" as const };
560 }
561 }
562 // The code hash depends only on statically-known props — never
563 // gate it on the WHOLE props being resolved: an unresolved
564 // reference elsewhere in props would make code-only changes
565 // silently noop (see the same pattern in Service.ts). By diff
566 // time the effect-config form has been evaluated, so the object
567 // view is safe to read.
568 const statics = news as Partial<Pick<SpriteProps, "main" | "port">>;
569 if (isResolved({ main: statics.main, port: statics.port })) {
570 const hash = yield* hosted.hash(news as HostedProgramProps);
571 if (hash !== output.code.hash) {
572 return { action: "update" as const };
573 }
574 }
575 return undefined;
576 }),
577
578 read: Effect.fn(function* ({ id, olds, output }) {
579 const name = yield* resolveSpriteName(id, olds?.name, output?.name);
580 const found = yield* (
581 output?.name !== undefined ? getByName(output.name) : Effect.undefined
582 ).pipe(
583 Effect.flatMap((existing) =>
584 existing !== undefined ? Effect.succeed(existing) : getByName(name),
585 ),
586 Effect.catchTag("SpritesNotEnabled", () => Effect.undefined),
587 );
588 if (found === undefined) return undefined;
589 const attrs = toAttrs(found, name, output?.code.hash ?? "");
590 if (output !== undefined) return attrs;
591 return isOwnedSprite(found) ? attrs : Unowned(attrs);
592 }),
593
594 list: Effect.fn(function* () {
595 const items = yield* sprites.listSprites.items({ max_results: 50 }).pipe(
596 Stream.runCollect,
597 Effect.map((chunk) => Array.from(chunk)),
598 Effect.catchTag("SpritesNotEnabled", () => Effect.succeed([])),
599 );
600 return items
601 .filter(isOwnedSprite)
602 .map((sprite) => toAttrs(sprite, sprite.name ?? "", ""));
603 }),
604
605 reconcile: Effect.fn(function* ({ id, news, output, bindings, session }) {
606 const props = news;
607 const name = yield* resolveSpriteName(id, props.name, output?.name);
608 const urlAuth = props.urlAuth ?? DEFAULT_URL_AUTH;
609 const port = props.port ?? DEFAULT_PORT;
610 const labels = yield* ownershipLabels(id);
611 const boundEnv = collectBindingEnv(bindings ?? []);
612 const env = desiredEnv(props, boundEnv, hosted.alchemyEnv, port);
613
614 let current = output?.name !== undefined ? yield* getByName(output.name) : undefined;
615 if (current === undefined && output?.name !== name) {
616 current = yield* getByName(name);
617 }
618
619 if (current === undefined) {
620 yield* sprites
621 .createSprite({
622 name,
623 url_settings: { auth: urlAuth },
624 labels,
625 })
626 .pipe(Effect.catchTag("Conflict", () => Effect.void));
627 current = yield* waitForSprite(name).pipe(
628 Effect.catchTag("Fly.SpritePending", () => getByName(name)),
629 );
630 }
631
632 if (current === undefined) {
633 return yield* new SpriteNotCreated({ resourceName: name });
634 }
635 // Narrowed once so the `NotFound` fallbacks below keep the
636 // non-optional type instead of widening back to `| undefined`.
637 let sprite = current;
638
639 const observedAuth = toUrlAuth(sprite.url_settings?.auth);
640 if (observedAuth !== urlAuth) {
641 sprite = yield* sprites
642 .updateSprite({
643 name,
644 url_settings: { auth: urlAuth },
645 })
646 .pipe(Effect.catchTag("NotFound", () => Effect.succeed(sprite)));
647 }
648
649 const codeHash = yield* hosted.hash(props);
650 if (codeHash !== output?.code.hash) {
651 const bundled = yield* hosted.bundleProgram(props);
652 yield* deployProgram({
653 name,
654 files: bundled.files,
655 env,
656 port,
657 session,
658 });
659 sprite = (yield* getByName(name)) ?? sprite;
660 }
661
662 return toAttrs(sprite, name, codeHash);
663 }),
664
665 delete: Effect.fn(function* ({ output }) {
666 if (output.name.length === 0) return;
667 yield* sprites
668 .deleteSprite({ name: output.name })
669 .pipe(Effect.catchTag(["NotFound", "SpritesNotEnabled"], () => Effect.void));
670 }),
671 });
672 }),
673 );