Before You Start: How to Read This Book

By the end of this chapter you can answer:

• Given a chunk of AI-generated Rust gateway code, which responsibilities does this book's contract leave to you?
• A request goes to jackdaw: which stations does it pass through between your curl and the answer streaming back?
• Where do you switch languages, search, and unfold self-check answers on this site?

The Contract: You Don't Write Rust, You Read It

You already write at least one other language — Python, Go, TypeScript all count — and you're at zero with Rust. That is exactly the reader this book assumes: zero is the starting point, not a deficit. The contract in one sentence: AI writes the code; you read it, review it, and verify it.

Why split the work this way? AI has pushed the cost of "producing code that compiles" close to zero, and the bottleneck moved to the other end: code you can't read is unusable no matter how well it runs. You can't audit it for security, you can't debug it when it breaks, and you can't answer for what it does. Reading is the half of the job you keep. This book trains exactly that: hand you annotated Rust, and you can tell where the data comes from, where it goes, and how errors travel through it.

Prerequisites: the basics of one language (variables, functions, JSON, HTTP) and comfort with the command line. You need to install nothing to read this book. Whether you run the commands yourself is your call.

jackdaw: The Project We Take Apart

From Chapter 4 on, every example in this book comes from the same real project: jackdaw, a gateway that runs on your machine — a resident forwarding service: one unified entry point, several providers behind it. A provider is whoever serves a model API.

Its prototype is magpie: a local gateway plus model manager that listens on 127.0.0.1:3425 by default, speaks the OpenAI / Anthropic / Gemini protocols and translates between them, supports provider types from subscriptions to local models, and adds a large set of routing rules. jackdaw deliberately keeps only the minimal core: an OpenAI-compatible protocol in and out; providers configured by hand, with no built-in catalog; group/<id> routing groups with two strategies, order and rotate, plus failover. Most of what magpie has, jackdaw leaves out on purpose — a teaching choice, not a flaw. Wherever the two differ, the book says so explicitly: "magpie has X; jackdaw skips it on purpose, because this book only needs the core." Chapter 2 uses pi (a family of coding agent tools that calls itself the "Pi Agent Harness") to explain what an agent actually is; from Chapter 10 on, you watch jackdaw grow layer by layer.

One Request's Journey (Watch First, Take It Apart Later)

Here is the finished jackdaw doing one complete piece of work. For now you only need to see what happens; each station's internals are tagged with the chapter that opens them up.

Setup: jackdaw is running on your machine, with a config that looks like this (excerpted from jackdaw/jackdaw.example.toml; TOML — bracketed lines open a section, entries are key = value):

[gateway]
port = 3426
auth_token_env = "JACKDAW_TOKEN"   # agents send this variable's value as the Bearer token

[providers.openai]                 # the table name is the provider name — no built-in catalog
base_url = "https://api.openai.com/v1"   # OpenAI-compatible endpoint, no trailing slash
api_key_env = "OPENAI_API_KEY"           # stores the env var NAME, never the key itself

# ...

[groups.coder]
strategy = "order"                 # order | rotate
models = ["openrouter/deepseek/deepseek-chat", "openai/gpt-5.2"]

How to read it: start at [groups.coder] — the model field of an incoming request points at it. order means "walk the list top to bottom": try deepseek-chat first, fall back to openai/gpt-5.2 if it fails (rotate instead starts at the next member each time, spreading load). The # ... hides the openrouter block, which has the same shape as openai: one base URL plus one environment variable name — note that it stores the variable name, never the API key itself.

Then you — or some coding tool — send this:

curl -N http://127.0.0.1:3426/v1/chat/completions \
  -H "Authorization: Bearer $JACKDAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "group/coder",
        "messages": [{"role": "user", "content": "Introduce yourself in one sentence"}],
        "stream": true
      }'

How to read it: -N turns off curl's buffering so each piece prints as it arrives; the request hits port 3426 on 127.0.0.1, which is jackdaw itself; $JACKDAW_TOKEN is the value of the environment variable that auth_token_env names; and model isn't a concrete model — it's a group name.

Four stations follow:

curl ──▶ jackdaw :3426 ──▶ openrouter ──▶ deepseek-chat
              └─ on failure ──▶ openai / gpt-5.2

1. jackdaw checks the Bearer credential (Chapter 14), recognizes group/coder, and picks the first member under order (Chapter 13).
2. jackdaw forwards the request to openrouter's URL: it swaps in the value of OPENROUTER_API_KEY and rewrites model from the group name to the first member's model; everything else stays untouched.
3. The upstream cuts the answer into small pieces and pushes them back as a stream (SSE); jackdaw passes them through unchanged (Chapter 14). If the upstream fails, failover switches to the next entry (Chapter 13).
4. Your terminal prints the answer piece by piece:

data: {"choices":[{"delta":{"content":"I'm"}}]}

data: {"choices":[{"delta":{"content":"a jackdaw"}}]}

data: [DONE]

How to read it: each data: line is a small slice of incremental text; only the concatenation is the full answer. This block trims most of the JSON fields to keep the focus — Chapter 2 shows the real structure. On a first pass, register the shape and move on; don't study it field by field.

That is where this book is heading: by the end of Chapter 14, you'll be able to explain every station above against the source code.

How to Use This Site

• Language switch: the top-right corner toggles 简体中文 / English. The two versions are parallel writing — same depth and coverage, not sentence-by-sentence translation. Read whichever flows better for you.
• Search: the box at the top is local search, indexed separately per language. When a term trips you up, looking it up usually beats grinding through.
• Self-checks: every chapter ends with three questions whose answers are collapsed by default — answer first, unfold second. Don't reverse that order.
• Glossary: linked terms in the text (like gateway above) lead to the glossary; click through whenever a term slips your mind.

The site has five parts: Part 1 builds the worldview, Part 2 teaches you to read Rust itself, Part 3 covers projects and the ecosystem, Part 4 grows jackdaw layer by layer, Part 5 points beyond. Read them in order.

Summary

The contract: AI writes; you read, review, and verify — code you can't read doesn't belong in your project, however well it runs. jackdaw is the minimal gateway this book dissects: a request comes in from curl, picks a model by group, goes out to a provider, streams back. On this site: switch languages top-right, search at the top, unfold answers at chapter ends. Next chapter: what exactly is an agent — the pi worldview.

Self-Check

1. A colleague says: "I had AI write a Rust gateway for me. It runs — no need to understand it." Using this book's contract, name the risk in that sentence.
2. In the demo, openrouter fails on this call. Following the groups.coder config, what happens next? And what changes under strategy = "rotate"?
3. Why does the config say api_key_env = "OPENAI_API_KEY" (a variable name) instead of storing the key itself?

Answers

1. The contract is AI writes, you read: auditing for security, debugging, and answering for the behavior all stay with you. Code that runs but that you can't read fails on all three — the risk hides inside a black box nobody is accountable for.
2. Failover kicks in: under order, jackdaw retries with the next list entry, openai/gpt-5.2. rotate doesn't always start at the first member; each request starts one further down the list, spreading the load (Chapter 13).
3. Config files end up in repositories and get shared around; storing only the name keeps each key in the environment of the machine it belongs to, so the config file is safe to publish (Chapter 11).