@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 2,826 lines 102 KB
Raw
1 /**
2 * The intro, as authored. Each entry is one press of → in the presenter;
3 * `title` is the caption at the bottom of the screen and `notes` is the
4 * talk track. `intro/build.ts` resolves this into `out/capture/intro/intro.json`.
5 *
6 * Code comes from `snippets/` (real files, type-checked; `*.error.ts` must
7 * fail and their real errors are shown) or inline `code` for the imagined
8 * language. Boards are drawn by `remotion/intro/boards.tsx`.
9 */
10 import type {
11 ArchStep,
12 BundlePanel,
13 DashStep,
14 Drill,
15 LoopPart,
16 MiniGraph,
17 PhaseTimeline,
18 PanelItem,
19 PyramidStep,
20 ReqItem,
21 ReqPanel,
22 Tone,
23 } from "../shared/intro.ts";
24 import CLIENTS from "./bundle-clients.json" with { type: "json" };
25 import { demo } from "./demo.ts";
26
27 /** Where in the code: the first match of `text` (or the `nth`, 1-based). */
28 export type Find = string | { text: string; nth?: number };
29
30 /**
31 * `regions` picks what's shown (other code collapses to "…"); `omit` drops regions
32 * entirely, for building a file up one piece per step from the finished version.
33 */
34 /** `fold` collapses a region to one line, like an editor fold: `first line … last line`. */
35 export type Source =
36 | { snippet: string; regions?: string[]; omit?: string[]; fold?: string[] }
37 | { code: string };
38
39 export interface CodeSpec {
40 kind: "code";
41 title: string;
42 notes?: string;
43 group: string;
44 file?: string;
45 pseudo?: boolean;
46 src: Source;
47 lang?: "typescript" | "yaml" | "ansi" | "shellscript" | "json";
48 fontSize?: number;
49 /** Tint lines by phase: a snippet region, or the lines from one match to another. */
50 tints?: (({ region: string } | { from: Find; to?: Find }) & { tone: Tone })[];
51 focus?: { from: Find; to?: Find };
52 marks?: {
53 kind: "circle" | "underline" | "strike" | "box" | "highlight";
54 find: Find;
55 /** For boxes spanning lines: the last line (found by text). */
56 to?: Find;
57 label?: string;
58 side?: "right" | "left" | "above" | "below";
59 tone?: Tone;
60 /** Set the label further away, with an arrow pointing at the mark. */
61 arrow?: boolean;
62 }[];
63 /**
64 * For `*.error.ts` snippets: which lines of the compiler's message to show,
65 * or `hide` to show the (still failing) code before the error is revealed.
66 */
67 error?: {
68 pick?: (lines: string[]) => string[];
69 hide?: boolean;
70 /** Show the error under the code, so the code keeps the full width. */
71 below?: boolean;
72 };
73 panel?: { title: string; items: PanelItem[] };
74 /** A drawing beside the code that evolves with it. */
75 diagram?: MiniGraph;
76 /** The two phases over time, drawn where the diagram goes. */
77 timeline?: PhaseTimeline;
78 /** A value passed down a call chain, drawn beside the code. */
79 drill?: Drill;
80 /** The code's requirements (Effect's Req), listed beside it. */
81 req?: ReqPanel;
82 /** The Worker's bundle, beside the code. */
83 bundle?: BundlePanel;
84 /** A second file shown side by side, on the right. */
85 beside?: Pick<CodeSpec, "file" | "src" | "lang" | "tints" | "marks">;
86 /** Lines from text in this file to text in `beside`. */
87 links?: { from: Find; to: Find; tone?: Tone }[];
88 /**
89 * A third file under this one, on the left, generated from it: an arrow labelled
90 * `label` runs down from this file to it, and `links` run from it to `beside`.
91 */
92 under?: Pick<CodeSpec, "file" | "src" | "lang" | "marks"> & {
93 label: string;
94 links?: { from: Find; to: Find; tone?: Tone }[];
95 };
96 /** Arcs from text in the code to a node or an edge's label in `diagram`. */
97 diagramLinks?: { from: Find; to: { node: string } | { edge: [string, string] }; tone?: Tone }[];
98 /** A hand-written aside in the bottom-right corner. */
99 aside?: { text: string; tone?: Tone; image?: string; at?: "left" | "right" };
100 /** A big hand-drawn red X across the code: this approach is wrong. */
101 cross?: boolean;
102 /** Don't highlight or spotlight the lines that changed since the previous step. */
103 quiet?: boolean;
104 /**
105 * Lines to mark in green, by text they contain. Replaces the automatic diff:
106 * the green is for drawing the eye, not a faithful patch.
107 */
108 emphasize?: string[];
109 /** A row of options under the code, with the current one lit (as on roll slides). */
110 reel?: { items: string[]; at: number };
111 /** What the new lines add, in pyramid terms: tints them and labels them. */
112 layer?: "resource" | "binding" | "api";
113 /** Show lines removed since this file was last on screen, in red, above what replaced them. */
114 showRemoved?: boolean;
115 frames?: number;
116 }
117
118 export interface SlideSpec {
119 kind: "slide";
120 title: string;
121 notes?: string;
122 layout?: "title" | "section";
123 eyebrow?: string;
124 heading: string;
125 subtitle?: string;
126 /** Small text pinned to the bottom of a title slide, e.g. a URL. */
127 footer?: string;
128 frames?: number;
129 }
130
131 export interface BoardSpec {
132 kind: "board";
133 title: string;
134 notes?: string;
135 board: string;
136 stage: number;
137 frames?: number;
138 }
139
140 /** A terminal pane. `lines` is everything shown; `fresh` of them (at the end) are new. */
141 export interface TerminalSpec {
142 kind: "terminal";
143 title: string;
144 notes?: string;
145 group?: string;
146 tabs?: string[];
147 active?: number;
148 lines: string;
149 fresh?: number;
150 /** A live deploy under the lines (see TerminalStep.progress); `done` is ANSI text. */
151 progress?: {
152 rows: { name: string; type?: string; binding?: boolean; from: number; to: number }[];
153 done: string;
154 at: number;
155 };
156 frames?: number;
157 }
158
159 /** A browser window showing a screenshot from `intro/assets/`. */
160 export interface BrowserSpec {
161 kind: "browser";
162 title: string;
163 notes?: string;
164 url: string;
165 image: string;
166 frames?: number;
167 }
168
169 /** The whole path from an edit to production, with some parts lit up (loop deck). */
170 export interface LoopSpec {
171 kind: "loop";
172 title: string;
173 notes?: string;
174 /** Parts drawn so far, for building the map up; omit to draw everything. */
175 show?: LoopPart[];
176 /** Parts shown at full strength; the rest are dimmed. Omit to light everything. */
177 lit?: LoopPart[];
178 /** Parts that glow: what this step is about. */
179 focus?: LoopPart[];
180 frames?: number;
181 }
182
183 /** A pull request page with its checks and comments (loop deck). */
184 export interface CommentSpec {
185 kind: "comment";
186 title: string;
187 notes?: string;
188 pr: { number: number; title: string; branch: string };
189 checks: { name: string; state: "pending" | "passed" | "failed"; detail?: string }[];
190 comments: { author: string; bot?: boolean; lines: string[] }[];
191 frames?: number;
192 }
193
194 /** An application's layers as a pyramid (loop deck). */
195 export type PyramidSpec = Omit<PyramidStep, "notes" | "frames"> & {
196 notes?: string;
197 frames?: number;
198 };
199
200 /** Code with ⟨0⟩, ⟨1⟩… slots that roll to new values from step to step (loop deck). */
201 export interface RollSpec {
202 kind: "roll";
203 group: string;
204 title: string;
205 notes?: string;
206 file?: string;
207 fontSize?: number;
208 template: string;
209 values: string[];
210 /** A snippet whose shown code must equal the filled template, so every variant is type-checked. */
211 check?: string;
212 beside?: { file: string; lang?: "yaml" | "typescript"; code: string };
213 reel?: { items: string[]; at: number };
214 /**
215 * Spin slot `slot` through `through` before landing. Each value is checked like the
216 * landing one: `check(value)` names a snippet that must equal the filled template.
217 */
218 spin?: { slot: number; through: string[]; check?: (value: string) => string };
219 frames?: number;
220 }
221
222 /** A full-screen architecture drawing (loop deck). */
223 export type ArchSpec = Omit<ArchStep, "notes" | "frames"> & { notes?: string; frames?: number };
224
225 /** A mocked observability dashboard (loop deck). */
226 export type DashSpec = Omit<DashStep, "notes" | "frames"> & { notes?: string; frames?: number };
227
228 export type StepSpec =
229 | DashSpec
230 | ArchSpec
231 | RollSpec
232 | CodeSpec
233 | SlideSpec
234 | BoardSpec
235 | TerminalSpec
236 | BrowserSpec
237 | LoopSpec
238 | CommentSpec
239 | PyramidSpec;
240
241 /** The compiler's message lines that name the missing requirement. */
242 const requirementLines = (needle: string) => (lines: string[]) => {
243 const at = lines.findIndex((line) => line.includes(needle));
244 return at < 0 ? lines.slice(0, 2) : lines.slice(Math.max(1, at - 1), at + 1);
245 };
246
247 // ── Act 1 & 2: one program in an imaginary cloud language ────────────────
248 // The code on the left grows one idea at a time; the drawing on the right
249 // shows what that code means in the cloud.
250 const C = {
251 bucket: { id: "bucket", title: "Bucket", color: "#8b7cf6" },
252 queue: { id: "queue", title: "Queue", color: "#e0a86b" },
253 api: { id: "api", title: "Function", color: "#f38020" },
254 };
255 const FN = `
256
257 function fetch(req) {
258 const file = bucket.get(req.key)
259 queue.send(file)
260 }`;
261 const VERSIONED = `const bucket = Bucket({ versioning: true })
262 const queue = Queue()${FN}`;
263 const COLORED_APP = `construct app() {
264 const bucket = Bucket({ versioning: true })
265 const queue = Queue()
266
267 runtime function fetch(req) {
268 const file = bucket.get(req.key)
269 queue.send(file)
270 }
271 }`;
272 /** What the function needs, inferred from its body the way a type would be. */
273 const INFERRED_NEEDS = COLORED_APP.replace(
274 " runtime function fetch(req) {",
275 " // needs: s3:GetObject | sqs:SendMessage\n runtime function fetch(req) {",
276 );
277 /** Step one of the colors: only construction is marked. */
278 const CONSTRUCT_ONLY = COLORED_APP.replace(
279 " runtime function fetch(req) {",
280 " function fetch(req) {",
281 );
282 /** The question: what would a bucket created inside the function even mean? */
283 const SCRATCH = VERSIONED.replace(
284 " const file = bucket.get(req.key)",
285 " const scratch = Bucket()\n const file = bucket.get(req.key)",
286 );
287 /** The mirror mistake, before phases exist: reading the bucket outside the function. */
288 const EARLY_READ = VERSIONED.replace(
289 "const queue = Queue()\n",
290 'const queue = Queue()\nconst hello = bucket.get("hello.txt")\n',
291 );
292 const SCRATCH_NODE = {
293 id: "scratch",
294 title: "Bucket?",
295 color: "#ff7b72",
296 x: 360,
297 y: 610,
298 ghost: true,
299 };
300 const COLORED_BAD = COLORED_APP.replace(
301 " const file = bucket.get(req.key)",
302 " const scratch = Bucket()\n const file = bucket.get(req.key)",
303 );
304
305 /** The mirror mistake: calling runtime code during construction. */
306 const COLORED_EARLY = COLORED_APP.replace(
307 " const queue = Queue()\n",
308 ' const queue = Queue()\n bucket.get("hello.txt")\n',
309 );
310
311 const at = (
312 node: { id: string; title: string; color: string },
313 x: number,
314 y: number,
315 notes?: string[],
316 ) => ({
317 ...node,
318 x,
319 y,
320 ...(notes ? { notes } : {}),
321 });
322 /** The program's graph; `env` lists variables injected into the Function. */
323 const GRAPH = (notes?: string[], env?: string[]) => [
324 at(C.api, 125, 270, env),
325 at(C.bucket, 590, 100, notes),
326 at(C.queue, 590, 440),
327 ];
328 const USES = [{ from: "api", to: "bucket" }];
329 /** A binding: the connection carries its permission, and the Function gets an env var. */
330 const GET = { from: "api", to: "bucket", tone: "construct" as const, label: "s3:GetObject" };
331 const SEND = { from: "api", to: "queue", tone: "construct" as const, label: "sqs:SendMessage" };
332 const BINDINGS = [GET, SEND];
333 const ENV = ["$BUCKET_NAME", "$QUEUE_URL"];
334 const lang = (
335 spec: Omit<CodeSpec, "kind" | "group" | "pseudo" | "fontSize"> & { group?: string },
336 ): CodeSpec => ({
337 kind: "code",
338 group: "lang",
339 pseudo: true,
340 fontSize: 32,
341 ...spec,
342 });
343
344 const B1 = "const bucket = Bucket()";
345 const B2 = "const bucket = Bucket({ versioning: true })";
346 const BQ = `${B2}
347 const queue = Queue()`;
348 const EMPTY_FN = `${BQ}
349
350 function fetch(req) {
351 }`;
352 const GET_FN = `${BQ}
353
354 function fetch(req) {
355 const file = bucket.get(req.key)
356 }`;
357
358 const program = (): StepSpec[] => [
359 lang({
360 title: "I wanted one language where a variable could be a cloud resource",
361 src: { code: B1 },
362 diagram: { nodes: [at(C.bucket, 360, 150)], edges: [] },
363 notes:
364 "Imagine a programming language for the cloud. Declaring a bucket wouldn't allocate memory: it would create a real bucket in the cloud.",
365 }),
366 lang({
367 title: "Change its configuration, and the cloud would update to match",
368 src: { code: B2 },
369 diagram: { nodes: [at(C.bucket, 360, 150, ["versioning: on"])], edges: [] },
370 notes:
371 "Resources have configuration that changes over time. Turn on versioning in the code, and the language would reconcile the real bucket to match.",
372 }),
373 lang({
374 title: "You'd declare a queue the same way",
375 src: { code: BQ },
376 diagram: {
377 nodes: [at(C.bucket, 590, 100, ["versioning: on"]), at(C.queue, 590, 440)],
378 edges: [],
379 },
380 notes: "A queue would be declared just like the bucket: one line, one real queue in the cloud.",
381 }),
382 lang({
383 title: "Unlike variables, these resources would outlive the program",
384 src: { code: BQ },
385 diagram: {
386 nodes: [at(C.bucket, 590, 100, ["versioning: on"]), at(C.queue, 590, 440)],
387 edges: [],
388 labels: [
389 {
390 text: "these live in the cloud\nlong after the program runs",
391 x: 190,
392 y: 262,
393 tone: "construct",
394 arrows: [
395 { from: [300, 220], to: [462, 118] },
396 { from: [300, 335], to: [462, 425] },
397 ],
398 },
399 ],
400 },
401 notes:
402 "An ordinary program runs from start to finish and its state is gone. These wouldn't go away when the program ends: they'd be a persistent world, and the next run would start from it.",
403 }),
404 lang({
405 title: "Functions would be resources too",
406 src: { code: EMPTY_FN },
407 diagram: { nodes: GRAPH(["versioning: on"]), edges: [] },
408 notes: "Declaring a function would deploy it: another node in the world.",
409 }),
410 lang({
411 title: "When the function reads the bucket, they'd become connected",
412 src: { code: GET_FN },
413 diagram: { nodes: GRAPH(["versioning: on"]), edges: [USES[0]!] },
414 notes: "Call bucket.get inside the function, and the function would now depend on the bucket.",
415 }),
416 lang({
417 title: "That connection would need permission to read the bucket",
418 src: { code: GET_FN },
419 diagram: { nodes: GRAPH(["versioning: on"]), edges: [GET] },
420 notes:
421 "For the function to call bucket.get, it would need an IAM policy that allows s3:GetObject on this bucket.",
422 }),
423 lang({
424 title: "…and the bucket's name, passed in as an environment variable",
425 src: { code: GET_FN },
426 diagram: { nodes: GRAPH(["versioning: on"], [ENV[0]!]), edges: [GET] },
427 notes:
428 "And it would need to know which bucket: its name would be injected as an environment variable. The permission plus the configuration is what we call a binding.",
429 }),
430 lang({
431 title: "Sending to the queue would connect them the same way",
432 src: { code: VERSIONED },
433 diagram: { nodes: GRAPH(["versioning: on"], ENV), edges: BINDINGS },
434 notes:
435 "Same again for the queue: sqs:SendMessage, and the queue's URL in an environment variable.",
436 }),
437 lang({
438 title: "The language would work all of this out from code",
439 src: { code: VERSIONED },
440 diagram: { nodes: GRAPH(["versioning: on"]), edges: BINDINGS },
441 diagramLinks: [
442 { from: "bucket.get(req.key)", to: { edge: ["api", "bucket"] } },
443 { from: "queue.send(file)", to: { edge: ["api", "queue"] } },
444 ],
445 frames: 40,
446 notes:
447 "A cloud language would derive all of this by static analysis. Nobody would write policies or environment variables by hand: the program would be a graph of resources, and the code would be the source of truth for how they connect.",
448 }),
449 lang({
450 title: "But what if the function created a bucket?",
451 src: { code: SCRATCH },
452 diagram: {
453 nodes: [...GRAPH(["versioning: on"], ENV), SCRATCH_NODE],
454 edges: BINDINGS,
455 labels: [{ text: "one per request?", x: 590, y: 622, tone: "bad" }],
456 },
457 notes:
458 "So far every resource was declared at the top. What if the function itself declared one? The function runs on every request, maybe thousands of times a second. Would each request get a new bucket? Who would delete them? Who would give the function permission to create them?",
459 }),
460 lang({
461 title: "Uh-oh. Resources need to be known ahead of time",
462 src: { code: SCRATCH },
463 marks: [{ kind: "strike", find: "Bucket()", tone: "bad" }],
464 diagram: {
465 nodes: [...GRAPH(["versioning: on"], ENV), SCRATCH_NODE],
466 edges: BINDINGS,
467 labels: [{ text: "one per request?", x: 590, y: 622, tone: "bad" }],
468 cards: [{ text: "✗ not known until a request arrives", tone: "bad" }],
469 },
470 notes:
471 "It wouldn't make sense. Infrastructure has to be created once, ahead of time, by the deploy. The function only uses it. So there would really be two different kinds of code in this program.",
472 }),
473 lang({
474 title: "…and code outside the function has no request to serve",
475 src: { code: EARLY_READ },
476 quiet: true,
477 marks: [{ kind: "strike", find: 'bucket.get("hello.txt")', tone: "bad" }],
478 diagram: {
479 nodes: GRAPH(["versioning: on"], ENV),
480 edges: BINDINGS,
481 cards: [{ text: "✗ runs at deploy, not per request", tone: "bad" }],
482 },
483 notes:
484 "And the mirror image. Reading the bucket outside the function would run at deploy time, while the bucket is still being created, with no request and no permissions yet. That doesn't make sense either.",
485 }),
486 lang({
487 title: "So a cloud program is actually a language with two phases",
488 src: { code: VERSIONED },
489 timeline: { resources: [C.bucket, C.queue, C.api], requests: 5 },
490 frames: 60,
491 notes:
492 "Two phases, one after the other. Construction runs once, at deploy: it creates the bucket, the queue and the function, and they live on. Then runtime: the function body runs on every request, reading the bucket and sending to the queue, using what construction made.",
493 }),
494 lang({
495 title: "One for construction, containing the resource declarations",
496 src: { code: CONSTRUCT_ONLY },
497 tints: [{ from: "const bucket", to: "const queue", tone: "construct" }],
498 diagram: {
499 nodes: GRAPH(["versioning: on"], ENV),
500 edges: BINDINGS,
501 frame: { label: "construction", tone: "construct" },
502 },
503 notes:
504 "In a real language we'd make the phases explicit. First, construction: a construct function runs once, at deploy time, and everything it declares becomes infrastructure.",
505 }),
506 lang({
507 title: "One for runtime, where those resources implement the API",
508 src: { code: COLORED_APP },
509 tints: [{ from: "const file", to: "queue.send(file)", tone: "runtime" }],
510 diagram: {
511 nodes: GRAPH(["versioning: on"], ENV),
512 edges: BINDINGS,
513 frame: { label: "construction", tone: "construct" },
514 incoming: { to: "api", label: "runtime · each request", tone: "runtime" },
515 },
516 notes:
517 "Then runtime: a runtime function inside it runs on every request, using the resources construction declared. These are colored functions: construct and runtime are different colors, and the compiler knows which is which.",
518 }),
519 lang({
520 title: "Now creating a bucket at runtime is a compile error",
521 src: { code: COLORED_BAD },
522 marks: [{ kind: "strike", find: "Bucket()", tone: "bad" }],
523 diagram: {
524 nodes: GRAPH(["versioning: on"], ENV),
525 edges: BINDINGS,
526 cards: [{ text: "✗ can't create a resource at runtime", tone: "bad" }],
527 },
528 notes:
529 "The colors are boundaries the compiler enforces. The mistake from before, creating a bucket inside a request, is now a compile error instead of a question.",
530 }),
531 lang({
532 title: "…and so is reading the bucket during construction",
533 src: { code: COLORED_EARLY },
534 quiet: true,
535 marks: [{ kind: "strike", find: 'bucket.get("hello.txt")', tone: "bad" }],
536 diagram: {
537 nodes: GRAPH(["versioning: on"], ENV),
538 edges: BINDINGS,
539 cards: [{ text: "✗ can't call runtime code at deploy time", tone: "bad" }],
540 },
541 notes:
542 "And the rule goes both ways. Reading the bucket is runtime code, and construction runs at deploy time, before there's any request to serve. So calling bucket.get there is a compile error too.",
543 }),
544 lang({
545 title: "And inferring permissions becomes a kind of type checking",
546 src: { code: COLORED_APP },
547 quiet: true,
548 diagram: { nodes: GRAPH(["versioning: on"], ENV), edges: BINDINGS },
549 diagramLinks: [
550 { from: "bucket.get(req.key)", to: { edge: ["api", "bucket"] } },
551 { from: "queue.send(file)", to: { edge: ["api", "queue"] } },
552 ],
553 frames: 40,
554 notes:
555 "And working out those permissions is a kind of type checking. Each call in the runtime function tells you something it needs: bucket.get needs s3:GetObject on that bucket, queue.send needs sqs:SendMessage on that queue.",
556 }),
557 lang({
558 title: "…just as a compiler infers a type from a function's body",
559 src: { code: INFERRED_NEEDS },
560 quiet: true,
561 marks: [{ kind: "box", find: "// needs: s3:GetObject | sqs:SendMessage", tone: "construct" }],
562 diagram: {
563 nodes: GRAPH(["versioning: on"], ENV),
564 edges: BINDINGS,
565 labels: [{ text: "for every possible req…", x: 360, y: 530, tone: "runtime" }],
566 },
567 diagramLinks: [
568 { from: "bucket.get(req.key)", to: { edge: ["api", "bucket"] } },
569 { from: "queue.send(file)", to: { edge: ["api", "queue"] } },
570 ],
571 notes:
572 "A compiler infers a function's return type by looking at every path through its body. Do the same with the calls, and you infer what the function needs: s3:GetObject and sqs:SendMessage, for every possible request. Its permissions become part of its type, and the policy falls out of type checking.",
573 }),
574 ];
575
576 const PUNCHCARD = `const topic = new SNS.Topic(stack, 'Topic', {
577 shape: NotificationRecord
578 });
579
580 new Lambda.Function(stack, 'MyFunction', {
581 depends: topic,
582 }, async (event, topic) => {
583 await topic.publish(new NotificationRecord({
584 key: 'some key',
585 count: 1,
586 timestamp: new Date()
587 }));
588 });`;
589
590 /** Functionless, simplified: no dependency list, the body is read instead. */
591 const FUNCTIONLESS = `const table = new Table(stack, "Todos");
592
593 new Function(stack, "Delete", async (id: string) => {
594 await table.delete({ id });
595 });`;
596
597 /** A Function built around a callback it can't see inside, typed as `type`. */
598 const deleter = (type: string) => `function deleter(remove: (id: string) => ${type}) {
599 return new Function(stack, "Delete", async (id: string) => {
600 await remove(id);
601 });
602 }`;
603
604 /** The Worker's requirements, listed beside its code. */
605 const REQ_LABEL = "Req · what it needs";
606 const BUCKET: ReqItem = { name: "R2.BucketProvider", note: "to create the bucket" };
607 const READ: ReqItem = { name: "R2.ReadBucket", note: "to read it at runtime" };
608 const WORKER_PROVIDER: ReqItem = {
609 name: "Cloudflare.WorkerProvider",
610 note: "to deploy the Worker",
611 };
612 const QUEUE: ReqItem = { name: "Queues.QueueProvider", note: "to create the queue" };
613 const WRITE_LOGS: ReqItem = { name: "R2.WriteBucket", note: "only in dev" };
614 const WRITE: ReqItem = { name: "Queues.WriteQueue", note: "to send at runtime" };
615 const met = (item: ReqItem, note: string): ReqItem => ({ ...item, state: "met", note });
616 const WORKER: ReqItem = { name: "Cloudflare.Worker", note: "native bindings run inside a Worker" };
617 const PHANTOM: ReqItem = {
618 name: "RuntimeContext",
619 state: "met",
620 note: "RuntimeContext.phantom\nopted out, in plain sight",
621 };
622 /** Everything the Worker version of the program needs, with the bindings provided. */
623 const PROVIDED: ReqItem[] = [
624 met(READ, "ReadBucketBinding\nadds a native R2 binding"),
625 met(WRITE, "WriteQueueBinding\nadds a native Queue binding"),
626 met(WORKER, "it runs in a Worker"),
627 ];
628
629 /** The Worker with a hypothetical catch-all layer: not a real API. */
630 const ALL_BINDINGS = `export default Cloudflare.Worker(
631 "Api",
632 { main: import.meta.url },
633 Effect.gen(function* () {
634 const bucket = yield* R2.Bucket("Uploads");
635 const uploads = yield* R2.ReadBucket(bucket);
636 const queue = yield* Queues.Queue("Jobs");
637 const jobs = yield* Queues.WriteQueue(queue);
638 return {
639 fetch: Effect.gen(function* () {
640 const file = yield* uploads.get("hello.txt");
641 yield* jobs.send({ size: file?.size });
642 return HttpServerResponse.text("ok");
643 }),
644 };
645 }).pipe(
646 Effect.provide([
647 R2.AllBindings,
648 Queues.AllBindings,
649 ]),
650 ),
651 );`;
652
653 /** The Lambda in AWS calling R2 and Queues in Cloudflare through a scoped token. */
654 const CROSS_CLOUD = (connected: boolean): MiniGraph => ({
655 nodes: [
656 at({ id: "api", title: "Lambda", color: "#ff9900" }, 125, 270),
657 at({ id: "bucket", title: "R2 Bucket", color: "#f38020" }, 560, 100),
658 at({ id: "queue", title: "Queue", color: "#f38020" }, 560, 440),
659 ],
660 edges: connected
661 ? [
662 { from: "api", to: "bucket", tone: "construct", label: "R2: read" },
663 { from: "api", to: "queue", tone: "construct", label: "Queues: write" },
664 ]
665 : [],
666 labels: [
667 { text: "AWS", x: 125, y: 190, tone: "neutral" },
668 { text: "Cloudflare", x: 560, y: 25, tone: "neutral" },
669 { text: "🔒 scoped API token,\nbound as a secret", x: 110, y: 400, tone: "construct" },
670 ],
671 });
672
673 /** The first line of the compiler's message that starts with `prefix`. */
674 const firstLine = (prefix: string) => (lines: string[]) =>
675 lines.filter((line) => line.startsWith(prefix)).slice(0, 1);
676
677 /** One version of the Api Worker, `snippets/api-*.ts`, with its Req beside it. */
678 const api = (s: {
679 title: string;
680 /** A type-checked `snippets/api-*.ts`, or inline code for an idea that was never shipped. */
681 snippet?: string;
682 code?: string;
683 notes: string;
684 req: ReqItem[];
685 /** Req of the runtime function, when it has its own. */
686 fetchReq?: ReqItem[];
687 tints?: CodeSpec["tints"];
688 marks?: CodeSpec["marks"];
689 error?: CodeSpec["error"];
690 quiet?: boolean;
691 emphasize?: string[];
692 bundle?: BundlePanel;
693 frames?: number;
694 aside?: CodeSpec["aside"];
695 cross?: boolean;
696 }): CodeSpec => ({
697 kind: "code",
698 group: "api",
699 file: "src/Api.ts",
700 title: s.title,
701 src: s.snippet ? { snippet: s.snippet, regions: ["show"] } : { code: s.code! },
702 tints: s.tints,
703 marks: s.marks,
704 error: s.error,
705 quiet: s.quiet,
706 emphasize: s.emphasize,
707 aside: s.aside,
708 cross: s.cross,
709 bundle: s.bundle,
710 frames: s.frames,
711 req: s.bundle
712 ? undefined
713 : {
714 label: REQ_LABEL,
715 items: s.req,
716 parts: s.fetchReq ? [{ label: "fetch's Req", items: s.fetchReq }] : undefined,
717 },
718 notes: s.notes,
719 });
720
721 // My first attempt: infer the binding from how the bucket is used, the way
722 // the imaginary language did. Never shipped, so it isn't type-checked.
723 const INFERRED = `const api = Effect.gen(function* () {
724 const bucket = yield* R2.Bucket("Uploads");
725 return {
726 fetch: Effect.gen(function* () {
727 const file = yield* bucket.get("hello.txt");
728 return HttpServerResponse.text("ok");
729 }),
730 };
731 });`;
732 const INFERRED_ON_FETCH = `const api = Effect.gen(function* () {
733 const bucket = yield* R2.Bucket("Uploads");
734 return {
735 fetch: Effect.gen(function* () {
736 const file = yield* bucket.get("hello.txt");
737 return HttpServerResponse.text("ok");
738 }).pipe(Effect.provide(R2.ReadBucket(bucket))),
739 };
740 });`;
741 const INFERRED_HOISTED = `const Uploads = R2.Bucket("Uploads");
742
743 const api = Effect.gen(function* () {
744 const bucket = yield* Uploads;
745 return {
746 fetch: Effect.gen(function* () {
747 const file = yield* bucket.get("hello.txt");
748 return HttpServerResponse.text("ok");
749 }),
750 };
751 }).pipe(Effect.provide(R2.ReadBucket(Uploads)));`;
752 const INFERRED_DEV = `const Uploads = R2.Bucket("Uploads");
753 const Logs = R2.Bucket("Logs");
754
755 const api = Effect.gen(function* () {
756 const bucket = yield* Uploads;
757 const logs = dev ? yield* Logs : undefined;
758 return {
759 fetch: Effect.gen(function* () {
760 const file = yield* bucket.get("hello.txt");
761 if (logs) yield* logs.put("last-read", file);
762 return HttpServerResponse.text("ok");
763 }),
764 };
765 }).pipe(Effect.provide([R2.ReadBucket(Uploads), R2.WriteBucket(Logs)]));`;
766 const HOIST_TYPE = `type Hoisted<A> =
767 A extends { fetch: Effect<any, any, infer R> } ? R : never;`;
768 const INFERRED_DEV_2 = INFERRED_DEV.replace(
769 "Effect.provide([R2.ReadBucket(Uploads), R2.WriteBucket(Logs)])",
770 "Effect.provide(R2.ReadBucket(Uploads))",
771 );
772 const PUT_LOGS: ReqItem = { name: "R2.PutObject<Logs>", note: "hoisted out of fetch's type" };
773 const GET_OBJECT: ReqItem = { name: "R2.GetObject<Uploads>", note: "inferred from bucket.get" };
774 const GET_OBJECT_HOISTED = met(
775 { name: "R2.GetObject<Uploads>" },
776 "R2.ReadBucket(Uploads)\ngrants s3:GetObject at deploy",
777 );
778
779 // The last problem: a service's interface can't hide which implementation it has.
780 const SERVICE = `class Storage extends Context.Service<Storage, {
781 get(key: string): Effect<File, NotFound>;
782 }>()("Storage") {}`;
783 /** The idiomatic Effect Layer: yield dependencies in the body, return methods that close over them. */
784 const STORAGE_LIVE = `const StorageLive = Layer.effect(
785 Storage,
786 Effect.gen(function* () {
787 const db = yield* Database;
788 return {
789 get: (key) => db.get(key),
790 };
791 }),
792 );`;
793 /** The same thing as a class: the constructor takes the dependency, the methods use it. */
794 const STORAGE_CLASS = `class StorageImpl {
795 constructor(private db: Database) {}
796
797 get(key: string) {
798 return this.db.get(key);
799 }
800 }`;
801 const SERVICE_R2 = SERVICE.replace(
802 "Effect<File, NotFound>",
803 "Effect<File, NotFound, R2.GetObject<Uploads>>",
804 );
805 const STORAGE_R2 = `const StorageR2 = Layer.effect(Storage, Effect.gen(function* () {
806 const bucket = yield* R2.Bucket("Uploads");
807 return { get: (key) => bucket.get(key) };
808 }));`;
809 const STORAGE_S3 = `const StorageS3 = Layer.effect(Storage, Effect.gen(function* () {
810 const bucket = yield* S3.Bucket("Files");
811 return { get: (key) => bucket.get(key) };
812 }));`;
813
814 // ── Act 0: infrastructure as code, and why combine it with runtime code ──
815 const CFN = `Conditions:
816 IsProd: !Equals [!Ref Stage, prod]
817 Resources:
818 Uploads:
819 Type: AWS::S3::Bucket
820 ApiRole:
821 Type: AWS::IAM::Role
822 Properties:
823 Policies:
824 - PolicyName: uploads
825 PolicyDocument:
826 Statement:
827 - Effect: Allow
828 Action: [s3:GetObject, s3:PutObject]
829 Resource: !Sub "\${Uploads.Arn}/*"
830 Api:
831 Type: AWS::Lambda::Function
832 Properties:
833 Handler: index.handler
834 Role: !GetAtt ApiRole.Arn
835 MemorySize: !If [IsProd, 1024, 256]
836 Environment:
837 Variables:
838 BUCKET_NAME: !Ref Uploads`;
839 const CDK = `class Api extends Construct {
840 constructor(scope: Construct, id: string) {
841 super(scope, id);
842 const uploads = new s3.Bucket(this, "Uploads");
843 const fn = new lambda.Function(this, "Fn", {
844 runtime: lambda.Runtime.NODEJS_22_X,
845 handler: "index.handler",
846 code: lambda.Code.fromAsset("dist"),
847 environment: {
848 BUCKET_NAME: uploads.bucketName,
849 },
850 });
851 uploads.grantReadWrite(fn);
852 }
853 }`;
854 const HANDLER = `const s3 = new S3Client({});
855
856 export const handler = async (event) => {
857 await s3.send(new PutObjectCommand({
858 Bucket: process.env.BUCKET_NAME,
859 Key: event.key,
860 Body: event.body,
861 }));
862 };`;
863 /** Roughly what `cdk synth` emits for the Api construct (logical IDs get hashes). */
864 const CDK_SYNTH = `Resources:
865 Uploads1E2F3A4B:
866 Type: AWS::S3::Bucket
867 FnServiceRoleB9001A96:
868 Type: AWS::IAM::Role
869 FnServiceRoleDefaultPolicy:
870 Type: AWS::IAM::Policy
871 Properties:
872 PolicyDocument:
873 Statement:
874 - Action: [s3:GetObject*, s3:PutObject*]
875 Resource: !Sub "\${Uploads1E2F3A4B.Arn}/*"
876 Fn9270CBC0:
877 Type: AWS::Lambda::Function
878 Properties:
879 Handler: index.handler
880 Environment:
881 Variables:
882 BUCKET_NAME: !Ref Uploads1E2F3A4B`;
883 const CDK_LINKS: NonNullable<CodeSpec["links"]> = [
884 { from: '"index.handler"', to: "export const handler" },
885 { from: "BUCKET_NAME", to: "process.env.BUCKET_NAME" },
886 { from: "grantReadWrite", to: "PutObjectCommand" },
887 ];
888
889 // ── terminal output, in the CLI's own colors ─────────────────────────────
890 const T = {
891 ok: "\x1b[38;5;113m",
892 soft: "\x1b[38;5;150m",
893 accent: "\x1b[38;5;173m",
894 grey: "\x1b[38;5;102m",
895 dim: "\x1b[2m",
896 bold: "\x1b[1m",
897 reset: "\x1b[0m",
898 };
899 const RULE = `${T.grey}${T.dim}${"─".repeat(46)}${T.reset}`;
900 const DEPLOY_PLAN = [
901 `${T.dim}$${T.reset} alchemy deploy`,
902 `${T.ok}✓${T.reset} Plan ready ${T.dim}(0.8s)${T.reset}`,
903 RULE,
904 `${T.accent}${T.bold}Deploy${T.reset}${T.dim} · ${T.reset}${T.ok}3 to create${T.reset}${T.dim} · ${T.reset}${T.soft}2 bindings${T.reset}`,
905 ``,
906 `${T.ok}+${T.reset} ${T.ok}${T.bold}Uploads${T.reset} ${T.dim}(Cloudflare.R2.Bucket)${T.reset}`,
907 `${T.ok}+${T.reset} ${T.ok}${T.bold}Jobs${T.reset} ${T.dim}(Cloudflare.Queues.Queue)${T.reset}`,
908 `${T.ok}+${T.reset} ${T.ok}${T.bold}Api${T.reset} ${T.dim}(Cloudflare.Worker)${T.reset}`,
909 ` ${T.ok}+${T.reset} ${T.soft}Uploads${T.reset}`,
910 ` ${T.ok}+${T.reset} ${T.soft}Jobs${T.reset}`,
911 RULE,
912 `${T.bold}Deploy?${T.reset} ${T.accent}${T.bold}› Deploy${T.reset} ${T.dim}Cancel${T.reset}`,
913 ].join("\n");
914 const DEPLOY_APPLIED = [
915 `${T.dim}$${T.reset} alchemy deploy`,
916 `${T.ok}✓${T.reset} Plan ready ${T.dim}(0.8s)${T.reset}`,
917 RULE,
918 `${T.accent}${T.bold}Plan${T.reset}${T.dim} · ${T.reset}${T.ok}3 created${T.reset}`,
919 ``,
920 `${T.ok}✓${T.reset} ${T.bold}Uploads${T.reset} ${T.dim}(Cloudflare.R2.Bucket)${T.reset} created ${T.dim}(1.2s)${T.reset}`,
921 `${T.ok}✓${T.reset} ${T.bold}Jobs${T.reset} ${T.dim}(Cloudflare.Queues.Queue)${T.reset} created ${T.dim}(1.9s)${T.reset}`,
922 `${T.ok}✓${T.reset} ${T.bold}Api${T.reset} ${T.dim}(Cloudflare.Worker)${T.reset} created ${T.dim}(6.4s)${T.reset}`,
923 ` ${T.ok}✓${T.reset} ${T.soft}Uploads${T.reset} created`,
924 ` ${T.ok}✓${T.reset} ${T.soft}Jobs${T.reset} created`,
925 RULE,
926 `${T.ok}Stack deployed (3/3)${T.reset} ${T.dim}{ url: "https://api.workers.dev" }${T.reset}`,
927 ].join("\n");
928
929 // The Stack, built up one piece at a time; the last version is snippets/stack.ts.
930 const STACK_1 = `export default Alchemy.Stack(
931 "App",
932 );`;
933 const STACK_2 = `export default Alchemy.Stack(
934 "App",
935 {
936 providers: Cloudflare.providers(),
937 },
938 );`;
939 const STACK_3 = `export default Alchemy.Stack(
940 "App",
941 {
942 providers: Cloudflare.providers(),
943 state: Cloudflare.state(),
944 },
945 );`;
946 const STACK_4 = `export default Alchemy.Stack(
947 "App",
948 {
949 providers: Cloudflare.providers(),
950 state: Cloudflare.state(),
951 },
952 Effect.gen(function* () {
953 const api = yield* Api;
954 }),
955 );`;
956 /** The same Stack deployed to two stages: the same resources, twice, isolated by name. */
957 const stageColumn = (stage: string, x: number) => [
958 at({ id: `api-${stage}`, title: "Api", color: "#f38020" }, x, 130, [`${stage}-api`]),
959 at({ id: `uploads-${stage}`, title: "Uploads", color: "#8b7cf6" }, x, 280, [`${stage}-uploads`]),
960 at({ id: `jobs-${stage}`, title: "Jobs", color: "#e0a86b" }, x, 430, [`${stage}-jobs`]),
961 ];
962 const STAGES: MiniGraph = {
963 nodes: [...stageColumn("dev", 140), ...stageColumn("prod", 530)],
964 edges: [],
965 groups: [
966 { label: "dev", nodes: ["api-dev", "uploads-dev", "jobs-dev"], tone: "runtime" },
967 { label: "prod", nodes: ["api-prod", "uploads-prod", "jobs-prod"], tone: "good" },
968 ],
969 };
970
971 /** One step of building the Stack in alchemy.run.ts. */
972 const stack = (s: {
973 title: string;
974 code: string;
975 notes: string;
976 marks?: CodeSpec["marks"];
977 panel?: CodeSpec["panel"];
978 diagram?: MiniGraph;
979 req?: ReqItem[];
980 }): CodeSpec => ({
981 kind: "code",
982 group: "stack",
983 file: "alchemy.run.ts",
984 title: s.title,
985 src: { code: s.code },
986 marks: s.marks,
987 panel: s.panel,
988 diagram: s.diagram,
989 req: s.req ? { label: REQ_LABEL, items: s.req } : undefined,
990 notes: s.notes,
991 });
992
993 // ── what infrastructure as code is ──────────────────────────────────────
994 const SCRIPT = `aws s3api create-bucket --bucket uploads
995 aws s3api put-bucket-versioning --bucket uploads \\
996 --versioning-configuration Status=Enabled`;
997 const SCRIPT_IF = `if ! aws s3api head-bucket --bucket uploads; then
998 aws s3api create-bucket --bucket uploads
999 fi
1000 aws s3api put-bucket-versioning --bucket uploads \\
1001 --versioning-configuration Status=Enabled`;
1002 const SCRIPT_IFS = `if ! aws s3api head-bucket --bucket uploads; then
1003 aws s3api create-bucket --bucket uploads
1004 fi
1005 status=$(aws s3api get-bucket-versioning --bucket uploads \\
1006 --query Status --output text)
1007 if [ "$status" != "Enabled" ]; then
1008 aws s3api put-bucket-versioning --bucket uploads \\
1009 --versioning-configuration Status=Enabled
1010 fi`;
1011 const CFN_1 = `Resources:
1012 Uploads:
1013 Type: AWS::S3::Bucket`;
1014 const CFN_2 = `Resources:
1015 Uploads:
1016 Type: AWS::S3::Bucket
1017 Properties:
1018 VersioningConfiguration:
1019 Status: Enabled`;
1020 /** One step of the infrastructure-as-code primer: a file beside the cloud it describes. */
1021 const iac = (s: {
1022 title: string;
1023 lang: CodeSpec["lang"];
1024 file: string;
1025 code: string;
1026 notes: string;
1027 diagram: MiniGraph;
1028 marks?: CodeSpec["marks"];
1029 }): CodeSpec => ({
1030 kind: "code",
1031 group: "iac",
1032 file: s.file,
1033 lang: s.lang,
1034 title: s.title,
1035 src: { code: s.code },
1036 marks: s.marks,
1037 diagram: s.diagram,
1038 fontSize: 32,
1039 notes: s.notes,
1040 });
1041
1042 // ── the Worker bundle, for the tree-shaking steps ──────────────────────
1043 const BUNDLE_LABEL = "the Worker bundle";
1044 const USED_CLIENTS = ["get", "send"];
1045 const PRECISE: BundlePanel = {
1046 label: BUNDLE_LABEL,
1047 size: 38,
1048 items: USED_CLIENTS,
1049 used: USED_CLIENTS,
1050 note: "just what the code calls",
1051 };
1052 /** Every R2, Queues and S3-compatible operation distilled knows about. */
1053 const EVERYTHING: BundlePanel = {
1054 label: BUNDLE_LABEL,
1055 size: 1840,
1056 items: CLIENTS,
1057 used: USED_CLIENTS,
1058 note: "{extra} clients the code never calls",
1059 };
1060
1061 /** The build-up to Effect: write what fetch needs into its type. */
1062 const TYPED = (type: string) =>
1063 COLORED_APP.replace(
1064 " runtime function fetch(req) {",
1065 ` runtime function fetch(req): ${type} {`,
1066 );
1067 const typedFetch: StepSpec[] = [
1068 lang({
1069 title: "So write what it needs into its type",
1070 src: { code: TYPED("Promise<Response, never, s3:GetObject>") },
1071 emphasize: ["runtime function fetch"],
1072 notes:
1073 "So write it down, as a third type parameter: fetch returns a Response and needs s3:GetObject. Once it's in the type, nothing has to read the body: anything that calls fetch inherits that need, like any other type.",
1074 }),
1075 lang({
1076 title: "It could say how it fails too, that seems like a good idea 😏",
1077 src: { code: TYPED("Promise<Response, NotFound, s3:GetObject>") },
1078 emphasize: ["runtime function fetch"],
1079 notes: "And while we're at it, the middle parameter could say how it fails: NotFound.",
1080 }),
1081 lang({
1082 title: "Wait… this looks familiar",
1083 src: { code: TYPED("Effect<Response, NotFound, s3:GetObject>") },
1084 emphasize: ["runtime function fetch"],
1085 notes: "Wait. What it returns, how it fails, and what it needs. We've seen this before.",
1086 }),
1087 ];
1088
1089 /** Every step ever written, in the original long order. `steps` below picks from it. */
1090 const allSteps: StepSpec[] = [
1091 // Act 1: a programming language for the cloud
1092 {
1093 kind: "slide",
1094 layout: "title",
1095 title: "A programming language for the cloud",
1096 eyebrow: "Alchemy",
1097 heading: "A programming language for the cloud",
1098 subtitle: "…without building a new language",
1099 notes:
1100 "The idea underneath Alchemy: a programming language for the cloud, without actually building a new language.",
1101 },
1102
1103 {
1104 kind: "slide",
1105 layout: "section",
1106 title: "What is infrastructure as code?",
1107 eyebrow: "In case you're new to it",
1108 heading: "What is infrastructure as code?",
1109 notes: "For anyone who hasn't used it, a quick primer on infrastructure as code.",
1110 },
1111 iac({
1112 title: "Without it, you change the cloud by running scripts",
1113 lang: "shellscript",
1114 file: "setup.sh",
1115 code: SCRIPT,
1116 diagram: { nodes: [], edges: [] },
1117 notes:
1118 "Without infrastructure as code, you change the cloud by running commands: create this bucket, then turn on versioning. A script of steps, run in order.",
1119 }),
1120 iac({
1121 title: "…but running it a second time fails",
1122 lang: "shellscript",
1123 file: "setup.sh",
1124 code: SCRIPT,
1125 marks: [
1126 {
1127 kind: "underline",
1128 find: "create-bucket",
1129 label: "the bucket already exists",
1130 side: "right",
1131 tone: "bad",
1132 },
1133 ],
1134 diagram: { nodes: [at(C.bucket, 360, 150, ["versioning: on"])], edges: [] },
1135 notes: "Run it again and create-bucket fails, because the bucket already exists.",
1136 }),
1137 iac({
1138 title: "You have to check what already exists first…",
1139 lang: "shellscript",
1140 file: "setup.sh",
1141 code: SCRIPT_IF,
1142 diagram: { nodes: [at(C.bucket, 360, 150, ["versioning: on"])], edges: [] },
1143 notes: "So you add a check: only create the bucket if it isn't there yet.",
1144 }),
1145 iac({
1146 title: "…for every single setting, and it never stops",
1147 lang: "shellscript",
1148 file: "setup.sh",
1149 code: SCRIPT_IFS,
1150 diagram: { nodes: [at(C.bucket, 360, 150, ["versioning: on"])], edges: [] },
1151 notes:
1152 "And then for versioning, and then for every other setting, and every change after that. Every script ends up re-discovering the current state of the world, one if statement at a time.",
1153 }),
1154 iac({
1155 title: "Infrastructure as code declares what should be, not what is",
1156 lang: "yaml",
1157 file: "template.yaml",
1158 code: CFN_1,
1159 diagram: { nodes: [], edges: [] },
1160 notes:
1161 "Infrastructure as code inverts this. You stop tracking what is, and declare what the cloud should be: the desired state. This is CloudFormation, AWS's version. One bucket.",
1162 }),
1163 iac({
1164 title: "An engine compares it to the cloud, and creates what's missing",
1165 lang: "yaml",
1166 file: "template.yaml",
1167 code: CFN_1,
1168 diagram: {
1169 nodes: [at(C.bucket, 360, 150)],
1170 edges: [],
1171 labels: [{ text: "created", x: 470, y: 90, tone: "good" }],
1172 },
1173 notes:
1174 "An engine compares the desired state with what actually exists. The bucket doesn't exist yet, so the engine creates it.",
1175 }),
1176 iac({
1177 title: "Change what it should be…",
1178 lang: "yaml",
1179 file: "template.yaml",
1180 code: CFN_2,
1181 diagram: { nodes: [at(C.bucket, 360, 150)], edges: [] },
1182 notes:
1183 "Now we want versioning. We don't write a script to turn it on. We just change the description.",
1184 }),
1185 iac({
1186 title: "…and the engine updates only what changed",
1187 lang: "yaml",
1188 file: "template.yaml",
1189 code: CFN_2,
1190 diagram: {
1191 nodes: [at(C.bucket, 360, 150, ["versioning: on"])],
1192 edges: [],
1193 labels: [{ text: "updated in place", x: 470, y: 90, tone: "good" }],
1194 },
1195 notes:
1196 "Deploy again, and the engine works out the difference: the bucket exists, but versioning is off. It turns versioning on and leaves everything else alone. You say what, the engine works out how. That's infrastructure as code.",
1197 }),
1198
1199 // Act 0: why combine infrastructure and runtime code at all
1200 {
1201 kind: "code",
1202 group: "cfn",
1203 file: "template.yaml",
1204 lang: "yaml",
1205 title: "I started out writing CloudFormation templates like this",
1206 src: { code: CFN },
1207 notes:
1208 "That's how I started: writing CloudFormation templates for real apps, a bucket, a role, a Lambda function, all in YAML.",
1209 },
1210 {
1211 kind: "code",
1212 group: "cfn",
1213 file: "template.yaml",
1214 lang: "yaml",
1215 title: "…but I never liked trying to program in YAML",
1216 src: { code: CFN },
1217 marks: [
1218 {
1219 kind: "circle",
1220 find: "!If [IsProd, 1024, 256]",
1221 label: "an if statement, in YAML",
1222 side: "right",
1223 tone: "bad",
1224 },
1225 {
1226 kind: "underline",
1227 find: '!Sub "${Uploads.Arn}/*"',
1228 label: "string templating for references",
1229 side: "right",
1230 tone: "bad",
1231 },
1232 ],
1233 notes:
1234 "But I never liked it. I'm a coder. I don't want to write config files, and I really don't want to program in YAML: conditions, string substitution, intrinsic functions.",
1235 },
1236 {
1237 kind: "code",
1238 group: "cdk",
1239 file: "infra/api.ts",
1240 title: "Then the AWS CDK came out",
1241 src: { code: CDK },
1242 notes: "Then the AWS CDK came out. The same infrastructure, as a TypeScript class.",
1243 },
1244 {
1245 kind: "code",
1246 group: "cdk",
1247 file: "infra/api.ts",
1248 title: "Finally, I could configure infrastructure with real code",
1249 src: { code: CDK },
1250 marks: [
1251 {
1252 kind: "underline",
1253 find: "uploads.grantReadWrite(fn);",
1254 label: "the whole IAM policy",
1255 side: "right",
1256 tone: "good",
1257 },
1258 ],
1259 notes:
1260 "Finally, real code: variables, functions, types, and abstractions like grantReadWrite that write the IAM policy for you.",
1261 },
1262 {
1263 kind: "code",
1264 group: "cdk",
1265 file: "infra/api.ts",
1266 title: "…or so I thought. The CDK just generated CloudFormation",
1267 src: { code: CDK },
1268 beside: { file: "cdk synth → template.yaml", lang: "yaml", src: { code: CDK_SYNTH } },
1269 links: [
1270 { from: 'new s3.Bucket(this, "Uploads")', to: "Uploads1E2F3A4B:" },
1271 { from: "uploads.grantReadWrite(fn);", to: "FnServiceRoleDefaultPolicy:" },
1272 { from: '"index.handler"', to: "Handler: index.handler" },
1273 ],
1274 frames: 45,
1275 notes:
1276 "Or so I thought. It's worth being clear about what the CDK actually is. Run cdk synth and your TypeScript executes once, on your machine, and spits out a CloudFormation template. Every construct becomes a block of YAML. That template is what actually gets deployed.",
1277 },
1278 {
1279 kind: "code",
1280 group: "cdk",
1281 file: "infra/api.ts",
1282 title: "It's a template generator, not programmable infrastructure",
1283 src: { code: CDK },
1284 marks: [
1285 {
1286 kind: "underline",
1287 find: "class Api extends Construct",
1288 label: "runs once, at synth",
1289 side: "right",
1290 tone: "neutral",
1291 },
1292 ],
1293 beside: {
1294 file: "cdk synth → template.yaml",
1295 lang: "yaml",
1296 src: { code: CDK_SYNTH },
1297 marks: [
1298 {
1299 kind: "underline",
1300 find: "Resources:",
1301 label: "what's actually deployed",
1302 side: "right",
1303 tone: "construct",
1304 },
1305 ],
1306 },
1307 links: [
1308 { from: 'new s3.Bucket(this, "Uploads")', to: "Uploads1E2F3A4B:" },
1309 { from: "uploads.grantReadWrite(fn);", to: "FnServiceRoleDefaultPolicy:" },
1310 { from: '"index.handler"', to: "Handler: index.handler" },
1311 ],
1312 notes:
1313 "So it's a much nicer way to write the template, but it's still a template generator. The code is gone by the time anything deploys. Anything that depends on the real cloud at deploy time is back to CloudFormation intrinsics. It's not really programmable infrastructure.",
1314 },
1315 {
1316 kind: "code",
1317 group: "cdk",
1318 file: "infra/api.ts",
1319 title: "It also bothered me that the runtime code lived elsewhere",
1320 src: { code: CDK },
1321 beside: { file: "src/handler.ts", src: { code: HANDLER } },
1322 notes:
1323 "It also always bothered me that the code that actually runs in the Lambda lives somewhere else entirely: a separate file, bundled and deployed separately.",
1324 },
1325 {
1326 kind: "code",
1327 group: "cdk",
1328 file: "infra/api.ts",
1329 title: "You have to write two programs",
1330 src: { code: CDK },
1331 marks: [
1332 {
1333 kind: "underline",
1334 find: "class Api extends Construct",
1335 label: "one for the infrastructure",
1336 side: "right",
1337 tone: "construct",
1338 },
1339 ],
1340 beside: {
1341 file: "src/handler.ts",
1342 src: { code: HANDLER },
1343 marks: [
1344 {
1345 kind: "underline",
1346 find: "const s3 = new S3Client({});",
1347 label: "one for the runtime",
1348 side: "right",
1349 tone: "runtime",
1350 },
1351 ],
1352 },
1353 notes:
1354 "You end up writing two programs: one for the infrastructure, and one for the code that runs on it.",
1355 },
1356 {
1357 kind: "code",
1358 group: "cdk",
1359 file: "infra/api.ts",
1360 title: "…even though they're really one program",
1361 src: { code: CDK },
1362 beside: { file: "src/handler.ts", src: { code: HANDLER } },
1363 links: CDK_LINKS,
1364 frames: 45,
1365 notes:
1366 "And the two are coupled. The handler name has to match an export. The environment variable has to match what the handler reads. The grant has to cover every call the handler makes. Every change means juggling two programs that are really one.",
1367 },
1368 {
1369 kind: "code",
1370 group: "cdk",
1371 file: "infra/api.ts",
1372 title: "Rename one side, and nothing tells you the other broke",
1373 src: { code: CDK.replace("BUCKET_NAME", "UPLOADS_BUCKET") },
1374 beside: {
1375 file: "src/handler.ts",
1376 src: { code: HANDLER },
1377 marks: [
1378 { kind: "circle", find: "BUCKET_NAME", label: "undefined!", side: "right", tone: "bad" },
1379 ],
1380 },
1381 links: [
1382 { from: '"index.handler"', to: "export const handler" },
1383 { from: "UPLOADS_BUCKET", to: "process.env.BUCKET_NAME", tone: "bad" },
1384 { from: "grantReadWrite", to: "PutObjectCommand" },
1385 ],
1386 notes:
1387 "Rename the environment variable in the infrastructure, and the handler still compiles, still deploys, and then fails at runtime. Neither program knows about the other. That's what made me want one program, and one language, for both.",
1388 },
1389 ...program(),
1390
1391 // Act 3: how we tried before
1392 {
1393 kind: "board",
1394 board: "history",
1395 stage: 0,
1396 title: "I've tried to build this before",
1397 notes: "Before Alchemy I tried this more than once.",
1398 },
1399 {
1400 kind: "code",
1401 group: "punchcard",
1402 file: "punchcard · stack.ts",
1403 title: "First came Punchcard, which added runtime code to the AWS CDK",
1404 src: { code: PUNCHCARD },
1405 tints: [{ from: "async (event", to: "}));", tone: "runtime" }],
1406 notes:
1407 "In 2018 and 2019 I built Punchcard on top of the AWS CDK. It modeled the two phases: declare a topic, depend on it from a Function, and get a typed client at runtime with the IAM policy generated for you.",
1408 },
1409 {
1410 kind: "code",
1411 group: "punchcard",
1412 file: "punchcard · stack.ts",
1413 title: "But its runtime code shipped with the whole CDK",
1414 src: { code: PUNCHCARD },
1415 tints: [{ from: "async (event", to: "}));", tone: "runtime" }],
1416 marks: [
1417 {
1418 kind: "circle",
1419 find: "SNS.Topic",
1420 label: "brings the CDK with it",
1421 side: "right",
1422 tone: "bad",
1423 },
1424 ],
1425 panel: {
1426 title: "What the Lambda bundle contains",
1427 items: [
1428 { title: "Your handler", bar: 0.04, tone: "runtime" },
1429 { title: "Punchcard", bar: 0.3, tone: "bad" },
1430 { title: "The AWS CDK", bar: 1, tone: "bad" },
1431 ],
1432 },
1433 notes:
1434 "The problem: it was coupled to the CDK. Importing the Topic imported everything needed to provision it, so bundling hacks had to strip the CDK out of the runtime, and serverless apps still shipped a massive amount of bloat. (Sizes illustrative.)",
1435 },
1436 {
1437 kind: "code",
1438 group: "punchcard",
1439 file: "punchcard · stack.ts",
1440 title: "And every dependency had to be declared up front",
1441 src: { code: PUNCHCARD },
1442 marks: [
1443 {
1444 kind: "circle",
1445 find: "depends: topic",
1446 label: "declared up front…",
1447 side: "right",
1448 tone: "construct",
1449 },
1450 {
1451 kind: "underline",
1452 find: "(event, topic)",
1453 label: "…then passed down to where it's used",
1454 side: "right",
1455 tone: "construct",
1456 },
1457 ],
1458 notes:
1459 "And every dependency had to be listed up front, in depends, and then prop-drilled into the handler as an argument. The code that uses the topic can't just reach for it.",
1460 },
1461 {
1462 kind: "code",
1463 group: "punchcard",
1464 file: "punchcard · stack.ts",
1465 title: "…and carried through every function on the way down",
1466 src: { code: PUNCHCARD },
1467 marks: [
1468 {
1469 kind: "circle",
1470 find: "depends: topic",
1471 label: "declared up front…",
1472 side: "right",
1473 tone: "construct",
1474 },
1475 {
1476 kind: "underline",
1477 find: "(event, topic)",
1478 label: "…then passed down to where it's used",
1479 side: "right",
1480 tone: "construct",
1481 },
1482 ],
1483 drill: {
1484 label: "in a real app",
1485 name: "topic",
1486 lines: [
1487 "handler(event, topic)",
1488 " placeOrder(order, topic)",
1489 " chargeCard(order, topic)",
1490 " sendReceipt(order, topic)",
1491 " topic.publish(receipt)",
1492 ],
1493 note: "carried by every layer, used by one",
1494 },
1495 frames: 45,
1496 notes:
1497 "That's prop drilling. The handler rarely publishes directly: it calls placeOrder, which calls chargeCard, which calls sendReceipt, and only that last one publishes. Every function in between has to take the topic as a parameter just to hand it down. Add a second resource and you touch every signature again.",
1498 },
1499 {
1500 kind: "code",
1501 group: "functionless",
1502 file: "functionless · app.ts",
1503 title: "Then came Functionless, which used compiler tricks instead",
1504 src: { code: FUNCTIONLESS },
1505 notes:
1506 "So in 2022 the next attempt, Functionless, dropped the declarations. Just use the table inside the function, and let static analysis work out what it touches.",
1507 },
1508 {
1509 kind: "code",
1510 group: "functionless",
1511 file: "functionless · app.ts",
1512 title: "It peeks inside to see which resources the function uses",
1513 src: { code: FUNCTIONLESS },
1514 marks: [
1515 {
1516 kind: "circle",
1517 find: "table.delete",
1518 label: "found by reading the body",
1519 side: "right",
1520 tone: "construct",
1521 },
1522 ],
1523 panel: {
1524 title: "Inferred",
1525 items: [{ title: "IAM policy", mono: `Allow dynamodb:DeleteItem\non table Todos` }],
1526 },
1527 notes:
1528 "It walks the function's syntax tree, follows variables into the scope they came from, sees table.delete, and infers the DynamoDB permission. That looks like it works.",
1529 },
1530 {
1531 kind: "code",
1532 group: "hidden",
1533 file: "functionless · app.ts",
1534 title: "But it can't see inside a function that's passed in",
1535 src: { code: deleter("Promise<void>") },
1536 marks: [
1537 {
1538 kind: "circle",
1539 find: "remove(id)",
1540 label: "which function? could be anything",
1541 side: "right",
1542 tone: "bad",
1543 },
1544 ],
1545 notes:
1546 "But peeking inside breaks down fast. Take a function that's passed in. Which function is remove? It depends on the caller, so reading this body tells you nothing.",
1547 },
1548 {
1549 kind: "code",
1550 group: "hidden",
1551 file: "functionless · app.ts",
1552 title: "Unless its type says what it needs",
1553 src: { code: deleter("Promise<void, DeleteItem>") },
1554 notes:
1555 "But what if the type of remove told us? Imagine a type parameter that lists what the function needs from the outside world: here, permission to delete an item.",
1556 },
1557 {
1558 kind: "code",
1559 group: "hidden",
1560 file: "functionless · app.ts",
1561 title: "Then inferring permissions is just type checking",
1562 src: { code: deleter("Promise<void, DeleteItem>") },
1563 marks: [
1564 { kind: "circle", find: "DeleteItem", tone: "construct" },
1565 {
1566 kind: "underline",
1567 find: "new Function",
1568 label: "so it needs DeleteItem too",
1569 side: "right",
1570 tone: "construct",
1571 },
1572 ],
1573 notes:
1574 "Now nobody has to read the body. A type checker never looks inside the functions you call; it reads their signatures. The Function calls remove, so it needs DeleteItem too, and that's the policy. Higher-order functions and classes just work.",
1575 },
1576 {
1577 kind: "code",
1578 group: "hidden",
1579 file: "functionless · app.ts",
1580 title: "It could say how it fails too, that seems like a good idea 😏",
1581 src: { code: deleter("Promise<void, NotFound, DeleteItem>") },
1582 notes: "And while we're at it, the type could say how the function fails, too.",
1583 },
1584 {
1585 kind: "code",
1586 group: "hidden",
1587 file: "functionless · app.ts",
1588 title: "Wait… this looks familiar",
1589 src: { code: deleter("Effect<void, NotFound, DeleteItem>") },
1590 notes: "Wait. A value, an error, and its requirements. We've seen this before.",
1591 },
1592
1593 // Act 4: Effect is the missing piece
1594 {
1595 kind: "code",
1596 group: "effect",
1597 title: "That's exactly the type of an Effect",
1598 src: { code: "Effect<A, Err, Req>" },
1599 fontSize: 96,
1600 marks: [
1601 { kind: "underline", find: "A", label: "what it returns", side: "above", tone: "neutral" },
1602 { kind: "underline", find: "Err", label: "how it fails", side: "below", tone: "neutral" },
1603 { kind: "circle", find: "Req", label: "what it needs", side: "above", tone: "construct" },
1604 ],
1605 notes:
1606 "That's Effect. Success, errors, and the requirements channel: the signature we were missing.",
1607 },
1608
1609 // Act 5: the same program, in Alchemy. The code grows one idea at a time;
1610 // beside it, the Worker's Req: what it still needs from the outside world.
1611 api({
1612 title: "Let's write the program again with Effect",
1613 snippet: "api-01-effect.ts",
1614 req: [],
1615 notes:
1616 "Start with just the function. Effect.gen describes a program without running it, and this one returns a fetch handler, which is itself an Effect. On the right is its Req, what it needs from the outside world. Right now: nothing.",
1617 }),
1618 api({
1619 title: "The outer Effect is the construction phase",
1620 snippet: "api-01-effect.ts",
1621 tints: [{ from: "const api = Effect.gen", to: "return {", tone: "construct" }],
1622 req: [],
1623 notes:
1624 "The outer Effect runs once, when the function is set up: that's the construction phase.",
1625 }),
1626 api({
1627 title: "…and fetch is the runtime phase",
1628 snippet: "api-01-effect.ts",
1629 tints: [{ from: "fetch: Effect.gen", to: "}),", tone: "runtime" }],
1630 req: [],
1631 notes:
1632 "And fetch runs for each request: the runtime phase. The same two phases as our imaginary language, written with plain TypeScript and Effect.",
1633 }),
1634 api({
1635 title: "Resources are declared in construction, with yield*",
1636 snippet: "api-02-bucket.ts",
1637 req: [],
1638 notes:
1639 "Declare a bucket in the construction phase with yield*. Creating it is the deploy's job, which we'll come back to with the Stack. For now, Req stays empty.",
1640 }),
1641 api({
1642 title: "My first try inferred the binding from how it's used",
1643 code: INFERRED,
1644 req: [],
1645 fetchReq: [GET_OBJECT],
1646 notes:
1647 "My first attempt looked exactly like the imaginary language. Just call bucket.get, and the type of that call carries the requirement: R2.GetObject for the Uploads bucket. No declaration needed.",
1648 }),
1649 api({
1650 title: "The goal was least privilege, guaranteed by the type checker",
1651 code: INFERRED,
1652 marks: [
1653 {
1654 kind: "underline",
1655 find: 'bucket.get("hello.txt")',
1656 label: "grant this, and nothing more",
1657 side: "right",
1658 tone: "good",
1659 },
1660 ],
1661 req: [],
1662 fetchReq: [GET_OBJECT],
1663 notes:
1664 "Here's what I was after: least privilege, guaranteed by the type checker. The type lists exactly what the code touches, and the layer you provide for each requirement grants exactly that permission. If it compiles, the function can do what it uses, and nothing more.",
1665 }),
1666 api({
1667 title: "Providing a layer for it grants exactly that permission",
1668 code: INFERRED_ON_FETCH,
1669 quiet: true,
1670 marks: [
1671 {
1672 kind: "underline",
1673 find: "Effect.provide(R2.ReadBucket(bucket))",
1674 label: "grants s3:GetObject",
1675 side: "right",
1676 tone: "good",
1677 },
1678 ],
1679 req: [],
1680 fetchReq: [met(GET_OBJECT, "R2.ReadBucket(bucket)\ngrants s3:GetObject")],
1681 notes:
1682 "And here's how it gets granted. To satisfy R2.GetObject, you provide a layer for it, R2.ReadBucket for this bucket. And providing that layer is what grants the policy: s3:GetObject on Uploads, and nothing more.",
1683 }),
1684 api({
1685 title: "This approach doesn't work…",
1686 code: INFERRED_ON_FETCH,
1687 quiet: true,
1688 cross: true,
1689 req: [],
1690 fetchReq: [met(GET_OBJECT, "R2.ReadBucket(bucket)\ngrants s3:GetObject")],
1691 notes:
1692 "It looked just like the imaginary language, and I was pretty pleased with it. But this approach doesn't work, and the problems got worse the further I took it.",
1693 }),
1694 api({
1695 title: "…it's in the wrong spot",
1696 code: INFERRED_ON_FETCH,
1697 marks: [
1698 {
1699 kind: "circle",
1700 find: "Effect.provide(R2.ReadBucket(bucket))",
1701 label: "on fetch, at runtime",
1702 side: "right",
1703 tone: "bad",
1704 },
1705 ],
1706 req: [],
1707 fetchReq: [
1708 { ...GET_OBJECT, state: "bad", note: "provided per request:\ntoo late to grant a policy" },
1709 ],
1710 notes:
1711 "It's in the wrong spot. The requirement lands on fetch, so that's where its layer has to be provided. But fetch runs at runtime, on every request. The layer grants the policy, and by then the deploy is long over. This makes no sense.",
1712 }),
1713 api({
1714 title: "Moving the bucket out lets the layer go on construction",
1715 code: INFERRED_HOISTED,
1716 req: [GET_OBJECT_HOISTED],
1717 notes:
1718 "Where we actually want it is on the outer Effect, the construction phase. So the bucket moves out to module scope, where the layer can name it, and Effect.provide(R2.ReadBucket(Uploads)) goes on the outer Effect. Now its policy is granted at deploy time, where it belongs.",
1719 }),
1720 api({
1721 title: "But construction only finds it by digging into fetch's type",
1722 code: `${INFERRED_HOISTED}\n\n${HOIST_TYPE}`,
1723 marks: [
1724 {
1725 kind: "circle",
1726 find: "infer R",
1727 label: "type magic on what it returns",
1728 side: "right",
1729 tone: "bad",
1730 },
1731 ],
1732 req: [GET_OBJECT_HOISTED],
1733 notes:
1734 "But the outer Effect doesn't need R2.GetObject. Only fetch does. The only way construction learns about it is type magic: dig into the return type of the Effect, find fetch, infer its requirements, and hoist them up. The requirement is discovered by analyzing the runtime function, not declared.",
1735 }),
1736 api({
1737 title: "This is starting to feel like peeking inside again…",
1738 code: `${INFERRED_HOISTED}\n\n${HOIST_TYPE}`,
1739 marks: [
1740 {
1741 kind: "circle",
1742 find: "infer R",
1743 label: "type magic on what it returns",
1744 side: "right",
1745 tone: "bad",
1746 },
1747 ],
1748 req: [GET_OBJECT_HOISTED],
1749 notes:
1750 "Hang on. Reaching into fetch to find out what it uses… that's Functionless all over again. Peeking inside, just with types instead of the compiler. Let's keep going anyway and see where it breaks.",
1751 }),
1752 api({
1753 title: "…which becomes really clear when your infrastructure is conditional",
1754 code: INFERRED_DEV_2,
1755 req: [GET_OBJECT_HOISTED, PUT_LOGS],
1756 notes:
1757 "And that becomes really clear the moment your infrastructure is conditional. Say we only want a Logs bucket in dev, and fetch writes the last read to it when it's there. That write shows up in fetch's type as R2.PutObject for Logs, and the type magic hoists it up.",
1758 }),
1759 api({
1760 title: "The types can't tell that logs.put only runs in dev",
1761 code: INFERRED_DEV_2,
1762 marks: [
1763 { kind: "underline", find: "if (logs)", label: "only in dev", side: "right", tone: "bad" },
1764 ],
1765 req: [GET_OBJECT_HOISTED, { ...PUT_LOGS, state: "bad", note: "required in every stage" }],
1766 notes:
1767 "But the if only runs in dev, and a type can't know that. fetch's type is the union of every path through it, so R2.PutObject for Logs is required everywhere, production included. Types see every possible path, never the one that actually runs.",
1768 }),
1769 api({
1770 title: "Now the Layer has to cover every path the code might take",
1771 code: INFERRED_DEV,
1772 req: [
1773 GET_OBJECT_HOISTED,
1774 {
1775 name: "R2.PutObject<Logs>",
1776 state: "bad",
1777 note: "R2.WriteBucket(Logs)\nprovided in production too",
1778 },
1779 ],
1780 notes:
1781 "So to compile, we provide R2.WriteBucket for Logs, in every stage. And the layers are what carry the policies, so every policy for every path gets granted, whether that path runs or not.",
1782 }),
1783 api({
1784 title: "…even the ones it never takes",
1785 code: INFERRED_DEV,
1786 marks: [
1787 {
1788 kind: "underline",
1789 find: "R2.WriteBucket(Logs)",
1790 label: "prod gets a permission only dev needs:\nleast privilege, violated",
1791 side: "below",
1792 arrow: true,
1793 tone: "bad",
1794 },
1795 ],
1796 req: [
1797 GET_OBJECT_HOISTED,
1798 {
1799 name: "R2.PutObject<Logs>",
1800 state: "bad",
1801 note: "R2.WriteBucket(Logs)\nprovided in production too",
1802 },
1803 ],
1804 notes:
1805 "Even if production never takes that path. The dev-only write to Logs is still in the type, so the WriteBucket layer has to be provided everywhere, and production gets permission to write to a bucket only dev uses. The very goal of this design, least privilege, is broken by the type system itself.",
1806 }),
1807 api({
1808 title: "Worst of all, we've broken encapsulation",
1809 code: INFERRED_DEV,
1810 marks: [
1811 {
1812 kind: "underline",
1813 find: "fetch: Effect.gen(function* () {",
1814 label: "its type now says R2, and which buckets",
1815 side: "right",
1816 tone: "bad",
1817 },
1818 ],
1819 req: [
1820 GET_OBJECT_HOISTED,
1821 {
1822 name: "R2.PutObject<Logs>",
1823 state: "bad",
1824 note: "R2.WriteBucket(Logs)\nprovided in production too",
1825 },
1826 ],
1827 notes:
1828 "Step back and look at what happened. The infrastructure a function uses has become part of its type. fetch's type now says R2, and exactly which buckets. That's broken encapsulation, and it's the problem that finally killed this design.",
1829 }),
1830 {
1831 kind: "code",
1832 group: "service",
1833 file: "src/Storage.ts",
1834 title: "To illustrate this, let's try to implement an Effect service",
1835 src: { code: SERVICE },
1836 notes:
1837 "To illustrate this, let's try to implement an Effect service, Effect's tool for encapsulation. An interface, with implementations provided as Layers. Storage gets a file by key, and says nothing about where files live. That's the whole point.",
1838 },
1839 {
1840 kind: "code",
1841 group: "service",
1842 file: "src/Storage.ts",
1843 title: "Its R2 implementation needs R2.GetObject<Uploads>",
1844 src: { code: `${SERVICE}\n\n${STORAGE_R2}` },
1845 marks: [
1846 {
1847 kind: "underline",
1848 find: "bucket.get(key)",
1849 label: "requires R2.GetObject<Uploads>",
1850 side: "right",
1851 tone: "bad",
1852 },
1853 ],
1854 notes:
1855 "Now implement it with R2. Because the requirement is inferred from usage, this get doesn't just return a file: its type also requires R2.GetObject for the Uploads bucket. And that doesn't match the interface, which requires nothing.",
1856 },
1857 {
1858 kind: "code",
1859 group: "service",
1860 file: "src/Storage.ts",
1861 title: "The only fix is to name R2, and the bucket, in the interface",
1862 src: { code: `${SERVICE_R2}\n\n${STORAGE_R2}` },
1863 marks: [
1864 {
1865 kind: "circle",
1866 find: "R2.GetObject<Uploads>",
1867 label: "the implementation, in the interface",
1868 side: "below",
1869 tone: "bad",
1870 },
1871 ],
1872 notes:
1873 "The only way to make it fit is to put the requirement in the interface. Now Storage says R2, and which bucket. The implementation has leaked into the interface.",
1874 },
1875 {
1876 kind: "code",
1877 group: "service",
1878 file: "src/Storage.ts",
1879 title: "Now there can never be a second implementation",
1880 src: { code: `${SERVICE_R2}\n\n${STORAGE_R2}\n\n${STORAGE_S3}` },
1881 marks: [
1882 {
1883 kind: "circle",
1884 find: "R2.GetObject<Uploads>",
1885 label: "the implementation, in the interface",
1886 side: "below",
1887 tone: "bad",
1888 },
1889 {
1890 kind: "underline",
1891 find: { text: "bucket.get(key)", nth: 2 },
1892 label: "requires S3.GetObject<Files>: doesn't fit",
1893 side: "right",
1894 tone: "bad",
1895 },
1896 ],
1897 notes:
1898 "And that's the nail in the coffin. Try an S3 implementation: same code, but its get requires S3.GetObject, and the interface already promised R2. You can't swap implementations, which is the whole point of a service. Infrastructure requirements can't live in the runtime function's type.",
1899 },
1900 {
1901 kind: "code",
1902 group: "service",
1903 file: "src/Storage.ts",
1904 title: "This is why a Layer yields its dependencies in the body…",
1905 src: { code: `${SERVICE}\n\n${STORAGE_LIVE}` },
1906 marks: [
1907 {
1908 kind: "underline",
1909 find: "const db = yield* Database;",
1910 label: "dependencies, yielded in the body",
1911 side: "right",
1912 tone: "construct",
1913 },
1914 ],
1915 notes:
1916 "This is why Effect has a pattern for this. When you build a Layer, you don't reach for dependencies inside each method. You yield them once, in the body of the Effect.",
1917 },
1918 {
1919 kind: "code",
1920 group: "service",
1921 file: "src/Storage.ts",
1922 title: "…and returns methods that close over them",
1923 src: { code: `${SERVICE}\n\n${STORAGE_LIVE}` },
1924 marks: [
1925 {
1926 kind: "underline",
1927 find: "const db = yield* Database;",
1928 label: "dependencies, yielded in the body",
1929 side: "right",
1930 tone: "construct",
1931 },
1932 {
1933 kind: "underline",
1934 find: "get: (key) => db.get(key),",
1935 label: "methods that close over them",
1936 side: "right",
1937 tone: "runtime",
1938 },
1939 ],
1940 notes:
1941 "And then it returns the implementation: methods that close over those dependencies. The interface stays clean, because the dependency lives in the constructor, not in the method's type.",
1942 },
1943 {
1944 kind: "code",
1945 group: "ctor",
1946 file: "src/Storage.ts",
1947 title: "It's an effectful constructor, like a class constructor",
1948 src: { code: STORAGE_LIVE },
1949 beside: { file: "the same idea, as a class", src: { code: STORAGE_CLASS } },
1950 links: [
1951 { from: "yield* Database", to: "constructor(private db: Database)" },
1952 { from: "db.get(key)", to: "this.db.get(key)", tone: "runtime" },
1953 ],
1954 frames: 40,
1955 notes:
1956 "It's called an effectful constructor, and it's just like a class constructor: take your dependencies once, up front, and the methods use them. The difference is the constructor is an Effect, so its dependencies are tracked in the type.",
1957 },
1958 api({
1959 title: "A cloud program is an effectful constructor too",
1960 snippet: "api-02-bucket.ts",
1961 marks: [
1962 {
1963 kind: "underline",
1964 find: 'const bucket = yield* R2.Bucket("Uploads");',
1965 label: "yields its resources",
1966 side: "right",
1967 tone: "construct",
1968 },
1969 {
1970 kind: "underline",
1971 find: "fetch: Effect.gen(function* () {",
1972 label: "returns what runs later",
1973 side: "right",
1974 tone: "runtime",
1975 },
1976 ],
1977 req: [],
1978 notes:
1979 "And that's what I finally realized. Look at our cloud program: it's the same shape. Yield resources in the body, return a fetch handler that closes over them. A cloud program is an effectful constructor, and it fits Effect's Layers perfectly. I'd been fighting the model instead of using it.",
1980 }),
1981 api({
1982 title: "A binding is just another dependency to yield",
1983 snippet: "api-04-get.ts",
1984 req: [{ ...READ, note: "declared in construction" }],
1985 notes:
1986 "A binding is just another dependency of the constructor. Yield R2.ReadBucket(bucket) in the body, exactly like the Storage layer yields Database, and fetch closes over the client it got back. The requirement lands on the program, where a Layer can satisfy it, and fetch's type stays clean, so a service built on it can have any implementation. It's still infrastructure as code, and I should embrace that.",
1987 }),
1988 api({
1989 title: "A queue works the same way",
1990 snippet: "api-05-queue.ts",
1991 req: [READ, WRITE],
1992 notes: "A queue is the same: declare it, ask to write to it, and Req gains Queues.WriteQueue.",
1993 }),
1994 api({
1995 title: "Then we hand it a Layer for each binding it needs",
1996 snippet: "api-06-provide.ts",
1997 req: [met(READ, "ReadBucketBinding"), met(WRITE, "WriteQueueBinding"), WORKER],
1998 notes:
1999 "Effect.provide satisfies each one with a Layer: an implementation of the requirement. These use Cloudflare's native bindings, and that adds a requirement of its own: they only work inside a Cloudflare Worker.",
2000 }),
2001 api({
2002 title: "Each one is a binding layer, and it has two faces",
2003 snippet: "api-06-provide.ts",
2004 marks: [
2005 {
2006 kind: "box",
2007 find: "R2.ReadBucketBinding,",
2008 to: "Queues.WriteQueueBinding,",
2009 label: "binding layers",
2010 side: "right",
2011 tone: "construct",
2012 },
2013 ],
2014 req: [met(READ, "ReadBucketBinding"), met(WRITE, "WriteQueueBinding"), WORKER],
2015 notes:
2016 "Each of these is a binding layer, and a binding layer has two faces: one that runs at construction, and one that runs at runtime.",
2017 }),
2018 api({
2019 title: "Its first face runs at construction and wires up the binding",
2020 snippet: "api-06-provide.ts",
2021 tints: [{ from: "const api = Effect.gen", to: "const jobs", tone: "construct" }],
2022 marks: [
2023 {
2024 kind: "circle",
2025 find: "R2.ReadBucket(bucket)",
2026 label: "binding, policy, env vars",
2027 side: "right",
2028 tone: "construct",
2029 },
2030 ],
2031 req: [
2032 met(READ, "ReadBucketBinding\nattaches the R2 binding"),
2033 met(WRITE, "WriteQueueBinding\nattaches the Queue binding"),
2034 WORKER,
2035 ],
2036 notes:
2037 "The first face runs during construction. When R2.ReadBucket(bucket) runs at deploy time, ReadBucketBinding wires up the binding: the native R2 binding on the Worker, plus whatever policy and environment variables it needs. Only for what the code actually declared.",
2038 }),
2039 api({
2040 title: "Its second face runs at runtime and implements the interface",
2041 snippet: "api-06-provide.ts",
2042 tints: [{ from: "fetch: Effect.gen", to: "}),", tone: "runtime" }],
2043 marks: [
2044 {
2045 kind: "underline",
2046 find: 'uploads.get("hello.txt")',
2047 label: "the layer's get",
2048 side: "right",
2049 tone: "runtime",
2050 },
2051 ],
2052 req: [
2053 met(READ, "ReadBucketBinding\nimplements get"),
2054 met(WRITE, "WriteQueueBinding\nimplements send"),
2055 WORKER,
2056 ],
2057 notes:
2058 "The second face is what R2.ReadBucket(bucket) returns: code that runs at runtime and implements the interface. When fetch calls uploads.get, that's the layer's get, talking to the native R2 binding.",
2059 }),
2060 api({
2061 title: "Conditional infrastructure is just an if statement",
2062 snippet: "api-06b-dev.ts",
2063 req: [
2064 met(READ, "ReadBucketBinding"),
2065 met(WRITE, "WriteQueueBinding"),
2066 met(WRITE_LOGS, "WriteBucketBinding"),
2067 WORKER,
2068 ],
2069 notes:
2070 "Remember the Logs bucket that only exists in dev? Now it's ordinary code: create it and bind it for writing only when dev is true. No new syntax, no analysis. The program uses R2.WriteBucket, so its layer, R2.WriteBucketBinding, goes in the array like any other.",
2071 }),
2072 api({
2073 title: 'And "peeking inside" is solved by just running the code',
2074 snippet: "api-06b-dev.ts",
2075 marks: [
2076 {
2077 kind: "underline",
2078 find: "R2.WriteBucket(logs)",
2079 label: "skipped in prod",
2080 side: "right",
2081 tone: "good",
2082 },
2083 ],
2084 req: [
2085 met(READ, "ReadBucketBinding"),
2086 met(WRITE, "WriteQueueBinding"),
2087 met(WRITE_LOGS, "WriteBucketBinding\nnever runs in prod"),
2088 WORKER,
2089 ],
2090 notes:
2091 "And that solves peeking inside. Alchemy doesn't read your code to find the bindings; it runs it. The layer's construction face only runs when that line runs. In dev it does, and the binding and its policy are attached. In production logs is undefined, so R2.WriteBucket(logs) never runs: no binding, no policy, no environment variable.",
2092 }),
2093 api({
2094 title: "The layer ships in the bundle, but least privilege holds",
2095 snippet: "api-06b-dev.ts",
2096 marks: [
2097 {
2098 kind: "underline",
2099 find: "R2.WriteBucket(logs)",
2100 label: "skipped in prod",
2101 side: "right",
2102 tone: "good",
2103 },
2104 {
2105 kind: "box",
2106 find: "R2.WriteBucketBinding,",
2107 label: "in the bundle, never granted",
2108 side: "right",
2109 tone: "good",
2110 },
2111 ],
2112 req: [
2113 met(READ, "ReadBucketBinding"),
2114 met(WRITE, "WriteQueueBinding"),
2115 met(WRITE_LOGS, "WriteBucketBinding\nno permission in prod"),
2116 WORKER,
2117 ],
2118 notes:
2119 "So the WriteBucketBinding code is still in the production bundle, but it never grants anything there. Providing a layer isn't granting a permission; running the code is. That's the difference from my first attempt, where the type demanded the permission in every stage.",
2120 }),
2121 api({
2122 title: "The types no longer guarantee it, running the code does",
2123 snippet: "api-06b-dev.ts",
2124 marks: [
2125 {
2126 kind: "underline",
2127 find: "R2.WriteBucket(logs)",
2128 label: "skipped in prod",
2129 side: "right",
2130 tone: "good",
2131 },
2132 {
2133 kind: "box",
2134 find: "R2.WriteBucketBinding,",
2135 label: "in the bundle, never granted",
2136 side: "right",
2137 tone: "good",
2138 },
2139 ],
2140 req: [
2141 met(READ, "ReadBucketBinding"),
2142 met(WRITE, "WriteQueueBinding"),
2143 met(WRITE_LOGS, "WriteBucketBinding\nno permission in prod"),
2144 WORKER,
2145 ],
2146 aside: { text: "pragmatism beats purity", image: "michael-pointing.jpg" },
2147 notes:
2148 "So that's where my original goal ended up. Least privilege is no longer guaranteed by the type checker; it comes from running the code. The types still guarantee every binding has an implementation, and the cost is a few bytes of unused client code in production. Pragmatism beats purity. Sorry, Michael.",
2149 }),
2150 api({
2151 title: "So far, though, it's just a program that nothing runs",
2152 snippet: "api-06-provide.ts",
2153 req: [met(READ, "ReadBucketBinding"), met(WRITE, "WriteQueueBinding"), WORKER],
2154 notes:
2155 "Let's drop the Logs bucket again to keep the code small. And notice what we have: api is just a value. An Effect describing a program. Nothing has deployed it, and nothing runs it yet.",
2156 }),
2157 api({
2158 title: "Now let's actually deploy it, starting with a Worker",
2159 snippet: "api-07-worker.ts",
2160 req: PROVIDED,
2161 notes:
2162 "So let's actually deploy it somewhere. Wrap it in a Cloudflare Worker: the function resource from our imaginary language. The Worker checks the program's Req against what it can provide, and it can provide itself.",
2163 }),
2164 api({
2165 title: "export default and import.meta.url say what to bundle",
2166 snippet: "api-07-worker.ts",
2167 marks: [
2168 {
2169 kind: "underline",
2170 find: "export default",
2171 label: "the Worker's entrypoint",
2172 side: "right",
2173 tone: "construct",
2174 },
2175 {
2176 kind: "circle",
2177 find: "import.meta.url",
2178 label: "this file",
2179 side: "right",
2180 tone: "construct",
2181 },
2182 ],
2183 req: PROVIDED,
2184 notes:
2185 "Two conventions you'll see everywhere. The Worker is the file's default export, and main is import.meta.url: this very file. That tells Alchemy what to bundle and what the entrypoint is. There's no separate handler file to keep in sync.",
2186 }),
2187 api({
2188 title: "Rolldown bundles it, and tree-shakes what you don't use",
2189 snippet: "api-07-worker.ts",
2190 marks: [
2191 {
2192 kind: "box",
2193 find: "R2.ReadBucketBinding,",
2194 to: "Queues.WriteQueueBinding,",
2195 label: "only these clients are bundled",
2196 side: "right",
2197 tone: "construct",
2198 },
2199 ],
2200 req: PROVIDED,
2201 bundle: PRECISE,
2202 notes:
2203 "At deploy time Alchemy runs the file through Rolldown and tree-shakes it hard. Anything the Worker doesn't reach is dropped. The binding layers you provide decide which runtime clients end up in the bundle.",
2204 }),
2205 api({
2206 title: "A catch-all like R2.AllBindings would bundle every client",
2207 code: ALL_BINDINGS,
2208 quiet: true,
2209 marks: [{ kind: "circle", find: "R2.AllBindings", tone: "bad" }],
2210 req: PROVIDED,
2211 bundle: EVERYTHING,
2212 frames: 50,
2213 notes:
2214 "That's why there's no R2.AllBindings or Queues.AllBindings. A catch-all would be convenient, but it would pull every client for every operation into every bundle, whether you call it or not.",
2215 }),
2216 api({
2217 title: "That's why you provide only the bindings you use",
2218 snippet: "api-07-worker.ts",
2219 quiet: true,
2220 marks: [
2221 {
2222 kind: "box",
2223 find: "R2.ReadBucketBinding,",
2224 to: "Queues.WriteQueueBinding,",
2225 label: "just what you use",
2226 side: "right",
2227 tone: "good",
2228 },
2229 ],
2230 req: PROVIDED,
2231 bundle: PRECISE,
2232 notes:
2233 "So you provide the specific bindings, one per capability. It's a little more typing, and it keeps each bundle down to exactly the code it runs.",
2234 }),
2235 api({
2236 title: "The right bindings also depend on where it runs",
2237 snippet: "api-10-lambda.error.ts",
2238 error: { hide: true },
2239 req: [...PROVIDED.slice(0, 2), WORKER],
2240 notes:
2241 "Which bindings are right also depends on where the program runs. The program itself doesn't care, so let's swap Cloudflare.Worker for AWS.Lambda.Function.",
2242 }),
2243 api({
2244 title: "On Lambda, our Cloudflare binding layers won't compile",
2245 snippet: "api-10-lambda.error.ts",
2246 error: { pick: firstLine("Type 'WorkerEnvironment'") },
2247 req: [...PROVIDED.slice(0, 2), { ...WORKER, state: "bad", note: "not a Worker" }],
2248 notes:
2249 "The native binding layers require a Cloudflare Worker, and a Lambda Function can't provide one. The type checker catches it before anything is deployed.",
2250 }),
2251 api({
2252 title: "Swap the native bindings for HTTP, and it runs anywhere",
2253 snippet: "api-11-http.error.ts",
2254 // TODO: fails today: Cloudflare *Http layers also need CloudflareEnvironment and Self,
2255 // which AWS.Lambda.Function doesn't provide yet.
2256 error: { hide: true },
2257 req: [
2258 met(READ, "ReadBucketHttp\ncalls Cloudflare's API"),
2259 met(WRITE, "WriteQueueHttp\ncalls Cloudflare's API"),
2260 ],
2261 notes:
2262 "Swap each binding layer for its HTTP twin. ReadBucketHttp and WriteQueueHttp call Cloudflare's API instead of a native binding, so they don't need a Worker, and the Cloudflare.Worker requirement disappears. Same program, different runtime, different layer. That's the other reason there's no AllBindings: the right implementation depends on the environment you're running in, so you choose it.",
2263 }),
2264 api({
2265 title: "Each HTTP layer mints a least-privilege Cloudflare API token",
2266 snippet: "api-11-http.error.ts",
2267 error: { hide: true },
2268 marks: [
2269 {
2270 kind: "box",
2271 find: "R2.ReadBucketHttp,",
2272 to: "Queues.WriteQueueHttp,",
2273 label: "one scoped token each",
2274 side: "right",
2275 tone: "construct",
2276 },
2277 ],
2278 req: [
2279 met(READ, "ReadBucketHttp\nmints an R2 read-only API token"),
2280 met(WRITE, "WriteQueueHttp\nmints a Queues write-only API token"),
2281 ],
2282 notes:
2283 "But how does a Lambda get into Cloudflare? At deploy time, each HTTP layer's construction face mints a Cloudflare account API token, scoped to exactly what the code declared: read this bucket, write to this queue, and nothing else.",
2284 }),
2285 {
2286 kind: "code",
2287 group: "api",
2288 file: "src/Api.ts",
2289 title: "…and binds it securely into the Lambda",
2290 src: { snippet: "api-11-http.error.ts", regions: ["show"] },
2291 error: { hide: true },
2292 diagram: CROSS_CLOUD(false),
2293 notes:
2294 "Then it binds the token into the Lambda as a secret, just like the bucket's name was bound in our imaginary language. The token never appears in your code or your repository.",
2295 },
2296 {
2297 kind: "code",
2298 group: "api",
2299 file: "src/Api.ts",
2300 title: "Now AWS can call Cloudflare, with only the access it needs",
2301 src: { snippet: "api-11-http.error.ts", regions: ["show"] },
2302 error: { hide: true },
2303 diagram: CROSS_CLOUD(true),
2304 notes:
2305 "And now the Lambda, running in AWS, reads from R2 and writes to a Cloudflare Queue, with a token that can do exactly that. Cross-cloud, least privilege, and the same program as before.",
2306 },
2307 lang({
2308 group: "phase-callback",
2309 title: "Remember the phase rule from our imaginary language?",
2310 src: { code: COLORED_BAD },
2311 marks: [
2312 {
2313 kind: "strike",
2314 find: "Bucket()",
2315 label: "can't create a resource at runtime",
2316 side: "right",
2317 tone: "bad",
2318 },
2319 ],
2320 notes:
2321 "Before we deploy, remember the rule from our imaginary language. Construction and runtime are different colors, and creating a bucket inside a request was a compile error.",
2322 }),
2323 lang({
2324 group: "phase-callback",
2325 title: "…and that construction can't call runtime code",
2326 src: { code: COLORED_EARLY },
2327 quiet: true,
2328 marks: [
2329 {
2330 kind: "strike",
2331 find: 'bucket.get("hello.txt")',
2332 label: "no request yet",
2333 side: "right",
2334 tone: "bad",
2335 },
2336 ],
2337 notes:
2338 "And the other direction: reading the bucket during construction, when there's no request yet, was an error too.",
2339 }),
2340 api({
2341 title: "So let's make that mistake in Alchemy",
2342 snippet: "api-08-construct.error.ts",
2343 marks: [
2344 {
2345 kind: "underline",
2346 find: 'yield* uploads.get("hello.txt");',
2347 label: "at deploy time",
2348 side: "right",
2349 tone: "bad",
2350 },
2351 ],
2352 error: { hide: true },
2353 req: [...PROVIDED, { name: "RuntimeContext", note: "only exists during a request" }],
2354 notes:
2355 "Let's make exactly that mistake in the Worker: read the bucket during construction, at deploy time, when there's no request yet. Req picks up RuntimeContext.",
2356 }),
2357 api({
2358 title: "It won't compile, because a Worker can't provide RuntimeContext",
2359 snippet: "api-08-construct.error.ts",
2360 error: { pick: firstLine("Type 'RuntimeContext'") },
2361 req: [
2362 ...PROVIDED,
2363 { name: "RuntimeContext", state: "bad", note: "only exists during a request" },
2364 ],
2365 notes:
2366 "A Worker's constructor runs at deploy time and cold start, with no request, so it can't provide RuntimeContext. Reading the bucket there is a type error, just like in our imaginary language.",
2367 }),
2368 api({
2369 title: "Unless you opt out explicitly (don't do this)",
2370 snippet: "api-09-phantom.ts",
2371 req: [...PROVIDED, PHANTOM],
2372 notes:
2373 "You can still make the call, but only by providing RuntimeContext.phantom: an explicit opt-out that squashes the error, like ts-expect-error. It's there for emergencies. Don't do this.",
2374 }),
2375 api({
2376 title: "What actually creates the bucket, though?",
2377 snippet: "api-07-worker.ts",
2378 marks: [{ kind: "circle", find: 'R2.Bucket("Uploads")', tone: "construct" }],
2379 req: PROVIDED,
2380 notes:
2381 "Drop the opt-out, we're done with that. We've seen exactly what ends up in the Worker's bundle. But nothing in it creates the bucket. So what does declaring one actually do?",
2382 }),
2383 api({
2384 title: "Declaring a resource just yields a plain piece of data",
2385 snippet: "api-07-worker.ts",
2386 marks: [
2387 {
2388 kind: "circle",
2389 find: 'R2.Bucket("Uploads")',
2390 label: "a type, a name, and props",
2391 side: "right",
2392 tone: "construct",
2393 },
2394 ],
2395 req: PROVIDED,
2396 notes:
2397 "A resource in Alchemy is just data: its type, its name, and its props. Yielding it doesn't call any cloud API.",
2398 }),
2399 api({
2400 title: "…that asks for a provider to create it",
2401 snippet: "api-07-worker.ts",
2402 marks: [
2403 {
2404 kind: "underline",
2405 find: 'R2.Bucket("Uploads")',
2406 label: "needs R2.BucketProvider",
2407 side: "right",
2408 tone: "construct",
2409 },
2410 {
2411 kind: "underline",
2412 find: 'Queues.Queue("Jobs")',
2413 label: "needs Queues.QueueProvider",
2414 side: "right",
2415 tone: "construct",
2416 },
2417 ],
2418 req: [BUCKET, ...PROVIDED.slice(0, 1), QUEUE, ...PROVIDED.slice(1)],
2419 notes:
2420 "And it expresses a requirement: a provider that knows how to create, update and delete that kind of resource. R2.BucketProvider, Queues.QueueProvider. They show up in Req like any other requirement.",
2421 }),
2422 api({
2423 title: "Unlike a CDK construct, none of the provisioning code is in here",
2424 snippet: "api-07-worker.ts",
2425 marks: [
2426 {
2427 kind: "box",
2428 find: 'const bucket = yield* R2.Bucket("Uploads");',
2429 to: "const jobs = yield* Queues.WriteQueue(queue);",
2430 label: "no create, update, or delete",
2431 side: "right",
2432 tone: "good",
2433 },
2434 ],
2435 req: [BUCKET, ...PROVIDED.slice(0, 1), QUEUE, ...PROVIDED.slice(1)],
2436 notes:
2437 "Compare that with where I started. A CDK construct carries all of its provisioning code with it. Here the resource is a description plus a requirement, and the code that actually provisions it lives somewhere else.",
2438 }),
2439 stack({
2440 title: "This is where Stacks come in",
2441 code: STACK_1,
2442 notes:
2443 "So who provides the providers, and how do we actually deploy this Worker? This is where Stacks come in: the entry point for alchemy deploy, in alchemy.run.ts. It starts with a name.",
2444 }),
2445 stack({
2446 title: "A Stack is a set of resources you deploy as one unit",
2447 code: STACK_1,
2448 marks: [{ kind: "circle", find: '"App"', label: "one app", side: "right", tone: "construct" }],
2449 notes:
2450 "So what is a Stack? It's the root of the program: a collection of resources that are deployed, updated and destroyed together, as one unit.",
2451 }),
2452 stack({
2453 title: "…and each stage is its own isolated copy of it",
2454 code: STACK_1,
2455 marks: [{ kind: "circle", find: '"App"', label: "one app", side: "right", tone: "construct" }],
2456 diagram: STAGES,
2457 notes:
2458 "And every deploy targets a stage. Each stage is a separate, isolated instance of the same Stack, with its own resources and its own state. Your dev copy and production never share a resource.",
2459 }),
2460 stack({
2461 title: "We give the Stack the providers that create resources",
2462 code: STACK_2,
2463 notes:
2464 "Next, the providers: the code that actually creates, updates and deletes resources. Cloudflare.providers() is every Cloudflare provider there is.",
2465 }),
2466 stack({
2467 title: "All of them, because this code isn't bundled or used at runtime",
2468 code: STACK_2,
2469 marks: [
2470 {
2471 kind: "box",
2472 find: "providers: Cloudflare.providers(),",
2473 label: "all of them",
2474 side: "right",
2475 tone: "construct",
2476 },
2477 ],
2478 notes:
2479 "Unlike the bindings, we don't have to be precise here. This code is never bundled into the Worker and never runs at runtime. It only runs on your machine, or in CI, during deploy, so none of it needs to be tree-shaken.",
2480 }),
2481 stack({
2482 title: "It also needs somewhere to remember what it deployed",
2483 code: STACK_3,
2484 notes:
2485 "Then state: where Alchemy records what it deployed for each stage, so the next deploy knows what to create, update or delete. Here it's stored in your Cloudflare account, so your laptop and CI share it.",
2486 }),
2487 stack({
2488 title: "Then you give it an Effect that yields the resources you want",
2489 code: STACK_4,
2490 notes:
2491 "Finally, the program itself: an Effect that yields the resources you want. Here, that's our Worker.",
2492 }),
2493 {
2494 kind: "code",
2495 group: "stack",
2496 file: "alchemy.run.ts",
2497 title: "…and returns what we want to know, like its URL",
2498 src: { snippet: "stack.ts", regions: ["show"] },
2499 notes:
2500 "And it returns the outputs we care about, like the Worker's URL, printed after every deploy.",
2501 },
2502 {
2503 kind: "code",
2504 group: "stack",
2505 file: "alchemy.run.ts",
2506 title: "Yielding Api brings its provider requirements with it",
2507 src: { snippet: "stack.ts", regions: ["show"] },
2508 marks: [
2509 {
2510 kind: "underline",
2511 find: "yield* Api",
2512 label: "needs these",
2513 side: "right",
2514 tone: "construct",
2515 },
2516 ],
2517 req: { label: REQ_LABEL, items: [BUCKET, WORKER_PROVIDER, QUEUE] },
2518 notes:
2519 "Yielding Api brings its requirements along: a provider for every kind of resource it declared. R2.BucketProvider for the bucket, Queues.QueueProvider for the queue, and Cloudflare.WorkerProvider for the Worker itself. They bubble up to the Stack.",
2520 },
2521 {
2522 kind: "code",
2523 group: "stack",
2524 file: "alchemy.run.ts",
2525 title: "…and Cloudflare.providers() satisfies all of them",
2526 src: { snippet: "stack.ts", regions: ["show"] },
2527 marks: [
2528 {
2529 kind: "box",
2530 find: "providers: Cloudflare.providers(),",
2531 label: "all three",
2532 side: "right",
2533 tone: "good",
2534 },
2535 ],
2536 req: { label: REQ_LABEL, items: [met(BUCKET, ""), met(WORKER_PROVIDER, ""), met(QUEUE, "")] },
2537 notes:
2538 "And the providers we gave the Stack satisfy them. That's why it can be every Cloudflare provider: this code runs during deploy, and none of it ships in the Worker.",
2539 },
2540 {
2541 kind: "code",
2542 group: "stack",
2543 file: "alchemy.run.ts",
2544 title: "Give it no providers, and it won't compile",
2545 src: { snippet: "stack-empty.error.ts", regions: ["show"] },
2546 quiet: true,
2547 error: { pick: (lines) => lines.slice(0, 2) },
2548 req: {
2549 label: REQ_LABEL,
2550 items: [
2551 { ...BUCKET, state: "bad", note: "" },
2552 { ...WORKER_PROVIDER, state: "bad", note: "" },
2553 { ...QUEUE, state: "bad", note: "" },
2554 ],
2555 },
2556 notes:
2557 "And it's checked. Swap Cloudflare.providers() for Layer.empty and the Stack no longer compiles: the Worker still needs its providers, and nothing is providing them.",
2558 },
2559
2560 {
2561 kind: "code",
2562 group: "deploy",
2563 file: "terminal",
2564 lang: "ansi",
2565 title: "alchemy deploy runs the Stack and shows you a plan",
2566 src: { code: DEPLOY_PLAN },
2567 marks: [
2568 {
2569 kind: "box",
2570 find: "+ Api (Cloudflare.Worker)",
2571 to: " + Jobs",
2572 label: "the bindings, too",
2573 side: "right",
2574 tone: "construct",
2575 },
2576 ],
2577 notes:
2578 "Now deploy. alchemy deploy runs the Stack's construction phase on your machine. That run discovers every resource and binding, and diffs them against the state into a plan: three resources to create, and the Worker's two bindings.",
2579 },
2580 {
2581 kind: "code",
2582 group: "deploy",
2583 file: "terminal",
2584 lang: "ansi",
2585 title: "Approve it, and everything is created and wired together",
2586 src: { code: DEPLOY_APPLIED },
2587 notes:
2588 "Approve it, and the providers do the work: the bucket, the queue, then the Worker with its bindings attached. One program, deployed. Now let's build something real.",
2589 },
2590 ...demo,
2591 ];
2592
2593 // ─── The talk: condensed ─────────────────────────────────────────────────────
2594 // The problem fast, the idea (a language for the cloud) as a hypothetical, why
2595 // Alchemy is shaped the way it is, then demos. Steps are picked from `allSteps`
2596 // by title, optionally retitled, with a few new ones in between.
2597
2598 /** A step from `allSteps`, by its current title; `as` renames it for the new flow. */
2599 const pick = (title: string, as?: string, patch?: Partial<CodeSpec>): StepSpec => {
2600 const found = allSteps.find((step) => step.title === title);
2601 if (!found) throw new Error(`no step titled ${JSON.stringify(title)}`);
2602 return { ...found, ...(as ? { title: as } : {}), ...(patch ?? {}) } as StepSpec;
2603 };
2604
2605 const LIVE = {
2606 file: "src/Api.ts",
2607 snippet: "ApiLive.ts",
2608 group: "demo-live",
2609 regions: ["top", "rooms", "fetchTop", "live", "click", "fetchEnd"],
2610 };
2611 const ROOM = { file: "src/LinkRoom.ts", snippet: "LinkRoom.ts", group: "demo-room" };
2612
2613 /** A code step from the Shorty app in `snippets/shorty/`. */
2614 const shorty = (s: {
2615 title: string;
2616 notes: string;
2617 file: string;
2618 snippet: string;
2619 group: string;
2620 regions?: string[];
2621 omit?: string[];
2622 marks?: CodeSpec["marks"];
2623 }): StepSpec => ({
2624 kind: "code",
2625 group: s.group,
2626 file: s.file,
2627 title: s.title,
2628 src: { snippet: `shorty/${s.snippet}`, regions: s.regions ?? ["show"], omit: s.omit },
2629 marks: s.marks,
2630 notes: s.notes,
2631 });
2632
2633 const liveClicks: StepSpec[] = [
2634 {
2635 kind: "slide",
2636 layout: "section",
2637 title: "Now let's make it live",
2638 eyebrow: "Durable Objects + WebSockets",
2639 heading: "Now let's make it live",
2640 subtitle: "Every click, pushed to every dashboard, as it happens",
2641 notes:
2642 "Shorty works. Now let's make it feel alive: count every click, and push the count to every open dashboard in real time. That's a job for a Durable Object with WebSockets.",
2643 },
2644 shorty({
2645 ...ROOM,
2646 title: "A Durable Object is a tiny stateful server per link",
2647 omit: ["count", "record", "socket"],
2648 notes:
2649 "A Durable Object is a class with its own storage, one instance per name. We'll have one per short link: a room that owns that link's clicks.",
2650 }),
2651 shorty({
2652 ...ROOM,
2653 title: "It keeps the click count in its own storage",
2654 omit: ["record", "socket"],
2655 notes: "When it wakes up, it reads its count from transactional storage.",
2656 }),
2657 shorty({
2658 ...ROOM,
2659 title: "Each click bumps the count and saves it",
2660 regions: ["body"],
2661 omit: ["push", "socket"],
2662 notes:
2663 "record adds one and saves it. Storage and compute live together, so there's no round trip to a database.",
2664 }),
2665 shorty({
2666 ...ROOM,
2667 title: "fetch upgrades to a WebSocket",
2668 regions: ["body"],
2669 omit: ["push"],
2670 notes: "fetch upgrades the request to a WebSocket and sends the current count straight away.",
2671 }),
2672 shorty({
2673 ...ROOM,
2674 title: "…and every click is pushed to every socket",
2675 regions: ["body"],
2676 notes:
2677 "And on every click, the new count goes to every connected socket. These are hibernatable: the object can sleep while the sockets stay open, so idle rooms cost nothing.",
2678 }),
2679 shorty({
2680 ...LIVE,
2681 title: "The Worker asks for the rooms, like any other binding",
2682 omit: ["live", "click"],
2683 notes:
2684 "In the Worker, yield LinkRoom. Same shape as every binding so far: declared in construction, used at runtime.",
2685 }),
2686 shorty({
2687 ...LIVE,
2688 title: "A click records itself in the link's room…",
2689 omit: ["live"],
2690 notes:
2691 "When someone follows a short link, look it up, record the click in that link's room, and redirect.",
2692 }),
2693 shorty({
2694 ...LIVE,
2695 title: "…and /live hands the socket to the room",
2696 notes:
2697 "And GET /:code/live hands the WebSocket straight to the room. That's the whole backend.",
2698 }),
2699 shorty({
2700 title: "The dashboard just opens a socket",
2701 notes:
2702 "On the website, each row opens a socket to its link's room and renders whatever arrives.",
2703 file: "web/src/useClicks.ts",
2704 snippet: "useClicks.ts",
2705 group: "demo-hook",
2706 }),
2707 {
2708 kind: "browser",
2709 title: "Click a link, and every dashboard updates",
2710 url: "http://localhost:5173",
2711 image: "04-durable-objects-browser-1.png",
2712 notes:
2713 "Click the link from your phone and the count ticks up here, instantly. No polling, no pub/sub service to set up.",
2714 },
2715 ];
2716
2717 export const steps: StepSpec[] = [
2718 pick("A programming language for the cloud"),
2719
2720 // 1. The problem, fast
2721 pick(
2722 "Infrastructure as code declares what should be, not what is",
2723 "Infrastructure as code: declare what the cloud should be",
2724 ),
2725 pick("An engine compares it to the cloud, and creates what's missing"),
2726 pick("Then the AWS CDK came out", "The CDK made it real code"),
2727 pick(
2728 "It also bothered me that the runtime code lived elsewhere",
2729 "But the code that runs is a second program",
2730 ),
2731 pick("Rename one side, and nothing tells you the other broke"),
2732
2733 // 2. The idea: a language for the cloud
2734 pick(
2735 "I wanted one language where a variable could be a cloud resource",
2736 "Imagine a language where a variable is a cloud resource",
2737 ),
2738 pick("You'd declare a queue the same way"),
2739 pick("Functions would be resources too"),
2740 pick("When the function reads the bucket, they'd become connected"),
2741 pick("That connection would need permission to read the bucket"),
2742 pick("Sending to the queue would connect them the same way"),
2743 pick(
2744 "The language would work all of this out from code",
2745 "Least-privilege IAM, inferred from the code",
2746 ),
2747 pick("But what if the function created a bucket?"),
2748 pick("Uh-oh. Resources need to be known ahead of time"),
2749 pick("…and code outside the function has no request to serve"),
2750 pick("So a cloud program is actually a language with two phases"),
2751 pick("Now creating a bucket at runtime is a compile error"),
2752 pick("And inferring permissions becomes a kind of type checking"),
2753
2754 // 3. Effect already models this
2755 ...typedFetch,
2756 pick("That's exactly the type of an Effect"),
2757
2758 // 4. How bindings work in Alchemy
2759 pick("Let's write the program again with Effect", "So let's write it with Effect"),
2760 pick("Resources are declared in construction, with yield*"),
2761 api({
2762 title: "Translated directly, the need lands on fetch",
2763 code: INFERRED,
2764 emphasize: ["bucket.get("],
2765 req: [],
2766 fetchReq: [{ name: "R2.GetObject<Uploads>", note: "to read the bucket" }],
2767 notes:
2768 "Translate the imaginary language directly: fetch calls bucket.get, and its type needs R2.GetObject for Uploads. So the requirement lands on fetch.",
2769 }),
2770 api({
2771 title: "But permissions are granted at deploy, and deploy runs construction",
2772 code: INFERRED,
2773 marks: [
2774 {
2775 kind: "underline",
2776 find: "fetch: Effect.gen(function* () {",
2777 label: "runs per request, too late to grant anything",
2778 side: "right",
2779 tone: "bad",
2780 },
2781 ],
2782 req: [],
2783 fetchReq: [{ name: "R2.GetObject<Uploads>", state: "bad", note: "to read the bucket" }],
2784 notes:
2785 "But whatever grants s3:GetObject has to run when the Worker is deployed, and that's construction. fetch only runs once requests arrive, long after the deploy.",
2786 }),
2787 pick(
2788 "A binding is just another dependency to yield",
2789 "So declare it in construction, and get back a client",
2790 ),
2791 pick("A queue works the same way"),
2792 pick("Then we hand it a Layer for each binding it needs"),
2793 pick("Each one is a binding layer, and it has two faces"),
2794 pick("Its first face runs at construction and wires up the binding"),
2795 pick("Its second face runs at runtime and implements the interface"),
2796 pick("Conditional infrastructure is just an if statement"),
2797 pick(
2798 'And "peeking inside" is solved by just running the code',
2799 "Running the code decides what's granted",
2800 ),
2801 pick(
2802 "Now let's actually deploy it, starting with a Worker",
2803 "Wrap it in a Worker, and it deploys",
2804 { group: "api-host" },
2805 ),
2806 pick(
2807 "On Lambda, our Cloudflare binding layers won't compile",
2808 "Point it at Lambda, and the types catch the wrong bindings",
2809 { group: "api-host" },
2810 ),
2811 pick("Swap the native bindings for HTTP, and it runs anywhere", undefined, { group: "api-host" }),
2812 pick("Now AWS can call Cloudflare, with only the access it needs", undefined, {
2813 group: "api-host",
2814 }),
2815 pick("This is where Stacks come in", "A Stack deploys it"),
2816 pick("Yielding Api brings its provider requirements with it"),
2817 pick("…and Cloudflare.providers() satisfies all of them"),
2818 pick("alchemy deploy runs the Stack and shows you a plan"),
2819 pick("Approve it, and everything is created and wired together"),
2820
2821 // 5. Demo: build Shorty with an agent
2822 ...allSteps.slice(allSteps.findIndex((s) => s.title === "Let's build something")),
2823
2824 // 6. Demo: live clicks with Durable Objects and WebSockets
2825 ...liveClicks,
2826 ];