pipework 0.114.0 → 0.116.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.116.0
+
+- **Added: a step graph run carries the requesting actor** (#601). `request()` records the requesting Flow's actor (`auth.userId`) on the run (new nullable `pipework_step_run.actor` column; run `pipework generate` for an existing database). Every step job, the `finish` job that delivers `onDone`, and `onFailed` run with `auth = { userId }`, so audited writes in them name the user who started the run. A later request by another user carries that user for the steps it queues. `RequestOptions.carryActor: false` records none.
+- **Added: `EnqueueOptions.actor?: string | null`**: record this actor instead of the Flow's (`null` for none); overrides `carryActor`.
+- **Fixed: `onFailed` ran with no `auth` in its Flow** (its trace had the actor, its audited writes did not).
+
+## 0.115.0
+
+- **Added: every traced answer carries `x-pipework-trace-id`** (#599), the request's trace row id (`trace.id`). A browser reads it once the route's CORS `exposedHeaders` lists it, and sends it as `ClientFaultReport.traceId`, which then names a real trace. Not set with tracing off, or on an answer refused before the request's context is built (a 401 from auth, a 404 before routing). `x-request-id` is unchanged.
+- **Added: `ClientFaultReport.requestId`** (#599): the `x-request-id` of the answer the page last saw (1-100 of `A-Za-z0-9._:-`), recorded in the alert context beside `traceId`.
+
 ## 0.114.0
 
 - **Added: `onJobEvent` reports a job this worker's attempt dead-lettered** (#596). `{ kind: 'dead-lettered', cause, error, job }`, once, after the dead-lettering transaction commits, in the job's tenant Flow and traced under the job's trace, like `reaped`. `cause` is `'failed'`, `'timeout'` (the handler's `.timeout(ms)` fired), `'permanent'` (`JobPermanentError`) or `'no-handler'`; `error` is the error as stored in `error_payload`. Never for an attempt that will be retried. `onDeadLetter` is unchanged: still inside the transaction, with no Flow.

package/REFERENCE.md

@@ -250,7 +250,7 @@ Computes the next fire time for a CronSchedule after a given date, with optional
 - **Trace.** The job's trace is a child of the enqueuing trace: `trace.parent_id` is the enqueuing trace, `root_id` its root, `parent_step_id` the step open at enqueue. Nothing is recorded when tracing is off or the enqueuing trace is truncated.
 - **Tenant.** The job runs under the enqueuing Flow's `tenant` (the tenant string, whatever its key type), so row-level security applies as it does for a request.
 - **Actor.** Only with `carryActor: true`: the job's `auth` is `{ userId }` from the Flow's `auth.userId`, so audited writes record that `actor_id`. Otherwise the job's `auth` is `null`.
-- **Options on `EnqueueOptions`.** `continueFlow?: boolean` (default `true`; `false` records none of the above, so the job is a root trace with no tenant), `tenant?: string | null` (run under this tenant instead of the Flow's; `null` runs without one), `carryActor?: boolean` (default `false`).
+- **Options on `EnqueueOptions`.** `continueFlow?: boolean` (default `true`; `false` records none of the above, so the job is a root trace with no tenant), `tenant?: string | null` (run under this tenant instead of the Flow's; `null` runs without one), `carryActor?: boolean` (default `false`), `actor?: string | null` (record this actor instead of the Flow's, `null` for none; overrides `carryActor`).
 - **No Flow.** Enqueued outside any Flow (a script, a schedule): the columns are null and the job runs as before. Schedule-fired jobs never continue a flow.
 - **Retries and `enqueueAndWait`** keep the recorded flow. `ClaimedJob.flow` exposes `{ traceId, rootId, stepId, tenant, actor }`.
 - **`executeJob`** takes `parent?: ParentTraceRef | null` (`{ id, rootId, stepId? }`); omitted, it continues the active Flow's trace and records the open step as `parent_step_id`.
@@ -1534,8 +1534,8 @@ await ops.resolve('engine-unavailable')
 `alerts.clientFaults(handle, { path, apps, key?, cors?, rateLimit? })` returns one POST route for failures that browser code reports; register it with the other handlers. It answers 204 with no body and needs no session (sign-in and public pages have none); with one, the tenant and user are used.
 
 - `apps` — `{ web: { owner?, runbook? } }`, at least one; a report's `app` must be one of its keys. `key(report)` — default `client-fault:<app>:<where>`. `cors` — the route's grant (see `Builder.cors`). `rateLimit` — a `rateLimits` class; omitted, the route's default class.
-- Body, strict (an unknown field is 400, and nothing is raised): `app`, `where` (1-100 of `A-Za-z0-9._:/-`), `kind` (`error | rejection | render | request`), `severity?` (`warning | error`, default `error`), `code?` (100), `message` (1-500), `stack?` (4096), `route?` (200, starts with `/`, no `?`, `#` or `://`: a route pattern, never a page URL), `release?` (100), `traceId?` (a uuid).
-- Each report is a trace step `pipework/alerts:client-fault` capturing the report, and raises the key with severity as sent, the app's `owner` and `runbook`, and context `{ app, where, kind, code?, route?, release?, traceId? }`. The stack is in the step's capture only. A raise that fails is logged; the answer is still 204.
+- Body, strict (an unknown field is 400, and nothing is raised): `app`, `where` (1-100 of `A-Za-z0-9._:/-`), `kind` (`error | rejection | render | request`), `severity?` (`warning | error`, default `error`), `code?` (100), `message` (1-500), `stack?` (4096), `route?` (200, starts with `/`, no `?`, `#` or `://`: a route pattern, never a page URL), `release?` (100), `traceId?` (a uuid: the `x-pipework-trace-id` of an answer), `requestId?` (1-100 of `A-Za-z0-9._:-`: the `x-request-id` of an answer).
+- Each report is a trace step `pipework/alerts:client-fault` capturing the report, and raises the key with severity as sent, the app's `owner` and `runbook`, and context `{ app, where, kind, code?, route?, release?, traceId?, requestId? }`. The stack is in the step's capture only. A raise that fails is logged; the answer is still 204.
 
 `reportClientFault(url, report)` from `pipework/client` sends a report with `keepalive` and `credentials: 'include'`, cuts `message` and `stack` to their caps, and never throws.
 
@@ -1754,6 +1754,7 @@ interface InjectResponse
 **`ServerConfig`** — Configuration for http.createServer() — CORS, security headers, rate limiting, transaction timeout.
 
 - `trustProxy` — which proxies to believe when reading the client address (`request.ip`) from `X-Forwarded-For`. Passed to Fastify unchanged. `false` (default): ignore forwarding headers, the address is the socket's. `true`: trust every hop, so a client can set its own address; only right when every request comes through your proxy. A string or string[] of addresses or CIDRs (e.g. `'10.0.0.0/8'`): trust only proxies at those addresses. A hop count (number) is not accepted: Fastify cannot check the immediate peer from a count alone, so it trusts no one.
+- Every traced answer carries `x-pipework-trace-id`, the request's trace row id; a browser reads it once the route's CORS `exposedHeaders` lists it.
 - `onInternalError(fault)` — called, and awaited, before the server sends a 5xx for a thrown error: an unhandled error, a `PipeworkError` with `httpStatus` >= 500, a failed route screen or file response. Never for a 4xx. `fault` is `{ error, method, route, requestId, tenantId, userId, traceId }` (`traceId`: the trace row id, null with tracing off); `route` is the registered pattern (`/things/:id`), the raw path where no route matched. Runs in the request's Flow with no transaction open, so `pipe.system()` works. A throw or rejection is logged (`onInternalError failed`) and the response is unchanged. `alerts.requestFaults(handle)` is such a hook.
 
 ```typescript