The best way to control Claude Code, Codex and more from any computer or phone
| 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 | ]; |