# Mike Bild > Software architect & engineer in Berlin. More than 30 years of software, a good 15 of them focused on distributed systems, APIs and digital products. These days also agentic engineering. ## Navigation - [Profile](https://www.mikebild.dev/en/profile/) - [Blog](https://www.mikebild.dev/en/blog/) - [Projects](https://www.mikebild.dev/en/projects/) - [Contact](https://www.mikebild.dev/en/contact/): mike.bild@gmail.com - [GitHub](https://github.com/MikeBild) - [LinkedIn](https://www.linkedin.com/in/mikebild) - [Mike Bild · Blog](https://www.mikebild.dev/en/feed.xml) - [Mike Bild · Blogcast](https://www.mikebild.dev/de/blogcast.xml): Selected blog articles by Mike Bild as audio versions – software architecture, engineering and method. - [MCP knowledge server](https://worker.mikebild.dev/workshop-online-api/knowledge/mcp): Articles, slide decks and the workshop catalog for AI assistants, read-only, no login. Guide: https://www.mikebild.dev/en/mcp/ - [Deutsch](https://www.mikebild.dev/llms-full.txt) ## Current projects - [SubKit](https://subkit.mikebild.dev/en/): Built once with the AI, shared by approval: team workflows with permissions and history. (Beta by invitation) - [Harmoniqs](https://harmoniqs.mikebild.dev/en/): Develop song ideas with chords, the Looper and BRAIN. (Beta) - TackTics: A sailing trainer meant to analyze data from on board. (In progress) ## Training - [JavaScript and TypeScript from scratch](https://slides.mikebild.dev/introduction-javascript-typescript.en.html): You write modern JavaScript and type it with TypeScript so the compiler finds your mistakes before deployment. – Repository: https://github.com/MikeBild/introduction-javascript – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-javascript-typescript/introduction-javascript-typescript.en.pdf?v=7c3d048ab16c – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-javascript-typescript/introduction-javascript-typescript.en.mp4?v=7c3d048ab16c – Deutsch: https://slides.mikebild.dev/introduction-javascript-typescript.html - [Python for developers with uv, pytest, and Flask](https://slides.mikebild.dev/introduction-python.en.html): You learn modern Python with uv, type hints, and pytest, and build a tested HTTP API with Flask for the workshop shop. – Repository: https://github.com/MikeBild/introduction-python – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-python/introduction-python.en.pdf?v=a9426e4ffd37 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-python/introduction-python.en.mp4?v=a9426e4ffd37 – Deutsch: https://slides.mikebild.dev/introduction-python.html - [Modern web platform without a framework](https://slides.mikebild.dev/introduction-web-plattform.en.html): You build the workshop shop using only the browser’s HTML, CSS, and JavaScript: accessible, fast, offline-capable, and with Web Components. – Repository: https://github.com/MikeBild/introduction-web-plattform – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-web-plattform/introduction-web-plattform.en.pdf?v=a8018c5e80c1 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-web-plattform/introduction-web-plattform.en.mp4?v=a8018c5e80c1 – Deutsch: https://slides.mikebild.dev/introduction-web-plattform.html - [Node.js backend, functional and type-safe](https://slides.mikebild.dev/introduction-nodejs.en.html): You build a Node.js service with Express 5 from the first request to container operations, tested, logged, and hardened. – Repository: https://github.com/MikeBild/introduction-nodejs – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-nodejs/introduction-nodejs.en.pdf?v=965710139dd0 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-nodejs/introduction-nodejs.en.mp4?v=965710139dd0 – Deutsch: https://slides.mikebild.dev/introduction-nodejs.html - [React with TypeScript all the way to production](https://slides.mikebild.dev/introduction-react.en.html): You use React, TypeScript, and React Router to build an app from small components, then ship it to production with tests and good accessibility. – Repository: https://github.com/MikeBild/introduction-react – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-react/introduction-react.en.pdf?v=19f0d4ba8526 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-react/introduction-react.en.mp4?v=19f0d4ba8526 – Deutsch: https://slides.mikebild.dev/introduction-react.html - [Svelte 5 and SvelteKit with TypeScript](https://slides.mikebild.dev/introduction-svelte.en.html): You build the workshop store with Svelte 5, runes, and SvelteKit 3, from the first component to a tested Node server. – Repository: https://github.com/MikeBild/introduction-svelte – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-svelte/introduction-svelte.en.pdf?v=8ed6ed7c9262 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-svelte/introduction-svelte.en.mp4?v=8ed6ed7c9262 – Deutsch: https://slides.mikebild.dev/introduction-svelte.html - [Modernize KnockoutJS and migrate step by step](https://slides.mikebild.dev/introduction-knockoutjs.en.html): You maintain a Knockout application with TypeScript, Vite, and tests, close security gaps, and plan the migration in small steps. – Repository: https://github.com/MikeBild/introduction-knockoutjs – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-knockoutjs/introduction-knockoutjs.en.pdf?v=db3087c1f285 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-knockoutjs/introduction-knockoutjs.en.mp4?v=db3087c1f285 – Deutsch: https://slides.mikebild.dev/introduction-knockoutjs.html - [GraphQL from schema to production](https://slides.mikebild.dev/introduction-graphql.en.html): You build a GraphQL API with Apollo, from the first schema to a public graph that limits cost and can evolve safely. – Repository: https://github.com/MikeBild/introduction-graphql – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-graphql/introduction-graphql.en.pdf?v=a1a1bae43fe5 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-graphql/introduction-graphql.en.mp4?v=a1a1bae43fe5 – Deutsch: https://slides.mikebild.dev/introduction-graphql.html - [Reactive programming with RxJS](https://slides.mikebild.dev/introduction-reactive-programming.en.html): You describe search, live status, and user input as streams with RxJS and test time-dependent code without real waiting time. – Repository: https://github.com/MikeBild/Reactive-Programming – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-reactive-programming/introduction-reactive-programming.en.pdf?v=51202b99fbfc – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-reactive-programming/introduction-reactive-programming.en.mp4?v=51202b99fbfc – Deutsch: https://slides.mikebild.dev/introduction-reactive-programming.html - [Docker & Kubernetes](https://slides.mikebild.dev/introduction-docker-kubernetes.en.html): You put the workshop shop API into containers and run it in Kubernetes: from image and Compose to rollout, Gateway API, and hardening. – Repository: https://github.com/MikeBild/introduction-docker – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-docker-kubernetes/introduction-docker-kubernetes.en.pdf?v=dcfe9fd4c4f6 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-docker-kubernetes/introduction-docker-kubernetes.en.mp4?v=dcfe9fd4c4f6 – Deutsch: https://slides.mikebild.dev/introduction-docker-kubernetes.html - [AWS serverless with Lambda, CDK, and DynamoDB](https://slides.mikebild.dev/introduction-aws-serverless.en.html): You build the workshop shop order flow serverless on AWS, with Lambda, DynamoDB, events, and Step Functions, all as code in CDK. – Repository: https://github.com/MikeBild/introduction-aws – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-aws-serverless/introduction-aws-serverless.en.pdf?v=686d760b188f – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-aws-serverless/introduction-aws-serverless.en.mp4?v=686d760b188f – Deutsch: https://slides.mikebild.dev/introduction-aws-serverless.html - [Microservices with Node.js, Express 5, and Docker Compose](https://slides.mikebild.dev/introduction-microservices.en.html): You split the workshop shop into services along domain boundaries and connect them with contracts, events, outbox, and sagas. – Repository: https://github.com/MikeBild/introduction-microservices – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-microservices/introduction-microservices.en.pdf?v=755b9c76bf78 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-microservices/introduction-microservices.en.mp4?v=755b9c76bf78 – Deutsch: https://slides.mikebild.dev/introduction-microservices.html - [Design patterns as functions](https://slides.mikebild.dev/introduction-design-patterns.en.html): You solve recurring problems in the workshop shop with design patterns as functions and recognize them again in Express, React, and Apollo. – Repository: https://github.com/MikeBild/introduction-design-patterns – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-design-patterns/introduction-design-patterns.en.pdf?v=d9e4820e2aef – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-design-patterns/introduction-design-patterns.en.mp4?v=d9e4820e2aef – Deutsch: https://slides.mikebild.dev/introduction-design-patterns.html - [Architecture: DDD, CQRS, and Event Sourcing](https://slides.mikebild.dev/introduction-cqrs-event-sourcing.en.html): You model the workshop shop with DDD, separate writes and reads with CQRS, and store orders as events, only where it pays off. – Repository: https://github.com/MikeBild/introduction-nodejs/tree/master/EXAMPLES/ARCHITECTURE – PDF: https://media.mikebild.dev/site/mikebild/decks/introduction-cqrs-event-sourcing/introduction-cqrs-event-sourcing.en.pdf?v=d420df81ac12 – Video: https://media.mikebild.dev/site/mikebild/decks/introduction-cqrs-event-sourcing/introduction-cqrs-event-sourcing.en.mp4?v=d420df81ac12 – Deutsch: https://slides.mikebild.dev/introduction-cqrs-event-sourcing.html ## Blog - [Interim Review and System View: Taking Stock of the Series](https://www.mikebild.dev/en/blog/interim-review-and-system-view/): Months after the conversation where it all began, it’s time for an honest assessment: which expectations from the opening came true, which didn’t, what remains open – and why the most exciting question is no longer what the models can do, but what organizations make of it. - [MCP, HTTP, Webhooks and A2A Explained Simply](https://www.mikebild.dev/en/blog/mcp-http-webhooks-and-a2a-explained-simply/): MCP, HTTP with OpenAPI, webhooks and A2A connect systems at different levels. What matters is which responsibility lies at each boundary. - [A2A: When Agents Work Together](https://www.mikebild.dev/en/blog/a2a-when-agents-work-together/): Agent Card, Message, Task and Artifact explained clearly: how A2A 1.0 connects independent agent systems, what sets the protocol apart from MCP and when delegating to an independent system pays off. - [Hourly Is Not Real Time](https://www.mikebild.dev/en/blog/hourly-is-not-real-time/): A closed hourly report answers different questions than ongoing operational monitoring – and gets simpler as soon as time windows, delays and measurement gaps are modeled explicitly. - [Claims: Small, Sourced, Verifiable](https://www.mikebild.dev/en/blog/claims-small-sourced-verifiable/): Claims break wiki pages down into individual statements with subject, predicate, object, confidence, status and a verbatim quote as evidence. This makes agreement and disagreement precise. - [Products Report Through Their API](https://www.mikebild.dev/en/blog/products-report-through-their-api/): Product statistics stay understandable when every system aggregates its own data and offers it through a small HTTP contract with uniform time semantics. - [From Org Chart to Product Ownership](https://www.mikebild.dev/en/blog/from-org-chart-to-product-ownership/): AI makes the path from customer problem to impact more continuous. - [llms.txt: Docs for Machines](https://www.mikebild.dev/en/blog/llms-txt-docs-for-machines/): Context for models, not for ranking: why llms.txt and llms-full.txt help coding agents – and what an MCP server makes of them. - [Tools That Hold Up: Concepts, Methods, Processes](https://www.mikebild.dev/en/blog/tools-that-hold-up-concepts-methods-processes-article/): You cannot install an agent for your own domain – but you can very well learn the way there. Which concepts hold up, which methods keep the start small and which processes keep rules from going stale. - [AI Agents per Domain: Rules, Approvals and Evidence](https://www.mikebild.dev/en/blog/ai-agents-per-domain/): How an AI agent enforces domain rules across several tool calls: with case state, checked plans, approvals and traceable execution. - [MCP Security: Tools, Permissions and Approvals for AI Agents](https://www.mikebild.dev/en/blog/mcp-security-tools-permissions-and-approvals/): How to integrate MCP tools into applications safely: server-side permission checks, human approvals, protection against prompt injection and traceable calls. - [Agent, Model, Domain](https://www.mikebild.dev/en/blog/agent-model-domain/): The model is rented, the agent can be under your own control – what matters is whether the domain lives as prose in the prompt or as a checked interface in the agent. - [Knowledge That Survives the Session](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/): Session knowledge evaporates when no one curates it – why teams should treat their AI working knowledge like code, and why it’s not the model that gets smarter but the organization that learns. - [Clean Grounding II: Grounding Answers](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/): My working model for grounding distinguishes conventions, documents and API descriptions. What stays in the scarce context, I prioritize by task and by the cost of fetching it again. - [AI in the Enterprise: Faster Development Needs Different Processes](https://www.mikebild.dev/en/blog/ai-in-the-enterprise-faster-development-different-processes/): AI shortens research, design and implementation. If handoffs, ticket hierarchies and approvals stay the same, the bottleneck just moves – so large companies have to rethink workflow and governance together. - [Clean Grounding I: Why AI Guesses So Convincingly](https://www.mikebild.dev/en/blog/clean-grounding-i-why-ai-guesses-so-convincingly/): Why language models invent plausible things, why more training doesn’t reliably eliminate the problem and what grounding has to do with it. - [My Success Cannot Be Copied](https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/): A colleague takes over my AI setup and gets different results. Tools, tests and conventions can be transferred; how you cut tasks, how you review and the course of an individual session only to a limited degree. - [What I Am Critical Of](https://www.mikebild.dev/en/blog/what-i-am-critical-of/): Four observations and one open hypothesis after intense months with AI – from a possible loss of skills to the worry about more uniform solutions, and my practical countermeasures. - [Good Enough: The Model Is Rarely the Bottleneck](https://www.mikebild.dev/en/blog/good-enough-models/): For the everyday tasks I work on with AI myself, the choice of model is rarely the first bottleneck. How the task is cut, the context and the verification usually matter more. - [From Tool to Way of Working](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/): How a conversation in Berlin, after more than thirty years of software craftsmanship, got me working daily with Claude, ChatGPT and Claude Code – and why I still distrust my own enthusiasm for now. - [React Overview: From JSX to Component Architecture](https://www.mikebild.dev/en/blog/react-overview-from-jsx-to-component-architecture/): A complete walk through React the way I teach it today – from declarative rendering through the question of who owns a piece of state to the architecture of a growing application. The details of individual stops will follow later as separate posts. - [Forms in React 19: Actions, useActionState and useOptimistic](https://www.mikebild.dev/en/blog/forms-in-react-19-with-actions/): React 19 makes the form the actual interface: a function as the form action, plus three hooks for the result, the pending state and instant UI feedback. This post shows how they work together – and where optimistic rendering breaks down without a clean error path. - [React Server Components and Server Actions: The New Boundary](https://www.mikebild.dev/en/blog/react-server-components-and-server-actions/): Server Components run outside the client bundle and send their result to the browser instead of their code. Server Functions move writes to the server – both are implemented by a suitable framework or bundler. - [React Router Data Router: The URL as the Place for State](https://www.mikebild.dev/en/blog/react-router-data-router-the-url-as-state/): The data router in React Router makes the URL the point of coordination – a route loads its data via loader before rendering and writes via action, so loading logic disappears from the component body. - [React Transitions: Non-Urgent Updates with useTransition](https://www.mikebild.dev/en/blog/react-transitions-with-usetransition/): useTransition marks updates as non-urgent and keeps React responsive during expensive or suspending renders. Plus useDeferredValue as the tool for downstream renders. - [React Testing Without Theater](https://www.mikebild.dev/en/blog/react-testing-without-theater/): Tests tied to visible user behavior are less coupled to DOM structure, component boundaries and internal state. As a result, they survive certain refactorings without changes. - [Suspense and the use Hook: Rendering as If the Data Were Already There](https://www.mikebild.dev/en/blog/suspense-and-the-use-hook/): Instead of managing a loading state in every component, Suspense lets you describe in a single place in the tree what appears while waiting – and the use hook lets the component below render as if the data had long arrived. - [Client State vs. Server Cache: The Most Consequential Boundary in the Frontend](https://www.mikebild.dev/en/blog/client-state-vs-server-cache/): Server data is state, but not client-owned state. Why this distinction matters, when useEffect turns into a bad cache and what a server state library takes over. - [Testing Schedulers and Virtual Time](https://www.mikebild.dev/en/blog/testing-schedulers-and-virtual-time/): Injectable time makes time-dependent rules testable quickly and deterministically. Data, isolation and external systems remain unaffected by it. - [GraphQL Overview: From Schema to Federated API](https://www.mikebild.dev/en/blog/graphql-overview-from-schema-to-federated-api/): A walk through GraphQL – from the typed schema through queries and resolvers to real time, operations and federated architecture, assessed as of October 2024. - [HTTP/2 and Server-Sent Events in Node.js](https://www.mikebild.dev/en/blog/http2-and-server-sent-events-in-nodejs/): How HTTP/2 multiplexes many streams over one connection and why Server-Sent Events are often a simpler answer to live data than WebSocket – with a working SSE endpoint in Node and the usual pitfalls. - [Markdown Reports Instead of Dashboard Mandates](https://www.mikebild.dev/en/blog/markdown-reports-instead-of-dashboards/): Why a diffable Markdown report often does more for traceability, review and operations than a dashboard – and how I set that up architecturally. - [GraphQL Federation: One Schema from Many Subgraphs](https://www.mikebild.dev/en/blog/graphql-federation-and-subgraphs/): When one team can no longer carry a monolithic schema on its own, Federation splits the graph into subgraphs that a router composes into a supergraph. Using a users and orders example, this article shows how @key and __resolveReference hold entities together across subgraph boundaries. - [Fuzzy Matching with Explicit Limits](https://www.mikebild.dev/en/blog/fuzzy-matching-with-explicit-limits/): A fuzzy match is a claim with a confidence, not a fact – it only becomes useful through versioned thresholds, three decision zones, and a diffable report of the gray zone. - [Event Sourcing on AWS: DynamoDB Streams and Lambda](https://www.mikebild.dev/en/blog/event-sourcing-on-aws-dynamodb-streams-and-lambda/): Event Sourcing implemented serverless: DynamoDB as an append-only event store, DynamoDB Streams as the change feed and Lambda as an idempotent projector into CQRS read models. - [Testing RxJS with Marble Diagrams](https://www.mikebild.dev/en/blog/testing-rxjs-with-marble-diagrams/): Marble diagrams make the timing of asynchronous streams visible. With TestScheduler.run and virtual time, you test RxJS operators deterministically: no real waiting, no flakiness. - [Invoice Data as a Domain](https://www.mikebild.dev/en/blog/invoice-data-as-a-domain/): Why an invoice import isn’t a CSV job but a domain with its own terms, invariants and time rules – and how explicit types and a rejection report turn silent data errors into explainable data. - [Testing Node.js: The Test Pyramid with Mocha](https://www.mikebild.dev/en/blog/testing-nodejs-the-test-pyramid-with-mocha/): How to distribute a Node.js test suite sensibly across different test levels and how Mocha, node:assert, sinon and supertest work together along the way. - [Deterministic CLIs](https://www.mikebild.dev/en/blog/deterministic-clis/): Determinism is an architecture decision: same inputs, same report, reviewable via diff. It pays off wherever an artifact is checked repeatedly. - [Observability with OpenTelemetry: Logs, Traces and Metrics](https://www.mikebild.dev/en/blog/observability-with-opentelemetry/): Instrument logs, traces and metrics consistently with OpenTelemetry, connect them through trace IDs and export them via OTLP to suitable backends. - [The GraphQL Client: Apollo Link and Fragments](https://www.mikebild.dev/en/blog/graphql-client-apollo-link-and-fragments/): Apollo Link runs every GraphQL operation through a chain of middleware: authLink sets headers, errorLink handles errors in one place, split routes subscriptions. Plus fragments as reusable field sets and why interfaces need possibleTypes. - [OCR with a Cache and Distrust](https://www.mikebild.dev/en/blog/ocr-with-a-cache-and-distrust/): Why an OCR pipeline for receipt data only feels reliable once you secure every recognized value with a hash cache, a confidence gate and plausibility rules instead of believing it. - [The Four Subject Types in RxJS](https://www.mikebild.dev/en/blog/the-four-subject-types-in-rxjs/): Subject, BehaviorSubject, ReplaySubject and AsyncSubject differ in what late subscribers see and in how completion or an error ends their stored behavior. - [Apollo Client: The Normalized Cache and Optimistic Updates](https://www.mikebild.dev/en/blog/apollo-client-normalized-cache-and-optimistic-updates/): HTTP caching is possible with GraphQL too, but for client state it is often less direct. That is why Apollo normalizes objects and supports optimistic updates in the UI. - [Securing GraphQL: Query Depth, Complexity and Rate Limiting](https://www.mikebild.dev/en/blog/securing-graphql-depth-complexity-rate-limiting/): A single GraphQL endpoint accepts arbitrarily nested queries – convenient and at the same time a risk of abuse. I show how I build a layered defense against expensive queries with a depth limit, a complexity budget, pagination caps and rate limiting. - [TypeScript in Node.js: Setup, Types and Tests](https://www.mikebild.dev/en/blog/typescript-in-nodejs/): Setting up TypeScript in a Node project: understand the tsconfig essentials, type async code and handlers, and get the tests running, step by step from project practice. - [TypeScript in React: Typing Props, Hooks and Events](https://www.mikebild.dev/en/blog/typescript-in-react/): How props and state become verifiable contracts – and your editor reports errors before your users see them. From interface/type through useState generics and event types to useRef and utility types. - [Resilience Patterns: Timeout, Retry, Circuit Breaker, Idempotency](https://www.mikebild.dev/en/blog/resilience-patterns-timeout-retry-circuit-breaker/): Why resilience is no accident: timeout, retry with backoff and jitter, circuit breaker and idempotency as deliberately designed patterns against the failure modes of distributed systems. - [GraphQL Subscriptions over SSE: Real Time Without Being Forced into WebSocket](https://www.mikebild.dev/en/blog/graphql-subscriptions-over-sse/): Subscriptions don’t need a WebSocket. Server-Sent Events are enough for the one-way server-to-client channel, while queries and mutations stay plain HTTP, and the schema decides what counts as a domain event in the first place. - [Contract Testing Instead of an E2E Marathon](https://www.mikebild.dev/en/blog/contract-testing-instead-of-an-e2e-marathon/): Consumer-Driven Contracts check interfaces at the boundary between services instead of in an expensive, flaky end-to-end suite. The result: a faster, deterministic deploy gate and teams that release independently. - [Errors as Architecture in Node.js: Safety Nets Against the Crash](https://www.mikebild.dev/en/blog/errors-as-architecture-in-nodejs/): Error handling in Node.js is not try/catch cosmetics but a decision about levels, escalation and orderly termination. If you know the four error levels and take graceful shutdown seriously, you build services that die in a controlled way instead of running on in a corrupt state. - [DORA Metrics: What Really Shortens Development Cycles](https://www.mikebild.dev/en/blog/dora-metrics-what-really-shortens-cycles/): Lead time, deploy frequency, change fail rate, and recovery time are diagnostic values, not vanity velocity. They show where the cycle gets stuck – and why speed and stability don’t have to be opposites. - [child_process in Node.js: Scaling Without Illusions](https://www.mikebild.dev/en/blog/child-process-in-nodejs-scaling-without-illusions/): Node.js runs on a single event loop – CPU work blocks everything. This post shows when fork, cluster, and worker_threads really help and when they are just overhead. - [Understanding Lambda Performance and Cold Starts](https://www.mikebild.dev/en/blog/understanding-lambda-performance-and-cold-starts/): What a cold start in AWS Lambda really is, which levers you control – from bundle size through init code and memory to Provisioned Concurrency – and how to measure all of it properly. - [RxJS in Node.js: Processing Event Streams Reactively](https://www.mikebild.dev/en/blog/rxjs-in-nodejs-event-streams/): RxJS in Node.js: how fromEvent turns an EventEmitter into an observable, how operators transform server-side streams declaratively and why RxJS has no real backpressure. - [Evolutionary Architecture: Systems That Are Allowed to Change](https://www.mikebild.dev/en/blog/evolutionary-architecture-systems-allowed-to-change/): Architecture is not an end state that you lock down once. Small changes and suitable fitness functions make selected risks visible earlier, but they guarantee neither speed nor quality. - [From HOCs and Render Props to Custom Hooks](https://www.mikebild.dev/en/blog/from-hocs-and-render-props-to-custom-hooks/): How do I share logic between components without copy-paste? Custom hooks usually avoid nested wrappers for this; HOCs and render props keep a few specific composition tasks. - [Async Context in Node.js: AsyncLocalStorage, async_hooks and diagnostics_channel](https://www.mikebild.dev/en/blog/async-context-in-nodejs-with-asynclocalstorage/): How to carry request-scoped context such as request ID, user and trace through deep asynchronous call chains without threading it through every function signature – with AsyncLocalStorage, the underlying async_hooks and diagnostics_channel for decoupled tracing. - [GraphQL Auth: Identity in the Context, Authorization in the Domain Logic](https://www.mikebild.dev/en/blog/graphql-auth-identity-in-the-context/): The GraphQL context carries the identity of a request. Whether that identity may perform an operation is decided by a central policy in the domain logic. - [Debugging and Profiling Node.js Locally](https://www.mikebild.dev/en/blog/debugging-and-profiling-nodejs-locally/): From the console.log reflex to the built-in inspector: node --inspect, the debug module, nodemon and first CPU and memory profiles for local diagnosis. - [Developer Productivity: Shorter Cycles with High Quality](https://www.mikebild.dev/en/blog/developer-productivity-shorter-cycles/): Short feedback loops with reliable quality are my mental model for developer productivity. Where the waiting actually happens has to be shown by your own lead time. - [Slots, Context and Web Components in Svelte](https://www.mikebild.dev/en/blog/slots-context-and-web-components-in-svelte/): Three composition tools in Svelte 3: slots pass content in from the outside, the Context API avoids prop drilling, and custom elements make a component reusable independently of any framework. - [Build vs. Runtime in Web Projects](https://www.mikebild.dev/en/blog/build-vs-runtime-in-web-projects/): The rendering time is decided per route. Static, dynamic and incremental models can be combined according to data shelf life, cost and failure behavior. - [Streams in Object Mode: Data Pipelines Beyond Bytes](https://www.mikebild.dev/en/blog/streams-in-object-mode/): Node.js streams carry more than bytes: with objectMode:true they become composable data pipelines that parse, filter and aggregate – including the bridge to async iterators. - [Reproducible Test Pipelines: No Flakiness, No Chance](https://www.mikebild.dev/en/blog/reproducible-test-pipelines/): Flakiness points to uncontrolled inputs or dependencies. If you make time, data and isolation visible, you can narrow down the cause and make the merge gate trustworthy again. - [Adapter Design: Where Frameworks End](https://www.mikebild.dev/en/blog/adapter-design-where-frameworks-end/): What a framework adapter really does: the contract over the build output, the translation of request and response, and the silent environment assumptions at the boundary between SvelteKit and AWS. - [RxJS in React: Observables in the UI Data Flow](https://www.mikebild.dev/en/blog/rxjs-in-react-observables-in-the-ui-data-flow/): RxJS does not shine everywhere in React, only where asynchronous events have to be coordinated – debounced input, canceled autocomplete requests, continuous streams. The post shows the few places where observables really pay off, and where useState is perfectly enough. - [Motion, Transitions and Animations in Svelte](https://www.mikebild.dev/en/blog/motion-transitions-and-animations-in-svelte/): How Svelte ships motion declaratively and without an extra library: transition directives for fading in and out, svelte/motion for smoothly interpolated values and animate:flip for reordering lists. - [Buffers in Node.js: Working with Binary Data](https://www.mikebild.dev/en/blog/buffers-in-nodejs-working-with-binary-data/): Why JS strings don’t work for raw bytes and Buffer is Node’s tool for them: alloc versus allocUnsafe, reading and writing encodings cleanly, and the memory trap behind slice and subarray. - [Svelte Stores: State Outside the Component](https://www.mikebild.dev/en/blog/svelte-stores-state-outside-the-component/): Svelte stores are a minimal model for state that doesn’t fit into a single component: writable, readable, derived – plus the $ shorthand that subscribes and cleans up on unmount. - [Node.js Streams: Understanding and Using Backpressure](https://www.mikebild.dev/en/blog/nodejs-streams-understanding-backpressure/): Why a fast producer must not overrun a slow consumer – and how pipe, pipeline, the return value of write() and the drain event handle flow control in Node.js. - [Fitness Functions: Checking Selected Architecture Properties](https://www.mikebild.dev/en/blog/fitness-functions-checking-architecture-properties/): Fitness functions make selected properties such as coupling, dependencies and latency continuously checkable. They don’t replace domain quality or architectural trade-offs. - [Svelte Reactivity: The Compiler Instead of a Virtual DOM](https://www.mikebild.dev/en/blog/svelte-reactivity-the-compiler-instead-of-a-virtual-dom/): Svelte compiles components at build time into targeted DOM code instead of diffing a virtual DOM at runtime. I show the mental model, reactive assignment with $: and the classic push trap that I keep running into in projects. - [EventEmitter: The Event Model at the Core of Node.js](https://www.mikebild.dev/en/blog/eventemitter-the-event-model-at-the-core-of-nodejs/): EventEmitter is the common denominator beneath streams, HTTP servers and processes: I show on/once/off/emit, the special behavior of 'error' and how to avoid listener leaks. - [GraphQL Pagination: Cursors, Connections and the Relay Pattern](https://www.mikebild.dev/en/blog/graphql-pagination-cursors-and-connections/): Why offset/limit produces duplicates and gaps in changing lists, and how cursor-based pagination with the connections pattern stays stable – including the schema, a resolver sketch and the pitfalls from real projects. - [SvelteKit Adapter AWS: Framework Meets Cloud](https://www.mikebild.dev/en/blog/sveltekit-adapter-aws-framework-meets-cloud/): Why I built my own SvelteKit adapter for AWS and what the translation between the framework build and Lambda, S3 and CloudFront reveals about both sides. - [Preview Environments per Pull Request](https://www.mikebild.dev/en/blog/preview-environments-per-pull-request/): Ephemeral environments per pull request shorten feedback and make reviews concrete: you click through the change instead of imagining it from the diff. - [Jamstack as an Architecture Style for Web Applications](https://www.mikebild.dev/en/blog/jamstack-as-an-architecture-style/): Jamstack describes an architecture style with a pre-rendered frontend and decoupled services. This post puts the original building blocks JavaScript, APIs and Markup into context as of 2021. - [Serverless Transactional Email: SES and Lambda](https://www.mikebild.dev/en/blog/serverless-transactional-email-with-ses-and-lambda/): How SES becomes an event-driven email building block: outgoing confirmation emails from a Lambda Function and incoming Receipt Rules that turn an email into a handler call. - [State Management in React: Redux Toolkit, Lightweight Stores, MobX](https://www.mikebild.dev/en/blog/state-management-in-react/): When state is truly app-wide, the tool question comes up – Redux Toolkit, a lightweight store such as Zustand or Jotai, or the reactive model of MobX. But why this choice only comes after the counter-check, and usually turns out smaller than expected. - [DynamoDB Data Modeling: Single-Table Design](https://www.mikebild.dev/en/blog/dynamodb-data-modeling-single-table-design/): DynamoDB rewards a different way of thinking than a relational database: not starting from the data model but from the access patterns. Single-table design combines several entity types in one table through composite keys. - [CDN Construct: A Small Infrastructure API](https://www.mikebild.dev/en/blog/cdn-construct-a-small-infrastructure-api/): Why a custom CDK construct for static websites is more than saved lines: an opinionated interface over S3, CloudFront, certificates and DNS. - [Outcome Before Output: Why Velocity Is the Wrong Number](https://www.mikebild.dev/en/blog/outcome-before-output/): Completed tickets are output, but not yet evidence of impact. Why velocity misleads in management reporting and how to align teams with outcomes instead. - [Data Analysis with NumPy, Pandas, and Matplotlib](https://www.mikebild.dev/en/blog/data-analysis-with-numpy-pandas-and-matplotlib/): From raw data to insight: how NumPy, pandas, and Matplotlib work together – vectorized computation, groupby aggregation, and a quick plot in a small pipeline. - [When CQRS and Event Sourcing Are Too Much](https://www.mikebild.dev/en/blog/when-cqrs-and-event-sourcing-are-too-much/): For most systems, CRUD is enough. CQRS and Event Sourcing only pay off under clear conditions – this article offers an honest decision guide instead of patterns for their own sake. - [GraphQL Concepts: Schema, Resolvers, Execution](https://www.mikebild.dev/en/blog/graphql-concepts-schema-resolvers-execution/): The ideas behind GraphQL that last, no matter which server is in fashion right now – the schema as a typed contract, the query as a shape, the resolver model and the order of execution. A conceptual deep dive with diagrams. - [GraphQL APIs with AppSync and DynamoDB](https://www.mikebild.dev/en/blog/graphql-apis-with-appsync-and-dynamodb/): AWS AppSync moves the GraphQL server out of your own operational responsibility and into a managed service. Using a DynamoDB backend, I show when this build-vs-buy decision holds up and when managed becomes a dead end, including the VTL mapping templates that are the price for it in 2021. - [Using Context Well: A Distribution Path, Not Secret Global State](https://www.mikebild.dev/en/blog/using-react-context-well/): Context solves distributing data through the tree – but not the question of who owns the state. If you confuse the two, you build a global store through the back door and cause unnecessary renders when provider values change carelessly. - [Reading Data in Python: CSV, JSON, Excel and Databases](https://www.mikebild.dev/en/blog/reading-data-in-python/): A toolkit for every data source: when the standard library is enough, when pandas pays off, and how to keep encoding, memory and SQL injection from becoming your downfall. - [Architecture Decision Records: Decisions You Will Still Understand in Two Years](https://www.mikebild.dev/en/blog/adrs-decisions-you-still-understand/): Why did we choose PostgreSQL back then and decide against the message bus? ADRs make the why durable as a versioned Markdown artifact – instead of letting it seep away in hallway talk. - [A GraphQL Schema That Grows: Evolution Without Breakage](https://www.mikebild.dev/en/blog/a-graphql-schema-that-grows/): How to evolve a GraphQL schema additively instead of versioning it – safe changes, real breaking changes, @deprecated as a tool and a field migration step by step. - [Serverless Workflows with AWS Step Functions](https://www.mikebild.dev/en/blog/serverless-workflows-with-aws-step-functions/): Step Functions turn nested Lambda handlers into a declarative state machine: a visible flow, explicit retry and catch paths, Standard or Express. - [Event Sourcing: The Event Store as a Logbook](https://www.mikebild.dev/en/blog/event-sourcing-the-event-store-as-a-logbook/): Event Sourcing doesn’t store the current state but the sequence of events as the source of truth: the event store as a logbook, the state as the result of a fold. Benefits, honest costs and how it differs from CQRS. - [Testing Flask Apps: The Test Client and Reliable Endpoints](https://www.mikebild.dev/en/blog/testing-flask-apps/): How I test Flask endpoints: with app.test_client() without a running server, pytest fixtures and verified JSON responses. - [Preserving and Resetting State: React and the Position in the Tree](https://www.mikebild.dev/en/blog/preserving-and-resetting-state-in-react/): React does not store state in the component but at its position in the render tree – once you understand that, you control preservation and reset on purpose instead of by accident. - [Serverless Auth with Cognito User Pools](https://www.mikebild.dev/en/blog/serverless-auth-with-cognito-user-pools/): Cognito User Pools as a managed identity backend: sign-up, confirm and sign-in without your own auth server, the three tokens properly understood, and an API Gateway endpoint secured by a Cognito authorizer. - [Trunk-Based Development Instead of a Branch Graveyard](https://www.mikebild.dev/en/blog/trunk-based-development-instead-of-a-branch-graveyard/): Short integration cycles with feature flags beat long-lived branches: daily integration without merge hell and a release that becomes a decision instead of a deploy event. - [How React Renders and Updates the Tree](https://www.mikebild.dev/en/blog/how-react-renders-and-updates-the-tree/): From the JSX element to the visible pixel – what exactly happens between a state change and the redrawn screen. Render and commit as separate phases, the comparison of two trees and why React almost always touches only a tiny part of the DOM. - [Team Automation with GitHub Actions](https://www.mikebild.dev/en/blog/team-automation-with-github-actions/): Why I run selected, recurring checks as workflows – and how you can tell whether the automation actually takes load off the team. - [Web APIs with Flask: From the App to a JSON API](https://www.mikebild.dev/en/blog/web-apis-with-flask/): From Hello World to a JSON API: how routing, request handling and jsonify work together in Flask 1.1 – and why SSR and APIs are the same mechanism. - [Read Models from Events: Projections Instead of Accidental Caches](https://www.mikebild.dev/en/blog/read-models-from-events-projections/): A read model built from events is a deliberately maintained projection for concrete queries. Origin and rebuild set it apart from an accidentally grown cache, even if the technical view can look cache-like. - [Cloud Guardrails Instead of Cloud Gatekeeping](https://www.mikebild.dev/en/blog/cloud-guardrails/): Why central approval processes in the cloud breed shadow infrastructure and how technically enforced guardrails – SCPs, Permission Boundaries, Config Rules, budgets – give teams their freedom of movement back. - [CDK Constructs: Abstraction with Liability](https://www.mikebild.dev/en/blog/cdk-constructs-abstraction-with-liability/): If you publish a CDK construct, you’re not shipping a helper function but operational decisions – about defaults, upgrade paths and what ends up in the consumer’s CloudFormation template. - [Bounded Contexts Before the Service Split](https://www.mikebild.dev/en/blog/bounded-contexts-before-the-service-split/): Before I split services, I clarify domain boundaries. A bounded context is a language boundary and a possible, but not mandatory, service split. - [Functional Patterns in Python: Comprehensions, itertools and functools](https://www.mikebild.dev/en/blog/functional-patterns-in-python/): Comprehensions, functools and itertools working together: how I show in projects when a comprehension is a better choice than map/filter, where lru_cache and groupby shine, and which pitfalls are waiting. - [JSX Precisely: The Rules Behind the Markup](https://www.mikebild.dev/en/blog/jsx-precisely-the-rules-behind-the-markup/): A precise look at JSX – what the compiler turns it into, why curly braces hold expressions rather than statements, how attributes, children, conditions and lists work, and where beginners stumble. - [AWS Deployment Pipelines Are Architecture](https://www.mikebild.dev/en/blog/aws-deployment-pipelines-are-architecture/): Deployment pipelines are architecture because they determine how often, how safely and how reversibly a system is changed. - [Advanced Python: Decorators, Magic Methods and Generators](https://www.mikebild.dev/en/blog/advanced-python-decorators-magic-methods-generators/): Three building blocks that make code Pythonic: decorators wrap functions, magic methods bind your own objects to Python’s protocols, generators produce lazy sequences. - [Policy as Code for CDK](https://www.mikebild.dev/en/blog/policy-as-code-for-cdk/): Policy as code makes a checkable part of your architecture rules executable and versionable. - [The Aggregate as a Consistency Boundary](https://www.mikebild.dev/en/blog/the-aggregate-as-a-consistency-boundary/): An aggregate is neither an ORM entity nor a table but a consistency and transaction boundary: a cluster of objects that an Aggregate Root protects as a unit. Why a transaction changes exactly one aggregate and other aggregates are referenced only by ID. - [`ssmenv-cli`: Small CLIs for Big Order](https://www.mikebild.dev/en/blog/ssmenv-cli-small-clis/): A small CLI on top of AWS SSM shows how configuration gets from a named, access-controlled source into local processes and CI – including questions of versions and failures. - [GitHub Actions with AWS CDK](https://www.mikebild.dev/en/blog/github-actions-with-aws-cdk/): GitHub Actions and AWS CDK connect code changes, infrastructure and deployment into a reviewable pipeline – and make the architecture decision visible in the pull request. - [PouchDB and Offline-First](https://www.mikebild.dev/en/blog/pouchdb-and-offline-first/): If you allow writes while offline, you move from request/response to replication – and the revision tree of PouchDB and CouchDB turns conflicts into a job for the domain model. - [Cleanly Separating Commands, Events and Queries](https://www.mikebild.dev/en/blog/separating-commands-events-and-queries/): Command, event and query are three kinds of messages with clear semantics: a request that can be rejected, a fact that has happened and a query without side effects. If you name and separate them cleanly, you gain clarity in the model – without a big CQRS setup. - [Infrastructure as Code Needs Code Reviews](https://www.mikebild.dev/en/blog/infrastructure-as-code-needs-code-reviews/): Once infrastructure is code, a small diff decides about security, cost and the risk of outages – that is why it belongs in the same review process as application code. - [Secrets in the Build Are Product Decisions](https://www.mikebild.dev/en/blog/secrets-in-the-build-are-product-decisions/): Secrets in the build are a trust problem: who may see, store and deploy what, and when? - [Product Discovery Before the First Line of Code](https://www.mikebild.dev/en/blog/product-discovery-before-the-first-line-of-code/): Discovery lowers the risk of efficiently building the wrong thing. I show a continuous track that tests assumptions before they tie up expensive delivery – not a phase before development. - [CQRS Is a Domain Boundary, Not a Framework](https://www.mikebild.dev/en/blog/cqrs-is-a-domain-boundary-not-a-framework/): CQRS separates the model for writing from the model for reading – a domain decision, not an installable framework. When the boundary pays off, how to start small and which mix-ups get expensive. - [Node.js Training: From the Event Loop to Architecture Decisions](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/): You can’t explain Node.js through a framework. You explain it through the event loop, through streams and through the question of which architecture decision a team will still understand tomorrow – and that is exactly what I practice with participants in the introduction-nodejs repo. - [CDK Early Days: Infrastructure in a Programming Language](https://www.mikebild.dev/en/blog/cdk-early-days-infrastructure-in-a-programming-language/): With the CDK, infrastructure moves into the same toolchain as application code, which means tests, reviews, and logical identities suddenly decide whether production data survives. - [AWS Parameter Store in the Build](https://www.mikebild.dev/en/blog/aws-parameter-store-in-the-build/): Parameter Store in the build makes configuration explicit, but it raises hard questions about secrets and reproducibility. - [Running Your Own Docker Registry](https://www.mikebild.dev/en/blog/running-your-own-docker-registry/): How I set up a private Docker registry with registry:2 in projects: tagging, pushing and pulling images, then securing it with htpasswd and TLS. - [Kubernetes Basics Under Deployment Pressure](https://www.mikebild.dev/en/blog/kubernetes-basics-under-deployment-pressure/): Under the pressure of a real deployment, the Kubernetes concepts sort themselves by importance – from the pod through deployment and service to the ingress. - [Central Logging with the ELK Stack in Docker](https://www.mikebild.dev/en/blog/central-logging-with-the-elk-stack-in-docker/): Container logs are scattered across many containers and they are ephemeral. This article shows how an ELK stack of Elasticsearch, Logstash and Kibana in a Compose setup centralizes logs, indexes them and makes them searchable. - [Micro-Frontends: Team Boundaries in the Browser](https://www.mikebild.dev/en/blog/micro-frontends-team-boundaries-in-the-browser/): Why the real work in micro-frontends is not the integration technique but the team split – shown with a runnable example landscape of a gateway, four applications and a component library. - [Frontend Interfaces Are APIs](https://www.mikebild.dev/en/blog/frontend-interfaces-are-apis/): Why props, URLs, events, CSS classes and localStorage deserve the same versioning discipline as a REST endpoint – at the latest when several teams work in the same browser. - [Node.js and Redis with Docker Compose](https://www.mikebild.dev/en/blog/nodejs-and-redis-with-docker-compose/): How I describe a two-container app of Node.js and Redis with Docker Compose in projects: one YAML file for the whole stack, service discovery via the service name, persistence through a volume – and why depends_on doesn’t wait for readiness. - [Containerization and False Security](https://www.mikebild.dev/en/blog/containerization-and-false-security/): Why “runs in a container” means neither isolation nor reproducibility nor well-run operations – and which steps actually close the three gaps. - [My Working Definition of an MVP: Learning Instead of Shipping Half-Finished](https://www.mikebild.dev/en/blog/my-working-definition-of-an-mvp/): I use MVP for an experiment that honestly tests a risky assumption. This working definition keeps a merely reduced feature set from counting as learning. - [A GraphQL Schema in the Domain Language](https://www.mikebild.dev/en/blog/a-graphql-schema-in-the-domain-language/): A GraphQL schema is the best place there has ever been for the ubiquitous language of a domain – and if the domain is German, it may stay German there, too. - [Angular, React and the Value of Transitions](https://www.mikebild.dev/en/blog/angular-react-and-the-value-of-transitions/): Whether a framework switch becomes a move or a rebuild depends on how cheaply two worlds can run side by side for months. - [Prototypes: The Object Model Behind JavaScript Classes](https://www.mikebild.dev/en/blog/prototypes-the-object-model-behind-javascript-classes/): class in ES2015 is essentially syntactic sugar over prototypes: if you understand the [[Prototype]] chain, Object.create, and the new sequence, you debug this errors and shared methods with more confidence. - [Redux as a Protocol for UI Changes](https://www.mikebild.dev/en/blog/redux-as-a-protocol-for-ui-changes/): The store is the most boring part of Redux – the value lies in the message protocol of named, serializable actions that makes UI changes traceable, testable and open to discussion. - [JavaScript Patterns That Stayed: Modules, Higher-Order Functions, Currying](https://www.mikebild.dev/en/blog/javascript-patterns-that-stayed/): Three JavaScript patterns have survived every framework change: the module pattern for clean encapsulation, higher-order functions for functions as values and currying for specialized variants. Why they form the foundation of modern utility libraries. - [WebSockets Are Not Always the Answer](https://www.mikebild.dev/en/blog/websockets-are-not-always-the-answer/): Why Server-Sent Events are the simpler choice for most real-time requirements and when the price of a real WebSocket connection actually pays off. - [KnockoutJS: Fine-Grained Reactivity with Observables and Computed](https://www.mikebild.dev/en/blog/knockoutjs-fine-grained-reactivity-with-observables/): How KnockoutJS solves reactivity: observables as get/set functions, computed with automatic dependency tracking and targeted DOM updates instead of a global tree comparison. - [PWA Weather: Offline Is a Feature](https://www.mikebild.dev/en/blog/pwa-weather-offline-is-a-feature/): A small weather app built as a Progressive Web App shows why offline behavior is a product decision and how honestly a UI should deal with outdated data. - [Tic-Tac-Toe with Minimax in React](https://www.mikebild.dev/en/blog/tic-tac-toe-with-minimax-in-react/): An unbeatable tic-tac-toe opponent in React shows why game logic as a pure function must know nothing about rendering – and why immutable moves fit React’s model. - [Simple Design Can Save Process](https://www.mikebild.dev/en/blog/simple-design-can-save-process/): In many projects, process overhead compensates for a design that is too large or too speculative. Cutting smaller can save coordination; external requirements and real dependencies remain. - [HTML5, CSS3 and ECMAScript as a Baseline](https://www.mikebild.dev/en/blog/html5-css3-and-ecmascript-as-a-baseline/): In the spring of 2017, CSS Grid, Flexbox, fetch and native ES2015 carry so far that the first architecture question in the frontend deserves to be asked again: How far do I get without a framework? - [RxJS: Finally Telling Push and Pull Apart](https://www.mikebild.dev/en/blog/rxjs-telling-push-and-pull-apart/): Once you name the producer and the consumer, you see right away whether data is pulled or pushed, and you choose between function, iterator, Promise and Observable without guessing. - [Node.js: Async I/O Explains Architecture](https://www.mikebild.dev/en/blog/nodejs-async-io-explains-architecture/): The calculation “one thread times 200 connections” shows which systems fit Node.js and which work belongs in separate processes. - [Babel Node Express: Modern Syntax, Old HTTP](https://www.mikebild.dev/en/blog/babel-node-express-modern-syntax-old-http/): Babel translates syntax, not an execution model – once you keep the two apart, you know why babel-node belongs in the development loop and not in production. - [API Thinking Before Framework Thinking](https://www.mikebild.dev/en/blog/api-thinking-before-framework-thinking/): If you define operations, data and failure cases before choosing a framework, you can swap the frontend almost at will later – the other way around, you get an API that mimics a framework. - [Tyrian Rx React: UI as Data Flow](https://www.mikebild.dev/en/blog/tyrian-rx-react-ui-as-data-flow/): A rebuild of the Elm Architecture with RxJS and React – actions as a stream, scan() folds the model, side effects stay at the edge – and what this proof of concept reveals about UI architecture that ages well. - [GraphQL-Pouch: Local Data with a Schema](https://www.mikebild.dev/en/blog/graphql-pouch-local-data-with-a-schema/): An open-source experiment from the summer of 2016: a GraphQL runtime that generates a complete CRUD API on top of PouchDB from a schema shorthand – including synchronization via the CouchDB replication protocol. - [Definition of Done as a Quality Gate, Not Bureaucracy](https://www.mikebild.dev/en/blog/definition-of-done-as-a-quality-gate/): The automatable core of a Definition of Done belongs in a green gate of lint, build and test. Business acceptance and other judgments remain shared quality work. - [React: Components as Interfaces](https://www.mikebild.dev/en/blog/react-components-as-interfaces/): Why props are the public contract of a React component – and what changes when you design them like an API instead of a parameter list. - [GraphQL as a Question to the System](https://www.mikebild.dev/en/blog/graphql-as-a-question-to-the-system/): Half a year after the specification, this post sorts out what is really new about GraphQL – and which questions nobody had answered yet in early 2016. - [Build Scripts as Product Code](https://www.mikebild.dev/en/blog/build-scripts-as-product-code/): Build scripts deserve the care of product code, because they determine how reproducible a system actually is. - [ES6 Memory: Understanding UI State](https://www.mikebild.dev/en/blog/es6-memory-understanding-ui-state/): A memory game in fresh ES2015, built without a framework, makes visible which states a UI really has, where they should live and who may change them. - [Web Messaging with RxJS](https://www.mikebild.dev/en/blog/web-messaging-with-rxjs/): If you hide incoming messages behind an observable, the transport between browser and server becomes interchangeable – and you notice along the way how far plain HTTP gets you. - [Functional Styles in Everyday Code](https://www.mikebild.dev/en/blog/functional-styles-in-everyday-code/): Why functional style in everyday team work in 2015 does not mean Haskell, but the discipline of separating pure functions from I/O – and how ES2015 finally makes that convenient. - [Containers Are Not Architecture](https://www.mikebild.dev/en/blog/containers-are-not-architecture/): Docker makes system boundaries visible and portable – you still have to draw them by hand, and a monolith remains a monolith inside a container. - [Programming Styles as an Architecture Comparison](https://www.mikebild.dev/en/blog/programming-styles-as-an-architecture-comparison/): The same small task solved in dozens of programming styles is the most compact architecture comparison I know – because every style is a deliberately chosen set of constraints. - [Docker for .NET, Before It Was Normal](https://www.mikebild.dev/en/blog/docker-for-dotnet-before-it-was-normal/): Packing a small Nancy API under Mono into a Docker container was a detour via Linux in the spring of 2015 – and it taught me more about .NET deployment than any IIS manual. - [Tests Before There Is a Product](https://www.mikebild.dev/en/blog/tests-before-there-is-a-product/): Early tests help you grasp a problem, even if the code is later replaced entirely. - [Flood-It: A Game as an Architecture Lens](https://www.mikebild.dev/en/blog/flood-it-a-game-as-an-architecture-lens/): A board of numbers, a move as a pure function and a greedy solver show on a small scale what gets blurry in large systems: the separation of core logic, strategy and presentation. - [MathParser: Parsers as a Thinking Tool](https://www.mikebild.dev/en/blog/mathparser-parsers-as-a-thinking-tool/): A look back at a parser demo of my own from 2010 shows why a handwritten expression parser teaches more about layers, structure and the boundary between syntax and semantics in a few lines than many a large project. - [State Mutation on Streams](https://www.mikebild.dev/en/blog/state-mutation-on-streams/): If you compute state as a fold over a stream of events instead of changing it directly, you get undo, replay and traceability almost for free. - [HTTP APIs: Small, Stable, Readable](https://www.mikebild.dev/en/blog/http-apis-small-stable-readable/): What the Heroku HTTP API Design Guide is worth when you hold it up against your own APIs – and why a few resources, a versioning promise and self-explanatory errors achieve more than any framework. - [What I Was Looking for in Elixir](https://www.mikebild.dev/en/blog/what-i-was-looking-for-in-elixir/): It wasn’t the syntax that brought me to Elixir but the execution model of the Erlang VM – processes, messages and supervisors, seen through JavaScript and C# eyes. - [Control Flow Before `async/await`](https://www.mikebild.dev/en/blog/control-flow-before-async-await/): A look at the tiny library cflow shows how Node developers wired asynchronous steps into a chain by hand, and why the missing error channel is the real lesson. - [Why Katas Are More Than Finger Exercises](https://www.mikebild.dev/en/blog/why-katas-are-more-than-finger-exercises/): A kata is an architecture lab in miniature – because the task stays constant, it reveals what otherwise only the design knows. --- # Interim Review and System View: Taking Stock of the Series URL: https://www.mikebild.dev/en/blog/interim-review-and-system-view/ Date: 2026-08-17 The conversation with which [this series began](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/) took place in October of last year; this text takes stock as of August 2026. The opening ended with a resolution: to distrust my own enthusiasm for the time being, look closely and measure every result against more than thirty years of craft. The [last installment](https://www.mikebild.dev/en/blog/tools-that-hold-up-concepts-methods-processes-article/) announced that it would take this resolution at its word. So: which of the expectations came true, which didn’t, what remains open – and what system view has emerged from the individual sessions of the beginning? *Part 13 of the series “From Session to System” – [the opening post is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).* ## The enthusiasm survived the test – barely The most important thing first, because everything else builds on it: the few days of trial in October have become everyday work, and that is the least spectacular evidence I can offer. I no longer think about these tools, any more than I think about the editor or version control. They are infrastructure. A flash in the pan looks different – you recognize one by the fact that after three months you’re telling stories about it again instead of working with it. Still, it would be too cheap to simply declare my own perception to be the assessment. In July 2025, the American research institute METR – a nonprofit that measures the capabilities of AI systems with controlled experiments – published a study that has occupied me more than any benchmark: experienced open-source developers were measurably slower with AI support on randomized tasks – by roughly a fifth – and yet afterwards estimated that they had been considerably faster. So exactly the perception I have relied on since the opening can be systematically deceptive. I take that seriously, because it is the same warning I gave myself in the opening: fresh enthusiasm is a poor witness. That’s why I check against things that can’t be talked up. What is actually done in the evening? Which of the stalled projects are in operation today? How often did I find errors in reviews that would have slipped through without the shift toward checking? By this standard, the assessment is positive – as an observation, not a measurement; I lack reliable numbers on it. That is exactly why the study remains important for my assessment: as long as I don’t measure with comparable rigor, I have to factor in that my perception may deceive me too. The study does, however, measure tasks that were familiar to the developers, in code they knew well. My biggest gain lies elsewhere – in the projects that would never have been started at all without these tools. That doesn’t refute the study; it’s a different calculation. Both can be true at the same time. ## What came true The opening recorded three observations. All three have survived the months since the opening, but none has stayed the way it was. The first – generating gets cheap, checking becomes the bottleneck – has turned out to be the load-bearing observation of the entire series. In hindsight, almost every installment is an answer to this one shift: the harness organizes checking around the model, the [house rules](https://www.mikebild.dev/en/blog/what-i-am-critical-of/) defend it against my own convenience, [grounding](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/) anchors it in real sources, and [rules in the path](https://www.mikebild.dev/en/blog/ai-agents-per-domain/) make it independent of the checker’s form on the day. What I didn’t see yet in November: the bottleneck keeps moving. First checking was scarce, then cleanly writing down what is supposed to apply – by now it is deciding what gets built at all. The second observation – the drawers open up again – came true, with a limitation I didn’t see coming back then. Some of what had been lying around for years is in operation today: smaller than the original idea, and that is not a defeat but a finding. Because what the tools don’t deliver is a judgment on which of the old ideas were worth it. I shut down two projects again after a few weeks – failed faster than would have been possible before, and that is exactly the underestimated gain: cheap implementation makes discarding cheap too. The third observation – the tone is always right, even when the content isn’t – was a gut feeling in November. It has since become [a structural explanation](https://www.mikebild.dev/en/blog/clean-grounding-i-why-ai-guesses-so-convincingly/) and then a procedure. The distrust has stayed, but it has moved: from my private vigilance into check steps that don’t depend on whether I’m having a good day. That is perhaps the most compact summary of what these months have done to my way of working – diligence went from being a virtue to being a property of the setup. ## What I expected wrongly An assessment that only lists hits is advertising. Two expectations didn’t hold. The most expensive misjudgment: that writing things down is enough. For months I put work into ever better instruction files before I honestly drew up the chronicle of these attempts – written rules remain recommendations, no matter how well they are phrased. From this disillusionment came the most important insight of the series: rules that are supposed to apply need a path that enforces them – check before effect, approvals, evidence. If I could take a single sentence away from these months, it would be this one. The second misjudgment is more pleasant: I had expected the choice of model to become more important over time – that at some point one model would pull ahead and the question “which one?” would turn into a strategic question after all. The opposite happened. For my tasks, several model changes since the opening felt like quality improvements, and with every jump the choice became [less important, not more](https://www.mikebild.dev/en/blog/good-enough-models/). My way of working hardly noticed the changes. What does make itself felt every time, on the other hand: a badly cut task, a missing piece of context, a rule that only exists in prose. My own share dominates the result – that was there early as a thesis, and by now it concretely decides whether a run holds up: in how the task is cut, in the context provided and in the rules enforced in the path. ## What remains open Three questions remain unanswered in this interim review. The junior question. The opening contained a suspicion: the lever works because three decades of judgment stand behind it – and whether it works the same way for someone without that foundation, I didn’t know. I still don’t know today, and the [critical installment](https://www.mikebild.dev/en/blog/what-i-am-critical-of/) sharpened the suspicion rather than dispelled it: if you get working code before the pain sets in from which understanding arises, you may never build up the substance that checking draws on. A suspicion is still not knowledge. But it is the question I consider more important than any model question. Homogenization. That teams asking the same model build more similar solutions is something I have recognized several times since that one observation in February, but never measured. It remains a concern without evidence, and I deliberately leave it at that instead of inflating it into a thesis. Unlearning my own craft. The house rules from February hold up about as well as New Year’s resolutions: better than nothing, worse than claimed. The deliberate run without AI does happen, but less often than I had planned. The pull of the convenient option is real, every day. Exactly this experience made me skeptical, for the second half of the series, of everything that relies on discipline – and receptive to everything that moves diligence into the setup. ## The arc, in hindsight The triad of I, We, System was already there as an intention in the opening. What I hadn’t planned is the mechanism that emerged while writing: each level inherits the unsolved problem of the previous one. The discipline of the individual [doesn’t scale to the team](https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/), so the team writes down its rules; written rules bind nobody, so you need knowledge with owners and [a place that survives the session](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/); curated knowledge doesn’t yet answer the question of what is binding, so the hard rules move [into the path of a dedicated agent](https://www.mikebild.dev/en/blog/ai-agents-per-domain/); and so that this doesn’t remain a drawing-board design, you need [concepts, methods and processes](https://www.mikebild.dev/en/blog/tools-that-hold-up-concepts-methods-processes-article/) that keep the beginning small. ```mermaid flowchart LR subgraph AKT1["Act 1 · I"] S["Session
generating gets cheap"] --> P["Way of working
checking becomes the bottleneck"] end subgraph AKT2["Act 2 · We"] P --> V["Team variance
discipline doesn’t scale"] --> D["Instruction files
recommendation instead of rule"] end subgraph AKT3["Act 3 · System"] D --> W["Curated knowledge
with owners"] --> R["Rules in the path
agent per domain"] --> B["System architecture
UI, contracts, approvals"] end ``` The sentence that holds this arc together came up in the installment on curated knowledge: it’s not the model that gets smarter – the organization curates its knowledge. ## Today’s system view At the center is the property this series has been about from the start: the separation of proposal and effect, built as a dedicated approval boundary, not as a blanket switch. A workflow engine can hold back external writes until confirmation. A publishing system can tie the promotion of a preview to a human. A knowledge system can leave changes standing as a proposal until a human decides. An order control system can tie execution to approved orders. The same principle, cut differently each time – because the question of what “taking effect” means has to be answered differently in every domain. Published content takes effect differently from an approved knowledge revision, and both differently from a workflow that writes into a third-party system. With that, the question the opening asked has shifted too. It was: what can the models do? It is now: what does an organization make of it? Access to an external model API is not the part of this architecture that the organization permanently controls itself. A UI backed by a cleanly cut domain, machine contracts that other systems can rely on, and approval paths that prevent a proposal from taking effect without the intended human decision: an organization has to build these itself, and that is exactly the share that remains its own, independent of any single model. ## Position instead of prediction I have no basis for judging model capabilities a year from now, productivity curves of entire industries or labor markets, and above all these months have taught me how quickly such statements age. That’s why I’m not formulating a vision, and I explicitly mark what this interim review is: my limited state of experience, not a prediction about inevitable market or organizational developments. What I can stand behind, because it has been confirmed repeatedly over these months: the lasting value lies less in the individual model than in your own knowledge, enforceable rules, clear domains and verifiable processes. That is not a statement about the future but a description of what remained after every model change – and of what was missing every time a result didn’t hold up. And for my own desk, one expectation remains that you can measure me against: the first domain agent that has been in operation long enough for its rejections to tell stories – correct noes, overly tight noes, special cases that deserve a verb of their own. Only then will it show whether the cycle from the last installment holds up or just sounds good. ## Interim review, not a final word This series pauses here, for a simple reason: the supply of observations is used up. What would come now would be extrapolation, and there is enough of that. What this interim review lacks is time in operation. When enough new material has come together again, when the noes of the first domain agent have something to tell, I’ll keep writing. Until then, the resolution from the opening applies unchanged: distrust your own enthusiasm, measure against real tasks, check every result against your own craft. Looking closely pays off, and it doesn’t stop. ## Further reading - [Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity (METR, July 2025)](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) – the study that puts measured slowdown and perceived speedup side by side - [The Anthropic Economic Index](https://www.anthropic.com/economic-index) – ongoing data collection on what AI is actually used for in the economy - [Things we learned about LLMs in 2024 (Simon Willison)](https://simonwillison.net/2024/Dec/31/llms-in-2024/) – a sober annual review as an antidote to prediction prose --- # MCP, HTTP, Webhooks and A2A Explained Simply URL: https://www.mikebild.dev/en/blog/mcp-http-webhooks-and-a2a-explained-simply/ Date: 2026-08-17 Four connections can all run over HTTP technically and still serve four fundamentally different purposes. An agent application discovers a tool. A fixed program calls a documented endpoint. A service reports an event that has already happened. An independent agent takes on a task with its own lifetime. MCP, HTTP with OpenAPI, webhooks and A2A describe these boundaries. None of them replaces the domain decision about who may read, write, approve or publish. A product can offer several of these machine interfaces and also have its own web UI for people. It still remains one domain with one authoritative product state and the same domain rules. ## Four questions instead of a ranking An interface is an agreed boundary between systems. It defines inputs, results and errors. The transport, however, doesn’t yet answer which responsibility is handed over at this boundary. | Technique | Guiding question | Typical task | | --- | --- | --- | | MCP | Which capabilities can an agent application discover and use? | Providing tools and context for an open-ended task | | HTTP with OpenAPI | Which known machine command can a client execute? | Calling and checking a stable service contract | | Webhook | Which event that has occurred should another system learn about? | Triggering a downstream process promptly | | A2A | Which bounded task can an independent agent take on? | Delegating stateful work to another agent system | The four options are not ranked, and they don’t sit on the same technical layer. HTTP is a transport protocol, OpenAPI describes an interface, webhooks use HTTP to deliver events, and MCP and A2A each bring their own interaction contracts. An A2A agent can call MCP tools and ordinary HTTP APIs internally. ## MCP provides capabilities for agent applications MCP stands for Model Context Protocol. With it, an agent application can, for example, discover a knowledge service’s search as a tool; the visibility of this tool is not yet a domain permission and no substitute for a fixed workflow. A server can run locally as a process or remotely as a web service. The word “server” describes its role in the protocol, not its location. ```json { "mcpServers": { "knowledge": { "type": "http", "url": "https://knowledge.example.com/mcp" } } } ``` After connecting, the agent application can check the input schema and call the tool. This doesn’t give the model a blanket permission. The host controls which capabilities are visible and which calls require consent. The server authenticates and authorizes the call. The responsible service additionally enforces its domain rules for the operation. MCP fits open-ended tasks. An agent application can search a knowledge service for approved knowledge, read sources and, depending on the result, decide which next step makes sense. For repeated publications with an identical sequence of steps, this freedom is unnecessary. A stored, approved workflow is easier to check and repeat there. ## HTTP and OpenAPI form an explicit machine contract HTTP governs request and response. OpenAPI describes the APIs built on top of it in a machine-readable way: paths, methods, inputs, responses and security schemes. People can read the description, programs can generate clients from it, and checks can compare the implementation with the contract. The following call is a schematic example: ```http POST /v1/sites/demo/previews HTTP/1.1 Host: content.example.com Authorization: Bearer Content-Type: application/json { "revisionIds": ["rev-123", "rev-456"] } ``` The call requests a preview. It says nothing about who reviewed the content from a domain point of view or whether this preview may be published. OpenAPI can make the technical contract precise. The approval rule belongs in the domain and in the controlled process. In a publishing system, the HTTP and OpenAPI interface can serve fixed integrations, a remote MCP endpoint can offer selected capabilities to agent applications, and a web UI can carry the human work in the same publishing domain. All three access paths then work with the same revisions, previews, releases and permission boundaries; none of them introduces a second persistence path. ## A webhook reports an event With a normal API call, the client actively asks. With a webhook, the event source sends an HTTP request to a previously registered address. That way, the receiver doesn’t have to keep checking whether something has changed. ```http POST /webhooks/knowledge HTTP/1.1 Host: orchestration.example.com webhook-id: evt-789 webhook-timestamp: 1785585600 webhook-signature: v1, Content-Type: application/json { "type": "proposal.approved", "data": { "space": "product-docs", "concepts": ["integration-options"] } } ``` The event type in the example is deliberately generic. In this flow, the webhook only carries the event and the reference to the authoritative state. The receiver checks signature and age, detects duplicate deliveries via the event ID and then reads the state from the responsible system with its own permissions. Duplicate delivery is part of the normal failure pattern. The receiver has to work idempotently: the same event ID may only take effect once in domain terms. It responds quickly and moves longer work into a stored process. A knowledge service can deliver signed Standard Webhooks for this. A workflow engine can bind such an input – with signature checks and protection against replays – to exactly one versioned workflow, without taking over the knowledge or publishing rules of the systems involved. ## A2A delegates to an independent agent system A2A stands for Agent2Agent. The protocol connects a calling agent with an independent remote agent system. The client knows its published capabilities, but not its internal plan, memory or tools. The remote agent remains responsible for how it handles the task within its boundaries. An Agent Card describes identity, endpoint, capabilities and authentication requirements. A message carries a conversation step made of text, files or structured data. Longer-running work gets a task with its own ID and a lifecycle. Results are returned as artifacts. Follow-up questions and other necessary decisions appear as state transitions of the task. That distinguishes delegation from a tool call. With MCP, an agent application calls a described capability. With A2A, one agent hands a goal to another system that can plan on its own, use tools and carry out several steps. ## Web UIs and machine interfaces serve different purposes A web UI for people is not a fifth kind of integration. MCP, HTTP with OpenAPI, webhooks and A2A connect machines. The web UI and the machine interfaces work with the state of the same domain and don’t introduce a second persistence path. Each web UI uses the terms and decisions of its own domain for this. In a knowledge service, a pending knowledge change is a change proposal; in a workflow engine, an execution belongs to a specific workflow version. Two boundaries follow from this separation: - A web UI doesn’t become a second domain system with diverging rules. - A machine protocol doesn’t become an unintended way around the human decision. ## No protocol grants permissions by itself Authentication answers: who is making the request? Authorization answers: what may this identity do? A valid key shouldn’t lump reading, writing and publishing together across the board. An agent searching for knowledge only needs read permissions. A step that builds a preview needs the write permissions required for that. A publication may require its own permission and a visibly bound human approval. If an operation is offered via several interfaces, the same domain approval boundaries must apply to it. Reliability doesn’t come from the name of the protocol either. An HTTP call can break off after successful processing, before the response reaches the client. A webhook can arrive more than once. An A2A task can wait a long time for a decision. Every writing step therefore needs a stable identifier, a clear retry rule and a stored state. For integrations that write or require approval, three contracts have to fit together: - The technical contract describes inputs, results and errors. - The domain contract defines which system owns knowledge, approval and publication. - The operational contract governs time limits, retries, logging and how outages are handled. ## A flow with all four boundaries ```mermaid flowchart LR U["Human
states a goal"] --> A["Agent application
works on an open task"] A -->|"MCP
search and read"| K["Knowledge service
reviewed knowledge"] A -->|"MCP or HTTP / OpenAPI
revision and preview"| C["Publishing system
publishing domain"] K -->|"signed webhook
approval event"| S["Workflow engine
versioned workflow"] S -->|"HTTP / OpenAPI
defined steps"| C A -.->|"A2A
delegate a bounded task"| R["Agent system
independent task"] H["Human in the respective web UI"] -.-> K H -.-> S H -.-> C H -.-> R ``` The first run can be supervised. An agent application reads from the knowledge service, generates Markdown and builds a preview in the publishing system. A person sees the results and can still change the order. As soon as the sequence repeats reliably, it belongs in a workflow engine as a versioned workflow. The workflow reads a specific approved knowledge revision, creates a content revision and builds a preview. It doesn’t publish automatically just because a webhook started it. The publishing system keeps the approval and release boundary. A2A comes in when an independent agent system actually takes on a bounded task with its own lifetime. Calling something an “agent” doesn’t turn a simple API call into delegation. ## The decision comes before the protocol The table only helps once three questions are answered: which system owns the state? Which identity may change it? Which effect requires a human decision? From these follow the rules for retries and the view in which a person can check the current state. First you decide who owns state and approval. Then comes the protocol. ## Further reading - [Model Context Protocol: Architecture](https://modelcontextprotocol.io/docs/learn/architecture) - [Model Context Protocol: Introduction](https://modelcontextprotocol.io/docs/getting-started/intro) - [OpenAPI Specification](https://spec.openapis.org/oas/) - [Standard Webhooks](https://www.standardwebhooks.com/) - [A2A: Key concepts](https://a2a-protocol.org/latest/topics/key-concepts/) - [A2A and MCP compared](https://a2a-protocol.org/latest/topics/a2a-and-mcp/) --- # A2A: When Agents Work Together URL: https://www.mikebild.dev/en/blog/a2a-when-agents-work-together/ Date: 2026-07-22 An agent system needs a limited code change in someone else’s repository. It could load tools itself, read the code and draft the change. But it can also hand the job over to an independent system that runs in a different environment, has its own permissions and later reports back a verifiable result. A2A 1.0 – the abbreviation stands for Agent2Agent – describes, for this second case, how a job is handed over and tracked between independent systems. The published specification of the open protocol covers how a client finds a remote agent, sends it messages, tracks longer-running tasks and receives results. It doesn’t prescribe which language model, which programming language or which framework works internally. ## Independent is the key word Not every named role is a separate agent. If an application runs three prompts one after the other and manages all tools, credentials and state centrally, then from an architecture perspective, those are three work steps in one agent system. A2A brings little there. A remote A2A agent, by contrast, is an independent service. Within its job, it decides for itself how it works. The calling agent sees the offered capabilities and the exchanged data, but not automatically the other system’s internal memory, reasoning or tools. This encapsulation separates the permission and task boundaries of both systems: the remote agent works with its own access rights, and only what the job calls for should be exchanged. In the protocol, an A2A client makes contact on behalf of the user. The A2A server provides the remote agent. Client and server are communication roles, not classes of systems: for a different job, the same system can take on the other role. ```mermaid flowchart LR U["User
sets a goal"] --> C["Calling agent
A2A client"] C -->|"Read Agent Card"| S["Remote agent
A2A server"] C -->|"Message
job and context"| S S -->|"Task
state and follow-up questions"| C S -->|"Artifacts
results"| C S --> M["Internal models, tools
and data sources"] C -.->|"no automatic access"| M ``` ## The Agent Card is the description, not the permission Before a client sends a job, it has to know what the other agent offers and how it can be reached. That is what the Agent Card is for, a JSON document with metadata. The published A2A 1.0 specification describes in it, among other things, identity, supported interfaces and offered skills; as ways to obtain it, it names a standardized address (`https://{domain}/.well-known/agent-card.json`), as well as catalogs or a fixed configuration. The following fictional publishing example is reduced to the fields needed here and doesn’t claim to be a complete A2A 1.0 Agent Card. ```json { "name": "Publishing Agent", "description": "Builds previews and prepares approved releases", "supportedInterfaces": [ { "url": "https://publishing.example.com/a2a", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0" } ], "version": "1.0.0", "capabilities": { "streaming": true, "pushNotifications": true, "extendedAgentCard": true }, "defaultInputModes": ["text/plain", "application/json"], "defaultOutputModes": ["text/markdown", "application/json"], "skills": [ { "id": "prepare-publication", "name": "Prepare publication", "description": "Creates a preview from approved knowledge", "tags": ["publishing", "preview", "content"] } ] } ``` The Agent Card is comparable to a public service description. The fact that a skill is listed there doesn’t yet permit a call. Authentication and authorization remain separate security decisions: for every job, the server has to check who is asking and what this client is allowed to do. A public Agent Card should also not reveal internal capabilities or confidential endpoints. ## Message, Part, Task and Artifact Message, Part, Task and Artifact denote different building blocks of a job. | Term | Meaning | Example in delegated work | | --- | --- | --- | | Message | A conversational turn by the user or the agent | “Analyze this dependency and propose a change.” | | Part | A component of a Message or an Artifact | Instruction as text, a file or structured data | | Task | A stateful unit of work with a unique ID | The job is waiting for an answer to a question or keeps working | | Artifact | A result produced by the agent | Analysis report, prepared change, preview URL | A Message can be answered immediately with another Message. That fits a short conversation without a lasting work state. If the work has to keep running or be preserved across several conversation rounds, the remote agent responds with a Task. The Task is more than a technical request ID. It holds the state of a domain unit of work. The client can read it later, answer a follow-up question or request a cancellation. According to the specification, several Messages can belong to the same conversation context via a `contextId`; a `taskId` denotes the concrete work. A simplified, non-normative example: ```http POST /message:send HTTP/1.1 Host: agents.example.com Authorization: Bearer Content-Type: application/a2a+json A2A-Version: 1.0 { "message": { "role": "ROLE_USER", "messageId": "msg-123", "parts": [ { "text": "Prepare a limited change proposal. Do not merge it." }, { "data": { "repository": "product-service", "scope": ["dependency-upgrade"] }, "mediaType": "application/json" } ] } } ``` The Parts separate different kinds of content within the same Message: text carries an instruction, a file hands over a document, structured data allows an agreed schema without parsing it out of prose again. The recipient has to check the media type, size, origin and permission of each piece of content. Artifacts are the work results, not just conversational turns. According to the specification, a Task can deliver several Artifacts, and an Artifact can be extended step by step during a stream. The client should therefore store the Artifact ID and Task ID instead of just copying the last visible text. A typical first response looks like this – the server has accepted, but not finished yet: ```json { "task": { "id": "task-456", "contextId": "context-789", "status": { "state": "TASK_STATE_WORKING", "timestamp": "2026-08-07T10:05:00Z" }, "artifacts": [] } } ``` ## The lifecycle makes longer work visible A2A is designed for asynchronous tasks. A server can return a Task immediately and keep working in the background. For updates, the specification provides three delivery paths: queries, a continuous stream or push notifications. ```mermaid stateDiagram-v2 [*] --> SUBMITTED SUBMITTED --> WORKING WORKING --> INPUT_REQUIRED: follow-up question INPUT_REQUIRED --> WORKING: further Message WORKING --> AUTH_REQUIRED: additional approval AUTH_REQUIRED --> WORKING: permission granted WORKING --> COMPLETED WORKING --> FAILED SUBMITTED --> REJECTED WORKING --> CANCELED COMPLETED --> [*] FAILED --> [*] REJECTED --> [*] CANCELED --> [*] ``` The diagram simplifies the state space defined in the version 1.0 specification. `INPUT_REQUIRED` means that the agent needs further domain information. `AUTH_REQUIRED` signals an authorization needed during the job; credentials don’t belong in a Message as plain text but go through a separate, previously agreed path. The specification defines `COMPLETED`, `FAILED`, `CANCELED` and `REJECTED` as final states. A client must not revive a final state by blindly retrying, but has to deliberately create a new Task. Polling, streaming and push solve the same delivery problem in different ways. With polling, the client asks for the Task at sensible intervals – simple, but wasteful during long pauses. With streaming, a connection stays open and the server sends status and Artifact updates as events; after an interruption, the client has to read the stored Task again, because a stream is not an archive. Push notifications spare you the permanent connection, but require a secured HTTP endpoint on the client side, including authentication, protection against internal target addresses and handling of duplicate deliveries. ## Delegation creates no new permission A2A doesn’t make any security decision for a system. A calling agent should not trust an Agent Card it found just because it is formally correct. Before a job, it has to be clear which provider your own system trusts, which data may leave it and which effects the remote agent can trigger. The A2A server has the same obligation: for every job, it has to check who is asking and what this client is allowed to do, and treat Messages as untrusted input. The most important principle behind this: delegation must not create new permissions. Whoever submits a job must not gain more rights in the target system by doing so, and the executing agent must not silently inherit the rights of its client. The job stays limited. A target system can make this limitation explicit: a delegated job is then bound to an active, human-approved job state. What this state doesn’t allow, even a technically correct A2A call cannot trigger. A human approval step thus remains a domain decision in the target system – an agent must not infer an approval from friendly wording in a Message. ## MCP, A2A and a web UI are different access paths, not labels MCP provides an agent application with tools and context; responsibility for the open task stays with the application. A2A connects independent agent systems: the client hands over a goal, the remote agent is responsible for the execution and runs its own Task lifecycle. MCP and A2A thus model different responsibilities and lifecycles. | Question | MCP | A2A | | --- | --- | --- | | Counterpart | Capability server | Independent agent system | | Discoverable description | Tools and context sources | Agent Card with skills and interfaces | | Typical work | Select and call a tool | Delegate a goal or subtask | | Longer-running state | Modeled by the application | Task lifecycle is a protocol concept | | Result | Tool result or resource | Message or one or more Artifacts | | Internal implementation | Capability with a defined schema | Remote agent stays independent internally | On top of that comes a web UI as an access path for people. These access paths have different jobs, and a system can offer several of them without that turning into several domain models. For example, a system can offer limited analysis and change jobs via A2A 1.0, while REST, MCP, A2A and the web UI read the same structured task and result record. ## When A2A makes sense A2A pays off when several conditions apply at the same time: the agents involved are developed or operated independently. The work may take longer than a single request, needs follow-up questions or produces several results. The client defines the goal and the permitted effect; the remote agent is responsible for the internal execution. For a known sequence of fixed steps, a deterministic workflow is usually simpler. Merely different role names, several language models or separate prompts don’t yet justify a distributed agent architecture – they only create an additional network boundary without an additional boundary of responsibility. The decision can be anchored in who carries the responsibility for the open task. If it stays in your own application and only needs tools or context, MCP may be enough. If an independent system takes over a limited job with its own Task lifecycle, A2A is the right contract. If you keep these levels apart, you don’t build unnecessary agents – and you recognize the features of the delegation described here: an Agent Card, an authenticated call, a traceable Task and a limited job. ## Further reading - [A2A Protocol Specification 1.0](https://a2a-protocol.org/latest/specification/) - [A2A: Core Concepts](https://a2a-protocol.org/latest/topics/key-concepts/) - [A2A: Life of a Task](https://a2a-protocol.org/latest/topics/life-of-a-task/) - [A2A and MCP compared](https://a2a-protocol.org/latest/topics/a2a-and-mcp/) - [Model Context Protocol: Architecture](https://modelcontextprotocol.io/docs/learn/architecture) - [MCP, HTTP, Webhooks and A2A Explained Simply](https://www.mikebild.dev/en/blog/mcp-http-webhooks-and-a2a-explained-simply/) --- # Hourly Is Not Real Time URL: https://www.mikebild.dev/en/blog/hourly-is-not-real-time/ Date: 2026-07-20 An hourly report doesn’t ask about the current state but about the hour that just closed. Whatever happens at 14:00:00 UTC already belongs to the next time window. So the run only starts once the time window is closed, and it publishes its state a few minutes later. For an alert, that would be far too late. For a reliable summary, it’s exactly the delay you want. This timing decision separates the hourly report from ongoing operational monitoring. A closed report answers a different question than monitoring: it records a bounded period as a verifiable state of the observations, while monitoring has to react to new signals. The difference isn’t primarily in Prometheus, Grafana or Markdown. It lies in how quickly a new value has to trigger a reaction and whether the statement in question may still change later. The article [“Markdown Reports Instead of Dashboard Mandates”](https://www.mikebild.dev/en/blog/markdown-reports-instead-of-dashboards/) already describes the difference between a fleeting view and a verifiable state. This one is more narrowly about the timing mechanics of a regular product report: closed time windows, late data, retries and the boundary to real operational monitoring. ## Two time axes, two jobs Monitoring works as close to the event as possible. An error rate rises, an alert is evaluated, someone opens logs and traces. New data keeps changing the display. A report, on the other hand, waits until its period has ended. It can then determine which sources were complete, hash its facts and deliver the same state again later. ```mermaid flowchart LR E["Event"] --> M["Live metric
seconds to minutes"] M --> A["Alert or investigation"] E --> W["Closed hourly window"] W --> R["Immutable report"] R --> V["Comparison and context"] ``` Both paths may see the same event and still arrive at different results. Monitoring can react at 13:42 to five errors in two minutes. Later, the hourly report records that in the time window from 13:00 to 14:00, five errors occurred across 1,200 executions, which sources were covered and whether the cluster stands out compared with earlier time windows. A continuously updated UI for the second job would show incomplete intermediate states. While the time window is running, counters are incomplete. A value of zero at 13:01 says almost nothing about the hour. A growing bar invites you to compare unmarked intermediate states with closed hours. Without accounting for the different coverage, that comparison doesn’t hold up. ## The boundaries of the time window Collection uses half-open UTC intervals. Start included, end excluded. This notation prevents an event at the boundary from ending up in two reports. ```ts type ClosedWindow = { from: string; // inclusive RFC 3339 timestamp to: string; // exclusive RFC 3339 timestamp bucket: "hour"; }; const window: ClosedWindow = { from: "2026-07-18T13:00:00.000Z", to: "2026-07-18T14:00:00.000Z", bucket: "hour" }; ``` UTC avoids an unpleasant special case: in Europe, the day of the daylight saving time switch doesn’t always have 24 local hours. Storage and collection therefore stay in UTC. The report page can localize a date for its readers later without changing the domain boundary. Between the end of the time window and the freshness check, this process provides an explicitly defined buffer. If collection grows more extensive, start time, timeout and check boundary have to be adjusted together. A secretly extended buffer would only make real delays visible later. ## Keeping late data and missing runs apart An HTTP call can fail temporarily. A workflow can abort after writing the artifact but before updating its status. A release can succeed even though the response never reaches the client. That’s why a retry must not simply mean “everything again.” Each run has a unique time window. Cadence-tagged reports are treated here as immutable publications: once an hourly state is published, it doesn’t change anymore. A repeated successful attempt must therefore not make a second, different hourly report visible for the same time window. Only after the intended buffer does the distinction between late and missing apply. A late run can still complete successfully and publish the same report. A missing run leaves a gap in the expected sequence of hours. Lateness, measurement gap and closed time window thus remain three separate facts that the report should name separately. ## What follows from a missing observation A critical case for an hourly report is an hour without data. An observation service should explicitly distinguish four states for this: a source has never been observed, it was checked and the expected content isn’t there, it is access-protected, or it is actually broken. A missing observation must be reported neither as a healthy state nor as the numeric value zero. For an hourly report, this means: if there’s no measurement for an hour, there’s no value for that hour. The report then must not claim there were zero events, because that statement would imply a measurement that never took place. Instead, it has to show that the source wasn’t observed in the period in question and the statement remains open. If, on the other hand, the source was checked and the expected content wasn’t found, that state is observed; but that doesn’t automatically mean a general error counter of zero. ## When you would miss Prometheus and Grafana Tools like Prometheus and Grafana support, among other things, ongoing investigation: you can adjust a query during the analysis and shift the time range. This way of working is valuable when the question wasn’t fixed in advance. A UI for hourly reports, on the other hand, can be geared toward closed report periods. That focus fits as long as the UI is meant to explain closed periods. For an incident analysis, though, warnings would come too late, and hourly resolution isn’t enough to trace a cause down to individual requests. An hourly report replaces neither alerting nor ongoing operational monitoring; it assumes both as separate jobs. ## Four questions before choosing a tool “Dashboard or report?” is too coarse. Four questions separate the requirements: reaction time, mutability, investigation and resolution. The first concerns reaction time. If someone has to act within seconds or a few minutes, the observation belongs in a monitoring and alerting system. If a team can check the state in the next regular work cycle, an hourly or daily report may be enough. The second concerns mutability. If the same URL should show new values tomorrow, a live query fits. If exactly the state from July 18 still has to be readable later, you need an immutable artifact or an explicitly stored snapshot. The third concerns investigation. If the questions are known in advance – number of releases, errors, source coverage – a limited schema can represent them precisely. If the questions only arise when you look at an anomaly, a query language, variable time ranges and drill-down become important. The fourth concerns resolution. An hourly counter can show that something failed more often. It can’t explain which individual request was slow or which log line belongs to a trace. For that investigation, the high-resolution data has to stay in its operational tool. ```yaml decision: reaction_time: next_work_cycle immutable_history: required questions_known_in_advance: true per_request_drilldown: false result: scheduled_report ``` As soon as one answer flips, the right tool can change too. A report and a live system may observe the same service, as long as they don’t pretend to do the same job. ## The scheduler is part of the statement A manually generated report only proves that someone pressed a button at some point. A scheduled run additionally makes visible whether the expected regularity was kept. A check of this regularity therefore has to distinguish between scheduled and manually triggered runs: manual runs must not cover up a missed scheduled hour, otherwise the check counts successes that say nothing about the promise of regularity. A pause isn’t an error either, if it was explicitly set during a release. But it has to be visible and deliberately lifted after the rollout. A forgotten pause switch isn’t a data problem but a broken promise about regularity. ## What an hourly report has to explain Without stated source coverage, an operator can read a measurement gap as a result. An hourly report therefore has to explain for itself what it’s based on. Overview, question, conclusion and next action can be derived from the same semantic report document; a second, separately maintained dashboard dataset isn’t needed for that. A suitable UI shows this answer in decreasing order of importance: first state and exception, then a few signals, then evidence and provenance. A page with thirty metrics and no question is harder to check than a page with one clear question, one supported state and one named next decision. For this, the fact definition also has to represent data gaps: it should name available, missing and stale sources separately, so that an open statement doesn’t look like an answered one. ```md ## Data quality The source window is complete for four product APIs. External acquisition data is not connected yet and is shown as unavailable. No value is inferred from missing input. ``` Aggregation needs an explanation too. A weekly median runtime answers a different question than the maximum of the slowest hour. The report names the period, the expected and available sub-windows and the aggregation used. Otherwise, a precise number looks more verified than it is. ## Rolling up over larger periods Daily, weekly, monthly and yearly reports are built from already closed artifacts. A daily report can build on the immutable hourly states instead of querying the same sources again for each hour, and in doing so show which hourly windows it’s missing. Cadence-tagged reports remain immutable publications; a rollup doesn’t replace an hourly state, it condenses it. ```mermaid flowchart TD H["24 hourly artifacts"] --> D["Daily report"] D --> W["Weekly report"] W --> M["Monthly report"] M --> Y["Yearly report"] H --> Q["Coverage and missing windows"] Q --> D ``` A daily report that’s missing individual hourly windows can still be more helpful than no report at all – but only if it clearly marks itself as incomplete. It must not radiate the same visual certainty as a fully covered period. Data quality belongs next to the metrics, not in a footnote. A UI can place the latest closed period ahead of further decision horizons and a limited history. Which question each coarser report answers is a design decision. An obvious split: the hour checks the data flow and fresh technical signals. The day answers what needs attention today. The week compares daily patterns and recurring exceptions. The month puts activity patterns, operational risks and measurement gaps in context for the next round of planning. The year condenses only the evidence that can support a strategic decision. Just widening the date filter would be formally correct and weak in substance. Numbers aren’t just values here either. A fact definition should distinguish counters, stocks, durations, ratios and data volumes, name the unit and specify whether a rollup prefers the sum, the last value or the mean. A machine then doesn’t have to guess from a metric name how the value should be read across several intervals. ## Simple technology needs a clear boundary The hourly approach can get by without an additional, permanently running analytics platform if existing systems take over collection, scheduling and publishing. Its questions are fixed before the run, and its result appears as an immutable publication. What matters is the boundary of responsibility: the report collects, closes and publishes; ongoing observation stays with the systems built for it. This simplicity only survives if the system stands by its job. A report may show a missing data source instead of secretly building in new data collection. It may point to an external incident view instead of becoming the control room itself. And it may leave a question unanswered if there’s neither a fact nor a connector for it. Hourly here doesn’t mean “almost live.” It means: regular, closed, repeatable and slow enough to verify a complete state. If you have to react faster, you need monitoring and alerting. If you want to trace later what was known in a clear period, you need an hourly report. Both exist side by side, with clearly assigned jobs: monitoring delivers ongoing signals, alerting triggers a reaction from them, and the hourly report preserves the closed, verifiable state of observation. ## Further reading - [Prometheus Overview](https://prometheus.io/docs/introduction/overview/) - [Grafana Dashboards](https://grafana.com/docs/grafana/latest/visualizations/dashboards/) - [W3C Trace Context](https://www.w3.org/TR/trace-context/) --- # Claims: Small, Sourced, Verifiable URL: https://www.mikebild.dev/en/blog/claims-small-sourced-verifiable/ Date: 2026-07-20 “Our publishing is secure, fast and reliable.” The sentence sounds good and is hardly usable as a claim. It contains three judgments, none of them has a criterion, and a source could at most support parts of it. A reviewer would have to accept or reject the whole sentence, even though they might only be able to confirm a documented rollback mechanism as part of reliability. A knowledge base should therefore store small statements as `subject / predicate / object`. The page text stays readable for people. Beneath it, claims form the units that can be cited, checked, disputed and retired one by one. Confidence and status answer different questions. ## A claim says exactly one thing The subject names the thing, the predicate the relationship or property, and the object the concrete value. A good claim can be understood without the rest of the paragraph on the page. ```json { "subject": "content-release", "predicate": "rollback_mechanism", "object": "switch the active pointer to an immutable revision" } ``` The form resembles a simple RDF triple, but it doesn’t force you to model the entire domain as a universal graph. Within a space, a controlled vocabulary emerges that fits its questions. `rollback_mechanism` can make sense where releases are compared; in an HR space it would be meaningless. Claims that are too large combine several verifiable statements. Claims that are too small lose their meaning. `content-release / uses / pointer` would be atomic, but it doesn’t explain what the pointer is used for. The wording should be narrow enough for a contradiction and complete enough for a reader. ```mermaid flowchart TD A["Statement from source"] --> Q{"one domain
assertion?"} Q -->|several| S["split into several claims"] Q -->|one| C{"understandable
without the paragraph?"} C -->|no| E["make the object more precise"] C -->|yes| V["add quote and status"] ``` ## The quote carries the statement Every claim points to one or more sources via citations. A citation contains a verbatim excerpt and, optionally, a locator. A quote check can make sure the quote appears verbatim in the archived source text. A claim whose evidence is only paraphrased or made up should be discarded before it reaches review. ```json { "subject": "content-release", "predicate": "rollback_mechanism", "object": "switch the active pointer to an immutable revision", "confidence": 0.94, "citations": [ { "source_id": "source_release_docs", "quote": "Rollback changes the active release pointer to a previous immutable revision.", "locator": "Rollback" } ] } ``` A quote has to support the statement within its scope. If the source only talks about a preview environment, the claim must not turn that into a general production rule. This check can’t be done with string matching alone. The reviewer reads the context. Several citations are useful when a statement is supported jointly by a contract and observed behavior. The API documentation can describe the intended mechanism, a production report can document its actual use. Many weak sources, however, don’t automatically make a claim stronger. ## Confidence is not a truth scale `confidence` describes how sure the generating synthesis was about its mapping. It can help the reviewer look at uncertain proposals first. It is not a substitute for status and not a probability that a statement is true in the world. ```ts type ClaimStatus = "proposed" | "verified" | "disputed" | "deprecated"; type Claim = { subject: string; predicate: string; object: string; confidence: number; status: ClaimStatus; }; ``` A claim with `confidence: 0.99` stays `proposed` until approval. An approved claim with `confidence: 0.78` can be `verified` because a person checked the source and the wording. Later, new evidence can make it `disputed` without reinterpreting the old confidence value. This separation prevents a convenient shortcut. A threshold like “approve automatically from 0.9” would confuse model self-confidence with domain authority. It makes more sense to turn every knowledge change into a change proposal, regardless of the value in `confidence`. It is only adopted after human approval. ## Status models the lifecycle `proposed` is staging and invisible to normal readers. `verified` marks an approved statement. `disputed` makes a traceable conflict visible. `deprecated` keeps an outdated statement in the history without treating it as the current state. The lifecycle allows more precise answers than deletion. If a service used a static retry value up to version 2 and shares a budget since version 3, both statements are historically relevant. The old one isn’t removed from all revisions. It gets a status and stays connected to its source. ```mermaid stateDiagram-v2 [*] --> proposed proposed --> verified: human approval proposed --> [*]: rejection verified --> disputed: conflicting evidence disputed --> verified: conflict resolved verified --> deprecated: superseded disputed --> deprecated: superseded ``` The transition from `proposed` to `verified` doesn’t happen automatically but only after a human decision. The visible page text can then explain the current state fluently. The claims beneath it preserve which individual statements carry that explanation and which conflicts are still open. ## Functional predicates make conflicts exact Some relationships may have several objects at the same time. A system can support several export formats. `supports_format=markdown` doesn’t contradict `supports_format=okf`. Other relationships should have only one current value per subject, such as `primary_database`. A space can declare such functional predicates. If two different objects for the same subject and predicate meet there, the knowledge base can mark both claims as `disputed` and connect them via `contradicts`. ```json { "settings": { "functional_predicates": [ "primary_database", "current_owner", "default_retention_days" ] } } ``` This rule stays deterministic. A model doesn’t have to decide whether two freely worded paragraphs collide semantically. The controlled predicate states in advance exactly where a single current value is expected. Too many functional predicates would be harmful. Marking `supports_format` as functional would wrongly put complementary facts in conflict. The vocabulary is therefore a domain decision of the space and belongs in review. ## Breaking a paragraph into claims A practical example shows the sizing decision. Suppose a source says: “The service runs as a single binary, migrates PostgreSQL on startup, and exposes health and readiness endpoints.” This should not turn into one claim with the object `single binary with migrations and probes`. Three properties change independently of each other. ```json [ { "subject": "service-runtime", "predicate": "distribution", "object": "single self-contained binary" }, { "subject": "service-runtime", "predicate": "database_migration", "object": "runs automatically on startup" }, { "subject": "service-runtime", "predicate": "exposes_probe", "object": "/health and /ready" } ] ``` If a sidecar is added later, it affects the distribution claim. The migration and the probes can stay unchanged. A reviewer sees exactly the small diff. An agent can keep using the two confirmed statements while the first one is being checked. The cross-check helps: would a change to the object automatically change the other parts of the statement? If not, several claims are appropriate. If a claim would be misleading without its neighboring sentence, it needs a more precise subject or object. Time and scope belong in the wording too. `uses PostgreSQL` fits a current architecture if the source describes the whole service. If it only refers to the production deployment, the subject should be `service-production-deployment`. Precision often comes more easily from a narrower subject than from a long object text. A claim is not a complete sentence for blog prose. It may stay machine-readable and terse. The concept page then explains how the three properties work together. ## A concept is more than its claims Claims alone don’t make a readable explanation. A concept still has a title, a summary, Markdown and relationships to other concepts. The page can explain an example, limitations and the historical context. The claims serve a different purpose. They let you: - trace a single statement back to the original quote; - mark a contradiction without rejecting the whole page; - check only the statements that actually changed in a new revision; - limit search hits and agent answers to visible, approved units. Page text and the structured layer should be revisioned together. A proposal must not already show new text while its claims are invisible or incomplete for readers. Atomic approval makes the new revision current as a unit. ## Relations connect, claims provide evidence Besides claims, a knowledge base can know directed relationships between concepts: `related`, `part_of`, `depends_on`, `contradicts` and `supersedes`. A relation answers how two pages are connected. It doesn’t replace a claim or a citation. ```json { "from_slug": "content-release", "kind": "depends_on", "to_slug": "immutable-revision" } ``` The relation enables navigation and context. The documented fact stays as a claim on one of the pages. Otherwise a mere link would carry a domain statement without naming its wording or its source. `contradicts` can arise as a consequence of the functional predicate logic. `supersedes` fits a traceable replacement where the new term or the new rule replaces the old state. Relations themselves are reviewed and published with the concept revision. ## Revisions answer the question of time A current claim alone doesn’t explain when it was introduced. A concept history should keep approved, rejected and proposed revisions together with their provenance: which model and which prompt version generated the proposal, which sources were used and which person approved it. This information doesn’t make a model the author in a legal or domain sense. It documents which technical synthesis path generated the proposal. Reviewer, note and timestamp explain the human decision. Approval, status and revision together make visible how a statement entered the valid body of knowledge – and how it can leave it again. The history allows a time-related question: which statement was visible in March, before the retention rule was changed? A knowledge service that always returns only the current paragraph can’t answer it reliably. Revisions preserve the state at the time without presenting old claims as valid today. For teams, this trail becomes especially useful after model or prompt changes. If a new synthesis version proposes noticeably different claims, the affected revisions can be identified and checked specifically. That way, besides the source, you can also trace which model and which prompt version generated the proposal. ## A step beyond “Clean Grounding II” [Clean Grounding II](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/) sorted grounding into conventions, documents and API descriptions. The central question was which material belongs in the scarce context for a specific task and how expensive it would be to retrieve it again. That was a working model for individual sessions. What’s added is a smaller, durable unit between document and context: the claim. An agent doesn’t have to treat a whole page as uniformly binding every time. It can read the current concept revision, check visible claims including their status and open their citations when needed. “Matching document into the context” becomes “matching, approved statement with a way back to the source.” The older article [Fuzzy Matching with Explicit Limits](https://www.mikebild.dev/en/blog/fuzzy-matching-with-explicit-limits/) separated a claim with confidence from a fact. The same caution applies here. Confidence helps sort a proposal. Only evidence, review and status determine how the statement appears in the knowledge base. ## Checking claims in review For a new proposal, four questions are enough. Does the claim assert exactly one thing? Is it understandable without the surrounding paragraph? Does the quote cover exactly this scope? Would a different new value be recognizable as a clear contradiction? If an answer is no, the claim gets split, worded more narrowly or rejected. This is not a formal word exercise. Small claims reduce the effort later. A changed retention rule then doesn’t require a complete rewrite of the page about storage. Only the affected statement and its explanation get adjusted. Only statements that matter for search, review, conflicts or provenance get structured. The point is not to map every sentence as a universal ontology. Everything else stays prose; no claim is created for it. ## Further reading - [W3C RDF 1.1 Concepts](https://www.w3.org/TR/rdf11-concepts/) - [W3C PROV-O](https://www.w3.org/TR/prov-o/) - [Clean Grounding II](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/) - [Fuzzy Matching with Explicit Limits](https://www.mikebild.dev/en/blog/fuzzy-matching-with-explicit-limits/) --- # Products Report Through Their API URL: https://www.mikebild.dev/en/blog/products-report-through-their-api/ Date: 2026-07-19 A statistics API is a product feature. That sentence sounds obvious, but while working on cross-product reporting, it only became clear after two worse designs. At first, a central collector was supposed to access several PostgreSQL databases directly. After that, special private reporting endpoints and dedicated keys were on the table. Both would have built the report deeper into the products than its purpose requires. What remained was a smaller contract. A publishing system, a knowledge base and an orchestrator aggregate their own data themselves and offer their view through normal, authenticated HTTP endpoints. A downstream process combines the aggregates for explicitly bounded time windows – it sees neither tables nor Markdown, names, keys or internal IDs. This split is not a special trick for dashboards. Every authorized consumer can use the same statistics resources: a capacity report, a quality check, a local analysis or a later export tool. ## Data ownership is more than storage location Whoever owns a table knows its meaning. A publishing system knows when a revision was created and when a release was actually activated. A knowledge base distinguishes a started ingest from a verified state of knowledge. An orchestrator aggregates its execution data where the runs actually take place. A central collector would have to rebuild these meanings and keep up with every product change. Direct SQL makes this rebuilding particularly easy – and therefore dangerous. A query works even though it may count an intermediate status that the product itself would never show as complete. A new migration can break the report without the public product API having changed. Database access also bypasses the normal permission check and pulls the credentials of several systems into one place. With a product API, the domain aggregation lives where the state change is implemented: :::process{title="Domain aggregation stays in the product" role="primary" preferredPattern="connected-process"} 1. Product action · creates a domain-defined state transition 2. Own data store · keeps the product’s authoritative domain state 3. Aggregation · translates internal states into bounded domain metrics 4. Statistics API · delivers authenticated values with time range and meaning 5. Collector · combines compatible responses without redefining them 6. Report · explains the frozen shared state ::: The collector may combine the responses, but it may not reinterpret what a successful release or a verified claim is. These terms belong to the product. ## Time is uniform, the domain is not A shared contract doesn’t mean that all products deliver the same metrics. That would be artificial leveling. The only shared properties are the ones a collector needs for reliable time windows: - `bucket` determines the resolution: hour, day, month or year. - `from` is the inclusive start of the window. - `to` is the exclusive end. - `tz` makes the time zone explicit, UTC throughout here. - `buckets` contains a dense series, including empty intervals. - `totals` summarizes exactly the requested window. The payload keeps its domain names. A publishing system can, for example, provide site-scoped aggregates for releases, content and reader access, a knowledge base space-scoped aggregates for usage, coverage and reviews, an orchestrator tenant-scoped runtime statistics for executions and connectors. No product has to adopt another product’s terms; all of them have to fulfill the same time contract. ```json { "bucket": "hour", "tz": "UTC", "from": "2026-07-18T10:00:00.000Z", "to": "2026-07-18T12:00:00.000Z", "buckets": [ { "ts": "2026-07-18T10:00:00.000Z", "items_created": 2 }, { "ts": "2026-07-18T11:00:00.000Z", "items_created": 0 } ], "totals": { "items_created": 2 } } ``` The half-open notation `[from,to)` prevents double counting. The window from 10 to 11 o’clock contains an event at 10:59:59, but none at 11:00:00. The next window starts exactly there. A retry queries the same time window again and gets the same meaning. ## Measured zero, missing observation, incomplete window A dense time series also contains empty buckets. That is practical, because the collector doesn’t have to guess or fill in missing hours. A zero is a measured value: the product evaluated the window and found no matching event. Two other states have to be distinguished from this. Missing means that there is no observation for the metric – for example, because a source isn’t connected or a ratio cannot be calculated without a base. In the reporting process described here, the downstream report also determines incompleteness: an expected snapshot is missing, or the window had not yet closed at the time of collection. These three cases must not look the same in the report, because they carry different consequences: zero technical errors are reassuring, zero page views can be correct, a missing analytics connection is an open connection and not a measurement. A product can make the distinction between measured and missing part of the response and label values, for example, with `value_state` and `value_kind`. A ratio without observations carries the state `missing` and is not output as a measured zero: ```json { "metric": "engagement_rate", "value_kind": "ratio", "value_state": "missing" } ``` For someone reading a report, this state matters more than another decimal place. Time window, data state and the meaning of a measurement therefore belong in the contract itself – not in a footnote on the report page. ## Privacy starts with the shape of the response Aggregates should leave out information the purpose doesn’t need. A statistic can count successful, failed and rate-limited reader requests without storing user names, IP addresses, session IDs, Markdown content, URLs, job IDs or credentials in the statistics table. A knowledge base doesn’t have to output source texts through its statistics resources. Such a negative list belongs in the documentation and in contract tests. “We currently don’t return any names” is weaker than a schema that has no field for names at all. The collector then cannot accidentally carry a sensitive value over into a JSON artifact or a report page. Trace data also stays limited to its purpose. W3C Trace Context standardizes `traceparent` and `tracestate` so that a call can be correlated across several services. The W3C recommendation explicitly warns against transporting personal or other sensitive information in these headers. A trace ID connects technical steps; it doesn’t describe a person. ```http GET /v1/sites/example/stats/releases?bucket=hour&from=2026-07-18T10:00:00Z&to=2026-07-18T11:00:00Z Authorization: Bearer traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 ``` ## Zero-config means using existing terms Telemetry is rarely completely configuration-free. A service needs at least durable storage and information about whether it runs in development, test or production. “Zero-config” is meant more narrowly here: for the reporting process, no special mode is activated in the product, no special key is created and no report target is entered. The statistics endpoints can use existing product boundaries: a publishing system, for example, the site and a normal read key, a knowledge base the space and its read scope, an orchestrator the tenant. OpenTelemetry provides a usable shared vocabulary for this. `service.name` names the logical service, `deployment.environment.name` distinguishes `development`, `staging`, `production` and `test`; as of August 2026, the older key `deployment.environment` is marked as deprecated in the OpenTelemetry conventions. Standardized fields like these prevent one service from treating `prod`, another `live` and a third `production-eu` as the same concept. The product sets these values once for its runtime; the reporting collector doesn’t have to repair labels. The shared name alone is not enough, though. If an aggregator reads different field names than an older write path still delivers, successful calls can show up as errors. Such a transition can be made compatible in both directions: the reader understands old and new fields, the writer delivers both for the time being, and tests use real audit rows instead of hand-built ideal objects. ## Bounded queries instead of hidden load A general statistics API needs hard limits, such as a maximum window length per resolution. Invalid or oversized windows return `422` instead of burdening the product database with an unexpected full evaluation. These limits belong to the product contract, because only the product knows its costs. A collector should not try to get around them with many overlapping queries. For a long period, it uses the coarser resolution or works in distinct, non-overlapping pages. The same applies to retention. Anonymous raw events can have their own retention period in the product. A report artifact can live longer if its aggregated content is meant for that. Raw event, product aggregate and published report have different lifecycles; they don’t have to end up in one store. ## Existing keys instead of a back door A dedicated “reporting key” seems tidy at first, but it creates a second security logic. What may this key read? Does it apply to a site, a space or the whole product? Who rotates it? As soon as every product gives a different answer, the supposedly simple collector becomes a special case with far-reaching permissions. The statistics APIs should therefore use existing scopes. A read-only key for a site may then read exactly the statistics of the site it was issued for. A read key for the knowledge base stays limited to its space. Without a matching key, each of these endpoints stays closed. So the same rule applies to the collector as to other API users: a separate key per product, as narrow as possible; secrets only in the credential store; no keys in the workflow definition, JSON artifact, log or report. The workflow only knows a `credential_ref`; the actual value is inserted at the HTTP call and appears neither in the stored process nor in its result. This separation can be tested: a call without a key must return `401`, a key without a matching scope `403`, a correct key `200`. ## PostgreSQL is internal, not forbidden Rejecting direct database queries doesn’t mean that aggregates have to live outside the product database. For a publishing system or a knowledge base, PostgreSQL may be exactly the right place. Events and domain state can be recorded transactionally there, scoped by site or space and evolved with the same migrations as the rest of the product. What matters is the direction of the dependency. The product may know its own database. An outside collector must not need to know it. Whether a response comes from a precomputed table, a bounded SQL aggregation or a cache remains an internal decision. What counts is that each product can design its internal storage according to its own operating model and, toward the outside, fulfills the same reliable time contract. ## Documentation is part of the contract A new endpoint is only done when OpenAPI, `llms.txt`, `llms-full.txt`, the README and the detailed product documentation tell the same story. Otherwise, a person finds a scope in the README, a client generates from an older OpenAPI file and an agent reads a third variant. That is why the repositories check their generated documents for drift. Contract tests send valid, invalid, oversized and unauthorized windows to the handlers. Integration tests use the real product storage. A binary test makes sure that the shipped file contains the same routes and the same version number as the source. These checks prevent the collector from depending on an outdated or internally known-only response shape. ## APIs make exchange possible The immediate effect of this separation shows up in testing. Every product API can be checked against its own schema with a fixed window. The collector gets fixtures without database access. A product release can be rolled back independently at the API level, as long as the published contract is preserved. A new consumer doesn’t need a new table in the product. Another reporting tool can call the same API just as well. A product may change its internal storage without the statistics resource having to be reinvented. That also keeps the products understandable. Each product keeps its role – as a publishing system, knowledge base or orchestrator. Their statistics resources describe their own work as bounded aggregates with domain names. Everything else happens outside their boundaries. As long as the published contract is preserved, one part can be replaced without adjusting the others. ## What has changed since then The post [HTTP APIs: Small, Stable, Readable](https://www.mikebild.dev/en/blog/http-apis-small-stable-readable/) described an endpoint in 2014 as a long-term promise to unknown clients. Small resources, unambiguous timestamps, stable meanings and readable errors were meant to prevent every client from building its own defensive layer. These requirements still apply. What’s new is the view of internal product statistics. A statistics path is not built for a specific dashboard but as a bounded projection of the product’s own data. It uses existing keys and scopes, delivers time boundaries and data state along with the values and publishes only aggregates. This keeps the API small, regardless of whether a person, a workflow or an agent calls it. ## Further reading - [W3C Trace Context](https://www.w3.org/TR/trace-context/) - [OpenTelemetry Service Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/resource/service/) - [OpenTelemetry Deployment Attributes](https://opentelemetry.io/docs/specs/semconv/registry/attributes/deployment/) - [HTTP APIs: Small, Stable, Readable](https://www.mikebild.dev/en/blog/http-apis-small-stable-readable/) --- # From Org Chart to Product Ownership URL: https://www.mikebild.dev/en/blog/from-org-chart-to-product-ownership/ Date: 2026-07-18 An AI assistant produces a draft – and afterwards the work item waits for approval, review and release just as before. Who carries it from the observed customer problem to measurable impact? No draft generation, however fast, answers this question. AI can make the flow of work from the first customer signal through plan and implementation to review and impact more continuous – if responsibility for problem, decision, review and impact is brought together in one place. AI doesn’t remove organizational boundaries automatically. It lowers the cost of getting up to speed on the next step. Whether this results in one connected piece of work or merely a faster feed into the same waiting points is decided by the organization, not by the model. ## The flow of work from customer problem to impact By flow of work I mean a concrete chain here: a customer signal is observed, it leads to a hypothesis, the hypothesis to a plan, the plan to an implementation, the implementation to a review with domain acceptance, then a release and finally an observable impact that flows back as a signal into the next cycle. ```mermaid flowchart LR S[Customer signal] --> H[Hypothesis and plan] H --> E[Design and implementation] E --> Q[Review and acceptance] Q --> R[Release] R --> W[Observe impact] W --> S A[AI: context, variants,
tests and documentation] --> H A --> E A --> Q ``` The starting hypothesis is that in organizations built on division of labor, this chain is rarely continuous: one ticket describes the wish, another person decides on the design, a third builds the interface, a fourth checks the release. Each role can do its job very well while the result for the customer still remains incomplete. If you only see a small slice, you can hardly judge whether a new feature solves the customer problem or merely makes a subprocess tidier. What AI mainly changes about this chain is one cost factor: getting up to speed on the next step. An assistant can explain an unfamiliar service, gather existing decisions, sketch a data flow and suggest suitable tests. It doesn’t replace domain knowledge in the process. It lowers the barrier to bringing in domain knowledge from other parts of the organization in time – before a decision is made, not after a finished solution has been delivered. ## Handoffs don’t get shorter automatically My thesis is: AI can shorten handoffs if responsibility for problem, decision, review and impact is brought together. This is a hypothesis about organization, not a proven law. If responsibility stays as distributed as before, AI merely speeds up the production of intermediate results that still wait for the same approvals. The [post on faster development and unchanged processes](https://www.mikebild.dev/en/blog/ai-in-the-enterprise-faster-development-different-processes/) describes this downside: if an organization just fills the same old process faster, the bottleneck moves. More drafts wait for the same reviewers, and more documents contradict each other. The gain only comes when the freed-up time flows into understanding the whole piece of work. Bringing responsibility together doesn’t mean that one person has to be product manager, designer, security expert and operations lead at the same time. It means that a clearly bounded slice of the product is followed through by the same place: from the observed problem through a hypothesis and a change to feedback from usage. Specialist disciplines remain indispensable. The difference lies in the timing: specialists are brought in earlier and more deliberately instead of receiving a finished solution at the end of a long chain. The org chart doesn’t disappear because of this. People need clear responsibilities, development prospects and decisions that don’t get lost between teams. But the continuous flow of work can become more important than the boundaries between the boxes – where responsibility actually has been brought together. ## Vertical slices as a testable hypothesis Vertical work packages make this thesis testable. Instead of breaking a change down by technical layers – first the data model, then the API, then the UI – a small, usable slice is carried through all layers. Such a slice has a clear purpose, a visible impact and a manageable number of open decisions. This way of working made sense even without generative AI. One possible obstacle was the effort of getting into unfamiliar parts of the system: a developer knew the frontend, say, but not the rules in the backend. The product team knew the impact for users, not the consequences for operations or the data model. So work packages were cut along responsibilities and then pieced back together over many meetings. ```mermaid flowchart TD P[Product problem] --> V[Vertical slice] V --> U[UI] V --> F[Domain logic] V --> D[Data and contracts] V --> B[Operations and observation] U --> X[One verifiable result] F --> X D --> X B --> X K[AI: make dependencies and
suggestions visible] --> V ``` Smaller vertical slices are a testable organizational hypothesis, not a blanket statement about every team. The hypothesis is that a team with AI support can explore more of this context on its own – which services are affected, which contracts change, which test cases are missing, which documentation needs to be updated. Whether the observations in a concrete context support this hypothesis can be checked using waiting time, number of handoffs, rework and time to user feedback. The values are collected with identical definitions before and after a limited pilot; other process changes have to be recorded, because such a comparison doesn’t prove a clear cause. If the measurement turns out differently than expected, the hypothesis is not confirmed for this context for now – the team hasn’t failed. A vertical slice must not become a pretext for offloading every specialist discipline onto a few people. Where security, regulation or deep domain knowledge are needed, collaboration remains mandatory. The slice changes the order of involvement, not its necessity. ## Technology becomes an option again Many technology choices arise from what a team happens to know. That’s understandable: an unfamiliar platform demands research, small experiments and the worry of being left alone with it later. That’s why requirements are sometimes adapted to the existing tools, even though a different path might fit better. AI changes this calculation. It can search documentation, explain examples from a repository, compare variants and prepare a small prototype. That alone doesn’t turn an unfamiliar technology into a good decision. But it becomes cheaper to make the decision based on a real experiment instead of habit. A useful investigation keeps several possibilities open: - What is the smallest change with which we learn something about the customer problem? - Which existing systems, data and contracts do we really need to understand? - Which assumption does the AI make, and how can it be checked? - What impact do we expect after the release, and how would we notice the opposite? The answers don’t always have to be documented like an architecture decision. For a small change, a clean pull request with tests and a short rationale is often enough. What matters is that the AI doesn’t just produce more options but helps evaluate options faster and discard bad ideas earlier. ## Creating gets cheaper, review and acceptance become more important The most visible result of AI is often a draft: code, a test, a summary, an API description, a release note. The draft can be surprisingly good. But it can also carry a false premise forward with great conviction. The cheaper creating becomes, the more the value of review and domain acceptance grows. Review here means more than the pull request. It includes the domain check of a requirement, the look at contradictions in existing knowledge, the test under realistic conditions and the question of whether the release improves the product. Quality assurance is therefore not a last gate before rollout. It accompanies the entire slice. ```yaml review_focus: product_question: "Does this solve the observed customer problem?" domain_question: "Which business rule could make this wrong?" technical_question: "Which contract or dependency can break?" quality_signal: "What evidence would change our decision?" release_check: "Can we observe the result and recover safely?" ``` This example is not a new checklist for every little thing. It shows the shift: with AI-assisted drafts, the bottleneck can move from generation to review. What then becomes more important is deciding quickly and reliably what to keep, change or discard from a draft. The NBER study “Generative AI at Work” provides a limited empirical hint on this. Among more than 5,000 customer support agents, an AI assistant increased the number of cases resolved per hour by 14 percent on average, with less experienced workers benefiting in particular. I read this finding about the less experienced workers as a hint that AI can spread proven practices – that is my interpretation, not a direct finding of the study. In any case, the study is not evidence of the same effect in every task, let alone in product development. What remains for product work is mainly this: the first draft becomes more accessible. That doesn’t devalue experience. Experience becomes more visible where it counts – in choosing a direction, in recognizing an atypical case and in judging quality. ## Anchoring responsibility technically If this thesis is meant seriously – responsibility for problem, decision, review and impact brought together – then it also has to be reflected in the systems through which work flows. Otherwise it remains a good intention. Two examples show what such anchoring can look like. A request control layer can route HTTP, MCP, A2A, webhooks and chat into the same planning path and bind execution to explicit task authority, budgets, contracts, evidence and review. That is the technical form of this bundling of responsibility: no matter which channel a request arrives through, it goes through the same planning, and execution is bound to explicit authority. A workflow engine can model recurring work across several systems as an approved, logged workflow and hold back steps with external effects until confirmation. Here too, the design separates preparation and execution from the confirmed external effect: a piece of work may be prepared, checked and repeated, but the step that has an external effect waits for acceptance. Transferring this to the organization is a hypothesis, not a guarantee. If knowledge can be found, if releases are prepared so that a team can follow a change in a controlled way all the way to its impact, and if product and service information comes from the same verified sources instead of aging in separate copies – then one piece of work can close more gaps at once: a product change delivers test cases, operational information and a draft of the customer documentation at the same time. Recurring support questions show early which product rule or explanation is missing. Errors and follow-up questions flow back into rules, tests and later work packages. Whether these conditions are met, every organization has to check against its own flow of work. ## One complete slice as a test The change doesn’t start with a new org chart. It starts with a real, limited product problem. A team takes a piece of work that has several handoffs today and carries it through completely once: understand the customer question, check the assumption, build the change, assess quality, release and look at the impact. ```yaml vertical_slice: customer_problem: "Describe the observed problem" smallest_change: "Deliver one useful outcome" ai_support: - "Find relevant context" - "Prepare tests and documentation" human_review: - "Validate domain assumptions" - "Accept quality and release risk" outcome_signal: "Measure customer use and failures" ``` After that, the discussion about roles and structure becomes more concrete. Perhaps it turns out that a team can own an interface itself. Possibly a shared source of knowledge is missing. Or a specialist remains a permanent part of the process. What matters is that the organization learns from observed work and not from an abstract restructuring plan – and that it discards the hypothesis where the measurement speaks against it. AI doesn’t make end-to-end product development easy. It makes it possible more often where responsibility, review and impact belong together and aren’t spread across many stations. Research, drafting, tests, documentation and release preparation move closer together. The org chart stays. But the decision every organization can make now is concrete: take ownership of one selected, limited flow of work end to end once, and measure by its impact whether the hypothesis holds. ## Further reading - [NBER: Generative AI at Work](https://www.nber.org/papers/w31161) - [AI in the Enterprise: Faster Development Needs Different Processes](https://www.mikebild.dev/en/blog/ai-in-the-enterprise-faster-development-different-processes/) --- # llms.txt: Docs for Machines URL: https://www.mikebild.dev/en/blog/llms-txt-docs-for-machines/ Date: 2026-07-15 `llms.txt` sits in the root directory of a website, which makes it look like the next signal for search engines – a neighbor of `robots.txt` and `sitemap.xml`, created in the hope of visibility. Exactly this conclusion misses the point. The file was never meant as a ranking signal, and there is no evidence of any ranking effect. Its value doesn’t lie in crawler signals but in providing agents with curated documentation context. There are two files, `llms.txt` and `llms-full.txt`. They look like marketing infrastructure, and their value lies somewhere else: in the question of how a model gets clean, curated context without first working its way through navigation bars, cookie banners and JavaScript. Both files are machine-readable self-documentation of a product. ## Two files, one problem Jeremy Howard, co-founder of Answer.AI, published the proposal on September 3, 2024; the description is at `llmstxt.org`. The starting point is a sober observation: models increasingly rely on web content, but their context window is too small to take in an entire website in one go. And turning raw HTML into usable text is tedious and imprecise – between the actual content there is a lot of clutter that only eats up space. The answer consists of two building blocks that you should keep clearly apart. `llms.txt` sits in the root directory of a site and is a curated index in Markdown. The format is deliberately narrow: an H1 heading with the project name, below it a blockquote with a short summary, optionally a few sentences of context, then H2 sections with lists of links. Each link carries a brief description. A separate `## Optional` section marks what a model may drop first when space is tight. This is how compact it looks: ```markdown # Orderflow API > Orderflow is a REST API for creating, tracking, and refunding orders. > These docs are written for LLMs and coding agents. Every write endpoint accepts an `Idempotency-Key` header, so retries stay safe. ## Core Documentation - [Quick Start](https://docs.example.com/quickstart.md): Authenticate and create your first order - [API Reference](https://docs.example.com/api.md): Endpoints, parameters, and error codes - [Webhooks](https://docs.example.com/webhooks.md): Event types and signature verification ## Optional - [Changelog](https://docs.example.com/changelog.md): Version history and breaking changes ``` `llms-full.txt` is the second building block and conceptually simpler: the full text of the important pages, concatenated into a single Markdown file. No longer an index, but the whole content in one piece, without HTML noise. An agent or client can load the bundled content with a single request instead of working its way through page by page – whether all of it fits the specific task is another question. In addition, Howard suggests also providing individual pages as a clean Markdown version at the same address with `.md` appended – `.../api` becomes `.../api.md`. That’s the glue between index and content: the index points to pages that already exist in the form a model processes best anyway. The distinction matters, because a lot gets mixed up here. `robots.txt` governs what a crawler may touch. `sitemap.xml` helps with indexing. `llms.txt` does neither: the file puts things in context and curates them, intended for the moment of inference, not for the crawl. An agent that reads it gets an editorial statement about what matters in a product – not a promise to a search engine. The three files don’t exclude each other; they answer different questions. ```mermaid flowchart TD A[Coding agent] -->|knows llms.txt| B[llms.txt
curated index] B --> C{Which page
do I need?} C -->|targeted| D[page.md
clean Markdown version] C -->|everything at once| E[llms-full.txt
entire content] A -.->|alternative without llms.txt| F[Crawl the HTML page
navigation, ads, JS] F -.->|lots of noise| G[Context window full,
content diluted] ``` ## Why this helps When integrating a third-party library, an agent without a Markdown view often loads the complete HTML page or improvises missing signatures. In the first case, it pulls in the menu, the footer and three code examples it doesn’t need at all – a noticeable part of the window is gone before the actual task begins. In the second case, it guesses. In a code review, I noticed that an agent had simply made up an API signature, plausible and wrong, because fetching the exact reference was too expensive for it. Both are symptoms of the same problem: too much noise per token, too little reliable substance. `llms.txt` addresses exactly this. Curated Markdown without layout ballast means more of the window is left for the actual content. The index also forces a decision: not every page is equally important, and someone with domain knowledge has to name which thirty to a hundred pages make up the core. And when the model needs the exact error message or the exact parameter, it fetches the matching `.md` page instead of improvising. The point about curation is often overlooked. A good `llms.txt` isn’t an arbitrary list of links but an editorial statement about what matters in a product. This decision is the actual work – not the file itself. ## Where it pays off For a blog or a marketing site, `llms.txt` brings little: there is no evidence of a ranking effect, and if you create the file hoping for better visibility, you’ll be disappointed. Anyone who promises such an effect promises too much. The exception is narrow but real: technical documentation and coding agents. An API reference, a component library, an SDK – content that is maintained in Markdown anyway and that an agent in the IDE looks up in a targeted way. For pure marketing pages without demonstrable agent usage, the maintenance effort usually doesn’t justify the file; for regularly queried technical documentation, it can pay off. Server logs with requests to `/llms.txt` give you a hint of usage, but they don’t carry the decision on their own: a lack of direct requests doesn’t necessarily prove a lack of usage, for example when the same content is retrieved through other paths such as MCP resources. ## Generated from the source, not maintained by hand A central risk when using these files is organizational, not technical: two versions of the same content that are maintained separately. The page for humans here, the Markdown version for models there. If `llms-full.txt` lags behind the real docs, you feed models outdated content – and that’s worse than no file at all, because it creates false trust. Without automatic generation from the same source, drift is only a matter of time. That’s why both files belong in the build, not in the editor. The build can generate `llms.txt`, `llms-full.txt` and Markdown twins per site and locale from the published state. What matters is the shared source for human-readable and machine-readable outputs; a second, hand-maintained documentation would make drift possible again. That’s the second half of the curation work. A human makes the editorial decision about what belongs in the index. The build takes care of generating the files. If you do both by hand, you have taken on a second set of docs that easily deviates from the published state. ## What an MCP server makes of it Up to this point, `llms.txt` is a static file that someone picks up at some point. MCP adds targeted access to resources and operations on top of the static index. The Model Context Protocol is the open protocol that Anthropic introduced at the end of 2024, through which an agent talks to external tools and data sources in a standardized way. As an index, `llms.txt` describes which content exists and where it lives; an MCP server provides resources and operations in a targeted way. With `mcpdoc`, the LangChain team built exactly such a docs server. It receives a list of `llms.txt` addresses and provides the agent with two tools: one that lists the registered sources and one that fetches a specific page from them. An MCP docs server designed for this can load context in a targeted way, make calls loggable and restrict access – three improvements over simply downloading the file. First, dosage. Instead of dumping all of `llms-full.txt` into the window, the agent uses the index to request only the one page that fits the task – the range between “no context at all” and “everything at once.” Second, traceability. With a docs server like `mcpdoc`, fetching runs through tool calls that you can inspect: which address was loaded and what came back. This doesn’t automatically apply to resource reads; there, you need your own logging on the server side. A direct download of the file doesn’t necessarily leave this trail in the agent workflow. For internal or protected documentation, this auditability can justify the additional operational effort. Third, access control. You can restrict the server to allowed domains, and for internal or protected docs you put authentication in front of it. If you need permission-bound access, you can offer the documentation as a resource through an authenticated MCP server and check permissions there for every read. This way, the convention also works behind the company firewall: the server points to a private `llms.txt`, and models in the team get curated knowledge without the content being openly available on the web. If both come from one product, it can offer a remote MCP interface alongside the generated files. In such a setup, MCP resources are application-managed context that the server offers the client as documentation. Tools stay separate from this: they represent domain operations and should only become visible with the matching scope. Such a system can additionally provide its own `llms.txt` documentation as an MCP resource, so that a client can read the tool model and API boundaries without guessing a web page. So MCP adds targeted access and operations to the static documentation; this access only becomes permission-bound once the server authenticates and authorizes resource reads. The documentation doesn’t replace MCP – without generated, up-to-date machine views, these documentation resources would lack a reliable foundation. ```mermaid flowchart LR H[Agent host
Cursor, Claude Code] --> M[MCP docs server
e.g. mcpdoc] M -->|list sources| L[llms.txt
registered indexes] M -->|fetch page| P[only the needed
.md page] P --> H ``` `llms-full.txt` in particular gains from this combination. You can attach the file directly to an MCP server as a knowledge source – without an embedding pipeline, without a vector database. More accurate than “a replacement for RAG” is to describe it as a tool-based, auditable variant of it: not unpredictable retrieval from a large vector index, but traceable access to curated pages. ## Where it falls short `llms.txt` is a proposal, not an adopted standard. There is no committee behind it and no guarantee that a particular model reads the file. You provide it; you can’t force it to be consumed. Size is a real limit. An `llms-full.txt` that is several megabytes in size may, depending on tokenization, model and client limits, not fit completely into the available context and then only gets loaded in fragments – and with that, the advantage of “everything in one request” is gone. For large sites, you stick with the curated index of the truly central pages, complemented by targeted fetching of individual `.md` versions. And finally, the question of trust. As soon as an agent takes over a third-party `llms-full.txt` without checking it, it takes over content it doesn’t control. That’s the same attack surface as with any external data source that ends up in the context – a good reason to go through an MCP server with a domain restriction instead of collecting arbitrary addresses. ## Conclusion `llms.txt` and `llms-full.txt` are machine-readable self-documentation. The index says what matters and where it lives; the full version delivers the content in one piece; the `.md` mirrors provide individual pages in the form models prefer. None of them is a reliable ranking factor, and if you create the files with that expectation, you’re measuring against the wrong goal. Their value arises where documentation meets agents – with SDKs, API references and coding tools. Two decisions follow from this. First: the files are generated from the same source as the documentation for humans, or you leave them out – a hand-maintained duplicate drifts and undermines exactly the trust it’s supposed to build. Second: if you need targeted or permission-bound access, you can offer the documentation as a resource through an authenticated MCP server and check permissions there. In this way, MCP can complement the static views with measured, auditable and – with server-side authorization – permission-bound access; it still depends on the documentation behind it being correct. ## Further reading - The original proposal and the format description: [llmstxt.org](https://llmstxt.org/) - Repository for the proposal: [AnswerDotAI/llms-txt](https://github.com/answerdotai/llms-txt) - MCP docs server that reads `llms.txt` as a source: [langchain-ai/mcpdoc](https://github.com/langchain-ai/mcpdoc) - Model Context Protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io/) --- # Tools That Hold Up: Concepts, Methods, Processes URL: https://www.mikebild.dev/en/blog/tools-that-hold-up-concepts-methods-processes-article/ Date: 2026-07-15 There is no installation package for an agent that represents a domain in a binding way. You can install available model weights and runtimes; you can implement or connect protocols. Model weights and runtimes alone, however, do not enforce a domain approval and do not produce meaningful domain evidence of who decided what. The binding part only emerges when you engage with your own domain – with its terms, its rules and the people who stand behind both. The way there can be learned, though, and it is less spectacular than many framework debates suggest. *Part 12 of the series “From Session to System” – [start with the opening post](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).* The [previous post](https://www.mikebild.dev/en/blog/ai-agents-per-domain/) described what such an agent has to be able to do: check plans before they take effect; approvals that no model can talk its way around; evidence that answers the questions of the day after tomorrow. What remained open was the way there. It leads through three kinds of tools: concepts that hold up. Methods that keep the start small. And processes that keep the whole thing alive in operation once attention moves on. One at a time. ## Concepts: none of this is new If you go through the list of capabilities from the previous post, you will not find a single AI invention in it. Domain language and domain boundaries – that a system should speak the terms of its domain and that those terms are only unambiguous within a defined context – were described by Eric Evans a good twenty years ago in “Domain-Driven Design” as ubiquitous language and bounded context. Every organization that reviews changes before rolling them out knows the separation of proposal and effect, from the four-eyes principle in accounting to `terraform plan` and `apply`. Validation, authorization and audit are the basic toolkit of any serious business application. And that answers [have to rest on real sources instead of plausible guessing](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/) and that [curated knowledge needs a cycle with owners](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/) was covered in the middle posts of this series – at its core that, too, is documentation and library work, not magic. The only new thing is the consumer: a loop in which a model acts, instead of a UI where people click. For choosing concepts, that is a small shift. Since then, one simple test question has helped me: did this concept hold up before there was AI? Domain boundaries, approval workflows, versioning, audit – yes, for decades. An orchestration framework that has existed for four months – probably not. That is not a dismissal of everything new; somewhere the next concept that holds up is actually emerging right now. But the burden of proof lies with the new, not with the proven. A natural building block shows that the old concepts carry over directly into agent systems: a workflow engine can separate mission, plan, run and the authority granted for it – and use the same planning path for HTTP, MCP, A2A, webhooks and chat. That is the old separation of proposal and effect, applied consistently to every input channel: no matter where an initiative comes from, it takes the same planning path. For the reflex to design the whole organization as an agent landscape right away, there is an old concept as well, and it hits harder than any technical question. John Gall phrased it in the seventies as an observation about systems: “A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over, beginning with a working simple system.” Twelve connected agents on a whiteboard are the design from scratch. The first process that actually runs and delivers a verifiable result is the beginning of the system. ## Method: take inventory of the rules first The first of the three questions from the end of the previous post was: which rules belong in the path, and which may stay prose? The answer does not start with technology, but with an inventory that is less popular than it needs to be. For the inventory, I would first check four places: the wiki, instruction files such as CLAUDE.md or AGENTS.md, code review comments – and heads, as in the knowledge of that one colleague you ask before every price change, just to be safe. This list is not complete; depending on the organization, tickets, policies, configuration or business procedures come on top. The inventory brings the rules into one place and notes four things for each: where is it written? How binding is it meant to be? What happens if it is violated? And how often was it actually violated recently? The last column is the most important, because it replaces opinion with findings. In the chronicle of my instruction files, the sobering lesson was that written rules remain recommendations; in the [post about tools](https://www.mikebild.dev/en/blog/agent-model-domain/), that turned into a transition criterion: when the same rule shows up in an instruction file for the third time and has been ignored for the second time, it is a candidate for enforcement in the path. The inventory turns this gut feeling into a list: ```yaml # rule inventory, one entry per rule - rule: "Credit notes above 500 EUR require team lead approval" source: wiki, AGENTS.md violation_impact: money leaves the company violated_recently: twice in Q2 decision: enforce # goes into the path - rule: "Use the customer number, not the invoice number, in replies" source: onboarding notes violation_impact: confusion, no damage violated_recently: unknown decision: prose # stays a convention ``` For classifying them, I consider three questions a solid starting point, and they match the criteria that have gradually emerged in this series: does a violation move money, personal data or effects to the outside? Does someone have to be able to prove afterwards who decided what and when? Was the rule broken repeatedly despite clean documentation – by people or by the model? A yes to any of these questions is my starting point for taking the rule into the path: check, approval, evidence. It remains a starting heuristic, though – where the possible damage is small, a mistake is easy to undo or existing controls catch it anyway, a rule can stay prose even with a yes. Three times no, and it stays prose – as a convention that the model reads and mostly follows, and whose remaining risk has been explicitly accepted. The inventory has a second yield that is easy to overlook: it finds dead rules. Requirements that nobody has needed for years, whose reason disappeared long ago, but which are still dragged along in every document. Those go – not into the path, but out entirely. An agent that represents a domain is also an opportunity to declutter the domain itself. ## Method: cut the first domain small The second question: how do you cut the first domain without overreaching? The short answer: one process, not one department. A department bundles many states and responsibilities that are never finished at the same time; a process has a verifiable beginning and a verifiable end. “Accounting” is therefore not a cut but a box on an org chart. “Credit notes and dunning stops” is one – a well-delimited process with a beginning, an end and a handful of verbs. How you recognize a suitable first candidate: - The process has a clear beginning and a clear end – no permanent state, no umbrella term. - A handful of verbs is enough: at the latest when the tool list reaches double digits during modeling, I would review the cut again. - There is already a person responsible for the domain today – the role that approves and decides even without AI. - The pain is documented: violations have actually happened in the past and demonstrably caused trouble. - The damage potential justifies the effort but stays manageable – credit notes yes, international payments maybe only in the second year. The last point deserves a moment. The first domain agent is not just a tool; it is also the piece on which a team builds and operates the three capabilities – check, approval, evidence – for the first time. You choose such first pieces so that mistakes are instructive, not existential. A small cut also calls for a small transition. Nobody tears down the existing way of working and replaces it with the agent; the prose version remains the prototype from which rules move into the path one by one, as soon as their binding nature has been proven. For this pattern – the new grows along the old until the old is no longer needed – Martin Fowler coined the image of the strangler fig that grows around a tree. Applied to rules: first the 500 euro rule applies as a sentence in the instruction file, then additionally as a check in the path, and at some point the sentence is just documentation of the check. No big switchover day, no risky migration over a weekend. The rest of the big sketch does not die in the process – it becomes backlog, sorted by exactly the criteria above. That can feel like a retreat. It is the opposite: the first step that can actually be taken and delivers a verifiable result. ## Processes: owner, change path, rhythm That leaves the third kind of tool, and it is the one most easily underestimated. You can learn concepts, you can apply methods – processes you have to sustain in operation. I consider three of them load-bearing. First: every rule has an owner, and that owner sits in the business unit. Engineering owns the enforcement – the code that checks, the gate that waits, the log that writes. But whether 500 euros is the right threshold, whether “goodwill” and “pricing error” take different paths, is decided by the business side that has always carried this responsibility. The discussion about proposing, reviewing and approving rules is not an obstacle on the way to the process. It is the process – if you skip it, you have rules without legitimacy, and they erode at the first conflict. Second: rule changes take the same path as rules. Proposal, review, approval, versioning – the same care that is a given for code. That the evidence records the rule version in force was a side detail in the previous post; in operation it becomes the precondition for touching rules at all without reinterpreting the past. Two building blocks show what this can look like: a knowledge system can keep domain guidelines in a versioned charter that people are responsible for, and route changes to the derived knowledge base through a review process. A workflow engine can describe approved procedures as workflows that run repeatably and log every run – work that has not been described and approved is not improvised. Both are expressions of the same principle: the change path is built into the system. Third, and most important: learn from the noes, at a fixed rhythm. In operation, the agent produces two streams – executions and rejections. For rules that are too narrow or missing, the rejections are often the more fruitful starting point; samples of successful runs are still necessary, because an execution that was waved through can also contain a wrong decision. The rejection log therefore belongs on the table regularly – at first at a fixed interval of a few weeks, later depending on the rejection rate and damage potential – with three questions: which noes were right and stay? Which were too narrow and need an adjusted threshold or a new reason for a credit note? And which special cases come up so regularly that they deserve their own verb? This is the same cycle that [the post about curated knowledge](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/) described, just with rules instead of insights: operations deliver candidates, curation turns them into something binding – the organization changes rules and interfaces in the process; the model stays unchanged. ```mermaid flowchart LR I["Inventory
collect and assess rules"] --> K["Classification
path or prose"] K --> B["Build
verbs · check · approval"] B --> O["Operation
executions and rejections"] O --> S["Review at a rhythm
learn from the noes"] S --> I ``` Together, the three processes deliver what the previous post merely claimed: that such an agent is a product with a lifecycle. A product has owners, a change path and a cadence at which it gets better. If one of these is missing, it decays – faster with rules than with code, because an outdated threshold does not fail a build and therefore has to be caught deliberately through review or operational metrics. ## Fads you can skip And the opposite list? I consider four patterns attention sinks that improve neither check nor approval nor evidence – that is a judgment, not a measurement. The multi-agent orchestra from day one: many agents sending each other messages before even one of them enforces a single binding rule – the design from scratch cast in software. Frequent framework switching, where the domain logic sinks a bit deeper into vendor conventions each time; the antidote – domain logic in your own services, the tool layer as a thin adapter – was already in [the post about agent, model and domain](https://www.mikebild.dev/en/blog/agent-model-domain/). The model comparison table as a substitute for strategy, which [this series argued against early on](https://www.mikebild.dev/en/blog/good-enough-models/): whether several models solve your own tasks well enough is shown by a concrete check against exactly those tasks – and where that is the case, the energy belongs in your own share, not in the table. And endless polishing of wording: when the same instruction is reworded for the third time so that the model “finally understands” it, that is not a writing problem. It is the signal that the rule belongs in the path, not in nicer words. The test question is always the same, and it keeps the list short: does it help build check, approval or evidence – or does it just feel like progress? Many of the frameworks and agent patterns currently under discussion can be left to mature in peace. They are not going anywhere, and whatever holds up will still be there in a year. ## Where things stand With that, the three questions from the end of the previous post are answered, as well as I can after these months: with an inventory that delivers findings instead of opinions, a cut the size of one process, and processes that define owner, change path and rhythm. So I would start with a documented rule violation in a process that has already been cut small – that is where the pain is documented, the cut is small and the result is verifiable. The concepts behind it are old, and that is their most important property: they have held up before. A good eight months ago, this series began with a session on my computer and the observation that my work was changing; now the path ends, for the time being, at organizations that put rules, knowledge and responsibility into their own agents. The next post checks the expectations from the opening: what came true, what did not – and where does all of this lead? ## Further reading - [Domain-Driven Design Reference (Eric Evans)](https://www.domainlanguage.com/ddd/reference/) – ubiquitous language and bounded context as design work - [John Gall: Systemantics](https://en.wikipedia.org/wiki/John_Gall_%28author%29) – why working complex systems evolve from simple working systems - [Martin Fowler: Strangler Fig Application](https://martinfowler.com/bliki/StranglerFigApplication.html) – the pattern for transitions without a big switchover day - [Building Effective AI Agents (Anthropic)](https://www.anthropic.com/engineering/building-effective-agents) – the advice to start with the simplest setup that works --- # AI Agents per Domain: Rules, Approvals and Evidence URL: https://www.mikebild.dev/en/blog/ai-agents-per-domain/ Date: 2026-07-14 An AI agent per domain connects the tools of a field of work with its rules, permissions and case state. What matters is not another chat but an executable path that checks related actions before they take effect. This article shows which responsibility lies with the model, with the tool and with the agent system you operate. A constructed example: an agent is supposed to refund 740 euros as a goodwill gesture. Anything over 500 euros needs approval from the team lead. The tool call for 740 euros is rejected; two calls for 370 euros each, however, would pass a check that only looks at individual calls. Each call would be allowed on its own, but their combined effect would not. This is exactly the gap a rule over the whole case has to close. *Part 11 of the series “From Session to System” – [the opening post is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).* The example describes a possible weakness, not an observed incident. Whether a model would actually propose two partial amounts is an open question. The architecture still has to prevent this kind of workaround: a rule about a case cannot be expressed as an isolated check of individual calls alone. This installment thus keeps two promises the series has left open. The chronicle of my instruction files ended with the finding that only what the environment enforces is a rule. The [last installment](https://www.mikebild.dev/en/blog/agent-model-domain/) closed with the question of why binding rules lead to a dedicated agent tied to the domain – and what that agent has to be able to do. The credit note construction gives the short answer: rules need a place where the context is visible. ## A tool sees the call, not the case A reminder of where the series stands: the last installment moved the domain from the prompt into the tools – typed operations whose names come from the domain language, whose inputs are validated and whose calls are authorized. The check now runs in the executable path instead of in the prompt: the 500-euro rule went from a recommendation the model can read and weigh to code that decides the same way on every call. In this example, the check sees only one call. A tool can also load and check case state; what matters is that this responsibility is implemented explicitly. Without it, three things stay hidden. The context. Domain rules are rarely rules about calls – they are rules about cases. “No more than 500 euros in goodwill” means per case, per customer, per period. Two credit notes of 370 euros for the same case violate the rule without any single call violating it. An authorization that only receives the input of the current call cannot notice this – not because the tool is technically incapable, but because it lacks the bound case state. The effect. Some errors don’t show in a single step but only in the overall picture – in what will exist after twenty steps. If you only check after execution, you check too late; by then the credit note has already reached the customer. The memory. Whether a pattern is suspicious is decided across sessions: the same invoice, three times in two weeks, triggered by two different people. The individual call knows nothing about that, and neither does the individual tool. What the individual tool call lacks, the agent can bring together: the history, a materialized plan and persistent case state – provided these states are stored explicitly and bound to the case. That is why enforcement moves up one level – out of the tool and into the agent that runs the loop. The agent is then no longer an interchangeable accessory but the place where the binding rules of a domain live: an operated software system with a plan, permissions, approvals, evidence and clear ownership. ## From proposal to evidence: five stations What does this enforcement look like? The core idea is old and doesn’t come from the AI world: separate building from executing. If you run infrastructure as code, you know it as `terraform plan` and `terraform apply` – first you get a complete preview of what would change, then you decide separately whether it actually happens. Between proposal and effect sits a check, and it doesn’t look at a single move but at the whole undertaking. Applied to agents, the path from idea to effect has five stations. It starts with the model proposal: a textual or structured output, as eloquent as it is non-binding. Whether the model delivers prose or fully formatted tool calls – at first it only produces a statement of intent without authorized effect. Second, this becomes an executable plan: an ordered sequence of typed operations with concrete parameters, stored as an immutable revision and bound to the checked state; the operations and parameters are machine-readable, while a rationale can remain free text. Third, domain authorization: the plan is checked as a whole against the rules of the domain. This is where two credit notes for the same case stand out, where sum and frequency rules apply, and where it is decided whether the undertaking is allowed, rejected or requires approval. Fourth, where the rules demand it, human approval: a confirmation by a domain role that the model can neither grant nor replace – it may make proposals but may not confirm a human decision itself. And fifth, evidence, in two forms: decision evidence for every rejection and every approval, and execution evidence for every operation actually executed – who, what, when, with what result, under which rule version. ```mermaid flowchart LR M["Model proposal
textual or structured, non-binding"] --> P["Plan
all planned operations"] P --> R{"domain authorization
rules of the domain"} R -- "violated" --> N["Rejection
justified and logged"] R -- "requires approval" --> H["human approval"] R -- "allowed" --> D{"bound state
still current?"} H -- "confirmed" --> D H -- "rejected" --> A D -- "yes" --> E["Execution"] D -- "no" --> R E --> A["Decision or execution evidence
who · what · when · rule version"] N --> A ``` Anyone who works with coding agents knows this on a small scale: first the diff, then the commit. The difference is that there a human looks voluntarily – and on a Friday afternoon sometimes doesn’t. In an agent that is responsible for a domain, the check is not a habit but part of the path. It happens whether anyone remembers it or not. ## A no that stays a no The second capability follows directly from the construction at the start. A model that runs into a rejection can rephrase, negotiate, look for detours. That wouldn’t be malice: searching on is exactly the behavior we appreciate elsewhere, when a model tackles a test failure three different ways until the build is green. Instead of trying to train this persistence away, you can give it a limit that is not up for negotiation. For that, the approval has to live outside the conversation. An operation that requires approval waits until a human confirms it – and no text in the context, however eloquent, moves this gate, because the gate doesn’t even read the text. The model can propose its two 370-euro credit notes as often as it likes: the sum rule triggers on the plan, the approval stays pending, and the case sits with the responsible human. What matters here is who gives this yes: not “some admin” but a role from the domain – the team lead who decides on 500-euro goodwill payments even without AI. The approval maps an existing domain responsibility; it doesn’t invent a new one. Sketched on the tool definition from the last installment, the extension looks roughly like this. The code block is a simplified, illustrative sketch: the API `defineTool` and the role `billing_team_lead` are freely chosen placeholders. ```ts const issueCreditNote = defineTool({ name: "issue_credit_note", input: z.object({ invoiceId: z.string(), amount: z.number().positive(), reason: z.enum(["complaint", "goodwill", "pricing_error"]), }), approval: { required: ({ input, history }) => input.amount + history.totalCreditedFor(input.invoiceId) > 500, approvers: ["billing_team_lead"], }, audit: { record: ["user", "input", "approval", "result"] }, }); ``` The crucial line is the one with `history`. The approval requirement doesn’t depend on the individual amount but on the sum across the case. The authoritative state lives in the domain, not in the conversation: the agent binds a checked state of the case to the plan and passes it as input to the authorization – exactly the view the isolated single-call check lacks. Binding alone isn’t enough, though: so that parallel calls can’t exceed the 500-euro limit after all, execution has to recheck the bound state against the current domain state beforehand and abort or reauthorize if it has changed in the meantime. ## Evidence instead of memory The third capability is the least conspicuous: every execution leaves evidence behind. Who triggered the case, which plan revision was checked, what exactly was executed, with which inputs, what came out, who approved it – and, easy to overlook: which version of the rules applied. Domain rules change. 500 euros becomes 300, an approval path gets rebuilt. When someone asks three months later why a credit note went through back then, the answer has to be able to say: under the rules as of March it was allowed, here is the entry. Such a log doesn’t exist because someone remembered to take notes. It exists because the path produces it – rejections included. The no leaves a trace too, and it is precisely the noes that show where rules are too tight or tools are cut too coarsely. Auditability is not a compliance exercise you bolt on afterwards. It is a property of the path, or it doesn’t exist. ## Why per domain So far, I have argued why binding rules belong in checkable state transitions and authorization boundaries rather than only in prompt prose. The second part of the question from the last installment is still open: why a *dedicated* agent per domain – and not one big agent that can do everything? Because each of the three capabilities requires domain knowledge. A plan check can only evaluate what it understands: that two credit notes belong to the same case, that a customer is in dunning, that “goodwill” and “pricing error” have different consequences – these are terms and relationships of a domain, not generic concepts. The approval needs roles that only exist there. The evidence has to be kept in the language in which someone will ask later. A generic agent can read files and run commands; it cannot know what an inadmissible credit note is. Then there are the permissions. An agent that carries the tools of all domains may need a correspondingly broad set of permissions if rights are not delegated and limited per call – and with such permanent rights it becomes a worthwhile target. OWASP lists “Excessive Agency” among its top 10 risks for LLM applications: too many tools, too broad permissions, too much autonomy in a single system. With his “lethal trifecta”, Simon Willison named the most toxic combination – access to private data, exposure to untrusted content and the ability to communicate externally, united in one agent. Cutting along domains is therefore also a security decision – but it only becomes an enforceable boundary with separate identities, permissions, states and interfaces: few tools, narrowly scoped permissions, a clear blast radius. The credit note agent cannot trigger deployments, and the deployment agent doesn’t know any customer data. And finally, knowledge. Curated insights, [grounded answers](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/), [knowledge that survives the session](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/) – all of this always belongs to a particular domain. An agent that is responsible for a domain carries its sources, its conventions, its special cases. Not as a cross-domain grab bag, but as a maintained, manageable collection with owners. This also closes the loop to the [variance from the team part of this series](https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/). Back then, the finding was: results vary between people, tasks and sessions, and files with rules change little about that. The domain agent doesn’t solve this problem by making people the same. It moves the line below which variance can do damage. Above it, everything stays different: how someone phrases, explores, delegates, which path a session takes. Below it, everything is the same: whatever takes effect in the end goes through the same authorization, the same approval, the same evidence – for the experienced colleague just as for the intern, on Friday afternoon just as on Tuesday morning. ## What your own agent has to be able to do With that, the question from the last installment can be answered compactly. An agent that is supposed to represent a domain in a binding way needs: - tools in the domain language – typed, validated, authorized - the separation of model proposal and effect, with a check of the whole plan instead of individual calls - rules about cases: sums, frequencies, relationships across calls and sessions - approvals in the path, outside the conversation, by roles of the domain - evidence of every execution and every rejection – with plan revision, rule revision, approval decision, caller, result and error status - the permissions of the respective caller instead of its own omnipotence – narrowly scoped, domain-specific - curated knowledge sources of the domain, with owners and maintenance Nothing on this list is something an experienced team wouldn’t have built long ago: validation, authorization, workflow, audit, permission model. The only new thing is what it’s for – not for a UI where people click, but for a loop in which a model acts. If you build an agent like this, you wrap ordinary, solid software around variable model proposals. That is exactly why the task is doable. Doable doesn’t mean on the side. What emerges here is an operated software system with a lifecycle, not a weekend project – the counter-calculation from the last installment still applies, from maintenance effort to the risk of building, out of sheer caution, a form with a chat UI. And it doesn’t belong to anyone alone: the rules come from the business side, enforcement comes from engineering, and neither can take over the other’s part. Regardless of the implementation effort, the team has to clarify who may propose, check and approve such rules in the future – that is organizational work. ## Where things stand The path of this series can now be told in three stations. Rules as prose: read, weighed, occasionally overruled – recommendations, the kind I spent half a year tightening in vain. Rules in the tool: checked on every call, reliable in detail, blind to the context. And rules in the path: a dedicated agent that knows the domain, checks plans before they take effect, obtains approvals no model can talk its way around, and produces evidence that answers the questions of the day after tomorrow. Only at this stage has the recommendation become a rule that holds even when nobody is looking. What this installment deliberately leaves open: the path there. No installed product automatically ships the rules of a domain – they emerge from engaging with the domain itself, and that immediately raises practical questions. How does a team find out which rules belong in the path and which may stay prose? How do you cut the first domain without overreaching? Which concepts, methods and processes hold up – and which fads can you safely skip? The next installment is about these tools. ## What SubKit contributes [SubKit](https://subkit.mikebild.dev/de/) is my tool for recurring processes: an assistant designs the workflow, a person checks it and approves its scope. Execution follows the defined steps; permissions and results become traceable. AI clients can use approved workflows as tools via MCP. This doesn’t replace modeling the domain. A case-based goodwill limit, shared case state and the handling of parallel requests have to be implemented explicitly in the respective process and the connected systems. SubKit doesn’t automatically supply the business rules for this. The [use cases](https://subkit.mikebild.dev/de/anwendungsfaelle/) show possible starting points; the article [MCP: When Software Offers Capabilities](https://www.mikebild.dev/en/blog/mcp-security-tools-permissions-and-approvals/) explains the role of the interface. ## Further reading - [Terraform: plan and apply](https://developer.hashicorp.com/terraform/cli/commands/plan) – separating proposal and effect in everyday infrastructure work - [OWASP Top 10 for LLM Applications: Excessive Agency](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/) – too many tools, too broad permissions, too much autonomy - [Simon Willison: The lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) – why the combination of data access, untrusted content and external communication is dangerous - [Domain-Driven Design Reference (Eric Evans)](https://www.domainlanguage.com/ddd/reference/) – domain language and domain boundaries as design work --- # MCP Security: Tools, Permissions and Approvals for AI Agents URL: https://www.mikebild.dev/en/blog/mcp-security-tools-permissions-and-approvals/ Date: 2026-07-13 # MCP Security: Tools, Permissions and Approvals for AI Agents An MCP tool can read data, publish a revision or call an external service. That turns a model response into an action with consequences. For developers and operators, the security question is therefore: Who may run which operation, on which data and after which approval? The Model Context Protocol standardizes the connection to such capabilities. You still have to enforce the rules of your application yourself. This article shows how, using a constructed publishing example: the same permissions across the web UI, HTTP and MCP, a verifiable approval before publishing, and a traceable way of handling retries and untrusted content. For context on the interfaces, here are the [differences between MCP, HTTP, webhooks and A2A](/en/blog/mcp-http-webhooks-and-a2a-explained-simply/). ## Not the app, but the capability The Model Context Protocol is an open standard that lets AI applications connect to external systems. The official documentation describes MCP as a connection between AI applications and data sources, tools and workflows. The specification talks about hosts, clients and servers: an LLM application is the host, a client sits inside it, and a server provides context or capabilities. At first, this sounds like integration infrastructure. In fact, it contains a bigger shift. An application is then no longer just a UI for humans. It is also a set of addressable capabilities for agents. The classic operating path looks like this: ```mermaid flowchart LR Human[Human] --> UI[UI] UI --> App[Application] App --> Result[Result] ``` The human opens a UI, looks for the right place, fills in fields, clicks preview, clicks publish, then checks the feed and search. The application is the visible bundle of interaction, domain logic and state. With an agent, a second path is added: ```mermaid flowchart LR Human[Human] --> Agent[Agent] Agent --> Validate[validate_markdown] Agent --> Preview[create_preview] Agent --> Publish[publish_revision] Agent --> Rollback[rollback_release] Agent --> Search[rebuild_search_index] ``` The UI doesn’t disappear because of this, and it doesn’t become secondary either. But it’s no longer the only access to the work. An agent doesn’t need to know where the button is. It needs to know which capability exists, which inputs it expects, which results come back and which rules apply. That’s the core: MCP makes software capabilities addressable for agents. What it doesn’t do: replace the product domain or push aside its human UI. ## A publishing system as an example The following publishing system is a constructed architecture example, not a finished integration and not a customer case. The flow is familiar: Markdown comes in, a preview is built, someone reviews it, and then a revision is published. If something goes wrong, you need a rollback. After the release, the index, feed and cache have to be right. In a classic UI, these steps are tied to pages and buttons. For humans, that makes sense: a good GUI shows context, can block invalid input and makes states such as approval status visible. For an agent, the same UI is a detour and a source of errors. It would have to click, wait, read from HTML, interpret, click again. That’s automation at the wrong level. As an MCP capability, the same step would look different: ```ts const publishRevision = defineTool({ name: "publish_revision", description: "Publish an approved content revision", inputSchema: { type: "object", properties: { site: { type: "string" }, revisionId: { type: "string" }, reason: { type: "string" } }, required: ["site", "revisionId", "reason"] } }); ``` The important part isn’t the specific syntax. The important part is the shift: an operating path becomes a named capability. `publish_revision` isn’t “click the green button.” It’s a domain operation with inputs, a result, permissions and errors. Once the operation exists in this form, an agent can work with it. It can call `validate_markdown` first, ask back when there are warnings, request a preview, check the approval status and only then publish. The agent doesn’t operate a screen. The MCP server described here gives it domain tools with an input schema and a permission check. ## Three access paths, one domain Such a publishing system can provide a domain-oriented tool surface under `/mcp` that runs through the same publishing domain as REST and the web UI. The MCP tools stay bound to the product scopes. What matters is what this construction is not: MCP isn’t a second system next to the product. The web UI, HTTP and MCP access the same publishing domain with its revisions and permission boundaries. The shared domain logic decides what applies – not the channel the request came through. This has a practical consequence for the tool list itself. Tools that the current principal isn’t allowed to use don’t need to appear in the list at all. So the agent only discovers capabilities its scopes allow. And where a human approval is required, the agent doesn’t provide that approval itself – it remains a separate step outside its reach. This filtering is more than convenience, but it’s visibility, not the actual protection. An agent that doesn’t see a tool in the list won’t discover it the regular way. Protection against unauthorized calls comes from server-side authorization; the tools stay bound to the scopes of the respective product. That’s why you can’t obtain a missing release permission by switching from the web UI to MCP. The access path changes, the permission doesn’t. ## Tool access is a permission An agent that writes text can produce nonsense. An agent that calls tools can produce effects. It can read data, change files, trigger releases or notify external systems. That’s why tool access isn’t a convenience feature but a permission. A tool being discoverable is not yet permission to act; the call remains an authorized operation that the system checks. In a remote MCP setup, these duties are split: according to the MCP specification, getting the user’s consent before a tool call is the host’s job, while the product checks every call on the server side against the principal’s scopes. The MCP specification itself says that such capabilities raise security and trust questions: users must be able to understand and control data access and operations, tools must be treated with caution, and hosts must obtain consent before tool calls. Consent and access control therefore belong in the execution path of every tool call. So in a production system, a tool definition isn’t enough. It needs a policy next to it: ```ts type ToolPolicy = { tool: string; allowedRoles: string[]; requiresApproval: boolean; requiresIdempotencyKey: boolean; maxRuntimeMs: number; }; type ToolAuditEntry = { tool: string; inputHash: string; idempotencyKey?: string; decision: "allowed" | "blocked" | "approved"; outcome: "succeeded" | "failed" | "unknown"; actorId: string; runId: string; }; ``` This turns “the agent may publish” into a verifiable rule. Who was allowed to make which call? Which input was used? Was an approval required? Was the call executed or blocked? For write operations, there is one more question: What happens if the agent repeats the same call after a timeout? An idempotency key only helps if the server binds it to the operation and its inputs, catches concurrent retries and stores the result reliably. With external side effects, the downstream service also has to recognize retries, or the system has to reconcile the unclear outcome. A key alone doesn’t guarantee a single execution. MCP standardizes how a tool is discovered and called. It doesn’t make the operation safe from a domain perspective, nor automatically idempotent or auditable. The capability being offered has to carry these properties itself. ## Prompt injection: content must not grant permissions An article that gets read in can contain instructions, for example to publish a different revision or to send data to an outside address. Treat such content as untrusted data. A prompt that tells the model to ignore such instructions isn’t sufficient access control. The allowed operations, target addresses and approvals have to be checked outside the document being read. Tool descriptions and labels like “read-only” aren’t proof of how a third-party server actually behaves either. Check which server you connect and which permissions you give it. The [security principles of the MCP specification](https://modelcontextprotocol.io/specification/2025-06-18#security-and-trust--safety) name this trust boundary explicitly. For a remote MCP server, securing authentication comes on top: check whether an access token was issued for your server; don’t pass received tokens on to downstream services unchecked. Request only the permissions you need. The official documentation on [MCP Security Best Practices](https://modelcontextprotocol.io/docs/2025-11-25/tutorials/security/security_best_practices) describes these measures and the risks of token passthrough. For the publishing example, I would check at least the following cases before going into production: - A user without publishing permission calls the tool directly: the server rejects it, even if the tool name is known. - An approval applies to revision A, but the call names revision B: the server rejects it. - A document asks for data to be sent to an outside address: the configured boundary stays in effect. - A call runs into a timeout: before another write attempt, its result is clarified or the retry is effectively deduplicated. - A failed or rejected operation appears in the history with its actual result. This is a checklist for this architecture example, not complete evidence of security. ## The wrong split and the right one I don’t believe that applications will fall apart into small MCP services and stop being products. A good application bundles more than functions: it bundles understanding, interaction, data model, permissions, feedback and responsibility. But at the edges, capabilities that used to be tied to operating paths become individually addressable. A capability is well cut when it’s understandable from a domain perspective, technically verifiable and operationally accountable. The wrong split would be a generic `run_sql` or `click_button` – a tool that bypasses the domain rules instead of carrying them. The better split is an operation with domain intent: `publish_revision`, `rollback_release`, `create_preview`. The agent shouldn’t work around the database. It should work within the same rules that apply to the web UI and HTTP. A standard takes away integration work, but not product responsibility. Anthropic introduced MCP at the end of 2024 to address exactly the problem that every new data source needed its own integration. The specification standardizes the exchange over JSON-RPC and describes resources, prompts and tools. Bad capabilities stay bad, even when they are offered in a standardized way. ## What happens to UIs The strongest version of the claim about the future goes like this: when agents operate software, GUIs become secondary. I think that’s wrong. Routine paths will shift. If I can tell an agent to review a draft, build a preview and show me only the deviations, I don’t want to click through five forms for that. This is especially true for recurring work that is well described and cleanly bounded. But humans need UIs for exploration, control, exceptions and trust. A preview is a GUI. A diff is a GUI. An audit log is a GUI. An approval dialog is a GUI. Precisely when agents execute more, good control UIs become more important. The control UI exists so that a human understands what an agent has done and steps in where their judgment is needed. So the control UI and MCP don’t compete for the same job. The control UI is aimed at human operation and control, MCP at agentic calls. Both are subject to the permission boundaries of the same domain. ## What I take away from this For me, MCP is less a spectacular technology than a good reason to describe software differently. Not only through the data a system holds, and not only through the UI it offers – but through the work it can do safely, traceably and verifiably. That’s an architecture question. If you publish capabilities only as a thin wrapper around internal functions, you’re probably building new risks. A domain split, permissions, idempotency and auditability create a controllable foundation for agents – they are not a quality guarantee. Not every application needs an MCP server right away. Many systems are better served by a good API, a CLI or a clear UI. Where it fits, though, this holds: software meant to be used by agents has to make its capabilities explicit – and it has to enforce the same permission boundaries across every access path. ## Where SubKit fits in In [SubKit](https://subkit.mikebild.dev/de/), AI helps you design a workflow. A person reviews the preview and approves its scope. After that, the defined workflow runs; the AI doesn’t decide on the further path during execution. Every run is checked for permissions and recorded. MCP is used in both directions: a workflow can serve as a tool for an AI client, and an external MCP server can be connected as a connector. Which external tools may be used is defined separately. The additional access path replaces neither the approval nor the permissions of the calling person. This is a concrete product reference, not a claim that SubKit makes every MCP server secure or automatically knows domain rules. The rules of your domain and the permissions of external systems still need to be checked. The article [AI Agents per Domain: Rules, Approvals and Evidence](/en/blog/ai-agents-per-domain/) goes deeper into how such rules can be separated from model decisions. :::note **Context and sources** The publishing system and the code snippets are constructed and illustrate architecture decisions. This article uses the MCP specification from June 18, 2025 and the linked Security Best Practices. The security sections were checked against these primary sources on November 9, 2026; this implies no statement about the security of any specific installation. The SubKit section is based on the confirmed product description from November 8, 2026. ::: ## Further reading - [Model Context Protocol: Specification 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) - [Model Context Protocol: Security Best Practices](https://modelcontextprotocol.io/docs/2025-11-25/tutorials/security/security_best_practices) - [Model Context Protocol: Introduction](https://modelcontextprotocol.io/docs/getting-started/intro) - [SubKit: workflows, approvals and operations](https://subkit.mikebild.dev/de/) --- # Agent, Model, Domain URL: https://www.mikebild.dev/en/blog/agent-model-domain/ Date: 2026-07-13 Some time ago, I sat in a meeting at a large enterprise that was supposed to decide on an “agent strategy” for the coming year. On the wall, a slide with three columns: three vendors, with checkmarks for features below them, prices per user, compliance seals. For an hour, the conversation revolved around the question of which agent was the best. At some point I asked a different question: What of all this actually belongs to us afterward? If we switch vendors in three years – what do we take with us? The room went quiet. Not because the question was particularly original, but because the slide had no answer to it. *Part 10 of the series “From Session to System” – [start here with the opener](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).* The [last episode](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/) ended with the question of whom I hand curated knowledge to – and where the generic agent reaches its limits. To answer it, I first have to take apart everything that gets packed into the word “agent.” Because the silent minute in the conference room had a simple reason: the group talked about agents as if they were a device you buy, set up and use. That picture is misleading – and precisely at the point where it gets expensive for the company. ## An agent is software What an agent really is can be said in one sentence. In the fall of 2025, Simon Willison put forward a useful working definition: an agent is a model that runs tools in a loop to achieve a goal. There is nothing more to it. No consciousness, no intent, no magic. There is a loop: the model gets a task and the history so far, proposes the next step, the agent executes it, the result flows back – until a stop condition applies. There are tools: functions that the agent offers the model and whose calls it executes. There is context: everything the agent gives the model, from files and search results to instructions. There is state: what persists between steps and beyond the session. And there are permissions: what the agent is allowed to execute at all, with whose rights, with what evidence. Each of these five things is ordinary software. In episode 3, I described how exactly this frame – the harness – makes the difference between an impressive tool and a useful one. Back then I meant it personally: my machine, my tools, my way of working. Today I read the same sentence organizationally. What applies to my command line applies all the more to the company: the model produces outputs, such as suggestions, classifications and wording. The agent determines the loop, context, state, permissions and tool integration. These parts can be designed. ## What you rent and what you can control This division of labor deserves a close look, because economically it describes two completely different things. A proprietary model that you get through a vendor’s API is rented: it belongs to the vendor, and you have a say in version changes only within the frame set by the API contract and the vendor. You own nothing of it – and that is acceptable as long as several models solve your own, concretely checked tasks well enough. If you build your strategy on “the best model,” you build on something you neither own nor control. I laid out this thought in detail [early in this series](https://www.mikebild.dev/en/blog/good-enough-models/). The agent layer, on the other hand, can be under your own control. The loop, the context building, the state, the permissions, above all the tools – all of this can be your own code and your own configuration, versionable, testable and reviewable. The integration is also becoming less proprietary: since December 2025, MCP, together with AGENTS.md and goose, sits with the Agentic AI Foundation under the umbrella of the Linux Foundation. That is no guarantee that every vendor provides the same capabilities in the same way. ```mermaid flowchart TB subgraph rented["rented – interchangeable"] M["Model
Suggestions · Classification · Language"] end subgraph owned["designable – under your own control"] A["Agent
Loop · Context · State · Permissions"] W["Tools and interfaces
typed operations"] F["Domain
Terms · Rules · Processes"] A --> W W --> F end A -- "requests" --> M M -- "suggests steps" --> A ``` If the model is rented and the integration increasingly standardized, one particularly important part remains your own: what a company puts into the agent. Its terms, its rules, its processes, its data – in short: its domain. That raises the question of this post. Where does the domain live? ## Option A: the domain as prose The obvious place is the prompt. In practice, that means instruction files such as CLAUDE.md or AGENTS.md, system prompts, attached policy documents. They then contain something like: “Credit notes over 500 euros may only be issued by a team lead. Customers in an ongoing dunning process receive no goodwill credit. Price changes apply only from the following month.” I do not want to belittle this option. It is fast: if there is an approved way to maintain it, the business department can change the text without touching the business application. The changed version is available to the model as soon as the agent loads it. For exploratory work, that is often enough – and at the beginning it is almost always the right way, because you first have to find out which rules are needed at all. But it is fragile, and structurally so, not just in its craftsmanship. First, prose is unchecked: nobody validates it, no compiler reports that sentence 12 and sentence 47 contradict each other, no type check notices that “500 euros” meant gross in one place and net in another. Second, for the model, prose is a recommendation, not a reliable enforcement mechanism – that was the central disillusionment of my futile attempts with instruction files: the model can follow instructions, but you cannot enforce compliance with them this way. Third, the session lottery kicks in: the same sentence is heeded today and skipped tomorrow, depending on what else is in the context. And fourth – in a company, this weighs heaviest – you can version the file, but not the behavior. The instruction file alone provides no deterministic, blocking check that prevents a credit note that breaks the rules; without an additional check, the violation only shows up afterward. Prose scales with the amount of knowledge. It does not scale with how binding that knowledge is. ## Option B: the domain as an interface The alternative: do not put the domain knowledge next to the agent but build it into its tools. Instead of giving the model generic database and file access and placing the rules next to it as text, the agent gets typed operations whose names come from the domain language and whose inputs are checked: ```ts const issueCreditNote = defineTool({ name: "issue_credit_note", description: "Issue a credit note for an existing invoice", input: z.object({ invoiceId: z.string(), amount: z.number().positive(), reason: z.enum(["complaint", "goodwill", "pricing_error"]), }), authorize: ({ user, input }) => input.amount <= 500 || user.hasRole("team_lead"), execute: (input, ctx) => billing.issueCreditNote(input, ctx.audit), }); ``` The difference is more fundamental than the short code block suggests. The 500-euro rule is no longer a request but code: it is checked on every call, the same in every session, regardless of the model’s mood of the day or the state of its context. It exists exactly once, it has an owner, a review, a test. The AI does the wording; the interface decides what is possible at all. This is the logical continuation of two thoughts from the last episodes. [Episode 8](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/) was about grounding answers: looking things up instead of guessing, real sources instead of plausible assumptions. A tool is grounded knowledge in executable form – the agent does not have to guess the credit note rules; it can only act within them. And [episode 9](https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/) was about knowledge that survives the session: a tool definition survives it on its own, because it is part of the system and not part of the conversation. The tool names connect directly to Domain-Driven Design: they become the binding domain language. What Eric Evans called “ubiquitous language” a good twenty years ago – a shared, precise language between the business side and development – gets a very tangible form of existence. If `issue_credit_note` and `waive_dunning_fee` are the only verbs the agent knows, the organization has to agree on what exactly these verbs mean. Modeling the tools is domain work, not infrastructure work. The interface can reliably check the inputs and permissions of individual calls; process rules spanning several calls need additional state checks and, where necessary, a check of the planned process. ## The counter-calculation So much for the opportunity. The same calculation includes lock-in, maintenance effort, responsibility and over-constraining. First, lock-in. Tool definitions, skill formats and agent configurations follow vendor conventions today. MCP standardizes the transport, not the semantics: the protocol defines how a tool is called, not how my credit note logic is structured. If you pour your domain logic directly into the formats of an agent framework, that is exactly where it will be in three years – and moving costs money. The remedy is an old one: put the domain logic into your own services and build the tool layer as a thin adapter. But you have to do it; it does not happen on its own, and under deadline pressure, the opposite happens regularly. Then the maintenance effort. Your own tool layer causes ongoing maintenance and operating effort. Business rules change: the 500-euro threshold becomes 300, a new credit reason is added, a role is restructured. Someone has to maintain, prioritize, test and roll that out – next to everything else. The prose option was so tempting partly because it hid this effort. The tool option makes it visible, and visibility at first feels like it makes things more expensive, even though the effort was only somewhere else before: in the corrections afterward. Third, reviewability and responsibility. Who is liable for a tool definition? The question sounds legal, but it is above all organizational. With purely advisory use, a human can reject the answer. If the agent may execute tools without approval, an error in their authorization can take effect immediately: a wrong upper limit then applies reliably wrong, in every session, for every user. Tool definitions therefore need the same care as any production interface: review, tests, clear ownership, change history. And responsibility shifts noticeably: away from the individual who wrote a prompt, toward the team that defined the tool. That is consistent and right – but an organization has to want it, decide it and bear it. And finally, over-constraining. After the first incident, it is tempting to define away every conceivable deviation until the agent knows only a single, narrow path. Then you have built a form with a chat UI in front of it – more expensive, slower and moodier than the form would have been. The model’s strength lies precisely in the unforeseen: in the special case, in the follow-up question, in the connection between two cases that nobody thought of during the design. If you give the agent tools only for the expected, you could have had classic automation more cheaply. Tools that are too narrow can limit risks, but they can also take away so much room for action that classic automation would be the better fit. ## When generic tools are enough – and when they are not For my decision, four criteria matter: the kind of work, the people responsible, the potential for damage and the maturity of the domain knowledge. Generic tools – file access, shell, search – go surprisingly far as long as a few conditions come together: - The work is exploratory: analyzing, prototyping, researching, migrating – tasks whose result a human reviews anyway. - A single person is working who owns the result and can judge it themselves. - The potential for damage is small: everything is reversible, nothing leaves the building, no money moves. - The domain knowledge is still in flux – it would simply be too early to pour it into interfaces. Conversely, the domain belongs in the agent as soon as the picture flips: - A process repeats in the team: the same operation, many people, different levels of care and experience. - Rules are binding, not recommended – they must also hold at 5 p.m. on a Friday afternoon. - There are audit or evidence obligations: who triggered what and when, with what justification? - The potential for damage is high: money, personal data, external impact. In between, I use a pragmatic transition: the prose option is the prototype of the interface. When the same rule shows up in an instruction file for the third time – and has been ignored for the second time – it is a candidate for a tool for me. That way, the domain moves piece by piece from recommendation into structure, following how binding it actually is rather than a big up-front plan. ## Where things stand For me, the series so far shifts responsibility from the session to the system. It started with the session: the experience that the models are good enough for my work and that the difference lies in my own frame – tools, context, way of working. Then came the team: the disillusionment that my success at work cannot be copied by file and that instruction files remain recommendations, however carefully you write them. Then knowledge: clean grounding instead of convincing guessing, curated insights that survive sessions. And now the system: the insight that the model is rented and stays rented – and that the part you can control in the long run lies in the agent. More precisely: in the tools through which the agent touches the domain. What remains open is the question of how binding rules are enforced across individual tool calls. Tools decide what is possible in a single call – beyond that, you need approvals before something takes effect; traceability after it has taken effect; a no that stays a no, even when the model keeps phrasing things politely. Why this ultimately leads to an agent of your own, bound to the domain – and what it has to be able to do – deserves a post of its own. ## Further reading - [Building Effective AI agents](https://www.anthropic.com/engineering/building-effective-agents) – Anthropic’s distinction between workflows and agents - [Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents) – tool design for agents from practice - [Designing agentic loops](https://simonwillison.net/2025/Sep/30/designing-agentic-loops/) – Simon Willison on loops, tools and stop conditions - [Model Context Protocol](https://modelcontextprotocol.io/) – specification and documentation of the tool protocol - [Founding of the Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) – MCP, AGENTS.md and goose under the umbrella of the Linux Foundation --- # Knowledge That Survives the Session URL: https://www.mikebild.dev/en/blog/knowledge-that-survives-the-session/ Date: 2026-06-23 Tuesday morning, the third session this week. I’m typing the same explanation for the third time. Our error model distinguishes between expected and unexpected errors; expected errors come back as values, and there should be no try/catch cascades around service calls. The session before knew that. It had understood it, applied it and even cleanly solved an edge case I wouldn’t have thought of myself. Now I’m sitting in a new session again without that explanation and writing it once more, in different words, a bit more impatiently than last time. *Part 9 of the series “From Session to System” – [the opening post is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).* This is session amnesia as an everyday experience. Not as a theoretical problem of context windows and token budgets, but as the quiet annoyance of working with a tool that hears from me for the first time every morning. The vendors are working on it. As of August 2026, there are different storage mechanisms for this: Anthropic’s Memory Tool lets agents store information outside the immediate context window in files and load it again later; Claude Code provides project instructions through hierarchical CLAUDE.md files and personal notes through Auto Memory, both across sessions. Personal Auto Memory starts with the individual person; shared, jointly maintained CLAUDE.md files are a different matter. None of these features solves the variant of the problem that really occupies me on its own. Because the team variant is worse. On Wednesday, a colleague tells me he explained our error model to “his” session. I ask how. He explained it differently than I did. Not wrong – differently. Different terms, different examples, one nuance I would leave out, one I’m missing. A third colleague didn’t explain it at all, because he didn’t know there was anything to explain; his session built try/catch cascades, and the pull request looked like it. Four people, four private explanations of the same convention, four slightly different results. This is exactly the variance problem I described in [“My Success Cannot Be Copied”](https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/) – except that here it’s not about ways of working but about knowledge. Each of us feeds our sessions with our own oral tradition of what the team should actually know together. Personal Auto Memory doesn’t change that: it remembers my version of the explanation, not ours. Versioned, jointly maintained CLAUDE.md files would be the place for a shared version – but only if the team curates them deliberately. So the core question of this episode is: how does session knowledge become team knowledge – and eventually company knowledge? How does what comes out of a good session get into the next session of another person? ## Two kinds of knowledge To talk about this sensibly, a distinction helps me that I carried around only implicitly for a long time: curated knowledge and emergent knowledge. Curated knowledge is deliberately distilled. Someone sat down and put an experience or a decision into words, someone else proofread it, and the result sits in a place where it gets found. Architecture decisions in ADRs, conventions in a CLAUDE.md or AGENTS.md, a runbook for the deployment edge case that strikes every six months. Curated knowledge is expensive – it costs the time of one person who writes it down and of a second who reviews it. In return, it is addressable: I can point to it, link to it, hand it to a session. Emergent knowledge comes about on the side. In Tuesday’s session, half a dozen small insights came up: that our test setup has a quirk when mocking the message broker, that a certain library in version 4 has a different default behavior than our docs say, that my prompt framing for refactorings works better when I put the target picture before the constraints. I wrote none of it down. The session ended, and with it everything evaporated that didn’t solidify into code or a commit message. Emergent knowledge is cheap to create – and not reliably available to later sessions unless it was saved. The gap between the two is the real problem. Teams today produce more emergent knowledge in AI sessions than ever before – every session is a small lab where someone tries things out, phrases things, fails, readjusts. And almost none of it survives. What survives is the code. But the code contains only the result, not the reasoning, not the discarded wrong turn, not the phrasing that untied the knot. ## Treating knowledge like code A team’s distilled working knowledge deserves the same treatment as its code. Versioned. Reviewed. With ownership. And with a lifecycle that includes dying. That is where this episode is headed. At first that sounds trivial – Docs as Code means treating documentation with the same versioned ways of working as source code, including review and automated checks. But in the AI context, each of these four properties gets a new edge: - Versioned, because the knowledge is now consumed by machines. When an instruction file changes, the behavior of the sessions that load it can change. Such changes affect the behavior of the system – and behavior changes belong in the history, with a diff and a date and the option to go back. - Reviewed, because a wrong convention now misleads not only human readers but also several sessions. A person reading a bad wiki article often notices that something is off. A session can’t recognize the error and will apply the wrong convention, as I described in [“Clean Grounding II: Grounding Answers”](https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/): whatever is in the context becomes the session’s reality, whether it’s true or not. - With ownership, because no one maintains knowledge that belongs to no one. Every convention file, every runbook needs a person who feels responsible. That’s not bureaucracy – it’s the simple answer to the question “Whom do I ask whether this still applies?” - With a lifecycle, because outdated knowledge is worse than none. This is the point I see underestimated most often. A session without a matching source can guess or ask; a session with outdated grounding guesses with a citation. It quotes the convention from 2024 that we dropped in the fall, and sounds so well-supported that no one checks. The last point deserves its own paragraph because it is counterintuitive. We are trained to see documentation as “better than nothing.” In the AI context, that’s no longer true. Wrong, old, half-baked knowledge in a session’s grounding is actively harmful, because it turns the model’s uncertainty into false confidence. An empty directory forces me to think about what the session needs to know. A full directory that has never been cleaned out fools me into thinking that’s been taken care of. That is why the lifecycle also includes regular checks against the sources: does the convention still apply? Does the runbook still describe the system that is running? ## The cycle If you take this distinction seriously – emergent knowledge is created all the time, curated knowledge has an effect – a cycle follows almost inevitably. From these observations I derive four stations. First: learn from real runs. Not from opinions, not from blog posts, but from what actually happened in your own sessions. Which explanation worked? Where does the same follow-up question come up repeatedly? Which error shows up independently in several pull requests? The raw material is lying around – you just have to recognize it as raw material. Second: a human curates and approves. This is the decisive station, and it is deliberately not automated. Distilling means selecting, condensing, throwing away. Ten observations become one paragraph; one paragraph may become one line in the convention file; eight of the ten observations are discarded because they were one-offs. The team has to make this decision, because only the team can define what is binding from now on: what is a rule here, what was an exception and what should apply starting tomorrow. And the approval – a second pair of eyes, a real review – turns a private note into a shared commitment. Third: the distillate flows into the grounding of the next session. It sits in the file every session reads, or in the knowledge source that is pulled in during work. From that moment on, not every colleague has to explain the error model to “his” session orally and differently – the explanation is the same, for everyone, reviewed. Fourth: the next piece of work can get better. Not dramatically, not all at once. Whether the cycle works can be checked with concrete questions: does the follow-up question that kept repeating come up less often? Does the recurring error still show up in new pull requests? And the next runs produce new raw material – ideally at a slightly higher level. ```mermaid flowchart LR A["Real runs
and experiences"] --> B["Observe and
collect raw material"] B --> C["Human curates,
review approves"] C --> D["Distillate in the grounding
of the next session"] D --> A ``` This is not a framework and not a ceremony. To get started, a regular, short pass is enough, in which the team discusses what stuck, plus the discipline to treat changes to the knowledge files like code changes: branch, review, merge. How much effort is appropriate depends on the team, the scope and the risk. ## It’s not the model that gets smarter The point of this cycle only became clear to me over time, and it changed how I see the whole model debate: in this cycle, the model doesn’t get smarter. The organization learns: people select insights, justify them and make them reusable for others. The selected insights show up as versioned changes to the curated knowledge – not in a model retaining more context. At the end of the quarter, the model hasn’t automatically retained anything from our sessions as team knowledge. The version on offer may well have changed during that time – that doesn’t mean it knows our error model. What has improved is the layer around it: our curated knowledge, our explanations, the quality of what we give each session. And – this is the decisive difference – this layer belongs to us. We can read it, check it, correct it, roll it back. We can steer it. Which model version a vendor ships and how it behaves is something we can influence far less. If you locate the learning ability of your AI work in the model, you have a steering problem: you’re waiting for progress you can’t influence. If you locate it in curation, you have a work problem – more strenuous, but solvable. I consider that the most sober answer to the question of where a team should invest: in the part it owns. ## The anti-patterns Most of the attempts I’ve seen to capture session knowledge have failed. And in three recognizable ways. The prompt collection in the wiki. Someone creates a page: “Our best prompts.” For three weeks people contribute, then never again. After half a year, the page contains outdated prompts without context of use: for models no one uses anymore, for problems no one has anymore, without saying when they work and when they don’t. No one dares to delete, no one wants to maintain. The mistake is already in the form: a prompt without the situation it was distilled for is not knowledge but a souvenir. The instruction file dump. I already looked at this from a different angle in “Futile Attempts: Skills, AGENTS.md and the Limits of Recommendation”: convention files that everyone writes something into now and then and from which nothing ever drops out. After a year, there are two thousand lines in which rules contradict each other because the one from March doesn’t know the one from October. The sessions read everything and weight it somehow – the result is a lottery. A knowledge file without deletion discipline is not a knowledge file but a sediment basin. The written-down-once. The third variant is the quietest: in a good week, a motivated colleague writes everything down – thoroughly, structured, really useful. Then it’s never touched again. No ownership, no review rhythm, no occasion to update it. Twelve months later, parts of it may be outdated, and because no one knows which ones, no one trusts the rest anymore. The one-time heroic effort is the natural enemy of the cycle: it feels like a solution and prevents exactly the routine that would be one. All three patterns lack the same thing: the way back from the real work into the knowledge. They treat writing things down as an event instead of a cycle. ## The opportunity that costs work And still – or precisely because of this – I consider this moment an unusual opportunity. Organizations have been talking for decades about making implicit knowledge explicit. Knowledge management initiatives, wikis, communities of practice: my thesis is that the lack of an immediate consumer contributed to many of these initiatives petering out. Whoever wrote down their knowledge wrote for an abstract “later” and a hypothetical “someone.” The feedback was missing; writing things down remained a sacrifice without visible return. That is changing right now. AI sessions form an additional immediate consumer for explicit knowledge. If you distill a convention cleanly today, you can check it in the next session: does the AI behave differently? Does the pull request follow the convention? Does the familiar follow-up question stay away? The feedback loop that was missing in these cases can become much shorter in such workflows. AI thus creates an immediate incentive to make implicit knowledge explicit – and the next session gives early hints about whether what was written down holds up. I don’t want to hide the criticism of this. Curating costs the time of exactly the people who have the least of it. There is a real risk that the cycle gets out of hand and every line of convention has to pass through its own approval committee. And not all knowledge wants to be frozen – some of it is deliberately in flux, and if you distill it too early, you cement an interim state. The answer to that is moderation, not abstinence: start small, distill only what has repeated itself, and take deleting as seriously as writing. What keeps me busy at the end of this episode is a question one level deeper. Suppose the cycle is in place: the team curates, the knowledge survives the session, the organization learns. Then there is a growing body of distilled conventions, domain terms, decisions – and session after session, I hand it to a generic assistant that knows nothing about my domain and reconstructs everything from the context every time. At some point the question arises of whom I’m actually entrusting this knowledge to: is the generic agent with good grounding enough – or does the domain need a counterpart built for it? Where exactly the generic agent ends is the question of the next episode. ## Further reading - [AGENTS.md – the open format for agent instructions](https://agents.md/) - [Anthropic: Memory Tool – knowledge across sessions](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool) - [Claude Code: How Claude remembers your project](https://code.claude.com/docs/en/memory) - [Ikujiro Nonaka: The Knowledge-Creating Company (Harvard Business Review)](https://hbr.org/2007/07/the-knowledge-creating-company) - [Write the Docs: Docs as Code](https://www.writethedocs.org/guide/docs-as-code/) --- # Clean Grounding II: Grounding Answers URL: https://www.mikebild.dev/en/blog/clean-grounding-ii-grounding-answers/ Date: 2026-06-03 A few weeks ago, a colleague and I sat in front of a half-finished piece of integration. The AI was supposed to write a client for an internal API, and it did what it always does: it suggested `customerId`. In our system, the field is called `customer_ref` – for historical reasons that no one defends anymore but everyone knows. We had already explained that to the assistant twice that week. This time I did something different: I didn’t contradict it; I put the OpenAPI description of the API into the context. The next suggestion was right. Not roughly, but exactly – including the somewhat idiosyncratic pagination that no model in the world could have made up, because it was simply a decision of ours. Same model, same day, same task. The difference: it no longer had to guess. *Part 8 of the series “From Session to System” – [the opening post is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).* In the [last episode](https://www.mikebild.dev/en/blog/clean-grounding-i-why-ai-guesses-so-convincingly/), I described why AI guesses so convincingly: a language model uses symbols to refer to symbols, not to my systems. It knows a thousand APIs that look similar to mine – and that is exactly why it invents plausibly. That was the diagnosis. This episode is the constructive side: how do I give the AI my reality? For myself, I call this clean grounding – grounding answers instead of leaving them hanging in the air. And as so often, the core is less a tool than a sorting: what knowledge is there at all, where does it come from, and when does it belong in the context? ## My working model: three layers of knowledge When I look at what gives my answers solid ground in practice, I keep ending up with three layers. This is my sorting for this work, not a general taxonomy of knowledge. The layers differ not only in content but in their character – and that is the real point. ```mermaid flowchart TB subgraph Schichten["Three layers of knowledge"] K["Conventions
how we work
prescriptive, curated"] D["Documents
runbooks, specs, decisions
descriptive, aging"] S["API descriptions
OpenAPI, GraphQL introspection, schemas
machine-checkable"] end K --> E["Grounding while building
and preparing"] D --> E S --> E E --> A["Checked work result
document, plan, code, configured flow"] ``` The first layer is our **conventions and ways of working**. This is prescriptive knowledge: not “this is how the world is,” but “this is how we do it here.” Error handling belongs to the caller, migrations never run automatically, commit messages explain the why, reviews check the interface first. None of this is in an API description, and none of it can be guessed by a model – these are decisions, not facts. In episode 6, I told how I tried to pack exactly this knowledge into instruction files like AGENTS.md or CLAUDE.md – and where recommendations reach their limits. Giving up was not the lesson. This layer has to be small, dense and curated: a short list of rules the team stands behind can be followed and enforced in review. A long collection of hints competes with itself for attention. The second layer is our **documents**: runbooks, specifications, architecture decisions, operations notes. This is descriptive knowledge – it describes what applies here and why it came about this way. A recorded architecture decision can prevent the AI from overriding three-year-old system boundaries with its suggestion. A runbook explains what really needs to be done for a particular alert, instead of what sounds generically sensible. But I’ve learned to approach this layer with a certain skepticism: documents age. They describe the state of back then, not of today. A runbook that no one has touched in two years can mislead the AI just as much as its own guessing – only then the answer sounds even more convincing because it cites “our docs.” The third layer is **real API descriptions** – and it’s my favorite, because it has a character the other two lack: tools can read their structure, even if schema and runtime behavior can drift apart. An OpenAPI description, a GraphQL schema queried via [introspection](https://graphql.org/learn/introspection/), a JSON Schema, a database schema – that is not a colleague’s memory of the system but a machine-readable description of structure or API. Introspection shows the schema this environment offers at this point in time: if the field is called `customer_ref`, that’s what it says there. That proves neither correct resolvers nor agreement with other deployments or with data-dependent responses. Depending on the artifact, I can read field names, types or endpoints from it instead of guessing them from conventions or documents. The three layers answer different questions, and they don’t replace each other: - Conventions say **how** something should be built – style, boundaries, responsibilities. - Documents say **why** things are the way they are – context and history. - The respective API description names fields, types or endpoints. Whether the implementation matches this state and works has to be checked separately. If you supply only the third layer, you get code that matches the described contract but doesn’t necessarily work at runtime. If you supply only the first, you get stylistically clean code against an invented API. Only together do they ground an answer. ## Look it up instead of guessing The principle behind all three layers is the same, and it’s so unspectacular that it’s easy to read past: **look it up instead of guessing**. The easiest way to understand it is through an analogy everyone knows from the editor: IntelliSense. When I type `customer.` in my editor, the editor doesn’t guess which fields a customer probably has. It looks them up. A type-based editor derives suggestions from the available type definition, not from statistical similarity. Exactly this derivation is what a language model lacks when we let it work without grounding. An agent with suitable tools and read permissions can look things up. It can read an OpenAPI file, query a GraphQL schema via introspection, open a type definition in the repository. The [Model Context Protocol](https://modelcontextprotocol.io/) provides tools and context sources for this through a protocol contract. And such an agent can go one step further, beyond IntelliSense: it can **try** endpoints. A read-only call against the real API, a look at the actual response structure, and the next suggestion is based on observed data instead of invention. “This field probably exists” becomes “I have seen this field – in this response, with these permissions, in this environment and at this point in time.” That is a categorical difference, not a gradual one, even if a single response doesn’t prove the behavior for other data, permissions, environments and points in time. Exploratory read access must be authorized; whether it is free of side effects in domain terms has to be clarified beforehand. Such calls are valuable for research. Writing calls “just to try it out” are a topic of their own with their own safeguards – I’ll come to that later in this series. For grounding answers, the reading side is almost always enough. ## Grounding of repeatable workflows belongs at build time The second principle took longer to sink in for me, and it’s the one with the biggest consequences: **when** does grounding happen? Wherever a repeatable workflow has an artifact that can be checked in advance, grounding belongs at build and preparation time – not in the critical path of execution. If, on the other hand, the question only arises at runtime, the grounding has to happen there too. The diagram above shows this case for an artifact that can be checked in advance. At this point I have to place RAG, because it’s the first word in the room as soon as someone says “our own knowledge” and “AI” in the same sentence. Retrieval-Augmented Generation – described in 2020 by [Lewis and colleagues](https://arxiv.org/abs/2005.11401) – means: at query time, matching text passages are searched in a corpus and passed to the model. That is exactly right when the question only arises at runtime and the answer has to come from a body of documents – an assistant that answers questions about the handbook, a search across internal notes, support cases. Such cases correspond to the pattern of retrieval and generation described in the RAG paper. It goes wrong when RAG becomes the reflex for everything. Because retrieval at runtime has two properties that hurt in day-to-day work: additional latency and possible changes in results when the index, ranking or search method changes. Every execution searches anew, and what gets found depends on embeddings, rankings and the state of the index – the same workflow can see different text passages today than yesterday and therefore behave differently. For an exploratory question, that’s tolerable. For a workflow that runs every night and whose result people rely on, changing hits can lead to non-reproducible results. That is why, for such repeatable workflows, I pull grounding forward. The knowledge – the conventions, the documents, the API descriptions – flows in while something is being **created**: a document, a plan, a piece of code, a configured workflow. This work result is checked, by me or by a colleague, and from then on it is fixed. The later execution doesn’t roll the dice again; it executes what was checked. The difference is the same as between a program that guesses its dependencies from the network on every start and a build with pinned versions: all the uncertainty belongs in the fleeting, creative moment – it doesn’t belong in what then runs again every night. This is not a rejection of RAG but a clarification of responsibilities. Search across documents at runtime, where the question arises at runtime. Grounding at build time, where the result is an artifact that is meant to last. In my work, the second case is the more common one – yet it is still discussed in the vocabulary of the first. ## Context economics: what goes last The third principle sounds trivial and decides a surprising amount in practice: context is scarce. Yes, the windows have gotten big. But if you work with agent sessions for a while, you know that “big” doesn’t mean “inexhaustible” – long sessions, files read, tool outputs and intermediate states fill every window, and at some point things get trimmed, summarized, left out. Anthropic put this in a nutshell under the term context engineering: context is a finite resource; relevant information is found deliberately and loaded only when needed. A large, unfiltered context is not a mark of quality – the source that is authoritative for the task belongs in it at the time of the work. For my grounding, this leads to a prioritization rule: when something has to leave the context under pressure, I first remove material that can be looked up again in a targeted way. A long runbook stays in the context only with the paragraphs that are relevant right now. Small, task-relevant conventions I hold on to longer, because their loss is harder to notice. For a different task, this order can look different; what matters is relevance and the cost of fetching it again, not the name of the layer. That’s why I keep convention documents small and tailored to the task. A sprawling document competes with sources and tool outputs for space. Curating here means deciding deliberately what has to stay in the context for the next step. ## What grounding doesn’t do Honesty includes the counter-calculation, and I don’t want to squeeze it in at the end as if it were a footnote. Grounding doesn’t eliminate guessing. With the OpenAPI description loaded, the next suggestion contained no invented field names or structures. But a language model remains a language model: it can have a correct specification in the context and still draw a conclusion from it that doesn’t hold. It can read two documents together that contradict each other and elegantly bridge the contradiction instead of reporting it. And it can be grounded in an aged runbook – then the answer is cleanly reasoned and still wrong, only harder to recognize as wrong. So checking remains mandatory. The grounded work result is a better candidate, not a final verdict. What has changed for me is the kind of checking: I search less often for freely invented fields and more often for wrong conclusions from correct sources. That’s a better problem – the same kind of problem I would have with a human colleague who had conscientiously read up. But it is a problem, and grounding replaces neither consistency checks nor tests – without such checks, wrong conclusions can go undetected. One question hasn’t let go of me since. Everything I’ve described here grounds one session: the conventions, the documents, the interfaces flow into one working context, and at the end there is a checked result. But the session ends. The window closes, the context is gone – and with it everything the AI learned in those two hours about our system, our quirks, our corrections. Tomorrow I’ll explain `customer_ref` for the third time, or I’ll have found a way for knowledge to survive the session. What that can look like – without accumulating outdated, unfindable or unsupported entries – is the subject of the next episode. ## Further reading - [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) – Anthropic’s engineering post on context as a finite resource - [Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks](https://arxiv.org/abs/2005.11401) – the original RAG paper by Lewis et al. (2020) - [GraphQL Introspection](https://graphql.org/learn/introspection/) – how a GraphQL schema provides information about itself - [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) – the standard for machine-readable HTTP API descriptions - [Model Context Protocol](https://modelcontextprotocol.io/) – an open standard for giving AI tools access to real data sources and systems --- # AI in the Enterprise: Faster Development Needs Different Processes URL: https://www.mikebild.dev/en/blog/ai-in-the-enterprise-faster-development-different-processes/ Date: 2026-05-19 If implementation takes two days instead of five, but the change then waits twelve days for reviews, approvals and a shared test window, the product hardly reaches users any sooner. The local work got faster. The overall process did not. This is exactly the shift that AI exposes in large companies. A developer can prepare code, tests and a first draft of the documentation in a fraction of the previous time. In research and development (R&D), hypotheses can be tested faster and prototypes shown earlier. At the same time, dependencies between teams, contradictory documentation and long-grown approval rounds stay the same. The bottleneck moves from implementation into the organization. This is not an argument against large companies. Their formalities rarely came from a pure love of bureaucracy. Regulation, product liability, changing staff, distributed systems and software that has run for decades all need traceability. It becomes a problem when nobody can tell anymore which formality controls a real risk and which one only administers an old uncertainty. ## AI amplifies the workflow you already have At first glance, the productivity numbers don’t add up. Three field experiments at Microsoft, Accenture and another Fortune 100 company with a total of 4,867 developers found that users of a coding assistant completed about 26 percent more tasks; the effect varied with experience and context. A randomized METR study with experienced open-source developers, on the other hand, found 19 percent longer completion times with early-2025 tools. In February 2026, METR reported signs of better results with newer agentic tools, but itself considered the data too uncertain, due to selection effects, to put a number on the size of the benefit. The findings contradict each other less than it seems. Task, codebase, experience, tool and acceptance criteria all change the outcome. The [DORA Report 2025](https://dora.dev/research/2025/dora-report/) sums up the organizational part well: AI acts as an amplifier. Good feedback loops, well-maintained internal data and small changes benefit. Unclear ownership and cumbersome processes get amplified too. A survey result from the [Atlassian State of Developer Experience Report 2025](https://www.atlassian.com/teams/software-development/state-of-developer-experience-2025) points in the same direction: developers reported time saved through AI and, at the same time, weekly time lost to organizational friction. Self-reports like these are not a stopwatch. As a diagnosis, they are still useful: faster code does not remove waiting time. ## The ticket tree is not the product In a large company, a product idea can first become an initiative, below it an epic, several features, stories and subtasks. The business description lives in Confluence, an architecture decision in a comment, the acceptance condition in a ticket and the actual rule in the code. Each level makes sense on its own. Together, they create several truths. This often leads to a half-agile, half-waterfall approach. The team works in sprints but has to fix the content months in advance for budget, dependencies and committees. Questions end up as ticket comments because the spoken word doesn’t count as reliable. So people write more, without the documentation becoming any more consistent. When several systems are integrated, the number of alignment meetings grows faster than the number of domain decisions. AI should not fill this apparatus automatically. Otherwise you just get more epics, longer summaries and even more convincing-sounding comments. The better approach starts with a single, small description of the intent. Everything else is derived from it and stays versioned with the change. ```yaml change: id: customer-address-v2 outcome: reduce failed deliveries constraints: - preserve existing API clients - keep customer consent auditable owners: product: customer-experience technical: customer-platform evidence: - contract-tests - migration-report - rollback-plan risk: medium ``` This is not a new mandatory form. It is an example of a small, versioned change artifact that you can have a meaningful argument about. With read access to an indexed body of code and decisions, an agent may use it to gather the affected repositories, earlier decisions, contracts and tests. It may propose a plan, acceptance examples and documentation changes. Outcome, constraints, risk and owners are still decided by the team. The difference from the ticket tree lies in the direction: people don’t maintain five representations of the same change. The different views are generated from a few versioned sources. The ticket points to the artifact, the pull request shows the diff, and the documentation points to the decision. A summary for management may look different from the technical view, but both have to trace back to the same state. ## Integration needs contracts, not more alignment AI does not automatically make complex integration simple. An agent can read an unfamiliar service quickly and still miss a domain assumption that only the team running it knows. That is exactly why collaboration should depend less on prose and more on verifiable contracts. In the example of the changed customer address, the relevant event could exist as a schema: ```json { "$id": "CustomerAddressChanged.v2", "type": "object", "required": ["customerId", "address", "consentId"], "properties": { "customerId": { "type": "string" }, "address": { "$ref": "Address.v2.json" }, "consentId": { "type": "string" } } } ``` The AI can search the code for producers and consumers, write a compatibility report, add contract tests and prepare test data. The compatibility report has to cite repository, revision and location for every statement – for example, that the CRM already delivers `consentId`, that the shipping service ignores the field and that an old export works with `Address.v1`. That way, the research can be checked before a decision is based on it. It doesn’t have to make the decision. Whether an old address may still be processed is a domain question. Whether both versions run in parallel or an adapter is needed is an architecture decision. The agent collects evidence; the teams involved own the contract. This is exactly where [ADRs](https://www.mikebild.dev/en/blog/adrs-decisions-you-still-understand/) and executable specifications are valuable: they don’t record every conversation, only the result and its reasons. ## Documentation is derived, not abolished Confluence stays useful for explanations, entry points and overviews. It just shouldn’t be the third manually maintained copy of what the ticket and the code also describe. A page needs a named owner, a verifiable link to a contract, ADR or repository, and a visible update date. If that link is missing, an agent may flag the page as possibly outdated, but must not quietly declare it the truth. AI can generate different views from an approved change: release notes for users, a technical integration note and a short summary for the portfolio. Each text stays verifiable because it points to the same artifacts. People then don’t have to write every sentence three times. They check whether the derived view is right for its readers. This makes the documentation more consistent and the obligation smaller at the same time: what gets recorded is the decision, the contract and the operational consequence – not every intermediate stage of the discussion. ```mermaid flowchart LR Idea[Product idea] --> Ticket[Ticket hierarchy] Ticket --> Docs[Separate documentation] Docs --> Meetings[Alignment rounds] Meetings --> Build[Large implementation] Build --> Test[Shared test window] Test --> Approval[External approval] Intent[Versioned intent] --> SmallChange[Small change] SmallChange --> Evidence[Tests, contract and diff] Evidence --> Review[Peer Review] Review --> Release[Release] Release --> Feedback[User and operations signal] Feedback --> Intent ``` ## You become agile through the cost of a change Agility is not a particular board or a number of meetings. The original Agile Manifesto values working software over comprehensive documentation and responding to change over following a plan. Neither statement calls for carelessness. Both call for new information to actually be able to change the state of the work. Whether AI shortens research, prototyping or test design in a specific value stream has to be measured there. If it does, the cost of small experiments drops. R&D can then work more with hypotheses: What do we want to learn, which smallest experiment delivers evidence, and which result would change our direction? Product development can use the same rhythm. The prerequisite is small batches. More code generated in parallel makes the flow worse if review capacity stays the same. The result would be a new kind of inventory – half-finished pull requests instead of half-finished tickets. As with [developer productivity](https://www.mikebild.dev/en/blog/developer-productivity-shorter-cycles/), what counts is therefore not typing speed but the time to reliable feedback. [DORA metrics](https://www.mikebild.dev/en/blog/dora-metrics-what-really-shortens-cycles/) help with the diagnosis; they must not become a target for individual employees. ## Governance without a blanket queue Control is still necessary, but not every change deserves the same path. A text correction, a backward-compatible API extension and a new permission model have different potential for damage. Good governance makes this difference executable. The NIST AI Risk Management Framework follows the same idea at the level of the AI systems themselves: it structures risk management through governance, measurement and ongoing management instead of a single blanket approval. ```yaml approval_policy: - risk: low requires: [tests, policy-checks, peer-review] decision: peer-approved - risk: medium requires: [tests, contract-checks, owner-review, rollback-plan] decision: peer-approved - risk: high requires: [security-review, compliance-review, business-owner, audit-record] decision: manually-approved ``` This YAML file, too, is only a sketch, not a finished policy language. Automated checks produce the same evidence for every change. People review where context, liability or effects that are hard to reverse come into play. DORA recommends replacing heavyweight external change approvals with peer review, continuous testing, monitoring and targeted extra review of risky changes. That means less bureaucracy and more precise control at the same time. ```mermaid flowchart TD Change[Change with evidence] --> Risk{Risk class} Risk -->|low| Guardrails[Automatic guardrails] Guardrails --> Peer[Peer Review] Peer --> Release[Release] Risk -->|medium| Owner[Domain and technical owner] Owner --> Release Risk -->|high| Specialist[Security, compliance and business] Specialist --> Approval{Approval} Approval -->|yes| Release Approval -->|no| Rework[Rework or discard] ``` The EU AI Act makes a second distinction important. Article 4 of [Regulation (EU) 2024/1689](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32024R1689) on AI literacy has applied since February 2, 2025: providers and deployers must take measures to ensure that people who work with AI systems on their behalf have a sufficient level of AI literacy. Annex III, point 4 of the regulation covers – depending on the intended purpose – among other things systems that evaluate or monitor employees or allocate tasks based on individual behavior or personal traits. A productivity ranking built from process data does not automatically fall under it. But if it is used for HR decisions, performance evaluation or task allocation, it sits in a legally particularly sensitive area. Governance should protect the work, not put people under general suspicion. ## The organization has to follow the workflow A new assistant alone doesn’t change an org chart. In the long run, though, an organization with many handoffs is a poor fit for a way of working that is supposed to learn in short loops. For value streams with frequent cross-team changes, three structures become more important: - long-lived, cross-functional product teams that own an outcome from idea to operation and can approve small changes themselves - an internal platform that offers secure access to code, documentation, test environments and approved AI models as the default path - governance, security and architecture groups that design rules, reference solutions and exceptions instead of waving through every normal change individually This matches the pattern I already described for [simpler design and less process](https://www.mikebild.dev/en/blog/simple-design-can-save-process/): first make the change small and its expectations explicit, then remove the process step that this makes unnecessary. A locally measured time saving does not replace this architecture work. For the roles involved, the focus shifts: | Role | New focus | | --- | --- | | Developers | Slicing tasks, providing context, reviewing generated changes, designing tests and operational signals | | Architects | Designing system contracts, automated architecture rules, reversibility and safe default paths | | Product owners | Sharpening outcomes, acceptance examples and user feedback instead of managing the ticket backlog | | Project management | Reducing dependencies, risks, waiting times and work in progress instead of planning activities in detail up front | None of these roles disappears. On the contrary: the cheaper it becomes to generate proposals, the more valuable selection, judgment and responsibility become. The [result of a single AI power user cannot simply be transferred to an enterprise](https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/). Teams need shared review criteria, time to learn and a workflow that makes differences visible. ## Start small and measure the whole cycle A company-wide transformation program would be a contradictory start. A single value stream with a recurring change whose risk is known works better. There you can map today’s path from request to operation: How long is work being done, how long is it waiting, how often is the same information transferred, and where does rework happen? A first attempt needs only a few steps: - define a versioned change artifact and the leading sources - give the AI read-only access and log its context in a traceable way - generate tests, contract checks and documentation diffs automatically as evidence - at first, send only small, reversible changes through the new path - compare lead time, waiting time, number of handoffs, rework, change fail rate and time to user feedback I would not measure generated lines of code, closed tickets or individual prompt activity. Numbers like these reward volume. I would measure the inventory of half-finished work, the share of a predefined sample of documents that contradicts a named contract, ADR or repository state, and the time from opening a review request to the first approval or concrete change request. The share of releases that go through the controlled path measures process coverage, not impact. ## Conclusion The cumbersome processes of large companies are not a law of nature, but they are not just past stupidity either. They preserve ownership, knowledge and control where technical means were long insufficient. AI changes this calculation because it can gather context faster, prepare evidence and support recurring checks. The gain only materializes when the organization doesn’t fill the freed-up time with more output. Then changes get smaller, contracts replace part of the alignment and versioned artifacts avoid contradictory copies. Approvals follow risk instead of a blanket queue. People keep the decisions where domain knowledge, liability and consequences matter. That is how AI can actually make development and R&D more agile: not by filling out the old process faster, but by helping to make its detours unnecessary. ## Further reading - [DORA – State of AI-assisted Software Development 2025](https://dora.dev/research/2025/dora-report/) - [DORA – Capability Catalog](https://dora.dev/capabilities/) - [DORA – Streamlining Change Approval](https://dora.dev/capabilities/streamlining-change-approval/) - [DORA – Working in Small Batches](https://dora.dev/capabilities/working-in-small-batches/) - [DORA – Repository](https://github.com/dora-team/dora.dev) - [Microsoft Research – The Effects of Generative AI on High-Skilled Work](https://www.microsoft.com/en-us/research/publication/the-effects-of-generative-ai-on-high-skilled-work-evidence-from-three-field-experiments-with-software-developers/) - [METR – Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) - [METR – We Are Changing Our Developer Productivity Experiment Design](https://metr.org/blog/2026-02-24-uplift-update/) - [Atlassian – State of Developer Experience Report 2025](https://www.atlassian.com/teams/software-development/state-of-developer-experience-2025) - [Manifesto for Agile Software Development](https://agilemanifesto.org/) - [NIST – AI Risk Management Framework](https://airc.nist.gov/airmf-resources/airmf/5-sec-core/) - [European Commission – AI Literacy: Questions & Answers](https://digital-strategy.ec.europa.eu/en/faqs/ai-literacy-questions-answers) - [Regulation (EU) 2024/1689 – Artificial Intelligence Act](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32024R1689) --- # Clean Grounding I: Why AI Guesses So Convincingly URL: https://www.mikebild.dev/en/blog/clean-grounding-i-why-ai-guesses-so-convincingly/ Date: 2026-05-06 A few weeks ago I was sitting in a review of generated code. The assistant had suggested retry logic for our internal HTTP client – a client that exists only at our company, a thin TypeScript layer over `fetch` with a few in-house conventions. The suggestion: `client.withRetry({ backoff: "exponential", maxAttempts: 3 })`. Cleanly named, in the style of our codebase, with a comment on why exponential backoff was the right choice here. Plus a short explanation in the chat of how the method relates to our timeout handling. The method doesn’t exist. It never existed. Our client configures retries in a completely different place, when the instance is created, not at the call. But the frightening part wasn’t the mistake. I make mistakes too. The frightening part was the quality of the invention: the name fit our conventions perfectly, the signature looked like one of ours, the reasoning was sound from a domain point of view. If a human had suggested the method, I would have said: this person really knows our code well. Except that the suggestion was a complete guess – and was delivered with the same confidence as the twenty correct suggestions before it. *Part 7 of the series “From Session to System” – [the series opener is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).* If you work seriously with Copilot, Claude Code or Cursor, you can run into something like this. At first, I looked at such errors like a bug that should disappear with the next model generation. Today I don’t rely on that. Better models can reduce hallucinations, but they don’t reliably eliminate them – and since that became clear to me, I work differently with these systems. ## The model doesn’t reliably know the limit of its knowledge To understand why the invention sounded so convincing, I had to remind myself what a language model actually does: it continues text. From billions of examples it has learned which continuation is likely after a given beginning. That is not a disparaging simplification but the mechanism – and it is astonishingly powerful, as I described [in part 2 of this series](https://www.mikebild.dev/en/blog/good-enough-models/). But it has a property that can’t be argued away: true and false statements both arise as likely continuations; a truth check doesn’t automatically follow from this mechanism. A human developer – fallible as they are – has a sense of whether they know something or are guessing. If I ask a colleague about a method in our internal library, they answer either “it’s called this” or “I’d have to look it up”. This having-to-look-it-up is metacognition: knowledge about your own knowledge, a sense of your own uncertainty. Exactly this faculty is missing in the model. It has no inner state that distinguishes between “this appeared a thousand times in the training corpus” and “this sounds the way it ought to sound”. That’s why the confidence that irritates us so much is not arrogance but an artifact. The tone of a text is part of the continuation. Technical documentation, Stack Overflow answers, code comments – the material the model learned from is overwhelmingly written in a tone of certainty. Nobody documents an API with “I think this method exists”. So the invented method sounds like documentation too. The confident tone is not a signal of correctness. It never was. Two papers support parts of this explanation. In 2024, Ziwei Xu and colleagues argued formally that hallucinations cannot be completely eliminated for large language models. And in a publication of its own – available online as of August 2026 – OpenAI describes a second mechanism: training and evaluation incentives can push models toward guessing instead of admitting uncertainty. A model that says “I don’t know” when uncertain can score worse on benchmarks that reward correct answers but don’t properly account for abstentions than one that guesses confidently – just as a multiple-choice test teaches students to tick a box at random when they don’t know instead of leaving the field empty. ## Symbols that refer to symbols There is an even deeper level, and it is older than the current models. In 1990 – long before today’s large language models – the cognitive scientist Stevan Harnad formulated the *Symbol Grounding Problem*. His question: how does meaning get into a system that only manipulates symbols according to formal rules? His image: try to learn Chinese exclusively from a Chinese-Chinese dictionary. Every character is explained by other characters, and those in turn by more characters – you go around in circles without ever arriving at the thing itself. Symbols refer to symbols; nowhere does the system touch the world. I usually hesitate to drag cognitive science papers into everyday debates, because that often creates more fog than clarity. But here the analogy fits uncomfortably well. A language model knows text about the world, not the world. It has read what people have written about HTTP clients, about retries, about exponential backoff – and has learned statistical relationships between tokens from it. In any case, the answer in my opening scene gave no hint of a check against the thing itself: no compiler rejecting the call, no test turning red, no production alerting at three in the morning. Where I as a developer have calibrated my concepts against experience, the model has calibrated its concepts against other concepts. The dictionary explains itself, and it explains itself fluently. You don’t have to adopt Harnad’s problem in its full philosophical sharpness to see the practical core: a system whose entire “knowledge” consists of text statistics can’t tell a plausible invention from a fact, because both are made of the same stuff. For the model, `withRetry` was just as real as any method that actually exists – a likely symbol among other symbols. ## Why bigger models mitigate the problem but don’t solve it The objection is obvious: the models have gotten better, haven’t they? In my work, at any rate, I now rarely catch current models making things up freely when it comes to public, well-documented knowledge. But “more rarely” only means “less often”, not “fundamentally different”. The mechanism stays the same: a bigger model has learned finer statistical relationships – it guesses less often because it has seen more, not because it has stopped guessing. At the point where its material ends, it still produces the most likely continuation, in the same confident tone. The line between knowledge and guesswork moves outward, but it doesn’t disappear, and the model still doesn’t show it to me. That is exactly what makes the remaining cases so treacherous: the rarer the error, the less I expect it – and the more unchecked the suggestion goes through. ## Without internal sources, organization-specific facts remain guesswork And that brings me to the point that occupies me most in my daily work. Everything said so far applies to public knowledge – React, PostgreSQL, the AWS APIs. There I rarely see the model guess – the public material is huge. But the moment I open the door to a specific organization, the ratio flips. Because what counts there isn’t reliably accessible to the model without provided internal sources: - the internal libraries and services with their actual signatures and quirks - the in-house conventions – how errors are handled, how modules are split, what a deployment has to go through - the terms of the domain that mean something precise inside the company and something else or nothing at all outside it The case from the opening scene showed me how far this goes. The model had never seen our HTTP client, so it invented it – and did so in the way such a client typically looks. That’s why the suggestion was so good: it was the ideal form of an internal HTTP client, distilled from public patterns. Just not ours. Without an internal source, the actual signatures couldn’t reliably be derived by the model; the invention was an obvious move and looked deceptively similar to real knowledge, because the model is so good at continuing the style of a codebase. In hindsight, this also explains why my attempts with instruction files went so sobering – I told that story in detail in the last part. Back then I still thought the problem was compliance: the AI doesn’t stick to our rules, so the rules have to be stated more clearly, more strictly, more prominently. But even if an AGENTS.md were followed perfectly, it answers the wrong question. An instruction tells the system how to behave. It can’t give it what it actually lacks: the facts. “Don’t invent methods” is a helpless instruction to a system that doesn’t notice when it invents. The model doesn’t lack the will; it lacks the material. I was working on the motivation of a system that doesn’t have a motivation problem but a knowledge problem. ## Grounding: providing internal facts in the working context For this answer to the knowledge problem, I use the term grounding here – anchoring answers in verifiable facts. At its core, the idea is simple. If the model can’t know my reality from training, then I have to give it that reality at the time of the work: the real signature instead of the likely one, the actual schema instead of the typical one, our convention instead of the industry standard. Not as a rule of behavior, but as material. The model should be able to look things up instead of having to guess – roughly the way a good IDE with type information keeps me from typing method names from memory. Here I use grounding for providing concrete source material in the working context, and I thereby distinguish it from mere instructions that formulate rules of behavior. Grounding is not a product and not a feature you switch on. It is first of all an insight about the division of labor: the model provides language understanding, pattern recognition and synthesis – the facts about my world have to come from my world itself. And, to be honest, it isn’t a complete solution either. A grounded model can still connect the facts it was given incorrectly, and if you have ever tried to dump “simply all the documents” into the context, you know that this brings new problems. The difference lies elsewhere: with a grounded system, I argue about the quality of my sources. Without sources, I check free additions drawn from general patterns. With that, the conclusion of this part is settled, even if it saves no one any work: better models and stricter instructions don’t reliably eliminate convincing wrong answers. Grounding provides concrete source material where the system would otherwise have to fill in from general patterns. Which is where the real work begins – because “provide internal facts” is quickly said. Which facts, exactly, in what form, at which point in the workflow? That is not a rhetorical question but the next part. ## Further reading - [Stevan Harnad: The Symbol Grounding Problem (Physica D, 1990)](https://doi.org/10.1016/0167-2789(90)90087-6) – the original paper with the dictionary argument - [Ziwei Xu et al.: Hallucination is Inevitable – An Innate Limitation of Large Language Models (2024)](https://arxiv.org/abs/2401.11817) – the formal argument that hallucination cannot be eliminated for this class of models - [OpenAI: Why Language Models Hallucinate](https://openai.com/index/why-language-models-hallucinate/) – why training and evaluation incentives can reward guessing (retrieved in August 2026) - [Lilian Weng: Extrinsic Hallucinations in LLMs (2024)](https://lilianweng.github.io/posts/2024-07-07-hallucination/) – a detailed overview of causes, measurement and countermeasures --- # My Success Cannot Be Copied URL: https://www.mikebild.dev/en/blog/my-success-cannot-be-copied/ Date: 2026-03-04 In February, a colleague – an experienced developer with good judgment, no beginner – asked me whether he could have my setup. He had watched me work with Claude Code for weeks and wanted the same: the same tools, the same configuration, the same results. I gave him everything. The complete toolchain. My instruction files, grown over months. My prompt collection for recurring tasks, my checklists for reviews, even my notes on which tasks I delegate and which I do not. There was no secret remainder. He really had everything I have. *Part 5 of the series “From Session to System” – [start here with the opener](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).* Two weeks later, we sat down for coffee, and he was disillusioned. Not frustrated in the sense of “the tool is useless” – he had had some genuinely useful moments. But what he had seen with me, the matter-of-factness with which tasks go out and checked results come back, did not happen for him. For him, the AI went in the wrong direction three times, built things he did not want, and he spent more time cleaning up than he used to spend writing the code himself. His sentence stuck with me: “I have your setup. Why don’t I have your results?” The question occupied me longer than any tool problem of the past months. Because the obvious answers are all wrong. It was not the model – we used the same one. Not the configuration – it was identical, file for file. Not a lack of experience as a developer – he is at least as good as I am. What he was missing was not in any of the files I had given him. And that is exactly the point where this series has to make the leap: from me to the team. So far, I have described why the harness matters more than the model and [what makes me uneasy about my own way of working](https://www.mikebild.dev/en/blog/what-i-am-critical-of/). Both were the perspective of an individual. As soon as a second person comes into play, a problem shows up that I had previously only suspected: variance. And on three levels at once. ## First level: the same task, two sessions, two results The first level has nothing to do with my colleague yet. I can demonstrate it on my own machine. I give the same AI the same task twice – under largely the same visible conditions: same prompt, same repository, same instruction files. Session one decides to read the tests first, finds an existing pattern there and extends it cleanly. Session two jumps straight into the production code, considers a helper function unused, removes it “while it is at it” and delivers a solution that runs but is cut differently from everything around it. Both sessions got the same assignment. Both report confidently that they are done. The results differ in structure, style and side effects. In my runs, even early decisions differed – for example which file was read first or which pattern served as the model. After that, the subsequent steps diverged too. For me alone, that is manageable. I have learned to check results instead of prescribing paths, and in episode 3 I described how much of this the harness catches: tools, feedback loops, check steps. But even here, the mistake of confusing “best practices” with reproducible results becomes apparent: the same success case cannot be repeated exactly. When I show my colleague how great a session went yesterday, I am showing him a single run – even for me, the next one would look different. ## Second level: the knowledge that is in no file The second level is the one where my colleague actually failed. And it is more uncomfortable, because it disguises itself as a tool question but is a question of experience. When we talked through his disillusioning two weeks, I noticed: he did the same things I do – just in different places. He delegated, but the wrong tasks. He checked, but looked at the wrong things. He stopped, but too late. Three examples from our conversation: - He gave the AI a task I would never delegate as a whole – a change across three modules with unclear domain logic – and was surprised by the chaos. I would have cut it into three checkable chunks beforehand. This cut is not in any of my prompts; I make it in my head before I even start typing. - He read the AI’s explanations and found them convincing. I hardly read the explanations anymore – I look at the diff, the tests and the places where, in my experience, unwanted side effects occur. Where you look is judgment, not configuration. - He had a session make three rounds of fixes before he gave up. I stop after the first failed fix attempt and rephrase the task, because I have learned: once the direction is wrong, steering back costs more than starting over. That is not written down anywhere either – this stopping rule comes from repeated failed attempts. How you cut tasks, where you look when reviewing, when you stop – that is tacit knowledge in the classic sense. You acquire it through friction, not through reading. My instruction files are the sediment of this knowledge, but they are not the knowledge itself. They tell the AI what to do. They do not tell my colleague what *he* should do while the AI is working. The [METR study from summer 2025](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) made a related effect measurable: for experienced open source developers, tasks with early-2025 AI tools took 19 percent *longer* on average – even though the participants expected to save time. You can argue about how far the study generalizes; the conditions were special. But the documented finding fits what I saw with my colleague: expected time savings and measured working time can diverge. ## Third level: there is no identical run The third level is often overlooked because it sounds so banal: my colleague works on different tasks than I do. Not fundamentally different – same company, related systems, a similar stack. But his specific task on a specific Tuesday is never my specific task. His module has a different history, different legacy, different unwritten conventions. His bugs sit in different places. Even if he had my judgment and the session lottery went his way: he still could not reproduce my success, because the experimental setup “same task” simply does not exist in real work. That fundamentally distinguishes AI tools from almost everything we have introduced in teams before. Formatters and CI pipelines aim for reproducible execution under the same version, configuration and environment; a framework API provides the same contract. With these tools, the rule is: one person finds the good configuration, everyone adopts it, everyone gets the benefit. This exact pattern is what we all have in mind when we say “share the setup” – and this exact pattern does not apply here. The benefit of an AI session comes from the interplay of task, context, person and chance. Three of these four factors are different for every team member. ## What organizations regularly conclude wrongly from this At the organizational level, these differences can lead to false productivity assumptions. Because the individual observation “it works for Mike” invites three fallacies. The first fallacy: license bought means team productive. An enterprise procures access for all developers, books it as “AI adoption” and expects the productivity leap that the power users showed in the pilot project. But the power users were fast precisely because they had built up tacit knowledge over months. The license buys the tool, not the second level. The [2025 DORA report](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report) puts it in a formula I have been quoting constantly ever since: AI amplifies what is already there. Teams with good feedback loops and clean architecture get better; teams with weak processes get their weaknesses back amplified. The second fallacy: sharing a prompt library is a rollout. That was my own mistake with my colleague, just on a small scale. Prompts and instruction files are sediment – useful, but dead without the practice they came from. A shared prompt collection without shared judgment produces people who read convincing explanations instead of checking diffs. The [2025 Stack Overflow survey](https://survey.stackoverflow.co/2025/ai/) shows the consequences at scale: AI tools are widely used, but trust remains limited, and a frequently cited frustration is code that is “almost right.” Recognizing almost right is exactly the ability that cannot be distributed by file alone. The third fallacy: what works in the pilot scales linearly. It does not, because of all three levels of variance at once. A pilot can include motivated power users (person variance), selected tasks that are easy to cut (task variance) and selectively reported success stories – failed sessions may be missing from the management presentation (session variance). If you build a projection for 200 developers from that, you may be calculating with an unrepresentative average. I put it pointedly because I already used the sentence in [episode 4](https://www.mikebild.dev/en/blog/what-i-am-critical-of/) and here it describes the organizational consequence: the success stories of individuals are real, and they are still not a blueprint. Tools, tests, conventions and acceptance criteria can be copied. My concrete result also arises from task, context, review judgment and the course of the session. No setup file transfers that part. ## Variance is also a source of learning This sounds bleaker than I mean it. Because the same variance that prevents copying is a useful diagnostic source for a team. When my colleague and I dissected his two weeks, something remarkable happened: for the first time, I had to say out loud *why* I cut tasks the way I do. Why I ignore explanations and read diffs. Why I stop after one failed fix attempt. That was tacit knowledge that I had not perceived as knowledge myself – for me, it was simply “how you do it.” Only the difference between his way of working and mine made it visible. Exactly where two people do the same thing differently, the tacit knowledge lies in plain sight. You just have to look instead of dismissing the difference as a failure of the slower one. My conclusion after that February: if individual experiences are to flow together in a team, the prompts are not the valuable part. The differences are. Two developers, the same class of task, different results – that is not an annoyance; it is a finding. Each of these differences points to an unspoken rule, a heuristic, a piece of judgment that so far existed only in one head. By the way, my colleague still works with the setup – now with his own instruction files that differ more and more from mine, and with much better results. Not because he copies me better now, but because he stopped trying. What he took over from me is not the files. It is the questions he asks himself before every delegation. And that brings me to the consequence that every team sets out to draw at this point, mine included: if the decisive knowledge is tacit, then we simply make it explicit. We sit down, spell out the rules that so far existed only in heads and write them down – in exactly the files the AI reads in every session. Task cutting, review rules, stopping criteria, all of it goes in. That has to be enough. Why it is not – and why the AI follows our carefully written rules surprisingly selectively – is what the next episode is about. ## Further reading - [METR: Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) - [Google Cloud: Announcing the 2025 DORA Report](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report) - [Stack Overflow Developer Survey 2025: AI](https://survey.stackoverflow.co/2025/ai/) --- # What I Am Critical Of URL: https://www.mikebild.dev/en/blog/what-i-am-critical-of/ Date: 2026-02-10 On a Thursday evening in January, I almost waved through a pull request that I had commissioned myself. Claude Code had written a database migration, cleanly formatted, with comments, with a rollback path. I read it, nodded, already had the mouse pointer over the merge button – and then, more out of habit than mistrust, I took a look at the affected table in the staging system after all. The migration would have worked. It would just, on the side, have renamed a column that a report accesses, a report the session could not have known about. No drama, quickly found. But the moment before still occupies me today: I had not checked. I had read it the way you read a well-written text – benevolently, going with the flow. *Part 4 of the series “From Session to System” – [the series opener is here](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).* In the last installment, I described why delegating to AI only works for me with a good harness – with tools, feedback and guardrails around the model. At the end there was an unease that has grown louder with every delegated task. Today I want to take this unease seriously. Not as an alarm – I keep working with these tools every day, gladly and productively. But as what criticism should actually be: looking closely before you carry on. In doing so, I separate four observations from one open hypothesis. ## If you only review, you unlearn building When I rarely write code myself, I now have to distinguish more carefully: am I only missing an API signature, or am I missing practice in the routine? If you need a rarely used library function, you look up its signature – that has always been the case and is not a problem. The problem would be the direction of the movement: if it is no longer just the exception that gets looked up but the routine disappears altogether, the repetition from which fluency arises is missing. Whether and how fast this happens to me, I cannot measure. That is why I deliberately do certain routine tasks without AI and pay attention to where I lack practice. The CHI 2025 study by Microsoft Research and Carnegie Mellon surveyed 319 knowledge workers on this. In the self-reports, higher confidence in generative AI was associated with less critical thinking being applied. That is a correlation in a survey, not evidence that skills have already eroded. My worry goes one step further than the study’s result: if you hand off routine work and only deal with the exceptions, you could lose exactly the practice you need for the exceptions. For me, this is a creeping risk that I can actively manage. What concerns me more is what the math looks like for people starting their careers. I learned my craft by falling flat on my face often enough: hunting memory leaks myself, building race conditions myself and understanding them myself. If, during the learning phase, you mostly review generated code, you may get fewer opportunities to build up this substance – that is a guess, not a measurement, and the survey cited says nothing about it. Concretely, what would then be missing is the experience that makes good reviewing possible in the first place: being able to judge whether a timeout, a lock or an error handling approach fits your own system, because you have made such decisions yourself and borne their consequences. ## Plausible is not correct The scene from the beginning has a name: automation bias. A systematic review by Goddard, Roudsari and Wyatt describes it as the tendency to follow automated recommendations and overlook contradictory cues – the research on it is older than the current language models. In my migration, the clean formatting, the comments and the included rollback path amplified exactly this impression of trustworthiness: I almost approved what I had not checked. Whether review and the four-eyes principle work systematically worse against such plausible output than against visibly sloppy code, I cannot prove. In line with this, Perry and colleagues showed in a controlled study that participants with an AI assistant wrote insecure code more often and at the same time were more convinced that they had written secure code. The study does not examine code reviews. For my review practice, the combination is therefore a warning sign, not evidence of effectiveness. ## “That’s how the AI did it” is not an answer In a review, “That’s what the AI suggested to me” is not enough as a justification for me. The sentence explains the origin, but not the decision. Why is the timeout set to thirty seconds here? Why is that right for our system? If no answer follows, the decision is not justified in the review – because the session that chose the value ended long ago and took its reasons, if there were any, with it. In a review, there is no third party. There is the person who submits the code and the person who approves it – both with names, both reachable, both still around tomorrow. What the tool suggested is as relevant as the question of which editor the code was typed in. If you open a pull request, you are saying: I stand behind this. If this commitment dissolves because “the AI” is in the room as a diffuse co-author, the review loses its core. Then two people review something nobody feels responsible for. ## Debt that nobody took on Technical debt can arise from deliberate shortcuts: we build the quick solution now and clean up later. You knew the shortcuts you took deliberately and their consequences. Next to that, I see a possible second variant: code that works, passes all tests – and that nobody on the team really understands. Not because it is incomprehensible, but because nobody ever had to understand it. It was generated, it ran, it was merged. If a team only roughly follows a generated mechanism when it is built in, the next change may require reconstructing assumptions and the reasons behind decisions before the mechanism can be changed safely. Then technical debt may have arisen without anyone having taken it on deliberately – no note, no decision, no “we’ll clean up later.” Such debt can arise unnoticed because no deliberate shortcut was documented. A system that consists to a larger extent of such code is not broken. It is something worse: not understood while fully functional. ## When everyone asks the same model, designs can become more similar The last worry is an open hypothesis. A thought experiment makes it tangible: four groups get the same open-ended design task, and all four ask their first question to the same model. How different do the results turn out? If everyone starts with a very similar first answer, that answer can shape the rest of the design. The effect has not been measured and depends, among other things, on the prompt, context, sampling and model. The Microsoft study mentioned does not examine it. You can shrug and say: converging on proven patterns is a good thing. That is partly true – I am the last person to find an unusual solution good just because it is unusual. But architectural diversity is not an end in itself; it is a search process. Different designs make alternative assumptions and trade-offs visible. My worry is therefore: if many design decisions run through the same filter, the space of seriously considered alternatives narrows. I cannot measure that. ## Criticism does not mean rejection At this point, the text could tip over – into cultural pessimism, into “back then we still did real programming.” That would be convenient and wrong. None of these points is an argument against the tools. Each one is an argument against a particular way of using them: the passive one. Skills do not decay because AI exists but because I stop practicing. Automation bias strikes because I confuse plausibility with correctness. Responsibility diffuses because I let it diffuse. That is the catch: the answer does not lie in the next model release. It lies with me. I have set up a few rules for myself. No words of wisdom, more like house rules: - Regularly work deliberately without AI. Not a ritual of renunciation, more like a run without a watch: certain tasks – an algorithm, a data model, a tricky bug fix – by hand, to feel where it snags. Where it snags, I check whether I lack practice or whether I just do not have a rarely used API at hand. - An obligation to understand before the merge. Nothing goes into the main branch that I could not explain to a colleague at the whiteboard – line by line for critical spots. Critical spots are, for example, possible data loss, permission checks, concurrency and public APIs. “Roughly followed” does not count. - My own judgment first, then the model. For design questions, I write down my position in three sentences before I ask. It does not have to be the better one; it is an anchor against the plausible first answer – deviations then become real information. - Name the origin, keep the responsibility. When code was generated, I say so openly in the review – and take it on anyway as if I had typed it. None of this is original. The extra review costs me time, but it makes the approval more traceable. And I notice: it takes effort. In everyday work, it is easier to skip it. But this is exactly where the reach of this text ends. Everything I have described here are measures of an individual – my rules, my discipline, my house rules. That reaches exactly as far as my self-control does, and on bad days it reaches surprisingly little. A team cannot rely on the private discipline of its members; ten people with ten different sets of house rules do not yet make a shared way of working. What happens to these observations when not one person works like this but an entire team – with different experience, different levels of care and deadline pressure on top – that is the question I have set myself for the next installment. ## Further reading - [The Impact of Generative AI on Critical Thinking (Microsoft Research / Carnegie Mellon, CHI 2025)](https://www.microsoft.com/en-us/research/publication/the-impact-of-generative-ai-on-critical-thinking-self-reported-reductions-in-cognitive-effort-and-confidence-effects-from-a-survey-of-knowledge-workers/) - [Kate Goddard, Abdul Roudsari, Jeremy C. Wyatt: Automation bias – a systematic review of frequency, effect mediators, and mitigators (JAMIA, 2012)](https://academic.oup.com/jamia/article/19/1/121/732254) - [Neil Perry, Megha Srivastava, Deepak Kumar, Dan Boneh: Do Users Write More Insecure Code with AI Assistants? (arXiv, 2022)](https://arxiv.org/abs/2211.03622) --- # Good Enough: The Model Is Rarely the Bottleneck URL: https://www.mikebild.dev/en/blog/good-enough-models/ Date: 2025-12-09 *Part 2 of the series “From Session to System” – [start with the opening post](https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/).* End of November, an architecture review with a team I support, day two, first coffee break. A developer walks over to me, cup in hand, and asks the question that has come up in every team conversation and every hallway chat at conferences for two years: “Which model do you use?” This time with particular urgency, because November 2025 was wild: GPT-5.1 on the 12th, Grok 4.1 on the 17th, Gemini 3 on the 18th, Claude Opus 4.5 on the 24th. Four flagship announcements in twelve days, plus the usual benchmark screenshots making the rounds on the timelines. His team, he tells me, has been discussing for weeks whether they need to switch. I used to answer this question seriously, with model names and reasons. Every one of those answers was outdated after six weeks. These days I answer differently: “That is the second question. Let’s talk about the first one.” ## The convergence nobody likes to talk about Looked at soberly and without vendor loyalty: for the large block of everyday tasks I use AI for, the big models were close enough to each other in my own trials at the end of 2025. Reading and explaining code, proposing a refactoring, designing tests, reviewing a concept paper, summarizing API documentation, sketching a migration path – I got that done in usable quality with GPT-5, Claude Sonnet 4.5 and Gemini. Not equally well in every single run, but well enough that the choice of model was rarely my first construction site. Of course they are not identical. Every model has its own tone, its own preferences, its own weaknesses, and for individual tasks the differences can be large. Public benchmarks only help me to a limited extent, because they reflect neither my context nor my review criteria and shift quickly with new versions. For an architecture decision, I therefore need measurements on my own tasks rather than a general ranking. I do not like to be the first to say this in such meetings, because it cools down the discussion everyone was looking forward to. The model comparison is entertaining, it feels like engineering work, and it has the charm that you do not have to change anything about your own way of working. But it answers the wrong question. ## The noise in daily work is larger than the difference between models When a session with Claude or ChatGPT goes wrong for me, it is almost never because of the model. It is because I stated the task unclearly. Because the model did not know the context that was decisive for the solution – the architecture decision from two years ago, the unwritten convention in the team, the reason why this one service is built differently from all the others. Or because I did not check the result and the mistake only surfaced in review. An example from a team conversation at a large enterprise, anonymized as always: two colleagues, the same model, the same task – understand a piece of legacy code and propose a restructuring. One got a usable, concrete plan. The other got generic textbook text. The difference was not the model, not even the prompt in the narrow sense. One had given the model the relevant files, the test cases and the constraints. The other had typed a question into an empty window. In my own sessions, the result often varies more with how the task is cut, the context and the verification than with switching between the top models under consideration. That is not a general measurement of the market, but an observation from this work. For me it follows: before I switch models, I first check whether task, context and acceptance criterion are clean enough. ## If you bet on the best model, you bet on a commodity That brings me to the thesis I consider the most important in this post: if you build your way of working, let alone your product, on “the best model,” you are betting on a commodity you do not own. The models belong to a handful of vendors. I rent access through an API key or a subscription, just like my competitor, just like every other team. I cannot control when a version is deprecated, when behavior quietly shifts after an update, when the price drops or the next model upends the ranking. November demonstrated this: if you based your choice in October on a benchmark lead, you saw that lead change hands three times within two weeks. What I can own, on the other hand, is the layer around the model. That is not a platform and not a product, but simply everything I have in my own hands before and after the model computes: - how the tasks are cut, meaning the ability to break work down so that a piece of it becomes delegable - the context a session gets at the start, instead of the model having to guess my reality - the team’s knowledge in retrievable form, from conventions to the reasons behind old decisions - the process that governs when the AI works, when a person reviews and what may go into the main branch - the verification itself, meaning reliable ways to determine whether a result is correct before it has any effect This layer is the opposite of a commodity. It is specific to my team, my codebase, my domain. Nobody can take it away from me with a release, and the competitor cannot simply rent it too. Above all: it survives model changes. An hour I invest in better task descriptions, in a well-maintained CLAUDE.md or AGENTS.md, in review criteria still pays off with the model after next. An hour of studying benchmarks is devalued with the next release. There is a pleasant side effect that I know from architecture work: if you own the layer, your switching costs drop. When task cutting, context and verification are solid, the model behind them is as replaceable as a dependency behind a clear interface. Then I can even switch calmly when there is a real reason – because my actual capital does not hang on the model name. ## Where the choice of model does matter Honesty is part of this, otherwise the thesis turns into dogma. There are situations in which the choice of model plays a real, measurable role. I run into three of them regularly. First, the special cases. If you work with exotic languages or niche frameworks, have strongly multimodal tasks or have to stay on-premises for data protection reasons, you quickly end up with smaller open models – and there the quality differences are real and the trade-offs are different. “Good enough” applies to the large frontier models for everyday tasks, not to every class of model for every task. Second, cost and latency. As soon as models no longer run interactively but in volume – classification in a pipeline, autocompletion in the editor, processing thousands of documents – price per token and response time become hard criteria. Between models there are factors there, not percentage points, and measuring pays off. Third, long, agentic tasks. This is where the models still really differ noticeably at the end of 2025: how long they stay focused on a multi-step task, how reliably they operate tools, how they deal with their own mistakes. It is no coincidence that Claude Sonnet 4.5 in September and Opus 4.5 in November were promoted on exactly this capability. If you delegate entire work packages instead of individual questions, you may be picky about the choice of model. But – and this matters more to me than the three exceptions themselves – all of this is the second question. It can only be answered seriously once the first one has been answered. Without a clear cut of the task and without reliable verification, I cannot compare models at all; I am then only comparing gut feelings on different days. Only when the layer is in place does the choice of model become what it should be: an optimization with measurements, roughly as exciting as choosing a database index. And as there, the rule is: reassess occasionally, pin versions deliberately, take behavior changes after updates seriously. “Good enough” means neither “all the same” nor “forever” – it just means: not the bottleneck. ## The first question Back to the coffee break. Stick with the model you have, I told him, and put your team’s discussion energy into the questions before and after. How do you recognize that a result is correct? What would a session need to know about your system so it does not have to guess? Which of your tasks are even cut in a way that lets you hand them off? If you answer these three questions well, you get more out of any of the current models than your neighbor with the benchmark winner and an empty context window. He was visibly unhappy – the answer is less spectacular than a model comparison, and it means work. But it has a consequence that has occupied me ever since and that carries the rest of this series: if the model is rarely the bottleneck, then something else makes the difference between the session that delivers and the one that burns time. For me, it comes down every time to the environment the model works in – how much it shows the model, what it allows it to do and what it checks its results against. That is exactly where the next post picks up. ## Further reading - [Anthropic: Introducing Claude Opus 4.5](https://www.anthropic.com/news/claude-opus-4-5) - [Google: Gemini 3 – Google’s most capable model yet](https://blog.google/products/gemini/gemini-3/) - [Simon Willison: Claude Sonnet 4.5 is probably the best coding model in the world (at least for now)](https://simonwillison.net/2025/Sep/29/claude-sonnet-4-5/) - [Anthropic Engineering: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) --- # From Tool to Way of Working URL: https://www.mikebild.dev/en/blog/from-tool-to-way-of-working/ Date: 2025-11-18 *Opening of the series “From Session to System”.* Some time ago, I sat down with [Sebastian Korfmann](https://skorfmann.com/) in Berlin. I know Sebastian as a software engineer from the cloud and infrastructure world – someone who doesn’t judge tools by marketing slides, but by whether they take work off his hands in everyday life. He told me about his experiences with AI tools: what he builds with them, how his work has changed, where things get stuck. I listened with interest – and noticed that I had surprisingly little to contribute myself. I need to explain that. I have been working on software for more than thirty years, a large part of it on distributed systems – Node, TypeScript, GraphQL, cloud architectures – and for many years I gave training for software developers and architects. What appeals to me most about this work: building digital products, and doing it holistically. Really understanding the domain, making decisions about direction, shaping things – for a long time now, it hasn’t been just about programming and architecture for me. Over the years, my focus has shifted too: away from having every fine detail in my own hands, toward structure, consistency, processes, productivity, methods and concepts. Still, I had never worked with AI up to that point. Not a single session, no Copilot. Not out of rejection – fundamental skepticism toward new technology isn’t my style. It simply had never come up. The hype since the launch of ChatGPT at the end of 2022 was impossible to miss – headlines, conference keynotes, colleagues talking about it – but what I heard and read sounded to me like impressive demos, and my days were full. If anything, I was a little reserved – the way you are reserved about things you haven’t tried yourself yet. There was something else, too, and I don’t like talking about it much, because it has nothing to do with technology and everything to do with me. I had grown tired. Not of the profession, but of a particular kind of undertaking: my own, larger projects, digital products I had carried around in my head for a long time. I know the complexity of such undertakings well enough to know that I can’t deliver many of these topics alone at the quality I expect of myself. The ideas were there, some of them worked out in detail, in notes and half-started repositories. What was missing was the energy for the sheer amount of implementation work – alongside a job and everything else. If you have ever tried to build a complete product on your own, you know the ratio: for every hour in which you really shape something – a decision about direction, a concept, a piece of the domain – there are twenty hours of grunt work. Boilerplate, configuration, forms, error handling, deployment, documentation, plus all the organizational stuff around it. At some point, I stopped opening new drawers, because the old ones were already full. That was the state I was in when I met Sebastian. What grabbed me about the conversation was the way he told it: no superlatives, no “this changes everything” rhetoric, but the sober way you tell a colleague about a tool that has proven itself in everyday work. I knew that tone, and it made me curious. So I resolved to finally try it out myself. Not for ten minutes, but for a few days, on real tasks. ## The first days I started with Claude and ChatGPT, in the browser, on tasks from my actual everyday work: reviewing an architecture concept, sketching an API migration, writing a data import I would otherwise have kept putting off. Shortly afterward, Claude Code and Codex joined in – the tools that don’t just answer, but work directly on the repository in the terminal: reading files, changing them, running tests. Anthropic had released Claude Sonnet 4.5 at the end of September, and OpenAI its Codex update at about the same time; without planning it, I got started at a pretty good moment. And then something happened that I hadn’t expected: within days, I was very taken with it. Not mildly interested – taken. Three things got me: - The speed. Tasks for which I would have planned half a day were, within an hour, in a state I could seriously review. - The productivity across the whole day. Not a single impressive moment, but the sum: in the evening, measurably more was done than before. - The quality. I had expected that least of all. The generated code wasn’t bug-free, but considerably better than I would have expected after everything I had heard and read about generated code – structured, with sensible error handling, often with tests. The few days of trying turned into weeks of daily work. By now, I work with these tools every day and keep going deeper – Anthropic has just followed up with skills, a way to give Claude reusable working instructions, and I notice that I am starting to read such announcements the way I used to read Node release notes. A few weeks are not experience. I am aware of that, and that is exactly why I am writing this down. If you become a daily user this quickly, you should distrust your own enthusiasm for now – fresh enthusiasm is a poor witness. So I try to look closely and note down what I actually observe – with the only touchstone I have: more than thirty years of craft against which I can measure every result. ## Observation one: generating gets cheap, checking becomes the bottleneck I noticed the first shift after just a few days, and it is more fundamental than it sounds. The expensive part of my work was always generating: writing code, wording documents, working out concepts. Checking – reviews, proofreading, acceptance – was the smaller item. That ratio is flipping right now. Generating is suddenly cheap; in one hour, more text and code come into being than I used to manage in a day. What hasn’t gotten cheaper: judging whether what was generated is right. My work is visibly shifting from writing to reading, from producing to assessing. In a conversation with a colleague, I found a phrase for this that stuck: the tool is less an assistant, more a secretary. An assistant, as the product names promise, adds a line here and suggests a word there – the work stays mine. A secretary in the old sense takes on entire matters: I dictate the intent, they draw up the document, and I sign off. That sounds more convenient, but it is a different responsibility. With an assistant, I check suggestions in passing; with a secretary, I really have to read the finished piece, because my signature is underneath. If you sign without reading, you haven’t delegated, you have capitulated. I suspect that the real overhaul of my way of working lies in this shift – not in the tool itself. ## Observation two: the drawers open again The second observation is more personal, and it surprised me more than any benchmark. The tiredness I wrote about above isn’t gone – but it has lost its reason. The product ideas that were left lying around because implementing them was too big for one person are suddenly within reach again. Not because the AI builds the product. But because it takes over exactly the part that wore me down: the twenty hours of grunt work around the one hour that really requires thinking. The form scaffolding, the test coverage, the import adapter, the deployment script – all of this now comes into being so fast that, as the saying goes, I can strike while the iron is hot. Maybe that is also why the whole thing won me over so quickly: over the years, my focus had shifted to exactly where these tools take nothing away anyway – structure, consistency, concepts, the domain, the decisions about direction. The detailed work, on the other hand, and the recurring tasks, including the organizational ones, come more easily to me again now. Not all of them. But enough that it is fun again. Over the last few weeks, I have been building my own things again in the evenings, voluntarily and with a joy I hadn’t felt for a while. This is where I have to choose my words carefully, because it is so easily inflated into a gospel. So, soberly: for me, AI is above all a lever for the individual with experience right now. The emphasis is on both. The lever works because, after thirty years, I know what I want to build, how it has to be cut and how I can tell that a result is any good. Whether the same lever also works for someone who doesn’t have this judgment yet, I simply don’t know – I have a suspicion, but suspicion is not knowledge, and for this series I want to keep the two cleanly apart. ## Observation three: the tone is always right I am only noting the third observation briefly, because I don’t understand it well enough yet to make more of it. I notice *how* these systems answer. In German working life, there is a tongue-in-cheek acronym for it: SABTA – “sicheres Auftreten bei totaler Ahnungslosigkeit”, confident demeanor despite total cluelessness. Psychology knows the pattern as the Dunning-Kruger effect: those who know the least often come across as the most confident. That is exactly how these systems strike me – the right answer and the wrong one come in the same calm, competent tone. In a code review, an unsure colleague gives themselves away through their wording – “I think”, “should actually”. Here, that signal doesn’t exist. Twice in the past few weeks, I almost adopted a claim that turned out, when checked, to be completely made up – an API signature that never existed, delivered with confidence. Both times, only my habit of looking things up saved me. This confident demeanor deserves fundamental distrust, and I want to understand where it comes from – structurally, not anecdotally. I am saving that for later in this series, once I have gathered enough observations. ## What this series is meant to be I am starting a series here because I suspect the story is bigger than my desk. Right now, I am observing myself: one individual in the session, with direct control over every result. But I don’t work alone – I work in and with teams, and a team is something other than the sum of individual sessions. And above the teams are companies with their processes, their knowledge, their responsibility. I want to walk through this arc step by step in the coming installments: from me through us to the system. Not as theory, but along what I actually experience and try out – including the dead ends, of which there will predictably be a few. The next question is already pressing. In the team, at lunch among colleagues, most recently in a conference hallway: after a few minutes, the conversation lands in the same place. Which model is the best? Claude or GPT, which version, which benchmark. I have had this discussion myself and developed an unease I am only gradually able to place: after these first weeks of daily work, I notice that the choice of model has changed my results less than pretty much everything else about my way of working. Everyone is talking about the best model – but is that even the right question? I will pursue it in the next installment. ## Further reading - [Introducing Claude Sonnet 4.5](https://www.anthropic.com/news/claude-sonnet-4-5) – Anthropic’s announcement of the model I started with (September 2025) - [Claude Sonnet 4.5 is probably the “best coding model in the world”](https://simonwillison.net/2025/Sep/29/claude-sonnet-4-5/) – Simon Willison’s sober first assessment - [Introducing upgrades to Codex](https://openai.com/index/introducing-upgrades-to-codex/) – OpenAI’s Codex update with GPT-5-Codex (September 2025) - [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) – Anthropic’s engineering post on skills (October 2025) --- # React Overview: From JSX to Component Architecture URL: https://www.mikebild.dev/en/blog/react-overview-from-jsx-to-component-architecture/ Date: 2024-12-30 # React Overview: From JSX to Component Architecture React takes rendering off your hands, not architecture. The library computes a UI from a state and writes the differences to the DOM – but where this state lives, how long it lives and who may change it is something it never decides. Right there, at this inconspicuous boundary, the problems arise that you can no longer clean up later with any hook or library. That’s why this post goes through React in one go – from the first piece of JSX to the point where individual components turn into a system. It is deliberately an overview. For most of the stops I only touch on briefly here, separate posts that dig deeper will follow. Today the goal is to have the big picture in your head before you get lost in a detail. I rely on two repositories that I’m currently merging: `introduction-react` for the fundamentals and `advanced-react` for the advanced patterns. Neither is a slide deck in text form; both are runnable code that we practice on together. The version I describe here is React 19 – the stable release from late 2024, with everything that has become everyday practice since. ## The mental model: the UI is a function of state Before a single line of JSX makes sense, one idea has to sink in. React flips the way you think about a UI. Instead of describing step by step how the DOM should change – insert an element here, change an attribute there, remove a node over there –, you only describe what the UI should look like for a given state. React takes care of getting there. You can put this into a single sentence that carries everything else: the UI is a function of state. When the state changes, React calls the function again, compares the result with the previous one and writes only the actual differences to the real DOM. This reconciliation runs on an internal, lightweight representation of the tree, often called the Virtual DOM. The name matters less than the consequence: you describe the destination, not the route. I show how this reconciliation works step by step in detail in the post [How React Renders and Updates the Tree](https://www.mikebild.dev/en/blog/how-react-renders-and-updates-the-tree/). ```mermaid flowchart LR State["State"] --> Render["Component renders"] Render --> View["Described UI"] View --> DOM["React reconciles and writes to the DOM"] User["User interaction"] --> Event["Event / setState"] Event --> State ``` The second load-bearing idea is unidirectional data flow. Data flows from top to bottom, from the parent component to the child, via props. Events flow in the other direction, upward as callbacks. There is no mysterious two-way binding in which an input field and a variable magically stay in sync. At first this feels more cumbersome than in older frameworks, but it is the reason React applications can still be explained after two years: for every spot in the UI, you can say where its data comes from and who may change it. ## JSX and components: the smallest unit is a function JSX looks like HTML inside JavaScript, but it’s just a convenient notation for function calls. A `; } ``` The rule React demands at this point is: keep components pure. The same inputs should produce the same output. The state isn’t mutated directly but replaced via the setter function, and React decides when to re-render. If you take this seriously, you get components you can play through in your head without a running browser. It gets interesting as soon as a piece of state no longer fits into a single component. Then you have to answer honestly where it belongs, and the answer is rarely “in a global store”. I distinguish four places, and choosing between them is the real architecture work in the frontend: ```mermaid flowchart TB Frage["Who owns this state?"] Frage --> Lokal["Component
(useState) – UI detail"] Frage --> URL["URL
filter, page, selected object"] Frage --> Server["Server cache
loaded data that belongs to the backend"] Frage --> Global["Global store
app-wide, shared decisions"] ``` Much of what teams reflexively put into a global store actually belongs in the URL – which filter is active, which page is shown, which object is selected. In the URL, this state is shareable, can be saved as a bookmark and survives a reload. And a large part of what looks like application state isn’t state at all: it is data that belongs to the server and that you have merely cached. This distinction between real client state and cached server data is the most consequential one in the entire frontend, and I dedicate a separate post to it: [Client state vs. server cache](https://www.mikebild.dev/en/blog/client-state-vs-server-cache/). ## Effects are the edge, not the center `useEffect` is the hook that has caused the most misunderstandings in the teams I’ve worked with. It synchronizes a component with something outside of React – a network call, a subscription, the title of the browser tab, a timer. The key sentence is: an Effect is the edge of the system, not its center. Anything you can compute from state doesn’t belong in an Effect but directly in rendering. ```jsx import { useState, useEffect } from "react"; function useInvoice(id) { const [data, setData] = useState(null); const [error, setError] = useState(null); useEffect(() => { let active = true; fetch(`/api/invoices/${id}`) .then((r) => r.json()) .then((d) => active && setData(d)) .catch((e) => active && setError(e.message)); return () => { active = false; }; }, [id]); return { data, error }; } ``` Two things about this example are the real lesson. The dependency array `[id]` determines when the Effect runs again – if you forget a value there, the component keeps working with stale data. And the returned cleanup function, which sets `active` to `false`, prevents a late-arriving response from overwriting the state of a component that has already unmounted or of a request that has since been superseded. This race between two requests is exactly the bug that never shows up in tests with fast responses and only strikes in production on a slow network. I deliberately pulled the logic here into its own custom hook `useInvoice`. That already brings us to today’s way of reusing logic – more on that in a moment. All that matters at this point is the mindset: limit Effects, don’t pile them up. A frontend in which data loading, derivation, synchronization and user events all end up in a single lump of Effects is fragile, because nobody can say anymore why which Effect runs when. The most common mistake I see in code reviews is exactly the opposite reflex: mirroring a value that can be computed from other state into a second state via an Effect. If you write the full name from first and last name into its own variable via an Effect, you have built yourself two sources of truth that drift apart as soon as a render gets in between. The computed value doesn’t belong in an Effect, nor in a second `useState`, but simply in rendering, where it is created fresh on every pass. What can be derived is derived, not stored – this one rule saves you more bugs than any library. An Effect is only justified when something outside of React is really involved. By the way, for loading server data you rarely have to write this mechanism by hand in real projects. In practice, a library specialized for this handles caching, refetching and consistency. React 19 goes one step further with the `use()` hook and Suspense and lets you await a Promise directly during rendering, so loading and error states move further out to an enclosing `` component. I cover this big topic of its own in the post [Suspense and the use Hook](https://www.mikebild.dev/en/blog/suspense-and-the-use-hook/). ## From HOCs and render props to custom Hooks The advanced React patterns, which form their own block in the `advanced-react` material, are almost all answers to the same question: how do I share logic between components without copying it? The answer has shifted over the years, and this shift is instructive in itself. There used to be two established patterns for this. A higher-order component is a function that takes a component and returns an enhanced one – a wrapper that adds behavior. Render props solve the same problem by having a component expose its logic through a function as its child. Both work, but both come at the same price: they nest the component tree and turn a flat idea into a deep structure. [Custom Hooks](https://www.mikebild.dev/en/blog/from-hocs-and-render-props-to-custom-hooks/) solve exactly this problem without nesting the tree. A custom hook is simply a function whose name starts with `use` and that uses other hooks. The `useInvoice` from above is already one. The logic lives in a normal function, is called by several components and doesn’t show up in the tree at all: ```jsx function InvoiceView({ id }) { const { data, error } = useInvoice(id); if (error) return ; if (!data) return ; return ; } ``` You find the same movement with context. Passing data down through many levels without threading it as a prop through every intermediate component is the job of context: a provider at the top of the tree, a `useContext` further down. The important caveat: context is meant for distributing, not as a replacement for well-thought-out state ownership. If you put every changing value into a context, you only move the coupling problem one level up. I cover this too – context as a distribution channel versus context as hidden global state – in the post [Using Context well](https://www.mikebild.dev/en/blog/using-react-context-well/). ## When shared state really is global: Redux and the alternatives Sometimes state really is app-wide and is read and changed by many places far apart from each other. There are established tools for this case, and Redux is the best known. Its core is surprisingly small: the entire state lives in one store, it is changed only by dispatching an action – a plain object with a `type` –, and a reducer is a pure function that computes the new state from the old state and the action. ```js function invoicesReducer(state = [], action) { switch (action.type) { case "invoice/paid": return state.map((i) => i.id === action.id ? { ...i, paid: true } : i ); default: return state; } } ``` The appeal of this pattern is that every state change becomes a named, loggable event. You can trace the sequence of actions, record it and replay it in a test. The price is a certain amount of structure. In projects I have come across three ways to organize this structure, and the choice determines whether a UI system grows along the domain or along technical lines: the Rails style with separate folders for actions, reducers and containers; the domain style, which instead bundles per feature; and the Ducks pattern, which puts the actions and reducer for one thing into a single file. The domain split is almost always the better one, because it draws file boundaries along the domain and not along technical roles. Today hardly anyone writes Redux out by hand like this anymore. The official Redux Toolkit takes most of the repetition off your hands, and for many applications a lighter library or simply context with a reducer is enough. Reactive approaches like MobX pursue the same goal with a different model, in which derived values update automatically. Which of these tools fits depends less on fashion than on an honest answer to the ownership question from earlier – I dedicate a separate comparison to it: [State Management in React: Redux Toolkit, Lightweight Stores, MobX](https://www.mikebild.dev/en/blog/state-management-in-react/). In architecture discussions, I like to do the cross-check: for how much of the supposedly global state do you really need the store? Most of the time the list shrinks dramatically as soon as you use the URL for selection and filters and treat loaded server data as what it is – cache, not state. What often remains is just a small core of real, app-wide decisions: the signed-in person, the chosen language or theme setting, maybe a shopping cart. For this core a store pays off; for the rest it is dead weight. So a global store isn’t the default answer but the exception you have to be able to justify. ## Router, server and the edges of the application Two edges are still missing. The first is navigation. In a single-page application, you don’t switch pages; you map URLs to components. The router keeps the address bar and the displayed component in sync, so the back and forward buttons, bookmarks and shared links keep working: ```jsx import { BrowserRouter, Routes, Route } from "react-router-dom"; function App() { return ( } /> } /> } /> ); } ``` This also makes the router the natural place for the state that belongs in the URL. The `:id` parameter, which you read in the component via `useParams`, is exactly the selected object I talked about above – no reason to also keep it in a store. For new projects, React Router now recommends the data router variant with `createBrowserRouter`, in which routes also get loading and writing functions; that is the more modern way, and I dedicate the post [React Router data router](https://www.mikebild.dev/en/blog/react-router-data-router-the-url-as-state/) to it. The second edge is rendering on the server. For startup time, search engines and weak devices, it often makes sense to generate the first version of the page on the server and only bring it to life in the browser. Frameworks like Next.js take care of these mechanics for you. React 19 expanded the topic fundamentally once more with Server Components: components can run on the server, load data there and send only their result to the browser, while Server Actions form the counterpart for write operations. This noticeably shifts the old boundary between client and server, and it is such a big topic that I dedicate the post [React Server Components and Server Actions](https://www.mikebild.dev/en/blog/react-server-components-and-server-actions/) to it; here it only serves as a signpost. ## Operations: tests, toolchain, types An overview that stops at rendering would be incomplete, because all the boundaries I have described – state ownership, Effect discipline, data flow – can break unnoticed if nobody pins down an expectation about them. In the frontend, tests are not a chore but the place where these expectations stay visible. Today I test components with Vitest and the React Testing Library, and its guiding idea fits the architecture of this post exactly: you check what users see and do, not how the component is built inside. A test tied to the visible result survives a refactoring; a test glued to implementation details breaks with every rename. ```jsx import { describe, it, expect } from "vitest"; import { render, screen } from "@testing-library/react"; import userEvent from "@testing-library/user-event"; import { Counter } from "./Counter"; describe("Counter", () => { it("counts up on click", async () => { render(); const button = screen.getByRole("button", { name: "0" }); await userEvent.click(button); expect(screen.getByRole("button", { name: "1" })).toBeInTheDocument(); }); }); ``` Behind this is the same test pyramid as everywhere: many fast component tests at the base, fewer integration tests in the middle, a handful of end-to-end tests with a tool like Playwright at the top. If you turn this distribution upside down, you pay for it later with a sluggish build pipeline. The toolchain is an architecture decision too, not a matter of taste. Whether a project starts with Vite, Next.js, Parcel or a handwritten webpack configuration determines how fast the feedback is during development, how easy server rendering becomes and how much you maintain yourself. And on top of all this sits [TypeScript](https://www.mikebild.dev/en/blog/typescript-in-react/), which turns props and state into checkable contracts. A mistyped prop then doesn’t become a runtime error for the user but a red squiggle in the editor. Finally, the React Compiler, which the React team develops as a separate project alongside the library, takes over part of the manual optimization: it analyzes components at build time and automatically remembers what hasn’t changed between two render passes, so many calls to `useMemo`, `useCallback` and `memo` become unnecessary. ## The repository is already architecture One last look at the structure of the repositories themselves. `introduction-react` and `advanced-react` aren’t one big lump but many small, self-contained examples – a basic app, a Redux app, a router app, one with server rendering, plus the advanced folders for asynchronous patterns, functional composition and structure. Each example stands on its own and can be started individually. The fact that I’m currently merging the two repositories is therefore a small architecture exercise in itself. The question is the same as for any growing system: what may be shared, and what has to stay separate so that a change in one place doesn’t unexpectedly break something in another? A cleanly split monorepo of fundamentals and advanced examples solves exactly the same task as an application made up of many components and modules. In both places, the boundaries you draw are the real work. ```mermaid flowchart TB Repo["React monorepo"] Repo --> Grund["Basics
JSX, components, hooks, router"] Repo --> Fort["Advanced
async, functional, structure"] Repo --> Geteilt["Shared building blocks
UI components, test helpers"] Grund --> Geteilt Fort --> Geteilt ``` ## What should stick in the end At best, what remains from a walk-through like this is not the sentence “I know the hooks now” but a reflex: for every piece of state, first ask who owns it and how long it should live. That is exactly the core. React gives you a very good tool for describing UIs, but it doesn’t make the architecture decisions for you. Who owns a piece of state, where an Effect has its edge, which state lives in the URL, in the server cache or in the store – that remains the work a human has to do. That’s why this post is an overview and not a handbook. I only briefly touched on many stops: the difference between client state and server cache, context as a distribution channel, the choice between Redux and its lighter alternatives, Suspense and Server Components, testing without theater. There is more to say about each of these stops than an overview can carry, and that is exactly the plan: the details will follow as separate posts, each with a concrete example and at least one failure case. Once you have the big picture in your head, you’ll know where you currently stand. ## Further reading - Repository introduction-react (fundamentals): https://github.com/mikebild/introduction-react - Repository advanced-react (advanced patterns): https://github.com/mikebild/advanced-react - Slide overview for this overview: https://slides.mikebild.dev/introduction-react.en.html - React, official documentation (Thinking in React): https://react.dev/learn/thinking-in-react - React 19, announcement of the stable release: https://react.dev/blog/2024/12/05/react-19 - React, managing and sharing state: https://react.dev/learn/managing-state --- # Forms in React 19: Actions, useActionState and useOptimistic URL: https://www.mikebild.dev/en/blog/forms-in-react-19-with-actions/ Date: 2024-12-23 An optimistically inserted entry that disappears again on an error and leaves no message behind tells the user something false: they submitted, they saw it briefly, then there was nothing. This is the one place where the form APIs of React 19 create work instead of taking it off your hands – and that is why it comes first, right here at the start. Everything else about them is relief. Up to React 18, a form that saves a name consisted of `onSubmit`, `event.preventDefault()`, a `useState` for the loading state, a second one for the error message and a `try/catch` somewhere – a surprising amount of manual work for a surprisingly everyday task. React 19, stable since December 5, 2024, instead hands a function directly to the `
` element and puts three hooks next to it: `useActionState`, `useFormStatus` and `useOptimistic`. They take care of exactly the things you used to wire up by hand. I will go through what each of these building blocks takes over, how they work together and where the error path from the first paragraph belongs. ## From onSubmit to action The starting point is a small but far-reaching change to the `` element. In React 19, the `action` attribute accepts a function – no longer just a URL string as in classic HTML. On submit, this function receives a `FormData` object and is called by React. React calls `preventDefault` itself, wraps the call in a transition and – a detail that is easily overlooked – automatically resets an uncontrolled form after a successful action. Here is the comparison. Before: ```jsx function NameForm() { const [isSaving, setIsSaving] = useState(false); const [error, setError] = useState(null); async function handleSubmit(event) { event.preventDefault(); setIsSaving(true); setError(null); const formData = new FormData(event.currentTarget); const result = await save(formData.get("name")); setIsSaving(false); if (result.error) setError(result.error); } return ( {error &&

{error}

}
); } ``` And after, with a client action: ```jsx function NameForm() { async function updateName(formData) { await save(formData.get("name")); } return (
); } ``` The second variant is not just shorter, it shifts control. React now knows that a handover is happening here, keeps the pending state consistent and takes care of the native submit behavior. In its documentation, React simply calls a function that triggers transitions this way an “Action”. What the second variant still lacks is everything that actually made up the first code block: the loading state and the error handling. That is exactly what the three hooks bring back – but without the manual work. ## Who takes care of what At first glance, the three hooks sound similar, but they have very different jobs. So before the code, the responsibilities: - `useActionState` bundles the complete lifecycle of an action in one place: it wraps your action function, holds the returned result as state, provides an `isPending` flag and hands you back a wrapped `formAction` that you attach to the form. - `useFormStatus` reads the pending state of the nearest enclosing `
` – meant for child components like a submit button that don’t need to know anything about the action itself, but want to know whether a submission is in progress. - `useOptimistic` immediately shows an expected intermediate state while the action is still running, and afterwards automatically converges back to the real state – to the server value on success, to the old value on error. You can use the three individually or together. In a real form, they usually interlock, and how they work together is exactly where it gets interesting. ## useActionState: result and pending in one place You import `useActionState` from `react` – not from `react-dom`, which is a common first source of errors. The signature: ```jsx const [state, formAction, isPending] = useActionState(action, initialState, permalink); ``` The decisive point, and a surprising one for many, lies in the signature of the action function you pass in. It does **not** just receive the `FormData`; its first argument is the previous state, and only the second is the form data: ```jsx import { useActionState } from "react"; async function updateName(previousState, formData) { const name = formData.get("name"); const error = await save(name); if (error) { return { error }; } return { ok: true }; } function NameForm() { const [state, formAction, isPending] = useActionState(updateName, {}); return ( {state.error &&

{state.error}

} {state.ok &&

Saved.

} ); } ``` What happens here is the entire first code block from above – just without the manual work. The return value of the action becomes the new `state`, React manages the `isPending` flag, and `formAction` is the wrapped function that gets attached to the `action` attribute. The error message is no longer a separate `useState`; it simply falls out of the returned state. When I see in a code review that the state is suddenly `undefined` or the previous state gets lost, the cause is almost always the same: the action was written as `(formData) => …` instead of `(previousState, formData) => …`. The first parameter is simply not the FormData. If you come from the old `onSubmit` world, this reflex is in your fingers, and it regularly costs a few minutes of searching. A historical note so that older tutorials don’t confuse you: in the canary versions, this hook was called `useFormState` and lived in `react-dom`. With React 19, it was moved to `react` and renamed to `useActionState`; the third element `isPending` was added at the same time. `useFormState` has been deprecated since – if you still see it somewhere, the code is from an older state. ## useFormStatus: reading pending in the child Now to the submit button that I already used above as ``. You might ask why it is extracted – after all, I could have passed `isPending` from `useActionState` directly to a button in the form. Both are possible, but `useFormStatus` solves a specific problem: a reusable component that knows the pending state without you having to pass it down. ```jsx import { useFormStatus } from "react-dom"; function SubmitButton() { const { pending } = useFormStatus(); return ( ); } ``` The hook comes from `react-dom`, takes no parameters and, in addition to `pending`, returns `data`, `method` and `action` of the enclosing form. The one rule you need to know, and the one responsible for most of the error reports at this point: `useFormStatus` reads the status of the **nearest parent `
`** and therefore has to sit in a child component, not in the same component that renders the ``. If the hook accidentally sits in the form component itself, `pending` is simply always `false` – from that perspective, there is no enclosing form whose status could be read. The button has to be a child. A separate `SubmitButton` component is therefore not a matter of taste: without this nesting, the hook sees nothing at all. ## useOptimistic: showing the expected state immediately The third hook is the most impressive one – and the most dangerous if you only half understand it. `useOptimistic` immediately shows the state you expect after a successful action, without waiting for the server response. The classic example is a message list in which your own message appears immediately: ```jsx import { useOptimistic, useActionState } from "react"; function Thread({ messages, sendMessage }) { const [optimisticMessages, addOptimistic] = useOptimistic( messages, (currentMessages, newText) => [ ...currentMessages, { text: newText, sending: true }, ] ); const [state, formAction] = useActionState( async (previousState, formData) => { const text = formData.get("message"); addOptimistic(text); const error = await sendMessage(text); if (error) { return { error }; } return { ok: true }; }, {} ); return (
    {optimisticMessages.map((message, index) => (
  • {message.text} {message.sending && (sending…)}
  • ))}
{state.error &&

{state.error}

}
); } ``` `useOptimistic` receives the real state and a pure reducer function that computes the next intermediate state from the current state and the optimistic value. The call to `addOptimistic` has to happen inside an action or transition – here, inside the async action that `useActionState` manages. If you call it outside, you get a warning and no optimistic rendering. The truly elegant part is the automatic convergence: the optimistic value only applies while the action is running. As soon as it has finished, the displayed state falls back to the real `messages` state. On success, that is the updated server value; on error, the old value – so the optimistically inserted message disappears again on its own. You don’t have to reset anything manually. ## The pitfall: optimistic without an error path The automatic convergence tempts you to consider the error case done. It isn’t – this is where the bugs come from that nobody sees in testing and everybody reports to support. Imagine `sendMessage` fails. The optimistic value is rolled back automatically – the message disappears from the list. From the user’s point of view, that means: they submitted something, it appeared briefly, and then it was gone. Without any further feedback. No user interprets that as “error while sending”; most think they misclicked and simply try again – in the worst case, this creates a duplicate as soon as the server did respond after all. The flawed reasoning is to mistake `useOptimistic` for error handling. The hook takes care of the *visible intermediate state*, not of *communicating the result*. You have to keep these two jobs apart: - `useOptimistic` makes sure the optimistic value is rolled back automatically on an error – that is the rollback of the UI state, and you get it for free. - The visible error message is a separate responsibility. It has to come from the `state` of `useActionState`: the action catches the error, returns it as `{ error }`, and the UI derives a message from it. With concurrent changes, this UI rollback is not enough. Duplicate submissions, stale server states and conflicts still need idempotency keys, version checks or a domain conflict rule on the server. That is exactly what happens in the code above: in the error case, the action returns `{ error }`, and `{state.error &&

…

}` makes it visible. The optimistic value disappears automatically, but the user sees *why*. If, on the other hand, you swallow the error in the `catch` or never return it in the first place, you have a UI that, on errors, silently gives the false impression that nothing happened. Optimistic rendering without a real error path is worse than no optimistic rendering at all. ## How it fits together If you arrange the four participants – the form, the action, the pending state and the optimistic value – in time, the pattern becomes clear: ```mermaid flowchart LR A["form action(fn)
submit triggered"] --> B["isPending = true
button disabled
via useFormStatus"] B --> C["addOptimistic()
expected state
visible immediately"] C --> D["await save()"] D -->|Success| E["real state
state.ok
form reset"] D -->|Error| F["optimistic value reverted
state.error visible"] ``` The upper path is the normal case, the lower one is the one you have to actively design. React takes almost the entire path from A to D off your hands; the conscious design decision lies in the branch at D – and in making sure the error branch doesn’t lead nowhere. The second diagram sorts out the responsibilities once more, because the risk of confusing the three is real: ```mermaid flowchart TB subgraph Form["React 19 form"] UAS["useActionState
call + result + pending"] UFS["useFormStatus
reads pending of the parent form
in the child"] UO["useOptimistic
instant intermediate state
with auto-convergence"] end UAS -->|passes isPending
and state| UI["Error and success display"] UFS -->|pending| Button["SubmitButton"] UO -->|optimisticState| Liste["Live list"] ``` ## A word on Server Functions So far, I have talked about client actions – functions that run in the browser. But the same mechanism also carries across the network boundary. With the `"use server"` directive at the top of a file or a function, you mark Server Functions that can be called from the client but run on the server: ```js "use server"; export async function updateName(previousState, formData) { const name = formData.get("name"); await db.users.update({ name }); return { ok: true }; } ``` You can pass this function to `useActionState` or directly to `
` exactly like a client action – the signature is the same. It is important not to confuse `"use server"` with `"use client"`; the two directives mark opposite places of execution. And Server Functions require a framework or bundler that supports React Server Components; in a pure client app, they don’t exist. A nice side effect in this context is progressive enhancement. If you pass a `permalink` – a URL – to `useActionState` as the third argument, the form also works when JavaScript hasn’t hydrated yet or isn’t available at all: the browser navigates to this URL the classic way, the server processes the FormData, and as soon as React has hydrated, the client-side action takes over seamlessly. This is only relevant in an RSC context, but it shows that the Actions model was thought through all the way into server communication and is not just a prettier way of writing `onSubmit`. If you want to dig deeper into this interplay, my post on [React Server Components and Server Actions](https://www.mikebild.dev/en/blog/react-server-components-and-server-actions/) gives you the bigger picture. ## What sticks All in all, it comes down to a change of perspective. In React 19, you give the form a function; cleaning up after it with event handlers goes away. The three hooks are not three new things to memorize, but the three responsibilities you used to tie together yourself, cleanly separated: `useActionState` for the call, the result and pending, `useFormStatus` for the view of pending from the child, `useOptimistic` for instant feedback with automatic rollback. The two stumbling blocks that, in my experience, cost the most time: the action of `useActionState` receives the previous state as its first argument, not the FormData. And optimistic rendering is only done when the error case has a visible message – the hook takes the rollback off your hands, but not the communication. With these two points in mind, forms in React 19 become shorter *and* more robust than anything you built by hand before. ## Further reading - [React 19 release blog post (Actions overview)](https://react.dev/blog/2024/12/05/react-19) - [`useActionState` – react.dev](https://react.dev/reference/react/useActionState) - [`useFormStatus` – react.dev](https://react.dev/reference/react-dom/hooks/useFormStatus) - [`useOptimistic` – react.dev](https://react.dev/reference/react/useOptimistic) - [`` – react.dev](https://react.dev/reference/react-dom/components/form) - [`"use server"` / Server Functions – react.dev](https://react.dev/reference/rsc/use-server) - [`useTransition` (background on Actions/transitions) – react.dev](https://react.dev/reference/react/useTransition) --- # React Server Components and Server Actions: The New Boundary URL: https://www.mikebild.dev/en/blog/react-server-components-and-server-actions/ Date: 2024-12-19 # React Server Components and Server Actions: The New Boundary ```text Error: You're importing a component that needs `useState`. This React Hook only works in a Client Component. To fix, mark the file (or its parent) with the "use client" directive. ``` For many people, this message is their first contact with React Server Components, and the usual reflex is: put `"use client"` in the first line, error gone, move on. The build is green again, and the real question has been skipped. The message isn’t a configuration error, though. It asks which side of a boundary this piece of UI belongs on – and the answer reaches far beyond the file where the directive ends up. When you move an architectural boundary, you always move more than code: you also move where testing happens, what has to be deployed and which team owns which part of the UI. That is the trade-off this is really about. Faster delivery and a smaller bundle are the visible gain. The real effect lies underneath: shorter paths from data access to display, less friction at the seam between the two worlds – paid for with a boundary that you now have to draw and defend deliberately. **Editorial note (July 2026):** React 19 stabilized Server Components as a component model. The interfaces that frameworks and bundlers use to implement them, however, still don’t follow the usual semver stability within React 19.x. React alone therefore doesn’t yet provide a complete production architecture for them; the examples in this post use the Next.js App Router. Server Components can also run at build time or per request. Only the dynamic variant needs a runtime server. This is where many people get stuck at first: you look for a new hook and instead run into a boundary that has moved – with consequences for testing, operations and team structure. From now on, the framework no longer decides for you which part of the UI stays on the server and which goes to the browser. That is what this post is about. ## What a Server Component really is A Server Component runs in an environment outside the client bundle: at build time or on a server per request. There it can render with direct access to the database, file system or internal services and then send only its result to the browser. Not its code. That is the key sentence. For a component that merely displays something, no component code of its own ends up in the client bundle. The browser gets a description of what it should display, not the component that produced this description. That is a different use of the word “render” than you are used to. This is why it’s worth going back to an earlier post: in [How React renders the tree](https://www.mikebild.dev/en/blog/how-react-renders-and-updates-the-tree/) I showed that rendering in React is only a calculation anyway – a function that turns inputs into a description of the tree, which React then compares with the last state. But if rendering is only a calculation, the question arises immediately: where does this calculation run? This is exactly where Server Components come in. They permanently move part of this calculation to the server instead of doing it in the browser as before. ## The difference from SSR that almost everyone mixes up One point needs setting straight here, because it reliably causes confusion: Server Components are not the same as server-side rendering, and the difference is not cosmetic. Classic SSR takes perfectly normal client components and renders them once on the server to HTML so that the browser sees something right away. After that, though, the server still sends the component code along, and hydration runs in the browser: React attaches itself to the delivered HTML, runs the same component again and makes it interactive. So the code goes along – SSR is an early first impression, not a way to save JavaScript. In the end, the component exists twice: once as HTML from the server, once as runnable code in the browser. A Server Component, by contrast, never exists in the client bundle. There is nothing to hydrate, because there is no second execution in the browser. The server has done the calculation, the result is there, and that’s the end of the story for this part of the tree. SSR answers the question “when does the user see something for the first time”. Server Components answer the other question: “does this code ever need to go to the browser at all”. For pure display, the answer is now no. ```mermaid flowchart TB subgraph Server SC["Server Component
reads data directly"] end subgraph Browser UI["finished result
is displayed"] Island["Client island
(hooks, events)"] end DB[("Database / service")] SC -->|await| DB SC -->|only the result,
no code| UI SC -.->|embeds| Island ``` ## The boundary is called `"use client"` If Server Components are the normal case, you need a marker for the exception – for the place where interactivity begins. This marker is the `"use client"` directive at the top of a file. Everything above this boundary runs on the server: loading data, displaying it, building structure, no state. From the directive on, you are in browser land with everything that comes with it – `useState`, `useEffect`, event handlers, access to `window`. What matters is the direction in which these two worlds fit together. A Server Component may contain Client Components as children – you sprinkle islands of interactivity into an otherwise static, server-rendered page. The other way around is restricted: a Client Component can’t simply import a Server Component, because the server code would then have to end up in the browser after all. It can only embed a Server Component as a passed-in `children` slot – the server renders the child, the client component receives the finished result and wraps its interactive shell around it. This one rule explains most of the error messages people stumble over at the start. ```mermaid flowchart TB Page["Server Component (page)
loads data, displays it"] Page --> List["Server Component
invoice list"] Page --> Button["Client island
"use client": button with onClick"] Button -->|allowed as children| Slot["Server content
as slot"] ``` ## Server Components in practice Because a Server Component only runs on the server, it may do something that never worked in the browser: it may be `async` and use `await` directly in its body. Loading data then happens without `useEffect`, without a loading flag, without the whole apparatus – you write it down as if it were a normal function that just happens to be able to access a database. ```jsx // invoices-page.jsx — a Server Component, no "use client" here import { db } from "@/lib/db"; import { PayButton } from "./pay-button"; export default async function InvoicesPage() { const invoices = await db.invoice.findMany({ where: { open: true } }); return (

Open invoices: {invoices.length}

    {invoices.map((invoice) => (
  • {invoice.title} — {invoice.amount} €
  • ))}
); } ``` Two things deliberately sit side by side here. The `await db.invoice.findMany(...)` accesses the database directly – this code never leaves the server, there is no API route in between and no loading state in the browser. And `PayButton` is an embedded client island: everything that needs a click moves into its own file with `"use client"`. ```jsx // pay-button.jsx "use client"; import { useState } from "react"; export function PayButton({ invoiceId }) { const [busy, setBusy] = useState(false); return ( ); } ``` What doesn’t work in a Server Component is just as instructive: no `useState`, no `useEffect`. In this environment there is no local client state that you keep across clicks. A Server Component can render again on a later request or a new server execution; but it doesn’t handle direct browser interaction. Everything that should react immediately in the browser to a click belongs in a client island beyond the boundary. ## Server Actions: moving writes back to the server Server Components solve reading and displaying. For writing, there are Server Functions, often called Server Actions, marked with the `"use server"` directive. These are functions that run on the server but are called from the client through the framework’s integration – most directly as the `action` of a ``. In the application, you don’t build your own API route or your own request format for this call. However, transport, serialization and the security boundary are not handled by React as a runtime alone, but by the framework you use. ```jsx // invoice-actions.js "use server"; import { db } from "@/lib/db"; import { revalidatePath } from "next/cache"; export async function payInvoice(formData) { const id = formData.get("invoiceId"); await db.invoice.update({ where: { id }, data: { open: false } }); revalidatePath("/invoices"); } ``` It is called directly from the form. So that the user gets feedback while the action is running, there are two hooks made exactly for this: `useActionState` bundles the call with its result and a pending flag, and `useFormStatus` reads the pending state of the surrounding form in a child element. ```jsx // pay-form.jsx "use client"; import { useActionState } from "react"; import { useFormStatus } from "react-dom"; import { payInvoice } from "./invoice-actions"; function SubmitButton() { const { pending } = useFormStatus(); return ( ); } export function PayForm({ invoiceId }) { const [state, formAction] = useActionState(payInvoice, null); return ( ); } ``` The appeal lies in how little is written here. No `fetch`, no manual `POST`, no hand-built endpoint, no serialization. You call a function that happens to run on the server, and the pending state for the UI comes along for free. ```mermaid flowchart LR Form["Form in the browser
action = payInvoice"] Form -->|Submit| Action["Server Action
"use server""] Action -->|writes| DB[("Database")] Action -->|revalidatePath| Fresh["Server re-renders
the affected view"] Fresh -->|new result| Form ``` ## What this means for the series This new boundary shifts another one I have already written about. In [Client State vs. Server Cache](https://www.mikebild.dev/en/blog/client-state-vs-server-cache/) the core point was: most of what looks like state is really borrowed server cache that you only keep temporarily in the browser. Server Components shift this boundary once more. A large part of the data loading for display, which used to require a cache library in the browser, now moves to the server – there the Server Component reads directly and sends only the result. The need to track the same data in the client shrinks accordingly. That doesn’t mean server state libraries become unnecessary. As soon as things get interactive – data that changes after a click without reloading the whole page – the cache in the browser still makes sense. But the split shifts: less display in the client, more on the server. Staggered delivery is handled by [Suspense](https://www.mikebild.dev/en/blog/suspense-and-the-use-hook/), which streams the server-rendered parts to the browser piece by piece. ## What the shifted boundary does to testing, operations and teams So far this sounds like a clean technical reshuffle. It gets interesting, though, where this boundary meets the way a team works, tests and ships. Because an architectural boundary is never just a line of code. It decides where complexity arises – and complexity always comes with a bill. Let’s start with testability, because that is where it shows most clearly what the shift costs and what it saves. A pure display component that used to load data in the browser was surprisingly laborious to test: mock `fetch`, play through the loading state, reproduce the error path, wait for the re-render after the data arrives. As a Server Component, this whole apparatus disappears. The component is an `async` function that receives data and returns a description – testable like a function, without a browser environment, without timing. The price sits on the other side of the boundary: the direct `await db.invoice.findMany(...)` in the component body weaves data access and presentation together, and the component now wants to see a database for a test. So testing moves rather than disappears: you tend to check Server Components with integration tests against a real or in-memory data source, and the interactive islands still as isolated client tests. If you draw this split deliberately, you win; if you ignore it, you build hard-to-test hybrids. In deployment, the character of the application shifts as soon as Server Components run per request or Server Functions write. Client-only React could end up as a bundle of static files behind a CDN; pure Server Components executed at build time can also be delivered statically. The dynamic variant, however, needs a running process with access to the database and internal services. That brings proximity – data access sits right next to the component, without a separate API layer in between – and operational responsibility: server capacity, runtime errors beyond the browser and a boundary between public and internal code that becomes a security boundary. The gain is a shorter chain from click to persistence. The cost is an operational surface that wasn’t there before. And then there is team structure, the point that is easiest to overlook and most expensive to pay for. In the classic split there was a hard seam: frontend builds the UI, backend delivers the API, and in between sits a contract of endpoints and formats. This seam was friction, but also a clear boundary of responsibility. Server Components and Server Actions dissolve it – data access moves into the component, writing into a function next to it, and the contract of API routes disappears. For a team that works across the full depth, this is a noticeable reduction in friction: shorter paths, less coordination about endpoints, less code that only carries data back and forth. For two separate teams with a clean frontend-backend split, it is the opposite: the boundary where they handed over responsibility is gone, and the new one runs right through the middle of the UI. Whether Server Components are a gain or a source of conflict therefore depends less on the technology than on the organization. This leads to the decision criteria I apply in projects. Server Components pay off when the team works across the full depth and the frontend-backend seam has so far been more burden than protection, when a running server is part of operations anyway, and when the UI is data-heavy and not very interactive. They cost more than they bring when two teams deliver along a deliberately drawn API boundary, when operations are supposed to stay purely static, or when the application consists almost entirely of interactive islands. So the question is not “is the technology good” but “does the shifted boundary fit how we build, test and ship”. ## An honest assessment: new and with friction I don’t want to sugarcoat this. Server Components are new, and they come with friction. You have to really understand the boundary between server and client, or you produce exactly the errors I described above – an import across the boundary, a hook on the wrong side, a data access that suddenly is supposed to end up in the browser. The ecosystem is still in flux: the widespread implementation today is the Next.js App Router, other frameworks are catching up, and some libraries first have to learn where they belong in this world. And not every application needs this. A highly interactive dashboard that runs almost entirely in the browser anyway gains little if you force it through the server-client boundary. Where Server Components clearly pay off, on the other hand: for data-heavy, largely static UIs where a lot is displayed and little is clicked; when the client bundle noticeably weighs you down and you want to get rid of display code that has no business being in the browser; and where server-delivered HTML matters for search engines and the first impression. That is an honest trade-off, not an obligation. ## The real decision If one thought from this post should stick, it is this one: Server Components are not a faster way to render. They are a decision about location. For every part of the UI, you now ask first: does this stay on the server – because it only reads and displays – or does it belong in the browser because a human interacts with it? The `"use client"` and `"use server"` directives are nothing more than the visible markers of this one decision. If you draw the boundary deliberately, you reap the effect that lies beneath the technology: shorter paths from data access to display and therefore faster cycles, less friction at the dissolved frontend-backend seam, and testability that splits cleanly into server-side integration tests and client islands. If you blur the boundary, you get the opposite – hard-to-test hybrids, unclear responsibilities, operational load without a return. The difference doesn’t lie in the framework. It lies in whether the shifted boundary fits how a team builds, tests and ships – and whether you keep it clear enough afterwards to defend it. This question is what matters – long before you look up the first hook. ## Further reading - Repository introduction-react (chapters server-components, server-actions; App Router examples): https://github.com/mikebild/introduction-react - React, “Server Components”: https://react.dev/reference/rsc/server-components - React, “Server Functions”: https://react.dev/reference/rsc/server-functions - Next.js, App Router: https://nextjs.org/docs/app --- # React Router Data Router: The URL as the Place for State URL: https://www.mikebild.dev/en/blog/react-router-data-router-the-url-as-state/ Date: 2024-12-16 # React Router Data Router: The URL as the Place for State In the data router of React Router, a route is no longer a mapping from path to component. It is a complete description of everything that belongs to an address: which part of the UI appears, where its data comes from, what happens on a write, what you see when something fails. These descriptions are objects, and because they exist before the first render, the router can read from them what to do for a URL – without running a single component. How far this goes becomes clear when you compare it with the pattern the classic approach suggests: a route renders a component, the component has a `useEffect`, the effect loads the data, and next to it sit three `useState` calls for loading state, error and result. For one page, that works. For twenty nested pages, you get loading waterfalls: the outer component renders, its effect loads, only then does the inner one render, and its effect loads – one after the other, even though both were known from the start. In the React overview, I still showed routing with `BrowserRouter` and `Routes` and deliberately left the modern approach aside; it is the subject of this post. The data router reverses the order. **Editorial note (July 2026):** React Router 8 distinguishes three modes: Declarative, Data and Framework. This post covers Data Mode with `createBrowserRouter`. Framework Mode builds on it and adds, among other things, typed route modules, code splitting and optional SPA, SSR and static rendering strategies. ## The core idea: the route loads before it renders The key difference fits into one sentence. With the old approach, the component renders first and then loads its data. With the data router, the route loads its data first and then renders the component – with the data already in hand. For this, every route gets a function, the `loader`. It runs during navigation, before anything appears on the screen. Only when it’s done does React render the component, which picks up the data fully loaded instead of fetching it itself. This removes the loading logic from the component body. No more `useEffect` that loads on first render, no handful of `useState` calls for a state that, strictly speaking, should never exist – because by the time the component renders, the data is long there. The writing counterpart is called `action`. It receives form submissions, writes to the server, and afterward React Router reloads the affected `loader`s on its own so that the view is correct again. ## `createBrowserRouter` and the route objects You no longer describe the application as nested JSX elements but as objects. `createBrowserRouter` takes an array of route definitions, and each definition carries its building blocks in one place: the path, the component, the `loader`, the `action`, the error element. ```jsx import { createBrowserRouter } from "react-router"; import { RouterProvider } from "react-router/dom"; const router = createBrowserRouter([ { path: "/invoices", element: , loader: invoiceListLoader, errorElement: , children: [ { path: ":invoiceId", element: , loader: invoiceDetailLoader, action: invoiceDetailAction, }, ], }, ]); function App() { return ; } ``` Instead of hunting for `path` and `element` scattered across half the application, everything that makes up a route sits together: what it shows, where its data comes from, how it responds to writes, what happens on an error. This bundling is not a cosmetic advantage. It is the prerequisite for React Router knowing the data before rendering – because the router can read from the object tree which `loader`s are responsible for a URL without rendering the components first. ## The `loader`: fetch data before rendering A `loader` is an ordinary function. Among other things, it receives the parameters from the path, fetches the data and returns it. In the component, you pick it up with `useLoaderData()`. ```jsx import { useLoaderData } from "react-router"; async function invoiceDetailLoader({ params }) { const response = await fetch(`/api/invoices/${params.invoiceId}`); if (!response.ok) { throw new Response("Not found", { status: 404 }); } return response.json(); } function InvoiceDetail() { const invoice = useLoaderData(); return

Invoice {invoice.number}

; } ``` Note what isn’t here. No `useState` for the invoice, no `useEffect` for loading, no check for `null` while loading is still in progress. When `InvoiceDetail` renders, the `loader` has finished. Whether `invoice` exists in domain terms is something the loader itself has to guarantee – for example by throwing a 404 response on an empty result. The router’s waiting doesn’t replace this validation. The real gain shows with nested routes. If someone opens `/invoices/42`, two routes are involved: the list and the detail. With the `useEffect` approach, this would run sequentially – first the list renders and loads, then the detail renders and loads. React Router knows both `loader`s in advance and starts them **in parallel**. That eliminates the waterfall: all affected `loader`s start at the same time, and the page is ready as soon as the slowest one is through. ```mermaid flowchart TB Nav["Navigation to /invoices/42"] Nav --> Match["Router determines affected routes"] Match --> L1["loader list"] Match --> L2["loader detail"] L1 --> Ready["all loaders done"] L2 --> Ready Ready --> Render["Components render
with useLoaderData"] ``` Here the connection to the server cache is worth making. In the post on [client state and server cache](https://www.mikebild.dev/en/blog/client-state-vs-server-cache/), I showed that server data is not state you own but a copy you manage – with a key, an age and invalidation, which is what a library like TanStack Query is good for. The `loader` sits one level above that. It says *when* to load, namely during navigation, tied to the route instead of the component. Whether there’s a bare `fetch` or a cache behind it is unaffected. The two complement each other cleanly: the `loader` calls the `queryClient`, and the library decides whether it holds a fresh copy or really reloads. The router determines the timing, the cache the validity – they don’t exclude each other, they mesh. ## The `action`: writing via `
` For writes, React Router provides its own component. `` looks like an ordinary HTML form but is intercepted by the router: instead of reloading the page, it calls the `action` of the matching route and passes it the form data. ```jsx import { Form, redirect } from "react-router"; async function invoiceDetailAction({ request, params }) { const formData = await request.formData(); await fetch(`/api/invoices/${params.invoiceId}/pay`, { method: "POST", body: formData, }); return redirect(`/invoices/${params.invoiceId}`); } function InvoiceDetail() { const invoice = useLoaderData(); return (
); } ``` The decisive part happens after the `action`: by default, React Router revalidates the loaders of the active routes. The invoice has been paid, the `action` is through, and the view can show the fresh state because the affected loaders ran again. You can restrict this behavior with `shouldRevalidate`; external caches still have to be invalidated appropriately. The flow resembles the browser principle of “submit the form, fetch the page again,” just without rebuilding the whole document. ```mermaid flowchart LR F["Form method=post"] --> A["action writes
to the server"] A --> R["loaders are
revalidated"] R --> U["View shows
fresh state"] ``` If you compare this with the `useEffect` dashboard from the server cache post, you’ll recognize the same illness and a different medicine. There, the number at the top and the list next to it drifted apart because nobody made sure both reloaded after paying. Here, they reload together after the `action`, because revalidation affects all `loader`s of the active route levels and not a single component. ## Nested routes and `` The objects from the first example had `children`, and that’s more than a matter of organization. Nested routes mirror the UI hierarchy: an outer layout route renders the frame – navigation, header, sidebar – and where the inner route should appear, it places an ``. ```jsx import { Outlet, NavLink } from "react-router"; function InvoiceList() { const invoices = useLoaderData(); return (
); } ``` If you navigate in Data Mode from `/invoices/42` to `/invoices/43`, the outer route, whose own parameters haven’t changed, stays in place by default; its loader doesn’t run again in this example, and only the inner route switches its data and its content in the ``. Changed search parameters or a custom `shouldRevalidate` rule can trigger a broader revalidation. The URL then reads like a path through the tree of the UI: every segment stands for a level, every level for a route, every route for a piece of UI with its own data. A layout route without any `path`, by the way, can serve purely as the shared frame while its children carry the actual addresses. ## The URL as state: search parameters So far it was about the path. The second part of the URL is at least as useful: the search parameters after the `?`. In the React overview, I argued that selection and filters belong in the URL – and `useSearchParams` is the tool for that. It feels like `useState` but writes its value into the address bar. ```jsx import { useSearchParams } from "react-router"; function InvoiceFilter() { const [searchParams, setSearchParams] = useSearchParams(); const status = searchParams.get("status") ?? "all"; return ( ); } ``` The selected filter is now in the URL – `/invoices?status=open` – and that fundamentally changes its character. This state can be shared: you send the link, and the recipient sees the same filtered list. It can be saved as a bookmark. It survives a reload because it doesn’t live in component memory but in the address. And it can be connected to the `loader`: since the `loader` has access to the `request` URL, it can read the `status` parameter and fetch the correctly filtered list from the server right away. The filter is in the URL, the `loader` reads it, the server delivers – a piece of UI state becomes a navigable place. ## Errors and slow partial data Because the `loader` runs before rendering, failure needs a place of its own. If a `loader` or an `action` throws – such as the `throw new Response(..., { status: 404 })` from above – React Router looks for the nearest route with an `errorElement` and renders it instead of the component. Inside the error element, you get at what was thrown with `useRouteError()`. ```jsx import { useRouteError } from "react-router"; function RouteError() { const error = useRouteError(); return

Something went wrong: {error.status}

; } ``` This replaces many scattered `if (error)` branches with one place at the route level. The route error boundary handles not only errors from `loader` and `action` but also render errors in its branch of routes. The application should still model expected domain errors deliberately instead of treating every negative state as an exception. One side topic, only touched on here: sometimes the page shouldn’t wait for the slowest data source. React Router 8 removed the former `defer` helper. Today, a loader returns non-critical data as a not-yet-resolved promise; in the component, `` waits for it inside a `` boundary. Critical data is still `await`ed in the loader. That way, a sluggish part doesn’t block the whole view, without needing a special `defer` response. ## A word on the three modes What I’ve shown here is called Data Mode in the current documentation: `createBrowserRouter` in an existing application. Declarative Mode with `BrowserRouter` offers classic routing without the data APIs. Framework Mode builds on Data Mode, organizes routes as modules and adds build and server functions. That’s a separate, bigger topic, and I deliberately leave it aside here. The concepts that matter – `loader`, `action`, revalidation, the URL as the place for state – stay the same in Data and Framework Mode. ## Where the data belongs The common thread of this post is a single shift. In the classic approach, loading and writing hang off the component: it renders, its effect fetches, its handlers write, and with nesting the loads line up into a waterfall. The data router anchors both at the route. The `loader` fetches the data before rendering, and neighboring levels in parallel; the `action` writes and then lets the `loader`s revalidate on their own. What remains in the component is displaying – not fetching. This finally turns the URL into what the overview only claimed it was. It is no longer the address field that shows where you are. It is the place where navigable state really lives: the path determines which routes and therefore which data get loaded, the search parameters carry filters and selection, and together they can be shared, saved and survive every reload. Once you build this way, you’re happy to move the loading logic out of the component body. ## Further reading - Repository introduction-react (routing chapter, recipes folder on data fetching): https://github.com/mikebild/introduction-react - React Router, official documentation: https://reactrouter.com/ - React Router, “Picking a Mode”: https://reactrouter.com/start/modes - React Router, “Data Loading”: https://reactrouter.com/start/data/data-loading - React Router, “Actions”: https://reactrouter.com/start/data/actions --- # React Transitions: Non-Urgent Updates with useTransition URL: https://www.mikebild.dev/en/blog/react-transitions-with-usetransition/ Date: 2024-12-13 A React UI needs two priorities: one for what has to happen immediately and one for what can wait. React’s scheduler knows different priorities, but an ordinary state update is initially treated as a direct update. Only with a transition does the application explicitly mark the subsequent rendering work as non-blocking. This becomes clearest at a point that already came up in the [post on Suspense and the use Hook](https://www.mikebild.dev/en/blog/suspense-and-the-use-hook/): the hard jump back to the fallback. The area is still showing real content, the state changes, the data is gone – and the spinner appears. That is exactly how a colleague’s question came up in a project: “The content is inside a Suspense boundary. When the state changes, the fallback kicks in. What are we supposed to do about that?” You tell React that this one update isn’t urgent. That is what `useTransition` is for. ## Urgent or non-urgent – the only distinction that counts The dividing line runs between two kinds of updates. On one side are the urgent ones: I type a letter, and the character has to appear in the input field immediately. I check a checkbox, and it has to be checked immediately. Anything that should feel like a direct physical reaction is urgent. If React delays it by even 100 milliseconds, the app feels broken. On the other side are the non-urgent updates: I switch tabs, I change the filter of a large list, I change the search query. The result of this action may take a moment. Nobody expects 10,000 newly filtered rows to appear in zero milliseconds. But what everyone does expect: that the UI doesn’t freeze in the meantime and doesn’t flicker pointlessly. React can’t infer from the name of a state value which domain reaction may wait. With the concurrent features, which have been stably available since React 18 and the switch to `createRoot`, we get the tools to communicate this intent. `useTransition` is the most important of them. ## The signature is deliberately simple ```jsx import { useTransition } from 'react'; function TabContainer() { const [isPending, startTransition] = useTransition(); const [tab, setTab] = useState('overview'); function selectTab(nextTab) { startTransition(() => { setTab(nextTab); }); } return ( <> selectTab('overview')}> Overview selectTab('reports')}> Reports
); } ``` The hook takes no parameters and returns a two-tuple: `isPending`, a Boolean, and `startTransition`, a function. Like any hook, you may only call it in a component or a custom hook. The crucial part is in `selectTab`. The `setTab` call moves into the `startTransition` callback. With that, the component tells React: “This update is a transition.” If the new panel suspends inside a Suspense boundary that is already visible, React can leave the previous content in place instead of immediately replacing it with the fallback. Newly added Suspense boundaries, on the other hand, may still show their fallback. As long as the transition is running, `isPending` is `true`. In my example, that is exactly what the subtle graying out via `opacity` hangs on. This is the concrete fulfillment of the Suspense promise: an update inside `startTransition` prevents content that is already visible from jumping back to the fallback. ## What really happens in the background “React takes care of it” isn’t enough of an explanation, so here is the flow explicitly as a diagram. The important part is the branch at the end: a transition is interruptible. ```mermaid flowchart TD A[User clicks tab] --> B[setTab runs in
startTransition] B --> C[React renders new tab
in the background] C --> D[Old UI stays visible
isPending = true] D --> E{New data /
render done?} E -->|yes| F[Switch to the new UI
isPending = false] E -->|urgent update
comes in| G[Background render is
discarded and restarted] G --> C ``` The left path is the normal case: React renders in the background, keeps the old UI, shows `isPending`, and switches at the end. The right path is the reason the app stays responsive during expensive updates at all. If a more urgent update comes in during the background render – a keystroke, for example – React discards the half-finished work and starts over. You don’t have to wait until the expensive render is done before you can type again. This interruptibility is the real trick behind the word “concurrent.” ## startTransition without a component Not every state change originates in a component. In routers and stores, the triggering logic often sits outside the component tree. For this case, there is the standalone import: ```jsx import { startTransition } from 'react'; function navigate(url) { startTransition(() => { setCurrentUrl(url); }); } ``` This variant works everywhere but has a price: it doesn’t provide `isPending`. If you want to show the loading state, you need the hook. If you only want to mark an update as non-urgent and get the pending state from somewhere else, the standalone import serves you well. I use it deliberately in router callbacks, where the navigation indicator lives somewhere else anyway. By the way, since React 19, stable since December 2024, `startTransition` also accepts async functions; the new Actions and `
` build on this internally. That is a topic of its own – all that matters here is that the transition mechanism itself is the foundation underneath. ## The classic mistake: freezing the input field In code reviews, the same obvious mistake shows up at this point again and again. If a transition defuses expensive renders, why not simply wrap every update – including the search field’s? ```jsx // Do NOT do this function onChange(e) { startTransition(() => { setText(e.target.value); }); } ``` The result is a sluggish, mushy input field. The reason: text in the input is an urgent update. It feels directly physical; every letter has to appear immediately. If you put it in a transition, React may delay and interrupt it – and it does. So controlled inputs stay urgent, and the text state is set as usual. What is expensive isn’t the typing but what follows from the text – the filtered list. And there is a separate tool for that. ## useDeferredValue: when part of the display may lag behind `useTransition` marks state updates at the place that triggers them. `useDeferredValue` takes a different approach: the current value stays urgent and visible, while an expensive consumer may temporarily keep working with the previous version. That is useful for props, but just as much for local input state whose derived list should catch up more slowly. ```jsx import { useDeferredValue, useState } from 'react'; function SearchPage() { const [query, setQuery] = useState(''); const deferredQuery = useDeferredValue(query); const isStale = query !== deferredQuery; return ( <> setQuery(e.target.value)} />
); } ``` Here, the input field stays urgent: `setQuery` runs without any transition, and every letter appears immediately. But the expensive `SlowList` doesn’t get `query`; it gets `deferredQuery`. React first keeps rendering with the old value – the list stays put for a moment – and then re-renders with the new value in the background. The comparison `query !== deferredQuery` tells me whether the list is currently stale, and I gray it out subtly in the meantime. Since React 19, the signature takes an optional second argument: `useDeferredValue(value, initialValue)`. Without `initialValue`, nothing is deferred on the very first render; if you provide it, the first pass renders with this initial value and pushes the real value into the background. For everyday use, the single-argument form is almost always enough. One point that leads to misunderstandings again and again: `useDeferredValue` is not a debounce and not a throttle. There is no fixed delay, and it doesn’t prevent network requests. It is pure render prioritization. If you trigger a fetch on every keystroke, you have the same storm of fetches with `useDeferredValue` as before – only the rendering of the results is spread out. Debouncing the request remains a separate task. ## The second classic: the lost context after await As soon as async functions come into play, almost everyone falls into the same trap: ```jsx // The transition context is lost after the await startTransition(async () => { const data = await fetchPage(url); setPage(data); // no longer part of the transition }); ``` The `setPage` after the `await` no longer runs inside the transition. React tracks the transition context synchronously; after an `await`, the original call returned long ago. The fix is unspectacular: wrap the update after the `await` again. ```jsx startTransition(async () => { const data = await fetchPage(url); startTransition(() => { setPage(data); }); }); ``` A related stumbling block: a `set` call that happens from inside a `setTimeout` isn’t marked as a transition either, even if the `setTimeout` is inside `startTransition`. The callback only runs later, outside the synchronous window. `startTransition` expects a synchronous update; anything pushed into a later tick falls out of the transition context. ## Which tool when – the decision tree Whether `useTransition` or `useDeferredValue` applies depends on what may be delayed: the state transition itself or just a downstream part of the display. ```mermaid flowchart TD A[Expensive update must not
block interaction] --> B{May the transition
itself wait?} B -->|yes| C[useTransition /
startTransition] B -->|no, only the consumer| D[useDeferredValue] C --> E[Update is marked
isPending available] D --> F[Current value applies immediately
consumer catches up] E --> G[Both: old UI stays in place
instead of fallback] F --> G ``` So the dividing line isn’t “which one is more modern” but simply the question of control. To condense it, here are the two tools side by side: - `useTransition` / `startTransition`: I control an update whose visible result may wait. I want to avoid the hard jump back to the fallback, and with the hook I also need `isPending`. Typical: a tab switch or a non-urgent navigation. - `useDeferredValue`: the current value must apply immediately, but an expensive consumer may still see the previous version for a moment. There is no pending flag, but there is the comparison `value !== deferredValue` to gray out stale displays. Typical: the large derived list under a fast input field. What both have in common is that less urgent rendering work may take a back seat to a direct interaction. With a Suspense boundary that is already visible, the existing content can stay in place as a result. The difference lies in whether the triggering update or a value for downstream consumers is delayed; only `useTransition` provides `isPending`. ## What I recommend in practice A few guardrails that have proven themselves in projects: - State that drives a controlled text field stays urgent and must not go into a transition. For other direct inputs, I check which part has to react immediately and which follow-up work can wait. - Navigation and tab switches can belong in `startTransition` if their target suspends or renders expensively. Routers may already handle this coordination themselves. - For expensive derived renders under a fast input, `useDeferredValue` is the tool, because the current input value should stay visible immediately and only the list catches up. - `isPending` and `value !== deferredValue` indicate that something is currently stale. I use them for subtle graying out instead of a full-page spinner. After all, the whole point is that the content doesn’t disappear. - The loss of context after `await` and in `setTimeout` is treacherous. If an update stubbornly behaves as urgent even though it is inside a transition, that is almost always the cause. If you want to place the concurrent features in a broader context, you will find the bigger picture in my React overview from JSX to architecture. The key point for today stays narrow: React can’t know which domain reaction has to be visible immediately and which rendering work can wait. `useTransition` and `useDeferredValue` express this intent in different places. With expensive renders, this can keep the UI responsive; with Suspense content that is already visible, it lets you avoid an unnecessary jump back to the fallback. ## Further reading - Repository: the examples for the tab switch with `useTransition`, the `useDeferredValue` search field, and the standalone `startTransition` are available as a runnable repo. - [react.dev – useTransition](https://react.dev/reference/react/useTransition) - [react.dev – startTransition](https://react.dev/reference/react/startTransition) - [react.dev – useDeferredValue](https://react.dev/reference/react/useDeferredValue) - [react.dev – Suspense](https://react.dev/reference/react/Suspense) - [React 19 release (Actions and transition context)](https://react.dev/blog/2024/12/05/react-19) --- # React Testing Without Theater URL: https://www.mikebild.dev/en/blog/react-testing-without-theater/ Date: 2024-12-12 # React Testing Without Theater A green test doesn’t prove that the application works. At first, it only proves that the code still looks the way it did on the day the test was written. React suites like to blur exactly this difference: every component is surrounded by mocks, every assertion knows the hook, the state, the name of the internal function. Such tests turn red in droves at the first refactoring, even though the application still works unchanged from a domain point of view – expensive to maintain and saying nothing about the product. That is the theater in the title: lots of stage, little substance. The occasion for this post is mundane: a small Vite React app from the `introduction-react` repo, a single test, one visible line in the UI. What’s interesting is not the line but the boundary it draws – between what a user experiences and how I built it internally. This boundary is the real architectural decision in testing. If you draw it cleanly, you get tests that survive rebuilds. If you miss it, you get a suite that has to be maintained every sprint and still doesn’t catch a regression. ## The thesis: behavior beats implementation A test has exactly two jobs. It should catch real misbehavior before it reaches the user. And it shouldn’t stop me from restructuring the code. These two goals are in tension, and the resolution is: test what the user observes, not how the component achieves it internally. The difference becomes visible in two variants of the same test. First, the brittle variant that couples to the internals: ```tsx // Brittle: couples the test to internal state and structure test("increments the count state", () => { const { result } = renderHook(() => useCounter()); act(() => result.current.increment()); expect(result.current.count).toBe(1); }); ``` This test knows the hook, its return value and that “increment” is called that. As soon as I replace `useCounter` with a reducer, a store or a completely different mechanism, it breaks – even though the counter in the browser keeps doing what it should. The test measures my implementation, not the product. Now the same assertion via observable behavior: ```tsx // Robust: asserts what the user actually sees test("shows the new count after a click", async () => { const user = userEvent.setup(); render(); await user.click(screen.getByRole("button", { name: /increment/i })); expect(screen.getByRole("status")).toHaveTextContent("Count: 1"); }); ``` This test knows nothing about hooks, state or structure. It knows that there is a button you click, and that a number appears afterwards. That is exactly the contract with the user. I can swap out all the internals, and as long as this contract holds, the test stays green. This is the point at which a test turns from a brake on restructuring into a safety net. ## Where the boundary physically runs This boundary is not an attitude; it is built into the query design of Testing Library. The order of the queries is a statement about trade-offs: `getByRole` and `getByLabelText` first, `getByText` after that, `getByTestId` as a last resort. That isn’t a matter of style. A role query checks accessibility along the way – if the test finds the element by its role, a screen reader finds it too. A `data-testid` only checks that I stuck a label on myself. ```tsx // Prefer accessible queries – they double as an a11y assertion screen.getByRole("searchbox"); screen.getByRole("button", { name: /search/i }); // testid is an escape hatch, not the default screen.getByTestId("product-list"); ``` The practical consequence: I write components so that they can be addressed through roles and labels – semantic elements, `aria-label` where needed, real `; } ``` The `?` after `disabled` makes the prop optional. If someone forgets `label`, the compiler reports a missing required prop – not an `undefined` that later ends up as an empty button, but an error right where it happens. In code reviews, this is where the question reliably comes up: `interface` or `type`? Both work for props, and the pragmatic rule of thumb from the React TypeScript Cheatsheet is: “interface until you need type.” In other words: - `interface` supports declaration merging, which is handy for public library APIs, and reads a bit more naturally for simple object shapes. - `type` is the right choice as soon as you need union types, mapped types or compositions of several types – things an `interface` cannot express. For 90 percent of component props, the choice is purely a matter of taste. What matters is consistency in the team, not the debate over principles. ## children is no longer automatic As soon as a component wraps other elements, it needs `children`. And this is worth a close look, because something fundamental changed with version 18 of `@types/react`: the implicit `children` declaration was removed. `React.FC` used to bring an automatic `children` along. Today you have to declare it yourself if your component renders children. ```tsx interface CardProps { title: string; children?: React.ReactNode; } function Card({ title, children }: CardProps) { return (

{title}

{children}
); } ``` `React.ReactNode` is the right type for “anything that can be rendered”: strings, numbers, elements, arrays of those, `null`, `boolean`. If instead you want to enforce exactly one single element, you reach for `React.ReactElement`. By the way, in the version 18 types, the JSX namespace lives under `React.JSX`, so a single element can also be described as `React.JSX.Element`. For everyday work, `ReactNode` is almost always enough – it is deliberately generous. The fact that `children` no longer appears by magic is one of the reasons `React.FC` has lost importance. More on that shortly. ## Typing state: when inference is enough and when it isn’t `useState` is a nice example of how TypeScript doesn’t demand manual work everywhere. Most of the time, the compiler infers the type from the initial value: ```tsx const [count, setCount] = useState(0); // number const [name, setName] = useState(''); // string const [open, setOpen] = useState(false); // boolean ``` Adding a generic here would just be ballast. The inference is unambiguous, and `setCount('drei')` still fails at the compiler. It gets interesting when the initial value tells the compiler too little. I have fixed this pitfall in existing code many times: ```tsx // Wrong: type is inferred as `null` const [user, setUser] = useState(null); // later setUser({ id: 1, name: 'Mike' }) -> compile error // Correct: specify the generic explicitly const [user, setUser] = useState(null); ``` If you start with `null`, TypeScript infers the type `null` – and then you can never write anything else into it. The same happens with `useState([])`, which becomes `never[]`, or with an empty object. The rule I have adopted for this: if the initial value is empty, `null` or an empty array, specify the type with the generic. ```tsx const [items, setItems] = useState([]); const [selected, setSelected] = useState(null); ``` ## Typing events: no more `any` The next classic is event handlers. In JavaScript, you write `onChange={(e) => setValue(e.target.value)}` and don’t think further. In TypeScript, `e` without a type is an `any` – and `any` is the hole through which exactly the errors we wanted to get rid of come back. React ships precise types for its synthetic events. You just have to pick the right one. ```tsx function LoginForm() { const [email, setEmail] = useState(''); const handleChange = (e: React.ChangeEvent) => { setEmail(e.target.value); }; const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); console.log('submitting', email); }; return ( ); } ``` Two things matter here. First, the generic has to match the element: an `` yields `HTMLInputElement`, and only then is `e.target.value` known at all. If you accidentally write `HTMLElement`, you lose `value`. Second, there are matching types for `onChange`, `onSubmit` and `onClick`: - `React.ChangeEvent` for inputs, and likewise `HTMLSelectElement` and `HTMLTextAreaElement`. - `React.FormEvent` for submitting a form. - `React.MouseEvent` for clicks. If you define the handler inline, directly on the JSX attribute, you can often skip the type, because React infers it from the context. But as soon as you pull the handler out into a separate function, you have to specify the event type yourself. For props that take a handler, there are also the shorthands `React.ChangeEventHandler` and `React.FormEventHandler` – handy when you pass a callback down as a prop. ## useRef: DOM reference with a null check `useRef` is confusing at first because it plays two roles. The most common one is the DOM reference, for example to focus a field on mount. ```tsx function SearchBox() { const inputRef = useRef(null); useEffect(() => { inputRef.current?.focus(); }, []); return ; } ``` Three details count. The generic `` says what the ref points to. The initial value `null` is intentional: before the first render, the DOM element doesn’t exist yet. This combination produces a read-only `RefObject`, and that is exactly what fits the JSX attribute `ref`. Because `current` can be `null` before mounting, you need a null check on access – hence the `?.` in `inputRef.current?.focus()`. Without the guard, the compiler rightly complains. The second role of `useRef` is that of a mutable instance variable that doesn’t trigger a re-render – for example, to hold on to a timer ID or a previous value: ```tsx const timerRef = useRef(null); const start = () => { timerRef.current = window.setTimeout(() => { console.log('done'); }, 1000); }; ``` Here `current` is writable. The difference comes from the overload: with `null` in the union type and no DOM reference, you get a `MutableRefObject`. You don’t have to memorize this subtlety, but it helps to know that the DOM case is deliberately read-only. ## Utility types: derive props instead of copying them When data structures grow, you don’t want to update props by hand in three places. That is what the utility types from the TypeScript standard library are for – not from React, but constantly useful in everyday React work. Suppose there is a `User`: ```ts interface User { id: string; name: string; email: string; role: 'admin' | 'member'; } ``` A form that only edits name and email doesn’t need the whole `User`. `Pick` cuts out the relevant fields: ```ts type EditUserProps = Pick; ``` Conversely, `Omit` removes what you don’t want – for example, the server-assigned `id`: ```ts type NewUserProps = Omit; ``` `Partial` makes all fields optional, which fits patch operations or intermediate form states: ```ts type UserDraft = Partial; ``` The gain: if `User` changes, the derived types follow automatically. No field gets out of step. Besides `Pick`, `Omit` and `Partial`, `Required` and `Readonly` belong to the standard repertoire. A React-specific trick rounds out the picture: if your component should inherit the native props of an HTML element – all standard button attributes, for example – you use `React.ComponentPropsWithoutRef`: ```tsx type IconButtonProps = React.ComponentPropsWithoutRef<'button'> & { icon: string; }; function IconButton({ icon, ...rest }: IconButtonProps) { return ( ); } ``` This way you get `onClick`, `disabled`, `type` and all the other button attributes for free and type-checked, without listing them one by one. ## Everyday types at a glance This overview shows the five corners where you deal with types most often in a typed React component. ```mermaid graph TD K[Types in everyday React] --> P[Props
interface / type] K --> S[State
useState<T>] K --> E[Events
ChangeEvent / FormEvent] K --> R[Refs
useRef<HTMLInputElement>] K --> U[Derivation
Pick / Omit / Partial] P --> C[children:
ReactNode] ``` These five cover most of the daily work. Everything else builds on them. ## And what about React.FC? The question is guaranteed to come up, often with a code example from an older tutorial: `const Button: React.FC = (props) => ...`. Is that wrong? No. It works, it is available in 2024, and nobody has to rewrite existing code. But the modern default is the plain function with typed props, and there are reasons for that. Historically, the most important one was the implicit `children` that `React.FC` brought along – components accepted children even when they weren’t supposed to render any. With `@types/react` 18, this implicit `children` was removed, which defused one of the main points of criticism. What remains is mainly that `React.FC` gets in the way of generic components. If you want to write a type-safe list component over an arbitrary element type, you are better off with a normal function: ```tsx interface ListProps { items: T[]; render: (item: T) => React.ReactNode; } function List({ items, render }: ListProps) { return
    {items.map((item, i) =>
  • {render(item)}
  • )}
; } ``` Something like this is awkward to express with `React.FC`. So today `React.FC` is a question of style, not a mistake. Pick one variant in your team and stick with it. I write normal functions myself, because they are more flexible with generics and come with fewer special rules. ## Coming back to hooks If you already write your own hooks, you quickly notice that the building blocks shown here carry straight over: a custom hook returns typed state, takes typed arguments and encapsulates event logic. If you haven’t taken the path to reusable logic yet, have a look at [From HOCs and Render Props to Custom Hooks](https://www.mikebild.dev/en/blog/from-hocs-and-render-props-to-custom-hooks/) – the typing from this article is exactly what turns a custom hook from a loose collection of functions into a clear contract. ## Conclusion The gain of TypeScript in React can be summed up in four effects, and none of them is in the API documentation. Shorter cycles, because an integration error shows up in the editor in seconds instead of in days via a bug report. Less friction at the most expensive place, the boundary between components and teams, because the contract automatically checks what would otherwise be agreed on verbally and then forgotten. Higher quality, because a wrong prop type, a forgotten required field or a `null` that should never have stayed `null` never makes it into the build in the first place. And clear boundaries, because a typed props and event signature says unambiguously what goes in and what comes out. Getting started is manageable. Props as `interface` or `type`, `children` declared explicitly as `ReactNode`, `useState` with a generic only where inference is too narrow, the matching event types instead of `any`, `useRef` with a null check, and utility types to derive props instead of copying them. These six moves cover everyday work. Everything beyond that – generic components, complex unions, your own hooks – continues the same idea: type the boundaries where responsibilities meet, say clearly what you expect, and let the compiler make sure everyone sticks to it. ## Further reading - React TypeScript Cheatsheet: [react-typescript-cheatsheet.netlify.app](https://react-typescript-cheatsheet.netlify.app/) and the repository [github.com/typescript-cheatsheets/react](https://github.com/typescript-cheatsheets/react) - react.dev – “Using TypeScript”: [react.dev/learn/typescript](https://react.dev/learn/typescript) - react.dev – hooks reference: [useState](https://react.dev/reference/react/useState) and [useRef](https://react.dev/reference/react/useRef) - TypeScript Handbook – Utility Types: [typescriptlang.org/docs/handbook/utility-types.html](https://www.typescriptlang.org/docs/handbook/utility-types.html) - DefinitelyTyped – `@types/react`: [github.com/DefinitelyTyped/DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/react) --- # Resilience Patterns: Timeout, Retry, Circuit Breaker, Idempotency URL: https://www.mikebild.dev/en/blog/resilience-patterns-timeout-retry-circuit-breaker/ Date: 2024-01-30 A distributed system rarely falls over because of a spectacular crash. It falls over because a service still answers – just a little slower than usual. Add a call that nobody ever gave a time limit. And a client that dutifully keeps pushing requests while the dependency is long since down. That is how a single shaky component drags half the system down with it, without a single process crashing anywhere. Distributed calls fail. Over a longer period, that is part of normal operation. The network is slow now and then, a node gets restarted, a database hits its limit. The question is never whether a remote call fails, but what happens when it does. And this is exactly where it is decided whether a system is resilient or only looks stable until things get serious for the first time. Resilience is designed, not hoped for. I check four patterns for distributed calls: timeout, retry, circuit breaker and idempotency. Not every call needs all four; the choice depends on the failure mode, the cost and the semantics of the operation. The TypeScript code below is illustrative – it is about the mechanics behind it, not a production-ready library. The patterns differ mainly in the failure state they react to. Their names alone don’t tell you whether they make sense at a given boundary. ::::comparison{title="Resilience patterns by failure question" role="primary" preferredPattern="comparison-matrix"} :::side{label="Timeout"} - Question · How long may a single attempt take? - Effect · limits blocked resources ::: :::side{label="Retry"} - Question · Is the failure transient and the attempt safe to repeat? - Effect · repeats with bounded backoff and jitter ::: :::side{label="Circuit Breaker"} - Question · Should a visibly impaired target keep getting load? - Effect · interrupts calls and checks again later in a controlled way ::: :::side{label="Bulkhead"} - Question · How does a failure stay confined to one part of the system? - Effect · separates resources and areas of contention ::: :::side{label="Dead Letter Queue"} - Question · What happens to messages that can never be processed? - Effect · keeps failure cases for inspection and targeted reprocessing ::: :::: Only the failure question shows which patterns complement each other and which would just create extra traffic or hidden queues. ## The patterns at a glance Before I get into the code, a short overview. Four patterns, each with a clear responsibility: - A timeout limits how long a single call may wait. Without a timeout, a call may wait forever – and block a thread, a connection, a slot in the pool while doing so. - A retry repeats a failed call – but only for transient errors, only with exponential backoff and jitter, and only with a limited number of attempts. - A circuit breaker stops further calls to a visibly failed dependency so you don’t keep hammering it endlessly. - Idempotency is what makes retries safe in the first place: a call sent several times has the same effect as a single one. These four can interlock, but they are not an inseparable package. A timeout may deliberately fail fast without a retry. A retry on a non-idempotent operation can produce duplicate effects. A circuit breaker needs a usable failure signal, which often comes from a timeout. You only combine the patterns that fit the call at hand. ## Timeout: never wait forever The most expensive timeout is the one that doesn’t exist. A remote call without a time limit isn’t slow, it is potentially infinite. And infinity is a failure mode: threads pile up, connection pools run dry, and a service that is really just waiting on a slow downstream becomes unreachable itself. The distinction between the connection timeout (how long may establishing the connection take) and the request timeout (how long may the entire response take) matters. Set both. And both belong to the specific call, not nailed globally to one value – a health check has a different tolerance than a report export. In practice, I wrap this in a small helper. `Promise.race` against a timer, plus an `AbortController`, so the underlying operation is actually canceled and doesn’t keep running in the background: ```ts export async function withTimeout( fn: (signal: AbortSignal) => Promise, timeoutMs: number, ): Promise { const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), timeoutMs); try { return await fn(controller.signal); } finally { clearTimeout(timer); } } // usage: the signal is forwarded to fetch so the socket is released const result = await withTimeout( (signal) => fetch("https://payments.internal/charge", { signal }), 2_000, ); ``` The `AbortSignal` is the part that is easy to forget. A `Promise.race` that only cancels the waiting but leaves the HTTP connection open has merely moved the problem: the socket stays occupied. Only the forwarded signal releases the resource. A subtle interaction that Marc Brooker points out in the AWS Builders’ Library: a timeout set too low can itself trigger retry storms. If regular latency occasionally exceeds the timeout limit, the client interprets healthy responses as failures and retries – and creates exactly the load that then really tips the server over. You set timeouts based on the real latency distribution, not on wishful thinking. ## Retry: backoff and jitter, but with judgment Retry is the pattern that backfires fastest. The naive variant – “on error, try again immediately, and again, and again” – has nothing to do with resilience. It is a load weapon aimed at your own downstream. A server that is already under pressure gets finished off by synchronized repetitions from all clients. Three ingredients make retry usable. **Exponential backoff**: the wait time grows with each attempt (`base * 2^attempt`) so an overloaded service gets some air. A **cap**: the wait time doesn’t run to infinity but toward an upper limit. And **jitter**: a random component that keeps all clients from aligning their retries to the same millisecond and creating synchronized load spikes. There are several variants of jitter – Marc Brooker compared them in 2015 on the AWS Architecture Blog: Full Jitter, Equal Jitter, Decorrelated Jitter. The practical recommendation from that analysis is usually Full Jitter, because it spreads the retries most evenly across the time window. The formula is pleasantly simple: ```ts type RetryOptions = { maxAttempts: number; baseDelayMs: number; capMs: number; isRetryable: (error: unknown) => boolean; }; export async function retryWithBackoff( fn: () => Promise, opts: RetryOptions, ): Promise { let lastError: unknown; for (let attempt = 0; attempt < opts.maxAttempts; attempt++) { try { return await fn(); } catch (error) { lastError = error; if (!opts.isRetryable(error) || attempt === opts.maxAttempts - 1) { throw error; } // full jitter: random point in the exponentially growing window const window = Math.min(opts.capMs, opts.baseDelayMs * 2 ** attempt); const delay = Math.random() * window; await new Promise((resolve) => setTimeout(resolve, delay)); } } throw lastError; } ``` The `isRetryable` callback is deliberately pulled out. Not every error is retryable. A `503 Service Unavailable`, a dropped connection or a timeout can be transient. An unchanged `400 Bad Request`, on the other hand, stays wrong. Even `409 Conflict` isn’t a blanket no: after re-reading, with a new version number or an adjusted operation, another attempt can make sense; blindly repeating the identical request usually doesn’t. Retry decisions therefore need the error code, the operation and the remaining time budget. The AWS Well-Architected guidance sums this up under REL05-BP03 (“Control and limit retry calls”): backoff, jitter and a maximum number of attempts belong together. The AWS SDKs already implement exactly that in their built-in retry modes `standard` and `adaptive` – if you work at that level, you shouldn’t put a second retry loop of your own on top. Which brings us to the most dangerous pitfall. ## The retry storm Retries stack up. The client retries, the SDK underneath retries, the API gateway in front retries. Three layers with three attempts each are not three but up to twenty-seven calls for a single user action. If jitter is missing on top of that and all clients start at the same time, you get a retry storm: multiplicative load that hits the server exactly at the moment it can least handle it. The remedy is discipline, not more technology. For every call chain, it should be clear which layer owns the retry and which shared time and attempt budget applies. Lower layers such as an SDK may have their own retries if the layers above know about them and don’t multiply them in an uncoordinated way. Jitter and cap belong in the responsible place. If you coordinate many clients, add a retry budget or client-side rate limiting with a token bucket. ## Circuit breaker: stop hammering Retry with backoff cushions short disruptions. But what if a dependency doesn’t just cough briefly but really fails – for minutes? Then every further attempt is wasted load, wasted latency and wasted resources. This is exactly where the circuit breaker comes in, a pattern that Michael Nygard coined in “Release It!”. The idea comes from electrical engineering: a circuit breaker interrupts the circuit before the wire burns through. Applied to software, that means – when a dependency is visibly down, the breaker opens and lets calls fail immediately (fail fast) instead of running them into a dead timeout. The breaker knows three states: ```mermaid stateDiagram-v2 [*] --> CLOSED CLOSED --> OPEN: Failures >= threshold OPEN --> HALF_OPEN: Cooldown expired HALF_OPEN --> CLOSED: Probe succeeds HALF_OPEN --> OPEN: Probe fails ``` In the **CLOSED** state, everything runs normally; the breaker just counts the failures. If the number of failures exceeds a threshold, it switches to **OPEN**: calls are no longer let through but fail immediately – the client gets a quick answer or a fallback instead of a hanging connection. After a cooldown, the breaker moves to **HALF_OPEN** and lets a single probe request through. If it succeeds, it closes again (CLOSED). If it fails, it opens again and waits for the next cooldown. As a small state machine, this is manageable: ```ts type BreakerState = "CLOSED" | "OPEN" | "HALF_OPEN"; export class CircuitBreaker { private state: BreakerState = "CLOSED"; private failureCount = 0; private openedAt = 0; constructor( private readonly failureThreshold: number, private readonly cooldownMs: number, ) {} async execute(fn: () => Promise): Promise { if (this.state === "OPEN") { if (Date.now() - this.openedAt < this.cooldownMs) { throw new Error("circuit is open"); } this.state = "HALF_OPEN"; } try { const result = await fn(); this.onSuccess(); return result; } catch (error) { this.onFailure(); throw error; } } private onSuccess(): void { this.failureCount = 0; this.state = "CLOSED"; } private onFailure(): void { this.failureCount++; if (this.state === "HALF_OPEN" || this.failureCount >= this.failureThreshold) { this.state = "OPEN"; this.openedAt = Date.now(); } } } ``` AWS files the circuit breaker in Well-Architected under REL05-BP01 – “graceful degradation”, turning a hard dependency into a soft one. Instead of a failed recommendation service dragging down the whole product page, the breaker in the OPEN state delivers a fallback (such as a static list) and the page stays usable. That is the real gain: not the perfect answer, but an acceptable one that keeps the overall system alive. In production, you don’t have to write this yourself – established libraries such as `opossum` for Node.js, Polly for .NET or resilience4j for Java come with it, including metrics and half-open sampling. The code above is illustrative so the state logic stays visible. ## Idempotency: what makes retries safe Now the circle closes back to retry. A retry is only harmless if the repeated operation has the same effect as a single one. That is exactly what idempotency means. For a read, this is trivial – two `GET`s do no harm. For a write, it gets serious: if the first attempt at a payment actually went through but the response got lost in the timeout, the retry charges a second time. The customer pays twice. HTTP semantics provide a frame here: `GET`, `PUT` and `DELETE` count as idempotent, `POST` in principle does not. Idempotent means the same intended effect on repetition; the status code or response don’t have to be identical. Where you can design operations accordingly – a `PUT` on a natural ID instead of a `POST` that creates a new resource every time – you should. Where that isn’t possible, for example with “charge” or “send”, an explicit **idempotency key** helps. The client generates a unique key per business operation and sends it along; the server remembers key plus result and thereby prevents the second side effect. The pattern has been established for years – Stripe, for example, uses an `Idempotency-Key` header. At the time, an IETF standard was merely an Internet-Draft (`draft-ietf-httpapi-idempotency-key-header`), but the pattern itself works regardless. On the server side, the core looks like this: ```ts type Result = { status: string; id: string }; interface IdempotencyStore { get(key: string): Promise; set(key: string, value: Result): Promise; } export async function handleRequest( key: string, op: () => Promise, store: IdempotencyStore, ): Promise { const existing = await store.get(key); if (existing) { // key already processed: return the stored result, no second side effect return existing; } const result = await op(); await store.set(key, result); return result; } ``` Two details matter in real life. First, the store needs an expiry (TTL) – keeping idempotency keys forever is neither necessary nor cheap. Second, there is a concurrency problem: if two retries arrive almost simultaneously, the second can complete its `get` before the first writes its `set`. In production, you solve this with an atomic reservation of the key (for example a conditional insert), not with the naive get-then-set above. The code shows the principle, not the production-ready lock. ## Bulkhead and DLQ, briefly Two patterns round out the picture without me going into detail here. The **bulkhead** – named after the watertight compartments in a ship’s hull – isolates resources so that one overloaded path doesn’t flood the whole system. Separate connection pools or thread pools per downstream make sure a hanging dependency only exhausts its own pool and doesn’t drag all other calls into the abyss with it. This also comes from “Release It!”. And the **dead letter queue** (DLQ) is the catch basin for the case where all retries are exhausted. Instead of spinning an unprocessable message in circles forever or losing it silently, it lands in a separate queue – for inspection, for manual intervention or for a later retry. In AWS, this is a standard building block of SQS and SNS. If you want to orchestrate the chaining of such steps cleanly, [Serverless Workflows with AWS Step Functions](https://www.mikebild.dev/en/blog/serverless-workflows-with-aws-step-functions/) gives you the right frame, and I described how to spread load across several processes in [child_process and Scaling](https://www.mikebild.dev/en/blog/child-process-in-nodejs-scaling-without-illusions/). ## Conclusion Three mistakes show up in post-mortems again and again. No timeout – a call that may wait forever and ties up resources while doing so. Retry without jitter and cap – the well-meant retry that turns into a retry storm and finishes off the weak server for good. And non-idempotent writes that get repeated – the double charge nobody saw coming. All three have a common root: resilience was hoped for, not designed. The four patterns – timeout, retry, circuit breaker, idempotency – are not a library you import but decisions per call. Remote calls need a justified time limit. Retries need a budget, backoff and jitter. A breaker pays off for dependencies whose sustained failure would otherwise keep generating load and latency. An idempotency key belongs to operations where repetition is possible and a duplicate effect is harmful. That way, a system under load can degrade in a controlled manner instead of multiplying its failure. ## Further reading - [AWS Well-Architected, REL05-BP03 – Control and limit retry calls](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_mitigate_interaction_failure_limit_retries.html) - [AWS Well-Architected, REL05-BP01 – Graceful degradation (Circuit Breaker)](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_mitigate_interaction_failure_graceful_degradation.html) - [AWS Well-Architected, REL05-BP02 – Throttle requests (Token Bucket)](https://docs.aws.amazon.com/wellarchitected/latest/framework/rel_mitigate_interaction_failure_throttle_requests.html) - [AWS Builders’ Library – Timeouts, retries, and backoff with jitter (Marc Brooker)](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/) - [AWS Architecture Blog – Exponential Backoff And Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) - [Michael Nygard – Release It! (2nd edition, 2018)](https://pragprog.com/titles/mnee2/release-it-second-edition/) --- # GraphQL Subscriptions over SSE: Real Time Without Being Forced into WebSocket URL: https://www.mikebild.dev/en/blog/graphql-subscriptions-over-sse/ Date: 2024-01-12 If you set up a WebSocket for a one-way update flow, you bring a second protocol into operations: the upgrade handshake, sticky sessions, proxies and load balancers that need to know about it, plus reconnect and heartbeat as your own responsibility. The reason for it is usually modest – an order changes its status, a dashboard tile updates without a reload. The reason is done after one sprint; the transport stays and needs to be operated for years. So behind “real time” there is rarely a syntax problem and almost always an operations decision. A bidirectional full-duplex channel, like the one a WebSocket opens, is not a feature you get for free; it is an operations class of its own, with its own protocol, its own handshake and its own failure patterns. That is why this text is less about how to wire up subscriptions and more about the decision before that: SSE, WebSocket or plain polling – decided by operating cost, complexity and scaling, not by what sounds modern right now. And GraphQL subscriptions don’t even prescribe a WebSocket. The specification is transport-agnostic at this point: it says that a subscription delivers an event stream – not over which wire that stream flows. And for the common case “server informs client,” there is a candidate that has been built into every browser for years and runs over ordinary HTTP: Server-Sent Events. ## Queries and mutations stay as they are Before we get to the event stream, it’s worth looking at what doesn’t change at all. A query fetches data, a mutation changes state – both are request and response, one request, one response, done. That is plain HTTP, usually a `POST /graphql`. Nothing about subscription support forces you to touch it. Only the third operation type, the subscription, needs an open channel through which the server sends events over time. This is exactly where Server-Sent Events come in. SSE is a one-way channel from the server to the client over ordinary HTTP. The server responds with the content type `text/event-stream` and keeps the connection open; the client opens it through the built-in `EventSource` interface. The browser takes care of quite a lot that you would have to bolt on painfully in a homegrown solution: it reconnects automatically when the connection drops, and on reconnect it sends the last seen event ID in the `Last-Event-ID` header so the server can pick up where it left off. ```mermaid flowchart LR subgraph Client UI[Browser app] end subgraph Server GQL[GraphQL server] end UI -- "HTTP POST /graphql
Query & Mutation" --> GQL GQL -- "HTTP response (JSON)" --> UI GQL -- "text/event-stream
Events via EventSource" --> UI ``` The diagram shows the core: two channels, one transport. Queries and mutations take the familiar path of request and response. The event stream uses the same HTTP infrastructure; the response just stays open and trickles events through. There is no protocol switch, no upgrade handshake, no special treatment by proxies that don’t know WebSocket frames. ## The server side: an AsyncIterable from PubSub On the server side, a subscription resolver is not an ordinary field resolver. Instead of a function that returns a value, it is an object with a `subscribe` method that returns an `AsyncIterable`. The GraphQL server pulls the events from this iterable and sends them to the matching client. The usual tool for this is the `graphql-subscriptions` package, currently at version 2.0.0. It comes with a `PubSub` class whose `asyncIterator(topic)` creates exactly such an iterable. ```ts import { PubSub, withFilter } from 'graphql-subscriptions'; const pubsub = new PubSub(); const ORDER_STATUS_CHANGED = 'ORDER_STATUS_CHANGED'; const resolvers = { Subscription: { orderStatusChanged: { subscribe: withFilter( () => pubsub.asyncIterator(ORDER_STATUS_CHANGED), (payload, variables) => payload.orderStatusChanged.customerId === variables.customerId, ), }, }, Mutation: { advanceOrder: (_root, { id }) => { const orderStatusChanged = advanceOrderInStore(id); pubsub.publish(ORDER_STATUS_CHANGED, { orderStatusChanged }); return orderStatusChanged; }, }, }; ``` Two things matter here. First, the `withFilter` helper: it takes the iterator function and a predicate function that decides per event whether it concerns this subscriber at all. That way each customer only gets the status changes of their own orders, even though all of them run over the same topic. Second, the publish point in the mutation: when something happens in the domain – here, an order moves forward – the event is pushed into the stream with `pubsub.publish`. The `subscribe` resolver and the mutation are decoupled through the topic; the mutation knows nothing about who is listening right now. One note that in practice often comes up too late: the bundled `PubSub` implementation keeps its state in memory and only works within a single process. As soon as several server instances sit behind a load balancer, events fizzle out – one instance publishes, but the subscribers are attached to another. For production you then need an external backend, such as a Redis-backed variant that distributes the publish across the process boundary. For local development and getting started, the built-in variant is completely sufficient. ## The SSE endpoint: the stream to the outside For the events from the iterable to actually reach the browser, you need an endpoint that delivers the stream as `text/event-stream`. Conceptually, in Express it looks like this: ```ts app.get('/graphql/stream', (req, res) => { res.set({ 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive', }); res.flushHeaders(); const iterator = pubsub.asyncIterator(ORDER_STATUS_CHANGED); (async () => { for await (const event of iterator) { res.write(`event: next\n`); res.write(`data: ${JSON.stringify(event)}\n\n`); } })(); req.on('close', () => { if (typeof iterator.return === 'function') iterator.return(); }); }); ``` The format of an SSE frame is deliberately simple: lines with field names and a colon. The `data:` field carries the payload, here the serialized event; the browser would join several `data:` lines with a line break. With `event:` you name the event type so the client can listen for it specifically; without that line, everything ends up at the general `onmessage` handler. The `id:` field sets the event ID that the browser sends back as `Last-Event-ID` on reconnect, and `retry:` specifies in milliseconds how long the browser should wait before trying to reconnect. A frame ends with an empty line, that is, a double `\n`. Lines that start with a colon are comments and work as a heartbeat to keep intermediate layers from cutting a quiet connection. The `req.on('close')` part is not an extra. When the client closes the connection, the iterator has to be shut down cleanly; otherwise subscriptions pile up and the process leaks resources. This cleanup is where an SSE integration becomes either solid or brittle. ## The client: EventSource, nothing more On the client side, the work is surprisingly small because the browser handles most of it: ```js const es = new EventSource('/graphql/stream', { withCredentials: true }); es.addEventListener('next', (e) => { const payload = JSON.parse(e.data); render(payload.orderStatusChanged); }); es.onerror = () => { // The browser reconnects on its own; the retry: field controls the interval. }; ``` No manual reconnecting, no timer, no heartbeat protocol of your own. If the connection fails, the browser tries on its own to rebuild it and sends the last received event ID along. The `withCredentials` option makes sure cookies are sent across the origin boundary – handy when authentication runs over a session cookie and the endpoint needs to know who is listening. If you want to place authorization in the GraphQL server cleanly in the execution context, you’ll find the matching pattern in [GraphQL auth in the context](https://www.mikebild.dev/en/blog/graphql-auth-identity-in-the-context/); the same logic applies to the SSE endpoint – the identity is established at the HTTP layer and is available to the resolver. ```mermaid sequenceDiagram participant B as Browser (EventSource) participant S as GraphQL server participant P as PubSub B->>S: HTTP POST advanceOrder (mutation) S->>P: pubsub.publish(topic, payload) P-->>S: asyncIterator delivers event S-->>B: data: frame (event: next) Note over B,S: Connection drops B->>S: Reconnect with Last-Event-ID S-->>B: Events since the last ID ``` ## The schema is a domain model, not an event pipe That outlines the technical part, but the more important point from project practice is a different one. As soon as there is an easy way to send events to the client, the temptation grows to pump everything possible through subscriptions: every keystroke, every internal tick, every log line. But the schema is a domain model, not a collection point for technical signals. A subscription should represent an event that means something in the domain – “order changed its status,” “comment was added,” “payment was received.” An `orderStatusChanged` tells a consumer something about the domain. A `serverTick` or `internalMetric` tells them nothing they would look for in the schema. The same modeling discipline you apply to lists and paging – see the thoughts in [GraphQL pagination and connections](https://www.mikebild.dev/en/blog/graphql-pagination-cursors-and-connections/) – applies here just the same: the schema describes the language of the domain, not the internals of the transport. If an event is not part of that language, it doesn’t belong in a subscription. ## Avoiding the wrong abstraction That brings us to the actual decision, and it happens one level below GraphQL: in the architecture. SSE, WebSocket and messaging solve different problems, and the most common source of errors is treating one as a substitute for the other. - Server-Sent Events are one-way from server to client, run HTTP-native, reconnect on their own and carry only UTF-8 text. They fit exactly when the UI should show live updates: status changes, notifications, a dashboard that refreshes itself. - WebSockets are bidirectional and have their own protocol with their own handshake. They are the right choice when the client itself continuously sends data to the server in real time – chat, collaborative editing, a game state, anything with a busy back channel. - Messaging and brokers such as Kafka, AMQP or Redis solve integration between systems. They offer persistence, fan-out and decoupling in the backend. A GraphQL subscription doesn’t replace that. It covers the last mile to the browser; the nervous system between the services remains the broker’s job. If you keep these three cleanly apart, you won’t build the wrong thing. If you mix them – say, setting up a WebSocket to serve a purely one-way update flow, or misusing subscriptions to integrate services – you pay later with complexity that no feature justifies. ## Decision framework: SSE, WebSocket or polling Separating the transports cleanly is one thing; in a project I eventually have to pick one, and a framework along three axes helps with that: operating cost, complexity and scaling. These three questions answer the transport choice more reliably than any feature list, because they ask about the price in operations, not about the feature set. Polling is the honest starting point that people skip too quickly. The client asks at an interval, “is there anything new?”, and across HTTP, caching and load balancers that is the best-understood pattern of all. The operating cost is conceptually close to zero, but the load on the server grows linearly with the number of clients and the frequency, and most of the work goes into empty responses. The complexity is minimal because there is no open channel that would need cleanup or reconnects, and scaling horizontally is trivial because each request stands on its own. For updates in the range of seconds to minutes, where a bit of latency hurts no one, polling is often the economically right answer – and the option you should check first, before you build something more elaborate. SSE sits in the middle and hits exactly the case “server informs client promptly.” The operating cost consists of one open HTTP connection per client, but it stays HTTP-native and requires no special handling in the infrastructure. The complexity is low on the client because `EventSource` comes with reconnect and `Last-Event-ID`; on the server, the effort lies mainly in cleaning up the streams properly. Scaling has its cost center in the many open connections, and the PubSub state has to be distributed across instance boundaries as soon as more than one process runs. The gain over polling is low latency without idle traffic; the price is the open channel you have to operate. WebSocket is the most expensive class and only justifies itself with a real back channel. The operating cost includes a protocol of its own with a handshake, sticky sessions and proxies that need to know about the upgrade. The complexity rises because reconnect, heartbeat and state recovery are on me, not on the browser. Scaling is hardest because long-lived, stateful connections are the least easy to distribute horizontally. This effort pays off when the client itself sends continuously in real time – chat, collaborative editing, game state. For a one-way update flow, it is effort without return. So the decision criterion is short: first check whether polling is enough; if you need prompt server-to-client updates without a back channel, SSE; and WebSocket only for busy, bidirectional traffic. If you ask in this order, you pick the cheapest transport that meets the requirement instead of the most powerful one you know – and exactly this order separates an operations decision from a matter of taste. ## Where the SSE idea comes from – and what applies today The combination of GraphQL and SSE is not new, and its history helps put today’s state in context. In the early days of Apollo Client, the 1.x era, there was the `subscriptions-transport-sse` package. Back then, it was plugged into an Apollo Client through the `networkInterface` concept: ```js // HISTORICAL — Apollo Client 1.x, not today's API. import { SubscriptionClient, addGraphQLSubscriptions, } from 'subscriptions-transport-sse'; const sseClient = new SubscriptionClient('/subscriptions'); const client = new ApolloClient({ networkInterface: addGraphQLSubscriptions(httpInterface, sseClient), }); ``` This is explicitly legacy and has no place in a new project. Both `networkInterface` and the `SubscriptionManager` of that time – the predecessor of today’s pattern with `PubSub.asyncIterator` – are concepts of a generation that was replaced long ago. I show the fragment only to make the origin of the idea visible: SSE as a transport for GraphQL events is an old idea, not an experimental one. On the WebSocket side, it’s worth looking at the current state because it frames the transport question. The formerly common `subscriptions-transport-ws` is now considered unmaintained; its repository has carried a deprecation notice for quite a while and is no longer actively developed. The recommended successor for the WebSocket path is `graphql-ws`, with a different subprotocol that is not compatible with the old one. That is only context here: `graphql-ws` is the answer when you actually need a WebSocket. It doesn’t compete with SSE; it covers the other, bidirectional case. ## What I take away from practice When someone says “real time” in a requirements conversation, the first useful follow-up question is not “WebSocket or SSE?” but “In which direction does the data flow, and how fast does it need to arrive?” Usually it flows from the server to the client and can tolerate some latency, and then Server-Sent Events are the calmer solution that is easier to operate: ordinary HTTP, built-in reconnect, no special handling in the infrastructure. Queries and mutations stay untouched; only the event stream gets its own open channel. On the server, the `subscribe` resolver returns an `AsyncIterable` from a PubSub, events come in via `publish`, and `withFilter` makes sure everyone only gets what concerns them. You can feel the gain of this mapping in everyday project work. If you choose the cheapest viable transport, you shorten the cycles to a working live update, because half of the infrastructure discussion this text started with goes away. You reduce friction in operations, because an HTTP-native stream creates fewer special cases in proxies, load balancers and deployments. And you raise quality, because the schema stays a domain model and only carries events that mean something in the language of the domain. I deliberately keep two limits in view: the built-in PubSub keeps its state in memory and needs an external backend across multiple instances, and the transport choice remains a simple mapping – polling when latency is acceptable, SSE for the one-way path to the client, WebSocket only for a real back channel. These clear limits are what make the shorter cycles and lower friction possible in the first place. ## Further reading - MDN – Using server-sent events: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events - MDN – EventSource: https://developer.mozilla.org/en-US/docs/Web/API/EventSource - graphql-subscriptions (README/API): https://github.com/apollographql/graphql-subscriptions - graphql-subscriptions (npm): https://www.npmjs.com/package/graphql-subscriptions - Apollo Server – Subscriptions: https://www.apollographql.com/docs/apollo-server/data/subscriptions - subscriptions-transport-ws (legacy/archived): https://github.com/apollographql/subscriptions-transport-ws - subscriptions-transport-sse (historical origin): https://github.com/CodeCommission/subscriptions-transport-sse - GraphQL Spec: https://spec.graphql.org/ --- # Contract Testing Instead of an E2E Marathon URL: https://www.mikebild.dev/en/blog/contract-testing-instead-of-an-e2e-marathon/ Date: 2023-12-05 ```text FAIL e2e/checkout.spec.ts ✕ Bestellung abschließen (30014 ms) TimeoutError: waiting for selector "#order-confirmation" failed: timeout 30000ms exceeded Tests: 1 failed, 213 passed Dauer: 46m 08s ``` This failure says nothing about whether the code is broken. It says that somewhere in the fully booted system, something took thirty seconds instead of three – a container that starts slowly, an animation, a network hop. On the next run, the same test is green without a single line changed. This is exactly how a nightly end-to-end suite loses its authority: it answers the question of whether you may deploy today with a roll of the dice, and at some point the team just clicks the red runs away. The E2E marathon – the suite that boots the entire system at night, clicks through real UIs and shows red or green in the morning – is therefore not a discipline problem. It fails because of its structure. And the question that actually matters is much smaller than what it checks: Do these two services still fit together? The mechanics of the answer are quickly explained; the gain lies elsewhere. The key difference is not the number of tests but the place where compatibility is checked. ::::comparison{title="Checking compatibility at the right boundary" role="primary" preferredPattern="before-after"} :::side{label="Shared E2E environment"} - Setup · start all involved systems at the same time - Signal · one complete path just ran through successfully - Weakness · the cause of failure, timing and responsible boundary often stay unclear - Coupling · releases wait for the same integrated state ::: :::side{label="Consumer-Driven Contract"} - Setup · record expectations at a service boundary - Signal · consumer and provider fulfill the same contract independently - Strength · faster, deterministic and attributable to one boundary - Limit · does not replace a small selection of real end-to-end checks ::: :::: The comparison doesn’t eliminate E2E tests. It moves the frequent compatibility check to the place where the contract actually comes into being. ## Why the E2E marathon fails structurally What a team really needs is a fast, reliable answer to the question of whether a new release breaks the collaboration between services. A large E2E suite is the worst at delivering exactly this answer. Martin Fowler and Ham Vocke put it precisely in “The Practical Test Pyramid”: UI and end-to-end tests are “brittle, expensive to write, and time consuming to run”. They are prone to non-determinism – timing, animations, browser quirks, a network hop that takes 50 milliseconds one time and 800 the next. And this non-determinism is exactly the poison: as soon as a suite turns red in one out of twenty runs for reasons that have nothing to do with the code, the team starts clicking failures away. The test that was supposed to build trust produces the opposite. Then there is the coupling effect. An E2E suite needs all involved services at the same time, in compatible versions, booted in the same environment. This forces a lockstep: team A can only deploy once the shared suite is green with team B’s current state. You decoupled the services technically, only to chain them back together through the test infrastructure. The DORA research in the book “Accelerate” by Forsgren, Humble and Kim provides the empirical counterpart. Two of the strongest predictors of successful continuous delivery are a “loosely coupled architecture” and “continuous testing”. Elite performers can change and deploy their services independently of each other, without having to synchronize with other teams. The E2E marathon works against exactly this goal. It is the synchronized lockstep in test form. ## Check the boundary, not the whole system The crucial insight is one of test abstraction. When two services work together, I don’t have to boot the entire integrated system to check whether they understand each other. I only have to check whether the *boundary* between them is right – whether the consumer sends what the provider expects, and the provider returns what the consumer relies on. Fowler’s definition is precise enough to quote here: “An integration contract test is a test at the boundary of an external service verifying that it meets the contract expected by a consuming service.” The consumer tests against a mock, the provider verifies the recorded interactions – and both sides run fully isolated. No shared environment, no lockstep. The pattern behind it is anything but new. Ian Robinson described “Consumer-Driven Contracts: A Service Evolution Pattern” on martinfowler.com back in 2006. The consumer defines its expectations; the provider verifies against the union of all consumer expectations. This is not hype; it is a pattern that has matured for about seventeen years. What has changed is the tooling landscape, which today pours it pragmatically into a CI pipeline. In the classic test pyramid, the role becomes visible right away: contract tests sit in the middle, as a fast isolated test between the many unit tests at the base and the narrow, expensive E2E tip. ```mermaid flowchart TB subgraph Pyramid["Test Pyramid"] direction TB E2E["E2E
slow / flaky
few"] CT["Integration / Contract
fast / isolated
focus"] UNIT["Unit
fast / deterministic
many"] UNIT --> CT --> E2E end ``` The message of the pyramid is not “no E2E tests”. It is: check compatibility where it arises – at the boundary – and not through a fully booted system at the top. ## How a contract comes into being In concrete terms, it looks like this. The consumer – let’s say a WebApp – describes in a test what it expects from the provider, here an OrderService. This test runs against a local mock and, as a by-product, generates a contract file, the pact. ```js const provider = new Pact({ consumer: 'WebApp', provider: 'OrderService' }); provider .given('an order with id 42 exists') // provider state .uponReceiving('a request for order 42') .withRequest({ method: 'GET', path: '/orders/42' }) .willRespondWith({ status: 200, body: { id: like(42), // type matcher status: term({ matcher: 'PAID|OPEN', generate: 'PAID' }), total: like(19.99), }, }); // the consumer runs against the Pact mock, then publishes the pact file to the broker ``` Two details matter here, because they make the difference between “useful” and “brittle”. First, the matchers. `like(42)` doesn’t check for the exact value 42 but for the type – a number. `term(...)` checks against a pattern. This way the consumer states what it needs structurally instead of clinging to concrete example values. Matchers that are too lax give false confidence, matchers that are too strict make the test brittle; getting the granularity right is craft. Second, the provider state, the `given('an order with id 42 exists')`. With it, the consumer describes the precondition under which its expectation holds. And this, to be honest, is where the main effort of the whole approach lies – more on that in a moment. On the provider side, the contract is not rewritten but verified. The provider actually sets up every requested state and replays the recorded interactions against its real implementation. ```java @Provider("OrderService") @PactBroker class OrderServiceContractTest { @State("an order with id 42 exists") void orderExists() { // set up the provider state so the recorded interaction is reproducible orderRepository.save(new Order(42, "PAID", 19.99)); } } ``` Both sides run isolated in their own pipelines. The consumer knows nothing about the provider’s implementation, and the provider doesn’t boot a WebApp. And still you get a reliable statement about their compatibility. ## The deploy gate: a deterministic yes/no question Now comes the part that actually replaces the marathon. The contracts and the verification results end up in a central Pact Broker. Before every release, this lets you ask a simple, deterministic question: Are these specific versions of consumer and provider compatible with each other? ```bash # provider side: verify the recorded interactions and publish results to the broker pact-provider-verifier --provider OrderService --publish-verification-results # both sides gate their release on a deterministic check pact-broker can-i-deploy \ --pacticipant WebApp --version $GIT_SHA \ --to-environment production ``` `can-i-deploy` is the core. Instead of “we wait until the nightly E2E suite is green”, the pipeline gets an immediate, reproducible answer from the broker: yes, this version of the WebApp is verified against the version of the OrderService currently running in production – deploy. Or: no, a verification is missing – stop. The whole flow is a check at the boundary, not a fully booted system: ```mermaid sequenceDiagram participant C as Consumer (WebApp) participant B as Pact Broker participant P as Provider (OrderService) C->>B: publish pact (from mock test) P->>B: verify pact, publish results C->>B: can-i-deploy? (WebApp @ sha) B-->>C: yes -> deploy P->>B: can-i-deploy? (OrderService @ sha) B-->>P: yes -> deploy ``` The effect is the real argument. Feedback in minutes instead of overnight. A deterministic gate instead of a flaky roll of the dice. And – this is the real lever – every team can deploy independently as soon as its part of the contract is fulfilled. No lockstep, no “we have to sync with team B first”. Exactly the loose coupling that “Accelerate” identifies as a predictor of delivery performance becomes testable here. ## Where contract testing ends – the honest boundary Consumer-Driven Contracts replace the E2E *marathon* – not every E2E test. If you sell them as a cure-all, you promise too much. The most important caveat first: contract tests check interface compatibility. Structure, fields, status codes, the format at the boundary. They do *not* check real end-to-end business flows across several hops, not UI behavior, not network and infrastructure effects in interaction. A narrow E2E smoke set that runs the critical path once through the running system remains sensible and right. The thesis is “instead of an E2E marathon”, not “zero E2E”. You trade a broad, slow, unreliable suite for many fast, isolated contracts plus a handful of targeted smoke tests. The second point is where I spend the most time in practice: the provider states. Every `given('...')` must be something the provider can actually set up. If the consumer’s assumptions and the provider’s actual setup drift apart, the supposedly lightweight test becomes laborious after all. This is where the maintenance work lies, and if you underestimate it, you will be disappointed. It pays to keep the states deliberately lean and reusable. And the third point isn’t technical at all. Contract testing without a broker and without `can-i-deploy` in CI remains piecemeal. Contracts that only run locally and aren’t exchanged between pipelines in versioned form give no reliable deploy approval. Above all, though, Consumer-Driven Contracts are as much a question of collaboration as of technology: both teams have to commit to the contract as a binding agreement. The consumer says what it needs; the provider commits to delivering it and not breaking it. That is an organizational agreement, not a library. If the culture doesn’t play along, the best tool won’t help. A word on choosing tools, without slipping into product advertising: in the JS ecosystem, Pact generates the contracts; WireMock, Nock or MSW serve as consumer mocks there. On the JVM, Spring Cloud Contract is an established alternative to pact-jvm. The Pact Broker is open source and carries the CI mechanics. There are commercial extensions around it – you don’t need them for the core described here. The strategy doesn’t stand or fall with the vendor, but with the discipline to check at the boundary and to agree on contracts as teams. ## Conclusion The E2E marathon is not a testing problem but an architecture problem in test form: it couples services back together through the infrastructure that you decoupled for good reason, and in exchange it trades determinism and speed for a deceptive feeling of completeness. Consumer-Driven Contracts turn this around. They check compatibility where it arises – at the boundary between two services – isolated, fast and reproducible. The deploy gate becomes a yes/no question that is answered in minutes, and every team regains the freedom to release independently. In the end, the gain doesn’t show up in any test metric; it shows in delivery: shorter cycles, less friction between teams, higher reliability. A narrow E2E smoke set stays alongside – but the marathon can go. You trade one large, slow, unreliable safety net for many small, precisely strung ones. ## Further reading - [Consumer-Driven Contracts: A Service Evolution Pattern (Ian Robinson, martinfowler.com)](https://martinfowler.com/articles/consumerDrivenContracts.html) - [The Practical Test Pyramid (Ham Vocke, martinfowler.com)](https://martinfowler.com/articles/practical-test-pyramid.html) - [TestPyramid (Martin Fowler, Bliki)](https://martinfowler.com/bliki/TestPyramid.html) - [DORA: Loosely coupled architecture](https://dora.dev/capabilities/loosely-coupled-teams/) - [DORA: Continuous delivery](https://dora.dev/capabilities/continuous-delivery/) - [pact-jvm (pact-foundation, GitHub)](https://github.com/pact-foundation/pact-jvm) - Forsgren, Humble, Kim: *Accelerate* (2018) --- # Errors as Architecture in Node.js: Safety Nets Against the Crash URL: https://www.mikebild.dev/en/blog/errors-as-architecture-in-nodejs/ Date: 2023-11-07 A `try/catch` catches synchronous exceptions in the currently running stack and rejections of promises that are `await`ed inside the same block. A later callback, a detached promise and the `'error'` event of an EventEmitter, on the other hand, do not reach this block. A `try/catch` around their mere start call is then just decoration. This means a Node.js application has at least four levels at which errors arise, and each of them has its own mechanics. If you only know the first one, you have three holes in the net – and you wonder why the process crashes anyway, even though there is “try/catch everywhere.” Where these nets hang is decided at design time, not in the week before go-live when someone quickly layers some error handling on top. It determines whether a service stops under load and is back fresh within seconds – or whether it keeps working half broken and leaves behind data that nobody can straighten out afterward. Two axes need to be kept apart here. Callback, promise and EventEmitter describe **how** an error reaches the code. Operational errors and programmer errors describe **whether** the concrete state is still manageable. An expected timeout can be answered or retried at the edge of the request. A broken invariant in your own code should escalate to the process boundary so that the service starts fresh after an orderly shutdown. Not every error demands terminating the process; but an unknown program state must not keep running as if it were a normal operational error. ## The four levels at which errors arise Before we talk about nets, it has to be clear which sources of errors exist in a Node.js application in the first place. At the core there are four, and they differ not in severity but in the mechanism by which the error reaches you: - Synchronous: an error is thrown directly in the current call stack. A classic `try/catch` catches it. If you catch nothing here, the exception is passed up one level – all the way to the top. - Error-first callbacks: the old, still ubiquitous Node convention. The error does not come as an exception but as the first argument of the callback function: `callback(err, result)`. No `throw`, no `catch` – just a value you have to check actively. - Promises and async/await: an error becomes the rejection of the promise. You catch it with `.catch()` or with `try/catch` around an `await`. If it is not caught anywhere, an `unhandledRejection` occurs. - EventEmitter: servers, sockets, streams. The error comes as an `'error'` event. And this is where the nastiest trap lurks: if the `'error'` listener is missing, the error is not silently swallowed – it is thrown as an exception and takes the process down with it. Separating these four levels is the first step. The second is understanding that there is a fifth layer above them: the last net, which catches when nobody was responsible on any of the four levels. ## Level by level: where the error really arrives Let’s go through the levels one by one. Synchronous is simple – everyone knows it: ```js function parseConfig(raw) { try { return JSON.parse(raw); } catch (err) { // synchronous exception, caught right here return { ok: false, reason: err.message }; } } ``` The flawed thinking starts as soon as asynchrony comes into play. A `try/catch` around an error-first callback has no effect, because the callback is called later and in a different stack: ```js const fs = require('node:fs'); // This try/catch catches NOTHING from the callback below. try { fs.readFile('/etc/config.json', (err, data) => { if (err) return handle(err); // the error arrives HERE, as first argument process.stdout.write(data); }); } catch (err) { // never reached for the async error } ``` The error sits in the `err` argument, not in a thrown exception. If you forget the `if (err) return ...`, the code keeps running with `data === undefined` – and the actual crash then happens later in a place that has nothing to do with the cause. This is the most common way errors hide in Node.js. Promises turn this back toward `try/catch` – but only around `await`: ```js async function loadUser(id) { try { const user = await db.users.findById(id); if (!user) throw new Error(`user ${id} not found`); return user; } catch (err) { // rejection AND thrown error both land here logger.warn({ err, id }, 'loadUser failed'); throw err; // re-throw: let the caller decide } } ``` What matters is the consequence when nobody observes the rejection. Since Node.js 15, the default mode of `--unhandled-rejections` is `throw`. An unhandled promise rejection is no longer just a warning but terminates the process. In practice, this means: every asynchronous chain must either be returned to a responsible caller or be handled at a clear boundary at the latest, with `.catch` or `try/catch`. Detached promises in timers or callbacks need this boundary explicitly. The EventEmitter level is the most underestimated. A stream without an `'error'` listener crashes the process even though the error would have been entirely manageable: ```js const fs = require('node:fs'); const stream = fs.createReadStream('/does/not/exist'); // WITHOUT this line, the emitted 'error' is thrown and crashes the process. stream.on('error', (err) => { logger.error({ err }, 'stream failed, handled gracefully'); }); stream.on('data', (chunk) => process.stdout.write(chunk)); ``` This is standard Node semantics: an EventEmitter that emits an `'error'` event without a registered listener throws the error. That is why the `'error'` handler on servers, sockets and streams is not optional but an architectural must. If you work a lot with process boundaries and streams, you know the pattern from dealing with [child_process and scaling](https://www.mikebild.dev/en/blog/child-process-in-nodejs-scaling-without-illusions/) – there too, the `'error'` event on the child process is the difference between “handled cleanly” and “hard crash.” ## The last net – and what it is not there for What happens when nobody was responsible on any of the four levels? Then the last net catches it: `uncaughtException` and `unhandledRejection`. ```mermaid flowchart TD E["Error occurs"] --> D{"Which level
catches it?"} D -->|"try/catch"| H["handle &
continue"] D -->|"error-first callback"| H D -->|"promise .catch"| H D -->|"emitter 'error'"| H D -->|"nobody responsible"| ESC["escalates to
the last net"] ESC --> LOG["log
uncaughtException /
unhandledRejection"] LOG --> GS["start graceful
shutdown"] GS --> CLOSE["server.close()"] CLOSE --> EXIT["process.exit(1)"] EXIT --> SUP["Supervisor
pm2 / systemd / K8s
starts fresh"] ``` This is the decisive and often misunderstood point. If you register an `uncaughtException` handler, you override Node’s default behavior. Without a handler, Node writes the stack trace to stderr and terminates the process with exit code 1. As soon as a handler exists, this automatic exit no longer happens. The Node documentation is explicit here: “Adding a handler overrides this default behavior.” This means: if you register an `uncaughtException` handler, you have to make sure yourself that the process is terminated. If you do not, it keeps running in an undefined state. And that is exactly the anti-pattern I see most often in real codebases: ```js // ANTI-PATTERN: swallow and keep running. process.on('uncaughtException', (err) => { logger.error({ err }, 'oops'); // logged, but then... nothing // no process.exit — the process stays alive in a corrupt state }); ``` After an uncaught exception, the application’s state is potentially corrupt: half-completed transactions, leaked file handles, a connection pool in an unclear state. The Node docs explicitly warn against resuming normal operation afterward. `uncaughtException` and `unhandledRejection` are a last net for terminating cleanly – not for carrying on. The right net looks like this: log, then terminate in a controlled way. For the rejection, I deliberately escalate to an exception so that both paths end in the same shutdown: ```js process.on('unhandledRejection', (reason) => { logger.error({ reason }, 'unhandled rejection, escalating'); // escalate to uncaughtException so we exit through one path throw reason; }); process.on('uncaughtException', (err, origin) => { logger.fatal({ err, origin }, 'uncaught exception, shutting down'); process.exit(1); }); ``` There is a quieter variant you should know: `uncaughtExceptionMonitor`. This handler only serves for observing and logging – it does not change the crash behavior. If no `uncaughtException` handler is registered, the process still crashes, but the monitor has logged beforehand. That is ideal when you want to record the crash without accidentally suppressing it: ```js // Log the crash without changing the crash behavior. process.on('uncaughtExceptionMonitor', (err, origin) => { logger.fatal({ err, origin }, 'about to crash'); }); ``` ## Graceful shutdown: die in a controlled way, don’t repair The crash via the last net is the hard variant. The normal case in operations is a different one: the supervisor – pm2, systemd or a Kubernetes orchestrator – wants to terminate the process, for example during a deployment or when scaling down. To do so, it sends a `SIGTERM`. And here the application is responsible for finishing ongoing work cleanly, not for repairing itself. ```mermaid sequenceDiagram participant O as Orchestrator participant A as App O->>A: SIGTERM A->>A: stop accepting new requests A->>A: drain in-flight requests A->>A: close DB / pools A-->>O: exit 0 O->>O: restart fresh ``` The sequence is always the same: catch `SIGTERM`, stop accepting new connections, finish running requests, close resources, then exit. The supervisor then starts a fresh process. What matters is the default you override in doing so: without your own listener, Node exits on `SIGTERM` with exit code `128 + 15 = 143`. As soon as you register a listener, you are responsible for exiting yourself. ```js const http = require('node:http'); const server = http.createServer(handler); server.listen(3000); let isShuttingDown = false; function shutdown(signal) { if (isShuttingDown) return; // guard against double invocation isShuttingDown = true; logger.info({ signal }, 'graceful shutdown started'); // stop accepting new connections, finish in-flight ones server.close((err) => { if (err) { logger.error({ err }, 'error during server.close'); return process.exit(1); } logger.info('all connections drained, exiting'); process.exit(0); }); // fallback: never hang forever if a connection refuses to close setTimeout(() => { logger.error('shutdown timed out, forcing exit'); process.exit(1); }, 10_000).unref(); } process.on('SIGTERM', () => shutdown('SIGTERM')); process.on('SIGINT', () => shutdown('SIGINT')); ``` Two details are decisive here. First, the `isShuttingDown` flag: a container can send `SIGTERM` and shortly afterward another signal; without a guard, the shutdown runs twice and `server.close` is called on a server that is already closing. Second, the timeout with `.unref()`. If a hanging connection causes `server.close` never to return, the process would otherwise stay up forever – until the orchestrator eventually steps in hard with `SIGKILL`. The fallback timeout ensures that we exit on our own in a controlled way before that. The `.unref()` prevents the timer itself from keeping the process alive in case the clean path does finish in time. This division of labor is the core of the whole architecture: the application is responsible for finishing its ongoing work cleanly and then dying. The supervisor is responsible for restarting – not the application itself. A process that tries to heal itself after a serious error and keep running makes things worse. A process that dies in a controlled way and is restarted fresh is back in a defined state within seconds. ## Why this is an architecture decision The responsibilities are linked as a chain: the error arises on one of the four levels. Ideally, a responsible handler catches it right there – in the `try/catch`, in the `if (err)` check, in the `.catch`, in the `'error'` listener. Only when nobody was responsible does it escalate to the last net, and the last net has exactly one job: log cleanly and terminate in an orderly fashion. This is not a collection of individual tricks but a consistent decision about where an error is handled and where it only leads to a controlled end. You decide once how the net is strung, and then it holds everywhere – or you do not decide, and then it tears in the place you never looked at. If you want to dig deeper into the interplay of the event loop, callbacks and promises, you will find the foundation in the [Node.js training on event loop architecture](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/). Only once it is clear why a callback runs in a different stack than the `try/catch` around it does it become understandable why error handling in Node.js is not done with “try/catch everywhere.” Handle every error as close as possible to the level where it arises. String the last net only for dying cleanly, never for living on. And leave the resurrection to the supervisor. A service that knows how to die is more stable than one that wants to stay alive at any cost. ## Further reading - Repository with examples: [MikeBild/introduction-nodejs](https://github.com/MikeBild/introduction-nodejs) - [process – Event: 'uncaughtException'](https://nodejs.org/api/process.html#event-uncaughtexception) - [process – Event: 'unhandledRejection'](https://nodejs.org/api/process.html#event-unhandledrejection) - [process – signal events](https://nodejs.org/api/process.html#signal-events) - [events – EventEmitter 'error' events](https://nodejs.org/api/events.html#error-events) - [CLI – --unhandled-rejections=mode](https://nodejs.org/api/cli.html#--unhandled-rejectionsmode) - [Node.js Process API](https://nodejs.org/api/process.html) --- # DORA Metrics: What Really Shortens Development Cycles URL: https://www.mikebild.dev/en/blog/dora-metrics-what-really-shortens-cycles/ Date: 2023-10-24 Deployment Frequency, Lead Time for Changes, Change Failure Rate, Failed Deployment Recovery Time: four measurements that nobody has to estimate and nobody has to vote on. They come out of systems that are running anyway – the commit timestamp in version control, the deploy event of the CD pipeline, the incident log. No board, no points, no self-reporting. In older DORA texts, the recovery metric was called “Time to Restore Service.” **Editorial note (July 2026):** This post describes the model of four delivery metrics as it stood at the time. In 2024, DORA added the **Deployment Rework Rate** as a fifth metric. The current canon thus consists of three throughput and two instability metrics; the historical group of four in the main text remains as the starting point. A velocity curve comes about the opposite way. It adds up story points that a team has assigned to itself, and it can point steeply upward while releases stay sluggish, hotfixes pile up, and nobody wants to deploy on Fridays. The four measurements above can’t do that. They describe the path of a change from commit to production – and what happens when that change causes damage. These four DORA keys come from the DevOps Research and Assessment work around Nicole Forsgren, Jez Humble, and Gene Kim, are backed statistically in the book *Accelerate* (2018), and have been carried forward every year since in the *State of DevOps Report*. Their value lies in diagnosis: they show where in the chain things get stuck. What follows is about exactly where the keys make the bottleneck visible and how to collect them without turning them into a new numbers game. You can first sort the measurements by the question they answer. That prevents speed and instability from merging into a seemingly clear-cut overall grade. ::::comparison{title="Delivery performance has two axes" role="primary" preferredPattern="comparison-matrix"} :::side{label="Throughput"} - Deployment Frequency · How often does a change reach production? - Lead Time for Changes · How long does the path from commit to deploy take? ::: :::side{label="Instability"} - Change Failure Rate · What share of changes causes an incident? - Failed Deployment Recovery Time · How long does recovery take after a failed deploy? - Deployment Rework Rate · What share creates unplanned rework? ::: :::: This split isn’t a ranking. Only together do the two sides show whether a team can deliver quickly without hiding the cost of failed changes. ## Two axes instead of one number The first reasoning error is treating delivery performance as a single quantity. The four keys deliberately span two axes. On the throughput axis are **Deployment Frequency** – how often code goes to production – and **Lead Time for Changes** – how long it takes from commit to a successful deploy. That is the speed side: small batches, short paths. On the stability axis are **Change Failure Rate** – what share of deploys triggers an incident or a rollback – and **Failed Deployment Recovery Time** – how long recovery takes after a failed deployment. That is the robustness side: how expensive a failure gets. The central, counterintuitive finding from *Accelerate*: these two axes are not in opposition. The data shows that elite teams win on **both** at the same time – they deploy more often *and* fail less often *and* are back online faster. The old reflex “If we deliver faster, quality goes down” has been empirically refuted. That is exactly why it is negligent to measure only two of the four metrics. If you track only deploy frequency and lead time, you optimize for speed and ignore stability – and produce exactly the vanity illusion the DORA keys are meant to counter. ```mermaid quadrantChart title Throughput vs. Stability x-axis Low Throughput --> High Throughput y-axis Low Stability --> High Stability quadrant-1 Elite quadrant-2 Slow but Safe quadrant-3 Low Performer quadrant-4 Fragile Speed Elite Team: [0.85, 0.85] Big-Batch Team: [0.2, 0.6] Move-Fast-Break-Things: [0.8, 0.25] Stuck Team: [0.2, 0.2] ``` The matrix makes it clear: the goal is the top right, not a compromise on the diagonal. And it explains why a single number is misleading – a team in the “Fragile Speed” quadrant looks brilliant on a pure speed metric and is still on fire. ## Where the cycle gets stuck The real value of the keys lies not in the benchmark but in localization. Each metric is attached to a different segment of the value chain from commit to production – and thus shows where things get stuck. ```mermaid flowchart LR A[Commit] --> B[CI Build] B --> C[Test] C --> D[Deploy Gate] D --> E[Production] E -->|Incident| F[Restore] F --> E A -. Lead Time for Changes .-> E D -. Deployment Frequency .-> E E -. Change Failure Rate .-> F F -. Failed Deployment Recovery Time .-> E style D fill:#e8543f,color:#fff ``` An example from practice: a team complains about “slow releases.” The median lead time is eleven days. If you break it down, nine of those days sit between “feature done” and “deploy gate” – the pipeline and the manual approval step are the bottleneck, not the programming. Another team has a good lead time but a change failure rate of 30 percent and a restore time of hours: here the problem isn’t speed but the reversibility of changes. The same four numbers, completely different treatment. An aggregated velocity would only have said “the team is at full capacity” in both cases. Lead Time for Changes is my most important early indicator here. It is defined as the time from code commit to a successful run in production, and it correlates closely with batch size. Large batches lengthen feedback, increase the risk of failure, and turn every deployment into an event – Donald Reinertsen and Jez Humble have been insisting on this for years, and *Accelerate* backs it with data. A short lead time almost automatically forces small, continuous changes. ## Change Failure Rate and recovery time are coupled A widespread misunderstanding is that stability means “no failures.” That isn’t what the DORA data says. The coupling of Change Failure Rate and Failed Deployment Recovery Time says something subtler: what counts is not the absence of failures but their price. High deploy frequency plus a low change failure rate plus a short recovery time means that changes are small and reversible. A failure that I roll back in minutes is cheap. A zero-defect standard that turns every release into a nail-biter is expensive – precisely because it forces rarely practiced, risky deploys. That is why, in practice, a short restore time beats the demand for zero defects. And that is why the neighboring techniques belong right here: feature flags, to switch changes on or off without a deploy; canary and blue-green releases, to limit the blast radius; circuit breakers and bulkheads from Michael Nygard’s *Release It!*, to contain outages. Not buzzwords: these are exactly the levers that lower the change failure rate and shorten the restore time. In code, the coupling of a reversible rollout and automatic recovery looks like this, for example: ```typescript // Canary rollout gated by the live error rate. // Ties Change Failure Rate and recovery time together in one control loop. interface RolloutConfig { canaryPercentage: number; maxErrorRate: number; // e.g. 0.02 -> roll back above 2% observationWindowMs: number; } async function progressiveRollout( release: Release, config: RolloutConfig, ): Promise { await featureFlags.enableForCohort(release.id, config.canaryPercentage); const errorRate = await metrics.observeErrorRate( release.id, config.observationWindowMs, ); if (errorRate > config.maxErrorRate) { await featureFlags.disable(release.id); // instant, no redeploy return { status: "rolled_back", observedErrorRate: errorRate }; } await featureFlags.enableForCohort(release.id, 100); return { status: "promoted", observedErrorRate: errorRate }; } ``` It isn’t about the specific library; it is about the principle: recovery happens via a flag toggle in seconds, not via an emergency deploy. That is exactly what later shows up as a low restore time. ## Measuring the metrics without inventing them For the keys to stay honest, they have to come from systems that nobody maintains by hand. Lead time, for example, can be derived entirely from two sources: the commit timestamp in version control and the deploy event of the CD pipeline. No estimate, no self-reporting. ```typescript // Lead Time for Changes, derived from VCS + deploy events. // leadTime = deployedAt(prodDeployment) - firstCommitTime(changeSet) function leadTimeForChange(deployment: ProdDeployment): number { const firstCommit = deployment.changeSet .map((commit) => commit.authoredAt.getTime()) .reduce((min, t) => Math.min(min, t), Infinity); return deployment.deployedAt.getTime() - firstCommit; } // Aggregate as a median over a rolling window -- means get skewed by outliers. function medianLeadTime(deployments: ProdDeployment[]): number { const values = deployments.map(leadTimeForChange).sort((a, b) => a - b); const mid = Math.floor(values.length / 2); return values.length % 2 === 0 ? (values[mid - 1] + values[mid]) / 2 : values[mid]; } ``` Two details matter. First, the median instead of the mean – a single branch that sat around for a while would ruin any average. Second, the rolling time window: the number is a trend, not a daily hit. It gets even more effective when you don’t just display a metric but feed it back into the pipeline. In *Building Evolutionary Architectures*, Neal Ford, Rebecca Parsons, and Patrick Kua call this a fitness function – an executable rule that makes an architectural property verifiable. A DORA fitness function can turn the pipeline red when the change failure rate is above the threshold: ```python # Executable fitness function: assert a DORA metric as a CI gate. def assert_change_failure_rate(window_days: int = 30, threshold: float = 0.15): deployments = metrics_db.query_deployments(window_days) failed = [d for d in deployments if d.caused_incident or d.rolled_back] if not deployments: return # nothing to assert yet change_failure_rate = len(failed) / len(deployments) assert change_failure_rate < threshold, ( f"Change Failure Rate {change_failure_rate:.0%} " f"exceeds threshold {threshold:.0%} over {window_days}d" ) ``` This is how DORA connects with the idea of evolutionary architecture: the metric is no longer a slide for the quarterly meeting but a condition that the system places on itself. ## The pitfall: metrics as targets That brings us to the biggest danger. As soon as a metric becomes a target, it ceases to be a good measure – Goodhart’s Law in its purest form. Deployment Frequency can be inflated with trivial empty deploys. Change Failure Rate can be prettied up by redefining “failure” until hardly anything falls into it anymore. If you use the keys as a team ranking or a bonus KPI, you get exactly this gaming – and DORA itself explicitly warns against using them to compare teams. The four numbers are diagnosis, not competition. I often see two other mix-ups. First: the keys are not a replacement for story point velocity in the sense of “same thing, better numbers.” It is a different construct – velocity measures the output of a single team and is neither comparable nor tamper-proof; the keys measure the flow from commit to production across the entire delivery system. Second: fast deploys without impact are “faster to nowhere.” That is why DORA added a fifth dimension in the 2021 and 2022 reports, **reliability**, or operational performance. The statement from 2022: high delivery performance only pays off for organizational success if reliability in operations is right as well. I deliberately treat reliability as a younger, softer addition – not as a fifth, equal-ranking part of the canon. But the idea belongs in the “honest instead of vanity” framing: speed without operational stability is a vanity metric with better marketing. ## Conclusion The common thread is simple. Velocity measures what a team claims about itself. The four DORA keys measure what actually happens – from commit to production and back when things break. They do this on two axes, speed and stability, and the core message of *Accelerate* is that these axes are not a tradeoff: the good teams win on both. In practice, I use the keys as a searchlight. A long lead time points to large batches or a clogged pipeline. A high change failure rate points to missing reversibility. A long restore time shows that recovery isn’t practiced. Every number points to a concrete, technical countermeasure – small batches, Trunk-Based Development, feature flags, canary releases, circuit breakers. That is the difference between a metric that shortens the cycle and one that just fills a dashboard. And the discipline in all this: the keys diagnose; they don’t reward. The moment they become a target, they lose their value. If you can stand that – looking at numbers without chasing them – you get something rare: an honest view of where your own cycle really gets stuck. ## Further reading - [DORA Metrics – dora.dev](https://dora.dev/guides/dora-metrics/) - [Accelerate State of DevOps Report 2022 – dora.dev](https://dora.dev/research/2022/dora-report/) - [DORA 2022 Report – Google Cloud Blog](https://cloud.google.com/blog/products/devops-sre/dora-2022-accelerate-state-of-devops-report-now-out) - [Four Keys to measure DevOps performance – Google Cloud](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance) - [A history of DORA's metrics – dora.dev](https://dora.dev/insights/dora-metrics-history/) --- # child_process in Node.js: Scaling Without Illusions URL: https://www.mikebild.dev/en/blog/child-process-in-nodejs-scaling-without-illusions/ Date: 2023-09-19 Non-blocking doesn’t mean parallel. Node.js accepts thousands of concurrent network connections without breaking a sweat – but that doesn’t mean it spreads computational work across multiple cores. The two properties get lumped together all the time, and this confusion is what produces the endpoint that freezes the entire application under load without anyone understanding why. The difference lies in what the work consists of: waiting or computing. Node handles waiting on its own. Computing, it doesn’t. That is what `child_process`, `cluster`, and `worker_threads` are for – three tools with similar names, very different costs, and one shared pattern of misuse. ## One event loop, one thread, one bottleneck Let’s start at the root. A Node.js process has one event loop, and JavaScript runs in that process on exactly one thread. That isn’t a bug, that is the design principle. As long as the work consists of waiting – for a database response, for a file, for an HTTP response – the event loop can take care of other things in the meantime. The actual input and output happens in the background via libuv, and your code only gets the finished callback at the end. If you want to understand how this machinery works in detail, my [Node.js training on event loop architecture](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/) has the full version. The problem begins as soon as the work doesn’t consist of waiting but of computing. Scaling an image, parsing and transforming a large JSON document, verifying a password with an expensive hash function, a cryptographic operation, a synchronous loop over millions of entries. This work happens on the same single thread. And as long as it runs, the event loop can’t do anything else – no accepting new requests, no firing timers, no processing callbacks. Everything stops. The following code looks harmless and still slips through code reviews regularly: ```js const http = require('node:http'); function fibonacci(n) { if (n < 2) return n; return fibonacci(n - 1) + fibonacci(n - 2); } http .createServer((req, res) => { if (req.url === '/compute') { const result = fibonacci(45); // blocks the event loop for seconds res.end(`result: ${result}`); } else { res.end('ok'); } }) .listen(3000); ``` As long as `fibonacci(45)` is computing, not a single other client gets a response – not even on the harmless `/` path, which would normally finish in microseconds. A single slow request brings down the whole server. That is exactly what the official docs mean by “Don’t Block the Event Loop.” ## Four tools, four jobs Node.js offers several tools for this problem, and they get mixed up regularly. It pays to keep them cleanly apart: - `child_process` starts a completely separate operating system process with its own V8, its own heap, and its own event loop. Communication runs over pipes or – with `fork` – over an IPC channel via message passing. No shared memory. - `cluster` starts several Node instances behind a shared port and distributes incoming connections among them. Internally, it builds on `child_process.fork()` and serves request throughput. - `worker_threads` starts another thread within the same process. Each worker has its own V8 isolate and its own event loop, but can optionally share real memory with the main thread. Meant for CPU work. - The regular asynchronous APIs are for everything that is I/O – and that needs none of the three options above. I emphasize this last point deliberately, because that is where the most common reasoning error lurks. But one thing at a time. ## child_process: spawn, exec, execFile, fork The `node:child_process` module offers four ways to start a child process, and the differences matter in practice. `spawn(command, args, options)` starts a program and gives you its `stdout` and `stderr` as streams. It buffers nothing and doesn’t start a shell by default. That is the right choice when the output can be large or you want to process it as a stream. `exec(command, options, callback)` starts a real shell and buffers the entire output in memory before the callback is called. That is convenient for short commands but has two catches: the default for `maxBuffer` is 1 MB – if the output gets larger, Node kills the process with `ERR_CHILD_PROCESS_STDIO_MAXBUFFER`. And because a shell is involved, `exec` with unchecked input is an invitation to shell injection. `execFile(file, args, options, callback)` behaves like `exec` but doesn’t start a shell. That is safer and more efficient when you are only calling a specific program with arguments anyway. ```js const { execFile } = require('node:child_process'); execFile('git', ['rev-parse', 'HEAD'], (err, stdout) => { if (err) throw err; console.log('current commit:', stdout.trim()); }); ``` The choice fits into three lines: short output from a specific program – `execFile`. Large or streaming output – `spawn`. `exec` with a shell only when you really need the shell features (pipes, globbing) and you control the input. The most interesting of the four is `fork`. It is a special case of `spawn` that specifically starts a new Node instance – via `process.execPath`, the same Node binary – and automatically sets up an IPC channel. This lets you exchange messages between the parent and child process without handling pipes and serialization by hand. ## The main example: heavy computation in a fork Let’s take the blocking Fibonacci example from above and move the computation into a child process. The parent process stays responsive because the CPU load lands in an entirely different OS process. First the worker in `worker.js`: ```js // worker.js function fibonacci(n) { if (n < 2) return n; return fibonacci(n - 1) + fibonacci(n - 2); } process.on('message', ({ n }) => { const result = fibonacci(n); process.send({ n, result }); }); ``` And the parent process that starts it and hands it work: ```js // main.js const { fork } = require('node:child_process'); const http = require('node:http'); const child = fork('./worker.js'); const pending = new Map(); child.on('message', ({ n, result }) => { const res = pending.get(n); if (res) { res.end(`fibonacci(${n}) = ${result}`); pending.delete(n); } }); http .createServer((req, res) => { if (req.url === '/compute') { pending.set(45, res); child.send({ n: 45 }); // heavy work happens elsewhere } else { res.end('ok'); // stays responsive during the computation } }) .listen(3000); ``` The crucial point here: the `/` path now responds immediately, even while `/compute` is still computing. The main process’s event loop is free, because the expensive loop runs in a separate process with its own V8 heap. Communication between the two goes exclusively through messages – here via `child.send()` and the `message` event. This is worth a second look: `send` is not shared memory. The message is serialized and rebuilt as a copy in the child process. The default is `serialization: 'json'`, and JSON loses types – a `Date` becomes a string, `undefined` disappears, `BigInt` doesn’t work at all. If you want to send structured values over IPC, you can set `serialization: 'advanced'`, which uses the structured clone algorithm and preserves considerably more types. The following flow shows the principle as a sequence: ```mermaid sequenceDiagram participant Client participant Main as Main process
(event loop free) participant Child as Forked process
(own V8 heap) Client->>Main: GET /compute Main->>Child: send({ n: 45 }) Note over Main: Event loop stays free
for other requests Child->>Child: heavy computation Child-->>Main: message({ result }) Main-->>Client: HTTP 200 result ``` ## worker_threads: the same goal, shared memory A `fork` is robust but expensive. Every child process brings a complete V8 and its own heap – that costs memory and startup time. If you want to parallelize CPU work and don’t need the full isolation of a separate process, `worker_threads` are the lighter alternative. They have been stable since Node 12 and, in 2023, have long been the production standard. A worker runs in the same process but in its own thread with its own V8 isolate and its own event loop. The same computation looks like this: ```js // task.js const { parentPort, workerData } = require('node:worker_threads'); function fibonacci(n) { if (n < 2) return n; return fibonacci(n - 1) + fibonacci(n - 2); } parentPort.postMessage(fibonacci(workerData.n)); ``` ```js // main-threads.js const { Worker } = require('node:worker_threads'); function computeFib(n) { return new Promise((resolve, reject) => { const worker = new Worker('./task.js', { workerData: { n } }); worker.on('message', resolve); worker.on('error', reject); }); } computeFib(45).then((result) => { console.log('fibonacci(45) =', result); }); ``` The big difference from `fork`: worker threads can share real memory. A `SharedArrayBuffer` is the same memory region for the main thread and the worker thread – no copy, no serialization. Alternatively, you can pass an `ArrayBuffer` via `transferList`, which is a zero-copy transfer: the buffer moves to the receiver and is unusable on the sender afterward. For large amounts of data between threads, that is a real advantage that a separate process, by its nature, can’t offer. ## The pitfall that does the most damage The mistake that burns the most time in real codebases is this one: trying to “speed up” I/O-bound work with `worker_threads` or `cluster`. I have run into it in several projects, each time with the same justification. The motivation is understandable. Someone has heard that workers parallelize, sees an endpoint that makes many database queries or HTTP calls, and puts the whole thing into a worker pool. The result is regularly slower than before. The reason: network and file I/O in Node.js is already asynchronous and doesn’t block the event loop at all. There is nothing to offload. The docs say it unambiguously: worker threads don’t help much with I/O-intensive work. What you get is the overhead of thread creation and message passing – with no gain whatsoever. So the rule is simple and still gets violated all the time: - Is the work I/O-bound – database, network, file system? Then stick with the regular asynchronous APIs. Workers and processes bring nothing here except complexity. - Is the work CPU-bound – hashing, image processing, compression, crypto, large synchronous transformations? Only then are `worker_threads` or `child_process` the right tool. A second pitfall sits right next to it: creating a worker or process per task. Creation is expensive – V8 has to be initialized, memory gets allocated. If you start a fresh worker on every request, you often make things slower, not faster. The answer is a worker pool: a fixed number of reusable workers that process tasks from a queue. The same consideration applies to `fork` – keep the child processes alive and send them work one after another instead of restarting them constantly. ## cluster: throughput, not relief That leaves `cluster`, and here, too, there is a persistent misunderstanding. `cluster` doesn’t solve the problem of the single blocking computation. It solves the problem of throughput: a single Node process uses only one core, but your machine has several. `cluster` starts one Node instance per core, all of them listen behind the same port, and the primary distributes incoming connections round-robin. ```js const cluster = require('node:cluster'); const http = require('node:http'); const os = require('node:os'); if (cluster.isPrimary) { for (let i = 0; i < os.cpus().length; i++) { cluster.fork(); } cluster.on('exit', (worker) => { console.log(`worker ${worker.process.pid} died, restarting`); cluster.fork(); }); } else { http .createServer((req, res) => res.end(`handled by pid ${process.pid}`)) .listen(3000); } ``` This doubles or quadruples the throughput of concurrent requests. But if a single request triggers a synchronous computation that takes seconds, it still blocks the worker handling it. `cluster` only turns many slow requests into many parallel ones if each lands on a different worker – and the limited number of workers runs out at some point. For the actual CPU problem per request, you still need `worker_threads` or offloaded processes. By the way, `cluster.isPrimary` has been the preferred name since Node 16; `isMaster` still exists but is considered deprecated. ## What to use when: the decision at a glance The decision boils down to a few questions: ```mermaid flowchart TD A[Classify the work] --> B{I/O-bound?} B -->|Yes| C[Regular async APIs
no workers needed] B -->|No, CPU-bound| D{Shared memory
or lightweight?} D -->|Yes| E[worker_threads
SharedArrayBuffer possible] D -->|No, isolation
or external script| F[child_process / fork
own process + IPC] A --> G{Just more throughput
on all cores?} G -->|Yes| H[cluster
multiple instances, one port] ``` The three tools answer different questions – they don’t compete for the same one: - `child_process` / `fork` gives you a separate process with its own heap and communication via copied IPC messages – maximum isolation, ideal for external programs or standalone Node scripts. - `cluster` gives you several Node instances behind one port for more request throughput – it scales instances, not individual computations. - `worker_threads` gives you threads in the same process with optionally shared memory – the right choice for parallelizing CPU work without spinning up a whole process. ## Conclusion The illusion this post argues against is the most comfortable one: that Node.js somehow spreads CPU work across all cores on its own. It doesn’t. One process, one event loop, one JS thread – and every synchronous computational load blocks everything else. Once you accept that, the right decisions almost make themselves: I/O doesn’t need workers, just the asynchronous APIs that Node already ships with. Only CPU work justifies heavier artillery – `worker_threads` for in-process parallelism with shared memory, `fork` for isolated processes, `cluster` for pure throughput. The most expensive mistake is not choosing the wrong tool. It is reaching for a tool where there is no problem at all – “speeding up” I/O with workers and buying complexity and overhead in exchange, without gaining a single millisecond. First measure whether you are CPU-bound at all. If you are, you now know where the work belongs. If you push large amounts of data through your application anyway, my post on [Node.js streams and backpressure](https://www.mikebild.dev/en/blog/nodejs-streams-understanding-backpressure/) is the right complement – because often the best scaling is the kind where you never load the data completely into memory in the first place. ## Further reading - Repository with the code examples: [github.com/mikebild/introduction-nodejs](https://github.com/mikebild/introduction-nodejs) - [child_process – official Node.js docs](https://nodejs.org/api/child_process.html) - [worker_threads – official Node.js docs](https://nodejs.org/api/worker_threads.html) - [cluster – official Node.js docs](https://nodejs.org/api/cluster.html) - [Don't Block the Event Loop – Node.js Learn](https://nodejs.org/en/learn/asynchronous-work/dont-block-the-event-loop) --- # Understanding Lambda Performance and Cold Starts URL: https://www.mikebild.dev/en/blog/understanding-lambda-performance-and-cold-starts/ Date: 2023-08-08 An endpoint responds in 40 milliseconds, on the next call in 900 – nothing changed in the code, and monitoring reports no error. The difference lies solely in whether AWS Lambda could reuse an existing execution environment or had to create a new one. And every millisecond of work that happens outside the handler is paid by the first caller of that new environment – fully and visibly. This outlier is called a cold start, and its bad reputation is undeserved. It is neither a bug nor a sign of a poorly built function, but a direct consequence of Lambda’s execution model. Once you see through this model, the vague “sometimes slow” breaks down into a handful of concrete adjustment knobs – and a few stubborn misconceptions sort themselves out along the way. ## What really happens during a cold start Lambda doesn’t run your code in a permanently running process but in a so-called execution environment. This is an isolated, short-lived runtime that Lambda creates on demand, keeps alive for a while and eventually throws away. The lifecycle of this environment consists of three phases: Init, Invoke and Shutdown. A cold start is nothing other than the Init phase of a freshly created environment. Quite a lot happens before your actual logic even starts: - Lambda downloads your code – from internal storage or, for container images, from the registry. - The runtime is initialized, for example by starting the Node.js process. - Your function init code runs: everything you wrote at module level outside the handler – imports, creating SDK clients, reading configuration. Only then does the Invoke phase follow, in which your handler is called with the concrete event. An important detail for practice: the Init phase has a hard timeout of 10 seconds. If you do expensive work at module level, you can actually hit this limit – more on that later. After the invoke, Lambda doesn’t throw the environment away immediately. It is frozen and thawed again for another call within a short time. Then we speak of a warm invoke: the entire Init phase is skipped because the runtime and init code have already run. Only your handler runs. That is why the same endpoint sometimes takes 40 and sometimes 900 milliseconds – the difference is simply whether a warm environment was ready or a new one had to be created. ```mermaid flowchart TD Req[Incoming invoke] --> Q{Warm environment
available?} Q -->|No: cold start| C1[Download code] C1 --> C2[Initialize runtime] C2 --> C3[Run init code outside
the handler] C3 --> H[Run handler] Q -->|Yes: warm invoke| H H --> F[Freeze environment
for later invokes] F -.reuse.-> Q ``` The diagram makes the central point visible: the expensive part – download, runtime init, function init – only happens on the cold path. The “Init Duration” you’ll find in the logs in a moment is exactly the sum of these three steps. On every warm invoke, Lambda jumps straight to the handler. ## The first lever: keep the bundle small The most obvious contribution to the cold start is the time it takes to load your code and parse the modules. The bigger the bundle and the more branched the import graph, the longer that takes. That sounds trivial, but I regularly see deployment packages of several megabytes in which a complete SDK, three date libraries and unused parts of a framework travel along. The pragmatic answer is bundling with tree shaking. A bundler like esbuild throws out everything that isn’t actually reached and packs the rest into a compact file. A typical call looks like this: ```bash esbuild src/handler.ts \ --bundle \ --minify \ --platform=node \ --target=node18 \ --external:@aws-sdk/* \ --outfile=dist/handler.js ``` Two things here are deliberate choices. The target is `node18` – Lambda’s current LTS runtime at this point. And AWS SDK v3 is kept out of the bundle via `--external:@aws-sdk/*`, because it is preinstalled in the Node18 runtime anyway. Packing it in would only bloat the package unnecessarily without any benefit. If you work with AWS SAM or the CDK, you often don’t have to take care of the call yourself: the `NodejsFunction` construct uses esbuild internally and bundles automatically. The point stays the same – less code and fewer dependencies mean a shorter download and faster module loading, and therefore a shorter cold start. ## The second lever: init code in the right place Now comes the part that makes the biggest difference in practice and at the same time is most often done wrong: where do you create your clients and connections? Everything you write at module level outside the handler runs exactly once per execution environment – in the Init phase. On every following warm invoke, the result is reused. That is exactly where everything belongs that is reusable and stable across calls: SDK clients, database pools, parsed configuration. ```ts // module scope — runs once per execution environment (Init phase) import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; import { GetItemCommand } from "@aws-sdk/client-dynamodb"; // created once, reused across every warm invoke const client = new DynamoDBClient({}); export const handler = async (event: { id: string }) => { const result = await client.send( new GetItemCommand({ TableName: "orders", Key: { id: { S: event.id } }, }) ); return { statusCode: 200, body: JSON.stringify(result.Item) }; }; ``` The `DynamoDBClient` is created once here and then stays in the environment. Every warm invoke accesses the same instance – including the HTTP connections already established. This is where an often overlooked advantage of AWS SDK v3 lies: HTTP keep-alive is enabled by default. So the TCP and TLS handshakes only happen on the first call and are reused afterwards. A short but practically relevant note on migration: with the older AWS SDK v2, keep-alive was not on automatically. There you have to set the environment variable `AWS_NODEJS_CONNECTION_REUSE_ENABLED=1` (available from v2.463.0) to get the same behavior. If you still run v2 code, you should check this – it’s one of the cheapest latency improvements there is. ### Lazy init for what not every invoke needs Not every resource should go into the Init phase. If you only actually need an expensive connection in one out of twenty calls, building it at module level lengthens every single cold start – including those that never use it. This is where lazy init pays off: the resource is only created when it’s first actually needed and is then cached for the lifetime of the environment. ```ts import { createPool, type Pool } from "./db"; let dbPromise: Promise | undefined; // created on first use, then cached for the environment's lifetime const getDb = (): Promise => (dbPromise ??= createPool()); export const handler = async (event: { needsDb: boolean }) => { if (!event.needsDb) { return { statusCode: 204 }; } const db = await getDb(); const rows = await db.query("SELECT 1"); return { statusCode: 200, body: JSON.stringify(rows) }; }; ``` The `??=` operator makes sure the pool is built only a single time. The first call that really needs it incurs a small delay – in return, the Init phase stays lean and fast, and all invokes that don’t need the pool pay nothing for it. It’s the balance between “everything up front” and “everything per call,” and the right boundary depends on how often a resource is actually needed. ## The third lever: memory is also CPU This is the knob that is underestimated the most because it has a misleading name. The configuration value is called `MemorySize` and can be set between 128 MB and 10,240 MB in 1 MB steps. But it doesn’t only control memory: CPU is allocated linearly in proportion to memory. At exactly 1,769 MB, your function gets one full vCPU; at the top end, up to 6 vCPUs are available. That has immediate consequences. A function that does CPU-bound work – parsing JSON, cryptography, data preparation – gets faster with more memory, even though it doesn’t need the extra memory at all. And interestingly, this also applies to the cold start itself: loading and initializing the runtime is CPU work that benefits from more allocated computing power. The mistake I see most often here is one of two extremes. Either the function stays at 128 MB to save money and is therefore unnecessarily slow under CPU load – or someone blindly cranks memory up to a high level in the hope that “more helps more.” Both are guessing. More memory costs more per millisecond, and beyond a certain point it brings no latency gain because the function is no longer CPU-bound but I/O-bound. Then you’re waiting for a database or an external API, and no extra vCPU helps with that. The only serious answer is measuring. For exactly this purpose, there is the open-source tool AWS Lambda Power Tuning, which tries your function with different memory values and plots cost against latency. Instead of guessing, you see the actual curve for your specific workload and pick the point that fits your goal. ## The fourth lever: Provisioned Concurrency for predictable latency Sometimes shortening the cold start isn’t enough – you want to avoid it entirely for certain functions. That’s the case for latency-critical, well-predictable loads: a function behind a login flow, an endpoint that gets a predictable load peak at nine o’clock on weekdays. That’s what Provisioned Concurrency is for. Using `ProvisionedConcurrentExecutions`, you configure a number of environments that Lambda keeps permanently pre-initialized – with the Init phase already run. Calls then hit a warm environment without a cold start occurring. The important detail is that Provisioned Concurrency is configured on an alias or a specific version, not on `$LATEST`. If you also want to adapt these environments to a fluctuating load, you can scale them dynamically with Application Auto Scaling. That costs real money, though, and independently of load: pre-provisioned environments are billed even when they sit idle. Provisioned Concurrency is therefore not a cure-all you lay over every function, but a targeted tool for the few places where predictable, low latency justifies the surcharge. For most background and event-driven functions, the occasional cold start is completely uncritical – there, Provisioned Concurrency would be money thrown away. A side note, because the question often comes up in reviews: for Java, there has also been Lambda SnapStart since the end of 2022, which works from a snapshot of the initialized environment. For Node.js, it’s currently not an option – SnapStart is Java-only at this point. For our TypeScript functions, the levers above remain the relevant ones. ## Measure, don’t guess The common thread through all these levers is the same: without measurement, every optimization remains a gut feeling. Fortunately, Lambda delivers the decisive numbers for free. Every invoke writes a REPORT line to the CloudWatch logs, and for a cold start it contains an additional field: ```json { "Duration": "42.11 ms", "BilledDuration": "43 ms", "MaxMemoryUsed": "98 MB", "InitDuration": "312.44 ms" } ``` The `InitDuration` field appears only on a cold start – it is exactly the time for the download, runtime init and your function init code. If you find this line in the logs, you know two things: first, this was a cold start. Second, the number shows you how expensive your Init phase really is. If `InitDuration` climbs toward seconds, that’s a clear signal that too much is happening at module level. If you want to look deeper, enable AWS X-Ray. There, initialization shows up as its own subsegment in the trace, cleanly separated from handler time. This is especially valuable when you want to find out whether your latency comes from the cold start or from a slow downstream call in the handler – two completely different problems that can’t be told apart in the plain total. ## The levers at a glance If I had to summarize the concrete knobs, I’d end up with a compact list that I like to use as a checklist in reviews: - Keep the bundle small with esbuild and tree shaking; mark the AWS SDK available in the runtime as `external`. - Use few dependencies and keep the import graph deliberately lean. - Create reusable clients and connections outside the handler and reuse them across warm invokes. - Lazy init for expensive, rarely used resources so the Init phase stays lean. - Understand memory as a CPU dial and tune it empirically – with Lambda Power Tuning instead of gut feeling. - Use Provisioned Concurrency selectively for the few latency-critical, predictable functions. - Measure Init Duration in CloudWatch and X-Ray instead of guessing. ## Conclusion Cold starts are not a flaw but a property of Lambda’s execution model – and that is exactly why they can be controlled once you understand the model. The Init phase runs once per execution environment, warm invokes skip it, and almost everything you can adjust about latency depends on how heavy or light you make this Init phase. In practice, there’s no single big solution here. What works is an interplay of small, understandable decisions: a lean bundle, clients in the right place, a sensibly chosen memory value and – only where it really pays off – Provisioned Concurrency. And above all of it is always measurement. If you keep an eye on Init Duration, you turn the vague “sometimes slow” into a number you can work on. That is the real gain: a gut feeling becomes an engineering problem with clear levers. In the bigger picture, Lambda remains just one building block. API, persistence, identity, asynchronous processing and observability have to be considered together; a fast function alone doesn’t make a resilient system. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-aws-serverless.en.html - [Lambda execution environment lifecycle](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtime-environment.html) - [Configure function memory (Memory = CPU)](https://docs.aws.amazon.com/lambda/latest/dg/configuration-memory.html) - [Understanding and remediating cold starts (AWS Compute Blog)](https://aws.amazon.com/blogs/compute/understanding-and-remediating-cold-starts-an-aws-lambda-perspective/) - [Operating Lambda: Performance optimization – Part 1](https://aws.amazon.com/blogs/compute/operating-lambda-performance-optimization-part-1/) - [Reuse connections with keep-alive (AWS SDK v3)](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-reusing-connections.html) - [Reuse connections with keep-alive (AWS SDK v2)](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html) - [Lambda function scaling and Provisioned Concurrency](https://docs.aws.amazon.com/lambda/latest/dg/lambda-concurrency.html) --- # RxJS in Node.js: Processing Event Streams Reactively URL: https://www.mikebild.dev/en/blog/rxjs-in-nodejs-event-streams/ Date: 2023-07-25 ```js let buffer = []; let timer = null; emitter.on('data', line => { const entry = JSON.parse(line); if (entry.level !== 'error') return; buffer.push(entry); if (!timer) { timer = setTimeout(() => { saveErrors(buffer); buffer = []; timer = null; }, 1000); } }); ``` There are three requirements in this handler: parse, filter, write out in bundles once per second. The intermediate state lives in two module variables, and the only way left to test it is with fake timers. If a second consumer comes along tomorrow, or you also need to group by service, the nesting keeps growing – and with it the number of places where the shared state can tip over. This is exactly where RxJS comes in: wherever an event stream should become a composable program. If you’ve already looked at the imperative foundation – for example in the post on [EventEmitter and the event model](https://www.mikebild.dev/en/blog/eventemitter-the-event-model-at-the-core-of-nodejs/) – you’ll recognize the same idea in RxJS, just approached from the other side. ## From on/emit to declarative streams The `EventEmitter` is imperative. I say: “When `data` happens, run this function.” That is a command. Each handler is its own little island, and if I want to chain several steps, I connect them by hand through shared state. RxJS describes the same event stream declaratively. I no longer say “do this when that happens” but “this stream is the source, transformed by this chain of steps.” The chain is a description, not an execution. It only gets activated on `subscribe`. The bridge between the two worlds is `fromEvent`. The operator takes a Node `EventEmitter` and an event name and returns an observable: ```js const { EventEmitter } = require('events'); const { fromEvent } = require('rxjs'); const emitter = new EventEmitter(); const data$ = fromEvent(emitter, 'data'); const subscription = data$.subscribe({ next: value => console.log('received', value), }); emitter.emit('data', { level: 'info', message: 'server started' }); ``` `fromEvent(emitter, 'data')` doesn’t change anything about the emitter’s semantics. On every `subscribe` it registers a listener via `addListener` and removes it again on `unsubscribe`. That makes the observable an adapter: the emitter stays the source, and RxJS just puts a composable layer on top. If you want to dig deeper into the difference between the push model of observables and the pull model of iterators, you’ll find it in the post on [RxJS: push and pull](https://www.mikebild.dev/en/blog/rxjs-telling-push-and-pull-apart/). A note on convention: I append a `$` to variables that hold an observable (`data$`). It isn’t required, but it has become common in the RxJS world and makes it immediately visible in the code what is a stream and what is a single value. ## The pipeline: operators as pure functions The real gain lies in the operators. They are pure functions that take an observable and return a new one. You chain them with `.pipe(...)`. In RxJS 7, I import everything – creation functions like `fromEvent` and operators like `map` – directly from `'rxjs'`. The old import from `'rxjs/operators'` still works but is outdated. A typical server-side example is log processing. I want to parse incoming raw lines into objects, keep only the errors and write them out in bundles once per second, instead of touching the database for every single line: ```js const { fromEvent } = require('rxjs'); const { map, filter, bufferTime } = require('rxjs'); const logStream$ = fromEvent(logEmitter, 'line').pipe( map(line => JSON.parse(line)), filter(entry => entry.level === 'error'), bufferTime(1000), ); const subscription = logStream$.subscribe({ next: batch => saveErrors(batch), error: err => console.error('stream failed', err), }); ``` What’s written here reads almost like a description of the requirement. `map` transforms every value, `filter` lets only matching ones through, `bufferTime(1000)` collects over a one-second time window and then emits an array. So the `next` handler doesn’t receive individual entries but one bundle at a time – or an empty array if nothing came in during the window. Each step is understandable on its own and testable on its own. And if tomorrow the requirement comes to also group by service, I insert an operator instead of restructuring a nested callback structure. A second pattern from practice: throttling sensor data while computing a running average. Suppose a device fires much more often than I want to process: ```js const { fromEvent } = require('rxjs'); const { throttleTime, scan } = require('rxjs'); const average$ = fromEvent(sensor, 'reading').pipe( map(event => event.value), throttleTime(500), scan((sum, value, index) => (sum * index + value) / (index + 1), 0), ); average$.subscribe({ next: avg => console.log('running average', avg) }); ``` `throttleTime(500)` lets one value through and then ignores all others for 500 milliseconds. `scan` behaves like `reduce` but emits every intermediate result – so with every measurement that gets through, I get the updated average. This combination of running aggregation and time window is sketched in the repository under `operators.js`, although there it still uses the older RxJS 6 import style. If I want to trigger asynchronous follow-up processing for each event – such as loading details – `mergeMap` helps. It maps every value to an inner observable and flattens the results concurrently. The second parameter limits how many inner operations may run at the same time: ```js const { mergeMap } = require('rxjs'); const details$ = ids$.pipe( mergeMap(id => fetchDetails(id), 4), ); ``` With `mergeMap(id => fetchDetails(id), 4)`, at most four requests run in parallel. This limit matters, for a reason that will play its own role in a moment. The rough flow through such a pipeline always looks the same: ```mermaid flowchart LR E[EventEmitter] -->|emit data| F["fromEvent
(Observable)"] F --> M[map] M --> FI[filter] FI --> B[bufferTime] B --> S[Subscriber] ``` ## A Subject: turning one stream into many consumers So far, every stream had exactly one consumer. As soon as several parts of the application need the same event stream, the `Subject` comes into play. A `Subject` is both an Observer and an Observable: I can push values into it, and others can subscribe to it. It distributes every value to all subscribers at the same time – multicast. ```js const { fromEvent, Subject } = require('rxjs'); const bus = new Subject(); // one source feeds the bus fromEvent(emitter, 'data').subscribe(bus); // multiple consumers share the same stream const loggerSub = bus.subscribe({ next: v => logger.write(v) }); const metricsSub = bus.subscribe({ next: v => metrics.record(v) }); // clean up later loggerSub.unsubscribe(); metricsSub.unsubscribe(); ``` The difference from subscribing directly to the source observable is fundamental. If `logger` and `metrics` both subscribed to `fromEvent(emitter, 'data')`, the emitter would have two listeners and the source would run twice. With the `Subject`, there is one execution whose values are distributed to all subscribers. That is the core of the distinction between unicast and multicast: ```mermaid flowchart LR P[Producer] --> SUB[Subject] SUB --> C1[Logger subscriber] SUB --> C2[Metrics subscriber] SUB --> C3[Audit subscriber] ``` Besides the plain `Subject`, there are variants that fit different use cases: - `BehaviorSubject(seed)` holds the last value and delivers it to every new subscriber immediately. Handy for state that a late consumer needs to know. - `ReplaySubject(bufferSize)` buffers the last n values and replays them to new subscribers. - `AsyncSubject` emits only the very last value, and only on `complete`. In the repository under `subject.js`, you can see the basic principle: the same source, several `subscribe` calls. It still uses the positional `subscribe(next, error, complete)` form there. In RxJS 7, I use the object observer `subscribe({ next, error, complete })` throughout instead – more on that in a moment under pitfalls. ## Hot and cold: the difference that skews results One point that reliably causes confusion in teams is the question of when an observable’s source comes into existence. A cold observable creates its producer per `subscribe`. Every subscriber gets its own fresh execution – unicast. A `from([1, 2, 3])` is cold: everyone who subscribes sees the values 1, 2, 3 from the start. A hot observable has its producer outside. The values are produced whether or not anyone is listening. If you subscribe late, you miss what happened before – multicast. A `Subject` is hot, and a `fromEvent` over an emitter that’s already running behaves hot as well: the events fire anyway, and I just hook in. This distinction is not theory. If you expect that “every subscriber starts fresh” but are actually looking at a hot stream, late consumers simply get wrong results – missing initial values, an aggregation that starts in the middle of the stream. If I want a late subscriber to also see the latest state or the history, that is exactly the case for `BehaviorSubject`, `ReplaySubject` or the `shareReplay` operator. ## The important distinction: RxJS has no real backpressure This point should be cleared up early; otherwise expectations arise that the tool doesn’t meet. If you know Node streams, you know backpressure: a readable stream can pause, a `highWaterMark` limits the buffer, `pipe` regulates the flow between producer and consumer automatically. The fast producer gets slowed down when the slow consumer can’t keep up. RxJS doesn’t have this. There is no built-in mechanism for a subscriber to force the source to slow down. A `Subject` or a `fromEvent` pushes values as soon as they’re there, whether or not processing keeps up. What RxJS offers instead are time-based and buffering operators: - `throttleTime(ms)` lets one value through and then drops all others for a while. - `debounceTime(ms)` waits for a quiet period and then emits the last value. - `sampleTime(ms)` takes the current value at fixed intervals. - `bufferTime(ms)` collects over a window and delivers bundles. - the `concurrent` limit of `mergeMap` caps the number of parallel inner operations. The key difference: these operators drop or aggregate values, but they don’t slow down the source. The producer keeps firing unchanged; I only reduce what arrives at the end. For a log display or sensor data, that’s often exactly right – dropping a few intermediate values is harmless. For processing where every single value must count and the source really needs to be throttled, Node streams are the right tool, not RxJS. You can connect both worlds. The repository shows the bridge via `rxjs-stream` under `node.js`: ```js const { spawn } = require('child_process'); const { streamToRx } = require('rxjs-stream'); const { map } = require('rxjs'); streamToRx(spawn('ls', ['-lha']).stdout) .pipe(map(chunk => chunk.toString())) .subscribe({ next: text => console.log(text) }); ``` `streamToRx` turns a Node readable into an observable while keeping the stream’s backpressure in the lower part. That way, I get the composability of RxJS for the transformation without giving up the stream’s flow control. If you want to refresh the basics of the event loop and the stream architecture behind it, you’ll find them in the [Node.js training](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/). ## Pitfalls I run into again and again Two mistakes show up so regularly that I’ll name them explicitly here. The first is the subscription leak. `fromEvent` registers a listener on the emitter with every `subscribe`. Without `unsubscribe()`, this listener stays attached – even when the processing is long no longer needed. The result is a memory leak and a pipeline that keeps running unnoticed. The rule is simple: I keep the subscription that `.subscribe()` returns and call `unsubscribe()` when I’m done. Alternatively, I limit the stream declaratively with `take(n)` or `takeUntil(stop$)` so that it ends itself: ```js const { fromEvent, timer } = require('rxjs'); const { takeUntil } = require('rxjs'); const stop$ = timer(60000); fromEvent(emitter, 'data') .pipe(takeUntil(stop$)) .subscribe({ next: v => process(v) }); ``` Here `takeUntil` cleans up after 60 seconds without me having to manage the subscription myself. On long-running servers, one of these two strategies is mandatory; otherwise listeners pile up over time. The second pitfall is mixing up hot and cold, which I described above – it almost always shows up as “my second subscriber doesn’t get the same values.” The answer is usually a `Subject` of the right variant or `shareReplay`. And a third, more craft-related point: many examples on the web, and the older snippets in the repository too, still use RxJS 6 patterns. Concretely, for RxJS 7 that means: - Instead of `subscribe(next, error, complete)` with separate arguments, use the object observer `subscribe({ next, error, complete })` – the positional form has been deprecated since 6.4. - Instead of `tap(fn, errFn)` with several callbacks, also use the object observer. - Import operators from `'rxjs'` instead of `'rxjs/operators'`. These changes are mechanical but important, so that the code doesn’t build on a pattern that is going away. ## When RxJS instead of a raw EventEmitter? Not every Node application needs RxJS. A single `on('data', ...)` handler stays leaner with a plain `EventEmitter` and has no extra dependency. I reach for RxJS when at least one of these points applies: - I have to chain several processing steps – transform, filter, aggregate – and don’t want to solve that with nested callbacks and shared state. - I need time-based control: throttling, debouncing, bundling in windows. - Several consumers should process the same event stream independently (multicast via a `Subject`). - The stream should end cleanly and declaratively, for example via `takeUntil`. - The processing code should break down into small building blocks that are testable on their own. Conversely, I stick with the raw emitter or reach for Node streams when it’s just a single simple handler or when I need real backpressure all the way through. ## Conclusion In Node.js, RxJS shifts the perspective from command to description. The `EventEmitter` says what to do on every event; RxJS describes the whole event stream as a composable chain of pure functions. `fromEvent` is the bridge there without changing anything about the emitter’s semantics, and a `Subject` turns one stream into many consumers. Two things you should never forget. First, discipline when cleaning up: without `unsubscribe`, `take` or `takeUntil`, listeners and processing stay alive. Second, the honest limit of the tool: RxJS handles overload only in a time-based and buffering way, not through real backpressure. If you keep these two points in mind, RxJS gives you a very pleasant way to process server-side event streams – readable, testable and extensible, without sinking into a thicket of callbacks. ## Further reading - Repository examples: `/Users/mikebild/Documents/introduction-nodejs/EXAMPLES/RXJS/operators.js`, `.../subject.js`, `.../node.js` - [fromEvent](https://rxjs.dev/api/index/function/fromEvent) - [Subject guide](https://rxjs.dev/guide/subject) - [Observable guide](https://rxjs.dev/guide/observable) - [Operators guide](https://rxjs.dev/guide/operators) - [mergeMap](https://rxjs.dev/api/operators/mergeMap) - [throttleTime](https://rxjs.dev/api/index/function/throttleTime) - [bufferTime](https://rxjs.dev/api/operators/bufferTime) - [scan](https://rxjs.dev/api/operators/scan) - [subscribe arguments (deprecation)](https://rxjs.dev/deprecations/subscribe-arguments) - [Glossary and semantics: hot/cold, unicast/multicast](https://rxjs.dev/guide/glossary-and-semantics) - [Node.js events](https://nodejs.org/docs/latest-v18.x/api/events.html) --- # Evolutionary Architecture: Systems That Are Allowed to Change URL: https://www.mikebild.dev/en/blog/evolutionary-architecture-systems-allowed-to-change/ Date: 2023-06-26 Evolutionary Architecture is not a license for uncontrolled growth, nor is it another word for “agile.” In *Building Evolutionary Architectures* (O'Reilly 2017, second edition 2022), Neal Ford, Rebecca Parsons and Patrick Kua define it as an architecture that supports “guided, incremental change across multiple dimensions.” Three words carry this definition. Guided: there are named characteristics that are protected. Incremental: each individual change is small enough to be rolled back. Multiple dimensions: this means not just the code but equally data, operations and the organization that carries both. The counter-model is the frozen system. Cleanly designed three years ago, for a world that no longer exists in that form – and not moved since, because every change seemed too risky. The diagrams still hang on the wall, but they describe a car nobody drives anymore. Behind this lies a stubborn basic assumption: that architecture is something you get right once and then defend, a target picture you reach. But no system in production use stands still. Requirements shift, load profiles change, teams grow, dependencies age. The question is never whether a system changes, only whether the architecture accompanies this change or stands in its way. Evolutionary Architecture therefore turns the perspective around: instead of treating change as an exception to avoid as much as possible after go-live, it makes change the norm that you build for from the start. A system that is allowed to change – in small steps, and without breaking the characteristics that make it valuable. ## Why end-state thinking gets expensive The classic reflex is called Big Design Up Front. You think as far ahead as possible, decide everything important early and cast the result into a target picture. That feels responsible. And thinking early is not fundamentally wrong – quite the opposite. What is wrong is the expectation that these early decisions will hold for good. The flaw lies in the timing. At the very beginning of an undertaking, you know the least about the domain, the users and the real behavior under load. That is exactly when you make the most far-reaching decisions. Every later insight then has to assert itself against a structure that was not made for it. This is the moment when teams start working around the architecture instead of with it. The technical term for this is architectural drift or erosion: the real system moves away, piece by piece, from the intended one, until the diagram on the wall is mere folklore. The business damage is rarely a spectacular outage. It creeps in. Changes take longer. Every adjustment needs more coordination. New features collide with old assumptions. Time to market rises while confidence falls. And at some point the question comes up whether it would be better to rebuild everything – the most expensive of all options. ## The shift in perspective: guided evolution instead of a fixed target The way out is not a different target picture but a different way of dealing with target pictures. Instead of defining and defending an end state, you define the characteristics the system should keep and let the structure evolve within these guardrails. ```mermaid flowchart LR A[Change
small increment] --> B[Deployment pipeline] B --> C{Fitness functions
guardrails} C -->|pass| D[Learn & Adjust] C -->|fail| E[Stop & Fix] E --> A D --> A ``` The core is a feedback loop, not a waterfall. A small change runs through the deployment pipeline, is checked against defined guardrails, delivers clear feedback – passed or not – and the team learns from it for the next step. Small, guided, repeatable. That is the difference between a system that evolves and one that just gets older. The emphasis on guided is important. Evolutionary explicitly does not mean “no architecture” or “we let it grow however it wants.” That is the most common fallacy. Uncontrolled growth is not evolution but its opposite. Without consciously named, prioritized architecture characteristics, there is nothing to protect and nothing to measure. The first step is therefore not a technique but a decision: What exactly must distinguish this system? Response time under a certain limit? Loose coupling between business areas? Demonstrable security at the edges? Only when these goals are explicit can you defend them. ## Fitness functions: architecture you can measure The mechanism used to defend these goals is called a fitness function. The term is borrowed from evolutionary algorithms, where a fitness function evaluates how close a solution is to the desired result. Applied to architecture, according to the authors, it means: “any mechanism that provides an objective integrity assessment of some architectural characteristic(s).” In other words, any mechanism that objectively checks whether an architectural characteristic is still intact. The decisive word here is objective. A fitness function is not a meeting, not a gut feeling and not an architecture review board that meets once a quarter and passes judgment on slides. It is an automated test that runs in the pipeline and delivers an unambiguous result. This shifts governance from manual control toward something versioned, executable and repeatable at any time – not for nothing does the second edition carry the subtitle “Automating Software Governance.” The simplest and best-known example is structural rules. With a library like ArchUnit, you can express an architecture rule as a perfectly ordinary unit test: ```java @ArchTest static final ArchRule domain_must_not_depend_on_infrastructure = noClasses().that().resideInAPackage("..domain..") .should().dependOnClassesThat().resideInAPackage("..infrastructure.."); ``` This rule says: the domain layer must not access the infrastructure. Until now, something like that lived in a wiki and was hopefully noticed in code reviews. Now the build breaks as soon as someone violates the boundary – on the same day it happens, not three months later in a refactoring retrospective. The intent turns from a comment into an executable fact. And this is exactly where the second big fallacy lies: fitness functions are not limited to such package and layering checks. That is just the most visible category. Anything you can check objectively about an architecture is a candidate – performance budgets, security scans, checks for cyclic dependencies, even chaos experiments or monitoring-based checks in live operation. The authors organize this into a small taxonomy that helps you spot gaps in everyday work. Fitness functions can be atomic (checking a single characteristic) or holistic (checking how several work together). They can be triggered (running on an event, for example in the build) or continual (running permanently in production). And they can be static (fixed threshold) or dynamic (threshold depending on context). If you only have structural, atomic, triggered rules, you cover one corner and miss the rest. A performance budget, for example, is rather holistic and can be expressed as a gate in the pipeline: ```yaml fitness_functions: - name: p95_latency_budget metric: http_request_duration_p95_ms threshold: 300 on_breach: fail_build - name: max_module_coupling metric: afferent_efferent_coupling_ratio threshold: 0.7 on_breach: warn ``` The pattern is always the same: an architectural characteristic, an objective threshold, a defined consequence. If the 95th percentile latency breaks the budget, the build fails. If coupling rises above the limit, there is a warning at first. You do not have to enforce everything strictly – but you make the characteristic visible and decide consciously how strictly you treat it. ## Coupling is the real brake When a system can no longer be changed in small steps, coupling is almost always the reason. Not only the obvious kind between classes, but also hidden temporal coupling and data coupling. Two services that always have to be deployed together. A schema that three teams have to touch at the same time to change one field. As long as these ties exist, incremental change is impossible, no matter how good the intent. That is why controlling coupling itself is one of the most important fitness functions. And that is why a few proven patterns make the difference here. Martin Fowler’s Strangler Fig Application describes how to replace a legacy system incrementally by letting new functionality grow around the old core like a strangler fig until the core can eventually disappear – without the one big, risky switchover. At the data level, the expand-contract pattern (also called parallel change) does the same: you expand a schema, migrate step by step and remove the old part only when nobody needs it anymore. This makes refactoring a normal, safe movement instead of a feat of strength. At the operations level, resilience patterns such as Circuit Breaker and Bulkhead from Michael Nygard’s *Release It!* make sure that the loosely coupled parts do not drag each other down during failures. And at the service edges, Consumer-Driven Contract Testing keeps the boundaries honest: every consumer describes what it expects from a service, and this contract is checked automatically. If the service changes incompatibly, the test fails before the user notices. That too is a fitness function – one that safeguards changeability at the most expensive breaking points. A word on Conway’s Law, because coupling is not only technical. Systems mirror the communication structures of the organizations that build them. If you want loosely coupled software, you also have to cut the teams accordingly. That is not a side note but often the precondition for the technical guardrails to take effect at all. ## The proof that it pays off At this point comes the objection: sounds good, but all this automation and constant change – doesn’t it come at the expense of stability? Faster means riskier, doesn’t it? The data says the opposite. The DORA research, summarized in *Accelerate* (Forsgren, Humble, Kim, 2018), shows across thousands of organizations that speed and stability are not opponents but rise together. The highest-performing teams deploy more often *and* have fewer outages *and* recover faster. The supposed trade-off between pace and reliability is an artifact of the old thinking – the result of rare, large, risky releases. The four classic DORA metrics read like system-wide fitness functions themselves: ```text Deployment Frequency - wie oft deployen wir? Lead Time for Changes - wie lange von Commit bis Produktion? Change Failure Rate - wie viele Deployments verursachen einen Fehler? Time to Restore Service - wie schnell sind wir wieder online? ``` They do not measure a single module but the changeability of the whole system. Shorter cycles, less friction and higher quality thus become quantities you can hook into the same feedback loop logic as a latency limit. ```mermaid flowchart TB subgraph Old[Architecture as end-state] O1[Big Design Up Front] --> O2[freeze] --> O3[drift & erosion] end subgraph New[Architecture as guarded evolution] N1[named characteristics] --> N2[fitness functions] --> N3[small guarded change] --> N1 end ``` Incidentally, this frame of thinking is not limited to technology. It is the same principle that *The Lean Startup* formulated for products – Build, Measure, Learn: a hypothesis, a small step, a measurement, an adjustment. Architecture evolution is the technical expression of the same attitude. You do not claim to know the right structure. You build in a way that lets you find it out cheaply. ## Conclusion Architecture is not an end state. It is a system’s ability to keep changing without losing the characteristics that make it valuable. If you take this seriously, you stop defending a target picture and start protecting the right things. The way there is surprisingly concrete. First: name the architecture characteristics that really count – not all of them, but the few that make the difference. Second: for each of these characteristics, build a fitness function that checks objectively, automatically and in the pipeline whether it still holds – structurally, but also for performance, security and coupling. Third: actively keep coupling low, technically and organizationally, so that small steps remain possible at all. And fourth: trust the whole thing, because the data shows that pace and stability grow together. The approach does not create short cycles by itself, and it does not guarantee stable quality. It makes named characteristics verifiable earlier when you make small changes. Whether that reduces friction or speeds up changes only shows in the real delivery flow. For me, the best architecture is therefore not the one that is supposed to be right forever, but one whose assumptions can be checked and changed when new insights arrive. ## Further reading - Neal Ford, Rebecca Parsons, Patrick Kua: *Building Evolutionary Architectures*, O'Reilly, 1st ed. 2017 / 2nd ed. 2022 (with Pramod Sadalage) - Martin Fowler: [Foreword to Building Evolutionary Architectures](https://martinfowler.com/articles/evo-arch-forward.html) - [DORA – Four Key Metrics](https://dora.dev/guides/dora-metrics-four-keys/) - Nicole Forsgren, Jez Humble, Gene Kim: *Accelerate*, IT Revolution, 2018 - [ArchUnit – unit tests for architecture rules](https://www.archunit.org/) - [InfoQ – Fitness Functions for Your Architecture](https://www.infoq.com/articles/fitness-functions-architecture/) - Michael Nygard: *Release It!*, Pragmatic Bookshelf, 2nd ed. 2018 --- # From HOCs and Render Props to Custom Hooks URL: https://www.mikebild.dev/en/blog/from-hocs-and-render-props-to-custom-hooks/ Date: 2023-06-20 Four levels in the React DevTools tree before the first one appears that actually renders something visible: `withRouter`, below it `withLoading`, below that `withData`, and at the very bottom the actual page. Three of these levels contribute nothing to the output. They exist only to pass state and behavior from the outside in. This tree is no accident but the logical consequence of a decision React carried around for years. Reusing stateful logic in several places without duplicating it is something the framework solved differently in three generations – and the first two solutions pay for it with exactly such levels. If you know the sequence, you also understand why the older patterns are still not worthless. ## The same old question An example that shows this well: a component needs to know whether the browser is currently online. That takes state, it takes an effect with event listeners, and it takes cleanup. If three components need this, nobody wants to write the same block three times. The naive solution is copy-paste. It works exactly until the logic changes – then you change it in one place and forget the other two. From that point on, React developers look for a mechanism that keeps the logic in exactly one place. Historically, the path there looked like this: ```mermaid graph LR A[Copy-Paste] --> B[Mixins
deprecated] B --> C[HOCs &
Render Props] C --> D[Custom Hooks
React 16.8 / 2019] ``` Mixins were the first answer in the very early days of `createClass`, but they were quickly discarded as problematic – unclear origin of properties, name collisions, implicit dependencies. After that came two patterns that dominated for a long time: higher-order components and render props. And since React 16.8 – stable since February 2019 – there are custom hooks. Let’s look at the three relevant answers in order. ## Answer 1: Higher-order components A higher-order component is basically an old acquaintance from functional programming. Just as a higher-order function takes a function and returns a new function, a HOC takes a component and returns a new, enhanced component. The signature is: ```js // a function that takes a component and returns a new component const withSomething = (Component) => EnhancedComponent; ``` The naming convention is `withXxx`. Let’s take the classic example `withLoading`, which encapsulates a loading state: ```jsx import { Fragment } from "react"; function withLoading(Wrapped) { return function WithLoading(props) { if (props.loading) { return ; } return ; }; } ``` The whole thing is applied at module level, not in render: ```jsx const UserPageWithLoading = withLoading(UserPage); ``` That reads cleanly. And it composes: you can stack several HOCs, `withRouter(withLoading(withData(Page)))`. But that is exactly where it has its price. The fact that application has to happen outside of render seems like a formality – until you violate it once. If you create a HOC directly in `render()`, a new component identity is created on every pass. React sees a different type, unmounts the entire subtree and rebuilds it – all the state below it is lost. That is one of those bugs you debug live once and then never produce again. On top of that come two more pitfalls you need to know: - Static methods of the original component disappear, because the wrapper doesn’t copy them along automatically – you need something like `hoist-non-react-statics`. - Refs don’t pass through the wrapper as a normal prop. If you need a ref to the inner component, you have to resort to `React.forwardRef` (available since React 16.3). And the basic rule that holds it all together: composition instead of mutation. A HOC doesn’t mutate the component passed in; it wraps it in a container. As soon as someone starts changing the original component directly, the pattern is broken. ## Answer 2: Render props The second pattern turns the tables. Instead of wrapping one component in another, you give a component a function that tells it what to render. That is a render prop: “a function prop that a component uses to know what to render”. Often you use `children` directly as a function for this. ```jsx class OnlineStatus extends React.Component { state = { isOnline: false }; handleOnline = () => this.setState({ isOnline: true }); handleOffline = () => this.setState({ isOnline: false }); componentDidMount() { window.addEventListener("online", this.handleOnline); window.addEventListener("offline", this.handleOffline); } componentWillUnmount() { window.removeEventListener("online", this.handleOnline); window.removeEventListener("offline", this.handleOffline); } render() { return this.props.children(this.state.isOnline); } } ``` It is then called like this: ```jsx {(isOnline) => ( {isOnline ? "Online" : "Offline"} )} ``` That is more flexible than a HOC, because the caller keeps full control over rendering. But here too there is a price: if you create the function inline in the JSX, it is recreated on every render. For a `PureComponent` or a child component optimized with `memo`, that is poison – the shallow compare fails because the function reference is new every time, and the optimization comes to nothing. You would have to move the function out into a stable instance method, which eats up the supposed elegance again. ## The shared problem: wrapper hell Both patterns – HOCs and render props – share logic through the same mechanism: additional levels in the component tree. Every HOC is a wrapper, every render prop another level of nesting. With one or two levels, you don’t notice anything. With five, the React DevTools tree looks like an onion, and that is affectionately called “wrapper hell”. This tree is exactly the crucial point. Let’s look at it: ```mermaid graph TD subgraph HOC["HOC / render props: nested"] R1[withRouter] --> L1[withLoading] L1 --> D1[withData] D1 --> P1[Page] end ``` Every intermediate level exists only to pass logic in. It has no domain meaning of its own; it is pure infrastructure in the tree. And because the data is passed through from the outside in, intermediate layers with stale closures arise easily – another debugging classic. ## Answer 3: Custom hooks Custom hooks solve the problem in a different place. A custom hook is simply a normal JavaScript function whose name starts with `use` and which may call other hooks. No wrapper, no additional component, no new level in the tree. The logic moves into a function, the component calls it – done. The same `withLoading` problem looks like this as a hook: the hook supplies the state and the component itself decides what to render with it: ```jsx import { useState, useEffect } from "react"; function useOnlineStatus() { const [isOnline, setIsOnline] = useState(true); useEffect(() => { const handleOnline = () => setIsOnline(true); const handleOffline = () => setIsOnline(false); window.addEventListener("online", handleOnline); window.addEventListener("offline", handleOffline); return () => { window.removeEventListener("online", handleOnline); window.removeEventListener("offline", handleOffline); }; }, []); return isOnline; } ``` And the usage is as unspectacular as it should be: ```jsx function StatusBar() { const isOnline = useOnlineStatus(); return {isOnline ? "Online" : "Offline"}; } ``` Compare this with the `OnlineStatus` render prop above: the same logic, but without the nesting, without the inline function, without the class. The tree stays flat: ```mermaid graph TD Page2[Page] -.calls.-> H1[useData] Page2 -.calls.-> H2[useLoading] Page2 -.calls.-> H3[useRouter] ``` The hooks hang off the side of the component – they are function calls, not tree levels. That is the whole trick, and it is a big one. Two properties of custom hooks are worth spelling out explicitly, because they are often misunderstood: - Custom hooks share **logic, not state**. If two components call `useOnlineStatus()`, each has its own, independent state. The hook is a recipe, not a shared pot. - Custom hooks re-render with their component. On every re-render, the hook gets fresh props and current state – the “stale closures” that arise so easily in HOC intermediate layers are much less of an issue here. ## Rules that apply to custom hooks too The `use` prefix is not cosmetic. It signals to the linter and to readers that this function may itself call hooks – and that the Rules of Hooks apply to it. Concretely, that means: Only React components and other hooks may call hooks. An ordinary function without `use` may not contain a `useState`. The reverse applies just as much: a function that doesn’t call any hooks at all shouldn’t be called `use`. Otherwise you take away your freedom to call it conditionally or in a loop – which is forbidden for real hooks. So the prefix is a contract in both directions. The whole thing is enforced by `eslint-plugin-react-hooks`, which I never leave out of a React project. A trap that is less technical than conceptual is one I see in codebases again and again: the urge to immediately build generic “lifecycle” hooks, such as a `useMount` that wraps an effect on mount. That is usually a bad trade. A custom hook should represent a concrete, nameable use case – `useOnlineStatus`, `useChatRoom`, `useFormInput`. If the hook’s name already explains what it does in domain terms, it is cut well. If it only renames a React mechanism, you’ve gained nothing, and the abstraction will get in your way later. ## When HOCs still make sense today After all this, it sounds as if custom hooks had completely replaced the two older patterns. For sharing stateful logic, that is largely true. But there is a handful of tasks for which HOCs are still the right form – namely real cross-cutting concerns that are brought to a component from the outside. The classic example is context injection: a HOC that makes a value from context available to any component as a prop, without the component itself having to know about the context. You often run into such `withXxx` wrappers in older libraries, and there they serve a purpose that a hook doesn’t cover cleanly – for example when class components are involved, which can’t call hooks at all. So if you maintain an existing codebase with class components, you’ll keep running into HOCs for a while. What I no longer recommend, on the other hand, is reaching for HOC toolkits like `recompose`. In its time, the library was a clever tool for composing functions such as `withState` or `withReducer`: ```js // recompose - historical, deprecated since 2018 import { compose, withState } from "recompose"; const enhance = compose( withState("count", "setCount", 0) ); ``` However, the author himself marked `recompose` as deprecated back in 2018 and explicitly pointed to hooks as its successor. So you only come across the package as historical context in older repositories – it is no good as a current recommendation. ## The common thread Three answers to one question, and the order tells a clear story. HOCs and render props showed that logic can be shared without copying it – but they solved it through the component tree and paid for it with nesting, lost refs and static methods, defeated `memo` optimizations and “wrapper hell”. Custom hooks solve the same task with a simple function call and keep the tree flat. For shared logic, the first choice today is therefore a custom hook with a `use` prefix that encapsulates a concrete use case. HOCs stay in the toolbox for the cross-cutting cases and for work on existing code with class components. And render props still show up where a component really wants to hand control over rendering back to the caller. But the standard case – the same logic in several components – has had a good, unspectacular answer since 2019. You just have to know why the other two were there before. ## Further reading - [Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) – the current chapter on custom hooks - [Higher-Order Components](https://legacy.reactjs.org/docs/higher-order-components.html) – the historical HOC documentation - [Render Props](https://legacy.reactjs.org/docs/render-props.html) – the original render props pattern - [Hooks – Custom Hooks (Legacy)](https://legacy.reactjs.org/docs/hooks-custom.html) – the historical custom hooks chapter - [Rules of Hooks / Invalid Hook Call Warning](https://react.dev/warnings/invalid-hook-call-warning) – why the `use` prefix and the rules matter --- # Async Context in Node.js: AsyncLocalStorage, async_hooks and diagnostics_channel URL: https://www.mikebild.dev/en/blog/async-context-in-nodejs-with-asynclocalstorage/ Date: 2023-05-16 `AsyncLocalStorage` is not a global variable with a better name. Every `run` call holds its own store, and two concurrent requests don’t get in each other’s way – exactly where the global variable you would otherwise reach for by reflex fails. The confusion persists anyway, because from the outside both look the same: put something down at the top, pick it up again far below. What this is good for shows in operations, not in the code. Whether finding a root cause takes minutes or hours depends on whether you can follow a single request seamlessly through logs, services and traces. Node.js ships three building blocks for this: `AsyncLocalStorage`, the underlying `async_hooks` and `diagnostics_channel`. In the post on [debugging and observing Node.js](https://www.mikebild.dev/en/blog/debugging-and-profiling-nodejs-locally/), I saved async context for later; I’m catching up on that here. This is not a niche problem. As soon as an application has more than a few endpoints, you want to know which log line belongs to which request. You want to see the logged-in user in the error report. You want to hold a trace together across several services. And all these values simply belong to the request, not to whatever function happens to be running. ## The problem: threading context through the depths Let’s look at what this looks like without any help. I have a handler that calls a service that calls a repository that, at the end, wants to log something. The request ID is created at the very top – it is needed at the very bottom. ```js function handler(req, res) { const requestId = randomUUID(); serviceA(req.body, requestId); } function serviceA(input, requestId) { // serviceA doesn't need requestId itself return repository(input, requestId); } function repository(input, requestId) { // repository doesn't either log('writing record', requestId); } function log(message, requestId) { console.log(`[${requestId}] ${message}`); } ``` That works – but it’s unpleasant. Every function in between gets a parameter forced on it that it never uses itself. It just passes it along. If a user object comes along tomorrow and a trace ID the day after, every signature grows with it. And the one library function you can’t change will, of course, not pass the parameter along – that’s where the chain breaks. You can work around it: attach the context to a class instance, pass along an object that collects all the extra data, or even set a global variable. The class instance route forces you into an object model you may not want at all. The context object is just a more nicely packaged version of the same passing along. And the global variable is simply wrong with concurrent requests – the next request overwrites it while the first one is still running. None of these variants really holds up. For exactly this “context threading” problem, Node.js has a clean answer. ## AsyncLocalStorage: the practical way `AsyncLocalStorage` lives in the `node:async_hooks` module and has been stable since Node v16.4.0. The idea is simple: you run a callback in a so-called store, and this store is preserved for all asynchronous operations created inside that callback. You read it back as deep down as you like – without a single extra parameter. An honest note up front: there is no example from a specific project codebase for this post. The following code blocks are generic Node.js examples that I checked against the official documentation. ```js import { AsyncLocalStorage } from 'node:async_hooks'; import { randomUUID } from 'node:crypto'; const als = new AsyncLocalStorage(); function handler(req, res) { const store = { requestId: randomUUID(), user: req.user }; als.run(store, () => { serviceA(req.body); }); } function serviceA(input) { return repository(input); } function repository(input) { log('writing record'); } function log(message) { const { requestId } = als.getStore() ?? {}; console.log(`[${requestId}] ${message}`); } ``` The difference is clear. `serviceA` and `repository` no longer know anything about the request ID. They know their actual job and nothing else. Only at the very top is the store set – with `als.run(store, callback)` – and only where it is really needed is it read with `als.getStore()`. Two details matter. First, `run` is synchronous: the callback’s return value is passed through, and if the callback throws, the error is passed on as well and the context is exited again. Second, outside a `run` call, `getStore()` simply returns `undefined`. That’s why the example has the `?? {}` – you should never assume a store is always there. Any object works as a store. In practice, I like to use a `Map` when values should be added during a request, or a plain object when the content is fixed from the start. The only thing that matters is that every `run` call gets its own store – then concurrent requests are cleanly separated from each other without you having to take care of the separation yourself. That is exactly the gain over the global variable from before. The following diagram shows this level. The store is set at the top, the deep calls read it, and no parameter is ever passed along. ```mermaid flowchart TD Req["HTTP Request"] --> Run["als.run(store)"] Run --> A["serviceA()"] A --> R["repository()"] R --> L["log()"] Store[("Store
requestId, user")] Run -.-> Store L -.->|"reads store"| Store ``` ### enterWith – the risky shortcut Besides `run`, there is `enterWith(store)`. The appeal is obvious: you don’t have to indent the rest of the code into a callback; you just set the context and carry on normally. But that is exactly the danger. `enterWith` applies to the entire rest of the synchronous execution plus all following asynchronous calls – there is no natural bracket that closes the context again. If you set it in an event handler, subsequent handlers may end up in the same context. `enterWith` is marked as experimental, and the documentation is unusually direct: you should use `run()` unless there are strong reasons against it. In practice that means: start with `run`. `enterWith` is reserved for rare special cases and is not the normal path. ## async_hooks: the foundation underneath How does `AsyncLocalStorage` even know which asynchronous operations belong to which `run` call? Underneath sits `async_hooks`, the actual low-level layer. It provides lifecycle hooks for asynchronous resources: for each such resource, Node goes through the phases `init`, `before`, `after` and `destroy`. You can hook into these phases. ```js import { createHook, executionAsyncId } from 'node:async_hooks'; import { writeSync } from 'node:fs'; const hook = createHook({ init(asyncId, type, triggerAsyncId) { writeSync(1, `init ${type} id=${asyncId} trigger=${triggerAsyncId}\n`); }, destroy(asyncId) { writeSync(1, `destroy id=${asyncId}\n`); }, }); hook.enable(); ``` Why `writeSync` instead of `console.log`? Because `console.log` itself creates asynchronous resources, and in an `init` hook you would write yourself into an infinite loop. That alone shows how delicate this layer is to work with directly. And here I have to be clear: `async_hooks` is experimental, and the Node documentation explicitly advises against using it directly – because of “usability issues, safety risks, and performance implications.” The `destroy` hook is especially expensive because it enables tracking of promises through the garbage collector. That costs measurable performance. So the message is not “learn async_hooks and use it.” The message is: `AsyncLocalStorage` stands on this foundation, but it is the stable, recommended and practical API. As a rule, you don’t reach for `createHook` yourself. I only show it here to make clear what happens one level down – not as a recommendation for production code. ## diagnostics_channel: decoupled instrumentation The third building block solves a different problem. Say a library wants to report that it is starting a request – but it shouldn’t dictate who hears about it or what happens with it. A logger? A tracer? A metric counter? The library shouldn’t have to know. `diagnostics_channel` has been stable since Node v18.13.0 and exists for exactly this: a decoupled publish/subscribe channel. Producers publish messages on a named channel, observers subscribe to it. Neither side knows the other. ```js import diagnostics_channel from 'node:diagnostics_channel'; const channel = diagnostics_channel.channel('app:request:start'); function handleRequest(req) { if (channel.hasSubscribers) { channel.publish({ requestId: req.id, route: req.url, startedAt: Date.now(), }); } // ... actual work } ``` On the other side, in a completely separate piece of code – maybe in the observability layer, maybe in a plugin – you subscribe to the same channel: ```js import diagnostics_channel from 'node:diagnostics_channel'; diagnostics_channel.subscribe('app:request:start', (message, name) => { console.log(`[${name}] request ${message.requestId} on ${message.route}`); }); ``` The `hasSubscribers` guard is not a detail but the heart of the matter. Without subscribers, nothing should cost anything. If you build the message object unconditionally – possibly with expensive fields or serialized payloads – you pay that price even when no one is listening. With the guard, there is practically no overhead at zero subscribers. A note on the API: the channel object also has `channel.subscribe(...)`, but this variant has been marked as deprecated since v18.7.0. In your own code, use the module-level functions, that is, `diagnostics_channel.subscribe(name, onMessage)`. ## Three levels, three jobs The three modules sound similar and do fundamentally different things – this is exactly where the confusion comes from. The division of roles: - `AsyncLocalStorage` carries context: stable since v16.4.0, the practical high-level API. Request ID, user and trace through deep async chains – without passing parameters along. - `async_hooks` is the foundation: experimental and explicitly not recommended for direct use. It provides the resource lifecycle that `AsyncLocalStorage` builds on. - `diagnostics_channel` reports events in a decoupled way: stable since v18.13.0. Producers and consumers don’t know each other – ideal for instrumentation and tracing. The following diagram arranges the three relative to each other: the context layer on its foundation, and next to it the independent event bus. ```mermaid flowchart TB subgraph Context["Kontext tragen"] ALS["AsyncLocalStorage
Stable"] AH["async_hooks
Experimental"] ALS --> AH end subgraph Bus["Ereignisse entkoppelt melden"] Pub["Publisher"] --> Ch["diagnostics_channel"] Ch --> S1["Subscriber: Logger"] Ch --> S2["Subscriber: Tracer"] end ``` ## Request correlation as a measurable operational quality The three modules are a means, not an end. The end is a property of the running system: can every operation be clearly assigned to a request? Once that is the case, a vague “the system feels slow” turns into a question you can answer. You grab a correlation ID, filter logs, metrics and traces by it and see that one request in all its depth – across service boundaries. This traceability is measurable, and that is exactly what makes it an operational quality rather than a gut feeling. The share of log lines assigned to a request ID is a metric. The time from the error report to the root cause found – the mean time to resolution – is a metric. Both move noticeably when correlation is complete instead of full of holes. `AsyncLocalStorage` provides the load-bearing building block for this: the key that reaches the deepest function without passing parameters along. `diagnostics_channel` provides the second: the decoupling that lets an observability layer pick up this key without the application code having to know who is listening. The trade-off should be named honestly. Context via `AsyncLocalStorage` costs a small but real overhead per asynchronous operation – negligible compared to the gain for the vast majority of backends, but in exceptional cases with extremely high throughput, something you measure rather than assume. The bigger price is discipline: the `run` call has to sit reliably at the entry of every execution chain; otherwise correlation breaks exactly where you need it most. So the decision isn’t made at the API but at the level of ambition. A handful of endpoints without real operational load can do without all this. But as soon as several services work together, there is an on-call rotation or errors cost money, request correlation goes from nice-to-have to foundation. It is the building block on which logging, tracing and alerting grow together into one picture – the bridge from individual signals to real observability. ## Pitfalls from practice The most common pain with `AsyncLocalStorage` is context loss: `getStore()` suddenly returns `undefined` even though you’re sure you’re inside a `run` call. This typically happens with certain callback-based APIs or with your own homegrown “thenable” objects, where Node can’t properly follow the asynchronous chain. The documentation names two remedies: convert such APIs into real promises with `util.promisify()`, or bind the resource with `AsyncResource`. A practical debugging trick: log `getStore()` at suspicious transitions. If the store is gone right after a particular call, you’ve found the transition where the chain breaks. I already hinted at the `enterWith` leak above – here it is once more, concretely, as a warning: the context runs through the entire remaining synchronous execution and beyond. Set in an event handler, subsequent handlers can inherit the same context even though they belong to an entirely different request. Those are the bugs you hunt at three in the morning. Prefer `run()`. And finally, the cost of `async_hooks`: the overhead is real, especially from promise tracking in the `destroy` hook. Together with the fact that the API is experimental and, according to the Node team, risky, that gives a clear line – don’t use it as a context mechanism in production. If you need context, use `AsyncLocalStorage`. `async_hooks` is something you know in order to understand what happens underneath, and otherwise leave alone. A side note for the curious: v18.16.0 added `AsyncLocalStorage.bind(fn)` and `AsyncLocalStorage.snapshot()` to bind the current context to a function. Both are still experimental and not needed to get started – I only mention them for completeness. ## Conclusion The common thread is layering. At the very bottom, `async_hooks` makes it possible for Node to track the lifecycle of asynchronous resources at all – a powerful but experimental and expensive layer that you rarely touch directly. On top of it stands `AsyncLocalStorage` as the stable, recommended API you use to carry request-scoped context through call chains of any depth without threading it through every signature. And next to it stands `diagnostics_channel` as a decoupled event bus that libraries and applications use for structured instrumentation without producer and consumer having to know about each other. The effect shows less in the code than in operations. Where context is carried cleanly, debugging cycles get shorter because every log line knows its request. Friction drops because no signature drags along a parameter it never uses. And quality rises measurably because traceability turns from chance into a property. For daily work, that means: `als.run(store, cb)` at the top, `als.getStore()` at the bottom – and you’re rid of the tedious passing of parameters. If you want to decouple observability, reach for `diagnostics_channel` with a `hasSubscribers` guard. `async_hooks` remains the foundation you should understand but don’t operate yourself day to day. The limit is just as clear: no mechanism replaces the discipline of setting the `run` call reliably – if the chain breaks there, the best API won’t help. If you want to dig deeper into Node’s event model at this point, the post on [EventEmitter and the event model](https://www.mikebild.dev/en/blog/eventemitter-the-event-model-at-the-core-of-nodejs/) is a good fit. And if you want to understand the architecture around the Event Loop and asynchronous execution from the ground up, the [Node.js training](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/) gives you the bigger picture. ## Further reading - [AsyncLocalStorage and async context (Node.js v18.x)](https://nodejs.org/docs/latest-v18.x/api/async_context.html) - [async_hooks (Node.js v18.x)](https://nodejs.org/docs/latest-v18.x/api/async_hooks.html) - [diagnostics_channel (Node.js v18.x)](https://nodejs.org/docs/latest-v18.x/api/diagnostics_channel.html) --- # GraphQL Auth: Identity in the Context, Authorization in the Domain Logic URL: https://www.mikebild.dev/en/blog/graphql-auth-identity-in-the-context/ Date: 2023-04-18 A resolver that only checks whether a token is present grants every logged-in user access to everything the schema offers. That isn’t a minor flaw in the auth, that is an open backend with a login form in front of it. The cause is almost always in the same place: this one check holds two questions that deal with entirely different things – and in the code, they have been fused into one. “We check that in the resolver” is therefore an answer that leaves everything open: is it checking whether someone is logged in, or whether they may see this field? As long as that isn’t answered, nobody knows what the application is actually protected against. ## Two questions, not one Authentication answers the question: **Who are you?** A token becomes an identity – a `user`. Authorization answers an entirely different question: **What are you allowed to do?** Whether this specific user may call this specific field or this specific mutation. These are different responsibilities, and they even have different failure modes. If you send no token or an invalid one, you get a `401` – not authenticated. If you have a valid token but the wrong role, you get a `403` – authenticated but not authorized. In code reviews, I regularly see the two mixed up, and then both end up at the client as HTTP `500` because an error wasn’t caught. That isn’t a cosmetic problem – a client can react sensibly to `401` and `403` (login flow vs. “no access”), but not to `500`. Once this separation is in place, the real architecture question comes up: where does the identity belong, and how does it reach every resolver that needs it? ## Why the context is the right place In GraphQL, a `contextValue` is built per request – an object that is passed to **every** resolver of the same request. That isn’t an incidental detail; it is the ideal hook for auth. The reason is the lifetime. The context is created anew once per request and lives exactly as long as that request. No state leaks between two requests, no cleanup is necessary, and I am guaranteed a freshly determined identity for every request. That is exactly where the `user` belongs. In Apollo Server 4 – the current major version – this is an `async` function that you pass in when starting the server. Important: in Apollo Server 4, the context function moves out of the `new ApolloServer({...})` constructor to `startStandaloneServer` or `expressMiddleware`. If you still have older examples from AS2/AS3 in mind, where `context` sat directly in the constructor: conceptually identical, it just gets hooked in somewhere else today. ```ts import { ApolloServer } from '@apollo/server'; import { startStandaloneServer } from '@apollo/server/standalone'; const server = new ApolloServer({ typeDefs, resolvers }); const { url } = await startStandaloneServer(server, { context: async ({ req }) => { const raw = req.headers.authorization || ''; const token = raw.replace('Bearer ', ''); const user = await getUserFromToken(token); return { user }; }, }); ``` Two details that regularly trip someone up in projects. First: in Express, `req.headers.authorization` is always lowercase – HTTP header keys end up there in lowercase, no matter how the client sends them. Second: an empty header must never pass as “logged in.” The `|| ''` fallback yields an empty string, `getUserFromToken('')` then cleanly returns `null` – and `null` means “unknown,” not “admin.” With that, the flow looks the same for every request: ```mermaid flowchart LR C[Client] -- "Authorization:
Bearer token" --> S[GraphQL server] S --> CTX["context()
token to user"] CTX --> R[Resolver] R --> BL[Business logic
checks user + role] BL -- allowed --> DATA[Data] BL -- denied --> ERR["GraphQLError
403 FORBIDDEN"] ``` You can see it clearly here: authentication happens exactly once, right at the front in `context()`. From then on, the request carries an identity with it, and everything else is authorization. ## What belongs in the context – and what doesn’t Because the context is so temptingly practical, it easily turns into a junk room. It pays to keep its contents deliberately short. What belongs in it: - the identity – `user` or `viewer`, determined from the token - this user’s permissions – `roles` or `scopes` - request-bound infrastructure – DataLoader instances, so that batching and deduplication work per request - access to the data layer – a `db` handle or repositories - request-specific values such as the locale or an auth token to pass on to downstream services And just as clearly, what does **not** belong in it: - global state that lives across requests - cross-request caches (that is exactly why a DataLoader is per request, not global) - plaintext secrets that have no business being there The rule of thumb behind it: anything that applies to exactly this one request and may disappear afterward is in good hands in the context. Anything long-lived belongs elsewhere. If you put DataLoader instances in the context per request, you already know the pattern from the world of efficient data access, by the way – I described it in more detail in connection with lists and cursors in [GraphQL pagination](https://www.mikebild.dev/en/blog/graphql-pagination-cursors-and-connections/). ## Authorization in the resolver Now the `user` is in the context, and every resolver can read it – as the **third argument**, `(parent, args, contextValue, info)`. That is the simplest, most direct form of authorization. ```ts import { GraphQLError } from 'graphql'; const resolvers = { Query: { me: (parent, args, { user }) => { if (!user) { throw new GraphQLError('Not authenticated', { extensions: { code: 'UNAUTHENTICATED', http: { status: 401 } }, }); } return user; }, adminReport: (parent, args, { user }) => { if (!user?.roles.includes('ADMIN')) { throw new GraphQLError('Forbidden', { extensions: { code: 'FORBIDDEN', http: { status: 403 } }, }); } return buildAdminReport(); }, }, }; ``` Important for anyone still working with older Apollo examples: the former classes `AuthenticationError` and `ForbiddenError` from the old `apollo-server` package no longer exist in Apollo Server 4. The way to go today is `GraphQLError` from `graphql` with an `extensions.code` – `UNAUTHENTICATED` for the missing login, `FORBIDDEN` for the missing permission – and optionally the matching HTTP status. You can already see the separation in the two resolvers: `me` only checks **whether** anyone is there at all (authentication enforced), `adminReport` checks **what** this someone is allowed to do (authorization). Two questions, two error codes. ## Field level versus query level Authorization isn’t just a matter of “whole query allowed or not.” GraphQL allows checks at the field level, and that is one of its stronger properties. Because every field has its own resolver and the check takes effect while the request is being executed, **partial responses** are possible: the client queries ten fields, the server delivers seven, and for three it gets an error and `null` – in a single response. That is exactly the behavior you want. A user should see their own name but not the internal credit rating field that only admins are entitled to. In the grounding repo, a declarative approach shows up for this: an `@auth` directive with a role enum. ```graphql enum Role { ADMIN OWNER USER } directive @auth(requires: Role!) on FIELD_DEFINITION type User { id: ID! name: String! role: String @auth(requires: ADMIN) } type Query { me: User @auth(requires: USER) } ``` Here you can see both levels: `me @auth(requires: USER)` protects an entire query field, `role @auth(requires: ADMIN)` protects a single field within the type. The directive itself is only a declaration – someone also has to enforce it at runtime. In the current generation of graphql-tools, you do that with a schema transformer. ```ts import { mapSchema, getDirective, MapperKind } from '@graphql-tools/utils'; import { defaultFieldResolver, GraphQLError } from 'graphql'; function authDirectiveTransformer(schema) { return mapSchema(schema, { [MapperKind.OBJECT_FIELD]: (fieldConfig) => { const directive = getDirective(schema, fieldConfig, 'auth')?.[0]; if (!directive) return fieldConfig; const { requires } = directive; const { resolve = defaultFieldResolver } = fieldConfig; fieldConfig.resolve = (source, args, context, info) => { if (!context.user) { throw new GraphQLError('Not authenticated', { extensions: { code: 'UNAUTHENTICATED', http: { status: 401 } }, }); } if (!context.user.roles.includes(requires)) { throw new GraphQLError('Forbidden', { extensions: { code: 'FORBIDDEN', http: { status: 403 } }, }); } return resolve(source, args, context, info); }; return fieldConfig; }, }); } ``` A note for anyone who comes across older tutorials: the former `SchemaDirectiveVisitor` is long gone – it hasn’t existed since graphql-tools v6. The approach via `mapSchema` and `getDirective` is the current one. If you google `SchemaDirectiveVisitor` and copy it, you will wonder why nothing can be imported. As elegant as the directive looks: it is only half the truth. And this is exactly where the interesting discussions in the team begin. ## Why auth doesn’t belong in the schema The `@auth` directive feels like the perfect solution at first – permissions sit right on the field, declarative, readable. For prototypes and for learning, that is perfectly fine. But as the **sole** strategy, it leads into a dead end, and the official GraphQL docs are surprisingly clear about it: authorization belongs in the business logic layer, not in the schema. The reason is duplication. Let’s take a typical rule: `OWNER` – a user may only edit their own posts. This rule can hardly be expressed purely declaratively, because it depends on the concrete data: does *this* post belong to *this* user? A directive knows the role but not the relationship between the user and the resource. And even simple role checks drift apart as soon as the same logic is needed in several places. If the same “may read the post” decision hangs on three fields and at some point is also needed by a REST endpoint or a background job, then you have the rule three or four times – and it drifts apart. That is the core of the argument: a single source of truth instead of scattered copies. So the clean variant is this: the resolver doesn’t decide on its own; it **delegates** to a business logic function that receives the context and makes the decision. ```ts const resolvers = { Query: { posts: (parent, args, context) => postRepository.getPosts(context), }, Mutation: { updatePost: (parent, { id, input }, context) => postRepository.updatePost(id, input, context), }, }; // Business logic layer – authorization lives here const postRepository = { async getPosts(context) { if (!context.user) { throw new GraphQLError('Not authenticated', { extensions: { code: 'UNAUTHENTICATED', http: { status: 401 } }, }); } // Owner rule: only the user's own posts return db.posts.findMany({ where: { authorId: context.user.id } }); }, }; ``` The resolver stays thin and dumb – it takes args and context and passes them on. The actual decision, including the data-dependent OWNER rule, lives in a single place. If another entry point is added tomorrow, it calls the same function. No duplication, no drift. I like to picture this as three layers, with the schema deliberately in the middle and without any decision-making power: ```mermaid flowchart TB subgraph Transport["Transport layer"] A["Authentication
token to user in the context"] end subgraph Schema["Schema layer"] B["Declarative only
optional @auth as a hint"] end subgraph Domain["Business logic layer"] D["Authorization
may user access this resource?"] end Transport --> Schema --> Domain ``` The message of this picture: identity is determined at the top, the permission decision is made at the bottom. The schema in the middle only describes; it doesn’t decide. ## The pitfall that gets most expensive There is one mistake I see again and again, and it really hurts: enforcing authorization in the client. The UI hides the “Delete” button if the user isn’t an admin – and everyone is happy. Except that the resolver behind it checks nothing at all. That isn’t security, that is cosmetics. Anyone who opens the developer tools or sends a GraphQL mutation directly bypasses this “check” in seconds. Hidden buttons are a matter of user guidance, not security. Enforcement **must** happen on the server – in the resolver or in the business logic layer behind it. The client is welcome to hide buttons as well, so that the UI stays tidy. But the only thing you can rely on is the server. That also answers the opening question. “We check that in the resolver” isn’t enough as an architecture decision. The identity goes into the context once per request. For the specific operation, the resolver calls a central policy or domain function; that is where the data-dependent permission decision is made. Directives and hidden buttons can make this visible, but they don’t replace this check. In the projects where auth ended up running quietly, it was never a schema question but a question of lifecycles and responsibilities. The context knows who you are. The business logic knows what you are allowed to do. If the two stay separate, the rest becomes simple. ## Further reading - [Grounding repository MikeBild/introduction-graphql](https://github.com/MikeBild/introduction-graphql) – `introduction-graphql/auth.md` and `recipes/auth/` - [graphql.org – Authorization](https://graphql.org/learn/authorization/) – why authorization belongs in the business logic layer - [Apollo Server – Authentication and authorization](https://www.apollographql.com/docs/apollo-server/security/authentication) – GraphQLError codes, `UNAUTHENTICATED` vs. `FORBIDDEN` - [Apollo Server – The context object](https://www.apollographql.com/docs/apollo-server/data/context) – context and contextValue, once per request --- # Debugging and Profiling Node.js Locally URL: https://www.mikebild.dev/en/blog/debugging-and-profiling-nodejs-locally/ Date: 2023-02-14 ```js console.log(x); console.log('HIER'); console.log('HIER 2'); ``` These three lines can do exactly one thing: show a value at a place you guessed in advance. The only way to turn them off is for someone to touch the file again. They can’t pause the process. They say nothing at all about memory usage. For all three gaps, Node.js has shipped its own tools since version 6.3, without any extra package to install – they are just rarely used. You can sort them as an escalation ladder. At the bottom is `console.log` – always on, unstructured, but immediately available. One step up is the `debug` module, which you can switch on and off through an environment variable without touching the code. Above that sits the built-in inspector with interactive breakpoints in Chrome DevTools or VS Code. And at the top, when performance or memory is the issue, I use the same inspector as a profiler. If you can keep these four steps cleanly apart, you stop guessing blindly. ## Why console.log hits its limits `console.log` has two properties that make it handy in the small and unpleasant in the large. First, it is always active: whatever is in the code runs on every pass, including in production, where it pollutes the output and, depending on volume, even costs performance. Second, it is unstructured – I see a value, but I can’t decide with a switch whether I want to see the HTTP layer or the database access right now without commenting lines out again. If you have ever dealt with the [event model of Node.js](https://www.mikebild.dev/en/blog/eventemitter-the-event-model-at-the-core-of-nodejs/), you know the problem in a sharper form: with asynchronous code, the order of the output isn’t always what you expect, and a `console.log` in the middle of a callback tells only a fraction of the story. This is exactly where it pays to move to tools that can pause and examine the running process. ## The built-in inspector: --inspect and --inspect-brk The most important thing first, because it keeps surprising teams: the debugger is already built into Node.js. There is no extra package to install. Historically, there was once a separate module (`node-inspector` with the command `node-debug app.js`), but it has been obsolete since Node 6 and is only a footnote today. Since Node 6.3, the process itself speaks the Chrome DevTools Protocol over a WebSocket – and that is exactly why both Chrome DevTools and VS Code work as clients. You start it with a flag: ```bash node --inspect ./src/server.js ``` A line like this then appears on stderr: ```text Debugger listening on ws://127.0.0.1:9229/8f2c...-uuid For help, see: https://nodejs.org/en/docs/inspector ``` By default, the process binds to `127.0.0.1:9229`. The difference between the two central flags matters: - `--inspect` only starts the debug server; the code keeps running normally. I use it for a server that runs permanently anyway and waits for requests. - `--inspect-brk` also starts the debug server, but pauses before the first line of my own code. That is ideal for short-running scripts that would otherwise have rushed through before I could even connect a client. ```bash node --inspect-brk ./src/server.js ``` For a script that finishes after 200 milliseconds, `--inspect-brk` is practically the only sensible choice – with `--inspect` alone, the process would have long since ended before I clicked “connect” in DevTools. Knowing this difference has saved me a lot of time in practice. If you want to activate the inspector not at startup but on a process that is already running, you can send the `SIGUSR1` signal on Unix systems. This route isn’t available on Windows. ## From flag to client The open inspector port is only half the battle – I still need a client that connects. I regularly use two ways. In Chrome (or Edge), I open `chrome://inspect` or `edge://inspect`. The running Node process shows up under “Remote Target”, and a click on “inspect” opens the familiar DevTools with sources, breakpoints, call stack and console. Under “Configure”, you can adjust host and port if you don’t use the default values. In VS Code, I create an attach configuration in `.vscode/launch.json`: ```json { "version": "0.2.0", "configurations": [ { "type": "node", "request": "attach", "name": "Attach to Node", "port": 9229 } ] } ``` With it, I attach to a process that I previously started with `--inspect`. Alternatively, VS Code has an “Auto Attach” mode that automatically attaches to Node processes started from the integrated terminal. Both ways end up in the same place: interactive breakpoints where I can inspect variables and step through the code. The following flow summarizes how flag, agent and client work together: ```mermaid flowchart LR A["node --inspect
or --inspect-brk"] --> B["Inspector agent
CDP via ws://127.0.0.1:9229"] B --> C["Chrome DevTools
chrome://inspect"] B --> D["VS Code
request: attach"] C --> E["Breakpoints
CPU profile
Heap snapshot"] D --> E ``` Both clients speak the same protocol with the same built-in agent. So I don’t have to commit to one ecosystem – I pick whichever client suits me better at the moment. ## The debug module: switchable logging without code changes Not every problem deserves a breakpoint. Often I just want to trace which path a request takes through my layers – but only while I’m investigating, and without anchoring the output in the code permanently. That is exactly what the `debug` module is for, at version 4.3.4 as of this writing. Many well-known libraries use it internally, and it’s quick to add to your own code. The core is a factory that you call with a namespace: ```js const debug = require('debug')('app:http'); function handleRequest(req, res) { debug('incoming request %s %s', req.method, req.url); // ... handle the request ... } ``` The trick isn’t in the code but in the startup. By default, this line prints nothing. Only when I set the `DEBUG` environment variable does the matching namespace become visible: ```bash DEBUG=app:* node server.js ``` The `*` is a wildcard, and with a leading minus I exclude namespaces specifically. That way I see, for example, everything from `app` but not the chatty database layer: ```bash DEBUG=app:*,-app:db node server.js ``` That achieves the central advantage: I switch logging on and off without changing a single line of code. The `debug` module also adds automatic time differences between outputs (the `+0ms` values), colors the namespaces in a real terminal and knows format placeholders such as `%s`, `%d`, `%j`, `%o` and `%O`. One detail regularly causes confusion: the output of `debug` goes to **stderr**, not stdout. If you want to redirect the output or filter it with `grep` and only look at stdout, you simply see nothing. And `DEBUG` only applies to libraries that use `debug` themselves – it isn’t a global switch for every log output. ## nodemon: auto-reload during development A tool that strictly speaking isn’t part of debugging but shortens the feedback loop enormously is nodemon (around version 2.0.20 as of this writing). It watches files and restarts the process on every change, so I don’t have to press `Ctrl+C` and restart by hand all the time. I add it to the project as a dev dependency: ```bash nodemon --watch ./ --ignore ./node_modules ./bin/www ``` A `nodemon.json` in the project root is nicer, because it captures the configuration and combines well with the inspector: ```json { "watch": ["src"], "ext": "js,json", "ignore": ["node_modules"], "exec": "node --inspect src/server.js" } ``` Through `exec`, I start the process directly with `--inspect`, so I get auto-reload and the debugger together. As of this writing, Node.js itself already shipped an experimental watch mode, but for everyday work I still rely on nodemon because it is mature and flexible to configure. ## A quick look at memory Before I get to actual profiling, there is a very cheap intermediate step that needs no tool at all: `process.memoryUsage()`. This function returns an object with several values, all in bytes: ```js const { rss, heapTotal, heapUsed, external } = process.memoryUsage(); console.error( `rss=${(rss / 1e6).toFixed(1)}MB ` + `heapUsed=${(heapUsed / 1e6).toFixed(1)}MB ` + `heapTotal=${(heapTotal / 1e6).toFixed(1)}MB` ); ``` The most important fields in practice: `heapUsed` and `heapTotal` concern the JavaScript heap managed by V8, while `rss` (resident set size) gives the process’s total memory, including native parts. If I watch `heapUsed` keep rising in a loop or across several requests and not coming back down after garbage collection, I have a first, very concrete hint of a memory leak. For a quick RSS value alone, there has also been `process.memoryUsage.rss()` since Node 15.6. That doesn’t replace real profiling, but it is a cheap early-warning value – especially for long-running processes or when processing large amounts of data, as happens when dealing with [streams and backpressure](https://www.mikebild.dev/en/blog/nodejs-streams-understanding-backpressure/). ## Profiling through the same inspector When the rough look with `process.memoryUsage()` isn’t enough, the next step leads back to the inspector. The same connection I use for setting breakpoints also opens the analysis tabs in DevTools: under “Memory”, I take a heap snapshot and see which objects occupy how much memory. Under “Profiler” or “Performance”, I record a CPU profile and find out in which functions the time is actually spent. If you prefer to work without a graphical frontend, there are CLI alternatives. `node --prof` writes a V8 log that I then turn into a readable report with `node --prof-process`: ```bash node --prof ./src/server.js # ... generate load, then stop the process ... node --prof-process isolate-0x*.log > processed.txt ``` In addition, since Node 12 there are the still experimental flags `--cpu-prof` and `--heap-prof`, which produce profile files in DevTools format directly. On teams, though, the interactive route through DevTools has usually won out, because it uses the same UI that is already familiar from the frontend. ## The four steps at a glance Back to the escalation ladder from the beginning. I deliberately summarize the four tools as steps, because each has its own purpose and none fully replaces another: - `console.log` – always active, unstructured, immediately available. Good for a quick one-off look, bad as a permanent solution and out of place in production. - `debug` – controlled by namespace, switchable via the `DEBUG` environment variable without code changes, output on stderr. Ideal for making specific layers visible during development. - Inspector – interactive breakpoints in Chrome DevTools or VS Code, via `--inspect` or `--inspect-brk`. The step from guessing to investigating. - Profiler – the same inspector, but for CPU profiles and heap snapshots. Used when it is not about correctness but about performance and memory. ```mermaid flowchart TB A["console.log
always on, unstructured"] --> B["debug
DEBUG env, namespace-controlled"] B --> C["Inspector
interactive breakpoints"] C --> D["Profiler
CPU profile and heap snapshot"] ``` ## Two pitfalls that can get expensive Finally, two things I explicitly raise in code reviews because they do real damage in production. The first concerns `console.log` in production. What looks harmless during development becomes a problem in continuous operation: the output is unstructured, can’t be turned off with a switch, pollutes stdout and, depending on volume, costs performance. For development, `debug` is the better choice, and production needs a proper logger that handles log levels, structured output and targeted switching on and off. The second pitfall is more dangerous and often underestimated: leaving an open `--inspect` port behind or binding it to `0.0.0.0`. The debug port allows executing arbitrary code in the process – whoever reaches it can take over the server. That is why Node.js binds only to `127.0.0.1` out of the box, and as a rule it should stay that way. If I really have to debug a remote process, I tunnel the port over SSH instead of exposing it publicly: ```bash ssh -L 9229:localhost:9229 user@remote-host ``` And the debug flag has no business in any production start script. This separation between development and production operation is closely tied to what already comes up in the [Node.js training on the event loop architecture](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/): tools that reach into the running process are powerful – and that is exactly why access to them must stay narrow. ## An outlook If you want to go even deeper, Node.js has two advanced building blocks that I only mention here as an outlook, because they deserve posts of their own: `async_hooks` to track the lifecycle of asynchronous resources, and `diagnostics_channel` to exchange structured diagnostic events between libraries and observers. Both are more for tool builders and library authors than for everyday bug hunting. ## Conclusion The way from the `console.log` reflex to deliberate debugging isn’t a big leap but a small ladder with four rungs. `console.log` remains for a quick look, but as soon as things get more structured, `debug` takes over with its switchable logging. When it gets really tricky, the built-in inspector pauses the process and lets me examine variables and call stacks – in Chrome DevTools or VS Code, whichever you prefer, because both speak the same protocol. And when performance or memory is the topic, the same inspector switches into profiler mode, while `process.memoryUsage()` already provides a cheap early-warning value beforehand. If you know these steps and keep the debug port consistently closed, you stop guessing and start investigating. ## Further reading - Grounding from the repository: `introduction-nodejs/19-quality-tools.md` (chapter “Quality Tools”) - Debugging Node.js (official guide): https://nodejs.org/en/learn/getting-started/debugging - CLI options (`--inspect`, `--inspect-brk`, `--prof`, `--cpu-prof`, `--heap-prof`): https://nodejs.org/api/cli.html - Inspector module: https://nodejs.org/api/inspector.html - `process.memoryUsage()`: https://nodejs.org/api/process.html#processmemoryusage - debug module: https://www.npmjs.com/package/debug or https://github.com/debug-js/debug - nodemon: https://github.com/remy/nodemon - Outlook – diagnostics_channel: https://nodejs.org/api/diagnostics_channel.html · async_hooks: https://nodejs.org/api/async_hooks.html --- # Developer Productivity: Shorter Cycles with High Quality URL: https://www.mikebild.dev/en/blog/developer-productivity-shorter-cycles/ Date: 2022-12-26 Lead time and processing time are two different quantities. Processing time is the span in which someone actually works on a change – reading, writing, testing. Lead time is the span from the first line to the feedback from production. The difference between the two is idle time: hours and days in which a finished change exists and nothing happens to it. Take a change with two hours of processing time and three days in queues: before the build, before the review, before a free test environment. In this example, the call for more people targets the smaller quantity. Whether your own system looks the same can be read from the timestamps of commit, review, build and deployment – not from a general claim about developer work. My mental model for this is: **short feedback loops with reliable quality**. That is not a measurable formula but a reminder of two limits. Speed without a quality net produces faster failures; quality assurance without timely feedback produces large queues. Which side is slowing you down right now is shown by the measured cycle time. Productivity emerges in two connected feedback loops whose rhythm and result must not be confused. ::::comparison{title="Two loops, two kinds of feedback" role="primary" preferredPattern="split-comparison"} :::side{label="Delivery loop"} - Question · How quickly does a small change reliably reach production? - Sequence · Code, build, test, review and deploy - Time scale · Minutes to hours - Signal · Technical feedback and production behavior ::: :::side{label="Discovery loop"} - Question · Does the change solve the right problem? - Sequence · Hypothesis, implementation, measurement and learning - Time scale · Days to weeks - Signal · Observed impact and validated learning ::: :::: A fast delivery loop without discovery may quickly ship the wrong thing. A good hypothesis without a short delivery loop waits too long for reliable feedback. ## Speed and stability are not a trade-off The most persistent fallacy in this discussion is the assumption that you have to choose between speed and stability. “We could deliver faster, but then more things break” – I hear this sentence regularly in steering meetings. The data says the opposite. The central finding of *Accelerate* (Forsgren, Humble, Kim, 2018), the book version of the DORA research with over 23,000 responses from more than 2,000 organizations, is unambiguous: high performers are better at speed **and** quality. Nowhere in the data does a team buy one at the expense of the other. The fast teams are also the stable ones. That is a statistical correlation, not a question of attitude – and the foundation for the thesis that cycles and quality support each other. This is operationalized through the four DORA metrics, which measure exactly these two dimensions. For throughput: *Deployment Frequency* and *Lead Time for Changes* – the time from commit to production. For stability: *Time to Restore Service* (the time to recover after an incident) and *Change Failure Rate* – the share of deployments that cause a failure. Lead time is the measurable version of the “short feedback loop” from my formula. If you lower it, you lower exactly the waiting time this is about. A note on precision, because this is often quoted sloppily: for years, the State of DevOps reports sorted teams into clusters – in 2021 still with a separate “elite” group. The 2022 report found only three clusters (high, medium, low), no “elite” anymore. If you argue today with “according to DORA, elite teams…,” you should know which year the number comes from. ## Why the bottleneck is waiting Continuous integration is often understood as “tooling” – you set up a build server and check the box. The point is a different one. Martin Fowler defines CI as a practice where members of a team integrate their work frequently and each integration is verified by an automated build, including tests, to detect integration errors as quickly as possible. The decisive word is “quickly.” CI is a latency machine: it shortens the time between a defect and its discovery. The bottleneck CI addresses is waiting and integration latency – not code volume. The deployment pipeline (also Fowler) is the deliberate handling of this latency. You break the path to production into stages: early stages give initial confidence in seconds to minutes, later ones are more thorough and may be slower for it. This turns where feedback should be fast and where it should be thorough into a design decision. ```yaml pipeline: - stage: commit # target: < 10 min -> fastest feedback steps: [compile, unit_tests, static_analysis] - stage: acceptance # target: minutes -> contract & integration steps: [contract_tests, integration_tests] - stage: deploy_staging # ephemeral environment on demand steps: [provision_env, smoke_tests] - stage: production # gated by feature_flag, not by branch age steps: [progressive_rollout, health_check] ``` In front of such a skeleton, exactly one question matters: where is time really lost? The answer is rarely `unit_tests`. It is `compile` when the commit build takes twelve minutes instead of under ten. It is `review` when a pull request sits in the queue for two days. It is `provision_env` when a test environment is requested by hand and provided overnight. Those are the real latency levers. Writing the tests, meaning the time at the keyboard, is almost never the problem. This also explains why “shift left” is more than a buzzword. A contract break between two services that only shows up in a nightly end-to-end environment costs a day. The same break showing up in the commit build costs minutes. It is the same defect – only the feedback latency differs by orders of magnitude. ## The two loops Short cycles exist on two levels, and I often see teams optimizing only one of them. The inner loop is delivery: `code → commit → build → automated tests → review → deploy`, measured in minutes. The outer loop is discovery: `hypothesis → build → measure → learn`, measured in days to weeks. The inner loop makes sure you ship something quickly and safely. The outer one makes sure it is the right thing. This outer loop is easily forgotten, even though it is the same idea at the product level. Eric Ries described it in *The Lean Startup* (2011) as *Build–Measure–Learn* with the goal of *validated learning*. Teresa Torres made it concrete in *Continuous Discovery Habits* (2021): weekly customer interviews, the opportunity solution tree that brings opportunities and solution ideas into a visible order, systematic assumption testing. Here, too, what counts is not more output but shorter learning cycles. A team that pushes its inner loop down to minutes but waits half a year before noticing that nobody needs the feature has optimized the wrong bottleneck. ```mermaid flowchart LR subgraph inner["Inner loop – Delivery (minutes)"] code["code"] --> commit["commit"] commit -->|"wait: build"| build["build"] build --> tests["automated tests"] tests -->|"wait: review"| review["review"] review -->|"wait: provision env"| deploy["deploy"] end subgraph outer["Outer loop – Discovery (days / weeks)"] hypothesis["hypothesis"] --> buildit["build"] buildit --> measure["measure"] measure --> learn["learn"] learn --> hypothesis end deploy --> measure learn -.-> code ``` The labeled edges in this sketch are deliberately the waiting edges: `build`, `review`, `provision env`. That is where cycle time is decided. DORA lead time measures the inner loop, discovery cadence the outer one. Together they give the number that counts: how often per week a team learns something validated. ## Quality is the net, not the brake Now the part that is easily skipped in the euphoria about speed. The formula is multiplicative. Short cycles without a quality net do not mean “delivering faster” but “breaking faster.” If you reduce batch size and deploy more often without automated tests, contract tests and a real deployment pipeline, you mainly lower one thing: the time to the next incident. Reducing batch size without stability mechanisms only shifts the bottleneck – from waiting before the deploy to cleaning up after it. That is why quality belongs in the same pipeline as speed. Where services talk to each other across system boundaries, consumer-driven contract testing carries a large part of this load. The idea (it goes back to Ian Robinson and Fowler, 2006, and is widely established with frameworks like Pact): the consumer describes what it expects from the provider, and this expectation is verified independently on both sides – without having to spin up a shared, slow end-to-end environment. ```javascript // consumer side: describe the expectation, generate a pact file consumerTest("fetches a user by id", () => { provider .given("a user exists") .uponReceiving("a request for user 42") .withRequest({ method: "GET", path: "/users/42" }) .willRespondWith({ status: 200, body: { id: 42, name: like("Ada") }, // matcher, not a fixed value }); // -> produces a pact contract, verified in the provider's own pipeline }); ``` The gain is twofold. The contract test runs in the `acceptance` stage in seconds instead of an end-to-end test running for minutes in a specially provisioned environment – the feedback loop at the service boundary gets shorter. And it is more precise: it does not just say “something is red,” but “the provider no longer returns `name`.” That is quality that enables speed instead of slowing it down. The same idea belongs at the architecture level. Michael Nygard described the stability patterns in *Release It!* (2007, 2nd edition 2018) – circuit breaker, bulkhead and relatives – so that a failure in one part does not drag down the whole. And Neal Ford, Rebecca Parsons and Patrick Kua introduced the idea of fitness functions in *Building Evolutionary Architecture* (2017): automated, executable checks for architectural properties such as latency, coupling or security. Both are the same movement as with tests – quality is turned into something executable that gives fast feedback in the pipeline instead of gathering dust in a review document. ## How to actually build short cycles From practice, a few levers that work reliably – ordered by what hits the waiting edges most directly. The commit build has to be fast. Fowler’s rule of thumb of the “ten-minute build” is not nostalgia but a psychological limit: if the build takes longer, the team stops integrating frequently, and the batches grow again. A fast, broad base of unit tests and a narrow top of slow end-to-end tests – the classic test pyramid – keeps the build fast without losing coverage. Keep branches short. Trunk-Based Development with short-lived feature branches and feature flags decouples “code is merged” from “feature is on.” This is the point at which `production` is gated by a feature flag, not by the age of a branch. Long-lived branches are the classic way integration waiting time builds up invisibly until the merge becomes a day-long project. Environments on demand. If `provision_env` is a ticket to another team, your lead time is not a technical quantity but an organizational one. Ephemeral, script-generated environments take this edge out of the queue. And the point that causes the most conflict: measure the system, not the person. The four DORA metrics are team and system outcome metrics. Misused as an individual developer ranking, they immediately produce Goodhart effects – you optimize the number instead of the thing. If you are measured by “deployments per developer,” you produce micro-deploys; if you are measured by change failure rate, you relabel incidents. Forsgren and colleagues explicitly warned against such vanity and individual metrics. The metrics show the health of a flow, not the performance of an individual. ## Conclusion Productivity in software development cannot be described meaningfully by hours worked alone. In many flows, a large part of the lead time is spent waiting for build, review or environment; whether that is the bottleneck here has to be shown by measurement. DORA metrics describe the delivery capability of the system. Contract tests, stability patterns and fitness functions can make selected quality risks visible earlier, while the discovery loop checks whether the team is working on the right problem at all. If you want to start tomorrow: draw your inner loop and write the real waiting time on every edge. The longest of them is a good candidate for the next improvement. Then measure again. Short cycles and reliable quality remain two separate quantities; neither may hide the other. ## Further reading - Nicole Forsgren, Jez Humble, Gene Kim: *Accelerate* (2018) – the finding that speed and stability are not a trade-off: - Four Keys / DORA metrics explained: - DORA metrics and the cluster classification: - Martin Fowler: *Deployment Pipeline*: - Martin Fowler: *Continuous Delivery*: - Teresa Torres: *Continuous Discovery Habits* (2021): --- # Slots, Context and Web Components in Svelte URL: https://www.mikebild.dev/en/blog/slots-context-and-web-components-in-svelte/ Date: 2022-11-22 A reusable card into which every team can put its own header and its own content: the requirement sounds harmless, and yet you cannot solve it cleanly with props alone. In review, the evasive maneuvers then show up – a store where a slot would have been enough; a prop threaded through seven components even though the Context API would have been the shorter route; a component library that only runs under Svelte even though framework-neutral reuse was the actual goal. Slots, the Context API and custom elements appear side by side in the same components and are therefore easily confused. What tells them apart is the direction in which something flows: markup from the outside into a component, data from the inside back to that markup, values downward through any number of levels of the component tree. If you briefly clarify which of these directions you need before choosing a tool, you have usually made the decision already. **Editorial note (July 2026):** The title explicitly refers to Svelte 3. In Svelte 5, snippets and `{@render ...}` are the preferred way of composition instead of slots; callback props replace many component events in new code. Context and custom elements remain. The historical syntax stays here; the sources also show today’s counterparts. ## Slots: passing content in from the outside A slot is a placeholder in a component that the caller fills from the outside. The card component decides on the frame, spacing and layout – the caller determines what goes inside. The simplest case is the default slot: ```svelte
Nothing here yet
``` The content between the `` tags is the fallback: it only appears when the caller passes nothing. The card is then used like this: ```svelte

This paragraph lands inside the card.

``` It gets interesting with named slots. A card often has more than one zone – a header and a body, for example. In the child component you assign names for them; in the call you assign markup to those names: ```svelte
{#if $$slots.header}
{/if}
``` ```svelte

Release notes

Everything else fills the default slot.

``` The `$$slots` object deserves a quick look. Its keys are the slot names that were actually passed, and that lets you render the structure conditionally. The `
` frame only appears if the caller really passed a header – otherwise you would have an empty, bordered box. That is the difference between a component you enjoy using and one you find awkward. What matters here is that `$$slots` only reports the presence of a slot, not its content at runtime. Whether a named slot is filled is decided at compile time based on the call, not by what the caller renders into it later. For the typical task – leaving out the frame when nobody supplies a header – that is exactly enough, and you should not confuse `$$slots` with a reactive check for empty content. A second point that comes up regularly in reviews: a named slot can only be output in one place in a component. If you render the same named slot twice, you do not get duplicated content but behavior you should not rely on. If you need the same passed-in content in several places, the way forward is slot props or restructuring the component, not a second ``. ### Slot props: data from the inside out Up to this point, content flows in only one direction: from the outside in. The second part reverses that direction, and this is exactly what gets confused most often. Slot props allow the child component to pass data outward to the inserted markup. The classic case is a list that takes care of iterating but leaves the rendering of each entry to the caller: ```svelte
    {#each items as item, index}
  • {item}
  • {/each}
``` The child component passes `item` and `index` outward through the slot. The caller receives these values with the `let:` directive and is free to decide what an entry looks like: ```svelte {index + 1}. {item.name} – {item.role} ``` The list takes care of the loop, keys and structure; the caller brings the concrete rendering and in return receives exactly the data it needs. Keeping these two directions cleanly apart is the core of understanding slots: markup flows in from the outside, data flows from the inside out via slot props. The following diagram captures both paths side by side. ```mermaid flowchart LR Parent["Parent
<List let:item>"] Child["List.svelte
<slot name='item' {item}>"] Render["Rendered <li>"] Parent -- "markup (outside in)" --> Child Child -- "slot props: item, index (inside out)" --> Parent Child --> Render ``` ## Context: passing through the tree without prop drilling Slots solve the question of how to give content to a direct child component. They do not help when a value is needed several levels deep. Imagine a toolbar whose individual buttons want to register with it. Between the toolbar and the button there may be groups, dividers, wrappers. Passing the registration callback through each of these levels as a prop is tedious and makes intermediate components depend on details that are none of their business. This passing along is called prop drilling, and the Context API is the direct answer to it. The provider component stores a value under a key, and every descendant component can retrieve it under the same key: ```svelte
``` ```svelte ``` The button finds its toolbar no matter how many levels lie in between. No prop travels through the intermediate components. By the way, the key may be any value – a string as here, a symbol or an object; a symbol reliably protects against name collisions in larger repositories. The scope of context is strictly limited to the subtree below the provider. A sibling component that does not hang under the same `setContext` component does not see the value – context flows only downward, never sideways and never upward. If a child component itself calls `setContext` with the same key, it shadows the value for its own subtree without changing the value further up; resolution therefore follows the instance hierarchy, not the order in the source code. If you are not sure whether a key was set at all, you can check with `hasContext` instead of relying on an `undefined` from `getContext` – that makes the failure case explicit instead of silent. Two pitfalls come up with remarkable regularity. The first: `setContext` has to be called synchronously during the component’s initialization. If you move the call into `onMount`, an event handler or an `async` function, you do not get an error but something worse – the children simply receive `undefined` on their later `getContext`, and the cause is hard to find. The second pitfall concerns reactivity. ```mermaid graph TD Provider["Toolbar
setContext('toolbar', …)"] Group["ButtonGroup
(no props)"] Divider["Divider
(no props)"] Consumer["ToolbarButton
getContext('toolbar')"] Provider --> Group --> Divider --> Consumer ``` ### Context is not the same as a store Context is bound to the component instance and is not reactive on its own. If I put a plain number into the context and change it later, the children do not update – they read their copy at init, and that is where it stays. A store, in contrast, can be shared globally and is reactive; with `$store` you subscribe to changes and re-render on every update. I have written in more detail about state outside the component and the store mechanics in [Svelte Stores](https://www.mikebild.dev/en/blog/svelte-stores-state-outside-the-component/), and the underlying reactivity is the topic of [Svelte reactivity](https://www.mikebild.dev/en/blog/svelte-reactivity-the-compiler-instead-of-a-virtual-dom/). The two do not exclude each other; on the contrary. The most useful combination in practice puts a store *into* the context. That gives you both: the implicit distribution through the tree from context and the reactivity of a store. ```svelte ``` ```svelte ``` Now context passes the store to every descendant component, and because it is a store, `{$theme}` reacts to every change – without threading a single prop through the tree. ## Web Components: framework-neutral reuse Slots and context solve composition problems inside a Svelte application. The third tool aims outward. Sometimes a component should also work where no Svelte runs – in an existing page, in another framework, in plain HTML. Svelte can compile a component as a custom element, that is, as a real Web Component according to the browser standard. You need two things for this. In the component, you assign a tag name via ``, and when compiling you enable the `customElement` option: ```svelte {name} ``` When bundling, you switch the compiler to custom element output. With Rollup and the official plugin, the relevant part looks like this: ```js // rollup.config.js import svelte from 'rollup-plugin-svelte'; export default { // ... plugins: [ svelte({ compilerOptions: { customElement: true, }, }), ], }; ``` After that, `` is a perfectly normal HTML element. You can use it in any page, without any Svelte runtime on the caller’s side: ```html ``` The exported props become element properties and attributes, so you can address the element like any other DOM element. Svelte encapsulates the styles via Shadow DOM – the badge styles do not spill over onto the surrounding page, and page styles do not leak in uncontrolled. That is usually desired, but it surprises you if you expect global styles; `:global` rules behave differently here. At this point it is worth taking an honest look at the rough edges, because at the end of 2022, Svelte’s custom element mode is functional but not free of tension. The most important point concerns passing data: HTML attributes are always strings. A `name="Ada"` in the markup arrives cleanly, but you cannot pass an object or an array as an attribute. You have to set such values as a JavaScript property on the element, such as `el.items = [...]` – a detail that is easy to overlook if you only use the element declaratively in HTML. Second, custom elements are registered globally once defined; the same tag name cannot be used twice in the same document, which can lead to conflicts when you include several bundles. And third, Shadow DOM encapsulation is a gain for isolation, but it takes away the convenient reach from the outside: if you want to style the element from the page, you have to open the intended places yourself and pass CSS custom properties in deliberately. None of this is a knockout criterion, but these are the places where practice deviates from the first smooth demo. A practical tip from projects: `customElement: true` belongs only on the components you actually want to export, not project-wide. Otherwise you compile the whole app into custom elements and lose the regular Svelte component mode with its advantages. In practice, I maintain a separate build entry for this that bundles exactly the components to be exported. ## When to use which tool The three mechanisms can be sorted clearly by their purpose: - You choose slots when a component dictates its layout but should get its content from the caller – with slot props also when the caller needs data from the inside for rendering. - You choose context when a value or a function is needed several levels deeper and prop drilling would burden the intermediate components unnecessarily; for reactive values, you put a store into the context. - You choose Web Components when a component should run outside the Svelte world – in other frameworks or in plain HTML. A brief note on context at the end of 2022: throughout, I refer to Svelte 3, the current version these days. The syntax shown, `tag="user-badge"`, is the state of Svelte 3; later versions brought changes at this point that are deliberately left out here. If you keep the repository you work on at Svelte 3, you are on safe ground with everything shown here. ## Conclusion Slots, context and Web Components seem at first like three unrelated features, but they are a coherent set of composition tools, each with its own direction. Slots pass markup in from the outside and, via slot props, data back out from the inside. Context distributes values implicitly through the component tree and saves you from prop drilling – it only becomes reactive with a store inside. And custom elements lift a component out of the Svelte world so that it runs wherever standard HTML runs. If you briefly ask yourself with every composition problem in which direction content or data should flow and how far it needs to reach, you will reach for the right one of the three tools almost by yourself. This one question saves you most of the detours in a project. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-svelte.en.html - [Svelte 5: Snippets](https://svelte.dev/docs/svelte/snippet) - [Svelte: slots in legacy mode](https://svelte.dev/docs/svelte/legacy-slots) - [Svelte: Context API](https://svelte.dev/docs/svelte/context) - [Svelte: custom elements](https://svelte.dev/docs/svelte/custom-elements) - [Svelte: ``](https://svelte.dev/docs/svelte/svelte-options) --- # Build vs. Runtime in Web Projects URL: https://www.mikebild.dev/en/blog/build-vs-runtime-in-web-projects/ Date: 2022-11-12 # Build vs. Runtime in Web Projects When you set up a project, this decision takes one second: you pick a framework, accept the default and from then on render everything on the server. You only notice that second months later – when the build takes twenty minutes or the servers fill up at the first traffic spike. The rendering time of a page is an architectural boundary, not a setting you configure away in the build setup. It determines when a page is created, how fresh its data is, what a failure costs and how fast a team can deliver. Still, the question – do we render at build time or at runtime? – usually gets answered implicitly. If you draw the boundary deliberately, you shorten cycles, cut costs and take friction out between content, development and operations. ## The two points in time Every piece of output on the web is created at one of two points in time. At **build time**, work runs once, before any user arrives: templates become HTML, data gets frozen, assets get bundled and optimized. At **runtime**, work runs per request or in the browser while a user waits: data gets fetched, permissions checked, HTML assembled, state hydrated. The key difference is not “fast vs. slow” but **who waits and how often the work happens**. Build work happens once and is delivered any number of times – the user never waits for it. Runtime work happens again on every request – in return, it knows the current moment, the logged-in user and the latest data. ```mermaid flowchart LR subgraph Build["Build-Zeit (einmal)"] Content --> Prerender Prerender --> StaticHTML["Static HTML + Assets"] end subgraph Runtime["Laufzeit (pro Request)"] Request --> Fetch["Fetch data + auth"] Fetch --> Render["Render + hydrate"] end StaticHTML --> CDN CDN --> User Render --> User ``` Between these poles lies a spectrum, not an either-or: static site generation freezes everything at build time. Server-side rendering rebuilds per request. Client-side rendering pushes the work into the browser. And hybrid forms – prerendering plus client-side loading, or static HTML with incremental revalidation – mix both points in time per route. The art lies in drawing the boundary in the right place for each page instead of proclaiming one approach for everything. ## The trade-off, concretely I tie the trade-off to three quantities, because exactly these three carry or slow down a product: freshness of data, cost per request and time to feedback in the team. A marketing or documentation page rarely changes and is the same for everyone. Freezing it at build time is almost always right: afterward it sits as a static file in the CDN, costs practically nothing per request, has no server latency and no server that can fail. ```js // Build-time: runs once, per deploy export async function getStaticProps() { const posts = await cms.getPublishedPosts(); return { props: { posts } }; } ``` An account balance, a personalized dashboard or a price list that changes every hour can’t be frozen. This data belongs at runtime – either per request on the server or as a client-side fetch after the first paint. ```js // Runtime: runs on every request, knows "now" and the user export async function getServerSideProps(ctx) { const user = await auth(ctx.req); const balance = await ledger.getBalance(user.id); return { props: { balance } }; } ``` The real question is not “SSG or SSR?” but: **How old may this output be without becoming wrong?** I call that the data shelf life. If the shelf life is practically infinite (a blog post from 2019), the page belongs in the build. If the shelf life is zero (the current account balance), it belongs at runtime. And in between – the shelf life is minutes or hours – it gets interesting: then I want the delivery cost of a static asset, but a controlled refresh. That’s exactly what caching with revalidation and incremental regeneration exist for. They are the technical answer to a finite data shelf life, not a framework gimmick. ## What this changes, measurably The reason I take this boundary so seriously is its effect on hard numbers. A statically delivered page responds with the latency of the nearest CDN node – double-digit milliseconds, regardless of load. Rendering the same page on the server per request means database round trips, template rendering and a server that has to scale with traffic. During a traffic spike, that’s the difference between “the CDN delivers a file” and “our instances are maxed out and the autoscaling bill explodes.” For pages without a real data shelf life, runtime rendering is therefore not only more expensive but also more fragile – you buy complexity without getting anything in return. Conversely, too much build work costs feedback. If every change to a post triggers a full rebuild of ten thousand pages, the build becomes the bottleneck: an editorial typo takes 20 minutes to become visible, and nobody dares to deploy shortly before the end of the day anymore. That’s not just a performance problem but a productivity problem. The consequence is not “more runtime” but a finer boundary: regenerate only the affected pages instead of everything. Shorter feedback loops are the real gain here – they decide how often a team ships and how calmly it does so. A case I’ve come across in projects: a content-heavy portal historically renders everything on the server because that was once the framework default. Under normal load it works, but the server bill grows linearly with traffic, and every press release that makes the portal go briefly viral turns into an incident. If you move the dozen or so truly static page types – articles, categories, landing pages – into the build and leave only search and personalized areas at runtime, the curve changes fundamentally. The lion’s share of the traffic becomes a CDN file, the servers only carry the small dynamic remainder, and the traffic spike is suddenly a non-event. Not a single line of domain logic was rewritten – only the boundary between build and runtime was adjusted to the actual data shelf life. That’s why I like to summarize the decision in a small table before I touch any tool: | Page | Data shelf life | Point in time | | --- | --- | --- | | Landing page, docs | practically infinite | Build | | Product catalog | hours | Build + revalidation | | Search result, feed | seconds | Runtime (server) | | Dashboard, account balance | zero, personalized | Runtime (server/client) | The table is deliberately simple. It forces exactly the one question you’d otherwise skip: how old may this be? ## How I draw the boundary Before the tooling question, I clarify per route: is the output the same for all users or personalized? How old may it be? What happens if the data source doesn’t respond during rendering? And can the point in time be changed later without rebuilding half the application? If I slice a page so that I can move its rendering time in isolation – from build to runtime, to incremental or back – without touching neighboring routes, then the boundary is usable. An often underestimated part of this is the lifetime of state. In the frontend, the hardest decision is rarely the component tree but the question of where state lives: in a component, in the URL, in a cache, on the server or in a local model. That question is the build-vs-runtime question in miniature. State that belongs in the URL can be rendered on the server and shared. State that exists only on the client requires runtime in the browser and is simply not present in the static HTML. If you get this mapping right, you get shareable, indexable, testable pages almost for free. ## Progressive enhancement as the same boundary This way of thinking isn’t new; it has just grown old. Progressive enhancement has always asked: what do I deliver as a robust baseline, and what do I add at runtime if the client can handle it? Even a canvas element carries this attitude – first check whether a capability is there, then enable a behavior, otherwise offer a fallback. ```html Clock fallback ``` ```js const canvas = document.getElementById("clock"); if (canvas.getContext) { const ctx = canvas.getContext("2d"); // enhance at runtime, only when supported } ``` Exactly the same order – capability, boundary, behavior – applies to server-delivered HTML plus client-side hydration. The static baseline is the build output. The enhancement is the runtime. If both layers are cleanly separated, the page works even when the runtime layer is slow or fails. That’s not outdated knowledge but the conceptual root of the whole rendering discussion. ## The failure path decides A rendering decision only holds up once its failure path is described. What happens if the CMS doesn’t respond during the build – does the deploy abort, or does the page go live with a gap? What happens if an API hangs during server-side rendering – does the whole response block, or does the page render without that part and load it on the client? These questions seem dry, but they’re the difference between a demo and production. Build rendering moves the risk of failure into the deploy pipeline: failures happen once, visibly, before any user sees them. Runtime rendering spreads the risk across every single request: failures happen live, under load, at the worst moment. Both are legitimate – but you should know which risk you’re buying. That’s why I always check whether the decision is reversible: can I switch a route from runtime to build when load increases? Can I invalidate a cache selectively without rebuilding everything? If the answer is no, part of the architecture is still missing. ## Typical mistakes The first mistake is confusing the tool with the decision. An SSG framework is not an architecture, SSR is not a data model, a CDN is not a freshness strategy. These tools can express the boundary between build and runtime cleanly, but they don’t draw it for you. If you accept a framework’s default, you haven’t made a decision; you’ve skipped one. The second mistake is orienting yourself on the happy path. In demo mode, every variant looks fast – one record, one user, no load. It gets interesting with ten thousand pages, with traffic spikes, with a slow upstream API, with an editor who wants to see a correction immediately. That’s exactly where it shows whether the boundary between build and runtime is in the right place. ## Validation Three checks are usually enough for me. First: for every route, it’s stated whether it’s created at build time or at runtime – and why, expressed as a data shelf life. Second: for every runtime route, the failure path is described, including the behavior when the data source is down. Third: the decision can be switched per route without touching neighboring routes. Once these three points are in place, the architecture is robust against exactly the surprises that otherwise catch up with such projects late and expensively. ## Further reading - React: Thinking in React: https://react.dev/learn/thinking-in-react - React: Managing State: https://react.dev/learn/managing-state The sources help you cross-check standards and platform behavior. The actual point remains the architecture decision in the concrete project. ## Conclusion In the end, build vs. runtime is a question about the data shelf life of each individual page. An immutable post can go into the CDN as a file, an account balance needs current data, and many routes lie in between with revalidation. If this decision stays movable per route, a new need for freshness doesn’t have to overturn the rendering of the entire application. --- # Streams in Object Mode: Data Pipelines Beyond Bytes URL: https://www.mikebild.dev/en/blog/streams-in-object-mode/ Date: 2022-11-08 If you switch a stream to `objectMode: true` and bring along your usual `highWaterMark: 16384`, you no longer buffer 16 KiB but 16,384 records. Same number, different unit, and a memory footprint that is off by orders of magnitude. Object mode looks like an incidental constructor option, but it changes what a stream pushes through the pipeline at all – and with it, when throttling kicks in. In the [earlier post on Node.js streams and backpressure](https://www.mikebild.dev/en/blog/nodejs-streams-understanding-backpressure/), everything revolved around bytes: buffers flowing through a pipe, and the art of throttling the flow before memory overflows. That is the standard case for file and network I/O. But as soon as you are not copying files but processing records – CSV lines, JSON objects, log entries – that picture no longer goes far enough. When a stream works in object mode, it no longer carries buffers or strings, but arbitrary JavaScript values – whole objects, arrays, numbers. That turns a tool for raw byte streams into a tool for data processing. And the nice part: the mechanics stay the same. You chain stages, each stage does one thing, and in the end you have a pipeline that passes one record after another without loading everything into memory at once. ## What object mode really changes A stream in standard mode knows exactly two data types: `Buffer` and `String`. Everything you push into it has to be one of the two. Object mode lifts this restriction. A `new stream.Transform({ objectMode: true })` accepts and emits arbitrary JS values. The only exception is `null` – this value is reserved and signals the end of the stream. More on that later, because this is exactly where a pitfall lies. Object mode is set per stream via the constructor option, and the default is `false`. So you turn it on deliberately. The pattern already shows up throughout the examples in my [Node.js repository](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/) – there, however, still in the ES5 style with `util.inherits` and `Readable.call(this, { objectMode: true })`. A `Readable` that passes on two small objects looks like this there: ```javascript const { Readable } = require('stream'); const util = require('util'); // ES5 pattern from the training repo const ReadStream = function () { Readable.call(this, { objectMode: true }); this.data = [ { id: 0, value: 1 }, { id: 1, value: 2 }, ]; this.curIndex = 0; }; util.inherits(ReadStream, Readable); ReadStream.prototype._read = function () { if (this.curIndex === this.data.length) { return this.push(null); // signals end of stream } this.push(this.data[this.curIndex++]); }; ``` That works and grew historically. Still, I prefer to show it in modern class syntax, because it is closer to what you find in codebases today. With `class ... extends Transform`, the constructor ritual becomes a `super({ objectMode: true })`, and the processing logic sits in a clearly named method. ## The one core method: `_transform` At its core, a transform stream has a single method you write yourself: `_transform(chunk, encoding, callback)`. It is called once for every incoming value. You emit results with `this.push(value)` and report with `callback()` that this value has been fully processed. In object mode, `chunk` is the raw JS value – the `encoding` argument is ignored because there is nothing to decode here. The key point: `push` and `callback` are two separate things. `push` sends output to the next stage, `callback` signals “I am done with this input value.” You can `push` zero, one or several times per input and call `callback` exactly once at the end. If you only call `callback()` without `push`, the value disappears – that is the natural way to leave something out in a filter. Here is a processing stage that parses raw CSV lines into objects: ```javascript const { Transform } = require('stream'); class ParseRow extends Transform { constructor() { super({ objectMode: true }); } _transform(line, _encoding, callback) { const [id, name, status] = String(line).split(','); this.push({ id: Number(id), name, status }); callback(); } } ``` And a filter stage that only lets active records through. This is where leaving out shows: if the condition is not met, nothing is pushed; only `callback()` is called. ```javascript const { Transform } = require('stream'); class FilterActive extends Transform { constructor() { super({ objectMode: true }); } _transform(record, _encoding, callback) { if (record.status === 'active') { this.push(record); } // no push means the record is dropped callback(); } } ``` A formatting stage rounds out the picture. It takes the object and shapes an output line from it: ```javascript const { Transform } = require('stream'); class FormatOutput extends Transform { constructor() { super({ objectMode: true }); } _transform(record, _encoding, callback) { this.push(`#${record.id} ${record.name}\n`); callback(); } } ``` Three small stages, each with a single responsibility. That is exactly how composability comes about. ## Chaining stages: parse, filter, format The actual pipeline is then almost unremarkable – and that is a good sign. I chain the stages with `pipeline()` from the `stream` module, not with a chain of `pipe()` calls. The reason: `pipeline()` propagates errors and cleans up the streams involved when one fails. A plain `pipe()` chain does not – there you have to handle errors and cleanup at every seam yourself, and that is exactly what gets forgotten in practice. ```javascript const { Readable, pipeline } = require('stream'); const csvLines = ['0,Ada,active', '1,Linus,inactive', '2,Grace,active']; pipeline( Readable.from(csvLines), new ParseRow(), new FilterActive(), new FormatOutput(), process.stdout, (err) => { if (err) { console.error('pipeline failed:', err); } else { console.log('pipeline finished'); } } ); ``` The source here is `Readable.from(csvLines)` – more on that in a moment. The sink is `process.stdout`, a perfectly ordinary writable stream. In between, one record after another flows through: first as a string, after `ParseRow` as an object, filtered by `FilterActive`, shaped back into a line in `FormatOutput`. At no point is the entire data set in memory – there is only ever a small supply of buffered values in flight. As a diagram, this data flow looks like this: ```mermaid flowchart LR A["Source
Readable.from"] -->|"CSV line (string)"| B["Parse
_transform"] B -->|"JS object"| C["Filter
_transform"] C -->|"JS object"| D["Format
_transform"] D -->|"output line"| E["Sink
Writable"] ``` The edges show what actually flows: first a line as a string, then JS objects through the middle stages, and text again at the end. Each stage only takes care of its own conversion and knows nothing about its neighbors. ## Aggregating with `_flush` Filtering and reshaping work record by record. For aggregations – sums, counts, groupings – you need a different rhythm: collect while the values arrive, and emit the result only once the source is exhausted. That is what `_flush(callback)` is for. This method is called exactly once, just before the stream ends. You collect in `_transform` and emit in `_flush`. ```javascript const { Transform } = require('stream'); class CountByStatus extends Transform { constructor() { super({ objectMode: true }); this.counts = {}; } _transform(record, _encoding, callback) { this.counts[record.status] = (this.counts[record.status] || 0) + 1; callback(); // nothing pushed yet, just accumulate } _flush(callback) { this.push(this.counts); // emit the aggregate once at the end callback(); } } ``` This stage swallows many objects and emits a single one at the end – the aggregate. It shows nicely that a stream stage does not have to keep its input and output counts one to one. ## Backpressure now counts objects In object mode, `highWaterMark` means something different than in byte mode – people regularly read past this, with noticeable consequences. `highWaterMark` is the threshold at which a stream counts as “full enough” and triggers backpressure. In byte mode, this threshold is measured in bytes; in 2022 the general default was 16 KiB, since Node 22 it has been 64 KiB. In object mode it is measured in objects, still with a default of 16 objects. That is no small detail. If you come from byte mode and read `highWaterMark: 16`, you reflexively think of 16 bytes and consider it absurdly small. In object mode, though, it means 16 buffered objects – a perfectly sensible supply. Conversely, a `highWaterMark: 16384` set out of byte-mode habit can mean in object mode that you buffer 16,384 objects before backpressure kicks in. That is rarely what you want. It is also important that `highWaterMark` is a threshold, not a hard barrier. The buffer may exceed it – the threshold is the signal from which `push()` returns `false` and asks upstream stages to throttle. With `pipeline()` and `pipe()`, this pausing and resuming happens automatically. So normally you rely on this automatic interplay and only have to check the return value of `push` yourself when you drive a source by hand. Backpressure works just as reliably in object mode as in byte mode; only the unit is different. To tell them apart, here are the two modes side by side: - Byte mode (standard) carries `Buffer` or `String`; `highWaterMark` counts bytes here. The general default depends on the Node version and has been 64 KiB since Node 22. - Object mode (`objectMode: true`) carries arbitrary JS values except `null`, `highWaterMark` counts objects here with a default of 16, and the typical uses are data pipelines that parse, filter, transform and aggregate. ## The bridge to async iterators So far I have built streams as classes. That is not always necessary, and it is often even cumbersome. Node offers two modern connectors that bring object mode together with the world of async iterators: `Readable.from(iterable)` and `for await ... of`. `stream.Readable.from(iterable)` takes any iterable or async iterable – an array, a generator, an async generator – and turns it into a readable stream. By default, this stream works in object mode. It is the most elegant way to feed a data source into a pipeline without writing your own `Readable` class. That is exactly what I already used above with `Readable.from(csvLines)`. The other direction is at least as handy: a readable stream is itself an async iterable. So you can consume it directly with `for await ... of`, and the language construct takes care of pausing, resuming, backpressure and the end – all automatically. ```javascript const { Readable } = require('stream'); async function* generateRecords() { yield { id: 0, value: 1 }; yield { id: 1, value: 2 }; yield { id: 2, value: 3 }; } async function main() { const source = Readable.from(generateRecords()); for await (const record of source) { console.log('received:', record); } } main(); ``` You can even use async generators as a pipeline stage. A generator that consumes a source and passes on filtered values replaces an entire transform class with a few lines: ```javascript async function* filterEven(source) { for await (const n of source) { if (n % 2 === 0) { yield n; } } } ``` Whether you write a transform class or an async generator is to a good extent a matter of taste. I reach for the class when I have to keep internal state across many values, for example in an aggregation with `_flush`. For pure filters and reshaping, async generators are often the shorter, more readable way. ## Two pitfalls that strike again and again The first pitfall is mixing byte and object mode in one pipeline. You start with `fs.createReadStream(...)`, which is a byte stream and delivers buffers. Right after it you attach an object mode stage that wants to work with `record.status` – and get a buffer instead of an object. Between a byte readable and the first object stage there always has to be a parse layer that decodes buffers into values. The reverse seam is just as tricky: if you push an object into a non-object-mode writable, Node answers with a type error (`ERR_INVALID_ARG_TYPE`) that demands a string, Buffer or Uint8Array. At every seam you should be aware of what data type is flowing right now. The second concerns `null` as a legitimate payload value. Because `push(null)` means the end of the stream, you cannot send a real `null` value through an object mode stream – it would be mistaken for the end signal and cut off the remaining data. If `null` has a real meaning in your payload, you need a stand-in object, a so-called sentinel, such as `{ value: null }` instead of a bare `null`. A third point is a matter of diligence: you pass errors in `_transform` to `callback(err)` instead of throwing them. Only then do they end up in the stream’s error channel and get propagated cleanly by `pipeline()`. An error thrown in the middle of asynchronous processing is much harder to catch – another argument for `pipeline()` over a bare `pipe()` chain. ## Conclusion Object mode turns Node.js streams from an I/O tool for bytes into a tool for data processing. The mechanics stay familiar – `_transform` with `push` and `callback`, `_flush` for aggregating, chaining via `pipeline()` – but the content is now whole JS values. This lets you build pipelines that parse, filter, transform and aggregate as separate, composable stages that only ever hold a small supply of records in memory. I take away two things as the core message. First: in object mode, `highWaterMark` counts objects, not bytes – mix that up and you size your buffer wrong by orders of magnitude. Second: `Readable.from` and `for await ... of` are the modern bridge between streams and async iterators and in many cases save you from writing your own stream class. If you have understood the byte-oriented part from the post on [buffers and binary data](https://www.mikebild.dev/en/blog/buffers-in-nodejs-working-with-binary-data/) and add object mode to it, you have both halves of the stream world together – the raw one and the structured one. ## Further reading - [Node.js Stream API – Object mode](https://nodejs.org/api/stream.html#object-mode) - [Node.js Stream API – Buffering](https://nodejs.org/api/stream.html#buffering) - [Node.js Stream API – stream.Readable.from](https://nodejs.org/api/stream.html#streamreadablefromiterable-options) - [Node.js Stream API – readable[Symbol.asyncIterator]](https://nodejs.org/api/stream.html#readablesymbolasynciterator) - [Node.js Stream API – Class: stream.Transform](https://nodejs.org/api/stream.html#class-streamtransform) --- # Reproducible Test Pipelines: No Flakiness, No Chance URL: https://www.mikebild.dev/en/blog/reproducible-test-pipelines/ Date: 2022-10-26 ```text $ git rev-parse HEAD 9f2c1ab Lauf 412 FAIL checkout.spec.ts › Rabatt gilt bis Monatsende (2.1s) Lauf 413 PASS checkout.spec.ts › Rabatt gilt bis Monatsende (2.0s) ``` The same commit, two runs, two results. If nothing in the code has changed and the result flips anyway, then the test reads another input that isn’t in the repository. “Just run the build again, it’s sometimes red for no reason” is therefore not a diagnosis. It is an admission that nobody knows which input that is. A test that changes its result without a code change is reacting to another input. Often it hides in time, data or missing isolation. With integration tests, the network, cloud services or other external systems can also genuinely fluctuate. Not every dependency can be frozen; I still have to make it visible, limit it and name it in the test type. Otherwise the team gets used to its own test suite reporting green one time and red the next, and loses trust in its merge gate. ## Why this is a business problem, not a test detail Before we get to the mechanics, here’s why the topic doesn’t end in the test directory: a flaky suite doesn’t stay a developer nuisance. It slows down the entire ability to deliver. Martin Fowler nailed this back in 2011. A non-deterministic test is not just useless – it is a “virulent infection”. As soon as a single test occasionally turns red for no reason, everyone gets used to ignoring red builds. At exactly that moment the suite no longer protects anything, because a real failure now looks like the usual noise. The damage is not the one flaky test but the loss of trust that spreads to the whole suite. This is not an academic argument. In 2016, Google published numbers on its Testing Blog: around 1.5 % of all test runs are flaky. That sounds like little until you scale it up. Flaky tests clog the pipeline, block branches, create duplicate bug tickets and burn developer time on a large scale – time that flows into diagnosing failures that aren’t failures at all. And this is exactly where the loop closes to delivery performance. Accelerate (Forsgren, Humble, Kim, 2018) connects the four well-known metrics – Deployment Frequency, Lead Time for Changes, Change Failure Rate and Time to Restore – with practiced continuous integration and *reliable* test automation. The word “reliable” matters. An elite team that deploys on demand can only do so because the suite is a trustworthy gate. A flaky suite is not a gate but a traffic light that switches randomly – and nobody deploys based on a random traffic light. Incidentally, I deliberately always read the four metrics together: a high deploy frequency combined with a high change failure rate is worthless. Determinism in the suite is one of the conditions under which these metrics become honest at all. So the gain doesn’t lie in “prettier tests”. It lies in shorter cycles, less friction in the team and higher delivery quality. That’s why determinism belongs in the architecture discussion and not on the QA checklist. ## The three axes as a gate The discussion can be reduced to a simple picture. A pipeline runs from left to right: commit, build, test, merge. Above the test stage there are three dials. Only if all three are set to “controlled” does the gate turn green and the merge become possible. If one tips to “uncontrolled”, you get flaky red. ```mermaid flowchart LR C[commit] --> B[build] --> T[test gate] --> M[merge] A1[TIME
frozen clock] --> T A2[DATA
seeded fixtures] --> T A3[ISOLATION
hermetic sandbox] --> T T -->|all three controlled| M T -->|any axis uncontrolled| F[flaky red] ``` The value of this picture lies in diagnosis. When a build is flaky, I don’t ask “which test is acting up” but “which of the three axes is uncontrolled”. That almost always leads to the cause faster, because it structures the search. Let’s go through the axes one by one. ## Axis 1: Time The most common hidden cause. As soon as domain code calls `new Date()` or `Instant.now()` directly, it is coupled to the wall clock – and the wall clock is guaranteed to change between two test runs. A test that checks “the discount applies until the end of the month” will behave differently on the 31st than on the 1st; a test with `expiresAt` in exactly 24 hours flips at time zone and DST boundaries. The solution is not a library but a design decision: the clock becomes an injected service. Domain code never asks the operating system but always the abstraction. ```typescript interface Clock { now(): Date; } class SystemClock implements Clock { now(): Date { return new Date(); } } class FixedClock implements Clock { constructor(private readonly instant: Date) {} now(): Date { return this.instant; } } // domain code never calls `new Date()` directly: function isExpired(subscription: Subscription, clock: Clock): boolean { return subscription.expiresAt.getTime() <= clock.now().getTime(); } ``` In production the `SystemClock` runs, in the test a `FixedClock(new Date("2022-01-01T00:00:00Z"))`. This is not an exotic idea: Java has had exactly this abstraction built in with `java.time.Clock` since version 8, in Ruby Timecop has done it since 2011, in JavaScript Sinon’s fake timers provide the same. I prefer the injected clock over global time freezing because it is more honest: it makes the time dependency visible in the code instead of overriding it globally. So that it doesn’t sound too simple: time determinism is more than freezing the clock. Time zones, DST transitions, locale-dependent formatting and the iteration order of maps or sets are sources of non-determinism of their own. The frozen clock solves the big chunk, not everything. ## Axis 2: Data The second axis is inconspicuous and does silent damage: random data. A `faker.name()` or an unseeded random number makes every test run unique. Most of the time that goes fine – until the one record shows up that breaks the sorting, a length limit or a Unicode edge case. Then the build is red, green on the next run, and nobody can reproduce it. The rule is simple: deterministic data. Either fixed fixtures or a seeded random generator. The seeded route is often the better one, because it keeps the variation and still stays reproducible. ```typescript import seedrandom from "seedrandom"; function makeRng(seed = "1337") { return seedrandom(seed); } // same seed -> same sequence -> reproducible failures function buildUser(rng: () => number): User { return { id: Math.floor(rng() * 1_000_000), tier: rng() > 0.5 ? "premium" : "free", }; } ``` Interestingly, exactly this rule is explicitly codified in contract testing. Pact – in use for consumer-driven contracts since 2013 – states the rule “use deterministic data, avoid random data” with no ifs or buts. The reason is revealing: if a contract contains random data, it is marked as “changed” on every run even though nothing has changed in the domain. So non-deterministic data produces not only flaky tests but flaky contracts. Contract testing deserves a brief appreciation here, because it connects the data axis with the isolation axis. Instead of one service starting the other to test “for real”, each consumer-provider pair is checked in isolation against a shared, deterministic contract. No network, no foreign runtime, no timing – the classic sources of flakiness are ruled out by construction. ## Axis 3: Isolation The third axis is the most fundamental and carries the fitting name hermeticity. The Bazel documentation uses “hermeticity” for builds and tests whose tools and inputs are known and controlled. This sealing off from the network, a shared database and host state removes important hidden influences; on its own, it doesn’t yet guarantee determinism if, for example, races, randomness or time remain uncontrolled in the test. A non-hermetic test can be reproducible, but it depends more strongly on its environment. The two practical enemies of isolation are shared state and test order dependency. If test B is only green because test A wrote a row into the database beforehand, the suite is a chain that breaks with every reordering. The antidote is called shared-nothing: each test builds up its state and tears it down again. For real dependencies such as a database or message broker, Testcontainers have become established since 2015: an ephemeral, throwaway instance per test instead of a shared, long-lived environment. The following skeleton shows the isolation discipline compactly – and it deliberately combines all three axes: ```typescript let db: EphemeralDatabase; let clock: Clock; let rng: () => number; beforeEach(async () => { rng = makeRng("1337"); // DATA: seeded clock = new FixedClock(FIXED_INSTANT); // TIME: frozen db = await startEphemeralContainer(); // ISOLATION: hermetic await db.beginTransaction(); }); afterEach(async () => { await db.rollbackTransaction(); // state reset, shared-nothing await db.stop(); }); ``` The transaction rollback per test is my preferred reset mechanism where it works: fast and complete. Where transactions aren’t enough, truncation between tests does the job. Only the principle matters: no test may depend on what another one left behind. Fowler’s list of causes, by the way, maps exactly onto these three axes. He names lack of isolation, time, asynchrony or remote services, and resource leaks. Drawn as a fishbone: ```mermaid flowchart LR ISO[lack of isolation] --> S[flaky build] TIME[time / clock] --> S ASYNC[async / remote services] --> S LEAK[resource leaks] --> S ``` Asynchrony deserves a sentence of its own, because it is the classic generator of flakiness. The most common mistake is a `sleep(500)` in the hope that an asynchronous operation is “probably done”. On a slow CI runner, sometimes it isn’t. The fix is never a longer wait but polling against a real condition – waiting until the state has actually been reached, with a timeout as an upper limit. “Wait until” instead of “wait how long”. ## Dealing honestly with retries That leaves the topic everyone talks around in such discussions: the automatic retry. Almost every CI system offers to simply rerun failed tests, and if the second run is green, the build counts as green. That is tempting, because it makes the red builds disappear immediately. The assessment is clear: retries hide non-determinism, they don’t eliminate it. As a short-term emergency patch to keep a team from grinding to a halt completely, a limited retry can be acceptable. As a permanent solution, it switches off exactly the signal you need for root cause analysis. A time-limited quarantine can be more honest: the test keeps running in a separate job and gets a named owner and a deadline. The main build doesn’t turn red because of it; the missing coverage in the merge gate, however, remains a deliberately accepted risk until the fix. ```yaml # conceptual pipeline stages stages: - name: test fail_on_red: true # the trustworthy merge gate - name: contract-verify run: pact can-i-deploy --to prod - name: quarantine tests: tagged("flaky") fail_on_red: false # does not block merge on_red: open_bug_ticket # but never silently ignored ``` The difference between retry and quarantine is a question of attitude. Retry says: “I hope it was chance.” Quarantine says: “I know the gap, its owner and its deadline.” Without these three pieces of information, quarantine too becomes nothing more than permanent ignoring. ## Conclusion The common thread is simpler than the number of libraries suggests. Flakiness has a cause, but not every cause lies entirely within the test function. Freezing time, fixing data and establishing isolation clears out the most common homemade sources. External dependencies are simulated, deliberately observed or moved into a dedicated integration test whose range of fluctuation is known. And the payoff is not “greener dashboards”. The payoff is a merge gate whose verdict the team can assess. If you dismiss flaky tests as “bad luck”, you hand your quality control over to chance. If you look for the hidden input and openly state the remaining uncertainty, you can react sensibly to a red build again. ## Further reading - Martin Fowler: “Eradicating Non-Determinism in Tests” (2011) – https://martinfowler.com/articles/nonDeterminism.html - Google Testing Blog: “Flaky Tests at Google and How We Mitigate Them” (2016) – https://testing.googleblog.com/2016/05/flaky-tests-at-google-and-how-we.html - Google Testing Blog: “Where do our flaky tests come from?” (2017) – https://testing.googleblog.com/2017/04/where-do-our-flaky-tests-come-from.html - Bazel: Hermeticity – https://bazel.build/basics/hermeticity and Test Encyclopedia – https://bazel.build/reference/test-encyclopedia - Pact: consumer-driven contracts, deterministic data – https://docs.pact.io/ - Forsgren, Humble, Kim: “Accelerate” (2018), DORA metrics – https://www.atlassian.com/devops/frameworks/dora-metrics - Ford, Parsons, Kua: “Building Evolutionary Architectures” (1st edition, 2017) – https://nealford.com/books/buildingevolutionaryarchitectures.html - Trunk-Based Development – https://trunkbaseddevelopment.com --- # Adapter Design: Where Frameworks End URL: https://www.mikebild.dev/en/blog/adapter-design-where-frameworks-end/ Date: 2022-10-12 # Adapter Design: Where Frameworks End An adapter in the SvelteKit sense is neither a textbook design pattern nor a deployment tool. It is a piece of code that runs after the build, takes the framework’s output and turns it into something a concrete platform can execute: a Node server, a Lambda function, a worker at the network edge. It starts no processes, it serves no requests, and at its core it provisions no infrastructure. It translates. The definition sounds harmless. What is interesting is what it implies: an adapter is exactly the place where a framework stops taking responsibility – and the platform begins. Everything before this place belongs to the framework: routing, rendering, data loading, the semantics of a page. Everything after it belongs to the platform: process model, network, file system, limits, price tag. If you write an adapter, you do not draw this boundary yourself, but you have to trace it precisely. And in doing so, you notice how many decisions were made silently on both sides. Since the beginning of the year, I have been maintaining such an adapter: `sveltekit-adapter-aws` brings SvelteKit applications to Lambda, S3 and CloudFront via CDK. [I have already introduced the project itself](https://www.mikebild.dev/en/blog/sveltekit-adapter-aws-framework-meets-cloud/) – this post is about what I learned about the interface while building it. Because the real insight is not in the AWS part but in the question every adapter has to answer: what belongs on which side? ## The contract over the build output SvelteKit gives an adapter surprisingly little – and that is exactly what is good about it. The interface consists of an object with a name and an `adapt` function that receives a `builder` object. The builder is the complete contract: it provides the client assets, the prerendered pages and the server code, plus a manifest with the route metadata. Nothing more. ```js import { writeFileSync } from 'node:fs'; export function adapter(options = {}) { return { name: 'sveltekit-adapter-aws', async adapt(builder) { const out = 'build'; builder.rimraf(out); builder.writeClient(`${out}/assets`); // static files for the CDN builder.writePrerendered(`${out}/prerendered`); builder.writeServer(`${out}/server`); // the SSR part const manifest = builder.generateManifest({ relativePath: './' }); writeFileSync( `${out}/server/manifest.js`, `export const manifest = ${manifest};` ); } }; } ``` With this, the framework says: there are three kinds of artifacts, and I write them wherever you want them. Where they ultimately belong, how they are delivered, what a “server” even is on your platform – your problem. For AWS, this concretely means: client assets and prerendered pages go into an S3 bucket behind CloudFront, the server code is built into a Lambda bundle with esbuild, and the routing rules of the CDN distribution have to decide which request goes to S3 and which to the function. ```mermaid flowchart LR subgraph FW[Framework-Seite] SRC[Quellcode] --> VITE[Vite-Build] VITE --> CL[Client-Assets] VITE --> PR[Prerenderte
Seiten] VITE --> SV[Server-Code +
Manifest] end subgraph AD[Adapter] CL --> MAP[Zuordnung,
Bundling] PR --> MAP SV --> MAP end subgraph PF[Plattform-Seite] MAP --> S3[S3-Bucket] MAP --> LB[Lambda-Bundle] S3 --> CF[CloudFront] LB --> CF end ``` The mapping in the middle box is the part nobody sees and where most of the work lies. Which paths are static, which are dynamic? What happens to a prerendered page that also has a server route? Who sets the cache headers? The framework has an opinion on this, but it does not enforce it – it cannot enforce it, because it does not know the platform. The adapter has to translate the framework’s opinion into the platform’s mechanics without inventing a third opinion of its own. ## Request and response as a common language At runtime, the contract is even narrower. The SvelteKit server speaks the web standards: it takes a `Request` object from the Fetch API and returns a `Response` object. That is a deliberate and, in my view, smart decision – the same types that have existed in the browser for years and that Deno Deploy and Cloudflare Workers use as their native format anyway. The newly founded WinterCG is currently trying to standardize exactly this core of server-side web APIs across runtimes. SvelteKit committed to it even before that. For the adapter, this means: its runtime job is one translation there and one back. AWS does not speak Fetch; AWS speaks API Gateway events. The handler in my Lambda bundle therefore essentially does only this: ```js import { Server } from './index.js'; import { manifest } from './manifest.js'; const server = new Server(manifest); await server.init({ env: process.env }); export async function handler(event) { const request = toRequest(event); // API Gateway event -> fetch Request const response = await server.respond(request, { getClientAddress: () => event.requestContext.http.sourceIp }); return toLambdaResult(response); // fetch Response -> Lambda result } ``` The two inconspicuous functions `toRequest` and `toLambdaResult` are where the platform shows its quirks. An API Gateway event carries query parameters already split up; the `Request` wants a complete URL. Binary responses have to be Base64-encoded, and whether something is “binary” is decided by the adapter based on the content type – a heuristic you get wrong for the first time at some point. And `Set-Cookie` is the classic: several cookies in one response are merged into one line by the `Headers` implementation, while API Gateway expects them as a separate array. ```js async function toLambdaResult(response) { const contentType = response.headers.get('content-type') || ''; const isBinary = !/^(text\/|application\/(json|javascript))/.test(contentType); return { statusCode: response.status, headers: Object.fromEntries(response.headers.entries()), // API Gateway expects cookies as a separate array cookies: splitSetCookie(response.headers.get('set-cookie')), body: isBinary ? Buffer.from(await response.arrayBuffer()).toString('base64') : await response.text(), isBase64Encoded: isBinary }; } ``` None of this is difficult. But all of it is responsibility that the framework explicitly does not take on – and should not take on either. If SvelteKit started knowing API Gateway quirks, tomorrow it would also have to know those of Azure, Google and every host that invents its own event structure. The narrow Fetch API is the boundary that keeps both sides independent. ```mermaid sequenceDiagram participant C as Client participant CF as CloudFront participant L as Lambda-Handler participant K as SvelteKit-Server C->>CF: HTTP-Request CF->>L: API-Gateway-Event L->>K: fetch Request K-->>L: fetch Response L-->>CF: statusCode, headers,
cookies, body CF-->>C: HTTP-Response ``` ## The silent assumptions of the environment The third part of the boundary is the most unpleasant because it appears in no interface signature: the assumptions about the environment. A SvelteKit application may run almost arbitrary Node code in its server routes. Which of it works on the target platform only the adapter knows – and often only operations. On Lambda, I kept running into three points: - The file system is read-only, except for `/tmp`. If your server code stores files, writes caches to disk or expects an SQLite file next to the code, it falls flat on its face with the first real request – locally with `vite dev`, everything works. - Environment variables come from the function configuration, not from a `.env` file. SvelteKit now has the hook `server.init({ env })` for this, through which the adapter passes the variables in explicitly. It is exactly such small handover points that make the boundary honest: the environment is a parameter, not global state. - There is no streaming. Lambda behind API Gateway buffers the complete response and delivers it in one piece, with hard size limits. A `Response` with a slow stream as its body simply cannot be represented on this platform – the adapter has to collect the stream and materialize it. The last point shows why adapter design is more than format conversion. With the `Response` type, the framework promises a capability – streaming bodies – that the platform cannot deliver. The adapter cannot fix that; it can only make it visible: document it, warn during the build if in doubt, and buffer the response correctly instead of cutting it off. Where framework promises and platform capabilities diverge, the adapter is the one that has to explain the difference. ## When the framework side moves In October 2022, SvelteKit is still pre-1.0, and as an adapter author you notice that more clearly than as an application developer. Since the beginning of the year, I have had to touch the adapter integration several times: `app.render(request)` became `server.respond(request, options)`, the manifest format and the builder methods shifted, and the big routing overhaul in late summer changed what ends up in the server output at all. The switch to Vite 3 added the tooling level on top. I do not want this to be understood as a complaint – a framework before 1.0 may change its interfaces; that is what this phase is for. Something else was revealing: each of these changes showed me which of my assumptions belonged to the contract and which I had only imagined. If you have to catch up with an interface three times, you understand it better afterward than someone who has read it once. In practice, I drew two consequences from this. First: the SvelteKit version is pinned exactly in the adapter project, and every update is a deliberate step with its own commit instead of an incidental `npm update`. Second: the most important test is not a unit test of the conversion functions but an example project that is actually built and deployed with every change. An adapter is a consumer of an unstable API; the only reliable check is the one that goes the whole way – from `vite build` to the HTTP response from CloudFront. Everything else only tests your own idea of the contract, not the contract. ## The same boundary, other frameworks The question “what belongs on which side” comes up everywhere; the frameworks just answer it differently – and the answers are revealing. Next.js has no adapter interface. The platform is implicitly Vercel, and if you deploy elsewhere, you struggle with an output that was never meant for it. What I find remarkable is that Vercel turned the tables this year with the Build Output API: there, the platform defines a documented directory format, and any framework can build toward it. That is the same boundary, just drawn from the other side – instead of “the framework defines, the adapter translates,” it is “the platform defines, the framework delivers.” Whoever owns the contract holds power over the boundary. Remix, in turn, built in the translation from the start: `createRequestHandler` takes platform-specific requests, and official adapters exist for Express, Architect and Cloudflare Workers. There, too, the core is identical to what SvelteKit does – web standard `Request` in, web standard `Response` out, and around it a thin layer of platform dialect. The more consistently frameworks commit to these standards, the thinner the adapters become. In the best case, the runtime translation shrinks to zero, as with Deno Deploy and the Workers, which speak Fetch natively, and only the build output part remains. ## What I take away from this An adapter is the most honest place in a framework architecture because nothing can be abstracted away there. On one side stands what the framework really guarantees: three kinds of artifacts, a manifest, a Fetch API. On the other side stands what the platform really demands: its event format, its file system, its limits. The adapter in between should be boring and thin. If it gets thick, that is a finding – then either the framework guarantees too little or the platform demands too much, and you should know both before you build an application on it. That is why looking into the adapter is worthwhile even for those who will never write one. If you understand what `adapter-node` or an AWS adapter does in detail, you know exactly which assumptions your own application makes about its environment – and which of them will break at the next platform change. The boundary between framework and platform does not disappear because you ignore it. It just becomes invisible. A good adapter makes it visible again, and that is worth more than any other feature it brings along. ## Further reading - My adapter project: https://github.com/MikeBild/sveltekit-adapter-aws - SvelteKit docs on adapters: https://svelte.dev/docs/kit/adapters - SvelteKit docs “Writing adapters”: https://svelte.dev/docs/kit/writing-adapters - Remix Server Adapters: https://v2.remix.run/docs/other-api/adapter --- # RxJS in React: Observables in the UI Data Flow URL: https://www.mikebild.dev/en/blog/rxjs-in-react-observables-in-the-ui-data-flow/ Date: 2022-10-05 An observable is not a state container. It holds no value that a component could read, and it does not replace `useState`. It describes an execution that pushes values to its subscribers over time and that can be canceled at any moment. If you take this definition seriously, you have half answered the question of RxJS in React: where it is only about the current value of a field, an observable contributes nothing. It only pays off where the timeline itself becomes the problem. **Editorial note (July 2026):** The component-local subscriptions with `useEffect` and cleanup shown here remain sensible. If, on the other hand, RxJS-based state is read by several components as an external store, React needs a stable snapshot contract, typically via `useSyncExternalStore` or an adapter library built on it. The post deliberately stays with the coordination of events and does not turn RxJS into a general state solution. The whole discussion, which usually gets stuck in React teams, hinges on this distinction. If you know RxJS from the Angular world, you often associate it with pipelines that ran across the entire application and that nobody could follow anymore. If you only know streams from the outside, you find them elegant and would pour the entire component state into observables. Both positions miss the narrow area that actually matters: keystrokes that arrive faster than an API responds. Responses that arrive in the wrong order. Connections that just keep sending. I take these three cases apart here – and after that, the places where React’s built-in tools remain the better choice. ## A quick framing: what an observable is in this context I assume the basics from [RxJS: Push and Pull](https://www.mikebild.dev/en/blog/rxjs-telling-push-and-pull-apart/) here – that post explains why an observable is a push producer and how it differs from promises and iterators. For the React context, three properties are decisive. First, an observable is *lazy*: the code in the `subscribe` callback only runs when someone actually calls `subscribe()`. An observable that nobody subscribes to does nothing. Second, a normal observable is *cold* and *unicast* by default – every subscription starts its own execution. Third, `subscribe()` returns a `Subscription`, and its `unsubscribe()` ends the execution again. Taken together, these three points explain why RxJS and the `useEffect` lifecycle fit together so well: an effect has exactly the structure “set up on mount, clean up on unmount” that an observable needs. ```ts import { Observable } from 'rxjs'; // A cold observable: the callback runs once per subscriber const ticker$ = new Observable((subscriber) => { let count = 0; const id = setInterval(() => subscriber.next(count++), 1000); // teardown logic runs on unsubscribe return () => clearInterval(id); }); const subscription = ticker$.subscribe((value) => console.log(value)); // later, to stop and clean up: subscription.unsubscribe(); ``` Once you have internalized the structure of this `subscribe`/`unsubscribe` pattern, you immediately recognize the parallel to the cleanup function of `useEffect`. That is no coincidence but the actual reason why the integration is so straightforward. ## The first sensible case: debouncing input The classic example is a search field. Firing an HTTP request on every keystroke is wasteful – the user types “React,” and six requests are already on their way, five of which are outdated immediately. The naive React solution cobbles together a `setTimeout` with `clearTimeout` in the effect. That works, but it quickly becomes confusing as soon as more than just debouncing comes into play. With RxJS, debouncing becomes a single declarative operator. `debounceTime(300)` only emits a value once no new value has followed for 300 milliseconds. I feed the input in through a `Subject` – a Subject is both an Observable and an Observer, so I can call `next()` in the `onChange` handler and subscribe to the pipeline at the other end. ```tsx import { useEffect, useRef, useState } from 'react'; import { Subject } from 'rxjs'; import { debounceTime, distinctUntilChanged } from 'rxjs/operators'; function SearchField() { const query$ = useRef(new Subject()).current; const [debounced, setDebounced] = useState(''); useEffect(() => { const subscription = query$ .pipe(debounceTime(300), distinctUntilChanged()) .subscribe(setDebounced); return () => subscription.unsubscribe(); }, [query$]); return ( query$.next(event.target.value)} placeholder="Enter search term" /> ); } ``` Two details regularly get lost in code reviews. I create the `Subject` with `useRef` so that it stays stable across re-renders – if I created it anew in the render body, every render would have its own Subject, and the connection between handler and pipeline would break. And `distinctUntilChanged()` filters out identical consecutive values so that a focus change without a text change does not trigger a new run. ## The case where RxJS really shines: autocomplete with switchMap Debouncing alone does not justify RxJS yet – you can do that with a timeout too. What carries RxJS is discarding outdated requests. This is exactly where the real race condition of an autocomplete lies: I type “re,” and a request goes out. I type “rea,” and a second request goes out. If the response to “re” now arrives *after* the response to “rea,” the outdated result overwrites the current one. The UI shows hits for a search term that is no longer in the field at all. `switchMap` solves this by construction. The operator subscribes to the inner observable – here the HTTP request – and cancels the previous inner subscription as soon as a new value comes from the outside. Combined with `fromFetch` and its `AbortController`, the outdated request is not just ignored but actually aborted. ```tsx import { useEffect, useRef, useState } from 'react'; import { Subject } from 'rxjs'; import { fromFetch } from 'rxjs/fetch'; import { debounceTime, distinctUntilChanged, filter, switchMap, } from 'rxjs/operators'; type Hit = { id: string; label: string }; function Autocomplete() { const query$ = useRef(new Subject()).current; const [results, setResults] = useState([]); useEffect(() => { const subscription = query$ .pipe( debounceTime(300), distinctUntilChanged(), filter((term) => term.length > 1), switchMap((term) => fromFetch(`/api/search?q=${encodeURIComponent(term)}`).pipe( switchMap((response) => response.json() as Promise), ), ), ) .subscribe(setResults); return () => subscription.unsubscribe(); }, [query$]); return (
query$.next(event.target.value)} />
    {results.map((hit) => (
  • {hit.label}
  • ))}
); } ``` The decisive difference hinges on a single operator name. If you write `mergeMap` here out of habit, all requests keep running in parallel, and the race condition described above is back. For “only the last input counts,” `switchMap` is the right choice. The difference becomes tangible if you deliberately build the pipeline with `mergeMap` once and run it against an artificially slowed-down API: the outdated hits then visibly flash up in the list before the current result replaces them. The following diagram shows the data flow of the pipeline from input to re-render. ```mermaid flowchart LR A["Input event
onChange"] --> B["Subject.next(term)"] B --> C["debounceTime(300)
wait for a quiet period"] C --> D["distinctUntilChanged
filter duplicates"] D --> E["switchMap
discard old request"] E --> F["subscribe
setResults"] F --> G["React re-render"] ``` The cancellation semantics of `switchMap` are important because they are the core of the whole thing. The second diagram shows them as a sequence: the input “rea” cancels the still open inner stream of “re,” so that only the response to the last input lands in the state. ```mermaid sequenceDiagram participant U as User participant P as Pipeline (switchMap) participant A as API U->>P: Input "re" P->>A: Request "re" U->>P: Input "rea" Note over P: switchMap cancels
inner stream "re" P--xA: Request "re" aborted P->>A: Request "rea" A-->>P: Response "rea" P->>U: setResults (only last response) ``` ## Continuous streams: WebSockets and events The third case where RxJS pays off is sources that do not deliver a single result but keep emitting over time. WebSockets are the obvious example. With `webSocket` from `rxjs/webSocket`, RxJS comes with a bidirectional wrapper that is both an Observable and an Observer – I can subscribe to incoming messages and send my own via `next()`. The detail that is worth its weight in gold here: `unsubscribe()` closes the connection cleanly. ```tsx import { useEffect, useState } from 'react'; import { webSocket } from 'rxjs/webSocket'; type Message = { id: string; text: string }; function LiveFeed() { const [messages, setMessages] = useState([]); useEffect(() => { const socket$ = webSocket('wss://example.com/feed'); const subscription = socket$.subscribe((message) => setMessages((prev) => [...prev, message]), ); // unsubscribe closes the underlying socket return () => subscription.unsubscribe(); }, []); return (
    {messages.map((message) => (
  • {message.text}
  • ))}
); } ``` I describe the basics behind such message streams in [RxJS: Push and Pull](https://www.mikebild.dev/en/blog/rxjs-telling-push-and-pull-apart/). Bidirectional channels do not change anything about this model: sending and receiving remain two separate streams. A variant with `fromEvent` belongs here too, because it reveals a stumbling point. `fromEvent` attaches to a real DOM node, not to React’s synthetic event system. So you need a `ref`, and it is only set after mount: ```tsx import { useEffect, useRef, useState } from 'react'; import { fromEvent } from 'rxjs'; import { map, debounceTime } from 'rxjs/operators'; function ScrollTracker() { const boxRef = useRef(null); const [position, setPosition] = useState(0); useEffect(() => { const node = boxRef.current; if (!node) return; const subscription = fromEvent(node, 'scroll') .pipe( map((event) => (event.target as HTMLElement).scrollTop), debounceTime(50), ) .subscribe(setPosition); return () => subscription.unsubscribe(); }, []); return
{/* scrollable content */}
; } ``` ## The pitfall that gets everyone once: a missing unsubscribe When an RxJS React component inexplicably eats memory or throws a “setState on an unmounted component” warning, the cause is almost always the same: the cleanup function is missing or does not release the subscription. Without `unsubscribe()`, the stream keeps running after unmount. The event listener stays attached, the timer keeps ticking, the WebSocket stays open – and every emitted value calls a `setState` on a component that no longer exists. ```tsx // Wrong: no cleanup, the stream keeps running after unmount useEffect(() => { interval(1000).subscribe((n) => setTick(n)); // memory leak }, []); // Right: keep the subscription and release it in cleanup useEffect(() => { const subscription = interval(1000).subscribe((n) => setTick(n)); return () => subscription.unsubscribe(); }, []); ``` The second related mistake is more subtle: building the pipeline in the render body instead of in the effect. A `fromEvent(...).pipe(...)` that is created anew on every render produces duplicate listeners and duplicate subscriptions. The order that works reliably: keep the source stable (via `useRef` or outside the component), set up the subscription in the effect, tear it down in the cleanup, and maintain the dependency array carefully. As a side note for 2022: with `useSyncExternalStore`, React 18 brings a mechanism for binding cleanly to external stores – including RxJS-based ones. For the cases shown here, though, the `useEffect` route is entirely sufficient, and I would only reach for `useSyncExternalStore` when a store really lives outside the component and is used from several places. ## When RxJS pays off – and when it does not The most common wrong decision is pulling RxJS in everywhere. Two short lists help you avoid it. RxJS pays off when: - input has to be debounced or throttled over time before an expensive effect runs. - outdated asynchronous results should be actively discarded (autocomplete, competing requests) – the core case for `switchMap`. - continuous streams such as WebSockets, server-sent events or timers are processed. - several event and time sources have to be combined, merged or coordinated in time. RxJS does not pay off when: - it is about simple local component state – that is what `useState` and `useReducer` are for. - a single request is loaded on mount; a `fetch` with `AbortController` in the effect is enough, or you reach for a data-fetching library. - the team has not mastered RxJS and the requirement contains no real asynchronous coordination – then the learning curve does not pay off. This separation is the actual core of the post. RxJS is not a replacement for React’s state model but a complement for a narrow but important slice: coordinating asynchronous events over time. If you use observables deliberately in these few places and stick with React’s built-in tools everywhere else, you get both: declarative streams where they solve real problems, and lean components in the rest of the application. And if you consistently call `unsubscribe()` in the cleanup, you avoid the one mistake that otherwise reliably comes back. ## Further reading - [RxJS: Push and Pull](https://www.mikebild.dev/en/blog/rxjs-telling-push-and-pull-apart/) – the basics of observables as push producers. - [Observable guide (rxjs.dev)](https://rxjs.dev/guide/observable) - [Operators guide / pipe (rxjs.dev)](https://rxjs.dev/guide/operators) - [Subject (rxjs.dev)](https://rxjs.dev/guide/subject) - [switchMap (rxjs.dev)](https://rxjs.dev/api/operators/switchMap) - [debounceTime (rxjs.dev)](https://rxjs.dev/api/operators/debounceTime) - [fromEvent (rxjs.dev)](https://rxjs.dev/api/index/function/fromEvent) - [Subscription / unsubscribe (rxjs.dev)](https://rxjs.dev/guide/subscription) - [React: Using the Effect Hook (reactjs.org)](https://reactjs.org/docs/hooks-effect.html) --- # Motion, Transitions and Animations in Svelte URL: https://www.mikebild.dev/en/blog/motion-transitions-and-animations-in-svelte/ Date: 2022-09-27 A notice appears above the list, and it is simply there – abruptly, without a transition. An entry is deleted, and everything below it jumps up one line at once. In React projects, at this point at the latest, `react-transition-group` or an animation runtime lands in `package.json`. In Svelte, it takes three imports from the standard toolkit, and the dependency list stays as it was. The three modules are designed to work together and between them cover almost everything that comes up in everyday work. If you have already understood why [Svelte does without a Virtual DOM and generates code at compile time instead](https://www.mikebild.dev/en/blog/svelte-reactivity-the-compiler-instead-of-a-virtual-dom/), you can already guess where this is heading: motion is also closely woven into the compiler – it translates the directives into code that, where possible, runs the animation through CSS keyframes instead of JavaScript per frame. **Editorial note (July 2026):** The examples are written in Svelte 3 style. `svelte/transition`, `svelte/animate` and `svelte/motion` also exist in Svelte 5; what has mainly changed is the surrounding reactivity model. The old tutorial URLs have been replaced with today’s API pages. ## Three tools, three jobs Before we write code, it pays to separate things cleanly in your head. The three modules have different responsibilities, and most of the misunderstandings I have come across arise from someone reaching for the wrong tool for the wrong job. - `transition:` (from `svelte/transition`) describes how a single element enters and leaves the DOM. It is about appearing and disappearing. - `animate:` (from `svelte/animate`) describes how elements move that stay in the DOM but change their position – that is, when reordering a list. - `svelte/motion` (with `tweened` and `spring`) initially has nothing to do with the DOM at all. It is about values that interpolate smoothly from one state to the next – a number, a color, a coordinate. This three-way split is the common thread for everything that follows. As soon as it is clear whether you are making an element appear, moving it within a list or letting a value glide, the right module almost picks itself. ## Transitions: fading in and out In Svelte, you attach a transition to an element as a directive. It is triggered as soon as the element enters or leaves the DOM through control flow – an `{#if}`, an `{#each}`. That is the crucial point: I do not call an animation; the state change does. I only describe what it looks like. ```svelte {#if visible}

fades in and out

flies in from below, flies back down on exit
{/if} ``` `transition:` is bidirectional – the same motion runs forward when fading in and backward when fading out. That is often exactly right. But sometimes you want to be asymmetric: fly in, but fade out. For that, there are the separate directives `in:` and `out:`. ```svelte {#if visible}
enters flying, leaves fading
{/if} ``` The built-in selection is manageable and well coordinated: `fade`, `blur`, `fly`, `slide`, `scale`, `draw` and `crossfade`. For everyday use, the first five are almost always enough. `fly` takes `x` and `y` as numbers in pixels, `slide` opens and closes vertically, `scale` scales from a starting value. One detail only became clear to me when I looked closely: an out transition takes time, and the element stays in the DOM for that duration. Svelte removes it only when the motion has finished. So if you think an element is already gone while it is still fading out, you will be surprised by briefly duplicated entries. That is not a bug but the precondition for being able to see the disappearance at all. ## What the compiler makes of it internally The reason these transitions run without performance worries lies in how they are generated. At its core, a transition function returns a `css` function that produces a CSS string for a progress value `t` (from 0 to 1). From this function, Svelte builds real CSS keyframes. The animation thus runs through the browser’s CSS engine and does not block the main thread with JavaScript per frame. ```mermaid flowchart LR A["State change
{#if} / {#each}"] --> B["Svelte compiler"] B --> C["transition: / animate:
directive"] C --> D{"css function
available?"} D -->|yes| E["CSS keyframes
off main thread"] D -->|no| F["tick per frame
JS on main thread"] E --> G["DOM update"] F --> G ``` Only when a motion cannot be expressed purely in CSS – for example because you want to change text content per frame – does the second path kick in, via a `tick` function that actually runs in JavaScript per frame. But the default case is the performant CSS path, and you get it for free without writing keyframes yourself. ## animate:flip for lists Let’s get to the second tool. `transition:` takes care of elements that come and go. But what about elements that stay and just swap places? When I sort or shuffle a list, the entries jump hard to their new position on their own. This is exactly where `animate:flip` comes in. The name FLIP stands for “First, Last, Invert, Play” – a well-known technique in which the old and new positions of an element are compared and the difference is animated away. Svelte does this calculation for us. Only one condition matters: `animate:` works exclusively in a keyed `{#each}` block, that is, an `{#each}` with a stable key. Without this key, Svelte cannot know which element was where before. The following example brings both tools together – `transition:fly` for fading new or removed entries in and out, and `animate:flip` for smoothly reordering the ones that stay: ```svelte
    {#each items as item (item.id)}
  • {item.label}
  • {/each}
``` The key `(item.id)` is not decorative here; it carries the whole mechanism. It lets Svelte recognize the same DOM `
  • ` as the same element across the reordering and animate the difference in position. The animated element must also be a direct child of the `{#each}` block. If you put a wrapper in between instead and attach `animate:flip` to the wrong element, you simply see no motion – a classic I keep stumbling over in reviews. By the way, combining `transition` and `animate` in the same list is intentional and well coordinated: new entries fly in, removed ones fly out and stay in the DOM briefly to do so, and all the others slide smoothly into their new places. Three motions, one declarative block. ## svelte/motion: values that glide The third tool leaves the DOM aside at first. `tweened` and `spring` are stores – writable stores, as I described them in the article about [state outside the component with Svelte stores](https://www.mikebild.dev/en/blog/svelte-stores-state-outside-the-component/), with one special feature: when you set their value, they do not jump to the target immediately but interpolate toward it. In the markup, you read them like any store with the `$` prefix. `tweened` interpolates over a fixed duration and an easing function – good for anything that should follow a clear timeline, such as a progress bar. ```svelte ``` `spring`, on the other hand, does not interpolate over a duration but via physics – stiffness and damping. The result feels more alive because it bounces slightly instead of arriving at an exact point in time. For things that should feel “natural,” such as an element that follows the mouse or reacts to input, `spring` is usually the nicer choice. ```svelte
    {$size.toFixed(2)}
    ``` Two details only become apparent when you work with them. First, `.set()` and `.update()` return a promise that only resolves when the interpolation has finished – so if you want to wait for a value to have “arrived,” you can `await` it. Second, Svelte automatically interpolates numbers, arrays and objects of numbers; for other value types, such as colors in a particular notation, you give `tweened` your own interpolation function via the `interpolate` option. The `stiffness` and `damping` parameters can even be adjusted at runtime. You can bind them to sliders and experience live how the spring’s behavior changes. That is the fastest way to get a feel for what the two numbers actually do – faster, in any case, than guessing values in code and reloading. ## Writing your own transitions Perhaps the nicest proof that no black box is at work here: a transition is nothing more than a function. It gets the DOM node and its parameters and returns an object that contains, among other things, a `css` function. This function receives the progress `t` from 0 to 1 as well as the counter value `u`, which equals `1 - t`, and returns a CSS string. ```js function spin(node, { duration = 400 }) { return { duration, css: (t, u) => ` transform: rotate(${u * 360}deg) scale(${t}); opacity: ${t}; ` }; } ``` You can use this custom transition exactly like the built-in ones: ```svelte {#if visible}
    spins into view
    {/if} ``` Once you have written this, the rest demystifies itself. `fade`, `fly` and `scale` are exactly such functions – they just live in the library. There is no second, hidden mechanism. This consistency is exactly what I appreciate so much about Svelte’s motion model: from the ready-made one-liner to your own function, it is one continuous concept, not a break. To put it in context, here are the three tools compared directly once more, so the mapping sticks for good: - `transition:` / `in:` / `out:` – for the appearing and disappearing of individual elements, triggered by `{#if}` or `{#each}`. - `animate:flip` – for elements that stay in the DOM and only swap positions in a keyed `{#each}`. - `tweened` / `spring` from `svelte/motion` – for interpolated values that you read as a store with `$` and bind into the markup. ## Conclusion In Svelte, motion is not an extra decision you retrofit later with a library; it is part of the language. That changes how you approach the topic. Instead of asking “Which package do I use?”, you ask “Is something appearing here, is something moving, or is a value gliding?” – and the answer leads directly to `transition:`, `animate:flip` or `svelte/motion`. The common denominator is the declarative approach: I describe what a motion looks like, and the compiler makes sure it is triggered when the state changes and that it runs performantly via CSS keyframes where possible. Because custom transitions are the same simple functions as the built-in ones, the whole thing can be learned right down to the bottom. For everyday project work, this means: fewer dependencies, less boilerplate and more time for the question of which motion really makes a UI easier to understand – instead of the question of which framework makes it possible at all. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-svelte.en.html - Repository for the article series with the runnable Svelte examples - [`svelte/transition` – official documentation](https://svelte.dev/docs/svelte/svelte-transition) - [`svelte/animate` – official documentation](https://svelte.dev/docs/svelte/svelte-animate) - [`svelte/motion` – official documentation](https://svelte.dev/docs/svelte/svelte-motion) --- # Buffers in Node.js: Working with Binary Data URL: https://www.mikebild.dev/en/blog/buffers-in-nodejs-working-with-binary-data/ Date: 2022-08-09 A `Buffer` isn’t a broken string. If `` shows up in the console after reading a file, nothing went wrong: Node shows exactly what’s in the file – a sequence of bytes that has no meaning as text and isn’t supposed to get one. In Node, such bytes come from many directions: from `fs`, from open network connections, from `crypto`. The `Buffer` is the type Node holds them in. What makes it interesting are mainly the places where it behaves differently from what you’re used to with strings and arrays – when creating it and when splitting it up. ## Why strings aren’t enough here A JavaScript string is a sequence of Unicode characters, not a sequence of bytes. That sounds like hair-splitting, but it’s the core of the problem. As soon as I have a string, the runtime has already made an interpretation: these bytes are text, in a specific encoding. But raw binary data – a PNG header, a compressed block, a cryptographic key – has no meaning as text at all. If I force it through a string, I lose or corrupt bytes, because invalid byte sequences get replaced with replacement characters. Often this is only noticed late, for example when an uploaded file arrives damaged at the other end. Node solves this with `Buffer`: a region of fixed byte length that contains exactly the bytes you put into it, without any reinterpretation. One detail is crucial here and explains a lot: a `Buffer` is a subclass of `Uint8Array`, so it’s a TypedArray itself. Everything you know from `Uint8Array` – index access, `length`, `for` loops, the TypedArray methods – works on a Buffer too. `Buffer` merely adds the extras that are practical for Node, first and foremost the encodings. ```js const fs = require('node:fs'); const data = fs.readFileSync('image.png'); console.log(Buffer.isBuffer(data)); // true console.log(data instanceof Uint8Array); // true console.log(data.length); // number of bytes console.log(data.subarray(0, 8)); // ``` By the way, the first eight bytes are the fixed signature of a PNG file. In practice, you read exactly such headers to detect file types without relying on the extension. ## Creating a buffer: alloc, allocUnsafe, from There are three ways to get a Buffer, and the differences matter – for security reasons too. - `Buffer.alloc(size)` reserves `size` bytes and sets them all to `0`. Optionally, you pass a fill byte and an encoding. This is the safe default when you need an empty buffer of a certain size. - `Buffer.allocUnsafe(size)` also reserves `size` bytes but doesn’t initialize them. The content is old memory – whatever was there before is still there. In return, creating it is measurably faster, because zeroing is skipped and the memory may come from an internal pool. - `Buffer.from(...)` creates a buffer from existing data: from a string (with an encoding), from an array of byte values, from another buffer (copied) or from an `ArrayBuffer`. The difference between the first two isn’t a detail. `allocUnsafe` returns memory that may contain leftovers from earlier allocations – possibly data from completely different parts of the program. ```js const zeroed = Buffer.alloc(8); console.log(zeroed); // const uninitialized = Buffer.allocUnsafe(8); console.log(uninitialized); // old memory ``` That’s why `alloc` is the default; `allocUnsafe` is only worth it where the buffer is completely overwritten right afterward anyway. If you use `allocUnsafe` and only partially fill the memory, you must never output or send the rest, because sensitive data may be in there. That’s the first of the two classic traps, and it’s treacherous because it never shows up in a local test – in a freshly started process, the memory often happens to be zeroed. Only under load, when the pool is reused, do the data leftovers appear. As an aside, because it still haunts old code: the former `new Buffer(...)` call has been deprecated at runtime since Node 10 (DEP0005) and shouldn’t be used anymore. And `Buffer.from(10)` doesn’t create a buffer of size 10 but throws a `TypeError` – a number isn’t a valid argument for `Buffer.from`. If you mean a size, use `alloc` or `allocUnsafe`. ## Encodings: the same bytes, different glasses The second big benefit of `Buffer` over a bare `Uint8Array` is the encodings. An encoding isn’t a conversion of the bytes but a rule for how to read the same bytes as text or how to break text down into bytes. The round trip between the two sides looks like this: ```mermaid graph LR S["String
    (Unicode text)"] -->|"Buffer.from(str, enc)"| B["Buffer
    (raw bytes)"] B -->|"buf.toString(enc)"| S B -->|"buf.toString('hex')"| H["Hex text"] B -->|"buf.toString('base64')"| B64["Base64 text"] ``` When writing in with `Buffer.from(str, enc)`, I say: break this text down into bytes according to this rule. When reading out with `buf.toString(enc)`, I say: interpret these bytes as text according to this rule. What matters is that both sides mean the same encoding, otherwise you get nonsense. The common encodings fall into two groups. The first describe text to bytes: `utf8` (the default), `utf16le`, `latin1` (also called `binary`) and `ascii`. The others are byte-to-text representations that make arbitrary binary data printable: `hex`, `base64` and `base64url`. You need `hex` and `base64` in particular all the time, for example to make a hash readable or to transport binary data in JSON. ```js const buf = Buffer.from('Grüße', 'utf8'); console.log(buf.length); // 7 bytes, not 5 console.log('Grüße'.length); // 5 characters console.log(buf.toString('hex')); // 4772c3bcc39f65 byte view as hex console.log(buf.toString('base64')); // R3LDvMOfZQ== byte view as base64 const b64 = buf.toString('base64'); const back = Buffer.from(b64, 'base64').toString('utf8'); console.log(back); // 'Grüße' again ``` The interesting point is in the first two lines: the string has five characters, but the buffer has seven bytes. The ü and the ß each take up two bytes in UTF-8. Bytes and characters simply aren’t the same thing, and if you mix up `length`, you calculate offsets wrong. In practice, a related problem arises from exactly this: with streams, a multibyte character can be cut apart at the point where one data chunk ends and the next begins. For clean decoding across such chunk boundaries, there is the `string_decoder`, which buffers half characters in between – but that’s a topic of its own, covered in more detail in the post [Node.js streams and backpressure](https://www.mikebild.dev/en/blog/nodejs-streams-understanding-backpressure/). ## Numbers as bytes: byte order Encodings take care of text. But as soon as you take apart a binary format – a file header, a network protocol, a frame – it’s about numbers spread across several bytes. For this, `Buffer` comes with a series of read and write methods that interpret a fixed number of bytes at an offset as an integer: `readUInt8`, `readUInt16BE`, `readUInt32LE`, plus the signed variants and, for 64 bits, the `BigInt` versions such as `readBigUInt64BE`. The counterpart for writing is called `writeUInt32BE` and so on. The suffix at the end is where many people stumble: `BE` stands for big-endian, `LE` for little-endian – that is, for the question of whether the most significant byte comes first or last. If you pick a different order when reading than the writer used, you get a completely different number, without any error being thrown. Network protocols are traditionally big-endian, and many file formats define their own order; so you have to look it up in the respective format and must not guess. ```js const buf = Buffer.alloc(4); buf.writeUInt32BE(0x89504e47, 0); // PNG signature bytes as one number console.log(buf); // console.log(buf.readUInt32BE(0).toString(16)); // 89504e47 console.log(buf.readUInt32LE(0).toString(16)); // 474e5089, reversed bytes ``` The same four bytes produce two different numbers depending on the chosen order. The buffer itself doesn’t know what’s right – the meaning lies in the format, not in the bytes. ## The memory trap: slice and subarray share memory Now to the second big trap, and it snaps shut especially often because arrays behave differently. When you call `slice` on an ordinary JavaScript array, you get a copy. With a buffer, it’s different: `buf.subarray(start, end)` and the older `buf.slice(start, end)` both create no copy but a view onto the same underlying memory. If you write into the view, you change the original too. ```mermaid graph TD M["Byte block in memory
    [1, 2, 3, 4, 5]"] O["original
    (whole block)"] --> M V["view = original.subarray(1, 3)
    (bytes 1 and 2)"] --> M ``` Both names, `original` and `view`, point to the same memory. A write through one is visible through the other. ```js const original = Buffer.from([1, 2, 3, 4, 5]); const view = original.subarray(1, 3); // shares memory, no copy view[0] = 99; console.log(view); // console.log(original); // byte 1 changed too! ``` The byte at position 1 in the original has changed, even though I seemingly only wrote into `view`. In a function that returns a partial buffer which the caller then modifies, this leads to bugs that are hard to find, because cause and effect sit in completely different places in the code. If you need an independent copy, you have to create it explicitly – for example with `Buffer.from` over the view or with `buf.copy` into a freshly reserved target buffer. ```js const original = Buffer.from([1, 2, 3, 4, 5]); const copy = Buffer.from(original.subarray(1, 3)); // independent copy copy[0] = 99; console.log(copy); // console.log(original); // untouched ``` On the naming question, because it comes up often: the Node documentation now recommends `subarray`. The name `slice` only still exists on buffers for compatibility reasons and deliberately differs from the behavior of `TypedArray.prototype.slice`, which returns a copy. This inconsistency grew historically and is a common source of confusion. I recommend consistently writing `subarray` for buffers – then anyone reading the code immediately knows that memory is shared here and no copy is created. ## Where buffers show up in everyday work You rarely create buffers by hand; usually the platform hands them to you. The `fs` module returns a buffer when reading without an encoding. Streams deliver their data in buffer chunks unless you configure them as text. The `net` network module passes received packets on as buffers. And `crypto` works with buffers almost throughout – a hash, for example, is created as a buffer that you then make readable with `toString('hex')`. ```js const crypto = require('node:crypto'); const hash = crypto.createHash('sha256') .update('hello world') // accepts string or Buffer .digest(); // returns a Buffer console.log(Buffer.isBuffer(hash)); // true console.log(hash.toString('hex')); // b94d27b9934d3e08a52e52d7da7dabfa... ``` Here you can see the two roles of the buffer nicely together: `update` accepts text or bytes, `digest` returns raw bytes, and `toString('hex')` makes those bytes readable for logs and comparisons. If you want to understand which execution model these inputs and outputs run in and why that doesn’t block, you’ll find the background in the post [Node.js Training](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/) on event loop architecture. ## What sticks Three things go a long way. First: a buffer is a `Uint8Array` with Node extras – if you keep that in mind, you immediately understand index access and length and don’t expect any string magic. Second: `alloc` is the safe default, `allocUnsafe` a deliberate compromise for cases where you overwrite the memory completely anyway; anything else risks exposing old data. Third: `subarray` and `slice` share memory and don’t copy – if you need an independent version, copy by hand. The two traps – uninitialized memory from `allocUnsafe` and the shared view from `subarray` – have one thing in common: they don’t show up in a quick test and only strike later or under load. That’s exactly why it pays to play through the behavior deliberately once instead of leaving it to chance. File access, networking and cryptography in Node run on raw bytes; once you have understood the buffer, you read their output in the console as what it is: a representation of the data without any reinterpretation. ## Further reading - [Node.js Training: Event Loop architecture](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/) - [Node.js streams and backpressure](https://www.mikebild.dev/en/blog/nodejs-streams-understanding-backpressure/) - [Node.js documentation: Buffer](https://nodejs.org/api/buffer.html) - [Buffer.alloc(size, fill, encoding)](https://nodejs.org/api/buffer.html#static-method-bufferallocsize-fill-encoding) - [Buffer.allocUnsafe(size)](https://nodejs.org/api/buffer.html#static-method-bufferallocunsafesize) - [Buffers and character encodings](https://nodejs.org/api/buffer.html#buffers-and-character-encodings) - [buf.slice() – legacy note, prefer subarray](https://nodejs.org/api/buffer.html#bufslicestart-end) - [MDN: Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) --- # Svelte Stores: State Outside the Component URL: https://www.mikebild.dev/en/blog/svelte-stores-state-outside-the-component/ Date: 2022-07-19 If you install a state management library before the ownership question is settled, you have already paid the price: an extra dependency, a second mental model, and boilerplate – for a problem your project may not even have. The trigger is usually harmless. Two components that aren’t directly related need to share a value; reactivity inside a component works beautifully, but there is no mechanism across the component boundary. From the React world, you know the move of reaching for the big library, and it happens by reflex, even though the real question isn’t an API question: who owns this state, and how much machinery is it allowed to cost? Svelte already ships with a tool for this case that consists of barely a handful of functions – stores. They answer the ownership question with the smallest possible means and let the cost rise only when a concrete problem forces it. The real gain lies less in the functions themselves than in the discipline they allow: start small and draw the line to “more” deliberately instead of crossing it by reflex. A store is state that lives outside the component. It doesn’t belong to any single `.svelte` file but sits in a separate module and can be subscribed to from anywhere. That solves a problem that quickly becomes annoying in component trees: passing values down through several levels just so a deeply nested child can get hold of a piece of information. If you have read my article on [Svelte reactivity](https://www.mikebild.dev/en/blog/svelte-reactivity-the-compiler-instead-of-a-virtual-dom/), you already know the foundation: the compiler builds reactivity in at build time, without a virtual DOM. Stores are the logical continuation of that idea for state that has to cross the component boundary. **Editorial note (July 2026):** This text uses the store model of Svelte 3/4. Stores are still supported in Svelte 5 and are especially useful for asynchronous streams or manually controlled subscriptions. For shared state, though, a `.svelte.js` or `.svelte.ts` file with runes can be enough today; stores are no longer the only built-in answer outside a component. ## The ownership question comes before the tool question Before I get to the concrete Svelte functions, one principle that has nothing to do with Svelte itself and applies to every component-based frontend – React, Vue, or Svelte. I derived it in detail for React elsewhere, in the [state management comparison](https://www.mikebild.dev/en/blog/state-management-in-react/), and the core carries over one to one: the deciding question is not “which state library” but “who owns this state?” State belongs at the lowest point where everyone involved can still reach it. As long as that is a single component, it stays there – local, without any ceremony. Only when several unrelated components share the same value, or the value comes from outside the tree, does it leave the component. A global or module-wide store is therefore the exception you justify, not the default you fall into. Why I stress this so much is a cost argument. Every level I lift state to makes it more expensive: more places that are allowed to write, changes that are harder to trace, a larger surface for bugs. In projects, I have gone the opposite way often enough – first the big library is chosen, then state gets pushed into it until everything is global. The counter-check goes the other way: does this value really need several components, and are they so decoupled that a shared parent component wouldn’t connect them anyway? In my experience, after asking this question, far less global state remains than initially assumed. To decide whether a value should leave the component, I use three criteria. Reach: do at least two components share it that aren’t in a clean parent-child relationship? Origin: is the value written from outside the tree – a timer, a WebSocket, a sensor? And lifetime: does it have to exist regardless of whether a particular component is currently mounted? If none of these applies, the state stays local, and any solution above that is paid-for complexity with nothing in return. If one applies, a lean, module-wide store is the right answer – in Svelte, literally one line of code. The real work lies in the decision before, not in the API after. ## The contract, not the class In Svelte, a store is not a special type and not a class you have to inherit from. A store is any object that provides a `.subscribe` method according to a fixed contract – and optionally a `.set` method if it should be writable. `subscribe` must deliver the current value to the subscriber synchronously and return a function for unsubscribing. That contract is what counts. Anything that fulfills it works with the `$` syntax. In practice, you almost never write this `.subscribe` method yourself. Svelte ships three factory functions that do the work for you. They all come from the same module: ```js import { writable, readable, derived, get } from 'svelte/store'; ``` The three store types cover three different roles: - `writable` – readable and writable. The default case for shared state that any component or function may change. Provides `.set(value)`, `.update(fn)`, and `.subscribe(run)`. - `readable` – read-only from the outside. The value is set internally via a start callback, ideal for external sources such as a clock, a WebSocket, or an event listener. - `derived` – derived. Computes its value reactively from one or more other stores and updates automatically when one of its sources changes. ## The writable store and the $ shorthand Let’s start with the most common case – a shared counter that several components use. The store lives in its own module so that every component can import it: ```js // stores.js import { writable } from 'svelte/store'; export const count = writable(0); ``` That is the complete store. One module, one line, one initial value. Now any component can read and write this counter – and this is where Svelte’s most elegant idea comes into play, the `$` shorthand: ```svelte ``` The `$count` in the template is not a magic global variable but an instruction to the compiler. It recognizes the `$` prefix in front of a store reference and generates two things from it: first, a `count.subscribe(...)` that writes the current value into a local variable and re-renders the template on every change; second – and this is the crucial part – an automatic `unsubscribe` as soon as the component is destroyed. So you don’t have to take care of cleanup; the compiler does it for you. Writing is covered by the shorthand, too. The compiler translates `$count++` into a `count.set(...)` call with the incremented value. If you prefer to be more explicit or need a more complex change, you use the methods directly: ```svelte

    Current value: {$count}

    ``` The difference between `set` and `update` is quickly explained. `set` overwrites the value unconditionally, `update` receives the current value as an argument and returns the new one – handy whenever the new value depends on the old one. And now the core of it all: as soon as a second component imports the same store and uses `$count`, both share the same state. If one changes the value, the other sees it immediately. No prop is passed down the tree, no shared parent component has to hold the state. The store is the shared source that everyone involved hangs on. ```mermaid graph TD S["writable count
    (stores.js)"] A["Component A
    read + write $count"] B["Component B
    display $count"] C["Component C
    display $count"] S --> A S --> B S --> C A -. "count.set()" .-> S ``` You can see clearly here what the store does: it decouples the components from each other. A, B, and C don’t have to be related or know about each other. They only know the store. ## Derived state with derived Often you need a value that follows from another one. You could recompute it in every component – or you derive it once, centrally, and everyone benefits. That is exactly what `derived` is for: ```js // stores.js import { writable, derived } from 'svelte/store'; export const count = writable(0); export const doubled = derived(count, $count => $count * 2); ``` `doubled` is itself a store again, but a read-only one. It has no `.set` method, because its value follows entirely from `count`. When `count` changes, `derived` recomputes the value and notifies its subscribers. In the component, it then looks just like a regular store: ```svelte

    {$count} doubled is {$doubled}

    ``` `derived` can also derive from several sources. In that case, you pass an array of stores and get an array of values in the callback: ```js import { writable, derived } from 'svelte/store'; export const price = writable(100); export const quantity = writable(2); export const total = derived( [price, quantity], ([$price, $quantity]) => $price * $quantity ); ``` Besides this synchronous form, there is a second one that receives a `set` callback. With it, you can set the derived value with a delay or conditionally – for example after a timeout or only once a certain condition is met: ```js import { derived } from 'svelte/store'; // Sets the value one second after each change of 'count' export const delayed = derived( count, ($count, set) => { const id = setTimeout(() => set($count), 1000); return () => clearTimeout(id); } ); ``` The return value of the callback function here is a cleanup function that Svelte runs before the next computation and on the last unsubscribe. That way, no timeout is left hanging. ## readable for external sources Not all state is written by the application itself. Sometimes it comes from outside – a clock that ticks, a WebSocket that delivers messages, a sensor. For cases like these, there is `readable`. From the outside, you can only read it; what feeds it is a start callback that sets up the source: ```js import { readable } from 'svelte/store'; export const time = readable(null, set => { const id = setInterval(() => set(new Date()), 1000); return () => clearInterval(id); }); ``` The timing is worth a close look here, because it reveals a central principle of stores. The start callback doesn’t run immediately when the store is created. It only runs when the first subscriber arrives – when the number of subscribers jumps from zero to one. And the returned function – the stop part – runs when the last subscriber leaves, that is, from one to zero. As long as nobody is listening, no interval ticks and no socket opens for this `readable`. With `writable`, `set` and `update` stay effective even without subscribers; only an optional start/stop piece of work is lazy. `derived`, in turn, computes for its subscribers and unsubscribes from its sources when there are none. In the component, handling it is trivial again, because `$time` subscribes automatically and cleans up on unmount: ```svelte

    The time is {$time?.toLocaleTimeString()}

    ``` ## The pitfall: subscribe without unsubscribe So far, everything ran through the `$` shorthand, and there, cleanup is not an issue. But stores aren’t limited to components. You can use them just as well in a plain JavaScript module – in a utility function, a service, anywhere outside of Svelte. And that is exactly where the most common mistake lurks. Outside a component, there is no `$` and no compiler that cleans up. You call `subscribe` by hand, and the method returns an unsubscribe function. You **must** keep this function and call it, or you have a leak: ```js // utils.js import { count } from './stores.js'; // WRONG: the callback runs forever. count.subscribe(value => { console.log('count is now', value); }); ``` The return value of `subscribe` is simply ignored here. As long as the module or this usage context lives, the callback stays registered. The store keeps counting one subscriber, the 1→0 stop callback is never triggered – with a `readable` that has an interval, the timer would keep running accordingly. This is the right way: ```js // utils.js import { count } from './stores.js'; const unsubscribe = count.subscribe(value => { console.log('count is now', value); }); // ... later, when no longer needed: unsubscribe(); ``` The same rule applies within components, too, if for some reason you use `subscribe` manually there instead of `$`: then you have to call the unsubscriber in `onDestroy`. But honestly, that is almost always a sign that you should simply have used the `$` syntax. That bookkeeping is exactly what it takes off your hands. If you want to read the value only once – without a subscription, without reactivity – there is a clean way that doesn’t let the leak problem arise in the first place: ```js import { get } from 'svelte/store'; import { count } from './stores.js'; const current = get(count); ``` `get` subscribes briefly under the hood, reads the current value, and unsubscribes right away. The value is a snapshot and doesn’t update anymore. That is exactly why `get` fits well for a one-time read in a JS module – and precisely not in a hot path that runs constantly. ```mermaid sequenceDiagram participant C as First subscriber participant S as Store participant Q as External source C->>S: subscribe(run) S->>Q: start callback (0 -> 1) Q-->>S: Values flow S-->>C: run(value) C->>S: unsubscribe() S->>Q: stop callback (1 -> 0) ``` ## When to use a store, and when not The store is the right tool as soon as state no longer fits cleanly into a single component – when several components that aren’t directly related share the same value, or when a value comes from outside the component tree. The classic symptom that calls for a store is prop drilling: you pass a value through three or four levels even though only the bottom component really needs it. A store cuts off this pass-through path. The affected components import the store directly, and the intermediate levels don’t need to know anything about the value. That leaves the question of whether you also need a big state management library. For the vast majority of Svelte applications: no. The three store types cover a surprising amount. `writable` for the state you change, `derived` for everything that follows from it, `readable` for external sources. That is no compromise, no “good enough for now” – for most real applications, it is simply sufficient. A central store module that exports the individual stores gives the application a clear, manageable structure without you having to drag along another mental model and another dependency. So where is the edge beyond which you think about more? I would say: only when the state gets truly complex – many interdependent transitions, strict traceability of every change, sophisticated time-travel debugging across a large domain. Requirements like these are rare, and even then you often build a thin layer on top of stores instead of replacing them. But as long as the question is just “How do my components share a value?”, the answer is a store – and you don’t need more. What remains after several projects with Svelte is less an API recommendation than an order: first determine the owner of the state, then the tool. For the model shown in 2022, `writable`, `readable`, and `derived` are often enough. The `$` shorthand handles the subscription bookkeeping in components; outside them, the simple rule remains to pair every manual `subscribe` with an `unsubscribe`. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-svelte.en.html - Repository: [mikebild.dev](https://www.mikebild.dev) – this and other articles on Svelte and frontend architecture - [Svelte Reactivity: The Compiler Instead of a Virtual DOM](https://www.mikebild.dev/en/blog/svelte-reactivity-the-compiler-instead-of-a-virtual-dom/) - [Svelte docs – stores and runes](https://svelte.dev/docs/svelte/stores) --- # Node.js Streams: Understanding and Using Backpressure URL: https://www.mikebild.dev/en/blog/nodejs-streams-understanding-backpressure/ Date: 2022-06-21 ``` FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory ``` This crash does not come from processing too much data. It comes from data arriving too fast. A source reads a log file from a fast SSD, every chunk goes via `write()` to a slow destination – and because nobody looks at what `write()` returns, the internal buffer grows until the heap is full. The amount of data does not matter; what matters is the speed gap between the two ends. Many people think of streams as file stuff around `createReadStream`. But they are the fundamental model of how Node.js pushes data piece by piece through a pipeline without ever holding everything in memory at once. The part of it that decides in real systems between “runs stable” and “process dies at three in the morning” is called backpressure. The stream API looks harmless: you chain a few `pipe` calls, and it works – until the day the source delivers faster than the destination can swallow. ## Why streams at all The classic way to process a file is `fs.readFile`. The function reads the entire file into a buffer and then calls the callback. For a 2 MB configuration file, that is perfectly fine. For a 4 GB log file, you have a problem: Node.js tries to load four gigabytes into the heap, and the process falls over long before a single line has been processed. A stream does it differently. It reads the file in small bites – chunks – and passes each chunk on individually. At any point in time, only a small buffer sits in memory, regardless of whether the file is two megabytes or two terabytes. Memory consumption stays constant. That is the core benefit, and it applies not only to files: HTTP requests, TCP sockets, compression, encryption – all of these are streams in Node.js. ## The four types Before we get to flow control, an overview of the four stream types is worthwhile. All four inherit from `EventEmitter`, so they communicate through events – that is the common thread running through the entire asynchronous side of Node.js, which I describe in more detail in [Node.js Training: From the Event Loop to Architecture Decisions](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/). - A Readable is a source you read from. `fs.createReadStream()` returns a Readable, as does the incoming body of an HTTP request. - A Writable is a destination you write to. `fs.createWriteStream()` or the HTTP response are Writables. - A Duplex is readable and writable at the same time, but with separate channels. A `net.Socket` is the prime example: in and out over the same connection. - A Transform is a Duplex whose output is a function of its input. `zlib.createGzip()` takes raw bytes in and puts compressed ones out. This is exactly where you add your own processing logic. You combine these types into a pipeline: a source, any number of Transforms in the middle, a destination at the end. ```mermaid flowchart LR A["Readable
    fs.createReadStream"] -->|chunks| B["Transform
    gzip / uppercase"] B -->|chunks| C["Writable
    fs.createWriteStream"] C -.->|drain signal| A style A fill:#2b6cb0,color:#fff style B fill:#2f855a,color:#fff style C fill:#c05621,color:#fff ``` The solid arrows are the forward data flow. The dashed arrow going back is the decisive one – it is backpressure. More on that in a moment. ## The naive approach and why it tips over Suppose we want to copy a large file into another one and process each chunk along the way. The intuitive code looks like this: ```js const fs = require('node:fs'); const source = fs.createReadStream('huge-input.log'); const target = fs.createWriteStream('huge-output.log'); source.on('data', (chunk) => { target.write(chunk); }); ``` That runs. Most of the time. And then comes the case where `huge-input.log` comes from a fast SSD and `huge-output.log` is written to a slow network drive. The source fires `data` events as fast as it can, and `target.write()` accepts every chunk. If the destination cannot write fast enough, Node.js buffers the chunks internally – and this buffer has no upper limit. Memory fills up, `RSS` climbs, the garbage collector works against an ever-growing pile, and at some point the operating system kills the process. That is the pitfall in one sentence: **If you ignore the return value of `write()` and just keep writing, you produce unlimited buffering.** ## What write() actually tells you `writable.write(chunk)` returns a Boolean, and this Boolean is half the battle: - `true` means: the internal buffer is still below `highWaterMark`; you may keep writing. - `false` means: the buffer has reached or exceeded `highWaterMark`. Stop writing, or Node.js will buffer into the void. `highWaterMark` is the buffer limit. In the Node 16/18 covered here, the general default for byte streams was 16384 bytes, that is 16 KiB; since Node 22 it is 64 KiB. In object mode – more on that later – the default stays at 16 objects. It is important to understand: this limit is a **threshold, not a hard wall**. Node.js does not stop buffering when you exceed `highWaterMark`. It just politely tells you with a `false` return value that it has had enough. If you ignore the warning, it keeps buffering anyway – at your own risk. Once `write()` has returned `false`, you should pause and wait for the `'drain'` event. The Writable emits `'drain'` as soon as its buffer has been emptied again – the signal that you may continue writing. Done by hand, the correct cycle looks like this: ```js source.on('data', (chunk) => { const ok = target.write(chunk); if (!ok) { source.pause(); target.once('drain', () => source.resume()); } }); ``` We write, check the return value, pause the source on `false` and resume it only after `'drain'`. That is exactly flow control: a fast producer is slowed down so that it does not overrun a slow consumer. You can also draw the cycle as a state machine: ```mermaid stateDiagram-v2 [*] --> Schreiben Schreiben --> Schreiben: write() returns true Schreiben --> Pausiert: write() returns false
    source.pause() Pausiert --> Schreiben: 'drain' event
    source.resume() ``` ## pipe does this automatically The good news: in practice, you rarely have to write this whole `pause`/`resume` dance by hand. `pipe()` does exactly that in the background. ```js const fs = require('node:fs'); fs.createReadStream('huge-input.log') .pipe(fs.createWriteStream('huge-output.log')); ``` `pipe()` connects source and destination, checks the return value of `write()` internally, pauses the Readable on backpressure and resumes it after `'drain'`. So backpressure is solved without you writing a single line of flow control yourself. `pipe()` also returns the destination so that you can chain – handy when a Transform sits in between: ```js const fs = require('node:fs'); const zlib = require('node:zlib'); fs.createReadStream('huge-input.log') .pipe(zlib.createGzip()) .pipe(fs.createWriteStream('huge-input.log.gz')); ``` And yet I advise against just chaining `pipe()` in production. The reason is error handling. ## Why pipeline is the better choice `pipe()` has a treacherous weakness: it does not propagate errors. If a stage in the middle of the chain throws an error – the network connection drops, the disk is full – a `pipe()` chain does not notice it cleanly. The other streams are not destroyed, file descriptors stay open, the stream hangs. In a long-running server process, such leaks accumulate until the resources eventually run out. `stream.pipeline()` solves this. It chains the stages the same way, but it propagates errors across all stages and calls `destroy()` on every stream involved on error or regular end. Nothing leaks. There is the callback variant: ```js const fs = require('node:fs'); const zlib = require('node:zlib'); const { pipeline } = require('node:stream'); pipeline( fs.createReadStream('huge-input.log'), zlib.createGzip(), fs.createWriteStream('huge-input.log.gz'), (err) => { if (err) { console.error('pipeline failed', err); return; } console.log('pipeline succeeded'); } ); ``` Since Node.js 15 – and thus firmly established in the release lines 16 and 18 that are current in 2022 – there is also a promises variant from `node:stream/promises`. It reads much more cleanly in async functions because you catch errors with try/catch: ```js const fs = require('node:fs'); const zlib = require('node:zlib'); const { pipeline } = require('node:stream/promises'); async function compress() { try { await pipeline( fs.createReadStream('huge-input.log'), zlib.createGzip(), fs.createWriteStream('huge-input.log.gz') ); console.log('done'); } catch (err) { console.error('pipeline failed', err); } } compress(); ``` The promises variant also takes options, such as a `signal` for an `AbortSignal` that lets you abort the pipeline from the outside. The point that tips the scales for me: `pipeline()` handles backpressure just as automatically as `pipe()` – but it also cleans up. For production code, `pipeline()` is the default choice; `pipe()` at most for short, isolated scripts. ## Writing your own Transform The point where streams become really useful is your own Transform in the middle. A Transform takes chunks in, processes them and pushes the result out. The skeleton consists of a `transform` function that receives three things: the chunk, the encoding and a callback you have to call at the end. ```js const { Transform } = require('node:stream'); const upperCase = new Transform({ transform(chunk, encoding, callback) { const transformed = chunk.toString().toUpperCase(); this.push(transformed); callback(); } }); ``` `this.push()` passes the result on to the next stage; `callback()` signals that this chunk has been fully processed. If you call `callback()` with an error – `callback(err)` – `pipeline()` propagates this error cleanly through the entire chain. Built into a pipeline, it looks like this: ```js const fs = require('node:fs'); const { pipeline } = require('node:stream/promises'); await pipeline( fs.createReadStream('input.txt'), upperCase, fs.createWriteStream('output.txt') ); ``` And because the `upperCase` Transform takes part in flow control like any stream, backpressure applies here too: if the destination is slow, the pipeline slows down across the Transform back to the source. You do not have to do anything extra for that. ## Async iteration as a modern alternative Since Node.js 10, every Readable implements `Symbol.asyncIterator`, so you can consume it directly with `for await ... of`. In async functions, this often reads more clearly than `on('data')` and keeps flow control intact without you having to touch `pause` and `resume`. ```js const fs = require('node:fs'); async function countLines(path) { const stream = fs.createReadStream(path, { encoding: 'utf8' }); let lines = 0; for await (const chunk of stream) { lines += chunk.split('\n').length - 1; } return lines; } ``` Backpressure arises implicitly here: as long as the loop body is busy with a chunk – and an `await` inside it holds it up further – the loop does not request a new chunk, and the Readable only delivers the next one then on its own. So you get the same brake as with `pipe()`, just in ordinary async/await code. The rule that comes up next still applies: if you iterate like this, you should not also consume the stream in parallel via `on('data')`. ## Object mode and a few rules By default, streams work with buffers and strings. If you set `objectMode: true`, the chunks may be arbitrary JavaScript objects – useful when you build a pipeline of parsed records instead of raw bytes. Note that in object mode, `highWaterMark` counts the number of objects, not bytes; the default is 16 objects. And an existing stream cannot be safely switched to object mode afterward – you decide that at construction. A rule that keeps snagging in reviews: do not mix consumption methods. Per Readable, you choose exactly one way of reading – either `on('data')`, or `on('readable')`, or `pipe()`, or async iteration. If you combine two of them, you produce race conditions, lost chunks and bugs that are hard to reproduce. One Readable, one consumption method. ## What should stick Streams are the tool for processing arbitrarily large amounts of data with constant memory – the buffer stays small no matter how large the source is. Backpressure is the mechanism that makes this work: the return value of `write()` and the `'drain'` event form the flow control that keeps a fast producer from overrunning a slow consumer. `highWaterMark` is the threshold at which `write()` flips from `true` to `false` – a warning, not a constraint. You rarely have to write this cycle by hand, because `pipe()` and above all `pipeline()` handle it automatically. The decisive difference lies in error handling: `pipeline()` propagates errors and cleans up all streams; `pipe()` does not. With this difference in mind, you get Node.js processing code that does not fall over even with four gigabytes and a slow destination – it just gets a bit slower, the way it should. ## Further reading - Repository for the Node.js introduction: [mikebild/introduction-nodejs](https://github.com/mikebild/introduction-nodejs) – teaching material on async patterns including `10-streams.md`. - [Node.js Stream API (v18)](https://nodejs.org/docs/latest-v18.x/api/stream.html) – Readable, Writable, Duplex, Transform, `pipe`, `pipeline`, `write`, `drain`, `highWaterMark`. - [Current Node.js Stream API – today’s defaults](https://nodejs.org/api/stream.html) - [stream.pipeline in the official docs](https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-callback) - [Guide: Backpressuring in Streams](https://nodejs.org/learn/modules/backpressuring-in-streams) --- # Fitness Functions: Checking Selected Architecture Properties URL: https://www.mikebild.dev/en/blog/fitness-functions-checking-architecture-properties/ Date: 2022-05-24 A fitness function is not a complete quality model. It evaluates one specific architecture property that can be operationalized – such as freedom from cycles, coupling, latency or compatibility between two services. In this post, I focus on automated checks that are as unambiguous as possible and deliver a narrowly scoped verdict on every commit. Properties such as understandability or domain appropriateness still need human judgment. How big the difference from common practice is shows in a sentence that comes up regularly in architecture reviews: “Of course the domain must not access the infrastructure.” Everyone nods. A diagram gets drawn, maybe a Confluence entry created. Three sprints later, an import statement points from the domain layer straight into the database adapter. No one did it maliciously. It was Friday afternoon, the bugfix had to go out, and the rule simply wasn’t in the code but in meeting minutes that no one reads anymore. Where an architecture property can be checked unambiguously, an automatic check is more reliable than memory in a review. A fitness function closes the path from a desired property to a repeatable decision. :::process{title="From architecture statement to gate" role="primary" preferredPattern="connected-process"} 1. Property · name an architecture quality that matters to the domain 2. Observation · pick a reproducible signal for it 3. Threshold · explicitly define the range that is still acceptable 4. Check · evaluate the signal automatically and repeatably 5. Gate · make a violation visible or let the change pass 6. Adjustment · re-examine property and threshold when conditions change ::: The order preserves the domain reason for the measurement. An existing tool alone doesn’t define a meaningful fitness function. ## From wish to mechanical check The term comes from *Building Evolutionary Architectures* by Neal Ford, Rebecca Parsons and Patrick Kua (O’Reilly, 2017), borrowed from evolutionary computing, where a fitness function measures how close a solution is to the goal. Applied to software, this means: an architectural fitness function is an objective, mechanical integrity test for one or more architectural characteristics – that is, for the properties that used to be called, somewhat clumsily, “-ilities”: performance, scalability, coupling, security. The change of perspective that makes the difference in practice is this: architecture is no longer treated as a state you decide on once, but as a property you maintain continuously. That sounds like a nuance, but it’s a break in the way of working. A diagram describes what the system should look like. A fitness function describes what it must look like – and breaks the build if it doesn’t. This moves part of governance from the meeting into the pipeline. The rules that can be automated run along with every commit; reviews remain necessary where trade-offs, context and domain appropriateness matter. The gain is above all early feedback: an explicitly agreed rule doesn’t depend on whether it gets noticed again in the next review. If you have ever seen a single creeping coupling violation block a refactoring for months, you know the price of after-the-fact control. ## The first fitness function is a unit test Getting started is unspectacular, and that’s the good news. The simplest category is static, atomic fitness functions – rules about the structure of the code that can be expressed as a completely normal test. In the Java world, ArchUnit by TNG has become established for this; it checks package and layer dependencies through bytecode analysis. For .NET there is NetArchTest, in the JavaScript world dependency-cruiser. The principle is the same everywhere. The rule invoked at the beginning – the domain knows no infrastructure – looks like this as a fitness function: ```java @ArchTest static final ArchRule domain_must_not_depend_on_infrastructure = noClasses().that().resideInAPackage("..domain..") .should().dependOnClassesThat().resideInAPackage("..infrastructure.."); @ArchTest static final ArchRule no_cyclic_dependencies = slices().matching("..(*)..").should().beFreeOfCycles(); ``` The nice thing about it: this rule documents itself. It lives in the repository, it runs in CI, and it’s not negotiable without someone visibly changing it. The Confluence entry from above describes an intention. The test makes the same chosen rule executable and its violation visible. The second block – `no_cyclic_dependencies` – addresses a classic that is notoriously hard to spot in reviews. Cyclic dependencies rarely arise in one big step. They grow out of many small imports, each harmless on its own. A human no longer sees the cycle in the diagram when it runs across seven modules. The machine does. Exactly such properties – afferent/efferent coupling, instability, freedom from cycles – are the ideal case for static fitness functions, because they are deterministic and cheap to check. ## More than a list of tools If you only think of ArchUnit when you hear fitness functions, you underestimate the reach of the concept. Ford, Parsons and Kua propose a taxonomy that works well as a sorting aid because it suggests the right type of test for each property. Two axes are enough to start with: ```mermaid quadrantChart title Classifying fitness functions x-axis "atomic (one characteristic)" --> "holistic (interplay)" y-axis "triggered (on demand)" --> "continuous (ongoing)" quadrant-1 "Latency/load tests in prod" quadrant-2 "Chaos/resilience checks" quadrant-3 "ArchUnit dependency rules" quadrant-4 "Security scan per commit" ``` *Atomic* measures a single property in isolation, *holistic* checks the interplay of several – such as security and latency together under load. *Triggered* runs on demand, for example in the build; *continuous* runs permanently against the production system. On top of that, the book adds further dimensions: static versus dynamic, automated versus manual, and temporal fitness functions, which deliberately apply only for a limited time – for example a reminder to finish a library migration by a deadline. The practical value of this classification doesn’t lie in classifying for its own sake. It lies in forcing a question you would otherwise dodge: which concrete architectural characteristic is this check actually tied to? If you can’t answer that, you’re probably building a vanity metric right now. ## When the property is dynamic Not everything can be checked statically. Latency, for example, is not a property of the source code but of the running system. This is where dynamic fitness functions come in, which measure against a deployment. Conceptually it stays the same – a threshold, a comparison, a verdict: ```python def latency_fitness(service): p95 = measure_p95_ms(service, window="5m") assert p95 < LATENCY_BUDGET_MS, f"p95 {p95} exceeds budget" ``` As clean as this looks, it’s just as dangerous to hang this assert blindly into CI as a hard gate. Latency values fluctuate. A p95 over a five-minute window can break because of a single garbage collection peak or a slow neighbor in the cluster without anything in your software having changed. If you ignore that, you produce flaky builds – and a flaky gate gets clicked away or commented out within two weeks. Then you have the friction of the check but no longer its benefit. The pragmatic answer is a separation: static, deterministic properties may block the build. Dynamic, statistically fluctuating properties run as observing, triggered checks with statistical windows and raise alerts instead of breaking hard. The same idea, two operating modes – depending on how deterministic the measured characteristic is. For resilience-related properties, it’s worth looking into Michael Nygard’s *Release It!*. The stability patterns described there – Circuit Breaker, Bulkhead, Timeout – provide not only building blocks for robust systems but also checkable expectations: does the circuit breaker open as intended under simulated overload? That is a fitness function too, just a dynamic one. ## Measuring coupling between services The most interesting coupling in distributed systems doesn’t run within one deployable but between them. Two teams, two services, one contract – and the silent assumption that the other side won’t break its API. Consumer-driven contract testing makes this assumption checkable. With Pact and a Pact Broker, the consumer describes its expectation of the provider, and the provider verifies against exactly this expectation. As a fitness function, this lands directly as a step in the deployment pipeline: ```bash pact-broker can-i-deploy \ --pacticipant Checkout \ --version "$GIT_SHA" \ --to-environment production ``` The question “can I deploy this without breaking a consumer?” thus turns from a gut decision into a mechanical answer. The assumption of staying compatible becomes evidence – coupling as governance-as-code. In practice, this is often the moment when teams can really deploy independently for the first time, because the fear of an unnoticed break has been taken out of the process. ## The place where everything comes together A loose collection of rules has little effect. Fitness functions only become effective as a gate in delivery. The deployment pipeline – conceptually established since Humble and Farley – is the natural place for this. Between build and deploy lies a barrier that checks several categories in parallel: ```mermaid flowchart LR commit["commit"] --> build["build"] build --> gate{"Fitness
    Functions
    Gate"} gate -->|static / atomic| s["Dependency & Cycle Rules"] gate -->|dynamic / holistic| d["Latency p95 & Load"] gate -->|contract| c["Pact can-i-deploy"] s -->|fail = break build| commit d -->|fail = break build| commit c -->|fail = break build| commit gate -->|all green| deploy["deploy"] ``` The red return arrows are the core of the idea: a violation doesn’t lead to a ticket that gets prioritized at some point, but to a broken build that is fixed by whoever caused it – immediately, with full context, before the error sinks into the history. This is the same mechanism that makes continuous integration effective, applied to architecture properties. And this is where the circle closes to measurable delivery quality. *Accelerate* by Forsgren, Humble and Kim and the DORA Four Key Metrics – Deployment Frequency, Lead Time for Changes, Change Failure Rate, Time to Restore – provide metrics for the delivery level. Fitness functions can check matching technical guardrails for them. A violated coupling rule is then noticed early; whether that lowers lead time or failure rate is something the team has to verify against its own data. ## Where it tips over in practice As convincing as the concept is, its naive implementation fails reliably in three places – and I’ve seen all of them in projects. First, the vanity metric. A green fitness function that checks a pure test coverage threshold feels like safety and yet measures nothing architectural. Coverage says how much code is executed, not whether the dependencies are right. Every function has to be tied to a concrete architectural characteristic; otherwise it’s theater. Second, the maintenance burden. Fitness functions are code and age like code. I’ve seen codebases in which every second rule carried an `@ArchIgnore`, because under deadline pressure it was faster to add the exception than to solve the problem. Without ownership and regular cleanup of the exception list, the meaningfulness erodes until only green noise remains. These rules need the same care as production code – otherwise they are worse than nothing, because they create false safety. Third, starting too late. If you unleash fitness functions on a grown legacy codebase, you get thousands of violations on the first run – and guaranteed frustration. The way out is a baseline: you freeze the current state, declare fitness from now on and only allow improvement, no deterioration. “Declare fitness from now on” is not a betrayal of purity. In grown systems, it’s the only way something like this gets started at all. ## Conclusion The common thread of these three building blocks – static rules, dynamic measurements, contract checks – is a single idea: architecture is a property you maintain, not a decision you make once. Fitness functions shift control from the review into the pipeline, and with it from hope to certainty. The gain is rarely the individual rule. It lies in the changed way of working. Teams that secure their most important architecture properties mechanically no longer discuss import directions in reviews, but the domain. They deploy more often because the silent fear of an unnoticed break has been taken out of the process. And they refactor more boldly because a net of green checks reports immediately when a restructuring violates a property. The start may be small: a single atomic, static rule that secures a property you really care about. A dependency rule that breaks the build is worth more than twenty rules in a document no one reads. The rest grows from there – as plain code that runs with every build and forces no extra process on anyone. ## Further reading - Neal Ford, Rebecca Parsons, Patrick Kua: *Building Evolutionary Architectures* (O’Reilly, 2017) – [chapter on fitness functions](https://www.oreilly.com/library/view/building-evolutionary-architectures/9781491986356/ch02.html) - [ArchUnit (TNG)](https://www.archunit.org/) – static architecture tests for Java - Nicole Forsgren, Jez Humble, Gene Kim: *Accelerate* (2018) and the DORA Four Key Metrics – [martinfowler.com: StateOfDevOpsReport](https://www.martinfowler.com/bliki/StateOfDevOpsReport.html) - Michael Nygard: *Release It!* (2nd edition, 2018) – stability patterns for resilience-related fitness functions - [Pact](https://docs.pact.io/) – consumer-driven contract testing with `can-i-deploy` --- # Svelte Reactivity: The Compiler Instead of a Virtual DOM URL: https://www.mikebild.dev/en/blog/svelte-reactivity-the-compiler-instead-of-a-virtual-dom/ Date: 2022-04-26 Two rules carry a large part of Svelte 3’s legacy model. First: the compiler recognizes assignments such as `count += 1`, `obj.key = value` or `array[index] = value`; a mere method call such as `array.push(...)` is not such an assignment. Second: a `$:` statement depends on the variables the compiler statically recognizes in its body. The direct syntax and some typical surprises follow from that. Both rules come from the same source. Svelte decides while compiling a component which variable touches which DOM node. What arrives in the browser are finished update instructions; there is no tree comparison at runtime. So `count += 1` really is enough – but only as long as you know how the compiler recognizes a change. The basis is Svelte 3, the current major version in April 2022. Everything that follows is based on the assignment-based reactivity model and the `$:` declarations. This isn’t complete; it’s the slice that lets you grasp the mental model the fastest. **Editorial note (July 2026):** For new code, Svelte 5 preferably works with runes such as `$state`, `$derived` and `$effect`. The `$:` and assignment model explained here belongs to the legacy mode, which is still supported. “Without a Virtual DOM” is still true, but on its own it no longer describes today’s reactivity API. ## The mistake in thinking almost everyone brings along If you come from React, you carry a certain picture in your head: a component is a function that runs again on every state change and returns a description of the desired UI state – a virtual DOM tree. The framework compares this new tree with the old one, finds the differences and transfers only those to the real DOM. This diffing is clever, but it’s work that happens in the user’s browser on every update. Rich Harris put it sharply in his often-quoted text “Virtual DOM is pure overhead”: the virtual DOM is not a feature to be grateful for, but a means to an end – and a means with a price. Svelte asks the question differently. If it’s already clear at build time which parts of the markup depend on which variables, why recompute this mapping in the browser on every update? The Svelte compiler analyzes the component statically and generates imperative JavaScript code that updates exactly the affected DOM nodes. No diff tree, no comparison at runtime. The compiler already knows that when `count` changes, exactly this one text node has to change, and it writes down exactly that instruction. One clarification matters to me here, because it tends to blur in blog posts: Svelte is not “no runtime at all.” The compiled code brings along a small core of helper functions, on the order of a few kilobytes. What’s missing is the runtime diff algorithm and a heavyweight framework traveling along in the bundle. So the correct sentence is: no virtual DOM, no runtime diffing – not: zero runtime. ## What the compiler takes over Before I get to the code, it’s worth looking at which tasks in Svelte are done by the compiler instead of by a runtime library. Exactly this shift explains why the whole thing means less overhead in the browser: - The static analysis of which DOM node depends on which state variable – the result ends up as fixed code in the bundle, not as a computation at runtime. - The generation of targeted update instructions that touch only the nodes actually affected, instead of comparing a complete tree. - The resolution of `$:` dependencies: the compiler determines from the source code which variables a reactive statement reads and generates the code for re-evaluation from that. This last point is where most of the traps lie, and I devote most of what follows to it. ## Reactivity through assignment Let’s look at the simplest reactive component. A file with the `.svelte` extension bundles script, markup and style. A completely normal `let` variable at the top level of the ` ``` There’s no special state API here. `count` is a variable, `count += 1` is an assignment. The point on which everything hinges for me: it’s not the variable itself that is reactive; the assignment to it is the triggering event. The compiler has seen that `count` is referenced in the markup. So around every assignment, it generates the code that marks the component as “dirty” and rewrites the affected text node. What looks like an ordinary change of value is accompanied by a targeted update in the compiled result. That also explains why some changes go nowhere. If you only read `count` or pass it around in a helper function, nothing is triggered. Only the assignment operator is the signal. ## Derived values with `$:` The next building block is values that follow from other values. In React you reach for `useMemo` or compute in the render body. In Svelte 3 there is the reactive declaration with the `$:` label. ```svelte

    {count} * 2 = {doubled}

    ``` `$: doubled = count * 2;` reads like a normal assignment with a strange prefix, but it’s an instruction to the compiler: “Keep `doubled` up to date as soon as one of its dependencies changes.” I don’t have to specify the dependencies myself. The compiler determines them at compile time from the source code – they are all variables that are read in the statement but not assigned. Here, that’s `count`. If `count` changes through an assignment, the declaration runs again, `doubled` gets a new value, and the dependent text node updates. `$:` can do more than derived values. You can also use it to couple side effects to state changes: ```svelte ``` Both forms run again as soon as `count` changes. The mechanism is the same as for the declaration: variables that are read become dependencies, assignments to them trigger re-evaluation. A detail for practice: these statements also run once during server-side rendering and before the first client render. They are part of the reactivity flow itself and not a replacement for a mount hook. The following diagram shows this flow from the assignment to the DOM update – including the side path that later becomes the trap. ```mermaid flowchart TD A[Assignment: count += 1] --> B[Variable marked as dirty] B --> C[reactive $: declarations
    re-evaluated] C --> D[targeted DOM update
    only affected nodes] E[array.push item] -.-> F[no assignment
    no reference change] F -.-> G[no update triggered] ``` ## Build time versus runtime The contrast with React becomes clear when you put both tracks side by side. Svelte determines dependencies and generates update code at build time; the browser still executes that code on every change. React creates a new element tree when rendering and reconciles it at runtime. So Svelte moves the analysis into the build, not all of the update work. ```mermaid flowchart LR subgraph Build[Build time – Svelte] S1[.svelte component] --> S2[Svelte compiler] S2 --> S3[targeted update code
    optimized vanilla JS] end subgraph Runtime[Runtime – React] R1[Render function] --> R2[new virtual DOM tree] R2 --> R3[Diff against old tree] R3 --> R4[Patch to the real DOM] end ``` The core of the picture is not “Svelte good, React bad,” but a different division of labor. React reconciles element trees at runtime. Svelte already knows the statically visible dependencies after the build and ships targeted update code for them. The user still runs this code, just not a virtual DOM diff for this update. On bundle sizes, I deliberately stay cautious. The Svelte core is on the order of a few kilobytes, React plus ReactDOM considerably more. I give that as an order of magnitude, not as an exact measurement – the concrete numbers depend on the version, the bundler and what you actually use, and if you need a hard number, measure your own project. ## The push trap Now to the flip side of the same model – the part this is really about for me. Because reactivity is tied to assignment, there is a class of changes that Svelte 3 simply doesn’t notice: in-place mutations without an assignment. The classic is `Array.push`. ```svelte

    {numbers.join(", ")}

    ``` You click, the console confirms that the array grows – and nothing happens in the browser. No error, no warning, just no update. The reason follows consistently from the model: `numbers.push(...)` changes the existing array, but there is no assignment to `numbers`. Without an assignment, Svelte doesn’t mark the variable as dirty, and without the dirty mark, no update runs. The compiler can’t know that a method has touched the inside of the array – it only sees assignments. The fix is as simple as the problem once you’ve internalized the model: you have to force an assignment. Two approaches are common. ```svelte
      {#each numbers as n}
    • {n}
    • {/each}
    ``` `numbers = [...numbers, ...]` creates a new array and assigns it – the clean variant familiar from other frameworks. `numbers = numbers`, on the other hand, looks like a no-op but is exactly what the compiler needs: an assignment to `numbers` that sets the dirty mark. So for Svelte to notice a change at all, the variable’s name has to end up on the left side of an `=`. With objects, the situation differs from the method call: Svelte’s legacy compiler recognizes a direct assignment such as `obj.key = value` and updates dependent places. What stays invisible is a mutation that only happens inside a called function or method. Then you need an assignment visible to the compiler afterwards, or an immutable replacement via spread. ## The quiet sibling: indirect dependencies There is a second trap that follows from the same principle and is less often recognized right away in reviews. The compiler determines the dependencies of a `$:` statement from which variables are directly referenced in the body. If you hide a variable behind a function call, it doesn’t appear in the body – and isn’t recognized as a dependency. ```svelte ``` `label` is computed on the first pass and never updated after that, because `count` isn’t visible in the body of the reactive declaration – only `getCount()` is there. The compiler has no way to recognize the dependency through the function boundary. The solution is to make the dependency visible, that is, to reference `count` directly in the statement. This isn’t a weakness; it’s the logical consequence of a model that analyzes statically at compile time instead of tracking dynamically at runtime. ## What this means in practice If I pull these two traps together, I get a surprisingly compact mental model for Svelte 3 that boils down to two points: - In legacy mode, reactivity is triggered by statically visible assignments. That includes direct property and index assignments, but not arbitrary method calls with internal mutations. - Dependencies of `$:` have to be directly visible in the body. Whatever disappears behind a function call isn’t tracked. These two rules cover a large part of the surprises I run into in legacy Svelte projects. Both follow from the same design decision: dependencies are analyzed statically at build time. That calls for vigilance at function boundaries and with methods that mutate internally. In a small data client, exactly these reactive assignments carry the data flow: a response replaces the previous value, and the compiler updates the dependent expressions in a targeted way. ## Conclusion Svelte reverses a basic assumption of many frontend frameworks: instead of comparing a virtual DOM at runtime, it lets the compiler determine at build time which state touches which DOM node, and generates targeted update code from that. This eliminates this category of runtime diffing; how big the practical advantage is depends on the application and the update pattern. Everyday code stays pleasantly direct – `count += 1` is enough. In legacy mode, reactivity hinges on statically visible assignments. Once you’ve internalized that, you understand both the `push` trap and indirect dependencies. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-svelte.en.html - [Svelte Docs](https://svelte.dev/docs) – the `$:` syntax and the dependencies determined at compile time in the component format - [Svelte Tutorial](https://svelte.dev/tutorial) – the chapters on Reactivity, Assignments and Updating arrays and objects - [Virtual DOM is pure overhead](https://svelte.dev/blog/virtual-dom-is-pure-overhead) – Rich Harris on the motivation behind the compiler approach - [Write less code](https://svelte.dev/blog/write-less-code) – Svelte’s guiding principle of shipping less runtime code --- # EventEmitter: The Event Model at the Core of Node.js URL: https://www.mikebild.dev/en/blog/eventemitter-the-event-model-at-the-core-of-nodejs/ Date: 2022-04-19 That `.on('data', …)` on a stream, `.on('request', …)` on an HTTP server and `.on('exit', …)` on a child process look the same is not a convention that module authors follow voluntarily. The similarity has a technical reason: all of these objects inherit from the same class – the `EventEmitter`. Once you have mastered this one class, you understand a large part of the standard library. This article takes the `EventEmitter` apart: first the idea behind it, then the concrete API, then the two or three places where it hurts in practice. If you want to read up first on why Node is event-driven at all, you will find that in the post on [Node.js training around the event loop](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/). This one is about the layer directly above it. ## The common denominator beneath everything At its core, Node.js is event-driven. An HTTP server does not wait in a loop for the next request; it registers: “When a request comes in, call this function.” A read stream does not say “give me the data” but “let me know when a chunk of data is there.” This pattern – register interest, get notified later – runs through the entire platform. So that this pattern is not reinvented in every module, there is a shared base class. `net.Server`, `http.Server`, the stream classes `Readable` and `Writable`, the global `process` object, the objects from `child_process` – they are all emitters or inherit from `EventEmitter`. That explains why `.on()` feels the same everywhere: it is literally the same method. ```mermaid classDiagram class EventEmitter { +on(event, listener) +once(event, listener) +off(event, listener) +emit(event, ...args) } EventEmitter <|-- HttpServer EventEmitter <|-- Readable EventEmitter <|-- Writable EventEmitter <|-- Process EventEmitter <|-- MyEmitter class HttpServer["http.Server"] class Readable["stream.Readable"] class Writable["stream.Writable"] class Process["process"] class MyEmitter["custom class"] ``` The class itself lives in the built-in module `events`. You get it the classic way via `require('events')` or – possible since Node 16 – with the prefix `require('node:events')`. Both forms return the same class; the prefix just makes it unmistakably clear that a built-in module is meant and not a package from `node_modules`. ## The four methods everything revolves around The emitter’s API is surprisingly small. Four methods are enough for everyday work. Three of them – `on`, `once` and `off` – return the emitter itself and can therefore be chained; `emit` is the exception and returns a `boolean` instead, as we will see in a moment. ```js const { EventEmitter } = require('node:events'); const emitter = new EventEmitter(); function onTask(job) { console.log('received task', job.id); } emitter.on('task', onTask); // register a listener emitter.emit('task', { id: 1 }); // trigger it synchronously emitter.off('task', onTask); // remove it again ``` `on(eventName, listener)` appends a listener to the end of the list for this event. `emit(eventName, ...args)` calls all registered listeners and passes the additional arguments through. `off(eventName, listener)` – alias `removeListener` – takes a listener out again. And `once(eventName, listener)` registers a listener that disappears automatically after it fires the first time. Two properties of `emit` are crucial for understanding, and both are often overlooked: - `emit` calls the listeners **synchronously**. There is nothing asynchronous here, no detour through the event loop, no delay. When `emit` returns, all listeners have run. - The listeners run **in the order they were registered**. Whoever called `on()` first has their function run first. ```mermaid sequenceDiagram participant C as Caller participant E as EventEmitter participant L1 as Listener 1 participant L2 as Listener 2 C->>E: emit('task', data) E->>L1: listener(data) L1-->>E: done E->>L2: listener(data) L2-->>E: done E-->>C: return true ``` The return value of `emit` is a `boolean`: `true` if there was at least one listener for this event, otherwise `false`. What the listeners themselves return does not interest the emitter – return values from listeners are simply ignored. If you want to report something to the outside from within a listener, you have to do it another way, such as another event or shared state. ## on, once and off working together The difference between `on` and `once` sounds harmless but has consequences. A listener registered with `once` is removed from the list **before** its own call and then executed. So it is guaranteed to fire exactly once, no matter how often the event is triggered afterward. ```js const { EventEmitter } = require('node:events'); const queue = new EventEmitter(); let handled = 0; queue.on('task', () => { handled += 1; }); let drained = 0; queue.once('drain', () => { drained += 1; }); queue.emit('task'); // handled = 1 queue.emit('task'); // handled = 2 queue.emit('drain'); // drained = 1 queue.emit('drain'); // drained stays 1 - the listener is gone ``` Removal deserves a close look. `off` removes **at most one** instance of a listener. If you accidentally registered the same function twice with `on`, you also need two `off` calls to get rid of it completely. And you can only remove what you can name – an anonymous arrow function that you pass directly to `on` is out of your hands afterward. That is why I always register listeners that I want to unregister later as a named function or as a variable. Here are the semantics of the four at a glance: - `on` – the listener stays registered and runs again on every `emit`. - `once` – the listener runs exactly once and removes itself beforehand. - `off` – removes one instance of a named listener; you cannot get rid of anonymous functions this way. - `emit` – calls all listeners synchronously in registration order and returns `true`/`false`. Besides these four, there are some useful side methods: `prependListener` adds a listener to the beginning instead of the end, `removeAllListeners` cleans up completely, `listeners(eventName)` returns a copy of the current listener list and `eventNames()` tells you which events anyone is registered for at all. You rarely need them, but when you do, they are worth their weight in gold – for example when debugging the question “who is actually listening here?” ## The error event is a special case This quirk once cost a running process in a project: the `'error'` event behaves differently from all others. For an ordinary event without listeners, nothing happens – `emit` returns `false`, and that is that. Not so for the `'error'` event. If an emitter calls `emit('error', ...)` and **no** listener is registered for `'error'`, the error is thrown. And because it is thrown inside the emitter machinery and nobody catches it, it can take down the whole process. This turns “a stream complained” into a complete crash of the Node process. ```js const { EventEmitter } = require('node:events'); const source = new EventEmitter(); // Without this listener the next line would crash the process: source.on('error', (err) => { console.error('handled:', err.message); }); source.emit('error', new Error('boom')); // handled cleanly ``` By the way, this is not harassment but a deliberate decision by the Node team. An error that nobody handles should be loud and not silently swallowed. This leads to a simple rule: for every emitter that can report errors – and that is practically all streams, all network objects, all child processes – I register an `'error'` listener before the actual work starts. It is the safety net without which the whole application breaks on a single unhandled message. There are two more special events used internally: `'newListener'` fires before a new listener is added, and `'removeListener'` fires after one has been removed. Both are meant more for tools and diagnostics than for everyday use, but it is good to know they exist if you ever want to watch who registers or unregisters when. ## Too many listeners: the leak warning Node keeps track, for every emitter, of how many listeners are registered per event. If this number exceeds a threshold – 10 by default – Node prints a warning to stderr: the `MaxListenersExceededWarning`. This warning is not an error and stops nothing. It is a heuristic against a very common class of bugs: the listener leak. The typical case is that somewhere, per request, per loop iteration or per retry, an `on()` is called, but the matching `off()` is missing. The listeners pile up, memory grows, and at some point Node speaks up. ```js const { EventEmitter } = require('node:events'); const bus = new EventEmitter(); // Optional: make the warning itself visible process.on('warning', (warning) => { console.log(warning.name, '- count:', warning.count); }); // Anti-pattern: a new, never-removed listener on every iteration for (let i = 0; i < 12; i += 1) { bus.on('data', (chunk) => processChunk(chunk)); } // From the 11th listener on, the MaxListenersExceededWarning appears. ``` What matters is this: the warning is the symptom, not the cause. The cause is the registration that is never removed. If you silence the warning with `emitter.setMaxListeners(Infinity)`, you have only taped over the warning light – the leak keeps running, memory keeps growing. The right fix is to unregister listeners when you no longer need them, or to register them as `once` right away if they should only fire once anyway. ```js function onData(chunk) { processChunk(chunk); } bus.on('data', onData); // ... later, when done: bus.off('data', onData); // cleanly removed, no pile-up ``` That does not mean the threshold of 10 is set in stone. There are legitimate cases where an emitter deliberately has more listeners. Then you adjust it intentionally: `emitter.setMaxListeners(n)` raises the limit for a single emitter, `events.defaultMaxListeners = n` moves the global default. The value `0` or `Infinity` turns the warning off entirely. The only important thing is that this decision is a conscious one and not a reflex to get rid of the message in the log. ## Building your own class The `EventEmitter` is not just something the standard library inherits from – you can just as well use it as a base yourself. Whenever a component of yours should inform its surroundings about things without knowing the receivers in advance, an emitter is the obvious choice. The pattern is `class MyThing extends EventEmitter` with a `super()` call in the constructor. Here is a small task queue that reports when a task is added, when it is done and when something goes wrong: ```js const { EventEmitter } = require('node:events'); class TaskQueue extends EventEmitter { constructor() { super(); this.pending = []; } add(job) { this.pending.push(job); this.emit('task', job); } run() { while (this.pending.length > 0) { const job = this.pending.shift(); try { job.handler(); this.emit('done', job); } catch (cause) { // Only emit 'error' when a listener exists - // otherwise it crashes the process: if (this.listenerCount('error') > 0) { this.emit('error', cause); } else { throw cause; } } } this.emit('drain'); } } const queue = new TaskQueue(); queue.on('task', (job) => console.log('queued', job.id)); queue.on('done', (job) => console.log('done', job.id)); queue.once('drain', () => console.log('all work finished')); queue.on('error', (err) => console.error('failed:', err.message)); queue.add({ id: 1, handler: () => {} }); queue.add({ id: 2, handler: () => { throw new Error('bad job'); } }); queue.run(); ``` This example shows several things working together. The queue does not know its listeners – it calls `emit`, and whoever wants to listens. `once('drain', ...)` makes sure the completion message arrives exactly once. And in the error case, I check with `listenerCount('error')` whether anyone is listening at all before I call `emit('error', ...)`. That way I avoid the crash from an unhandled `'error'` event and instead let the error continue as an ordinary exception if nobody catches it. A small but recurring stumbling block with your own classes concerns `this`. In a classic function listener, `this` points to the emitter that triggered the event – handy if you want to access the emitter from inside. In an arrow function, that does not apply; there, `this` keeps its meaning from the surrounding context. Both are legitimate; you just need to be aware of which variant you choose. ## Synchronous means synchronous Finally, one clarification that prevents bugs in everyday work. Because Node is so strongly associated with asynchrony, many people intuitively assume that `emit` calls the listeners at some later point. It does not. The call is synchronous, and the listeners block the calling code until they are done. Most of the time, that is exactly right, because it makes the flow predictable. But if, inside a listener, you deliberately want to move something out of the current flow – so that long work does not hold up the `emit` caller – you have to do that explicitly, for example with `setImmediate` or `process.nextTick`. The emitter itself reschedules nothing; it just calls, in order, whatever is registered. ## Conclusion The `EventEmitter` is a small class with a big reach. Four methods – `on`, `once`, `off`, `emit` – carry everyday work, and because a large part of the standard library inherits from exactly this class, the understanding carries over directly to streams, servers and processes. Two things you should never lose sight of: without a listener, the `'error'` event crashes the process, so an `'error'` listener belongs wherever errors can be reported. And the `MaxListenersExceededWarning` is an honest warning sign of a leak, not an annoying notice you configure away. With these two reflexes, you write event-driven Node code that keeps running stably even when things get uncomfortable. ## Further reading - Node.js docs: [Events API](https://nodejs.org/docs/latest-v16.x/api/events.html) - Node.js guide: [The Node.js Event emitter](https://nodejs.org/en/learn/asynchronous-work/the-nodejs-event-emitter) - Node.js docs: [Stream API](https://nodejs.org/docs/latest-v16.x/api/stream.html) (inherits from `EventEmitter`) - My own post: [Node.js training around the event loop](https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/) --- # GraphQL Pagination: Cursors, Connections and the Relay Pattern URL: https://www.mikebild.dev/en/blog/graphql-pagination-cursors-and-connections/ Date: 2022-03-08 If you page through a list by position, you silently rely on nobody writing in the meantime. In production, this assumption rarely holds. A position is not an anchor in the data; it is a count – and counts shift as soon as a record is added or removed at the front. The follow-up request then no longer asks the question the client meant to ask. That’s why pagination is one of the places where it shows whether an API is robust or only works in the demo case. As long as the list stands still, offset/limit does its job flawlessly. As soon as it changes under the paging client – and that is the normal case, not the exception – errors arise that are hard to reproduce and even harder to explain. For exactly this, the GraphQL community established a convention of its own: the connections pattern. That’s what this post is about. ## Why offset/limit fails with changing lists Let’s make the problem concrete. I have a list sorted by creation date in descending order and page through it two at a time. The client requests the first page: `offset: 0, limit: 2`. It gets the entries at positions 0 and 1. For the next page it asks for `offset: 2, limit: 2`. The insidious part: `offset` is a pure position count. It says “skip the first two elements” – but it has no idea *which* two elements those were on the first call. If a new entry is inserted at the front between the two requests, the whole list slides back by one position. The element that was just at position 1 is now at position 2 – and is delivered to the client a second time at `offset: 2`. A duplicate. The reverse case is just as annoying: if an entry at the front is deleted, everything moves forward by one position. The element that was at position 2 jumps to position 1 – and is skipped at `offset: 2`. A gap. The user never sees an entry, even though it exists. ```mermaid flowchart TB subgraph stabil["Stable: cursor-based"] direction LR a1["Request 1
    first: 2"] --> a2["returns A, B
    endCursor = B"] a2 --> a3["Request 2
    after: cursor of B"] a3 --> a4["returns C, D
    no duplicate"] end subgraph kaputt["Shifted: offset/limit"] direction LR b1["Request 1
    offset 0, limit 2"] --> b2["returns A, B"] b2 --> b3["new entry X
    inserted at the front"] b3 --> b4["Request 2
    offset 2, limit 2"] b4 --> b5["returns B, C
    B duplicated"] end ``` The core is always the same: offset counts positions, and positions are not a stable anchor as soon as the front of the list changes. Offset is like the train announcement “get off at the third stop” – wonderful, as long as nobody adds an extra stop. ## The cursor-based way out The solution is to change the question. Instead of “give me the elements from position N”, the client asks “give me the elements *after this specific element*”. This “specific element” is represented by a **cursor** – an opaque pointer that the server hands out and the client passes back unchanged. The crucial difference: a cursor is bound to an element or its sort value, not to a position. When the client says “continue after the element with cursor X”, this statement stays correct no matter how many entries are inserted or deleted before it. The window doesn’t shift, because it doesn’t depend on a count but on an anchor in the data. A point that regularly comes up in code reviews: the cursor is **opaque**. The client must not assume any structure and must not do any arithmetic with it. It may only hand it back. This is deliberate – the server alone decides what a cursor means. Today it may contain an ID, tomorrow a combination of sort field and ID, the day after something completely different. As long as the client only passes the cursor through, the server can change its cursor implementation without breaking a single client. Base64 encoding is common – but that’s convention, not a rule, and only serves to keep anyone from being tempted to interpret the content. ## The connections pattern: edges, node, pageInfo This brings us to the actual topic. Around cursor-based pagination, the GraphQL community formalized a convention: the Relay Cursor Connections Specification. You don’t have to use Relay as a framework to benefit from the pattern – it has established itself as a de facto standard because it cleanly solves an important question: where do I actually put the cursor? The naive answer would be to stick the cursor directly onto the record. But the cursor is not a property of the user or the article – it is a property of *this position in this list*. That’s why the pattern introduces an intermediate layer, the **edge**. An edge connects the actual record (`node`) with its `cursor`. The `node` stays clean, and the list-specific information sits on the edge. Above it sits the **connection**. It bundles the list of edges and an object called `pageInfo`, which carries the metadata for paging further. What exactly do the individual building blocks provide? - `edges` is the list of edges. Each edge contains `node` (the plain record, without a list wrapper) and `cursor` (the opaque pointer to exactly this edge). - `pageInfo.hasNextPage` says whether there are more elements after the current page. This is the authoritative stop condition for paging. - `pageInfo.hasPreviousPage` is the counterpart for the backward direction. - `pageInfo.endCursor` is the cursor of the last element of the current page – exactly the value the client puts into the follow-up request as `after`. - `pageInfo.startCursor` is its counterpart at the start of the page, relevant for paging backward with `before`. On naming conventions: the connection type ends in `Connection`, the edge type in `Edge`. `pageInfo` is non-null, and so are the two booleans in `PageInfo`. The two cursor fields `startCursor` and `endCursor`, by contrast, are nullable – on an empty page there simply is no cursor. A commonly seen field is `totalCount`, the total number of hits. It is handy, but it has a catch: `totalCount` is **not** part of the connections specification. It is a widespread optional extension, and depending on the data source, an exact `COUNT` can be expensive. If you include it, do so deliberately and not under the assumption that it belongs to the standard. ## An example schema Enough prose, let’s look at SDL. A query that returns users with pagination looks like this in the connections pattern: ```graphql type Query { users(first: Int, after: String): UserConnection! } type UserConnection { edges: [UserEdge!]! pageInfo: PageInfo! totalCount: Int } type UserEdge { node: User! cursor: String! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } type User { id: ID! name: String! createdAt: String! } ``` The arguments follow the specification. For forward pagination there is `first: Int` (the desired page size, non-negative) and `after: String` (the cursor after which to continue). For the backward direction, there are `last: Int` and `before: String` accordingly. Sending `first` and `last` at the same time is explicitly discouraged by the specification – the result would be ambiguous. A query from the client then reads like this: ```graphql query FirstPage { users(first: 2) { edges { cursor node { id name } } pageInfo { hasNextPage endCursor } } } ``` And the follow-up request takes the `endCursor` from the previous response as `after`: ```graphql query NextPage { users(first: 2, after: "dXNlcjpjdXJzb3I6NDI=") { edges { cursor node { id name } } pageInfo { hasNextPage endCursor } } } ``` Many introductory examples – including my own fundamentals material – show simplified variants, such as `skip`/`take` or an `after: 99` where the cursor looks suspiciously like an ID or an offset. That’s fine for explaining, but it isn’t the real Relay pattern. A production cursor is opaque and does *not* look like a readable number. This distinction is worth the extra sentence; otherwise someone will later start calculating with the cursor on the client. ## The resolver sketch On the server side, the resolver has to do three things: decode the incoming cursor, load the matching set of data and build edges plus `pageInfo` from it. The most interesting trick lies in determining `hasNextPage`. A common beginner’s mistake is to derive `hasNextPage` from whether the result is smaller than `first`. That’s unreliable: if exactly `first` elements happen to be left, you wouldn’t know whether anything comes after them. The clean way is to load one element more than requested – `first + 1`. If this extra element exists, there is a next page. Afterwards, you trim the result back to `first`. ```js function encodeCursor(id) { return Buffer.from(`cursor:${id}`).toString("base64"); } function decodeCursor(cursor) { const decoded = Buffer.from(cursor, "base64").toString("utf8"); return Number(decoded.split(":")[1]); } async function usersResolver(_parent, args, context) { const { first = 20, after } = args; const limit = Math.min(first, 100); // enforce an upper bound const afterId = after ? decodeCursor(after) : 0; // load one extra row to detect a following page const rows = await context.db.query( `SELECT id, name, created_at FROM users WHERE id > $1 ORDER BY id ASC LIMIT $2`, [afterId, limit + 1] ); const hasNextPage = rows.length > limit; const pageRows = hasNextPage ? rows.slice(0, limit) : rows; const edges = pageRows.map((row) => ({ node: row, cursor: encodeCursor(row.id), })); return { edges, pageInfo: { hasNextPage, hasPreviousPage: Boolean(after), startCursor: edges.length ? edges[0].cursor : null, endCursor: edges.length ? edges[edges.length - 1].cursor : null, }, }; } ``` Two details are worth a second look. First, the upper bound: without a `Math.min`, a client could send `first: 1000000` and bring the database to its knees. An enforced upper bound is mandatory, not optional. Second, the cursor helpers `encodeCursor`/`decodeCursor` – they demonstrate that the opaque string here simply contains an ID, but that the client doesn’t need to know that. As a dialog between client and server, the flow across several pages looks like this: ```mermaid sequenceDiagram participant C as Client participant S as Server C->>S: users(first: 2) S-->>C: edges A, B
    pageInfo endCursor=B, hasNextPage=true C->>S: users(first: 2, after: Cursor B) S-->>C: edges C, D
    pageInfo endCursor=D, hasNextPage=true C->>S: users(first: 2, after: Cursor D) S-->>C: edges E
    pageInfo endCursor=E, hasNextPage=false Note over C,S: Loop ends as soon as hasNextPage=false ``` So the client pages in a simple loop: as long as `hasNextPage` is true, it sends the next request with the most recently received `endCursor` as `after`. No counting positions, no recalculating. ## The price of sorting – and a database bonus One place where cursor-based pagination silently fails is ambiguous sorting. The cursor needs a **deterministic, unique** order. If I sort only by `created_at`, for example, and two records carry the same timestamp, then it is undefined at this tie which one comes first – and exactly there, duplicates or omissions appear again. The solution is a tie-breaker: you additionally sort by a guaranteed unique column, usually the ID. `ORDER BY created_at` becomes `ORDER BY created_at, id`. This yields a nice side effect. Cursor pagination can be expressed in SQL as so-called keyset pagination, and it scales much better than large offsets: ```sql SELECT id, created_at, name FROM users WHERE (created_at, id) > (:cursor_created_at, :cursor_id) ORDER BY created_at, id LIMIT :page_size; ``` The reason: a large `OFFSET n` forces the database to read and discard `n` rows before it even starts returning anything – on deep pages, this becomes noticeably slow. The keyset variant with `WHERE (sort_key, id) > (...)`, by contrast, can jump straight to the right place via the index. So cursor pagination is not only more correct for changing lists, it is often faster for deep paging too. ## When offset is still fine Cursor pagination is not an end in itself. There are cases in which offset is perfectly sufficient: - The list is essentially stable, such as a historical archive or a closed report into which nothing gets inserted anymore. - The user should be able to jump straight to page 7 – numbered pages can’t easily be represented with pure cursors, because you don’t know an absolute position. - The data volumes are small and the pages shallow, so that neither consistency nor performance problems occur. So this is not about dogma but about a deliberate choice. As soon as a list can change under the user *and* they potentially page deep into it – feeds, timelines, activity streams – cursor-based pagination with the connections pattern is the right answer. For a stable, manageable reference work, offset can happily stay. ## Conclusion Pagination seems trivial until you look at it in motion. Offset counts positions, and positions shift – the result is duplicates and gaps that never show up in the quiet demo and are hard to pin down in production. The cursor-based approach replaces the question “from which position” with “after which element” and thereby becomes robust against changes to the list. The connections pattern pours this idea into a clean structure: edges carry the list-specific cursor, nodes remain plain records, and `pageInfo` with `hasNextPage` and `endCursor` provides exactly the two pieces of information a client needs to page on correctly. Then come the details that make the difference between demo and production – an extra element for `hasNextPage`, a tie-breaker in the sorting, an upper bound for the page size and the discipline to treat the cursor as truly opaque. If you take these four things to heart, you have pagination that is still correct when the list moves under the user’s fingers. ## Further reading - Grounding repository: [introduction-graphql](https://github.com/mikebild/introduction-graphql) (`introduction-graphql/paging.md`) - [GraphQL Pagination – official learning resource](https://graphql.org/learn/pagination/) - [GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm) --- # SvelteKit Adapter AWS: Framework Meets Cloud URL: https://www.mikebild.dev/en/blog/sveltekit-adapter-aws-framework-meets-cloud/ Date: 2022-01-12 # SvelteKit Adapter AWS: Framework Meets Cloud When a framework’s deployment model and the target platform do not fit together, projects always produce the same by-product: a handwritten deploy script. It copies build output into an S3 bucket, zips up a Lambda handler somewhere, sets cache headers by hand and finally invalidates a CloudFront distribution. That works – until the framework changes the structure of its build output, until a header is forgotten or until the one person who can still explain the script leaves the project. After that, the team has a deployment nobody trusts anymore, and every release becomes a test of courage. This is exactly where SvelteKit applications that are supposed to run on AWS stand at the beginning of 2022. SvelteKit itself is still in beta – version 1.0 has been announced but not released – and it brings a remarkably clear concept for this problem: adapters. There is `adapter-node` for your own server, `adapter-static` for purely static sites, `adapter-vercel` and `adapter-netlify` for the respective platforms. There is no official adapter for AWS. So I wrote one: [sveltekit-adapter-aws](https://github.com/MikeBild/sveltekit-adapter-aws), an open source project that rolls out a SvelteKit app to Lambda, S3 and CloudFront via the AWS CDK. While building it, I noticed a few things about both sides – about the framework and about the cloud. That is what this post is about. ## Adapters are an architecture boundary At its core, a SvelteKit adapter is a Node module with a single essential function: `adapt()`. After the actual build, SvelteKit calls this function and passes a `builder` object through which the adapter picks up the build output: the client code for the browser, the server code for rendering, the prerendered pages. What the adapter does with it is up to the adapter. `adapter-node` builds a startable HTTP server, `adapter-static` a directory structure for any web server, `adapter-vercel` exactly the format the Vercel platform expects. This boundary is drawn deliberately. The framework knows how routes, components and endpoints become an application. It does not know – and does not want to know – where this application will run later. Everything platform-specific moves behind the adapter interface. For the user, the decision comes down to one line in `svelte.config.js`: ```javascript import { adapter } from 'sveltekit-adapter-aws'; import preprocess from 'svelte-preprocess'; export default { preprocess: preprocess(), kit: { adapter: adapter({ autoDeploy: true, FQDN: 'demo.example.com', MEMORY_SIZE: 256, LOG_RETENTION_DAYS: 7, }), }, }; ``` With `autoDeploy: true`, the build step rolls out the application directly – `svelte-kit build` then ends not with a directory but with a running CloudFormation stack. That is convenient for prototypes and small projects; for everything else, you can plug in your own CDK app via `cdkProjectPath` that uses the adapter output as a building block. ## Why there was no AWS adapter The fact that Vercel and Netlify have their own adapters and AWS does not is neither a coincidence nor an oversight. Vercel and Netlify are platforms: they control both sides of the interface and can define exactly which artifact they expect. AWS is not a platform in this sense but a construction kit. There is no single service called “SvelteKit hosting,” but dozens of primitives from which you assemble one of many possible deployments. An AWS adapter therefore has to do something the platform adapters do not: define an architecture. Which service answers SSR requests? Where do the static files live? Who distributes the traffic? These are decisions that an architect would otherwise make in a design document – here they live in an npm package. That is exactly what makes such an adapter an interesting piece of software: it is solidified architecture, versioned and reusable. ## The architecture: three services, one application The split I chose follows the character of the build output. A built SvelteKit app falls into two fundamentally different parts: static files (client bundles, assets, prerendered pages) that can be cached at will, and a server part that has to compute per request. Static content belongs in S3, dynamic content in a Lambda function, and in front of both sits CloudFront as the shared entry point that decides by path where a request goes. ```mermaid flowchart LR B[Browser] --> CF[CloudFront
    distribution] CF -->|/_app/*, assets,
    prerendered pages| S3[S3 bucket
    static files] CF -->|all other
    requests| GW[API Gateway
    HTTP API] GW --> L[Lambda
    SvelteKit SSR] R53[Route 53 + ACM
    custom domain] -.-> CF ``` The whole thing is provisioned with the AWS CDK, specifically version 2, which only became generally available in December 2021 – so the project builds on a fairly fresh foundation. Above all, CDK v2 cleans up the package chaos of v1: one library, `aws-cdk-lib`, instead of dozens of individually versioned modules. For an adapter that travels into other people’s projects as an npm dependency, that is a noticeable difference, because version conflicts between CDK subpackages were a constant issue in v1. The core of the stack, slightly shortened: ```typescript import { Stack, StackProps, Duration } from 'aws-cdk-lib'; import * as lambda from 'aws-cdk-lib/aws-lambda'; import { RetentionDays } from 'aws-cdk-lib/aws-logs'; export class AWSAdapterStack extends Stack { constructor(scope: Construct, id: string, props: StackProps) { super(scope, id, props); const serverHandler = new lambda.Function(this, 'ServerFunction', { runtime: lambda.Runtime.NODEJS_14_X, handler: 'index.handler', code: lambda.Code.fromAsset(process.env.SERVER_PATH!), memorySize: parseInt(process.env.MEMORY_SIZE ?? '128'), timeout: Duration.seconds(15), logRetention: RetentionDays.ONE_WEEK, }); // ... HTTP API, S3 bucket, CloudFront distribution, Route 53 records } } ``` A detail that is easy to miss: log retention is deliberately set to seven days. CloudWatch logs without a retention rule grow without limit, and with an SSR function that logs every page request, that adds up faster than you think. In my experience, such operational defaults belong in the adapter, not on a wiki page with recommendations. ## From the Lambda event to the framework response The actual translation work happens in two places. The first is the build: the server part of the SvelteKit output is bundled with esbuild into a single CommonJS file – format `cjs`, target Node 14, with the built-in Node modules kept external. Lambda thus gets an artifact without a `node_modules` directory, which has done package size and cold starts good. The second place is the runtime itself: a small handler shim receives the event from API Gateway, shapes it into the request structure the SvelteKit server expects and translates the response back: ```javascript // index.js – bridges API Gateway events to the SvelteKit server import { init, render } from './app.js'; init(); export async function handler(event) { const { rawPath, rawQueryString, headers, requestContext } = event; const response = await render({ method: requestContext.http.method, path: rawPath, query: new URLSearchParams(rawQueryString), headers, rawBody: event.body ? Buffer.from(event.body, event.isBase64Encoded ? 'base64' : 'utf8') : undefined, }); return { statusCode: response.status, headers: response.headers, body: response.body, }; } ``` This shim is unspectacular, but it is the place where the framework world and the cloud world actually meet. This is where it is decided whether binary data is passed through correctly, whether multiple `Set-Cookie` headers survive and whether query parameters with special characters arrive intact. I did not design any of these small things at my desk; I added each one after a concrete misbehavior. The entire flow from source code to stack looks like this: ```mermaid flowchart LR SRC[SvelteKit
    source code] --> BUILD[svelte-kit build
    via Vite] BUILD --> ADAPT[adapter adapt()
    sorts outputs] ADAPT --> ESB[esbuild
    SSR bundle, cjs] ADAPT --> STATIC[static files
    + prerendered] ESB --> CDK[AWS CDK v2
    synth + deploy] STATIC --> CDK CDK --> STACK[CloudFormation stack
    Lambda, S3, CloudFront] ``` ## Building against a moving API The most uncomfortable part of the project has nothing to do with AWS. SvelteKit is in beta, and the adapter interface is among the parts that move most often. Methods on the `builder` object were renamed, merged and changed in behavior; the structure of the server output has also shifted more than once. An adapter built against SvelteKit from October may still compile in December – and still produce a broken deployment. For an open source project, this means: the issues do not come from your own bugs but from the drift between the user’s framework version and the version the adapter was developed against. A typical bug report starts with “doesn’t work for me” and, after some digging, ends at a SvelteKit version that is three weeks newer than my last update. Only unspectacular measures help against this: pin the tested SvelteKit version in the project, keep example repositories up to date, follow changes to the framework promptly. That is the real price of building against a beta – and I consider it reasonable. If you wait until an interface is stable, you leave the experience from the meantime to others. Along the way, an adapter forces you to really understand the framework: you do not work with the documented surface but with the build output and its assumptions. What the adapter concretely takes care of during the build is manageable and, precisely for that reason, easy to maintain: - sort client bundles, assets and prerendered pages into an artifact directory - bundle the server part with esbuild into a Lambda-ready file - place the handler shim for API Gateway next to it - synthesize a CDK stack and, if desired, roll it out directly - wire up domain, certificate and DNS records via Route 53 and ACM when an `FQDN` is set ## What serverless does not take off your hands On the other side of the boundary, the second disillusionment is waiting: even with a finished adapter, AWS is not a platform that takes operations off your hands. Serverless moves work; it does not eliminate it. A few points became clear to me while running my own SvelteKit deployments. Cold starts are real but manageable. An SSR function bundled with esbuild starts fast enough for most pages at this scale – but if you pull heavy dependencies into the server part, you pay for it with every cold request. With Lambda, the memory size is also the CPU dial: the 128 MB default is often too tight for rendering, and more memory can improve response times so much that it pays off despite the higher price per millisecond. Measure instead of guessing. Then there is caching. CloudFront only relieves the function if the cache keys and headers are right – an SSR response with `Cache-Control` set to `private` hits the Lambda on every call. For small rewrites right at the edge, there have been CloudFront Functions since last year, which are much more lightweight than Lambda@Edge; for the actual rendering, both are the wrong place. And CloudFormation makes deployments traceable and reversible, but not fast: a change to the CloudFront distribution can take quite a few minutes. If you come from Vercel, you first have to get used to this pace. What remains is an honest division of labor. The adapter answers the question “how does the app get to AWS” – these questions stay with the team: - Observability: which logs, metrics and alarms show that rendering is suffering? - Costs: what do requests, data transfer and logs cost under real traffic? - Security: which permissions does the SSR function have, and which does it really need? - Lifecycle: who keeps up with framework and adapter updates, and how is a rollback rehearsed? ## Bottom line The project showed me two things that reach beyond SvelteKit and AWS. First: the adapter interface is a successful example of how a framework can draw a boundary without committing to a platform. Everything platform-specific – from the directory structure to the architecture decision – gets a clear place, and this place is versionable, testable and replaceable. The fact that a single person can provide a complete AWS foundation for a framework in a manageable repository speaks for the way this interface is cut. Second: a deployment target is never just configuration. The path from `svelte-kit build` to a running CloudFront endpoint consists of nothing but small decisions – bundling, routing rules, cache behavior, memory sizes, log retention – and each of them has consequences in operations. A handwritten deploy script makes the same decisions, only invisibly and unversioned. An adapter makes them explicit and shares them with everyone who has the same problem. That is exactly why it is worth building something like this as open source, even when the framework is still in beta and the interface wobbles under your hands: the alternative is not “no adapter” but a hundred private scripts that all make the same mistakes again. ## Further reading - Repository: https://github.com/MikeBild/sveltekit-adapter-aws - SvelteKit documentation on adapters: https://svelte.dev/docs/kit/adapters - AWS CDK v2 Developer Guide: https://docs.aws.amazon.com/cdk/v2/guide/home.html - Amazon CloudFront Functions: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-functions.html --- # Preview Environments per Pull Request URL: https://www.mikebild.dev/en/blog/preview-environments-per-pull-request/ Date: 2021-11-24 # Preview Environments per Pull Request “Is staging free?” – this question in the team chat is the real bottleneck. As long as one environment has to serve everyone, the order of the queue decides when someone even gets to see a change. If, instead, every pull request gets its own disposable instance, the relationship flips: the review doesn’t wait for the environment, the environment comes into being with it. ## The problem behind the diff A review often ends right here: someone opens a pull request, a colleague reads the diff, imagines the behavior that goes with it and writes “LGTM”. That is a guessing game. A diff shows which lines changed – not how the application feels afterward. Whether the new checkout flow is usable on a smartphone, whether the loading state flickers, whether an edge case in the domain is right: none of that is in any `git diff`. The classic answer was a shared staging environment. One team, one environment, one queue. If you want to test, you deploy your branch, overwrite the previous one and block everyone else. With two parallel features, that is a source of conflicts; with five, a permanent traffic jam. The actual goal – fast, concrete feedback – gets lost in the coordination. And the jam is only the visible side. The invisible one is that a shared staging environment never has a defined state: it always carries the leftovers of the last deploy, half-migrated schemas, test data from someone else’s feature. When a reviewer sees something odd there, nobody knows for sure whether it is the current PR or an artifact from yesterday. Exactly this “is it my change or the environment?” eats up time and trust. A freshly spun-up instance doesn’t have this problem – it starts from the same reproducible zero state on every run. The thesis of this article is simple: every pull request gets its own disposable environment with its own URL. Reviewers click through the running change instead of imagining it. And because the environment is ephemeral, it disappears again on merge – without a cleanup ritual, without a growing bill. ## The outcome, not the mechanics Before we get to `app.json` and CI pipelines, it pays to look at the why. The benefit lies in the shorter feedback loop – and that pays directly into measurable delivery performance. *Accelerate* (Forsgren, Humble, Kim, 2018) backed this up with data: small batches, short lead time for changes and high deployment frequency are the drivers of high-performing software delivery. A preview environment per pull request pushes exactly there. It rewards small changes – a tiny PR can be deployed in seconds and reviewed in minutes. It lowers the threshold to integrate at all, because feedback doesn’t have to wait for the next staging slot. That fits seamlessly with Trunk-Based Development and with what Humble and Farley described back in 2010 in *Continuous Delivery*: short-lived branches, fast integration, the PR as the unit of integration. Perhaps the most underestimated effect is social. As soon as there is a clickable URL, people who don’t set up a development environment can review too: QA, product management, design. A designer who sees the real implementation in the browser gives feedback in five minutes that would otherwise take a meeting and three screenshots. That is the point where a technical feature turns into a delivery advantage. Conceptually, this is closely related to the build-measure-learn loop from Ries’ *Lean Startup* (2011). A preview is a concrete artifact you can measure and learn from before anything goes to production. The smaller the batch, the faster the loop can become. Economically, though, an environment per PR only works if provisioning, data, runtime and teardown are under control. Otherwise, the preview merely shifts the friction from the review into operations. ## The lifecycle of an ephemeral environment The mechanics are the same across all established products – whether Heroku “Review Apps”, GitLab “Review Apps”, Netlify “Deploy Previews” or Vercel’s “Preview Deployments”. The PR is the trigger, the merge is the end. ```mermaid sequenceDiagram participant Dev as Developer participant PR as Pull Request participant CI as CI Pipeline participant Env as Preview Environment Dev->>PR: open / push commit PR->>CI: trigger build (HEAD commit) CI->>Env: deploy isolated instance (own URL + own DB) Env-->>PR: post preview URL as commit status Dev->>Env: reviewer clicks and tests Dev->>PR: push new commit PR->>CI: rebuild and redeploy Dev->>PR: merge or close PR->>Env: destroy environment ``` The important word is *isolated*. Instead of one staging environment for everyone, n previews run in parallel – each with its own URL, ideally with its own data layer. The contrast with the old model is the whole point: ```mermaid graph LR subgraph Classic["One staging for all"] A[PR 1] --> S[Shared Staging] B[PR 2] --> S C[PR 3] --> S S --> Q[Queue and conflicts] end subgraph Ephemeral["Preview per PR"] D[PR 1] --> P1[preview-1.example.com] E[PR 2] --> P2[preview-2.example.com] F[PR 3] --> P3[preview-3.example.com] end ``` ## Declarative instead of a script graveyard The most elegant approach describes the environment declaratively instead of assembling it from a chain of shell steps. Heroku shows how with an `app.json`: everything a review app needs – add-ons, migrations, feature flags – sits in one place, versioned in the repository. ```json { "name": "my-app", "environments": { "review": { "addons": ["heroku-postgresql:hobby-dev"], "scripts": { "postdeploy": "bundle exec rake db:migrate db:seed" }, "env": { "FEATURE_FLAGS": "preview" } } } } ``` The appeal lies in the `postdeploy` hook: every preview gets a fresh database, migrates the schema and loads seed data. This makes the environment reproducible from nothing – and that is exactly what makes it disposable. If you aren’t on a PaaS like Heroku or Netlify, you build the same pattern yourself with GitHub Actions. The three steps stay the same: build, deploy into an isolated instance, write the URL back into the PR. How the deploy script works internally – whether it talks to a container host, spins up an app on your own platform or ships a static bundle – is secondary for this skeleton; what matters is the clean contract of name, image and host. ```yaml name: preview on: pull_request: types: [opened, synchronize, reopened] jobs: deploy-preview: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Build and push image run: | docker build -t registry.example.com/app:${{ github.sha }} . docker push registry.example.com/app:${{ github.sha }} - name: Deploy preview instance run: | ./scripts/deploy-preview.sh \ --name "pr-${{ github.event.number }}" \ --image "registry.example.com/app:${{ github.sha }}" \ --host "pr-${{ github.event.number }}.preview.example.com" - name: Comment preview URL run: | gh pr comment ${{ github.event.number }} \ --body "Preview ready: https://pr-${{ github.event.number }}.preview.example.com" env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` Teardown is just as important as deployment. A preview that nobody cleans up is not a feature but a cost center. That is why a second workflow belongs with it, cleaning up when the PR is closed: ```yaml name: preview-teardown on: pull_request: types: [closed] jobs: destroy-preview: runs-on: ubuntu-latest steps: - name: Tear down environment run: | ./scripts/destroy-preview.sh --name "pr-${{ github.event.number }}" ``` Whether the deploy target is a Kubernetes namespace, a Heroku app or a static Netlify build doesn’t matter conceptually. The pattern is portable: PR opens, instance comes up, URL lands in the PR, merge cleans up. ## Ephemeral environments as a test bench An isolated, production-like instance is more than a click-through preview. It is a clean place to run automated checks against a real deployment – not just against mocks. Two examples that prove themselves in practice: Contract tests with Pact check whether a service still meets the expectations of its consumers. Verified against a real, running PR instance, that is more meaningful than against a stub. And architectural fitness functions, as Ford, Parsons and Kua describe them in *Building Evolutionary Architecture* (2017), can be armed against the running preview: response times, dependency rules, bundle sizes. This turns the preview into a gate that answers not only “looks good” but “sticks to the rules”. Feature flags complete the picture. A preview with `FEATURE_FLAGS=preview` set shows the target state while the same change stays dark in production – review and rollout are decoupled. If you take the flag idea seriously, you can merge a change several times without enabling it and take it live later via a toggle. That reduces long feature branches and fits the trunk-based idea: integrate, make visible, roll out in a controlled way. The line of thought behind this is the same as with blue-green or canary: you separate “deployed” from “visible to everyone”. In this sense, a preview is a canary for exactly one reviewer – the smallest conceivable rollout stage. Once you have internalized this separation, you no longer think of deployment and release as the same step, and that is one of the most effective reliefs for a team that wants to ship often and calmly. ## Where it really hurts None of this is frictionless. The hard part is never deploying the web process – it is everything underneath. The data layer is the hardest. If all previews share one database, they contaminate each other: one PR migrates a schema, another trips over it. A database per PR solves this, but costs provisioning time and money – and every migration has to run cleanly from zero. That, by the way, is an underestimated side effect: if you take previews seriously, you also test your migration path on a greenfield with every PR. Migrations that only work on grown datasets show up immediately here instead of surprising you at the next fresh setup. External services make the picture even sharper: payments, email delivery, third-party APIs must never fire for real from a preview. That takes sandbox modes or stubs, and they have to be configured before the first reviewer clicks – otherwise the preview of a marketing feature accidentally sends real emails to real addresses. The second perennial issue is the lifecycle. Forgotten environments cost money and drift away from the current state. The teardown on merge or close has to work reliably, supplemented by a TTL or an idle shutdown for PRs that stay open for weeks. A single close event that never fired – say, because a PR was deleted into the void – must not leave an orphaned instance behind, so in addition to event-driven teardown you need a regular cleanup job that sweeps by age or inactivity. And the feedback advantage flips when the build takes ten minutes: cold starts and long pipelines undermine exactly what you build the whole thing for. A fast, aggressively cached build is the precondition for the short loop to stay short at all. Third, secrets and access. Preview URLs are often public and guessable – `pr-42.preview.example.com` is not a security boundary. Unprotected, such previews leak unfinished features or real data. Secrets have to be injected securely, access belongs behind basic auth, SSO or password protection. Netlify offers password protection for deploy previews for exactly this reason. And finally, config skew. A preview is only useful if it is close to production. If it deviates too much, you get the worst of all outcomes: green review, red prod deploy. Then the environment has created trust it couldn’t back up. The countermeasures are unspectacular but effective: pass the same container image through from the preview all the way to production, control configuration consistently through environment variables instead of diverging build paths, and keep the few deliberate differences – sandbox endpoints, smaller resources, active feature flags – visible in one place. The closer the preview is to production, the more a green review is actually worth. ## The common thread In 2021, preview environments per pull request are common, productized practice – from Heroku through GitLab and Netlify to Vercel. The core is the same everywhere and told in a few sentences: the PR creates an isolated, disposable instance with its own URL, every new commit deploys again, the merge cleans up. The gain is the shorter and more honest feedback loop. Reviewers judge running behavior instead of lines in the diff. Non-developers can have a say. Small batches are rewarded, the staging jam disappears. That is the *Accelerate* logic in its purest form: friction out, cycles shorter, quality visible earlier. Getting started is therefore unspectacular: start with the outcome, not with the platform. The hard questions are the database, the lifecycle and access protection – not deploying the web process. If you solve them cleanly, you get reviews you click through instead of imagining. And that is the difference between “LGTM” and “I’ve seen it”. ## Further reading - [Heroku Review Apps](https://devcenter.heroku.com/articles/github-integration-review-apps) - [Netlify: Introducing Deploy Previews (2016)](https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/) - [GitLab Review Apps](https://docs.gitlab.com/ci/review_apps/) - [Vercel: Every push now receives a unique URL](https://vercel.com/changelog/every-push-now-receives-a-unique-url) - [Using the Four Keys to measure your DevOps performance (DORA)](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance) - Forsgren, Humble, Kim: *Accelerate* (2018) - Humble, Farley: *Continuous Delivery* (2010) - Ford, Parsons, Kua: *Building Evolutionary Architecture* (2017) --- # Jamstack as an Architecture Style for Web Applications URL: https://www.mikebild.dev/en/blog/jamstack-as-an-architecture-style/ Date: 2021-11-15 You can’t pull Jamstack into a project with `npm install`, and you can’t buy it anywhere either. It is an architecture style for web applications that emphasizes pre-rendering and decoupling the UI from services. That is why the decision is also made one level above the choice of the next framework. That is exactly where Jamstack comes in. The name was originally formed from **JavaScript, APIs and Markup**. Matt Biilmann and Chris Bach coined it at Netlify; Biilmann made it publicly known in 2015/2016. As early as 2021, Jamstack was used more broadly than the acronym. Two principles have remained: pre-rendering and decoupling. Instead of generating fresh HTML on the server for every request, markup is built in advance and delivered via a CDN; dynamic parts access APIs separately. ## The paradigm shift: classic SSR versus Jamstack To understand why this matters, it is worth looking at the classic model. With server-side rendering in the traditional sense, the same thing happens on every page view: the browser sends a request, an application server receives it, queries a database, assembles HTML from it and sends it back. Every single visitor triggers this chain again. That is proven, but it ties up server capacity per request and makes the app server both the bottleneck and the attack surface. Jamstack reverses this order. The work no longer happens per request but once, at build time. A static site generator pulls content from data sources, renders finished HTML pages from it and stores them as static files. These files land on a CDN and are delivered from there globally, close to the user. Whatever has to be dynamic – a shopping cart, a login, a search – is loaded afterwards on the client side via APIs. ```mermaid flowchart LR subgraph Classic["Classic SSR"] B1["Browser"] -->|"Request"| S1["App server"] S1 --> DB[("Database")] DB --> S1 S1 -->|"HTML per request"| B1 end subgraph Jam["Jamstack"] B2["Browser"] -->|"static page"| CDN["CDN
    (pre-rendered)"] B2 -->|"dynamic parts at runtime"| API["APIs /
    Serverless"] end ``` A clarification that regularly gets lost in discussions: Jamstack doesn’t forbid server-side rendering. It shifts the default case. Instead of “every page per request on the server”, it’s “every page once in the build” – and where it is really needed, I can still use server-side rendering selectively. That is exactly what the next section is about. ## Static site generators and hybrid rendering The engine of Jamstack is the static site generator. In the simplest case, it is a process that reads content and writes HTML from it. A deliberately reduced example makes the principle tangible – Markdown in, HTML out: ```jsx import { loadMarkdown, renderToHtml, writeFile } from "./ssg"; for (const post of loadMarkdown("content/**/*.md")) { const html = renderToHtml(post); writeFile(`dist/${post.slug}/index.html`, html); } ``` In practice, mature tools take care of this. Gatsby, for example, is a React-based generator with a GraphQL data layer and a large plugin ecosystem. Next.js – currently at version 12, released at the end of October 2021 with a new, much faster Rust compiler based on SWC – offers several rendering modes side by side. And SvelteKit, which has been in public beta since spring 2021, takes the same route with an adapter concept. SvelteKit should deliberately still be considered young; it is pre-1.0 and in beta, but the direction is already clearly visible. The decisive point of modern generators is that I don’t set the rendering globally but decide per page or route. Next.js is a good example for sorting this out: - SSG (Static Site Generation) via `getStaticProps` and `getStaticPaths` renders the page in the build; afterwards it is pure markup from the CDN. - SSR (Server-Side Rendering) via `getServerSideProps` generates the page per request on the server, for truly dynamic content. - ISR (Incremental Static Regeneration), available since version 9.5 from 2020, rebuilds a static page in the background based on time or events. - CSR (Client-Side Rendering) via hooks and data libraries such as SWR loads the data only in the browser. A typical SSG pattern with a touch of ISR looks like this: ```ts export async function getStaticProps() { const posts = await fetchFromCMS(); return { props: { posts }, revalidate: 3600, // ISR: regenerate at most once per hour }; } ``` The `revalidate` is the transition from purely static to hybrid: the page stays static and CDN-fast but doesn’t go stale, because it renews itself after the specified time. In my experience, this mix – static where possible, server-side or client-side where necessary – is the realistic normal case, not the pure doctrine. ## CDN and performance Why all the effort? Because pre-rendered assets from the CDN often reach the user faster. Instead of a computation chain of server and database, a nearby edge location delivers a finished file. That can improve time to first byte (TTFB) significantly. For interactivity, though, finished markup alone isn’t enough: a lot of JavaScript and expensive hydration can eat the advantage up again. That’s why I measure delivery and interactivity separately instead of crediting both to pre-rendering. Then there is the effect on SEO. With pre-rendered markup, search engines immediately see the complete content without depending on client-side loading. For content-driven sites – blogs, documentation, marketing – that is a real advantage I wouldn’t subordinate to pure loading speed. I want to clear up a common misunderstanding here: the CDN delivers the static assets, not the APIs. The dynamic data still comes via API requests – either directly from the frontend or via an upstream frontend API. So the CDN speeds up delivery of the skeleton, while the dynamic parts are served separately. ## Decoupling and API orchestration That brings us to the second big principle: decoupling. In Jamstack, delivering the frontend and dynamic data access are separate. The backend can still be one cohesive application or consist of several services; what matters is that the frontend accesses it via APIs during the build or at runtime. Authentication can be handled by an external service, content can come from a headless CMS, and your own business logic can live in serverless functions. These are common building blocks, not a definition of the architecture. The exciting question then is where all these APIs come together. Two ways have become established. Either I orchestrate directly in the frontend, with the components querying the endpoints they need themselves: ```jsx import useSWR from "swr"; const fetcher = (url) => fetch(url).then((res) => res.json()); function Cart() { const { data, error } = useSWR("/api/cart", fetcher); if (error) return

    Failed to load

    ; if (!data) return

    Loading…

    ; return ; } ``` Or I put a frontend API in front – often via GraphQL, for example with AWS AppSync or the GraphQL endpoint of a headless CMS. The frontend then makes a single, consolidated request, and orchestrating the services behind it happens one layer deeper. For larger applications with many data sources, I prefer this route because it relieves the frontend of detailed knowledge about every single backend. The serverless functions themselves are deliberately lean and stateless. A handler in Netlify or Lambda style typically looks like this: ```js exports.handler = async (event, context) => { const { name } = JSON.parse(event.body); return { statusCode: 200, body: JSON.stringify({ message: `Hello ${name}` }), }; }; ``` The economic appeal behind this can be the billing model: pay-per-execution. Depending on the platform, base fee and load profile, you pay more for actual invocations and compute time than for permanently provisioned servers. The provider also largely takes care of scaling within its limits. Runtime limits, distributed failures, quotas and the cost of individual invocations still remain architecture questions. ## Build and CI: the Git push as the trigger The pre-rendering has to happen at some point, of course. Often a Git push starts a CI pipeline – for example via GitHub Actions – that runs the static site generator and puts the result on a CDN. Many specialized platforms publish these artifacts atomically and versioned, so that a new version becomes active as a whole and can be rolled back. That is a property of the chosen deployment system, not automatically of every Jamstack build. ```mermaid flowchart LR Dev["git push"] --> CI["GitHub Actions
    (CI)"] CI --> SSG["Static Site Generator
    (Build)"] SSG --> Deploy["atomic deploy"] Deploy --> CDN["CDN
    (global edge)"] CDN --> User["User"] SSG -.->|"large catalog"| Shard["Sharding /
    parallel builds"] Shard --> Deploy ``` A simple workflow that does exactly this is quickly written down: ```yaml name: build-and-deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 with: node-version: "16" - run: npm ci - run: npm run build - run: npx netlify deploy --prod --dir=dist ``` For small sites, the build is done in seconds. For large catalogs with many thousands of pages, the build time itself becomes an issue – sharding helps here, splitting the build into parallel subprocesses. That is also a good transition to the limits I address further below. ## Security and operational benefits A side effect of the architecture that is easily overlooked concerns security. If no application server is hit per request at runtime, the attack surface shrinks considerably. No monolithic server that runs database queries on every request and becomes vulnerable in the process. What gets delivered are static files, and the dynamic parts sit in clearly delimited APIs that can each be secured individually. All in all, this yields a handy list of benefits: - TTFB can drop because pre-rendered markup comes straight from the edge; interactivity additionally depends on the JavaScript delivered. - For static pages, there is no application server per read; the APIs remain an attack surface of their own. - CDN and platform can take over a large part of the scaling, each within their quotas and runtime limits. - Pay-per-execution can save costs with a fitting load profile, but it isn’t inherently cheaper. - The developer experience benefits from clear separation, Git-based deploys and fast rollbacks. ## Three case studies from practice So this doesn’t stay theoretical, here are three scenarios that I almost read as maturity levels in this order. The first is the static blog or portfolio. This is where Jamstack plays to its strengths: content is rendered in the build, there is hardly any dynamic behavior, and the CDN can deliver it without an application server. For this class of projects, pure SSG is often already the complete answer. The second scenario is B2C e-commerce. As soon as sessions, shopping carts and transactions come into play, purely static is no longer enough. Product pages can be pre-rendered statically very well and delivered via the CDN, while the cart, checkout and user account are served on the client side via APIs. That is the classic hybrid case, where ISR additionally helps keep product data up to date without rebuilding every page per request. The third scenario is B2B, SaaS and IoT applications. Dashboards, personalized views and real-time data dominate here. A static skeleton can contribute to a fast initial delivery; protected areas can be rendered on the client, on the server or hybrid, depending on the product. A GraphQL frontend API can also make sense if several data sources really do have to be bundled for the UI. ## Where Jamstack hits its limits As convincing as the model is, I stay honest about the edges. Pure SSG doesn’t scale indefinitely. With a few thousand pages, build time slowly becomes relevant; with millions of pages, pre-rendering everything simply becomes impractical. This is exactly where the tools already mentioned come in: ISR only re-renders what really changes; hybrid rendering allows server-side generation for rarely visited or highly dynamic routes; and sharding spreads large builds across parallel processes. Sobriety also pays off when choosing tools. SvelteKit is promising at the end of 2021 but still in beta. Azure Static Web Apps has only been generally available since May 2021 and is therefore also quite young, but it integrates Azure Functions directly as a backend. Fast build building blocks such as esbuild by Evan Wallace speed up the pipeline enormously but are themselves still pre-1.0. If you build here, you choose deliberately between established and up-and-coming. ## Conclusion To me, Jamstack is less a technology than a stance on architecture. It moves suitable work from the request into the build and separates delivering the frontend from dynamic data access. Whether an enterprise application, several services or serverless functions sit behind it is a separate decision. Fast delivery via the CDN, a smaller runtime surface and simple deployments can follow from it if the application and platform fit. What matters is that Jamstack stays open to technology. It doesn’t prescribe a framework but a way of thinking, within which I can use Next.js, Gatsby or SvelteKit just as well as Netlify, Vercel or Azure. And it isn’t dogma: pure SSG for the blog, hybrid for the shop, server-side plus API orchestration for the SaaS platform. With this gradation, the architecture decision is made where it belongs – one level above the framework. ## Further reading - Mike Bild: “JAMstack-Architektur” – the detailed original article: https://www.developer-world.de/dwx-insights/architecture-patterns/jamstack-architektur - Official Jamstack resource: https://jamstack.org/ - [Jamstack: definition and origin of the name](https://jamstack.org/what-is-jamstack/) - Next.js 12 (release from October 26, 2021): https://nextjs.org/blog/next-12 - SvelteKit Public Beta: https://svelte.dev/blog/sveltekit-beta - Azure Static Web Apps GA (May 2021): https://www.infoq.com/news/2021/05/azure-static-web-apps-ga/ --- # Serverless Transactional Email: SES and Lambda URL: https://www.mikebild.dev/en/blog/serverless-transactional-email-with-ses-and-lambda/ Date: 2021-11-09 A `SendEmail` call carries up to 50 recipients and 10 MB of message. An incoming SES event carries zero bytes of email text: it delivers headers and metadata, and the body sits in S3. These two numbers say more about the service than any feature list – the outgoing direction is done in half an hour, the incoming one has its own rules that you need to know. Behind this lies a decision that sounds like configuration to the team: “So how do we send out the confirmation email now?” Often there is already a signup flow, maybe with user management as in [Serverless Auth with Cognito User Pools](https://www.mikebild.dev/en/blog/serverless-auth-with-cognito-user-pools/), and the email looks like the last, trivial building block. That is exactly where the mistake lies. The real question is: Do I treat email as an external Side Effect that I stick onto the end of a flow, or as a full domain event – in and out – that deserves the same treatment as an API call or a queue message? This choice decides whether the email part later fits cleanly into the architecture or causes friction as a foreign body. SES – the Simple Email Service – is instructive because it serves both directions with the same building blocks: Lambda on one side, Receipt Rules on the other. The leverage is not in the API fields but in this symmetry. Below I walk through both directions – first the outgoing confirmation email from a function, then the incoming email hook that turns a real email into, for example, a support ticket. The code is deliberately lean so that the common thread – event in, event out – stays visible. ## SES as a building block in two directions Before we write code, it pays to look at the mental model. SES sits at the system boundary between your application and the outside world of email. Outward: your app triggers an event – a new account, a paid order – and a Lambda Function calls `SendEmail`. Inward: someone sends an email to one of your addresses, and SES processes it further via so-called Receipt Rules, for example to S3, to SNS or directly to a Lambda Function. This symmetry is the core. As soon as SES shows up in the design as an event-driven building block, it fits cleanly into the rest of the serverless architecture. If it stays a mere “email sender,” it ends up bolted on from the outside. The outgoing direction is the more common one and the easier place to start. - Outgoing: `SendEmail` or `SendTemplatedEmail`, a verified sender, sandbox and quota in view, triggered by an app event. - Incoming: a Receipt Rule Set with actions for S3, Lambda or SNS, available only in certain regions, triggered by an arriving email, body loaded afterward from S3. Let’s keep these two lines in mind – they structure the rest of the article. ## Email as a domain event, not as SES configuration The difference sounds academic, but it has real consequences. If you see SES as a configuration task, you stop at “sender verified, `SendEmail` works.” If you model email as a domain event, you keep asking: Which business event triggers this email, and which event does an arriving email create in my system? “I send a message” becomes “a signup happened,” and “someone emailed” becomes “a support case came in.” The email is then only the transport, not the event itself. This perspective costs something and gives something. The price is extra care at the system boundary: verified identities, an active rule set, correct permissions, the knowledge that incoming bodies sit in S3. The return is connectability. An event can be passed on, orchestrated, logged and tested – a “sent email,” on the other hand, is a dead end. A few decision criteria help with the question of whether SES is the right building block: - Coupling and control: SES stays entirely within AWS and IAM, with no second provider and no additional contract. In return, you carry the regional restriction on receiving and the MIME parsing yourself. - Cost: SES bills per thousand emails and costs nothing when idle. A specialized transactional provider brings better deliverability tools and ready-made templates, but also its own bill and a second system that someone has to operate. - Impact: Only when the incoming email is a real event can you automate the follow-up – classification, assignment, draft reply. That is exactly what shortens the cycles that otherwise depend on manual triage. As long as email is an event source and sink inside an AWS architecture, SES is the choice with the least friction. As soon as marketing deliverability, bounce analytics and campaign tooling come to the fore, a dedicated provider is the more honest choice. For the transactional core – confirmation out, ticket in – the event-driven SES building block wins. ## The outgoing confirmation email Let’s start with the outgoing direction. A Lambda Function is triggered by an event – say, an API Gateway call after a successful registration – and is supposed to send a short confirmation email. The following diagram shows the path of the event. The event comes in, the Lambda Function translates it into a `SendEmail` call, and SES accepts the message. That is not yet a delivery guarantee: bounces and complaints run through their own SES events. If the triggering event is repeated, the email can also be sent twice. For a production flow, I therefore need a stable event key and a stored sending status or an outbox. ```mermaid flowchart LR A[Event: Signup] --> B[Lambda: sendConfirmationEmail] B --> C[ses:SendEmail] C --> D[Recipient Inbox] ``` The corresponding handler is manageable. Here I use the AWS SDK for JavaScript version 3, that is, the modular `@aws-sdk/client-ses` packages – the established version 2 with `new AWS.SES()` works just as well, but for new functions its import is simply too monolithic for my taste. ```ts import { SESClient, SendEmailCommand } from "@aws-sdk/client-ses"; const ses = new SESClient({ region: "eu-west-1" }); export async function sendConfirmationEmail(event: { email: string; name: string; }) { const command = new SendEmailCommand({ Source: "no-reply@example.com", Destination: { ToAddresses: [event.email], }, Message: { Subject: { Data: "Willkommen bei uns", Charset: "UTF-8", }, Body: { Html: { Data: `

    Hallo ${event.name}, dein Konto ist aktiv.

    `, Charset: "UTF-8", }, }, }, }); const result = await ses.send(command); return { messageId: result.MessageId }; } ``` Three things are mandatory here and therefore deserve a closer look. `Source` is the sender address and must be a 7-bit ASCII address of a verified identity. `Destination` groups the recipients into `ToAddresses`, `CcAddresses` and `BccAddresses`. `Message` carries `Subject` and `Body`, where the body can contain text and HTML, each as an object of `Data` and `Charset`. What comes back is a `MessageId` – the only receipt you get for a successful call. Optionally, you can add quite a bit more, such as `ReplyToAddresses` or a `ConfigurationSetName`, but for the confirmation email what is shown is enough. ### Verified senders, sandbox and quota The code is rarely the stumbling block. There are three organizational points you need to settle beforehand. First, the sender identity. SES only sends from verified senders. You can verify a single address or – much more sensible for production – an entire domain via DKIM and TXT records in DNS. If the sender is not verified, SES answers the call with “Email address not verified,” and the email does not go out. Second, the sandbox. Every new SES account starts in the sandbox. That means you may only send to verified recipients or to the SES Mailbox Simulator, and the sending quota is reduced. The confirmation email to a real customer therefore fails in the sandbox as long as their address is not verified itself. For production use, you have to request production access via a support case. Third, the quota. Every recipient of a message counts against your sending allowance. A `SendEmail` call may address at most 50 recipients across `To`, `Cc` and `Bcc` combined, and the message may be up to 10 MB in size. For demos and tests, the Mailbox Simulator is worth its weight in gold. A call to `success@simulator.amazonses.com` behaves like a successful delivery, without you running into sandbox limits or burdening real mailboxes. ### Templates instead of string concatenation As soon as more than one kind of email is involved, assembling HTML in code gets messy. SES offers server-side templates for this. You create a template once with `CreateTemplate` – with `SubjectPart`, `TextPart` and `HtmlPart`, containing placeholders in double curly braces – and then send with `SendTemplatedEmail`. ```ts import { SESClient, SendTemplatedEmailCommand } from "@aws-sdk/client-ses"; const ses = new SESClient({ region: "eu-west-1" }); export async function sendWelcome(email: string, name: string) { const command = new SendTemplatedEmailCommand({ Source: "no-reply@example.com", Destination: { ToAddresses: [email] }, Template: "WelcomeTemplate", TemplateData: JSON.stringify({ name }), }); return ses.send(command); } ``` `TemplateData` is a JSON string whose keys fill the placeholders in the template. The advantage: the text no longer lives in the deployment artifact but sits as a resource in SES and can be updated independently of the code. For many recipients at once, there is also `SendBulkTemplatedEmail` – in a transactional context, though, you rarely need it, because there one email usually goes to one person. ## The incoming email hook Now we reverse the direction. The second, often overlooked capability of SES: it can receive arriving emails and turn them into an event in your architecture. This is the basis for patterns such as “an email to support@ automatically becomes a ticket.” This is managed through a Receipt Rule Set. There can be several rule sets per account, but only one is ever active. Inside a rule set, you define individual Receipt Rules that match certain recipient addresses and work through a list of actions. Available actions include: storing in an S3 bucket, publishing to an SNS topic, invoking a Lambda Function, adding a header, a bounce or a stop. The usual setup for a ticket flow combines two actions: first the raw email is written to S3, then a Lambda Function is triggered that takes care of the processing. ```mermaid flowchart LR A[Incoming Mail] --> B[SES Receipt Rule] B --> C[S3: raw MIME] B --> D[Lambda: handleInboundEmail] D --> E[Ticket / DB] B -.-> F[SNS Notification] ``` ### The Receipt Rule as infrastructure The Receipt Rule itself belongs in Infrastructure as Code, not in a console setup clicked together by hand – otherwise it is gone after the next account switch. As a sketch in CloudFormation-like form, a rule looks roughly like this: ```yaml Resources: SupportRule: Type: AWS::SES::ReceiptRule Properties: RuleSetName: default-rule-set Rule: Name: support-inbound Enabled: true Recipients: - support@example.com Actions: - S3Action: BucketName: inbound-mail-bucket - LambdaAction: FunctionArn: !GetAtt InboundFn.Arn InvocationType: Event ``` Two details matter here. The order of the actions counts: the email must first be in S3, then the Lambda Function that reads it from there is called. And `InvocationType: Event` means an asynchronous call – that is the recommended variant. The synchronous `RequestResponse` call also exists, but it has a hard timeout of 30 seconds and lets the Lambda Function control the rest of the rule flow through its return value, for example with `{ disposition: "STOP_RULE" }`. For a ticket handler that does not want to control the email flow anyway, `Event` is the right choice. ### The handler and the most common mistake Let’s get to the handler – and to the pitfall that strikes most reliably in projects. The obvious assumption is that the Lambda event contains the email text. It does not. The event that SES passes to the Lambda Function carries only metadata and headers – sender, subject, message ID – but not the body. The complete MIME content lands in S3, and the handler has to load it from there. The event is built around a `Records` array, with `eventSource: "aws:ses"` and the fields `ses.receipt` and `ses.mail`. The latter contains the processed headers under `commonHeaders` and, under `messageId`, the key under which the raw email sits in S3. ```ts import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"; import { Readable } from "stream"; const s3 = new S3Client({ region: "eu-west-1" }); async function streamToString(stream: Readable): Promise { const chunks: Buffer[] = []; for await (const chunk of stream) { chunks.push(Buffer.from(chunk)); } return Buffer.concat(chunks).toString("utf-8"); } export async function handleInboundEmail(event: any) { const record = event.Records[0]; const mail = record.ses.mail; const messageId = mail.messageId; const raw = await s3.send( new GetObjectCommand({ Bucket: "inbound-mail-bucket", Key: messageId, }) ); const mime = await streamToString(raw.Body as Readable); // parse MIME, then create a support ticket await createTicket({ from: mail.commonHeaders.from?.[0], subject: mail.commonHeaders.subject, body: mime, }); return { status: "processed" }; } ``` I deliberately left out the actual MIME parsing here – you use a library for that, because parsing multipart emails with attachments by hand is not a good idea. The point is the flow: headers from the event, body from S3, then the business action. The S3 object can be up to 40 MB in size. ### Permissions and DNS, or nothing happens, silently The second pitfall on the receiving side is unspectacular and therefore treacherous: without the right permissions, SES simply and silently does not process arriving email. SES needs a resource policy that allows it to write to the S3 bucket, publish to the SNS topic or invoke the Lambda Function. If one of these permissions is missing, there is no loud error message – the email just seeps away. Then there is DNS. For email to reach SES at all, the MX records of your domain must point to `inbound-smtp..amazonaws.com`. And there is a hard regional restriction: SES offers email receiving only in selected regions – as of today us-east-1, us-west-2 and eu-west-1. Lambda and SNS for the incoming flow must be in the same region as the SES endpoint. If you run the rest of your infrastructure in a different region, you have to move this part there deliberately. ## Where SES fits into the larger architecture Together, the two directions make a nice picture: Lambda is the shared compute core, SES the system boundary to the world of email. Outward, a function translates app events into emails; inward, SES translates arriving emails into function calls. It gets interesting when the incoming hook is not the end but the beginning of a longer processing chain. A support email that gets parsed can kick off a chain of steps – classification, assignment, draft reply. This is exactly where orchestration is worth a look, as I described it in [Serverless Workflows with AWS Step Functions](https://www.mikebild.dev/en/blog/serverless-workflows-with-aws-step-functions/): the SES Lambda creates the ticket and hands over to a State Machine that coordinates the rest. That way the email hook stays small and does exactly one thing, while the domain logic gets its own traceable flow. ## Conclusion The aha moment with SES lies in the incoming direction: when it becomes clear that arriving email is not a special case but an entirely normal event trigger – just like an API call or a queue message. The outgoing side is quickly explained: verified sender, `SendEmail` or a template, keep sandbox and quota in mind. The incoming side needs more care: an active rule set, the right permissions, MX records and the knowledge that the body sits in S3 and not in the event. The gain from this perspective is concrete. Shorter cycles, because an incoming email hook kicks off follow-up work instead of parking it in a mailbox. Less friction, because email follows the same event-driven rules as the rest of the architecture and does not stand beside it as a foreign body. Higher quality, because a modeled event is testable, loggable and orchestratable, where a loosely sent email remains a dead end. And clear limits: as soon as deliverability at scale, bounce analytics or campaigns come to the fore, a specialized provider is the more honest choice – SES shines in the transactional core. Once you have built these two patterns cleanly, you no longer think “how do I send an email” but “email is simply another event source and sink” – in and out. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-aws-serverless.en.html - Repository: `introduction-aws`, chapter `ses.md` and `examples/email-hook` - [SendEmail (SES API Reference)](https://docs.aws.amazon.com/ses/latest/APIReference/API_SendEmail.html) - [SendTemplatedEmail (SES API Reference)](https://docs.aws.amazon.com/ses/latest/APIReference/API_SendTemplatedEmail.html) - [Creating verified identities](https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html) - [Email receiving – concepts](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-concepts.html) - [Invoke Lambda action](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-action-lambda.html) - [Example of an incoming email event](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-action-lambda-event.html) - [Deliver to S3 action](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-action-s3.html) - [Permissions for email receiving](https://docs.aws.amazon.com/ses/latest/dg/receiving-email-permissions.html) --- # State Management in React: Redux Toolkit, Lightweight Stores, MobX URL: https://www.mikebild.dev/en/blog/state-management-in-react/ Date: 2021-10-26 # State Management in React: Redux Toolkit, Lightweight Stores, MobX A global store is not part of the basic equipment of a React application. It’s the exception you have to justify. That’s what the React overview said, where the question of ownership was the focus – where does a piece of state belong? What remained open there was what to use when a piece of state actually passes the justification, that is, when it really is app-wide. I had promised the comparison. Here it is. **Editorial note (July 2026):** The tools part is a snapshot from October 2021: Redux Toolkit 1.x, Zustand 3.x, Jotai 1.x and MobX 6. The more important separation is less transient: URL state, server cache and your own client state have different owners. Current versions can change the ergonomics, not these responsibilities. Before we talk about tools, though, I have to hit the brakes. The question “Redux, Zustand or MobX?” is usually asked much too early – at a point when it isn’t even clear whether a store is needed at all. On closer inspection, the supposedly global state often turns out not to be global at all. That’s why the counter-check comes first, and only then the actual comparison. Not every kind of state needs the same storage. The choice starts with ownership, lifetime and the need for synchronization. ::::comparison{title="Classifying state by responsibility" role="primary" preferredPattern="comparison-matrix"} :::side{label="Local UI state"} - Owner · one component or a limited subtree - Lifetime · tied to the rendering - Examples · open dialog and input focus ::: :::side{label="Shared client state"} - Owner · several areas of the UI - Lifetime · within the application session - Examples · local selection and unsaved work in progress ::: :::side{label="Server state"} - Owner · backend or domain system - Lifetime · independent of the browser - Examples · records, permissions and approved revisions ::: :::: The matrix doesn’t recommend a library. First of all, it keeps server data from being treated like local state, or short-lived UI details like global domain objects. ## The counter-check first In a project that “absolutely needed a global store,” we first wrote down everything that was supposed to go into it – and then started crossing things out. A surprisingly large part of it was really URL state: filter, page, selection or tab, insofar as they should be shareable, navigable or bookmarkable. Short-lived display details may stay local. A store that additionally holds navigable values, on the other hand, easily builds up a second truth next to the address. The next big block is even trickier, because it looks like state and feels like state: loaded data. The list of invoices, the user profile, the search result. These are cache copies of something whose truth belongs to the backend. That calls for server cache semantics such as keys, freshness, invalidation and error states – whether a specialized library provides them or, say, RTK Query within the Redux store. The problem isn’t the physical storage location but a hand-managed slice that rebuilds these semantics. Take these two blocks out – navigable state into the address, server data into a cache – and often little is left. The real app-wide client state can be a small core: theme, language, a local draft or a shopping cart, insofar as its truth really lives in the client. Identity and permissions, on the other hand, usually come from the server; locally there is only their cache copy. For the remaining core, a store pays off, and because this core is small, the tool may be small too. ```mermaid flowchart TB Start["A value that looks like
    global state"] Start --> Global{"Really app-wide,
    or only needed locally?"} Global -->|only one corner| Lokal["useState / useReducer
    in the component"] Global -->|app-wide| URL{"Does it belong in the URL?
    filter, page, selection"} URL -->|yes| Adresse["Router / URL
    shareable, survives reload"] URL -->|no| Server{"Does the truth belong
    to the backend?"} Server -->|yes| Cache["Server cache
    TanStack Query / SWR"] Server -->|no| Store["Real core: only
    now choose a store"] ``` Everything depends on the order. If you start with the tool question, you fill the store with things that have no business being there and later wonder about synchronization bugs. If you start with the counter-check, you often get by with `useState` and the URL and don’t need a store at all. Only when a core remains after crossing things out is the rest of this post worth it. ## Three families for the real core Suppose this core exists. Then there are roughly three schools of thought on how to hold app-wide state. I show each with a tiny example and say honestly what it costs – because none of them is free. ### Redux Toolkit: the classic model, slimmed down Redux has a clear model: there is exactly one store, one central state tree. You never change it directly; you send actions – descriptive messages such as “increment” – and pure functions called reducers compute the new state from the old state plus the action. For years, this model earned Redux a reputation for being cumbersome: lots of ceremony, action types as constants, boilerplate for every little move. Redux Toolkit – RTK for short, today the officially recommended way to write Redux – takes exactly this ceremony away. A `createSlice` bundles state, actions and reducers in one piece. The reducer code is remarkable: it looks as if you were mutating the state directly, but it stays immutable internally, because RTK uses the Immer library, which turns the apparent mutations into a clean new copy. ```js import { configureStore, createSlice } from "@reduxjs/toolkit"; const cartSlice = createSlice({ name: "cart", initialState: { items: [] }, reducers: { addItem(state, action) { // looks mutable, stays immutable via Immer state.items.push(action.payload); }, clear(state) { state.items = []; }, }, }); export const { addItem, clear } = cartSlice.actions; export const store = configureStore({ reducer: { cart: cartSlice.reducer } }); ``` `configureStore` sets up the store with sensible defaults – the DevTools are already connected, common middleware is included. In TypeScript, you additionally create type-safe hooks once (`useAppSelector`, `useAppDispatch`) so that state and actions are typed throughout. RTK’s strength lies in traceability. Every state change is a named action that runs through a reducer – a loggable, reproducible transition. The DevTools show every action in order, allow time travel through the state history and turn “why is this value suddenly here?” into a question you can answer instead of guess. In large teams and with complex flows, that’s worth its weight in gold: the state flow is a convention everyone shares, not a matter of personal style. The price should be named just as honestly: more structure, more files, a central tree that everything runs through. For the small core of a medium-sized application, that is often more apparatus than the core deserves. ### Lightweight Stores: Zustand and Jotai The second family starts exactly there: minimal API, no forced provider, as little code as possible. Two representatives from the same ecosystem, but they think differently. Zustand (yes, the library really is called that – a German word for “state” as its name) gives you a `create` function that returns a hook. From this hook you use a selector to read exactly the slice of state a component needs. The selector is the key: a component that only reads `count` doesn’t re-render when another field in the store changes. Re-renders stay granular without you having to nest context providers. ```js import { create } from "zustand"; const useCartStore = create((set) => ({ items: [], addItem: (item) => set((state) => ({ items: [...state.items, item] })), clear: () => set({ items: [] }), })); // in a component: read only what you need const count = useCartStore((state) => state.items.length); ``` Jotai approaches it from the other side. Instead of one store you read slices from, there are many small, atomic units of state – atoms – that you combine freely. An atom holds a value; derived atoms compute from other atoms. A component subscribes to exactly the atoms it reads, and nothing more. ```js import { atom, useAtom } from "jotai"; const itemsAtom = atom([]); const countAtom = atom((get) => get(itemsAtom).length); // in a component const [count] = useAtom(countAtom); ``` The strength of both is obvious: very little code, fine-grained updates, a small bundle. You’re productive in minutes, and there are hardly any concepts to learn. The price is the other side of the same coin – less convention, less predefined structure. Redux forces you into a pattern; a lightweight store leaves you every freedom, including the freedom to build yourself a mess. The discipline to keep the store small and orderly, and not to dump server data into it after all, lies with the team. For the small core this is about, that is often exactly the right size. ### MobX: the reactive approach The third family thinks fundamentally differently. Redux and the lightweight stores are immutable at their core: changing state means producing a new state. MobX turns that around. You describe observable state, mutate it directly, and the library tracks on its own who reads what and updates exactly the places concerned. You make an object observable with `makeAutoObservable`. You declare derived values as `computed` – here as getters – and they update by themselves as soon as their basis changes. Components you wrap in `observer` react specifically to exactly the observed values they read while rendering. ```jsx import { makeAutoObservable } from "mobx"; import { observer } from "mobx-react-lite"; class CartStore { items = []; constructor() { makeAutoObservable(this); } addItem(item) { this.items.push(item); // direct mutation is fine here } get count() { return this.items.length; // derived, recomputes automatically } } const cart = new CartStore(); const CartBadge = observer(() => {cart.count}); ``` MobX shines when a lot of state is derived from other state. Where in Redux you would have to write and memoize selectors, in MobX the derived value comes about by itself and is only recomputed when its inputs change. Strikingly little code remains whose only job is to connect values. The price is implicitness: precisely because you don’t dispatch anything explicitly, the question “where does this change come from?” is harder to answer – the update happens in the background, triggered by a mutation somewhere in the code. And it’s a different mental model from the rest of the React ecosystem: targeted mutation instead of immutability. If you come from the Redux world, you have to rethink; if you think in objects, you feel at home immediately. ## What to base the choice on There’s no ranking that holds for everyone – the choice depends on a few properties of the project. The more people work on the same state, the more a fixed convention can help. For loggable transitions and rewinding the state history, the Redux DevTools are a strong but not exclusive solution. With a lot of derived state, MobX’s reactive model plays to its strengths. Add to that the bundle budget, existing tooling requirements and the team’s familiarity; hard judgments about size should be measured on the concrete build, not taken from a table. A few rules of thumb follow from this, without being laws. If the core really is small – a logged-in person, a theme, a shopping cart – [context with `useReducer`](https://www.mikebild.dev/en/blog/using-react-context-well/) or a lightweight store such as Zustand is enough, and more would be overkill. If a large team faces complex flows and wants auditable transitions, Redux Toolkit is the obvious choice, because it makes exactly this traceability a convention. If the application lives on a lot of derived state that should update in cascades, MobX is in its element. And if two options fit equally well, the team’s familiarity tips the balance. ## The choice is secondary No tool is “the best.” These comparisons are conducted with a seriousness the matter doesn’t deserve – as if the project’s success hinged on Redux versus MobX. It doesn’t. The choice of store is secondary to the question of ownership that comes before it. If you use the URL for what belongs in the URL and treat server data as a cache instead of as state, you keep the real client state so small that almost any of the three families is enough – and the decision between them shrinks to a matter of taste. The mistake the tool debate hides is the more expensive one: building a big global store and filling it with URL state and server data that don’t belong there. No Redux Toolkit and no MobX will save you from the bugs that result. Conversely, with cleanly drawn boundaries and the simplest of the lightweight stores, you get surprisingly far. That’s why the counter-check is at the beginning of this post and not at the end: it decides more than the three-column table after it. ## Further reading - Repository introduction-react (chapters react-hooks, state-management): https://github.com/mikebild/introduction-react - Redux Toolkit, official documentation: https://redux-toolkit.js.org/ - Zustand: https://github.com/pmndrs/zustand - Jotai: https://jotai.org/ - MobX: https://mobx.js.org/ --- # DynamoDB Data Modeling: Single-Table Design URL: https://www.mikebild.dev/en/blog/dynamodb-data-modeling-single-table-design/ Date: 2021-09-21 # DynamoDB Data Modeling: Single-Table Design When you define the partition key in DynamoDB, you have already decided which queries will be cheap later and which won’t work at all. There is no optimizer that rescues a clumsy choice after the fact, and no server-side join that connects two tables at runtime. The question “Where do I put the foreign keys?” simply has no answer – the relationship has to be in the key before the first item is written. That turns the familiar order around. With a relational database, I first design a clean, normalized model and think about the queries later; the optimizer makes sure most queries work somehow. With DynamoDB, I first write down which questions the application will ask of the data and derive the key schema from that. The data model is the result of these patterns, not their starting point. ## The three building blocks everything starts with Single-table design stands or falls with three basic building blocks. Until they are in place, every description of the pattern hangs in the air. A DynamoDB table has a primary key in one of two forms. Either a simple primary key – just a partition key (PK, historically “hash key”). Or a composite primary key made of partition key plus sort key (SK, “range key”). In the composite variant, the combination of PK and SK must be unique per item; the PK alone may repeat. That is exactly the lever for everything else. Through an internal hash, the partition key determines on which physical partition an item lands. The sort key orders the items within a partition and allows range conditions. All items with the same partition key form an item collection – and this item collection is the actual core of single-table design. The `Query` API always reads exactly one item collection, that is, exactly one PK value. Optionally, a condition on the sort key narrows the result, with operators such as `=`, `<`, `<=`, `>`, `>=`, `BETWEEN` or `begins_with`. One call returns up to 1 MB; after that, you paginate via `LastEvaluatedKey`. The opposite is the `Scan`, which goes through the whole table – something I practically never want in production. So the roles stay clear, here is the division of responsibilities at a glance: - The PK determines partition and distribution. Every query needs exactly one PK value – it decides which item collection gets read at all. - The SK orders and filters within the collection, through range conditions and `begins_with`. That is how I model one-to-many relationships and hierarchies. - A GSI (global secondary index) defines a new PK/SK combination for additional access patterns. It can be added at any time, is only eventually consistent and has its own throughput. The LSI (local secondary index) is the contrasting case: the same PK as the base table, just an alternative SK. It supports strong consistency, but it must be defined when the table is created and binds the item collection per PK to a 10 GB limit. When in doubt, I take the GSI. ## Why there is no join – and what happens instead DynamoDB has no server-side joins. That sounds like a shortcoming at first, but it is a deliberate decision for predictable latency. The trick: I don’t connect the data when reading but when writing. If different entity types carry the same partition key, they live in the same item collection and can be read together with a single query. That is pre-joining – the relationship is already built into the key schema before the first read happens. Take a small CMS with users, their posts and the comments on a post. The central access pattern is: “Get a user and all their posts in one call.” That is exactly what I derive the key design from, not from an ER diagram. ```mermaid flowchart LR A["Access pattern:
    Get user + their posts"] --> B["Choose PK:
    USER#id"] B --> C["Choose SK prefix:
    USER# and POST#"] C --> D["Query on PK = USER#123
    returns one item collection"] D --> E["Result:
    user item + all post items"] ``` The direction of derivation matters: I start on the left with the pattern and work my way to the key. That is the mental move that irritates relational developers at first. ## A single-table layout Single-table design means: several entity types in a single table, held together by generic, composite keys. Instead of descriptive attribute names such as `UserId`, I deliberately use generic names such as `PK` and `SK`, because the same column carries different meanings depending on the entity type. For the CMS, a layout looks like this: ```text PK SK weitere Attribute -------------- -------------------- ----------------------------- USER#123 USER#123 name, email, createdAt USER#123 POST#2021-09-01T... title, body, status USER#123 POST#2021-09-14T... title, body, status POST#987 COMMENT#2021-09-15.. author, text POST#987 COMMENT#2021-09-16.. author, text ``` The user and their posts share the partition key `USER#123` and thus form one item collection. The user item has an SK that repeats the PK (`USER#123`); the posts use the prefix `POST#` followed by a timestamp. As a bonus, the timestamp in the sort key sorts the posts chronologically – without any additional index. For the pattern “Get all comments on a post”, the primary index isn’t enough, because comments are sensibly grouped under a different PK. This is where a GSI comes into play. I add the attributes `GSI1PK` and `GSI1SK` and project an index over them that makes post-to-comment readable in reverse. That is the idea of the inverted index: a GSI with swapped roles to read a relationship from the opposite direction. I define the table itself with generic keys and one GSI. An excerpt of the `CreateTable` parameters: ```json { "TableName": "cms", "BillingMode": "PAY_PER_REQUEST", "AttributeDefinitions": [ { "AttributeName": "PK", "AttributeType": "S" }, { "AttributeName": "SK", "AttributeType": "S" }, { "AttributeName": "GSI1PK", "AttributeType": "S" }, { "AttributeName": "GSI1SK", "AttributeType": "S" } ], "KeySchema": [ { "AttributeName": "PK", "KeyType": "HASH" }, { "AttributeName": "SK", "KeyType": "RANGE" } ], "GlobalSecondaryIndexes": [ { "IndexName": "GSI1", "KeySchema": [ { "AttributeName": "GSI1PK", "KeyType": "HASH" }, { "AttributeName": "GSI1SK", "KeyType": "RANGE" } ], "Projection": { "ProjectionType": "ALL" } } ] } ``` `BillingMode: PAY_PER_REQUEST` is the on-demand mode, available since the end of 2018. I like to use it for examples and fluctuating load because I don’t have to worry about reserving capacity in advance. For a GSI, I deliberately choose via `ProjectionType` which attributes come along – `KEYS_ONLY`, `INCLUDE` or `ALL`. `ALL` is convenient but costs more storage and write throughput. ## The query over an item collection Now the part that justifies all the modeling. With SDK v3 and the `DynamoDBDocumentClient` from `@aws-sdk/lib-dynamodb`, I get all of a user’s posts with exactly one call: ```ts import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb"; const client = DynamoDBDocumentClient.from(new DynamoDBClient({})); async function getPostsByUser(userId: string) { const result = await client.send( new QueryCommand({ TableName: "cms", KeyConditionExpression: "PK = :pk AND begins_with(SK, :prefix)", ExpressionAttributeValues: { ":pk": `USER#${userId}`, ":prefix": "POST#", }, }) ); return result.Items ?? []; } ``` The `KeyConditionExpression` addresses exactly one item collection via `PK = :pk` and cuts out the posts with `begins_with(SK, :prefix)`. DynamoDB only reads the items that match `POST#` – the prefix acts directly on the sort key, not as an after-the-fact filter. If I want the user together with all posts, I drop the `begins_with` condition and get the complete collection in one go. For the reverse pattern via the inverted index, little changes. I address the GSI and use its keys: ```ts async function getCommentsByPost(postId: string) { const result = await client.send( new QueryCommand({ TableName: "cms", IndexName: "GSI1", KeyConditionExpression: "GSI1PK = :g AND begins_with(GSI1SK, :prefix)", ExpressionAttributeValues: { ":g": `POST#${postId}`, ":prefix": "COMMENT#", }, }) ); return result.Items ?? []; } ``` At its core, this is the same query mechanism, just on a different index. If you have understood the primary pattern, you can transfer it to the GSI without any adjustment. ## The pitfall with FilterExpression The `FilterExpression` looks like a cheap shortcut, but it isn’t one. Unlike the `KeyConditionExpression`, it only filters after the items have been read. That means I also pay the read capacity units for the items the filter then throws away. Worse still, combined with `Limit`, I can get empty pages back even though matching data exists – because the limit applies before the filter. The consequence is clear: selectivity belongs in the key design, not in the filter. If I often filter by a criterion, that criterion should move into the sort key or into a GSI. I only use `FilterExpression` for rare, non-critical refinements at the edges. ## When single-table pays off – and when it’s overkill As elegant as the pattern is, it isn’t an end in itself. Single-table design also gets introduced where it mainly looked impressive in a conference talk – and then saddles the application with complexity that nobody pays back. That’s why an honest look at the motivation is worth it. Single-table pays off when the access patterns are stable and known and when it matters to read a lot of related data with as few round trips as possible. The gain is performance and scaling with predictable latency, not storage savings. I deliberately accept data duplication and denormalization – that is a feature, not an accident. The approach is overkill in several situations: - The access patterns are still unclear early in the project or change frequently. Single-table makes later changes to the patterns expensive, because the key schema is anchored deep in the data. - The application needs ad-hoc evaluations or analytics. Without SQL, the export and reporting story gets tedious, and a single-table layout with many entity types doesn’t make it easier. Alex DeBrie, whose writing on DynamoDB I like to pass on, names another case: GraphQL. A GraphQL server resolves fields individually via resolvers anyway, so the big advantage of loading everything with one query fizzles out. There, a multi-table approach often gives more flexibility. I described how GraphQL and DynamoDB work together concretely on AWS in [GraphQL APIs with AppSync and DynamoDB](https://www.mikebild.dev/en/blog/graphql-apis-with-appsync-and-dynamodb/). A technical detail that becomes a problem with many entity types in one table is DynamoDB Streams: AWS recommends running no more than two concurrent consumers per shard, otherwise throttling effects loom. When different entities need different processing logic, you quickly end up wanting more consumers than a stream can handle. ## A word on the hard limits So the modeling doesn’t fail because of physical limits, I keep a few numbers in mind that hold steady in 2021. An item may be at most 400 KB in size. A query returns at most 1 MB per call; after that, you paginate. `BatchGetItem` fetches up to 100 items or 16 MB. By default, up to 20 GSIs and a maximum of 5 LSIs are possible per table. These limits force deliberate design – for example, not letting very large or unboundedly growing item collections come into being in the first place. ## Conclusion The decisive rebuild happens in your head, not in the code. If you treat DynamoDB like a relational database, you fight against the system. If you start with the access patterns and derive the partition key, sort key and suitable GSIs from them, you work with it. Single-table design then follows from the wish to read related data with one query and without a join – and not from the appeal of the pattern itself. Pragmatically, the way leads through three steps: first write down the access patterns, then design the key schema, then check whether a single primary index plus a few GSIs covers the patterns. If the patterns are still shaky or ad-hoc analyses are central, a simpler multi-table layout is the more honest choice. The goal is never the most elegant diagram, but the application that stays predictable under load. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-aws-serverless.en.html - Repository and accompanying article: [GraphQL APIs with AppSync and DynamoDB](https://www.mikebild.dev/en/blog/graphql-apis-with-appsync-and-dynamodb/) - AWS Docs, Core Components (tables, items, keys, item collections): https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html - AWS Docs, Query API: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html - AWS Docs, Global Secondary Indexes: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html - AWS Docs, Local Secondary Indexes: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html - AWS Docs, best practices and relational modeling: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-relational-modeling.html - Alex DeBrie, “The What, Why, and When of Single-Table Design”: https://www.alexdebrie.com/posts/dynamodb-single-table/ - Alex DeBrie, “How to model one-to-many relationships”: https://www.alexdebrie.com/posts/dynamodb-one-to-many/ - AWS Database Blog, “Single-table vs. multi-table design in Amazon DynamoDB”: https://aws.amazon.com/blogs/database/single-table-vs-multi-table-design-in-amazon-dynamodb/ --- # CDN Construct: A Small Infrastructure API URL: https://www.mikebild.dev/en/blog/cdn-construct-a-small-infrastructure-api/ Date: 2021-09-14 # CDN Construct: A Small Infrastructure API Around 280 lines of CloudFormation, spread across two stacks in two regions – that was recently the price of rolling out a static website “properly” on AWS. Fourteen resources for a handful of HTML files: an S3 bucket, a bucket policy, an origin access identity, a CloudFront distribution with cache and error behavior, an ACM certificate including DNS validation – mandatory in us-east-1, hence the second stack – plus A and AAAA alias records in Route53. None of this is difficult on its own. But all of it together is wiring that comes up again with every new project and turns out a little bit different each time. It was exactly this repetition that made me pack the whole chain into a small AWS CDK construct of my own: `cdk-cdn-construct`. Static content – a single-page application or a classic static website – lands in an S3 bucket and is delivered via CloudFront as a CDN. The call in your own stack shrinks to a few lines. That is the visible gain. The more interesting gain is a different one, and that is what this article is about: a good construct is an opinionated interface. It makes decisions explicit that were previously hidden in copy-and-paste templates, and it leaves free exactly the knobs that really vary from project to project. ## What actually gets wired up Before the abstraction holds, it is worth looking at what it encapsulates. A static website behind CloudFront consists of more parts than the sentence “S3 bucket with a CDN in front” suggests: - a private S3 bucket with Block Public Access fully enabled - an origin access identity (OAI) through which CloudFront – and only CloudFront – gets read access to the bucket - the matching bucket policy that allows exactly this identity `s3:GetObject` - a CloudFront distribution with enforced HTTPS, a default root object and sensible error behavior for client-side routing - an ACM certificate in us-east-1 including DNS validation - A and AAAA alias records in the Route53 zone that point to the distribution - the actual upload of the build output, including cache invalidation after the deployment As a diagram, the wiring looks like this: ```mermaid flowchart LR Browser[Browser] -->|HTTPS| CF[CloudFront distribution] CF -->|only via OAI| S3[S3 bucket
    private, Block Public Access] ACM[ACM certificate
    us-east-1] -.->|TLS| CF R53[Route53
    A/AAAA alias] -.->|resolves domain| CF Build[Build output
    e.g. ./build] -->|Upload + invalidation| S3 ``` Each of these edges is a decision. The bucket could also be public and offer website hosting directly – then no OAI would be needed, but the bucket would be reachable bypassing the CDN, and HTTPS on your own domain would be gone. The certificate could be imported instead of DNS-validated. The error pages could point to `404.html` instead of `index.html`. In handwritten templates, none of these decisions appear anywhere as a decision. They appear as 280 lines of YAML, and you can’t tell from them whether a deviation is intent or accident. ## From template to API With its construct levels, the AWS CDK offers a usable vocabulary for this. L1 constructs are generated one-to-one images of the CloudFormation resources. L2 constructs are handwritten classes with defaults and helper methods – `Bucket` instead of `CfnBucket`. And L3 constructs, also called patterns in the documentation, bundle several resources into a pattern with intent. Since last year, AWS itself has maintained a whole library of such patterns with the Solutions Constructs. My construct is such an L3 building block, technically implemented as its own stack so it can be plugged into an existing CDK app as a whole. Using it looks like this: ```typescript #!/usr/bin/env node import { App } from '@aws-cdk/core'; import { CdkCdnConstructStack } from 'cdk-cdn-construct'; const app = new App(); // ... your own stacks ... new CdkCdnConstructStack(app, 'MyWebsite', { namespace: 'my-app-namespace', env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION, }, }); ``` What stays configurable from outside deliberately follows a plain convention via environment variables – name, build directory, domain: ``` CDK_DEFAULT_REGION=eu-central-1 CDK_DEFAULT_ACCOUNT=default CDK_CDN_NAME=your-host-and-bucket-name CDK_CDN_PATH=./build CDK_CDN_DOMAIN=example.com ``` That is the entire public surface. No switch for the distribution’s price class, none for TTLs, none for the question of whether the bucket should be public after all. That isn’t laziness but the heart of the matter. An opinionated interface says: these points are decided, and decided this way. If you need a different opinion, you shouldn’t thread it through a parameter but take a different construct – or write your own. To be honest, the project is a work in progress, a building block from my own workshop and not a polished product. But that is exactly why it works as illustrative material: the question of which knobs an infrastructure API leaves free comes up with a small construct just as it does with a large platform – except that here, you can still discuss it during a coffee break. ## A look inside Inside, exactly what used to be in the template happens – just once, named and with defaults you can read in a code review. With the CDK v1 building blocks, the core can be sketched like this: ```typescript const originAccessIdentity = new cloudfront.OriginAccessIdentity(this, 'WebsiteOAI'); const websiteBucket = new s3.Bucket(this, 'WebsiteBucket', { blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL, }); websiteBucket.grantRead(originAccessIdentity); const certificate = new acm.DnsValidatedCertificate(this, 'WebsiteCertificate', { domainName: props.domainName, hostedZone: props.hostedZone, region: 'us-east-1', // CloudFront accepts ACM certificates from us-east-1 only }); const distribution = new cloudfront.Distribution(this, 'WebsiteDistribution', { defaultBehavior: { origin: new origins.S3Origin(websiteBucket, { originAccessIdentity }), viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS, }, domainNames: [props.domainName], certificate, defaultRootObject: 'index.html', }); new route53.ARecord(this, 'WebsiteAliasRecord', { zone: props.hostedZone, recordName: props.domainName, target: route53.RecordTarget.fromAlias(new targets.CloudFrontTarget(distribution)), }); ``` I find three details remarkable here, because they show what an L2/L3 cut actually achieves compared to raw CloudFormation. First: `websiteBucket.grantRead(originAccessIdentity)` is one line. Behind it is the complete bucket policy with the OAI’s canonical principal – a piece of JSON that, back in template days, I regularly copied from the last project, including the opportunity to drag something along in the process. The method expresses the intent (“this identity may read”), not the mechanism. Second: `DnsValidatedCertificate` with an explicit `region: 'us-east-1'`. CloudFront only accepts certificates from this one region, no matter where the rest of the stack lives. If you overlook this the first time, the deployment gives you an error message that points to the certificate but not to the cause – that happened to me back then with a certificate in eu-central-1, and the search cost half an afternoon. In the construct, this stumbling block is now a commented line. A colleague pointed at exactly that in a review and asked why the region is hardwired – and that very conversation is the point: the rule now lives in one place where you can discuss it, instead of being copied implicitly right or wrong in three projects. Third: the alias record is created in the same go as the distribution. In the template world, DNS entries were often the manual leftover, “we’ll do that later in the console” – and three months later, nobody knew why the staging environment pointed to a deleted distribution. When the record is part of the same building block, that leftover doesn’t exist. ## Defaults are opinion, not magic The usual objection to such building blocks is: abstraction hides what happens, and in the cloud, hidden quickly means expensive or insecure. The objection hits bad constructs, but it doesn’t hit the principle. The difference lies in whether the defaults are implicit or explicit. A copied template has defaults too – they just aren’t called that. They are whatever the author of the first template considered right two years ago, spread across 280 lines, without a name and without a reason. A construct, on the other hand, forces a decision: What is fixed? What is a parameter? What is deliberately not provided for? Answering these three questions cleanly once cost me more time when building the construct than the actual wiring – and it was the better-invested time. For the CDN building block, the fixed opinions are, for example: the bucket is private, always. Delivery happens exclusively via CloudFront, always over HTTPS. The certificate is validated via DNS and lives where CloudFront demands it. What stays free are the domain, the namespace and the path to the build output – exactly the things that actually distinguish two projects. Opening up everything else would only shift the repetition: if you pass twenty parameters through, you end up with CloudFormation again, just with different brackets. There is a limit here that I underestimated at first: a construct is an API, and infrastructure APIs have stricter compatibility rules than library APIs. If I rename a class in a library, builds break. If I change the structure in a construct, the logical IDs of the resources may change – and CloudFormation then replaces things instead of changing them. With an S3 bucket that has content, that isn’t a theoretical concern. Versioning a construct therefore doesn’t just mean assigning semantic version numbers, but keeping track of which changes trigger a replacement. That isn’t in any type system, and that is exactly why it belongs in the building block’s opinion. ## When a custom construct pays off You don’t have to build this wheel yourself. The AWS Solutions Constructs cover the “CloudFront to S3” pattern, and for many teams that is the right choice. In my view, a custom construct pays off when the opinion you want to encapsulate is more specific than that of a generic building block: your own naming conventions, a fixed deploy convention via environment variables, a specific error behavior for single-page applications, the in-house tagging requirement. In other words, whenever you notice that you readjust the generic building block in every project with the same five tweaks – then those five tweaks are the actual construct. The process to get there follows a simple flow that you can also read as a cycle: ```mermaid flowchart TD A[Wiring in the project
    typed for the second time] --> B[Name decisions:
    fixed, parameter, excluded] B --> C[Extract construct
    with minimal prop surface] C --> D[Use it in two projects] D --> E{Readjusted?} E -->|yes, always the same| B E -->|no| F[Opinion holds] ``` The order matters: first experience the repetition, then extract. A construct created before the second project doesn’t encapsulate experience but a guess – and you recognize guesses with twenty parameters by the fact that they don’t dare to commit to anything. Conversely: not every repetition deserves an abstraction. Two similar stacks are cheaper than a bad shared construct that grows a switch with every deviation. The honest question is whether the opinion is stable. For “static website behind CloudFront”, I’m sure of that by now – the pattern hasn’t moved across several projects; only the domains and build directories have changed. That is exactly the profile where the extraction pays for itself. ## The bottom line 280 lines in two regions become one import, one constructor call and five environment variables. That calculation is real, but it isn’t the actual return. The actual return is that the infrastructure decision now has an address. When someone asks why the bucket is private, why the certificate lives in us-east-1 or why there is no TTL switch, the answer points to a place in the code – with a name, a comment and Git history. Before, it pointed to a template that was copied somewhere at some point. For a long time, I treated infrastructure as something you describe and application code as something you design. The CDK removes this separation, and a small construct of your own is the point where you really feel it: suddenly the familiar questions of API design – what is public, what is a default, what is excluded, what breaks with a change – apply to buckets and distributions just as they do to classes and modules. Building a small infrastructure API is therefore less a DevOps topic than an entirely normal design exercise. Except that here, a bad default doesn’t end in an exception but in a bill or a public bucket. ## Further reading - Project repository: [github.com/MikeBild/cdk-cdn-construct](https://github.com/MikeBild/cdk-cdn-construct) - AWS CDK v1: [Construct Library](https://docs.aws.amazon.com/cdk/api/v1/docs/aws-construct-library.html) - CloudFront: [Restricting access to S3 origins with an origin access identity](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html) - ACM: [Supported regions – certificates for CloudFront in us-east-1](https://docs.aws.amazon.com/acm/latest/userguide/acm-regions.html) - AWS Solutions Constructs: [github.com/awslabs/aws-solutions-constructs](https://github.com/awslabs/aws-solutions-constructs) --- # Outcome Before Output: Why Velocity Is the Wrong Number URL: https://www.mikebild.dev/en/blog/outcome-before-output/ Date: 2021-08-26 ```typescript // Sprint-Report, wie er im Statusdeck landet const sprint42 = { storyPointsCommitted: 34, storyPointsCompleted: 38, ticketsDone: 17, velocityTrend: "up", }; ``` Exactly one statement follows from this object: the team completed more points than it had committed to. Whether a user reaches their goal faster as a result, whether a system runs more reliably, whether revenue is generated anywhere – there is no field for that here, and you can’t compute one in after the fact. Still, exactly this curve travels into reports sprint after sprint, gets compared between two teams and occasionally ends up on a board slide next to revenue. The question that actually counts isn’t “How many story points did the team complete?” but “What changed for the user, for the system, for the business as a result?” That’s the difference between output and outcome. And if you blur it, you systematically optimize a team for being busy instead of having an impact. The dividing line runs between an observed activity and the demonstrable change that follows from it. ::::comparison{title="Activity and impact answer different questions" role="primary" preferredPattern="split-comparison"} :::side{label="Output"} - Observation · What was built or completed? - Examples · Features, tickets and story points - Use · Planning and tracking the work - Limit · Doesn’t yet prove any change for the user ::: :::side{label="Outcome"} - Observation · What changed in behavior or results? - Examples · Activation, time to first value and error rate - Use · Checks whether a solution contributes to the goal - Limit · Needs context and a robust measurement ::: :::: This keeps velocity useful as an internal planning measure without turning it into a statement about productivity or business value. ## Velocity measures predictability, not productivity Let’s start at the source, because velocity has gotten a bad reputation it doesn’t deserve. Almost two decades ago, Martin Fowler described precisely what the number was meant for: a calibration tool for estimates. The principle is called “Yesterday’s Weather” – we assume that a team will get about as much done in the next sprint as in the last one. That keeps plans realistic without anyone making heroic commitments. Story points are a team-specific baseline. They mean something different for team A than for team B, because they are estimated relative to each context. That’s exactly why comparing two teams by their velocity isn’t just imprecise but simply meaningless – you compare two different units of measurement and pretend they are the same. And then the predictable happens. As soon as velocity becomes a management target, it gets gamed. Teams estimate more generously, split tickets more finely, declare minor things a story. The curve rises, delivery stays the same. That isn’t malice, it’s Goodhart’s Law in its purest form: “When a measure becomes a target, it ceases to be a good measure.” Any number you elevate to a measure of success stops being honest at that very moment. So I don’t want to demonize velocity at all. Internally, as an aid for planning and forecasting, it’s completely legitimate and useful. The mistake isn’t in the number but in promoting it to a measure of success. That’s an important distinction that tends to get lost in the heat of the “velocity is evil” debates. ## True output is impact – and you can’t measure it directly Fowler’s truly radical point comes next: “True output is business value.” A team’s real yield isn’t the number of features but the value created. His example sums it up: a team that delivers fewer features but generates ten million in profit is more productive than one with more features and five million in value. The catch is sobering. Business value lags behind the investment, often by years. What a team builds today pays off – if at all – only later, intertwined with the market, sales, timing and a dozen other factors. An immediate, clean measurement of productivity is therefore simply impossible. Fowler’s honest conclusion: “We have to admit our ignorance.” We can’t measure productivity directly. Period. That sounds discouraging, but it’s liberating. Because if the perfect number doesn’t exist, we stop looking for it and turn to what we can actually influence and observe: the impact of our work on users and the system. ## Outcome instead of output: the core of modern product work This is exactly where the product side comes in. In her work on continuous discovery, Teresa Torres draws a clean distinction: outputs are what we build – features, screens, endpoints. Outcome is the change in user behavior that creates value for the customer and the business. If you declare outputs the goal, you produce a “disconnect” between the team’s activity and the value delivered. The team is fully utilized, the board is full, and still nothing moves for the user. Marty Cagan puts the same observation even more sharply: “Empowered teams get outcomes, feature teams get output.” A feature team is handed a roadmap and works through it – output. An “empowered” team gets a problem and an outcome goal and is allowed to figure out for itself how to get there. The difference isn’t cosmetic. It decides whether people think along or just work through a list. The tool I have had the best experience with here is the Opportunity Solution Tree. At the root sits exactly one outcome, for example “increase the activation rate by X percent.” Below it branch out opportunities – concrete user problems or needs that contribute to this outcome. Below those come solutions, and at the very bottom the experiments we use to check whether a solution actually works. The tree forces the question the velocity curve never asks: Does what we are building right now contribute to the root at all? ```mermaid graph TD subgraph output["Output view (vanity)"] B[Backlog] --> S[Sprint] S --> V["Velocity chart
    many completed tickets"] V --> U["up and to the right"] end subgraph outcome["Outcome view"] O["Outcome
    activation rate +X%"] --> OP1[Opportunity A] O --> OP2[Opportunity B] OP1 --> SOL[Solution] SOL --> EXP[Experiment] end V -. "does the output move
    the root?" .-> O ``` The diagram shows the two worlds side by side. On the left, the output pipeline that reliably points upward. On the right, the tree that makes impact traceable. The dashed arrow in between is the real management question – and exactly this arrow is missing almost entirely from the reports I get to see. ## Vanity metrics: the engineering version of self-deception Eric Ries coined the term vanity metrics for this kind of number in the Lean Startup context. Sign-ups, page views, downloads – numbers that go “up and to the right” and feel good without proving real progress. Velocity and completed tickets are the engineering version of exactly this pattern. They rise reliably, they create a good feeling, and they say nothing about whether we have gotten closer to the goal. On the other side are actionable metrics: numbers that show a cause-and-effect relationship and lead to a decision. For Ries, the unit of progress isn’t “feature shipped” but “validated learning” – confirmed learning about what actually works for the user. The framework for this is called innovation accounting, the cycle Build-Measure-Learn. In practice, this means: you don’t instrument what you built, you instrument what the user does in response. An event that tracks an outcome looks different from one that counts output. ```typescript // Actionable: measures what actually moves the user track("activation_completed", { userId, cohort, timeToValueSeconds, // how fast does the user reach first value? }); // Vanity: feels like progress, says nothing about impact // track("features_shipped", { count }); // track("story_points_done", { total }); ``` The decisive step comes next: you roll out the feature behind a flag and compare the outcome delta between two cohorts. Does the new solution measurably increase the activation rate, or not? That’s Build-Measure-Learn in one line of infrastructure – and it shifts the question of success from “did we build it?” to “did it work?” ## Better proxies: DORA and fitness functions At this point, someone usually chimes in: But there’s DORA. The four key metrics from the Accelerate research by Forsgren, Humble and Kim – Deployment Frequency, Lead Time for Changes, Change Failure Rate and Time to Restore Service – are a big step forward. They deliberately measure team outcomes instead of individual outputs. Explicitly no lines of code, no story points, no utilization, because those are siloed activity numbers. And they balance speed against stability, so you can’t optimize one number at the expense of the whole system. DORA helps, with one caveat: these metrics are proxies too, not real outcomes. Deployment frequency isn’t user impact. A team can deploy fifty times a day and still miss what’s needed. DORA measures the ability to deliver quickly and stably – an excellent indicator of delivery health, but not the goal itself. If you confuse the two, you have just replaced one vanity number with four. At the architecture level, there is an instrument that is particularly close to my heart, because it makes outcome executable: fitness functions from Evolutionary Architecture by Ford, Parsons and Kua. A fitness function is an objective, automated assessment of an architectural property. Instead of checking off “performance improved” in a ticket, you write a test that checks the system’s effect itself: ```python def test_checkout_latency_stays_within_budget(): """Architectural fitness function: checkout stays fast under load.""" result = load_test(endpoint="/checkout", concurrent_users=200) assert result.p99_ms < 500 # latency budget, not a story point assert result.error_rate < 0.01 # reliability is the real outcome ``` The beauty of it: success is no longer a status update here but a measurable system property that is either maintained or not. The test is green because the system delivers the promised effect – not because someone moved a story to “done.” Consumer-Driven Contracts work in a similar way, for example with Pact: a test fails when a service breaks a promise to its consumer. That, too, is a test close to the outcome – it checks the actual effect at the interface instead of the mere existence of code. ## How to really align teams with outcomes When I set this up in an organization, I follow a simple process. It’s deliberately lean, because the whole point of the exercise is to replace process overhead with clarity, not to create new ceremonies. ```mermaid flowchart LR A["Define the outcome
    one goal, measurable"] --> B["Opportunities
    map user problems"] B --> C["Experiments
    behind feature flags"] C --> D["Measure impact
    cohort delta"] D -->|"works"| E["scale"] D -->|"does not work"| B ``` It starts with exactly one outcome, phrased as a measurable change in behavior – not “ship the checkout redesign” but “reduce the checkout abandonment rate.” The idea of a North Star Metric fits here and, at the goal level, OKRs: the objective describes the direction, and the key results are the outcome signals by which we recognize progress. The second step collects the opportunities: Where do users actually drop off, where does friction arise? Only then come solutions, and they aren’t rolled out and checked off but tested as an experiment behind a flag. If the cohort delta shows an effect, we scale. If it doesn’t, we go back to the opportunities – without a guilty conscience, because a disproven experiment is validated learning and therefore a result in itself. An important caveat belongs here, otherwise you walk into the next trap. Goodhart applies to outcome KPIs too. An activation rate can be gamed as well, and the time lag from Fowler’s observation remains: impact takes time, and attribution is rarely clear-cut. If you set an outcome goal, you have to factor in this fuzziness instead of defining it away – otherwise you construct false causalities and are no further along than with the velocity chart. ## Conclusion The common thread through all of this is simple: output is necessary, but impact is the goal. Completed tickets, story points and velocity describe work and planning – not whether anything improved for users or the business. As an internal planning aid, they are legitimate; as a measure of success for management, they steer in the wrong direction, because a target number gets optimized and being busy doesn’t yet prove impact. The way out isn’t a better single number but an attitude. We align teams with a measurable outcome, make impact visible through actionable metrics, fitness functions and experiments, and treat DORA as what it is – a good proxy for delivery capability, not the goal. In my experience, the result isn’t a heavier process but a lighter one: shorter cycles, because we abandon wrong paths early; less friction, because teams are allowed to decide for themselves; and higher quality, because success depends on impact and not on the status color of a ticket. Fowler’s sober admission remains the best starting point: we can’t measure productivity directly. But we can stop celebrating the wrong number and start asking the right question – does what we build move the root at all? ## Further reading - Martin Fowler: [CannotMeasureProductivity](https://martinfowler.com/bliki/CannotMeasureProductivity.html) and [XpVelocity](https://martinfowler.com/bliki/XpVelocity.html) - Teresa Torres: [Continuous Discovery Habits](https://www.goodreads.com/book/show/58046715-continuous-discovery-habits) (2021) - Nicole Forsgren, Jez Humble, Gene Kim: *Accelerate* (2018); [Four Keys to measure DevOps performance](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance) - Eric Ries: [The Lean Startup – Principles](https://theleanstartup.com/principles) (2011) - Neal Ford, Rebecca Parsons, Patrick Kua: [Building Evolutionary Architectures – Fitness Functions](https://www.oreilly.com/library/view/building-evolutionary-architectures/9781491986356/ch02.html) (2017) --- # Data Analysis with NumPy, Pandas, and Matplotlib URL: https://www.mikebild.dev/en/blog/data-analysis-with-numpy-pandas-and-matplotlib/ Date: 2021-08-24 A `DataFrame` is not a spreadsheet and not a database table. It is a collection of typed columns in memory, each of them a NumPy array, all tied together by a shared index. This origin explains almost everything that surprises you later: why looping over individual rows is so expensive, why a selection sometimes returns a view of the original data and sometimes a copy, and why a `groupby` does in a single expression what would otherwise take a loop plus a cache. Still, the first reflex when you face a CSV file with a few hundred thousand rows is the Python loop. Open it, walk through it line by line, sum up the values, print the result. That works – for a hundred rows. With a million rows, you end up waiting and wondering why it takes so long. The loop question is actually the smaller one. The bigger one is decided further up: an analysis is rarely an end in itself. In the end, a decision depends on it. A price gets adjusted, a budget gets shifted, a region gets expanded or scaled back. So the value of an analysis is not measured by how elegantly it computes but by how reliably its result supports a decision. And that is where the real risk lies: not in the runtime, but in whether the final number is right and whether I can produce the same number again tomorrow. The toolkit of NumPy, pandas, and Matplotlib is the answer to this requirement, not just to the speed problem. Together, the three libraries form a path from raw data to the finished chart, and each takes on a clearly defined job. What matters is that this path becomes repeatable: the same code, the same raw data, the same result, no matter who runs it. In this article, I walk the whole path once: first fast computation with NumPy, then structured tables with pandas, and finally visualization with Matplotlib. At the end, there is a small pipeline that loads, cleans, groups, and plots. I focus less on individual function calls and more on the places where an analysis gains or loses its reliability. If you are still wondering how the data gets into your program in the first place, [Reading Data in Python](https://www.mikebild.dev/en/blog/reading-data-in-python/) covers the basics. ## Why not a Python loop? NumPy and the ndarray At the core of NumPy is a single data type: the `ndarray`. At first glance, it looks like a list, but the difference lies in memory. A Python list holds references to arbitrary objects scattered somewhere in memory. An `ndarray` is homogeneously typed and stored contiguously – all elements have the same data type and sit right next to each other. This layout is the prerequisite for what makes NumPy fast: vectorized operations. Instead of iterating over individual elements in Python, the whole computation is handed off to compiled C code. An example makes the difference clear. ```python import numpy as np values = np.arange(1_000_000) # 0, 1, 2, ... 999999 result = values * 2 + 1 # vectorized, no Python loop total = result.mean() print(result.shape) # (1000000,) print(result.dtype) # int64 print(total) # 1000000.0 ``` The line `values * 2 + 1` computes on all million elements without a single Python `for` loop running. The expression is not only faster, it is also shorter and reads closer to the mathematical intent. That is the real gain: you describe *what* should be computed, not *how* to iterate over the elements. Besides arithmetic operations, two tools show up in virtually every analysis. One is reductions such as `.sum()`, `.mean()`, `.std()`, or `.min()` and `.max()`, which turn an array into a single metric. The other is Boolean masks. ```python import numpy as np data = np.array([-3, 7, -1, 4, 9, -8]) mask = data > 0 # array of True/False positives = data[mask] # keep only positive values clipped = np.where(data < 0, 0, data) # replace negatives with 0 print(positives) # [7 4 9] print(clipped) # [0 7 0 4 9 0] ``` `data > 0` does not produce a single `True` or `False` but a whole array of truth values. You can then use it to filter (`data[mask]`) or to replace values case by case with `np.where`. Again, no loop and no condition in Python code – the logic lives entirely in the vectorized operation. Closely related to vectorization is broadcasting. It lets you combine arrays of different shapes as long as their dimensions are compatible. Conceptually, a scalar is stretched across the entire shape of the array – that is why `values * 2 + 1` works without you having to inflate the `2` and the `1` to a million elements yourself. The same rule applies to two-dimensional data: a row vector with a matching number of columns can be applied to every row of a matrix, for example to subtract the mean from each column. Broadcasting saves you many explicit loops and keeps the code close to mathematical notation. The only important thing is to keep the shapes in your head: if the dimensions don’t fit, NumPy responds with a `ValueError` instead of silently computing something wrong. ## Pandas: tables with labels NumPy is good at computing with numbers, but real data has structure. Columns have names, rows have meaning, and numbers are often mixed with text and dates. This is where pandas comes in, and pandas builds directly on NumPy. Underneath pandas tables are NumPy arrays. The two central structures are `Series` and `DataFrame`. A `Series` is a one-dimensional column with an index. A `DataFrame` is a two-dimensional table with labeled rows and columns – essentially a collection of `Series` that share the same index. ```python import pandas as pd df = pd.DataFrame({ "region": ["north", "south", "north", "west", "south"], "amount": [120.0, 80.0, 45.0, 200.0, 95.0], "channel": ["online", "store", "online", "store", "online"], }) print(df.shape) # (5, 3) print(df["amount"].mean()) # 108.0 ``` Reading from a file usually goes through `pd.read_csv`, which turns a CSV file into a `DataFrame`. From then on, you keep working with the same table, no matter where it came from. ### Selecting with loc and iloc – the classic stumbling block As soon as you want to pick out specific rows and columns, two access methods show up that beginners reliably mix up: `.loc` and `.iloc`. The difference is actually simple, but you have to learn it consciously once. `.loc` is label-based. You access rows and columns by their labels, and – this is the quirk – the endpoint of a range is **inclusive**. `.iloc` is position-based. You access by integer position, and the endpoint is **exclusive**, just like regular Python slicing. ```python import pandas as pd df = pd.DataFrame( {"amount": [120, 80, 45, 200, 95]}, index=["a", "b", "c", "d", "e"], ) # label-based, endpoint INCLUDED -> rows a, b, c print(df.loc["a":"c", "amount"]) # position-based, endpoint EXCLUDED -> rows a, b, c (positions 0, 1, 2) print(df.iloc[0:3, 0]) ``` Both expressions return the same three rows here, but for different reasons: once because `"c"` is included as a label, once because position `3` is just barely left out. If you mix them up, you get either an off-by-one error or a `KeyError`. So: labels always via `.loc`, positions always via `.iloc`, and never mix the two in one expression. For filtering, you use Boolean masks – just like in NumPy, except that the condition refers to a column. ```python import pandas as pd df = pd.DataFrame({ "region": ["north", "south", "north", "west"], "amount": [120, 80, 45, 200], }) big = df[df["amount"] > 100] # keep rows above 100 big_regions = df.loc[df["amount"] > 100, "region"] # filter + pick column ``` ## The most common mistake: chained indexing Now to a pitfall that comes up regularly in code reviews and leads to one of the most searched warnings in the pandas world: the `SettingWithCopyWarning`. It is caused by chained indexing – two consecutive accesses in one expression. ```python # problematic: chained indexing df[df["amount"] > 100]["tier"] = "high" # may write into a copy! ``` The tricky part: depending on the situation, `df[df["amount"] > 100]` returns either a view of the original data or a copy of it – and you cannot reliably predict which. If you then write into the result, the assignment may land in a copy that is immediately thrown away. The original stays unchanged, and that is exactly what pandas warns you about. The correct form uses a single `.loc` access that addresses the row selection and the column in one step: ```python # correct: single .loc access df.loc[df["amount"] > 100, "tier"] = "high" ``` And if you deliberately want to keep working with an independent copy, say so explicitly with `df.copy()`. Then it is clear that changes should not touch the original. In my experience, this one rule – selection and assignment in a single `.loc` – saves you most of these warnings. The second mistake in the same category is iterating over rows. If you come from classic programming, you instinctively reach for `df.iterrows()` and go row by row. That is slow and memory-hungry, because pandas has to build a new object for every row, and the whole speed advantage of the vectorized NumPy foundation is lost. Almost always, you can express the same intent with a column operation, with `groupby`, or with `np.where` – and it then runs orders of magnitude faster. ## Grouping and aggregating with groupby Perhaps the most important operation for analysis is `groupby`. It follows a pattern known as split-apply-combine: the data is split into groups by a key (split), an aggregate function is applied to each group (apply), and the partial results are combined into a new table (combine). ```python import pandas as pd df = pd.DataFrame({ "region": ["north", "south", "north", "west", "south"], "amount": [120.0, 80.0, 45.0, 200.0, 95.0], }) summary = (df.groupby("region") .agg(total=("amount", "sum"), avg=("amount", "mean")) .reset_index()) print(summary) # region total avg # 0 north 165.0 82.5 # 1 south 175.0 87.5 # 2 west 200.0 200.0 ``` Named aggregation, `total=("amount", "sum")`, is my preferred notation: in a single line, it says which column is aggregated with which function and what the result column should be called. The result is a compact table that you can process further right away. The `.reset_index()` at the end moves the grouping key from the index back into a regular column – handy if you want to plot right afterward. Often the data does not live in a single table but is spread out. Sales figures here, region information there. To bring them together, you use `merge`, which works like database joins: ```python import pandas as pd sales = pd.DataFrame({ "region": ["north", "south", "west"], "amount": [165, 175, 200], }) managers = pd.DataFrame({ "region": ["north", "south", "east"], "manager": ["Ada", "Ben", "Cleo"], }) joined = sales.merge(managers, how="inner", on="region") print(joined) # region amount manager # 0 north 165 Ada # 1 south 175 Ben ``` It pays to keep a close eye on the `how` parameter here. With `how="inner"`, only regions that appear in both tables remain – “west” and “east” drop out. A `how="outer"` would keep all regions and fill the missing values with `NaN`. If you pick the wrong mode, you either silently lose rows or end up with unexpected gaps. It is worth checking `.shape` before and after a `merge` to see whether the row count matches your expectations. ## The pipeline: load, clean, group, plot Let’s put the pieces together. A typical analysis always passes through the same stations, and it helps to have this flow in front of you as a picture. ```mermaid flowchart LR A[Rohdaten
    CSV-Datei] --> B[Laden
    pandas.read_csv] B --> C[Bereinigen
    dropna / fillna] C --> D[Transformieren
    groupby / agg] D --> E[Plotten
    matplotlib] ``` Grouping is usually preceded by cleaning. Real data has gaps, and `groupby` or computations on top of it are sensitive to missing values. Two tools cover most cases: `dropna` throws away rows with missing values, `fillna` replaces them with a default value. Which one is right depends on the question – sometimes a gap is a genuine nothing, sometimes a disguised zero. ```python import pandas as pd df = pd.read_csv("sales.csv") # clean: drop rows without an amount df = df.dropna(subset=["amount"]) # transform: aggregate per region summary = (df.groupby("region") .agg(total=("amount", "sum")) .reset_index()) ``` ## Data quality and reproducibility as a decision risk The step `df.dropna(subset=["amount"])` looks like a formality. It isn’t. The moment I throw away missing values instead of filling them, I decide which number ends up in front of the decision-maker. `dropna` shrinks the population and can make a region disappear that was simply poorly recorded. `fillna(0)` turns an “unknown” into a hard zero and drags every average down with it. Both are sometimes right and sometimes wrong, but never neutral. The question is always the same: is the gap a genuine nothing or a disguised zero? This decision belongs in the documentation, not made silently. The second, more expensive risk factor is silent data loss. A `merge` with the wrong `how` drops rows without warning, a cleanup step quietly halves the population, and the bar chart still looks plausible. That is exactly the danger: a wrong analysis looks deceptively like a correct one. That is why I build checks directly into the pipeline instead of trusting what I see. ```python before = len(df) df = df.dropna(subset=["amount"]) assert len(df) >= before * 0.9, "dropped more than 10% of rows" assert df["amount"].between(0, 10_000).all(), "amount out of expected range" ``` Assertions like these cost minutes during development. A decision based on a population that shrank by ten percent costs considerably more, and the error is often noticed only after it has already had its effect. That is the real trade-off: a little friction while writing in exchange for a reliable number when deciding. The third point is reproducibility. An analysis that I click together in a spreadsheet can no longer be traced after two weeks. Nobody knows which cells were touched by hand. An analysis as code is the opposite: the same code on the same raw data delivers the same result, at any time, for everyone on the team. The raw data stays untouched, every transformation is visible in the script, and the result can be traced back to its source. This turns a one-off number into a process that I can check, version, and defend. That is exactly what lifts an analysis from a nice chart to a basis for decisions. ## Matplotlib: turning numbers into a picture At the end of the pipeline comes visualization. Matplotlib is the established library for it, and I recommend the object-oriented style from the start: first create a figure and an axis with `plt.subplots()`, then build everything on that axis. It is a bit more typing than the quick `plt.plot()` one-liner, but it stays clear as soon as a chart contains more than one line. ```python import matplotlib.pyplot as plt fig, ax = plt.subplots() ax.bar(summary["region"], summary["total"]) ax.set_xlabel("Region") ax.set_ylabel("Total sales") ax.set_title("Sales by region") plt.show() ``` For the three most common chart types, there is a matching function on the axis. A bar chart with `ax.bar(x, height)` compares categories – ideal for the `groupby` result from before. A line chart with `ax.plot(x, y)` shows trends, such as a metric over several months. And a scatter plot with `ax.scatter(x, y)` shows the relationship between two variables. For me, labels via `set_xlabel`, `set_ylabel`, and `set_title` are always part of it; a chart without axis labels is only half a statement. ## Who does what? The division of roles at a glance The division of work in the toolkit is clearly cut, and if you know it, you won’t reach for the wrong library for a problem: - NumPy forms the numerical foundation: homogeneous arrays, vectorized computation, mathematical operations. Everything above builds on it. - pandas takes care of structured, labeled tabular data: reading, cleaning, selecting, filtering, grouping, merging – the entire handling of real, messy data. - Matplotlib handles visualization: the fully prepared numbers become a chart that carries a message. This order is no accident. It describes exactly the path the data takes: from raw numbers through a structured table to a picture. ## The common thread The real shift in thinking for data analysis with Python is saying goodbye to the loop. No longer going element by element, but treating whole columns and whole tables as a unit. NumPy does this with vectorized operations on the `ndarray`, pandas lifts the same idea to labeled tables, and `groupby` aggregates whole groups at once following the split-apply-combine pattern. But the gain is not just speed. If you know the two beginner traps, chained indexing and iterating over rows, you avoid the most common friction points and write code that stays just as calm at a million rows as at a hundred. This toolkit has its impact where analysis meets decision. A pipeline made of code shortens the cycle from question to answer: if the raw data changes, the same script runs again, and the new number is ready in minutes instead of half a day of manual work. It reduces friction in the team, because everyone can reproduce the same result instead of deciphering someone else’s spreadsheet. And it raises quality, because checks and documented cleanup decisions make sure a wrong number gets noticed before it supports a decision. The limit is just as clear: these tools work well where the data fits in memory and a batch analysis is enough. With data volumes beyond a single machine or with continuous data streams, a different set of tools begins, and the art is recognizing this limit in time instead of forcing pandas beyond its scope. The rest is practice: load, clean, group, plot, and go through this cycle until it becomes second nature. The tool only becomes useful when the steps stay reproducible and a second person gets the same number. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-python.en.html - Repository `introduction-python` with runnable examples for NumPy, pandas, and Matplotlib - NumPy – “the absolute basics for beginners”: https://numpy.org/doc/stable/user/absolute_beginners.html - pandas – Indexing and Selecting Data (loc/iloc, chained indexing): https://pandas.pydata.org/docs/user_guide/indexing.html - pandas – Group by: split-apply-combine: https://pandas.pydata.org/docs/user_guide/groupby.html - pandas – Merge, join, concatenate: https://pandas.pydata.org/docs/user_guide/merging.html - Matplotlib – pyplot API: https://matplotlib.org/stable/api/pyplot_summary.html --- # When CQRS and Event Sourcing Are Too Much URL: https://www.mikebild.dev/en/blog/when-cqrs-and-event-sourcing-are-too-much/ Date: 2021-07-13 # When CQRS and Event Sourcing Are Too Much Changing an email address takes three lines in a CRUD handler: load, set the field, save. With CQRS and Event Sourcing, it takes five parts – a command, an event, an aggregate with a replay path, an append to the event store and a projection that updates the read model. On top of that comes a time window in which a query still returns the old address. Five moving parts and a consistency problem that didn’t exist before. You can pay this price, and under certain conditions it pays off. I like both patterns and have defended them in other articles. For the majority of systems, they’re still too much. This isn’t a bold claim. Martin Fowler puts it almost identically: “For most systems CQRS adds risky complexity.” And unusually clearly for him: in the majority of cases he came across, CQRS wasn’t a good choice but carried a considerable risk of getting the system into serious difficulties. When the author who made a pattern well known warns like that, an honest decision guide is worth it. ## The baseline is CRUD Before I talk about alternatives, I want to state what the standard solution actually achieves. CRUD means: a single data model for reading and writing, direct persistence of the current state, usually against a table through an ORM. Create, Read, Update, Delete. Fowler puts it soberly: “Many systems do fit a CRUD mental model, and so should be done in that style.” The key point is that CRUD isn’t the primitive preliminary stage you later replace with something better. For a form that gets saved and displayed again, CRUD isn’t the compromise but the right answer. An illustrative handler for it is unspectacular – and that’s exactly its strength: ```ts async function updateCustomerEmail(id: string, email: string): Promise { const customer = await repo.findById(id); customer.email = email; await repo.save(customer); // read and write share the same model } ``` One model, one access, no latency between writing and reading. If you optimize this value away without having a problem, you trade simplicity for complexity and get nothing back for it. ## What CQRS and Event Sourcing really are To make the decision clean, I separate the two terms that are often mentioned in one breath. CQRS – Command Query Responsibility Segregation – means you use a different model for changing data than for reading it. The write side accepts commands, checks invariants and returns nothing. The read side answers queries, returns data and changes nothing. That’s more than Bertrand Meyer’s Command Query Separation principle: CQS separates methods on an object, CQRS separates entire models. Event Sourcing is something else. Here, every state change is recorded as an event, and the current state comes from replaying the events. The event store is the authoritative source of truth; the state is purely derived. Fowler’s analogy for this is version control: the commit log corresponds to the event store, the working tree to the current system state. I developed this idea in more detail in [Event Sourcing: The Event Store as a Logbook](https://www.mikebild.dev/en/blog/event-sourcing-the-event-store-as-a-logbook/). Important for today’s article: the two patterns are independent of each other. Greg Young makes this clear several times – CQRS isn’t Event Sourcing, doesn’t need a message bus and isn’t necessarily tied to DDD either. You can run CQRS without Event Sourcing, that is, with a separate read database but classic state persistence. And you can run Event Sourcing with only one model. So if you introduce both together, you’re choosing two cost blocks, not one. ## The costs you rarely plan for Separate models effectively force eventual consistency. As soon as the write side produces an event and the read side only then builds a projection from it, there’s a time window in which a query doesn’t yet see the value that was just written. Fowler says so openly: separate models increase the likelihood of having to use eventual consistency. That isn’t a feature but a cost item. An illustrative contrast to the CRUD handler above shows the additional moving parts. First the messages: ```ts interface ChangeEmail { type: "ChangeEmail"; id: string; email: string; } interface EmailChanged { type: "EmailChanged"; id: string; email: string; version: number; } ``` Then the write model, which is rehydrated from its events and checks an invariant when changing instead of simply overwriting a field: ```ts class Customer { private constructor( private readonly id: string, private email: string, private version: number, ) {} static empty(): Customer { return new Customer("", "", 0); } static from(events: EmailChanged[]): Customer { // fold the event stream into current state (replay) return events.reduce( (state, event) => state.apply(event), Customer.empty(), ); } private apply(event: EmailChanged): Customer { return new Customer(event.id, event.email, event.version); } changeEmail(email: string): EmailChanged[] { if (email === this.email) return []; // no change, no event return [{ type: "EmailChanged", id: this.id, email, version: this.version + 1 }]; } } ``` And finally the handler, which loads, decides, appends – and updates the projection separately: ```ts async function handle(command: ChangeEmail): Promise { const events = await store.load(command.id); const customer = Customer.from(events); const newEvents = customer.changeEmail(command.email); await store.append(command.id, newEvents); // source of truth // read model is updated asynchronously by a projection } ``` The read side is its own, deliberately dumb read model built from the same events: ```ts class CustomerListView { private rows = new Map(); on(event: EmailChanged): void { this.rows.set(event.id, { id: event.id, email: event.email }); } // a query right after append may still return the previous email (stale read) find(id: string) { return this.rows.get(id); } } ``` Between the first CRUD example and this variant lies not progress but a trade-off. I’ve exchanged more types, more indirection, a replay path, a projection and a consistency window – for a benefit that only arises under certain conditions in the first place. Beyond that, Event Sourcing brings its own, often underestimated costs. Old events have to remain readable practically forever, which makes event versioning and schema evolution a permanent task. Projections and read models have to be buildable and rebuildable. External side effects during replay need careful handling, otherwise a rebuild accidentally sends real emails. And a simple ad hoc query on the current state no longer comes for free. These points come on top of the CQRS costs. ## A decision flow I base the decision on a few questions, in this order. Important: this applies per bounded context, not globally. Greg Young is unambiguous here – CQRS isn’t a top-level pattern; it’s applied within a component, not slapped over the entire system. ```mermaid flowchart TD Start([New context]) --> Inv{Real domain model
    with colliding invariants?} Inv -->|no| Crud[CRUD is enough] Inv -->|yes| Asym{Strong read/write asymmetry
    OR audit/time-travel requirement?} Asym -->|no| Lite[Stay with CRUD
    or CQRS-lite] Asym -->|yes| Team{Can the team handle eventual consistency
    and event versioning?} Team -->|no| Kompromiss[CRUD or compromise] Team -->|yes| Cqrs[CQRS – plus Event Sourcing
    if audit or temporal] ``` The benefit of CQRS is closely tied to two conditions. First, a complex domain in which a shared model for reading and writing actually becomes too complicated. Second, a pronounced read/write asymmetry – many reads, few writes – so that scaling the read and write sides independently pays off. If both are missing, Fowler’s observation leads straight into the trap: CQRS on a domain that doesn’t fit increases complexity, lowers productivity and raises risk. The pattern doesn’t simplify on its own, only where real model or invariant complexity already exists. ## Signals for and against In a concrete project, the answer hinges on a few signals that you usually see earlier than you take them seriously. In favor: - a task-based UI with many people working concurrently whose actions can collide in the domain - hard audit, compliance or time-travel requirements that demand a complete history – this is where Event Sourcing in particular pulls its weight - a pronounced read/write asymmetry with separate scaling goals - a rich domain with real, competing invariants and clearly different read and write shapes Against: - a classic CRUD or form application without real invariant complexity - a small team that has no experience with eventual consistency yet - no audit or history requirement that justifies the effort - the wish for a global one-size-fits-all architecture – or simply “because everyone does it” The last point leads to the actual pitfall. ## The pitfall: the pattern for its own sake The biggest risk isn’t the wrong technology but the wrong motivation. Greg Young describes the core precisely: teams want to implement CQRS and Event Sourcing everywhere, as a cookie-cutter architecture – and that’s exactly a massive risk. A pattern gets introduced because it shines, not because a concrete problem calls for it. Fowler advises caution because the pattern is hard to use well. Three symptoms give away the cargo cult. There are events, but nobody can name a domain invariant they protect. There’s a projection, but the read shape is identical to the write shape. And there’s an event store, but no requirement for audit or history. When these three things come together, the pattern is decorative, not load-bearing. Then there are the usual confusions. CQRS isn’t Event Sourcing – the two are orthogonal and can be used separately. CQRS isn’t an architecture or a top-level pattern but a decision within a bounded context. CQRS isn’t CQS, because it separates models, not methods. CQRS needs neither a message bus nor DDD. And Event Sourcing isn’t the same as event-driven integration via pub/sub – it’s an internal persistence and source-of-truth mechanism, not a communication style between systems. Fowler deliberately separates these meanings of “event-driven,” because otherwise four different things blur under one word. ## More moving parts, made visible A direct contrast of the paths makes the trade-off tangible. The CRUD path is short; the CQRS path with Event Sourcing has more stations – and each station is a place where something can go wrong. ```mermaid flowchart LR subgraph CRUD C1[Client] --> H1[Handler] --> DB[(Database)] end subgraph CQRS_ES Cmd[Command] --> Agg[Aggregate] --> ES[(Event Store)] ES --> Proj[Projection] --> RM[(Read Model)] RM --> Q[Query] end ``` This diagram isn’t selling anything. It just makes honest that the lower variant means more components, more contracts and more failure paths. If you know this price and pay it anyway because the domain is worth it, you’re making a good decision. If you pay it without getting the value in return, you’re building complexity in advance. ## Conclusion CQRS and Event Sourcing aren’t better default architectures but targeted tools for targeted problems. The honest starting point is CRUD, and for the majority of systems it remains the right answer. The two patterns pay off when a domain has real, colliding invariants, when read and write load diverge strongly or when audit and time-travel requirements demand a complete history – and when the team is ready to carry eventual consistency and event versioning. They become overhead in simple CRUD apps, in small teams, without real invariant complexity and whenever the pattern is chosen out of fashion rather than need. The best way to handle this is a conscious, context-local decision. Not globally, not as a cookie cutter, but per bounded context, with a clear “what for.” I described why CQRS needs this domain boundary and isn’t a framework in [CQRS Is a Domain Boundary](https://www.mikebild.dev/en/blog/cqrs-is-a-domain-boundary-not-a-framework/). The most mature architectural quality often shows not in using a demanding pattern – but in deliberately, and for good reason, not using it. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-cqrs-event-sourcing.en.html - Martin Fowler, CQRS: https://martinfowler.com/bliki/CQRS.html - Martin Fowler, Event Sourcing: https://martinfowler.com/eaaDev/EventSourcing.html - Martin Fowler, Command Query Separation: https://martinfowler.com/bliki/CommandQuerySeparation.html - Martin Fowler, What do you mean by Event-Driven?: https://martinfowler.com/articles/201701-event-driven.html - Greg Young, CQRS is not an Architecture (2012): https://gregfyoung.wordpress.com/2012/09/09/cqrs-is-not-an-architecture/ - Greg Young, CQRS (2012): https://gregfyoung.wordpress.com/2012/03/02/cqrs/ - Vaughn Vernon, Implementing Domain-Driven Design (sample): https://ptgmedia.pearsoncmg.com/images/9780321834577/samplepages/0321834577.pdf - My own talk material “CQRS + Event Sourcing” (SlideShare) The sources anchor the terms against established standards. The actual message remains the context-local decision to use the pattern only where the domain deserves it. --- # GraphQL Concepts: Schema, Resolvers, Execution URL: https://www.mikebild.dev/en/blog/graphql-concepts-schema-resolvers-execution/ Date: 2021-06-24 # GraphQL Concepts: Schema, Resolvers, Execution GraphQL isn’t a query language for databases, and a resolver isn’t a controller. Both comparisons hold up to a point and then break – at the latest with the query that looks harmless and triggers thirty individual database calls in the server. The explanation isn’t in the manual of whichever server you use but in the specification. Once you have properly understood its execution rules, you read different GraphQL servers with the same mental model. The GraphQL overview laid out the topic in breadth, from the schema to federated architecture. Here we go one level deeper, to the ideas behind the tools: what a schema really is, why a query looks like its response, and how execution walks through the tree field by field. That sounds like basics, but it’s exactly on these basics that it’s decided whether you master GraphQL or merely use it. ## The schema is a typed graph On first reading, a schema looks like a collection of data types. It is that, but the decisive property lies in the relationships between the types. Let’s take a blog again: ```graphql type Author { id: ID! name: String! posts: [Post!]! } type Post { id: ID! title: String! author: Author! } ``` `Author` points to `Post`, and `Post` points back to `Author`. So the schema doesn’t describe a flat catalog but a graph: the types are nodes, and the fields that point to other types are edges. The name is meant literally. A query is then nothing more than a path through this graph that the client chooses itself. The modifiers are part of the contract, not decoration. `String!` means: this field is guaranteed to be present. `[Post!]!` means: guaranteed to be a list, guaranteed to have no gaps in it. A client can rely on this and doesn’t have to check defensively for `null` where the schema rules `null` out. Conversely, a non-nullable field that does return `null` forces an error – so the guarantee is enforced, not merely promised. And then there are the three root types: `Query`, `Mutation` and `Subscription`. They are the only doors into the graph. Everything a client can do starts at a field of one of these three types. Whatever isn’t there doesn’t exist for the client. That makes the schema a complete, binding contract – and one of the few API descriptions that are documentation, validation rule and type definition at the same time. ## A query is a shape The second idea is simple and still the one that surprises people switching over the longest: a GraphQL query has the same shape as its response. ```graphql query { author(id: "1") { name posts { title } } } ``` The response to it has the same structure – an `author` with a `name` and a list of `posts`, in which every entry has a `title`. You don’t describe how data is fetched but which shape you want to have in the end. That’s the same declarative attitude that shows up elsewhere in the modern frontend world: you name the goal, not the path. From this follows the well-known promise of reducing over-fetching and under-fetching at the interface. The client only receives the selected fields and can request related data in one document. That guarantees neither a single network round trip under every transport architecture nor efficient access behind the resolvers. But the server gets a precise description of what is needed – a good basis for planning execution accordingly. ## The resolver model Now to execution. For every field in the query, the server calls a function, the resolver. A resolver always receives the same four arguments, in this order: ```js function resolver(source, args, context, info) { // source – the parent object (the return value of the field above) // args – this field's arguments in the query // context – a per-request object (e.g. the logged-in user, data access) // info – information about execution state (which field, which path) } ``` The first argument is the key to understanding the chain. The return value of a resolver becomes the `source` for the resolvers of the fields below it. If the resolver for `author` resolves an author, the resolver for that author’s `posts` gets exactly this author as `source` and can use it to load the posts. ```js const resolvers = { Query: { author: (source, { id }, context) => context.db.loadAuthor(id), }, Author: { // source here is the author from the resolver above posts: (author, args, context) => context.db.loadPostsForAuthor(author.id), }, Post: { // source here is a single post author: (post, args, context) => context.db.loadAuthor(post.authorId), }, }; ``` For most fields, you don’t write a resolver at all. If a field is called `name` and the parent object has a `name` property, the default resolver kicks in: it reads the property of the same name from the `source`. So you only write resolvers explicitly where something needs to be done – where data is loaded, computed or transformed. That keeps most schemas surprisingly lean. The `context` deserves a sentence of its own, because a lot depends on it. It’s built once per request and passed to every resolver. That’s where the identity of whoever makes the request ends up, and that’s where access to the data sources lives. Because every resolver sees the same context, it’s the natural place for authentication and for shared resources – without having to thread them through every function signature. ## The order of execution How exactly does execution walk through the tree? It follows the selection recursively from the root fields to their subfields. A subfield can only be resolved once the value of its parent field is available; independent sibling fields, on the other hand, may be evaluated in parallel. So it isn’t a strictly clocked breadth-first traversal, level by level. ```mermaid flowchart TB Q["Query"] --> A["author resolver
    returns author"] A --> N["name
    (default resolver)"] A --> P["posts resolver
    returns list"] P --> T1["title of post 1"] P --> T2["title of post 2"] ``` Two subtleties matter, because they have consequences in everyday work. First: the server resolves sibling fields on the same level concurrently, not strictly one after the other. If a resolver returns a promise, the server waits for it, but it doesn’t block the siblings. That’s why resolvers must not make assumptions about their execution order relative to neighboring fields – they should work independently of one another. Second, and this is the one deliberate exception: at the top level of a mutation, execution runs serially. If a mutation names several write fields, the server executes them one after the other in document order. That replaces neither transactions nor isolation. For queries, freedom from side effects is an important convention, not a guarantee enforced by the execution model; that’s why the server may evaluate independent root fields in parallel. ## N+1 and why batching belongs to it An almost inevitable problem follows from the resolver model, one that every GraphQL developer runs into sooner or later. If someone queries a list of authors and the posts for each, the `posts` resolver runs once per author. With ten authors, that’s ten calls – and if each makes its own database query, you have ten queries plus the one for the author list. That’s the N+1 problem: one query for the list, N more for the children. The way out is batching. Instead of running off immediately, you collect all requests that arise within one execution tick and answer them with a single query. The usual implementation is the DataLoader library: you no longer ask the database directly but a loader for an ID; the loader waits until the end of the current tick, bundles all collected IDs and resolves them in one go. Along the way, it remembers within the request what it has already loaded, so the same ID isn’t fetched twice. ```mermaid flowchart LR R1["posts of author 1"] --> L["DataLoader
    collects IDs in the tick"] R2["posts of author 2"] --> L R3["posts of author 3"] --> L L -->|one batched query| DB[("Database")] ``` Batching doesn’t paper over a design flaw. It’s the consistent answer to the nature of the resolver model: field-by-field resolution is the reason for GraphQL’s flexibility – and batching is both its price and the clean solution for it. A loader belongs in the `context`, so that it’s fresh for each request and its cache doesn’t persist across request boundaries. ## Why these concepts last You can build GraphQL with Apollo Server, with GraphQL Yoga, with a library in C#, Go or Python. The server changes, the ecosystem shifts, the specification gets new versions. But the schema remains a typed graph, the query remains a shape, the resolvers remain a chain with the same four arguments, and execution remains a top-down traversal with serial mutations and concurrent siblings. That’s exactly why it pays to understand this level and not just the API of a particular server. If you know what a resolver receives and how execution runs through the tree, you can narrow down N+1 problems in a more targeted way, design [schemas that grow with you](https://www.mikebild.dev/en/blog/a-graphql-schema-that-grows/), and find your way around a different server faster. The tools are interchangeable. The concepts aren’t. ## Further reading - Repository introduction-graphql (chapters resolver, schema, subscriptions): https://github.com/mikebild/introduction-graphql - Slide overview for this topic area: https://slides.mikebild.dev/introduction-graphql.en.html - GraphQL, execution: https://graphql.org/learn/execution/ - GraphQL, Schema and types: https://graphql.org/learn/schema/ - GraphQL specification, execution: https://spec.graphql.org/ - DataLoader (batching and caching per request): https://github.com/graphql/dataloader --- # GraphQL APIs with AppSync and DynamoDB URL: https://www.mikebild.dev/en/blog/graphql-apis-with-appsync-and-dynamodb/ Date: 2021-06-15 If you publish a GraphQL schema, you have taken on running a server – even if the project plan only says “schema and clients”. The resolvers have to run somewhere, the connections have to end somewhere, the load has to be absorbed somewhere. That bill doesn’t arrive on deployment day; it arrives every month after. The popular GraphQL introductions stop before this bill. Defining types, writing queries, fetching data with Apollo or urql: all well explained. The server with the resolvers, the database underneath, scaling, the real-time connections – they say nothing about those. Still, you can’t define this layer away. Someone builds it, deploys it and keeps it running. That leaves the question of who this someone is: your own team or a managed service. I tie the answer to a concrete setup – AWS AppSync on DynamoDB, as it actually looks in mid-2021, including the VTL mapping templates that take some getting used to at first. The code isn’t the core here. The core is what this decision gains you and what it costs. **Editorial note (July 2026):** Besides VTL, AppSync today supports the JavaScript-based resolver runtime `APPSYNC_JS`. VTL remains valid, but it is no longer the only direct mapping to DynamoDB. Managed takes running the GraphQL server off the team’s hands; schema, resolvers, permissions, data model, deployment and observability remain your own work. ## What AppSync actually is AppSync is a fully managed GraphQL layer. The crucial point: you don’t run your own GraphQL server. There is no Node process with Apollo Server, no container, no hosting, no scaling logic you would have to take care of. Instead, you upload a schema in the GraphQL Schema Definition Language (SDL) and attach a resolver to each field that points to a data source. AWS handles the rest. This shift is the real value. In a classic setup, the GraphQL server is the centerpiece that you write, deploy and run yourself. With AppSync, running that server lies with AWS, while the team describes the mapping between schema field and data source as well as its infrastructure. This is the familiar serverless trade: less operations of your own in exchange for tighter coupling to the service. A resolver always connects exactly one schema field to a data source. And in 2021 there is a manageable but well-covered selection of those: - DynamoDB tables as a key-value and document store - AWS Lambda for any custom logic - HTTP endpoints to connect existing REST APIs - Amazon Elasticsearch Service for full-text search - relational databases via RDS or Aurora Serverless, plus “None” local resolvers without an external source In this post I focus on DynamoDB, because it is the most common combination in serverless projects and because it shows the VTL mechanics best. ## The request flow Before we look at code, it helps to look at the path a request takes. A client sends a GraphQL query or mutation to AppSync. AppSync validates it against the schema and calls the matching resolver for the requested field. The resolver has two parts: a request template that translates the GraphQL request into a DynamoDB call, and a response template that turns the DynamoDB result back into GraphQL form. ```mermaid flowchart LR Client[GraphQL Client] -->|Query / Mutation| AppSync[AppSync
    Schema + VTL Resolver] AppSync -->|Request Template| DDB[(DynamoDB Table)] DDB -->|Response Template| AppSync AppSync -->|JSON Result| Client AppSync -.->|other data sources| Lambda[AWS Lambda] AppSync -.->|other data sources| HTTP[HTTP Endpoint] ``` These two templates are the centerpiece and, at the same time, the part where opinions split in 2021. That’s because they are not written in JavaScript but in the Apache Velocity Template Language, VTL for short. ## VTL: the language in between VTL is a template language, not a full programming language. It can insert values and express simple conditions and loops, but it is deliberately kept narrow. For translating between GraphQL arguments and DynamoDB calls, that is enough in most cases, and AWS ships a set of helper functions that take care of the typical tasks. Let’s take a small CMS as an example. We want to create blog posts, fetch them individually and be notified in real time about new posts. The schema looks like this: ```graphql type Post { id: ID! title: String! body: String! } type Query { getPost(id: ID!): Post } type Mutation { createPost(title: String!, body: String!): Post } type Subscription { onCreatePost: Post @aws_subscribe(mutations: ["createPost"]) } ``` This is plain SDL, as you know it from any GraphQL introduction. The only AppSync-specific addition is the `@aws_subscribe` directive on the subscription field, more on that later. First, the resolvers for `createPost` and `getPost`. ### A PutItem resolver When a client calls `createPost`, a new item should land in the DynamoDB table. The request template describes exactly this `PutItem` call: ```vtl { "version": "2017-02-28", "operation": "PutItem", "key": { "id": $util.dynamodb.toDynamoDBJson($util.autoId()) }, "attributeValues": $util.dynamodb.toMapValues($ctx.args) } ``` A lot happens in a small space here. The version string `"2017-02-28"` sets the template format. In 2021 that’s the default value you don’t change without a specific reason. The `operation` field tells DynamoDB what to do. The key is created via `$util.autoId()`, a helper function that generates a UUID so that each post gets a unique primary key. The most important point hides in `$util.dynamodb.toDynamoDBJson(...)` and `$util.dynamodb.toMapValues(...)`. DynamoDB doesn’t expect values as bare strings or numbers but in a typed attribute format: a string becomes `{"S": "..."}`, a number `{"N": "..."}`. These helper functions handle the conversion automatically. If you forget them and insert the raw values directly, you write an item in the wrong format – the mistake almost everyone stumbles over once when getting started with AppSync. The response template, by contrast, is unspectacular. It simply returns the written item as JSON: ``` $util.toJson($ctx.result) ``` `$ctx`, also available as `$context`, is the object that gives you access to everything relevant: `$ctx.args` for the arguments of the GraphQL operation, `$ctx.identity` for information about the calling user, `$ctx.result` for the result of the data source. The response template uses `$ctx.result` to send the item that was just written back to the client. Besides the plain result, AppSync also provides `$ctx.error` in the response template in case the data source returns an error, such as a rejected condition on a `PutItem`. If you ignore it, you silently return `null` on failure instead of giving the client a meaningful message. With `$util.error(...)` or `$util.appendError(...)` you can pass the error through to the GraphQL response in a controlled way, so that it ends up in the `errors` block of the response. For the two simple resolvers here, you can still do without it, but as soon as real conditions come into play, this check belongs in the template. ### A GetItem resolver For `getPost`, things are even simpler. The request template describes a `GetItem` call with the `id` argument as the key: ```vtl { "version": "2017-02-28", "operation": "GetItem", "key": { "id": $util.dynamodb.toDynamoDBJson($ctx.args.id) } } ``` Here, too, the value from `$ctx.args.id` goes through `toDynamoDBJson` so that it arrives at DynamoDB in the right format. The response template is identical to the previous one: ``` $util.toJson($ctx.result) ``` When you put these two resolvers side by side, the principle becomes tangible: a resolver is always a pair of request and response template that connects a schema field to a concrete DynamoDB operation. There is no more magic behind it. The available operations cover the usual DynamoDB repertoire. Besides `GetItem` and `PutItem`, there are `UpdateItem` and `DeleteItem`, plus `Query` and `Scan` for multiple results as well as the batch and transaction variants such as `BatchGetItem` or `TransactWriteItems`. The four single-item operations are enough to get started, and you grow into the more complex variants along with the data model. The nice thing is that the pattern always stays the same. You change the `operation` field, adjust key and values, and the structure of the template barely changes. This uniformity is what makes VTL manageable in daily work despite its clunkiness. ## Subscriptions with no effort of your own The part that surprises people most at first contact is the real-time subscriptions. In a self-built GraphQL server, this is the most laborious part of all: managing WebSocket connections, running a pub/sub system, keeping state in sync across several server instances. With AppSync, you have to do none of that. Let’s recall the directive from the schema: ```graphql type Subscription { onCreatePost: Post @aws_subscribe(mutations: ["createPost"]) } ``` This one line is enough. `@aws_subscribe(mutations: ["createPost"])` binds the subscription field `onCreatePost` to the `createPost` mutation. Whenever this mutation completes successfully, AppSync pushes the result over a WebSocket connection to all clients that have subscribed to `onCreatePost`. No polling, no server of your own, no connection management. ```mermaid sequenceDiagram participant A as Client A participant AS as AppSync participant D as DynamoDB participant B as Client B (subscribed) A->>AS: mutation createPost AS->>D: PutItem D-->>AS: written item AS-->>A: created Post AS-->>B: onCreatePost (WebSocket push) ``` The connection runs over WebSockets, which AppSync provides out of the box. The client only has to subscribe to `onCreatePost` once and then automatically receives every new post. For a live feed, a chat feature or a dashboard, this is a huge simplification, because the entire real-time part disappears from your own operational responsibility. One detail you must not overlook: without the `@aws_subscribe` directive, simply nothing happens. More than once I have seen someone define a subscription, connect the client and then wonder why no events arrive. The answer was the same every time: the directive was missing or pointed to the wrong mutation. The subscription field has to be coupled explicitly to the mutation that triggers it. ## Where VTL reaches its limits As elegant as the approach is, its edges are just as clear. VTL is deliberately not a programming language, and you notice that as soon as the logic gets more complex. Nested conditions, multi-step transformations, merging several sources: you can express all of this in VTL somehow, but the templates quickly become unreadable and hard to maintain. The limit lies where a template does more than reorder arguments and pour them into a DynamoDB call. As of 2021, more complex logic belonged in a Lambda resolver. Today you should first check whether an `APPSYNC_JS` resolver expresses the mapping more readably; for free-form runtime logic and external libraries, Lambda remains the further-reaching option. VTL is still well suited for lean, direct mappings to DynamoDB. The second edge doesn’t concern AppSync but DynamoDB itself. Whether an access becomes a `Query` or a `Scan` is decided by the table design. A `Query` uses partition and sort key or a global secondary index and is fast and cheap. A `Scan` reads the whole table if in doubt and becomes expensive and slow as the data grows. You have to think through these access patterns before the first write, because DynamoDB rarely forgives a poorly planned key design after the fact. The nice AppSync frontend doesn’t change the fact that underneath sits a DynamoDB table with its own rules. ## Managed or self-hosted: the real decision So far it has been about mechanics. The reason I bring up AppSync in projects at all lies one level higher. A GraphQL server is not a feature you write once and then forget. It is a permanent operational commitment. It has to run, scale, be updated and be monitored, and with real-time connections, all the state across several instances comes on top. These costs don’t arise once during the build but every month in operation. At this point, build vs. buy means concretely: running it yourself means a Node process with Apollo Server, hosting, a scaling strategy, a pub/sub system for subscriptions and the willingness to fix all of it at night when things go wrong. Managed means that I declare schema, resolvers and data sources and hand the rest over to AWS. I then no longer pay in operating hours but in usage and in a piece of control that I give away. When does managed hold up? Whenever the GraphQL server is not a differentiator for the product but a necessity. A CRUD backend with a real-time feed is rarely the part with which a team stands out from the competition. Exactly such standard layers are better bought in, because every self-operated hour is missing where the team actually creates value. Small teams without their own platform team, projects with fluctuating load, prototypes that have to go live quickly: in all these cases, dropping the operations is worth more than the control you give up. When does managed become a dead end? As soon as the mapping the service offers no longer fits your own problem. For AppSync in 2021, VTL is this mapping. As long as I pour arguments into DynamoDB calls, it’s a good trade. As soon as I squeeze nested logic, multi-step transformations or merging several sources into templates, I pay back the managed convenience with maintainability. The second dead-end marker is lock-in. Schema and clients stay portable; the VTL resolvers and the DynamoDB key design don’t. If you expect to switch providers later, you should keep this boundary layer deliberately thin. This boils the decision down to a few criteria. Is the layer standard or differentiation? How expensive are operations relative to team size? How well does the offered mapping fit your own problem, today and in two years? And how deep does the lock-in go if the answer no longer fits one day? Managed is not a matter of faith but a calculation you redo for each layer. For AppSync, it clearly comes out in favor of buy for a large share of serverless projects, but not for all of them. ## What remains in the end I’ll come back to the beginning, to the question of running the server. The popular GraphQL content covers schema design and the client side. That is important and stays important, no matter which backend sits underneath. AppSync with DynamoDB is the other half, the managed backend, where the self-written server melts down into a configuration of schema, resolvers and data sources. The effect of this decision is concrete: the team still deploys schema, resolvers and infrastructure, but doesn’t run its own GraphQL process or its own WebSocket layer. This leaves more time for the data model and domain logic. Whether the calculation works out depends on how well the resolver runtimes and data sources fit the problem. The price for this is the VTL templates and a degree of lock-in to AWS. Both are manageable as long as you know the limits: lean mappings in VTL, complex logic in Lambda, a key design that anticipates the access patterns. Where these limits hold, the trade is excellent. Where they break, the layer should be built yourself. Drawing this line cleanly is the real architecture work, not writing the templates. AppSync doesn’t stand on its own. It meshes with Lambda, DynamoDB and the other managed services, and it unfolds its value precisely in this interplay. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-aws-serverless.en.html - Repository with the schema and resolver examples from my serverless workshops - [DynamoDB resolver reference (AWS)](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html) - [`APPSYNC_JS` resolver reference (AWS)](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html) - [Tutorial: Simple Post Application with DynamoDB resolvers (AWS)](https://docs.aws.amazon.com/appsync/latest/devguide/tutorial-dynamodb-resolvers.html) - [Resolver mapping template overview (AWS)](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-overview.html) - [$util utility reference (AWS)](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference.html) - [AppSync FAQs on data sources and subscriptions (AWS)](https://aws.amazon.com/appsync/faqs/) --- # Using Context Well: A Distribution Path, Not Secret Global State URL: https://www.mikebild.dev/en/blog/using-react-context-well/ Date: 2021-05-26 # Using Context Well: A Distribution Path, Not Secret Global State ```jsx const AppContext = createContext(null); function AppProvider({ children }) { const [user, setUser] = useState(null); const [filter, setFilter] = useState(""); const [items, setItems] = useState([]); return ( {children} ); } ``` Three pieces of state hang off a single provider, and the object behind `value` is created anew on every render. One character in the filter field is enough, and everything that reads this Context re-renders along with it – including the header, which only shows the name of the signed-in person. A shortcut through the component tree has turned into a store without anyone consciously making that decision. Context can do exactly one thing: provide a value at the top and make it readable further down, without the layers in between passing it along. Everything else – where the value comes from, who updates it, how often it changes – remains manual work and has to be decided beforehand. Let us start with the problem Context was built for. ## The problem: prop drilling In React, data flows from top to bottom. A component passes values to its children through props, they pass them on to their children, and so on. As long as the path is short, that is exactly right – the data flow is visible, and you can read from the props what a component needs. It gets unpleasant when a value is created far up and needed far down, but nothing in between needs it at all. Take the signed-in person: they are determined once at the very top, and needed in the header, in a comment form deep in the tree and in a menu somewhere else entirely. All components along the way have to accept the value and pass it on, even though they only funnel it through. ```jsx function Page({ user }) { return ; } function Layout({ user }) { return ; } function Sidebar({ user }) { return ; } function Profile({ user }) { return {user.name}; } ``` `Layout` and `Sidebar` do not care about `user`. They only carry the prop along because someone further down needs it. That is exactly what is called prop drilling – you drill a value through a layer of components that have nothing to do with it. It makes intermediate components harder to reuse, because they are coupled to data they only pass through, and every new intermediate layer has to take the prop along by hand. ```mermaid flowchart TB subgraph drilling["prop drilling"] P1["Page (user)"] --> L1["Layout
    only passes user on"] L1 --> S1["Sidebar
    only passes user on"] S1 --> Pr1["Profile
    needs user"] end subgraph context["Context"] P2["Provider (user)"] -.-> Pr2["Profile
    reads via useContext"] end ``` ## How Context works Context reverses this passing along. Instead of handing a value down layer by layer, you provide it once at the top and read it directly at the bottom – without bothering the layers in between. Three parts belong to it: `createContext` creates the object, a `Provider` provides the value for a subtree, and `useContext` reads it where it is needed. ```jsx import { createContext, useContext } from "react"; const CurrentUserContext = createContext(null); function Page({ user }) { return ( ); } function Profile() { const user = useContext(CurrentUserContext); return {user.name}; } ``` `Layout` and `Sidebar` are out of the picture – they no longer know about `user` and do not have to pass anything on. `Profile` takes the value directly from the nearest provider above it. That is exactly the job of Context, and for this job it is the right tool: it is a distribution path, a shortcut through the tree. What matters is what does not happen here. The provider does not create the value. It receives it from above and makes it available. Where `user` comes from, who changes it, where it lives – all of that is still completely open at this point. And this is exactly where the problems start if you are not careful. ## The central trap: Context as a substitute for state ownership Because Context makes values so conveniently available everywhere, a temptation is close at hand: you simply put everything in it that several components need. The loaded list, the current filter, half-opened dialogs, the entire application state – Context becomes the storage place for everything shared. That feels great at first and reliably takes its revenge later. Two consequences come back to bite you. The first is rendering. React compares the old and new provider value with `Object.is`. If they differ, the components that read this Context re-render; plain descendants without `useContext` are not automatically affected. With a large object as the Context value, however, a changed reference also affects consumers that only use a different field from it. A small update can turn into a wave of renders this way. ```mermaid flowchart TB Change["Context value changes"] --> P["Provider"] P --> C1["Consumer A
    shows the value"] P --> C2["Consumer B
    reads another field –
    re-renders anyway"] P --> C3["Consumer C
    reads another field –
    re-renders anyway"] ``` In one project, the value of a search field happened to sit in the same Context as the theme. With every keystroke in the search field, half the UI flickered – components that had nothing to do with the search re-rendered along with it, just because they were attached to the same Context. The value had ended up in the wrong container. The second consequence is coupling. Everything that reads from a Context is bound to that provider. You can no longer use, test or reuse such a component in isolation without building the matching provider around it. The more a Context holds, the more components depend on it, and the more sluggish the application becomes. Context makes the origin of a value invisible – that is an advantage for distribution and a problem for ownership, because you no longer see who is actually responsible for a value. The core of the misunderstanding is this: Context answers the question “how does the data get to where it is needed.” It does not answer the question “who owns the data and who may change it.” You still have to answer the second question – state ownership – yourself, with `useState` or `useReducer` in a clearly named component. Context does not replace this decision; it only transports its result. ## Rules for clean use Three rules follow from this separation, and they keep Context exactly what it is meant to be – a means of transport. First: ownership lives at the top, Context only passes it through. The state belongs in a clearly named component – let us call it `CurrentUserProvider` – that holds it with `useState` or `useReducer`. This component is the one place where the value lives and is changed. Context transports it from there downward, nothing more. If you open the provider and look for `useState`, you find the owner right away; if you do not find it, you have probably built hidden global state. Second: keep the value stable. This is where the most common concrete mistake lies. If you write a fresh object directly into `value`, every render of the provider component creates a new reference – and because the reference changes, all consumers re-render, even if nothing has changed in content: ```jsx function CurrentUserProvider({ children }) { const [user, setUser] = useState(null); // new object on every render → all consumers re-render return ( {children} ); } ``` The fix is to memoize the value so that the reference only changes when something has actually changed: ```jsx function CurrentUserProvider({ children }) { const [user, setUser] = useState(null); const value = useMemo(() => ({ user, setUser }), [user]); return ( {children} ); } ``` With state from `useReducer`, a second step is often worth it: put state and dispatch into two separate Contexts. Dispatch is stable; it never changes. If you split it off, components that only trigger actions and do not display the state at all no longer re-render on a state change – they only depend on the immutable dispatch Context. ```jsx const StateContext = createContext(null); const DispatchContext = createContext(null); function StoreProvider({ children }) { const [state, dispatch] = useReducer(reducer, initialState); return ( {children} ); } ``` Third: do not put every changing value into it. Some things you reflexively put into a Context belong elsewhere. Server data – loaded lists, detail data, search results – is not application state but a cache, and it belongs in a data fetching library, not in Context. I covered this boundary in detail in “Client State vs. Server Cache.” And the current selection, the filter, the page in a list belong in the URL – shareable, bookmarkable, and they survive a reload. Subtract these two categories and surprisingly little is left for Context, and exactly that remainder is its real home. ## What Context is really good for Context plays to its strength with rarely changing, app-wide things – with what describes the environment of an application rather than its actual data. The active theme, the selected language, the signed-in person, an app-wide service or dispatch function: such values change rarely but are needed in many places. That is exactly what a distribution path that skips the layers in between is meant for. The common denominator of these good cases is that they are “environment” and not “application data.” They do not change every second, so the wave of renders hardly matters. And they really are app-wide, so the coupling to a provider does not get in the way – you only want to use these components inside the application anyway. Before every new Context, a test question is therefore worth asking: does the value describe the environment a component runs in, or the data it displays? Only the former belongs in it. ## Context and reducer as a small global core For a manageable global core, Context and `useReducer` can be combined into a lightweight pattern. The reducer holds the state and the logic in one place, two separate Contexts distribute state and dispatch, and consumers access them through small hooks: ```jsx function useStore() { return useContext(StateContext); } function useDispatch() { return useContext(DispatchContext); } ``` That goes surprisingly far – for a shopping cart, a few app-wide settings, a small set of actions. Ownership is clear (in the `StoreProvider`), transport is clean (two Contexts), and separating state and dispatch keeps renders in check. But you should know the limit of this pattern and name it openly: Context is not state management, it is transport. The reducer next to it is the actual logic, and Context only passes its result through. As long as the core stays small, the pattern holds. When the logic grows – many interdependent pieces of state, selectively reading individual fields without waves of renders, middleware, persistence, time travel while debugging – the combination reaches its limits. Then you need a real store that is built for exactly these jobs. That is not a defeat for Context, but the right division of labor: Context never claimed to be a store. ## What should stick Context answers a single question very well: how the data gets to where it is needed. It does not answer the other, more important question: who owns it and who changes it. You have to answer that second question yourself, in a clearly named component with `useState` or `useReducer`, before you touch Context at all. If you keep these two questions cleanly apart, you use Context for what it is – a distribution path for a few rarely changing, app-wide values, with a stable `value` and, where needed, separate state and dispatch Contexts. If you mix them up, you build global state through the back door, complete with waves of renders and coupling. The difference costs one single deliberate decision while writing and saves a lot of debugging afterwards. ## Further reading - Repository introduction-react: https://github.com/mikebild/introduction-react - react.dev, “Passing Data Deeply with Context”: https://react.dev/learn/passing-data-deeply-with-context - react.dev, “Scaling Up with Reducer and Context”: https://react.dev/learn/scaling-up-with-reducer-and-context - [react.dev: `useContext`, value comparison and re-rendering](https://react.dev/reference/react/useContext) --- # Reading Data in Python: CSV, JSON, Excel and Databases URL: https://www.mikebild.dev/en/blog/reading-data-in-python/ Date: 2021-04-27 A reader is not a transport function. `csv.DictReader`, `json.load`, `pandas.read_excel` – they all turn foreign bytes into Python objects, and in that transition it is decided whether an `ä` stays an `ä`, whether a required column is filled and whether an input will later wipe out an entire table. And the sources are rarely as tidy as you’d like: a CSV file someone pulled from an export. A JSON response from an API. An Excel workbook with three sheets and a header that only starts in row four. Or an SQLite file sitting quietly in the project folder, waiting to be queried. Which reader I pick for this is the smaller decision. The bigger one is where trust is established: Is the encoding right, are required fields filled, do the types match? A wrongly decoded umlaut or an unchecked input rarely costs anything at read time – the bill comes later, in the report to the customer, in the database, in the model trained on garbage. Reading data is therefore the boundary where data quality is decided. The step is unspectacular, and yet a surprising number of projects get stuck on it. It isn’t hard, just confusing: Python has its own way for every format, and it’s easy to lose track of which one is right when. This article puts together a small toolkit for it: the standard library for direct, row-by-row access, pandas for tabular analysis work, and a parameterized database query that never leads into the most common security trap in the first place. The tools are quickly explained – more interesting is the attitude behind them: treating data as a domain whose quality you actively own. ## Data is a domain, not a sideshow Before we get to readers, it’s worth taking a step back. If reading data is seen as transport – bytes in, objects out, move on – that is an expensive view, because it puts trust in the wrong place. If I only check late – in the report, in the analysis, in the production endpoint – then I’m checking data that has long since traveled through half my system. The error is then no longer a line in a file but an incident with a name: wrong revenue for the customer, a record that skews an analysis, an input that wipes a table. That’s why I treat reading data as its own small domain with a clear job: turn unknown bytes into trustworthy, typed objects – and reject everything that doesn’t meet that bar. Three questions decide the product risk here, and all three arise at the system boundary. Encoding: Is a character really the intended character? An `ä` instead of `ä` is not a cosmetic flaw. It is silent data damage that propagates through every later search, every comparison, every export. Trust: Who owns the source? I treat my own export differently from user input or a third-party API – for anything coming from outside, the assumption is that it may be hostile. Validation: Are the fields there, and do they have the expected shape? The trade-off lies in validation, because checking takes time. The further the data travels and the more people depend on it in the end, the earlier and stricter I check. A throwaway script for a one-off analysis can be lenient. A reader that feeds a customer database or a recurring report checks at the boundary and visibly rejects faulty data instead of passing it on without complaint. The gain is concrete: a problem shows up where it originates, with file and line – instead of three layers later as mysterious misbehavior that you have to trace backwards through half a system. ## The two camps: standard library or pandas Before we write code, a rough classification helps. Python already ships everything you need for the most common formats – `csv`, `json`, `xml.etree` and `sqlite3` are part of the standard library, with nothing to install. These modules work close to the raw data: you get lists, dictionaries, individual rows. That’s ideal when you want to process a file row by row, have little memory available or simply don’t want to pull an external dependency into your project. pandas belongs to the other camp. It’s an additional library, and it pays off whenever your data is tabular and you want to analyze, filter or aggregate it. Instead of maintaining a separate mental model for each format, in pandas you always end up in the same `DataFrame` – no matter whether the source was a CSV, an Excel workbook, a JSON document or an SQL query. `read_csv`, `read_excel`, `read_json`, `read_sql`: one reader per format, one common target. On top of that come type inference and a rich set of operations. The following overview shows the path from source to target structure: ```mermaid flowchart LR CSV[CSV] --> STD[Standard library
    csv, json, etree, sqlite3] JSON[JSON] --> STD XML[XML] --> STD DB[(SQLite/DB)] --> STD CSV --> PD[pandas
    read_csv, read_excel, read_sql] XLSX[Excel .xlsx] --> PD DB --> PD STD --> DICTS[dicts / lists] PD --> DF[DataFrame] ``` The classification I decide by is short: row by row, small, no extra dependency – standard library. Tabular, analytical, with filters and aggregates – pandas. And you can only sensibly read Excel in the modern `.xlsx` format through pandas anyway (with a helper library), because the standard library can’t do it. What matters is not the most convenient API but the data volume and the work that is supposed to happen with the data afterwards. ## CSV with the standard library: the classic CSV is the format you’ll run into most often, and at the same time the one with the most little pitfalls. The standard library offers two ways: `csv.reader` returns a list per row, `csv.DictReader` returns a dictionary per row and automatically uses the header row as keys. In practice I almost always reach for `DictReader`, because access through meaningful column names makes the code more readable. ```python import csv with open("customers.csv", newline="", encoding="utf-8") as f: reader = csv.DictReader(f) # header row becomes dict keys rows = [row for row in reader] # each row is a dict for row in rows[:3]: print(row["name"], row["email"]) ``` Two details on this `open` line are more important than they look. First, `newline=""`: the `csv` module handles line breaks inside fields itself, and if you don’t open the file with an empty `newline`, rows can get torn apart under certain conditions. The documentation says so, and it’s one of those rules you learn once and never forget – usually after the first broken record. Second, `encoding="utf-8"`. More on that in a moment, because this is where the pitfall lies that causes the most confusion in projects – hardly any data error shows up as reliably. A nice side effect of `DictReader`: because it iterates over the file, you can also use it for large files without loading everything into memory at once. Instead of materializing the list with a comprehension, you then process row by row in the loop and keep only what you really need. ## JSON: from file to Python object JSON is pleasantly straightforward in Python, because the structure maps almost one to one onto dictionaries and lists. `json.load` reads from an open file object, `json.loads` from a string. The result is a perfectly normal Python object you can work with right away. ```python import json with open("config.json", encoding="utf-8") as f: data = json.load(f) # dict or list, depending on the document print(data["version"]) for item in data["items"]: print(item["id"], item["title"]) ``` For writing back, there are the counterparts `json.dump` and `json.dumps`. When writing, `ensure_ascii=False` is usually worth it so umlauts end up in the file as real characters rather than `\u` escapes, along with `indent=2` for readable formatting. When reading, you don’t need these options – JSON is refreshingly undemanding there. ## Excel: here the path leads through pandas As soon as real tables come into play – several sheets, number formats, header rows – pandas becomes the tool of choice. `read_excel` reads an `.xlsx` into a DataFrame, and you can pick a specific sheet with `sheet_name`. ```python import pandas as pd df = pd.read_excel("report.xlsx", sheet_name="Sales") # openpyxl engine by default print(df.head()) print(df["revenue"].sum()) ``` One point many people stumble over the first time: for `.xlsx`, `read_excel` needs an additional library called `openpyxl`. Since pandas 1.2.0 (end of 2020), `openpyxl` has been the default engine for this format – the older `xlrd` library no longer supports modern `.xlsx` files and is only responsible for the old `.xls` files. So if you get an error message about a missing engine, the fix is almost always `pip install openpyxl`. If you pass `sheet_name=None`, pandas returns a dictionary of all sheets as DataFrames – handy when you want to read a whole workbook. And if your header isn’t in the first row, the `header` parameter helps you set the right row as column names. ## Databases: sqlite3 and the most important security note SQLite is my default tool for database access in small projects and prototypes, because it needs no server and the `sqlite3` module is already part of the standard library. The flow is always the same: open a connection, get a cursor, run a query, fetch the result, close the connection. ```python import sqlite3 conn = sqlite3.connect("shop.db") cur = conn.cursor() category = "books" cur.execute( "SELECT name, price FROM products WHERE category = ?", (category,), ) result = cur.fetchall() for name, price in result: print(name, price) conn.close() ``` The crucial part is in the `execute` line: the question mark as a placeholder and the value as a separate tuple in the second argument. This is not a matter of style but a matter of security. If you build the value directly into the SQL string instead – via concatenation or an f-string – you open the door to SQL injection. A manipulated input field can then rewrite the query, read data or delete entire tables. The comparison makes the difference clear: ```python # unsafe: never do this cur.execute(f"SELECT name, price FROM products WHERE category = '{category}'") # safe: the driver handles quoting and escaping cur.execute( "SELECT name, price FROM products WHERE category = ?", (category,), ) ``` Besides security, the parameterized way has a second advantage: the database driver handles quoting and escaping for you. You don’t have to worry about quotation marks in the value. One important detail: the placeholder `?` appears **without** surrounding quotation marks in the SQL text – the driver does the quoting, not you. If you want more convenience or want to switch between different databases, SQLAlchemy comes into play. With `create_engine("sqlite:///shop.db")` you set up a connection, and `pandas.read_sql(query, con)` reads the result directly into a DataFrame. That closes the loop between database and analysis: the query comes from SQL, and the result lands straight in the familiar pandas model. ## And XML? Don’t forget it, but you’ll rarely need it You’ll run into XML less often than you used to, but it still shows up in configurations, exports and older interfaces. The standard library covers it with `xml.etree.ElementTree`. You parse the source into a tree, get the root and navigate with `find`, `findall` and `iter` to the elements you care about. ```python import xml.etree.ElementTree as ET tree = ET.parse("catalog.xml") root = tree.getroot() for product in root.findall("product"): name = product.find("name").text price = product.get("price") # read an attribute print(name, price) ``` For simple structures, that’s entirely sufficient. With more complex XML documents with namespaces or deep nesting, it quickly gets fiddly – then I like to reach for specialized libraries. For everyday work, though, `ElementTree` covers most cases. ## Which reader for which format? To help you keep track, here is the mapping as a compact list: - For CSV, use `csv.DictReader` from the standard library for row-by-row reading and `pandas.read_csv` as soon as it gets analytical. - For JSON, `json.load` and `json.loads` from the standard library are enough; `pandas.read_json` helps when the JSON is tabular. - For Excel in the `.xlsx` format, the path leads through `pandas.read_excel` with `openpyxl` installed – the standard library can’t handle this format. - For databases, `sqlite3` covers direct, parameterized access; `pandas.read_sql` or SQLAlchemy come in when analysis or portability is needed. - For XML, `xml.etree.ElementTree` from the standard library is enough for manageable documents. ## Three pitfalls that strike again and again In practice, it’s rarely the readers themselves that cause problems, but three recurring topics around reading data. ### Encoding Why encoding is a product risk was covered above – here is the practical part. The default character set when opening a file depends on the platform, on Windows often `cp1252` instead of UTF-8. If umlauts appear as `ä` or `ö`, or a `UnicodeDecodeError` shows up, the encoding is almost always to blame, and the fix is to specify it explicitly: `encoding="utf-8"`. For files exported from Excel, you often need `encoding="utf-8-sig"`, because Excel puts a so-called byte order mark at the beginning, which plain `utf-8` misreads as a special character. ### Loading large files entirely into memory It’s tempting to simply load a CSV in full with `pandas.read_csv("big.csv")` – until the file is several gigabytes and memory overflows. pandas offers `chunksize` for this: instead of a DataFrame, you then get an iterator that lets you work through the file in blocks. ```python import pandas as pd total = 0 for chunk in pd.read_csv("big.csv", chunksize=100_000): total += chunk["amount"].sum() # process one block at a time print(total) ``` In the standard library you achieve the same by iterating row by row with `DictReader` instead of materializing everything into a list. One more note: `read_excel` has no native chunking – for very large tables it’s worth converting the data to CSV or into a database beforehand. ### SQL injection Important enough to repeat: never build user input into an SQL query via string concatenation or an f-string. Always use placeholders and pass the values separately. It doesn’t cost an extra line of code and saves you from an entire class of security vulnerabilities. The following decision tree sums up how I choose the path in practice: ```mermaid flowchart TD A{Tabular
    analysis needed?} -->|yes| B[pandas] A -->|no| C{Row by row,
    small, no dependency?} C -->|yes| D[Standard library] C -->|no| B B --> E{Very large file?} E -->|yes| F[chunksize / streaming] E -->|no| G[read directly] ``` ## Conclusion The choice of tool is quickly made: for row-by-row, direct access without an extra dependency, the standard library with `csv`, `json`, `xml.etree` and `sqlite3` is enough; as soon as things get tabular and analytical, or Excel is involved, pandas pays off with its uniform DataFrame model. The difference between a script that runs and one you trust doesn’t come from the readers but from the attitude: encoding, trust and validation belong at the system boundary. If you draw this boundary deliberately, you change the economics of the project. Errors show up early and with a name instead of late and mysteriously – that shortens debugging cycles and takes friction out of further work. The data that gets through is the data you can trust, which raises the quality of every later step. And the three reflexes that go with it cost almost nothing: always set the encoding explicitly so umlauts don’t fall apart. With large files, think early about `chunksize` or row-by-row streaming instead of filling up memory. Database queries always with placeholders, never with assembled SQL. The clear upper limit matters too: not every script needs full schema validation, and where effort and risk don’t match, leniency is the right choice. If you decide this instead of leaving it to chance, you reach your goal quickly and safely – and can turn to what’s actually interesting: what’s in the data. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-python.en.html - Repository `introduction-python` – data access examples from my training courses (`csv`, `json`, `sqlite3`, pandas). - csv – Python documentation: https://docs.python.org/3/library/csv.html - json – Python documentation: https://docs.python.org/3/library/json.html - sqlite3 – Python documentation: https://docs.python.org/3/library/sqlite3.html - xml.etree.ElementTree – Python documentation: https://docs.python.org/3/library/xml.etree.elementtree.html - pandas IO guide: https://pandas.pydata.org/docs/user_guide/io.html - pandas 1.2.0 – openpyxl as the default engine: https://pandas.pydata.org/docs/whatsnew/v1.2.0.html - SQLAlchemy documentation: https://docs.sqlalchemy.org/en/14/ --- # Architecture Decision Records: Decisions You Will Still Understand in Two Years URL: https://www.mikebild.dev/en/blog/adrs-decisions-you-still-understand/ Date: 2021-03-26 Five sections are enough to make an architecture decision durable: Title, Status, Context, Decision, Consequences. Michael Nygard described this format in 2011 in his blog post “Documenting Architecture Decisions” and called it an Architecture Decision Record, ADR for short – a small, versioned text artifact that records exactly one decision together with its forces. One page of Markdown, nothing more. Nygard states the motivation right in the first sentence: “One of the hardest things to track during the life of a project is the motivation behind certain decisions.” The *what* is in the code. The *why* is nowhere – or it’s buried in a Slack thread, a Confluence page nobody can find anymore, or in the head of someone who happens to be on vacation. The most expensive question in a project is therefore rarely “How do we build this?” but “Why did we actually build it this way back then?” A team takes over a system, runs into a strange decision – an unusual database, a homegrown cache, skipping the obvious message bus – and nobody can say whether it was intentional or an accident. The people who knew are long gone to the next project or the next company. What remains is code that executes a decision whose rationale has evaporated. ## The outcome first: less archaeology, faster handovers Before I talk about format and tooling, I want to say what ADRs bring in practice – because that’s what this is about, not another documentation ritual. In the projects where I introduced ADRs, one thing in particular gets dramatically shorter: the time it takes a new team member to go from “I understand the code but not the logic behind it” to “I can take part in decisions here.” Onboarding turns from digging into reading up. The second effect is subtler but more valuable. When a decision *has to* be written down, it also gets made more deliberately. While writing, you notice whether you really weighed alternatives or just took the first path that came along. The artifact doesn’t force more bureaucracy – it forces clarity. And clarity at the moment of decision is cheaper than any later reconstruction. What matters to me here is the distinction Nygard makes himself: agile methods are not against documentation, they are against *valueless* documentation. The 80-page architecture handbook that’s outdated by the first commit is valueless. A one-page ADR that sits next to the code and travels with it through the Git history is not. ADRs are the lightweight compromise between “write nothing down” and “document everything to death.” ## The format: five sections, one decision Nygard describes ADRs as “a format similar to an Alexandrian pattern” – a short text that describes a set of forces and records *one* decision in response to them. The format is deliberately minimal, and the brevity is not a shortcoming but the feature: small documents are more likely to be kept up to date than large ones. This is what an ADR typically looks like for me. It lives as Markdown in the same repository as the code, under `docs/adr/`: ```markdown # 7. Use PostgreSQL as primary datastore Date: 2021-03-12 ## Status Accepted ## Context The core service needs a transactional store. Expected load is moderate (low thousands of writes per minute at peak). The team has deep operational experience with PostgreSQL and none with distributed NewSQL stores. Strong consistency is a hard requirement for the billing path. ## Decision We will use PostgreSQL as the primary datastore for the core service. ## Consequences Positive: strong consistency, mature tooling, no learning curve for the team. Negative: single-primary HA needs operational care; revisit this decision if sustained write throughput exceeds ~5k writes/second. ``` The Context section is where the real value lies. It describes what Nygard calls the “balancing of forces” – the forces acting on the decision: expected load, team skills, consistency guarantees, cost. If you read this ADR two years from now, you don’t just see *that* PostgreSQL was chosen but under which assumptions. And – this is crucial – the Consequences section even names the condition under which the decision should be reevaluated. That’s not dogma; it’s a state of thinking, preserved. One point here is often overlooked: the Context has to describe the world *at the time of the decision*, not the world of today. An ADR is a snapshot, not a living document. That leads directly to the most important principle. ## Immutability: ADRs are never overwritten The most common mistake I see when teams try ADRs for the first time: they treat an ADR like a wiki page and update it when the decision changes. That destroys the whole point. An ADR is a log entry, not a state object. The rule is: once an ADR has been accepted, its content is never changed again. If the decision changes, you write a *new* ADR that replaces the old one. The old one gets the status `superseded` and a reference to its successor. The numbering is sequential and never reused – 0001, 0002, 0003, even if 0002 is long outdated. What you get is a decision *log*: a complete history that shows which decision applied when and what replaced it. ``` docs/adr/ # sequential, zero-padded, never renumbered 0001-record-architecture-decisions.md 0002-use-markdown-for-adrs.md 0007-use-postgres-as-primary-datastore.md # Status: superseded by 0012 0012-switch-to-cockroachdb.md # Status: accepted ``` You can think of this lifecycle as a state diagram. An ADR moves from `proposed` to `accepted` – and at some point, maybe, to `superseded`, with the pointer referring to the following ADR: ```mermaid stateDiagram-v2 [*] --> proposed proposed --> accepted: PR merged proposed --> rejected: not adopted accepted --> superseded: replaced by newer ADR superseded --> [*]: points to successor ADR rejected --> [*] ``` The charm of this is that the Git history and the ADR history run in parallel. Both live in the same repo, both travel through the same commits. When I check out an old commit, I see the ADRs that belonged to that state. The why travels through time with the code. ## Hallway talk versus artifact To show what ADRs actually change, a simple contrast helps. On one side is the normal state of many teams: decisions are made in meetings, in chat threads, in passing at the coffee machine. They are real, they shape the architecture – but they can’t be found anywhere. On the other side is the versioned Markdown artifact that lives in the repo and is reviewed via the pull request. ```mermaid flowchart LR subgraph Flurfunk A[Slack thread] --> X[lost knowledge] B[whiteboard photo] --> X C[hallway talk] --> X D[someone's memory] --> X end subgraph Artefakt E[ADR in docs/adr/] --> G[reviewed via PR] G --> H[versioned with the code] H --> I[readable in two years] end ``` The difference is not that no decisions are made on the left. The same decisions are made. The difference is whether the rationale becomes an artifact or evaporates. And in the end, that’s a question of friction: as long as writing things down costs more than forgetting them, things get forgotten. ADRs work because they make writing down so cheap – one Markdown file, one commit, done – that it’s worth it. ## Tooling: just enough not to get in the way You don’t need a tool for ADRs. A text file and Git are enough. Still, a bit of convention helps keep the numbering and the template consistent. Nat Pryce built `adr-tools` for this, a lean CLI you install via Homebrew: ```bash # create a new, auto-numbered ADR from the standard template $ adr new "Use PostgreSQL as primary datastore" # -> docs/adr/0007-use-postgres-as-primary-datastore.md # create an ADR that supersedes an earlier one $ adr new -s 7 "Switch to CockroachDB" # -> docs/adr/0012-switch-to-cockroachdb.md # and sets ADR-0007 status to "superseded by 0012" ``` If you prefer a richer template, MADR – “Markdown Any Decision Records” – offers a more structured one that explicitly leaves room for the options that were weighed. To get started, though, I almost always recommend the bare five Nygard sections. You can refine later; it’s hard to introduce discipline after the fact. The most effective lever isn’t a tool anyway but a process habit: an architecture-relevant change in a pull request only gets merged if the corresponding ADR is in the same PR. That makes the ADR part of the review. The decision isn’t just recorded but read by at least one other person at the same moment. The lonely “I just built something” becomes a deliberate, shared step. By the way, that the format holds up is not a lone opinion. The ThoughtWorks Technology Radar placed “Lightweight Architecture Decision Records” in *Adopt* – the highest recommendation level – as early as November 2017. That’s no longer a novelty; it’s established practice. ## Where ADRs tip over – the honest chapter ADRs don’t run themselves. They fail, and in three predictable ways. The first failure mode: ADRs go stale anyway. If you don’t write them with discipline for every relevant decision, you get a history full of gaps. And a history full of gaps is more dangerous than none at all, because it pretends to be complete. If someone reads “these are our decisions” and the crucial one is missing, they draw wrong conclusions. They rely on a log that lies – not by saying something false, but by leaving something out. Discipline beats tooling, always. No CLI and no template replaces the simple habit of pausing briefly at the moment of decision and recording it. The second failure mode: too big, too late. As soon as ADRs swell into design documents, the update rate drops, and Nygard’s whole point – brevity – is lost. Post-hoc ADRs are especially treacherous, that is, rationales you hand in weeks after the decision. They only rationalize instead of capturing the real forces. You then no longer write down *why* you decided but why the decision looks good in hindsight. That’s self-deception in Markdown – and it’s hard to spot, because a cleanly worded ADR looks convincing regardless of whether it captures the real forces or just builds a pretty facade in front of them. The third failure mode: the wrong granularity. Without a defined trigger, one of two things happens. Either every trifle becomes an ADR, and the signal drowns in noise. Or nobody knows what “architecture-relevant” means, and nothing gets written at all. A rough threshold, agreed on early in the team, helps: an ADR is written when a decision is hard to reverse, affects several teams or deliberately rejects an obvious alternative. Everything else is a comment in the code, not an ADR. This threshold may stay fuzzy; more important than the exact line is that the team shares any common idea of it at all. One more thought that lifts ADRs beyond pure documentation: if you take the condition in the Consequences section seriously – “revisit if write throughput exceeds 5k/s” – you can make it verifiable. In *Building Evolutionary Architecture*, Ford, Parsons and Kua call these *fitness functions*: automated checks that measure an architectural property. An ADR documents the decision; a Fitness Function watches over whether its assumption still holds. Together, they turn a dead document into a living guardian. ## Conclusion ADRs don’t solve a technical problem. They solve a memory problem – and in the long run, memory problems are more expensive than technical ones because they accrue interest. Every undocumented decision turns into a small debt over time: at some point, someone has to laboriously reconstruct what could have been written down in five minutes. The core is unspectacular and precisely for that reason durable: in my convention, an accepted text stays unchanged; a new decision replaces it with a reference to the old ADR. That way, context, decision and consequences stay versioned next to the code and reviewable via the pull request. This doesn’t need a new system, just the discipline to record the why while it’s still fresh. The easiest start is the first ADR itself – the one that records that from now on, ADRs will be written. `0001-record-architecture-decisions.md`. Everything else follows once the habit is in place. And in two years, someone will read it whom nobody on the team knows today. ## Further reading - Michael Nygard, “Documenting Architecture Decisions” (Cognitect, 2011): https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html - Martin Fowler, bliki “Architecture Decision Record”: https://martinfowler.com/bliki/ArchitectureDecisionRecord.html - ThoughtWorks Technology Radar, “Lightweight Architecture Decision Records” (Adopt, Nov 2017): https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records - adr.github.io – community collection on ADRs and tooling: https://adr.github.io/ --- # A GraphQL Schema That Grows: Evolution Without Breakage URL: https://www.mikebild.dev/en/blog/a-graphql-schema-that-grows/ Date: 2021-03-24 # A GraphQL Schema That Grows: Evolution Without Breakage A schema doesn’t break because it grows, but because it takes something back. One more field doesn’t bother any running client; one field less, a renamed argument, a withdrawn guarantee shuts it down. All of schema evolution rests on this one distinction – adding or taking back. In everyday work, it’s just less clear-cut than it sounds: some things look like a takeback and are completely harmless, some look purely additive and break anyway. The typed contract between server and client that I described in the GraphQL overview and in the GraphQL concepts is simple at the moment it is written down. It gets hard in ongoing operation: a new field has to go in, an old one has become superfluous, a signature no longer fits. Meanwhile, clients are running out there, some of which you don’t even know – web, mobile, a partner backend, an app version from eighteen months ago that is still in the field. Almost anyone can design a GraphQL schema. Maintaining it for years without breaking existing clients is the actual discipline. ## Not /v2, but one schema If you come from REST, you have a reflex: for a bigger change, you build `/v2`. The old URL stays, the new one runs alongside it, and at some point you switch off `/v1`. That works, but it costs – every version is code that someone builds, tests, operates and documents, often in parallel for years. GraphQL takes a different path. There is no version number in the URL, just exactly one schema that evolves additively. The reason lies in a property I already described in the concepts: a client gets only what it names in its query. It asks for `name` and `title`, so it gets `name` and `title` – and nothing else. If a `subtitle` field is added to the schema tomorrow, this client won’t even notice. It never named it, so it doesn’t show up in its response, and its response keeps exactly the same shape as yesterday. That’s the lever. Because the client determines the shape of its response itself, additional fields in the schema fundamentally don’t bother it. So you can let the schema grow without every addition being an event. The official docs put it in a nutshell: GraphQL takes a strong opinion on avoiding versioning and instead provides tools for the continuous evolution of a schema. ## Safe changes: what you can simply add A whole class of changes is harmless by nature, because they only add and never take away anything a client relies on. A new field on an existing type goes unnoticed by anyone who doesn’t query it. A new type or a new query or mutation entry point is purely an offer, not an obligation. A new optional argument on an existing field keeps everyone who omits it on the old behavior – provided the default matches what applied before. And a new enum value is also additive, though with a caveat I’ll come back to shortly, because there’s a trap lurking here. The common denominator: existing queries return the same result after the change as before. That is the actual definition of “non-breaking” – not that nothing changes, but that no valid query from yesterday suddenly becomes invalid today or returns a different shape. ## Breaking changes: what really tears clients apart On the other side are the changes that break a query that was valid yesterday. The most important ones, with concrete examples: The most obvious is removing or renaming a field. If a client asks for `user { fullName }` and I rename `fullName` to `displayName`, the query is invalid immediately. From the schema’s point of view, renaming is nothing but deleting plus adding – the old name disappears, and every query that names it runs into a validation error. More subtle, and reliably good for a surprise, is nullability in the wrong direction. Tightening a nullable field to non-null is *not* breaking: anyone who has so far reckoned with a possible `null` can also cope with a value always coming now. The other way around, however – making a non-null field nullable – *is* breaking. A client that relied on the `String!` guarantee and never checked for `null` suddenly gets a `null` it doesn’t expect. The same logic applies to arguments, just mirrored: making a required argument optional is harmless, making an optional one required breaks everyone who has omitted it so far. A changed argument type or a new required argument also breaks. If a `String` argument becomes an `Int`, existing queries no longer fit. And a new *non-optional* argument makes every query invalid that doesn’t supply it yet – hence the emphasis on *optional* above. And removing an enum value breaks just the same: if a value disappears that a client sends as an argument or expects in a response, the interaction breaks. ```mermaid flowchart LR subgraph Additiv["Safe – additive"] A1["add a field"] A2["add a type"] A3["optional argument"] A4["nullable → non-null"] end subgraph Breaking["Breaks clients"] B1["remove/rename a field"] B2["non-null → nullable"] B3["add a required argument"] B4["remove an enum value"] end ``` The trick when reading this list: it’s never about “more” or “less” but always about the same question – can a query that was valid yesterday still run validly after the change and return the same shape? If yes, the change is additive. If no, it is breaking, no matter how small it looks. ## @deprecated: deprecate instead of remove Because removing breaks, you need a way to get rid of a field *without* removing it right away. GraphQL has a built-in directive for exactly that: `@deprecated`. ```graphql type User { id: ID! fullName: String @deprecated(reason: "Use `displayName` instead. Removal planned for a future release.") displayName: String! } ``` The field stays fully functional – every query that names `fullName` still gets a response. But the schema now carries a visible marker. Through introspection, this hint lands in all tooling: the GraphiQL explorer strikes the field through, editor plugins warn while you type, codegen and linters report usage. The `reason` text is the actual message to the team on the other end – ideally with a successor *and* a deadline. Client teams see the hint, migrate to `displayName`, and only much later, when nobody queries `fullName` anymore, do I remove it. By the way, you can deprecate not only fields but also individual enum values and arguments. The pattern is the same everywhere: mark first, give time, then remove. That makes deprecation the most important tool of schema evolution, period. ## Nullability is a design decision, not a reflex One point deserves more than a line, because it is often decided wrongly during design and can hardly be corrected later: the question of whether a field should be non-null. `String!` feels clean. It says: a value always comes here. But non-null is a guarantee, and you can’t take guarantees back in a running contract – the way from non-null back to nullable is, as we saw, a breaking change. So you commit, and permanently. What weighs more is what happens at runtime when the guarantee doesn’t hold for once. If the resolver of a non-null field fails – the database hiccups, an upstream service returns nothing – then GraphQL *must* prevent a `null` where `null` is forbidden. It can’t just let the value through. So it lets the `null` propagate upward: the error bubbles up to the nearest nullable parent field and makes everything there `null`. A single failed non-null resolver can drag an entire response path down with it, all the way up to a point that tolerates `null`. A local problem turns into a large-scale outage in the response. So when in doubt, start nullable. Non-null only where the guarantee really holds – for an `id`, for a field that structurally can never be missing. For everything that depends on an external system, an optional relation or a computation that may fail, nullable is the more honest and more robust choice. You can always tighten from nullable to non-null later, once the guarantee has proven stable. You don’t have the way back. ## Input types: cutting mutations to be future-proof Additive evolution already starts at design time, and nowhere more clearly than with mutations. If you build a mutation with a handful of individual arguments, you block your own future: ```graphql type Mutation { createPost(title: String!, body: String!, authorId: ID!): Post! } ``` If a field is added later – a category, a publication date – the argument list grows, and every addition that isn’t optional breaks existing callers. The signature is rigid. That’s why you encapsulate the input in its own `input` type: ```graphql input CreatePostInput { title: String! body: String! authorId: ID! } type Mutation { createPost(input: CreatePostInput!): Post! } ``` The mutation now takes exactly one argument, `input`. You add new input fields additively in the `input` type – as *optional* fields, so that existing callers who don’t set them stay valid. The signature of the mutation itself never moves again. The same principle applies on the output side: a dedicated payload type instead of a bare `Post!` leaves room to add, say, an error or metadata field later without rebuilding the return value. A little more structure at the start, in exchange for years of additive freedom of movement. ## Extending enums carefully Back to the trap I left open in the safe changes. *Adding* an enum value is additive on the server side – the schema just gets richer. The breakage happens elsewhere, namely in client code. Many clients handle enum values in a `switch` or an `if` chain and cover exactly the values that existed when they were built. If a new value comes over the wire, such a client falls into no branch – at best it shows nothing, at worse it throws an error. A cleanly additive schema change thus becomes a real breakage for the user. The solution isn’t in the schema but in client discipline: every consumer of an enum should have a default or fallback branch for unknown values. The GraphQL best practices point this out explicitly – clients should behave so that a future enum value, unknown today, doesn’t crash anything. If you plan for this from the start, you can extend enums later without hesitation. ## A field migration step by step Let’s bring it all together with the example already hinted at above: `fullName` is to make way for `displayName`. This is how the migration runs cleanly, without any client breaking at any point. ```mermaid flowchart TB S1["1 – add displayName
    additively"] --> S2["2 – mark fullName with
    @deprecated"] S2 --> S3["3 – migrate clients
    (deadline running)"] S3 --> S4["4 – remove fullName
    once nobody asks anymore"] ``` Step one, add: I create `displayName` as a new field. Purely additive, nobody is affected. Existing clients keep asking for `fullName`, new ones can use `displayName` right away. Step two, deprecate: I mark `fullName` with `@deprecated` and a `reason` that points to `displayName` and the planned deadline. From now on, all client teams see through their tooling that the old field is being phased out – but it keeps working. The transition period is what matters: the resolver returns *both* fields correctly. ```js const resolvers = { User: { // legacy field – kept working until the deprecation window closes fullName: (user) => user.displayName, displayName: (user) => user.displayName, }, }; ``` Step three, migrate: the client teams switch to `displayName` at their own pace. How long that takes depends on the slowest relevant client – for a mobile app often months, because old versions stay in the field. A schema registry or traffic analysis shows whether `fullName` is still being queried at all. Step four, remove: only when the deadline has passed *and* there is demonstrably no more traffic on `fullName` do I remove the field and the resolver. Now, and not a moment earlier, the breaking change becomes a non-event, because nobody is left who could break. ## A safety net in CI Keeping all these rules in your head is one thing. Reliably following them on every merge while several people work on the schema is another. That’s why the check doesn’t belong in your head but in the pipeline. A tool like graphql-inspector compares the schema of a pull request with the currently published one and classifies every difference – additive, dangerous or breaking. If it finds a breaking change, it can turn the build red before anything is merged. A removed field, an argument that became non-null, a vanished enum value is caught in review this way, not only when a client breaks out there. If you also keep the schema in a registry, you can even run the check against actually observed traffic: a “breaking change” to a field that nobody has queried for months isn’t one after all – and the migration above can be tied exactly to this data. ## Maintained, not recut A GraphQL schema evolves differently from a REST API. You don’t put a `/v2` next to it every few years and migrate everything at once; you maintain a single contract over its entire lifetime. Growth is additive: new fields, new types, new optional arguments keep coming without anyone noticing. And where something does have to go, disciplined deprecation replaces the hard cut – mark, set a deadline, let clients migrate, then remove. That is less spectacular than a big version jump, and that’s exactly the point. To its clients, a good schema feels like something that has simply always been there and never hurt. This calm is no accident – it is the result of a few rules, applied consistently, and a CI check that watches over them. ## Further reading - Repository introduction-graphql (chapters schema, resolver): https://github.com/mikebild/introduction-graphql - GraphQL, schemas and types: https://graphql.org/learn/schema/ - GraphQL best practices (versioning, nullability, deprecation): https://graphql.org/learn/best-practices/ - graphql-inspector (schema checks in CI): https://github.com/kamilkisiela/graphql-inspector --- # Serverless Workflows with AWS Step Functions URL: https://www.mikebild.dev/en/blog/serverless-workflows-with-aws-step-functions/ Date: 2021-03-23 The first function validates and calls the second, which calculates and calls the third, which sends a notification. On the whiteboard, that makes a clean chain. At runtime, all that remains is a sequence of calls that nobody can pause, inspect or resume from the outside. If you chain Lambda functions together inside their handlers, you have taken the flow away from operations: when an order gets stuck, the search through the logs begins. AWS Step Functions turns this relationship around. Instead of hiding the flow in nested handlers, you describe it declaratively as a state machine – and the state becomes visible instead of disappearing into call chains. A state machine makes the flow visible as a series of named states and explicitly handled results. :::process{title="An explicit workflow" role="primary" preferredPattern="connected-process"} 1. Input · take over the business request and the context it needs 2. Task · run exactly one bounded capability 3. Choice · pick the next permitted path based on a result 4. Parallel · start independent branches only when there is real concurrency 5. Catch · route expected errors into a named handling path 6. Completion · record success or failure as an unambiguous end state ::: The diagram doesn’t pretend there is a linear happy path. Branching and error handling stay part of the model instead of disappearing into scattered function calls. ## The problem: orchestration in code Let’s first look at what the reflex solution typically looks like. A Lambda function that processes an order might orchestrate internally like this: ```js exports.handler = async (event) => { const order = await validateOrder(event); if (!order.valid) { await notifyFailure(order); return { status: "rejected" }; } if (order.amount > 1000) { await requestManualReview(order); } else { await autoApprove(order); } const [inventory, payment] = await Promise.all([ reserveInventory(order), chargePayment(order), ]); return finalize(order, inventory, payment); }; ``` At first glance, this is readable. But every one of these calls can fail, and as soon as you want robustness, the code grows. What happens if `chargePayment` throws a transient error? Then you need a retry with backoff. What if `reserveInventory` succeeds but `chargePayment` fails for good? Then the reservation has to be rolled back. Bit by bit, the handler fills up with try/catch blocks, counters and timeout logic. The actual business flow – validate, decide, run in parallel, finish – disappears under the error handling. And the most unpleasant part comes in operations. When an order gets stuck, there is no place where you can read its state. You have CloudWatch logs and have to reconstruct how far the process got. With a single function, that’s still manageable. With five functions calling each other, it turns into detective work. Coordinating several functions is one of the limits you quickly run into with plain code. ## The idea: the flow as a state machine Step Functions moves orchestration out of the code into a declarative description. This description is written in the **Amazon States Language** (ASL), a JSON format. You define states, their transitions and the error paths – the individual Lambda functions stay small and each do exactly one thing. The key gain: the flow no longer lives in a handler but exists as a standalone artifact that the console renders graphically. For every execution, you can see which state it is in, which transition was taken and where something failed. An ASL definition has only a few required fields at the top level. `StartAt` names the entry state, `States` holds the states as an object. Every state has a `Type` and either points to the next state with `Next` or marks itself as terminal with `"End": true`. Before we get into a concrete definition, here are the eight state types available in 2021 – that’s the complete toolkit: - `Task` does work, typically a Lambda function. - `Choice` branches based on conditions, the if/else of the state machine. - `Parallel` runs several branches at the same time and collects their results. - `Map` applies a flow to every element of a list, in 2021 only as the inline variant. - `Pass` passes input through or injects fixed data, useful for testing. - `Wait` pauses for a duration or until a point in time. - `Succeed` ends the execution successfully. - `Fail` ends the execution with an error. With these eight building blocks, you can model a surprising number of processes without writing a single line of orchestration code. ## A task with retry and catch Let’s start with the core: a task state that calls a Lambda function and handles errors declaratively. This is the part that costs the most code in the handler approach – and shrinks to a few fields in ASL. ```json { "Comment": "Order processing workflow", "StartAt": "ValidateOrder", "States": { "ValidateOrder": { "Type": "Task", "Resource": "arn:aws:lambda:eu-central-1:123456789012:function:ValidateOrder", "Retry": [ { "ErrorEquals": ["Lambda.ServiceException", "Lambda.SdkClientException"], "IntervalSeconds": 2, "MaxAttempts": 3, "BackoffRate": 2.0 } ], "Catch": [ { "ErrorEquals": ["States.ALL"], "Next": "NotifyFailure" } ], "Next": "CheckAmount" }, "NotifyFailure": { "Type": "Task", "Resource": "arn:aws:lambda:eu-central-1:123456789012:function:NotifyFailure", "End": true } } } ``` There is a lot in here, so let’s go step by step. The `Retry` block is an array of retrier objects. `ErrorEquals` names the errors this retrier responds to – here two transient Lambda service errors that you shouldn’t blame on the business code. `IntervalSeconds` sets the first wait time, `BackoffRate` multiplies it with every further attempt (default 2.0), `MaxAttempts` caps the retries (default 3). Without explicit values, AWS would use these defaults. The `Catch` block kicks in when the retries are exhausted or when an error occurs that no retrier covers. Every catcher needs `ErrorEquals` and a `Next` that describes the transition. `States.ALL` is the catch-all error that matches everything – and that is exactly why there are two rules you need to know: `States.ALL` has to stand alone in its `ErrorEquals` and has to come last. If another retrier or catcher follows it, the definition is invalid. An important detail about the order: the matching retriers are processed first, and only when none of them applies anymore is the catcher transition taken. Retry before catch, always in this order. That is exactly the behavior you would painstakingly rebuild by hand in code – here it is a convention of the language. One point that regularly causes discussion: not every `States.` error is caught by everything. `States.TaskFailed`, for example, matches pretty much everything except `States.Timeout` – so if you only retry on `States.TaskFailed` and expect a timeout, you’ll be surprised. And `States.DataLimitExceeded`, which occurs when the payload limit is exceeded (in 2021 that is 256 KB between states), is not caught by `States.ALL`. You have to deliberately avoid errors like these, not catch them. ## Branching with Choice After validation, the process should make a decision. Small orders are approved automatically, large ones go to manual review. In the handler this was an `if`; in ASL it is a choice state. ```json { "CheckAmount": { "Type": "Choice", "Choices": [ { "Variable": "$.amount", "NumericGreaterThan": 1000, "Next": "ManualReview" } ], "Default": "FanOut" }, "ManualReview": { "Type": "Task", "Resource": "arn:aws:lambda:eu-central-1:123456789012:function:RequestManualReview", "Next": "FanOut" } } ``` The choice state contains a `Choices` array. Each rule consists of a `Variable` (a path into the current input, here `$.amount`), a comparison operator such as `NumericGreaterThan`, `StringEquals` or `BooleanEquals`, and a `Next`. You can also nest conditions with `And`, `Or` and `Not`. If no rule matches, `Default` applies. This very `Default` is a common pitfall. Choice has no `End` and no implicit exit. Without `Default` and without a matching rule, the execution runs into a `States.NoChoiceMatched` error. That’s why I recommend always setting `Default`, even if you believe you have covered all cases in theory. ## Parallel: several branches at once For reservation and payment, which run independently of each other, there is the parallel state. It runs several `Branches` at the same time – each branch is itself a small state machine with its own `StartAt` and `States`. ```json { "FanOut": { "Type": "Parallel", "Branches": [ { "StartAt": "ReserveInventory", "States": { "ReserveInventory": { "Type": "Task", "Resource": "arn:aws:lambda:eu-central-1:123456789012:function:ReserveInventory", "End": true } } }, { "StartAt": "ChargePayment", "States": { "ChargePayment": { "Type": "Task", "Resource": "arn:aws:lambda:eu-central-1:123456789012:function:ChargePayment", "End": true } } } ], "Next": "Finalize" }, "Finalize": { "Type": "Task", "Resource": "arn:aws:lambda:eu-central-1:123456789012:function:Finalize", "End": true } } ``` The output of a parallel state is an ordered array – one entry per branch, in the order of the definition. So `Finalize` receives both results bundled together. Parallel also supports `Retry` and `Catch` at the state level, and so does the map state when you process a list iteratively. ## How data flows between states The first time you work seriously with ASL, you stumble over a question that never comes up in handler code: what exactly does the next state receive as input? In a JavaScript function, you simply pass values on as arguments. In a state machine, passing data on follows rules, and you need to know them, or data gets lost without anyone noticing. Every state receives a JSON object as input and returns a JSON object as output. Four fields control this flow. `InputPath` filters which part of the input reaches the state at all. `Parameters` builds the object the Lambda function actually receives from it. `ResultPath` determines where in the input the result is inserted. Finally, `OutputPath` filters what gets passed on to the next state. The most common pitfall is in `ResultPath`. Without a value, the default is `$`, which means the task’s result replaces the entire input. If you still want to access `$.amount` in the choice state after `ValidateOrder`, you have to put the result under its own key with `"ResultPath": "$.validation"`; otherwise the original order is gone. This very default is the reason a choice state then reaches into nothing: the key the condition expects no longer exists after the task. Errors like this look like a wrong condition but are really a data flow problem. ## The flow as a picture The real argument for Step Functions is visibility. What I described above in JSON, the console renders as a graph. And exactly this structure can be traced as a diagram: ```mermaid flowchart TD Start([Start]) --> Validate[ValidateOrder
    Task] Validate --> Check{CheckAmount
    Choice} Check -->|amount > 1000| Review[ManualReview
    Task] Check -->|else| FanOut[FanOut
    Parallel] Review --> FanOut FanOut --> Reserve[ReserveInventory] FanOut --> Charge[ChargePayment] Reserve --> Finalize[Finalize
    Task] Charge --> Finalize Finalize --> Done([Succeed]) Validate -. "Catch States.ALL" .-> Notify[NotifyFailure
    Task] ``` The dashed edge is the error path described by the catcher. For a running execution, the console colors the states it has passed through, so you can see at a glance where the process stands or where it got stuck. I never get this view with the handler approach – and that’s the difference between “we have to search the logs” and “just look at the execution.” ## Standard or Express When you create a state machine, you have to choose a type, and that choice is fixed afterward. If you get it wrong, you build a new state machine. That’s why it pays to understand the two types early. **Standard** is the type for long-running, auditable processes. An execution may last up to a year, execution is exactly-once, and the complete history is available through the API for up to 90 days. Billing is per state transition. Important for the cost calculation: every retry attempt is its own transition and counts too. Visual debugging in the console is only available for Standard. **Express** is meant for high-frequency, short flows. An execution may run for five minutes at most. Run asynchronously, the guarantee is at-least-once; run synchronously via `StartSyncExecution` (available since November 2020), it is at-most-once. Billing is based on the number of executions plus duration and memory. There is no execution history in the console – you depend on CloudWatch Logs, and for that, logging has to be enabled. The dividing line follows the domain: order processes, approval workflows, anything with human involvement or audit requirements belongs to Standard. High-throughput event processing, short transformations, IoT ingestion – that’s Express territory. The idempotent nature of short Express flows fits at-least-once semantics, while for a payment you want the exactly-once guarantee of Standard. ## When to use Step Functions – and when not I don’t recommend turning every sequence of two functions into a state machine. If one function calls another and that’s it, a direct call or an event is perfectly fine. The effort of Step Functions pays off from the point where there is real flow logic: branches, parallelism, retries with different strategies, compensation for partial failures, or when operations needs to see the state. A second criterion is error handling. As soon as you notice that the orchestrating handler contains more try/catch than domain logic, that’s a strong signal. Moving this handling out declaratively makes the code of the individual functions small and readable again – each function focuses on its one job, and the coordination lives in the state machine. And Step Functions doesn’t replace the other serverless building blocks; it coordinates them. The Lambda functions stay, the database stays, authentication – for example with [Cognito User Pools](https://www.mikebild.dev/en/blog/serverless-auth-with-cognito-user-pools/) – stays where it is. Step Functions is the layer on top that describes the flow. ## Conclusion Moving from nested handlers to a state machine is above all a change of perspective. Instead of hiding the flow in code, you make it an artifact: `StartAt`, a few states, `Next` transitions, and the error paths as `Retry` and `Catch` right on the state. The individual functions get smaller because they no longer have to carry the coordination, and operations get calmer because the state of every execution is visible. The eight state types are quickly learned, and with Task, Choice and Parallel you already cover most real-world flows. With the order of retry and catch in mind, a `Default` set on every choice and a deliberate choice between Standard and Express, you have the foundation in place. In the projects I was involved in, what really won people over was the colored execution in the console anyway. From then on, the flow is no longer buried in logs but is a picture everyone can look at. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-aws-serverless.en.html - Repository for the serverless training with the ASL examples from this article - [AWS Step Functions – States (States)](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-states.html) - [Amazon States Language](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html) - [Standard vs. Express Workflows](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-standard-vs-express.html) - [Error handling: Retry and Catch](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-error-handling.html) - [Task state](https://docs.aws.amazon.com/step-functions/latest/dg/state-task.html) - [Choice state](https://docs.aws.amazon.com/step-functions/latest/dg/state-choice.html) - [Tutorial: State machine with Lambda](https://docs.aws.amazon.com/step-functions/latest/dg/tutorial-creating-lambda-state-machine.html) --- # Event Sourcing: The Event Store as a Logbook URL: https://www.mikebild.dev/en/blog/event-sourcing-the-event-store-as-a-logbook/ Date: 2021-02-23 ```sql UPDATE accounts SET balance = 300 WHERE id = 42; ``` After this statement, the database says that the account holds 300 euros. The previous value is overwritten, and with it the answer to the question of how the 300 came about: one deposit of 300, or two of 200 plus a withdrawal of 100? The row no longer knows. Every booking eats its predecessor, and the `balance` field keeps only the result. Event Sourcing reverses this order. The truth isn’t the current state but the sequence of events that produced it. The event store is a logbook – an append-only log that only ever gets appended to and in which nothing is changed or deleted. The current state is then no longer a stored fact but a derived artifact: you fold the events and get the state out. Event Sourcing is almost always mentioned in the same breath as CQRS, and that’s exactly where the most stubborn misunderstandings arise. So first the core, then the boundaries – drawn deliberately sharp. ## State is a left fold Martin Fowler describes Event Sourcing as “Capture all changes to an application state as a sequence of events.” Every state change is recorded as an event, which makes the application state fully derivable from the event log. You can throw away the cached state completely and reconstruct it by replaying all events onto an empty initial state. Greg Young coined the most didactically elegant formula for this: “Current state is a left fold of previous behaviours.” The state isn’t a table but the result of a fold over the event sequence. In code anyone can read right away: ```ts type Event = | { type: "AccountOpened"; owner: string } | { type: "MoneyDeposited"; amount: number } | { type: "MoneyWithdrawn"; amount: number }; type Account = { owner: string; balance: number }; const apply = (state: Account, event: Event): Account => { switch (event.type) { case "AccountOpened": return { owner: event.owner, balance: 0 }; case "MoneyDeposited": return { ...state, balance: state.balance + event.amount }; case "MoneyWithdrawn": return { ...state, balance: state.balance - event.amount }; } }; const fold = (events: Event[]): Account => events.reduce(apply, { owner: "", balance: 0 }); ``` That’s the whole trick, and it’s deliberately little. `apply` takes a state and an event and returns the next state. `fold` runs over the stream with `reduce` and is nothing other than a `left fold` with `apply` as the folding function. The code here is illustrative – not a runnable repository, but the idea reduced to its essentials. A few properties are already in these lines. The events are named in the past tense – `AccountOpened`, `MoneyDeposited`. They’re facts that have already happened, and therefore immutable: an event is never changed and never deleted; only a new one is added. And `apply` has no side effects; it’s a pure function from the old to the new state. That’s no accident but the precondition for replay to work reliably at all. This all comes down to the same dividing line as in [Cleanly Separating Commands, Events and Queries](https://www.mikebild.dev/en/blog/separating-commands-events-and-queries/): a command is an intention that may fail; an event is what actually came of it and can no longer fail. Event Sourcing consistently stores the second kind. ## The logbook as the source of truth If you look at the flow, a simple picture emerges. A command arrives, the aggregate decides and produces one or more events from it, which are appended to the log. The state then comes from folding. ```mermaid flowchart LR C[Command] --> A[Aggregate decides] A --> E[New Event] E --> L[(Event Store
    append-only)] L --> F[fold / apply] F --> S[Current State] ``` What matters in this picture is the direction. The command produces an event, the log only grows at the end, and the state hangs at the end of the chain. If the state is lost – cache gone, new service, changed calculation – it can be restored from the log at any time. The log is authoritative; the state is derivable. This leads to three benefits that make Event Sourcing attractive, and they all hinge on the same property: the log is preserved in full. - A complete audit trail comes for free. Not as an after-the-fact protocol, but because the event log is the state. It doesn’t just describe what happened – it *is* what happened. - Temporal queries become possible. Because every earlier state is an intermediate result of the fold, I can ask: what did the account look like on January 3? I simply fold up to the event that was written on that day. - Projections can be rebuilt. A read model I don’t have today I can introduce tomorrow by running through the existing events again. History that would long have been overwritten with state-based storage is fully available here. The third point weighs the most in practice: when writing, nobody has to foresee which views will be needed later. ## Projections: read models from the stream If the state is derived anyway, then so are any number of views on the same stream. That’s exactly what projections are, and they’re the natural transition to [read models as projections](https://www.mikebild.dev/en/blog/read-models-from-events-projections/): derived models optimized for reading, disposable and rebuildable at any time. ```ts type BalanceView = Record; const project = (events: Event[]): BalanceView => events.reduce((view, event) => { switch (event.type) { case "AccountOpened": return { ...view, [event.owner]: 0 }; case "MoneyDeposited": // update the read model per event return view; case "MoneyWithdrawn": return view; } }, {} as BalanceView); ``` `project` is also a fold, just with a different target model. One fold produces the aggregate for decisions, the other a flat overview for the read side. From the same log you can derive an account overview, a monthly revenue report and fraud detection – three projections, three folds, one stream. ```mermaid flowchart LR L[(Event Store
    append-only)] -->|project| A[Read Model A
    balances] L -->|project| B[Read Model B
    monthly report] L -->|project| C[Read Model C
    fraud signals] ``` Two things have to be named honestly here. First, these read models are only eventually consistent – they lag behind the write log because the projection runs after the append. If you need immediate consistency between writing and reading, you don’t get it for free here. Second, projections must not trigger any external side effects, and that leads directly to the first serious pitfall. ## Replay is not innocent Fowler points out a detail that never stands out in demos and gets expensive in production: external systems don’t distinguish between real processing and replay. If I rebuild a read model and run through the events again, a gateway that sent an email or triggered a payment the first time sees no difference. It would send the email again. That’s why the rule is: `apply` and `project` are pure folds without side effects. Everything that has an effect on the outside – emails, payments, notifications – doesn’t belong in the fold but behind gateways that know a replay mode and suppress their effects in it. If you don’t separate this, you build yourself a disaster at the first rebuild. ## Snapshots: the memoized fold That leaves the question of performance. An account with twenty bookings folds in microseconds. An aggregate with two hundred thousand events no longer does on every access. The answer is called a snapshot, and Greg Young put it so precisely that his wording can hardly be improved: “A snapshot is a memoization of your left fold.” A snapshot is a stored capture of the fold result at event N. You then keep folding from the snapshot instead of starting at event 0. ```ts type Snapshot = { version: number; state: Account }; const rebuild = (snapshot: Snapshot, newerEvents: Event[]): Account => newerEvents.reduce(apply, snapshot.state); // snapshot = memorized left fold at version N ``` The crucial point: a snapshot is purely a performance optimization, not a new source of truth. Because the events are immutable, a snapshot can never become invalid – the past it was folded from doesn’t change, after all. If a snapshot is lost or the folding logic changes, you throw it away and fold again from the start. The log remains authoritative; the snapshot is only a cache of the fold. ## The distinction: Event Sourcing is not CQRS Event Sourcing and CQRS are almost always mentioned together, and many people think they’re the same thing. They aren’t. [CQRS is a domain boundary](https://www.mikebild.dev/en/blog/cqrs-is-a-domain-boundary-not-a-framework/) – the separation of write model and read model. Event Sourcing is a persistence strategy – events instead of state as what gets stored. These are two different decisions on two different axes. You can run CQRS without Event Sourcing: separate write and read sides, both classically with state tables. And you can run Event Sourcing without strict CQRS, even though the read model projections then suggest the separation almost by themselves. They’re often combined because Event Sourcing produces read model projections very naturally and CQRS offers exactly the right frame for them. But neither forces the other. If you keep them apart, you make both decisions consciously instead of one in the wake of the other. And one more distinction that becomes important in distributed systems: Event Sourcing isn’t Event-Driven Architecture. Event Sourcing is storage and source of truth within an aggregate. Pub/sub messaging between services is integration. A domain event that travels over a bus as an integration message isn’t automatically a stored Event Sourcing event. Where the two levels blur, you get systems nobody can see through after a year. ## The honest costs As attractive as the logbook sounds – Event Sourcing is expensive. The benefit comes with a real price, and both sides belong on the table next to each other. The benefits are a complete audit trail, temporal queries, projections you can introduce after the fact and good domain semantics through intentional events. The costs are event schema versioning over the entire lifetime, replay performance including snapshot management, the eventual consistency of the read models and higher operational complexity overall. The biggest cost block is versioning. Events live forever, and a replay still has to be able to read the old event versions from three years ago. If the schema changes – a field is added, a meaning shifts – I need a strategy for upcasting: converting old events to the current form when reading. If you underestimate this, you’ll notice at the first big rebuild that your log contains events in five generations that all still need to be read. You either plan for this effort from the start or you plan for it painfully afterward. On top of that comes eventual consistency – a permanent companion no ticket can debug away. And snapshots aren’t a free tool: additional infrastructure you have to manage, invalidate and regenerate when the folding logic changes. ## Two anti-patterns that destroy the benefit I see two mistakes so often that they deserve their own section. The first is “CRUD in disguise.” If the events are called `EntityUpdated` or generic `FieldChanged`, you’ve built in Event Sourcing mechanically but thrown away the actual intent. A `MoneyWithdrawn` tells you what happened in the domain; a `BalanceFieldSetTo` only tells you that some setter ran. All the value – intent, audit, semantics – lies in the domain naming. Generic setter events are CRUD with more ceremony and less benefit. The second is “Event Sourcing everywhere.” It isn’t a default persistence. It pays off where history, audit and temporal questions have real domain value – accounting, trading, anything with regulatory traceability. For a master data CRUD service that only needs the latest state, it’s expensive overhead. The art lies in drawing the line where the context really justifies the logbook, and not pushing it across the whole system out of enthusiasm. ## Conclusion Event Sourcing shifts a single assumption: the truth isn’t the state but the sequence of events that produced it. The event store becomes a logbook – append-only, immutable, authoritative – and the state falls out as a left fold over this stream. Audit trail, temporal queries and any number of rebuildable projections grow out of it almost by themselves. The price for this is real: event versioning over years, replay performance with snapshots as a memoized fold, eventual consistency and the discipline to keep side effects out of the folds. And the most important conceptual separation: Event Sourcing is a persistence strategy, CQRS a domain boundary – often together, never forced by each other. If you weigh this up soberly, you use Event Sourcing where the history pays back the effort, and otherwise keep storing good old state. Exactly this decision – conscious, not driven by fashion – is the real gain. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-cqrs-event-sourcing.en.html - Martin Fowler, *Event Sourcing*: https://martinfowler.com/eaaDev/EventSourcing.html - Martin Fowler, *Retroactive Event* (on corrections through new events): https://martinfowler.com/eaaDev/RetroactiveEvent.html - Greg Young, talk *CQRS and Event Sourcing*, Code on the Beach 2014 (left fold, snapshots as a “memorized fold”) - Greg Young, *Functional Domain Models and Event Sourcing* (2012) - Vaughn Vernon, *Implementing Domain-Driven Design* (2013) – chapters on Event Sourcing and CQRS - Mike Bild, talk material *CQRS + Event Sourcing* (SlideShare) – the author’s material this article draws on --- # Testing Flask Apps: The Test Client and Reliable Endpoints URL: https://www.mikebild.dev/en/blog/testing-flask-apps/ Date: 2021-02-16 `app.test_client()` is not an HTTP client. It doesn’t open a socket, doesn’t occupy a port and doesn’t need `app.run()`. It calls the WSGI application directly in the same process and returns what the view function produced – a Python object, not a network response. That removes the argument that endpoints are laborious to secure with tests. A `curl` in the terminal shows that a route does the right thing at this one moment; after the next refactoring, it no longer tells you anything. This article builds on [Web APIs with Flask](https://www.mikebild.dev/en/blog/web-apis-with-flask/) and flips the perspective: not building the endpoints but securing them. The tool for this is lean – Flask ships the test client, and pytest provides the structure around it. ## A test without a server The obvious approach would be to start the app for a test and then fire at it with an HTTP library. That works, but it is slow, error-prone and needs a free port. Flask offers a much better way. `app.test_client()` returns a client that calls the WSGI application directly in the same process. There is no socket, no `app.run()`, no real network connection – the request is passed to the app as a Python call, and the response comes back as an object. That is the crucial point: the test talks to your application, but not over the network. As a result, the tests run fast and also work in a CI environment without open ports. Leaving out the network and server path removes some sources of variation; but the test only becomes deterministic once data, time and external dependencies are under control too. ```mermaid flowchart LR A[Test] -->|client.get / post| B[test_client] B -->|WSGI in-process
    no socket, no server| C[Flask app] C --> D[View function] D -->|Response
    status_code + body| B B -->|Response object| A A -->|assert| E[Status & body checked] ``` The client behaves like a small browser without a UI. I call `client.get("/")` or `client.post("/json", json={...})` and get back a response object that I can examine. The most important attributes are quickly listed: `response.status_code` as an integer, `response.data` as the raw body in bytes and `response.get_json()` for already deserialized JSON responses. ## From unittest style to pytest fixtures Many older Flask examples – including the one I used to work with in my `introduction-python` repository – use `unittest`. The structure then typically looks like this: ```python import unittest from examples.app import app class HelloTestCase(unittest.TestCase): def setUp(self): app.testing = True self.client = app.test_client() def test_index(self): result = self.client.get("/") self.assertEqual(result.status_code, 202) self.assertEqual(result.data, b"Hello World!") if __name__ == "__main__": unittest.main() ``` That works and is a good starting point. The endpoint in my example deliberately returns the unusual status `202` – which is exactly why it is well suited for testing, because a wrong status stands out immediately. Still, I now modernize this to pytest, for two reasons: the tests become shorter and more readable, and fixtures make the setup reusable without me repeating it in every test class. The second, subtler reason lies in a detail of the code above. The app is imported as a module-global object, and the client shares this one instance. As long as the app is stateless, that works fine. As soon as it holds data, it gets tricky – more on that later. ## Fixtures in conftest.py With pytest, I put the setup into a file `tests/conftest.py`. pytest finds this file automatically, and the fixtures defined there are available to all tests in the directory. I define two fixtures: one for the configured app and one for the client. ```python import pytest from examples.app import app as flask_app @pytest.fixture def app(): flask_app.config.update({"TESTING": True}) yield flask_app @pytest.fixture def client(app): return app.test_client() ``` Two things matter here. First, the `TESTING = True` configuration. It turns on error propagation: if a view raises an exception, Flask passes it through in test mode instead of wrapping it in a generic `500` response. Without this flag you are debugging blind, because you only see the status `500` and not the actual stack trace. In one project I spent half an hour in a test run searching for a cause that would have been in the traceback from the start with `TESTING=True`. Second, the `client` fixture, which depends on the `app` fixture. pytest resolves this dependency automatically: it builds the app first, then the client. Every test that declares `client` as an argument gets a fresh, cleanly configured instance. Exactly this freshness is the key to isolated tests. ## The AAA structure When I write tests, I stick to the AAA pattern: Arrange, Act, Assert. First prepare the state, then perform the one action, then check. In Flask tests, most of the Arrange falls into the fixtures, the Act is the request and the Assert is checking the response. ```mermaid flowchart TD A["Arrange
    Fixtures: App + Client
    TESTING = True"] --> B["Act
    client.get / client.post"] B --> C["Assert
    check status_code
    check get_json / data"] ``` A first, simple test for the index endpoint then looks like this: ```python def test_index_returns_hello(client): # Act response = client.get("/") # Assert assert response.status_code == 202 assert response.data == b"Hello World!" ``` No `setUp`, no class, no `self`. The fixture takes care of the Arrange, and the test stays with the actual statement: this endpoint responds with status `202` and the body `Hello World!`. ## Bytes are not a string I have stumbled over this spot often enough myself. The obvious comparison ```python assert response.data == "Hello World!" # fails ``` fails. `response.data` returns bytes, not a `str`. The comparison between `b"Hello World!"` and `"Hello World!"` is always `False` in Python. There are two clean ways: either I compare against a byte literal `b"Hello World!"`, or I fetch the body as text. ```python def test_index_body_as_text(client): response = client.get("/") assert response.get_data(as_text=True) == "Hello World!" ``` `get_data(as_text=True)` decodes the body into a string. Both variants are correct – I choose depending on whether I want to check raw bytes or readable text. What I deliberately don’t use in this context is `response.text`; this string property only came with a later tooling version and isn’t available yet in Flask 1.1. ## Checking JSON responses Most real endpoints don’t return `Hello World!` but JSON. This is where the second big advantage of the test client shows. Instead of parsing the raw body yourself, you call `response.get_json()` and get a ready-made Python structure – a `dict` or a `list`. This cleanly separates two levels of checking: the body as bytes for the exact raw comparison and the deserialized structure for checking the content. Let’s take an endpoint that accepts a JSON object, adds fields to it and returns it – similar to the `/json` example from my repository: ```python from flask import Flask, request, jsonify app = Flask(__name__) @app.route("/json", methods=["POST"]) def json_endpoint(): payload = request.json result = {"username": "John Doe", "role": payload.get("role")} return jsonify(result) ``` The corresponding test sends JSON and checks the deserialized response: ```python def test_json_endpoint(client): # Act response = client.post("/json", json={"role": "admin"}) # Assert assert response.status_code == 200 data = response.get_json() assert data["username"] == "John Doe" assert data["role"] == "admin" ``` One detail is worth mentioning: the client’s `json=` parameter automatically sets the content type to `application/json` and serializes the dictionary. So you neither have to set headers by hand nor call `json.dumps` yourself. On the response side, `get_json()` takes the parsing off your hands. This keeps the test close to the actual statement about the endpoint’s behavior. ## Error cases are part of it A common mistake I come across in code reviews is testing only the happy path. An endpoint that works with correct input but silently does the wrong thing with wrong input is not reliable. That’s why every serious test suite includes at least one error case. The simplest one is the unknown route: ```python def test_unknown_route_returns_404(client): response = client.get("/does-not-exist") assert response.status_code == 404 ``` What I cover at a minimum fits into a short list: - The status code – do I expect `200`, `202`, `201` or a deliberate error code? - The response body or the JSON structure – are the fields and values right? - The error cases – such as `404` for unknown routes and `400` for invalid input. These three levels aren’t much work, but they fundamentally change how meaningful a test suite is. A test that only checks the status misses wrong content. A test that only checks the body misses a wrong status. Together they give a solid picture. ## The pitfall: shared state Now we come to the problem I hinted at above, which in practice causes most of the hard-to-find test failures: shared state between tests. As long as an app is stateless, all tests share the same instance without danger. But as soon as the app holds data – a list in memory, a global dictionary, a database – the order of the tests suddenly becomes relevant. Imagine an endpoint that collects entries in a module-global list. One test creates an entry, another counts the entries. If the counting test runs after the creating test, it sees one entry more than expected. If it runs before, it sees zero. Such tests are sometimes green, sometimes red, depending on the order – and nothing is more frustrating than a test that turns out one way or the other without any code change. The solution lies in the fixtures. Instead of importing a global app, I build it fresh for each test. pytest fixtures have the scope `function` by default, which means they are executed anew for every test call. If the fixture returns an app with empty state on every call, no test can influence the next one. ## Isolating databases cleanly The same problem one size bigger is the non-isolated database. If tests write to the same database without cleaning up, they get in each other’s way just like with the global list. One test creates a user, the next one finds it there and doesn’t expect it. The clean answer is setup and teardown around the fixture’s `yield`. Everything before the `yield` sets up the state, everything after it cleans up. In practice, I like to use a fresh temporary SQLite database per test or a transaction rollback at the end. Schematically, the pattern looks like this: ```python import pytest from myapp import create_app, db @pytest.fixture def app(): app = create_app({"TESTING": True, "DATABASE": ":memory:"}) with app.app_context(): db.create_all() # Setup: fresh schema yield app db.drop_all() # Teardown: clean up @pytest.fixture def client(app): return app.test_client() ``` The core is the `yield` in the middle. Before it comes creating the schema, after it the cleanup. This way, every test gets an empty database, works in it and leaves no traces for the next one. That is a bit more effort than a shared database, but it’s the difference between tests I trust and tests I first eye suspiciously on every red run. ## What counts in the end Flask’s test client turns securing endpoints into a matter of diligence rather than an infrastructure topic. It takes no running server and no network library, just `app.test_client()`, a few fixtures and the discipline to check status, body and error cases together. The three ideas that have proven themselves for me are simple. First: test in-process, without a server – then the tests are fast and independent of port and network. Second: use pytest fixtures so that every test gets a fresh, configured app – the best defense against shared state. Third: for anything that holds data, think about setup and teardown, otherwise the result depends on the test order. This lets you reliably check the WSGI application against its HTTP semantics. This test level deliberately doesn’t cover the real path through WSGI server, reverse proxy, TLS and network. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-python.en.html - Repository `introduction-python`, `web/4-testing.md` and the examples `examples/5-testing.py`, `examples/app.py` and `examples/3-json.py` - Flask, Testing Flask Applications: https://flask.palletsprojects.com/en/1.1.x/testing/ - Flask, API reference for `Flask.test_client` and the `TESTING` config: https://flask.palletsprojects.com/en/1.1.x/api/ - Werkzeug, test utilities and response object (`get_json`, `data`): https://werkzeug.palletsprojects.com/en/stable/test/ - pytest, fixtures: https://docs.pytest.org/en/6.2.x/fixture.html - Flask tutorial, Test Coverage: https://flask.palletsprojects.com/en/1.1.x/tutorial/tests/ --- # Preserving and Resetting State: React and the Position in the Tree URL: https://www.mikebild.dev/en/blog/preserving-and-resetting-state-in-react/ Date: 2021-01-26 # Preserving and Resetting State: React and the Position in the Tree Two facts decide whether a component’s state survives an update: the position in the render tree and the component type that sits at this position. If both stay the same, React passes on the remembered state. If either of them changes, the state is discarded. There are no other criteria – and no exception for “but it’s the same component.” This only becomes puzzling because a different picture pushes itself forward: the state lives in the component, the way a variable lives in an object. According to this picture, `useState` would have to hold its value where the function stands. React does not do that. When updating, it compares two trees – the old one and the new one – and derives from the differences what needs to happen in the DOM ([How React renders the tree](https://www.mikebild.dev/en/blog/how-react-renders-and-updates-the-tree/)). It is exactly this comparison that also decides about the state. Two kinds of bugs grow out of the wrong picture: sometimes a state is lost that you wanted to keep, sometimes one sticks around that you wanted to get rid of. ## State hangs on the position, not on the component The right picture is this: React does not store the state in the component but at its position in the render tree. Every spot in the tree – first child of a container, second child, the element behind this condition – is an address. At this address, React remembers which component last stood there and what state it had. If the same component stands at the same address again on the next update, React hands it the remembered state once more. If something else stands there – or nothing at all anymore – React throws away the state of this address. That gives you the whole rule in one sentence: the same component at the same position keeps its state. If the type changes at a position, or if the position disappears, the state there is discarded. Everything else in this post is just this one rule, applied to cases that otherwise seem puzzling. ## Example A: two counters, two positions Let’s take two identical components side by side. Both are the same `Counter`, written from the same function: ```jsx function Counter({ label }) { const [count, setCount] = useState(0); return ( ); } function App() { return (
    ); } ``` If you click the left one up, the right one stays put. That is irritating at first, because it is the same component – shouldn’t they share the same state? No, and the position rule immediately explains why. The left `Counter` sits at the address “first child of the `div`,” the right one at “second child.” Those are two addresses, so two separate states. That both come from the same function does not matter – the function is only the template; the state hangs on the position. Now the case that really sharpens the point. We conditionally hide the right counter and show it again: ```jsx function App() { const [showRight, setShowRight] = useState(true); return (
    {showRight && }
    ); } ``` You count the right one up to 7, switch it off, switch it back on – and it is at 0. The state is gone, irretrievably. As long as `showRight` is false, nothing stands at the second position. React sees a position that has disappeared and clears away its state. When the `Counter` comes back, from React’s point of view it is a freshly occupied address, not a reunion. The state was never “in the counter” – it was bound to a position that did not exist in the meantime. ## Example B: the same position, a different type The opposite case shows the same rule from the other side. As long as the same component type stands at a position, the state survives every change of props. You can give a `Counter` a different `label` on every update, change its color, switch it from active to inactive – the count stays, because the same type still stands at the position. Props reshape the component; they do not reset it. If, on the other hand, the type flips at the same spot, the state is gone. This is exactly where the type rule of reconciliation applies, which I described in [How React renders the tree](https://www.mikebild.dev/en/blog/how-react-renders-and-updates-the-tree/): if React encounters a different element type at a position than before, it tears down the old subtree and builds the new one from scratch – including state. A common trigger looks harmless: ```jsx function Panel({ editing }) { if (editing) { return ; } return

    draft

    ; } ``` At this position, the type switches between `` and `

    `. Every switch throws away the old node – the `` loses its typed text, because on the next toggle a `

    ` stands there and after that a brand-new ``. The same happens when one component is rendered at a spot sometimes and a different one at other times: different types at one address mean different things to React, and different things do not share state. ```mermaid flowchart TB subgraph erhalten["gleiche Position, gleicher Typ"] A1["Counter an Position 2
    count = 7"] --> A2["neue Props
    Typ bleibt Counter"] A2 --> A3["count = 7
    bleibt erhalten"] end subgraph reset["gleiche Position, anderer Typ"] B1["p an Position 2"] --> B2["jetzt input
    an Position 2"] B2 --> B3["alter Teilbaum weg,
    Zustand verworfen"] end ``` ## Resetting state on purpose So far this sounds like a trap. But you can turn the rule around and make it a tool. Sometimes you explicitly want a reset – and then the position rule tells you exactly how to order one. The crude way: render the component at a different position. Two branches of an `if` that seemingly show the same `Counter` are two different positions from React’s point of view if they hang at different spots in the tree; if you toggle between them, you get a fresh state every time. That works, but it is heavy-handed and easy to trigger by accident. The elegant way goes through the `key`. A `key` tells React explicitly: “This is a specific element; distinguish it from its neighbors.” From [JSX, precisely](https://www.mikebild.dev/en/blog/jsx-precisely-the-rules-behind-the-markup/), you know keys as the thing that makes lists stable so that React recognizes the elements when reordering. But exactly the same capability also works outside of lists for a targeted reset. If an element’s `key` changes, React treats it as a new element at this position – the old subtree is torn down, the state created fresh. The classic example is a form that should start fresh for each selected record: ```jsx function ContactEditor({ selectedId }) { return

    ; } ``` Without the `key`, `Form` would stay at the same position; if `selectedId` changed, the form would only get new props, and the half-typed text of the previous contact would remain in the field. With `key={selectedId}`, the key changes with every new selection, React sees a new element, and the form starts empty – without you resetting a single field by hand. The `key` does exactly the work you would otherwise rebuild with an effect and lots of `setState`. ```mermaid flowchart LR S1["selectedId = 1"] --> F1["Form key=1
    frischer Zustand"] S2["selectedId = 2"] --> F2["Form key=2
    neues Element,
    Formular leer"] S3["selectedId = 2
    Feld getippt"] --> F3["Form key=2
    Zustand bleibt"] ``` ## Preserving state even though the structure changes The counterpart is the case in which you want to keep the state but the surroundings change. Here the point is to keep position and type stable, even if things are being rebuilt around them. If you write a component into one branch or the other depending on a condition, you move it to a different position – and then wonder about the reset. Often you can avoid this by rendering the component at a fixed spot and only switching its props instead of letting it wander through the tree. And if a state has to survive a real restructuring, it usually does not belong where it currently is. Then you lift it up to a common parent that stays untouched by the restructuring. The state then hangs on a position that is stable, and the children below it may come and go without dragging it along. This is the same move as the classic lifting of state. The reason here is a different one: it is about surviving a structural change, not about sharing between siblings. ## The nastiest bug: a component inside a component I save the most unpleasant case for the end, because it puts the position rule to the test and because it hides in real codebases surprisingly often. It looks like this: ```jsx function Page() { function Sidebar() { const [open, setOpen] = useState(true); return ; } return (
    ); } ``` `Sidebar` is defined inside `Page`. That looks tidy – after all, the component stands where it is needed. The effect is devastating nonetheless. On every render of `Page`, the line `function Sidebar()` runs again and creates a new function. On every pass, it is literally a different function with a different identity. For React, however, the identity of the function is the type. A different type at a position means: old subtree gone, new one built, state discarded. In practice, this looks eerie. Every update of `Page`, however small, resets `open`, the input field inside loses its text, and if you are typing in a field, you lose focus mid-word because the DOM element under you was replaced. You search for the bug everywhere – in the effect, in the event handler, in the state management – except at the spot where the component is defined. And yet that is exactly it: a function identity reborn on every render that forces React to throw away the whole subtree. The solution is unspectacular and therefore easy to overlook: components belong at the module level, not in the body of another component. Then `Sidebar` exists exactly once, keeps the same identity across all updates, stands as the same type at the same position – and its state stays. If the inner component needs data from outside, you pass it in as props, not via the nested definition. ## Place and time in the tree State in React is bound to place and time: to a position in the render tree and to the duration for which this position stays occupied by the same type. Almost everything that seems puzzling about the behavior of state clears up as soon as you stop asking “which component is this in?” and instead ask “at which position in the tree, and does the same type still stand there?” Once you have internalized this, you have both directions in hand. You order a reset with a `key` or a new position instead of resetting fields one by one. You secure preservation by keeping position and type stable and, if necessary, lifting the state up. And you avoid the nastiest bug before it arises by keeping components where they belong – at the module level. That turns something that felt like magic into a decision you make on purpose instead of suffering it by accident. ## Further reading - Repository introduction-react: https://github.com/mikebild/introduction-react - React, “Preserving and Resetting State”: https://react.dev/learn/preserving-and-resetting-state - React, “State as a Snapshot”: https://react.dev/learn/state-as-a-snapshot - React, “Render and Commit”: https://react.dev/learn/render-and-commit --- # Serverless Auth with Cognito User Pools URL: https://www.mikebild.dev/en/blog/serverless-auth-with-cognito-user-pools/ Date: 2021-01-19 Cognito takes password handling off your hands – it doesn’t take the decision about who owns your users’ identities off your hands. These two things get lumped together all the time. The `signUp()` call is integrated in an afternoon; the `sub` that Cognito assigns along the way then travels as a foreign key through every table and stays for years. The integration is cheap, owning the identities is expensive. Storing passwords, sending confirmation emails, signing and rotating tokens – solved problems, and rarely what sets a product apart from the competition. A homegrown auth server isn’t differentiation but a surface that has to be maintained and secured for good. AWS has a managed building block for this responsibility: Cognito User Pools. What’s interesting about it is less the API call than the trade-off behind it: Which operational responsibility do I hand over, and what price do I pay if I switch later? That is exactly what I take apart here – with one continuous example that shows the path from registration to the secured endpoint. To me, serverless mainly means handing over operational responsibility where it creates no competitive advantage. Your own auth server rarely is one – it is an attack surface you have to maintain. ## What a user pool actually is A Cognito User Pool is a managed directory for your end users plus all the machinery around it: registration, email or SMS verification, sign-in, password reset and issuing tokens. Your application no longer stores passwords – it only talks to Cognito. That is the decisive change of perspective: it isn’t your app that decides whether a password is correct, it’s the user pool. In the end, your app just gets a signed token and has to be able to trust that token. You need to keep two objects apart. The **user pool** itself is the directory including its policies – password rules, which attributes are required, which get verified automatically. The **app client** is the application that authenticates against the pool; it defines which auth flows are allowed and how long a refresh token stays valid. A pool can have several app clients – for example one for the web and one for the native app. This is what it looks like minimally in CDK. I deliberately stick with the L1 constructs (`Cfn...`) because they map one to one to the CloudFormation resources, so you see exactly what gets created: ```js const { CfnUserPool, CfnUserPoolClient, CfnUserPoolGroup, } = require('@aws-cdk/aws-cognito'); const userPool = new CfnUserPool(this, 'UserPool', { userPoolName: 'UserPool', adminCreateUserConfig: { allowAdminCreateUserOnly: false, }, policies: { passwordPolicy: { minimumLength: 6, }, }, schema: [ { attributeDataType: 'String', name: 'email', required: true, }, ], autoVerifiedAttributes: ['email'], }); const userPoolClient = new CfnUserPoolClient(this, 'UserPoolClient', { clientName: 'UserPoolClient', explicitAuthFlows: ['ALLOW_USER_SRP_AUTH', 'ALLOW_REFRESH_TOKEN_AUTH'], refreshTokenValidity: 30, userPoolId: userPool.ref, }); ``` `autoVerifiedAttributes: ['email']` makes Cognito automatically send a confirmation code by email after registration. `refreshTokenValidity: 30` sets the lifetime of the refresh token to 30 days – more on that in a moment. If you prefer building with the higher-level L2 constructs (`UserPool`, `UserPoolClient`), you get more convenient defaults; for getting started, I find the explicit L1 variant more instructive. If you are wondering why I describe infrastructure in a programming language at all instead of YAML: I explained that in [CDK: Infrastructure in a Programming Language](https://www.mikebild.dev/en/blog/cdk-early-days-infrastructure-in-a-programming-language/). ## Sign-up, confirm, sign-in A user’s lifecycle has three stations. On the client – or, as in my example, in a thin Node backend – I use `amazon-cognito-identity-js`, the official JavaScript SDK for user pools. Registration, confirmation, sign-in: ```ts import { CognitoUserPool, CognitoUser, AuthenticationDetails, CognitoUserAttribute, } from 'amazon-cognito-identity-js'; const userPool = new CognitoUserPool({ UserPoolId: process.env.USER_POOL_ID, ClientId: process.env.USER_POOL_CLIENT_ID, }); // 1) sign-up: create the user, Cognito emails a confirmation code userPool.signUp( username, password, [new CognitoUserAttribute({ Name: 'email', Value: username })], [], (err, result) => { /* result.user is created but not yet confirmed */ } ); // 2) confirm: user submits the code from the email const cognitoUser = new CognitoUser({ Username: username, Pool: userPool }); cognitoUser.confirmRegistration(code, true, (err, result) => { /* result === 'SUCCESS' */ }); // 3) sign-in: authenticate and receive tokens cognitoUser.authenticateUser( new AuthenticationDetails({ Username: username, Password: password }), { onSuccess(session) { const idToken = session.getIdToken().getJwtToken(); const accessToken = session.getAccessToken().getJwtToken(); // refresh token is available too, but opaque }, onFailure(err) { /* wrong password, unconfirmed user, ... */ }, } ); ``` The important point: the confirm step sits between steps one and three. A freshly registered user is `UNCONFIRMED` at first and can’t sign in until they confirm the code delivered by email. Cognito sends that email itself. ## The three tokens – and why “three JWTs” is wrong After a successful sign-in, Cognito returns exactly three tokens. That sounds trivial, but a stubborn misconception lives here: people often say you get “three JWTs”. That isn’t true. Two of them are JWTs, one explicitly is not. The ID token is a JWT and carries the user’s identity – claims such as `sub`, `email` and `cognito:username`. It answers the question “who is this user?” and is the standard token for the classic API Gateway Cognito authorizer. The access token is also a JWT, but it carries OAuth scopes and answers “what is this client allowed to do?”; it comes into play as soon as you use scope-based authorization with resource servers. Finally, the refresh token is not a JWT but an encrypted string that only Cognito can read. It is long-lived – 30 days in my configuration – and serves only to exchange it for fresh ID and access tokens without entering the password again. Why is this more than hair-splitting? Because you can verify a JWT locally – check the signature, check the expiry, done – but not an opaque token. And if the frontend sends the wrong token to the API, you get a `401` without understanding why. For the REST Cognito authorizer without configured scopes, the ID token goes into the header. Only when you configure `authorizationScopes` does the gateway expect the access token. This exact mix-up is one of the most common sources of errors. A decoded ID token essentially looks like this – you can see the issuer, the audience and the intended use: ```json { "sub": "a1b2c3d4-....", "email": "user@example.com", "cognito:username": "user@example.com", "aud": "the-app-client-id", "iss": "https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_ABC123", "token_use": "id", "exp": 1611060000 } ``` ## Securing the endpoint – without your own verification code Now comes the part where managed auth really pays off. I could check the token myself in every Lambda: load the pool’s JWKS document, find the matching key via the `kid` from the token header, convert it to a PEM and verify the signature. I built exactly that in a classic Express backend, and it is instructive to have seen it done by hand once: ```ts export async function validateToken({ token, region, userPoolId }) { const response = await fetch( `https://cognito-idp.${region}.amazonaws.com/${userPoolId}/.well-known/jwks.json` ); const { keys } = await response.json(); const decoded = jwt.decode(token, { complete: true }); if (!decoded) throw new Error('Invalid JWT'); const key = keys.find((k) => k.kid === decoded.header.kid); if (!key) throw new Error('Invalid JWT'); const pem = jwkToPem({ kty: key.kty, n: key.n, e: key.e }); return new Promise((resolve, reject) => { jwt.verify(token, pem, (err, payload) => err ? reject(new Error('Invalid JWT')) : resolve(payload) ); }); } ``` That works – but it is code I have to write, test and maintain, and it shows up again in every secured route. The **API Gateway Cognito authorizer** takes exactly this work off your hands. You point the gateway at the user pool, and it handles the entire check as a managed service: signature against the pool JWKS, `exp`, `aud`, `iss`. If a valid token arrives, the Lambda gets invoked; if an invalid or expired one arrives, the gateway answers with `401` before your function even starts. No verification code of your own. In CDK, you connect this to a REST API route via a `CognitoUserPoolsAuthorizer`: ```ts import { RestApi, CognitoUserPoolsAuthorizer, AuthorizationType, LambdaIntegration, } from '@aws-cdk/aws-apigateway'; const authorizer = new CognitoUserPoolsAuthorizer(this, 'Authorizer', { cognitoUserPools: [userPool], }); const api = new RestApi(this, 'Api'); const items = api.root.addResource('items'); items.addMethod('GET', new LambdaIntegration(getItemsFn), { authorizer, authorizationType: AuthorizationType.COGNITO, }); ``` If you work directly at the API Gateway level – in an OpenAPI definition, for example – you’ll recognize the same configuration in its raw form. The authorizer is of type `cognito_user_pools`, references the pool by ARN and reads the token from the `Authorization` header: ```json { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:eu-central-1:123456789012:userpool/eu-central-1_ABC123" ], "identitySource": "method.request.header.Authorization" } } ``` So the client simply sends its ID token in the `Authorization` header – in practice usually as `Bearer ` – and doesn’t have to take care of anything else. The whole flow looks like this: ```mermaid sequenceDiagram participant C as Client participant Cog as Cognito User Pool participant GW as API Gateway participant L as Lambda C->>Cog: sign-in (username / password) Cog-->>C: ID + Access + Refresh tokens C->>GW: GET /items
    Authorization: Bearer idToken GW->>Cog: verify JWT via JWKS (signature, exp, aud, iss) GW->>L: invoke (token valid) L-->>C: 200 OK ``` ## Lambda triggers: hooking your own logic into the flow Sometimes the standard flow isn’t enough. For example, you want to allow only email addresses from a specific company domain, or write additional data to a table of your own during registration. For this, the user pool offers **Lambda triggers** – entry points at defined places in the lifecycle. Available in 2021 are, among others, `PreSignUp`, `PostConfirmation`, `PreAuthentication`, `PostAuthentication`, `PreTokenGeneration` and `CustomMessage`. A `PreSignUp` trigger runs before Cognito creates a new user. This is where I check the email domain, for example: ```js exports.handler = async (event) => { const email = event.request.userAttributes.email || ''; if (!email.endsWith('@example.com')) { throw new Error('Only example.com addresses are allowed'); } // do NOT auto-confirm: keep the email verification step intact event.response.autoConfirmUser = false; return event; }; ``` Two things are crucial here, and both are classic pitfalls. First: the trigger must **return** the `event` object at the end, unchanged except for the intended response fields. If you forget the `return event`, the flow aborts. Second: `autoConfirmUser` and the related auto-verify fields are powerful. If you accidentally set them to `true`, a user bypasses the email confirmation step completely – and later you wonder about unconfirmed addresses in the pool. The small component picture for this: ```mermaid flowchart LR Pool[User Pool + App Client] -->|JWKS| GW[API Gateway
    Cognito Authorizer] GW --> Fn[Lambda] Trigger[PreSignUp trigger] -.-> Pool ``` ## The real trade-off: managed identity versus vendor lock-in Everything shown so far is the credit side: no password handling, no homegrown token issuing, no verification logic in every route. This responsibility, including the attack surface, moves to AWS – usually the heavier item. Still, I won’t hide the debit side: lock-in to the vendor. This lock-in is more concrete than it seems at first. Your tokens are signed against this pool’s JWKS, your client talks through the Cognito SDK, your triggers are tailored to Cognito’s event structure – and weighing heaviest: every user’s `sub` is a UUID assigned by Cognito that travels as a foreign key across your databases. It isn’t the login code that sticks, it’s these identities. Two edge cases make this tangible. Cognito doesn’t hand out password hashes: if you move away, you can’t quietly take your users with you – either everyone resets their password, or you migrate them lazily on their next login through a `UserMigration` trigger on the target system. And everything beyond the standard – custom attributes, SRP assumptions in the client, MFA configuration – is Cognito vocabulary that another provider doesn’t speak one to one. So the migration risk doesn’t sit in the auth flow, which you can rebuild in days, but in the identities and their references, which have grown over years. This turns into a clear decision grid. For standard sign-in with email and password, small to medium teams without dedicated security staff and without a multi-cloud requirement, managed identity almost always wins – the operations you save clearly outweigh the lock-in risk. I would reconsider as soon as an existing identity provider is in place in-house, real vendor portability is required, or data residency dictates where identities may live at all. The trade-off doesn’t go away – but you make it deliberately instead of by reflex, and you make it at the start, when it is still cheap. ## An important distinction: infrastructure auth is not resolver auth Finally, the distinction that blurs fastest in practice. What the Cognito authorizer does at the API Gateway is **infrastructure or edge auth**. It answers a single, coarse question: “Is the caller authenticated at all?” If the token is valid, the request gets through – if it isn’t, it gets thrown out with `401` before any of your own code runs. That is a bouncer, not a case worker. What the authorizer doesn’t do: decide whether *this specific user* may see or change *this specific object*. May user A delete user B’s comment? May someone only query their own orders? That is fine-grained authorization, and it belongs in your application logic – in a GraphQL API, for example, in the resolver context, where you check the identity from the token against the actual data objects. The authorizer gives you the reliable identity; which permissions you enforce with it remains your job. Keeping these two levels cleanly apart saves a lot of confusion – and prevents the fallacy that with an authorizer, “authorization is done”. For the setup shown here – user pool, standard login and a secured API endpoint – Cognito takes a lot of infrastructure off your hands. You can build a first end-to-end path with it at a manageable effort; it only becomes production-ready with settled recovery flows, MFA, monitoring and fine-grained authorization. The authorizer provides the reliable identity; the permissions on concrete domain objects deliberately stay in your application logic. You pay the price, the vendor lock-in, with your eyes open – and you make the decision where it belongs: at the architecture level, not in passing with the first API call. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-aws-serverless.en.html - Repository with the complete example: `introduction-aws/examples/userpool` (CDK stack, sign-up/confirm/login and the manual token check as a contrast to the authorizer) - [Amazon Cognito – Using Tokens with User Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) - [Using the ID Token](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html) · [Using the Access Token](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html) · [Using the Refresh Token](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-refresh-token.html) - [Control access to a REST API using Amazon Cognito user pools](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html) · [Setting up the authorizer (ID vs. access token/scopes)](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-enable-cognito-user-pool.html) - [Decoding and verifying a JWT (JWKS)](https://repost.aws/knowledge-center/decode-verify-cognito-json-token) - [Customizing user pool workflows with Lambda triggers](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html) --- # Trunk-Based Development Instead of a Branch Graveyard URL: https://www.mikebild.dev/en/blog/trunk-based-development-instead-of-a-branch-graveyard/ Date: 2020-11-24 If you postpone integration, you haven’t avoided the conflict – you’ve just let it accrue interest. A branch called `feature/redesign` that runs alongside `master` for six weeks picks up a few changes every day that nobody checks against the current state anymore. The merge at the end is then no longer a work step but an excavation – and nobody can say beforehand how long it will take. Repositories in which half a dozen such branches slowly age away are what I call the branch graveyard in reviews. The way out isn’t the next branching model but less distance: integrate into a shared state daily, keep it shippable at all times and separate switching on a feature from rolling out the code. That sounds like Git cosmetics, but it affects lead times and fixing bugs. Deploy and release are two different things – everything else hinges on this separation. It isn’t free, though: every flag creates additional states, testing effort and a cleanup task. ## The actual idea: keep the integration distance small Let’s start with the core idea, not the tool. Trunk-Based Development – as Paul Hammant describes it on trunkbaseddevelopment.com – essentially means: all developers integrate their work into a single shared branch at least once a day. Let’s call it `main` or `trunk`. This branch stays releasable at all times. Branches, if they exist at all, are short-lived – well under a day. The key concept behind this is integration distance. Every day a branch lives away from the trunk increases the distance between what I’m working on and what the rest of the team sees. This distance isn’t linear. It grows disproportionately, because changes pile up on both sides and can conflict with each other. A merge after six weeks isn’t six times as expensive as one after a week but many times that – and above all, it’s unpredictable. Martin Fowler gets to the heart of this with his notion of Continuous Integration, and more literally than many read it. “Continuous Integration” really means integrating continuously. A long-lived feature branch is by definition the opposite: deferred integration. You can’t practice Continuous Integration and sit on your own branches for days at the same time. One rules out the other. In his Patterns for Managing Source Code Branches, Fowler provides the matching taxonomy: integration frequency, the notion of the “healthy branch,” the mainline. Once you have internalized this vocabulary, you spot the branch graveyard immediately. ## What the data says – carefully phrased I’m skeptical of methodology promises that rest only on gut feeling. That’s why I value the work of Nicole Forsgren, Jez Humble and Gene Kim in *Accelerate* and the State of DevOps Reports. There, Trunk-Based Development isn’t treated as an opinion but as a statistically identified capability. I phrase this deliberately carefully, because the temptation to exaggerate here is great. The data shows: higher software delivery performance correlates with few active branches in the repository – on the order of three or fewer – and with merges into the trunk at least once a day. Trunk-Based Development is one of the practices that statistically predict Continuous Delivery. Not “guaranteed to cause” but predicts and correlates. This difference is too important to blur when quoting. But the direction is clear, and it matches what I observe in teams: if you keep the integration distance small, you deliver faster, break things less often and with less drama. ## The flawed thinking: deploy isn’t release Now comes the part where many discussions tip over. “If everyone merges to the trunk all the time – how is anything half-finished ever supposed to stay out of production?” This question is fair, and its answer is the real lever of this whole approach. Deploy and release are two different events. Deploy means: the code is on the production environment. Release means: the behavior is active for users. Feature toggles – described by Fowler in the bliki and systematized in detail by Pete Hodgson in *Feature Toggles (aka Feature Flags)* – decouple exactly these two things. The code is rolled out, but the feature is switched off. Activation becomes a configuration and business decision, not a technical deploy event with a night shift and a rollback plan. ```mermaid flowchart LR subgraph friedhof["Branch graveyard"] direction TB M0["main"] --> M1["main"] M0 --> B1["feature branch
    day 1"] B1 --> B2["... day 20 ..."] B2 --> B3["diverges far"] M1 --> MG(("big
    merge conflict")) B3 --> MG end subgraph tbd["Trunk-Based"] direction TB T0["trunk"] --> T1["+ commit"] T1 --> T2["+ commit"] T2 --> T3["+ commit"] T3 --> T4["trunk stays green"] T4 -. "toggle on
    = release" .-> R(("Release
    as a switch")) end ``` The diagram shows the core: on the left, a branch diverges over twenty days and ends in a painful merge. On the right, a continuous trunk flows with many small commits, and activation happens on a separate axis – decoupled in time from the merge and the deploy. Release becomes a switch. Hodgson distinguishes four categories of toggles, and this distinction is valuable in practice because each has a different lifecycle. Release toggles hide unfinished work and are meant to be short-lived. Ops toggles control operational behavior, for example to switch off an expensive function under load. Experiment toggles drive A/B tests and fit well with the Build-Measure-Learn idea from Eric Ries’ *Lean Startup*. Permission toggles unlock behavior for specific user groups. If you don’t keep these four apart, you end up treating every flag the same – and that comes back to bite you. ## How unfinished work lives safely on the trunk A release toggle in its simplest form looks like this. What matters is that the flag isn’t scattered as a loose `if` in the domain code but sits behind a clean abstraction: ```typescript // The domain code does not know about flag plumbing. // It asks a small, well-named abstraction. if (features.isEnabled("new-checkout-flow")) { return newCheckoutService.process(cart); } return legacyCheckoutService.process(cart); ``` The configuration side decides whether a deploy is also a release. A disabled flag means: the code is there, but nobody sees it. That’s deploy without release: ```yaml features: new-checkout-flow: enabled: false # deploy != release strategy: canary # gradual rollout instead of big-bang percentage: 5 # start with 5% of traffic ``` For large rebuilds, though, a single `if` isn’t enough. When I replace a central module, the Branch by Abstraction pattern helps – described by Fowler and attributed to Paul Hammant. The idea: I introduce a shared interface under which the old and the new implementation live in the trunk at the same time. Switching happens through a factory or a toggle. Instead of a weeks-long branch, I integrate a large refactoring in small steps that are integrated daily: ```java public interface PaymentGateway { PaymentResult charge(Order order); } // Both live in the trunk at the same time. final class LegacyPaymentGateway implements PaymentGateway { /* ... */ } final class NewPaymentGateway implements PaymentGateway { /* ... */ } // A factory selects the implementation behind a toggle. PaymentGateway gateway = features.isEnabled("new-payment-gateway") ? new NewPaymentGateway() : new LegacyPaymentGateway(); ``` In addition, there are dark launching and the keystone interface: you build a large feature piece by piece but put the visible element – the keystone – in place only at the very end. Until then, the new code may already be running along, collecting data or being tested against production load, without any user noticing. Canary releases and blue-green deployments play into this too: rolling out and activating become gradual, controllable processes instead of a big bang. ## The contrast: GitFlow and the reflex toward the long branch I want to be fair. GitFlow, which Vincent Driessen introduced in 2010 in “A successful Git branching model,” was a well-thought-out answer to a real problem – for a particular kind of software. In 2020, Driessen himself added a note that his model wasn’t intended for continuously delivered web apps. That’s exactly the point. If you build a product with versioned releases and long support cycles, you can live well with a branching model like GitFlow. If you run a continuously delivered application, you get the branch graveyard delivered right to your door. As a lighter alternative, GitHub Flow has existed since 2011: a short-lived branch, a pull request, a quick merge back into the mainline. That’s already much closer to Trunk-Based Development. The real difference isn’t in the tooling but in the question of how long a team is willing to postpone integration. The longer the answer, the more expensive the bill. ## Honest about the pitfalls The approach doesn’t solve everything, and it brings its own problems. There are three edges where teams reliably cut themselves. First: toggle debt, the toggle graveyard. The irony is bitter. You introduce feature flags to avoid the branch graveyard and in the process produce a new graveyard of flags that were never removed. Every release toggle that stays in the code after the release is technical debt. It doubles paths, confuses readers and rots quietly. Hodgson is clear here: release toggles need an expiration date and must be actively removed. In the teams where this worked, removing the flag was a fixed part of the definition of a finished feature – it was only done once its release toggle had disappeared from the code again. ```mermaid flowchart LR A["create toggle"] --> B["deploy dark"] B --> C["gradual release"] C --> D["fully on"] D --> E["remove toggle"] E --> F["trunk stays clean"] ``` Second: Trunk-Based Development without robust test automation and a CI gate is dangerous. The whole approach stands or falls with the trunk staying green and releasable. If builds and tests are slow or unreliable, you import instability directly into the mainline instead of isolating it in branches. In poorly tested codebases, the long branch is sometimes a rational form of self-protection. The right order is therefore: first fast, reliable tests and a gate, then daily integration. Not the other way around. If you also fear integration risks between services with frequent merges, consumer-driven contract testing – for example with Pact – gives you an effective safety net. Third: the test matrix explosion. Every flag combinatorially doubles the possible paths through the code. Two flags result in four states, three in eight. Untested flag combinations are a real risk space, not a theoretical one. The discipline against this is unspectacular but effective: few toggles active at the same time, clear ownership for each one, and a deliberate eye on the combinations that can actually occur together. ## Why the effort pays off When I pull all of this together, I don’t end up with a tool recommendation but with an attitude toward delivery. Small integration distance, a trunk that is releasable at any time and the clean separation of deploy and release together produce something that shows up in business numbers. Cycles get shorter, because nobody loses days in merge conflicts anymore. Friction in the team drops, because everyone works against the same current state and conflicts are small and frequent instead of big and rare. Quality rises, because a feature is rolled out gradually and reversibly instead of in a single risky leap. And the release loses its terror: it’s no longer a nightly deploy event but a decision that someone makes with a switch – reversible, measurable, calm. In the end, that’s the appeal of the approach. It replaces process overhead with something simple and elegant. Instead of an elaborate branching model that manages the merge pain, you avoid the pain by never letting it arise. The branch graveyard isn’t a law of nature. It’s a consequence of postponed integration – and that can be abolished. ## Further reading - Paul Hammant et al.: [trunkbaseddevelopment.com](https://trunkbaseddevelopment.com/) - Martin Fowler & Pete Hodgson: [Feature Toggles (aka Feature Flags)](https://martinfowler.com/articles/feature-toggles.html) - Martin Fowler: [Patterns for Managing Source Code Branches](https://martinfowler.com/articles/branching-patterns.html) - Martin Fowler: [Branch by Abstraction](https://martinfowler.com/bliki/BranchByAbstraction.html) - Forsgren, Humble & Kim: *Accelerate* (2018) and the State of DevOps Reports - Humble & Farley: *Continuous Delivery* (2010) - Vincent Driessen: [A successful Git branching model](https://nvie.com/posts/a-successful-git-branching-model/) (for contrast) --- # How React Renders and Updates the Tree URL: https://www.mikebild.dev/en/blog/how-react-renders-and-updates-the-tree/ Date: 2020-10-24 # How React Renders and Updates the Tree ```js setCount(count + 1); ``` After this line, nothing at all happens in the browser at first. No node is replaced, no pixel redrawn. React initially just calls JavaScript functions – the components – and collects what they return. Whether a DOM node has to be touched at all is only decided afterward, in a separate step. That a component function runs and that the browser gets something to do are two different processes – and most misunderstandings about React performance dissolve at this separation. The article [JSX Precisely: The Rules Behind the Markup](https://www.mikebild.dev/en/blog/jsx-precisely-the-rules-behind-the-markup/) was about the fact that a JSX element is ultimately just an object – a description of what should be on the screen. Here the path continues: how does this description become a real DOM, and what happens to it when the state changes? Rendering is a computation in JavaScript, changing the DOM a write operation in the browser. React deliberately keeps the two apart. Between a state change and a visible DOM change lie several clearly separated stages. :::process{title="From update to DOM" role="primary" preferredPattern="vertical-journey"} 1. Trigger · state, props or context make work necessary 2. Render · React calls components and produces the next element structure 3. Reconcile · old and new structure are compared by type and key 4. Commit · necessary changes are applied to the DOM and effects ::: The separation explains why calling a component again doesn’t automatically mean a complete rebuild of the DOM. ## Three steps: trigger, render, commit React displays a UI in three steps. You can picture them like an order in a restaurant kitchen: someone places the order, the kitchen cooks, the waiter brings the dish to the table. ```mermaid flowchart LR Trigger["1. Trigger
    initial or setState"] --> Render["2. Render
    call components"] Render --> Commit["3. Commit
    minimal DOM change"] Commit --> Paint["Browser repaints"] ``` The first step is the trigger. There are exactly two occasions. At application startup, it happens once, when you create the root and pass in the top-level component. After that, a re-render is only triggered by a state change – always through the setter function from `useState` or a corresponding mechanism. Without a state change, React re-renders nothing. That’s important: a click alone does nothing; only when the click changes the state does the machine get going. ```jsx import { createRoot } from "react-dom/client"; const root = createRoot(document.getElementById("root")); root.render(); ``` ## Rendering means: React calls your functions The second step, rendering, is the one that is misunderstood the most. In React, rendering doesn’t mean painting something on the screen. Rendering means: React calls your component functions to find out what should be displayed. The first time, it calls the root component. On a re-render, it calls the component whose state has changed. And this call is recursive. If a component returns other components, React calls those too, and their children as well, until there are no more nested components. At the end of this pass there’s no DOM but a new tree of React elements – the same description objects from the JSX article, just the whole tree of them. ```mermaid flowchart TB App["App()"] --> Liste["InvoiceList()"] App --> Kopf["Header()"] Liste --> Z1["Row() #1"] Liste --> Z2["Row() #2"] Z1 --> Betrag1["Amount()"] Z2 --> Betrag2["Amount()"] ``` For this pass to be reliable, React requires a property I already emphasized in earlier articles: rendering has to be a pure computation. The same props and the same state must produce the same description, and nothing that already existed may be changed during rendering. Only under this condition can React safely repeat rendering, defer it or discard it in favor of a later result – all things the modern, concurrent version of React actually does. ## Reconciliation: comparing two trees Now comes the core that explains why the whole thing is fast. After a re-render, React has two trees: the new one, just computed, and the previous one from the last pass. Before anything is written to the DOM, React compares the two. This comparison is called reconciliation, and it follows a few simple rules. At the same position in the tree, the type of the element decides. If the type is the same – a `
    ` before, a `
    ` again now, or the same component before and now – React keeps the existing node and only updates the properties that have changed. If the type is different – a `

    ` before, a `

    ` now – there’s no detailed comparison: React tears down the old subtree, throws away its state and builds the new one from scratch. ```mermaid flowchart LR subgraph Vorher["Before"] A1["div"] --> A2["span: 'Hello'"] end subgraph Nachher["After"] B1["div"] --> B2["span: 'World'"] end A1 -. "same type:
    node stays" .-> B1 A2 -. "only text content
    changes" .-> B2 ``` This rule has a practical consequence that beginners often stumble over. Because a type change discards the whole subtree, you also lose its state: an input field that used to sit in a `
    ` and now sits in a `
    ` is treated as a new element and is empty again. If you want state to be preserved, you have to make sure the same type is at the same position. ## Lists are the special case – and this is where keys come in For children in a list, the position isn’t enough, because lists change their order. That’s exactly what the key is for, which I already talked about in the article [JSX Precisely](https://www.mikebild.dev/en/blog/jsx-precisely-the-rules-behind-the-markup/) – and here it becomes clear why it matters so much. When reconciling a list, React doesn’t compare position with position but key with key. An element with the same key counts as the same element as before, no matter where it is now. React then moves the existing DOM node instead of throwing it away and rebuilding it. That’s why the array index as a key is so treacherous. If you insert an element at the front, every index shifts by one. To React it then looks as if the content of every row had changed – and the state that actually belonged to the third invoice suddenly sticks to the fourth. With a stable domain ID as the key, React recognizes the identity correctly: the inserted element is new, all the others are the same as before and simply move one position further. ## Commit: React only touches what has changed Only after reconciliation comes the third step, the commit. Now React writes to the real DOM – but only what reconciliation identified as a difference. On the very first render, everything has to be created, and React attaches the created nodes to the page with the usual DOM calls. Every time after that, the decisive sentence from the documentation applies: React only changes a DOM node if there’s a difference between two render passes. That sounds obvious, but it has visible consequences. When a parent component re-renders but an input field deep inside it stays unchanged, React doesn’t touch that node – and the text you just typed stays put, even though the whole branch was recomputed. That’s exactly the proof that rendering and DOM changes are separate: the component was re-rendered (the function ran), but the DOM wasn’t touched (there was no difference). ```mermaid sequenceDiagram participant N as User participant R as React participant D as DOM N->>R: setState (state changes) R->>R: call components again (render) R->>R: compare new tree against old one R->>D: write only the differences D->>N: Browser paints the result ``` After the commit, React is done. What happens next belongs to the browser: it repaints the changed part of the page. This repainting is a separate step, independent of React – another reason why the minimal DOM change is worth so much, because the less changes in the DOM, the less the browser has to repaint. ## Why a re-render doesn’t have to be expensive With this picture, a widespread misunderstanding dissolves. Many people believe a re-render is automatically slow and optimize wildly against it. But rendering at first only means that a JavaScript function runs again and creates a few objects. That’s rarely the problem. What gets expensive is writing to the DOM and the subsequent repaint – and that’s exactly what React keeps small through reconciliation. That doesn’t mean rendering is free. If a component high up in the tree re-renders, React calls the whole subtree below it again, even if hardly any DOM changes come out of it in the end. For the vast majority of applications, that’s not an issue. Where it does become measurable, you can memoize a subtree by hand, for example with `React.memo`: React then skips re-rendering as long as its props haven’t changed. But the order stays the same: measure first, then check whether rendering really is the problem – and most of the time it isn’t. ## What to take away The whole mechanism boils down to one sentence: on every state change, React computes a new description of the UI, compares it with the old one and writes only the differences to the DOM. The description is cheap, the comparison is clever, and the expensive DOM work stays minimal. The key isn’t a detail here but the information the comparison uses to tell identity from position – and the reason a good choice of key decides whether state is preserved correctly. With that in mind, you make better decisions in everyday work: you no longer flinch at a re-render, you know why an input field keeps or loses its text, and you understand when a type change or a changing key throws away an entire subtree. For the deeper behavior of state across render boundaries – why state is bound to a position in the tree and when it gets reset – there’s the follow-up article on preserving and resetting state. ## Further reading - Repository introduction-react (examples to follow along): https://github.com/mikebild/introduction-react - React, Render and Commit: https://react.dev/learn/render-and-commit - React, State as a Snapshot: https://react.dev/learn/state-as-a-snapshot - React, Preserving and Resetting State: https://react.dev/learn/preserving-and-resetting-state - React, Rendering Lists (keys): https://react.dev/learn/rendering-lists --- # Team Automation with GitHub Actions URL: https://www.mikebild.dev/en/blog/team-automation-with-github-actions/ Date: 2020-10-12 # Team Automation with GitHub Actions A file under `.github/workflows` is not a build script and not a better Makefile. It is a rule with teeth: something that applies on every push and every pull request without anyone having to remind people. The difference sounds academic, but it decides what such a file can actually do in a team’s everyday work. It becomes visible in the questions that end up there. Is code merged before the tests are green? Is the code formatted? Does the change have a changelog entry? Who may trigger a release? As long as the answers live in the head of an experienced person, in a wiki or in a PR comment you have already written three times, they hold – but only as long as everyone is awake and present. They break on the day someone new joins, someone is on vacation or it is simply late. In the repository, on the other hand, the rule sits next to the code, in the same history, and is applied instead of negotiated. That is exactly where its value lies, and exactly where the interesting architecture questions begin. ## Automation as an executable agreement The first mistake is to sell automation as a time saver. It does save time, but that is the smaller effect. The bigger one is that a decision stops being negotiable. If “we only merge with green tests” is a convention, it holds until the pressure rises. If the same rule is a required check on the branch, it holds even when nobody is looking. The rule moves from the social space to the technical space, and there it is robust against fatigue and hierarchy. This shifts my design question. I do not ask “which steps can I automate” but “which decision do I want to make reliable.” That is an architecture decision, not a scripting exercise. A good workflow encodes an intent: this class of errors should never reach the main branch. Nobody should do this follow-up work by hand anymore. This step should be traceable, even in half a year. ## Where the line runs Before I write a line of YAML, I draw a line that many pipelines do not draw cleanly: the one between checking and changing. A gate only reads. It says yes or no and touches nothing – lint, tests, typecheck, format check. A changing step intervenes: it publishes an artifact, tags a release, deploys, comments, labels. These two classes have completely different requirements for permissions, repeatability and failure behavior, and if you mix them in the same job, the harmless test step suddenly inherits the permissions of the dangerous deploy step. Check steps therefore run on every pull request, including those from forks, and get no secrets. Changing steps run only on trusted triggers – a merge to the main branch, a tag, a deliberately triggered run. This separation carries the security architecture of the entire repository. GitHub takes care of part of it: for a pull request from a fork, the `GITHUB_TOKEN` is read-only and secrets are not visible. That is the answer to a real attack scenario, and I build my workflows so that they respect this boundary instead of working around it. ## A concrete gate This is what a pull request gate looks like that I set up in this form again and again. It checks and changes nothing: ```yaml name: pr-gate on: pull_request: branches: [main] jobs: verify: runs-on: ubuntu-latest strategy: fail-fast: false matrix: node-version: [12.x, 14.x] steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v1 with: node-version: ${{ matrix.node-version }} - run: npm ci - run: npm run lint - run: npm run typecheck - run: npm test -- --ci ``` A few decisions in it are deliberate and carry more meaning than they appear to. `npm ci` instead of `npm install`, because I want reproducible installs from the lockfile and no creeping drift of dependencies. The matrix over two Node versions, because “works on my machine” is the most common lie in teams and I would rather move compatibility from the laptop into the pipeline. `fail-fast: false`, because on a red run I want to see both versions, not just the first one that aborts – an aborted report costs a whole round of feedback. But the real lever is not the YAML. It is the branch protection rule that makes this check mandatory. Only that turns a friendly recommendation into a boundary that the main branch defends. The workflow provides the signal; the protection rule gives it teeth. ## The expensive mistake is the happy path The happy path is quickly built: everything green, artifact built, release out. It gets interesting exactly where things do not go well, and that is where it is decided whether the automation is a tool or a new source of errors. The first stumbling block is idempotency. A changing step must be built so that a second run does no harm. Runs get repeated – after a network error, via the re-run button, because someone sets the same tag again. If my publish step creates a duplicate artifact the second time or aborts with a hard error, I have not abolished the manual follow-up work, only moved it. That is why I build such steps so that they check whether the version already exists and then cleanly do nothing. The second stumbling block is the fork. A pull request from outside should be checked, but not rewarded with trust. There is `pull_request_target`, which runs with the permissions of the target repository and has access to secrets – intended for harmless tasks such as labeling or commenting on a PR. If you use it to check out and run foreign code from the fork, you open the door to exactly the secrets you wanted to protect. That is why, in my setups, `pull_request_target` only runs code from the target branch and never the content of the PR. This puts the separation of checking and trust exactly where it really hurts. The third stumbling block is the flaky test. A check that turns red at random is worse than no check, because it teaches the team to ignore the red cross. The moment “just run it again” becomes a habit, the value of the gate is gone. For me, an unstable test is not a side issue but a defect in the boundary itself – it should be fixed or isolated, not tolerated. ## The path from checking to changing The picture behind it is simple, and I deliberately draw it as a flow, because the direction carries the whole message: ```mermaid flowchart LR PR[Pull Request] --> Gate{Gate
    lint, test, types} Gate -- red --> Stop[Merge blocked] Gate -- green --> Merge[Merge to main] Merge --> Trusted[Trusted run] Release --> Audit[Traceable in the history] Trusted --> Release[Tag, Publish, Deploy] ``` On the left, things are only read; on the right, changes happen only after the merge. Between the two lies the trust boundary. Almost all of the security and operations questions that come up in real projects can be traced back to whether a step sits on the right side of this line. ## The deliberate trigger Not every changing step should fire automatically. For a release, I often want a human involved, but without someone typing commands locally that nobody else sees. That is exactly what I use `workflow_dispatch` for – a trigger that you deliberately press a button for, with a small input form: ```yaml name: release on: workflow_dispatch: inputs: level: description: "semver bump level" required: true default: patch jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v1 with: node-version: 14.x - run: npm ci - run: npm run build - run: node ./scripts/release.js --level "${{ github.event.inputs.level }}" env: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} ``` This is the manual decision as a form instead of a verbal agreement. The actual logic deliberately lives in `release.js`, a tested script that the workflow merely calls – the secret is limited to this one trusted path and never shows up in the check gate. The gain lies in traceability: every release appears with its trigger, time and person in the same history as the code. A process that used to vanish into a terminal becomes an entry you can still read half a year later. ## What it measurably delivers I do not like automation that only feels good. The benefit should show in three places; otherwise I have traded effort for a gut feeling. The first is the lead time of a pull request. If the gate already answers the usual review questions – is it formatted, do the tests pass, is the typecheck clean – before a human looks at it, the time from “PR open” to “merged” shrinks noticeably. The review can focus on what a machine cannot see: whether the solution is the right one. The second is the friction in the review itself. Discussions about formatting and style are expensive, not because they take long, but because they poison the tone. A machine that decides formatting questions takes them out of the interpersonal level. Nobody argues with a linter anymore. The third is the time until a new person’s first meaningful contribution. If the team’s rules are in the repository and become visible with the first PR, nobody has to pass them on verbally. Onboarding turns from an obligation of experienced colleagues into a property of the project. For me, this is the most underrated effect: automation is also a form of documentation that never goes stale, because it is executed. ## When I deliberately do not do it A tool is not an architecture, and GitHub Actions is no exception. There are cases where I advise against it. If an automation would be real orchestration across many systems with state, restart points and long run times, a workflow runner is the wrong home – that belongs in a proper job runner or a platform built for it, not in a CI file. And if a rule is still in flux because the team itself does not know whether it is right, I do not cement it in a required check. Automation is good at enforcing settled decisions and bad at replacing unsettled ones. The most expensive mistake is letting the runner grow into a secret deployment platform until critical processes live in a YAML file nobody understands anymore. A workflow that fills a page is a win. A workflow that fills three screens and catches special cases with `if` conditions is usually a program in the wrong place – then the logic belongs in a tested script or a small CLI that the workflow merely calls. ## How I get started In practice, I do not turn this into a big initiative. I start with exactly one gate that removes a real, recurring friction – usually tests plus a format check on every PR – and make it mandatory via branch protection. Then I wait two weeks and see whether it takes load off the team or just annoys it. Only when it holds does the next step come along, and the first changing step deliberately comes later than the first checking one. The yardstick stays the same as for any architecture: a decision is only good once I can describe its failure path. What happens on a re-run? What if the PR comes from a fork? What if a test becomes flaky? Who notices when the gate fails silently? When I can answer these questions, convenience has turned into a piece of reliable team infrastructure. That a machine takes work off your hands along the way is the pleasant Side Effect. The point is the decision that finally holds. --- # Web APIs with Flask: From the App to a JSON API URL: https://www.mikebild.dev/en/blog/web-apis-with-flask/ Date: 2020-09-22 Three terms are enough to describe everything Flask does: route, request, response. A decorator binds a URL path to a Python function, the `request` object describes the incoming request, and the function’s return value becomes the response. Templates, blueprints, JSON – everything else hangs off these three points. That makes Flask a good starting point when a Python script is supposed to become an interface another program can talk to over HTTP. It’s a micro-framework: routing, request object and template engine are included, almost everything else is left open. There’s hardly any magic you’d first have to take apart to understand what actually happens between the HTTP request and your own function. Throughout, this text refers to Flask 1.1 – the stable series at the time of writing (1.1.2 came out in April 2020). If you’ve worked with Python objects, decorators and dictionaries before, you’ll find your way quickly. **Editorial note (July 2026):** In today’s Flask 3.1, `request.json` calls `get_json()` internally and responds with 415 by default if the `Content-Type` isn’t suitable. Only `request.get_json(silent=True)` returns `None` in that case. This change affects error handling, not the routing model of this article. ## Hello World, and what’s behind it The smallest meaningful Flask server fits into six lines. You can read the entire model from it. ```python from flask import Flask app = Flask(__name__) @app.route('/') def hello_world(): return 'Hello World!' if __name__ == '__main__': app.run(debug=True, port=8080) ``` `Flask(__name__)` creates the application. Flask later uses the module name as a starting point, for example to find templates and static files relative to the project. The decorator `@app.route('/')` links a URL path to a function. When the server is called at `/`, Flask calls `hello_world()` and sends the return value back as the response. `app.run()` starts the built-in development server. The central idea: a function that returns a string becomes an HTTP response with `Content-Type: text/html`. Flask takes care of the entire translation between HTTP and the Python function for me. And this translation is more flexible than the first impression suggests. A view may return not only a string but also a tuple of body and status code: ```python from flask import Flask app = Flask(__name__) @app.route('/') def hello_world(): return 'Hello World!', 202 ``` Here the client gets the same text, but with status 202 instead of the default 200. The tuple can even have three elements – body, status and a dictionary with additional headers. These return conventions are the core of Flask, and they explain why the same route sometimes behaves as an HTML page and sometimes as a JSON API. ## Routing, request, response Before we get to the actual API, the three terms deserve a closer look, because they come up again and again: - Route: The decorator `@app.route(pfad, methods=[...])` binds a URL path to a function. Path parameters like `` pass parts of the URL directly to the function, and `methods` defines which HTTP verbs the route serves. - Request: The imported `request` object describes the incoming request – `request.args` reads the query string, `request.form` the form fields, `request.json` the JSON body, `request.method` the verb used. - Response: The function’s return value. A string becomes HTML, `jsonify(...)` becomes JSON, a tuple `(rumpf, status)` controls the status code. These three axes are enough to build a surprising amount. A path with a parameter looks something like this: ```python @app.route('/user/') def profile(username): return f'Profile page of {username}' ``` The placeholder `` is passed to the function as an argument. If you need a numeric value, the converter `` requires an integer and delivers it already as an `int` – if the path doesn’t match this pattern, Flask responds with 404 on its own, before my function even runs. The request lifecycle can be summarized in a simple diagram. Between the incoming request and the finished response there are only a few clearly named steps. ```mermaid graph LR A[HTTP Request] --> B["@app.route
    Matching"] B --> C[View Handler] C --> D["jsonify()"] D --> E[JSON Response] ``` The request arrives, Flask looks for the matching route, calls the associated function, which builds a response with `jsonify`, and that goes back to the client. None of these steps is hidden – you can put a `print` anywhere and watch. ## From page to interface Now to the actual goal: a small, REST-style interface. For this I build a single path that serves two verbs – a `GET` returns the list of all entries, a `POST` creates a new one. That one URL can serve several methods is exactly the point where REST thinking becomes visible: the resource is the same, only the action on it differs. ```python from flask import Flask, request, jsonify app = Flask(__name__) items = [] # demo-only in-memory store @app.route('/items', methods=['GET', 'POST']) def items_collection(): if request.method == 'POST': payload = request.get_json() item = {'id': len(items) + 1, 'name': payload['name']} items.append(item) return jsonify(item), 201 return jsonify(items) # GET @app.route('/items/') def item_detail(item_id): match = next((i for i in items if i['id'] == item_id), None) return (jsonify(match), 200) if match else ('Not found', 404) ``` A few things here are deliberate. For `POST`, I read the JSON body with `request.get_json()` and respond with status 201, the code for “created.” For `GET`, I return the entire list. And the second route shows the path parameter in action: `/items/3` looks up the entry with this ID and returns either it or a 404 response. `jsonify` is more than a prettier `json.dumps`. It serializes the dictionary or list, sets the `Content-Type` correctly to `application/json` and builds a finished response object. The handmade way – turning `json.dumps(...)` into a string and setting the header manually – works, but it’s more error-prone and duplicates exactly the work Flask does cleanly anyway. ## The historical twist: returning a dict directly A note is worth making here, because it causes confusion in older examples. Since Flask 1.1, a view may return a `dict` directly – Flask then automatically calls `jsonify()` on it internally: ```python @app.route('/status') def status(): return {'ok': True, 'items': len(items)} # Flask >= 1.1 -> JSON ``` That’s convenient, but it’s a relatively recent convenience. In Flask 1.0 and earlier, exactly this line was an error: a dictionary wasn’t a valid return type, and you got a `TypeError`. If you wanted to deliver JSON back then, you had to write `return jsonify({...})` explicitly. Tutorials and Stack Overflow answers show both variants side by side without stating the version – which makes it easy to mix up version and behavior. As long as I’m not sure which Flask version is running, I write `jsonify` explicitly. It works in every version and makes the intent clear. ## SSR and APIs are the same mechanism Server-side rendering (SSR) and a JSON API are often seen as two different worlds. In Flask they aren’t: the same routing mechanism, the same function, just a different return type. Instead of `jsonify`, I use `render_template`, which fills an HTML file from the `templates/` folder with Jinja2. ```python from flask import Flask, request, render_template app = Flask(__name__) @app.route('/') def index(): return render_template('index.html', items=items) @app.route('/forms', methods=['POST']) def forms(): return 'You said: ' + request.form['text'] ``` The corresponding template is ordinary HTML with placeholders. The context passed in – here `items` – is available in the template as a variable: ```html
      {% for item in items %}
    • {{ item.name }}
    • {% endfor %}
    ``` The difference between the API and the rendered page is purely the representation: once JSON for machines, once HTML for the browser. The framework underneath stays the same. As a diagram, the branching is quickly told. ```mermaid graph LR A[View Handler] --> B{Representation?} B -->|render_template| C[HTML] B -->|jsonify| D[JSON] ``` With that, “API framework” and “web framework” dissolve as separate categories. It’s a decision per route, not an architectural break. ## Structure with blueprints As soon as more than a handful of routes come together, the one big `app.py` gets cluttered. Flask offers blueprints for this – a way to group routes by topic and attach them to the app with a shared prefix. ```python from flask import Blueprint, jsonify api = Blueprint('api', __name__, url_prefix='/api') @api.route('/items') def list_items(): return jsonify(items) # in the main app: # app.register_blueprint(api) ``` All routes of this blueprint then live under `/api` – so the route above is reachable at `/api/items`. Important to understand: a blueprint is purely a structural tool. It doesn’t change anything about runtime behavior and brings no magic of its own; it only helps cut the code into understandable units. I like to use it to separate the JSON API from the rendered pages – two blueprints, one project. ## Three pitfalls Finally, the places where things regularly get stuck in practice. None of these points is a bug in Flask – they’re peculiarities you need to know. The first concerns `request.json`. In the Flask 1.1 used here, the value was simply `None` without `Content-Type: application/json`, and a direct access like `payload['name']` ran into an error. Current Flask versions respond to this access with 415 by default. If you deliberately want to handle it yourself, use `request.get_json(silent=True)` and check for a possible `None`. ```python @app.route('/echo', methods=['POST']) def echo(): data = request.get_json(silent=True) if not data: return jsonify({'error': 'expected JSON body'}), 400 return jsonify(data) ``` The second is `debug=True`. In the development server, debug mode is handy – it reloads on changes and shows an interactive traceback on errors. But exactly this interactive traceback is an executable console in the browser. In a publicly reachable environment, that’s an open door for executing arbitrary code. `debug=True` belongs exclusively in local development. And `app.run()` itself is only the development server anyway – for production, you put a WSGI server like gunicorn or uWSGI in front of it. The third concerns global state. My `items = []` list is a demo shortcut and not a database. It lives in the process’s memory, is lost on every restart and behaves unreliably as soon as several workers run in parallel – then each worker sees its own list. For an example like this, that’s perfectly fine; for real data you need persistence, such as a database behind the route. ## Conclusion The path from a Python script to a web interface is shorter with Flask than many expect, and – more importantly – it’s easy to follow. A function is bound to a path through a decorator, the `request` object describes the request, the return value becomes the response. Whether that becomes an HTML page via `render_template` or a JSON API via `jsonify` is a decision per route, not a change of system. Blueprints give the whole thing structure as it grows, without introducing new concepts. More important to me than the list of features is that you can say at any time what happens between the HTTP request and your own function. Flask keeps this chain visible. Once you’ve walked through it, you’ll also read more comfortable frameworks more calmly – underneath, they all have the same model of route, request and response. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-python.en.html - Repository `introduction-python`, directory `web/examples/` – the runnable Flask examples (`1-app.py`, `2-html.py`, `3-json.py`, `app.py`) this article builds on. - Flask 1.1 Quickstart – routing, methods and path parameters: https://flask.palletsprojects.com/en/1.1.x/quickstart/ - Flask 1.1 API reference – request object and `jsonify`: https://flask.palletsprojects.com/en/1.1.x/api/ - Flask 1.1 Blueprints: https://flask.palletsprojects.com/en/1.1.x/blueprints/ - Flask 1.1 Deployment – why the development server doesn’t belong in production: https://flask.palletsprojects.com/en/1.1.x/deploying/ - [Flask 3.1: incoming request data and `get_json()`](https://flask.palletsprojects.com/en/stable/api/#flask.Request.get_json) --- # Read Models from Events: Projections Instead of Accidental Caches URL: https://www.mikebild.dev/en/blog/read-models-from-events-projections/ Date: 2020-09-15 # Read Models from Events: Projections Instead of Accidental Caches This post looks at the event sourcing case: behind the read view there is an event stream from which it can be derived again. That makes the read model the view intended for queries, not an accidental acceleration layer. Technically it may still look cache-like, for example as a denormalized table with fast replacement. What matters is origin and rebuild, not the storage product. The comparison with a cache is still tempting: a denormalized, fast view that sits next to the actual database simply looks like one. It gets expensive the moment the first schema on the read side has to change. A read side that was built as a cache can then no longer be restored cleanly. One that was built as a projection has the rebuild in its design from the start – and this difference runs through operations, migration and troubleshooting. ## Where the cache reflex comes from The reflex has a grain of truth. On the surface, a read model and a cache solve the same problem: queries should be fast without asking the expensive write model every time something is displayed. Both are denormalized, both sit closer to the user than the source of truth, both are potentially stale. The break lies one level deeper, in the question: who is the source of truth, and how does the fast view emerge from it? A cache has an authoritative database *behind* it. If the cache entry drops out, you pull the record from that source again and store it again. Invalidation is a side effect of TTL or eviction, and a cold start is an operational detail. A read model, on the other hand, has no “actual” read database behind it from which you reload it when needed. It *is* the authoritative read view. What lies behind it is the event store or the write model – and the read model is not “reloaded” from it but *computed*. That computation is the projection. And it is the reason I insist on the distinction. ## What makes a projection Three terms come before the code. Martin Fowler describes CQRS as a deliberate separation: you use a different model to update information than the model you use to read information. The read model is not a view through the domain model, but a separate model that serves queries exclusively. Greg Young and Vaughn Vernon provide the link: the projection – the process that derives and updates the read model from the changes on the write side, specifically from the domain events. The decisive property of the projection discussed here is its origin in an immutable event stream. If events, order, projection code and other inputs are fixed, replaying produces the same read model. The second property follows from that: you can throw the view away and recompute it entirely from the events. The rebuild is not an emergency plan but a regular tool. This is exactly where the projection parts ways with the cache. You can refill a cache too, but that rebuild is a cold-start side effect whose result depends on the source at the *current* moment. Rebuilding a projection is deterministic and independent of time, because it rests on history, not on a momentary state. A caveat belongs here: this free rebuild assumes that the events are available permanently and completely – that is, a write path with event sourcing in which the event store is the source of truth. CQRS and event sourcing are two separate decisions that are often made together but do not have to be; Fowler explicitly describes CQRS independently of the form of persistence. If you run CQRS without a persistent event history and only update the read side from transient notifications, you have a projection in operation, but not the deterministic rebuild from history. The examples here assume the event store – and with it the property that separates the read model from the cache. ## The projection as a fold It becomes clearest in code. At its core, a projection is a fold – a `reduce` over the events that starts with an empty state and applies each event to the state so far. As an illustration, in TypeScript: ```ts type OrderPlaced = { type: "OrderPlaced"; orderId: string; total: number } type OrderShipped = { type: "OrderShipped"; orderId: string } type OrderCancelled = { type: "OrderCancelled"; orderId: string } type OrderEvent = OrderPlaced | OrderShipped | OrderCancelled type OrderSummary = { orderId: string total: number status: "placed" | "shipped" | "cancelled" } // pure reducer: (state, event) => state function apply(state: OrderSummary, event: OrderEvent): OrderSummary { switch (event.type) { case "OrderPlaced": return { orderId: event.orderId, total: event.total, status: "placed" } case "OrderShipped": return { ...state, status: "shipped" } case "OrderCancelled": return { ...state, status: "cancelled" } } } // the projection is a fold over the event stream function project(events: OrderEvent[]): OrderSummary { return events.reduce(apply, {} as OrderSummary) } ``` `apply` is a pure function `(state, event) => state`. No access to the clock, no network, no randomness. That is not a stylistic preference. Without this purity, the rebuild does not stay deterministic. As soon as a `Date.now()` or an external lookup sneaks into `apply`, the nice property “same events, same read model” is lost – and you have unknowingly built yourself a cache whose rebuild depends on the point in time. ## One read model per view The second key point: there is no *single* read model. There is one per query, each denormalized and tailored exactly to the view it serves. Vernon points out that read models are especially useful where the displayed data cuts across several aggregates. The read model pulls this data together in advance, so the query stays flat and cheap. A view for an order list pulls different fields than a detail view. Instead of joining and computing at runtime, the projection stores the finished values: ```ts type CustomerOrderListItem = { orderId: string customerName: string // denormalized from the customer aggregate itemCount: number // precomputed, no join at read time totalAmount: number statusLabel: string // display-ready, e.g. "Versandt" } // this projection cuts across order and customer to build one flat view function toListItem( order: OrderSummary, customerName: string, itemCount: number, ): CustomerOrderListItem { return { orderId: order.orderId, customerName, itemCount, totalAmount: order.total, statusLabel: order.status === "shipped" ? "Versandt" : "Offen", } } ``` The direction of thinking is what matters: the read model is built for the query, not the query for the read model. That is exactly what I mean in [CQRS is a domain boundary](https://www.mikebild.dev/en/blog/cqrs-is-a-domain-boundary-not-a-framework/) when I say that separating reads and writes is a statement about responsibility, not about two databases. The read side may have its own shape because it has its own job. ## The rebuild is part of the design Because the projection emerges deterministically from the events, the rebuild is trivial to express – you clear the read side and replay the events: ```ts interface ReadStore { clear(): void save(view: OrderSummary): void } interface EventStore { allEvents(): Iterable } function rebuild(events: EventStore, read: ReadStore): void { read.clear() const views = new Map() for (const event of events.allEvents()) { const current = views.get(event.orderId) ?? ({} as OrderSummary) views.set(event.orderId, apply(current, event)) } for (const view of views.values()) read.save(view) } ``` This `rebuild` is the practical litmus test. If you can write it cleanly, you have a projection. If you *cannot* write it cleanly – because state flows in from outside, because events were discarded, because `apply` is not pure – then you have a cache and should stop calling it a read model. The rebuild is also the answer to a question that comes up in projects sooner or later: what happens with a schema change on the read side? With a cache, that is a migration problem with data transfer. With a projection, it is a new projector that you run over the existing events. The new view emerges from the same source as the old one. This is the moment when the initial discipline pays off. ## The data flow in a picture One source, several view-specific projections – this is what the flow looks like: ```mermaid flowchart LR C[Command] --> W[Write Model /
    Event Store] W -->|Events| P[Projector] P -->|async · eventual| A[Read Model A
    List] P -->|async · eventual| B[Read Model B
    Detail] P -->|async · eventual| R[Read Model C
    Report] ``` The command runs against the write model and produces events. The projector subscribes to these events and uses them to update as many read models as there are views. The edges to the read models are deliberately labeled “async · eventual,” because this is where the third key point lies: consistency. ## Eventual consistency is a deliberate trade The projection runs asynchronously after the write has succeeded. Fowler states the consequence soberly: you cannot guarantee exactly *when* the read model is consistent. Shortly after the write, it is potentially stale. That is not a bug, not data loss and not corruption – it is a bounded, known delay that you accept in order to decouple the read side from the write side. The delay itself rarely causes trouble. How you deal with it does. If you expect synchronous read-after-write consistency, you build the UI so that it reads from the read model immediately after the command and are surprised that the new record is “missing.” It is not gone; the projection just has not caught up yet. That belongs in the design of the UI, not in a bug report. The second variant is more dangerous: checking command-side invariants from the read model. Greg Young is clear here – the read model must not carry a business decision that has to rely on current, consistent state. Because it can be stale, you would be deciding on stale data. Checking whether an account has sufficient funds or whether an order may still be canceled belongs on the write side, against the aggregate, not against the read view. I wrote up this division of labor in more detail in [Cleanly Separating Commands, Events and Queries](https://www.mikebild.dev/en/blog/separating-commands-events-and-queries/): a query asks a question and changes nothing; that is why it must not force a decision either. ## Projection or cache – the distinction in five points Whether a concrete read side is a projection or a cache becomes clear from five questions: - Who is the source of truth? With a projection, the event store is the source, and the read model is the authoritative read view. With a cache, the authoritative source is the database behind it. - How is it invalidated? The projection is updated event-driven, the cache through TTL or eviction. - How does the rebuild work? The projection can, by design, be recomputed deterministically from history; the cache rebuild is a cold-start side effect that depends on the current state of the source. - What shape does the view have? The projection is denormalized per view and pulled together across aggregates, the cache is usually a copy of the source record. - What about consistency? The projection is deliberately eventually consistent with a bounded delay, the cache best effort. You can argue about one or two of these points. But if the answers mostly land in the cache column, you should call the thing what it is and not hang the expectations of a read model on it. ## The three pitfalls, concretely Finally, the patterns that cause the trouble, each named in one sentence along with the countermeasure. The first is cache thinking itself: treating the read model as an optional accelerator that you pull again from the “actual” database on a miss. That actual database does not exist. Updates are event-driven, and the rebuild comes from the events. If you take this seriously, you stop looking for the source *behind* the read model. The second is the read model as the source of truth: deciding on command invariants from a potentially stale read view. The consequence is decisions based on old state. The countermeasure is discipline across the boundary between the sides – decisions go on the write side, against the aggregate. The third is the forgotten rebuild: building a projection that cannot be replayed because `apply` is not pure or events were discarded. Then the first schema migration becomes a dead end. The countermeasure is in the code above – keep the projector a pure fold over the events, and write the `rebuild` early, not only when things are on fire. ## Conclusion A read model deserves a better name than “cache,” because the name sets the expectations. If you call it a cache, you build an optional accelerator with a supposed source behind it, TTL invalidation and a rebuild that remains a side effect. If you call it a projection, you build a pure fold over an immutable event stream, tailored per view, updated event-driven and deterministically recomputable at any time. The three properties I use to pin this down are always the same: deterministically derived, rebuildable at any time, deliberately eventually consistent. If you build these three into the design, you have a read side that you can operate and migrate without breaking a sweat at every change. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-cqrs-event-sourcing.en.html - Martin Fowler, [CQRS](https://martinfowler.com/bliki/CQRS.html) – the conceptual model split and the warning to use it only locally within a context. - Martin Fowler, [Reporting Database](https://martinfowler.com/bliki/ReportingDatabase.html) – the related but narrower idea of a separate read database. - Martin Fowler, [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) – the form of persistence that makes projections so natural. - Greg Young, [CQRS Documents (2010, PDF)](https://cqrs.files.wordpress.com/2010/11/cqrs_documents.pdf) – the foundations of read models, eventual consistency and rebuild. - Vaughn Vernon, *Implementing Domain-Driven Design* (2013), chapters on architecture and CQRS; sample code in the [IDDD Samples](https://github.com/VaughnVernon/IDDD_Samples). - My own talk material “CQRS + Event Sourcing” on SlideShare – the slides from which I derive the core in trainings: reading and writing are different responsibilities. --- # Cloud Guardrails Instead of Cloud Gatekeeping URL: https://www.mikebild.dev/en/blog/cloud-guardrails/ Date: 2020-09-12 # Cloud Guardrails Instead of Cloud Gatekeeping An approval process with a three-day wait doesn’t create control. It creates shadow infrastructure. The team waiting for approval of a DynamoDB table isn’t really waiting – it finds a way around: a colleague’s private AWS account, the project lead’s credit card, the “temporary” bucket in the sandbox account that still holds production data two years later. The process that was supposed to prevent risks shifts them exactly to where nobody looks anymore: no review, no central logging, no cost control, no backups. On a project last year, I saw this up close. A central cloud team, a Jira board, every new resource a ticket. Official lead time: three days. Actual lead time with follow-up questions: a week or more. The cloud team was neither malicious nor lazy – it was simply too small for twelve product teams, and every ticket needed context that only the requesting team had. What struck me was that the actual discussion was never “allow or forbid.” It was almost always: “In which region? With which tagging? Who pays for it?” In other words, questions that can be phrased as a rule. And whatever can be phrased as a rule, a machine can enforce – without any waiting time. ## What the ticket process actually protects Before you abolish the process, it’s worth looking at which legitimate concerns it carries. On that project, there were four at the core: - Cost: nobody should accidentally start an expensive cluster with an exotic instance size. - Data sovereignty: data stays in European regions, period. - Security baselines: no public S3 bucket, no disabled CloudTrail, no wide-open security groups. - Privilege escalation: anyone who may create roles could otherwise grant themselves arbitrarily far-reaching permissions. All four concerns are real. But none of them needs a person who reads a ticket three days later. They need boundaries that apply at the moment of the API call – not at the moment of approval. The ticket process checks a declaration of intent; it never again checks what actually happens afterward. The guardrail checks every single action, every time. AWS itself now has a name for this way of thinking: Control Tower, generally available since summer 2019, literally calls its preconfigured rules “guardrails.” So the term isn’t a buzzword from conference slides; it comes from the platform’s product practice. More interesting than the name is the distinction Control Tower makes: preventive guardrails prevent an action, detective guardrails detect a deviation. This distinction carries the entire architecture. ```mermaid flowchart LR A[Team changes
    infrastructure] --> B{Preventive:
    SCP / Boundary} B -->|violates| C[API call rejected
    immediately] B -->|allowed| D[Resource
    is created] D --> E{Detective:
    AWS Config} E -->|compliant| F[Nothing happens] E -->|deviation| G[Alarm or
    auto-correction] ``` ## Hard limits: Service Control Policies The outermost guardrail is Service Control Policies in AWS Organizations. An SCP applies to entire accounts or organizational units and overrides every IAM policy in the account – not even the account administrator gets past it. That’s exactly why only the rules that are truly non-negotiable belong here. On that project, there were two: allowed regions and a short list of forbidden services. ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "DenyOutsideAllowedRegions", "Effect": "Deny", "NotAction": [ "iam:*", "organizations:*", "route53:*", "cloudfront:*", "support:*" ], "Resource": "*", "Condition": { "StringNotEquals": { "aws:RequestedRegion": ["eu-central-1", "eu-west-1"] } } }, { "Sid": "DenyUnapprovedServices", "Effect": "Deny", "Action": ["gamelift:*", "robomaker:*", "chime:*"], "Resource": "*" } ] } ``` Two details matter to me here. First, the `NotAction` exceptions: IAM, CloudFront and Route 53 are global services, and their API calls technically run through us-east-1 – if you forget them in the region lock, you lock yourself out. We learned that the hard way, luckily in a test account. Second, the nature of the list of forbidden services: it’s short and justified, not an allowlist of a hundred entries. An SCP that forbids everything except what someone once requested is just the old gatekeeping in JSON form. The guardrail marks the edge of the road, not the only permitted lane. Important for understanding: an SCP grants no permissions itself. It defines the upper limit of what IAM policies in the account can effectively allow at all. Within this limit, the teams move freely – and that’s exactly the point. ## Self-service for IAM: Permission Boundaries The most uncomfortable question on the project came from the security officer: “If developers may create their own IAM roles, can’t they give themselves any permissions they want?” Without a countermeasure: yes. Anyone with `iam:CreateRole` and `iam:AttachRolePolicy` can build a role with administrator permissions and assume it. That’s why IAM was historically the last territory of the central team – and the most common reason for waiting, because every Lambda function and every pipeline needs a role. Since 2018, there have been Permission Boundaries for this: a managed policy attached to a role as an upper limit. The effective permissions are the intersection of the boundary and the attached policies. The trick lies in self-reinforcement – the boundary only allows creating new roles if the new role carries the same boundary again: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowWorkloadServices", "Effect": "Allow", "Action": [ "s3:*", "dynamodb:*", "lambda:*", "sqs:*", "logs:*", "cloudwatch:*", "apigateway:*" ], "Resource": "*" }, { "Sid": "DenyCreateWithoutBoundary", "Effect": "Deny", "Action": ["iam:CreateRole", "iam:CreateUser"], "Resource": "*", "Condition": { "StringNotEquals": { "iam:PermissionsBoundary": "arn:aws:iam::111122223333:policy/workload-boundary" } } }, { "Sid": "DenyBoundaryTampering", "Effect": "Deny", "Action": [ "iam:DeleteRolePermissionsBoundary", "iam:DeletePolicy", "iam:CreatePolicyVersion" ], "Resource": "arn:aws:iam::111122223333:policy/workload-boundary" } ] } ``` With this, the teams could create roles for their services without anyone having to approve them – but no role could ever allow more than the `workload-boundary`. In the CDK, which we used to describe the infrastructure anyway, that’s one line per role: ```ts import * as iam from '@aws-cdk/aws-iam'; const boundary = iam.ManagedPolicy.fromManagedPolicyName( this, 'WorkloadBoundary', 'workload-boundary' ); const serviceRole = new iam.Role(this, 'OrderServiceRole', { assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'), permissionsBoundary: boundary, }); ``` That got rid of the three-day wait for “please create a role for the order service.” Not because someone approved faster, but because there was nothing left to approve: the boundary was already drawn before the request came up. ## Detect, don’t just prevent: AWS Config Preventive rules have a gap: they can only forbid what can be expressed as an IAM condition. “No S3 bucket without encryption” or “no security group with 0.0.0.0/0 on port 22” are properties of a resource, not API actions – for these, you need the second kind of guardrail. AWS Config records the state of all resources and continuously checks it against rules. On deviation: an alarm and, where it can be done safely, automatic correction. ```ts import * as config from '@aws-cdk/aws-config'; import * as budgets from '@aws-cdk/aws-budgets'; new config.ManagedRule(this, 'BucketsNotPublic', { identifier: 'S3_BUCKET_PUBLIC_READ_PROHIBITED', }); new config.ManagedRule(this, 'VolumesEncrypted', { identifier: 'ENCRYPTED_VOLUMES', }); new budgets.CfnBudget(this, 'TeamMonthlyBudget', { budget: { budgetType: 'COST', timeUnit: 'MONTHLY', budgetLimit: { amount: 500, unit: 'USD' }, }, notificationsWithSubscribers: [ { notification: { notificationType: 'ACTUAL', comparisonOperator: 'GREATER_THAN', threshold: 80, }, subscribers: [ { subscriptionType: 'EMAIL', address: 'team-orders@example.com' }, ], }, ], }); ``` For me, the budget belongs in the same category, even though it’s technically a different service. Fear of costs was the emotional core of the old approval process – and a budget alarm at 80 percent answers it better than any ticket, because it reacts to actual spending instead of estimated spending. On that project, each team got its own budget with its own notification. The discussions about costs didn’t become fewer, but they took place with numbers instead of guesses, and they took place within the team – not between the team and a gatekeeper. The second benefit of Config is less conspicuous: the history. If a security group looks different today than yesterday, Config shows when what changed – that saved us hours in more than one debugging session, quite apart from the rules. An approval process only knows what was requested; Config knows what actually happened. I have become more cautious with automatic correction. A rule that immediately removes a public bucket policy is a security gain. A rule that deletes resources at night whose tags are wrong once cost us a morning of debugging, because a legitimate prototype had disappeared. Detecting and reporting is almost always right; intervene automatically only where the correction is guaranteed not to destroy anything. ## Guardrails are code, not click configuration The point where such setups tip over, in my experience, isn’t the technology but the maintenance. An SCP that someone clicked together in the console a year ago is just as opaque as the old approval process – except that now nobody knows why port 22 is blocked and who may change that. Guardrails are infrastructure, and for infrastructure, what I already described [when reviewing infrastructure code](https://www.mikebild.dev/en/blog/infrastructure-as-code-needs-code-reviews/) applies: it should be versioned, reviewed and changed traceably. For us, that specifically means: SCPs, boundary policies and Config Rules live as code in the repository, changes go through a pull request, and the review includes someone from a product team alongside the platform team. The pull request replaces the ticket – with one crucial difference: what gets discussed is a permanent rule for everyone, not a one-off approval for one team. So the discussion is worth it, and its result keeps having an effect. I described how such rules can also be checked when synthesizing your own stacks in [Policy as Code for CDK](https://www.mikebild.dev/en/blog/policy-as-code-for-cdk/) – together, the two give you two checkpoints: one early in the build, one at the account boundary that can’t be bypassed. By the way, the pattern isn’t AWS-specific. The same thing is happening right now in the Kubernetes world with Open Policy Agent and Gatekeeper – rules as code, enforced at the admission controller instead of in a meeting. If you run both worlds, you’ll recognize the line of thinking immediately. ```mermaid flowchart TD Root[Organization Root] --> Sec[OU Security
    Logging, Audit] Root --> Work[OU Workloads] Root --> Sand[OU Sandbox] Work --> A1[Account Team Orders] Work --> A2[Account Team Billing] SCP1[SCP: EU regions,
    service blocklist] -.applies to.-> Work SCP2[SCP: additionally
    tight cost limits] -.applies to.-> Sand ``` The organizational structure itself is part of the guardrails: a sandbox OU with tight limits and a cleanup rule takes the risk out of experimenting, and a workload OU carries the binding rules. If you start with a multi-account structure today, Control Tower gives you exactly this scaffolding preconfigured – the guardrails behind it are the same SCPs and Config Rules, just already wired up. ## What’s different in the end After half a year with this setup, the cloud team’s Jira board was almost empty – not because less was happening, but because most things no longer needed an approval. The tickets that remained were the interesting ones: requests to change a guardrail. That’s exactly where human attention belongs. And the platform team suddenly had time for the work that had been left lying around before: better templates, sharper rules, a new account in an hour instead of a week. I take away a few observations. The approval process and the guardrail answer the same question – “what may happen here?” – but at different times: the process once, beforehand, based on a description; the guardrail at every action, based on reality. That makes guardrails not only faster but more honest. Second: the split into preventive and detective isn’t a subtlety but the central design decision. Everything that is strictly forbidden belongs in SCPs and boundaries; everything that concerns properties of resources belongs in Config Rules with an alarm. If you try to enforce everything preventively, you rebuild the gatekeeping in JSON. And third: shadow infrastructure isn’t a discipline problem of the teams but a symptom. It doesn’t disappear through stricter processes, but through an official path that is faster than the detour. ## Further reading - [Service Control Policies – AWS Organizations User Guide](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) - [Permissions Boundaries for IAM Entities – AWS IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) - [What Is AWS Config? – AWS Config Developer Guide](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) - [AWS Control Tower – Set up & Govern a Multi-Account AWS Environment (AWS News Blog, 2019)](https://aws.amazon.com/blogs/aws/aws-control-tower-set-up-govern-a-multi-account-aws-environment/) --- # CDK Constructs: Abstraction with Liability URL: https://www.mikebild.dev/en/blog/cdk-constructs-abstraction-with-liability/ Date: 2020-08-12 # CDK Constructs: Abstraction with Liability An abstraction you import is responsibility you hand off – that is the unspoken assumption when a team pulls its first ready-made CDK construct into its project. Three lines of code, one `cdk deploy`, and the S3 bucket, CloudFront distribution and bucket policy are in place. After all, someone else has thought through the details. I think exactly this assumption is wrong, and in both directions. If you use a construct, you don’t hand off responsibility – you import someone else’s decisions into your own CloudFormation template, onto your own AWS bill and into your own attack surface. And if you publish a construct, you haven’t simply shared code – from now on you are liable for defaults, for upgrade paths and for everything that ends up in other people’s production. A construct is abstraction with liability. That sets it apart from almost everything else I get from npm. ## Three levels, three different promises The CDK sorts its building blocks into three levels, and the liability question arises differently on each. L1 constructs (`CfnBucket`, `CfnDistribution`) are generated one-to-one mappings of the CloudFormation resources. They promise nothing except completeness: every property, no default, no opinion. L2 constructs (`s3.Bucket`, `lambda.Function`) are handwritten wrappers with an opinion – sensible defaults, convenience methods like `grantRead`, automatically wired IAM policies. Finally, L3 constructs, also called patterns in CDK parlance, wire several services together into a domain building block: “static website with a CDN”, “API with Lambda and DynamoDB”. The higher the level, the bigger the promise – and the bigger the liability. An L1 construct can hardly surprise me, because it decides nothing. An L3 construct decides almost everything, and I can’t tell from the code. That is exactly why L3 constructs are so tempting: they read like domain concepts (“a website”, “an API”) and hide the fact that underneath lies a bundle of very concrete operational decisions. What really happens only shows up in synthesis: ```mermaid flowchart LR L3[L3: StaticSite
    own pattern] --> L2[L2: s3.Bucket
    CloudFrontWebDistribution] L2 --> L1[L1: CfnBucket
    CfnDistribution] L1 --> SYNTH[cdk synth] SYNTH --> TPL[CloudFormation template
    several hundred lines] TPL --> DEPLOY[cdk deploy] DEPLOY --> RES[real resources:
    cost, permissions, attack surface] ``` The arrow on the far right is where a construct differs from a library function. A function from lodash produces an array at runtime. A construct produces a CloudFront distribution that costs money, a bucket that may or may not be public, and IAM statements that allow someone to do something. If `map` has a bug, a test fails. If a construct has a bug, a bucket lies open on the internet or a removal policy deletes production data when the stack is torn down. That’s no reason to do without abstraction – but it is a reason to treat it differently. ## A construct of my own and its uncomfortable decisions This really became clear to me when I built a small construct myself: a static website in S3, delivered via CloudFront. It was the third or fourth handwritten stack of this kind around me, always the same sixty lines, so extracting it was the obvious move. The first draft was done quickly. Things got interesting with the questions the first draft left open. ```typescript import { Construct, RemovalPolicy } from '@aws-cdk/core'; import * as s3 from '@aws-cdk/aws-s3'; import * as cloudfront from '@aws-cdk/aws-cloudfront'; import * as deployment from '@aws-cdk/aws-s3-deployment'; export interface StaticSiteProps { readonly sourcePath: string; readonly retainBucket?: boolean; } export class StaticSite extends Construct { public readonly siteBucket: s3.Bucket; public readonly distribution: cloudfront.CloudFrontWebDistribution; constructor(scope: Construct, id: string, props: StaticSiteProps) { super(scope, id); const originAccessIdentity = new cloudfront.OriginAccessIdentity( this, 'OriginAccessIdentity' ); this.siteBucket = new s3.Bucket(this, 'SiteBucket', { encryption: s3.BucketEncryption.S3_MANAGED, blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL, removalPolicy: props.retainBucket ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY, }); this.siteBucket.grantRead(originAccessIdentity); this.distribution = new cloudfront.CloudFrontWebDistribution(this, 'Distribution', { originConfigs: [ { s3OriginSource: { s3BucketSource: this.siteBucket, originAccessIdentity, }, behaviors: [{ isDefaultBehavior: true }], }, ], }); new deployment.BucketDeployment(this, 'DeploySite', { sources: [deployment.Source.asset(props.sourcePath)], destinationBucket: this.siteBucket, distribution: this.distribution, }); } } ``` Each of these lines is an operational decision I make for all future users. The bucket is not public but only reachable through the Origin Access Identity – that is the right decision, but it isn’t a given: the bare `s3.Bucket` from the CDK still sets no public access block to this day if you don’t specify one. Encryption is turned on, even though the content of a public website strictly speaking doesn’t need it – because nobody should have to discuss later why this particular bucket is unencrypted. And the removal policy defaults to `DESTROY`. I thought longest about this last default. The CDK itself retains buckets when a stack is torn down (`RETAIN`), because a bucket with content can’t simply be deleted and because data loss is the most expensive of all errors. For a website construct whose bucket content is regenerated from the build on every deployment, however, `RETAIN` is the wrong protection: it leaves an orphaned bucket behind for every test stack torn down, and after three months nobody knows which of them can go. So `DESTROY` as the default and `retainBucket` as the way out for cases where the bucket does contain more than build artifacts. Maybe that’s the wrong trade-off – but it now sits in one line of interface definition and can therefore be discussed. Before, it was hidden, unspoken, in sixty lines of copied stack code. The two `public readonly` fields are just as deliberate. A construct that hides its inner resources forces its users to fork at the first special case. If you need to get at the `CfnDistribution`, you can reach it via `this.distribution.node.defaultChild` and use `addPropertyOverride` to override anything my abstraction didn’t anticipate: ```typescript const cfnDistribution = site.distribution.node .defaultChild as cloudfront.CfnDistribution; cfnDistribution.addPropertyOverride( 'DistributionConfig.ViewerCertificate.MinimumProtocolVersion', 'TLSv1.2_2019' ); ``` These escape hatches are not a blemish on the abstraction but part of the contract. In infrastructure, an abstraction without a way out is a dead end, and you only ever notice dead ends once you’re already standing in one. ## cdk synth is the test of truth For the other side of liability – the consumer’s – there is a tool I consider more important than any documentation: synthesis. `cdk synth` writes out the CloudFormation template that results from the whole construct tree. The template doesn’t lie. It contains every resource, every policy, every default that any construct has set anywhere. ```bash npm install @aws-cdk/aws-s3@1.57.0 @aws-cdk/aws-cloudfront@1.57.0 cdk synth StaticSiteStack > synthesized.yaml # what did the abstraction actually decide for me? grep -A 6 'PublicAccessBlockConfiguration' synthesized.yaml grep -B 2 'DeletionPolicy' synthesized.yaml # and before every deployment: what changes against reality? cdk diff StaticSiteStack ``` Before I use someone else’s construct, I build a minimal example, synthesize and read. Not the whole template line by line – but specifically the places where other people’s defaults become expensive or dangerous. That takes half an hour and has paid off every time so far: once I found a CloudFront price class this way that delivered worldwide where Europe would have been enough; another time a log configuration that was simply missing, which would only have been noticed at the first incident. A pattern with three lines of application code easily produces several hundred lines of template, and somewhere in there are the answers to the questions the README doesn’t answer: - Which IAM statements are created, and do they contain wildcards I didn’t order? - Which resources cost money continuously, even when nobody uses the system? - What is publicly reachable, what is encrypted, what has which `DeletionPolicy`? - Which properties can I change through the interface – and for which do I need the escape hatch on day one? This spring, AWS launched its own library of such patterns with the Solutions Constructs: vetted two-service combinations such as CloudFront in front of API Gateway in front of Lambda, with defaults along the Well-Architected Framework. I have read some of them, used a few, and find the source code especially instructive – there you see how many lines of default logic it takes for “CloudFront plus S3” to be wired really sensibly, including the details that are regularly missing from handwritten stacks. That is exactly the value of someone else’s L3 abstraction: not that I no longer need to know anything, but that someone has already made and written down the decisions I can hold my own up against. I already looked at how such checks can be automated instead of depending on discipline in [Policy as Code for CDK](https://www.mikebild.dev/en/blog/policy-as-code-for-cdk/) – for me, synthesis and rule checking now belong together. ## What the author owes That leaves the question of what you take on when you publish yourself. After half a year with my own construct and quite a few others I’ve read, I have a provisional list, and it is longer than I realized when I extracted the first sixty lines. First there are the defaults, about which everything has already been said above – with the addition that a published default is practically impossible to change. If you tighten it, you break existing deployments; if you loosen it, you make existing users less secure without them noticing. A default is a promise with a very long term. Then the upgrade paths. The CDK currently ships a new version almost weekly, we’re at 1.5x, and modules like CloudFront still carry the experimental stamp, so they may change in minor releases. A construct I publish spans this movement: my users raise their CDK version and expect my construct to come along. Peer dependencies on the right `@aws-cdk` packages, prompt releases after upstream changes, a changelog that mentions template changes – that is not a bonus, that is half the work. And because the CDK also generates Python, Java and .NET bindings via jsii, the shape of the API alone (no TypeScript specialties that jsii can’t represent) decides whom I can reach as users at all. Then there are tests, and on the right level. Unit tests against your own TypeScript logic check only half the truth; what I’m liable for is the template. With `@aws-cdk/assert`, you can pin down both – individual assertions (`expect(stack).to(haveResource('AWS::S3::Bucket', { PublicAccessBlockConfiguration: … }))`) for the decisions that must never flip, and a snapshot of the entire synthesized template so that every change in the output becomes visible in review rather than at the user’s end. Since I started doing this, I’ve caught two upstream changes before they reached a release – both would have changed the template without a single line of my code changing. And finally the template output itself. Logical IDs in the template are derived from the construct path; if you rename or move children while refactoring your construct, you change the IDs – and CloudFormation then replaces resources instead of updating them. For a CloudFront distribution that means half an hour of waiting; for a bucket with data, an incident. That’s why for me `cdk diff` against a deployed example stack comes before every release of the construct, for the same reason it comes before every deployment. Since July, CDK Pipelines (Developer Preview) has offered a building block that pulls such checks into a self-mutating deployment pipeline – still fresh, but the direction is right: delivering a construct is infrastructure too and wants to be treated as such. ## Bottom line A little over a year ago, I [wrote about what changes when infrastructure becomes a programming language](https://www.mikebild.dev/en/blog/cdk-early-days-infrastructure-in-a-programming-language/). Constructs are the continuation of that: if infrastructure is code, it also takes on the properties of code – reuse, packaging, versioning. Only the cost of errors remains that of infrastructure. That’s why I think both comfortable attitudes are wrong. “I write everything myself, then I know what’s in it” doesn’t scale and reproduces the same forgotten details in every stack. “I take the ready-made pattern, then I don’t have to understand it” mistakes abstraction for absolution. What works for me lies in between: L3 abstractions, yes, including your own – but read before use, synthesized before trust, and, when publishing, with the awareness that from now on you share in decisions about other people’s production environments. A construct is not a snippet. It is a contract about defaults, ways out and upgrade paths, and `cdk synth` is the document in which this contract is written in black and white. ## Further reading - AWS Solutions Constructs on GitHub: https://github.com/awslabs/aws-solutions-constructs - AWS CDK on GitHub: https://github.com/aws/aws-cdk - Constructs in the CDK Developer Guide: https://docs.aws.amazon.com/cdk/latest/guide/constructs.html - Announcement of the AWS Solutions Constructs (AWS blog): https://aws.amazon.com/blogs/aws/aws-solutions-constructs-a-library-of-architecture-patterns-for-the-aws-cdk/ - CDK Pipelines Developer Preview (AWS blog): https://aws.amazon.com/blogs/developer/cdk-pipelines-continuous-delivery-for-aws-cdk-applications/ --- # Bounded Contexts Before the Service Split URL: https://www.mikebild.dev/en/blog/bounded-contexts-before-the-service-split/ Date: 2020-07-24 # Bounded Contexts Before the Service Split If you fix the number of services before the domain boundaries are settled, you do not remove coupling – you distribute it over the network. The split then separates code, but not responsibilities: a change to a single term still runs through three systems, only now with HTTP in between and three teams that have to coordinate. The boundary that is missing beforehand is not a technical one. It runs where a word stops meaning the same thing. The architecture emerges at the language boundaries and at the translations between them. :::relationship{title="Domain boundaries before technical splits" role="primary" preferredPattern="architecture-map"} - Subdomain · describes a domain problem space - Bounded context · gives terms and rules an unambiguous scope - Model · implements the language within this boundary - Context map · names dependencies and influence between contexts - Anti-Corruption Layer · translates a foreign model into your own language - Service · can run a boundary, but does not automatically define it ::: This keeps boxes from becoming an end in themselves. What matters is where meaning changes and who is responsible for that translation. ## Why the order decides the outcome The question monolith migrations usually start with is: “How many microservices do we break the monolith into?” It is already the wrong question. The number is a result, not a target. What needs clarifying is where the domain boundaries lie – and whether you can name a separate, internally consistent language for each boundary. How many services that turns into becomes clear afterwards. The reason is economic. A service split is cheap to draw and expensive to correct once teams, deployments and databases depend on it. A domain boundary, on the other hand, can be moved on the whiteboard as long as it is still a model and not infrastructure. That is why I invest the first week of such a project in language and not yet in infrastructure and deployment diagrams. The business result is measurable: shorter change cycles, because a change stays within one context; less friction between teams, because nobody trips over shared tables; higher quality, because the model reflects the domain instead of an accidental technical structure. ## The bounded context is a language boundary Eric Evans coined the term in 2003 in *Domain-Driven Design*, and Martin Fowler summed it up in his bliki: a bounded context is the area in which exactly one model and exactly one ubiquitous language apply. Within this boundary, every word means exactly one thing. Across the boundary, the same word may mean something else – that is where the real gain lies. An example from retail: the word “Product.” In sales, a Product is a thing with a price, a description and availability. In the warehouse, the same Product is an SKU with stock, a storage location and a reorder point. In accounting, it is a line item with a tax rate and a revenue account. Three contexts, three legitimate meanings. The classic mistake is to try to build a single canonical `Product` object out of this that does justice to all three. The result is a class with forty fields, of which each context ignores ten – and every change affects all three teams. Fowler names not technology but “human culture” – language and organization – as the dominant factor in drawing these boundaries. This is where Conway’s Law comes in: context boundaries and team boundaries influence each other. If I draw a clean boundary but two teams have to work on it together, I am drawing it in the wrong place. In practice, I test a suspected boundary with two questions. First: can I say a sentence in this context that a domain expert from the neighboring context no longer understands unambiguously without translation? If so, these are two languages and therefore two contexts. Second: is there a rule that applies exactly here and not next door – for example “a Product without stock is still visible in sales, but does not exist in the warehouse”? Such rule breaks are the most reliable boundary markers I know. They come up in conversations with domain experts, not in the class diagram, and that is exactly why I only find them if I listen first instead of modeling. ## Sort subdomains, implement bounded contexts Before I draw boundaries, I sort the problem space. Strategic DDD separates problem space and solution space. The subdomains live in the problem space, and I categorize them into three classes: The core domain is what a company does better than its competitors – that is where the best team and most of the modeling work belong. Supporting subdomains are necessary, but not a differentiator; solid standard work is enough here. Generic subdomains are solved problems such as authentication, accounting or notifications; I buy or standardize them instead of building them myself. This classification is a business decision, not a technical one. It answers the question of where effort pays off. Bounded contexts are then the answer in the solution space: ideally, one subdomain corresponds to exactly one bounded context. In reality, they rarely match – a system that grew historically often cuts across. But the core/supporting/generic classification tells me at which boundary I need precision and where pragmatism is enough. ## The edges are the architecture, not the boxes Isolated models are not a system yet. The system emerges from the relationships between the contexts, and naming these relationships is the core of the work – context mapping. Without a context map, you get exactly what Evans calls a “distributed Big Ball of Mud”: many services that all depend on each other, without anyone controlling the translation. I draw a context map as boxes with edges. The boxes are the contexts, each with its own language. The edges are what is interesting: who is upstream (determines the model), who is downstream (has to adapt)? Who translates, who publishes? ```mermaid graph LR subgraph U["Upstream"] INV["Inventory
    Product = SKU + stock"] end subgraph D["Downstream"] SAL["Sales
    Product = price + description"] BIL["Billing
    Product = tax + revenue account"] end INV -->|"OHS / PL"| SAL SAL -->|"ACL"| BIL INV -.->|"SK shared kernel"| SAL ``` The labels carry the statement. An Open Host Service with a Published Language (OHS/PL) on the upstream side means: Inventory offers a stable, documented interface that many can connect to. An Anti-Corruption Layer (ACL) on the downstream side means: Billing actively protects its model from foreign terms. A Shared Kernel (SK) means: two contexts deliberately share a small common model – and with it, coupling. The decisive point: the later service split is laid *on top of* this context map. First it exists, then I decide which context becomes one service, which becomes two, and which stay deployed together. The bounded context is the model boundary, the service the deployment unit. Vladik Khononov put it aptly in 2018: bounded contexts are not microservices. A service can be part of a context, and a context can span several services. ## The pattern that saves the most friction: the Anti-Corruption Layer Of all context mapping patterns, the Anti-Corruption Layer is the one whose absence I most often see paid for dearly. As soon as a cleanly modeled context borders on a legacy or third-party system, it needs a translation layer. Without it, the foreign model – often a bad one – seeps into my core. What starts as “we’ll adapt briefly” (Conformist) silently becomes the permanent solution. Concretely: my Sales context knows a clean `Product`. The Inventory system speaks in `LegacyInventoryResponse` with `sku` and `price_cents`. I never let these foreign DTOs into my domain model. An adapter translates in exactly one place: ```java // Downstream context: Sales interface CatalogPort { Product findById(ProductId id); } // ACL: isolates the upstream "Inventory" model. // Only this class knows the foreign DTOs; the domain never does. class InventoryAntiCorruptionLayer implements CatalogPort { private final LegacyInventoryClient legacyClient; @Override public Product findById(ProductId id) { LegacyInventoryResponse raw = legacyClient.get(id.value()); return new Product( new ProductId(raw.sku), Money.of(raw.price_cents) // translate cents into the domain type ); } } ``` The gain is not cosmetic. When the Inventory team changes its format, exactly one class changes. My core stays stable, my tests stay green, and the translation is documented instead of scattered across the code. That is the difference between a boundary that holds and one that leaks. The flip side applies to the Shared Kernel: I only use it when two teams work in a real partnership and deliberately want the coupling. A shared model means shared change – every adjustment forces both teams to coordinate. Misused as the default, the Shared Kernel becomes a brake. When in doubt, I give each context its own model and connect them through a Published Language. Between Conformist and ACL there is a cost trade-off, and it should be spelled out. Conformist means: we take over the foreign model one to one and save ourselves the translation. That is legitimate when the upstream is stable and its model fits your own – for example with a generic subdomain that is only integrated anyway. But as soon as your own core is affected or the upstream has a weak model, the translation layer you saved becomes a deferred debt. The ACL costs its setup once and pays back with every foreign change. I do this calculation explicitly instead of leaving the decision to the chance of the first integration sprint. In practice, I write it down as a short decision: which foreign model are we coupling to, how stable is it, what would a change cost us? Once you have answered this question deliberately, you no longer make it by accident under time pressure. ## Recording boundaries declaratively So that the context map does not rot as a photo of the whiteboard, I record it in a versionable form. With Context Mapper and its DSL, I write the relationships as text that sits in the repository next to the code and is versioned with every change: ```text ContextMap ShopMap { contains Sales, Inventory, Billing Inventory -> Sales : Customer-Supplier { implementationTechnology = "REST" downstreamRights = INFLUENCER exposedAggregates = Product } Sales -> Billing : Conformist { implementationTechnology = "Messaging" } } ``` This is not an end in itself. The value lies in the fact that the relationship – Customer-Supplier, who is upstream, which aggregate is exposed – is documented in a verifiable way. A new developer can read in one place how the contexts fit together instead of reconstructing it from call chains. I have discussions about boundaries on the diff of this file, not on the next wiped-clean whiteboard. ## How I proceed in practice My process is deliberately unspectacular and needs no toolchain. I get the domain experts and one or two developers into a room and let them tell the business flow – for larger domains, I use Event Storming as a discovery technique to get the events onto the wall. While doing so, I listen for breaks in language: as soon as the same word means two different things, I have probably found a context boundary. Then I name the contexts, classify them into core, supporting and generic, and draw the edges with their patterns. I immediately mirror every suspected boundary back to the domain experts: I retell the flow in their language and watch where they correct me. These corrections are worth their weight in gold, because they show me the places where my model and the domain as actually practiced still diverge. Only after that – and often only weeks later – do we talk about services, repositories and deployment. To technology-driven teams, this approach feels slow at first. It is the opposite. The weeks I invest in language up front I save three times over later, because I no longer have to correct boundaries through a production system. Simple and elegant here means: few, well-founded boundaries instead of many accidental ones. ## Conclusion The common thread is an order. First the language: where does which model apply, where does a term break? That is the bounded context. Then the relationships: who is upstream, who translates, where do I protect my core with an Anti-Corruption Layer, where do I couple deliberately through a Shared Kernel? That is the context map. And only at the very end the deployment unit: which context becomes a microservice? If you stick to this order, you can align services with domain boundaries instead of cutting them along technical layers. If you reverse it and count services before you understand the language, you risk a distributed Big Ball of Mud with more network in between. First comes the model boundary, then the decision about operations. Not every bounded context has to become its own service. ## Further reading - [Martin Fowler – BoundedContext](https://martinfowler.com/bliki/BoundedContext.html) - [Martin Fowler – UbiquitousLanguage](https://martinfowler.com/bliki/UbiquitousLanguage.html) - [Martin Fowler – Conway's Law](https://martinfowler.com/bliki/ConwaysLaw.html) - [Vladik Khononov – Bounded Contexts are NOT Microservices](https://vladikk.com/2018/01/21/bounded-contexts-vs-microservices/) - [Context Mapper – Context Map](https://contextmapper.org/docs/context-map/) --- # Functional Patterns in Python: Comprehensions, itertools and functools URL: https://www.mikebild.dev/en/blog/functional-patterns-in-python/ Date: 2020-07-15 ```python from itertools import groupby from operator import itemgetter records = [ {"team": "a", "pts": 3}, {"team": "b", "pts": 5}, {"team": "a", "pts": 2}, ] totals = { team: sum(r["pts"] for r in group) for team, group in groupby(records, key=itemgetter("team")) } # {"a": 2, "b": 5} – erwartet war {"a": 5, "b": 5} ``` No traceback, no warning, just a wrong result. `groupby` only groups *consecutive* equal keys. Without sorting first, team `a` falls apart into two groups, and the second one overwrites the first in the dictionary. If you know `GROUP BY` from SQL, you expect the exact opposite here. That is how Python’s functional tools behave across the board: they carry familiar names from Java, C# or SQL, but follow their own rules. If you want to work functionally in Python, you reach for `map` and `filter` less often and for comprehensions, `functools` and `itertools` more often. Together these three cover almost everything you know from functional programming – in a style that is typical for Python. I go through them in order: first comprehensions as the idiomatic replacement for `map`/`filter`, then the lazy combinators from `itertools`, then the helpers from `functools` – above all `lru_cache` – and finally the leaning toward immutability. In several places I show not only how it works, but where I regularly see mistakes in practice. If you have already looked at [advanced Python](https://www.mikebild.dev/en/blog/advanced-python-decorators-magic-methods-generators/), you know generators and decorators – here we build on that. ## Comprehensions instead of map and filter Let us start with a concrete example. I want the squares of all even numbers from 0 to 9. In the `map`/`filter` version it reads like this: ```python nums = range(10) # map/filter with lambdas – works, but reads inside out squares_even = list(map(lambda n: n * n, filter(lambda n: n % 2 == 0, nums))) ``` That works, but you read it from the inside out: first `filter`, then `map`, and the two `lambda` expressions sit between the arguments. The comprehension turns this around and puts the transformation in front and the condition at the end: ```python nums = range(10) # comprehension – transform first, condition last, one line squares_even = [n * n for n in nums if n % 2 == 0] ``` This is the form that dominates in Python code, and the reason is simply readability. Idiomatic Python code usually prefers a comprehension over `map` or `filter` with `lambda`; PEP 8, however, does not prescribe this particular choice. Comprehensions come in three flavors – for lists, dictionaries and sets: ```python words = ["alpha", "beta", "gamma"] # list, dict and set comprehensions lengths = [len(w) for w in words] by_length = {w: len(w) for w in words} initials = {w[0] for w in words} ``` One detail is easy to miss: since Python 3, a comprehension has its own namespace. The loop variable `w` stays inside the comprehension and no longer leaks into the surrounding code – an old stumbling block from Python 2 days that you no longer need to fear. Does that mean `map` and `filter` are superfluous? No. They are still idiomatic when a named function already exists. `map(str.upper, words)` is clearer than `[w.upper() for w in words]` – there is no `lambda` here, just a ready-made function, and the expression stays short: ```python words = ["alpha", "beta", "gamma"] # map shines with an existing named function – no lambda noise shouted = list(map(str.upper, words)) ``` So the `lambda` works as a signal: if there is one in `map` or `filter`, a comprehension would be the better choice. A named function in `map`, on the other hand, is perfectly fine. A related detail regularly causes confusion: the difference between the filter at the end and a conditional expression in front. Both use the keyword `if`, but they do opposite things: ```python nums = range(10) # if at the end filters elements out – only evens survive evens = [n for n in nums if n % 2 == 0] # if ... else at the front transforms – all elements stay masked = [n if n % 2 == 0 else 0 for n in nums] ``` The `if` at the end selects and drops the odd numbers; the `if ... else` in front keeps every element and only replaces the odd ones with `0`. Two constructs that are easy to mix up and produce completely different results – I trip over this regularly in code reviews. ## Lazy evaluation with map, filter and generator expressions One point is often overlooked: in Python 3, `map` and `filter` no longer return lists, but iterators. They compute on demand – values are only produced when you ask for them. That is exactly why the examples above wrap them in `list(...)`; otherwise you would just get the iterator object. A comprehension, by contrast, materializes immediately: it builds the complete list in memory. For small amounts of data that does not matter; for large ones it can get expensive. This is where the generator expression comes in – syntactically almost identical to the list comprehension, just with parentheses instead of square brackets: ```python # list comprehension: builds the whole list in memory total_eager = sum([n * n for n in range(1_000_000)]) # generator expression: yields one value at a time, constant memory total_lazy = sum(n * n for n in range(1_000_000)) ``` Both return the same result, but the second version does not materialize a complete result list. It produces its values on demand; upstream data sources or individual operations can of course still take up memory. When I only iterate over an expression once anyway – say as an argument to `sum`, `any` or `max` – the generator expression is usually the right choice. A word of caution: a generator is exhausted after one pass. If you want to iterate over the same generator twice, the second pass returns an empty result. For repeated access you need a materialized list – or you design the pipeline so that one pass is enough. So we have three ways to process a sequence, and each has its place: - Comprehension – readable, materializes immediately, its own namespace, filter and transformation in one expression. - `map`/`filter` – lazy, ideal in combination with an existing named function, less readable with `lambda`. - `itertools` – lazy combinators for long or infinite streams, constant memory, composes well. Let us take a closer look at the third one now. ## itertools: lazy combinators for streams `itertools` is a collection of building blocks that all work lazily. They produce iterators, not lists, and can be plugged together into pipelines without intermediate results piling up in memory. A few that I use almost daily: ```python from itertools import chain, islice, count # count: infinite counter, here 1, 3, 5, 7, 9 first_five_odds = list(islice(count(1, 2), 5)) # chain.from_iterable: flatten a list of lists lazily flat = list(chain.from_iterable([[1, 2], [3, 4], [5, 6]])) ``` Besides `chain`, `islice` and `count`, I often reach for `takewhile` and `dropwhile`. Both take a predicate and a stream: `takewhile` yields values as long as the condition holds and stops for good at the first `False`; `dropwhile` skips the leading block for which the predicate is true and returns everything from there on. On a sorted stream, this lets you cut out a range without checking the whole rest. `count(1, 2)` is an infinite counter – without `islice` it would never stop. `islice` cuts out the first five values and stops evaluation exactly there. That is the pattern behind lazy pipelines: you describe a potentially infinite source and limit it only at the end. `chain.from_iterable`, in turn, flattens nested sequences without copying the sublists together first. The building block that triggers the most aha moments is `groupby`. It lets you group records by a key and aggregate them: ```python from itertools import groupby from operator import itemgetter records = [ {"team": "a", "pts": 3}, {"team": "a", "pts": 2}, {"team": "b", "pts": 5}, ] # IMPORTANT: sort by the same key before grouping records.sort(key=itemgetter("team")) totals = { team: sum(r["pts"] for r in group) for team, group in groupby(records, key=itemgetter("team")) } # {"a": 5, "b": 5} ``` This brings us back to the example from the beginning: if the input is not sorted by the same key first, you get several groups for the same key, and the result is silently wrong. The `records.sort(...)` before `groupby` is not optional; it is mandatory – it is the one line that makes the difference between `{"a": 5, "b": 5}` and `{"a": 2, "b": 5}`. A second point: the groups that `groupby` returns are transient iterators. As soon as you move on in the outer loop, the previous group becomes invalid. If you want to keep a group beyond the iteration, you have to materialize it with `list(group)` before moving on. In the example above that is no problem, because `sum(...)` evaluates the group directly in the same step. Before we get to `functools`, a look at the big picture. The following sketch shows how raw data moves through such a pipeline – from the eagerly materializing comprehension through lazy generator expressions and `itertools` combinators to the final fold into a single value. ```mermaid graph LR A[Raw data] --> B[Comprehension
    eager, materialised] B --> C[Generator expr
    lazy, constant memory] C --> D[itertools
    chain / islice / groupby] D --> E[reduce / sum / prod
    fold to a value] E --> F[Result] ``` ## functools: partial, reduce and lru_cache `functools` bundles tools that act on functions themselves. Three of them are central to functional patterns. `partial` binds some of a function’s arguments in advance and returns a new callable function. That is handy for specializing general functions: ```python from functools import partial def power(base, exponent): return base ** exponent # fix the exponent, get a specialised function square = partial(power, exponent=2) cube = partial(power, exponent=3) print(square(5)) # 25 print(cube(5)) # 125 ``` `reduce` folds a sequence into a single value – the classic of functional programming. In Python 3, `reduce` is deliberately no longer a builtin but was moved to `functools`. That is a clear signal: use it sparingly. ```python from functools import reduce flat = [1, 2, 3, 4] # reduce works, but a built-in is almost always clearer total = reduce(lambda acc, x: acc + x, flat, 0) # 10 better = sum(flat) # same result, obvious intent ``` One detail of `reduce` is easy to overlook: the third argument. It is the initial value of the fold and at the same time decides what happens with an empty sequence. With an initial value of `0`, `reduce` returns exactly that `0` for empty input; without an initial value, `reduce` raises a `TypeError` on an empty sequence instead. If you leave out the initial value, you buy yourself a special case that is easy to forget in tests – and that then strikes precisely in the edge case. This is where the most common `functools` mistake I see shows up: `reduce` gets overused. Nested `reduce` lambdas are hard to read, and for most cases there are clearer alternatives – `sum` for sums, `math.prod` for products (since Python 3.8), a comprehension or simply a loop. `reduce` is justified when the fold is genuinely non-trivial and no specialized function exists. In all other cases, the more explicit way wins. For me, the star of `functools` is `lru_cache`. The decorator memoizes a function’s results – the same arguments return the stored result instead of computing it again. The classic textbook example is the naive recursive Fibonacci function, whose runtime explodes exponentially without memoization: ```python from functools import lru_cache @lru_cache(maxsize=None) def fib(n: int) -> int: return n if n < 2 else fib(n - 1) + fib(n - 2) print(fib(50)) # 12586269025 – instant instead of minutes print(fib.cache_info()) # CacheInfo(hits=48, misses=51, maxsize=None, currsize=51) ``` With `lru_cache`, every Fibonacci value is computed exactly once – the complexity drops from exponential to linear. `cache_info()` gives insight into hits and misses, `cache_clear()` empties the cache. A note on style: I consistently write `@lru_cache(maxsize=None)` with parentheses. That is unambiguous across all versions and saves discussions about which Python version allows the call without parentheses. There are two conditions you need to know. First: the arguments must be hashable – lists or dictionaries as parameters do not work, and tuples only if their elements are hashable too. Second: `lru_cache` fits when the result depends only on those arguments and the returned object can safely be reused. With side effects or mutable external state, the cache easily returns wrong results. And `maxsize=None` means an unbounded cache – with a great many different arguments, memory usage can grow without limit. For such cases you set a concrete `maxsize`. `functools` offers more than fits into one article – for example `singledispatch`, which lets a function resolve differently depending on the type of its first argument, or `cmp_to_key`, which turns an old comparison function into a `key` for `sorted`. For functional patterns in the narrower sense, though, `partial`, `reduce` and `lru_cache` are the three I reach for most often in practice. ## The leaning toward immutability Functional work and immutability go together. Python offers two immutable containers that help here: `tuple` for ordered sequences and `frozenset` for sets. Both are hashable as long as their elements are hashable, and can then be used as dictionary keys or as elements of a set – something you cannot do with `list` or `set`: ```python # immutable, hashable – usable as dict keys or set members point = (3, 4) allowed = frozenset({"read", "write"}) permissions = { frozenset({"read"}): "viewer", frozenset({"read", "write"}): "editor", } print(permissions[allowed]) # editor ``` The advantage is not just hashability. Immutable data cannot change unnoticed while you send it through a pipeline. That is exactly the foundation of side-effect-free work: a function takes data in, returns new data and leaves the input untouched. Especially in larger systems, this separation makes transitions traceable. That leads directly to the last pitfall I see often: side effects in comprehensions. A comprehension is supposed to produce values, not call `print`, append to a list or change state: ```python # don't do this: a comprehension used only for side effects [print(w) for w in words] # builds a useless list of None values # do this instead for w in words: print(w) ``` The first version builds a list full of `None` values on the side that nobody needs. It misuses the comprehension for something the normal loop is there for. Comprehensions are meant for transformations – if no value is produced, the code belongs in a loop. ## Making the right choice What matters is less knowing every tool than reaching for the right one at the right moment. The following decision tree sums up how I weigh things in practice. ```mermaid graph TD A[Sequence to process] --> B{Build a new container?} B -->|Yes| C[Comprehension
    list / dict / set] B -->|No| D{Transform with a
    named function?} D -->|Yes| E[map] D -->|No| F{Large or infinite,
    save memory?} F -->|Yes| G[Generator expr
    or itertools] F -->|No| H{Fold to one value?} H -->|Yes| I[sum / prod / reduce] ``` The thread running through all of this: Python provides the functional tools, but expects you to use them in its own idiom. Comprehensions come before `map`/`filter` with `lambda` because they read better. Generator expressions and `itertools` step in when data gets large or streams are infinite – lazy and easy on memory. `functools` contributes `partial` for specialization, `reduce` for the rare genuine folds and `lru_cache` for memoizing pure functions. And the immutable containers `tuple` and `frozenset` keep the whole thing free of side effects. The pitfalls I have shown are all of the same kind: `reduce` where `sum` would have been enough; `groupby` without sorting first; side effects in a comprehension. They do not come from missing knowledge, but from the habit of using a tool beyond its purpose. If you know these three groups of tools and use them with discipline, you write Python that stays compact and is still easy to read – and that is exactly the standard the language sets for functional code. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-python.en.html - Repository `introduction-python` – the examples from this article to try out. - [functools – Higher-order functions (Python 3.8)](https://docs.python.org/3.8/library/functools.html) - [itertools – Functions creating iterators (Python 3.8)](https://docs.python.org/3.8/library/itertools.html) - [List Comprehensions – Python Tutorial (3.8)](https://docs.python.org/3.8/tutorial/datastructures.html#list-comprehensions) - [map and filter – Built-in Functions (Python 3.8)](https://docs.python.org/3.8/library/functions.html#map) --- # JSX Precisely: The Rules Behind the Markup URL: https://www.mikebild.dev/en/blog/jsx-precisely-the-rules-behind-the-markup/ Date: 2020-06-24 # JSX Precisely: The Rules Behind the Markup JSX isn’t a template language and it isn’t an HTML variant that somehow tolerates JavaScript. It’s a notation for function calls: every element you write is translated into a call before execution, and that call returns an ordinary JavaScript object. **Editorial note (July 2026):** The main text explains the classic JSX transform, which was the published state in June 2020. Since React 17, the automatic transform can use functions from `react/jsx-runtime`; that doesn’t change the mental model. How React later reconciles the resulting elements is covered in the article published afterward, [How React Renders and Updates the Tree](https://www.mikebild.dev/en/blog/how-react-renders-and-updates-the-tree/). The React overview had a single sentence on this – looks like HTML, but is JavaScript. The sentence is true and still prevents none of the mistakes that happen in everyday work: reserved attribute names, statements in curly braces, a lonely `0` in the UI, keys from array indexes. So here are the rules in order, each with a tiny example and, where it matters, with the mistake you make if you don’t know the rule. ## What the compiler really turns it into JSX isn’t a JavaScript language feature. No browser understands it. Before the code runs, a build step like Babel translates every JSX element into a normal function call. This one fact explains almost all the rules that follow. As of June 2020, the target of this translation is `React.createElement`. The markup becomes a call, and the call becomes a plain object. ```jsx const el = ; ``` becomes, roughly: ```js const el = React.createElement( "button", { className: "primary", onClick: handleClick }, "Save", ); ``` The returned object only describes what should be rendered – it’s not a DOM node, nothing happens in the browser yet. React later takes this object and creates or updates the real DOM from it. Such a description object is called a React element. With that in mind, it becomes clear why a typo in JSX often shows up as a perfectly normal JavaScript error: in the end, it is a function call. ## Expression, not statement The most important rule for the content of curly braces is: between `{` and `}` there’s an **expression**, not a **statement**. An expression is something that produces a value – `user.name`, `a + b`, `price > 0 ? "ok" : "no"`, a function call. A statement is something that does something but doesn’t yield a value – `if`, `for`, `while`, `switch`. Statements aren’t allowed inside the braces. ```jsx // works – an expression

    {user ? user.name : "Guest"}

    // does not work – if is a statement

    {if (user) { user.name }}

    ``` That’s why in JSX you reach so often for the ternary operator `? :` and the logical `&&`: they’re the expression variants of `if`. If you need a real branch with several arms, you pull it in front of the `return` and work there with a perfectly normal `if`: ```jsx function Status({ status }) { let text; if (status === "open") text = "Open"; else if (status === "paid") text = "Paid"; else text = "Unknown"; return {text}; } ``` That isn’t a detour. It’s the clean separation: logic at the top, presentation at the bottom. A common beginner reflex is to nest ever more complex ternaries until nobody reads them anymore. As soon as you reach two levels, the decision belongs at the top. ## Attributes are props, and they’re named differently than in HTML JSX attributes look like HTML attributes but are the properties of the created object – that is, props. Because the target language is JavaScript and not HTML, they follow JavaScript’s rules, and in a few places that visibly differs from HTML. Two names are reserved, because `class` and `for` are keywords in JavaScript. That’s why the class attribute is called `className` and the label attribute `htmlFor`: ```jsx ``` All multi-word HTML attributes are written in camelCase: `tabindex` becomes `tabIndex`, `readonly` becomes `readOnly`, `maxlength` becomes `maxLength`. Event handlers are called `onClick`, `onChange`, `onSubmit` – with a capital C in the middle – and get a function, not a string: ```jsx // correct – a function reference // wrong – calls handleSave IMMEDIATELY on render and passes the return value ``` The second case is one of the most common beginner mistakes. `onClick={handleSave()}` runs `handleSave` during rendering and attaches its result to the handler. If you want to pass arguments, you wrap the call in an arrow function: `onClick={() => handleSave(id)}`. You give values in curly braces, fixed strings in quotation marks. An attribute without a value is implicitly `true`: ```jsx // disabled is equivalent to disabled={true} ``` ## How values in content are rendered – and what disappears What React makes of an expression in the content depends on the type of the value, and a whole series of small surprises lurk here. Strings and numbers are output as text. Arrays are rendered element by element. But `null`, `undefined`, `true` and `false` render **nothing** – they disappear without a trace. That’s exactly what makes conditional rendering possible in the first place. ```jsx
    {message} {/* string or number -> gets displayed */} {null} {/* nothing */} {isAdmin && } {/* Panel only when isAdmin is true */}
    ``` A classic mistake lies in the `&&`. It renders the right-hand element only if the left side is truthy – but it returns the left side if it’s falsy. With booleans this is harmless, because `false` disappears. With a number, it isn’t: ```jsx // pitfall: if count is 0, a 0 appears in the UI, not nothing {count && } // correct: convert to a boolean first {count > 0 && } ``` The `0` simply isn’t `false` but a number, and numbers get rendered. If you’ve ever hunted for a lonely `0` in your UI, you know this mistake. The rule behind it is simple: in front of a `&&`, it’s best to have a real boolean, not a value that happens to be falsy. ## One element, one root node – and fragments Because a JSX expression ultimately produces a single object, a component has to return exactly one root element. Two elements side by side without wrapping are a syntax error. You could wrap everything in a `
    `, but that creates an additional, often unwanted node in the DOM. That’s what the fragment is for – a wrapper that leaves nothing behind in the DOM: ```jsx function Row() { return ( <> Name Amount ); } ``` The short form `<>...` is almost always enough. Only when the fragment itself needs a `key` – say, as a direct child of a list – do you have to use the long form `...`, because the short form doesn’t accept attributes. By the way, the parentheses around multi-line JSX after `return` aren’t cosmetics against indentation but protection against a JavaScript trap: if the first element is on a new line directly after `return`, JavaScript automatically inserts a semicolon, and the function returns `undefined`. The parentheses prevent that. ## Lists and keys: the most underestimated rule You render a list by using `map` to turn an array into an array of elements. Each of these elements needs a `key` attribute. The key isn’t a decorative detail – it’s the information React uses on the next render to recognize which old element corresponds to which new one. ```jsx
      {invoices.map((i) => (
    • {i.number}
    • ))}
    ``` The key has to have two properties: it must be unique among its siblings, and it must be stable, that is, always the same for the same data. That’s why you use a domain ID, not a random value and – this is the sore point – preferably not the array index. The index as a key seems to work as long as the list never changes. But as soon as you insert something at the front, delete or sort, the indexes shift, and React assigns the old states to the wrong elements. This shows up in ghostly bugs: an input field keeps its text even though the row should be a completely different one; a checkbox stays checked even though the corresponding element was deleted. The index describes a position, but the key is supposed to describe an identity – and position and identity are two different things. Only when a list is guaranteed to be static and never re-sorted is the index acceptable as a key. How React performs this comparison in detail when re-rendering is a topic of its own. ## Spread, children and the small pitfalls on the side You can set props individually or pass them through from an object with the spread operator. That’s convenient but deserves caution: ```jsx const props = { type: "text", value: value, onChange: handleChange }; ``` It’s clean when you know exactly what’s in the object. It gets messy when you blindly pass through an entire foreign object and thereby unknowingly set attributes you didn’t want at all. If a single attribute follows the spread, the last one wins – `` overrides the `value` from the object. The content between the opening and closing tag ends up in the special prop `children`. A component that renders `children` knows nothing about its content and is usable everywhere precisely for that reason. You can also pass `children` explicitly as an attribute, but that’s rarely nicer than natural nesting. A few more details that come up again and again: inline styles in JSX are an object, not a CSS string, and their keys are in camelCase – `
    `, with double braces, because the outer pair starts the expression and the inner one is the object. You write comments inside JSX as an expression: `{/* so */}`. And you only insert raw HTML from a string via `dangerouslySetInnerHTML` – the unwieldy name is intentional, because this is exactly where cross-site scripting holes arise when the string comes from a foreign source. Normal text in JSX is automatically escaped by React and is therefore safe; this one path deliberately bypasses that protection. ## Why precision pays off All these rules follow from a single idea: JSX is a notation for function calls that produce a description object. The reserved names, the expression rule, the disappearance of `null` and `false`, the `0` trap, the requirement for one root node, the meaning of the key – none of it is arbitrary; it all follows from the fact that in the end JavaScript runs, not HTML. If you read JSX this way, you stop working against the language. You no longer accidentally write `className` as `class`, you turn a number in front of `&&` into a real comparison, you assign keys from domain IDs instead of indexes – not because a linter complains, but because you understand what the compiler makes of it. The individual building blocks only touched on here – data flow through props, the question of state ownership, rendering on the server – have their own articles. JSX is the beginning of everything, and that’s exactly why it pays to be precise here. ## Further reading - Repository introduction-react (JSX chapter and examples): https://github.com/mikebild/introduction-react - React, Writing Markup with JSX: https://react.dev/learn/writing-markup-with-jsx - React, JavaScript in JSX with Curly Braces: https://react.dev/learn/javascript-in-jsx-with-curly-braces - React, Rendering Lists and keys: https://react.dev/learn/rendering-lists --- # AWS Deployment Pipelines Are Architecture URL: https://www.mikebild.dev/en/blog/aws-deployment-pipelines-are-architecture/ Date: 2020-05-12 # AWS Deployment Pipelines Are Architecture The time from a merged commit to the moment the change takes effect in production is under a quarter of an hour for some teams and a whole quarter for others – often with comparable application code. This span appears in no architecture diagram. It comes about where a change makes its way: in the steps between commit and runtime, in the controls it has to pass, and in what is left when it has to be taken back. The way there therefore belongs in the same design discussion as the choice of a database – and needs the same justification. The concrete occasion for this text is a small GitHub Action that does nothing more than deploy an AWS CDK project. A few lines of YAML. And yet exactly this building block determines which error shows up early, which only in production – and who is allowed to trigger a change to the infrastructure at all. ## The pipeline determines changeability Architecture answers the question of what can be changed independently of each other. That is exactly the core question of a pipeline too. A system that can only be deployed in a quarterly release has a different architecture from one that rolls out the same codebase twenty times a day – even if both contain identical application code. Changeability isn’t only in how modules are split, but in the path from a commit to the runtime. On AWS, this path has become especially visible since infrastructure itself became code. With the CDK, I describe Lambda functions, API gateways, tables and permissions in TypeScript. `cdk synth` translates that into a CloudFormation template, `cdk deploy` brings it into an account. This shifts something fundamental: the question “what does my infrastructure look like?” and the question “how does a change get there?” coincide. Both live in the same repository and go through the same review and the same pipeline. I wrote about this in more detail in [Infrastructure in a programming language](https://www.mikebild.dev/en/blog/cdk-early-days-infrastructure-in-a-programming-language/); here I’m interested in the step after that – what happens when this code is rolled out automatically. A minimal stack looks like this: ```ts import * as cdk from "@aws-cdk/core"; import * as lambda from "@aws-cdk/aws-lambda"; import * as apigw from "@aws-cdk/aws-apigateway"; export class ApiStack extends cdk.Stack { constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); const handler = new lambda.Function(this, "ApiHandler", { runtime: lambda.Runtime.NODEJS_12_X, handler: "index.handler", code: lambda.Code.fromAsset("dist/api"), }); new apigw.LambdaRestApi(this, "Api", { handler }); } } ``` The example is deliberately small. It isn’t meant to show a complete application but to mark the boundary: everything here is part of the deployable artifact from now on. If I change the runtime, extend a permission or rebuild the API, it takes the same path as a code change. The exciting decision isn’t how many constructs I write, but which control stands between this code and production. ## The “CDK Action” as the smallest honest building block The simplest way to automate this deployment is a GitHub Action that reacts to every push to `main`: ```yaml name: deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v1 with: node-version: 12 - run: npm ci - run: npm test - run: npx cdk deploy --require-approval never env: AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_DEFAULT_REGION: eu-central-1 ``` That looks harmless, but it makes one architecture decision after another. `on: push` means: every merge to `main` is a deployment – the trunk is the delivery, not just an intermediate state. The `npm test` step before `cdk deploy` draws a quality line: whatever is red doesn’t go out. `--require-approval never` skips the CDK’s interactive prompt for security-relevant changes – convenient, but it shifts responsibility for IAM changes entirely to the review before. And the two secrets determine with which permissions this pipeline acts in the account; in practice, that’s where most of the unspoken power lies. That is exactly why this small building block is more revealing than any big reference pipeline. You can walk through it with the team in five minutes, and every line stands for a conscious or unconscious decision about frequency, safety and responsibility. ## The review point comes before the deploy, not after With application code, we review the diff. With infrastructure, many people don’t – and are surprised when a merge opens a security group on the side or replaces a table. The CDK has a good tool for this that becomes the actual review artifact in a pipeline: ```bash # what will actually change in the account cdk diff ApiStack ``` `cdk diff` doesn’t show my TypeScript diff but the difference between what is in the account and what I want to deploy – including the IAM statements CloudFormation derives from it. In a clean pipeline, this step runs automatically and attaches the result to the pull request. That way, a person decides about the effect, not about the source code. That’s a methodological difference with a direct operational effect: a reviewer who sees “this change adds `iam:PassRole`” stops it before it lands in the account. A reviewer who only reads `stack.ts` often misses it. This is what the path looks like as a whole: ```mermaid flowchart LR Commit --> Build["Build & Test"] Build --> Synth["cdk synth
    CloudFormation template"] Synth --> Diff["cdk diff
    review artifact"] Diff --> Approve{"Approval?"} Approve -->|yes| Deploy["cdk deploy"] Approve -->|no| Stop["Stop"] Deploy --> Observe["Metrics &
    alarms"] Observe -->|failure| Rollback["Rollback to
    previous revision"] ``` Every node in this sketch is an adjustment knob. Where the approval sits decides speed versus control. Whether anything is observed after `Deploy` at all decides whether a bad release is noticed before the customer reports it. And whether there is a real `Rollback` path decides whether a change is reversible – or just hopefully right. ## The same artifact through several environments As soon as more than one environment is involved – staging and production, often in separate AWS accounts – the pipeline becomes the actual definition of what “promoting” means. That only holds up under one condition: the same checked artifact moves through the stages, not a second build with slightly different ingredients. With the CDK, that means synthesizing the same app with a different context. ```ts const app = new cdk.App(); new ApiStack(app, "ApiStack-staging", { env: { account: "111111111111", region: "eu-central-1" }, }); new ApiStack(app, "ApiStack-prod", { env: { account: "222222222222", region: "eu-central-1" }, }); ``` This puts the environment topology in the same repository as the code, and it goes through the same review. The methodological gain is trust: when staging and production are synthesized from one source, staging actually tests what later runs in production – and not a plausible copy that differs in three places. It’s exactly these differences that otherwise only surface in the most expensive account. Splitting into separate accounts isn’t an operations detail but an architecture boundary: a deploy to staging can’t accidentally touch production because it simply lacks the permissions in the other account. ## Trade-offs you have to name The interesting work on a pipeline isn’t getting it to run but laying its compromises open. Three of them come up regularly: - Auto-deploy on `main` versus a manual gate. The automatic path shortens lead time drastically but requires a reliable test net and good alerts. The gate gives a feeling of safety, but in practice it collects changes into large, risky batches – the most common reason for rare, fear-ridden releases. - One stack versus many stacks. One big stack is easy to deploy, but every change touches everything. Separate stacks for API, data and static frontend let you keep risk small and roll out parts independently – at the cost of more coordination at the interfaces. - Rollback via redeploy versus fix-forward. CloudFormation can roll back automatically on a failed deploy. But that only holds as long as the change hasn’t already migrated data or extended a schema. From then on, “just go back” is an illusion, and you need additive, backward-compatible steps instead of an undo button. None of these decisions is universally right. But they belong in an architecture conversation and in a short ADR, not in a YAML file someone committed a year ago that no one has questioned since. ## Why a CTO should care For technical leadership, all this translates into numbers that have had an established vocabulary since “Accelerate.” Four metrics describe the performance of delivery fairly completely, and all four are determined by the pipeline, not by the application code: - Deployment frequency – how often anything goes live at all. An auto-deploy on `main` raises it by orders of magnitude compared to a manual quarterly gate. - Lead time – how long from “code done” to “in production.” `cdk diff` in the PR plus an automatic deploy pushes that down from days to minutes. - Change failure rate – what share of releases causes a failure. The test step and the diff review before the deploy lower it without sacrificing frequency. - Time to restore – how quickly the normal state is back. A real, practiced rollback path is the difference here between minutes and a lost afternoon. The important thing about these four: they make different sides of delivery capability visible. Small changes limit the scope of a review and of a possible failure; automated checks shorten feedback; a practiced recovery path lowers the time to repair. Whether a pipeline actually has this effect only shows in Lead Time for Changes, Change Failure Rate and Time to Restore Service in your own system. It is therefore not an add-on for the operations side but part of the architecture. ## How I check a pipeline A pipeline design only holds up once the failure path is described too. The questions that uncover the most aim exactly there. What happens if `cdk deploy` aborts in the middle of a change – is a half-finished state left behind? Is the deploy idempotent enough that a second run heals it? Where is the line beyond which a rollback is no longer enough because data has already been migrated? And quite simply: who may trigger this pipeline, and is that logged in a traceable way? What I run into most often is overrating the happy path. In the demo account, everything runs cleanly. It gets interesting with partial failures, permissions that are just barely insufficient, resources that CloudFormation wants to replace instead of change, and that one deploy that hangs at 5 p.m. on a Friday. That’s exactly where it shows whether the pipeline model holds up – and whether “reversible” is a real promise or just a word in a presentation. ## Conclusion The temptation is to treat a pipeline as a tool question: which Action, which runner, which provider. The real substance lies elsewhere. A pipeline encodes how often a team may change its mind, how safely it does so and how easily it takes back a mistake. These are architecture properties, and they don’t come from the tool’s name but from the few deliberate decisions behind it – auto-deploy or gate, one stack or many, undo or fix-forward. If you name these decisions and measure their effect, you can change bottlenecks in a targeted way. If you leave them to an old YAML file, you make them anyway – only unconsciously and usually at the worst possible moment. ## Further reading - AWS CDK Developer Guide: https://docs.aws.amazon.com/cdk/latest/guide/home.html - AWS CDK Constructs: https://docs.aws.amazon.com/cdk/latest/guide/constructs.html - AWS CloudFormation – how deployments and rollbacks work internally: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html - Nicole Forsgren, Jez Humble, Gene Kim: “Accelerate” – the four delivery metrics in detail. --- # Advanced Python: Decorators, Magic Methods and Generators URL: https://www.mikebild.dev/en/blog/advanced-python-decorators-magic-methods-generators/ Date: 2020-04-08 Python code that you could have written line for line just the same in Java or C# is rarely wrong – it just doesn’t use the language. Three mechanisms make the difference, and none of them is magic: the `@` decorator, the dunder method and `yield`. All three are documented in the language core, each can be rebuilt yourself in a few lines, and each solves a problem you would otherwise solve with copy-paste or with too much memory. The state here is early 2020, so Python 3.8. All examples run there without extra packages – just with `functools`, `time` and the standard library. The prerequisites are Python objects, functions and the usual built-in data types. ## Decorators: functions that wrap functions Getting into decorators is easier than the `@` sugar suggests. In Python, functions are perfectly ordinary objects. You can assign them to a variable, pass them as an argument and return them from another function. A decorator is nothing more than a Higher-Order Function: it takes a function and returns a – usually wrapping – function. ```python import functools import time def timer(func): @functools.wraps(func) def wrapper(*args, **kwargs): start = time.perf_counter() result = func(*args, **kwargs) elapsed = time.perf_counter() - start print(f"{func.__name__} took {elapsed:.4f}s") return result return wrapper @timer def slow_sum(n): return sum(range(n)) ``` The notation `@timer` above `def slow_sum` is exactly syntactic sugar for `slow_sum = timer(slow_sum)`. Nothing else happens. After decorating, the name `slow_sum` no longer points to the original function but to `wrapper`. On every call, timing starts first, then the real function runs, and afterward the elapsed time is printed. The `*args, **kwargs` makes sure the wrapper passes through any signature without having to know anything about the arguments itself. Here’s the flow when calling a decorated function, drawn out – the wrapper brackets the actual work: ```mermaid flowchart LR Call["call slow_sum()"] --> W["wrapper()"] W -->|"before:
    start timer"| F["original func()"] F -->|"return value"| W W -->|"after:
    print elapsed"| Ret["return result"] ``` ### functools.wraps isn’t optional One detail is missing from hand-written decorators with remarkable regularity: the line `@functools.wraps(func)`. Without it, the decorator still works, but the wrapper doesn’t take on the identity of the original function. `slow_sum.__name__` then returns `"wrapper"` instead of `"slow_sum"`, `slow_sum.__doc__` is the wrapper’s docstring, and `help(slow_sum)` shows the wrong signature. ```python def timer_broken(func): def wrapper(*args, **kwargs): return func(*args, **kwargs) return wrapper @timer_broken def greet(name): """Say hello to someone.""" return f"Hello, {name}" print(greet.__name__) # -> "wrapper" print(greet.__doc__) # -> None ``` `functools.wraps` is a convenience wrapper around `functools.update_wrapper`. It copies `__module__`, `__name__`, `__qualname__`, `__annotations__` and `__doc__` from the original function to the wrapper and also sets `__wrapped__`, so that you can get back to the undecorated function if needed. For debugging, introspection and tools that look at metadata, this is the difference between useful and confusing. That’s why this line goes into every decorator I write. ### Decorators with arguments Often you want to configure a decorator, for example: “Run the function three times.” For that you need one more level. A decorator with arguments is a function that returns a decorator, which in turn returns the wrapper – three nested functions. ```python def repeat(times): def decorator(func): @functools.wraps(func) def wrapper(*args, **kwargs): result = None for _ in range(times): result = func(*args, **kwargs) return result return wrapper return decorator @repeat(times=3) def ping(): print("ping") ``` `@repeat(times=3)` is evaluated first: the call `repeat(times=3)` returns `decorator`, and this `decorator` is then applied to `ping`. Once you’ve read the structure from the inside out, the pattern opens up – and it shows up in exactly this form in many libraries, for example in routing decorators in web frameworks. ## Magic methods: your own objects behaving like built-in ones The second building block reaches deeper into the language. Magic methods – also called dunder methods, because of the double underscores – are the way your own classes plug into Python’s protocols. You never call these methods directly. Instead, the interpreter calls them when you put an object into a known context: `len(obj)` triggers `__len__`, `==` triggers `__eq__`, a `for` loop triggers `__iter__`, a `with` block triggers `__enter__` and `__exit__`. A few of the most common dunder methods and what triggers them: - `__init__` – construction when an instance is created - `__repr__` – `repr()` and the display in the REPL, ideally unambiguous and at best `eval`-able - `__str__` – `str()` and `print()`; if it’s missing, `__repr__` steps in - `__eq__` – comparison with `==` - `__len__` – the call `len(obj)`, which is also used for truth testing when `__bool__` is missing - `__iter__` and `__next__` – iteration in `for` loops and when unpacking - `__enter__` and `__exit__` – entering and leaving a `with` block - `__call__` – calling an instance like a function, `obj()` To make this concrete, I build a class that provides lines from a file. It should have a proper `__repr__`, be comparable with `==`, work as a context manager and be iterable. ```python class LineStore: def __init__(self, path): self.path = path def __repr__(self): return f"LineStore({self.path!r})" def __eq__(self, other): return isinstance(other, LineStore) and self.path == other.path def __enter__(self): self._file = open(self.path, encoding="utf-8") return self def __exit__(self, exc_type, exc_value, traceback): self._file.close() return False # do not swallow exceptions def __iter__(self): return (line.rstrip("\n") for line in self._file) ``` A `LineStore` now behaves like a built-in object. In the REPL it shows `LineStore('access.log')` instead of a meaningless memory address. Two instances with the same path are equal. And the real highlight is in the `with` block: ```python with LineStore("access.log") as store: for line in store: if "ERROR" in line: print(line) ``` The `with` calls `__enter__`, binds the return value to `store`, runs the body and then – guaranteed, even on an exception – calls `__exit__`. That’s where the file gets closed. That’s exactly the point of a context manager: cleanup you can’t forget. The return value of `__exit__` decides how errors are handled. If the method returns `True`, an exception raised in the block is suppressed; a falsy value like `False` passes it on. I deliberately return `False` here, because an error while reading the file shouldn’t silently disappear. For simple cases, by the way, you don’t have to implement the protocol by hand. `contextlib.contextmanager` turns a generator function into a context manager, with the `yield` separating setup and teardown. That leads us straight to the third building block. ## Generators: lazy sequences with yield The `LineStore` carries a peculiarity with it: its `__iter__` already returns a generator expression. Generators are the third pillar, and for me the most important in practice as soon as data grows larger than memory. As soon as the keyword `yield` appears in a function, it’s no longer a normal callable but a generator function. Calling it doesn’t run the body but immediately returns a generator object. The code only runs when you iterate over the object – and it stops at every `yield`, remembers its state and continues exactly there on the next step. ```python def stream_lines(path): with open(path, encoding="utf-8") as fh: for line in fh: # a file object is itself an iterator yield line.rstrip("\n") for line in stream_lines("big.log"): if line.startswith("2020"): print(line) ``` Here only one line is in memory at a time. Whether the file is ten kilobytes or ten gigabytes – memory usage stays constant. That’s exactly the difference from a list. If I wrote `fh.readlines()`, Python would hold all lines at once. The generator produces them one at a time, on demand. The same principle exists in compact form as a generator expression – syntactically like a list comprehension, just with round instead of square brackets: ```python # list comprehension: builds the whole list in memory lengths_list = [len(line) for line in stream_lines("big.log")] # generator expression: yields one length at a time total = sum(len(line) for line in stream_lines("big.log")) ``` The second variant sums the line lengths without ever creating a complete list. For aggregations over large amounts of data, that’s the standard way. And if you want to chain generators, `yield from` helps you delegate to another iterable without writing a loop yourself: ```python def chained(*paths): for path in paths: yield from stream_lines(path) ``` ## Three pitfalls As clear as the three building blocks are, the same stumbling blocks show up just as reliably in practice. These three cost the most time. The classic is mutable default arguments. If you write an empty list as a default, you don’t get a fresh list on every call but always the same one. ```python def append_item(item, acc=[]): # trap: shared across calls acc.append(item) return acc print(append_item(1)) # [1] print(append_item(2)) # [1, 2] – surprise ``` The default is evaluated exactly once, namely at `def`. After that, all calls share the same object. The solution is a guard on `None`: ```python def append_item(item, acc=None): if acc is None: acc = [] acc.append(item) return acc ``` The second stumbling block is the forgotten `functools.wraps`, the case shown above. A decorator without this line works, but it swallows the name, docstring and signature of the decorated function. In small scripts you don’t notice; as soon as someone introspects the function or a framework looks at the metadata, it becomes a puzzle. The third hits generators: after one pass they’re exhausted, and that’s the flip side of lazy evaluation. A generator remembers its progress and doesn’t reset it. If you run through it twice, you get nothing the second time. ```python gen = stream_lines("big.log") first = list(gen) # reads all lines second = list(gen) # empty – the generator is exhausted ``` You can iterate over a list as often as you like, over a generator only once. If you need the data several times, deliberately materialize it into a list – or call the generator function again to get a fresh object. Related to this: `len()` doesn’t work on a generator, because its length isn’t even known without a full pass. ## Conclusion Decorators, magic methods and generators seem like advanced extras at first contact, but they’re basic tools in everyday work. Decorators cleanly separate recurring behavior – timing, logging, repetition – from the actual logic, as long as you don’t forget `functools.wraps`. Magic methods connect your own objects to the language, so that `len()`, `==`, `for` and `with` just work without the calling code having to know anything about the internals. And generators turn a function into a lazy sequence that delivers large amounts of data element by element instead of holding everything at once. What connects these three building blocks is a shared idea: Python provides clearly defined protocols, and your own code hooks into them. You don’t write against the language but with it. Once you’ve internalized that, you recognize the patterns everywhere in the standard library – and write code that can not only be run but also read. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-python.en.html - Repository `introduction-python` – chapters `13-decorators.md`, `14-magic-methods.md`, `15-iter.md` with the corresponding examples under `examples/` (`decorators.py`, `classes.py`, `functional.py`) - Python Data Model / Special Methods: https://docs.python.org/3.8/reference/datamodel.html - The `with` statement and the context manager protocol: https://docs.python.org/3.8/reference/compound_stmts.html#the-with-statement - `functools` with `wraps` and `update_wrapper`: https://docs.python.org/3.8/library/functools.html - `contextlib.contextmanager`: https://docs.python.org/3.8/library/contextlib.html - Yield expressions and generators: https://docs.python.org/3.8/reference/expressions.html#yield-expressions - Tutorial on generators and generator expressions: https://docs.python.org/3.8/tutorial/classes.html#generators - PEP 318 – Decorators for Functions and Methods: https://www.python.org/dev/peps/pep-0318/ --- # Policy as Code for CDK URL: https://www.mikebild.dev/en/blog/policy-as-code-for-cdk/ Date: 2020-03-12 # Policy as Code for CDK If you only write an architecture rule down, sooner or later you get it back as an incident. No publicly readable bucket, every table encrypted, no instance larger than necessary, everything tagged: this list is rarely complete in one place. It exists in a few heads, in a wiki nobody opens anymore, and in review comments that depend on who happens to be looking and how much time they have. One inconspicuous default is enough, and the good intention turns into an open bucket in production. This problem is exactly what this post is about – and `cloudpatrol` is my attempt to solve it. In my [post about the early days of CDK](https://www.mikebild.dev/en/blog/cdk-early-days-infrastructure-in-a-programming-language/), the text ends with a subordinate clause: for rules that are not negotiable, an automated check of the synthesized template is worthwhile, a kind of policy as code for your own CDK output. Here I make good on that clause. It is less about yet another tool than about running well-founded guardrails as automated checks. Trade-offs remain architecture work. ## Why rules fall out of the review A review is a human with limited attention. Today they see that a bucket has no encryption, and next week they miss it because the pull request is big, it’s Friday afternoon or the interesting discussion was happening elsewhere. That is no accusation. That’s how attention works. Knowledge that only exists in the review is as reliable as the reviewer’s form on the day. It follows that a rule you can’t execute is not a rule. It is a hope. As long as “no public bucket” is a sentence in the onboarding document, it will be broken at some point – not out of ill will, but because a default slips through unnoticed. The point of policy as code is therefore less technical than cultural. It moves the rule from a place where it has to be remembered to a place where it is checked. The CDK is what makes this shift possible. Because infrastructure here is code that is synthesized into a CloudFormation template, there is an intermediate step you can inspect before anything is created in the cloud. This intermediate step is exactly the right place for a check. ## The checkpoint lies between synthesis and deployment You can check cloud resources in many places. At runtime, a service that scans accounts finds violations only once they already exist. A weekly report is better than nothing but always comes too late for the person who made the mistake. It gets interesting when the check moves to where the decision is made: the moment the code generates the template. ```mermaid flowchart LR Source["CDK code (TypeScript)"] --> Synth["cdk synth"] Synth --> Policy["Policy check"] Policy -->|violation| Fail["Feedback in the PR"] Policy -->|ok| Deploy["Deployment"] ``` `cloudpatrol` comes in at exactly this point. It hooks into synthesis and evaluates the constructs while they are being created. That is an architecturally different approach from a downstream scanner. The check doesn’t see the raw JSON template but the typed constructs with their properties. That way you can write a rule against `s3.CfnBucket` instead of matching a string path in a YAML tree. The boundary where the check happens is the same boundary the developer thinks in. The effect on the cycle is concrete. A violation that used to become visible as an incident – someone reports an open bucket, there is an investigation, a fix, a postmortem – now becomes visible as a red test run before the pull request is merged. The time between error and detection shrinks from days to seconds, and the cost of the correction drops accordingly. ## A policy is code, not a config entry The decisive design choice in `cloudpatrol` is that a rule is not a line in a YAML file but a class. It declares which construct type it applies to, and it contains a validator method that checks the concrete node and reports findings to a reporter. ```ts import { Policy, PolicyInterface, Reportable } from "cloudpatrol"; import * as s3 from "@aws-cdk/aws-s3"; export class BucketEncryptionPolicy extends Policy implements PolicyInterface { public policyName = "Bucket Encryption"; public description = "S3 buckets must be encrypted at rest."; public scope = s3.CfnBucket; public validator(node: s3.CfnBucket, reporter: Reportable): void { if (!node.bucketEncryption) { reporter.addError(node, this, "Bucket has no server-side encryption configured."); } } } ``` The `scope` is the selector: the validator only runs for buckets, not for every node in the tree. Inside the validator, I have the full expressive power of TypeScript. I can nest conditions, allow exceptions for certain environments, evaluate several properties together. This is exactly where a declarative rule language hits its limit – the interesting rules are rarely “field X must be Y” but “field X must be Y, unless Z, and then please with this justification”. The whole thing is applied via a patrol that walks through a stack: ```ts const patrol = new AwsCdkPatrol(awsDefaults); patrol.check(stack); ``` `cloudpatrol` comes with a handful of built-in policies – encryption, versioning, instance types – but the built-in ones are only the starting point. The real value emerges when a team translates its own unwritten list into such classes. From then on, the list is no longer unwritten. It lives in the repository, it is versioned, it has an author and a history, and you can discuss it in a pull request like any other code. ## warn or block is a design decision Not every rule carries the same weight. A missing cost center tag is annoying; a publicly readable bucket with customer data is an incident. That’s why the severity of a rule is not a detail but the central design decision. A warning reports and lets things through. An error blocks. If you block everything, you train your team to work around the check. If you block nothing, all you end up with is nicely formatted log output. Here I deliberately distinguish between guardrails and architecture police. Guardrails define the few boundaries that are truly non-negotiable: encryption, least privilege, no open networks, hard cost limits. Within these boundaries, the team stays able to act and stays fast. Architecture police, on the other hand, tries to centralize every decision and thereby shifts responsibility away from the teams. The first speeds up safe work; the second slows things down and frustrates. The difference lies not in the tool but in the question of how many rules you set to `block` and how well you justify those few. ```ts type Severity = "warn" | "block"; type RuleMeta = { policyName: string; severity: Severity; reason: string; suggestion: string; }; ``` ## Every rule needs a reason and a way out A check that only says “forbidden” is a wall. The developer stands in front of it, doesn’t understand why and looks for the shortest way around it. A check that delivers the reason and an alternative is learning feedback. It explains the decision exactly where it becomes relevant and makes the next developer a bit more independent. ```json { "policy": "lambda-timeout-max", "severity": "block", "reason": "A timeout above 30s usually hides a synchronous call that should be async.", "suggestion": "Move the work behind a queue or a Step Function and return early." } ``` These three fields – reason, severity, way out – are the difference between a rule that creates friction and one that reduces it. The reason prevents the rule from being read as arbitrary. The way out turns blocking into a recommendation. That’s exactly why every policy in `cloudpatrol` has a `description` and a `link` field: the rule carries its own justification with it instead of parking it in a wiki that is decoupled from the code. ## The pull request is the right place Guardrails work best before deployment, and the pull request is the natural place for that, because that’s where code, context and discussion come together. In practice, this means the policy check runs in the same pipeline that builds the code and ships the infrastructure. A red check is then not a bureaucratic step but the same kind of signal as a failed unit test. At this point the benefit is measurable, on three levels. First, cycle time: a violation becomes visible when the pull request is opened, not days later in operation. Second, consistency: the check is always equally strict, regardless of who reviews and how full their calendar is. Third, review load: people no longer have to mechanically search for the same ten things but can focus on the questions a machine can’t answer – does the cut of the stack make sense, does the abstraction fit, is the cost profile right. That is the real productivity gain: a machine takes over the same boring checking work every time, and the minds on the team are freed up for the interesting work. ## Costs are an architecture signal One side effect is worth mentioning because it is often overlooked. Cloud costs are not just a topic for accounting; they are a behavioral signal of the architecture. A function that starts too often, a resource that is sized too generously, a deployment that produces unnecessary artifacts – all of this leaves a cost trail before it gets named as an architecture problem. ```mermaid flowchart LR Usage["Usage"] --> Cost["Cost trail"] Cost --> Signal["Signal"] Signal --> Rule["Policy as a guardrail"] ``` A policy that flags an overly generous instance type or a missing lifecycle rule is therefore not just a technical check. It catches a cost decision before it shows up as a bill next month. Costs don’t replace design, but they are an honest touchstone for whether the architecture behaves the way you assumed when designing it. ## Where policy as code reaches its limit It would be a mistake to try to cast everything into a rule. Some decisions are not a check but a trade-off, and those belong to a human. A timeout above thirty seconds can be wrong or exactly right, depending on context. Such cases belong in an architecture conversation or a short ADR, not in a blunt blocker. The policy then doesn’t say “forbidden” but “this needs a justification”. This gives policy as code a clear responsibility. It is suitable for the small set of non-negotiable guardrails whose violation is objectively recognizable. It is not suitable for matters of taste, nor for trade-offs where the right answer depends on the project. If you respect this boundary, you get a tool that creates trust. If you ignore it and turn every opinion into a blocking rule, you get a tool that gets bypassed. A second caveat concerns abstraction. `cloudpatrol` checks what synthesis produces. A self-written construct that encapsulates a dozen resources can unintentionally undermine a rule if it sets the checked property differently than you think. So the check is only as honest as the visibility of the constructs. That is not an argument against abstraction, but a reminder that a rule and the building blocks it runs against have to be designed together. ## What I take away after a few weeks `cloudpatrol` is alpha, the API is moving, and I wouldn’t build a big initiative on it today. But the direction convinces me, and it is independent of the specific tool. As soon as infrastructure is code, its rules belong in the same cycle as the code: versioned, checked, open to discussion in the pull request. The gain is not that a machine finds errors. The gain is that an architecture decision no longer lives in the head of a single person but sits in the repository as an executable, justified rule that another developer can meaningfully disagree with tomorrow. Whether a rule is worth it comes down to three points. It has to prevent a real failure case that I can name, it has to deliver its reason, and it has to show a way out. If it does, the rule no longer depends on the reviewer’s form on the day but on a check that is always equally strict. Everything else remains a topic of conversation for humans – and that’s a good thing. ## Further reading - AWS CDK, introduction and concepts: https://docs.aws.amazon.com/cdk/latest/guide/home.html - Constructs as building blocks: https://docs.aws.amazon.com/cdk/latest/guide/constructs.html - Policy as code for the CDK (cloudpatrol): https://github.com/MikeBild/cloudpatrol --- # The Aggregate as a Consistency Boundary URL: https://www.mikebild.dev/en/blog/the-aggregate-as-a-consistency-boundary/ Date: 2020-02-19 ```typescript @Entity() class Order { @PrimaryGeneratedColumn() id: number; @ManyToOne(() => Customer) customer: Customer; @OneToMany(() => LineItem, (li) => li.order) lineItems: LineItem[]; @Column() status: string; } ``` This class carries four annotations and not a single rule. Nothing stops code anywhere from calling `order.lineItems.push(...)` even though `status` has long been set to `'CONFIRMED'`. And through `order.customer.updateAddress(...)`, the same caller changes a second model on the side, in the same transaction. What you see here is an object graph: data classes with getters and setters, connected by foreign keys. And yet exactly this kind of class is regularly called an aggregate. An aggregate comes into being earlier. It starts with the question of which rules have to hold at the same instant, and only after that does it become classes and tables. If you read the term this way, you make different decisions: about transactions, about references between objects, about the size of your models and about where eventual consistency begins. This continues a line of thought I have pursued elsewhere – that [CQRS is a domain boundary](https://www.mikebild.dev/en/blog/cqrs-is-a-domain-boundary-not-a-framework/) and not a framework. The aggregate is the next, smaller boundary in the same conceptual building. ## What an aggregate really is Martin Fowler puts it concisely: an aggregate is “a cluster of domain objects that can be treated as a single unit”. The classic example is an `Order` with its `LineItems`. These are separate objects, but they are never loaded, changed or saved individually. They come out of the repository as a whole and go back as a whole. The aggregate is the basic unit of storage transfer. Within this cluster there is exactly one distinguished component: the Aggregate Root. It is the only entity that may be referenced from outside. Nobody outside the aggregate ever holds a `LineItem` directly – you always go through the `Order`. That sounds like an annoying encapsulation rule, but it has a deep reason: only if all access goes through the root can the root guarantee that the state of the entire aggregate is correct. And that brings us to the core. Eric Evans, Vaughn Vernon and Fowler all mean the same thing when they talk about the aggregate: it is the consistency boundary. The invariants – the business rules that must always hold – are satisfied after every completed change. Not “eventually”, not “after the next batch run”, but immediately, transactionally. Vernon aptly calls this “must always be transactionally consistent”. An invariant might be: “After confirmation, no more line items may be added.” Or: “The sum of the line items equals the order total.” Such rules don’t belong in a service somewhere further up; they belong in the root itself. This is the decisive change of perspective: the shape of an aggregate is determined by the invariants that have to be protected together. Which objects belong together in the domain follows from that – not the other way around. ## The root protects its invariants Let’s look at this in code. The following example is illustrative – I care about the structure, not about a runnable system. What matters is what’s missing: public setters. The `lineItems` list is private, and the only way to change it is through methods that know the invariants. ```typescript type OrderStatus = 'DRAFT' | 'CONFIRMED'; class Order { private status: OrderStatus = 'DRAFT'; private readonly lineItems: LineItem[] = []; constructor( readonly id: OrderId, private readonly customerId: CustomerId, ) {} addLineItem(product: ProductId, quantity: number): void { if (this.status === 'CONFIRMED') { throw new Error('Cannot modify a confirmed order'); } if (quantity <= 0) { throw new Error('Quantity must be positive'); } this.lineItems.push(new LineItem(product, quantity)); } confirm(): void { if (this.lineItems.length === 0) { throw new Error('Cannot confirm an order without line items'); } this.status = 'CONFIRMED'; } } ``` Two invariants are expressed here: a confirmed order no longer accepts line items, and an empty order cannot be confirmed. Both are enforced in exactly one place, the root. There is no way to sneak a `LineItem` into the list past this check – because nobody outside the `Order` can get at the list. That is exactly what “the root ensures the integrity of the entire aggregate” means. The state can’t become invalid in the first place. Compare this with the annotated data class from the beginning, whose `lineItems` and `status` are wide open. There, any code anywhere can manipulate the list or set the status. The rule “no line items after confirmation” then exists at best as a convention, scattered across the codebase, and will be violated sooner or later. The aggregate moves it to a single place that cannot be bypassed. ## One transaction changes exactly one aggregate The transaction boundary follows directly from the consistency boundary. Evans and Vernon are clear here: transactions must not cross aggregate boundaries. The rule of thumb is that one transaction changes exactly one aggregate instance. Anything beyond that is not done in the same atomic commit but in separate transactions, connected through eventual consistency. This rule reliably meets resistance, and the objection always sounds similar: “When an order is confirmed, the stock has to be reserved too – that belongs in one transaction.” It doesn’t. `Order` and `Inventory` are two aggregates, each with its own invariants. Forcing them into a shared commit couples them technically, creates lock contention and makes the system harder to scale. Instead, transaction T1 confirms the order and writes an `OrderConfirmed` event. A separate transaction T2 processes this event and reserves the stock in `Inventory`. ```mermaid graph LR subgraph T1["Transaction T1"] O["Order
    confirm()"] end subgraph T2["Transaction T2"] I["Inventory
    reserve()"] end O -- "OrderConfirmed (event)" --> I ``` Important, to counter a widespread misunderstanding: eventual consistency does not mean “no consistency”. Within an aggregate, everything is strictly and transactionally consistent – after T1, the `Order` is in a valid state no matter what. Between aggregates it is eventual: a short but finite amount of time passes until `Inventory` has caught up. Setting this boundary deliberately is a domain decision. The question is always: does this rule have to hold at the same instant, or may it hold a few milliseconds later? Only if the answer is “at the same instant” does the data belong in the same aggregate. If you want to keep this separation of write intentions and the resulting facts clean, you quickly end up with the question of how to [separate commands, events and queries](https://www.mikebild.dev/en/blog/separating-commands-events-and-queries/) anyway. The event between T1 and T2 is exactly such a fact: something that happened and lets other aggregates react. ## Reference other aggregates by identity only For the transaction boundary to hold at all, a second rule is needed, and it is the one most often violated: an aggregate references another aggregate only through its identity, its ID, never through a direct object pointer. Vernon states this as a design rule of its own: “Reference Other Aggregates by Identity”. You can already see this in the `Order` above. The root holds `customerId: CustomerId`, not `customer: Customer`. The difference is no small matter. ```typescript // Wrong: the customer is pulled inside the order class Order { private customer: Customer; // pulls another aggregate inside the boundary } // Right: only the identity crosses the boundary class Order { private readonly customerId: CustomerId; // reference by identity } ``` As soon as `Order` holds a real `Customer` object, the boundary blurs. The developer who sees the `Customer` reference will use it sooner or later – `order.customer.updateAddress(...)` – and suddenly two aggregates are changed in one transaction. Referencing by ID prevents this structurally: you can’t accidentally mutate a `CustomerId`. If you really need the customer aggregate, you load it beforehand through its own repository and pass in exactly what’s needed – so the ID reference forces a deliberate decision. The side effect is valuable too: aggregates stay small. There is no eager loading of entire object graphs, no “loading the order pulls in the customer, which pulls in their addresses, which pull in their countries”. What lies within the boundary gets loaded, and nothing else. To keep the rules together in one picture, here is the consistency boundary as a diagram. Inside the framed block is the `Order` aggregate with its root and inner objects; `Customer` lies outside, as an aggregate of its own, and is connected only through its identity. ```mermaid graph TB ext["Client code"] subgraph agg["Aggregate: Order (consistency boundary)"] root["Order (Aggregate Root)"] li["LineItem"] money["Money (Value Object)"] root --> li li --> money end cust["Customer
    (separate aggregate)"] ext -->|"references the root only"| root root -. "customerId (by identity)" .-> cust ``` Note the arrows: external access points exclusively at the root, never at `LineItem` or `Money`. And the connection to `Customer` is dashed and labeled `customerId` – a reference, not containment. ## Keep aggregates small This leads to what may be Vernon’s most practical rule: “Design Small Aggregates”. The temptation to let aggregates grow is enormous, and it even has a name – “object graph greed”. Out of convenience, you include everything you’d like to have at hand while navigating. A `Customer` that holds all its `Orders` as a list is the standard example. In domain terms that sounds plausible; technically it’s a problem: every change to a single order would have to load and lock the entire customer aggregate including all orders. For a customer with a thousand orders, every small operation becomes expensive, and concurrent accesses block each other. The heuristic against this is simple: model along real invariants, not along navigation wishes. The question is not “do I want to be able to navigate from A to B” but “does A have to become invalid when B changes, and immediately so”. Only if there is a real, instantaneous consistency rule between two objects do they belong in the same aggregate. For everything else there are references by ID and, if you want to navigate for reading, a read model. The aggregate is a write model; if you’re looking for navigation convenience for display, build a projection for it instead of bloating the aggregate. Let’s sum up the rules I use to check an aggregate during design: - All access from outside goes through the Aggregate Root; inner objects are encapsulated. - The root enforces the invariants, transactionally consistent after every change. - One transaction changes exactly one aggregate instance; everything else runs through eventual consistency and domain events. - Other aggregates are referenced only by their identity, never as an embedded object. - Aggregates stay small and are cut along real invariants, not along navigation wishes. ## The three pitfalls Three confusions come up again and again, and it’s worth naming them. The first and most common: equating the aggregate with a database table or an ORM entity. That is wrong. The aggregate is a modeling and consistency concept; how it is mapped to tables is an entirely separate question. An aggregate can be persisted across several tables, and one table can contain several value objects. Persistence is orthogonal to the model. A class annotated with `@Entity` and full of getters and setters is far from being an aggregate – it lacks the crucial part, the enforced invariant. The second: misunderstanding the Aggregate Root as a “God Object”. Because the root is the only entry point, inexperienced teams tend to put everything into it. That is the opposite of the intent. The root is small and driven by invariants. It holds exactly what it needs to enforce its rules – no more. A root that holds everything is usually a sign that several aggregates have mistakenly been merged into one. The third: direct object references between aggregates, the mistake from the beginning. It is so insidious because it feels harmless and because ORMs practically invite it – a `@ManyToOne` relationship is quickly annotated. But every such reference is an invitation to change several aggregates in one transaction and soften the boundary. The discipline is: reference by ID, and if you really need the other aggregate, load it beforehand through its repository – before calling the aggregate method, not in the middle of it. ## A brief distinction Because people constantly mix up what belongs together in the DDD world and what doesn’t, a brief clarification on the side. CQRS and Event Sourcing are not the same thing, and neither of them is the aggregate. CQRS separates the write model from the read model, command from query. Event Sourcing persists state as a sequence of events instead of a current snapshot. Both can be used independently of each other – you can use either one without the other, as Fowler and Greg Young emphasize. The aggregate, in turn, is a building block that appears in all of these worlds: it is the consistency boundary against which a command is validated and from which events arise. If you keep these terms cleanly apart, you save yourself many fruitless architecture discussions. And one more subtle but important distinction: the consistency boundary is not the transaction boundary of the database. It’s the other way around. The aggregate defines the logical boundary within which everything has to be consistent – and the database transaction has to respect it. It is not the available transaction mechanisms that determine how models are cut; the domain invariants determine how far a transaction may reach. If you turn this around and align your aggregates with the technical capabilities of the ORM, you have drawn the boundary at the wrong end. ## Conclusion The aggregate deserves its central place in DDD because it answers one of the hardest questions in software development: where does consistency end and where does coordination begin? It is neither a data container nor a persistence artifact, but a deliberately drawn consistency and transaction boundary with a root that relentlessly enforces its invariants. Almost everything else follows from this one idea: one transaction per aggregate, references between aggregates only through identity, small models along real rules, and eventual consistency wherever instantaneous consistency is neither necessary nor affordable. So the first question before a domain model is not “which objects belong together” but “which rules have to hold at the same instant”. The answer cuts the aggregates – and with them half the architecture. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-cqrs-event-sourcing.en.html - Martin Fowler: [DDD_Aggregate](https://martinfowler.com/bliki/DDD_Aggregate.html) – the compact definition of aggregate and Aggregate Root. - Vaughn Vernon: [Effective Aggregate Design](https://www.dddcommunity.org/library/vernon_2011/) (2011), parts I–III – the rules “Design Small Aggregates” and “Reference Other Aggregates by Identity”. - Eric Evans: *Domain-Driven Design* (2003), chapter 6 – the primary source for aggregates and Aggregate Roots. - Greg Young / Martin Fowler on distinguishing CQRS and Event Sourcing – useful for cleanly separating the aggregate from both. - From my own talk material: the deck “CQRS + Event Sourcing” (SlideShare), in which I play through this boundary-drawing with concrete examples. --- # `ssmenv-cli`: Small CLIs for Big Order URL: https://www.mikebild.dev/en/blog/ssmenv-cli-small-clis/ Date: 2020-02-12 # `ssmenv-cli`: Small CLIs for Big Order Configuration isn’t a file format. It is a data set with access rights, versions and a history – the `.env` file is only a copy of it, and rarely the only one. And copies multiply: one `.env` on the laptop, a second in CI, a third in the onboarding wiki, a fourth as a screenshot in a chat, a fifth “only on my machine”. At some point, nobody knows which value is authoritative anymore. That is where the bugs come from that can’t be reproduced, and the onboarding days you never get back. `ssmenv-cli` draws a consequence from this: the AWS Systems Manager Parameter Store holds the authoritative values, and the tool only translates them into the environment of a process. ## The problem behind the tool The classic pattern is the shared `.env` note. It works on day one and slowly falls apart afterwards. I know the typical symptoms by heart: a secret accidentally ends up in the Git history. A new colleague gets an outdated copy and loses half a day to “it doesn’t run for me”. A value is changed in production but not documented anywhere traceable. And nobody can say offhand who actually has the right to read a production secret. At its core, this isn’t a tooling problem but a boundary problem. There is no clear answer to three questions: Which data is authoritative? Who may read and change it? Where does a change become traceable? As long as these boundaries stay blurry, even the nicest script won’t help. So the three questions come before the tool. ## The decision: SSM as the single source The load-bearing decision is: the AWS Systems Manager Parameter Store becomes the single source for configuration and secrets. Not Git, not the laptop, not the chat – a hierarchical namespace in AWS that is already there anyway if you deploy there. That is a deliberate choice against a system of my own and against a large additional product. The Parameter Store brings exactly what I need for this boundary: a hierarchy via paths such as `/myapp/prod/DATABASE_URL`, encryption of sensitive values via KMS as `SecureString`, access control via IAM and a complete record via CloudTrail. That answers the three open questions from above without me operating a single line of infrastructure myself. All that is missing now is the last mile: the way from the Parameter Store into the environment variables of a process. Exactly that – and nothing more – is the CLI’s job. ## Architecture: a thin adapter, not a platform The most important architecture decision about `ssmenv-cli` is what the tool deliberately does *not* do. It stores nothing, it decides on no permissions, it holds no state. It is a thin adapter between an authoritative data source and the 12-factor principle “config in the environment”. This separation is the actual boundary. The Parameter Store is the store of truth. IAM is the permission boundary. KMS is the confidentiality boundary. The CLI is pure translation: it reads a path prefix, resolves `SecureString` values and provides them to a process as its environment. Because the tool itself has no authority, I can swap it out at any time without anything changing in the security or data model. That is the value of a cleanly drawn boundary: it makes the tool replaceable. ## A small example The practical core fits into a few lines. You set values once – ideally through automation, here by hand for illustration: ```bash # Store a secret as an encrypted SecureString under a namespaced path ssmenv set --path /myapp/prod DATABASE_URL "postgres://db.internal:5432/app" # List everything under a prefix (values masked by default) ssmenv list --path /myapp/prod ``` The real gain shows when loading. Instead of distributing a file, you resolve the environment at runtime: ```bash # Run a process with the resolved environment, nothing written to disk ssmenv exec --path /myapp/prod -- node server.js # Or export into the current shell for a quick local session eval "$(ssmenv export --path /myapp/staging)" ``` And because two environments are rarely identical, comparing them is a full-fledged command and not an afterthought: ```bash # Show which keys differ between staging and prod ssmenv diff --path /myapp/staging --path /myapp/prod ``` The example is deliberately small. It doesn’t simulate a complete platform; it shows the boundary: the CLI only touches the last mile between store and process. A good example isn’t the one with the most options but the one where you can discuss the decision after five minutes. ## Sketch ```mermaid flowchart LR Store["SSM Parameter Store
    /myapp/prod/*"] --> CLI["ssmenv-cli
    thin adapter"] IAM["IAM
    permission boundary"] --> CLI KMS["KMS
    SecureString decrypt"] --> CLI CLI --> Env["process env"] Env --> App["node server.js"] ``` The sketch makes the responsibilities visible: the store holds the truth, IAM and KMS draw the boundaries, the CLI translates. No box in this picture depends on a tool name – that is intentional. ## Trade-offs: why small, why not more The obvious counter-question is: why not go straight for a full-fledged secret management product? That is a trade-off, not dogma. A large system brings rotation, dynamic credentials and fine-grained policies – plus operations, a learning curve and another dependency. For many teams that deploy on AWS anyway, that is more machinery than the problem calls for. I build the smallest solution that cleanly answers the three boundary questions and leave room for a switch. Because `ssmenv-cli` is only an adapter, that switch is cheap. If a team later needs rotation on a large scale, I swap the backend store, not the mental model. The expensive decision – configuration is central, access-controlled and auditable – stays the same. That is exactly what a trade-off should look like: start small without blocking the way to expand. The second trade-off concerns network dependency. Resolving values from the store at runtime means that a process start requires AWS to be reachable. That is a deliberate choice: I trade a short network call at startup for the permanent danger of outdated local copies. For local offline work, there is still an explicit export – a visible exception that someone has to trigger deliberately. ## Operational consequences The consequences of an architecture don’t show in the demo but in failures, load, rollback and review. Here the model holds, because the heavy tasks sit where they belong. Access is an IAM question. Who may read `/myapp/prod/*` is written in a policy and not in a chat history – and can therefore be checked and revoked. Confidentiality is a KMS question: sensitive values are stored encrypted as `SecureString`, and the CLI only decrypts if the caller has the right to do so. Traceability is a CloudTrail question: every read and write access is recorded. When someone asks “who read this secret when?”, there is an answer instead of a shrug. Reversibility is the strongest point. Because the Parameter Store keeps versions, a wrongly set value isn’t an emergency but a rollback to the previous version. That makes a change to configuration as manageable as a change to code. ## Failure cases An idea is only robust once the failure path is described. Three cases belong to it. Missing permission: if the caller isn’t allowed to read the path, the CLI must abort hard and clearly. An empty value that silently slips through as an empty string is the most dangerous bug – the application starts with half its configuration and only falls over deep in operation. An `exec` must therefore fail on missing or unreadable keys before the target process even starts. A partially resolved environment: if only nine of ten expected keys are there, that isn’t “almost right” but wrong. I treat it as an error with a clear message about which key is missing. Network and region errors: an unreachable store or a wrong region must not pass through a cryptic SDK exception but a message that names the path and the cause. The difference between demo and operations almost always lies in exactly these unexciting error messages. ## The same boundary in CI The real test of a configuration boundary is the pipeline. In CI, it isn’t a human with personal permissions that runs but a role – and that is exactly what makes the model clean. Instead of duplicating secrets as CI variables, the build job gets an IAM role that may read exactly the path it needs, and no other. A staging deploy sees `/myapp/staging/*`, a production deploy `/myapp/prod/*`, and the separation isn’t a convention but a permission. ```bash # In CI: the job's role grants read on /myapp/staging/* only ssmenv exec --path /myapp/staging -- npm run deploy ``` That makes the whole class of “the secret now also lives in CI” copies disappear. There is no second source that can go stale, and the principle of least privilege applies to machines just as it does to people. If a CI token is compromised, the damage is limited to exactly the path this job was allowed to read – traceable in CloudTrail, revocable in a policy. That literally the same command runs locally, in CI and in production, just with a different path, is the core of reproducibility. ## Business outcome: shorter cycles, less friction The benefit is measurable, even if the tool is small. Onboarding that used to mean “get the current `.env` from somebody” becomes a single command against a path – half a day of friction turns into minutes. The whole class of “works for me, not for you” bugs disappears, because dev, CI and production use the same authoritative source and differ only in the path prefix. And the risk of leaving a secret in the Git history drops structurally, because there is no longer any reason to put secrets in files that get versioned. These are the three levers that count for technical decision-makers: shorter cycles when setting up and switching environments, less friction in everyday work and higher quality through reproducible configuration. The gain isn’t in the tool’s name but in the decision to treat configuration like a verifiable data system. ## The pattern for small CLIs `ssmenv-cli` deliberately stays an adapter. Whether the Parameter Store can really be the authoritative source is decided by write permissions, the handling of versions and the behavior when it’s unreachable. The CLI solves none of these questions; it only makes the answer that was chosen usable for local processes and CI. That’s why I prefer to build many small, sharply delimited CLIs rather than one large, blurry framework. Each does one job, has a visible boundary and at least one honest failure case. The same way of thinking is in `ssmenv-cli`: small in scope, clear in responsibility, replaceable in detail. Big order doesn’t come from big tools but from many small ones with clear responsibilities. ## Closing More important than how `ssmenv-cli` works is where the boundary runs: configuration central and auditable, the tool deliberately thin and replaceable. This decision still holds when the tool has long been replaced by another one – and that is exactly why you can reuse it in the next team conversation. ## Further reading - Repository ssmenv-cli: https://github.com/MikeBild/ssmenv-cli The source helps you cross-check the concrete implementation. --- # GitHub Actions with AWS CDK URL: https://www.mikebild.dev/en/blog/github-actions-with-aws-cdk/ Date: 2020-01-12 # GitHub Actions with AWS CDK Two commands carry this setup: `cdk diff` in the pull request and `cdk deploy` on `main`. The first changes nothing and shows everything – new resources, changed permissions, deleted tables. The second changes everything and shows nothing that was not already in the review. **Editorial note (July 2026):** The workflow and CDK code show the state of January 2020: Actions v1, Node 12, CDK v1 and permanently stored AWS keys. A setup today calls for current action versions, CDK v2 and short-lived AWS credentials via OpenID Connect in the workflow. The review idea around `cdk diff` is not affected by this. This order holds the difference between automation and architecture. Connecting GitHub Actions and AWS CDK takes an hour. What is more interesting is which decision it brings to the table earlier. ## Why this combination is more than automation GitHub Actions has been generally available for a few weeks, and the obvious reaction is to rebuild the familiar flow with it: build the tests, package the artifact, deploy via script. That works, but it gives away the real lever. Because with AWS CDK, I describe my infrastructure in the same TypeScript repository as my application – Lambda, API Gateway, IAM roles, tables. That turns infrastructure into code that can be reviewed, versioned and tested like any other. The point I care about only emerges from the interplay. When application code and infrastructure code sit in the same pull request and run through the same pipeline, a change is no longer “new handler” plus “someone clicks a role together in the console later.” It is a single, traceable unit. The code change and its operational consequence sit side by side before anything goes to production. That is the architectural gain – not the clicks saved. This boundary is often drawn somewhere else. Infrastructure then lives in a wiki, in terminal commands, in the heads of two people. The pipeline deploys the code, but nobody in the review can say which permissions, which resources and which costs a change brings with it. CDK plus GitHub Actions turns this question into an artifact you can discuss. ## Approval comes before the workflow Before I write YAML, I clarify three concrete points: Who may trigger a deployment? Which changes must be visible in the pull request? And what is the way back if the new stack does not hold? GitHub Actions answers none of these questions. The workflow only enforces the answers. If, for example, a protected environment with approval is missing, `cdk deploy` on `main` quickly becomes an automatism that is faster than the control behind it. ## `cdk diff` as a review artifact For me, the methodological core of this combination is a single command: `cdk diff`. It compares the synthesized CloudFormation state with what is actually running in AWS and shows the difference – new resources, changed permissions, deleted tables. If I pull this command into the pull request run, every review gets an honest preview of the operational consequence. That noticeably changes the quality of a review. A reviewer does not just see that a handler is being added but that this handler brings along a new IAM policy with `dynamodb:*`. This line in the diff is the moment a bad decision stands out – before the merge, not in the next security audit. I thereby move an error from “expensive and late” to “cheap and early,” and that is the concrete effect this is about. The diff also uncovers a class of problems that otherwise stays invisible: drift. If someone changes a resource by hand in the console, the real state deviates from the code. Without a diff, nobody notices until a deployment silently overwrites the manual change and something breaks that “was still working yesterday.” With the diff in the pull request, this deviation becomes a visible signal – and an opportunity to ask the real question: why was someone working in the console, and how do I bring this change back into the code where it belongs? The diff is thus not just a review tool but a quiet way of disciplining the whole team toward “the code is the truth.” ## A small stack The basis is a deliberately small stack – a Lambda behind an API Gateway. It is not meant to simulate a complete application but to show the boundary. ```ts import * as cdk from "@aws-cdk/core"; import * as lambda from "@aws-cdk/aws-lambda"; import * as apigw from "@aws-cdk/aws-apigateway"; export class ApiStack extends cdk.Stack { constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); const handler = new lambda.Function(this, "ApiHandler", { runtime: lambda.Runtime.NODEJS_12_X, handler: "index.handler", code: lambda.Code.fromAsset("dist/api"), timeout: cdk.Duration.seconds(10) }); new apigw.LambdaRestApi(this, "Api", { handler }); } } ``` What is interesting is less what is here than what is not here. `LambdaRestApi` is a construct that creates an API, an integration and the matching execution role in the background. That is the value of a good abstraction: it reduces repetition and encapsulates sensible defaults. And that is also its risk – it must not hide which resources, permissions and costs actually come about. `cdk diff` is exactly the control that makes the hidden visible again. A good example has few features and one point you can argue about after five minutes. The `timeout` is such a point: ten seconds is an operational decision, not a detail, and it belongs in the code, not in a verbal agreement. ## The pipeline The pipeline has two jobs that I keep cleanly separate. In the pull request, it shows the diff without changing anything. On `main`, it deploys. This separation is not cosmetic – it ensures that the preview has no consequences and the deployment has a clear trigger. ```yaml name: deploy on: push: branches: [main] pull_request: jobs: diff: if: github.event_name == 'pull_request' runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - uses: actions/setup-node@v1 with: node-version: "12" - run: npm ci - run: npm run build - run: npx cdk diff env: AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_DEFAULT_REGION: eu-central-1 deploy: if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - uses: actions/setup-node@v1 with: node-version: "12" - run: npm ci - run: npm run build - run: npx cdk deploy --require-approval never env: AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_DEFAULT_REGION: eu-central-1 ``` The credentials are stored as GitHub secrets in the repository and passed to the CDK CLI via environment variables. That is the pragmatic route I take today – and at the same time the place with the greatest responsibility; more on that in a moment. The flow as a sketch: ```mermaid flowchart LR PR[Pull request] --> Diff[cdk diff
    visible in review] Diff --> Merge[Merge to main] Merge --> Build[Build + synth] Build --> Deploy[cdk deploy] Deploy --> CFN[CloudFormation
    Change Set] CFN --> Observe[Logs + metrics] ``` ## An environment you can reproduce As soon as the first stack is running, the question of staging and production comes up. And this is where it shows why infrastructure as code is more than a more convenient deployment. Because my stack is a TypeScript class, I can parameterize it and instantiate it twice – the same definition, different names, different accounts. Staging is then, by construction, an exact copy of production, not an environment that slowly drifts apart over months until nobody knows anymore which difference was intended and which was chance. This is one of the methodological consequences I value most. The classic break between “works on my machine” and “works in production” almost always comes from environment differences that nobody documented. When the environment itself is versioned, this break does not disappear completely, but it becomes a question I can answer in the repository instead of a puzzle I solve under time pressure in the production system. That is exactly why, for me, CDK belongs to the topic of reproducibility. The deployment steps saved are just the visible side effect. ## Permissions that do not grow with every convenience The most tempting shortcut is a deploy identity with `AdministratorAccess`. It always works, it never explains an error, and it is the reason a compromised repository becomes a compromised account. The trade-off is real: a narrowly cut role means that a deployment occasionally fails on a missing permission and I have to tighten things up. But this failure is cheap and instructive, while silent full access only gets expensive once. Serverless moves operational work; it does not remove it. Permissions, logs, cold starts, timeouts, costs and the ability to roll back still have to be designed explicitly. The difference is that with CDK I design them in the same review in which I write the handler – instead of postponing them to “we’ll do it later.” In practice, “later” is the name for “never.” ## Rollback and the happy-path fallacy That leaves overrating the happy path. Many pipelines look clean as long as every deployment succeeds. It gets interesting with partial failures: one resource is created, the next one fails, and the stack is stuck halfway. What helps here is that CDK builds on CloudFormation. A failed deployment rolls back to the last consistent state, and this behavior is part of the platform, not of my script. That is a strong reason to stay with CDK instead of stringing individual resources together with imperative CLI calls: I get a defined transaction boundary for free. Still, I have to know it. A deployment that migrates data is not automatically reversible just because the stack is – the question of idempotency and repeatability remains mine. ## What changes measurably as a result When these parts work together, the work changes noticeably, and in a direction I can explain to a technical decision-maker. The cycle from “idea” to “running in production” gets shorter because there is no longer a manual handover step between code and infrastructure. Friction in the team drops because nobody holds deployment knowledge as personal gatekeeping knowledge anymore – it lives in the repository. And quality rises because `cdk diff` moves an error to where it is cheap: into the pull request. Concretely, it looks like this: in a team without this setup, an infrastructure change takes as long as the available person with AWS access needs – plus the time until someone notices that the change turned out differently in staging and production. With the pipeline, the same change is a pull request that two colleagues can read without having console access themselves. The “one person with permissions” bottleneck disappears, and with it the silent queue that nobody ever sees on a board. That is developer productivity in the literal sense: not typing faster, but fewer handovers, fewer follow-up questions, fewer states in which someone is waiting for someone else. That is the arc from mechanics to effect. GitHub Actions and CDK are interchangeable tools. The reusable decision behind them – treating infrastructure as a reviewable part of every change – is not. ## What I check in the review When reviewing this setup, I ask three questions. Does the pull request show the operational consequence, that is, the diff, or only the application code? Is the deploy identity cut so narrowly that I can explain a permission error instead of configuring it away? And is it clear what happens when a deployment has run halfway? If one of these questions remains open, the pipeline is still missing something – a visible diff, a sharper role or a clarified rollback path. A construct should reduce repetition and encapsulate good defaults, but never obscure which resources, permissions and costs come about. It is exactly at this edge between convenient abstraction and honest visibility that it is decided whether the combination holds. ## Further reading - AWS CDK Developer Guide: https://docs.aws.amazon.com/cdk/latest/guide/home.html - AWS CDK Constructs: https://docs.aws.amazon.com/cdk/latest/guide/constructs.html - [GitHub Actions: OpenID Connect with AWS](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws) - Repository aws-cdk-js-github-action: https://github.com/MikeBild/aws-cdk-js-github-action The sources help you cross-check platform behavior. The actual statement remains the architecture decision in the concrete example. ## Closing Bringing GitHub Actions and CDK together is done quickly. The return lies in the boundary between application and platform moving into the pull request. That is where the benefit arises for developers, architects and technical decision-makers. It hinges on a reusable decision: taking infrastructure as seriously as the code that runs on it. The tool name is interchangeable. --- # PouchDB and Offline-First URL: https://www.mikebild.dev/en/blog/pouchdb-and-offline-first/ Date: 2019-11-12 # PouchDB and Offline-First Offline is treated as a special case: first finish building the application, then shortly before the release put a cache in front of it, catch failed requests, show a “You are offline” banner. This assumption holds exactly until the first write without a network. Reads can be cached – writes cannot. As soon as a user is allowed to change a record on the train, the question is no longer how to cache responses but: Where does the truth live while the connection is missing? And what happens if two devices have changed the same record in the meantime? That makes offline-first not a feature checkbox you tick off at the end. It is an architecture decision that swaps out the application’s communication model: replication instead of request/response. The offline-first movement has been saying this for years – the term comes from the circle around hood.ie and offlinefirst.org, long before Progressive Web Apps brought the topic to a wide audience. Still, in everyday work it is often shortened to “service worker plus cache.” But the service worker solves only half of the task: it delivers the application itself without a network – HTML, JavaScript, CSS. The data is the real problem, and for that you need a different tool. ## Replication instead of request/response In the request/response model, the server is the single source of truth. The client asks, the server answers, and without a connection there simply is no state. In this model, every offline feature is a detour: a queue for pending POSTs, a cache for stale responses, retry logic, lots of special cases that cut across the actual application. In the replication model, this flips around. The application reads and writes exclusively locally, against a database in the browser. Synchronization is a separate process that runs in the background when a connection is available – and pauses when it is not. At first, the UI notices nothing of the network at all. ```mermaid flowchart LR subgraph rr["Request/Response"] UI1["UI"] -->|"HTTP request
    blocks without network"| API["API server"] API --> DB1[("central
    database")] end subgraph repl["Replication"] UI2["UI"] -->|"read and write
    locally"| LOCAL[("PouchDB
    IndexedDB")] LOCAL <-->|"sync when
    network is available"| REMOTE[("CouchDB")] end ``` The difference shows first in perceived speed: local reads and writes take milliseconds, regardless of dead zones, latency or server load. But the real gain and the real price lie elsewhere. The replication model accepts that at times there are several valid views of the same data. In it, conflicts are not an operational accident but an expected consequence of the architecture – and that is exactly why they belong in the domain model, not in an error handler. ## PouchDB in the browser, CouchDB at the other end PouchDB is a JavaScript database that builds on IndexedDB in the browser and replicates CouchDB’s HTTP API – including the CouchDB replication protocol. This protocol is openly documented and describes how two peers exchange their changes: read the changes feed, determine missing revisions, transfer documents, write a checkpoint. If the connection drops, the next run picks up at the last checkpoint, not at the beginning. That you can set up bidirectional synchronization with this in a few lines almost seems suspicious on first contact: ```js const localNotes = new PouchDB('notes'); const remoteNotes = new PouchDB('https://couch.example.com/notes'); localNotes.sync(remoteNotes, { live: true, retry: true }) .on('change', info => renderChange(info)) .on('paused', () => setSyncStatus('idle')) .on('active', () => setSyncStatus('syncing')) .on('error', err => reportSyncError(err)); ``` `sync` is nothing magical here, just two one-way replications, one in each direction. `live` keeps the changes feed open, `retry` bridges connection drops with backoff. The `paused` and `active` events work as an honest status display: `paused` means “everything transferred or no network right now,” `active` means “changes are flowing.” In small applications, I have truly never needed more sync code than this – the rest is conflict handling, more on that shortly. Important for putting this in context, as of today with PouchDB 7 and CouchDB 2.x: the replication protocol is not an internal detail but an interface. Anything that speaks it can participate – a CouchDB cluster, a second browser tab, a Node process with express-pouchdb in front. Synchronization logic thus becomes infrastructure. What remains in the application is the domain question that no library can answer: What does it mean when two states diverge? ## The revision tree The core of the model is the versioning of every single document. Every change creates a new revision, and every write must name the revision it wants to continue. If that does not match, the database rejects it immediately: ```js async function saveNote(note) { try { await localNotes.put(note); } catch (err) { if (err.status !== 409) throw err; // optimistic locking: fetch the current revision and retry once const current = await localNotes.get(note._id); await localNotes.put({ ...note, _rev: current._rev }); } } ``` This 409 is the immediate conflict: two writers on the same database, classic optimistic locking, easy to handle. The second case is more interesting. Two devices change the same document offline, both writes are perfectly valid locally, and only replication brings the states together. Then a revision tree with two branches appears in the document: ```mermaid graph TD R1["Rev 1-a4f
    shared starting state"] --> R2A["Rev 2-c91
    changed on device A"] R1 --> R2B["Rev 2-b07
    changed on device B"] R2A --> R3["Rev 3-e12
    merge
    by the application"] R2B -. "losing branch
    is kept" .-> R3 ``` In this situation, CouchDB and PouchDB deterministically choose a winner: the longer revision path wins; on a tie, the lexicographically higher revision hash. Deterministic means every node arrives at the same result without coordination – a cluster needs no consensus algorithm for that. It explicitly does not mean: correct for the domain. The losing branch is not deleted either but stays attached to the document as `_conflicts`. The database keeps both states and waits for someone to decide. That “someone” is the application. ## Conflicts are the normal case This is where cache thinking finally parts ways with the replication model. If you retrofit offline capability, you treat conflicts as errors that should ideally not occur. If you replicate, you treat them as an ordinary event with a domain answer. The database cannot give that answer, because it does not know what the data means. Whether the longer text wins for a note, whether two shopping lists can be combined as sets or whether a human has to decide – that lives in the domain model, nowhere else. The resolution itself is mechanically unspectacular: fetch the conflicting revisions, merge them, write the result, remove the losers. ```js async function resolveConflicts(id) { const winner = await localNotes.get(id, { conflicts: true }); if (!winner._conflicts) return winner; const losers = await Promise.all( winner._conflicts.map(rev => localNotes.get(id, { rev })) ); const merged = mergeNotes(winner, losers); // domain-specific merge await localNotes.put(merged); await Promise.all( losers.map(loser => localNotes.remove(loser._id, loser._rev)) ); return merged; } ``` What matters is `mergeNotes` – and that this function exists at all. In code reviews, I have noticed that exactly this function is almost always missing: sync built in, demo running, and the conflict case gets pushed to later because it simply does not occur during development. A single developer with one device and stable Wi-Fi produces no conflicts. Two field reps with tablets in a dead zone produce them on day one. If the resolution is missing then, the deterministic algorithm silently wins, and from the user’s point of view the loser’s changes have vanished – not deleted, but invisible. That is the most expensive kind of bug: no crash, no log entry, just quiet data loss from the point of view of the person in front of the screen. That is why a conflict strategy also needs a visibility strategy. A small indicator saying “three changes waiting to sync” costs little and noticeably changes trust in the application. Users forgive waiting times when they can see where they stand. ## What this does to the data model Replication and conflicts feed back into how you split documents. A document is the unit that gets replicated and fought over – so it pays to split documents in a way that makes conflicts rare and, when they do occur, resolvable. A few rules have proven themselves for me: - One document per domain unit that a user edits in one go – no collective document for half the application state. - Meaningful IDs like `note:2019-11-12` instead of pure random UUIDs where the domain allows it; that makes direct access predictable and saves you some indexes. - Append instead of overwrite where possible: if you write events as new documents instead of changing an existing one, you structurally get fewer conflicts. - Treat deletions as part of the model: deleted documents persist as `_deleted` revisions so that the deletion itself can be replicated. For queries beyond key access, there are Mango queries via pouchdb-find, now part of the standard build: ```js await localNotes.createIndex({ index: { fields: ['updatedAt'] } }); const recent = await localNotes.find({ selector: { updatedAt: { $gte: '2019-11-01' } }, sort: [{ updatedAt: 'desc' }], limit: 20 }); ``` On top of that comes a browser reality you should know about: IndexedDB storage is not guaranteed. The browser may clean up under pressure, and storage quotas differ significantly by platform. You can request persistent storage through `navigator.storage.persist()`, but I would not rely on it – the copy on the server remains the life insurance; the local database is the working state. ## Two experiences of my own In 2016, I used graphql-pouch to try out how far the idea could be pushed: a GraphQL runtime directly on PouchDB, Schemas in GraphQL shorthand notation, as a standalone service with CouchDB synchronization and master/master replication. The prototype showed me two things. First, how much backend the replication protocol replaces: sync endpoints, retry logic, delta calculation – all code I never wrote because the protocol brings it along. Second, that the conflict question catches up with you on the server side too. As soon as two instances replicate against each other, the “server” carries the same revision trees as the browser. So the architecture decision does not disappear when you push it to the server side; it only changes location. On the side, I have been maintaining the list awesome-pouchdb for a few years, where I collect tools, plugins and articles around PouchDB. The view of the ecosystem is itself a data point: a striking number of entries revolve around exactly the places where the model pinches – pouchdb-find for queries, express-pouchdb for your own sync endpoints, pouchdb-authentication for logging in against CouchDB. Where a community builds many tools, it is rarely a coincidence but a recurring problem. ## Where I would not use it As convincing as the model is for notes, forms and field service scenarios – it has clear limits, and you should know them before the decision, not after: - Fine-grained access rights: CouchDB authorizes per database, not per document. The usual remedy is one database per user, which noticeably complicates operations and server-side analysis. - Large amounts of data that need central analysis: what the browser holds has to be replicated there. For dashboards over millions of rows, the approach is the wrong tool. - Strictly consistent processes: account balances, inventory levels, bookings with hard invariants need central coordination. You cannot configure away eventual consistency. - Data that must not leave the device but would – or, conversely, must not be on it in the first place. Replication distributes copies; that is its purpose. Filtered replication can limit the amount of data per client, but it has its own price: the filter runs over the complete changes feed, and changing filters later is tedious. If you only want to synchronize a subset, you should take that into account early when splitting documents, for example with separate databases per tenant or project. ## Bottom line You decide on offline-first at the beginning of a project, not at the end – because document splitting, conflict behavior and the permission model depend on it. PouchDB and CouchDB take the mechanics off your hands completely: replication protocol, revision trees, checkpoints, resumption after a drop. What they do not take off your hands is the domain answer to the one question everything hinges on: What should happen when two devices have changed the same thing? If you have an answer to that, you get, with surprisingly little code, an application that works in a dead zone just as well as in the office. If you do not, you get one anyway – only then a hash comparison decides about your users’ data. ## Further reading - [awesome-pouchdb – curated list of PouchDB tools and plugins](https://github.com/MikeBild/awesome-pouchdb) - [graphql-pouch – GraphQL runtime on PouchDB with CouchDB sync](https://github.com/MikeBild/graphql-pouch) - [PouchDB Guide: Replication](https://pouchdb.com/guides/replication.html) - [PouchDB Guide: Conflicts](https://pouchdb.com/guides/conflicts.html) - [CouchDB Replication Protocol (official specification)](https://docs.couchdb.org/en/stable/replication/protocol.html) - [Offline First – offlinefirst.org](http://offlinefirst.org/) --- # Cleanly Separating Commands, Events and Queries URL: https://www.mikebild.dev/en/blog/separating-commands-events-and-queries/ Date: 2019-10-08 `updateOrder(...)` is not a domain message. The name doesn’t say whether someone wants something or whether something has already happened – it only describes that fields change. Method names like this are the reason models get blurry: request, fact and question travel under the same name through the same classes, and nobody can tell from the signature which of them is currently on its way. Command, event and query clean this up. The three differ in three points that you can check on every single message: in their tense, in whether they may be rejected and in the number of recipients. The following sections go through these points – first conceptually, then in TypeScript, then along the mistakes that regularly happen along the way. The form of a message follows its meaning. JSON objects that look the same can still carry completely different contracts. ::::comparison{title="Telling messages apart by what they state" role="primary" preferredPattern="comparison-matrix"} :::side{label="Command"} - Meaning · request to attempt a state change - Time reference · aimed at an intended future - Outcome · can be rejected or fail ::: :::side{label="Event"} - Meaning · a fact that has already occurred - Time reference · immutable past - Outcome · is not rejected after the fact ::: :::side{label="Query"} - Meaning · request for existing information - Time reference · view of the current or a specified state - Outcome · does not change the domain state ::: :::: This distinction makes names, error paths and responsibilities more precise before any framework comes into play. ## Three messages, three meanings Let’s start with the core, because this is where everything is decided. A command, an event and a query are fundamentally different things, even if they look superficially similar in code – in the end, each of them is an object with a few fields. The difference is not in the structure but in the meaning. A **command** is an imperative wish. “Do X.” `CreateOrder`, `ShipProduct`, `CancelReservation`. A command expresses an intention that has not happened yet. And this is crucial: a command is a request that can be rejected. It goes through validation and business rules, and if something isn’t right, it fails. Exactly one handler is responsible; a command is directed – it has an intended recipient. An **event** is the exact opposite on the timeline. It is a fact that has already occurred. `OrderCreated`, `ProductShipped`, `ItemOrdered` – named in the past tense. An event is immutable, because you can no longer change the past. And an event cannot be rejected: you cannot say “no” to something that has happened. It is the result of a successfully processed command. While a command has exactly one handler, an event can have zero, one or many consumers – it is a notification to potentially many. Finally, a **query** retrieves data without changing anything. `GetOrderSummary`. It returns a result and leaves the observable state of the system untouched – it is free of side effects. A query reads, ideally from a view optimized for reading, and can be repeated harmlessly as often as you like. This semantic separation is the whole point. Bertrand Meyer formulated it decades ago as Command-Query Separation: every method is either a command that changes state but returns nothing, or a query that returns something but doesn’t change state – never both. The event joins as a third kind when we want not only to order state changes but also to report on them. ## The name carries the semantics When I come across blurry models in reviews, it is almost always down to naming. The name of a message is not decoration – it is the semantics made visible. A command in the imperative, an event in the past tense. This discipline sounds trivial, but it is the cheapest and most effective lever I know. Let’s compare the three kinds directly: - A command is in the imperative and present tense (`CreateOrder`): an intention, directed at exactly one handler, that can be rejected and can fail. - An event is in the past tense (`OrderCreated`): a fact, immutable and not rejectable, directed at zero to many consumers. - A query usually starts with `Get` or `Find` (`GetOrderSummary`): a question, free of side effects; it returns data and changes nothing. Once a team has internalized this naming convention, the code almost reads itself. You see `CreateOrder` and know: someone wants something here that can go wrong. You see `OrderCreated` and know: this has already happened, I can count on it. The name replaces half the documentation. ## The flow: from wish to fact to answer So how do the three fit together? The typical flow is surprisingly straightforward. A command arrives and is checked by its handler. The handler validates and applies business rules. If everything checks out, it emits one or more events – the facts that follow from the successful command. These events then update the read model, the view for reading. And finally, a query reads from exactly this read model without touching the write path at all. Martin Fowler describes this as two separate paths: the changed state is routed through the command model, and the display comes from the query model. Writing goes via command to event, reading goes straight to the read model. ```mermaid flowchart LR C[Command: CreateOrder] --> H[Command Handler] H -->|validate / business rules| E[Event: OrderCreated] E --> RM[(Read Model)] Q[Query: GetOrderSummary] --> RM ``` In this picture, you can see the asymmetry that defines the whole approach. The write path is a process with a check: command, validation, and only then the fact. The read path is a direct query without a detour. Both share the read model, but they approach it from opposite sides – one writing via events, the other reading via queries. ## Cast in code Enough theory – let’s look at what this looks like in TypeScript. The following code is illustrative, not a runnable repository; it is meant to show the semantics, not to replace a framework. Let’s start with the message types themselves, modeled as discriminated unions: ```ts type LineItem = { sku: string; quantity: number }; type Command = | { type: 'CreateOrder'; orderId: string; customerId: string; items: LineItem[] }; type DomainEvent = | { type: 'OrderCreated'; orderId: string; customerId: string; occurredAt: Date }; type Query = | { type: 'GetOrderSummary'; orderId: string }; ``` You can already read the semantics from the types. The command is in the imperative. The event is in the past tense and carries an `occurredAt` – the point in time at which the fact occurred, because an event lives from its place in time. The query starts with `Get` and visibly carries nothing but a question. Now the command handler. It is the heart of the write path: it checks, decides and emits. What matters is that a command can be rejected – and that the return value is a list of events, because a command may well entail several facts: ```ts class RejectedCommand extends Error {} function handleCreateOrder(cmd: Extract): DomainEvent[] { if (cmd.items.length === 0) { throw new RejectedCommand('order needs at least one item'); } return [ { type: 'OrderCreated', orderId: cmd.orderId, customerId: cmd.customerId, occurredAt: new Date(), }, ]; } ``` This is where the semantics become concrete. The handler validates, and if the request cannot be fulfilled, it rejects it – the command fails before any fact comes into being. Only when the check passes is the event born. No event without passed validation; that is the order we want. On the other side is the query handler. It does exactly one thing: read. No mutation, no emitted event, no side effect: ```ts interface OrderReadModel { findSummary(orderId: string): OrderSummary; } type OrderSummary = { orderId: string; itemCount: number; status: string }; function handleGetOrderSummary( q: Extract, readModel: OrderReadModel, ): OrderSummary { return readModel.findSummary(q.orderId); // read only, no mutation, no events } ``` And to close the circle: how does the read model get its data in the first place? Through a projection that reacts to events. The projection takes an `OrderCreated` and updates the read view – this is how the fact flows from the write path into the view that queries later read: ```ts function applyOrderCreated( event: Extract, store: Map, ): void { store.set(event.orderId, { orderId: event.orderId, itemCount: 0, status: 'created', }); } ``` If you lay these four building blocks side by side – command type, command handler, projection, query handler – you see the entire flow at a glance. The command is the wish, the handler checks it, the event is the fact, the projection carries it into the read model, and the query reads from there. Every message has its place and its meaning. ## The pitfalls I keep seeing As clear as the theory is, the mistakes in practice are just as stubborn. I keep running into four of them. The most common one is **inverted naming**. An `OrderCreated` that is actually a command, or a `CreateOrder` that flies around as an event. As soon as that happens, the team loses the distinction between “intention that can fail” and “fact that has already occurred”. The name lies, and the model with it. When I find an event in the imperative in a review, that is my first red flag. The second pitfall is the **query with a side effect**. A supposed query that writes on the side, increments a counter or fires an event. That breaks the freedom from side effects that Meyer demands for queries. A query has to be harmlessly repeatable – if I call it twice, nothing in the system may change. As soon as a query mutates state, it is no longer a query but a command in disguise. The third mistake is conceptual: **confusing CQRS with Event Sourcing**. Separating command, event and query doesn’t need Event Sourcing. Nor does it necessarily need two databases or an asynchronous message bus. You can cleanly separate the three kinds of messages in a perfectly ordinary service with a single database. Greg Young sums up the relationship in one rule of thumb: you can use CQRS without Event Sourcing; if you use Event Sourcing, you practically need CQRS. Not the other way around. The fourth pitfall is the **anemic command as a setter**. An `UpdateOrder(status = 'shipped')` reveals nothing about the domain intention. Why is the status changing? Because the product was shipped. Then the command is called `ShipProduct`, not `UpdateOrder`. A command should express a domain intention, not a generic data manipulation. The difference between `UpdateOrder` and `ShipProduct` is the difference between a form and a story. ## A quick look beyond: CQS, CQRS and the costs So that the terms don’t get mixed up, a clean distinction pays off. **CQS** – Command-Query Separation according to Meyer – is a principle at the method level: every method is either a command or a query. **CQRS** – coined by Greg Young and popularized by Fowler – lifts the same principle to the object or service level: a separate model for writing and a separate model for reading. Fowler puts it this way: you can use a different model to update information than the model you use to read information. And that comes with a sentence that often gets lost: CQRS is not a default. Fowler explicitly warns that CQRS adds risky complexity and is only justified when there is a clear benefit. Separate models, possibly separate stores, asynchronous consistency – you don’t want that everywhere. If you introduce CQRS everywhere by reflex, you take on more problems than you solve. I have described in more detail elsewhere why [CQRS is a domain boundary, not a framework](https://www.mikebild.dev/en/blog/cqrs-is-a-domain-boundary-not-a-framework/) – the decision for separate models belongs at the domain consistency boundary, not in every service. The good news: the purely semantic separation of command, event and query costs almost nothing and almost always pays off. It is not CQRS. It is the conceptual hygiene that CQRS can later build on, if you need it at all. You can name commands in the imperative, events in the past tense, keep queries free of side effects – and stay in a completely conventional service while doing so. This clarity in the small is the real gain. ## The common thread The question from the beginning – does someone want something, or has something happened? – can be answered for every message as soon as it carries an honest name. A command is the wish that gets checked and can fail. An event is the fact that follows from it, immutable and not negotiable. A query is the question that reads without touching. Three messages, three meanings, three names – and the name carries the meaning outward. This separation is not a big architecture project. It starts with discipline in naming and with refusing to let a query secretly write. You don’t have to introduce Event Sourcing or set up two databases to reap the benefits. If you consistently distinguish between `CreateOrder`, `OrderCreated` and `GetOrderSummary` in your next model, you have already done most of the work. Everything else – CQRS, projections, separate stores – is a question you ask later, and only when there is a real need. The semantic separation itself costs nothing but attention, and that attention pays off in every model. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-cqrs-event-sourcing.en.html - Martin Fowler, [CQRS](https://martinfowler.com/bliki/CQRS.html) – the compact definition, including the warning about complexity. - Martin Fowler, [CommandQuerySeparation](https://martinfowler.com/bliki/CommandQuerySeparation.html) – Meyer’s original principle at the method level. - Martin Fowler, [What do you mean by “Event-Driven”?](https://martinfowler.com/articles/201701-event-driven.html) – on classifying events as messages and facts. - Greg Young, [CQRS](https://gregfyoung.wordpress.com/2012/03/02/cqrs/) – the origin of the object/service level and the relationship to Event Sourcing. - Vaughn Vernon, *Implementing Domain-Driven Design* (2013), chapter on domain events – on naming events and their meaning in the domain. - My own talk material “CQRS + Event Sourcing” (SlideShare) – the slides in which I go through this separation in more detail. --- # Infrastructure as Code Needs Code Reviews URL: https://www.mikebild.dev/en/blog/infrastructure-as-code-needs-code-reviews/ Date: 2019-09-24 # Infrastructure as Code Needs Code Reviews If you wave a wildcard permission through, you have granted it. The merge is the moment of decision, not the audit a year later in which the same line gets marked red. And this moment looks harmless: a few changed lines, a green build, a thumbs-up. The trigger is the AWS CDK, which became stable this summer. With it, I no longer describe cloud infrastructure in a thousand lines of YAML but in TypeScript – with types, functions and abstractions. That is noticeably more productive, and that is exactly the catch. Because a change to the infrastructure now looks like any other pull request. But what is in this inconspicuous diff is not a Feature Flag. It is an IAM policy, a security group or the memory allocation of a function that is billed per invocation. The friction of making changes has dropped – the risk per change has not. This widening gap is the real topic. ## What Infrastructure as Code really changes Before, infrastructure lived in click sessions in the console and in the heads of two or three people. Nobody could review a change, because there was no diff. Whoever opened a rule in a security group left no traceable trail. Outages turned into archaeological digs: Who changed what and when, and why? Infrastructure as Code turns this around. Every change becomes a commit, every commit is versioned, every version can be checked. The real gain is not the nicer syntax. It is that infrastructure is finally subject to the same control mechanisms as the rest of the system. Rollback becomes a `git revert`, traceability becomes a `git blame`, knowledge becomes a readable repository instead of a conversation at the bar. The catch: review discipline did not automatically grow along with this shift. We have been reviewing application code for years with a clear eye for side effects, edge cases and security. With infrastructure code, many teams read the same diff with half their attention, because it looks short and the build is green. With IaC, though, a green build only means that synthesis ran through – not that the resulting infrastructure is secure, affordable and can be rolled back. ## The diff I really have to review CDK works with constructs: building blocks that encapsulate one or more CloudFormation resources along with sensible defaults. That is the strength and the trap at the same time. A high-level construct can create a dozen resources from three lines of TypeScript – a function, a log group, an execution role, a few permissions. The TypeScript diff shows me the intent. It does not show what actually gets provisioned. The real review artifact is therefore the `cdk diff`, not the code alone: the comparison of the current and planned CloudFormation state. Only there does it become visible that an inconspicuous line creates a role with a wildcard permission or opens a security group. ```ts const handler = new lambda.Function(this, "ApiHandler", { runtime: lambda.Runtime.NODEJS_10_X, handler: "index.handler", code: lambda.Code.fromAsset("dist/api") }); ``` These four lines are deliberately small. But they create more than a function: a log group, an execution role with basic permissions and the links between them. The review question is not “does the handler run?” but “which permissions does this role get, how long do the logs stay around, and what does an invocation cost?” A good construct reduces repetition and encapsulates good defaults – but it must not hide which resources, permissions and costs arise. That is exactly the boundary I check in the review. ## The most expensive line is often a permission The classic mistake is the convenient permission. It works right away if I give a function broad access, and nobody notices in the demo that the boundary is drawn too wide. ```ts // convenient, and wrong bucket.grantReadWrite(handler); table.grant(handler, "dynamodb:*"); ``` That runs. It is also the kind of line that gets marked red in a security audit a year later. Least privilege is not a chore for later. The decision about it is made in the review, at the moment of the merge – after that, the role is in operation, and “I will tighten it later” rarely turns into anything. That is why I ask concretely in the review: Does this function really need write permissions, or only read? Does it need the whole table or one action? Every wildcard is a claim that needs evidence. The pattern repeats with public buckets, open security groups and shared secrets. None of these mistakes is technically difficult. All of them are cheap to prevent if someone reads the diff with the right question – and expensive if nobody does. ## Cost belongs in the review With serverless infrastructure, the bill is a direct result of lines of code. A function’s memory size, provisioned concurrency, a NAT gateway, an instance type chosen too large, a retention setting that keeps logs forever – all of these are one-line changes with an ongoing monthly consequence. I have seen a single changed line double a team’s cloud bill because a default was adopted without thinking. The diff was inconspicuous, the build green, the review a formality. Cost transparency in the review does not mean predicting every bill. It means asking the question at all: What does this line change about the running costs – one-time, per invocation or per month? Serverless shifts operational work; it does not remove it. Permissions, logs, cold starts, timeouts, cost and the ability to roll back still have to be designed explicitly. ## What I look for in an infrastructure review Across the individual examples, I always check the same boundaries. Is the permission as narrow as possible, or does the diff open more than the task needs? How big is the blast radius if this resource is misconfigured – does it hit one service or the entire account? Is the change idempotent and reversible, or does a second deployment create a different state than the first? What happens on a failed deployment – is there a clean way back, or does someone have to repair things by hand at night? And does operations produce enough signals – logs, metrics, alarms – to explain an error later at all? These questions seem dry. But they are the difference between a system that looks clean in the demo and one that holds up under repetition, partial failures, old data and wrong permissions. The happy path is never the problem. Infrastructure gets interesting exactly where something goes wrong. ## The trade-off of abstraction CDK offers constructs on several levels: thin wrappers around individual CloudFormation resources, convenient building blocks with good defaults and entire patterns made of several resources. The higher the level, the less code I write – and the more decisions I delegate to defaults I do not see. That is not an argument against abstraction. It is an argument for choosing the level of abstraction deliberately and making it visible in the review. A high-level construct is a good trade if its defaults match my requirements for security and cost. It is a bad trade if I have never checked its defaults and get to know them by surprise in production. The methodical consequence is simple: the `cdk diff` belongs in every pull request, so that the level at which I delegate does not stay implicit. ## Where the review belongs in the pipeline ```mermaid flowchart LR Source --> Synth Synth --> Diff["cdk diff"] Diff --> Review["Review
    Permissions · Cost · Rollback"] Review --> Deploy Deploy --> Observe ``` The diff is not a formality at the end. It is the place where the review takes hold: before the deployment, as a visible artifact in the pull request. This moves the error from operations into the review phase – and that is the whole point. A configuration error that stands out in the diff costs ten minutes of discussion. The same error in production costs an incident, a night shift and trust. ## What the machine checks, what the human checks A good review process does not waste human attention on things a rule can handle. Much of an infrastructure review is mechanical and can be automated: open security groups, unencrypted buckets, wildcard policies, missing log retention. Static analysis of the synthesized CloudFormation template – for example with cfn_nag – catches this class of errors in the pipeline before a human even looks at it. Because the infrastructure is now code, I can also pin down assumptions as tests. CDK allows assertions against the synthesized template: “this role must not contain a wildcard action,” “this bucket is not public.” Such a test fails as soon as someone loosens the boundary – not only in the audit a year later. It is the same reflex I know from application code: what was right once and has to stay right becomes a test, not a mnemonic. Automation does not take the work away from the human review; it focuses it. When the machine enforces the same rules every time, the human can concentrate on what no rule can decide: Is this level of abstraction the right one? Is the blast radius acceptable? Does the cost consequence fit the task? These questions are exactly why the review exists at all. ## The mistake of taking the tool for the solution A tool does not create good architecture; it can only express it. CDK is not a security concept. CloudFormation is not a permission model. Serverless is not an operations strategy. These tools make it easier to draw good boundaries – they do not draw them by themselves. If you believe that switching to Infrastructure as Code settles the security and cost question, you have only changed the medium in which the same decisions are now made faster and less visibly. That is exactly why Infrastructure as Code needs the review more, not less. The low friction that makes the whole approach so attractive is at the same time its biggest risk. Changing has become cheap – understanding has to stay. ## What it gives the team The benefit is measurable, even if it shows up as an absence. Errors that used to appear as incidents now show up as comments in a pull request. The cloud bill stays predictable, because cost changes are named instead of discovered. Onboarding gets shorter, because new people read the infrastructure instead of guessing. And lead time even drops: there is not less checking; there is less to repair. A review costs minutes. An open bucket, a wildcard role or a doubled NAT gateway costs days and, in the worst case, customer data. Infrastructure as Code has finally brought infrastructure into a format in which this trade pays off. It would be a shame to skip the review as the only step that turns a diff into a decision. ## Further reading - AWS CDK Developer Guide: https://docs.aws.amazon.com/cdk/latest/guide/home.html - AWS CDK Constructs: https://docs.aws.amazon.com/cdk/latest/guide/constructs.html The sources help you double-check platform behavior and defaults. But the actual decision is not in the docs. It is in the concrete diff – and it depends on someone reading it before it goes live. --- # Secrets in the Build Are Product Decisions URL: https://www.mikebild.dev/en/blog/secrets-in-the-build-are-product-decisions/ Date: 2019-09-12 # Secrets in the Build Are Product Decisions ```console $ docker history --no-trunc myapp:staging IMAGE CREATED BY /bin/sh -c #(nop) COPY file:3f2a… in /app/.env /bin/sh -c #(nop) ENV DATABASE_URL=postgres://app:S3cr3t@db.prod.internal:5432/app ``` Two lines of layer metadata, readable by anyone with pull rights on the registry. In one project, half the configuration lived in an `.env` file that was copied into the image via `COPY`. That went well for months, until someone pulled the image from the registry, ran `docker history` and read the database URL including the password in plain text. No attack, no exotic bug – just an artifact that knew more than it was allowed to. The mistake wasn’t forgotten encryption. The mistake was an unspoken boundary: the team had never decided whether a build artifact may know secrets. It had just copied a tutorial. And that is exactly where this stops being an operations question. Where a token, a password or a certificate is created, stored and injected into an artifact determines who may deliver without checking with anyone and who has to wait. That decides a team’s speed, friction and error rate – long before any tool has been chosen. ## The real question is trust, not encryption Encryption solves a narrow problem: protecting data at rest and in transit. It doesn’t answer the question that gets expensive in everyday work – who in the process gets their hands on the secret at all. A KMS-encrypted value that every CI job may decrypt is convenient and still an open boundary. Before I choose a tool, I clarify four questions. Which component is authoritative for the value? Who may read it, and in which environment? When is it read – at build time or at runtime? And what has to be traceable later if it is compromised? These answers decide rotation and blast radius. Encryption alone answers none of them. ## Build time and runtime are two different trust zones The most important boundary runs between build and runtime. A build produces an artifact that travels through several environments and lands in a registry that more people often have access to than you’d think. Everything baked into this artifact is therefore exactly as confidential as the registry – and no more. The classic anti-pattern looks harmless: ```dockerfile # ANTI-PATTERN: the secret becomes part of a shared, promotable artifact COPY .env /app/.env ``` ```dockerfile # ANTI-PATTERN: build args stay recoverable via `docker history` ARG NPM_TOKEN RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc \ && npm ci \ && rm .npmrc ``` The `rm` fakes security. The token remains visible in the layer metadata, and the `.env` travels along as a layer of its own. Both survive every later `docker run` in every environment. The real problem is not the command but the mixed trust zone: an artifact that is supposed to be identical in staging and production suddenly carries production secrets. The architectural answer is a clean separation. The build produces an environment-neutral artifact without secrets. Configuration is only added at runtime, injected from a source that is separate per environment. A multi-stage build makes this intention visible in the code: ```dockerfile # build stage produces an artifact that knows nothing about any environment FROM node:12 AS build WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # runtime stage receives config from the environment, never from the image FROM node:12-slim WORKDIR /app COPY --from=build /app/dist ./dist CMD ["node", "dist/server.js"] ``` The same thinking applies to build secrets the build really needs – a private registry token, for example. They come in via a secret mount that isn’t persisted in the final image, instead of via an `ARG` that stays in the history. The principle remains: a secret that only the build needs must not reach the runtime artifact. ## Parameter Store as an interface, not a database Once the separation is in place, Parameter Store becomes interesting. Its value comes from the structure it enforces, not from the fact that it stores values. The hierarchical path is the real lever: it encodes the environment, and the environment is the boundary where permissions take hold. ```bash # resolve runtime config just-in-time, scoped by environment path aws ssm get-parameters-by-path \ --path "/myapp/production/" \ --with-decryption \ --query "Parameters[].{Name:Name,Value:Value}" ``` The path `/myapp/production/` is more than cosmetics. It makes it possible to express least privilege cleanly: a deploy job for staging gets an IAM policy that points exactly at `staging/*` and can’t even read production. ```json { "Effect": "Allow", "Action": "ssm:GetParametersByPath", "Resource": "arn:aws:ssm:eu-central-1:123456789012:parameter/myapp/staging/*" } ``` This anchors the domain intention in the infrastructure instead of in a sentence in a wiki. The value is resolved at runtime and never written into the repo or the image: ```bash #!/usr/bin/env bash set -euo pipefail # inject secrets at container start, keep them out of the image and the repo export DATABASE_URL="$(aws ssm get-parameter \ --name "/myapp/production/database-url" \ --with-decryption --query "Parameter.Value" --output text)" exec node dist/server.js ``` Whether Parameter Store, Secrets Manager or a vault sits behind it is the smaller question. The bigger one is that access is separated per environment, auditable and rotatable. The tool expresses the boundary – it doesn’t create it. ## Sketch ```mermaid flowchart LR Repo[Code
    without secrets] --> Build[Build
    reproducible artifact] Build --> Registry[Artifact
    same for every environment] Store[Parameter Store
    separate per environment] --> Runtime Registry --> Runtime[Runtime
    injects config just-in-time] ``` The sketch shows the one statement that matters: the left path is identical everywhere, the secret path comes separately and is only added at the very right. Exactly at this junction it is decided whether a team can deliver fast and safely or trades one off against the other. ## The trade-offs you really weigh No approach is free. An environment-neutral artifact plus runtime injection needs a working secret source in every environment and makes container startup depend on another service. If Parameter Store fails, the service doesn’t start – that is a deliberate price for the boundary, not an oversight. You cushion it with caching and clear error messages, not by baking secrets back in after all. Conversely, the convenience of the `.env` in the image is real: one artifact, no dependency at startup, easy to reproduce locally. The price for it only comes due later – at rotation, at a leak, at the question of who had the staging image with production credentials in their hands. Architecture here means moving the price to a place where you can control it, instead of shifting it into a later incident. The second trade-off concerns centralization. A central secret source simplifies rotation and auditing but itself becomes a critical path and a coveted boundary. That’s why the path and IAM structure is not a formality: it is the difference between “one service knows everything” and “every service knows exactly its own”. The actual product decision lies between the two. ## The failure path decides, not the happy path A secrets architecture is only robust once the failure path is described. In demo mode, every approach looks clean. It gets interesting exactly where systems normally break. Rotation is the most honest test. Can I change a compromised value without rebuilding an image and promoting it through all environments? With runtime injection, that is a parameter update plus a restart. With a baked-in secret, it is a full release cycle under time pressure – the worst moment for a long road. Rollback is the second test. With clean separation, a rolled-back image only brings back old code, not old secrets. If you mix the two, rolling back the code also silently rolls back expired or rotated credentials. And third, the audit: if a value leaks, I want to reconstruct which job read it when. A central store with access logs answers that; a file in a layer doesn’t. These questions seem dry, but they are the difference between a demo and operations. ## The business outcome is speed with controlled risk The reason I treat secrets as a product decision is measurable. When a team no longer has to pass secrets along manually, a whole class of waiting time disappears. A developer deploys to staging without someone from the ops team copying a password via chat – the IAM policy allows exactly this path and nothing beyond it. That shortens the cycle from idea to running change and at the same time lowers the risk, because access is narrowly scoped. Speed and security are not in conflict here; the right boundary delivers both. Less friction also comes from the boundary living in the code and not in one person’s head. New team members read from the path structure and the policy what is allowed instead of having to ask. And quality goes up, because the most expensive mistake – a secret in a shared artifact – structurally can no longer happen, instead of only being prevented by discipline. That is exactly what I mean by developer productivity: not typing faster, but waiting less often and cleaning up less often. The effect is not a soft promise; it can be observed. I measure it by three numbers: the time from “the password has to be changed” to “changed and in operation”, the number of manual handoffs per release, and how many environments a single credential can read. Each of these numbers drops once the build-runtime boundary is in place – and when in doubt, each is more convincing than the claim that things are now more secure. ## Typical mistakes The first mistake is confusing the tool with the solution. A secret store is not an architecture, KMS is not an access boundary, and a `--build-arg` is not confidentiality. These tools can express good boundaries, but they don’t create them automatically. If you introduce the store without drawing the build-runtime boundary, you have only moved the file to a different place. The second mistake is overestimating the happy path. Many setups look clean on the first deploy and only show their weakness at the first urgent rotation. The third is treating everything as equally confidential. A feature flag configuration and a database password need different boundaries; if you throw both into the same pot, you make the harmless case expensive and the critical case convenient. ## What I check Three checks are usually enough for me. First: is a build artifact environment-neutral, or does it know secrets? A `docker history` and a look at the layers answer that in a minute. Second: is access separated per environment, so that a staging job can’t read production? Third: can I rotate a secret without rebuilding, and trace access after the fact? If one of these questions ends with a no, part of the architecture is still missing – not another tool, but a deliberately drawn boundary. I wouldn’t make a big initiative out of it but start with a small, verifiable result: a multi-stage Dockerfile, an IAM policy with path scope, a startup script that resolves the value just-in-time. Concrete enough that another developer can meaningfully disagree. Agreement is good, but disagreement often reveals the hidden assumption. ## Conclusion Storing a secret safely is the smaller half of the work. The bigger half is the reasoning for why the boundary between build and runtime runs exactly there. What matters is the concrete risk, the permitted access and the question of whether a compromised value can be rotated independently of the artifact. The name of the secret store comes after that. --- # Product Discovery Before the First Line of Code URL: https://www.mikebild.dev/en/blog/product-discovery-before-the-first-line-of-code/ Date: 2019-06-26 The most expensive lines of code I have seen in projects were technically flawless. Cleanly tested, elegantly structured, shipped several times a day in a continuous delivery pipeline. The only problem: they solved a problem nobody had. Half a year of development capacity, a flawless feature, and at the first real contact with users, the underlying assumption collapsed. Clean craftsmanship simply says nothing about whether anyone gets anything out of it in the end. No pipeline asks that question. This is exactly where product discovery comes in. And I don’t mean an upfront analysis phase in which documents are produced for six weeks before anyone is allowed to touch code. I mean a parallel, continuous track. An assumption is confronted with the cheapest sensible experiment before the team builds it out as a feature. That is what this article is about. ## Discovery and delivery are two tracks, not phases The most common reasoning error is to see discovery as a preliminary stage. First think, then build. That is waterfall in new clothes. The approach that Marty Cagan and Jeff Patton popularized under the term dual-track agile means something else: two tracks that run side by side permanently. The discovery track clarifies *what* should be built. The delivery track builds it solidly. Both run in every sprint, not one after the other. The trick lies in the size of the handoff. Before a team commits a large or hard-to-reverse undertaking to delivery, the riskiest assumption behind it should have been tested. Small technical spikes and thin, reversible slices may go into delivery earlier and generate evidence themselves. Dual track isn’t a hard lock between thinking and building. ```mermaid flowchart LR subgraph Discovery A[Idea] --> B[Assumption] B --> C[Experiment] C --> D[Validated item] end subgraph Delivery E[Build] --> F[Test] F --> G[Release] end D -->|only validated work
    enters delivery| E ``` The arrow in the middle is the real message. It is a filter. Everything that passes through it has passed a test. Everything that fails in the discovery track has never burdened a development team. That is the lever: a discarded experiment costs hours, a discarded feature costs months. Just as important is who does discovery. It isn’t a task that an upstream analysis department completes and then hands over as a finished specification. Teams that do this well put product management, design, and engineering on the discovery track together – the trio Marty Cagan describes. The developer who assesses feasibility hears in the same user interview why a feature is wanted in the first place. The designer who builds a prototype understands the technical limits firsthand. This shared responsibility is why discovery stays fast: decisions are made where the knowledge sits, without the detour through handoff documents. If you delegate discovery to a single role, you bring back the waterfall dynamic that the dual-track approach is meant to avoid. ## The four big risks discovery addresses When you ask *why* a particular feature should be built, the answer in discussions usually covers only a single dimension. In the second edition of *INSPIRED*, Cagan named four classes of risk that any serious discovery has to probe: Value risk asks whether users want it at all and whether they will switch or pay for it. Usability risk asks whether they can use it. Feasibility risk asks whether we can build it with our time, our data, and our technology. And viability risk asks whether it fits the business – legally, economically, strategically. Feasibility attracts attention because it is the question developers most like to answer. “Can we build it?” can almost always be answered with “yes.” But the expensive failures sit in value and viability risk. Discovery forces you to look at all four before the first story is sliced. ## Making assumptions visible and prioritizable The most practical step is both banal and effective: write down the assumptions. Every product idea is a stack of unspoken bets. “Users want to configure their reports themselves.” “The payment API meets our latency requirement.” “Sales can sell this without training.” As long as these sentences stay in people’s heads, you can’t test them and can’t prioritize them. With assumptions mapping, David J. Bland established a simple tool: a matrix with two axes. One axis measures how important an assumption is – does the whole undertaking fall apart if it is wrong? The other measures how much evidence we already have. The top-right quadrant, important and barely supported, gets tested first. That is the riskiest assumption, and it deserves the first test. ```mermaid quadrantChart title Assumptions Map x-axis Low evidence --> High evidence y-axis Low importance --> High importance quadrant-1 Test first quadrant-2 Keep as leap of faith quadrant-3 Ignore for now quadrant-4 Already known Users self-configure reports: [0.2, 0.9] Payment API meets latency SLA: [0.35, 0.85] Sales can sell without training: [0.6, 0.4] Login flow is usable: [0.8, 0.3] ``` I store this state versioned in the repository instead of pinning it to a whiteboard. An assumption register next to the code makes the bets part of the project and not part of a forgotten workshop: ```yaml # assumptions.yaml — reviewed before any story enters delivery assumptions: - id: A-1 statement: "Users will self-configure their reports instead of asking support" type: desirability importance: high evidence: low test: landing-page kill_criterion: "signup-to-config rate below 20% after 200 visitors" - id: A-2 statement: "The payment API stays under our latency budget at peak load" type: feasibility importance: high evidence: low test: spike kill_criterion: "p95 response time above 200ms in a load test" - id: A-3 statement: "Sales can close the feature without extra training" type: viability importance: medium evidence: low test: interview kill_criterion: "3 of 5 reps ask for a dedicated enablement session" ``` For a confirmatory test, `kill_criterion` is the crucial field. If you only decide after the test what a good result would have been, you easily find an explanation for why your favorite idea won after all. Exploratory discovery may start more openly; as soon as a concrete hypothesis is to be decided, the criterion belongs on record beforehand. ## Progress means validated learning, not shipped features In *The Lean Startup*, Eric Ries coined the term I still orient myself by today: validated learning. Progress is measured by assumptions we have settled reliably, not by features in a release. The build-measure-learn loop revolves around exactly this question: what is the fastest way to test a bet? This is where the biggest misunderstanding around the MVP lurks. A minimum viable product isn’t a cheap, half-finished product. It is the experiment with the greatest learning yield per effort. Very often, it contains no code at all. A landing page that advertises a feature that doesn’t exist yet and counts sign-ups. A concierge approach, in which a human manually does what software is supposed to do later. A demo video that measures the reaction. For assumption A-1 above, the landing page is faster and more honest than any implementation. It answers the value question in days instead of months. If the result clearly speaks against the assumption, the right reaction isn’t to build anyway. It is the pivot – change direction and go after a different bet. Teams find that hard, because discarded ideas feel like failure. They are the opposite. Every assumption that is knocked over early is capital saved. ## Technical assumptions need testing too Discovery isn’t purely a product or UX topic. Feasibility risk is often the quietest and most expensive bet. “The payment API meets our latency” is a technical assumption that you can make tangible before a feature builds on it. I phrase assumptions like these as executable tests – a Fitness Function in the sense of *Building Evolutionary Architectures*. It makes a quality goal measurable and repeatable: ```typescript // fitness function — runs the riskiest technical assumption as a test import { measureP95 } from "./load-harness"; const SLA_MS = 200; test("checkout endpoint stays under the latency budget at peak load", async () => { const p95 = await measureP95({ endpoint: "/api/checkout", concurrentUsers: 500, durationSeconds: 60, }); expect(p95).toBeLessThan(SLA_MS); }); ``` The value of this test shows at the moment it turns red before a feature goes live. Then we know: the technical assumption doesn’t hold. Better now than in production. The same way of thinking applies to failure behavior. If a feature depends on an external service, the assumption “the service is available” is a bet that you defuse with stability patterns such as a circuit breaker from Michael Nygard’s *Release It!* – and with consumer-driven contract tests that check whether two services still understand each other before the break shows up in production. ## Why efficiency alone doesn’t protect you The obvious objection is: “But we already ship quickly and reliably.” And yes, that is valuable. The book *Accelerate* by Nicole Forsgren, Jez Humble, and Gene Kim used four metrics to show how delivery quality can be measured: Deployment Frequency, Lead Time for Changes, Change Failure Rate, and Mean Time to Restore. Teams that are strong here ship often, fast, and with few failures. But none of these metrics measures whether the right thing is being built. They measure how well the delivery track runs. A team with top scores can ship features nobody needs at a high frequency. Speed at building the wrong thing is still waste – just faster. That is why both tracks belong together: discovery makes sure we work on the right thing, delivery excellence makes sure we build it well. If you only optimize the second half, you end up building yourself the most efficient way to burn money. That is the economic core. Discovery isn’t an additional process layer that slows down cycles. It shortens the cycle that really counts: from idea to validated insight. A landing page test takes days. A misguided feature takes months and still fails. Discovery trades the expensive, late feedback of the market for cheap, early feedback in an experiment. ## What this looks like day to day I boil the method down to a few habits that don’t need a heavy framework. Before every larger undertaking, the assumptions are written down and placed on the two-axis matrix. The riskiest assumption gets a suitable experiment; a confirmatory test gets a decision criterion defined in advance. Technical bets are tested as a Fitness Function or a spike, not nodded through on gut feeling. As long as the biggest uncertainty is open, the delivery investment stays small and reversible. That sounds like more work up front. In practice, it can shorten big detours, but it doesn’t guarantee that. The teams I work with this way argue less about opinions and more about evidence. A landing page with two hundred visitors can deliver a signal if the target group, traffic source, and expected effect fit; it replaces neither proper sample design nor qualitative follow-up questions. What disappears is part of the unproductive friction between opinions without data. The productive friction around the problem remains. ## Conclusion The first line of production code increases the investment, but it isn’t an irreversible border crossing. Product discovery keeps the riskiest decisions small until there is enough evidence for the next stake. Discovery and delivery run in parallel: one track clarifies what to build, the other delivers small, reliable steps and can itself be part of the experiment. The common thread is simple: you can do everything right technically and still deliver the wrong thing. Efficiency in delivery is necessary, but it is no substitute for the question of whether we are working on the right thing. If you make assumptions visible, test the riskiest one first, and set a decision criterion for confirmatory tests, you improve your chances of shorter learning cycles and well-founded decisions. Discovery remains work; its value lies in not confusing expensive certainty with unsupported confidence. ## Further reading - Marty Cagan: *INSPIRED* (2nd edition, 2017) and the “four big risks” at svpg.com/four-big-risks - Jeff Patton and Marty Cagan on dual-track agile, jpattonassociates.com and svpg.com - Eric Ries: *The Lean Startup* (2011), build-measure-learn and MVP, theleanstartup.com - David J. Bland: assumptions mapping, precoil.com and strategyzer.com - Nicole Forsgren, Jez Humble, Gene Kim: *Accelerate* (2018) - Neal Ford, Rebecca Parsons, Patrick Kua: *Building Evolutionary Architectures* (2017) - Michael Nygard: *Release It!* on circuit breakers and stability patterns --- # CQRS Is a Domain Boundary, Not a Framework URL: https://www.mikebild.dev/en/blog/cqrs-is-a-domain-boundary-not-a-framework/ Date: 2019-06-25 Every application asks its data two questions: What should change? And what should be displayed? Most systems answer both with the same model – the same entities, the same mapping, the same objects. CQRS answers them with two. Still, the most common follow-up question about the acronym – Command Query Responsibility Segregation – is about tools: Which library, which package? You’ll look for that in vain. The boundary between the write model and the read model runs through the domain, not through the dependency tree. What CQRS is, what it explicitly isn’t, when the separation pays off and where the most expensive mistakes lie – that’s what this article is about. The result is less spectacular than the acronym promises, and that’s exactly the good news. ## Where the term comes from CQRS stands for Command Query Responsibility Segregation. The core is a single idea: you use a different model to change information than the model you use to read it. What is a single conceptual model in classic systems – the same entities you write and read with – is deliberately split into two separate models. One for commands, that is, for intentions and changes. One for queries, that is, for views and queries. Martin Fowler sums up the reasoning: for many problems, particularly in more complicated domains, a shared conceptual model for commands and queries leads to a model that does both jobs worse than two specialized models would. Fowler himself first heard the term from Greg Young, who coined and fleshed out CQRS around 2010. What matters is the distinction from an older principle that CQRS is often confused with: Command Query Separation, CQS for short, by Bertrand Meyer. CQS separates at the method level – a method is either a command that changes state and returns nothing, or a query that returns a value without changing state. CQRS lifts exactly this principle to the architecture level: no longer two kinds of methods, but two separate object models. Conceptually, CQRS builds on CQS, but it works at a much coarser grain. ## The two sides have a different shape The write side and the read side don’t just have different jobs; they have a different shape. That’s not a cosmetic observation but the actual reason for the separation. The write side works with a rich domain model. This is where the invariants live, the domain rules that decide whether a change is allowed at all. A command is the expression of a domain intention – phrased imperatively, nameable, rejectable. `DeactivateInventoryItem` isn’t a record update but a statement: “I want to deactivate this item.” That fits perfectly with task-based UIs, in which users express intentions instead of filling in form fields. The read side, by contrast, doesn’t want to decide anything. It wants to display. Its natural shape is flat DTOs tailored to presentation – often a direct projection of what appears on screen. Rules, invariants, behavior: the read side needs none of that. You only force it into a rich domain model because that model happens to exist already. This is exactly where CQRS comes in. Instead of squeezing both sides into one model that serves neither of them well, you give each side the shape it deserves. ```mermaid flowchart LR Client -->|Command| CommandHandler CommandHandler --> WriteModel WriteModel --> Store[(Store)] Client -->|Query| QueryService QueryService --> ReadModel ReadModel --> Store ``` Note: both paths can use the same store. More on that in a moment – it’s more important than it looks. ## A look at the write side Illustrative, in TypeScript. The write side receives a command, loads the rich write model, lets it enforce the domain rule and saves. ```ts interface DeactivateInventoryItem { itemId: string; reason: string; } class InventoryCommandHandler { constructor(private readonly repo: InventoryItemRepository) {} handle(cmd: DeactivateInventoryItem): void { const item = this.repo.findById(cmd.itemId); // rich write model item.deactivate(cmd.reason); // domain rule enforced here this.repo.save(item); } } ``` The interesting part is in the middle line. `item.deactivate(cmd.reason)` is where the domain logic sits. Whether an item may be deactivated, whether a reason is mandatory, whether an already deactivated item rejects the command: the domain object decides that, not the handler. The command handler is deliberately thin. It orchestrates; it doesn’t decide. ## And a look at the read side The read side completely ignores this rich model. It queries a view optimized for display and returns a flat DTO. ```ts interface InventoryListItemDto { id: string; name: string; isActive: boolean; } class InventoryQueryService { constructor(private readonly readDb: ReadDatabase) {} listActiveItems(): InventoryListItemDto[] { return this.readDb.query( "SELECT id, name, is_active FROM inventory_view WHERE is_active = true", ); } } ``` No repository, no domain object, no invariant. Just a query against a view that delivers exactly what the list needs. You could object that raw SQL sits directly in a service here – for the read side, that’s often exactly right. There is nothing to protect, no rule to uphold. The detour through a rich model would be pure ceremony. The point it all comes down to: these two classes don’t know each other. They share no common model. They are two separate answers to two separate questions. That’s CQRS. ## Start small – one store is enough And now comes the part that surprises most people. Nothing in the two examples above requires two databases. `InventoryItemRepository` on the write side and `readDb` on the read side can point to the same database. Fowler puts it unmistakably: the models can share the same data store – the database then acts as the communication between the two models. This means: you can practice CQRS without introducing a single additional store. A rich write model that works against the tables. A view that the read side queries directly. Both in the same database. You get the domain separation without buying into a second data store and its consequences. On one project, we had put off the pattern for years because it was considered unaffordable – too much infrastructure, too much operations. The concern was based on a mix-up: CQRS was equated with one specific, elaborate expansion stage of CQRS. Separating the models is cheap. What costs money is separate stores, and they are optional. ## What CQRS is – and what it isn’t Because so many half-truths gather around the term, here is a clear sorting. CQRS is: - the domain separation of the write model and the read model, - a pattern for selected bounded contexts, - combinable with Event Sourcing when the domain justifies it, - practicable with a single store from the start. CQRS is not: - a framework or a library, - a synonym for Event Sourcing, - an obligation to have two databases, - a system-wide architecture standard that you roll out everywhere. Most of the trouble I see in reviews hinges on this second list. ## The three most expensive mix-ups The first is trying to use CQRS everywhere. It’s a minority case, not a default. Fowler explicitly warns that for most systems CQRS adds risky complexity and that you should be very cautious about using it. The separation belongs in a single bounded context where the domain justifies it – not in every module, not in every entity. If you roll out CQRS system-wide, you pay the cost of the separation everywhere and reap the benefit only in the few places where the models really drift apart. The second is confusing CQRS with Event Sourcing. That’s the most common mix-up of all, and I understand where it comes from – the two almost always appear together in talks and examples. But they are independent patterns. Event Sourcing is a decision about persistence: instead of storing the current state, you store the sequence of events that led to it. CQRS is a decision about models: writing and reading get separate models. You can have either without the other. Vaughn Vernon’s IDDD samples do show contexts that combine Event Sourcing and CQRS – but even there, it remains a deliberate combination of two patterns, not a definition in which one contains the other. If you say CQRS and mean Event Sourcing, you’ll constantly talk past each other in discussions. The third is introducing two databases too early. Separate read and write stores are an optional, later optimization – usually driven by asymmetric load, when you want to scale the read side and the write side independently. If you introduce them too early, you take on two costs before any need has been proven: the synchronization effort between the stores and, more seriously, eventual consistency. From the moment the read store lags behind the write store, users may see data that is already outdated. That’s a domain problem, not a technical detail – and you should only take it on when you have a concrete reason for it. This is what that expansion stage would look like – one you deliberately take only when the load demands it: ```mermaid flowchart LR CommandHandler --> WriteModel WriteModel --> WriteStore[(Write Store)] WriteStore -.->|projection
    eventual consistency| ReadStore[(Read Store)] QueryService --> ReadStore ``` The dashed arrow is the price. There is now a projection between the write store and the read store, and with it a delay. As long as this arrow isn’t needed, it shouldn’t exist. ## When the boundary really pays off After all these warnings, the constructive side: there are situations in which CQRS is the right answer. I see essentially three. The first is complex domains in which a shared model serves neither side well. When the write model is barely queryable because of all its invariants and behavior, and the read side painfully works its way through this model to produce simple lists, both are fighting the same structure. The separation frees both. The second is asymmetric load. Many systems read orders of magnitude more often than they write. Separate models – and, in the expansion stage, separate stores – let you scale the read side independently without touching the write side. The third is task-based UIs. When the UI thinks in intentions anyway – “deactivate item,” “cancel order” – instead of in CRUD forms, the command side of CQRS is already in the air. You just have to name it. All three criteria have the same origin: the structure follows from the domain, not from the wish for a modern diagram. CQRS isn’t a goal. It’s an answer – and only right where the domain asks the matching question. ## Conclusion If you understand CQRS as a framework, you’re looking in the wrong place. There is nothing to install. The only decision that counts is a domain decision: Does this domain benefit from writing and reading getting different models? If yes, you draw the boundary – small, with a single store, without Event Sourcing, in a single bounded context. If no, you leave it, and that’s the more common case. The separate databases, the projections, eventual consistency – all of these are later, optional expansion stages that you take when the load demands it, and not earlier. Equating CQRS with these expansion stages is the mistake that makes the pattern expensive and intimidating. In its essence, it’s the opposite: an unspectacular, cheap, domain-driven separation. Two questions, two models. That’s all you need to get started. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-cqrs-event-sourcing.en.html - Martin Fowler, “CQRS”: [martinfowler.com/bliki/CQRS.html](https://martinfowler.com/bliki/CQRS.html) - Martin Fowler, “CommandQuerySeparation”: [martinfowler.com/bliki/CommandQuerySeparation.html](https://martinfowler.com/bliki/CommandQuerySeparation.html) - Greg Young, “CQRS Documents” (PDF): [cqrs.wordpress.com](https://cqrs.wordpress.com/documents/) - Vaughn Vernon, “Implementing Domain-Driven Design,” chapter 4 (Architecture / CQRS), and the [IDDD_Samples](https://github.com/VaughnVernon/IDDD_Samples) - My own talk material “CQRS + Event Sourcing” (SlideShare), which some of the examples shown here come from --- # Node.js Training: From the Event Loop to Architecture Decisions URL: https://www.mikebild.dev/en/blog/nodejs-training-from-event-loop-to-architecture/ Date: 2019-05-12 # Node.js Training: From the Event Loop to Architecture Decisions Express answers exactly one question: which function runs for which URL. It doesn’t answer the questions that actually break a Node backend in production – what happens when a single call blocks the only thread, when a response grows larger than the free memory, when a promise is rejected and nobody is listening. If you start with a framework, you memorize an API. If you start with the event loop, you understand why that API looks the way it does and what exactly happens when you use it wrong. Still, the question “Why don’t we just build this with Express?” comes up very early in Node trainings – whether I run them directly or through partners like [Grossweber](https://grossweber.com/). It’s a fair question, and it’s still premature. So the starting point is somewhere else: a single line that, at first glance, has nothing to do with architecture. ## The first snippet already shows everything ```js const fs = require("fs"); const data = fs.readFileSync("input.txt"); console.log(data.toString()); console.log("Fertig"); ``` This isn’t exciting code. That’s exactly why it works as a starting point. `readFileSync` blocks the process until the file has been read completely. Only then does the next line run. I let participants run this code, then I change one line: ```js const fs = require("fs"); fs.readFile("input.txt", (err, data) => { if (err) return console.error(err); console.log(data.toString()); }); console.log("Fertig"); ``` Now “Fertig” shows up first in the console, even though that line comes later in the source. For beginners, this is often the first small moment of shock: the code doesn’t run from top to bottom, at least not the way you’re used to from other languages. You can hang the entire rest of the training on this tiny difference. At its core, Node.js isn’t a framework and isn’t a collection of modules. It’s a decision: a program reacts to a slow input/output operation by moving on instead of waiting. ## The event loop is architecture, not a footnote Node runs on Chrome’s V8 engine and in a single JavaScript thread. That regularly surprises participants, because the server can still handle thousands of concurrent connections. The contradiction dissolves as soon as you distinguish between concurrent and parallel. At any given moment, Node only processes one piece of JavaScript, but while that piece waits for an answer from the disk, the network or a database, Node hands the work down to libuv, the kernel or an internal thread pool. The event loop is the part that picks up the returned results and calls the matching callbacks as soon as the main thread is free. This is where I deliberately slow down in the training, because this is where the real architectural statement lives: concurrency in Node isn’t an implementation detail you can ignore as long as the code works. It determines which work may happen right away and which has to wait, and it determines what a single blocking call means for every other request running at the same time. A CPU-heavy loop, a synchronous JSON.parse over several megabytes, a nested regex with catastrophic backtracking – none of these just stalls the one request that triggered it. They stall the entire process, because there is no second thread that could take over in the meantime. ```mermaid flowchart LR subgraph Call["Call stack (one thread)"] direction TB JS["Your JavaScript"] end JS -->|"hands off I/O"| LibUV["libuv / kernel / thread pool"] LibUV -->|"result is ready"| Queue["Callback queue"] Queue -->|"call stack is empty"| JS ``` For participants who come from Java or .NET environments, this is often the biggest adjustment. The sentence I want to stick isn’t “Node is fast.” It’s this: Node is fair as long as you don’t sneak blocking work into it. That’s an operational promise, not a marketing line, and it has direct consequences for what is allowed to end up in a Node service at all. ## Why callbacks, EventEmitter, streams and promises come in exactly this order In the `introduction-nodejs` repo, which I work through together with participants, the chapters deliberately follow this order: callbacks first, then EventEmitter, then streams, then promises and, at the very end, RxJS. It looks like an arbitrary list of async tools, but it’s actually a learning curve with clear logic behind it, and that logic is worth spelling out once. A callback delivers exactly one result, exactly once, and error handling is pure convention: the first argument is set in case of an error, otherwise it isn’t. This convention is called error-first, and it only works if every function sticks to it with discipline. An EventEmitter goes one step further and delivers any number of events over time, but it has no built-in error channel. An `error` event is just an agreement, and if nobody listens to it, Node throws the exception further up, uncaught. At its core, a stream is a specialized EventEmitter that adds two things that matter in everyday work: a fixed role (Readable, Writable, Duplex or Transform) and backpressure, a built-in brake for when the destination is slower than the source. Finally, a promise goes back to exactly one result, exactly once, but gains a real, composable error channel through `.catch` that neither the callback nor the EventEmitter has. RxJS combines both properties at the end: many values over time, as with the EventEmitter, but with the same reliable error and completion contract that promises introduced. Once participants have seen this arc, they stop asking for the “best” async pattern. The question shifts to something more useful: How many values do I expect, how many times may an error happen, and who is responsible for handling it? ## Streams and backpressure in a concrete example No chapter in the training produces as many aha moments as streams, because they show for the first time that Node architecture is also a question of memory and throughput, not just syntax. A small example that gets shown a lot is all you need: ```js const fs = require("fs"); const zlib = require("zlib"); fs.createReadStream("input.txt") .pipe(zlib.createGzip()) .pipe(fs.createWriteStream("input.txt.gz")); ``` At first glance, this is just a convenient way to compress a file. The line only gets interesting when you ask what happens when `input.txt` is ten gigabytes. Without streams, you would have to load the entire file into memory before compression could even start. With `pipe`, Node reads a chunk, compresses it, writes it, and only then does the next chunk get its turn – and automatically only as fast as the write target can keep up. That’s backpressure: a built-in queue that prevents a fast source from flooding a slow destination with data until the process chokes on its memory limit. ```mermaid flowchart LR Source["Readable
    (e.g. file)"] --> Transform["Transform
    (e.g. gzip)"] Transform --> Sink["Writable
    (e.g. target file)"] Sink -. "Backpressure" .-> Transform Transform -. "pause / resume" .-> Source ``` For the architecture of a backend, this isn’t niche knowledge for file conversion. Every file upload, every CSV export, every log tail and every forwarded HTTP response body benefits from exactly the same principle. If you instead collect the entire request body in a buffer before anything happens with it, you have built in a memory limit that never shows up in a test with a small test file and very much does show up in production with real user files. ## Express is not an architecture pattern This finally brings us to the question participants actually wanted to start with. Express is an excellent, lean routing tool, but it doesn’t make a single one of the decisions that actually define a web architecture. Those decisions live elsewhere: Does the server respond with fully rendered HTML, as in classic server-side rendering? Does it respond with structured data to an RPC-style call, where a function and its parameters sit in the body? Or does it follow the RESTful idea, where resources are addressed through URIs and HTTP methods carry their own meaning? For the latter, I like to use the Richardson Maturity Model in the training as a small orientation aid, because it makes the levels tangible. At level 0, there is only a single URI, usually with POST, and the actual action sits in the body – basically RPC over HTTP. Level 1 adds several URIs for different resources, but still without proper use of HTTP methods. Level 2 uses GET, POST, PUT, DELETE and status codes the way they are meant: 200 for success, 201 for created, 204 for no content, 404 when the resource is missing. Level 3 adds hypermedia, meaning links in the response that tell the client which next steps are possible, instead of the client having to know that up front. Most systems I see in projects stop at level 2, and that’s usually perfectly fine. What matters is that the decision is made deliberately and isn’t simply the result of whichever Express examples you happened to copy first. What Express actually contributes is something else, and it has a surprising connection to streams: a middleware pipeline. ```js const express = require("express"); const app = express(); app.use(express.json()); app.use((req, res, next) => { console.log(`${req.method} ${req.url}`); next(); }); app.get("/invoices/:id", async (req, res, next) => { try { const invoice = await loadInvoice(req.params.id); if (!invoice) return res.status(404).json({ error: "not_found" }); res.status(200).json(invoice); } catch (err) { next(err); } }); app.use((err, req, res, next) => { console.error(err); res.status(500).json({ error: "internal" }); }); app.listen(3000); ``` Each middleware gets the request and the response, does something and passes control on with `next()`, or it aborts with an error that ends up in the four-parameter error handler. Structurally, that’s the same principle as the streams above: a source, a chain of transformations, a destination and a separate channel for the error case. As soon as participants see this kinship, Express stops being a list of calls to memorize. It becomes one of several forms of the same pipeline idea that runs through the whole training. ## Scaling without illusions A single Node process uses exactly one CPU core. That regularly surprises participants with servers that have eight or sixteen cores, because under load only one of them gets anything to do unless you take further steps. For this, Node offers `child_process` with three tools of different granularity: `spawn` starts any system command and delivers its output as a stream, `exec` does something similar but collects the output entirely in memory before it returns, and `fork` specifically starts another Node script as a separate process with a built-in message channel. For compute-heavy work that would otherwise block the event loop, that’s the clean way: offload the work instead of sacrificing the only thread. In the repo, a `fork` looks like this, for example: ```js const { fork } = require("child_process"); const worker = fork("./heavy-computation.js"); worker.send({ numbers: [1, 2, 3, 4, 5] }); worker.on("message", (result) => { console.log("Result from worker process:", result); }); ``` The main process stays free while `heavy-computation.js` computes in its own process and sends the result back through the built-in message channel. That’s coarser than a thread, because every `child_process` brings its own V8 context and its own memory, but in many cases this very isolation is an advantage: a crashed worker doesn’t take the main process down with it. Right now, in spring 2019, this picture is getting more interesting. Node 10 is the long-term support version that currently runs in production in most projects, solid and mature. Node 12 came out a few weeks ago and brings two things I already talk about in the training without recommending them for production: Worker Threads, which now run without a command-line flag but which the Node maintainers themselves don’t yet call fully mature, and experimental support for ECMAScript modules behind the `--experimental-modules` flag. Both show where Node is heading, but if you ship something today, you stay with `require`, with CommonJS and with the 10 line until 12 becomes the LTS version. I find this distinction important enough to make it explicit: curiosity about the new and responsibility for what’s running are two different things, and a good training shows both. ## Errors are architecture too, not just a try/catch In the Express example above, an error ends up in the four-parameter handler because I explicitly passed it there with `next(err)`. That’s the clean case. It gets interesting with the errors nobody passed on explicitly. For those, Node offers two global safety nets, and I deliberately show participants that they are nets, not repair tools. ```js process.on("uncaughtException", (err) => { console.error("Unexpected error, process is in an undefined state:", err); // only synchronous cleanup, then exit process.exit(1); }); process.on("unhandledRejection", (reason) => { console.error("Promise rejected without .catch:", reason); }); ``` The Node documentation is unusually clear at this point: after an `uncaughtException`, the process is in an undefined state. That sentence is meant literally. Some module may have stopped in the middle of an operation, a file half written, a connection half established. So you don’t carry on in the handler. You clean up as quickly and as synchronously as possible and end the process, so that a supervisor – `pm2`, systemd, Kubernetes, whatever runs in the project – restarts it fresh. `unhandledRejection` is the promise variant of the same problem: a promise that was rejected without a `.catch` waiting for it anywhere. For participants who come from a world with central exception handling, this takes some getting used to. The actual lesson is this: a global handler never replaces the `try/catch` or the `.catch` at the place where the error means something for the domain – that an invoice wasn’t found, that a payment failed, that a file doesn’t exist. It’s the last safety net for whatever fell through all the deliberately placed nets. It fits that Node allows a controlled shutdown through `process.on("SIGINT", ...)` and related signals: finish serving open connections, close database connections cleanly, and only then exit. Behind this is the same idea as with backpressure: a system says honestly when it’s done instead of simply being killed. ## Test before it hurts The last building block I deliberately don’t skip in the training is testing, for a simple reason: everything shown so far – backpressure, error paths, the order of middleware – can be broken invisibly in no time if nobody has captured an expectation about it. I work with Mocha, because in 2019 it’s a proven, unexcited standard, and with the built-in `assert` module, because you don’t need an extra library to understand the idea. ```js const assert = require("assert"); const { describe, it } = require("mocha"); describe("Array.reverse", () => { it("reverses the order of elements", () => { const sut = "ABC".split(""); const actual = sut.reverse(); assert.deepEqual(actual, ["C", "B", "A"]); }); }); ``` Arrange, Act, Assert: set up test data, run the function, check the result. These three steps sound trivial, but most hard-to-read tests violate exactly this separation by happily mixing setup and checks. With asynchronous code, Mocha pays off even more, because a test either accepts a `done` callback or simply returns a promise: ```js it("resolves with the expected value after the async call", () => { return computeAsync().then((actual) => { assert.equal(actual, 2); }); }); ``` If the test function returns a promise, Mocha automatically waits for it before evaluating the result. If you forget the `return`, the test may report success before the actual assertion has even run – a bug that’s easy to miss in code reviews, because the test is green after all. For integration tests, `before`, `after`, `beforeEach` and `afterEach` come in, for example to set up a test database once and bring it back to a known state after each test. The test pyramid remains the guardrail: many fast unit tests at the base, fewer but meaningful integration tests in the middle, a handful of end-to-end tests at the top. If you invert this distribution, you usually only notice it in the runtime of the build pipeline, when it’s too late to change it cheaply. ## The repository itself is architecture One point I like to explain to participants only at the end, because it would be too abstract earlier: `introduction-nodejs` is itself built as a Yarn Workspaces monorepo and not just a folder full of Markdown files. The root directory has a `package.json` with `"private": true` and a `workspaces` field that points to a `packages` folder, and each example lives below it as a standalone package: `ARCHITECTURE`, `BASICS`, `ECMA`, `EVENTEMITTER`, `EXPRESSJS`, `FUNCTIONALJS`, `HTTP2`, `RXJS`, `STREAMS`, `TESTING`, `TYPESCRIPT`. Each of these packages has its own dependencies and can be installed and run on its own, without the examples polluting each other. That isn’t a coincidence, and it isn’t just a way of keeping things tidy. It’s the same lesson that already came up with streams and with Express, one level higher: clear boundaries between building blocks, each with its own responsibility, connected through an explicit, visible mechanism instead of silent dependencies. I deliberately show participants this structure of the repo itself, because a monorepo with clean workspace boundaries solves pretty much the same architecture problem as a backend made up of several services: Where may something be shared, and where must it stay separate so that a change in one place doesn’t surprisingly break something somewhere else? ## How I actually run the training I rarely show a slide without opening the code right after it. The slide overview for the training is available for reference and for anyone who wants to see the overview again between sessions, here: [Introduction to Node.js – slides](https://slides.mikebild.dev/introduction-nodejs.en.html). But the slide is the signpost, not the path itself. The real learning happens in the repository, together: I type, a participant types, we deliberately introduce a bug and look at the error message together, then we fix it together. If you only watch, you remember the syntax for the moment. If you type yourself and forget to return the callback yourself or put the `await` in the wrong place, you remember the boundary – and boundaries are what you can still recall a year later, not syntax. That’s why the training is carried by the repo [introduction-nodejs](https://github.com/mikebild/introduction-nodejs) and not by the slide deck. The 23 chapters are set up as standalone Markdown files that you can look up in any order and that, as a whole, form a learning curve from the first script to production readiness – from the introduction through the event loop, streams and error handling to Express, testing, promises, RxJS and TypeScript. The accompanying `EXAMPLES` are runnable code, not pseudocode – exactly the code we change together in the room. ## What should stick at the end On the last day of the training, I sometimes ask participants what they’re taking away. The answer that makes me happiest is rarely “I know Express now.” It’s more like: “I now know when to reach for a callback and when for a stream, and I know why an `await` is still something I have to think about.” That’s exactly the difference between a list of tools and an understanding of architecture. You can pick up a framework over a weekend. A feel for which decision will come back to bite you later takes practice on real, sometimes deliberately broken code. Node.js works as a training subject for a reason that has nothing to do with being current or popular: its central design decision – non-blocking I/O in a single thread – is so uncompromising that it forces its own consequences. You can’t ignore it without the server eventually behaving strangely. And it’s exactly in these strange moments that you learn the most. Even Ryan Dahl, who invented Node ten years ago, publicly questioned some of his own design decisions a while ago in a widely noted talk and has been experimenting with a possible successor ever since. Regardless of where this experiment leads, I find that remarkably healthy for an ecosystem: the inventor himself is willing to say what he would do differently today. That’s exactly the attitude I try to convey in the training. Node.js isn’t a finished, closed worldview that you memorize. It’s a series of decisions, each with its price, each open to debate. Once you have internalized that, you’ll also read the next technology that will be in vogue in five years as another set of decisions that you can understand and, if needed, refute – and not as the truth. ## Further reading - Repository introduction-nodejs (the basis for the joint exercises): https://github.com/mikebild/introduction-nodejs - Slide overview for the training: https://slides.mikebild.dev/introduction-nodejs.en.html - Node.js, Event Loop and timers (official documentation): https://nodejs.org/learn/asynchronous-work/event-loop-timers-and-nexttick - Node.js Streams API: https://nodejs.org/api/stream.html - Node.js 12 release announcement: https://nodejs.org/en/blog/release/v12.0.0/ - Richardson Maturity Model, overview: https://martinfowler.com/articles/richardsonMaturityModel.html --- # CDK Early Days: Infrastructure in a Programming Language URL: https://www.mikebild.dev/en/blog/cdk-early-days-infrastructure-in-a-programming-language/ Date: 2019-03-12 # CDK Early Days: Infrastructure in a Programming Language The AWS Cloud Development Kit has been available as a developer preview for a few weeks now, and it noticeably changes how I think about infrastructure. Instead of writing YAML and hoping the indentation is right, I write TypeScript. I get types, autocompletion, loops, functions, and classes. That sounds like a pure convenience upgrade, but it is a shift in responsibility. If you describe infrastructure in a real programming language, you inherit all the tools of that language. But you also inherit its classes of bugs. **Editorial note (July 2026):** The CDK is not a programming language of its own but a framework for defining infrastructure in existing languages and provisioning it through CloudFormation. The code shows the developer preview and later CDK v1: separate `@aws-cdk/*` packages and the Lambda runtimes of that time. CDK v2 bundles the stable Construct Library in `aws-cdk-lib`; new projects should therefore not copy the examples verbatim. The same applies to the deployment action further down: current GitHub Actions workflows should connect to AWS via OIDC and short-lived role credentials, not via long-lived access keys in repository secrets. In what follows, I use a small, plausible stack as the common thread: an S3 bucket that users upload files into, and a Lambda function that processes those files. This example shows the interesting architecture question better than a list of features would. ## From template to program Anyone who has worked with AWS for a while knows CloudFormation. You describe the target state declaratively, and the service reconciles it. The model is robust, but the format is tedious. Repetition can only be expressed through parameters and mappings, and as soon as a template grows beyond a thousand lines, you lose track of which resource actually depends on which. The CDK reverses the direction. I write code, and in the end this code generates a CloudFormation template again. This step is called synthesis. What matters is that CloudFormation is still doing the work underneath. The CDK doesn’t replace the provisioning mechanism; it puts a programming layer on top of it. The advantage is obvious: abstraction, reuse, type checking. The price is that there is now a translation step between my source code and the real resources, and I should know its result. In the current preview release, the library is split up by service. There is a core package and one package per AWS service. If you use S3 and Lambda, you install exactly those packages. That is unusually granular, but it has the effect of keeping your own dependencies small. ## The three levels: App, Stack, Construct The model has three layers, and it pays to keep them cleanly apart, because each has a different job. At the very bottom are the constructs. A construct is a building block. It encapsulates one or more CloudFormation resources along with sensible defaults. An S3 bucket is a construct, a Lambda function is a construct, and a self-written module that combines both into an upload processor is one as well. Constructs can be nested, and that is exactly where reusability comes from. One level above is the stack. It is the unit that gets deployed and corresponds one to one to a CloudFormation stack. Whatever is in a stack is rolled out together and, in case of an error, rolled back together. At the very top sits the app. It is the entry point and bundles one or more stacks. When the app runs, a template is generated for each stack. ```mermaid flowchart TD App["App (entry point)"] --> Stack["Stack (deployment unit)"] Stack --> C1["Construct: S3 bucket"] Stack --> C2["Construct: Lambda function"] C1 --> Synth["Synthesis"] C2 --> Synth Synth --> CFN["CloudFormation template"] CFN --> AWS["Resources in the cloud"] ``` This hierarchy is not an end in itself. It determines what can be changed independently and what can’t. Two things in the same stack share their fate during a rollback. Two things in separate stacks can be updated separately, but then they have to express their connection explicitly through references. ## The stack as code This is what the upload processor I mentioned looks like in the current library. Deliberately kept small so that the decision stays visible and doesn’t disappear in the trimmings. ```ts import cdk = require("@aws-cdk/core"); import s3 = require("@aws-cdk/aws-s3"); import lambda = require("@aws-cdk/aws-lambda"); class UploadStack extends cdk.Stack { constructor(scope: cdk.App, id: string, props?: cdk.StackProps) { super(scope, id, props); // Storage for incoming files. // RETAIN keeps the bucket even when the stack is deleted. const uploads = new s3.Bucket(this, "Uploads", { removalPolicy: cdk.RemovalPolicy.RETAIN }); const handler = new lambda.Function(this, "ProcessUpload", { runtime: lambda.Runtime.NODEJS_10_X, handler: "index.handler", code: lambda.Code.fromAsset("dist/handler"), environment: { // The bucket name is resolved at runtime, not hard-coded. BUCKET_NAME: uploads.bucketName } }); // Instead of writing an IAM policy by hand: // the construct grants the necessary permissions and nothing more. uploads.grantReadWrite(handler); } } const app = new cdk.App(); new UploadStack(app, "UploadStack"); app.synth(); ``` Three places deserve a second look. The call `uploads.grantReadWrite(handler)` doesn’t write a policy by hand; it derives from the relationship between the two constructs which actions the function needs on the bucket. That is more than convenience, because it makes the principle of least privilege the default path instead of the exception. The line `BUCKET_NAME: uploads.bucketName` shows that at synthesis time, `bucketName` is not a finished string but a reference that CloudFormation resolves later. And `removalPolicy: RETAIN` is the small, inconspicuous line I will come back to shortly, because leaving it out gets expensive. What stands out here: it is regular code. I can refactor it, extract it into a function, iterate over a list of environments. That is exactly the appeal. And that is exactly where the responsibility begins. ## What you take on with a programming language As long as infrastructure lives in YAML, it is static and boring, but easy to oversee. As soon as it is code, the laws of code apply. A typo in a loop doesn’t create one wrong resource but fifty. A changed constant takes effect everywhere it is read. An abstraction that hides too much also hides costs and permissions from whoever reviews the stack. This shifts what diligence means here: when infrastructure becomes programmable, it has to be treated like application code. It needs tests, it needs reviews, and it needs an understanding of what happens when you change it. That is not a burden the CDK imposes on us, but the honest consequence of using a real language. Tests are not an add-on here. The library already ships an assertion module that lets you check the synthesized result without deploying at all: ```ts import { expect, haveResource } from "@aws-cdk/assert"; test("Bucket survives deletion of the stack", () => { const app = new cdk.App(); const stack = new UploadStack(app, "TestStack"); expect(stack).to(haveResource("AWS::S3::Bucket", { DeletionPolicy: "Retain" }, undefined, true)); }); ``` This test deploys nothing. It checks the generated template. That lets you pin down a rule that otherwise only exists in the head of an experienced colleague: this bucket must not disappear by accident. Checks like these are exactly what separate a stack that survives a demo from one that survives a change in staff. ## The mistake that actually happens The most dangerous mistake in the CDK is not a syntax error, because the compiler catches those. It has to do with the logical identity of resources, and it is so treacherous because the code looks perfectly fine afterward. CloudFormation identifies every resource by a logical ID. The CDK generates this ID from the construct’s path in the tree, so essentially from the second argument of the constructor, the name. In my example, the bucket is called `"Uploads"`. Suppose someone finds this name unattractive and renames it purely for cosmetic reasons: ```ts const uploads = new s3.Bucket(this, "UploadBucket", { removalPolicy: cdk.RemovalPolicy.RETAIN }); ``` Functionally, nothing changes. The code compiles, and the tests for the function’s behavior keep passing. But the logical ID has changed. For CloudFormation, that doesn’t mean the same resource with a new name. It means the old resource is gone and a new one has been added. So on the next deployment, a new, empty bucket is created, and the application then points to this empty storage. The deletion or replacement policy applies to the old resource. This is where the inconspicuous line from before saves you. If `removalPolicy: RETAIN` is in the code, the old bucket is not deleted but released from the stack and remains as an orphaned resource. The data survives, even if the application can no longer find it, until someone cleans up manually. If this policy is missing, CloudFormation tries to remove the old resource. CloudFormation doesn’t silently empty a non-empty S3 bucket in the process; the deletion fails as long as it contains objects, unless a mechanism such as `autoDeleteObjects` has also been set up. That doesn’t make the rename harmless: the application already points to a new, empty bucket, and with other deletable resources or explicit automatic emptying, the replacement can actually destroy data. The crucial point is not the individual policy. The point is that a harmless rename in the code triggers a destructive operation in the infrastructure, and that this consequence is not visible in the source code. It only becomes visible in `cdk diff`, which marks a replacement as such. If you read the diff before deploying, you see the damage coming. If you skip it because the last deployment went through just fine, you see it afterward. ```text $ cdk diff Resources [-] AWS::S3::Bucket Uploads destroy [+] AWS::S3::Bucket UploadBucket create ``` This leads to a concrete operating rule: for stacks with state, the diff is not an optional intermediate step but part of the review. And stateful resources – buckets, databases, tables – get an explicit removal policy so that deleting or replacing a stack never silently takes data with it. ## Abstraction is a decision, not a free convenience The `grantReadWrite` call is a good example of a successful abstraction, because it removes repetition and enforces a safe default. But there is the other kind, too. A self-written construct that encapsulates an entire microservice with a database, queue, function, and alarm is tempting. It keeps the calling code short. But it also makes invisible which twelve resources and which permissions come into being. A good abstraction in the CDK reduces repetition and encapsulates reasonable defaults without obscuring what it costs and which permissions it hands out. The touchstone for your own construct is therefore not its elegance. It is the question of whether someone in the review still understands what they are buying into. If the only answer is that it works, the abstraction isn’t mature yet. It helps to look at the result of the synthesis now and then. A `cdk synth` writes the finished template to the console. For an inconspicuous stack, that quickly adds up to a few hundred lines, and it is worth consciously noticing this ratio between short code and an extensive template. It is the most honest indicator of how much the abstraction is doing for you right now. ## How this fits into a pipeline Infrastructure as code only shows its value when nobody deploys by hand anymore. In 2019, I built a small GitHub Action for this that installs the CDK in a container and runs `deploy` with AWS credentials from repository secrets. This credential pattern is historical; for new workflows, I use OIDC and a time-limited AWS role. What has remained is the appeal of the same mechanism shipping both application code and infrastructure. A pull request then changes not only the service but also its foundation, and both go through the same review. This is exactly where the circle closes back to responsibility. If a merge is enough to change production infrastructure, then the review is the last place where a human can step in. The diff belongs in that review. The tests run before deployment. And for rules that are non-negotiable, such as that no bucket may be publicly readable, an automated check of the synthesized template pays off – a kind of policy as code for your own CDK output. That way, knowledge that otherwise depends on the reviewer’s form on the day moves into a check that is always equally strict. ## What I take away from the first weeks The CDK is still young, the API is moving, and some things will change before the stable version. Still, the direction is clear, and it convinces me. Infrastructure becomes testable, reusable, and refactorable. That is a real gain over handwritten YAML. But the gain is tied to an attitude. If you program infrastructure, you have to treat it like software, with everything that goes with it: small, verifiable building blocks, a test for every assumption that would be expensive if it broke, a diff that gets read before every deployment, and a conscious decision about what an abstraction may hide and what it may not. The logical ID and the removal policy are not footnotes here; they are the places where it is decided whether a refactoring stays harmless or costs data. So the tool switch from YAML to TypeScript is the smaller part of the story. The bigger part is that operations and code quality are now the same topic. If you embrace that, you get infrastructure that you can read, check, and change with confidence. If you ignore it, all you end up with is the old mistakes in a new language. ## Further reading - [AWS CDK v2, introduction](https://docs.aws.amazon.com/cdk/v2/guide/home.html) - [Constructs as building blocks](https://docs.aws.amazon.com/cdk/v2/guide/constructs.html) - [CloudFormation `DeletionPolicy`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-deletionpolicy.html) and [`UpdateReplacePolicy`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-updatereplacepolicy.html) - [GitHub OIDC with AWS](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws) - GitHub Action for CDK deployment: https://github.com/MikeBild/aws-cdk-js-github-action - Policy as code for the CDK (cloudpatrol): https://github.com/MikeBild/cloudpatrol --- # AWS Parameter Store in the Build URL: https://www.mikebild.dev/en/blog/aws-parameter-store-in-the-build/ Date: 2019-02-12 # AWS Parameter Store in the Build ```bash $ gatsby build success Building production JavaScript and CSS bundles - 42.108s Done in 71.4s $ grep -o "undefined/graphql" public/app-8f2c1a.js undefined/graphql ``` `GATSBY_API_URL` wasn’t in `process.env` during the build. The build still went green, the artifact is deployable, and the empty value is baked into the shipped JavaScript – the first place it will show up is a user’s browser. No crash, no error message in the pipeline, just a static bundle that talks to nothing. The concrete reason for writing this down is a small Gatsby plugin I built: [gatsby-plugin-aws-parameter-store-environment](https://github.com/MikeBild/gatsby-plugin-aws-parameter-store-environment). During the build, it pulls configuration values from AWS Systems Manager Parameter Store and provides them as environment variables. Fifty lines of code, a very manageable problem – and still a good opportunity to make visible an architecture question that is considerably bigger than the plugin itself. The question isn’t “How do I get a value from an AWS service?” but “Where does the configuration of a static frontend belong, who owns it, and what does the answer cost me in operations?” This boundary is exactly where it is decided whether a deployment runs smoothly or every release remains a small manual feat of strength. A tiny plugin is often the most honest place to think through a decision like this, because nothing distracts from the actual question. ## The problem: configuration in a static build Gatsby generates static HTML, CSS, and JavaScript at build time. That is the core of the JAMstack promise: fast, cache-friendly delivery without a server in the request path. The price for this is a shift that many underestimate – configuration isn’t read at runtime but baked in at build time. Whatever is in `process.env` during `gatsby build` ends up in the result. Whatever is missing stays missing until the next build runs. In practice, a familiar pattern quickly grows out of this. Every environment – local, staging, production – gets its own `.env` file. Some values live in the CI system as secrets, others in the Git repository, a few only in the head of whoever deployed last. There is no single source, just scattering. And scattering creates drift: staging runs against a different API endpoint than intended, a feature flag is set differently in production than documented, a rotated access key was updated in three of four places. That isn’t an exotic edge case. It is the most common source of friction between “the code is done” and “the change is live.” And it is expensive, because it doesn’t show up as an outage but as creeping uncertainty: nobody knows for sure anymore which configuration a particular build actually saw. ## The idea: a single source for build configuration Parameter Store reverses this scattering. Instead of maintaining many `.env` files, I define the configuration hierarchically in one place in AWS, organized by application and environment: ```bash # One source of truth, organized by app and environment aws ssm put-parameter \ --name "/mikebild-dev/production/GATSBY_API_URL" \ --value "https://api.mikebild.com/graphql" \ --type "String" aws ssm put-parameter \ --name "/mikebild-dev/production/CONTENTFUL_DELIVERY_TOKEN" \ --value "cda-xxxxxxxx" \ --type "SecureString" \ --key-id "alias/build-config" ``` The build then pulls the entire subtree of an environment and exports it as environment variables. In `gatsby-config.js`, this looks deliberately unspectacular: ```js module.exports = { plugins: [ { resolve: "gatsby-plugin-aws-parameter-store-environment", options: { // Pull the whole subtree for this environment path: `/mikebild-dev/${process.env.DEPLOY_ENV}/`, withDecryption: true, }, }, ], }; ``` The hierarchy is the real gain, not the API call. A path like `/app/environment/KEY` gives the configuration a structure that you can slice with an IAM policy: the production build may read `/mikebild-dev/production/*`, nothing else. Values of type `SecureString` are stored encrypted with KMS, and every access leaves a trace in CloudTrail. “There is a file somewhere” becomes “a named, versioned, access-controlled value with an audit trail.” ## Architecture: build time versus runtime Before I use the plugin, I draw a line. It is the most important decision of the whole topic, and the plugin doesn’t make it for me. ```mermaid flowchart LR PS["Parameter Store
    /app/env/*"] -->|build time| B["gatsby build"] B --> OUT["Static bundle
    HTML / JS / CSS"] OUT --> CDN["CDN / Browser"] RT["Runtime secrets
    never here"] -.->|not in bundle| OUT ``` Everything that moves into the static bundle at build time is public. Period. An API endpoint, a public content delivery key, a feature flag, an analytics ID – these may be in the shipped JavaScript, because they are visible to every browser anyway. Gatsby even makes this explicit through the `GATSBY_` prefix convention: these variables are deliberately embedded in the client bundle. Anything that is a real secret – write access to a database, a private API key, a signing key – never belongs in a build-time value for a frontend. Not because Parameter Store couldn’t protect it, but because the target is a static artifact that is delivered publicly. The most secure storage in the world doesn’t help if I then write the decrypted value into a file that ends up on a CDN. Parameter Store is a little seductive here, and that is the hard question about secrets: because it offers `SecureString` and KMS, every value feels “secure.” But the security ends at the boundary of the build. That is why I sort every parameter in advance into exactly one of two drawers: “may be public” or “is a runtime secret.” The plugin may only touch the first drawer at all. Real runtime secrets belong in a serverless function or a backend that reads them from Parameter Store itself at runtime and never hands them to the client. ## The second trade-off: reproducibility The second hard question is subtler and easily overlooked. The moment the build reads external configuration, it is no longer a pure function of the repository. The same Git commit no longer necessarily produces the same result – it produces the result that matches the external state of Parameter Store at build time. That is a real loss. If someone changes a value in Parameter Store and doesn’t trigger a rebuild, the deployment and the declared configuration drift apart without any commit showing it. A rollback to an old commit may not restore the old configuration, because the parameter values have changed in the meantime. “Works on my machine” gets a new, unpleasant dimension: on my machine with yesterday’s parameters. Parameter Store has a tool for this problem, and I consider it the decisive methodological lever: every parameter is versioned. I can reference a specific version – `/app/prod/KEY:4` – instead of “whatever the current value is.” That makes the build more deterministic again: a commit plus a pinned set of parameters yields a reproducible artifact. The price is deliberate discipline, because someone has to bump the version and thereby treat the configuration change exactly like a code change: visible, traceable, rollback-capable. That is exactly the point where configuration stops being a sideshow and becomes part of the architecture. ## What this measurably improves The effort pays off because it has a concrete effect in three places, not just elegance. Shorter cycles: a new environment is a new path in Parameter Store, not a new ritual of `.env` files, copy and paste, and questions in the chat. A deploy no longer needs manual preparation, because the configuration lives where the build picks it up anyway. The path from “change the value” to “the value is live” shrinks to a parameter update plus a build. Less friction: access is tied to environments via IAM, not to people with file access. A developer can set a staging configuration themselves without getting at a production secret. Self-service within clean boundaries replaces the bottleneck that otherwise consists of a single person who “knows the `.env`.” Higher quality: config drift becomes structurally less likely, because there is only one source left. And if something does go wrong, there is an audit trail. CloudTrail answers the question “Who changed which value when?” – the question that, with a scattering of files and CI secrets, remains fundamentally unanswerable. There is a fourth effect that is easily overlooked but saves a lot of friction day to day: the same mechanism works locally. A developer who is allowed to read the staging values runs their local build against exactly the same path in Parameter Store as the pipeline – no manual copying of an `.env`, no outdated local state, no discussion about why something behaves differently locally than in staging. That closes one of the most annoying gaps in the development cycle, namely the one between the configuration on the laptop and the configuration in CI. With that, the “works on my machine” from above loses one of its most common causes, because the laptop and the pipeline read from the same source. The boundary still matters here: locally, only the public, build-safe subtree may be visible, never a production runtime secret. ## What I check before using it An idea only holds up once its failure path is described. Before I hook the plugin into a pipeline, I go through a few questions that all stay invisible in demo mode and decide things in operations. What happens if Parameter Store isn’t reachable during the build or an expected value is missing? A build that silently runs through with an empty `process.env.GATSBY_API_URL` is more dangerous than one that aborts loudly – because it produces a broken but deployable artifact. Here I want a hard fail-fast, not an `undefined` that only shows up in the user’s browser. Is access scoped narrowly enough? Via an IAM role, the build runner should be allowed to read exactly the one environment path, with `withDecryption` only for the values it really needs. Broad `ssm:GetParametersByPath` access across the entire hierarchy is convenient, and it is exactly the kind of convenience that makes a security review expensive later. And the crucial question: is there accidentally a real secret in the path the build reads? That isn’t a technical mistake but a disciplinary one – and the most common one. That is why I separate the hierarchy right in the naming, so that build-public values and runtime secrets never end up in the same subtree in the first place, and access that is too broad doesn’t immediately mean a leak. ## The typical mistake The most tempting mistake with this topic is confusing the tool with the solution. Parameter Store isn’t a configuration architecture, any more than encrypted storage is automatically a secrets strategy. It is a very good place to express a boundary – the boundary between build-public configuration and a runtime secret, between environments, between what a build may read and what it should never see. But I create this boundary, not the service. That is exactly where the real value of this small plugin lies. It forces me to answer the question that the `.env` scattering successfully hid: what part of my frontend’s configuration is public, what is secret, and who owns each of these values across its lifecycle? As soon as that answer is in place, the technical rest – a path, a plugin, a `GetParametersByPath` – is almost trivial. ## Closing Parameter Store in the build is a good example of how the interesting decision rarely lies in the tool’s name. The plugin fetches values from AWS – that is the easy half. The load-bearing half is the method behind it: make configuration explicit, keep it in exactly one place with clear access boundaries, enforce the separation of public and secret, and get reproducibility back through pinned versions. If you draw these lines, you gain shorter deploy cycles, less friction with every environment, and fewer silent errors in operations. If you don’t, you end up with very secure storage from which secrets still seep into a public bundle. The difference isn’t in the service but in the decision it makes visible. --- # Running Your Own Docker Registry URL: https://www.mikebild.dev/en/blog/running-your-own-docker-registry/ Date: 2018-11-27 A Docker registry is not a file server where you drop images. It is the namespace through which Docker addresses images in the first place: a fully qualified image name has the form `host:port/name:tag`, and its host part decides where a `push` goes and where a `pull` comes from. If it is missing, Docker Hub is meant – even when the image contains your own application code. **Editorial note (July 2026):** This tutorial describes the state of 2018. Docker Content Trust is based on Notary v1 and is being retired by Docker; for new signing and verification workflows, Docker points to Sigstore or Notation. Portus is no longer a current product recommendation either: the project was archived in 2023. Basic registry operation with `registry:2`, TLS, authentication and immutable digests is not affected by this. If you set this host part yourself, you also decide where your images live, where they come from and who answers for production running exactly what was built and checked. The way there is short. First we clarify why a private registry makes sense at all. Then we start `registry:2` with a single command, tag an image, push it and pull it down again on another host. Because an open registry is a real problem, we secure it with basic auth and TLS. Finally, we go beyond the tool: to the provenance, signing and operational responsibility for your own images. If you already know Docker Compose – for example from my article on [Node.js and Redis with Docker Compose](https://www.mikebild.dev/en/blog/nodejs-and-redis-with-docker-compose/) – you will find your way around here quickly. ## Why your own registry at all? Docker Hub is convenient. You push an image, it sits in the cloud, anyone can pull it. But in many company contexts, that is exactly the problem: your own application code is in the image, and it should not be publicly visible. Sure, Docker Hub has private repositories, but then the entire deployment chain depends on an external service and on an internet connection that can be slow or disrupted at times. A private registry in your own network solves these points in one go. The images stay internal, pulling runs over the local network and is noticeably faster, and you keep full control over where the data lives and how long it is kept. Especially in a CI/CD pipeline that pushes many builds around every day, this shows quickly. To make the differences tangible, I like to put the two side by side: - I host the private registry myself, in my own network, with full control over storage location and lifecycle – in return, I also operate and secure it myself. - Docker Hub is a hosted service with accounts, organizations, a web UI and official images – in return, it depends on the internet and lives outside your own infrastructure. Both have their place. I still pull official base images such as `node`, `redis` or `registry` itself from Docker Hub. My own application images, on the other hand, go into the private registry. One does not exclude the other. ## The registry itself is just a container Let’s get to the actual tool. The open source registry that uses the same technology behind Docker Hub is called “Docker Distribution” and is provided as the ready-made image `registry:2`. No separate server, no elaborate installation – one `docker run`, and the registry is running. By default it listens on port 5000. ```bash docker run -d \ -p 5000:5000 \ --restart=always \ --name registry \ -v /mnt/registry:/var/lib/registry \ registry:2 ``` A few things here are set deliberately. `-d` starts the container in the background. `--restart=always` makes sure the registry comes back up on its own after a restart of the Docker daemon or the host – for a service the whole pipeline depends on, you want that. And most important: the volume with `-v`. By default, the registry stores its images under `/var/lib/registry` via the filesystem storage driver. Without a volume, this data lives only in the container. Delete the container, and the images are gone. With the mounted directory `/mnt/registry`, they persist. With that, the registry is running. But it does nothing visible yet – it is waiting for its first image. ## Tag, push, pull The decisive point when working with your own registry is the image name. Docker does not use a separate configuration switch to decide which registry an image goes to; it uses the name itself. A fully qualified image name has the form `host:port/name:tag`. If the host part is missing, Docker automatically assumes Docker Hub (`docker.io`). If I put my own registry host in front of the name, Docker knows exactly where to go on `push` and `pull`. Let’s say I have built an image `app:1.0` locally. Then I retag it for my registry: ```bash docker tag app:1.0 registry.local:5000/app:1.0 ``` `docker tag` copies nothing and rebuilds nothing – it just attaches a second name to the same image. Then I push it into the registry: ```bash docker push registry.local:5000/app:1.0 ``` Docker reads the host part `registry.local:5000` from the name and uploads the individual layers there. On another machine in the same network – or on the CI runner that later handles the deployment – I pull the image down again the same way: ```bash docker pull registry.local:5000/app:1.0 ``` That is the complete cycle. Build, tag, push, pull somewhere else. I like to capture exactly this arc as a diagram, because it shows how the pieces fit together at a glance: ```mermaid flowchart LR A[docker build
    app:1.0] --> B[docker tag
    registry.local:5000/app:1.0] B --> C[docker push] C --> D[(Private Registry
    :5000)] D --> E[docker pull
    other host / CI] ``` So the whole mechanism hinges on the registry host. That also explains why retagging before the push is necessary: an image named just `app:1.0` would be sent toward Docker Hub. ## The weak spot: out of the box, everything is open The registry we just started runs without any protection. No password, no encryption. Anyone who can reach `registry.local:5000` on the network can push and pull. For a quick local test on your own machine, that is fine. But as soon as the registry is reachable from more than one machine, it must not stay like this. Securing it consists of two independent building blocks that you should not confuse: - TLS encrypts the transport so nobody can read what goes over the wire. - Basic auth via htpasswd protects access so only authorized users can push and pull. One does not replace the other. TLS without auth encrypts, but lets everyone in. Auth without TLS, in turn, is not accepted by the registry at all – the passwords would go over the network in plain text, and `registry:2` deliberately does not allow that. So both belong together. Let’s look at auth first. For basic auth, the registry needs an `htpasswd` file, and it must use bcrypt hashes. The easiest way to create it is with the `httpd` image, which ships the `htpasswd` tool: ```bash docker run --rm --entrypoint htpasswd httpd:2 \ -Bbn deploy s3cret > auth/htpasswd ``` The flags are quickly explained: `-B` forces bcrypt (mandatory for the registry), `-b` passes the password directly on the command line, and `-n` prints the result to stdout instead of writing it to a file – which is why I redirect the output to `auth/htpasswd` myself. The result is a user `deploy` with the password `s3cret`. For TLS, I need a certificate and the matching key. In a real environment they come from an internal CA or from Let's Encrypt; in a test network, a self-signed pair will do. I put the two files as `domain.crt` and `domain.key` into a `certs` directory. Now I restart the registry – this time with both layers of protection. I pass the configuration through environment variables that the registry reads at startup: ```bash docker run -d \ -p 5000:5000 \ --restart=always \ --name registry \ -v "$(pwd)"/auth:/auth \ -v "$(pwd)"/certs:/certs \ -v /mnt/registry:/var/lib/registry \ -e REGISTRY_AUTH=htpasswd \ -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \ -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \ -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \ -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ registry:2 ``` The `REGISTRY_AUTH_*` variables turn on htpasswd authentication and point to the file we just created in the mounted `/auth` directory. The two `REGISTRY_HTTP_TLS_*` variables enable TLS with the certificate and key from `/certs`. From now on, you have to log in before you can push anything: ```bash docker login registry.local:5000 ``` After logging in with username and password, `push` and `pull` work as usual again – just secured. Docker remembers the login locally, so the pipeline runs through after a one-time `docker login`. For completeness: instead of setting everything through environment variables, you can also give the registry its own `config.yml`. It contains the same settings in structured form under `auth.htpasswd`, `http.tls` and `storage.filesystem`. You then build a small image `FROM registry:2`, copy the configuration into it and start it with the matching entrypoint. Both ways are common; for getting started, I find the environment variable variant clearer, because you see everything in one command. This picture shows how the two layers of protection work together and where the insecure emergency exit is: ```mermaid flowchart LR C[Client] -->|TLS| R[Registry container :5000] R -->|htpasswd auth| S[(Storage volume
    /var/lib/registry)] C2[Client without TLS] -.HTTP.-> I[insecure-registries
    test network only] I -.-> R ``` ## When no TLS is at hand When you are trying things out quickly, it happens that no certificate is at hand, but you still want to test a push. Then you run into a typical error message: `http: server gave HTTP response to HTTPS client`. By default, the Docker client expects HTTPS and refuses to talk to a plain HTTP registry. For exactly this case there is an exception – but you should really only use it in an isolated test network. On every client, you add the registry as “insecure” to the file `/etc/docker/daemon.json`: ```json { "insecure-registries": ["registry.local:5000"] } ``` Then the Docker daemon has to be restarted for the change to take effect. The important part is “on every client”: the entry applies locally per machine, not centrally in the registry. If you use the registry on five hosts, you maintain the entry five times. For a registry in permanent operation, that is no way to run things – there is no way around TLS. By the way, if you use a self-signed certificate, you have to install it as a CA on the clients, otherwise the Docker client distrusts it just the same. ## The registry as a checkpoint in the supply chain So far, the registry has mainly been a means of transport: build, tag, push, pull. But the real leverage sits one level higher. As soon as all your own images run through a registry that you control yourself, it becomes the central point where the provenance of what runs in production is decided. In many company contexts, that counts for more than the few seconds a pull saves on the local network. The first point is provenance. A tag like `registry.local:5000/app:1.0` is convenient, but mutable. Nothing stops someone from later overwriting the same tag with different content – the name stays the same, the image behind it is a different one. If you want to know for certain which image is running, you reference it by its digest instead of its tag: ```bash docker pull registry.local:5000/app@sha256:9b2a4c... ``` The digest is the hash over the image content and therefore immutable. When a CI runner or a production host pulls an image by digest, it is guaranteed to get exactly the bits that were once built and checked – not whatever happens to sit under the tag right now. In the pipeline, this means: the build outputs the digest, the deployment pins exactly this digest, and the tag remains only a readable name for humans, not an anchor of trust. The second point is signing. Provenance via the digest says “it is the same image,” but not yet “it comes from whoever it is supposed to come from.” That is what Docker Content Trust is for. If I set `DOCKER_CONTENT_TRUST=1`, Docker signs the images on push and requires a valid signature on pull: ```bash export DOCKER_CONTENT_TRUST=1 docker push registry.local:5000/app:1.0 ``` In the background, a Notary service manages the signatures and the associated keys. The gain is that a client recognizes a planted or tampered image and refuses the pull instead of running it blindly. This takes effort – keys need to be created, stored securely and rotated – and it is overkill for a pure test setup. But as soon as images run all the way into production, the question “did we build this, and has nobody touched it since?” is no longer academic. The third point is operational responsibility, the flip side of all that control. If you run the registry yourself, you do not just decide who may push and pull. You are also responsible for the service running, being patched, keeping its data and staying recoverable if needed. This responsibility does not disappear; it only changes owners. With Docker Hub, the provider carries it; with your own registry, I carry it. In 2018, this produced the real decision criterion. `registry:2` was enough as long as provenance and access were covered with digests, a handful of htpasswd users and Content Trust. But as soon as many teams, fine-grained permissions, traceable audit logs and a reliable separation between “built” and “approved for production” were required, products such as Portus, Sonatype Nexus or JFrog Artifactory came into play. Portus has since been archived; for a selection today, maintenance and support status has to be checked again. ## What to keep an eye on in operation Two things tend to get lost in the first wave of enthusiasm. The first is the persistence already mentioned: without a mounted volume, you lose all images on the next container restart. So the volume is not optional but basic equipment. The second is disk space. The filesystem backend grows with every push, and old layers that have long been unneeded do not disappear on their own. Over time, the disk fills up. The registry ships a garbage collection for this, which you should run regularly to clean up blobs that are no longer referenced. This is easily forgotten in operation and takes its revenge months later with a full disk. A backup of the storage directory belongs here as well – with a self-hosted registry, nobody else takes care of it. These are the concrete chores behind the words operational responsibility. The fact that `registry:2` starts with one command does not take them off your hands – from then on, they are mine. ## Conclusion Your own Docker registry sounds like an infrastructure project, but technically it is a matter of a few minutes – as long as you have internalized the decisive points. The registry itself is just a container, `registry:2`, and the registry host is addressed through the image name `host:port/name:tag`. Out of the box everything is open, and securing it always needs both building blocks – TLS for encrypted transport and htpasswd for access control. The `insecure-registries` entry is a crutch for test networks, not a way to operate. The real gain only shows in operation. Your own images live in your own network, are available faster and shorten the paths in the pipeline. With digests and the Docker Content Trust common at the time, fast delivery became traceable delivery – you knew what was running and where it came from. The limits are just as clear: where governance across many teams, fine-grained permissions and complete audits are required, `registry:2` ends and a specialized product begins. For everything before that, a container, a cleanly set host part in the image name and two layers of protection are enough. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-docker-kubernetes.en.html - [Deploy a registry server – docs.docker.com](https://docs.docker.com/registry/deploying/) - [Run an externally-accessible registry (basic auth + TLS)](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry) - [Registry configuration reference (config.yml)](https://docs.docker.com/registry/configuration/) - [Test an insecure registry (daemon.json)](https://docs.docker.com/registry/insecure/) - [docker tag / docker push / docker pull / docker login – CLI reference](https://docs.docker.com/engine/reference/commandline/tag/) - [Docker Content Trust and Notary v1](https://docs.docker.com/engine/security/trust/) - [Docker: retired products and recommended alternatives](https://docs.docker.com/retired/) - [Portus – archived repository](https://github.com/SUSE/Portus) - [Node.js and Redis with Docker Compose](https://www.mikebild.dev/en/blog/nodejs-and-redis-with-docker-compose/) --- # Kubernetes Basics Under Deployment Pressure URL: https://www.mikebild.dev/en/blog/kubernetes-basics-under-deployment-pressure/ Date: 2018-10-24 # Kubernetes Basics Under Deployment Pressure At two in the morning, a container dies. No attack, no hardware defect – the Node.js process inside tripped over a memory leak, the operating system killed it, and with the process, the container is gone too. From this moment on, a single question decides how the rest of the night goes: Who restarts it when nobody is watching? On a classically operated server, the answer is always a chain of people and semi-automation – monitoring that calls someone, a systemd unit with a restart rule, an admin with SSH access and little sleep. The lesson from such nights is the real reason Kubernetes exists: a system in which the restart isn’t a human reaction but the normal operation of a machine that continuously compares desired and actual state. ## The docs explain everything except the order If you try to learn Kubernetes from the concept documentation, you get a vocabulary list: pods, ReplicaSets, deployments, services, endpoints, ingress, ConfigMaps, secrets, volumes, namespaces, DaemonSets, StatefulSets, jobs, CronJobs. All correctly described, all side by side with equal weight. That is exactly the problem. The docs are a reference work, not a learning order – and without an order, Kubernetes feels like a foreign language where you are only allowed to speak once you know the entire dictionary by heart. I noticed this this year in a project in which an existing Node.js application, including its database, was supposed to move into a cluster – with a deadline, not someday. Under this deployment pressure, something interesting happened: the concepts sorted themselves. Not by the structure of the documentation, but by the question of which object the application can’t run without right now. What remained was a surprisingly short list: - Pod – what actually runs - Deployment – what keeps pods alive - Service – a stable address in front of unstable pods - Ingress – the door to the outside - ConfigMap and Secret – configuration out of the image Everything else – StatefulSets, DaemonSets, NetworkPolicies, the finer points of RBAC – only came up later, when the application was already running and the pressure had eased. The examples I used to play through this order are public in the repository [introduction-kubernetes](https://github.com/MikeBild/introduction-kubernetes): a collection of material around a small todo application with frontend, backend and database that you can follow locally with Minikube. ## Desired state instead of command choreography The most important basic insight isn’t in any YAML example but behind them: Kubernetes is declarative. You don’t tell the cluster what to do; you describe what the world should look like when everything is fine. Three copies of this container, reachable under this name, with this configuration. A controller loop compares this desired state with reality nonstop and corrects the difference. If a pod dies, one is missing – so one gets started. Not because someone gives a command, but because desired and actual state no longer match. ```mermaid flowchart LR M[Manifest
    todo-api.yaml] -->|kubectl apply| A[API server] A --> E[(etcd
    desired state)] C[Controller loop] -->|reads desired| E C -->|measures actual| P[Pods in the cluster] C -->|corrects difference| P ``` That also explains why `kubectl apply -f` is the central command – and not a choreography of “start this, then that, then wire both together”. On the old server, a deployment was a screenplay: shell scripts in the right order, and heaven help you if step four fails while step three has already gone through. In Kubernetes, this screenplay no longer exists. There is only a description of the desired state, and `apply` hands it over. What happens afterwards is the controllers’ business – even at two in the morning. ## The pod: what actually runs A pod is the smallest unit Kubernetes starts: one or more containers that share network and lifecycle. In practice, almost always one container per pod. The second insight under pressure: pods are disposable. You rarely create them directly, you don’t look after them, you don’t repair them. A pod that dies isn’t healed but replaced – with a new name and a new IP address. Once you accept that, you understand the rest of the system almost by itself. If, on the other hand, you try to cling to individual pods, climb into them with `kubectl exec` and rescue state, you fight against the platform instead of working with it. ## The deployment: self-healing as the core idea Because pods are mortal, something is needed to keep them alive. That is the deployment – for me, the actual heart of it all: ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: todo-api spec: replicas: 3 selector: matchLabels: app: todo-api template: metadata: labels: app: todo-api spec: containers: - name: todo-api image: mikebild/todo-api:1.4.2 ports: - containerPort: 3000 readinessProbe: httpGet: path: /health port: 3000 initialDelaySeconds: 5 livenessProbe: httpGet: path: /health port: 3000 initialDelaySeconds: 15 ``` Since Kubernetes 1.9, `apps/v1` has been the stable API version for this; the guesswork of the early beta versions is over. The deployment describes three things: how many copies should run, what a pod has to look like and how the cluster recognizes whether a pod is healthy. The readiness probe decides whether a pod gets traffic; the liveness probe decides whether it gets restarted. I underestimated this distinction at first – until a backend needed twenty seconds at startup to connect to the database, and without a readiness probe, requests happily ran into a system that wasn’t ready yet. The moment Kubernetes “clicked” for me was a deliberately provoked failure: ```bash kubectl apply -f todo-api.yaml kubectl get pods --watch kubectl delete pod todo-api-7d9f6c8b45-x2x7k # simulate a crash # a replacement pod appears within seconds kubectl rollout status deployment todo-api kubectl rollout undo deployment todo-api # roll back a bad release ``` You delete a pod, and before you have read the output, the replacement is already there. That is the answer to the two-in-the-morning question – not as a feature promise but observable in the terminal. And `rollout undo` turns a failed release from an emergency into a step back to the last working desired state. ## The service: a stable address in front of unstable pods If pods constantly come and go and change their IP addresses in the process, nobody can connect to them directly. The service solves exactly this problem: a stable virtual address and a DNS name, with a changing set of pods behind it, selected via labels. ```yaml apiVersion: v1 kind: Service metadata: name: todo-api spec: selector: app: todo-api ports: - port: 80 targetPort: 3000 ``` From now on, every pod in the cluster reaches the backend at `http://todo-api` – no matter which three pods happen to be behind it, no matter how often they have been replaced. The todo application’s frontend no longer knows any IP addresses, only this name. For me, this was the point at which the migration work paid off for the first time: service discovery, which previously consisted of maintained configuration files and hope, is simply DNS in the cluster. ## The ingress: the door to the outside At first, services are only reachable inside the cluster. For the way out, there is the ingress – a rule that maps hostnames and paths to services, executed by an ingress controller such as ingress-nginx: ```yaml apiVersion: extensions/v1beta1 kind: Ingress metadata: name: todo-api spec: rules: - host: todo.example.com http: paths: - path: / backend: serviceName: todo-api servicePort: 80 ``` ```mermaid flowchart LR B[Browser] --> I[Ingress
    todo.example.com] I --> S[Service
    todo-api] S --> P1[Pod] S --> P2[Pod] S --> P3[Pod] ``` To be honest, the ingress is the most unfinished corner of this list: the resource has been in beta status for years (`extensions/v1beta1`), the controller isn’t part of the cluster but has to be installed separately, and depending on the environment – Minikube, your own cluster, GKE – things behave slightly differently. Still, it belongs to the basic equipment, because without a door to the outside, even the nicest application remains a monologue. ## ConfigMap and Secret: configuration out of the image The last building block on the pressure list sounds unspectacular but has the biggest effect on everyday work: configuration doesn’t belong in the container image. An image that has to be rebuilt for staging because a database address is different isn’t an artifact but a hack. ConfigMaps and secrets pull these values out of the image and into the cluster: ```yaml apiVersion: v1 kind: ConfigMap metadata: name: todo-api-config data: DATABASE_HOST: "postgres" LOG_LEVEL: "info" ``` In the deployment, `envFrom` turns this into a set of environment variables, and the same image runs unchanged locally in Minikube and in the cluster at the cloud provider. With secrets, a sober look is worth it: the values are Base64-encoded, not encrypted. That separates them cleanly from the rest of the configuration and keeps them out of Git, but it isn’t a vault. ## Debugging without SSH Something else you learn immediately under pressure: debugging works differently than on a server. There is no SSH into “the machine”, because it’s unclear which machine would even be meant. Instead, you ask the cluster what it knows about the state: ```bash kubectl describe pod todo-api-7d9f6c8b45-x2x7k kubectl logs todo-api-7d9f6c8b45-x2x7k kubectl logs todo-api-7d9f6c8b45-x2x7k --previous # logs of the crashed container kubectl get events --sort-by=.metadata.creationTimestamp ``` `describe` shows the events – that is where the classics are spelled out in plain text: `ImagePullBackOff` when the image can’t be found, `CrashLoopBackOff` when the container dies at startup. And `logs --previous` shows the output of the container that just crashed – exactly what you want to know at two in the morning. That isn’t necessarily easier than before, but it is more systematic: the cluster logs what it decided, and you don’t have to piece it together from four different log files. ## What the pressure doesn’t argue away Honesty also includes the other side. For a single small application, there are now five YAML files in the repository, together well over a hundred lines – for something that Docker Compose would describe in twenty lines. Helm promises relief through packaging, but in version 2, with Tiller, it brings its own server component with far-reaching permissions into the cluster – trading YAML volume for operational and security questions, a trade I wouldn’t make in every project yet. And even though Amazon, as the last of the big providers, has offered managed Kubernetes with EKS since June, and GKE and AKS take cluster setup off your hands: they don’t take the concepts off your hands, and a cluster you set up yourself with kubeadm is a whole operational task of its own. That’s why the sober counter-check comes before the migration starts. A single host with Docker Compose is simply enough when a few things come together: - the application runs on one machine, and short outages are tolerable - a restart policy in the Compose file covers the nightly process death well enough - there is no team deploying in parallel and no load that requires scaling Then Kubernetes mostly buys you complexity and gives little back. The point at which the calculation flips can be named surprisingly precisely: as soon as the question “who restarts it when nobody is watching?” may no longer be answered with “the one machine, hopefully”. ## What I take away from it Deployment pressure is an unpleasant but honest teacher. It didn’t replace the concept docs for me, but it sorted them: first the pod as what actually runs, then the deployment as its guardian, then the service as a stable address, the ingress as the door to the outside, ConfigMap and secret as externalized configuration. Five objects with which a real application runs in production – the rest of the dictionary can wait until it is needed. The deeper insight is the declarative way of thinking. The switch from the screenplay (“execute these steps”) to the desired state (“this is how it should look”) changes how you think about operations – outages are no longer incidents but differences that a controller evens out. And the two-in-the-morning question from the beginning gets its best answer: nobody restarts it. When the first person looks at the dashboard in the morning, the restart is a line in the events – happened, logged, done. ## Further reading - Repository with the examples: https://github.com/MikeBild/introduction-kubernetes - Kubernetes documentation on deployments: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/ - Kubernetes documentation on services: https://kubernetes.io/docs/concepts/services-networking/service/ - Kubernetes documentation on ingress: https://kubernetes.io/docs/concepts/services-networking/ingress/ - Using ConfigMaps in pods: https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/ --- # Central Logging with the ELK Stack in Docker URL: https://www.mikebild.dev/en/blog/central-logging-with-the-elk-stack-in-docker/ Date: 2018-09-18 `docker logs ` scales up to exactly one. With a frontend, an API, a database and a cache, that’s four calls in four terminals; with three hosts and a few replicas, it quickly becomes fifteen – and each one shows only its own slice, and only as long as the container lives. **Editorial note (July 2026):** The example deliberately uses Docker Compose and ELK 6.4 from 2018. It is not a current production template. Regardless of the version, the Docker GELF driver supports both UDP and TCP; the earlier claim that it could only do UDP was already wrong in 2018. The decision behind it is less a technical one than a strategic one. The question isn’t “which logging driver do I configure?” but “how much visibility into my system do I want, and what do I pay for it in storage, compute and operational effort?” Central logging isn’t a feature you switch on. It’s an investment with running costs. If you treat the ELK setup as a pure API exercise, you will reliably build a system that either shows too little or fills up the disk. That’s why placing logs in context comes here before the first reconfigured container. This is exactly where the ELK stack comes in. In this article I walk the path I also take in projects: first place logs within the observability strategy, then understand where Docker actually writes the logs and which logging drivers exist, then set up a complete ELK stack with Docker Compose, send the logs of an app container there and finally make them searchable in Kibana. Along the way I collect the pitfalls I’ve run into most often in practice. ## Logs as one of three pillars Before you switch a single driver, the context needs to be clear: logs are only one of three pillars that visibility into a distributed system rests on, and none of the three replaces the others. Metrics are aggregated numbers over time – requests per second, error rate, memory usage – and answer “is something broken right now, and since when?”. Logs are individual events with context and answer “what exactly happened in this one case?”. Traces follow a request across several services and answer “where in the path is it stuck?”. The ELK stack covers the middle pillar, and it helps enormously to know that consciously: if you try to watch an error rate over time with logs alone, you pay far more than a simple metric would have cost. And that brings us to the heart of the matter: cost. Logs are the most tempting and at the same time the most expensive of the three pillars, because every single line is stored and, in Elasticsearch, indexed by default. The cost driver is called cardinality. A field with few possible values – say a `log_level` with `info`, `warn`, `error` – is cheap to index. A field with an almost unlimited number of distinct values – a `request_id`, a `user_id`, a full query string – drives up the size of the index and with it the storage and RAM requirements. With metrics, such high cardinality quickly becomes an existential threat; with logs it’s expensive but manageable, as long as you control it deliberately. That control is the actual design work, and it comes down to a few levers. First: what ends up in the log at all, and at which level? A `DEBUG` that keeps running in production is a pure cost driver with no return. Second: how long do I keep logs? The daily index I build further down is exactly the lever for that – entire days can be deleted in one go. Third: does every event really need to be fully indexed, or is a sample enough at high volume? The rule behind it is simple and still annoying to implement: you don’t log everything that’s possible, you log what you actually want to read when something goes wrong – and you don’t pay for the rest. The rest of this article shows the mechanics; whether they are set up with cost awareness decides whether the setup still holds after three weeks. ## Where Docker logs end up by default Docker has a concept that surprises many people at first: it doesn’t care what happens in your application, only what gets written to STDOUT and STDERR. Everything the process with PID 1 in the container writes to these two streams is captured by Docker and handed to a so-called logging driver. The default driver is called `json-file`. It writes each log line as a JSON object to a file on the host, typically under `/var/lib/docker/containers//-json.log`. This is exactly the file `docker logs` reads from. That’s also the reason for a quirk that causes confusion in practice: `docker logs` only works with `json-file` (and `journald`). If you switch the driver to `gelf` or `syslog` because you want to send the logs somewhere else, the local `docker logs` command for that container is empty. The logs haven’t disappeared, they just aren’t kept locally anymore. The drivers available as of 2018 are quite a list: - `json-file` and `journald` – local, readable with `docker logs`. - `syslog`, `gelf`, `fluentd`, `splunk` – forwarding to a central receiver. - `awslogs`, `gcplogs`, `etwlogs` – platform-specific targets. - `none` – logging switched off entirely. For centralization, `gelf` and `syslog` are the most interesting. They send the log lines over the network to an endpoint – and that endpoint can be Logstash. You can set a logging driver per container with `docker run`: ```bash docker run \ --log-driver=gelf \ --log-opt gelf-address=udp://logstash:12201 \ --log-opt tag="myapp" \ myorg/myapp:latest ``` In Compose, the same thing per service looks like this: ```yaml version: "3" services: app: image: myorg/myapp:latest logging: driver: "gelf" options: gelf-address: "udp://logstash:12201" tag: "myapp" ``` A detail worth knowing: the `gelf` driver supports UDP and TCP. This example uses UDP. It’s fast and lean, but it doesn’t confirm receipt – if a message gets lost under load, it’s gone. TCP is connection-oriented, but that still doesn’t turn a log transport into a tamper-proof audit trail. ## The three roles in the ELK stack Before we write Compose, it’s worth a look at the three letters. ELK stands for Elasticsearch, Logstash and Kibana, and each component has exactly one clearly defined job. Elasticsearch stores and indexes: it’s the search engine at the center that makes every log line searchable and holds the data. Logstash receives, parses and transforms – it’s the front door that accepts logs from various sources, gives them structure and passes them on to Elasticsearch; its pipeline consists of `input`, `filter` and `output`. And Kibana visualizes and searches: the web UI where you filter logs, build dashboards and make patterns visible. The data flow is a short chain: ```mermaid flowchart LR A[App Container] -->|stdout / gelf| B[Logstash] B -->|index| C[Elasticsearch] C -->|query| D[Kibana] E[Browser] -->|http :5601| D ``` The app writes to STDOUT, the Docker driver forwards to Logstash, Logstash indexes into Elasticsearch, and Kibana makes the whole thing visible in the browser. The important part: the application itself knows nothing about any of this. It logs to STDOUT and STDERR – the way the Twelve-Factor principle intends – and transport is the infrastructure’s job. No custom log file handling in the container, no rotation logic in the app. That keeps the application clean and makes the log path replaceable. ## The Compose stack Now let’s build the stack. I deliberately pin the images to a fixed version – in this case the 6.4 line – because an untagged `elasticsearch:latest` is the most reliable source of “but it looks different on my machine.” Here’s the `elk-compose.yml`: ```yaml version: "3" services: elasticsearch: image: docker.elastic.co/elasticsearch/elasticsearch:6.4.0 environment: - discovery.type=single-node - "ES_JAVA_OPTS=-Xms512m -Xmx512m" volumes: - es-data:/usr/share/elasticsearch/data ports: - "9200:9200" - "9300:9300" logstash: image: docker.elastic.co/logstash/logstash:6.4.0 volumes: - ./pipeline:/usr/share/logstash/pipeline ports: - "12201:12201/udp" depends_on: - elasticsearch kibana: image: docker.elastic.co/kibana/kibana:6.4.0 environment: - ELASTICSEARCH_URL=http://elasticsearch:9200 ports: - "5601:5601" depends_on: - elasticsearch volumes: es-data: ``` A few points in the configuration are there on purpose. Elasticsearch gets `discovery.type=single-node` so it doesn’t look around in vain for cluster peers. The heap is fixed at 512 megabytes with `ES_JAVA_OPTS` – that’s enough for trying things out; in production you would size it more generously, but always with the same `Xms` and `Xmx`. And the data lives on a named volume `es-data` so it survives a container restart. That’s not a detail: if you forget the volume, every `docker-compose down` loses all indexed logs – especially annoying for, of all things, the log system. Kibana gets the address of Elasticsearch through `ELASTICSEARCH_URL`. The service name `elasticsearch` works as a hostname because Compose puts all services on the same network and provides name resolution. What’s still missing is the Logstash pipeline. It lives as `pipeline/logstash.conf` next to the Compose file and defines how Logstash accepts messages and where it writes them: ```ruby input { gelf { port => 12201 } } filter { # room for grok, mutate, date & co. } output { elasticsearch { hosts => ["elasticsearch:9200"] index => "docker-logs-%{+YYYY.MM.dd}" } } ``` The `gelf` input listens on port 12201 – exactly the port our app service sends its logs to. The `filter` block is empty here, but in real setups that’s where the actual work happens: splitting lines into fields with `grok`, normalizing timestamps with `date`, renaming fields with `mutate`. The `output` block writes to Elasticsearch, into a daily index `docker-logs-2018.09.18`. This pattern is chosen on purpose: one index per day makes cleaning up old logs easy later, because you can delete whole indexes instead of hunting for individual documents. ## Connecting the app What’s still missing is the application whose logs we want to see. I add an app service to the same stack and give it the `gelf` logging driver: ```yaml app: image: myorg/myapp:latest logging: driver: "gelf" options: gelf-address: "udp://localhost:12201" tag: "myapp" depends_on: - logstash ``` The `gelf` driver has a stumbling block that almost certainly shows up the first time you set it up: the `gelf-address` is resolved by the Docker daemon on the host, not from inside the container network. That’s why it says `udp://localhost:12201` with the mapped host port, not the service name `logstash`. The daemon doesn’t know Compose’s internal DNS – it only sees the port Logstash publishes on the host. When you start the stack with `docker-compose -f elk-compose.yml up`, Elasticsearch comes up first, then Logstash and Kibana, then the app. From now on, every log line of the app flows as a GELF message to Logstash, gets indexed and is visible in Kibana. A word about ordering: `depends_on` only controls the order in which Docker starts the containers – not whether the respective service is ready yet. After starting, Elasticsearch needs a few seconds until the index is green, and during that time Kibana likes to report “Kibana server is not ready yet” in the browser. That’s not an error, that’s the reality of asynchronous startup. Take a breath, reload the page. ## Searching in Kibana Kibana runs on port 5601. On first access it asks for an index pattern – you enter `docker-logs-*`, pick the time field, and the Discover tab already shows the log lines trickling in. From here you filter by the `tag` field (`myapp`), run full-text searches on the messages, narrow down time ranges and build visualizations if needed. The aha moment reliably comes right here: scattered `docker logs` calls across several terminals turn into a single searchable UI. ## Pitfalls from practice Three things go wrong most often with this setup, and I’ve experienced all three live more than once. The classic is that Elasticsearch doesn’t even start and the log says `max virtual memory areas vm.max_map_count [65530] is too low`. Elasticsearch 6.x requires `vm.max_map_count=262144` on the host. That’s a kernel setting, not a container parameter, and it has to be set on the Docker host: ```bash sudo sysctl -w vm.max_map_count=262144 ``` On a Docker Machine with VirtualBox, you set it in the VM accordingly. If you forget it, no container restart helps – Elasticsearch dies reproducibly on startup. The second pitfall is log volume. The default driver `json-file` writes to disk without limit. A chatty container can fill up a development machine overnight. That’s why `json-file` always needs a limit: ```yaml logging: driver: "json-file" options: max-size: "10m" max-file: "3" ``` And for the UDP transport of `gelf` chosen here, what I touched on above applies: under load, messages can get lost without anything blowing up anywhere. For critical logs, GELF over TCP or a buffered collector are options. Whether a log has to be complete, immutable and provable remains a separate business requirement beyond that. The third point is the startup coupling already mentioned. Logstash and Kibana need a reachable Elasticsearch. `depends_on` only guarantees the start, not readiness. In production you solve that with health checks and retry logic; when trying things out locally, it’s usually enough to know that “not ready” in the first few seconds is normal and no reason to panic. ## Two ways of forwarding Finally, a bit of context that shows the logging driver isn’t the only way. There are basically two approaches to getting logs from containers to Logstash. The first is the one we took here: the Docker logging driver on the app service forwards directly. The second is a log collector as a sidecar – an additional container such as logspout that reads the Docker socket and forwards the collected logs of all containers via syslog. The advantage of the collector approach is that you don’t have to change anything on the app services and `docker logs` keeps working, because the containers stay on the default driver. The downside is one more moving part in the stack. Which way fits better depends on how much control you have over the individual services – with third-party images, the collector is often the more pragmatic choice. If you want to embed the ELK stack in a larger Compose setup, [Node.js and Redis with Docker Compose](https://www.mikebild.dev/en/blog/nodejs-and-redis-with-docker-compose/) covers the basics for multi-part stacks. Compose keeps several parallel projects apart through their own project names and the networks derived from them. ## Conclusion Container logs are local and ephemeral by default – that’s no problem with one container and a big one with twenty. The ELK stack solves this with a clear division of labor: Logstash receives and transforms, Elasticsearch stores and indexes, Kibana makes things searchable. With its logging drivers, Docker provides the bridge to get a container’s logs there in the first place, without having to touch the application. The effect I care about is a shift in day-to-day work. The path from incident to cause gets shorter, because you no longer piece together `docker logs` across several terminals but filter in one UI. Friction drops, because the app stays clean – it logs to STDOUT and STDERR, and transport stays the infrastructure’s job and therefore replaceable. And the quality of diagnoses goes up, because a searchable history reveals patterns that get lost in an ephemeral single log. If you know the three big pitfalls – `vm.max_map_count`, unlimited log volume and readiness at startup – you can cover this path in an afternoon. Knowing the limits is just as important. Logs are one of several telemetry signals, not all of observability: for trends over time, metrics are cheaper; for the path of a request through several services, traces are the right tool. Costs grow with volume and cardinality, which is why retention, log levels and the question of which fields get indexed have to remain deliberate decisions. And the `gelf` over UDP used here is fine for non-critical application logs, but not for audit trails or billing data, where no message may get lost. Within these limits, the core stays simple: the app logs to STDOUT and STDERR, everything else is infrastructure – and what that infrastructure costs is up to you. ## Further reading - Slide deck on this topic: https://slides.mikebild.dev/introduction-docker-kubernetes.en.html - [Docker GELF logging driver – TCP and UDP configuration](https://docs.docker.com/engine/logging/drivers/gelf/) - [Docker 17.11 release notes – introduction of GELF TCP support](https://docs.docker.com/engine/release-notes/17.11/) - [Docker: Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/) - [Docker: json-file logging driver](https://docs.docker.com/config/containers/logging/json-file/) - [Docker: gelf logging driver](https://docs.docker.com/config/containers/logging/gelf/) - [Docker: syslog logging driver](https://docs.docker.com/config/containers/logging/syslog/) - [Elastic: Getting started with the Elastic Stack and Docker Compose](https://www.elastic.co/blog/getting-started-with-the-elastic-stack-and-docker-compose) - [Elasticsearch 6.4: Install with Docker](https://www.elastic.co/guide/en/elasticsearch/reference/6.4/docker.html) - [Kibana 6.4: Running Kibana on Docker](https://www.elastic.co/guide/en/kibana/6.4/docker.html) - [Logstash 6.4: Running Logstash on Docker](https://www.elastic.co/guide/en/logstash/6.4/docker.html) - [Reference stack: deviantony/docker-elk](https://github.com/deviantony/docker-elk) --- # Micro-Frontends: Team Boundaries in the Browser URL: https://www.mikebild.dev/en/blog/micro-frontends-team-boundaries-in-the-browser/ Date: 2018-08-21 # Micro-Frontends: Team Boundaries in the Browser Four teams, one `index.html`, one shared deployment per week. The math behind it looks harmless and is not: every release requires two days of code freeze, a regression round over the entire UI and four approvals. If one team is not done, three others wait. With fifty working weeks a year, that is at best fifty opportunities to ship something – and in practice far fewer, because a single failed smoke test holds back the entire release. Yet the backends of these teams have long been separate services with their own pipelines. In the browser, though, all four come together again in a single JavaScript bundle, and with the bundle returns exactly the bottleneck that splitting into services was supposed to remove. ## An organizational problem with a technical symptom Micro-frontends are often discussed as a frontend topic: which framework, which integration technique, how small a fragment may be. Over the past few months, I have noticed that this discussion regularly misses the core. The real question is: Does the structure in the browser reflect the structure of the organization – or does it work against it? Conway’s observation from 1968 applies here too: systems mirror the communication paths of the organization that builds them. When four teams work separately by domain but maintain a shared single-page application, friction arises exactly at this seam – as merge conflicts in the router configuration, as coordination rounds over CSS classes, as a release calendar that becomes a permanent topic. The pattern is not new. The ThoughtWorks Technology Radar has listed “Micro Frontends” since November 2016, and since May of this year in the “Trial” ring. With the Mosaic project and the layout service Tailor, Zalando has been running such an architecture in production for a good two years. What is new, at most, is the insight that comes when you rebuild it: the technical part is the easy one. ## A runnable example landscape So as not to merely claim this, in July I put together the repository `introduction-micro-frontends` – a runnable example landscape with a gateway on port 7000 and, behind it, four standalone applications: Home (7010), Docs (7020), Products (7030) and Contact (7040), plus a catalog API, a GraphQL API on port 9000 and a shared component library on port 5000. Each application starts on its own, has its own build and could be run by its own team. The gateway knows the applications through a simple service discovery – from files, from Docker/Kubernetes or from Google Cloud, as you prefer – and routes by path. ```mermaid flowchart LR B[Browser] --> G[Gateway
    :7000] G -->|/| H[home-app
    :7010
    Team A] G -->|/docs| D[docs-app
    :7020
    Team B] G -->|/products| P[products-app
    :7030
    Team C] G -->|/contact| C[contact-app
    :7040
    Team D] P --> Q[graphql-api
    :9000] H -. shared UI .-> L[components-library
    :5000] P -. shared UI .-> L ``` The diagram already shows the central design decision: the dividing lines run vertically. Each team owns a domain slice from the route to the API – not a horizontal layer such as “all buttons” or “all of the CSS.” This split is exactly what makes independent deployments possible in the first place; everything else is craftsmanship. ## The easy part: integration The integration techniques are quickly listed, and none of them is spectacular. The oldest is the hyperlink. If `/products` and `/contact` are separate applications, an `` is enough – the browser loads the next page, the next team takes over. No shared code, no shared runtime, but a visible page change. For many transitions, that is entirely sufficient, and it is the only integration that is guaranteed never to break. If fragments from different teams should appear on one page, you compose on the server side. Every nginx supports server-side includes out of the box: ```nginx # gateway: compose one page from team fragments location / { ssi on; proxy_pass http://home-app:7010; } location /fragment/header { proxy_pass http://components-library:5000/header; } ``` ```html
    ``` Zalando’s Tailor takes the same principle further and streams fragments in parallel, with a timeout and fallback per fragment. Edge-side includes move composition into the Varnish or CDN layer. What all variants have in common: the page is built from independently deployable parts, and a slow fragment does not block the whole release, at most its own placeholder. On the client side, Custom Elements are the cleanest bracket – native in Chrome and Safari since v1, in Firefox and Edge currently still via polyfill: ```js // products-app: expose a fragment as a custom element class ProductTeaser extends HTMLElement { connectedCallback() { const sku = this.getAttribute('sku'); fetch(`/products/api/teaser/${sku}`) .then((res) => res.text()) .then((html) => { this.innerHTML = html; }); } disconnectedCallback() { // team C cleans up its own listeners here } } customElements.define('product-teaser', ProductTeaser); ``` The receiving team writes `` and does not need to know which framework the fragment is built with internally. The DOM interface – attributes in, events out – is the contract between the teams. Then there are iframes: disreputable, but the only technique with complete isolation of CSS, JavaScript and global state. For a third-party payment form or a legacy module nobody wants to touch anymore, still a legitimate choice. And finally, single-spa orchestrates several framework applications within one single-page application – that solves the routing problem elegantly, but pulls all teams back into a shared runtime with a shared failure domain. Which technique works is decided by a few questions: - How many page changes can the user flow tolerate – is a link enough? - Must the page deliver a usable first view without JavaScript (SSI, Tailor), or is the audience logged in anyway (client-side composition)? - How strictly must fragments be isolated – is naming discipline enough, or do you need the iframe boundary? - Who operates the composition point: a platform team running the gateway, or each team its own entry point? ## Due diligence: routing, dependencies, CSS You still have to settle three things cleanly, or the monolith will catch up with you through the back door. First, routing ownership. The URL is the public interface of the entire application, so it needs an owner. In the example repository, the gateway owns the top level – `/products` belongs to team C, completely, including all subpaths. As soon as two teams have to negotiate over a path, the split is drawn wrong. Deep links have to work like on any decent website: a reload on `/products/42` lands at the right team without a central client router having to know about it. The gateway itself deliberately stays dumb – it knows paths and targets, but no domain logic. Every additional rule at this point turns it into the next shared deployment that everyone has to coordinate on again. Second, shared dependencies. Four applications that each bundle their own React send the framework over the wire four times – with a library of a good 100 KB, that is measurable but rarely the end of the world. The alternative, a centrally mandated framework version for everyone, sounds more economical and costs more: every framework update becomes a four-team project again, and the shared release cadence is back. That is why in the repository, each application bundles for itself. I pay this price deliberately, because it is paid in kilobytes instead of meetings. Third, CSS isolation. CSS has a global namespace, and in a composed page that is the gateway for action at a distance: team B changes a class `.card`, and team C’s layout shifts. Prefix conventions per team help immediately and cost nothing. Shadow DOM encapsulates styles completely, but depends on the same browser support as Custom Elements. The most reliable protection remains discipline: no global selectors, no element selectors, no `!important` across team boundaries. ## The hard part: who owns the header? Up to this point, everything was technology, and technology can be tried out. The questions where such undertakings actually get stuck are not in any nginx configuration. The header is the best example. It appears on every page, belongs to nobody in domain terms and to everybody technically. In one project, we played through three answers. A dedicated “header team” creates a new horizontal layer and thus a new bottleneck – every domain change becomes a ticket for another team. The second answer: one domain team owns the header, and all others embed it as a fragment. That works as long as this team takes the wishes of the others seriously – the header becomes an internal product with internal customers. The third answer is in the example repository: the header lives in the component library, versioned, and each team updates at its own pace. The price is honesty about reality – for a few days, two header versions are live at the same time. If you cannot live with that, you have decided against independent deployments and should call it that. The design question has the same structure. A shared look and feel does not come from a central CSS file but from a styleguide that is maintained like a product: with versions, a changelog and contacts. Atomic Design provides a useful vocabulary for this – small, dumb building blocks are shared, composed views belong to the teams. The higher a component sits in this hierarchy, the more expensive it is to share. ## What shared state costs The hardest currency is shared state. The standard example: on the product page, team C adds an item to the cart, and the mini cart in the header – owned by another team – should show the new count. The obvious reflex is a global store that all fragments read and write. With that, you bring back exactly the coupling you just got rid of: a shared state schema whose changes affect all teams at once, plus the question of whose version of the store gets loaded. The cheaper answer: fragments do not share memory; they share events. The DOM brings the mechanism along, without any additional library: ```js // products-app: announce the change, share no memory window.dispatchEvent(new CustomEvent('cart:item-added', { detail: { sku: '42', quantity: 1 } })); // header fragment: react and re-fetch its own truth window.addEventListener('cart:item-added', () => { fetch('/cart/api/summary') .then((res) => res.json()) .then((summary) => updateBadge(summary.count)); }); ``` The header keeps its own state and fetches the truth from the cart API; the event is only the trigger. The contract between the teams shrinks to an event name and a small `detail` object – both can be documented and extended in a backward-compatible way. The login status, the second perennial candidate for shared state, is a similar case. No fragment needs another team’s session object: a cookie on the shared domain, checked by the gateway, is enough as a shared fact – each fragment decides for itself what to show a logged-out visitor. Where that is not enough, for example for the display name in the header, a small API again provides the answer instead of a global object being passed through all fragments. Still: every such event is an interface, and interfaces need maintenance. When the list of cross-team events reaches double digits, that is not a tooling problem but a sign that the domain split is wrong – the teams are then long since working on the same thing, just against each other. ## Bottom line The rule of thumb I take away from building the example landscape: you do not buy micro-frontends as a technology; you buy them as a form of organization – the technology can be learned in two weeks, the team split cannot. If you have only one frontend team, you do not need any of this; a well-structured monolith with clean module boundaries is then the more honest architecture. The rebuild becomes interesting when approval rounds, code freezes and release queues measurably cost time and several teams could actually deliver independently if you let them. Then it pays to settle the uncomfortable questions first – who owns the header, who maintains the styleguide, which events form the contract – and only then choose between SSI, Custom Elements and iframes. In the end, the integration technique is interchangeable. The team split it extends into the browser is not. ## Further reading - Repository with the runnable examples: https://github.com/MikeBild/introduction-micro-frontends - ThoughtWorks Technology Radar on Micro Frontends: https://www.thoughtworks.com/radar/techniques/micro-frontends - Zalando Tailor, layout service from Project Mosaic: https://github.com/zalando/tailor - single-spa, router for several framework applications: https://github.com/single-spa/single-spa - MDN on Custom Elements: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements --- # Frontend Interfaces Are APIs URL: https://www.mikebild.dev/en/blog/frontend-interfaces-are-apis/ Date: 2018-08-12 # Frontend Interfaces Are APIs ```diff UserCard.propTypes = { - name: PropTypes.string.isRequired, + fullName: PropTypes.string.isRequired, avatarUrl: PropTypes.string, onSelect: PropTypes.func }; ``` A diff like this sails through review. A rename, the new name is more descriptive, your own application runs, the tests are green, merged. Three weeks later, another team pulls the new version of the shared component library, and their browser console says: ``` Warning: Failed prop type: The prop `fullName` is marked as required in `UserCard`, but its value is `undefined`. ``` That is still the good case, because `propTypes` at least makes noise. The worse case: the card simply renders without a name, nobody looks at the console, and the bug only gets noticed when a user reports it – two releases later, with a diff in which nothing suspicious remains. If someone had done the same with a field in a REST response – renamed `name` to `fullName` without comment, without announcement and without a version bump – there would be plenty of trouble, and rightly so. With a component prop, exactly this happens all the time, and hardly anyone calls it what it is. Yet the situation is identical: there is a contract between two codebases that are changed and shipped by different teams at different times. That is the definition of an API. The fact that the contract consists of JSX instead of HTTP doesn’t change that. ## More surfaces than the architecture diagram shows In a portal project I worked on for quite a while, application parts from four teams ran in the same browser tab: a shell, two business applications, an embedded widget. When, after a particularly stubborn integration bug, we once wrote down what these parts actually talk to each other about, we ended up with a list that was considerably longer than anything that had ever appeared in an architecture diagram: - props and callbacks of the shared component library - URLs with paths and query parameters that are linked to - CustomEvents and `postMessage` messages between parts of the page - CSS classes and CSS custom properties that other parts use deliberately - localStorage keys that more than one module reads Each of these surfaces had consumers outside the team that maintained it. None of them was versioned. Only the first was documented at all. The REST APIs of the same project, by contrast, had version prefixes, changelogs and a deprecation policy – because everyone understood there that other people’s code depended on them. In the frontend, the same dependency existed, just invisibly. ```mermaid flowchart LR subgraph FE[One team’s frontend] P[Props & callbacks] U[URLs & parameters] E[CustomEvents /
    postMessage] C[CSS classes &
    custom properties] S[localStorage
    keys] end A[Team B:
    business application] --> P B[Users: bookmarks,
    shared links] --> U M[Emails, campaigns,
    monitoring checks] --> U W[Widget in an iframe] --> E T[Team C:
    theming] --> C X[Old portal script] --> S ``` The diagram is no exaggeration but the tidied-up version of our list back then. And it explains why “we’re only refactoring internally” goes wrong so often in the frontend: what looks internal has long had consumers. ## Props: the contract between teams For the component library, we drew the obvious conclusion: it is treated like an API. In concrete terms, that means three things. First, the prop signature is the contract, and `propTypes` make it machine-readable. Second, Semantic Versioning applies for real – a removed or renamed prop is a breaking change and therefore a major version, no matter how small the diff looks. Third, every change gets a deprecation window: the old form keeps working but warns in development mode. For the `UserCard` example above, it looks like this: ```jsx import React from 'react'; import PropTypes from 'prop-types'; // v2.3.0: `name` is deprecated in favor of `fullName`. // Both work until v3.0.0, where `name` will be removed. export function UserCard({ fullName, name, avatarUrl, onSelect }) { const displayName = fullName || name; if (name && process.env.NODE_ENV !== 'production') { console.warn( 'UserCard: prop `name` is deprecated, use `fullName` instead. ' + 'Support for `name` will be removed in v3.0.0.' ); } return (
    {avatarUrl && } {displayName}
    ); } UserCard.propTypes = { fullName: PropTypes.string, name: PropTypes.string, // deprecated, see above avatarUrl: PropTypes.string, onSelect: PropTypes.func }; ``` That is more code than the pure rename, and exactly this extra effort is the point. It forces the question of whether the rename is worth the price. For an internal helper function, the answer is almost always yes, because the compiler or a search finds all callers. For a published prop, you can’t find the callers – they sit in repositories you have no access to. For documentation, Storybook has proven itself for us – as a living contract description, not just as a pretty component catalog: for each component there are stories that show the supported prop combinations, including a story for the deprecated form as long as it exists. If you want to know what `UserCard` can do, you don’t look at the component team’s source code but at the built Storybook instance of the version you use. The team that maintains the library also notices earlier itself when a change touches the contract – a broken story is a clear signal. ## URLs: the contract with everyone else The second surface is underestimated even more often: the URL. Routes feel like an internal implementation detail of the router, but they are the exact opposite – the most public interface a frontend has. Bookmarks point to a route, as do links shared by email, campaigns, monitoring checks, the neighboring team’s documentation and occasionally a PDF that was printed two years ago. None of these consumers gets an update when someone renames `/clients` to `/customers` in the code. Renaming a route is therefore a breaking change with especially long-lived consumers, and here the deprecation phase is called a redirect. With React Router v4, it’s one line plus discipline: ```jsx import { Switch, Route, Redirect } from 'react-router-dom'; {/* Deprecated 2018-08: keep this redirect for at least 12 months. */} ``` The discipline lies in the comment: the redirect stays until the old links are realistically gone from the world, not until the next cleanup commit. In the portal project, at some point we counted hits on old routes before a redirect was removed – the same practice you use to switch off an old REST endpoint. The numbers were regularly sobering: links we thought were dead were still being called months later. The same goes for query parameters. If you support `?tab=invoices`, you have entered into a contract as soon as the first user shares the link. And the URL is also persisted state: what’s in it survives reloads and travels between browsers – one more reason to design it deliberately instead of leaving it to router chance. Designing deliberately mainly means: domain identifiers instead of internal IDs, no implementation details in the path, and a scheme that a colleague can guess without looking at the code. In my experience, a URL you can read out over the phone also survives the next redesign. ## Events and messages: contracts at runtime As soon as several application parts run in the same browser, at some point they talk to each other directly – for us via CustomEvents on `window` and via `postMessage` to the embedded widget. These messages are the most fleeting form of interface: no type check, no shared repository, often not even a shared deployment. That is exactly why they need the most explicit contract. We treated every message like a small wire format – a named type, a documented payload schema, a version field: ```js // Contract: 'cart:item-added' (version 1) // detail: { version: number, sku: string, quantity: number, source: string } window.dispatchEvent(new CustomEvent('cart:item-added', { detail: { version: 1, sku: 'A-4711', quantity: 1, source: 'product-page' } })); // Consumer side: tolerate unknown versions instead of guessing. window.addEventListener('cart:item-added', (event) => { if (event.detail.version !== 1) return; updateCartBadge(event.detail.quantity); }); ``` The version field seems overly cautious until the first time two parts of the page with different release levels run in the same tab. Then it is the difference between an ignored event and an `undefined` that explodes three functions further on. With `postMessage`, the origin check comes on top, but the principle stays the same: the receiver validates, the sender promises backward compatibility within a version. Custom Elements v1, by the way, makes this way of thinking official – an element with attributes and events is nothing but an API registered in the browser. ## CSS and localStorage: the contracts nobody wanted to make The last two surfaces are the most unpleasant, because they are contracts nobody ever entered into deliberately. If you write BEM classes like `user-card__avatar` into the DOM, you publish them. Somewhere, another team styles against this class, a test selects it, an analytics snippet hooks into it. By the same logic, CSS custom properties that a theme offers to the outside – `--brand-primary`, `--spacing-unit` – are a real, intended API and should be maintained as such: named, documented, stable. The unintended variant can be contained by clearly separating which classes are part of the contract and which are generated or marked as private. But the basic rule remains: whatever is observable and stays stable long enough will be used – regardless of what the documentation says about it. localStorage is the same case, only worse: global per origin, without namespaces, without a schema. A key like `user-settings` that two modules read is an unintended database API including a migration problem – if one module changes the format, the other parses garbage. On top of that comes a property that sets storage apart from all other surfaces: the old values are already out there. A deployment swaps the code but not the data in thousands of browsers – every format change hits values there that an older version wrote. Since the portal project, I therefore give such keys a prefix with the module name and a version number in the value, and the reading code treats an unknown format like a missing value. Not because that’s elegant, but because the alternative is a production bug you can only diagnose with “clear storage in the DevTools panel”. ## Versioning is communication, not bureaucracy The objection is obvious: that’s a lot of process for a frontend. But the effort is tiered, and most of it is simply communication. For the component library in our Lerna monorepo, the window for a breaking change looked like this: - announce the change in the changelog, with the old and the new contract - a minor version in which both work and the old form warns in development mode - mark the Storybook story for the old form as deprecated - removal only in the next major version, with a migration note That costs maybe an hour per change. The prop rename without this window cost us several days back then, counting everyone involved – debugging in someone else’s codebase, a hotfix, a special release, and the trust between two teams along with it. I have written about the sloppy treatment of code that sits between areas of responsibility before, among other places in [Build Scripts as Product Code](https://www.mikebild.dev/en/blog/build-scripts-as-product-code/); frontend interfaces get overlooked in the same way, only more teams depend on them here. What struck me is that teams don’t fail at the discipline but at the perception. Nobody refuses to version an API cleanly – you just don’t see that you have one. The most effective step was therefore not the tooling but the list from the beginning: write down once which surfaces your own frontend actually offers and who depends on them. Everything on this list that has a consumer outside your own team deserves the three familiar ingredients – an explicit contract, a semantic version, a deprecation window. ## Bottom line A frontend is not a leaf at the end of the dependency tree but itself a provider of interfaces: props, URLs, events, CSS surfaces, stored keys. As long as a single team owns all of it and ships it in one step, you can ignore that. At the latest when several teams work in the same browser – and the design system and micro-frontend movement is currently making sure that this becomes the norm – the rules apply that have been taken for granted in the backend for years. A breaking change means a major version. Renaming means deprecating. And a harmless-looking diff is exactly as harmless as the number of consumers nobody asked. ## Further reading - Semantic Versioning 2.0.0 (German version): https://semver.org/lang/de/ - React documentation: typechecking with PropTypes: https://legacy.reactjs.org/docs/typechecking-with-proptypes.html - MDN: CustomEvent: https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent - MDN: Window.postMessage: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage - Storybook: https://storybook.js.org/ --- # Node.js and Redis with Docker Compose URL: https://www.mikebild.dev/en/blog/nodejs-and-redis-with-docker-compose/ Date: 2018-07-24 A second container doesn’t double the work, it changes it. A single `docker run` is about one image, one port, maybe two environment variables. As soon as a Node process depends on Redis, new questions come up that you can only answer with tedious command-line acrobatics: Which network are both containers in? At which address does one find the other? Who starts first – and where does the data go when a container gets replaced? Docker Compose answers these questions in a single place. Afterwards, the knowledge of how the stack starts lives in a versioned file instead of in people’s heads and a setup doc: `git clone`, `docker-compose up`, running. A new team member no longer loses half a day to Node versions, a local Redis installation and occupied ports. You pay for it with a file that needs maintenance – a deal that pays off quickly. I walk the technical path completely: from the `docker-compose.yml` through service discovery and persistence to the pitfall that easily costs half an hour the first time. The state is summer 2018, so Compose file v3 and the hyphenated CLI `docker-compose`. **Editorial note (July 2026):** Current Docker Compose can wait for a successful health check with the long form of `depends_on` and `condition: service_healthy`. The application should still cope with dropped connections and restarts on its own; a health check doesn’t replace a retry strategy. The main text keeps the limitation of the Compose v3 format of the time. ## Why Compose at all A single container is quickly explained. But as soon as two containers have to work together, the imperative variant gets tedious: create a network, start both containers in it, publish ports, set environment variables, mind the start order. That is a lot of commands nobody reproduces from memory without mistakes – least of all the colleague who clones the project tomorrow for the first time. Compose turns this around. Instead of a sequence of commands, I write a declarative description of the target state. The file says which services exist, which images they use, which ports are open and how they relate. The start command is always the same afterwards. If you have worked with Docker before, you know the principle from the Dockerfile – Compose just lifts it one level higher, from one image to a whole application. The whole thing follows a simple idea: reproducible, encapsulated environments that start the same way on every machine. ## The docker-compose.yml Here is the file I start with. Two services, kept minimal so that every line has a recognizable job. ```yaml version: '3' services: web: build: . environment: NODE_ENV: production REDIS_HOST: 'redis' REDIS_PORT: '6379' ports: - '8080:8080' depends_on: - 'redis' redis: image: redis:4.0.11 ``` The first line is mandatory in 2018: `version: '3'`. Without this key, Compose refuses to read the file. Below it come the top-level keys that interest us here – `services:` for sure, `volumes:` and `networks:` in a moment. Two lines are worth a closer look. The `web` service has `build: .` – Compose builds the image locally from the Dockerfile in the current directory. The `redis` service has `image: redis:4.0.11` – here a ready-made image is pulled from the registry. That is the central contrast: - I use `build:` for my own code, which doesn’t exist as a finished image yet. Compose runs a `docker build` in the background. - I use `image:` for everything I take over unchanged – databases, caches, message brokers. I pin Redis to a concrete version (`4.0.11`) instead of `latest` so the environment stays reproducible. In case my web service has already been built and pushed to a registry, I simply swap `build: .` for `image: mikebild/compose-nodejs-redis:1.0.0`. The same file, a different source – exactly what you want in a deploy context. What’s missing from the `redis` service is also striking: no `ports`. That is intentional. Only `web` publishes a port to the host with `'8080:8080'`, because only the web service should be reachable from outside. Redis stays internal to the containers and therefore doesn’t need to be published on the host. I’ll come back to this isolation point below, because it has a very real security side. ## Service discovery: Redis is simply called “redis” That leaves the question of how the Node process knows at which address to find Redis. There is no IP written anywhere, after all. On startup, Compose automatically creates a default network named after the project, something like `_default`. Every service is attached to this network and reachable in it under its service name via built-in DNS. In other words: every service reaches every other service under that service’s name. The name `redis` from the YAML becomes the hostname in the network. That is why I set `REDIS_HOST: 'redis'` in the file. The Node client connects to `redis:6379` – no hardcoded IP, no `--link` acrobatics. If Compose gives the container a different internal address tomorrow, it doesn’t matter, because resolution happens via the name. ```mermaid graph LR Client["Client / Browser"] -->|"Host port 8080"| Web subgraph net["Compose default network"] Web["web container"] -->|"DNS: redis:6379"| Redis["redis container"] end Redis --> Vol[("volume
    redis-data (/data)")] ``` From outside, exactly one way leads in, via the published host port 8080 to `web`. Internally, `web` talks to `redis` via the service name. And the Redis data lives in a volume, which we’ll get to in a moment. If you want to make the default network visible, you can also write it out explicitly. I like to do that once in a new project to make it clear there is no magic involved: ```yaml version: '3' services: web: build: . environment: REDIS_HOST: 'redis' REDIS_PORT: '6379' ports: - '8080:8080' networks: - app-net depends_on: - 'redis' redis: image: redis:4.0.11 networks: - app-net networks: app-net: ``` Functionally, this changes nothing compared to the first file – Compose would have built a network anyway. But the mechanism is now visible in the file, and the network is no longer an implicit side effect. ## The Node client So the connection doesn’t stay abstract, here is the relevant excerpt of the server. It is a lean Express server that uses `node_redis` in version `^2.8`, common in 2018 – so the callback API, not yet the later promises. ```js const SERVICE_PORT = process.env.SERVICE_PORT || 8080; const REDIS_HOST = process.env.REDIS_HOST || 'localhost'; const REDIS_PORT = process.env.REDIS_PORT || '6379'; const express = require('express'); const redis = require('redis'); const app = express(); const client = redis.createClient(REDIS_PORT, REDIS_HOST); client.on('error', err => { console.error(`Redis connection error.\n${err.message}`); process.exit(1); }); app.get('/redis', (req, res, next) => { client.get('foo', (error, result) => { if (error) return next(error); res.send(result); }); }); app.post('/redis', (req, res, next) => { client.set('foo', 'bar', (error, result) => { if (error) return next(error); res.status(201).send('done'); }); }); app.listen(SERVICE_PORT, () => console.log(`Listen on ${SERVICE_PORT}`)); ``` The crucial line is `redis.createClient(REDIS_PORT, REDIS_HOST)`. Host and port come from the environment, and Compose fills the environment through the `environment` block. That keeps the code free of addresses. On my laptop it runs against `localhost`, in the Compose network against `redis` – without a single line of application code changing. There is one detail I keep in mind: the `client.on('error', …)` handler terminates the process with `process.exit(1)` as soon as the Redis connection fails. That is deliberately harsh and leads straight to the most important pitfall. ## The pitfall: depends_on doesn’t wait for “ready” `depends_on: ['redis']` reads as if Compose waits until Redis is ready before starting `web`. It doesn’t. `depends_on` only controls the start order: Compose starts the Redis container before the web container. But it doesn’t wait until Redis accepts connections – only until the container has been started. The difference sounds academic until the harsh error handler above strikes. Redis needs a moment until the server inside the container is actually listening. If `web` starts in this window and tries to connect immediately, `client.on('error')` fires, the process exits with exit code 1 – and the freshly started stack is already half dead again. On slower machines, this happens reproducibly. The clean solution isn’t in the YAML but in the application. It has to tolerate dropped connections and attempt a reconnect with retry instead of bailing out on the first error. Where I don’t want to touch the application code, in 2018 I put a small wait script in front of the start – `wait-for-it.sh`, `dockerize` or `wait-for` checks whether `redis:6379` is reachable before the Node process starts. One thing needs an explicit no here: the long form `depends_on: {redis: {condition: service_healthy}}`, which waits for a health check, doesn’t exist in Compose v3 in 2018. If you write it into a v3 file, it simply isn’t recognized. So the wait logic belongs in the application or a wait script, period. ## Persistence: Redis needs a volume The second pitfall is quieter, but more annoying. In the starting file, Redis has no volume. As long as the container runs, all is well – the data lives in the container file system under `/data`. But as soon as the container gets replaced, for example after `docker-compose down` and another `up`, the cache is empty. The container is ephemeral, and so is its file system. If you use Redis as more than a throwaway cache, mount a named volume on `/data`. The redis image stores its RDB snapshots exactly there. ```yaml version: '3' services: web: build: . environment: REDIS_HOST: 'redis' REDIS_PORT: '6379' ports: - '8080:8080' depends_on: - 'redis' redis: image: redis:4.0.11 volumes: - 'redis-data:/data' volumes: redis-data: ``` The named volume `redis-data` survives the container’s lifecycle. I can rebuild `web`, shut the stack down and bring it back up – the Redis data is still there. Only an explicit `docker-compose down -v` also cleans up the volumes. With that, I have the four building blocks that make up a Compose file: - `services` are the application’s containers, here `web` and `redis`. - `ports` defines which container ports are published to the host; only `web` gets one. - `volumes` keeps data in named volumes that should survive the container, here `redis-data`. - `networks` describes the mostly automatic network that enables service discovery by service name. ## The cycle: up, logs, down In operation, it’s only a handful of commands, and they stay the same across projects. I start the stack in the background, look at the logs and shut everything down again at the end. ```bash docker-compose up -d docker-compose logs web curl -X POST http://localhost:8080/redis curl http://localhost:8080/redis docker-compose down ``` `up -d` starts both containers detached. `logs web` shows the web service’s output specifically, which helps when debugging the startup window above. The two `curl` calls first write the value to Redis and then read it back – proof that `web` actually reaches its neighbor under the name `redis`. `down` stops and removes the containers and the default network; the named volumes stay unless I add `-v`. By the way, if you use Docker Toolbox instead of Docker for Mac or Windows, you don’t reach the stack at `localhost` but at the IP of the docker-machine, `192.168.99.100` in the default configuration. In 2018 that is still reality on many machines and costs a few puzzled minutes the first time. ## The real gain: time to the first commit The YAML is only the means. The result is an environment that everyone on the team gets with the same two commands. Whoever joins the project today clones the repository, types `docker-compose up` and shortly after has a running stack of Node and Redis in front of them – without hunting for the right Node version by hand, without installing Redis locally, without the silent assumption that port 6379 is free. The environment lives in the file, not on a wiki page nobody maintains. This is where Compose pays off in business terms. Onboarding is expensive, and the most expensive part is rarely understanding the code – it is setting up an environment in which the code runs at all. Compose moves exactly this part from every single developer into a versioned file. The time to the first commit, which can otherwise be anywhere between half a day and a full day, shrinks to the duration of an image pull. It isn’t free. I take on an additional abstraction the team has to understand, and a file that needs maintenance. Version pinning is discipline: a `redis:latest` undermines exactly the reproducibility I use Compose for in the first place. And Compose covers development and local integration, not production operations with their questions of fault tolerance, scaling and secrets. So the decision falls at a clear boundary. As soon as more than one process works together and more than one person touches the project, Compose quickly earns back its effort – every setup hour avoided per new team member already makes the file worth it. For a single tool without neighbors, `docker run` remains the more honest answer. What tips the scale is less the technology than the friction it saves. ## A word on security The missing `ports` entry for Redis is intentional and the actual core of the isolation. `ports` publishes on all host interfaces. If I exposed Redis with `'6379:6379'`, an open Redis instance, unsecured by default, would sit on the network – and Redis has repeatedly made negative headlines for exactly that. Inside the Compose network, `web` reaches its cache via the service name anyway. Nobody should reach it from outside. So I leave Redis unpublished. The principle stays simple: only services that must be reachable from the host get a published port. As an aside: the `links` entry you come across in older examples is legacy. In v3, the default network with its DNS makes it unnecessary. If you still have it in place, you can remove it. ## Conclusion Compose turns a handful of `docker run` commands into a single, readable file that describes the whole stack. `image` versus `build` separates adopted services from self-built ones. Service discovery via the service name gets hardcoded IPs out of the way completely – `REDIS_HOST: 'redis'` is enough, and the Node client connects to `redis:6379`. A named volume on `/data` saves the Redis data across the container lifecycle. And `ports` publishes only what really needs to be reachable from outside. The one point that matters most to me: `depends_on` orders the start but doesn’t guarantee readiness. If you don’t know that, you chase a race condition bug that no YAML line fixes – the wait logic belongs in the application or a small wait script. If you know it, you build the stack to be resilient from the start. But more important than any single YAML line is what it saves the team. A reproducible environment shortens the loop from cloning to the first commit, takes the friction out of onboarding and turns “works on my machine” into a verifiable statement instead of a hope. As a side effect, that raises quality, because everyone develops and tests against the same state. The boundary stays clear: Compose is a tool for development and local integration, not a production orchestrator. Within that boundary, `docker-compose up` feels like a single, reliable move every time – and that is exactly the gain. ## Further reading - [Docker Compose: startup order and `service_healthy`](https://docs.docker.com/compose/how-tos/startup-order/) - Slide deck on this topic: https://slides.mikebild.dev/introduction-docker-kubernetes.en.html - [Compose file v3 reference](https://docs.docker.com/compose/compose-file/) - [Networking in Compose (DNS, default network)](https://docs.docker.com/compose/networking/) - [Control startup order in Compose](https://docs.docker.com/compose/startup-order/) - [Compose CLI overview](https://docs.docker.com/compose/reference/overview/) - [redis Official Image, tag 4.0.11](https://hub.docker.com/_/redis) --- # Containerization and False Security URL: https://www.mikebild.dev/en/blog/containerization-and-false-security/ Date: 2018-07-12 # Containerization and False Security “It runs in a container” has turned into a kind of seal of quality in project conversations. The sentence is supposed to prove three things at once: the application is isolated, the build is reproducible, and operations are under control. None of these three statements follows from the packaging. A container is first of all just an ordinary process with a restricted view of the system – whether it brings security and repeatability along is decided in the Dockerfile and the startup configuration, not in the word “container”. I have been noticing this confusion in reviews for a few months now. One team shows a clean deployment on Kubernetes 1.10, everything green, and when asked about the patch level of the base image, they shrug. Another team has been building on `node:latest` for a year and wonders why the CI build behaves differently from the local one. These three false senses of security are worth a closer look, because they need three different remedies. ## First false sense of security: isolation A container is not a small virtual machine. A VM brings its own kernel and talks to the host through a hypervisor. A container shares the kernel with the host and with all other containers on the same machine. What separates it are kernel namespaces for processes, network and file system, plus cgroups for resources – useful mechanisms, but a much thinner wall than a hypervisor. ```mermaid flowchart TB subgraph VM["Virtual machine"] A1[App] --> K1[Guest kernel] K1 --> H1[Hypervisor] H1 --> HW1[Host kernel
    + hardware] end subgraph CT["Container"] A2[App as a process] --> NS[Namespaces
    + cgroups] NS --> HW2[shared
    host kernel] end ``` The practical consequence: if you run as root in the container, you run as root on the host. UID 0 is UID 0. User namespaces, which map container root to an unprivileged host user, have existed in Docker for a while – but they are opt-in via `--userns-remap`, and in the environments I have seen this year, the feature was switched on exactly zero times. As long as that’s the case, the only thing separating a root process in the container from the host is the question of whether it finds a way out. A `--privileged` container is guaranteed to find that way. The flag unlocks all capabilities and grants device access – which lets you mount the host file system from inside the container. I have found the flag in production setups, set months earlier “because otherwise it didn’t run”, and never questioned again. A privileged container is not an isolation layer with a weakness; it is an open door with a curtain in front of it. For a while now, Docker has shipped a default seccomp profile that filters risky syscalls, plus AppArmor profiles on Ubuntu hosts. That helps, but it doesn’t change the principle: the boundary is the kernel, and the kernel is shared. In January, Meltdown and Spectre additionally showed that even process boundaries can wobble at the CPU level. If you need real tenant separation, that is, if you run third-party or untrusted code, you still use VMs – or take a look at gVisor, which Google introduced in May: a userspace kernel between container and host. An exciting approach, but in July 2018 too fresh to base a production decision on. What you can already do today is shrink the attack surface at startup: ```bash docker run -d \ --read-only \ --cap-drop ALL \ --cap-add NET_BIND_SERVICE \ --security-opt no-new-privileges \ --memory 256m \ order-service:1.4.2 ``` All of this has been available for years; none of it is the default. That is exactly the point: with containers, isolation is not a state but a configuration that someone has to actively set up. ## Second false sense of security: reproducibility The second assumption goes: because the application is shipped as an image, the build is reproducible. That is only true for the finished image – the same image ID starts the same state everywhere. It isn’t true for the path there. A Dockerfile like this one is not a description but a snapshot: ```dockerfile FROM node:latest WORKDIR /app COPY . . RUN apt-get update && apt-get install -y imagemagick RUN npm install ENV API_SECRET=changeme-in-prod EXPOSE 3000 CMD ["node", "server.js"] ``` Almost every line here is a time bomb. `node:latest` is not a version but a bet on when the build happens – last year you got Node 8, for a few weeks now Node 10, and nobody made a decision. `apt-get install` without a version pulls whatever the mirror server offers today. `npm install` without a lockfile rolls the dice on dependency versions at build time; since npm 5 that’s solvable with `package-lock.json`, but only if the file is checked in and respected. And the secret in the `ENV` line now sits in the image history forever – `docker history` shows it to anyone allowed to pull the image. On top of that come build args as a silent variable: an `ARG` that is set differently on the CI server than on the developer machine produces two different images from identical source – and because the argument isn’t anywhere in the repository, you only see the difference once you put both images side by side. So two builds of the same Dockerfile six weeks apart can differ in low-level OS layers, system packages and npm dependencies without a single line in the repository having changed. In a project this spring, we lost an afternoon over exactly this: the hotfix build for a six-week-old state behaved differently from the running system, because the base image under the same tag had meanwhile become a different one. The honest formula is: an image is a result. It only becomes reproducible once all inputs are nailed down – base image by tag or, better, by digest (`node:8.11-alpine@sha256:...`), system packages with versions, application dependencies via the lockfile. ## Third false sense of security: operations The third assumption is the quietest: the container runs, so operations are taken care of. Yet an image doesn’t only freeze the application but also every library underneath – including its vulnerabilities. On a classically administered server, `unattended-upgrades` installs security updates at night. In a container, this path doesn’t exist. The only patch route is: new base image, new build, new deployment. If you haven’t set up this chain as a routine, you are running a fleet that goes quietly more out of date every day while the dashboard stays green. Before that comes a question that surprisingly often goes unanswered: which images are actually running, and from which state were they built? On a cluster with a few dozen deployments, that is pure archaeology without an inventory. When the first Meltdown patches arrived in January, I saw in one project how long the inventory alone takes when tags like `latest` and `stable` are in circulation – you then literally don’t know what you are running, only that it runs. ```mermaid flowchart LR CVE[CVE in the base image
    published] --> BASE[Base image
    updated] BASE --> BUILD[Rebuild
    of all services] BUILD --> SCAN[Image scan
    e.g. Clair] SCAN --> DEPLOY[Rollout] DEPLOY -. without routine
    the chain breaks here .- BUILD ``` That operations are the real weak flank was shown this year by a prominent case: in February it became known that Tesla’s Kubernetes administration console was reachable from the internet without password protection. The attackers didn’t need a kernel vulnerability and didn’t break out of any container – they settled in via the open console, deployed crypto-mining pods, throttled the CPU load and hid the mining pool behind Cloudflare to avoid attention. Same category: Docker daemons whose remote API listens unauthenticated on port 2375 and that get grazed by mining scripts one after another. In both cases, the container technology was completely innocent. What was vulnerable was the operating model around it – exposed admin interfaces, missing access control, nobody looking. For me, this is the most important lesson from the case: the platform shifts the operational questions; it doesn’t answer them. If you used to have to know which packages are on the server, you now have to know which layers are in the images. If you used to secure SSH, you now have to secure the kubelet, API server and dashboard. The effort hasn’t disappeared; it has changed its address. ## What concretely helps None of this is an argument against containers – it is an argument against the seal of quality. The remedies are unspectacular and have been available for quite some time. In the Dockerfile itself, it looks like this: ```dockerfile # build stage FROM node:8.11-alpine AS build WORKDIR /app COPY package.json package-lock.json ./ RUN npm install COPY . . RUN npm run build && npm prune --production # runtime stage FROM node:8.11-alpine WORKDIR /app RUN addgroup -S app && adduser -S app -G app COPY --from=build /app/dist ./dist COPY --from=build /app/node_modules ./node_modules USER app EXPOSE 3000 CMD ["node", "dist/server.js"] ``` Multi-stage builds have existed since Docker 17.05, so they have been established for more than a year and are no longer an experiment. The effect: compilers, dev dependencies and build tools stay behind in the first stage, and only what is needed at runtime gets shipped. The `USER` directive makes sure the process doesn’t start as root in the first place – one line that defuses a large part of the isolation problem from the first section, because a breakout then lands with an unprivileged user. The pinned base image takes the dice out of the reproducibility question. A pleasant side effect of the small runtime stage: the image scanner has less to report, simply because fewer packages are on board – an Alpine image with a handful of libraries produces findings you actually read, instead of a list with three hundred entries that nobody opens anymore after the second week. Beyond that, a few points have settled in as a checklist for my reviews: - Choose small base images – `alpine` for everyday use, and for compiled languages the distroless images that Google released last year, which contain nothing except the application and its runtime dependencies, not even a shell. - Pin tags, and for production deployments also record the digest – `latest` has no place in a deployment manifest. - Hook image scanning into the CI chain: Clair or Anchore match the layers against known CVEs and turn “we should patch at some point” into a red build. - Never put secrets into the image – not as `ENV`, not as `ARG`, not as a copied file. They end up in the history or in the build context. Secrets come from outside at runtime, for example as a Kubernetes Secret or via the orchestrator. - Trim capabilities at startup and treat `--privileged` like open root access: anyone who wants to set it has to justify why. None of these points is hard. The real obstacle is that they are invisible as long as everything runs – and that’s exactly why they belong in the review and not in the “we’ll do it when there’s time” category. ## Bottom line Containers have made our delivery noticeably better: the same artifacts in all environments, fast startups, a clean interface between build and operations. What they don’t deliver is what the phrase “runs in a container” so readily claims. Isolation is a configuration, not a property – without `USER`, without trimmed capabilities and with a shared kernel, the wall is thinner than the word suggests. Reproducibility is a discipline, not a property – unpinned tags and packages turn the Dockerfile into a photo instead of building instructions. And operations are a routine, not a property – an image that nobody rebuilds is a server that nobody patches, only without the nightly updates. When someone tells me today that an application is secure because it is containerized, I ask three things: as which user does the process run? How does the next build know that it builds the same thing as the last one? And who rebuilds when a vulnerability in the base is published tomorrow? The answers show pretty reliably whether the team has an operating model – or just a seal of quality. ## Further reading - Repository introduction-docker: https://github.com/MikeBild/introduction-docker - Docker documentation on multi-stage builds: https://docs.docker.com/build/building/multi-stage/ - Docker Engine Security Overview: https://docs.docker.com/engine/security/ - Clair, static analysis of container images: https://github.com/quay/clair - Distroless images from Google: https://github.com/GoogleContainerTools/distroless - Report on the Tesla incident (CNBC, February 2018): https://www.cnbc.com/2018/02/21/hackers-hijack-teslas-cloud-system-to-mine-cryptocurrency-redlock.html --- # My Working Definition of an MVP: Learning Instead of Shipping Half-Finished URL: https://www.mikebild.dev/en/blog/my-working-definition-of-an-mvp/ Date: 2018-05-24 If you leave out half and call the result an MVP, you haven’t reduced any risk; you have only postponed the day the mistake becomes obvious. The build time is spent, something half-done has shipped, and the most expensive question is still in the room, unchanged: How do we know we are building the right thing at all? Still, the word is attached in exactly this sense to roadmaps, ticket titles and budget lines. Fewer buttons, fewer screens, less backend – MVP has become a polite expression for “the product, but worse”. The reduced feature set doesn’t answer a single open question. It confuses speed in building with speed in learning. For my work, I stick to the reading from Lean Startup: an MVP is an experiment, the smallest version of a product with which a concrete, risky assumption can be tested honestly. The term is used differently in practice, too; this working definition is my deliberate choice. From it follows what belongs in, what doesn’t, and why the apparent detour via learning can be the fastest way to a viable product. ## The definition that carries everything In 2011, Eric Ries put the term like this in “The Lean Startup”: an MVP is “that version of a new product which allows a team to collect the maximum amount of validated learning about customers with the least effort.” The core is in two words: *validated learning*. The purpose is learning confirmed by real data, namely about the *leap-of-faith assumptions* – the assumptions the whole idea rests on and that nobody has backed up so far. That makes the MVP not a delivery step but the build part of an experiment. Ries places it in the *Build-Measure-Learn* loop: we build something, measure the reaction, learn from it and decide. The outcome of an MVP is always a decision, which Ries calls *pivot or persevere* – stay the course, or discard the assumption and turn. ```mermaid flowchart LR A[Risky assumption] --> B[Build:
    MVP as an experiment] B --> C[Measure:
    real users, real metric] C --> D[Learn:
    validated learning] D --> E{pivot or
    persevere?} E -->|persevere| A E -->|pivot| A ``` For this working definition, this yields a hard criterion that is missing in everyday practice: an MVP without a defined learning question and without a metric is then not an experiment but just a small product. The difference isn’t academic. If nobody wrote down beforehand which assumption is being tested and how you recognize the outcome, the result can’t refute anything either. You build, launch, find it “pretty okay” and carry on – you have learned nothing. Steve Blank states the other side of the misunderstanding directly: “A minimum viable product is not always a smaller/cheaper version of your final product.” His customer development approach revolves around a single imperative: *get out of the building*. The truth about the product isn’t in the meeting room; it is with the users. The MVP is the tool you use to go out. ## A vertical slice instead of a horizontal amputation The difference can be shown with two cuts through the same planned scope. The wrong MVP is a horizontal cut. You take all planned features and build each one to forty percent. The registration form is half done, the search returns results without filters, the checkout ends in a dead end. Nothing works end to end. At no point does the user get from the start to the value. There is nothing to measure, because there is no complete path anyone could go through. The MVP is often a vertical slice: a thin but continuous path from the user to the value, with a measurement at its end. With concierge, Wizard-of-Oz or landing page experiments, though, the smallest reliable test can look different. What matters is not the shape of the cut but whether it honestly tests the risky assumption. ```mermaid flowchart TB subgraph L[Horizontal: half-finished] L1[Feature A – 40%] L2[Feature B – 40%] L3[Feature C – 40%] end subgraph R[Vertical: smallest learning product] R1[Entry] --> R2[one continuous path] --> R3[Value] --> R4[Metric] end ``` This is exactly where the meaning of “viable” lies. The word doesn’t refer to quality; it refers to scope. Minimal is the scope, not the care. A buggy, cobbled-together MVP distorts the learning signal, because in the end you don’t know whether users reject the idea or just the broken implementation. “Viable” means: good enough to produce an honest signal. The narrow path has to be clean, otherwise you are measuring noise. ## The MVP doesn’t have to be code The strongest evidence that “viable” doesn’t mean “fully built” are two MVP types that existed long before 2018 and get by entirely without a finished product. In a *concierge MVP*, a human first provides by hand the service that software is supposed to provide later. You don’t pretend there is a product – you deliver the value directly and personally to a handful of real users and observe whether they want it at all. In a *Wizard-of-Oz MVP*, the user sees a real UI, but behind it there is no system but a human who enters the answers by hand. The user believes in software, the learning comes from real behavior, and almost nothing has been built. Both test a hypothesis before a single line of production code exists. They prove the thesis in the clearest way: “viable” means enough to learn honestly, not enough to sell. What matters here is the separation from the prototype, without turning it into an artificial wall. A prototype usually examines feasibility or usability and can of course be tested with real users for that. An MVP in my working definition, on the other hand, tests a market or value hypothesis. What counts are the question and the evidence, not whether the artifact is shown internally or externally. ## The hypothesis as code If an MVP is an experiment, then the experiment should be declared so precisely that it can be refuted. In the projects where this held up, the hypothesis came before the first line of code – structured, versioned, next to the code in the repository instead of on a forgotten slide. ```yaml # experiment.yaml – declares the MVP before any code is written experiment: name: "concierge-checkout" riskiest_assumption: "users will connect a payment method to finish an order" hypothesis: "at least 30% of activated users will add a payment method" target_metric: activation_rate # added payment / reached checkout success_threshold: 0.30 kill_criteria: "activation_rate < 0.10 after 200 sessions" sample_size: 200 cohort: "new signups, region DE" ``` The decisive point is the last fields. Without `success_threshold` and `kill_criteria`, it isn’t an experiment. An experiment that can’t be allowed to fail measures nothing. Agreement most often breaks down at `kill_criteria`, and that is exactly where its value lies: it forces the team to agree beforehand when the idea is refuted – before emotional attachment to its own solution clouds the judgment. Ries calls the opponents of these honest numbers *vanity metrics*: figures such as total registrations, which always point upward and never force a decision. The `target_metric` has to be an *actionable metric* that can topple an assumption. ## Cutting the narrow path cleanly on the technical side The vertical slice also has a technical side, and here two worlds connect that are often discussed separately: product thinking and delivery. The wrong MVP grows for weeks in a long feature branch next to the main line and at some point lands in a big, risky merge. The better way is to build the experiment on trunk and switch it on for the experiment cohort only through a feature flag. Everyone else sees the status quo; the narrow new path is fully live for a small group. ```javascript // the MVP path ships on trunk, gated by a flag – not hidden in a long branch function renderCheckout(user, cart) { if (featureFlags.isEnabled("concierge_checkout", user)) { trackExperiment("concierge-checkout", user); return conciergeCheckout(cart); // narrow but complete path to value } return standardCheckout(cart); // everyone else: unchanged status quo } ``` That is more than a technical trick. It makes visible what an MVP is: a narrow but fully working segment – not a feature that is half visible everywhere and finished nowhere. Trunk-Based Development and short-lived branches make sure the experiment can be shipped at any time and switched off again just as quickly. Techniques such as *canary release* and *blue-green deployment* give the same principle its operational side: a small cohort gets the new thing, the rest stays safe. If the experiment reaches beyond one service, another angle helps with honest testing. Instead of faking a full integration, the MVP service fulfills a minimal but real *consumer-driven contract*. The consumer writes down what it really needs, and the MVP fulfills exactly that – no more. ```groovy // consumer-driven contract: the MVP fulfils a real, minimal contract // instead of faking a full integration Pact.provider("payment-service").upon("checkout") .given("an activated user") .uponReceiving("a request to attach a payment method") .withRequest(method: "POST", path: "/methods") .willRespondWith(status: 201, body: [status: "attached"]) ``` The point behind it: the narrow path is real, not a facade. It really integrates against what it needs, but only against that. That keeps the learning signal clean without having to finish building the whole system. ## Why this is faster, even though it sounds like more effort The most common objection: setting up experiments, metrics, flags and contracts sounds like more work, not less. The objection confuses two quantities – effort per delivery and effort per insight gained. “Accelerate” by Forsgren, Humble and Kim provides part of the technical foundation for this. The four DORA metrics of the time – deployment frequency, lead time for changes, change fail rate and time to restore – stand for delivery capability, not for the market value of an experiment. A team that can ship small changes frequently and stably does, however, lower the technical hurdle for short experiments and quick rollbacks. An MVP that is only a reduced feature set saves build time once and pushes the risk to the back. An MVP as an experiment costs some discipline up front and makes the risk visible earlier. That is no guarantee of less friction or higher quality. But it separates the question “Can we deliver it?” from the more important question “Which assumption are we testing with it?”. By the way, if you take the MVP as an experiment seriously, you think toward a viable architecture from the start. An approach such as *evolutionary architecture* with *fitness functions* fits exactly, because it accepts that the product evolves along what you learn – not along a plan nobody has tested. ## Conclusion An MVP isn’t an amputated product. In my working definition, it is an experiment that honestly tests a risky assumption – the smallest version with which you can really test a hypothesis. A confirmatory test needs a learning question and a decision criterion set in advance; exploratory discovery may start more openly. Often that is a vertical slice through to the value, sometimes a concierge test or a landing page. “Minimal” refers to the necessary scope, not to carelessness. And it doesn’t even have to be code. When a team switches from “the product, but less” to “the smallest version that honestly tests an assumption”, it isn’t the toolbox that changes but the guiding question. No longer “What else can we leave out?” but “What do we need to learn next, and what does the smallest honest test for it look like?”. This question doesn’t prevent wrong decisions, but it makes visible which learning is supposed to justify the next investment. ## Further reading - Eric Ries, *The Lean Startup* (2011) – definition of the MVP, Build-Measure-Learn, validated learning, vanity vs. actionable metrics - Steve Blank, “A minimum viable product is not always…” (blog, 2013) and *The Four Steps to the Epiphany* (2005) – customer development - Melissa Perri, “Finding the Truth Behind MVPs” (2016) – concierge and Wizard-of-Oz MVP - Nicole Forsgren, Jez Humble, Gene Kim, *Accelerate* (2018) – the four DORA metrics - Neal Ford, Rebecca Parsons, Patrick Kua, *Building Evolutionary Architectures* (O’Reilly, 2017) – fitness functions - Martin Fowler, “FeatureToggle” (2017) and trunkbaseddevelopment.com – feature flags and Trunk-Based Development - Consumer-Driven Contracts (Fowler/Robinson, 2006) and the contract testing tool Pact --- # A GraphQL Schema in the Domain Language URL: https://www.mikebild.dev/en/blog/a-graphql-schema-in-the-domain-language/ Date: 2018-04-24 # A GraphQL Schema in the Domain Language The German word “Fachsprache” has two readings, and the more common one is explicitly not meant here. It isn’t about jargon – not the vocabulary an industry uses to keep outsiders at a distance. What I mean is what Eric Evans described in 2003 in “Domain-Driven Design” as the ubiquitous language: the one shared language that the business side and development actually speak in a project. The same words in the meeting, in the ticket, in the model, in the code. One vocabulary for everyone – not two vocabularies with a translation table in between. The idea is fifteen years old, and in practice it rarely fails for lack of will. It fails for lack of a place. A glossary in the wiki goes stale from the day it is created, because nobody updates it when a field gets renamed. The code would be the more honest place, but the code belongs to only one side: the business department doesn’t read Java classes. What was missing all these years was an artifact that both sides can read and that is checked by machines at the same time. Since I started working with GraphQL, I’m convinced this artifact now exists: the schema. And – this is the more uncomfortable part of the thesis – you may speak the domain language there in German, too. ## Translating twice, losing twice In projects with a German-speaking business side, I have run into the same pattern again and again over the years. The business department says “Angebot” (offer). The database says `OFFER`, the class in the service is called `Quote`, and a `Proposal` shows up in the frontend – three translations of the same word, created at three points in time under three different deadlines. Ever since, every conversation between the business side and development translates twice: on the way in while listening, on the way back while answering. Each of these translations doesn’t just cost time, it distorts. Whether “Angebot” should be called offer, quote, bid or proposal isn’t a neutral choice – each of these words carries its own meaning in English, and none matches exactly what the business side means. In the end, a developer under deadline pressure makes the decision, and it then stays in the system for years – unnoticed, but effective in every single conversation about exactly this field. ```mermaid flowchart LR F["Business side
    says “Angebot”"] -->|translate| E["Development
    Offer? Quote? Bid?"] E -->|translate| S["System
    OFFER, Quote, Proposal"] S -->|translate back| E E -->|translate back| F ``` The most expensive misunderstandings I have seen in reviews were rarely technical in nature. They were terms that had changed their meaning on the way through this chain – a “storniertes Angebot” (canceled offer) that was a `cancelled quote` in the system, even though the business side understood something different by “Stornierung” than development did by cancelled. ## The experiment: uber-ng In March, I created a small repository for this: [uber-ng](https://github.com/MikeBild/uber-ng), a deliberately manageable recreation of a ride-hailing service like the one you know from Uber. Not a product – a prototype with in-memory data, a few Mocha tests and a single question: How does a GraphQL schema read when the domain terms stay German? The schema sits there as a separate file in schema notation – the SDL that is currently being added to the GraphQL specification after years of being merely a tooling convention. The core looks like this: ```graphql enum STATUS { angefragt warteAufBestaetigung angenommen } type Angebot implements Node { id: ID! fahrgast: Fahrgast von: String! nach: String! fahrer: Fahrer wartezeit: String status: STATUS } type Mutation { fahrtAnfragen(input: AnfrageInput!): Angebot angebotAnnehmen(input: AngebotAnnehmenInput!): Angebot angebotAblehnen(input: AngebotAblehnenInput!): Angebot } type Subscription { onAngebotChanged: Angebot } ``` If you read this, you don’t need a glossary next to it. A ride is requested (“fahrtAnfragen”); what results is an offer (“Angebot”); an offer can be accepted or declined – and whoever declines must give a reason, because `AngebotAblehnenInput` requires a `grund: String!`. The mutations are verbs of the domain, not CRUD prose. `fahrtAnfragen` even enforces a domain distinction that a `createOffer` would have swallowed: what gets requested is a ride – the offer is the system’s answer to it, not something the passenger creates themselves. I only noticed this difference while formulating the schema, not before. The clients’ requests then speak this language, too: ```graphql mutation { fahrtAnfragen(input: { fahrgastId: "f1" von: "Alexanderplatz" nach: "Flughafen Tegel" }) { id status wartezeit } } ``` You can read this mutation out loud in a meeting, and the business side understands it without an interpreter. That is no small thing. It is the moment an API stops being a pure developer artifact. Technically, the setup is deliberately ordinary: Node, a GraphQL server, subscriptions over WebSockets, as they have become established with `subscriptions-transport-ws` by now. `onAngebotChanged` pushes every state change of an offer to the connected clients – the passenger sees when `angefragt` (requested) turns into `warteAufBestaetigung` (awaiting confirmation) without having to ask. For the experiment, that is a side issue. The only interesting part is that this channel speaks the domain language, too: what arrives at the client is called Angebot, not `OfferDTO`. ## What makes the schema a glossary A glossary describes a language. The schema enforces it – and that is exactly what it has over every glossary I have come across so far: - Every query is validated against the schema. Whoever invents or misspells a term gets an error instead of a silent misunderstanding. - Introspection makes the vocabulary queryable: GraphiQL shows types, fields and descriptions while you type – the glossary delivers itself. - `@deprecated` retires terms in an orderly way, with a reason and visible to every client. In uber-ng, exactly such a note is attached to `fahrgastId`. - The schema lives in version control. Every change of a term is a diff, and a diff can get a review in which the business side takes part, too. Then there are the description texts: the SDL allows a description on every type, every field and every enum value, and introspection delivers it along. So it doesn’t just say that there is an `Angebot`, but what the business side means by it – the definition travels with the term instead of aging in another system. A wiki can do none of this. Neither can a UML model. To my knowledge, the GraphQL schema is the first artifact that is at the same time readable by humans, checkable by machines and binding for operations. The schema is the glossary – not a copy of it. ## States have names The most inconspicuous part of the schema carries the most weight: the enum. `STATUS` with its three values is a complete, checkable description of an offer’s lifecycle – and the values are named the way the business side would say them on the phone. In older systems, I rarely found this lifecycle written down anywhere. There, it is scattered across status strings in the database, if cascades in the service and the memory of the longest-serving colleague. Here, it is a few lines long, versioned and visible to every client: ```mermaid stateDiagram-v2 [*] --> angefragt: fahrtAnfragen angefragt --> warteAufBestaetigung: Matching in progress warteAufBestaetigung --> angenommen: angebotAnnehmen warteAufBestaetigung --> [*]: angebotAblehnen ``` This is also where the first ugly spot shows: `warteAufBestaetigung`. GraphQL names only allow ASCII – letters, digits, underscore. The “ä” has to stay out; the domain language only gets into the schema filtered. I write this down deliberately instead of hiding it: if you choose German identifiers, you also choose `Bestaetigung`, `Strasse` and `ueberweisen`. In running text, that would be a spelling mistake; in the schema, it is the price of the decision, and you should know it before you make it. ## Schema in German, implementation in English The second question the experiment was supposed to answer: Where does the boundary run? After a few weeks, for me it lies exactly at the resolver map. The schema carries the domain language; everything behind it stays English – variables, helper functions, comments. Simplified, and written here with `graphql-subscriptions`, the pattern looks like this: ```javascript const uuid = require('uuid/v4'); const { PubSub } = require('graphql-subscriptions'); const pubsub = new PubSub(); const offers = {}; // in-memory store, resets on restart const resolvers = { Query: { angebote: (root, { take = 10, skip = 0 }) => Object.values(offers).slice(skip, skip + take), }, Mutation: { fahrtAnfragen: (root, { input }) => { // a ride request creates a new offer in its initial state const offer = { id: uuid(), von: input.von, nach: input.nach, status: 'angefragt', }; offers[offer.id] = offer; pubsub.publish('offerChanged', { onAngebotChanged: offer }); return offer; }, angebotAnnehmen: (root, { input }) => { const offer = offers[input.angebotId]; // accepting is only valid while the offer awaits confirmation if (offer.status !== 'warteAufBestaetigung') return offer; offer.status = 'angenommen'; pubsub.publish('offerChanged', { onAngebotChanged: offer }); return offer; }, }, Subscription: { onAngebotChanged: { subscribe: () => pubsub.asyncIterator('offerChanged'), }, }, }; ``` The German words appear exactly where the schema demands them: as keys of the resolver map and as enum values. The rest is ordinary English code. This separation has proven surprisingly stable, and it corresponds to the domain truth: `offers` and `pubsub` are technology and may be English. `Angebot` is a term with domain meaning, and it belongs to the business side – not to whoever happens to be implementing it. A side effect I hadn’t expected: the tests suddenly read like domain texts, too. A Mocha test that calls `fahrtAnfragen` and then checks whether the status is `angefragt` describes a domain fact – you could copy it almost word for word into the ticket as an acceptance criterion. Test coverage turns into a piece of documented domain knowledge, without needing an additional tool. ## What speaks against it Let me stay honest: the experiment also made the resistance visible, and it isn’t small. The break in style first. `type Angebot implements Node` mixes two languages in one line. `onAngebotChanged` glues an English prefix onto a German noun and appends an English participle – an identifier made of three language layers. camelCase is built for English word boundaries; with German compounds it gets bumpy, and nobody reads `warteAufBestaetigung` fluently. That bothers you while reading, a little bit every day, and it never stops bothering you. Then there is the ecosystem. Every tutorial, every Stack Overflow answer, every example in the Apollo documentation is in English – whoever transfers snippets now translates in the opposite direction. And the hardest limit is the team itself: as soon as a colleague joins who doesn’t speak German, the calculation flips completely. Then the German schema is no longer a bridge to the business side but a wall right through development. And a practical point that counts in everyday work: searchability. If you search for an error message along with `angebotAnnehmen`, you find nothing – if you search with `acceptOffer`, you at least find other people’s discussions that half fit. German identifiers decouple a project to some extent from the web’s collective debugging. For a prototype, that doesn’t matter; for a team under deadline pressure, it does. ## When the domain language wins So the trade-off isn’t a matter of taste but a question to the domain: In which language is the domain itself written? A ride-hailing service is a rewarding playground, but the real use case is domains that are German – not out of habit, but by law. Contracts under German law. Collective wage agreements. Billing rules whose terms a German regulation prescribes word for word. In a billing project a few years ago, words such as “Abschlag” (installment) and “Gutschrift” (credit note) were legally defined; their English translations in the code regularly triggered discussions that didn’t exist in the domain at all – was the `discount` now an “Abschlag” or rather a “Rabatt”? When the law speaks German and the business side thinks in German, an English API layer is the only place in the system that translates. And therefore the only place that can lie without anyone noticing. The reverse holds just as well. An international team, a product for several markets, a public API – there, English is the domain language, and then it belongs consistently in the schema. By the way, the SDL comes with a usable middle path: English identifiers, but German description texts on types and fields. Then the schema at least carries the definitions of the terms, if not their names – and the translation table sits where it is checked and versioned instead of gathering dust in a wiki. ## The bottom line uber-ng won’t become a product, and it never had to. The experiment showed me two things. First: the place is right. A GraphQL schema can deliver what glossaries, wikis and model documents promised for fifteen years and didn’t keep – a shared language that is checked instead of merely described. Second: the language in the schema is an architecture decision, not a question of style. German in the schema has a cost – breaks in style, ASCII crutches, friction with the ecosystem. It pays off exactly when the domain is German and every translation would create a second, unchecked truth. For the projects in between, the question stays open, and that is fine. All that matters to me is that it gets asked at all. So far, in every schema I have seen, it was silently answered with “English” – and silent answers are rarely the well-considered ones. ## Further reading - [uber-ng – GraphQL demo with a German schema (GitHub)](https://github.com/MikeBild/uber-ng) - [GraphQL documentation: Schemas and Types](https://graphql.org/learn/schema/) - [GraphQL Specification](https://spec.graphql.org/) - [Martin Fowler: Ubiquitous Language](https://martinfowler.com/bliki/UbiquitousLanguage.html) - [Eric Evans: Domain-Driven Design Reference](https://www.domainlanguage.com/ddd/reference/) --- # Angular, React and the Value of Transitions URL: https://www.mikebild.dev/en/blog/angular-react-and-the-value-of-transitions/ Date: 2018-03-12 # Angular, React and the Value of Transitions A decision like “we are rewriting the frontend from scratch” does not do its damage right away but with a delay of about nine months. By then, two half products exist: an old AngularJS frontend, officially frozen, that still gets hotfixes all the time because paying users work with it – and a new one that feels about sixty percent done and has no release date, because “everything has to be finished first.” From then on, every business requirement is negotiated twice: once for the old world, once for the one that has not shipped yet. The team quietly splits into keepers and rebuilders, and both groups slow down. I have now seen this course of events up close more than once, most recently in a product team with an AngularJS application that had grown over years. The mistake was never the target framework. It was a word missing from the decision: transition. In practice, a framework switch is not a rewrite but a state in which two worlds run in parallel for months. And whether this state turns out cheap or ruinous has surprisingly little to do with Angular or React. ## The driver: AngularJS gets an expiration date Since the end of January, what had long been looming is official: AngularJS 1.x gets one last development cycle with version 1.7 and then moves into a three-year long-term support phase. From then on, there will only be security fixes and adjustments to new browser and jQuery versions, no more features. For teams with large 1.x applications, this is the moment when “at some point we have to get out of there” becomes a date. Accordingly, many migration decisions are being made right now. Whether the target is called Angular 5 (Angular 6 is due in the coming months) or React 16 – I find the direction secondary. What is interesting is how the decision is phrased. “We are rewriting” is a project with an end date, and that end date almost always slips. “We run both worlds in parallel and move piece by piece,” on the other hand, is a state you can steer, measure and stop if necessary. ## Rewrite or move That brings me to the actual thesis: the quality of a frontend architecture does not show in how modern its framework is, but in how cheap it would be to run two frameworks in parallel. If you have kept domain logic framework-free – plain modules, services without DI magic, state outside the components – you move. If you have poured calculations, validations and API calls into controllers, directives and components, you rewrite, whether you want to or not. The framework was then never a frame but the load-bearing structure of the entire building, and you do not swap load-bearing structures while the building is in use. In the product team I mentioned, we did not migrate anything at all for two weeks before the first migration step. We pulled domain logic out of directives and moved it into simple ES modules, with the existing AngularJS services as a thin shell on top. Only after that was it even possible to decide which part would be a move and which part had to remain a rebuild. The distinction was sobering in its concreteness: whatever got by without an `angular.module` import could be moved like a piece of furniture. Everything else had to be assessed individually. ## Hybrid operation with ngUpgrade For the direction from AngularJS to Angular, running in parallel is not a trick but a documented, officially supported mode. The `UpgradeModule` starts the old application inside the new one: ```typescript // app/app.module.ts — Angular 5 hosting AngularJS 1.6 import { NgModule } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; import { UpgradeModule } from '@angular/upgrade/static'; @NgModule({ imports: [BrowserModule, UpgradeModule], }) export class AppModule { constructor(private upgrade: UpgradeModule) {} ngDoBootstrap() { // AngularJS boots inside Angular, not the other way around this.upgrade.bootstrap(document.documentElement, ['orderApp'], { strictDi: true }); } } ``` From this point on, both frameworks run in the same DOM tree. New Angular components can be passed down into old templates: ```typescript // expose a new Angular component to old AngularJS templates import { downgradeComponent } from '@angular/upgrade/static'; import { InvoiceFooterComponent } from './invoice-footer.component'; angular .module('orderApp') .directive('invoiceFooter', downgradeComponent({ component: InvoiceFooterComponent })); ``` Conversely, old services can be passed up into the new dependency injection. That sounds convenient, and that is exactly where the danger lies: if you use the bridge too often, you intertwine both worlds more tightly than they were before the migration. Two change detection mechanisms run at the same time: AngularJS’s digest cycle and Angular’s zone-based detection. Every event that crosses the boundary is translated into both worlds, and bugs at this seam are unpleasant to track down. Hybrid operation is a tool for getting through a transition period – not for extending it. It needs an end that someone says out loud. ## Route by route: the strangler approach The idea behind it is much older than any of the frameworks involved. Back in 2004, Martin Fowler described how new systems grow around old ones like a strangler fig around its host tree – the Strangler Application. Translated to a frontend, that means: a thin shell owns the router and decides per route which world renders. There is now even a small framework of its own for exactly this pattern, single-spa, but at its core, routing discipline is enough. ```mermaid flowchart LR B[Browser] --> S[Router shell] S --> O["/orders
    AngularJS 1.6"] S --> I["/invoices
    Angular 5"] S --> R["/reports
    Angular 5"] O -. "moves over
    route by route" .-> I ``` Splitting along routes has three properties that I have not found in this combination in any other migration split: - Every step can be rolled back individually – switching a route back is a router entry, not a rollback drama. - Progress is measurable and visible to everyone: this many routes old, this many new. - The boundary is about the domain, not the technology. “Invoices have moved” is something the product owner understands too; “the directive layer has been ported” is something nobody outside the team understands. The big-bang alternative has none of these properties. It only has a deadline, and deadlines do not defend themselves. Incidentally, the route split also changes the team dynamics. Instead of a keepers group and a rebuilders group, there is one team that runs the same application and rebuilds it route by route along the way. Every completed step lands in production and gets put through its paces by real users – feedback arrives after weeks, not after a year and a half. That is unspectacular, but that is exactly where its value lies. ## Domain logic that survives the move The cheapest thing to move is code that knows nothing about any framework. In the application I mentioned, the invoice total logic was such a candidate – previously spread across a directive and two controllers, afterward a single module: ```javascript // billing/invoice-totals.js — plain ES module, no framework imports export function calculateInvoiceTotal(items, taxRate) { const net = items.reduce((sum, item) => sum + item.price * item.quantity, 0); const tax = net * taxRate; return { net, tax, gross: net + tax }; } ``` The old world uses the module through an AngularJS component: ```javascript // old world: AngularJS 1.6 component wrapping the plain module import { calculateInvoiceTotal } from '../billing/invoice-totals'; angular.module('orderApp').component('invoiceFooter', { bindings: { items: '<', taxRate: '<' }, controller: function InvoiceFooterController() { this.$onChanges = () => { this.totals = calculateInvoiceTotal(this.items, this.taxRate); }; }, template: '{{ $ctrl.totals.gross | currency }}', }); ``` The new world – deliberately React 16 here, to show that the direction does not matter – uses the same module unchanged: ```jsx // new world: React 16 component, same module untouched import { calculateInvoiceTotal } from '../billing/invoice-totals'; export function InvoiceFooter({ items, taxRate }) { const totals = calculateInvoiceTotal(items, taxRate); return {totals.gross.toFixed(2)} €; } ``` The direction of dependencies is the actual rule here, not the module format: ```mermaid flowchart TD OLD["AngularJS components
    old world"] --> CORE["Domain logic modules
    without framework import"] NEW["React or Angular components
    new world"] --> CORE CORE -. "forbidden:
    core knows no UI" .-> OLD ``` More can be kept framework-free than you might think at first glance: calculations and validations as pure functions, API access behind a module of its own instead of `$http` or `HttpClient` directly in components, application state in a store of its own. Redux is a good example here, because it is deliberately built to be framework-neutral – `react-redux` and `ng-redux` are just thin bindings. A Redux store including its reducers moves from AngularJS to React without a single changed line. What remains are thin components that take data and emit events. Those are exactly what then get rewritten – and that is the part of the work that goes quickly and carries little risk. ## Custom Elements as a neutral bridge If you are not migrating from AngularJS to Angular but, say, have to reconcile Angular and React in the same product, you have no `UpgradeModule`. The most neutral bridge emerging here is the web platform itself: Custom Elements. A component registered in the DOM as `` can be rendered by any world – React simply writes the tag into JSX, AngularJS into a template, a server-rendered CMS into its HTML stream. With Angular Elements, an official labs project has been announced for exactly this, which is supposed to become tangible with Angular 6: packaging Angular components as Custom Elements, without an adapter per target framework. I find the direction remarkable, because it pulls the bridge out of the framework dispute and puts it on a browser standard. You have to stay honest about the browser situation: Custom Elements v1 run natively in Chrome and Safari; elsewhere, polyfills are still needed for now. For internal applications, that is usually acceptable; for public sites, it needs to be weighed. ## The honest price: two bundles Running in parallel is not free, and I do not believe in downplaying that. If you ship AngularJS and Angular – or Angular and React – at the same time, you send two framework runtimes over the wire. Depending on the combination, that quickly adds up to 150 kilobytes of additional compressed JavaScript before the first line of your own code is loaded. On top of that come two rendering models in the same browser tab, duplicate date and number formatting, and in the worst case duplicate HTTP layers with separate caches. The freshly released webpack 4 at least makes the bundle side easier to handle: `splitChunks` replaces the old CommonsChunkPlugin and automatically pulls shared modules – such as the framework-free domain logic packages – into shared chunks. But tools only ease the price; they do not remove it. That is why an honest transition includes a budget: a measured upper limit for the total weight, a date after which the old bundle may no longer grow and a target quarter in which it disappears. Running in parallel is a loan. You may take it out – you should just know the interest rate and write down the repayment plan. ## What I take away from this The LTS announcement for AngularJS has just handed many teams a deadline, and deadlines tempt you into heroic decisions. The big-bang rewrite is one such heroic decision: it feels good on the day of the decision and, nine months later, like two half products. The transition is the unspectacular alternative – hybrid operation where it exists, a strangler split along the routes, Custom Elements as a bridge, an honestly quantified load weight. But what really occupies me about the topic is looking back at your own architecture. Running in parallel is a test bench: it reveals how much of the application really belongs to us and how much to the framework. Domain logic in plain modules, state outside the components, API access behind boundaries of your own – that does not only pay off during a migration, but during a migration the bill comes due mercilessly. And since, after this switch, the next one will come at some point, I write the new world right away so that it makes the transition after next cheap. That may be the most useful question to ask of any frontend design, with no migration pressure at all: How expensive would it be to start a second world next to this application? ## Further reading - Angular documentation: Upgrading from AngularJS: https://angular.io/guide/upgrade - Martin Fowler: StranglerApplication (2004): https://martinfowler.com/bliki/StranglerApplication.html - Angular blog: Stable AngularJS and Long Term Support: https://blog.angular.io/stable-angularjs-and-long-term-support-7e077635ee9c - single-spa: https://single-spa.js.org/ --- # Prototypes: The Object Model Behind JavaScript Classes URL: https://www.mikebild.dev/en/blog/prototypes-the-object-model-behind-javascript-classes/ Date: 2017-11-21 ```js class Animal { constructor(name) { this.name = name; } speak() { return this.name + ' makes a sound'; } } const minka = new Animal('Minka'); const rex = new Animal('Rex'); minka.speak === rex.speak; // true minka.hasOwnProperty('speak'); // false Object.getPrototypeOf(minka) === Animal.prototype; // true ``` Three lines of output, and the whole article is in them. The method `speak` exists exactly once, even though two instances call it. Neither instance owns it – `hasOwnProperty` says no. It is found on a third object, `Animal.prototype`, which both instances point to with an internal reference. `class` didn’t invent this third object; it just moved it out of sight. In JavaScript, the reference to it carries every method lookup, every inheritance relationship, and every lost `this` binding. That is why I build up the model from the bottom here: first plain prototypes with `Object.create`, then constructor functions and the `new` sequence, then `class` as the facade that combines both. ## Every object has a link upward The foundation is surprisingly simple. Every object in JavaScript carries an internal reference, called `[[Prototype]]` in the specification. This reference points either to another object – the prototype – or to `null`. When you access a property that the object itself doesn’t have, the language doesn’t give up and return `undefined`. It first follows the `[[Prototype]]` link and keeps searching there. And if it finds nothing there, it goes one link higher. That is how the prototype chain comes about, and it ends at `null`. You see this most clearly without any `class` and without `new`, using only `Object.create`: ```js const animal = { describe() { return this.name + ' makes ' + this.sound; } }; const dog = Object.create(animal); dog.name = 'Rex'; dog.sound = 'woof'; dog.describe(); // 'Rex makes woof' Object.getPrototypeOf(dog) === animal; // true dog.hasOwnProperty('describe'); // false dog.hasOwnProperty('name'); // true ``` Look at what happens here. The object `dog` itself only owns `name` and `sound` – `hasOwnProperty` confirms that. It doesn’t find the method `describe` on itself but only one step higher, on `animal`. During the call, though, what counts is who the receiver was: `this` is `dog`, which is why `describe` reads `Rex` and `woof`. The method lives on the prototype, the data lives on the instance, and the lookup connects the two. That is the whole mechanism – no classes, no constructors, just one object pointing to another. `Object.create` makes this link explicitly visible: the first parameter becomes the new object’s `[[Prototype]]` directly. You can even write `Object.create(null)` and get an object with no prototype at all – no `toString`, no `hasOwnProperty`, a bare dictionary. Useful when you want an object as a pure key-value store and don’t want inherited properties getting in the way. ## The chain, visualized When `dog.describe()` is called, the lookup walks up the chain. The following diagram shows the stations up to the end at `null`: ```mermaid graph TD A["dog
    own: name, sound"] -->|"[[Prototype]]"| B["animal
    own: describe"] B -->|"[[Prototype]]"| C["Object.prototype
    own: hasOwnProperty, toString"] C -->|"[[Prototype]]"| D["null"] ``` Every arrow is a `[[Prototype]]` reference, and the lookup climbs along them. If the language looks for `describe`, it finds it at `animal`. If it were looking for `toString`, it would go one station further to `Object.prototype`. And if it were looking for something that exists nowhere, it would arrive at `null` and return `undefined`. This chain is not a special case for hand-built objects – every object, every array, every function hangs on a chain like this, with `Object.prototype` at its root. ## Constructor functions: the way before `class` Before ES2015, you built reusable “types” with constructor functions. The trick lies in two parts that you have to keep apart. First: every function has a property called `prototype` – an ordinary object that serves as a template. Second: the `new` operator connects a fresh object to exactly this template. ```js function Animal(name) { this.name = name; } Animal.prototype.speak = function () { return this.name + ' makes a sound'; }; const cat = new Animal('Minka'); cat.speak(); // 'Minka makes a sound' Object.getPrototypeOf(cat) === Animal.prototype; // true cat.hasOwnProperty('speak'); // false ``` What exactly does `new Animal('Minka')` do? The sequence has – simplified – three steps. First, a new, empty object is created, and its `[[Prototype]]` is set to `Animal.prototype`. Then `Animal` is called with `this` pointing to this new object – that is how `this.name = name` ends up as an own property on the instance. And finally: if the function itself doesn’t return an object, the new object becomes the result. That is why `speak` isn’t on the instance but on `Animal.prototype`, and is shared by all cats. Before `class`, inheritance was manual work – and precisely this manual work shows what `extends` later automates: ```js function Dog(name) { Animal.call(this, name); // Parent-Konstruktor auf eigenem this } Dog.prototype = Object.create(Animal.prototype); // Kette einhängen Dog.prototype.constructor = Dog; // constructor wieder setzen Dog.prototype.speak = function () { return this.name + ' makes woof'; }; const rex = new Dog('Rex'); rex.speak(); // 'Rex makes woof' rex instanceof Dog; // true rex instanceof Animal; // true ``` Three lines carry the load here. `Animal.call(this, name)` calls the parent constructor on your own `this` so that `name` gets set. `Dog.prototype = Object.create(Animal.prototype)` hooks in the prototype chain, so that a Dog instance searches first at `Dog.prototype`, then at `Animal.prototype`, then at `Object.prototype`. And the third line repairs something the second one broke: overwriting `Dog.prototype` lost the `constructor` back-reference, which we restore manually. Details like these are exactly what you forget in practice – and what `class` takes off your hands. ## The same thing as a `class` Now the same code in ES2015 syntax, imagined side by side. The result is identical in the object model – the same prototype objects, the same chain, the same shared methods: ```js class Animal { constructor(name) { this.name = name; } speak() { return this.name + ' makes a sound'; } } class Dog extends Animal { constructor(name) { super(name); } speak() { return this.name + ' makes woof'; } } const rex = new Dog('Rex'); Object.getPrototypeOf(rex) === Dog.prototype; // true Object.getPrototypeOf(Dog.prototype) === Animal.prototype; // true ``` Compare this with the ES5 version, and the translation becomes immediately visible. The `speak` methods in the class body end up on `Animal.prototype` and `Dog.prototype` – not on the instance. `extends Animal` takes care of hooking in the chain, for which we just wrote `Object.create(Animal.prototype)` by hand. And `super(name)` replaces the manual `Animal.call(this, name)`. The last line proves it: `rex` points to `Dog.prototype`, and that points to `Animal.prototype`. The same chain as before, just without the boilerplate and without the forgotten `constructor` line. You still have to be honest, though: `class` is syntactic sugar, but not exclusively. A class body always runs in strict mode. A class can’t be called without `new` – the attempt throws an error, whereas a constructor function could also be misused as a regular function. And `class` declarations aren’t hoisted to the top and initialized like `function` declarations; they sit in a temporal dead zone and can’t be used before the line where they are defined. `super` in methods also relies on an internal mechanism (`[[HomeObject]]`) that you can’t replicate one to one in plain ES5. So the facade is convenient and, at a few edges, stricter than the original – but the model underneath is still prototypes. ## Cleanly separating `prototype`, `__proto__`, and `Object.create` The most common confusion I run into in code reviews revolves around two similar-sounding names. `prototype` and `__proto__` are not the same, and mixing them up produces bugs you stare at for a long time. This list sorts out the three tools: - A constructible function usually has its own `prototype` property. `new` uses the object referenced there as the prototype of the instance. Ordinary instances don’t have their own `prototype` property; arrow functions and methods aren’t constructible and don’t have such a template either. - `__proto__` (or the internal `[[Prototype]]`) is the actual chain link that every object carries. The canonical access goes through `Object.getPrototypeOf(obj)`; `__proto__` itself is only standardized in ES2015 via Annex B and is considered legacy. - `Object.create(proto)` creates an object and sets its `[[Prototype]]` directly to `proto` – with no constructor function at all. That is the direct way to lay down a chain link. The crucial difference: `Fn.prototype` is the template on the function, `instance.[[Prototype]]` is the link on the created object. When `new Fn()` is called, one becomes the other. And to untangle it once and for all – the function itself is also an object and has its own link: ```js function Fn() {} const obj = new Fn(); Object.getPrototypeOf(obj) === Fn.prototype; // true (Instanz-Link) obj.prototype; // undefined (Instanz hat keine) Object.getPrototypeOf(Fn) === Function.prototype; // true (Fn ist selbst Objekt) ``` Pay attention to the last line. `Fn.__proto__` is `Function.prototype`, not `Fn.prototype`. If you mix these two up, you look for methods in the wrong place. When in doubt, `Object.getPrototypeOf` always helps you walk the chain step by step instead of guessing. ## The most expensive pitfall: methods in the constructor Now to the point that costs memory in real codebases and often slips through reviews. It makes a tangible difference whether a method lives on the prototype or is created in the constructor: ```js function WidgetBad() { this.render = function () { /* ... */ }; // pro Instanz eine neue Funktion } function WidgetGood() {} WidgetGood.prototype.render = function () { /* ... */ }; // geteilt const a1 = new WidgetBad(); const a2 = new WidgetBad(); a1.render === a2.render; // false -> zwei getrennte Funktionen const b1 = new WidgetGood(); const b2 = new WidgetGood(); b1.render === b2.render; // true -> eine Funktion, geteilt ``` The proof is in the comparisons. With `WidgetBad`, every instance gets its own `render` function – with a thousand widgets, that is a thousand identical functions in memory. With `WidgetGood`, `render` lives once on `WidgetGood.prototype`, and all instances share it. That is exactly what `class` does automatically: methods in the class body end up on the prototype, not on the instance. So with `class`, you don’t have to make any effort for the good case – you just must not destroy it with an assignment in the `constructor`. The second common pitfall is losing `this`. A prototype method only knows its receiver when it is called as `obj.method()`. If you detach it, the binding is gone: ```js const cat = new Animal('Minka'); const fn = cat.speak; fn(); // this ist nicht mehr cat -> Fehler oder falsches Ergebnis const bound = cat.speak.bind(cat); bound(); // 'Minka makes a sound' -> this wieder gebunden ``` That is not a bug but a direct consequence of the model: `this` is determined at call time, not at definition time. If you pull `cat.speak` out into a free variable, the receiver is missing. The tools against this are established in 2017: `.bind(cat)` creates a permanently bound variant, or you wrap the call in an arrow function that takes `this` from the surrounding scope. A side note on what is coming: class fields with arrow functions are in the works and are meant to make exactly this binding more elegant – but at the end of 2017, that is still a TC39 proposal and not a standard. If you need it in production today, reach for `bind` or an arrow wrapper. ## Why this pays off You can write JavaScript with `class` for years without ever saying “prototype.” Until the day `this` is `undefined` in an event handler, an inherited method can’t be found, or a profiler shows the same function a thousand times in the heap. That is when the people who know the model part ways with the people who guess. The three recurring symptoms – lost `this`, a method in the wrong place, memory per instance – are not quirks of the language but logical consequences of a chain of objects pointing to each other. `class` has its place: readable, strict, and it takes the error-prone boilerplate of ES5 inheritance off your hands. But it is a facade, and behind the facade there is still `Object.create`, `Fn.prototype`, and a `new` that connects the two. The next time you write `extends`, think briefly about the three lines it replaces – the hooked-in chain, the `super` call, the `constructor` back-reference. Then `class` is no longer magic but a shortcut whose long form you could write out yourself at any time. This prototypal thinking is the same common thread that runs through the [JavaScript patterns that stayed](https://www.mikebild.dev/en/blog/javascript-patterns-that-stayed/) – objects pointing to objects, functions as building blocks. If you understand this foundation, you build on frameworks more calmly. ## Further reading - MDN, Inheritance and the prototype chain: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain - MDN, Object.create: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create - MDN, Object.getPrototypeOf: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getPrototypeOf - MDN, Object.setPrototypeOf: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/setPrototypeOf - MDN, Object.prototype.\_\_proto\_\_: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto - MDN, Classes: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes - MDN, new operator: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/new - ECMAScript 2015 (ES6) Spec: https://www.ecma-international.org/ecma-262/6.0/ - ECMAScript 2017 (ES8) Spec: https://www.ecma-international.org/ecma-262/8.0/ --- # Redux as a Protocol for UI Changes URL: https://www.mikebild.dev/en/blog/redux-as-a-protocol-for-ui-changes/ Date: 2017-10-12 # Redux as a Protocol for UI Changes In networking, a protocol is not software but an agreement: it defines which messages may flow between parties, how each message is structured and what it means. TCP doesn’t dictate to anyone which program runs at the endpoints – it only determines the shape of the packets and the rules of the exchange. Exactly this notion, applied to a user interface, describes Redux more accurately than the usual shorthand. That shorthand goes: Redux is a global state container for React applications. That isn’t wrong, but it points at the most boring part. Every application has an object that holds application state – as `window.appState` if need be, and that alone gains you nothing. What’s interesting about Redux is the agreement on how this object may change: exclusively through named, serializable messages. Redux is less a container than a protocol for changes – between the parts of the UI and, which is easily overlooked, across time. When you dispatch an action today, you are also talking to the colleague who reads the action log of a bug report in three months. ## Three building blocks, very unevenly weighted Redux consists of three parts: the store, which holds the state, the actions, which describe changes, and the reducers, which compute the new state from the old state and an action. The store itself is surprisingly unspectacular – a few dozen lines around an object, a `dispatch` function and a list of subscribers. If you read the source code of `createStore`, you’re done in one cup of coffee. The value lies in what the other two building blocks enforce. An action is a simple object with a `type` and a payload: ```js // actions.js export const ORDER_SUBMITTED = 'ORDER_SUBMITTED'; export const ORDER_ACCEPTED = 'ORDER_ACCEPTED'; export const ORDER_REJECTED = 'ORDER_REJECTED'; export const submitOrder = order => ({ type: ORDER_SUBMITTED, payload: { orderId: order.id, items: order.items } }); ``` No function pointer, no class instance, no reference to a component. Just data that can be written down as JSON. That looks like a restriction – and it is meant to be exactly that. A message that can be serialized can also be recorded, sent, compared and still read years later. A method call can do none of that. The reducer is the second half of the agreement: a pure function that never triggers anything itself but only answers what a message means for the state. ```js // ordersReducer.js import { ORDER_SUBMITTED, ORDER_ACCEPTED } from './actions'; const initialState = { pending: [], accepted: [] }; export default function ordersReducer(state = initialState, action) { switch (action.type) { case ORDER_SUBMITTED: return { ...state, pending: [...state.pending, action.payload.orderId] }; case ORDER_ACCEPTED: return { ...state, pending: state.pending.filter(id => id !== action.payload.orderId), accepted: [...state.accepted, action.payload.orderId] }; default: return state; } } ``` Almost everything teams value about Redux follows from this separation – message here, meaning there. It is usually filed under “predictability”. A different sorting helps me more: - Every change can be recorded and replayed, because it exists as a data object. - Every change can be tested without a browser, because the reducer is a pure function. - Every change has a name that you can talk about in code review and with the business side. - Every change can be observed from outside without touching the UI. These are not four features. This is the same property four times: there is a protocol. ## Time travel is not magic The Redux DevTools demonstrate this most impressively. Every action appears there as a line in a log, and because the state results only from folding all previous actions over the reducers, you can jump back anywhere in the log – the UI follows. The first time you show it, it looks like a trick. In fact, it is the mundane consequence of the protocol idea: if you know all messages and apply a deterministic function to them, you can reconstruct every intermediate state. Network people have known this forever – a packet capture plus a state machine gives you the complete session. In a project this summer, exactly this spared us a stubborn bug. A user reported a state nobody could reproduce: an order that was displayed as open and confirmed at the same time. Instead of collecting guesses, we had the exported action history sent to us and replayed it locally. The faulty order – `ORDER_ACCEPTED` arrived before `ORDER_SUBMITTED` because two requests had overtaken each other – was there in black and white in the log after five minutes. With scattered `setState` calls, the same diagnosis would have been an afternoon with a debugger and luck. Testing also benefits from the message form, without any test infrastructure at all: ```js // ordersReducer.test.js import ordersReducer from './ordersReducer'; import { submitOrder } from './actions'; it('moves a submitted order into pending', () => { const state = ordersReducer(undefined, submitOrder({ id: '42', items: [] })); expect(state.pending).toEqual(['42']); }); ``` No DOM, no mock of a store, no rendering. Input, output, done. Reducer tests are among the few frontend tests I have never seen be flaky. ## Events instead of commands This is also exactly where the value gets lost fastest, though – not because of the library but because of how the messages are cut. In a code review this spring, I was looking at a reducer whose action list looked like this: `SET_LOADING_TRUE`, `SET_LOADING_FALSE`, `SET_ORDERS`, `SET_ERROR`, `RESET_ERROR`. Formally, everything was correct: named, serializable objects, pure reducers, the DevTools work. Still, the protocol was worthless, because the messages didn’t describe what had happened but which field value the sender would like. That’s not an event protocol; those are remote assignments – `setState` with a detour and more typing. The difference becomes clear in a direct comparison: ```js // commands: the sender prescribes how state must change dispatch({ type: 'SET_LOADING_TRUE' }); dispatch({ type: 'SET_ORDERS', payload: orders }); dispatch({ type: 'SET_LOADING_FALSE' }); // events: the sender reports what happened in the domain dispatch({ type: 'ORDERS_REQUESTED' }); dispatch({ type: 'ORDERS_LOADED', payload: { orders } }); dispatch({ type: 'ORDERS_LOADING_FAILED', payload: { error } }); ``` The event variant has three properties that the command variant lacks. First, it brings domain language into the code: `ORDER_SUBMITTED` is a sentence the product owner understands too; `SET_LOADING_TRUE` is understood only by the author of the component. In review we then talk about the question “May a rejected order be resubmitted?” instead of boolean choreography. Second, an event is in the past and therefore undisputed – it is reported, not ordered. The sender doesn’t need to know who is listening. Third, and precisely for that reason, the circle of receivers scales: if a second reducer later needs to count the number of open orders for a badge, it simply subscribes to `ORDER_SUBMITTED` as well. With `SET_ORDERS`, the sender would have to be rebuilt. A command knows its receiver, an event knows only its cause – in the protocol picture, that’s the difference between an RPC call and a broadcast. Since then, I read action files like a message directory. If they contain a vocabulary of the domain in the past tense, the protocol holds. If they contain a list of setters, the team has built a second `setState` mechanism, only more cumbersome. ```mermaid sequenceDiagram participant V as View participant M as Middleware participant R as Reducer participant S as Store V->>M: dispatch(ORDER_SUBMITTED) Note over M: Listening point:
    logging, analytics, DevTools M->>R: action (unchanged) R->>S: new state S-->>V: notify + render ``` ## Middleware: listening in on the protocol If you take actions seriously as messages, you get a second capability for free that stays invisible in the container view: you can tap into the message stream. That’s exactly what middleware is – a function that sits between `dispatch` and the reducer and sees every message before it acquires meaning. ```js // analyticsMiddleware.js const analyticsMiddleware = store => next => action => { if (action.type.startsWith('ORDER_')) { trackEvent(action.type, action.payload); } return next(action); }; ``` The triple-nested signature takes some getting used to, but it’s simply applied currying – I took apart how such function chains come about a few weeks ago in [JavaScript Patterns That Stayed: Modules, Higher-Order Functions, Currying](https://www.mikebild.dev/en/blog/javascript-patterns-that-stayed/). More important than the form is the consequence: analytics doesn’t need a single call in a component. In the ordering project, the product analytics hang entirely on this one file. When a new metric was requested – how often a rejection follows a submission – that was a change in the middleware, not in thirty components. The same goes for logging in the error case: writing the last fifty actions into a ring buffer and attaching them to the error report costs twenty lines. In the end, the async question is a protocol question too. Whether `redux-thunk` for the simple cases or `redux-saga` and `redux-observable` when flows have to be orchestrated – all three are middleware, and all three eventually flow back into ordinary actions. The asynchronous part doesn’t change the language; it just speaks it with a delay. How push and pull data flows fundamentally differ is covered in [RxJS: Push and Pull](https://www.mikebild.dev/en/blog/rxjs-telling-push-and-pull-apart/) – Redux consistently lives on the push side. ## The limit: not every change deserves a message As useful as the protocol is, it has a price per message: a constant, an action creator, a reducer branch, and if in doubt a test. Only what is worth it should pay this price. Whether a dropdown is currently open, which tab is active, what is in an input field before it is submitted – that is local UI state, and it belongs in the component, in a plain `setState`. Nobody wants to read thirty `INPUT_CHANGED` between two domain events in the action log; the protocol gets noisy, and time travel turns into a slide show. Dan Abramov himself wrote this down clearly last year in “You Might Not Need Redux”, and the text is not a distancing but a price list: the benefits of Redux arise precisely from its constraints, so it only pays off where you actually cash in those benefits. My check questions before state moves into the store: - Do several components that are far apart in the tree read this state? - Does the change have a domain name that would explain something in a bug report? - Does anyone care about the history of these changes – support, analytics, debugging? Three times no means: component. React has always been able to handle local state itself, and the just-released React 16 hasn’t changed that – the new Fiber core renders differently, but `setState` stays `setState`. The two mechanisms don’t compete; they serve different questions. ```mermaid flowchart TD A[State comes into being] --> B{Do distant
    components read it?} B -- no --> L[Local:
    setState in the component] B -- yes --> C{Domain name?
    History relevant?} C -- no --> L C -- yes --> S[Store:
    action + reducer] ``` In the repository [introduction-react](https://github.com/MikeBild/introduction-react), in which I have been collecting React topics for talks and examples since the spring, the Redux part is deliberately small for exactly this reason: a manageable example app in which the message vocabulary stays limited to a handful of domain events. Not because more wouldn’t be possible – but because the difference between protocol and container is easier to see in a small, clean vocabulary than in a large, noisy one. ## What I take away from this Over time, I noticed that the teams who are happy with Redux and the ones who curse it aren’t using different libraries at all – they are using different protocols. The former have a vocabulary of domain events that you can read out loud; their action log reads like a running report of the application. The latter have setters in capital letters and wonder why the promised benefit fails to appear: the DevTools show noise, the tests check assignments, and there is nothing to discuss in review, because `SET_VALUE` contains no domain statement anyone could disagree with. That’s why I now consider the store an implementation detail and the protocol the real architectural decision. The three questions that make the difference have little to do with the library: Which events exist in this application? What are they called in the language of the domain? And who may trigger them? If you have answered these questions, Redux gives you traceability, testability and a shared language almost for free. If you skip them, you get a global state container with ceremony – and then you really wouldn’t have needed Redux. Should Redux be replaced by something else at some point, the exercise still remains valuable. A protocol of named, serializable change messages is not an invention of this library – networking has lived on it for decades, and so have event-driven systems on the server. Redux merely carried this discipline to a place where it used to be rare: right into the UI. ## Further reading - [MikeBild/introduction-react](https://github.com/MikeBild/introduction-react) – repository with React examples, including a Flux/Redux part and an example app - [Redux documentation: Motivation](https://redux.js.org/understanding/thinking-in-redux/motivation) – why mutation plus asynchrony is the real problem - [Dan Abramov: You Might Not Need Redux](https://medium.com/@dan_abramov/you-might-not-need-redux-be46360cf367) – the price list for the constraints, from the author himself - [React v16.0 release announcement](https://legacy.reactjs.org/blog/2017/09/26/react-v16.0.html) – the fresh Fiber core, which changes nothing about the data flow model --- # JavaScript Patterns That Stayed: Modules, Higher-Order Functions, Currying URL: https://www.mikebild.dev/en/blog/javascript-patterns-that-stayed/ Date: 2017-09-19 A pattern is not a library and not a framework feature. It is the shape in which code is arranged – and that sits one level below whatever framework currently sits on top. For us, only a few years lay between jQuery, Backbone, Angular 1, Angular 2 and React. The tools were swapped out; the arrangement underneath stayed remarkably constant. I pick out three of these arrangements here: the module pattern, higher-order functions and currying or partial application. They build on each other, and once you have taken them apart, you read modern JavaScript code with different eyes. I assume ES2015 as the baseline. The three patterns in one sentence each: - The module pattern encapsulates state and exposes only a deliberately chosen public API. - Higher-Order Functions treat functions as values – they take functions as arguments or return them. - Currying and partial application turn a generic function into specialized, preconfigured variants. ## Module pattern: two routes, one goal The oldest problem in browser JavaScript is the global namespace. In the past, every variable you did not deliberately encapsulate ended up on the `window` object, and two scripts could overwrite each other without noticing. The solution before ES6 was a convention, not a language feature: the Immediately Invoked Function Expression, IIFE for short. You wrap code in a function, call it immediately and use the resulting scope as a private space. What is declared inside stays inside – unless you deliberately return it as an object. This return of the public API is also called the Revealing Module Pattern. ```js const counterModule = (function () { let count = 0; // private, not accessible from outside return { increment() { return ++count; }, get() { return count; } }; })(); counterModule.increment(); // 1 counterModule.increment(); // 2 counterModule.get(); // 2 counterModule.count; // undefined – deliberately not exposed ``` The trick lies in the closure: the returned methods keep access to `count` even though the outer function finished long ago. From the outside, there is no way to set `count` directly. That is exactly what we wanted – encapsulation without language support, purely through scope and closure. Since ES2015, there are real modules in the language. Every file is its own module scope, nothing leaks to global automatically, and what should be visible from the outside you mark with `export`. Importing happens statically with `import`. The same example as an ES module: ```js // counter.js let count = 0; // module-private, only visible in this file export function increment() { return ++count; } export function get() { return count; } ``` ```js // app.js import { increment, get } from './counter.js'; increment(); // 1 increment(); // 2 get(); // 2 ``` Both pursue the same goal: private state and a clearly defined public API. The difference is the semantics. With the IIFE, encapsulation is a runtime construct based on functions and closures. With the ES module, it is part of the module system – tools can analyze the imports before execution and remove unused code. Imported bindings are also live and cannot be reassigned by the importer. Modules run implicitly in strict mode. ```mermaid graph LR A[IIFE + Closure] --> C[Encapsulation
    private state
    clear public API] B[ES6 import/export] --> C ``` An honest word about the state of things in 2017: Node.js does not yet support native ES modules in a stable way. There you still write CommonJS with `require` and `module.exports`; the experimental `--experimental-modules` flag has only just appeared with Node 8.5.0. In browsers, support is fresh – Chrome 61 and Safari 10.1 already handle `type="module"`, Firefox and Edge still behind a flag. In practice, in 2017 we therefore bundle with webpack or Rollup and let Babel translate the `import/export` syntax. That does not change the pattern: we think in modules, even if deployment still goes through a bundler. ## Higher-Order Functions: functions are values The second building block is JavaScript’s real strength, and most of us used it long before we had a name for it. In JavaScript, functions are first-class values: you can store them in variables, pass them as arguments and return them from other functions. A function that takes a function as an argument or returns a function is called a higher-order function. The best-known examples are the array methods `map`, `filter` and `reduce`. They have been available everywhere since ES5 (2009) and replace imperative loops with declarative transformations. Instead of describing how to iterate, you describe what happens to each element: ```js const numbers = [1, 2, 3, 4, 5]; const doubled = numbers.map(n => n * 2); // [2, 4, 6, 8, 10] const evens = numbers.filter(n => n % 2 === 0); // [2, 4] const sum = numbers.reduce((acc, n) => acc + n, 0); // 15 ``` Each of these methods is itself a higher-order function because it takes a callback. `map` calls the callback for each element and collects the return values in a new array. `filter` keeps only the elements for which the callback returns true. `reduce` folds the array into a single value by carrying an accumulator through all elements. The other half of the pattern – functions that return functions – is the key to everything that comes after. A function that produces a configured function is sometimes called a function factory: ```js const multiplyBy = factor => n => n * factor; const double = multiplyBy(2); const triple = multiplyBy(3); double(5); // 10 triple(5); // 15 [1, 2, 3].map(double); // [2, 4, 6] ``` `multiplyBy(2)` does not return a number but a new function that has remembered `factor` via closure. `double` and `triple` are specialized tools built from a single generic function. And because they are perfectly normal functions, you can pass them directly to `map`. This is exactly where higher-order functions interlock with the next pattern. ## Currying and partial application: from generic to specific Currying means turning a function with several arguments into a chain of unary functions. `f(a, b, c)` becomes `f(a)(b)(c)`. Each call takes exactly one argument and returns a function that waits for the next one – until all arguments are there and the result is computed. Again, this is implemented via closures. ```js const add = (a, b) => a + b; // ordinary, two arguments at once const curriedAdd = a => b => a + b; // curried, unary chain curriedAdd(10)(5); // 15 const add10 = curriedAdd(10); // specialized function, waits for b add10(5); // 15 add10(90); // 100 ``` Closely related, but not the same, is partial application. Here you fix some arguments of a function and get a new function with fewer parameters. The difference from currying: partial application does not force you into unary chains but simply fixes a few arguments up front. In JavaScript, you can get this without any helpers of your own via `Function.prototype.bind`, which has also been available since ES5: ```js const add = (a, b) => a + b; // bind fixes this (here null) and the leading arguments const add10 = add.bind(null, 10); add10(5); // 15 add10(90); // 100 ``` The benefit shows as soon as you compose such specialized functions. From a small stock of generic building blocks, you build tailored variants and plug them together. An example that shows how naturally such a building block fits into the array methods – `add10` from the `bind` step goes straight into `map`: ```js const numbers = [1, 2, 3, 4]; const shifted = numbers.map(add10); // [11, 12, 13, 14] const total = shifted.reduce((sum, n) => sum + n, 0); // 50 ``` The arc from generic to specialized function reads well as a flow: ```mermaid graph LR A["add(a, b)
    generic, two arguments"] --> B["curriedAdd(10)
    or add.bind(null, 10)"] B --> C["add10(n)
    specialized, one argument"] ``` And that is exactly why these patterns have stayed for years: they are the foundation of modern utility libraries. Ramda (since 2013) and `lodash/fp` ship many functions curried and with a “data-last” signature – the data comes last so that you can fix the configuration up front and conveniently compose the resulting building blocks. Once you understand the principle behind `multiplyBy` and `curriedAdd`, you also understand why these libraries are built the way they are. ## Three pitfalls I see again and again As elegant as the patterns are, teams reliably stumble over the same spots. I want to name three of them because they get expensive in real codebases. The first concerns the `this` binding with higher-order functions. If you pass an object method directly as a callback, the receiver is lost. The method is called without its object, and `this` is then undefined or the global object: ```js const counter = { count: 0, increment() { this.count += 1; // this depends on HOW it is called } }; [1, 2, 3].forEach(counter.increment); // TypeError, i.e. counter.count stays 0 – this is not counter ``` The solution in 2017 is clear-cut. You bind `this` with `bind`, wrap the call in an arrow function that takes its `this` lexically from the surrounding context, or use the `thisArg` parameter that `map`, `filter` and `forEach` offer as a second argument: ```js [1, 2, 3].forEach(counter.increment.bind(counter)); [1, 2, 3].forEach(() => counter.increment()); [1, 2, 3].forEach(counter.increment, counter); // thisArg ``` Arrow functions are the sharpest tool here because they do not bring their own `this` at all – they inherit it from the surrounding scope. In many cases, that makes this class of error disappear entirely. The second pitfall is overusing currying. Deeply nested `f(a)(b)(c)(d)` chains look neat in a blog post, but in team code they cost readability. They are harder to debug, the stack traces become confusing, and whoever reads the code six months later has to unfold the chain in their head again. Currying pays off where specialization or composition brings a concrete advantage. Where it only looks functional, it costs more than it brings. The third concerns `reduce` without an initial value. If you leave out the `initialValue` argument, `reduce` takes the first array element as the initial value – and throws a TypeError on an empty array. On top of that, the semantics of the accumulator are then tied to the element type, which quickly leads to subtle bugs: ```js [].reduce((sum, n) => sum + n); // TypeError: Reduce of empty array [].reduce((sum, n) => sum + n, 0); // 0 – correct, because initial value set ``` For sums, building lists and other folds with a neutral element, I therefore set the initial value explicitly. Where there is no neutral element in domain terms, I prefer to handle the empty case deliberately instead of inventing an artificial initial value. ## Conclusion When I put the three patterns side by side, a common line stands out. The module pattern encapsulates state, whether via IIFE and closure or via ES module – the goal stays the same, only the level moves from convention into the language. Higher-order functions turn functions into values and replace loops with transformations. Currying and partial application build specialized variants from Generic Functions that can be composed. The syntax shifted between ES5 and ES6; the principle behind it did not. That is exactly what I have learned over the years: patterns beat syntax. The language features will keep changing – years lie between the first IIFE and today’s `import` – but encapsulation, functions as values and specialization through preconfiguration have stayed stable. If you master this core, you do not have to start from scratch at the next framework change. You recognize the old acquaintances in new clothes, and in the long run that is worth more than any current library version. ## Further reading - [ES modules guide (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) - [export (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export) and [import (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) - [IIFE (MDN Glossary)](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) and [Closures (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures) - [Array.prototype.map (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map), [filter (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter), [reduce (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) - [Function.prototype.bind (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind) and [Arrow functions (MDN)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) - [ECMAScript 2015 (ES6) Specification](https://www.ecma-international.org/ecma-262/6.0/) - [Eloquent JavaScript – Higher-Order Functions](https://eloquentjavascript.net/05_higher_order.html) --- # WebSockets Are Not Always the Answer URL: https://www.mikebild.dev/en/blog/websockets-are-not-always-the-answer/ Date: 2017-09-12 # WebSockets Are Not Always the Answer A dashboard that shows new orders. A notification when the build has finished. A progress bar for an import that takes twenty minutes. Three typical “real-time” requirements – and in all three cases, the data flows in one direction only: from the server to the client. Still, the first technical answer is surprisingly often: WebSockets, socket.io, a persistent bidirectional connection. The reflex “real-time equals WebSocket” runs deep, and it is understandable. WebSockets are the most prominent tool on the shelf; every other tutorial series builds a chat with them. But a chat is bidirectional. An order dashboard is not. If you fire up the heavy machinery for pure server-to-client push, you pay for capabilities you never use – and the price is not zero. ## What “real-time” really means in the requirements If you seriously take the requirement apart, it rarely says “client and server continuously exchange messages in both directions”. It says: the user should see something as soon as it happens, without pressing F5. That is notification, not conversation. The client still talks to the server through ordinary requests – it clicks, it saves, it loads more. The only new thing is that the server may say something on its own. Incidentally, for some of these cases, simple polling is even enough. A progress bar that sends a GET every two seconds is not an elegant solution, but it is one that everyone on the team understands, that every cache and every proxy knows, and that can be thrown away and replaced in a minute. So the question is not just “WebSocket or not”, but how much machinery the requirement justifies in the first place. This became clear to me in a shop project this spring. The team had built socket.io into an order dashboard, and the connection itself was never the problem. The problem was everything around it: after every deployment, clients hung on dead connections until the homegrown reconnect kicked in. The load balancer needed special treatment for the protocol upgrade. And when a browser was offline for thirty seconds, exactly the orders from those thirty seconds were missing – nobody had built resuming from the last known state, simply because the protocol doesn’t provide it. ## The price of a WebSocket connection A WebSocket starts as an HTTP request, but leaves HTTP after the upgrade handshake and becomes its own protocol (RFC 6455) on a raw TCP connection. From that moment on, none of the infrastructure and semantics that the HTTP world brings along apply anymore. Concretely, you buy into: - Connection state management on the server: Who is connected, since when, with which session? - Your own heartbeats, because dead TCP connections don’t reveal themselves – ping/pong is manual work or a library feature, but always part of your own responsibility. - Reconnect logic in the client, including backoff and the question of what was missed during the silence. - Special cases in the infrastructure: proxies, load balancers and corporate firewalls that don’t know the upgrade or cut long silent connections. None of this is unsolvable. Libraries like socket.io take a lot off your hands; that is exactly why they exist. But it remains complexity that has to be operated, monitored and understood when something goes wrong. For a channel that only sends in one direction, that is a bad trade. ```javascript const WebSocket = require('ws') const server = new WebSocket.Server({ port: 8080 }) server.on('connection', socket => { socket.isAlive = true socket.on('pong', () => { socket.isAlive = true }) }) // dead connections are not detected for free – ping/pong is on us setInterval(() => { server.clients.forEach(socket => { if (!socket.isAlive) return socket.terminate() socket.isAlive = false socket.ping() }) }, 30000) ``` That is just the heartbeat. Reconnect, message buffers and resuming after an interruption are a different story – and in most projects I have seen, surprisingly little of that story has been written. ## Server-Sent Events: push over ordinary HTTP Server-Sent Events are the unspectacular counterpart: a perfectly normal HTTP GET request whose response never ends. The server keeps the connection open and writes events into it as text; the browser consumes them through the `EventSource` API. No protocol switch, no upgrade, no new vocabulary for the infrastructure. An SSE endpoint in Express is a few lines: ```javascript const express = require('express') const app = express() let nextEventId = 0 const eventLog = [] const clients = [] app.get('/events', (req, res) => { res.set({ 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' }) res.flushHeaders() // replay everything the client missed while it was offline const lastEventId = Number(req.get('Last-Event-ID') || 0) eventLog .filter(event => event.id > lastEventId) .forEach(event => res.write(toMessage(event))) clients.push(res) req.on('close', () => clients.splice(clients.indexOf(res), 1)) }) function broadcast(data) { const event = { id: ++nextEventId, data } eventLog.push(event) clients.forEach(res => res.write(toMessage(event))) } function toMessage({ id, data }) { return `id: ${id}\ndata: ${JSON.stringify(data)}\n\n` } app.listen(3000) ``` The client is even shorter – and that is the real point: ```javascript const source = new EventSource('/events') source.onmessage = event => { const order = JSON.parse(event.data) renderOrder(order) } // no reconnect code here: EventSource reconnects on its own // and sends the Last-Event-ID header with every new attempt ``` The comment in the client code is not a claim but the specification. If the connection drops, `EventSource` reconnects on its own – the server can even set the waiting time via the `retry:` field in the stream. And when reconnecting, the browser automatically sends the `Last-Event-ID` header with the ID of the last event received. The server can use it to continue exactly where the client left off. The very feature that was so painfully missing in the shop project is part of the protocol here. ```mermaid sequenceDiagram participant B as Browser (EventSource) participant S as Server (Express) B->>S: GET /events S-->>B: Event 41 (order A-1041) S-->>B: Event 42 (order A-1042) Note over B,S: Connection drops
    (deployment, dead zone, proxy timeout) B->>S: GET /events with header Last-Event-ID 42 S-->>B: Event 43 (everything since 42 is delivered) ``` On top of that comes an advantage you only learn to appreciate in operations: the entire channel is ordinary HTTP. Load balancers route it like any other request, authentication runs over the same headers and cookies as the rest of the application, and debugging needs no special tooling: ```bash $ curl -N http://localhost:3000/events id: 1 data: {"orderId":"A-1041","total":89.9} id: 2 data: {"orderId":"A-1042","total":24.5} ``` If you have ever tried to go through a WebSocket frame capture together with a colleague from operations, you know what this one curl call is worth. The stream is readable text, every event carries its ID, and the browser sees the same output. ## Where SSE honestly hits its limits So that this doesn’t turn into an advertisement: Server-Sent Events have limits, and they belong on the table before the decision is made. The channel is strictly unidirectional. If the client wants to say something, it does so through a normal POST – for forms, clicks and commands, that is perfectly fine and the natural way anyway; for a high-frequency back channel, it isn’t. Second: Internet Explorer and Edge still don’t support `EventSource` to this day; there you need a polyfill. The available polyfills work decently, but it is one more building block you have to plan for. Third, under HTTP/1.1, SSE shares the browser limit of roughly six connections per host – if you open several streams per tab, you run into it. Under HTTP/2, this eases considerably, because all streams run over a single multiplexed connection. And finally: buffering proxies occasionally have to be convinced by configuration to pass the stream through immediately instead of collecting it – but that is one line of nginx configuration, not an architecture problem. ## GraphQL subscriptions: the same reflex, one floor up It gets interesting when the reflex moves into frameworks. In the Apollo ecosystem, GraphQL subscriptions run over `subscriptions-transport-ws` by default, that is, over WebSockets. Yet subscriptions are the textbook example of unidirectional data flow: the client registers once what it is interested in, and from then on only the server talks. Queries and mutations go over HTTP anyway. The bidirectional capability of the transport is used for a single handshake – after that it lies idle, while its operating costs remain. This kept me busy enough this spring to try it out: `subscriptions-transport-sse` is my API-compatible SSE variant of this transport, created in my GitHub organization CodeCommission. On the server side, the `SubscriptionServer` attaches to an Express app and the `SubscriptionManager` from `graphql-subscriptions`; on the client side, the `SubscriptionClient` is attached to Apollo’s network interface as usual: ```javascript import { SubscriptionClient, addGraphQLSubscriptions } from 'subscriptions-transport-sse' const httpClient = createNetworkInterface({ uri: 'https://example.com/graphql' }) const sseClient = new SubscriptionClient('https://example.com/subscriptions') const apolloClient = new ApolloClient({ networkInterface: addGraphQLSubscriptions(httpClient, sseClient) }) apolloClient.subscribeToMore({ document: gql` subscription onOrderCreated { orderCreated { id total } }`, updateQuery: (prev, { subscriptionData }) => { // merge the new order into the store and return the new state } }) ``` From the application’s point of view, nothing changes – the same subscription, the same `subscribeToMore`. Only the transport underneath is now ordinary HTTP with everything described above: automatic reconnect, `Last-Event-ID`, curl debugging. As a practical test, I built a small presence list with it in April – who is online right now, React and Apollo in the frontend, Node in the backend, events over SSE. Both are deliberately lean projects, more evidence than product. I wanted to show that “GraphQL subscriptions need WebSockets” is a convention, not a necessity. ## When WebSockets are the right answer After so much counterargument, the other side, because it exists. WebSockets are the right choice when both sides actually send continuously and with low latency: - Collaborative editing, where keystrokes and operations from both sides converge - Cursor positions and presence signals that flow in both directions many times per second - Games and simulations in which every round reconciles client input against server state - Frontends where the overhead of a separate POST per client message really matters The common denominator: the back channel is not an occasional command but a stream. Then the protocol pays off, and then the operational complexity is justified too – after all, you use what you pay for. The deciding question is therefore not “Do we need real-time?” but “Where does the data flow, and how often?”. ```mermaid flowchart TD A[Requirement: real-time] --> B{Does data flow continuously
    in both directions?} B -- no --> C[Server-Sent Events
    plus normal HTTP requests] B -- yes --> D{Is the back channel a stream
    with latency requirements?} D -- no --> C D -- yes --> E[WebSockets –
    plan for operating costs] ``` If you answer these two questions honestly, in my experience you end up on the left side of the diagram in the vast majority of cases. The order dashboard, the build monitor, the import progress, the notification bell in the top right of the application – all cases for SSE. The editor with your colleagues’ live cursors is the rare, genuine case for the right side. ## The bottom line From the shop project and the two SSE experiments, I take away one observation above all: the costs of a technology rarely sit where its strengths are advertised – they sit in operations, in debugging and in the failure cases the protocol doesn’t cover on its own. WebSockets can do something SSE can’t, and if you need that something, they are unrivaled. But “real-time” in the requirements is not yet evidence that you need it. Most of the time, a server just wants to tell you something, and for that, an HTTP request that never ends is enough – with built-in reconnect, built-in resuming and a debugging experience that consists of a single curl call. The more boring technology wins here not despite but because of its boredom. It has fewer moving parts – and every moving part you never build in can’t break at three in the morning. ## Further reading - [subscriptions-transport-sse on GitHub](https://github.com/CodeCommission/subscriptions-transport-sse) – GraphQL subscriptions over Server-Sent Events, API-compatible with subscriptions-transport-ws - [graphql-subscriptions-sse-presence-list on GitHub](https://github.com/MikeBild/graphql-subscriptions-sse-presence-list) – presence list example with React, Apollo and SSE - [Server-Sent Events in the HTML specification (WHATWG)](https://html.spec.whatwg.org/multipage/server-sent-events.html) - [EventSource API on MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) - [RFC 6455 – The WebSocket Protocol](https://tools.ietf.org/html/rfc6455) --- # KnockoutJS: Fine-Grained Reactivity with Observables and Computed URL: https://www.mikebild.dev/en/blog/knockoutjs-fine-grained-reactivity-with-observables/ Date: 2017-08-22 Three functions are enough to keep an entire UI reactive in KnockoutJS: `ko.observable`, `ko.observableArray` and `ko.computed`. None of them takes a dependency list. Still, after the first run, Knockout knows which value is attached to which place in the DOM. It reads the dependencies from the actual program flow. **Editorial note (July 2026):** This post explains KnockoutJS as a historical forerunner of today’s fine-grained reactivity. I am not recommending that you build a new frontend on Knockout in 2026. What has remained interesting is the mechanism: capturing dependencies on read and updating only the affected places. Knockout declaratively couples the DOM to a ViewModel through bindings such as `text`, `value`, `foreach` and `click`. Here I look one level deeper: How does Knockout notice that something has changed, and how does it figure out which parts of the UI are affected? The core of this mechanism is called observables and computed. ## An observable is a function – not a property The first mental leap you have to make with Knockout is this: in KnockoutJS, an observable is not a property but a function. More precisely, a function that is getter and setter at the same time. If I call it without an argument, I read the value. If I call it with an argument, I write the value – and Knockout notifies everyone interested in that value. ```js var name = ko.observable('Bob'); name(); // read -> 'Bob' name('Mary'); // write -> sets the value and notifies subscribers name(); // read -> 'Mary' ``` That is the whole trick. No `Object.defineProperty`, no proxy, no compiler magic. Just a function that remembers who read it and who wants to be notified. Writing is chainable, by the way, because the setter returns the ViewModel: ```js viewModel.name('Mary').age(50); ``` For lists, there is a matching variant. A `ko.observableArray` behaves like an observable on read – `arr()` returns the underlying array – but it also comes with mutation methods that trigger tracking: ```js var todos = ko.observableArray([]); todos(); // read -> the current array todos.push({ title: 'Buy milk' }); todos.remove(someItem); todos.removeAll(); ``` The first pitfall is already lurking here, and I will come back to it later: these `push`, `remove` and `splice` methods are Knockout’s own wrappers. They are what triggers a notification. If you write `todos().push(x)` instead, you bypass them on the raw array, and Knockout notices nothing of the change. ## Computed derives – and automatically tracks what it reads Now comes the really interesting part. You rarely want to just store a value and output it again. Most of the time you need derived values: the total of a shopping cart, the full name from first and last name, the number of open tasks. That is what `ko.computed` is for. ```js var firstName = ko.observable('Mike'); var lastName = ko.observable('Bild'); var fullName = ko.computed(function () { return firstName() + ' ' + lastName(); }); fullName(); // 'Mike Bild' firstName('Michael'); fullName(); // 'Michael Bild' ``` And here something happens that I looked at twice myself when I first encountered Knockout, because it is the linchpin of the whole model. Nowhere did I tell Knockout that `fullName` depends on `firstName` and `lastName`. I declared no dependency list. Knockout figured that out by itself. How? When the evaluator function runs for the first time, Knockout observes which observables are actually read. At that moment, `firstName()` and `lastName()` register themselves, so to speak: “This computed is reading me right now.” Knockout then registers a subscription. The dependency graph thus emerges at runtime, purely through execution – nothing is declared. This is the fine-grained, automatic dependency tracking that defines Knockout. The evaluator does not run just once. It is executed once immediately on creation, and after that again every time one of the dependencies it read changes. The second part is important: on every re-evaluation, Knockout determines the dependencies afresh. That allows dynamic dependencies behind conditions: ```js var showFullName = ko.observable(true); var displayName = ko.computed(function () { if (showFullName()) { return firstName() + ' ' + lastName(); } return firstName(); }); ``` As long as `showFullName` is `true`, `displayName` depends on three observables. If it is `false`, `lastName()` is no longer read at all – and Knockout automatically removes this dependency again on the next run. A change to `lastName` then no longer triggers a re-evaluation. That is exactly what “dynamic” means: the graph adapts to the actual control flow. Drawn as a graph, this relationship looks like this: ```mermaid graph LR A[firstName
    observable] --> C[fullName
    computed] B[lastName
    observable] --> C C --> D[text binding
    DOM] ``` The arrows mean “is read by and notifies.” If `firstName` changes, the notification travels along the edge to `fullName`, which recalculates, and from there on to the text binding in the DOM. Only this one path becomes active. Nothing else in the tree is touched. For the toolbox, this small trio is enough for now: - `ko.observable(value)` – a single reactive value, read with `obs()`, written with `obs(newValue)`. - `ko.observableArray([...])` – a reactive list with mutation methods such as `push`, `remove` and `splice` that notify bindings. - `ko.computed(fn)` – a derived value that automatically tracks which observables it reads and recalculates when they change. ## From the ViewModel into the DOM: the todos app So this does not stay abstract, here is a small todos application. It shows all three building blocks working together. ```js function TodoViewModel() { var self = this; self.todos = ko.observableArray([]); self.newTodo = ko.observable(''); self.remaining = ko.computed(function () { return self.todos().filter(function (t) { return !t.done(); }).length; }); self.addTodo = function () { self.todos.push({ title: self.newTodo(), done: ko.observable(false) }); self.newTodo(''); }; } ko.applyBindings(new TodoViewModel()); ``` A few things here are built this way on purpose. `self.todos` is an `observableArray`, `self.newTodo` a simple observable for the input field. `self.remaining` is a computed that counts the tasks still open. It reads `self.todos()` and, per entry, `t.done()` – which means it depends both on the list and on every single `done` observable. If you add a todo or check one off, `remaining` recalculates by itself. Notice that every single todo gets its own `done: ko.observable(false)`. Only this way is the done status reactive per entry. A plain `done: false` would be a dead value with nothing to observe. The view declaratively couples the ViewModel to the DOM. Here is the relevant excerpt: ```html
    remaining ``` `ko.applyBindings` activates these connections once at startup. From then on, everything runs through tracking: when the user types into the field, the `value` binding updates `newTodo`. A click on the button calls `addTodo`, which changes the list via `push`. This change notifies the `foreach` binding (new list entry) and the computed `remaining` (recalculation), which in turn updates the `text` binding in the ``. Each of these updates hits exactly the place that is affected. ## Why targeted tracking is a different model At this point, it pays to draw the distinction that gives the whole thing its shape. There is a second, very widespread approach to the same problem: Virtual DOM diffing, as you know it from React, for example. There, on every change you build a new virtual tree, compare it with the old one and apply the difference to the real DOM. The framework does not know up front which data change affects which place in the DOM – it computes the difference afterward. Knockout goes the opposite way. Through fine-grained tracking, it knows exactly, per observable, which computed and which bindings depend on it. It does not have to compare anything. When a value changes, Knockout simply follows the registered edges of the dependency graph and updates only the DOM places attached to them. No tree comparison, no re-rendering of subtrees that have not changed at all. The sequence of a single change looks like this: ```mermaid sequenceDiagram participant U as User participant O as observable participant C as computed participant D as DOM binding U->>O: obs(newValue) O->>C: notify subscriber C->>C: re-evaluate C->>D: targeted text update ``` Both models have their place, and I do not want to declare either one the winner. But once you have understood the difference at this point, you also understand why the two worlds feel so different. Knockout’s approach is immediately comprehensible, because you can almost see the graph in the code. The price for that is discipline: you have to work consistently with observables, or the graph breaks at some point. ## Pitfalls from practice It is exactly this discipline where the graph tends to break, and at three recurring places. All three have cost me hours in my own projects, because they fail silently. The classic is forgotten parentheses. An observable is a function. If you use it without parentheses, you are working with the function itself instead of its value: ```js // wrong: todo.done is the function itself, so always truthy if (todo.done) { // this branch ALWAYS runs } // correct: todo.done() reads the value if (todo.done()) { // ... } ``` The bug is treacherous because it throws no error. A function is truthy, so the condition simply always comes out the same. You then search for a long time in the wrong place. Reading always takes parentheses, without exception. The second pitfall is the native array methods. I hinted at it above: ```js // wrong: mutates the raw array without notification todos().push(newItem); // correct: KO wrapper, notifies dependent bindings todos.push(newItem); ``` `todos()` returns the underlying JavaScript array. Its native `push` does change the content, but Knockout learns nothing about it – the `foreach` binding stays as it was. The KO wrapper `todos.push`, on the other hand, triggers tracking. The only difference is the parentheses before `.push`, which once again makes the bug unpleasantly subtle. The third concerns the `this` context in computed. If the evaluator wants to access the ViewModel, `this` really has to point to the ViewModel: ```js function ViewModel() { this.price = ko.observable(10); this.count = ko.observable(3); // wrong: this does not reliably point to the ViewModel here this.total = ko.computed(function () { return this.price() * this.count(); // this.price is undefined }); } ``` Knockout calls the evaluator in a different context, so `this` does not point to the instance. There are two established ways out. Either you pass the context as a second argument: ```js this.total = ko.computed(function () { return this.price() * this.count(); }, this); // second argument binds this ``` Or you use the `self` pattern I already used in the todos example: ```js function ViewModel() { var self = this; self.price = ko.observable(10); self.count = ko.observable(3); self.total = ko.computed(function () { return self.price() * self.count(); }); } ``` In my projects I prefer the `self` pattern, because it works across the board – in event handlers and callbacks too, not just in computed. One pattern for everything is easier to remember than a special rule for each case. In passing, it is worth mentioning `ko.pureComputed`, which has been available since KO 3.2. It behaves like a normal computed but “sleeps” as long as nobody subscribes to it, which saves recalculations for pure derivations without side effects. For getting started, `ko.computed` is enough; as soon as you notice that a purely deriving computed recalculates unnecessarily often, `pureComputed` is the obvious improvement. ## Conclusion Once you have understood the core of KnockoutJS, you are basically holding just three building blocks: observables as get/set functions, observableArrays for reactive lists and computed for derived values. The real elegance lies between these building blocks: in automatic dependency tracking. Knockout observes at runtime which observables a computed reads, builds a dependency graph from that and, on every change, updates only the affected places – determined afresh on every run, so that dynamic dependencies behind conditions are mapped cleanly too. This model deliberately runs counter to Virtual DOM diffing: instead of comparing trees, Knockout follows the edges it registered itself while reading. That makes the behavior immediately comprehensible, but it demands discipline – parentheses for reading, KO wrappers for mutating lists, the right `this` context in computed. Once these three reflexes are internalized, working with Knockout becomes surprisingly calm. You describe what a value depends on, and the framework takes care of the rest. This clarity is exactly why I still consider Knockout’s reactivity model one of the best entry points for understanding what really happens behind reactive UIs. ## Further reading - [Observables – KnockoutJS Documentation](https://knockoutjs.com/documentation/observables.html) - [Computed Observables – KnockoutJS Documentation](https://knockoutjs.com/documentation/computedObservables.html) - [How Dependency Tracking Works – KnockoutJS Documentation](https://knockoutjs.com/documentation/computed-dependency-tracking.html) - [Observable Arrays – KnockoutJS Documentation](https://knockoutjs.com/documentation/observableArrays.html) - [Pure Computed Observables – KnockoutJS Documentation](https://knockoutjs.com/documentation/computed-pure.html) --- # PWA Weather: Offline Is a Feature URL: https://www.mikebild.dev/en/blog/pwa-weather-offline-is-a-feature/ Date: 2017-08-12 # PWA Weather: Offline Is a Feature On the subway between two stations, no signal. The weather app opens, briefly shows a loading spinner and then: nothing. A white screen. And yet this morning’s weather would have been perfectly fine – the question was whether to take the umbrella, not whether it’s 21.3 or 21.4 degrees this minute. The app had even loaded this data before. It just threw it away, because nobody decided that it’s worth anything without a network. This white screen is not a technical defect. It is the result of a non-decision. Somewhere in the backlog, “offline support” was probably listed as a technical nice-to-have, behind the next feature and the redesign after that. That is exactly what I consider the mistake in thinking: offline is not an add-on you bolt onto a finished app later. Offline is a feature with product questions – what should work without a network, what explicitly should not, and how honestly the UI shows the state of the data. ## A small demo as a test bench To play this through for myself, I created a small repository in April of this year: [pwa-weather-demo](https://github.com/MikeBild/pwa-weather-demo). It is deliberately not a product but a rebuild exercise following Google’s tutorial “Your First Progressive Web App” – one weather card per city, a public weather API behind it, a service worker in front. Locally, the whole thing starts with a simple `http-server`; it needs no more infrastructure than that. The value isn’t in the feature set but in the fact that a manageable example lets you touch every decision one at a time. And there are more decisions than the word “caching” suggests. While working through it, I noticed that the real work isn’t in the service worker code. You can write that in an afternoon. The work lies in the question of what answer the app owes a person without a network connection. ## Offline is a product question, not a cache option For the weather app, my answer looks like this: - The most recently loaded weather for the saved cities is shown – always, immediately, even without a network. - The UI itself (layout, icons, fonts, logic) loads completely from the local cache. - Searching for new places doesn’t work offline – and says so, instead of letting a spinner turn. - Every weather card shown carries a timestamp: “Updated 2 hours ago” instead of silently old data. The third point matters to me. It would be technically possible to cache search results too and show something offline. But a place search against a two-day-old cache doesn’t deliver a search; it delivers a dummy. Not everything that can be cached should be cached. The line runs along the question of whether an outdated answer is still an honest answer: this morning’s weather is honest, clearly dated information. A search result from the day before yesterday is not. The fourth point is the second half of the same decision. If you show old data without marking it as old, your interface is lying. A small timestamp turns the same record from potential misinformation into useful information. It costs one line of UI and a date – and it’s the difference between “the app shows something” and “the app tells me what it knows and how sure it is.” ## The service worker: a proxy with a lifecycle Technically, all of this hinges on the service worker – a script that the browser runs separately from the page and that sits as a programmable proxy between the app and the network. Every request from the page goes through its `fetch` handler, and there, code instead of chance decides whether a response comes from the network, from the cache or from a combination of both. If you work with it for the first time, you stumble less over the API than over the lifecycle. A service worker is registered, installed, waits if necessary for the old version to end and only then takes control of the page: ```mermaid flowchart LR A[register] --> B[install
    precache the app shell] B --> C[waiting
    old version still running] C --> D[activate
    clean up old caches] D --> E[fetch
    control requests] ``` The registration itself is unspectacular and belongs at the end of the app startup: ```js // app.js if ('serviceWorker' in navigator) { navigator.serviceWorker .register('/service-worker.js') .then(function (registration) { console.log('service worker registered, scope:', registration.scope); }) .catch(function (error) { console.error('service worker registration failed', error); }); } ``` The `if` is not a formality but part of the architecture: in browsers without service workers, the app simply keeps running as a normal website. More on that later, because in 2017 this case is anything but exotic. Two quirks of the lifecycle actually cost me time in the demo. First: by default, an updated service worker only takes over once all tabs of the old version are closed – if you just reload during development and wonder why the new code doesn’t apply, you’re fighting `waiting`, not a bug. Second: the `activate` step is the right place to delete old cache versions. If you skip it, you accumulate another cache with every deployment and wonder months later about the storage usage. ## App shell: the frame always comes from the cache The first cache decision concerns the app shell – everything the application needs for display before even a single byte of weather data is there: HTML, CSS, JavaScript, icons. These files only change with a deployment, so they are put into the cache completely once during `install` (precache) and always served from there afterward: ```js // service-worker.js var SHELL_CACHE = 'weather-shell-v1'; var DATA_CACHE = 'weather-data-v1'; var SHELL_FILES = [ '/', '/index.html', '/styles/app.css', '/scripts/app.js', '/images/icons/icon-192.png' ]; self.addEventListener('install', function (event) { event.waitUntil( caches.open(SHELL_CACHE).then(function (cache) { return cache.addAll(SHELL_FILES); }) ); }); self.addEventListener('activate', function (event) { event.waitUntil( caches.keys().then(function (keys) { return Promise.all( keys .filter(function (key) { return key !== SHELL_CACHE && key !== DATA_CACHE; }) .map(function (key) { return caches.delete(key); }) ); }) ); }); ``` The version number in the cache name is the deployment concept in its simplest form: new shell, new name, old caches get thrown out on `activate`. Tools like `sw-precache` generate this part from the build, and Workbox has just been released as a fresh successor that brings the common strategies as a library. For the demo, I deliberately wrote it by hand – not out of principle, but because you should only leave a strategy to a generator with a clear conscience once you’ve formulated it yourself. ## Two kinds of data, two strategies The more interesting decision happens in the `fetch` handler, because the app shell and the weather data need opposite strategies. The shell should arrive as fast as possible and may well be one deployment cycle old: cache first. The weather data should be as fresh as possible, and the cache is just the safety net for the subway moment: network first, with the last known response as a fallback. ```mermaid flowchart TD R[fetch event] --> Q{Path starts with
    /api/weather?} Q -- yes --> N[Network first] N -- response ok --> C1[Copy into weather-data-v1
    response to the app] N -- no network --> C2[last known response
    from the cache] Q -- no --> S[Cache first:
    app shell] S -- hit --> C3[serve immediately] S -- no hit --> C4[pass through to the network] ``` In code, this switch looks like this: ```js self.addEventListener('fetch', function (event) { var url = new URL(event.request.url); if (url.pathname.indexOf('/api/weather') === 0) { // network first, cached data as offline fallback event.respondWith( fetch(event.request) .then(function (response) { var copy = response.clone(); caches.open(DATA_CACHE).then(function (cache) { cache.put(event.request, copy); }); return response; }) .catch(function () { return caches.match(event.request); }) ); return; } // app shell: cache first, network as fallback event.respondWith( caches.match(event.request).then(function (cached) { return cached || fetch(event.request); }) ); }); ``` An alternative for the data route would be stale-while-revalidate: deliver the cached response immediately and fetch the fresh one in the background in parallel, which is then ready for the next render. For a weather app, that’s a legitimate choice – the display appears instantly, and the update trickles in afterward. In the demo, I still chose network-first, because with weather data the fresh response deserves priority as long as the network is there. The point is not which of the two strategies is “right.” The point is that it’s a choice with visible consequences – and that it’s made per route, not across the board for the whole app. Jake Archibald’s Offline Cookbook spells out these patterns one by one and has been my reference for them for years. ## The age of the data belongs in the UI So that “showing old data” doesn’t turn into quietly slipping it in, the app has to know how old a response is. Conveniently, this information is already in the cached response – the `Date` header of the original server response is stored with it: ```js // show data age when rendering a cached response caches.match('/api/weather?city=berlin').then(function (cached) { if (!cached) { return; } var fetchedAt = new Date(cached.headers.get('date')); var ageInMinutes = Math.round((Date.now() - fetchedAt.getTime()) / 60000); showLastUpdated(ageInMinutes); // "Stand: vor 120 Minuten" }); ``` That’s ten lines, and they change the character of the app. “Why is it showing me sunshine when it’s raining outside” becomes “ah, that’s the state from this morning.” In a project review, I would weigh these ten lines higher than the entire cache logic underneath – the cache logic decides whether something is shown; these lines decide whether you can trust what’s shown. ## Manifest, HTTPS and the home screen Besides the service worker, two more building blocks belong to a PWA. The web app manifest describes how the app behaves when it lands on the home screen: ```json { "name": "PWA Weather", "short_name": "Weather", "start_url": "/index.html", "display": "standalone", "background_color": "#3f51b5", "theme_color": "#3f51b5", "icons": [ { "src": "images/icons/icon-192.png", "sizes": "192x192", "type": "image/png" } ] } ``` With a manifest plus a registered service worker plus repeated use, Chrome on Android offers “Add to Home screen” on its own – the app then starts without browser chrome, with its own icon, and feels surprisingly like an installed application. Lighthouse checks whether a page meets the criteria; the PWA audit reliably complains about missing icons, missing offline behavior of the start route or missing HTTPS. HTTPS is not a recommendation here but a requirement: browsers only register service workers over secure connections (with `localhost` as the development exception). And that’s a good thing – you don’t want to deliver a script that may intercept and answer every request of a domain over a connection that can be tampered with. ## The honest limit: Safari Now the part that comes up suspiciously quietly in many PWA articles this year: Safari has no service worker. Neither on the Mac nor – and this weighs more – on iOS. Chrome, Firefox and Opera support the API, Microsoft Edge is working on it, and on the WebKit status board the entry has at least recently moved to “In Development.” But as of today, August 2017, a PWA on an iPhone is simply a normal website: no offline cache, no intercepting of requests, no install banner. That’s no reason to give up on it – but it absolutely belongs in the product decision, not in a footnote. For the weather demo, this concretely means: the app has to work fully without a service worker, just without the offline comfort. The service worker is an enhancement layer (Progressive Enhancement in the original sense of the term), not a prerequisite. If you build your app so that it breaks without a service worker, you have nothing at all on iOS. If you build it so that the service worker adds behavior instead of carrying it, you have a decent website on iOS and an app on Android that survives the subway moment. Depending on the target audience, this shifts the calculation considerably. With an audience with a high iOS share, the PWA effort today mainly buys you better load times through the shell cache in Chrome and Firefox – not nothing, but a different promise than “works offline.” This calculation should be openly on the table in the team before anyone writes “offline-capable” on a slide. ## Bottom line The technology behind the demo is manageable: a lifecycle, two cache strategies, a manifest, HTTPS. What sticks is something else. The white screen on the subway doesn’t happen because caching is hard – it happens because “offline” was never treated as a feature, with the same questions as any other feature: What exactly should it be able to do? What deliberately not? How does the person in front of it recognize what’s happening right now? My answers for the weather app – last known weather yes, place search no, timestamp always – are not universal. A banking app draws the line differently, a news site differently again. The only universal thing is that this line has to be drawn before the first `fetch` handler is written. The service worker carries out a product decision. It doesn’t replace it. ## Further reading - Repository: [MikeBild/pwa-weather-demo](https://github.com/MikeBild/pwa-weather-demo) - Jake Archibald: [The Offline Cookbook](https://jakearchibald.com/2014/offline-cookbook/) - MDN: [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) - MDN: [Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) --- # Tic-Tac-Toe with Minimax in React URL: https://www.mikebild.dev/en/blog/tic-tac-toe-with-minimax-in-react/ Date: 2017-06-12 # Tic-Tac-Toe with Minimax in React ```js function score(board, depth) { if (winnerOf(board) === COMPUTER) return 10 - depth; if (winnerOf(board) === HUMAN) return depth - 10; return 0; } ``` An unbeatable tic-tac-toe opponent doesn’t need more evaluation than this. A board is worth `10 - depth` if the computer has won, `depth - 10` if the human has won, and zero for a draw. As a bonus, the search depth in the value provides playing style: a win in two moves counts more than one in four, and a loss in four moves is less bad than one in two. So the opponent wins as early as possible and loses as late as possible – if it can lose at all, which never happens with flawless play. More striking than what is in the function is what is missing: no React, no DOM, no event handler, no `this`, no `setState`. A board goes in, a number comes out. That is exactly what this article is about. The game itself is trivial; every child learns it in five minutes. What’s interesting is the dividing line: the entire opponent is a set of pure functions over an array, and in the end React only renders state. If you don’t draw this line, you later have neither testable logic nor a replaceable UI. I built the accompanying repository `react-tic-tac-toe` in October 2016, prompted by Carsten König’s Othello in Elm – a project that impressed me at the time because the same separation was a matter of course there. In Elm, there simply is no other option: game logic is one function, the view another. In JavaScript, you have to decide on it. ## The board is an array, a move is a new board The data structure is as small as it sounds: an array with nine fields, each field `'X'`, `'O'` or `null`. The indices 0 to 8 run row by row from top left to bottom right. The winning conditions are eight lines over these indices – three rows, three columns, two diagonals. ```js const HUMAN = 'X'; const COMPUTER = 'O'; const LINES = [ [0, 1, 2], [3, 4, 5], [6, 7, 8], [0, 3, 6], [1, 4, 7], [2, 5, 8], [0, 4, 8], [2, 4, 6], ]; function winnerOf(board) { const line = LINES.find(([a, b, c]) => board[a] && board[a] === board[b] && board[a] === board[c]); return line ? board[line[0]] : null; } function movesFor(board) { return board.reduce((moves, field, index) => field === null ? moves.concat(index) : moves, []); } function applyMove(board, index, player) { const next = board.slice(); next[index] = player; return next; } ``` The most important decision is in `applyMove`: a move doesn’t change the board, it creates a new one. `board.slice()` copies the array, then one field is set, and the original stays untouched. For nine elements, that costs nothing, and it pays off twice. First, for the search. Minimax tries moves hypothetically: What if the computer plays field 4 and the human then plays field 0? With mutation, every tried move would have to be taken back after the evaluation – classic do/undo with every opportunity to forget the undo part. With immutable boards, there is nothing to take back. Each branch of the game tree holds its own board, and when the recursion returns, the old board is still exactly the old board. Second, for React. `setState` with a fresh array means: if you want to know whether something has changed, you compare references instead of contents. It is no coincidence that the official React tutorial – of all things also a tic-tac-toe – recommends `slice()` at the same spot. Immutable data is the currency React thinks in. That the same decision simplifies the search algorithm and serves the UI model at the same time was the real aha moment of this small project for me. ## Minimax, told recursively The algorithm is older than any web framework and can be summed up in one sentence: I choose the move that maximizes my result, assuming that the opponent then chooses the move that minimizes my result – and so on, until the game is decided. Two players, alternating maximum and minimum, hence the name. ```js function minimax(board, player, depth) { if (winnerOf(board) || movesFor(board).length === 0) { return score(board, depth); } const values = movesFor(board).map(index => minimax( applyMove(board, index, player), player === COMPUTER ? HUMAN : COMPUTER, depth + 1 )); return player === COMPUTER ? Math.max(...values) : Math.min(...values); } function bestMove(board) { const moves = movesFor(board); const values = moves.map(index => minimax(applyMove(board, index, COMPUTER), HUMAN, 1)); return moves[values.indexOf(Math.max(...values))]; } ``` The recursion has three building blocks, and all three are visible in the code: - The base case: if someone has won or no field is free anymore, `score` returns the value of the end state. - The step: for every free field, `applyMove` creates a successor board, which is evaluated with the player swapped and the depth increased by one. - The choice: if it is the computer’s turn, the maximum of the child values wins, otherwise the minimum. `bestMove` is then just the top level of this search, written out: evaluate all of your own moves, return the index of the best one. A small game tree shows why the depth in the evaluation makes the difference between a correct and a smart opponent: ```mermaid graph TD R["Board, O to move
    takes the maximum"] --> A["Move to field 2 blocks
    X to move, takes the minimum"] R --> B["Move to field 5
    O wins immediately: value +9"] A --> A1["X later forces the win
    value -6"] A --> A2["Draw
    value 0"] A -.-> AV["Minimum: -6"] B -.-> BV["Leaf: +9"] ``` Here, the computer faces the choice of blocking an opposing line or winning itself. Without the depth bonus, both wins would be worth the same, and the choice would depend on the order of evaluation. With `10 - depth`, the immediate win is strictly better – the opponent doesn’t just play flawlessly, it plays purposefully. For a sense of scale: from an empty board, there are around 255,000 possible games, and the tree shrinks drastically with every stone placed. A laptop evaluates that in milliseconds; optimization is computationally unnecessary. The repository still contains a variant with alpha-beta pruning, formulated non-recursively – that was curiosity following the Elm template, because for Othello with its 8×8 board, pruning is no longer a gimmick but a prerequisite. For this article, I deliberately stick with the recursive basic form: it is the version you can derive on a whiteboard, and [simple beats elegant](https://www.mikebild.dev/en/blog/simple-design-can-save-process/) as long as the simple form is measurably enough. ## React only renders state Only now does React come into play, and in a decidedly boring role. The entire game state is `state.board`, and the only place where this state changes is the click handler. The handler orchestrates two moves – the human’s, then the computer’s reply – and delegates everything of substance to the pure functions from above. ```jsx class Game extends React.Component { constructor(props) { super(props); this.state = { board: Array(9).fill(null) }; this.handleClick = this.handleClick.bind(this); } handleClick(index) { const afterHuman = applyMove(this.state.board, index, HUMAN); const finished = winnerOf(afterHuman) || movesFor(afterHuman).length === 0; const nextBoard = finished ? afterHuman : applyMove(afterHuman, bestMove(afterHuman), COMPUTER); this.setState({ board: nextBoard }); } render() { return ; } } const Board = ({ board, onSquareClick }) => (
    {board.map((field, index) => ( ))}
    ); ``` `Board` is a stateless functional component: board in, nine buttons out. `Game` is a React 15 class with exactly one state field and exactly one handler. The setup around it is an ordinary create-react-app project – `npm install`, `npm start`, running on port 3000. In 2017, you no longer need more tooling than that for something like this, and that is a pleasant development. The contrast to the official React tutorial is instructive. There, tic-tac-toe is the vehicle for explaining React: break down components, lift state up, pass props down, and at the end a time history. The opponent is a second human; the game logic is limited to checking for a winner. Here it is exactly the other way around: React is the vehicle, the algorithm is the center. Both perspectives are legitimate – but only the second forces you to draw the boundary between logic and presentation cleanly, because otherwise the logic immediately becomes unwieldy. ```mermaid flowchart LR subgraph core["Pure functions – no React import"] score --> minimax winnerOf --> minimax movesFor --> minimax applyMove --> minimax minimax --> bestMove end subgraph ui["React 15"] state["state.board"] --> render["render()"] render --> onclick["onClick(index)"] end onclick -->|"applyMove + bestMove"| core core -->|"new board"| setState["setState"] setState --> state ``` The arrows between the two boxes are the entire coupling: the handler calls functions and writes the result back into the state. No import runs in the opposite direction. You could replace the right box with a console application, with jQuery or, indeed, with Elm – the left box wouldn’t notice. ## Tests without a browser This separation isn’t a matter of taste; it is measurable – most directly in the tests. The game logic runs in Node, without a DOM, without jsdom, without a mocked event system. Jest, which comes with create-react-app, runs something like this in milliseconds: ```js test('computer blocks an open line', () => { const board = [ HUMAN, HUMAN, null, COMPUTER, null, null, null, null, null, ]; expect(bestMove(board)).toBe(2); }); test('computer prefers the immediate win over the block', () => { const board = [ HUMAN, HUMAN, null, COMPUTER, COMPUTER, null, null, null, null, ]; expect(bestMove(board)).toBe(5); }); ``` These aren’t unit tests in the fine-grained sense but game sense as a specification: the opponent must block an open line, and it must prefer its own win to the block. You can take such cases straight from games – every time the opponent behaves oddly while you try it out, the position becomes a test case. For me, it was exactly such a case at the beginning: without the depth component in `score`, the search kept postponing a certain win, because a win in four moves had the same value as one in two. The position from the second test above is the fossil of this bug. Now the counter-check, and I have seen it in the wild often enough in reviews: the move logic sits in the click handler, the winner check in `render`, the computer’s move in a lifecycle hook such as `componentDidUpdate`. Functionally identical, but now the following applies: - Every logic test needs a mounted component and simulated clicks – a function call turns into a browser ritual. - The position from the bug case can’t be written down directly; it has to be played out through a sequence of clicks. - Switching the UI library, or even just a larger restructuring of the component tree, drags the game logic along with it. - The algorithm can no longer be read in one piece, because it is spread across handlers, render branches and lifecycle methods. None of this is dramatic with three by three fields. But tic-tac-toe is only the lab animal here. Replace “game logic” with “price calculation”, “validation” or “planning rules”, and it is the same decision with the same consequences – except that the entangled version can no longer be untangled in an afternoon. ## What I take away from it Hardly anyone will need minimax itself in everyday project work. What remains is the pattern underneath. The whole opponent is an evaluation function plus a search over immutable values – and because that is so, you can test it like a price formula and render it with whatever happens to be at hand. In this project, React has the role that suits it best in my view: take in state, turn it into a UI, report inputs back. Nothing more. What I find remarkable is how well the parts fit together without being built for each other. Minimax demands immutable boards because otherwise the recursion would need bookkeeping. React rewards immutable state because otherwise comparisons would be expensive. An algorithm from the early days of game theory and a UI library from 2013 meet in the same discipline: no mutation, values instead of changes. That is no coincidence but a sign that this discipline is more fundamental than any single tool. If you want to rebuild this: an array with nine fields, five pure functions, one class with one handler. One afternoon – and afterwards a precise sense of where the line between logic and presentation should run in your own, much larger applications. And a game you will never win again. ## Further reading - Repository `react-tic-tac-toe` (“Tic Tac Toe in React with Minimax-AI”): https://github.com/MikeBild/react-tic-tac-toe - Carsten König’s Othello in Elm, the source of inspiration: https://github.com/CarstenKoenig/ElmOthello - The official React tutorial (tic-tac-toe, current version): https://react.dev/learn/tutorial-tic-tac-toe - Minimax at a glance: https://en.wikipedia.org/wiki/Minimax - Alpha-beta pruning: https://en.wikipedia.org/wiki/Alpha%E2%80%93beta_pruning --- # Simple Design Can Save Process URL: https://www.mikebild.dev/en/blog/simple-design-can-save-process/ Date: 2017-05-24 A change board doesn’t measure how risky a change is. It measures how big it was cut. The same goes for the approval round, the design review and the weekly integration meeting: they react to the shape a design gave the work, not to its domain value. That’s why the usual proposals against too much process start in the wrong place – one more committee, tighter approvals, a rebuilt ticket board. That manages friction instead of getting rid of it. The question that comes before is more fruitful: why does this one change need three teams, two reviews and an approval meeting in the first place? Very often the answer lies in the design, not in the organization. Not always, but often enough that it’s worth looking there first. ## Overhead is expensive before it becomes visible Before I get to design, it’s worth looking at the bill. In his text on YAGNI (“You Aren’t Gonna Need It”), Martin Fowler neatly broke premature, speculative complexity down into types of cost: there’s build cost – building the feature you don’t need today. There’s delay cost – what you didn’t work on in the actual problem during that same time. There’s carry cost – every line of speculative flexibility has to be carried, understood, tested and worked around from now on. And there’s repair cost when the prebuilt assumption turns out to be wrong. The point that almost always gets lost in discussions: a large part of these costs is coordination cost. A flexible, configurable design laid out “for later” needs a design review. It needs a config ticket. It crosses team boundaries and therefore needs alignment. That’s why YAGNI isn’t a laziness principle but a design principle – and, incidentally, a process-saving principle. Less prebuilt complexity means less to align on. A small example I see again and again in variations: ```python # Over-engineered: a pluggable strategy, a factory, and a config object # for ONE rule that exists today. This needs a design review, a config # ticket, and a feature-flag rollout before it ships. class DiscountEngine: def __init__(self, strategy: DiscountStrategy, config: DiscountConfig): self.strategy = strategy self.config = config def apply(self, price: Money, customer: Customer) -> Money: return self.strategy.compute(price, customer, self.config) # YAGNI: the one rule you actually have today. One PR, no coordination, # no ticket for a config value nobody has asked for yet. def apply_discount(price: Money, is_returning_customer: bool) -> Money: return price * 0.9 if is_returning_customer else price ``` The lower variant isn’t “sloppy.” It’s honest. It describes exactly the one rule that exists today. And it costs almost nothing to ship – no round through the committee, no flag, no meeting. If a second discount rule comes along tomorrow, I refactor – then, with real information, instead of today on suspicion. ## The real lever: the size of the cut The discount is the small stage. The big one is the question of how large a change is before it goes live. And this is exactly where the connection lies that I most like to draw out in reviews. ```mermaid flowchart TB A["One large change
    crossing three teams"] --> B[Design Review] B --> C[Cross-team Ticket] C --> D[Merge Conflict] D --> E[Change Board] E --> F[Coordination Meeting] F --> G[Release] A2["Same value, cut into three
    small independent changes"] --> H["Context A
    own pipeline"] A2 --> I["Context B
    own pipeline"] A2 --> J["Context C
    own pipeline"] H --> K[Release] I --> K J --> K ``` The core message of the diagram is simple: coordination effort doesn’t depend on the feature’s value. It depends on the size of the cut and how many team boundaries a cut crosses. A large change that touches three teams creates thick coordination edges – reviews, merge conflicts, change board, alignment rounds. The same domain value, broken down into three small, independent changes, creates almost no cross edges. Each change stays in its own bounded context and goes through its own pipeline. This isn’t theory. The State of DevOps reports of recent years – the work around Forsgren, Humble and Kim – show the same empirically. High performers work with few active branches, integrate into trunk at least once a day and have no long integration or freeze phases. They replace merge and coordination overhead with small batches. Trunk-Based Development is exactly that: making the cut so small that the elaborate coordination never arises in the first place. And the part that surprises skeptics: small deployments aren’t riskier but safer. The same data shows that high deployment frequency and short lead time for changes correlate with a lower change fail rate and shorter time to restore. A small cut is easier to understand, easier to review and easier to roll back if something goes wrong. A large cut needs the heavy approval ceremony – because it really has earned it. You build yourself the process that the size forces on you. ## When coordination is just a symptom A pattern that persists stubbornly in projects: two teams align in a recurring integration meeting because team A provides an endpoint that team B depends on. Every change is discussed in advance, every integration tested together. The process is real – but it only compensates for the fact that nobody made the expectation between the teams explicit. Consumer-Driven Contracts turn this around. The consumer describes exactly what it needs – no more. The provider verifies this contract in its own pipeline, independently. The alignment meeting disappears because the alignment lives in the code: ```javascript // The consumer declares only what it actually needs. No cross-team // integration meeting, no shared end-to-end test suite to schedule. pact .given("customer 42 exists") .uponReceiving("a request for the customer name") .withRequest({ method: "GET", path: "/customers/42" }) .willRespondWith({ status: 200, body: { name: like("Ada") }, }); // The provider replays this contract in ITS OWN pipeline and fails fast // if it ever breaks the expectation — independently, no meeting required. ``` Tools like Pact have made this practical for a few years now. The effect is the same as with the small cut: a piece of coordination that used to exist as a meeting becomes an executable specification – and the process around it is no longer needed. ## Governance without a committee The same pattern applies at the architecture level. Many heavyweight governance processes – the architecture committee that signs off on every change – exist because nobody found a more lightweight way to enforce architecture rules. Neal Ford and Rebecca Parsons coined a nice term for the alternative: fitness functions. Instead of designing big once up front and then guarding it through a committee, you formulate the architecture goals as automatically checkable rules in the deployment pipeline. ```yaml # Architecture rules as executable guardrails in the pipeline, # not as a slide reviewed once a quarter by a committee. fitness_functions: - name: modules_stay_decoupled rule: "no cyclic dependencies between packages" - name: p95_latency_budget threshold_ms: 300 - name: public_api_is_stable rule: "no breaking change without a new version" ``` If the rule is violated, the build turns red – immediately, traceably, the same for everyone. That doesn’t replace architecture work; it replaces the ritual you otherwise use to enforce it. Related to this are Fowler’s ideas of “Sacrificial Architecture” and “MonolithFirst”: build simply and, if necessary, disposably at first, and only bring in complexity when reality forces it. Evolutionary architecture is the consistent refusal to pay process overhead for a future you don’t know yet. ## Where the thesis reaches its limit The counterargument is justified. Three honest caveats, so that a good heuristic doesn’t turn into an ideology. First: simple isn’t the same as simplistic. YAGNI applies to speculative features and premature flexibility – not to internal quality. “We’ll leave out the tests and the design, then we’ll be faster” is the misreading Fowler explicitly writes against. The difference is the one between accidental and essential complexity that Brooks already drew. Less speculative structure: yes. Less care in the core: no. The small discount function from above needs its test just as much as the big engine – just exactly one, for the one rule that exists. Second: overhead isn’t always the design’s fault. Compliance requirements are real. Regulatory gates are real. Real dependencies between teams that can’t be cut away are real. That’s why it deliberately says “often” above and not “always.” It’s not about abolishing every process step. It’s about questioning it: are you compensating for a requirement from outside right now – or for a complexity we built ourselves? Third: a smaller cut can also just shift complexity. Turning one module into two services trades code coupling for distributed coupling and network. That’s sometimes right, but it’s never free. That’s exactly why contract tests are the replacement for the full end-to-end integration circus – and exactly why Fowler’s “MicroservicePremium” is worth remembering: you have to earn distribution; it’s not a default. If you cut small without placing the cut along real domain boundaries, you end up with more coordination, not less. ## How I approach it concretely The order that has proven itself doesn’t start with the process. ```mermaid flowchart LR A["Spot the heavy
    process step"] --> B["Ask: what complexity
    is it compensating?"] B --> C["Cut the change
    smaller"] C --> D["Make the expectation
    explicit as a contract"] D --> E["Turn the gate into a
    fitness function"] E --> F["Drop the step
    that is now redundant"] ``` First I look for the most expensive process step – the meeting that annoys everyone, the approval that always blocks. Then I don’t ask “how do we make it more efficient” but “what complexity is it absorbing.” Most of the time we find a cut that is too large behind it, an unspoken expectation or governance nobody has automated. Then we cut smaller, make the expectation explicit as a contract, cast the gate into a fitness function – and drop the step that no longer absorbs anything, without replacement. The result is rarely spectacular and almost always noticeable: shorter cycles, because less is waiting for approvals. Less friction, because less has to be aligned across team boundaries. Higher quality, because small changes are easier to check and easier to roll back if something goes wrong. Simple and elegant instead of process overhead – that falls out as a by-product of better design and isn’t a cost-cutting measure. ## Conclusion Process is expensive, and usually it’s expensive for a good reason: it absorbs friction that really exists. But the more interesting question is almost never how to make the process more efficient. It’s why the friction arises in the first place. Very often the answer is a design that is too large, too speculative or too implicit. Cutting smaller beats coordinating more. Explicit contracts beat recurring alignment. Automated guardrails beat committees. And YAGNI beats any flexibility you build today and work around tomorrow. This isn’t an invitation to sloppiness – internal quality remains non-negotiable. It’s an invitation not to take process overhead as a law of nature but to read it as a symptom. If you make the problem small in the right place, you don’t need the heavy machinery around it in the first place. Where the process compensates for self-built complexity, a simpler design can actually make it superfluous. Where regulation, operations or real team dependencies are the cause, that calculation remains open. To me, exactly this distinction matters more than the blanket demand for less process. ## Further reading - [Martin Fowler – Yagni](https://martinfowler.com/bliki/Yagni.html) - [Martin Fowler – Is Design Dead?](https://martinfowler.com/articles/designDead.html) - [Sacrificial Architecture (InfoQ, 2014)](https://www.infoq.com/news/2014/11/sacrificial-architecture/) - [Building Evolutionary Architectures / Fitness Functions (O’Reilly, 2017)](https://www.oreilly.com/library/view/building-evolutionary-architectures/9781491986356/ch02.html) - [Neal Ford – Building Evolutionary Architectures](https://nealford.com/books/buildingevolutionaryarchitectures.html) - [Pact – documentation](https://docs.pact.io/) --- # HTML5, CSS3 and ECMAScript as a Baseline URL: https://www.mikebild.dev/en/blog/html5-css3-and-ecmascript-as-a-baseline/ Date: 2017-05-12 # HTML5, CSS3 and ECMAScript as a Baseline Baseline means something specific here: the set of HTML, CSS and JavaScript capabilities that runs in all of a project’s browsers without a single dependency. No `npm install`, no framework, no plugin – only what the platform ships out of the box. This set is not a fixed quantity. It depends on which browsers a project actually has to serve, and it shifts with every browser release. If you know it, you can precisely answer a question that otherwise gets answered by reflex: what exactly do I need a dependency for – and what not? This question is especially worth asking right now, because over the last few months the baseline has moved further up than it has in a long time. ## An unusual spring In March, Chrome 57, Firefox 52 and Safari 10.1 shipped CSS Grid Layout within a few weeks of each other. I’ve never before seen a major layout feature land practically simultaneously and without prefixes in three major browsers. Usually something like this dragged on for years – think of the three different Flexbox syntaxes that coexisted for a long time. Grid is usable in its final syntax from day one. But Grid is only the most visible part. If you can limit your target browsers to current versions of Chrome, Firefox, Safari and Edge, here’s what you have in May 2017 without any dependency: - Flexbox and CSS Grid for layout, plus `@supports` for clean feature queries in the stylesheet - CSS custom properties (widely supported since last year, IE11 excepted) - Native ES2015: classes, arrow functions, destructuring, template literals, promises - `async`/`await` from ES2017 in the current versions of the evergreen browsers - `fetch` as a built-in HTTP client, since Safari 10.1 there too - Custom Elements v1 and Shadow DOM v1 in Chrome and Safari - Service workers in Chrome and Firefox – Safari and Edge are still missing here, and honesty requires saying so Two or three years ago, every single item on this list was a reason to install a library. That’s exactly why the question matters to me again. In a code review recently, I went through a frontend that dragged along jQuery, a grid system, an AJAX helper library and a class emulator – well over 100 KB together before the first line of its own code ran. In 2013, there was a good reason for each of these dependencies. In 2017, the platform handles all four tasks itself. Nobody had ever reversed the decision, because nobody had ever looked at it as a decision. ## Layout now belongs to the platform The example I use to play this through is deliberately ordinary: a product overview, cards in a grid, data from an HTTP interface. The classic case for which you’d otherwise install Bootstrap along with its jQuery dependency. The grid first. With Grid, the layout is a handful of lines, and the fallback for older browsers isn’t a second codebase but a layer underneath: ```css /* baseline for every browser: a simple flex wrap */ .products { display: flex; flex-wrap: wrap; } .product-card { flex: 1 1 240px; margin: 8px; } /* enhancement for browsers with grid support */ @supports (display: grid) { .products { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); grid-gap: 16px; } .product-card { margin: 0; } } ``` I find two things about this remarkable. First: `repeat(auto-fill, minmax(240px, 1fr))` replaces what grid systems needed classes like `col-md-4` and a cascade of media queries for over the years – without a single media query. Second: `@supports` turns the browser matrix into a design decision instead of a compatibility hack. IE11 and the current Edge get the Flexbox grid, modern browsers get Grid. The pages don’t look pixel-identical, and that’s fine – the idea that every browser version has to render identically has cost us a lot of unnecessary code for years. You have to stay honest about Edge: so far it only supports the old Grid syntax with the `-ms` prefix, which dates back to the IE10 era. If Edge is in your target set, treat it like IE11 for Grid for now and use the fallback. That’s exactly what the `@supports` query is for. ## Loading data without a library The second building block is fetching data. What used to require `$.ajax` or your own XHR wrapper is now handled by `fetch` – and with `async`/`await`, the control flow finally reads like synchronous code. How tedious the same task was three years ago with callback chains I recorded back then [in a separate post](https://www.mikebild.dev/en/blog/control-flow-before-async-await/); the distance between these two worlds is surprisingly short. ```js async function loadProducts() { const response = await fetch('/api/products', { headers: { 'Accept': 'application/json' } }); // fetch resolves on HTTP errors too, so check explicitly if (!response.ok) { throw new Error('Request failed with status ' + response.status); } return response.json(); } ``` The comment in the code marks the pitfall I run into most often in reviews: `fetch` doesn’t reject the promise on a 404 or 500, only on network errors. If you come from jQuery, you expect the opposite. You have to learn quirks like this once – but in doing so you learn the platform, not a library’s opinion, and that knowledge goes stale much more slowly. For IE11: no `fetch`, no promises, no `async`/`await`. If you have to support it, compile with Babel and load two small polyfills. That’s a build step I otherwise like to avoid – but it’s manageable, targeted and above all temporary. The polyfill goes away as soon as IE11 drops out of the matrix. In my experience, a framework dependency never goes away. ## Components directly in the browser The third building block is the most interesting because it comes closest to what you’d otherwise reach for a framework for: reusable components. Custom Elements v1 have arrived in Chrome and Safari, and with them you can define the product list as your own HTML element: ```js class ProductList extends HTMLElement { async connectedCallback() { this.textContent = 'Loading products ...'; try { const products = await loadProducts(); this.render(products); } catch (error) { this.textContent = 'Products are currently unavailable.'; } } render(products) { this.innerHTML = '
    '; const container = this.querySelector('.products'); products.forEach(product => { const card = document.createElement('article'); card.className = 'product-card'; card.textContent = product.name; container.appendChild(card); }); } } customElements.define('product-list', ProductList); ``` The markup then simply contains ``, and the browser calls the lifecycle methods itself. No virtual DOM, no data binding, no render loop – a component of this size needs none of that. Firefox and Edge still need the polyfill from the webcomponents.org project for this, and it isn’t free: it adds noticeable weight and has to be tested across the browser matrix. If you rely on Custom Elements in production today, you should know these costs and not just the Chrome demo. A note on the side: native ES modules in the browser are also just around the corner – Safari 10.1 already supports `