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

main
md 439 lines 17.9 KB
Rendered Raw
1 # Content plan: Shorty, from zero to production
2
3 A link shortener with live click counts, built from an empty folder. Each
4 chapter adds one concept, and each chapter runs the same loop, so the
5 viewer watches the code, the running app, the architecture and the tests
6 evolve together.
7
8 ## The screen
9
10 | Window | What runs there |
11 | --- | --- |
12 | VS Code | The chapter's edit, typed from the real diff |
13 | Terminal, top pane | `alchemy dev`, started once in chapter 1 and never stopped. It hot-reloads the Worker, the Durable Object, the queue consumer and the Vite site on every save |
14 | Terminal, bottom pane | `pnpm test` after every change (deploy → assert → destroy against real infrastructure), plus the odd `curl` |
15 | Browser | The dashboard served by `alchemy dev` (`localhost`) |
16 | Diagram | Resources and Bindings, generated from Alchemy's state, with each Binding expandable to the grant it produced |
17
18 ## The loop, every chapter
19
20 1. **Code.** Type the change in VS Code.
21 2. **Dev.** The top pane shows `alchemy dev` picking the change up; the
22 browser (or a `curl`) shows the new behaviour straight away.
23 3. **Diagram.** New Resources and Bindings animate in. The new Binding
24 expands to its grant (a native binding, a secret, a token scope).
25 Nodes carry a `local` or `cloud` badge: under `alchemy dev`, Workers,
26 Durable Objects, D1 and Queues run in local simulators, while Neon
27 and Axiom have no emulator and deploy for real into the `dev_$USER`
28 stage.
29 4. **Test.** `pnpm test` in the bottom pane deploys a full copy of the
30 stack to `test_$USER` (the plan is printed), runs the assertions
31 against it, and destroys it. The diagram shows the `test_$USER` copy
32 appear beside `dev_$USER` and fade out when it's destroyed.
33
34 `alchemy deploy` appears twice: chapter 0 (the first deploy) and the
35 finale (`--stage prod`).
36
37 The diagram is generated from the state files (the demo uses
38 `Alchemy.localState()`, so they sit in `.alchemy/state/`), so it always
39 matches what's deployed. Each host resource's state already records its
40 bindings and the grants they produced, e.g. from the previous reference
41 app:
42
43 ```jsonc
44 // .alchemy/state/Shorty/<stage>/Api.json → bindings
45 { "sid": "LinkRoom", "data": { "bindings": [{ "type": "durable_object_namespace", "className": "LinkRoom" }] } }
46 { "sid": "Clicks", "data": { "bindings": [{ "type": "queue", "name": "Clicks", "queueName": "shorty-clicks-…" }] } }
47 ```
48
49 Nodes are resources, edges are `bindings[].sid`, edge details are the
50 binding data, and local resources are recognisable by their `dev:` ids.
51
52 ## Chapter 0: Deploy a website
53
54 ```ts
55 // alchemy.run.ts
56 export default Alchemy.Stack(
57 "Shorty",
58 { providers: Cloudflare.providers(), state: Alchemy.localState() },
59 Effect.gen(function* () {
60 const web = yield* Cloudflare.Website.Vite("Web", { rootDir: "./web" });
61 return { web: web.url };
62 }),
63 );
64 ```
65
66 - **Deploy:** `alchemy deploy` → `+ Web` → the `workers.dev` URL.
67 - **Browser:** the dashboard shell: an empty list and "API offline".
68 - **Diagram:** `[Web]`, no bindings.
69 - **Concepts:** Stack, Resource, Output, stage, state.
70
71 ## Chapter 1: An Effectful Worker with an API
72
73 ```ts
74 // src/ShortyApi.ts: one value, served by the Worker and called by the UI and the tests
75 export class LinksGroup extends HttpApiGroup.make("links")
76 .add(HttpApiEndpoint.post("create", "/links", { payload: Schema.Struct({ url: Schema.String }), success: Link }))
77 .add(HttpApiEndpoint.get("list", "/links", { success: Schema.Array(Link) }))
78 .add(HttpApiEndpoint.get("get", "/links/:code", { params: Code, success: Link, error: LinkNotFound })) {}
79 export class ShortyApi extends HttpApi.make("ShortyApi").add(LinksGroup) {}
80 ```
81
82 ```ts
83 // src/Api.ts
84 export default class Api extends Cloudflare.Worker<Api>()(
85 "Api",
86 { main: import.meta.url },
87 Effect.gen(function* () {
88 // Construction phase: runs at deploy time and at cold start
89 const links = new Map<string, Link>(); // per isolate, on purpose; chapter 2 fixes it
90 const handlers = HttpApiBuilder.group(ShortyApi, "links", (h) =>
91 h.handle("create", ({ payload }) => /* … */)
92 .handle("list", () => Effect.succeed([...links.values()]))
93 .handle("get", ({ params }) => /* … or LinkNotFound */));
94 return {
95 // Runtime phase: runs per request
96 fetch: yield* HttpRouter.toHttpEffect(
97 HttpApiBuilder.layer(ShortyApi).pipe(
98 Layer.provide(handlers), Layer.provide(Http.Platform), Layer.provide(HttpRouter.cors()),
99 ),
100 ),
101 };
102 }),
103 ) {}
104 ```
105
106 ```diff
107 // alchemy.run.ts
108 + const api = yield* Api;
109 const web = yield* Cloudflare.Website.Vite("Web", {
110 rootDir: "./web",
111 + env: { VITE_API_URL: api.url }, // an Output flowing into the build
112 });
113 ```
114
115 ```ts
116 // web/src/client.ts: typed client from the same value, no codegen
117 export const client = HttpApiClient.make(ShortyApi, { baseUrl: import.meta.env.VITE_API_URL });
118 ```
119
120 - **Dev:** start `alchemy dev` in the top pane; it stays up for the rest
121 of the talk. Create a link in the browser at `localhost`.
122 - **Diagram:** `Web ──VITE_API_URL──▶ Api` (a reference, not a binding).
123 - **Slide:** Construction vs Runtime phase.
124
125 ## Chapter 2: Store links in D1
126
127 ```sql
128 -- migrations/0001_links.sql (runs on SQLite now and on Postgres in chapter 6)
129 CREATE TABLE links (code TEXT PRIMARY KEY, url TEXT NOT NULL, created_at BIGINT NOT NULL);
130 ```
131
132 ```ts
133 // src/Db.ts
134 export const Db = Cloudflare.D1.Database("Db", { migrations: "./migrations" });
135 ```
136
137 ```diff
138 Effect.gen(function* () {
139 + const d1 = yield* Cloudflare.D1.QueryDatabase(Db); // the Binding
140 + const sql = yield* SQL.D1(d1); // Effect SQL on top
141 const handlers = HttpApiBuilder.group(ShortyApi, "links", (h) =>
142 h.handle("create", ({ payload }) =>
143 + sql<Link>`INSERT INTO links (code, url, created_at)
144 + VALUES (${newCode()}, ${payload.url}, ${Date.now()}) RETURNING *`.pipe(/* … */))
145 /* list, get */);
146 + // GET /:code → 302
147 - }),
148 + }).pipe(Effect.provide(Cloudflare.D1.QueryDatabaseBinding)),
149 ```
150
151 - **Dev:** the top pane applies `0001_links.sql` to the local D1; links
152 now survive reloads; `curl -I localhost:1337/<code>` shows the `302`.
153 - **Diagram:** `Api ──d1──▶ Db [local]`. The grant: `{ type: "d1", name: "Db" }`,
154 this one database and no account token.
155
156 ## Chapter 3: Test it against the real cloud
157
158 ```ts
159 // test/api.test.ts
160 const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
161 providers: Cloudflare.providers(),
162 state: Alchemy.localState(),
163 });
164 const stack = beforeAll(deploy(Stack)); // a full copy in stage test_$USER
165 afterAll(destroy(Stack)); // gone again afterwards
166
167 test("create, get, redirect", Effect.gen(function* () {
168 const { api } = yield* stack;
169 const client = yield* HttpApiClient.make(ShortyApi, { baseUrl: api }); // the same typed client
170 const link = yield* client.links.create({ payload: { url: "https://effect.website" } });
171 expect((yield* client.links.get({ params: { code: link.code } })).url).toBe("https://effect.website");
172 const missing = yield* client.links.get({ params: { code: "nope" } }).pipe(Effect.flip);
173 expect(missing._tag).toBe("LinkNotFound"); // a typed error, across HTTP
174 }));
175 ```
176
177 - **Test:** `pnpm test`: the plan for `test_sam` (`+ Db`, `+ Api`, `+ Web`),
178 the apply, the green assertions, the destroy. From here on every
179 chapter ends with `pnpm test`.
180 - **Diagram:** a `test_sam` copy appears beside `dev_sam`, all nodes
181 `cloud`, and fades out on destroy.
182 - **Point:** `alchemy dev` is for trying it; `pnpm test` proves it on
183 the real infrastructure.
184
185 ## Chapter 4: Durable Objects and hibernatable WebSockets
186
187 ```ts
188 // src/LinkRoom.ts: one instance per link
189 export default class LinkRoom extends Cloudflare.DurableObject<LinkRoom>()(
190 "LinkRoom",
191 Effect.gen(function* () {
192 const state = yield* Cloudflare.DurableObjectState;
193 return Effect.gen(function* () {
194 let clicks = (yield* state.storage.get<number>("clicks")) ?? 0;
195 return {
196 record: Effect.fn(function* (n: number) {
197 clicks += n;
198 yield* state.storage.put("clicks", clicks);
199 for (const ws of yield* state.getWebSockets()) yield* ws.send(JSON.stringify({ clicks }));
200 return clicks;
201 }),
202 fetch: Effect.gen(function* () { // hibernatable: sockets outlive eviction
203 const [response, socket] = yield* Cloudflare.upgrade();
204 yield* socket.send(JSON.stringify({ clicks }));
205 return response;
206 }),
207 };
208 });
209 }),
210 ) {}
211 ```
212
213 ```diff
214 + const rooms = yield* LinkRoom;
215 // GET /:code
216 + yield* rooms.getByName(link.code).record(1); // typed RPC, no schema
217 // GET /links/:code/live
218 + return yield* rooms.getByName(code).fetch(request); // hand the socket to the room
219 ```
220
221 ```ts
222 // web: a live counter per row
223 new WebSocket(`${WS_URL}/links/${code}/live`).onmessage = (e) => setClicks(JSON.parse(e.data).clicks);
224
225 // test: a click is pushed to an open socket
226 test("clicks are pushed live", Effect.gen(function* () {
227 // open ws → GET /:code → the next message is { clicks: 1 }
228 }));
229 ```
230
231 - **Dev:** the browser counter ticks as the short link is opened in
232 another tab.
233 - **Diagram:** `Api ──durable_object_namespace──▶ LinkRoom ×N`, plus
234 `Browser ⇄ LinkRoom` (WebSocket). The grant: the namespace binding
235 and its class migration.
236
237 ## Chapter 5: A Queue, so redirects stay fast
238
239 ```ts
240 export const Clicks = Cloudflare.Queues.Queue("Clicks");
241 ```
242
243 ```diff
244 + const clicks = yield* Cloudflare.Queues.WriteQueue(Clicks);
245 + yield* Cloudflare.Queues.consumeQueueMessages<ClickEvent>(Clicks,
246 + { batchSize: 100, maxWaitTime: "1 second", retryDelay: "3 seconds" },
247 + (events) => events.pipe(
248 + Stream.runFold(() => new Map<string, number>(),
249 + (counts, { body }) => counts.set(body.code, (counts.get(body.code) ?? 0) + 1)),
250 + Effect.flatMap((counts) => Effect.forEach(counts,
251 + ([code, n]) => rooms.getByName(code).record(n),
252 + { concurrency: "unbounded", discard: true }))));
253 // GET /:code
254 - yield* rooms.getByName(link.code).record(1);
255 + yield* clicks.send({ code: link.code, at: Date.now() }); // off the hot path
256 ```
257
258 - **Dev:** the local broker batches; the top pane logs each batch; the
259 browser counter jumps by batch.
260 - **Diagram:** `Api ──queue──▶ Clicks ──consumer──▶ Api ──▶ LinkRoom`, a
261 cycle Alchemy resolves. Grants: the producer binding and the
262 `Consumer` resource.
263 - **Test:** ten `GET /:code` → poll until `clicks` is 10.
264 - **Aside:** `retryDelay` covers batches delivered while a fresh deploy
265 is still rolling out (found while building #1781).
266
267 ## Chapter 6: Storage as a Layer, with Neon as the alternative
268
269 ```ts
270 // src/Links.ts: the contract the Worker depends on
271 export class Links extends Context.Service<Links, {
272 create(url: string): Effect.Effect<Link, LinkStoreError, Alchemy.RuntimeContext>;
273 get(code: string): Effect.Effect<Link, LinkNotFound | LinkStoreError, Alchemy.RuntimeContext>;
274 list(): Effect.Effect<Link[], LinkStoreError, Alchemy.RuntimeContext>;
275 }>()("Links") {}
276
277 // one implementation, written against Effect's generic SqlClient
278 export const LinksSql = Layer.effect(Links, Effect.gen(function* () {
279 const sql = yield* SqlClient.SqlClient;
280 const insert = SqlSchema.single({ Request: NewLink, Result: Link,
281 execute: (l) => sql`INSERT INTO links ${sql.insert(l)} RETURNING *` });
282 return { create: (url) => insert({ code: newCode(), url, created_at: Date.now() }), /* … */ };
283 }));
284 ```
285
286 ```ts
287 // src/Storage.ts: each storage Layer owns its infrastructure
288 export const D1Storage = Layer.unwrap(Effect.gen(function* () {
289 return SQL.D1Layer(yield* Cloudflare.D1.QueryDatabase(Db));
290 })).pipe(Layer.provide(Cloudflare.D1.QueryDatabaseBinding));
291
292 export const NeonStorage = Layer.unwrap(Effect.gen(function* () {
293 const db = yield* Neon.Project("Postgres", { migrations: "./migrations" }); // same SQL files
294 const pool = yield* Cloudflare.Hyperdrive.Connection("Pool", {
295 origin: db.origin, // deployed: Hyperdrive pools Neon's direct endpoint
296 dev: db.pooledOrigin, // alchemy dev: straight to Neon's own pooler
297 caching: { disabled: true }, // links must be read-after-write
298 });
299 const conn = yield* Cloudflare.Hyperdrive.Connect(pool);
300 return Postgres.PostgresLayer({ url: conn.connectionString });
301 })).pipe(Layer.provide(Cloudflare.Hyperdrive.ConnectBinding));
302 ```
303
304 ```diff
305 // src/Api.ts
306 - }).pipe(Effect.provide(Cloudflare.D1.QueryDatabaseBinding)),
307 + }).pipe(Effect.provide(LinksSql.pipe(Layer.provide(NeonStorage)))),
308 // alchemy.run.ts
309 - providers: Cloudflare.providers(),
310 + providers: Layer.mergeAll(Cloudflare.providers(), Neon.providers()),
311 ```
312
313 - **Dev:** the top pane creates a real Neon project and branch in
314 `dev_sam` (no Neon emulator) and applies the migration; the local
315 Worker talks to it. The browser behaves exactly as before.
316 - **Diagram:** `Api ──hyperdrive──▶ Pool ──▶ Neon Main [cloud] ◀── Db [cloud]`,
317 `Db [local D1]` removed. Grant: the Hyperdrive binding, with the
318 connection string delivered as a secret and never in plan output.
319 - **Test:** the chapter 3–5 suite, unchanged, passes on Neon. The
320 unchanged tests are the proof that the swap is behaviour-preserving.
321 - **Note:** `SqlSchema` decodes rows through `Link`, so D1's numbers and
322 Postgres's `bigint` for `created_at` both decode to the same type.
323
324 ## Chapter 7: OpenTelemetry to Axiom
325
326 ```ts
327 // src/Observability.ts: names include the stage so dev, test and prod never collide
328 export const Observability = Effect.gen(function* () {
329 const { stage } = yield* Stack;
330 const traces = yield* Axiom.Dataset("Traces", { name: `shorty-${stage}-traces`, kind: "otel:traces:v1" });
331 const logs = yield* Axiom.Dataset("Logs", { name: `shorty-${stage}-logs`, kind: "otel:logs:v1" });
332 const ingest = yield* Axiom.ApiToken("Ingest", {
333 name: `shorty-${stage}-ingest`,
334 datasetCapabilities: { // can write these two datasets and nothing else
335 [traces.name]: { ingest: ["create"] },
336 [logs.name]: { ingest: ["create"] },
337 },
338 });
339 return { traces, logs, ingest };
340 });
341 ```
342
343 ```ts
344 // the exporter is a Layer built from those resources
345 export const Telemetry = Layer.unwrap(Effect.gen(function* () {
346 const { traces, logs, ingest } = yield* Observability;
347 return Axiom.Telemetry({ token: ingest, traces, logs });
348 }));
349 ```
350
351 ```diff
352 }).pipe(Effect.provide(Layer.mergeAll(
353 LinksSql.pipe(Layer.provide(NeonStorage)),
354 + Telemetry,
355 ))),
356
357 // spans come from code that is already Effect
358 - create: (url) => insert(/* … */),
359 + create: Effect.fn("links.create")(function* (url) { /* … */ }),
360 ```
361
362 - **Dev:** click around in the browser, then open Axiom's trace view:
363 `GET /:code` → `links.get` → SQL → queue send, and separately the
364 consumer → `LinkRoom.record`.
365 - **Diagram:** `Api ──otlp──▶ Traces, Logs [cloud]`, `Ingest` as a
366 secret binding. Grant: the token's `datasetCapabilities`.
367 - **Test:** optional: query Axiom until the test's own request span
368 arrives.
369
370 ## Chapter 8: A dashboard as code
371
372 ```ts
373 yield* Axiom.Dashboard("Shorty", {
374 dashboard: {
375 name: `Shorty (${stage})`, owner: "", schemaVersion: 2, refreshTime: 15,
376 timeWindowStart: "qr-now-30m", timeWindowEnd: "qr-now",
377 charts: [
378 { id: "rps", name: "Requests / route", type: "TimeSeries",
379 query: { apl: `['${traces.name}'] | where kind == 'server' | summarize count() by bin_auto(_time), name` } },
380 { id: "p95", name: "p95 latency", type: "Statistic",
381 query: { apl: `['${traces.name}'] | summarize percentile(duration, 95)` } },
382 { id: "clicks", name: "Clicks / link", type: "Table",
383 query: { apl: `['${traces.name}'] | where name == 'LinkRoom.record' | summarize sum(toint(['attributes.n'])) by tostring(['attributes.code'])` } },
384 { id: "errors", name: "Errors", type: "TimeSeries",
385 query: { apl: `['${traces.name}'] | where error == true | summarize count() by bin_auto(_time)` } },
386 ],
387 layout: [/* 2 × 2 grid */],
388 },
389 });
390 ```
391
392 - **Dev:** a small load loop in the bottom pane; the Axiom dashboard
393 fills in live in the browser.
394 - **Diagram:** `Shorty dashboard ──reads──▶ Traces`: the architecture now
395 includes how the service is observed.
396
397 ## Finale: production
398
399 ```sh
400 alchemy deploy --stage prod
401 ```
402
403 The whole diagram, panned back through each chapter's version, then the
404 `prod` copy appearing beside `dev_sam`: the same program, a second
405 complete environment. `alchemy destroy` runs off camera.
406
407 ## Build status
408
409 All nine chapters are built in `chapters/` (see its README). Each one
410 type-checks and was run under `alchemy dev`; chapters 3–8 pass
411 `pnpm test` against the `testing` account (deploy, assert, destroy in
412 17–62 s). Things learned while building:
413
414 - Hyperdrive caches query results by default, so a link created and
415 then listed came back missing. Chapter 6 turns caching off; that is a
416 good on-camera aside.
417 - `created_at` is ISO text so the same migration and queries run on D1
418 and Postgres.
419 - Axiom accepts stage names like `dev_samgoodwin` in dataset names, and
420 telemetry exports from a local Worker under `alchemy dev`.
421 - `Axiom.Dataset.name` is a deploy-time Output, so the dashboard builds
422 its query strings from the stage instead.
423 - The dashboard's dev port is pinned (`dev: { port: 5173 }`) so the API
424 always lands on `localhost:1337`.
425 - Right after a fresh deploy, requests and queue batches can briefly hit
426 the placeholder Worker. Tests retry cold-start responses
427 (`Test.executeWhenReady`), and the consumer uses `maxRetries: 10` with
428 `retryDelay: "3 seconds"` so no click is dropped.
429
430 ## Tooling this plan needs
431
432 - The diagram renderer (Remotion, auto layout, `local`/`cloud` badges,
433 expandable grants), driven by the state files after each save.
434 - A terminal window with two panes (tmux): `alchemy dev` on top, tests
435 below.
436 - Live browser recording (WebSocket counters, Axiom charts).
437 - `pnpm test` output captured in the terminal clip.
438 - One saved code checkpoint per chapter, each of which type-checks,
439 runs under `alchemy dev` and passes `pnpm test`.