edgeway 0.2.0 → 0.3.0

data/README.md

@@ -38,6 +38,11 @@ end
 
 ## Contents
 
+- [Usage](#usage)
+  - [Generators](#generators)
+  - [Building](#building)
+  - [Spinel version](#spinel-version)
+- [Configuration](#configuration)
 - [Models](#models)
   - [Attribute types](#attribute-types)
   - [Strong parameters](#strong-parameters)
@@ -53,18 +58,159 @@ end
   - [Read replication (Sessions)](#read-replication-sessions)
   - [D1 API coverage](#d1-api-coverage)
 - [Views](#views)
-- [Usage](#usage)
-  - [Generators](#generators)
-  - [Building](#building)
-  - [Spinel version](#spinel-version)
-  - [Known limitations](#known-limitations)
-- [Configuration](#configuration)
+- [Static assets](#static-assets)
+- [Logging](#logging)
 - [Authentication](#authentication)
 - [CORS](#cors)
+- [HTTP caching](#http-caching)
+- [Caching](#caching)
+  - [Stores](#stores)
+  - [config/cache.yml](#configcacheyml)
+  - [KV](#kv)
+  - [In tests](#in-tests)
+- [Outbound HTTP](#outbound-http)
+- [Rate limiting](#rate-limiting)
+  - [In tests](#in-tests-1)
 - [Testing an app](#testing-an-app)
+  - [Writing tests](#writing-tests)
+  - [Local D1 (`adapter: d1` in `test:`)](#local-d1-adapter-d1-in-test)
+  - [SQLite (`adapter: memory` in `test:`)](#sqlite-adapter-memory-in-test)
+  - [Differences from production](#differences-from-production)
+- [Known limitations](#known-limitations)
 - [Development](#development)
 - [License](#license)
 
+## Usage
+
+```sh
+gem install edgeway
+
+edgeway new myapp
+
+# mise, bundle, pnpm and the local D1 migrations
+cd myapp && bin/setup
+
+# the app's tests, as wasm on a local D1 (see "Testing an app")
+bundle exec edgeway test        # or bin/test [FILE...] in a generated app
+
+# edgeway build: writes build/app.wasm and build/edgeway/ (the JS).
+# A development build: Spinel's --incremental caches the generated C in units,
+# so a rebuild recompiles only what changed (no inlining across units)
+bin/build
+
+pnpm exec wrangler dev
+edgeway routes
+
+# bin/build --release (one unit, without --incremental), remote D1 migrations,
+# then pnpm exec wrangler deploy
+bin/deploy
+```
+
+`edgeway` commands: `new`, `build`, `test`, `generate` (`g`), `routes`, `version` (`edgeway help` lists them).
+
+Before `bin/deploy`:
+
+1. Log in (`pnpm exec wrangler login`).
+2. Create the D1 database (`pnpm exec wrangler d1 create <name>-db`).
+3. Put its `database_id` in `wrangler.toml`.
+
+`bin/setup` prints these steps when they are missing.
+
+- A generated app's Gemfile takes `edgeway` and `spinel_test-unit` from RubyGems.
+- A generated app's `.github/workflows/ci.yml` installs Ruby (from `.ruby-version`, which `edgeway new` writes with the Ruby that ran it), mise's tools and wrangler, then runs `bin/test` and `bin/build --release`.
+- An app uses [pnpm](https://pnpm.io/) for wrangler (`package.json`, `bin/setup`, `mise.toml`);
+  `edgeway new` names it in one place (`Edgeway::CLI::PackageManager`).
+- `SPINEL=/path/to/spinel bin/build` uses a Spinel other than the one on `PATH`.
+- `bin/deploy` applies pending remote D1 migrations (`wrangler d1 migrations apply <name>-db --remote`) before deploying.
+
+### Generators
+
+Inside an app made by `edgeway new`, `edgeway generate` (or `edgeway g`) writes the files and never overwrites one:
+
+```sh
+# app/models/todo.rb, db/migrations/0001_create_todos.sql, test/models/todo_test.rb
+edgeway generate model Todo title:string done:boolean
+
+# app/controllers/todos_controller.rb, test/controllers/todos_test.rb
+edgeway generate controller Todos index show
+
+# the model's files, a JSON API controller (index, show, create, update, destroy) and its test
+edgeway generate scaffold Todo title:string done:boolean
+```
+
+- Field types are `string` (the default), `text`, `integer`, `float`, `boolean` and `datetime`.
+- A model gets `timestamps` and an `id`, `created_at` and `updated_at` column.
+- The migration is numbered one above the highest in `db/migrations`.
+- Each action of a controller is a stub that renders `{}`.
+- `config/routes.rb` is not changed by `model` and `controller`: the command prints the route to add (`r.resources :todos`).
+- `model` and `scaffold` stop if a `db/migrations/*_create_todos.sql` already exists (a rerun would add a second table).
+- `scaffold` singularizes its name (`scaffold Todos` is `Todo`), checks that none of its files exist before it writes one, and adds `r.resources :todos` as the last line of the `routes.draw` block, so that it does not shadow an earlier `/todos/search`. It leaves a route that is already there alone, and prints the route and the reason instead if there is no `routes.draw do |r|` block with a closing `end`.
+- The scaffold's controller permits the given fields (`params.require(:todo).permit(...)`), and with no fields it takes no params.
+
+### Building
+
+`edgeway build` needs Spinel and the WASI SDK.
+
+- An app made by `edgeway new` has a `mise.toml` for both (`mise install`):
+  Spinel comes from the [mise-spinel](https://github.com/y-yagi/mise-spinel) plugin and is put on `PATH`,
+  and the WASI SDK is pointed at by `WASI_SDK`.
+- Without mise, set `SPINEL` (or put `spinel` on `PATH`) and `WASI_SDK`.
+- `SPINEL` wins over `spinel` on `PATH`, which is how to use a Spinel checkout instead of a release.
+
+See `todo-api` in [edgeway-examples](https://github.com/y-yagi/edgeway-examples) for an example (checked with its `check.sh`).
+
+### Spinel version
+
+Edgeway needs a Spinel newer than the 2026.09.12 release
+(that release refuses `send` with a computed name, which `Callbacks#run_before_actions` uses).
+
+- `mise.toml` (Edgeway's own and the one `edgeway new` writes) pins a commit of [matz/spinel](https://github.com/matz/spinel),
+  `ec0ad13e4`, which mise-spinel builds from source.
+  A commit rather than `master`, so that an install is the Spinel that was tested.
+- The WASI SDK (`wasi-sdk-34`) is installed first,
+  because mise-spinel builds Spinel's wasm32-wasi runtime only when it finds one.
+- Changing the pin means re-running `rake test` and `todo-api/check.sh` in [edgeway-examples](https://github.com/y-yagi/edgeway-examples).
+
+## Configuration
+
+Two files configure the database, each for its own side:
+
+- `config/database.yml` is Edgeway's: for each environment (`edgeway build --env ENV`),
+  the adapter (`d1`, or `memory`, which stores nothing) and the name of the D1 binding the app uses. It is compiled into the wasm.
+- `wrangler.toml` is Cloudflare's: which D1 database the binding is (`database_name`, `database_id`),
+  the migrations, and the Worker. `binding` in it must match `binding` in `config/database.yml`.
+
+Another database goes under `databases:` of an environment, with its own binding in `wrangler.toml`:
+
+```yaml
+production:
+  adapter: d1
+  binding: DB
+  databases:
+    analytics:
+      binding: ANALYTICS
+```
+
+Its migrations are in `db/analytics/migrations` (`migrations_dir` of its `[[d1_databases]]`; apply them per database).
+A name is lowercase letters, digits and `_`, and not `primary`; `binding:` is required.
+The extra databases use the environment's adapter.
+`sessions: true` next to `binding:` (in the environment for the primary, in the entry for another) turns on D1 Sessions for it (see [Read replication](#read-replication-sessions)).
+
+`database_id` is not a secret: it only names the database, and using it takes an API token of the account,
+so it is committed with `wrangler.toml` as Cloudflare's own examples do.
+Secrets the app needs go in Worker secrets (`pnpm exec wrangler secret put NAME`),
+which the app reads with `Edgeway.config("NAME")`.
+
+Not every Worker variable reaches the app. Only these are passed into the wasm:
+
+- the framework's own settings (`JWT_ISSUER`, `JWT_AUDIENCE`, `JWT_LEEWAY`, `JWT_ALGORITHMS`, `JWT_JWKS_URL`, `LOG_LEVEL`)
+- the variables whose name starts with `APP_`
+
+Name your own settings `APP_...` (`APP_PAGE_SIZE = "20"` in `[vars]`, `Edgeway.config("APP_PAGE_SIZE", "20")` in Ruby),
+and likewise your secrets (`wrangler secret put APP_NAME`).
+Anything else, such as a key the Worker holds for another purpose, is never visible to the app.
+`JWT_SECRET` is never passed.
+
 ## Models
 
 ### Attribute types
@@ -79,33 +225,34 @@ end
 | `:binary` | binary String (`.b`) | BLOB | base64 string |
 | `:bigint` | decimal String (`"3000000000"`) | INTEGER | string |
 
-- Integers are 32 bits in a wasm build. A `:integer` value beyond -2147483648..2147483647 casts to `nil`; use `:bigint` for those columns.
-  Assigning one is refused by validation ("is out of range"). A row that already holds one (a foreign key to a bigint parent
-  declared as `:integer`) loads as `nil`, and saving it fails the same way instead of writing `NULL` over it.
-- A `:bigint` holds its value as a String of an optional `-` and digits, without leading zeros (`"-0"` is `"0"`);
-  anything else, or a value beyond 64 bits, casts to `nil` ("is invalid"). It is bound as text and SQLite's INTEGER affinity
-  stores it as an integer, so `where`, `order` and comparisons work on the number.
-  It renders in JSON as a String, which JavaScript clients read exactly.
-  D1 hands rows over as JavaScript numbers, so a value beyond 2^53 (9007199254740991) has already lost precision before Ruby sees it.
-  Keep such values below 2^53, or store them as `:string`.
+#### `:integer` and `:bigint`
+
+- Integers are 32 bits in a wasm build. An `:integer` value outside -2147483648..2147483647 casts to `nil` and fails validation
+  ("is out of range"); use `:bigint` for such columns. A row that already holds one loads as `nil`, and saving it fails the same way
+  instead of writing `NULL` over it.
+- A `:bigint` is a String of an optional `-` and digits, without leading zeros (`"-0"` is `"0"`); anything else, or a value beyond 64 bits,
+  casts to `nil` ("is invalid"). It is stored as an INTEGER, so `where`, `order` and comparisons work on the number,
+  and it renders in JSON as a String.
+- D1 hands rows over as JavaScript numbers, so a value beyond 2^53 (9007199254740991) loses precision before Ruby sees it.
+  Keep values below 2^53, or store them as `:string`.
 - Pass bigint values as Strings: `Todo.find("3000000000")`, `where(id: "3000000000")`, `create!(owner_id: "5000000000")`,
-  `Model.execute("... WHERE id = ?", ["3000000000"])`. A Hash holding an Integer literal beyond 32 bits raises `RangeError` in a wasm build
-  (a Spinel limitation), so do not write them as Integers.
-- `attribute :id, :bigint` makes the primary key a bigint: `find`, `where(id: ...)`, `update`, `destroy` and an insert
-  (`RETURNING id`) work past 2^31, and `id` is a String. A foreign key to it is `attribute :owner_id, :bigint`
-  (declare it before `belongs_to` and it keeps its type).
-- Rows from raw SQL (`Model.select_all`) hold what the database gave: in a wasm build an INTEGER beyond 32 bits is a Bignum,
-  and `render json:` of it raises. Select it as text (`SELECT CAST(id AS TEXT) AS id ...`) or pass it through `Edgeway::Model.cast(:bigint, value)`.
-- A `:binary` attribute holds a binary String. Assigned from Ruby, a String keeps its bytes (`Document.new(body: bytes)`), and so does a `{"$blob" => base64}` Hash.
-  It is bound as a BLOB (`where(body: bytes)` too), and renders in JSON as a base64 String.
-  In a request body the value is that base64 String, so a GET then PATCH round trip is stable: params assigned through `permit` are decoded,
-  and invalid base64 fails validation ("is invalid"). `{"$blob": ...}` objects are not supported in a request body (nested objects are dropped).
-  `presence` counts a binary String blank only when empty, and `length` counts bytes.
-  A BLOB crosses between wasm and JS as `{"$blob": "<base64>"}`: binds and rows cross as JSON text, which can't hold arbitrary bytes.
-  In raw SQL (`Model.select_all`, `Model.execute`, `where("...", value)`) bind a BLOB with `Edgeway::Model.blob(bytes)`,
-  and a BLOB column comes back as `{"$blob" => base64}`.
+  `Model.execute("... WHERE id = ?", ["3000000000"])`. An Integer literal beyond 32 bits in a Hash raises `RangeError` in a wasm build (a Spinel limitation).
+- `attribute :id, :bigint` makes the primary key a bigint, and `id` is a String. A foreign key to it is `attribute :owner_id, :bigint`,
+  declared before `belongs_to` so it keeps its type.
+- Raw SQL rows (`Model.select_all`) hold what the database gave: an INTEGER beyond 32 bits is a Bignum in a wasm build, and `render json:` of it raises.
+  Select it as text (`SELECT CAST(id AS TEXT) AS id ...`) or convert it with `Edgeway::Model.cast(:bigint, value)`.
 - `Model.execute` answers `"last_insert_id"` as an Integer, or as a decimal String when the rowid is beyond 32 bits.
 
+#### `:binary`
+
+- A `:binary` attribute holds a binary String. It is bound as a BLOB (`where(body: bytes)` too) and renders in JSON as a base64 String.
+- Assigned from Ruby, a String keeps its bytes (`Document.new(body: bytes)`), and so does a `{"$blob" => base64}` Hash.
+- In a request body the value is the base64 String, so a GET then PATCH round trip is stable. Invalid base64 fails validation ("is invalid"),
+  and `{"$blob": ...}` objects are not supported (nested objects are dropped).
+- `presence` counts a binary String blank only when empty, and `length` counts bytes.
+- In raw SQL (`Model.select_all`, `Model.execute`, `where("...", value)`), bind a BLOB with `Edgeway::Model.blob(bytes)`;
+  a BLOB column comes back as `{"$blob" => base64}`, the form in which BLOBs cross between wasm and JS.
+
 ### Strong parameters
 
 Params must go through `permit` before a model takes them.
@@ -220,14 +367,15 @@ Edgeway::Model.exec("DELETE FROM tags\nDELETE FROM todos")        # nil
 (a wasm instance serves one request, so it starts at zero):
 
 - `queries`: the number of successful D1 calls (a `Model.batch` is one). A failed call and its time are not counted.
-- `rows_read`, `rows_written`: the sums of D1's `meta`, capped at 2147483647 (32-bit; the log line shows a capped count with a trailing `+`).
+- `rows_read`, `rows_written`: the sums of D1's `meta`, capped at 2147483647 (32-bit).
 - `duration_ms` (Float): the sum of D1's `meta.duration`.
 - `served_by_region` and `served_by_primary`: from the last call (`""` and `true` when D1 doesn't say, as in `wrangler dev`).
 
-When a request ran any query, `Edgeway::Server` logs one line after it, also for a request that raised and was rescued:
+When a request ran any query, `Edgeway::Server` logs one `query stats` line after it ([Logging](#logging)), also for a request that raised and was rescued.
+Its fields are `queries`, `rows_read`, `rows_written`, `db_ms` and, for a database other than the primary, `database`:
 
-```
-[edgeway] db=3 rows_read=12 rows_written=1 db_ms=2.46
+```json
+{"level":"info","message":"query stats","queries":3,"rows_read":12,"rows_written":1,"db_ms":2.46}
 ```
 
 The Memory and SQLite adapters report zeros and log nothing.
@@ -298,7 +446,7 @@ Todo.eager_load(:comments, :tags)   # several at once, still one query
 
 ### Multiple databases
 
-A model uses the primary database unless it names another, declared in `config/database.yml` (see "Configuration"):
+A model uses the primary database unless it names another, declared in `config/database.yml` (see [Configuration](#configuration)):
 
 ```ruby
 class Event < ApplicationModel
@@ -318,8 +466,8 @@ Edgeway::Model.execute("DELETE FROM events", [], database: :analytics)
   `eager_load` across databases raises `ArgumentError`: a `JOIN` can't cross them.
 - A `Model.batch` belongs to the database of its first write; a write for another one raises `ArgumentError`
   (D1 batches are per database). Use one `batch` per database.
-- `Edgeway::Model.query_stats(:analytics)` is that database's stats. The request log has one line per database that ran queries,
-  and the extra ones start with `database=analytics`.
+- `Edgeway::Model.query_stats(:analytics)` is that database's stats. The request logs one `query stats` line per database that ran queries,
+  with a `database` field for the ones other than the primary.
 
 ### Read replication (Sessions)
 
@@ -357,8 +505,8 @@ Every query and `Model.batch` of such a database then goes through `env.DB.withS
 | `batch()` | `Model.batch` (and `destroy` with dependents) |
 | `exec()` | `Model.exec` |
 | `withSession()`, `getBookmark()` | `sessions: true` ([Read replication](#read-replication-sessions)) |
-| `result.meta` | `Model.query_stats` and the `db=…` log line |
-| `first()`, `raw()` | not used: `find_by`/`first` send `LIMIT 1` through `all()`, which also keeps `meta`; `raw()` made the JSON smaller but rebuilding the rows in Ruby cost as much as it saved |
+| `result.meta` | `Model.query_stats` and the `query stats` log line |
+| `first()`, `raw()` | not used (`find_by`/`first` send `LIMIT 1` through `all()`) |
 | `dump()` | not supported (alpha databases only) |
 
 Time Travel, export/import and migrations are `wrangler d1` commands, outside the Worker API.
@@ -406,161 +554,61 @@ so it sees the action's `@variables`, `params` and the controller's methods.
 
 Not supported yet: partials (`render partial:`), layouts other than `application`, and templates other than `.html.erb`.
 
-## Usage
-
-```sh
-gem install edgeway
-
-edgeway new myapp
-
-# mise, bundle, pnpm and the local D1 migrations
-cd myapp && bin/setup
-
-# the app's tests, natively (needs libsqlite3-dev, see "Testing an app")
-bundle exec edgeway test        # or bin/test [FILE...] in a generated app
-
-# edgeway build: writes build/app.wasm and build/edgeway/ (the JS).
-# A development build: Spinel's --incremental caches the generated C in units,
-# so a rebuild recompiles only what changed (no inlining across units)
-bin/build
-
-pnpm exec wrangler dev
-edgeway routes
-
-# bin/build --release (one unit, without --incremental), remote D1 migrations,
-# then pnpm exec wrangler deploy
-bin/deploy
-```
-
-`edgeway` commands: `new`, `build`, `test`, `generate` (`g`), `routes`, `version` (`edgeway help` lists them).
-
-Before `bin/deploy`:
-
-1. Log in (`pnpm exec wrangler login`).
-2. Create the D1 database (`pnpm exec wrangler d1 create <name>-db`).
-3. Put its `database_id` in `wrangler.toml`.
-
-`bin/setup` prints these steps when they are missing.
-
-- A generated app's Gemfile takes `edgeway` and `spinel_test-unit` from RubyGems.
-- A generated app's `.github/workflows/ci.yml` installs libsqlite3-dev, Ruby (from `.ruby-version`, which `edgeway new` writes with the Ruby that ran it), and mise's tools, then runs `bin/test` and `bin/build --release`.
-- An app uses [pnpm](https://pnpm.io/) for wrangler (`package.json`, `bin/setup`, `mise.toml`);
-  `edgeway new` names it in one place (`Edgeway::CLI::PackageManager`).
-- `SPINEL=/path/to/spinel bin/build` uses a Spinel other than the one on `PATH`.
-- `bin/deploy` applies pending remote D1 migrations (`wrangler d1 migrations apply <name>-db --remote`) before deploying.
-
-### Generators
-
-Inside an app made by `edgeway new`, `edgeway generate` (or `edgeway g`) writes the files and never overwrites one:
-
-```sh
-# app/models/todo.rb, db/migrations/0001_create_todos.sql, test/models/todo_test.rb
-edgeway generate model Todo title:string done:boolean
-
-# app/controllers/todos_controller.rb, test/controllers/todos_test.rb
-edgeway generate controller Todos index show
-
-# the model's files, a JSON API controller (index, show, create, update, destroy) and its test
-edgeway generate scaffold Todo title:string done:boolean
+## Static assets
+
+`public/` is served by Cloudflare as Workers Static Assets (`[assets]` in `wrangler.toml`).
+A request that matches a file is answered without starting the wasm (no CPU time for the app); the others go to the app.
+
+- The files are public: authentication in the app does not apply to them.
+- A file takes its path from the app, for every method. With the default `html_handling` (`auto-trailing-slash`),
+  `public/todos.html` answers `GET /todos`, and `POST /todos` is an empty 405; `public/index.html` answers `/`.
+- The Worker does not run for them, so CORS and the app's headers do not apply (Cloudflare reads headers for them from `public/_headers`).
+- `public/.assetsignore` (`.gitignore` syntax) lists files not to upload. `edgeway new` writes it, which also keeps `public/` in git
+  (wrangler fails without the directory).
+- `edgeway test` calls the app directly, so tests do not see `public/`.
+
+For a single-page app, `not_found_handling = "single-page-application"` serves `index.html` for unknown paths.
+With a `compatibility_date` of 2025-04-01 or later it also answers browser navigations (`Sec-Fetch-Mode: navigate`)
+with assets before the Worker runs, so the app's HTML views are hidden and a browser that opens an API URL gets `index.html`.
+List the app's paths in `run_worker_first` (patterns support `*` and `!` negation; needs wrangler 4.20.0 or later).
+It replaces that navigation detection, so every app path must be listed: one that is not gets `index.html`, even from `fetch`.
+
+```toml
+[assets]
+directory = "./public"
+not_found_handling = "single-page-application"
+run_worker_first = ["/health", "/todos", "/todos/*"]
 ```
 
-- Field types are `string` (the default), `text`, `integer`, `float`, `boolean` and `datetime`.
-- A model gets `timestamps` and an `id`, `created_at` and `updated_at` column.
-- The migration is numbered one above the highest in `db/migrations`.
-- Each action of a controller is a stub that renders `{}`.
-- `config/routes.rb` is not changed by `model` and `controller`: the command prints the route to add (`r.resources :todos`).
-- `model` and `scaffold` stop if a `db/migrations/*_create_todos.sql` already exists (a rerun would add a second table).
-- `scaffold` singularizes its name (`scaffold Todos` is `Todo`), checks that none of its files exist before it writes one, and adds `r.resources :todos` as the last line of the `routes.draw` block, so that it does not shadow an earlier `/todos/search`. It leaves a route that is already there alone, and prints the route and the reason instead if there is no `routes.draw do |r|` block with a closing `end`.
-- The scaffold's controller permits the given fields (`params.require(:todo).permit(...)`), and with no fields it takes no params.
-
-### Building
-
-`edgeway build` needs Spinel and the WASI SDK.
-
-- An app made by `edgeway new` has a `mise.toml` for both (`mise install`):
-  Spinel comes from the [mise-spinel](https://github.com/y-yagi/mise-spinel) plugin and is put on `PATH`,
-  and the WASI SDK is pointed at by `WASI_SDK`.
-- Without mise, set `SPINEL` (or put `spinel` on `PATH`) and `WASI_SDK`.
-- `SPINEL` wins over `spinel` on `PATH`, which is how to use a Spinel checkout instead of a release.
-
-See `todo-api` in [edgeway-examples](https://github.com/y-yagi/edgeway-examples) for an example (checked with its `check.sh`).
+## Logging
 
-### Spinel version
-
-Edgeway needs a Spinel newer than the 2026.09.12 release
-(that release refuses `send` with a computed name, which `Callbacks#run_before_actions` uses).
-
-- `mise.toml` (Edgeway's own and the one `edgeway new` writes) pins a commit of [matz/spinel](https://github.com/matz/spinel),
-  `ec0ad13e4`, which mise-spinel builds from source.
-  A commit rather than `master`, so that an install is the Spinel that was tested.
-- The WASI SDK (`wasi-sdk-34`) is installed first,
-  because mise-spinel builds Spinel's wasm32-wasi runtime only when it finds one.
-- Changing the pin means re-running `rake test` and `todo-api/check.sh` in [edgeway-examples](https://github.com/y-yagi/edgeway-examples).
-
-### Known limitations
-
-- Only the subset of Ruby that Spinel supports can be used.
-- `has_many` does not work with namespaced models (`Admin::Post`);
-  `belongs_to` and `has_many` look models up by their full name, and that case is not handled.
-- Cloudflare Access is not supported in this release: its token comes in `Cf-Access-Jwt-Assertion`,
-  and only `Authorization: Bearer` is read (see [Authentication](#authentication)).
-- Tests run natively, not in wasm: D1 and JSPI (`Edgeway::Cloudflare::JWTVerifier`) are not covered by them,
-  and the production wasm never loads the SQLite adapter (see [Testing an app](#testing-an-app)).
-- Not verified on a production Cloudflare deploy yet: CPU and wall time on a cold start and on a JWKS cache miss,
-  and read replication with real replicas (local D1 has none, and D1 itself accepts any bookmark there). Everything was checked under `wrangler dev`.
-- Integers are 32 bits in a wasm build: use `:bigint` for larger ones and pass them as Strings,
-  and keep them below 2^53, as D1 hands rows over as JavaScript numbers (see [Attribute types](#attribute-types)).
-- A `Model.batch` runs on one database: there is no transaction across databases ([Multiple databases](#multiple-databases)).
-- `Model.exec` does not work on a database with `sessions: true`: a D1 session has no `exec()` ([Queries](#queries)).
-- Spinel can't build a Range of Times: use ISO 8601 Strings or a SQL fragment in `where` ([Queries](#queries)).
-- `first()` and `raw()` are not used and `dump()` is not supported; Time Travel and export/import are `wrangler d1` commands ([D1 API coverage](#d1-api-coverage)).
-
-## Configuration
-
-Two files configure the database, each for its own side:
-
-- `config/database.yml` is Edgeway's: for each environment (`edgeway build --env ENV`),
-  the adapter (`d1`, or `memory` for tests) and the name of the D1 binding the app uses. It is compiled into the wasm.
-- `wrangler.toml` is Cloudflare's: which D1 database the binding is (`database_name`, `database_id`),
-  the migrations, and the Worker. `binding` in it must match `binding` in `config/database.yml`.
-
-Another database goes under `databases:` of an environment, with its own binding in `wrangler.toml`:
-
-```yaml
-production:
-  adapter: d1
-  binding: DB
-  databases:
-    analytics:
-      binding: ANALYTICS
+```ruby
+Edgeway.logger.info("order placed", order_id: 42, total: 12.5)
+Edgeway.logger.error("payment failed", order_id: 42)
 ```
 
-Its migrations are in `db/analytics/migrations` (`migrations_dir` of its `[[d1_databases]]`; apply them per database).
-A name is lowercase letters, digits and `_`, and not `primary`; `binding:` is required.
-The extra databases use the environment's adapter.
-`sessions: true` next to `binding:` (in the environment for the primary, in the entry for another) turns on D1 Sessions for it; see "Read replication (Sessions)".
-
-`database_id` is not a secret: it only names the database, and using it takes an API token of the account,
-so it is committed with `wrangler.toml` as Cloudflare's own examples do.
-Secrets the app needs go in Worker secrets (`pnpm exec wrangler secret put NAME`),
-which the app reads with `Edgeway.config("NAME")`.
-
-Not every Worker variable reaches the app. Only these are passed into the wasm:
-
-- the framework's own settings (`JWT_ISSUER`, `JWT_AUDIENCE`, `JWT_LEEWAY`, `JWT_ALGORITHMS`, `JWT_JWKS_URL`)
-- the variables whose name starts with `APP_`
-
-Name your own settings `APP_...` (`APP_PAGE_SIZE = "20"` in `[vars]`, `Edgeway.config("APP_PAGE_SIZE", "20")` in Ruby),
-and likewise your secrets (`wrangler secret put APP_NAME`).
-Anything else, such as a key the Worker holds for another purpose, is never visible to the app.
-`JWT_SECRET` is never passed.
+- `debug`, `info`, `warn` and `error` take a message and optional fields (a Hash, or `key: value`).
+- Each call writes one line to stderr, a JSON object: `{"level":"info","message":"order placed","order_id":42,"total":12.5}`.
+  Field names are Strings or Symbols; values are Strings, numbers, `true`/`false`, `nil`, or Arrays/Hashes of them.
+  `level` and `message` can't be fields.
+- `LOG_LEVEL` (`debug`, `info`, `warn`, `error`; default `info`) is the lowest level written. An unknown value counts as `info`.
+  Set it in `[vars]` of `wrangler.toml`.
+- The runtime sends each line to `console.<level>` as an object, so every line is one Workers Logs entry at its level, with its fields indexed.
+  It adds `ray` (the `cf-ray` header, when there is one). A field of the same name that the app logs wins over it.
+- Other stderr text (Spinel's runtime messages, a trap) goes out as text at error level.
+- Turn Workers Logs on with `[observability]` `enabled = true` in `wrangler.toml` (`edgeway new` writes it).
+  It records at most 256 KB of log data per request; nothing beyond that is kept.
+- `Edgeway::Application` logs the rescued errors (401, 404, 409, 429 at `info`, 503 and 500 at `error`) with a `status` field.
+- `edgeway test` with a local D1 prints a structured line as text, `[edgeway] INFO order placed order_id=42 total=12.5`.
+  A native build (`adapter: memory`) writes the JSON lines as they are.
+- `Edgeway.logger =` replaces the logger (an object with the four methods, each `(message, fields = {})`), as the framework's tests do.
 
 ## Authentication
 
 Edgeway verifies JWTs that an external IdP issued (Auth0, Firebase, Cognito, ...) and that come in `Authorization: Bearer`;
 it does not issue them.
 
-- Cloudflare Access, which sends its token in `Cf-Access-Jwt-Assertion`, is not supported in the first release,
+- Cloudflare Access, which sends its token in `Cf-Access-Jwt-Assertion`, is not supported,
   nor are Cognito access tokens, which carry `client_id` instead of `aud` (Cognito ID tokens work).
 - `sub` is required and must be a non-empty string.
 - `auth_time`, when present, must not be in the future (leeway applies).
@@ -583,19 +631,29 @@ Without a valid `Authorization: Bearer <token>`, the request is answered 401 wit
 - a bad token: `{"error":"invalid token"}` with `WWW-Authenticate: Bearer error="invalid_token"` (`Edgeway::InvalidToken`)
 
 `rescue_from` them to answer differently.
-The reason ("token expired", "unknown kid", ...) is only in the log (stderr), never the token,
+The reason ("token expired", "unknown kid", ...) is only in the log, never the token,
 so a client learns nothing from the wording.
 
 Settings are Worker variables in `wrangler.toml`, and the secret is a Worker secret (`.dev.vars` locally):
 
 | Variable | |
 |---|---|
+| `JWT_ISSUER`, `JWT_AUDIENCE` | **required**: the token's `iss` and `aud` must match |
 | `JWT_ALGORITHMS` | allowed algorithms, comma-separated (default `RS256`; `HS256/384/512`, `RS*`, `PS*`, `ES256/384`, `EdDSA`). `none` is never accepted |
-| `JWT_JWKS_URL` | the IdP's JWKS, for the asymmetric algorithms. Must be `https` (`http` only for `localhost`, `127.0.0.1`, `[::1]`), otherwise the request is answered 500. Cached for 10 minutes, fetched again when a `kid` is unknown (at most every 30 seconds); an expired JWKS is never used, so when the fetch fails the answer is 500. The fetch has a 5 second timeout, follows no redirect, needs status 200 and a body of at most 64 KB. A token needs a `kid`; a JWK with `key_ops` must list `verify` |
-| `JWT_SECRET` | the shared secret, for `HS*` (a secret; it never enters the wasm). At least 32 bytes for `HS256`, 48 for `HS384`, 64 for `HS512` (UTF-8 bytes, RFC 7518 3.2), otherwise the request is answered 500 |
-| `JWT_ISSUER`, `JWT_AUDIENCE` | **required**: `iss` and `aud` of the token must match. If either is empty the request is answered 500 (a misconfiguration, details only in the log), never let through; a token without `iss` or `aud` is 401. Without them a token the IdP issued for another API would pass: Firebase's signing keys are shared by all Firebase projects (so any project's user token), and an Auth0 Management API token of the same tenant. Applies to every algorithm, `HS*` too |
-| `JWT_LEEWAY` | seconds of clock skew allowed for `exp`, `nbf`, `iat` and `auth_time` (default 5; `0` for none; a whole number up to 300, anything else is answered 500) |
-
+| `JWT_JWKS_URL` | the IdP's JWKS, for the asymmetric algorithms |
+| `JWT_SECRET` | the shared secret, for `HS*` (a Worker secret; it never enters the wasm) |
+| `JWT_LEEWAY` | seconds of clock skew allowed for `exp`, `nbf`, `iat` and `auth_time` (default 5, up to 300) |
+
+A misconfigured setting answers every request 500, with the details only in the log; a request is never let through.
+
+- `JWT_ISSUER` and `JWT_AUDIENCE` apply to every algorithm, `HS*` too. Without them a token the IdP issued for another API would pass:
+  Firebase's signing keys are shared by all Firebase projects, and Auth0 signs its Management API tokens with the tenant's keys.
+  A token without `iss` or `aud` is 401.
+- `JWT_JWKS_URL` must be `https` (`http` only for `localhost`, `127.0.0.1`, `[::1]`).
+  The JWKS is cached for 10 minutes and fetched again when a `kid` is unknown (at most every 30 seconds); an expired one is never used.
+  The fetch has a 5 second timeout, follows no redirect, and needs status 200 and a body of at most 64 KB.
+  A token needs a `kid`, and a JWK with `key_ops` must list `verify`.
+- `JWT_SECRET` must be at least 32 bytes for `HS256`, 48 for `HS384` and 64 for `HS512` (RFC 7518 3.2).
 - `exp` is required, and a token with a `crit` header is refused (no extension is understood, RFC 7515 4.1.11).
 - In tests, use `Edgeway::Auth::StubVerifier` (`edgeway/http/auth/stub`; see `test/auth.rb`).
 - Like D1, this needs JSPI.
@@ -621,19 +679,291 @@ Settings are Worker variables in `wrangler.toml`:
 
 | Variable | |
 |---|---|
-| `CORS_ORIGINS` | allowed origins, comma-separated, compared as exact strings with the request's `Origin` (`https://app.example, http://localhost:3000`; no trailing slash). `*` allows any origin. Unset or empty means CORS is off: nothing is added and `OPTIONS` goes to the app. The origin `null` (sandboxed iframes, `file:` pages) is never allowed, even with `*` |
-| `CORS_HEADERS` | request headers a preflight allows (default `Authorization, Content-Type`). Listed one by one, as `*` does not cover `Authorization`. `X-D1-Bookmark` is added when a database has `sessions: true` |
-| `CORS_MAX_AGE` | seconds a browser may cache a preflight (default `600`). Not a non-negative integer: every request is answered 500, as with a bad JWT setting |
-| `CORS_EXPOSE_HEADERS` | response headers the page may read (`Access-Control-Expose-Headers`, e.g. `X-Total-Count`); none by default, except `X-D1-Bookmark` when a database has `sessions: true` (it is also merged into the app's own `Access-Control-Expose-Headers`) |
-
+| `CORS_ORIGINS` | allowed origins, comma-separated (`https://app.example, http://localhost:3000`), or `*` for any. Unset or empty turns CORS off |
+| `CORS_HEADERS` | request headers a preflight allows (default `Authorization, Content-Type`) |
+| `CORS_MAX_AGE` | seconds a browser may cache a preflight (default `600`) |
+| `CORS_EXPOSE_HEADERS` | response headers the page may read (e.g. `X-Total-Count`) |
+
+- Origins are compared as exact strings with the request's `Origin` (no trailing slash). The origin `null` (sandboxed iframes, `file:` pages)
+  is never allowed, even with `*`. With CORS off, nothing is added and `OPTIONS` goes to the app.
+- List `CORS_HEADERS` one by one: `*` does not cover `Authorization`.
+- `Retry-After` is always exposed. With `sessions: true`, `X-D1-Bookmark` is added to the allowed and exposed headers.
+- A `CORS_MAX_AGE` that is not a non-negative integer answers every request 500, as a bad JWT setting does.
 - A preflight from an allowed origin is answered 204 with `Access-Control-Allow-Origin` (the request's origin),
   `Access-Control-Allow-Methods` (`GET, HEAD, POST, PUT, PATCH, DELETE`), `Access-Control-Allow-Headers` and `Access-Control-Max-Age`.
 - A preflight from another origin is 403 `{"error":"origin not allowed"}`.
 - Other responses get `Access-Control-Allow-Origin` when the `Origin` is allowed, and `Origin` is added to `Vary`.
+- Files in `public/` are answered before the Worker, so they get no CORS headers and a preflight to one is 405 (see [Static assets](#static-assets)).
 - Cookies (credentials) are not supported: `Access-Control-Allow-Credentials` is never sent,
   and a token that `fetch` puts in `Authorization` does not need it.
 
-Serving the frontend from the same origin as the API avoids CORS altogether.
+Serving the frontend from the same origin as the API (see [Static assets](#static-assets)) avoids CORS altogether.
+
+## HTTP caching
+
+```ruby
+class TodosController < ApplicationController
+  def show
+    todo = Todo.find(params["id"])
+    render json: todo if stale?(etag: todo, last_modified: todo.updated_at)
+  end
+
+  def index
+    todos = Todo.order(:id)
+    render json: todos if stale?(etag: todos)
+  end
+
+  def settings
+    expires_in 300, public: true
+    render json: { "theme" => "dark" }
+  end
+end
+```
+
+- `stale?(etag:, last_modified:, public: false)` sets the validators and answers `304 Not Modified` (empty body; `Content-Type` is dropped)
+  when the request's `If-None-Match` / `If-Modified-Since` match; it returns `false` then, so the action stops. `fresh_when` is the same
+  and returns `true` when it answered 304.
+- `etag:` takes a model (its class, `id` and `updated_at`; a model without `updated_at` raises `ArgumentError`), a `Relation` or an Array of them (each element counts, in order),
+  or anything else (its `to_s`). The header is a weak `ETag: W/"<32 hex digits>"` (a proxy may recompress the body and weaken a strong one).
+- The ETag depends only on what you pass, not on the JSON an action renders. When a deploy changes what an action renders for the same record,
+  add a version to the source (`stale?(etag: [todo, "v2"], ...)`), or clients keep the old shape through 304 until the record changes.
+- Cross-origin JavaScript that handles ETags itself needs `If-None-Match` in `CORS_HEADERS` and `ETag` in `CORS_EXPOSE_HEADERS`
+  (see [CORS](#cors)); the browser's own cache revalidation needs neither.
+- `last_modified:` takes a `Time` or an ISO 8601 String (a model's `updated_at`); anything else is an `ArgumentError`.
+- Freshness: when `If-None-Match` is present it alone decides (weak comparison; a list, or `*` when the action has an ETag) and
+  `If-Modified-Since` is ignored; otherwise the response is fresh when `Last-Modified` is not later than `If-Modified-Since`
+  (HTTP-date only; one that does not parse is stale). Only GET and HEAD are answered 304; other methods get the headers only.
+- Only the validators you give are used; Edgeway does not derive an ETag from the body.
+- Unless the action set `Cache-Control` already (`expires_in`, `no_store` or `headers["Cache-Control"]`), `fresh_when` sets
+  `max-age=0, private, must-revalidate` (`public` with `public: true`). Without a `Cache-Control`, a shared cache may keep the response by heuristic.
+- `expires_in(seconds, public: false, must_revalidate: false)` sets `Cache-Control: max-age=N, private` (or `public`, and `, must-revalidate`);
+  `seconds` must be a non-negative Integer. `no_store` sets `Cache-Control: no-store`.
+
+Cloudflare's Workers Cache (opt-in: `[cache] enabled = true` in `wrangler.toml`, wrangler 4.69.0 or later) sits in front of the Worker.
+Edgeway does not enable it. If you do:
+
+- A `public` response with `max-age` is served from the cache without running the app, so `before_action :authenticate!` does not run for it.
+  A request with an `Authorization` header bypasses the cache unless the response is `public`, `must-revalidate` or has `s-maxage`.
+- `private` and `no-store` responses bypass it.
+- A response with no `Cache-Control` is cached by heuristic (a 200 for 2 hours).
+
+## Caching
+
+`Edgeway.cache` is a cache store like Rails' `Rails.cache`:
+
+```ruby
+class TodosController < ApplicationController
+  def stats
+    stats = Edgeway.cache.fetch("todo-stats", expires_in: 300) do
+      { "open" => Todo.where(done: false).count, "done" => Todo.where(done: true).count }
+    end
+    render json: stats
+  end
+
+  def show
+    todo = Todo.find(params["id"])
+    render json: Edgeway.cache.fetch(todo) { todo.as_json }
+  end
+end
+```
+
+- `read(key)` answers the value, or `nil` for a miss. `write(key, value, expires_in: nil)` and `delete(key)` answer `true`, or `false` when the store failed.
+  `exist?(key)` is true for an entry, also one that holds `nil`.
+- `fetch(key, expires_in: nil, force: false, skip_nil: false) { ... }` answers the cached value, or runs the block, stores its value and answers it.
+  `force: true` always runs the block. A `nil` is cached like any value; with `skip_nil: true` a `nil` from the block is not stored.
+  Without a block, `fetch` is `read` (with `force: true` it raises `ArgumentError`). A `delete` answers `true` also when there was nothing to delete.
+- Values are JSON values: a String (valid UTF-8), Integer, Float (finite), `true`, `false`, `nil`, and Arrays and Hashes of them.
+  Anything else (a Time, a model, a String that is not valid UTF-8, which includes a binary String such as `"\xFF".b`) raises `ArgumentError`; put `todo.as_json` in the cache, not the model.
+  A Hash comes back with String keys.
+- Keys: a String, Symbol or Integer is used as it is (any other type raises `ArgumentError`, and so does a key that is not valid UTF-8 or has a NUL byte); an Array is joined with `/`; a model is `"<table>/<id>-<updated_at>"`, so updating
+  the record makes a new key instead of needing a delete (a model without `updated_at` raises `ArgumentError`).
+  A key must not be blank. A key over 512 bytes is cut and ends with the SHA256 of the whole key, so two long keys that share a start stay apart.
+- `expires_in:` is a whole number of seconds, 1 to 31,536,000 (a year); anything else raises `ArgumentError`. The store checks it on every read, to the second.
+  Without `expires_in:` (and without a default from `config/cache.yml`) an entry stays until it is deleted, or the backend drops it.
+- A store failure never fails the request: it is logged at `warn` (with the binding and the operation, not the key), a read is a miss,
+  and `write` and `delete` answer `false`. An explicit `expires_in: nil` is the same as leaving it out: the store's default from `config/cache.yml` applies (unlike Rails, where it means no expiry).
+- `Edgeway.cache = store` replaces the store.
+
+### Stores
+
+| `store:` | Class | Entries |
+| --- | --- | --- |
+| `null` (the default) | `Edgeway::Cache::NullStore` | not kept: `fetch` always runs its block |
+| `memory` | `Edgeway::Cache::MemoryStore` | in the process: in a Worker, for one request |
+| `kv` | `Edgeway::Cloudflare::KVStore` | in a Cloudflare KV namespace |
+
+### config/cache.yml
+
+For each environment (`edgeway build --env ENV`):
+
+```yaml
+production:
+  store: kv
+  binding: CACHE        # a [[kv_namespaces]] binding in wrangler.toml; required for kv
+  namespace: myapp      # optional: every key starts with "myapp:"
+  expires_in: 3600      # optional: the seconds for a call that gives no expires_in:
+```
+
+Without the file, or a section for the environment, the store is `null`. `store: null` (also written without quotes) is the same.
+`edgeway build` writes the matching `Edgeway.cache = ...` line into `build/main.rb`, and links the KV backend only for `store: kv`.
+
+The binding is declared in `wrangler.toml` (`edgeway new` writes this commented out):
+
+```toml
+[[kv_namespaces]]
+binding = "CACHE"
+id = "<namespace id>"
+```
+
+Create the namespace with `pnpm exec wrangler kv namespace create CACHE`. `wrangler dev` simulates it locally.
+A `kv` store that names a binding the Worker does not have fails every operation (logged, read as a miss).
+
+### KV
+
+- KV drops an entry when its `expirationTtl` passes, and its minimum is 60 seconds. For an `expires_in:` under 60 the store asks KV for 60 and
+  checks the exact time itself on read, so `expires_in: 10` still means 10 seconds.
+- KV is eventually consistent: a write or delete is seen at once in the same location, and in other locations up to 60 seconds later
+  (last write wins). Prefer keys that change with the data (a model as the key, or a version in an Array key) over deleting a key and expecting every location to miss.
+- Writes to the same key are limited to 1 per second (more is a 429, which is logged and answered `false`).
+- The Free plan allows 1,000 writes, 1,000 deletes and 100,000 reads a day, and a Worker invocation can make 1,000 KV operations.
+  Each `fetch` is one read, and one write on a miss; a `delete` counts against the deletes.
+- A key is at most 512 bytes (handled by the store) and a value at most 25 MiB. KV refuses the keys `.` and `..`, so the `kv` store raises `ArgumentError` for them.
+- Like D1, this needs JSPI.
+
+### In tests
+
+`Edgeway.cache` is a `NullStore` in every test (`edgeway test`), whatever `config/cache.yml` says, so tests do not depend on each other.
+A test of caching sets a store itself:
+
+```ruby
+class StatsTest < Edgeway::IntegrationTest
+  def test_second_request_is_cached
+    Edgeway.cache = Edgeway::Cache::MemoryStore.new
+    get "/stats"
+    Todo.create!(title: "new")
+    get "/stats"
+    assert_equal 0, json["open"]
+  end
+end
+```
+
+## Outbound HTTP
+
+```ruby
+response = Edgeway::HTTP.get("https://api.example/items", headers: { "Authorization" => "Bearer #{token}" })
+response = Edgeway::HTTP.post("https://api.example/items", body: JSON.generate({ "name" => "a" }),
+                              headers: { "Content-Type" => "application/json" }, timeout: 5)
+response.status     # Integer
+response.success?   # 2xx
+response.headers    # Hash, names in lower case
+response.body       # String
+response.json       # the body parsed
+```
+
+- `get` and `delete` take `headers:`; `post`, `put` and `patch` also take `body:` (a String, empty by default).
+  All take `timeout:` in seconds (default 10; from 0.001 to 300, otherwise `ArgumentError`).
+  A `body:` must be UTF-8 text; binary uploads are not supported.
+- The answer is an `Edgeway::HTTP::ClientResponse`. A non-2xx status does not raise.
+- Redirects are not followed: a 3xx comes back as it is, with its `location` header.
+- Of repeated response headers only the last `Set-Cookie` is kept; other repeated headers are joined with ", ".
+- The URL must be `https` (`http` only for `localhost`, `127.0.0.1`, `[::1]`); any other is an error.
+- The response body is at most 1 MB; a larger one is an error. A binary body keeps its bytes but is labelled UTF-8 (`body.b` has the bytes).
+- `Edgeway::HTTP::Error` is raised for a network failure, a refused URL and a response that is too large;
+  `Edgeway::HTTP::Timeout` (a subclass) when the timeout passes. Unrescued they are a 500, with the message only in the log.
+- A Worker can make 50 subrequests per invocation on the Free plan and 10,000 by default on Paid,
+  and has at most 6 connections open at once.
+- Like D1 and the JWT check, this needs JSPI.
+- In tests, `stub_http` (see [Writing tests](#writing-tests)) stands in for the network, so no test makes a request.
+
+## Rate limiting
+
+```ruby
+class PostsController < ApplicationController
+  before_action :authenticate!
+  rate_limit "WRITE_LIMITER", only: [:create, :update, :destroy], retry_after: 10
+end
+```
+
+The limit and the period are set on the binding in `wrangler.toml`, where Cloudflare reads them (the period is 10 or 60 seconds only; `namespace_id`
+is a positive integer, as a string, unique in your account):
+
+```toml
+[[ratelimits]]
+name = "WRITE_LIMITER"
+namespace_id = "1001"
+  [ratelimits.simple]
+  limit = 100
+  period = 60
+```
+
+`wrangler dev` enforces the limit locally. `edgeway new` writes this commented out. It needs wrangler 4.36.0 or later (the generated app pins a newer one).
+
+`rate_limit` is a `before_action` (run in declaration order), like Rails' `rate_limit`:
+
+```ruby
+rate_limit "API_LIMITER", by: :rate_limit_key, name: nil, retry_after: nil, only: [...], except: [...]
+```
+
+- The first argument is the binding name. A controller can have several, such as a 10 second and a 60 second binding.
+- A request over the limit raises `Edgeway::TooManyRequests`: the answer is 429 with `{"error":"rate limit exceeded"}`.
+  `rescue_from Edgeway::TooManyRequests` answers otherwise; the error has `retry_after` (0 without `retry_after:`).
+- `Retry-After` is sent only with `retry_after:` (a positive Integer, in seconds): the binding does not tell when the count resets.
+- The key is `"<name>:<by>"`. `name:` defaults to the controller's class name, so every controller has its own count; give several controllers the same `name:` to share one.
+- `by:` is a Symbol naming a controller method (not a lambda) that answers the key's second part, such as `:current_account_id`.
+  That method is never a route's action, even if it is public.
+  Don't key on a value the client sends (a header, a parameter): the client could pick a fresh count with every request.
+- Without `by:`, the key is `"user:<sub>"` for a request that passed `authenticate!`, and otherwise `"ip:<client address>"`
+  (`request.remote_addr`, from `CF-Connecting-IP`).
+  An IPv6 address is keyed by its /64 prefix (`2001:db8:1:2::/64`), and an IPv4-mapped one (`::ffff:192.0.2.1`) by its IPv4 address.
+- Order matters: a `rate_limit` declared after `before_action :authenticate!` never sees a request that `authenticate!` rejects (401), so token probing is not counted.
+  Declare an IP-keyed limit before `authenticate!` (it sees every request) and, if wanted, a per-user limit after it:
+
+  ```ruby
+  rate_limit "IP_LIMITER"       # before authenticate!: no user is known yet, so the key is the IP; 401s are counted
+  before_action :authenticate!
+  rate_limit "USER_LIMITER"     # after: the key is the user's sub
+  ```
+
+- An empty key part (no client address, or a `by:` method answering `nil` or `""`) puts every such request in one shared count.
+- The binding gets a SHA256 digest of the key, so the key is never sent as it is, and any bytes are safe in it.
+- `wrangler dev` passes a `CF-Connecting-IP` sent by the client through, so a local test of the IP key can be spoofed; in production Cloudflare sets it.
+- Cloudflare warns that an IP address can be shared by many users (a company, a mobile carrier), and that a limit on it can block them all.
+  Prefer a stable identifier such as a user or an API key.
+- The key is never logged.
+
+Counts are kept per Cloudflare location and are eventually consistent, so they are approximate: a burst can get past the limit,
+and a client in another location has its own count. For a strict limit use a Durable Object. The limit is not shown in the Cloudflare dashboard;
+look for the 429s in the logs.
+
+A binding the Worker does not have (a typo in the name), or a value that has no `limit` function, is a misconfiguration:
+the request raises `Edgeway::ConfigurationError` (500, the details only in the log), like a missing `JWT_ISSUER`, so a typo cannot switch limiting off silently.
+Any error thrown by `limit()` itself lets the request through (fail open), including a binding of another kind that happens to have the name: it logs `rate limit check failed` with the `binding` and the `error`, and the request goes on.
+
+Like D1, this needs JSPI.
+
+### In tests
+
+No test is limited by default. A test turns a limit on for a binding, and reads the checks the app made:
+
+```ruby
+class PostsControllerTest < Edgeway::IntegrationTest
+  def test_over_the_limit
+    stub_rate_limit("WRITE_LIMITER", exceeded: true)
+    post "/posts", json: { post: { title: "a" } }
+    assert_response 429
+    assert_equal "WRITE_LIMITER", rate_limit_checks.first[0]   # [[binding, key], ...]
+  end
+end
+```
+
+The stub and the recorded checks start empty in every test.
+
+A request has no client address unless the test gives one, so the default key is `ip:`; `remote_addr:` sets it for that request only:
+
+```ruby
+get "/posts", remote_addr: "203.0.113.7"
+assert_equal "PostsController:ip:203.0.113.7", rate_limit_checks.first[1]
+```
 
 ## Testing an app
 
@@ -643,6 +973,9 @@ bin/test [FILE...]                # in a generated app: the same, all of test/ w
 ```
 
 `edgeway test` is the only supported way to run an app's tests.
+`config/database.yml` decides how: with `adapter: d1` in its `test:` section (what `edgeway new` writes)
+the tests are compiled to wasm32-wasi and run on a local D1, as in production; with any other adapter
+(`memory`) they are a native build with an in-memory SQLite database (see [SQLite](#sqlite-adapter-memory-in-test)).
 
 - `spinel_test-unit` is the test framework (on RubyGems;
   `edgeway new` puts `gem "spinel_test-unit", "~> 0.1", group: :test` in the Gemfile).
@@ -654,16 +987,53 @@ bin/test [FILE...]                # in a generated app: the same, all of test/ w
 
 - Tests `require "edgeway/test"` in `test/test_helper.rb`.
 - Model tests inherit `Edgeway::UnitTest` (the database, no requests).
-- `Edgeway::IntegrationTest` inherits it and adds `get`/`post`/..., `json` and `assert_response`.
+- `Edgeway::IntegrationTest` inherits it and adds `get`/`post`/..., `json` and `assert_response`. `get`/`post`/... take `json:`, `headers:` and `remote_addr:` (the client address, for that request only).
 - Both inherit `SpinelTest::Unit::TestCase`.
 
-Each test runs against a real in-memory SQLite database (`Edgeway::DB::SQLiteAdapter`, through Spinel's FFI)
-with `db/migrations/*.sql` applied in file name order, so requests really write and read rows.
-Each database under `databases:` (in any environment) gets its own, with `db/NAME/migrations`; `db(:analytics)` answers it, and `db` the primary.
+Outgoing HTTP (see [Outbound HTTP](#outbound-http)) never reaches the network in a test:
 
-### SQLite
+```ruby
+stub_http(:get, "https://api.example/items", status: 200, body: '{"items":[]}', headers: { "Content-Type" => "application/json" })
+stub_http_error(:post, "https://api.example/items", "connection refused")          # raises Edgeway::HTTP::Error
+stub_http_error(:post, "https://api.example/items", "timed out", timeout: true)    # raises Edgeway::HTTP::Timeout
+http_requests   # the requests sent, in order: Hashes with "method", "url", "headers", "body" and "timeout_ms"
+```
 
-Running the tests requires SQLite (sqlite3). This needs the SQLite library at link time:
+- A request is matched on its method and exact URL; one without a stub raises `Edgeway::HTTP::UnstubbedRequest`.
+- The stubs and the recorded requests start empty in every test.
+- This is plain Ruby, so it works in the native and the wasm builds alike.
+- `Edgeway.cache` is a `NullStore` in every test (see [Caching](#caching)); a test of caching sets a `MemoryStore` itself.
+- `stub_rate_limit` and `rate_limit_checks` stand in for the limiter (see [Rate limiting](#rate-limiting)); no request is limited unless a test says so.
+
+Each test starts from an empty database with `db/migrations/*.sql` applied in file name order
+(so the migrations' seed rows are there), and requests really write and read rows.
+Each database under `databases:` gets its own, with `db/NAME/migrations`; `db(:analytics)` answers it, and `db` the primary.
+`db.log` has the SQL the test ran.
+
+### Local D1 (`adapter: d1` in `test:`)
+
+The tests are built like the app (`--target=wasm32-wasi`, with `--incremental`; the wasm is `tmp/test_app.wasm`) and run by Node.js
+(`js/cloudflare-test-runner.js`, copied to `tmp/edgeway/` with the other `js/` files) on the D1 that wrangler's `getPlatformProxy` starts,
+the one `wrangler dev` uses, but in memory (`persist: false`): `.wrangler/state` is never touched.
+
+- Before each test every table and view is dropped (except `sqlite_*`, `_cf_*` and `d1_migrations`) and the migrations are applied again,
+  so a test cannot see another's rows and the ids start from 1.
+  Foreign keys are enforced as in D1.
+- The bindings are the `binding:` of `test:` and of its `databases:`, which must exist in `wrangler.toml`.
+  Give each its own `database_id`: bindings with the same id are the same local database.
+  Databases that share a binding are one database: it is emptied once and the migrations of each are applied, the primary's first.
+  Only the databases in `test:` exist in the tests (not those of other environments).
+- The Worker variables of `wrangler.toml` (`JWT_*`, `APP_*`) are the app's settings, as in production.
+- Needs Node.js 24 or later (`edgeway test` passes `--experimental-wasm-jspi --experimental-wasm-exnref` to Node.js 24, which needs them),
+  wrangler in `node_modules` (`pnpm install`, or `bin/setup`), `wrangler.toml`, the WASI SDK (`WASI_SDK`) and Spinel.
+  It stops with the fix when one is missing.
+- The first build of an app takes a while; later ones reuse Spinel's cached C units.
+
+### SQLite (`adapter: memory` in `test:`)
+
+The tests are a native build with a real in-memory SQLite database per test (`Edgeway::DB::SQLiteAdapter`, through Spinel's FFI).
+Every database under `databases:` (in any environment) gets one.
+This needs the SQLite library at link time:
 `libsqlite3-dev` on Debian/Ubuntu, `sqlite-devel` on Fedora (preinstalled on macOS).
 
 - `edgeway test` first tries to link `-lsqlite3` with `$CC` (or `cc`/`gcc`/`clang`) and stops with the fix if that fails.
@@ -674,22 +1044,50 @@ Edgeway's own tests use `MemoryAdapter`, which stores nothing; `SQLiteAdapter` i
 
 ### Differences from production
 
-The tests are native builds, while production is wasm32-wasi on Workers.
+With a local D1 the tests are wasm on a D1 as in production, and JSPI and `Edgeway::Cloudflare::D1Adapter` are exercised.
+What differs:
+
+- It is wrangler's local D1 (miniflare), not Cloudflare's: its limits and timing are not reproduced, and neither is read replication
+  (`sessions: true` is passed on, but there is one local replica).
+- The app is called directly (`get`, `post`), not through `js/cloudflare.js` and the Worker: no CORS, no `X-D1-Bookmark`.
+- A JWT's signature is checked only when the test sets `Edgeway::Auth.verifier = Edgeway::Cloudflare::JWTVerifier.new`
+  (`JWT_SECRET` and the like come from the Worker variables, `.dev.vars` included); otherwise use `Edgeway::Auth::StubVerifier`.
+- `db.log` has the SQL the test ran, but not the migrations'.
+
+With SQLite the tests are native builds, while production is wasm32-wasi on Workers.
 
 - D1 (`Edgeway::Cloudflare::D1Adapter`) and JSPI are not exercised,
   and neither is a JWT's signature check (use `Edgeway::Auth::StubVerifier`).
-- `SQLiteAdapter` is loaded only by `edgeway/test`: `edgeway build` never requires `edgeway/db/sqlite`,
+- `SQLiteAdapter` is loaded only by `edgeway test`: `edgeway build` never requires `edgeway/db/sqlite`,
   because libsqlite3 can't be linked into the wasm.
 - SQLite and D1 (itself SQLite) take the same SQL, but D1's own limits
   (such as the number of bound parameters) are not reproduced.
 
+## Known limitations
+
+- Only the subset of Ruby that Spinel supports can be used.
+- `has_many` does not work with namespaced models (`Admin::Post`);
+  `belongs_to` and `has_many` look models up by their full name, and that case is not handled.
+- Cloudflare Access is not supported: its token comes in `Cf-Access-Jwt-Assertion`,
+  and only `Authorization: Bearer` is read (see [Authentication](#authentication)).
+- Tests call the app directly, not through the Worker, so CORS and `X-D1-Bookmark` are not covered.
+  With `adapter: memory` in `test:` they are a native build, and D1 and JSPI are not covered either (see [Testing an app](#testing-an-app)).
+- Not verified on a production Cloudflare deploy yet: CPU and wall time on a cold start and on a JWKS cache miss,
+  and read replication with real replicas (local D1 has none, and D1 itself accepts any bookmark there). Everything was checked under `wrangler dev`.
+- Integers are 32 bits in a wasm build: use `:bigint` for larger ones and pass them as Strings,
+  and keep them below 2^53, as D1 hands rows over as JavaScript numbers (see [Attribute types](#attribute-types)).
+- A `Model.batch` runs on one database: there is no transaction across databases ([Multiple databases](#multiple-databases)).
+- `Model.exec` does not work on a database with `sessions: true`: a D1 session has no `exec()` ([Queries](#queries)).
+- Spinel can't build a Range of Times: use ISO 8601 Strings or a SQL fragment in `where` ([Queries](#queries)).
+- `first()` and `raw()` are not used and `dump()` is not supported; Time Travel and export/import are `wrangler d1` commands ([D1 API coverage](#d1-api-coverage)).
+
 ## Development
 
 ```sh
 # mise install (Spinel, the WASI SDK) and bundle install
 bin/setup
 
-# needs libsqlite3-dev (test/spinel/sqlite.rb);
+# needs libsqlite3-dev (test/spinel/sqlite.rb) and, for the Node.js tests, node;
 # runs test/*.rb under CRuby and as Spinel native builds, and compares with .expected
 bundle exec rake test