json-rest-api 1.0.29 → 2.1.0

package/docs/GUIDE/22-version-field-migrations.md

@@ -0,0 +1,208 @@
+---
+title: "Version-field migrations"
+chapter: 22
+chapter_label: "22"
+---
+
+# 22. Version-field migrations
+
+This explicit schema/data procedure is verified on SQLite, PostgreSQL and MySQL
+in both storage modes. The library implements revision conditions, membership
+invalidation and optional HTTP validators. Stored revisions and HTTP
+representation validators have different scopes; see the
+[API migration guide](33-migrating-to-v2.md) for their contracts. Apply this
+procedure to each application database before enabling conditional writes.
+
+## Choose the field deliberately
+
+Declare a stored string attribute, such as `revision`, and later select it with
+`versionField: 'revision'`. The field must be distinct from the primary ID and
+cannot have a getter, setter, storage serializer, computed/virtual behavior or
+relationship. The library creates opaque UUID tokens. Clients must compare and
+submit the entire token, without parsing, trimming or changing its case.
+
+Keep the selected output visibility explicit. A hidden revision remains hidden;
+enabling versioning does not expose it. Clients using conditional writes need
+an authorized way to read the revision. Full write responses or a subsequent
+GET can provide it; minimal and none responses do not promise a new token.
+
+## What changes a revision
+
+The revision tracks public resource writes and declared relationship membership.
+It is not a hash of the complete response and is not an HTTP ETag.
+
+| Operation | Revision behavior |
+| --- | --- |
+| POST or unconditional PUT-create | Initializes a fresh UUID. Reusing a deleted ID never reuses its old revision. |
+| PATCH or PUT-update | Assigns a fresh UUID, including unconditional writes and writes that submit unchanged attribute values. Clients must not treat tokens as operation counts. |
+| Conditional PUT-create | Fails as not found; a condition cannot match a nonexistent row. |
+| DELETE | Checks the supplied condition before deletion; surviving versioned relationship parents are invalidated. |
+| Public relationship mutation | Rotates the owner's revision and affected configured inverse revisions. Explicitly retained many-to-many targets may also receive new tokens. |
+| Child creation, reparenting, detachment or deletion | Rotates affected configured has-many/has-one parent revisions, including declared polymorphic inverses. |
+| Child attribute change with unchanged membership | Does not rotate the parent's revision merely because included child attributes changed. |
+| Ordinary pivot-resource write | Invalidates affected configured parents when either membership key changes. Canonical through-resource records remain separate from canonical links. |
+| Bulk PATCH or DELETE | Applies the same rules per child. Optional `expectedVersions` must contain one token per input entry. |
+| Transaction rollback | Restores revisions together with the associated writes and links. |
+
+Submit conditions through `expectedVersion`, not as an attribute update. Omitting
+the condition permits an unconditional write; versioning does not require every
+client to submit a token. JSON:API and plain formats use the same stored revision
+and preserve the field's visibility rules. SQL writers, triggers and transitive
+database cascades require application-owned revision maintenance; the library
+cannot infer their arbitrary effects on other resources or representations.
+
+Each successful write consumes the previous revision even inside one transaction.
+Use the returned revision for a second conditional write in that transaction;
+reusing the first token conflicts. Rolling back the transaction restores the
+revision that existed before its writes.
+
+## Prepare existing data
+
+Stop all writers, including old application instances, jobs and raw SQL writers.
+Take the application's normal backup. Keep writers stopped through field
+allocation, backfill, configuration deployment and readiness checks. Do not
+enable version conditions against partially migrated data.
+
+For ordinary Knex storage, add a nullable string column in an explicit schema
+migration. Resolve any declared physical column mapping rather than assuming
+the attribute and column names coincide. Allocate at least 128 characters if
+using VARCHAR. Do not set a single shared default revision for existing rows.
+Schema DDL and the data backfill are separate migration steps: transactional
+DDL support differs by database.
+
+For canonical storage, allocate a stored string field through `addKnexFields`
+on the unversioned resource. This records its canonical slot allocation; do not
+choose a `string_N` slot by inspection of empty record values. Read the resulting
+descriptor's `fields.revision.slot` and use that actual column for the backfill.
+Every canonical record query must include both `tenant_id` and `resource`, and
+pagination must use physical `any_records.id`, not tenant-local `logical_id`.
+
+Backfill SQL NULL revisions with a fresh UUID for each row in a caller-owned
+transaction. Preserve existing valid string tokens so retries do not invalidate
+clients unnecessarily. Reject empty or overlong existing values and resolve
+them explicitly; do not silently overwrite them. If any validation or write
+fails, let the error escape the transaction callback so the entire data phase
+rolls back. The migration must not call public PATCH merely to populate tokens:
+that would run application write hooks and side effects.
+
+The repository's backfill example (source checkout: `examples/migrations/resource-versions.js`)
+implements this data phase in pages of 100 records. Copy it into the application
+migration directory and import it locally; it is an example, not a new library
+export. Use an active raw Knex transaction for this one-off SQL migration.
+
+For a dedicated ordinary table, after adding its nullable column:
+
+```javascript
+import { backfillResourceVersions } from './resource-versions.js'
+
+await knex.transaction(transaction => backfillResourceVersions(transaction, {
+  tableName: 'books',
+  idColumn: 'id',
+  versionColumn: 'revision',
+  scope: {}
+}))
+```
+
+Replace the physical names with the application's actual mapping. An explicit
+empty scope means the whole dedicated table. For canonical storage, allocate
+the field and resolve its persisted slot first:
+
+```javascript
+await api.resources.books.addKnexFields({
+  fields: { revision: { type: 'string', nullable: true } }
+})
+const tenant = api.anyapi.tenantId
+const descriptor = await api.anyapi.registry.getDescriptor(tenant, 'books', {
+  bypassCache: true
+})
+await knex.transaction(transaction => backfillResourceVersions(transaction, {
+  tableName: 'any_records',
+  idColumn: 'id',
+  versionColumn: descriptor.fields.revision.slot,
+  scope: { tenant_id: tenant, resource: 'books' }
+}))
+```
+
+Run field allocation once as its own migration step. Rerun only the data phase
+to check backfill retry behavior; adding an already allocated field is an error.
+The returned `scanned` and `initialized` counts let the migration record exactly
+what it inspected and initialized. A successful retry preserves all tokens and
+returns `initialized: 0`.
+
+## Deploy and check readiness
+
+Persist the field declaration in application source, including canonical field
+configuration where applicable, then restart with `versionField: 'revision'`.
+Selecting this option alone does not perform schema migration or backfill.
+Restart resource registration against existing tables; do not run
+`createKnexTable` again for an ordinary table that already exists.
+Canonical `alterKnexFields` is not supported; do not use it to enforce SQL
+NOT NULL on a shared slot. Application `required: true` can be enabled in the
+new resource declaration after the backfill.
+
+Verify every selected row has a valid string token, unrelated tenants/resources
+are unchanged, and retrying the backfill initializes zero additional rows.
+Check that a new POST initializes a token, unconditional PATCH rotates it,
+a current conditional PATCH succeeds, and a stale one returns
+`REST_API_VERSION_CONFLICT` without changing stored data. Test rollback before
+allowing writers to resume.
+
+Clients send `expectedVersion` alongside the single-write options, or aligned
+`expectedVersions` for bulk PATCH/DELETE. They must not submit the revision among
+the record attributes. A conflict requires fetching and reconciling the current
+record; blindly retrying with a newly fetched token can overwrite another
+client's edits. These tokens are not HTTP ETags.
+
+If application deployment is rolled back, stop writers first. Old unconditional
+writers do not maintain the new contract. Before re-enabling conditional clients,
+rotate revisions for rows that might have changed under those writers, or
+restore the pre-migration backup as part of the application's rollback plan.
+The nullable added column can remain during rollback; dropping it is not
+necessary to disable conditional writes.
+
+
+## Pivot-resource writes
+
+For ordinary storage, public writes to a declared many-to-many through resource
+also invalidate affected versioned parent revisions. Both keys matter: changing
+the member while retaining the parent still changes that parent's membership.
+
+Canonical through-resource records are separate from canonical relationship
+links. Use public relationship methods to change canonical memberships; creating
+a through-resource record does not create a canonical link. Direct SQL and other
+writers that bypass the public mutation paths still need explicit revision
+maintenance.
+
+## Deleting linked resources
+
+Deleting a resource through the public API removes its many-to-many links in
+the same transaction. Recreating the same resource ID starts without those old
+memberships. Surviving versioned parents receive new revisions when their
+membership changes. A caller rollback restores the deleted record, links and
+parent revisions together.
+
+Ordinary storage removes remaining declared pivot references after deleting the
+resource row; canonical storage removes links matching its tenant, resource and
+ID in either direction. Applications must not depend on deleted IDs retaining
+memberships for later reuse. This does not provide revision maintenance for
+arbitrary database triggers or SQL writers outside the public API.
+
+Earlier releases deliberately left ordinary pivot rows for application cleanup.
+That behavior changes: declared membership rows are removed automatically,
+including for unversioned resources and custom IDs. Related resource records
+are preserved; deleting a book's author links does not delete its authors.
+
+Explicit ordinary SQL foreign keys retain their configured behavior: `RESTRICT`
+can reject deletion, leaving both membership and revisions unchanged; `CASCADE`
+can remove the pivot, with the surviving parent's revision updated by the public
+delete transaction. These two rules are tested on SQLite, PostgreSQL and MySQL.
+
+## Verification
+
+The executable example and allocation/restart workflow pass six checks in each
+of six database/storage combinations (36 total), with no failures or skips.
+Tests cover 103 rows across multiple pages, distinct initialization tokens,
+preservation of existing tokens, retry, rollback after late invalid data,
+caller-owned rollback, filtered records, overlapping canonical tenants/resources,
+and post-migration conditional updates and creation. See
+the test suite (source checkout: `tests/conformance-version-migration.test.js`).

