edgeway 0.1.0 → 0.3.0

data/README.md

@@ -38,27 +38,221 @@ end
 
 ## Contents
 
+- [Usage](#usage)
+  - [Generators](#generators)
+  - [Building](#building)
+  - [Spinel version](#spinel-version)
+- [Configuration](#configuration)
 - [Models](#models)
+  - [Attribute types](#attribute-types)
   - [Strong parameters](#strong-parameters)
   - [Uniqueness](#uniqueness)
+  - [Database errors](#database-errors)
   - [Ordering and deleting](#ordering-and-deleting)
+  - [Queries](#queries)
+  - [Query stats](#query-stats)
   - [Batch](#batch)
   - [Associations](#associations)
   - [Eager loading](#eager-loading)
-- [Usage](#usage)
-  - [Generators](#generators)
-  - [Building](#building)
-  - [Spinel version](#spinel-version)
-  - [Known limitations](#known-limitations)
-- [Configuration](#configuration)
+  - [Multiple databases](#multiple-databases)
+  - [Read replication (Sessions)](#read-replication-sessions)
+  - [D1 API coverage](#d1-api-coverage)
+- [Views](#views)
+- [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
+
+| Type | Ruby value | SQLite column | In JSON |
+| --- | --- | --- | --- |
+| `:string`, `:text` | String | TEXT | string |
+| `:integer` | Integer (32 bits) | INTEGER | number |
+| `:float` | Float | REAL | number |
+| `:boolean` | `true`/`false` | INTEGER (1/0) | `true`/`false` |
+| `:datetime` | String, ISO 8601 UTC | TEXT | string |
+| `:binary` | binary String (`.b`) | BLOB | base64 string |
+| `:bigint` | decimal String (`"3000000000"`) | INTEGER | 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"])`. 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.
@@ -92,6 +286,22 @@ Project.where(owner_id: uid).find_or_create_by(name: "default")
   the database's message (table and columns) goes only to the log.
 - A controller can `rescue_from Edgeway::RecordNotUnique` to answer otherwise.
 
+### Database errors
+
+All are `Edgeway::DatabaseError`; the database's message goes only to the log.
+
+- `NotNullViolation`, `InvalidForeignKey` and `CheckViolation` (a constraint the app broke):
+  answered 500 `{"error":"internal error"}`, like any other `DatabaseError`.
+- `DatabaseUnavailable` (D1 lost its connection, was reset or is overloaded):
+  answered 503 `{"error":"database unavailable"}` with `Retry-After: 1`.
+- A controller can `rescue_from` any of them to answer otherwise.
+  `rescue_from Edgeway::DatabaseError` also catches `DatabaseUnavailable` and `RecordNotUnique`,
+  so it replaces their default 503 and 409.
+- D1 retries read-only queries itself. Edgeway never retries a query, a write or a batch.
+- A write that got a 503 may still have been applied:
+  only an idempotent request (a GET, or a write the app made idempotent) is safe to retry.
+- Timeouts and CPU or memory limits stay a plain `DatabaseError` (500).
+
 ### Ordering and deleting
 
 ```ruby
@@ -115,6 +325,61 @@ class Todo < ApplicationModel
 end
 ```
 
+### Queries
+
+```ruby
+Todo.where(id: [1, 2])                    # id IN (?, ?)
+Todo.where(position: 1..5)                # position >= ? AND position <= ?
+Todo.where(position: (3..))               # position >= ?
+Todo.where("title LIKE ?", "%x%")         # (title LIKE ?)
+Todo.where("done = 1")
+
+Todo.find_by_sql("SELECT * FROM todos WHERE done = ?", [true])   # records
+Edgeway::Model.select_all("SELECT COUNT(*) AS n FROM todos", [])  # row Hashes
+Edgeway::Model.execute("DELETE FROM todos WHERE done = ?", [true]) # {"changes" => n, "last_insert_id" => id}
+Edgeway::Model.exec("DELETE FROM tags\nDELETE FROM todos")        # nil
+```
+
+- `where(column: value)` is `=`, `IS NULL` for `nil`. Every form chains, and works with `order`, `limit`, `count`, `delete_all`, `eager_load` and `todo.comments.where(...)`.
+- An Array is `IN`; each value is cast by the column type. An empty Array matches nothing (`1 = 0`).
+  A `nil` in an Array also matches `NULL`: `(position IN (?) OR position IS NULL)`.
+- A Range is `>=` and `<=` (`<` for `1...5`); an endless or beginless Range has one side.
+  Spinel can't build a Range of Times: use ISO 8601 Strings (`"2026-10-28"..."2026-10-29"`) or a fragment.
+- A String is a raw SQL fragment, in parentheses and ANDed with the rest; its binds follow it.
+  It is raw SQL: put user input in the binds, never interpolate it.
+  Its binds are not cast by column type: only booleans (1/0) and Times (ISO 8601) are converted.
+  An Array bind raises `ArgumentError` (not expanded): use `where(column: [...])`.
+- `build`/`create`/`find_or_create_by` on a relation copy only the plain equality conditions.
+- `find_by_sql` makes records of the rows, so select the model's columns (`SELECT *` or each of them): a missing one is `nil`.
+- `Model.select_all` and `Model.execute` take `?` placeholders. Booleans are bound as 1/0, and a Time as ISO 8601 UTC (`2026-10-28T05:00:00.000Z`, as timestamps are stored), also in `where` values.
+  `execute` is a write, so inside `Model.batch` it is queued (and answers 0 counts).
+- `Model.exec` is D1's `exec()`: one or more statements with no binds, and it answers `nil`. Meant for one-off maintenance, as D1 says.
+  A statement must fit on one line (D1 splits the text at newlines); `a; b` on one line also works. Empty SQL raises `ArgumentError`.
+  When a statement fails, none of them stay applied (seen on local D1; the SQLite adapter in tests does the same).
+  D1's error message names the first line, not the one that failed.
+  It can't run inside `Model.batch` (`ArgumentError`), and fails on a database with `sessions: true` (`DatabaseError`): a D1 session has no `exec()`.
+- D1 allows 100 bound parameters per statement: more raises `ArgumentError`, in every adapter (`limit` and `offset` are literals, not binds).
+  `where(id: ids)` with over 100 ids needs chunking.
+
+### Query stats
+
+`Edgeway::Model.query_stats` (it raises `ConfigurationError` without a connection) is what D1 reported for the queries of the current request
+(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).
+- `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 `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`:
+
+```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.
+
 ### Batch
 
 `Edgeway::Model.batch` makes several writes atomic.
@@ -179,129 +444,171 @@ Todo.eager_load(:comments, :tags)   # several at once, still one query
 - Only `to_a` and what is built on it (`each`, `map`, `size`) read the loaded records;
   `comments.where(...)`, `count` and `first` query as usual.
 
-## Usage
-
-```sh
-gem install edgeway
+### Multiple databases
 
-edgeway new myapp
-
-# mise, bundle, pnpm and the local D1 migrations
-cd myapp && bin/setup
+A model uses the primary database unless it names another, declared in `config/database.yml` (see [Configuration](#configuration)):
 
-# the app's tests, natively (needs libsqlite3-dev, see "Testing an app")
-bundle exec edgeway test
-
-# edgeway build: writes build/app.wasm and build/edgeway/ (the JS)
-bin/build
-
-pnpm exec wrangler dev
-edgeway routes
+```ruby
+class Event < ApplicationModel
+  self.database = :analytics   # inherited by subclasses
+  attribute :name, :string
+end
 
-# bin/build, remote D1 migrations, then pnpm exec wrangler deploy
-bin/deploy
+Event.create!(name: "signup")
+Edgeway::Model.select_all("SELECT COUNT(*) AS n FROM events", [], database: :analytics)
+Edgeway::Model.execute("DELETE FROM events", [], database: :analytics)
 ```
 
-`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.
-- 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
+- Every query and write of a model goes to its database, including `find_by_sql`.
+  `Model.select_all` and `Model.execute` use the primary unless given `database:`.
+- Associations between models on different databases work as separate queries.
+  A `has_many` with `dependent:` to a model on another database raises `ArgumentError` on `destroy`, before any query: it can't be atomic.
+  `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 logs one `query stats` line per database that ran queries,
+  with a `database` field for the ones other than the primary.
+
+### Read replication (Sessions)
+
+With D1 read replication enabled for a database (dashboard, or `PUT` its settings), reads can be served by a replica near the user.
+A replica may lag, so D1's Sessions API keeps a request sequentially consistent through a bookmark. Opt in per database in `config/database.yml`:
+
+```yaml
+production:
+  adapter: d1
+  binding: DB
+  sessions: true
+  databases:
+    analytics:
+      binding: ANALYTICS
+      sessions: true
 ```
 
-- 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: the command prints the route to add (`r.resources :todos`).
-
-### 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`).
+`sessions:` must be `true` or `false` (anything else fails the build), and does nothing with the `memory` adapter.
+Every query and `Model.batch` of such a database then goes through `env.DB.withSession(...)`, created on first use and kept for the request.
 
-### 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).
+- A `GET` or `HEAD` starts from the bookmark the client sent, else `first-unconstrained`, so it may read a replica. Other methods always start `first-primary` and ignore the sent bookmark.
+- The response has `X-D1-Bookmark: DB=<bookmark>, ANALYTICS=<bookmark>`: a `BINDING=bookmark` pair for each session the request used (also with one database).
+- A client that sends that header back as it is on its next request starts that session from the bookmark and so reads its own writes (`GET` and `HEAD` only). On a `GET` or `HEAD`, a binding that is not in the header starts `first-unconstrained`. A bookmark is D1's and opaque; one that does not look like it (not lowercase hex and `-`, or over 128 characters) is ignored, and not echoed.
+- A database the request did not use keeps the bookmark the client sent for it in the response (on any method), so the client just stores the latest header value whole and sends it back.
+- Responses of an app with sessions get `Vary: X-D1-Bookmark`.
+- With CORS on, `X-D1-Bookmark` is exposed to the page and allowed in preflights (no need to add it to `CORS_HEADERS` or `CORS_EXPOSE_HEADERS`).
+- `Edgeway::Model.query_stats(:analytics)` has `served_by_primary` and `served_by_region` of the last query, to see which one answered (`true` and `""` in `wrangler dev`, which has no replicas).
 
-- `mise.toml` (Edgeway's own and the one `edgeway new` writes) pins a commit of [matz/spinel](https://github.com/matz/spinel),
-  `530ba2b17`, 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).
+### D1 API coverage
 
-### Known limitations
+| D1 Worker API | In Edgeway |
+| --- | --- |
+| `prepare().bind().all()` | every query, `find_by_sql`, `Model.select_all`, and inserts (`INSERT ... RETURNING id`) |
+| `prepare().bind().run()` | updates and deletes, `Model.execute` |
+| `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 `query stats` log line |
+| `first()`, `raw()` | not used (`find_by`/`first` send `LIMIT 1` through `all()`) |
+| `dump()` | not supported (alpha databases only) |
 
-- 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.
-  Everything was checked under `wrangler dev`.
+Time Travel, export/import and migrations are `wrangler d1` commands, outside the Worker API.
 
-## Configuration
+## Views
 
-Two files configure the database, each for its own side:
+```ruby
+# app/controllers/todos_controller.rb
+class TodosController < ApplicationController
+  def index
+    @todos = Todo.order(:id).limit(50)
+    # renders app/views/todos/index.html.erb
+  end
+end
+```
 
-- `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`.
+```erb
+<%# app/views/todos/index.html.erb %>
+<ul>
+<% @todos.each do |t| -%>
+  <li><%= t.title %></li>
+<% end -%>
+</ul>
+```
 
-`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")`.
+Spinel has no `eval`, so `edgeway build` (and `edgeway test`) compile `app/views/**/*.html.erb` into Ruby
+(`build/views.rb`, `tmp/views.rb`): each template becomes a method of its controller,
+so it sees the action's `@variables`, `params` and the controller's methods.
+
+- `<%= expr %>` is HTML-escaped (`Edgeway::View.escape`) unless the value is `raw(text)` or `text.html_safe`
+  (an `Edgeway::View::SafeHTML`); `<%== expr %>` is never escaped.
+  Safety is not kept across string operations (`"<b>".html_safe + x` is not defined): build the HTML in a template,
+  or escape the pieces with `Edgeway::View.escape` and mark the result.
+  `<% code %>`, `<%# comment %>`, `<%%` (a literal `<%`) and `-%>` (drops the newline after the tag) work as in ERB.
+- The public methods of `Edgeway::Controller::Base` (`render`, `head`, `params`, `raw`, ...) are not actions; a route to one is a 404.
+- An action that renders nothing renders its template, or answers 204 when it has none.
+- `render :name` / `render "name"` renders another template of the controller, `render html: value` a string (HTML-escaped; a `SafeHTML` is output as is);
+  both take `status:` and `layout: false`.
+  A name with no template raises `Edgeway::MissingTemplate` (a 500).
+- `app/views/layouts/application.html.erb` wraps every HTML response, at `<%= yield %>`. `edgeway new` writes one.
+- HTML responses are `Content-Type: text/html; charset=utf-8` with `X-Content-Type-Options: nosniff`.
+- A template's directory names its controller (`app/views/admin/posts/` is `Admin::PostsController`);
+  one without a controller is a build error, and so is a syntax error in a template,
+  which Spinel reports in the generated file (its `# app/views/...:LINE` comments point back).
+
+Not supported yet: partials (`render partial:`), layouts other than `application`, and templates other than `.html.erb`.
+
+## 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/*"]
+```
 
-Not every Worker variable reaches the app. Only these are passed into the wasm:
+## Logging
 
-- the framework's own settings (`JWT_ISSUER`, `JWT_AUDIENCE`, `JWT_LEEWAY`, `JWT_ALGORITHMS`, `JWT_JWKS_URL`)
-- the variables whose name starts with `APP_`
+```ruby
+Edgeway.logger.info("order placed", order_id: 42, total: 12.5)
+Edgeway.logger.error("payment failed", order_id: 42)
+```
 
-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).
@@ -324,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.
@@ -362,27 +679,303 @@ 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` |
-| `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 |
-
+| `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
 
 ```sh
 bundle exec edgeway test [ARGS]   # ARGS go to spinel_test-unit
+bin/test [FILE...]                # in a generated app: the same, all of test/ without FILE
 ```
 
 `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).
@@ -394,15 +987,53 @@ bundle exec edgeway test [ARGS]   # ARGS go to spinel_test-unit
 
 - 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.
+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.
@@ -413,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