package/docs/GUIDE/23-fastify.md

@@ -0,0 +1,179 @@
+---
+title: "Fastify integration"
+chapter: 23
+chapter_label: "23"
+---
+
+# 23. Fastify integration
+
+`json-rest-api` includes a Fastify connector. Integration tests exercise
+Fastify with ordinary Knex and canonical AnyAPI SQLite storage. The current
+verification runtime is Node 24; see [backend capabilities](30-backend-capabilities.md)
+for the supported matrix and limits.
+
+## Runnable connector example
+
+Install `fastify` alongside the library and database dependencies. Begin with
+an API instance that has `RestApiPlugin` and one storage plugin installed, as in
+[initial setup](01-getting-started.md). Use a fresh database and run the next
+three blocks before registering other resources.
+
+```javascript
+import fastify from 'fastify'
+import { FastifyPlugin } from 'json-rest-api'
+
+const app = fastify()
+await api.use(FastifyPlugin, { app, mountPath: '/api' })
+```
+
+```javascript
+await api.addResource('books', {
+  schema: { title: { type: 'string', required: true } }
+})
+await api.resources.books.createKnexTable()
+```
+
+Fastify's `inject` runs its HTTP routing, parsers and handlers without opening a
+listening socket. This makes the example runnable as a short verification script.
+
+```javascript
+let createdResponse, listResponse, invalidResponse, malformedResponse
+try {
+  await app.ready()
+  createdResponse = await app.inject({
+    method: 'POST', url: '/api/books',
+    headers: { 'content-type': 'application/vnd.api+json' },
+    payload: { data: { type: 'books', attributes: { title: 'Fastify example' } } }
+  })
+  listResponse = await app.inject({ method: 'GET', url: '/api/books?page[number]=1&page[size]=10' })
+  invalidResponse = await app.inject({
+    method: 'POST', url: '/api/books',
+    headers: { 'content-type': 'application/vnd.api+json' },
+    payload: { data: { type: 'books', attributes: {} } }
+  })
+  malformedResponse = await app.inject({
+    method: 'POST', url: '/api/books',
+    headers: { 'content-type': 'application/vnd.api+json' }, payload: '{'
+  })
+  console.log(createdResponse.statusCode, listResponse.json(), invalidResponse.statusCode, malformedResponse.statusCode)
+} finally { await app.close() }
+```
+
+Creation returns 201 and a JSON:API resource even when programmatic calls default
+to plain records. The list contains one book and reports a total of 1. Missing
+required title returns 422, while malformed JSON returns 400. Neither rejected
+request creates another book.
+
+In a running application, call `await app.listen({ port: 3000 })` after declaring
+resources instead of running the injection block. Close the Fastify app and
+destroy its database connection during application shutdown.
+
+## What the connector does
+
+The Fastify connector listens to the same `addRoute` hook as the Express connector and registers the generated REST routes on the Fastify instance you pass in `pluginOptions.app`.
+
+It publishes the transport schema exported by `json-rest-schema` and uses the
+existing compiled request contract through Fastify's route validator compiler:
+
+- `POST` routes use the schema export in `create` mode
+- `PUT` routes use the schema export in `replace` mode
+- `PATCH` routes use the schema export in `patch` mode
+- relationship `POST` / `PATCH` / `DELETE` routes use JSON:API relationship document schemas
+
+Those field schemas are wrapped in the JSON:API document envelope expected by
+`json-rest-api`. Resource routes select JSON:API input/output and full write
+responses explicitly, regardless of the programmatic or resource defaults.
+Relationship writes and resource DELETE return 204 with no body.
+
+The route validator resolves the current cached contract for each payload, so
+canonical field additions also update resource write validation. The JSON
+Schema published when registering the route is an initialization snapshot;
+finalize declarations before generating route-based API documentation.
+
+The route validator uses the same contract as programmatic calls. This avoids
+Ajv rejecting `json-rest-schema` metadata at server startup, stripping unknown
+fields, or applying different coercion rules before the resource sees the input.
+The connector registers routes and JSON parsers in a child Fastify scope. The
+host application's parser and validator configuration is not replaced. Register
+resources before calling `app.ready()` or `app.listen()`. Custom routes
+without resource metadata keep their existing unschematized behavior.
+
+## What gets rejected early
+
+Fastify can now stop malformed write payloads before they reach the app layer:
+
+- missing `data`
+- invalid `data.type`
+- invalid `data.id` on `PUT` / `PATCH`
+- malformed attribute payloads
+- unknown attribute fields
+- invalid scalar types according to the resource schema
+- malformed relationship write documents
+
+The transport schema also reflects the existing write contract:
+
+- output-only computed fields are removed from `data.attributes`
+- direct `belongsTo` foreign keys are removed from `data.attributes`
+- relationship linkage still belongs under `data.relationships`
+
+Invalid request documents use the library's typed validation error and HTTP 422
+response. Malformed JSON uses HTTP 400. Resource attribute validation, setters,
+permissions, storage and transaction decisions still run in the resource method.
+Transport request hooks run before document validation; errors with an existing
+request context pass through the transport response hook.
+
+## HTTP boundaries
+
+The connector accepts `application/vnd.api+json` and `application/json` request
+bodies, and sends `application/vnd.api+json` responses without a charset
+parameter. Both input types use the same JSON parser inside the connector's
+scope. Bodyless resource DELETE works with either content type. Invalid JSON is
+400; a valid JSON value that is not a resource document is 422.
+
+Unsupported write media types are rejected with 415 before parsing. JSON:API
+`charset` parameters and extensions are rejected; unknown profiles are ignored.
+An incompatible `Accept` header produces 406, including an explicit zero quality
+for JSON:API. Valid wildcards and JSON:API alternatives are accepted. Responses
+include `Vary: Accept`, preserving other values set by response hooks. These
+rules follow [JSON:API content negotiation](https://jsonapi.org/format/#content-negotiation).
+
+Configure the body size limit on the Fastify instance (`fastify({ bodyLimit:
+1048576 })`). The Express connector's corresponding option is
+`requestSizeLimit`. Oversized bodies produce 413 before storage runs.
+
+Unknown routes under `mountPath` return a JSON:API 404 and run the transport
+response hook. `handle404: false` leaves these responses to the host application.
+Host routes and parsers outside the API prefix keep their own behavior.
+
+Fastify handles malformed URL encodings before plugin lifecycle hooks. Its
+default is a native Fastify 400 document. Applications requiring JSON:API at that
+boundary can configure the host's
+[`routerOptions.onBadUrl`](https://fastify.dev/docs/latest/Reference/Server/#onbadurl)
+when constructing the server:
+
+```js
+const app = fastify({
+  routerOptions: {
+    onBadUrl (path, req, res) {
+      res.writeHead(400, { 'Content-Type': 'application/vnd.api+json' })
+      res.end(JSON.stringify({
+        errors: [{ status: '400', title: 'Bad Request', detail: 'Malformed URL' }]
+      }))
+    }
+  }
+})
+```
+
+This is a host-wide setting using raw Node request/response objects. The
+connector cannot install it after receiving an existing Fastify instance.
+
+## Executed coverage
+
+`tests/http-connectors-parity.test.js` exercises real Fastify injection and
+Express 4/5 request handling against both storage modes. It checks resource CRUD,
+PUT creation/replacement, relationship routes, includes, sparse fields,
+pagination links, scalar coercion/nulls, defaults, headers, trusted URL overrides,
+validation, parsing, body limits, content negotiation, asynchronous request-hook
+failures, and host route/parser isolation. Registration/schema tests also use a
+real Fastify instance. Multipart and real database coverage remain separate
+roadmap requirements.

package/docs/GUIDE/24-cors.md

@@ -0,0 +1,172 @@
+---
+title: "CORS"
+chapter: 24
+chapter_label: "24"
+---
+
+# 24. CORS
+
+`CorsPlugin` adds CORS response headers and handles OPTIONS requests beneath the
+HTTP connector's API prefix. Install Express or Fastify before this plugin.
+Register resources and plugins before starting the server.
+
+CORS controls whether browser JavaScript can read a cross-origin response.
+Authentication, authorization and CSRF protection remain application concerns;
+an ordinary request from a disallowed origin can still execute. A denied
+preflight stops the browser from sending the subsequent request. See the
+[Fetch CORS protocol](https://fetch.spec.whatwg.org/#http-cors-protocol).
+
+## Basic setup
+
+This runnable example uses an in-memory database. The response is visible to
+`https://app.example.com`, including when a request returns an error.
+
+```js
+import { JsonRestApi } from 'json-rest-api'
+import { RestApiPlugin, RestApiKnexPlugin, ExpressPlugin, CorsPlugin } from 'json-rest-api'
+import express from 'express'
+import knex from 'knex'
+
+const db = knex({
+  client: 'better-sqlite3',
+  connection: { filename: ':memory:' },
+  useNullAsDefault: true
+})
+const app = express()
+const api = new JsonRestApi({ name: 'cors-example' })
+await api.use(RestApiPlugin)
+await api.use(RestApiKnexPlugin, { knex: db })
+await api.use(ExpressPlugin, { mountPath: '/api' })
+await api.use(CorsPlugin, {
+  origin: 'https://app.example.com',
+  credentials: true,
+  allowedHeaders: ['Content-Type', 'Authorization'],
+  exposedHeaders: ['Location', 'Link'],
+  maxAge: 600
+})
+await api.addResource('countries', {
+  schema: { id: { type: 'id' }, name: { type: 'string', required: true } }
+})
+await api.resources.countries.createKnexTable()
+api.http.express.mount(app)
+const server = app.listen(3000)
+```
+
+Close `server` and call `db.destroy()` when shutting down. The database and its
+records in this example last only for the lifetime of the process.
+
+For Fastify, replace the Express import, app creation, connector installation and
+mount/listen lines with the following respective equivalents. Keep the resource
+and CORS setup before `listen()`:
+
+```js
+import fastify from 'fastify'
+import { FastifyPlugin } from 'json-rest-api'
+
+const app = fastify()
+await api.use(FastifyPlugin, { app, mountPath: '/api' })
+// Install CorsPlugin and register resources here.
+await app.listen({ port: 3000 })
+```
+
+## Configuration options
+
+Pass options directly to `api.use(CorsPlugin, options)`.
+
+| Option | Default | Behavior |
+| --- | --- | --- |
+| `origin` | `'*'` | Exact string, regular expression, array of candidates, function, or `false` to disable origin permission |
+| `credentials` | `true` | Adds `Access-Control-Allow-Credentials: true` for allowed origins |
+| `methods` | GET, POST, PUT, PATCH, DELETE, OPTIONS | Array advertised in preflight `Access-Control-Allow-Methods` |
+| `allowedHeaders` | Content-Type, Authorization, X-Requested-With, X-HTTP-Method-Override, Accept, Origin | Array advertised in preflight `Access-Control-Allow-Headers` |
+| `exposedHeaders` | X-Total-Count, X-Page-Count, Link, Location | Array of response headers available to browser JavaScript; `[]` omits this header |
+| `maxAge` | `86400` | Preflight cache lifetime in seconds; `0` is respected |
+| `optionsSuccessStatus` | `204` | Successful OPTIONS status; use `200` if required by your client |
+
+The default permits every origin, including credentialed requests. With
+`origin: '*'` and `credentials: true`, the plugin reflects the request's Origin.
+Use an explicit list for applications with credentialed browser sessions. For
+public responses without credentials:
+
+```js
+await api.use(CorsPlugin, { origin: '*', credentials: false })
+```
+
+This returns the literal `Access-Control-Allow-Origin: *` and omits the credential
+header. A browser credentialed fetch requires an explicit allowed origin;
+the literal wildcard is insufficient. The
+[Fetch credentials table](https://fetch.spec.whatwg.org/#cors-protocol-and-credentials)
+shows how these response headers interact.
+
+An origin function receives the request Origin and returns a boolean or a
+promise for one. It is evaluated once per HTTP response, including preflight:
+
+```js
+const allowedOrigins = new Set(['https://app.example.com', 'https://admin.example.com'])
+await api.use(CorsPlugin, {
+  origin: async origin => allowedOrigins.has(origin),
+  credentials: true
+})
+```
+
+A false result grants no CORS permission. A thrown/rejected predicate produces a
+500 JSON:API error without an allowed-origin header; it is not retried while
+constructing that response. Array candidates are awaited in order. Regular
+expressions match independently for each request without modifying `lastIndex`.
+
+`api.vars.cors` contains the current configuration. Changes apply to later
+requests. Prefer updating an origin allowlist used by your predicate rather than
+reinstalling the plugin or duplicating its OPTIONS route.
+
+## Preflights and rejected requests
+
+Allowed OPTIONS requests return the configured status, origin, methods, headers
+and cache age. Disallowed origins receive 403 with a JSON:API error document:
+
+```json
+{"errors":[{"status":"403","title":"Forbidden","detail":"CORS origin not allowed"}]}
+```
+
+The plugin advertises the configured methods and headers; the browser checks
+whether the requested method/headers are allowed. It does not add or authorize
+resource methods. Application request hooks also run for OPTIONS: an
+application that requires authentication on every request should deliberately
+handle browser preflights in its authentication hook, since a preflight does not
+carry the later request's credentials.
+
+CORS headers are applied to connector responses for malformed JSON (400), body
+limits (413), unsupported media types (415), incompatible Accept (406), rejected
+request hooks, resource validation, missing records, API 404s and successful
+writes/deletes. A disallowed ordinary request receives no CORS permission, but
+its resource operation is still governed by normal application authorization.
+
+When a response reflects or filters Origin, `Vary` includes Origin even for
+absent or denied origins. Host, custom-route and response-hook vary fields are
+merged case-insensitively with the connector's Accept field; `Vary: *` stays `*`.
+Header order is not significant.
+
+The CORS hook appends to headers already present when it runs. A later custom
+hook that replaces `response.headers.vary` must preserve any existing fields.
+Use the runtime's `beforeFunction`/`afterFunction` placement options when hook
+order matters; numeric ordering options are not supported.
+
+## Response hooks and host boundaries
+
+`transport:response` is attempted once for each connector-generated HTTP
+response, including early parser/media errors and `context.reject(...)`.
+On early errors, `context.transport.request.body` can be undefined because the
+parser or resource method never ran. Use `context.transport.response.status`
+when examining the attempted response. If a response hook throws, the connector
+maps the error without running the hook chain a second time. A failure at this
+stage cannot undo a write that has already committed.
+
+Host routes outside the API prefix, host middleware that sends its own response,
+and a hook that takes over the raw response are outside this lifecycle. Fastify
+rejects malformed URL escapes before connector hooks; its native 400 response
+therefore has no connector CORS headers. Configure the host's error boundary if
+needed; see the [Fastify guide](23-fastify.md). Express route-parameter decode
+errors do reach the connector error handler.
+
+Socket.IO has its own handshake/transport CORS configuration. Configure it
+through `startSocketServer` or the Socket.IO plugin options; this HTTP plugin
+does not replace Socket.IO authentication or subscription permissions.

package/docs/GUIDE/{GUIDE_X_URL_Management.md → 25-url-management.md}

@@ -1,4 +1,10 @@
-# URL Management in JSON REST API
+---
+title: "URL management"
+chapter: 25
+chapter_label: "25"
+---
+
+# 25. URL management
 
 ## Overview