Skip to content

API Integration

This document describes how the Vayu Manager communicates with the Vayu Engine (C++ daemon) via HTTP.

Overview

The app communicates with the engine through: - HTTP REST API: For CRUD operations and request execution - Server-Sent Events (SSE): For real-time load test metrics

All communication happens on 127.0.0.1:9876, or on a fallback port (9880-9889) when another program holds 9876 (issue #2118). The main process chooses the port before the window exists and the preload exposes it as electronAPI.enginePort; config/network.ts reads it once into ENGINE_BASE_URL, and everything the renderer sends goes through that. With no preload (a browser tab, the test suite) it is 9876.

API Client Architecture

┌─────────────────────────────────────────┐
│         React Components                │
│  (RequestBuilder, Dashboard, etc.)     │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│  Hooks + singletons                     │
│  (useEngine, queries/, loadTestService) │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│         Services Layer                  │
│  - api.ts (HTTP client)                │
│  - sse-client.ts (SSE client)          │
│  - http-client.ts (fetch wrapper)       │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│         Vayu Engine                     │
│  (localhost:9876)                      │
└─────────────────────────────────────────┘

HTTP Client (services/http-client.ts)

Low-level fetch wrapper with error handling and timeout management.

Features

  • Base URL Configuration: ENGINE_BASE_URL (config/network.ts), re-exported as API_ENDPOINTS.BASE_URL by config/api-endpoints.ts. http://127.0.0.1:9876 unless the app fell back to another port
  • Request Timeout: 30 seconds default
  • Error Transformation: Converts HTTP errors to ApiError with user-friendly messages
  • Query Parameters: Automatic URL encoding
  • JSON Serialization: Automatic request/response JSON handling
  • No Caching: every request passes cache: "no-store", matching the engine's own Cache-Control: no-store on every response (#1507) - nothing the engine answers is valid to replay from Chromium's disk cache

Error Handling

class ApiError extends Error {
  statusCode: number
  errorCode: string
  userFriendlyMessage: string
  response?: any
}

Every engine error body is {"error": {"code", "message"}}, so message is the engine's own text (a validation reason, a not-found) and errorCode is its code - per-status (bad_request, not_found, ...) unless the route names a more specific one. Two fallbacks sit behind that, and both matter: a body in the legacy flat shape ({"error": "..."}, which a pre-#173 engine sends and the sidecar's version can lag the app's) still yields its string as the message, and a body carrying neither falls back to HTTP <status>: <statusText>. response keeps the raw body, which is where per-error detail lives - error.item on a failed bulk import, the provider fields on /oauth2. See the engine's error contract.

Error Types: - isTimeout: Request timeout - isNetworkError: Connection/DNS errors - isDatabaseError: Engine database errors

API Service (services/api.ts)

High-level service layer that wraps HTTP client with domain-specific methods.

Data Transformation

The service handles transformation between frontend (snake_case) and backend (camelCase) formats:

Frontend Format (snake_case):

{
  collection_id: "col_123"
  created_at: "2024-01-01T00:00:00Z"
  elements: []
}

Backend Format (camelCase):

{
  collectionId: "col_123"
  createdAt: 1704067200000
  elements: []
}

Request bodies

body goes to the engine as the discriminated union { mode, content } or - for the two form modes - { mode, fields }, built by buildExecBody (modules/request-builder/utils/execute-mapping.ts) and passed through untransformed. The mode strings are a contract: the engine matches "form-data" and "x-www-form-urlencoded" exactly and reads the content out of fields, so a renamed mode or a flattened content string sends an empty body rather than failing. Disabled rows are sent and dropped engine-side, and the engine writes the Content-Type each mode implies when the request declares none: application/json for json, graphql and jsonrpc, application/xml for xml, text/plain for text, the form type for each form mode and the file's own type for binary. A bodyless POST goes out with no Content-Type at all, where libcurl would write application/x-www-form-urlencoded (issue #2464). A form-data row may be a file part ({type: "file", src, fileName?, contentType?}): the renderer sends the path the user picked - never the bytes - and the engine opens the file at send time. A text part may carry just contentType, the type it declares for itself (a Postman import keeps one, #2539, and the form-data editor's Content type column sets it by hand, #3022); the renderer sends it, resolved like the file members, and a part without it sends none. A binary body is one file as the whole body, {mode: "binary", file: {src, fileName?, contentType?}}, built from RequestState.binaryFile; it is sent even with an empty src, so the engine can refuse it as "no file selected" rather than send a bodiless request.

unresolved comes back, never goes out (#2356). The engine sends a file reference only when its path was picked on this machine or lies under a folder allowed in Settings > Files (allowed folders), and decides that from its own records: on every read that hands a body to an editor it writes unresolved on each file reference with a path (true: it would refuse it), and on every write and send it ignores the key. So the renderer keeps the derived value for display - RequestTransformer and the History run seed leave it as read - and strips it from everything it sends, through lib/file-trust.ts: the send (buildExecBody), the save (toBodyPayload, which a pasted command's new request uses too), History's Save to request and a Duplicate. A pick or a drop in the editor is the grant itself (the preload reports the path to the main process, which records it), so it sets unresolved: false locally until the next read; a typed or pasted path carries no flag and reads as not chosen until the engine answers for it. An import's POST /import/apply payload echoes the parse answer's flag unchanged, because it is pinned to the engine's own apply mapping (orchestrator.payload-conformance.test.ts); the engine drops it there too. A refused file comes back as a send failure (status 0, the engine's message naming the field or "Body file", the path and what to do), which the response pane's ClientErrorView prints as-is under "Couldn't send the request". See the engine's body union for the full contract.

API Methods

Health & Configuration

apiService.getHealth(): Promise<EngineHealth>
apiService.getConfig(): Promise<EngineConfig>
apiService.updateConfig(config): Promise<EngineConfig>
apiService.getRequestDefaults(scope?: RequestDefaultsScope): Promise<RequestDefaults>

getRequestDefaults reads what the engine will add to a request that names none of it (issue #1229) - a User-Agent, a negotiated Accept-Encoding, an opt-in correlation id, and an Expect: 100-continue row while sendExpectContinue is on (issue #2468) - as {headers: [{name, value?, generated, configKey?}]}. A row with generated: true carries no value: it is made fresh per transfer. The set is read, never derived: the engine resolves it (its libcurl decides which encodings can even be asked for), so a renderer working it out from the config entries would be a second definition of the same rule. The Headers tab renders it as the read-only "Added by Vayu" group, and a row ticked off there rides the send as disabledDefaultHeaders, which POST /execute and POST /runs both take. None of it is persisted on the request. The engine also leaves libcurl no default of its own to fill (issue #2464).

What the transport adds on its own (Host, Accept, Content-Length, the Cookie the jar matched) is not part of that set and not part of requestHeaders: it exists only on the wire. The response's Headers tab lists the request as it was sent, taken from the engine's recorded raw request when it has one: one read-only, collapsed "Request headers" table holding every line of the rawRequest header block in wire order, the author's rows and the transport's alike, and a repeated name as separate rows. The renderer reads it off that block and carries it as ResponseState.wireRequestHeaders, set by responseFromExecuteResult and responseFromRunResult alike. It is a display of what went out: nothing in it is sent, stored on the request or visible to pm.request.headers. A restored row with no recorded frame lists requestHeaderLines instead, because the Raw tab's fallback frame is fabricated from the composed request, and so does a send that failed, whose frame the engine may have synthesized because nothing was sent. requestHeaderLines is the request's own lines as the transfer sent them (issue #2466): the answer's requestHeaderLines, or a stored trace's request.sentHeaderLines, in wire order, a repeated name repeated and each in the spelling typed. requestHeaders beside it is the same set folded to one value per name (a repeat joined with ", ", Cookie with "; ") and is what the section falls back to only for an answer from before the lines existed. Both funnels set it, an empty list reading as absent in each.

The stored counterpart is a different field (issue #1765): disabledSystemHeaders, Postman's per-request list, kept on the request as lowercased names and edited in the Settings tab's "Don't send automatic headers" list. The engine unions the two at send time, so the Headers tab shows a name stored there as off (disabled, "off for this request in Settings") rather than offering a tick that could not turn it back on.

scope (issue #1338) selects which send is being asked about: "design" (the default, and the Headers tab's own answer) or "load". The two can disagree - negotiateCompression governs a design send's Accept-Encoding and loadNegotiateCompression governs a load run's - so the load-test dialog reads both and names the difference rather than starting a run whose headers silently do not match what the tab just showed. sendExpectContinue is one key for both scopes, so it never makes them disagree.

apiService.getCookies(): Promise<GetCookiesResponse>
apiService.clearCookies(scope?: { environmentId: string | null }): Promise<ClearCookiesResponse>

The engine keeps one cookie jar per environment for design-mode requests (issue #301); CookiesCard in Settings → General shows and clears them.

Allowed folders

apiService.getFileRoots(): Promise<FileRoot[]>                 // GET /file-roots, a bare array
apiService.allowChosenFolder(): Promise<AllowFolderReply>     // picker in main, then POST /file-roots
apiService.deleteFileRoot(id: string): Promise<void>           // main's DELETE /file-roots/:id

The folders a request-body file may be sent from without a per-file pick - the second half of the trust rule under Request bodies. Only the list is an engine call from the renderer. Both writes need the engine's grant secret (who may call the API), which only the main process holds, so they cross the Electron bridge (#2356):

electronAPI method Channel What main does
allowFolder(key) file:allowFolder Opens the system folder picker, then POST /file-roots with the folder the user chose and the secret. The renderer names the dialog by key ("allow-folder", FOLDER_DIALOG_TITLES in electron/file-ipc.ts) and nothing else: the title is main's, the picker opens where the last one ended in this process (the first call, none), and an unknown or non-string key rejects (#2378).
removeAllowedFolder(id) file:removeAllowedFolder DELETE /file-roots/:id with the secret, for an id shaped like one the engine mints.

Both answer only the app window's main frame (electron/ipc-sender.ts) and resolve with the engine's answer rather than throwing it away at the process boundary: {outcome: "done", value}, {outcome: "refused", status, code, message} or {outcome: "unreachable", message}, and for allowFolder also {outcome: "cancelled"}, with the chosen folder as path on every other outcome. The row is stored canonical, so it can differ from the folder picked. useAllowFolder (hooks/useAllowFolder.ts) is the one caller that interprets an add, for Settings > Files (FilesPanel), the binary body editor and the import preview, and it treats a 409 (already allowed) as success; deleteFileRoot turns a refusal back into an ApiError. Outside Electron neither write exists, and the surfaces offer no way to add one.

A picked file is recorded by main, not sent by the renderer. When the preload's getFilePath(file) gets a path from webUtils.getPathForFile, it also reports it on an internal channel, file:picked, that no electronAPI method exposes; main checks the sender is the app window's main frame and the value an absolute path, then records it with POST /file-grants and the secret (electron/file-grants.ts). A document the OS hands the app (open-intent.ts) is recorded the same way. The report is one-way, so the renderer cannot wait for it: a pick followed by a send within the same few milliseconds can reach the engine first.

Request examples

apiService.listRequestExamples(requestId): Promise<RequestExample[]>
apiService.createRequestExample(requestId, example): Promise<RequestExample>
apiService.deleteRequestExample(requestId, exampleId): Promise<void>

Saved example responses stored against a request (issue #481) - what an import found next to it, and what a mock server will serve. Not read-only any more (issue #588): the response viewer's Save as example keeps the response on screen as one, with its body as received (bodyRaw, not the indented pane copy), and the Examples tab removes one. PUT still has no caller and so no endpoint constant - the panel is a viewer, and editing a stored example is its own change. The three consumers are in queries/request-examples.ts (useRequestExamplesQuery, useCreateRequestExampleMutation, useDeleteRequestExampleMutation); both writes settle by invalidating the one list key rather than splicing a row in, since the engine decides the id, the order an append lands on and the stored shape of the row. The delete also invalidates trash.all (#2971): the engine moves a saved example to the Trash and keeps an imported one as a spec-sync tombstone, and the mutation cannot tell which, so an open Trash view refetches either way. A saved example's delete raises the shared Moved "<name>" to the Trash toast with an Undo (hooks/useTrashUndo.ts); an imported one raises none, since there is nothing in the Trash to restore.

A saved example is written with origin: "user", and an imported one keeps the engine's "import" default. Its first reader is the OpenAPI spec sync (#627), which may replace the examples a document produced and must never touch one a person saved - and since #722 the panel reads it too: RequestExample claims the field, an imported row carries an Imported chip, and the delete dialog says what can still bring that kind of row back (the Trash for a saved one, a re-import for an imported one). The asymmetry the field encodes is a fact about the list, so leaving it invisible made which rows the next sync would replace unpredictable. The rest of the payload is the importers' own mapping, contentType included (the response's Content-Type header verbatim, "" when it stated none), so an app-saved example and an imported one are served identically. No order is ever sent: the engine appends, which is what keeps a restarted mock answering with the same first example.

A response from a live send also carries sentRequest, the request as the builder held it at Send ({{vars}} unresolved, the stored request-column shapes from sentRequestOf in utils/execute-mapping.ts; issue #1763). RequestBuilderProvider attaches it - to the /execute result on the buffered path, and on a stream to the stored run's response at stream end, only when that run is the one the snapshot was taken for. The save sends it as the create-only savedFrom: { request, statusText, responseTimeMs, receivedAt }, the server's own reason phrase, the response time and when the response came in (epoch ms, from receivedAt, or the stored run's restoredFrom.at on a stream's reloaded copy - the time a cookie's Max-Age counts from) beside it. The engine builds the Postman saved-response shape from it once and stores it for the export. A response restored from a stored run has no snapshot, so its save omits savedFrom and the export regenerates that example.

No transformer, unlike a request row: an example carries no timestamp the app renders and no column that predates a schema change, so the wire shape is the domain shape - minus the order and timestamps the RequestExample type deliberately does not claim, since the list arrives already ordered and no surface displays either. The stored order is the contract, not a suggestion: a mock server answers with the first example of a matched request, so the panel renders the list as received rather than re-sorting it.

Imported examples take a different route entirely: they ride nested on their request item in POST /import/apply (ImportApplyRequestItem.examples), not through this endpoint, so the whole tree still lands in one engine transaction.

Webhook inbox

apiService.listInboxes(): Promise<Inbox[]>
apiService.startInbox(request?: StartInboxRequest): Promise<Inbox>
apiService.stopInbox(inboxId): Promise<Inbox>
apiService.deleteInbox(inboxId): Promise<DeleteInboxResponse>
apiService.updateInboxResponse(inboxId, response: Partial<InboxCannedResponse>): Promise<Inbox>
apiService.listInboxCaptures(inboxId, limit?, offset?): Promise<InboxCapturesResponse>
apiService.clearInboxCaptures(inboxId): Promise<ClearInboxCapturesResponse>

An inbox records the requests sent to it and answers a canned response (issue #480); modules/inbox/ is the surface. updateInboxResponse is a merge-patch - an omitted field keeps what the inbox is serving - and the live capture stream (INBOX_LIVE) is a plain EventSource rather than SSEClient, which maps load-test metrics specifically. Captures arriving on that stream are merged into the listInboxCaptures cache, so there is one list. InboxCapture.bodyEncoding is "base64" when the stored bytes are not valid UTF-8 (issue #3109): body is then the base64 of the stored prefix, and bodyBytes is the size as received. parseCaptureEvent reads the marker off the stream the same way the list route carries it, because a payload that dropped it would show the base64 as the body's text. deleteInbox is the stronger of the two lifecycle calls: stopInbox frees the listener and leaves the record and its captures readable for the life of the engine process, while a delete takes both (issue #553). Its mutation removes the captures cache entry rather than invalidating it - an invalidation would refetch an id the engine now 404s. Inbox.captureCount is what a delete would destroy, and is what the confirmation is worded from. StartInboxRequest.allowedOrigins (issue #2367) is the optional CORS policy: absent is the any-origin default, and the one-click start still sends {}. Only the options dialog beside Start (modules/inbox/InboxStartOptions) sends a list, parsed and checked by the same lib/allowed-origins.ts the mock's form uses; the engine echoes the canonical list as Inbox.allowedOrigins, which the inbox tab's header and the Services drawer row read. It is fixed for the inbox's life. clearCookies distinguishes three cases the way the engine does, and they are not interchangeable: omitted clears every jar, { environmentId: null } clears only the jar used when no environment is selected, and an id clears that environment's. It reaches DELETE /cookies with the parameter absent, present and empty, or present with the id, respectively.

OAuth 2.0 mock issuer

apiService.listMockIssuers(): Promise<MockIssuer[]>
apiService.startMockIssuer(request?: StartMockIssuerRequest): Promise<StartMockIssuerResponse>
apiService.updateMockIssuer(issuerId, update: UpdateMockIssuerRequest): Promise<MockIssuer>
apiService.stopMockIssuer(issuerId): Promise<StopMockIssuerResponse>

A local issuer that mints HS256 tokens on demand (issue #479); the Services drawer (modules/services/) is the surface, added in #502 - before it these routes had no client but curl and the MCP tools. Two asymmetries the surface has to respect: startMockIssuer answers with the URLs and the signing key only, not the full record, so the list is refetched rather than patched; and a stopped issuer leaves the list altogether, unlike an inbox, which stays listed with running: false. updateMockIssuer accepts only expiresInSeconds, failureMode and slowMs - a port, client list or claim set cannot move under a bound listener and the engine refuses one with a 400 rather than half-applying it.

Collection mock server

apiService.listMockServers(): Promise<MockServer[]>
apiService.startMockServer(request: StartMockServerRequest): Promise<MockServer>
apiService.stopMockServer(mockId): Promise<StopMockServerResponse>
apiService.listMockServerRoutes(mockId): Promise<MockServerRoute[]>

A loopback listener answering a collection's saved example responses on the paths its requests describe (issue #481 phase 2). collectionId is the only required field; latencyMs and errorRatePct are the injection knobs, and an out-of-range value is a 400 rather than a clamp.

The mock is literal: it resolves no variables, so a {{variable}} in an example body is served as written, and it drops a leading {{baseUrl}} whole, so a path inside the variable's value is not part of any route (the engine's Mock Server section).

Two surfaces, deliberately split. CollectionDetail/MockServerControl is the only one that can start one, because a mock needs a collection and the Services drawer has none selected; the drawer's Mock servers group lists and stops whatever is running, wherever it came from. Both read the same polled list, so a mock started in one is visible in the other within a poll.

The knobs are sent from that control's options dialog and nowhere else (StartMockServerDialog, issue #570), bounds-checked against mock-server-options.ts before the request leaves - the engine's 400 names the field but not the range. There is no update verb: latencyMs and errorRatePct are read per response and so could change under a running mock, but a run pointed at one has to be able to say which configuration produced its numbers, so they are frozen at start like the route table.

The same dialog takes allowedOrigins (issue #2367), one origin per line. The key is sent only when non-empty: an empty box leaves the payload what it was, so the engine's any-origin default is its own and not restated here. The lines are parsed and checked by lib/allowed-origins.ts (the engine's rules, in words, sent in the engine's canonical spelling), and the echoed MockServer.allowedOrigins is shown on the mock-server tab as Origins: any or the list. Frozen at start like the knobs.

listMockServerRoutes is polled, at MOCK_ACTIVITY_POLL_INTERVAL_MS, even though it carries staleTime: Infinity: the route table's shape is a snapshot taken when the mock started and a running mock does not reload the collection, but each route's hits changes live as traffic arrives, so the poll is what keeps that count current. staleTime: Infinity only means mounting a second reader of the same query does not force a redundant fetch - it does not stop the interval firing. Stopping drops the record engine-side - unlike an inbox, which stays listed with running: false - so the mutation removes the routes cache entry instead of invalidating it, which would refetch an id the engine now answers 404 for.

Requests that share a method and path are one route, because the mock drops the query (#3115). MockServer.duplicateRoutes counts the ones that never answer (optional in the type: an engine older than the fix omits it), and each such MockServerRoute carries shadowed: true and shadowedBy: { requestId, requestName }; both keys are absent, never false, on every other row. The route table marks the row and names the request that answers, and MockServerControl's chip counts them beside the routes without an example.

Create vs update

For collections, requests and environments the engine splits the write verbs: POST /<resource> creates and never updates; PUT /<resource>/:id updates and answers an unknown id with 404. They are not interchangeable, so apiService keeps one method per verb:

  • createX(data) posts the object to the collection path with id stripped (withoutId in api.ts). The engine assigns every id and answers a create carrying one with a 400, and the Create*Request types declare id?: never - but TypeScript only excess-property-checks object literals, so a call site that spreads a whole record (a duplicate flow, a restored tab) would slip one through. The strip is what actually holds. (Import used to be the exception, pre-assigning ids to wire parentId / collectionId across a tree before anything was persisted; it sends one applyImport call now, see below.)
  • updateX(data) takes data.id, puts it in the path, and sends the rest of the object as a merge-patch body - an omitted field keeps its stored value, an explicit null resets it to the default. The id is not repeated in the body; a body id disagreeing with the path is a 400.

The full contract, including the null-vs-absent table and which fields have no default, is in engine/api-reference.md under "Resource writes". src/services/api.write-verbs.test.ts pins the method and path of every one of these calls - a regression here is invisible at every other layer, because the payload shape does not change.

Collections

apiService.listCollections(): Promise<Collection[]>
apiService.createCollection(data): Promise<Collection>   // POST /collections
apiService.updateCollection(data): Promise<Collection>   // PUT  /collections/:id
apiService.deleteCollection(id): Promise<void>

A collection carries dataSchema - the data contract it declares (issue

599): {columns?: string[], declaredAt?: number, fileName?: string}, where

{} means it declares none. CollectionTransformer normalizes it field by field rather than casting, because a row can come from an engine that predates the column and every reader treats columns as a string array; use hasDataContract(schema) instead of hand-rolling the check, since a cleared contract is {} and not undefined.

On updateCollection the field is CollectionDataSchema | null, like parentId: the engine reads absent as "keep the declared contract" and an explicit null as "reset to none", so the Data tab's Clear and its picker's Remove (the two writers of it) are only expressible as a null that survives to the wire. The rows behind the schema are never sent by these calls at all - they ride only the POST /runs payload, and are persisted by neither side.

A collection also carries openapi - the spec document it is bound to (issue #637): {specId?, specHash?, syncedAt?}, where {} means bound to nothing. It is normalized field by field for the same reason dataSchema is, and hasSpecBinding(binding) is the check to use - a collection that was bound and then unbound holds {}. On updateCollection the field is CollectionOpenApiBinding | null, and the Spec tab's Unbind is that null.

Specs

apiService.createSpec(data): Promise<SpecDocument>       // POST /specs
apiService.getSpec(id): Promise<SpecDocument>            // GET  /specs/:id
apiService.getSpecMeta(id): Promise<SpecDocumentMeta>    // GET  /specs/:id/meta
apiService.syncSpec(payload): Promise<SpecSyncResponse>  // POST /specs/sync
apiService.describeSpec(payload)                         // POST /specs/describe
apiService.matchSpecOperations(payload)                  // POST /specs/match
apiService.diffSpec(payload): Promise<SpecDiffResponse>  // POST /specs/diff
apiService.bindSpec(payload): Promise<SpecBindResponse>  // POST /specs/bind
apiService.exportSpec(payload): Promise<SpecExportResponse> // POST /specs/export
apiService.exportPostman(payload): Promise<PostmanExportResponse> // POST /export/postman
apiService.exportPostmanEnvironment(payload): Promise<PostmanEnvironmentExportResponse> // POST /export/postman-environment
apiService.exportRunReport(payload): Promise<RunReportExportResponse> // POST /export/run-report

describeSpec is the read that replaced the last parse this app did of a spec document (issue #869). It sends the picked bytes and gets back what they are - the dialect ("OpenAPI 3.1", "OpenAPI 3.0", "OpenAPI 2.0 (Swagger)"), info.title, and the identities the document declares, and the basePaths its server URLs name - and the Spec tab paints its card from that and hands the identities and the base paths to matchSpecOperations. It parsed the file itself until then, with services/openapi/spec-operations.ts, while the bind derived the same identities engine-side from the same bytes: two readers of one document, which could preview one pairing and commit another. A document that is not a contract, or that will not read at all, is a 400, and the tab prints the engine's sentence.

matchSpecOperations is a read (issue #761): it pairs the requests in a collection's subtree with the operations a document declares and writes nothing, which is what lets the Spec tab show the counts before the user commits to a bind. The pairing rule lives in the engine (core/operation_match.hpp) rather than in the renderer, so binding an existing collection is reachable from anything that is not the Spec tab - an agent over MCP first among them. The payload names the collection and sends the operations and the basePaths describeSpec answered (issue #3030); it does not send the requests, because an OpenAPI import files them under tag sub-collections and the engine gathers the whole subtree itself. The base paths are relayed rather than left for the engine to guess because they are what lets a request written as a literal URL (https://h/v1/pets) pair with the document's /pets: the bind derives them from the document it stores, so a preview that omitted them would show fewer matches than the bind stamps.

exportSpec is a read for the same reason and sends even less (issue #855): a collection id, a format, and - for a bound collection - the mode the user chose (contract or full). The engine reads the subtree, each request's stored examples and the bound document - which is the point, since a bound export patches those stored bytes - and answers with the finished text, a file name and the notes the dialog prints. A 409 there is a binding whose document is not stored, or stored bytes that will not read as OpenAPI; the renderer prints the engine's sentence rather than falling back to a skeleton.

exportPostman is the same kind of read for the other way out: a collection id and includeSecrets (default false, which writes auth secrets, secret variables and, by name, the credentials in headers, parameters, URLs, saved examples and cookie values empty, and counts them in notes.secretsOmitted; bodies and scripts are not judged). The answer is the Postman Collection v2.1 text, a <name>.postman_collection.json file name, and notes with the request and folder counts plus notCarried - one entry per kind of thing Postman has no place for, each with a count and the engine's sentence, which the dialog prints as written.

exportPostmanEnvironment is the same read for one environment (issue #2253): an environment id and includeSecrets (default false, which keeps each secret variable's row and name and writes its value "", counted in notes.secretsOmitted). The answer is the Postman environment text, a <name>.postman_environment.json file name and notes with variablesExported plus notCarried, whose one kind is variable_types: json-typed variables, which Postman has no type for, written as default, and typed secrets, whose type gives way to secret (#3252). The renderer's only caller is the environment row's Export as Postman environment item, which sends the id alone, saves text as fileName and, once the file is written, puts secretsOmitted and the variable_types count in the toast (modules/variables/sidebar/postman-environment-export.ts).

exportRunReport is the same kind of read for a finished load run (issue

2127). RunReportExportRequest is {runId, format?, series?, baseRunId?}:

format is "json" (the default), "markdown" or "html", series is "full" (the default, every tick of the time series) or "none" (which html ignores: its charts need the series), and baseRunId names a second finished load run, which fills the document's comparison. The answer, RunReportExportResponse, is {text, fileName, mimeType, notes}: the document (schema docs/engine/run-export.schema.json, built by allowlist so no trace, sample, header value or body is in it; for "markdown", its plain GFM rendering; for "html", one self-contained page with the charts), <title> <UTC start, YYYY-MM-DD HHmm>.run.json (.run.md, .run.html), application/json (text/markdown, text/html), and notes.urlCredentialsOmitted, the count of values the URL lost. A missing run or base is a 404, a run still executing a 409 run_in_progress, a design or collection-sequence run a 400 unsupported_run_type (API reference). useRunReportExport (queries/exports.ts) is its mutation, and EngineClient.exportRunReport the MCP server's call.

Neither index is sent on any write that stores a document - not by createSpec, syncSpec or the specs section of importCollection below. The engine reads the document it is storing and derives the operations index (#629, moved by #853) and the responseSchemas index (#628, moved by #860) from those very bytes, so sending either is a 400, the way a supplied hash is; a sync that forgets one can no longer turn coverage or response validation off for a collection that had it. The renderer stamps no identity of its own any more either (issue #877): an import is parsed by the same reader, so the identity on a request and the identity in the index come off one walk rather than two that had to be pinned to each other.

Create and read-by-id only, plus the two writes that move a binding. syncSpec is one (issue #655): it stores the re-fetched document, points the collection at it and applies the created, updated and deleted requests in a single engine transaction, because a sync that stopped halfway would leave a collection bound to a document its requests do not reflect. The renderer decides what to send (services/openapi/spec-apply.ts) and never sequences the writes itself.

diffSpec is the read that the Sync section's Check is (issue #854). It sends the collection and the re-fetched bytes and nothing else: the engine walks the collection's subtree itself and reads the bound document from the binding, because the three-way userTouched flag - the request holds neither the new document's value nor the bound one's - is worth nothing if a caller can supply the previous side. It writes nothing, and the answer carries, per entry, the draft an apply would write, so spec-apply.ts builds a POST /specs/sync payload out of it without reading a document at all. The comparison used to be services/openapi/spec-diff.ts, which is gone.

Each entry also carries what a sync with no ticks would do to it - safe, and safeFields on a changed request (issue #871). defaultSelection reads those rather than deriving them from userTouched, because the rules behind them are the ones whose silent failure destroys a person's work and they now have one author: core::safe_spec_apply, which POST /specs/sync's policy: "safe" applies for a caller that states no rows at all. syncSpec still sends explicit rows from here, since the ticks a person changed are not a policy.

The diff's declined bucket (issue #3031) lists operations whose request the user deleted: entries shaped like added's, safe always false. It is separate so nothing pre-ticks it. SpecApplySelection.declined starts empty whatever safe says, and a tick goes out as an ordinary create[] item built by the same draftOf / createItem path as an added operation, carrying specOperation. No flag marks it a revival: the engine sees a create naming a declined operation and clears the record in the same transaction. A policy: "safe" response's skipped counts what it left as declined.

The one field of that draft spec-apply.ts does not send back is examples (issue #869): an update carries examples: true - refresh this request's imported examples - and the engine writes the responses the document it is storing documents. A created request states none at all, for the same reason. Echoing the rows back was a round trip through the client of an answer the engine had already given, and it let a payload state an example for a response no document describes.

bindSpec is the other (issue #862), and it decides even less: the payload is a collection and a document, with no pairing in it. Binding used to be three calls made in order from useBindSpecMutation - store the document, move the binding, then stamp the matched requests and clear the stale ones - and both halves of that were defects waiting to happen: three writes are three places to stop, and the clearing half is a list a caller can forget, which is exactly what issue #718 was. POST /specs/bind commits all of it or none of it and works the pairing out from the bytes it stores. matchSpecOperations above is still what the Spec tab previews with; it is not a payload for this call, and the bind matches again over the same rule.

A document is immutable - a changed spec is a new document and a moved binding, which is what keeps a run's specHash stamp meaningful - and the hash is computed engine-side on the bytes it stored, never here. There is no delete call: unbinding is a PUT /collections/:id, and the document stays for whatever else binds it. Both reads are cached with staleTime: Infinity, because the row behind a given id cannot change.

Describing a document and reading one are two calls (issue #712). getSpecMeta answers sourceUrl, fetchedAt, hash and contentBytes and nothing else; getSpec sends content and both extracted indexes with it - up to maxSpecDocumentBytes, which is 12 MB for Stripe's published spec. The rule for choosing is what the caller does with the answer:

Caller Read Why
The Spec tab's card (useSpecMetaQuery) meta It paints a source, a date and a size; it never renders the document
The Sync section's Check (useSpecMetaReader) meta, on the click Since #854 it needs only sourceUrl - where to re-fetch from - because the engine compares its own stored bytes
The import dialog's bound-spec match (useBoundSpecReader) full, on the action It compares the document itself

Export needs neither read any more (issue #855): POST /specs/export assembles the document engine-side from the bytes it already stores, so the renderer asks for the finished text and never for the spec.

Reading the full document on tab open is the thing this split removed: a first open of a bound tab transferred the whole spec to paint two fields, on a query that then sat in cache forever. A reader that needs the text still asks for it - on the action that needs it, where the wait is something the user started.

Requests

apiService.listRequestSummaries(params?): Promise<RequestSummary[]>  // GET /requests?fields=summary
apiService.listRequests(params?): Promise<Request[]>     // GET /requests, whole rows
apiService.getRequest(id): Promise<Request>
apiService.createRequest(data): Promise<Request>         // POST /requests
apiService.updateRequest(data): Promise<Request>         // PUT  /requests/:id
apiService.deleteRequest(id): Promise<void>

The two list calls answer the same rows in the same order; params is { collectionId? } on both. listRequestSummaries is the tree's (#2546): each row is a RequestSummary (id, collectionId, name, method, url, order, createdAt, specOperation), read by RequestTransformer.toSummary, and it is the only list call the launch makes. listRequests is the whole row, RequestTransformer.toFrontend (built on toSummary, so a column the two share reads the same way in both); only the column audit asks for it (useFullCollectionRequests). A reader that needs one request's body, headers or scripts reads getRequest, which never substitutes a default for an over-cap column the way a full list row can.

A request carries specOperation - which operation of the bound spec it is (issue #637): {operationId?, method, path}, where path is the document's templated path and not the URL the request sends. The engine serializes null for a request that names none, and RequestTransformer turns that into an absent key; on updateRequest the field is SpecOperation | null, so stamping and clearing an identity are the same verb.

A request also carries methodSource - which app setting last wrote method, still unclaimed by the user (issue #1505): MethodSource ("graphql", the GraphQL body mode's auto-POST) or absent. Same null-vs-absent rule as specOperation: the engine serializes null for no marker, RequestTransformer turns that into an absent key and drops a value it does not recognize, and updateRequest's field is MethodSource | null, so leaving GraphQL - or picking a method by hand - clears the marker the same way.

A request carries timeout - its own timeout in milliseconds, 1-86400000 (issue #2937) - or null when it states none and sends with the defaultTimeout setting read at each send. The engine always serializes it, and RequestTransformer keeps null as null rather than filling in a default (a non-number reads as null too). On updateRequest the field is number | null: absent keeps the stored value and null resets it, so the builder's buildUpdatePayload writes a cleared field as an explicit null. The engine refuses a number outside the range with a 400 naming timeout, so the Settings tab clamps what is typed.

The builder seeds its Params rows from the stored params and the URL's query together (issue #3491, initialRequest in modules/request-builder/index.tsx). A request stored with its query only in url (written before the engine derived the rows from a URL-only write, issue #3551, or by a write that stated params: []) opens with those pairs as rows, through mergeParamsFromUrl - the rule a URL-bar edit already uses, so stored disabled rows stay and a stored row keeps its id and description. Without it the table opened empty and its first edit rebuilt url from the rows alone, deleting the query. The seed is not an edit: the draft's saved baseline is seeded from the same rows, so the request is not marked unsaved, and nothing is written back until the user changes something.

Trash

apiService.listTrash(): Promise<ListTrashResponse>              // GET    /trash
apiService.restoreTrashEntry(id): Promise<RestoreTrashResponse> // POST   /trash/:id/restore
apiService.purgeTrashEntry(id): Promise<PurgeTrashResponse>     // DELETE /trash/:id

What deleteCollection, deleteRequest, deleteEnvironment (#2970), deleteRequestExample for a saved example (#2971) and deleteClientCertificate (#2973) now do is a soft delete (issue #988): the engine stamps the row instead of removing it, and these three read that stamp back. No transformer on any of the three - a trash entry is the engine's own summary of a deleted row (a name, a stamp and its counts), not a stored record the app reshapes, so the wire shape is the only shape.

listTrash returns roots only - the row a user actually asked to delete, never a descendant the same cascade took with it. A deleted collection's whole subtree is represented by that one root entry, with collections / requests counting what that delete took along (the cohort a restore puts back) and purgeCollections / purgeRequests counting everything a purge would destroy under it, an earlier delete's rows included (#3449). The row and the purge prompts read the purge totals; the cohort counts are a floor there. kind is "collection", "request", "environment", "example" or "clientCertificate"; an environment entry is always a root, counts 0 for both, and alone carries variables, how many variables it holds. An example entry counts 0 for both too; the engine's parentId on it is the owning request, which TrashEntry does not claim: it carries the owner's name as parentName instead (#3449), sent on request and example entries only, which the row shows as "from " so two same-named entries tell apart. A client-certificate entry is a root with both counts 0 and a null parentId; its name is its target, host or host:port.

restoreTrashEntry puts one deleted root back, with everything the same delete took, and answers with the entry plus restored: true and reparentedToRoot - true when the collection's parent is gone or itself in the trash, so the engine clears its parent and returns it as a tree root instead. It rejects with a 404 for an id the trash does not hold (a live row, or one already purged) and a 409 for a request whose collection is itself deleted or gone - a request has no root to land on the way a collection does, so the engine's message names the request, its collection and the Trash root to restore first (the collection, or the ancestor whose delete took it), by name and id - and the same 409 for an example whose request is in the trash (naming the example, the request and the root to restore) or gone, or already holds the most examples a request may (100), and for a client certificate while a live entry holds the same host and port (the message names that entry); surface ApiError.message rather than inventing wording for it. Both the Trash view's Restore and the toast's Undo do. A restored environment comes back with every variable but inactive: the delete cleared its active flag and the restore does not set it again. A restored example reappears in its request's Examples list because the restore invalidates requests.all, under which the examples key sits; a restored client certificate reappears in Settings because the restore invalidates clientCertificates.all.

purgeTrashEntry is the hard purge the soft delete deferred - it destroys the row for good, with its whole subtree, and there is no undo. For a client certificate that is the registry entry and its stored passphrase; the certificate and key files it names are never touched. It answers with the entry plus purged: true, or a 404 if the trash does not hold that id.

The full contract - request/response bodies, the restore's cohort and re-parent rules, and the startup retention sweep - is in engine/api-reference.md under Trash.

Reorder

apiService.reorder(data: ReorderRequest): Promise<ReorderResponse>  // POST /reorder

The write path behind a drop. One call repositions any number of collections and requests, and the engine applies the whole batch in one transaction - so a drop that displaces N siblings is one round trip, not N updateRequest calls that can half-land and race a concurrent create into the middle of their range.

The payload carries moves (each row's type, its new order, plus parentId / collectionId when it changes owner) and normalize, one { parentId } per parent to renumber dense 0..n-1 in sibling order first (null for the top level), for a parent whose rows predate explicit orders. A parent's sub-collections and requests are one list in one order space (#2535), so one entry covers both kinds and a single drop can move a request between two folders; the per-kind { type, parentId | collectionId } entries earlier engines took are a 400. modules/collections/reorder-math.ts computes both arrays from the merged sibling list the tree is already showing; the full contract is in engine/api-reference.md under POST /reorder.

Unlike the other writes, the response is read: it is the rows as written, and useReorderMutation settles its caches on them so a normalization the engine performed shows up without waiting for the refetch.

Environments

apiService.listEnvironments(): Promise<Environment[]>
apiService.getEnvironment(id): Promise<Environment>
apiService.createEnvironment(data): Promise<Environment> // POST /environments
apiService.updateEnvironment(data): Promise<Environment> // PUT  /environments/:id
apiService.deleteEnvironment(id): Promise<void>         // DELETE /environments/:id

deleteEnvironment is a soft delete (#2970): the engine moves the environment to the Trash and clears its active flag in the same write, and every environment read stops returning it. restoreTrashEntry (above) brings it back, inactive.

Global Variables

apiService.getGlobals(): Promise<GlobalVariables>
apiService.updateGlobals(variables): Promise<GlobalVariables>

Import

apiService.importFetch(url, maxBytes?, onProgress?, signal?, options?): Promise<ImportFetchResponse> // POST /import/fetch
apiService.applyImport(payload): Promise<ImportApplyResponse>      // POST /import/apply

importFetch's maxBytes is the largest response that fetch may read. The engine has no format to derive one from - the route proxies Postman and Insomnia exports as well as OpenAPI documents - so the caller states it: the spec paths ($ref bundling, spec re-fetch, the Spec tab's URL box) pass the live maxSpecDocumentBytes from useSpecDocumentLimit, and the format-agnostic import URL box passes nothing, leaving the engine's transport ceiling. Over the bound is a 413 whose message names it, raised while the body is arriving rather than after it has been buffered whole.

importFetch's third argument is what asks the engine to stream the download (issue #882): with an onProgress callback the call goes through httpClient.stream, which sends Accept: text/event-stream and reports {received, total} as the bytes land - total being null whenever the upstream declared no Content-Length. Without it this is the buffered POST it has always been, which is what $ref bundling and spec re-fetch want: they have nowhere to draw a bar and no reason to pay for a stream.

Two things httpClient.stream does that request cannot. Its timeout is an idle one, so a 10 MB document arriving steadily is no longer racing the budget - what is bounded is the stall, not the transfer. And a response that comes back as buffered JSON yields one buffered message instead of failing, because the app and the engine sidecar are not updated together and an older engine answers this request the way it always has.

importFetch takes a fourth argument, an AbortSignal, and it is what actually stops a download (issue #893). Abandoning the iteration releases the stream, but a caller that is not itself iterating - a dialog closing while importFetch sits in the loop on its behalf - has no way to reach that, so 0.22.0 shipped a transport that could cancel and a dialog that never asked it to. An abort raises an AbortError, deliberately distinct from the idle stall's Request timeout: both end in an AbortController, and a deliberate cancel reported as a timeout is an error banner about a failure nobody had.

Both forms of importFetch budget the call from the engine's fixed stall, not from the defaultTimeout setting (issue #2836): the engine abandons a fetch after IMPORT_FETCH_STALL_TIMEOUT_MS (30 s, mirrored from constants::import_fetch::STALL_TIMEOUT_MS and pinned by import.engine-parity.test.ts) of near-silence whatever the setting says, so the client arms that plus the 10 s grace (40 s). The buffered form's 40 s is a total, so a steady download slower than that still aborts client-side while the engine keeps reading; closing that needs a progress-aware timer, which the buffered callers ($ref bundling, spec re-fetch) have no stream to feed.

importFetch's fifth argument, options: ImportFetchOptions, marks the fetch as a $ref a document asked for rather than a URL a person typed (issue #2364): { reference: true, sourceUrl? } adds those two fields to the body of both the buffered and the streamed form, and the engine then follows no redirect and refuses a loopback or link-local peer other than the source's own host and port (see POST /import/fetch). Only ref-bundler sets it, with sourceUrl the URL of the document the ref was found in (the intermediate document for a nested ref) and absent for a picked or pasted document, whose references can then reach no local peer. Without it the body is exactly {url} or {url, maxBytes}: the import dialog's URL box, the Spec tab's URL box and a spec re-fetch's own document are the user's URLs and stay that way. Every layer between the bundler and importFetch (ExternalRefIntake.fetchUrl, BatchIntake.fetchUrl, SpecRefetchIo.fetchUrl) forwards the options as its second argument, and TypeScript will not flag a wrapper that drops it.

applyImport sends a whole parsed import - collections, requests, environments and spec documents - in one atomic call. Items reference each other by opaque tempIds and the engine returns the temp-id -> real-id idMap; a rejected payload persisted nothing, so there is nothing to roll back. An OpenAPI import puts the document in the specs section and binds its root collection with openapi.specTempId, so the spec, the binding and every request's specOperation land in the same transaction - specs: [] is sent for every other format rather than omitted, so the payload is one shape. Imported globals are not in this payload: they are a singleton written through updateGlobals after the apply succeeds. See import-collections/README.md for the pipeline and engine/api-reference.md for the contract.

Execution

apiService.composeRequest(data): Promise<ComposedRequest>
apiService.executeRequest(data, signal?): Promise<SanityResult>
apiService.startLoadTest(data): Promise<StartLoadTestResponse>
apiService.startScenarioRun(data): Promise<StartLoadTestResponse>

startLoadTest and startScenarioRun are the same POST /runs endpoint and the same 202 {runId} answer - the payload is what selects the executor. A scenario states its work as an ordered collection ({scenario: {source: "collection", collectionId, recursive?, iterations?, data?, dataFileName?, dataFileHash?, dataFileCastNumbers?}}), so it carries no method/url, and its iteration count lives inside the block rather than beside a load-test mode. data is the parsed rows of a data file (services/data-files/), sent inline because the engine never opens a file, and dataFileName / dataFileHash name that file beside them (issue #2051): the picked file's name and the SHA-256 of its bytes, never its path, so the run records which file drove it. dataFileCastNumbers (issue

2540) is the picker's Read numbers as numbers (parsed.castNumbers), sent

beside them on every run with a file, so the run records how its rows were typed; the engine stores it only when true. iterations is omitted when the user left it blank, so the engine's "absent means one pass per row" rule stays in one place. Both send allowScriptRequests, for the same reason: every step runs the scripts a Send of that request would run. The engine resolves the whole plan before answering, so an empty collection, a step that will not compose, or a plan over maxScenarioSteps is a 400 with no run row created - a failed start leaves nothing to clean up.

All four run-starting calls (executeRequest, executeStreamRequest, startLoadTest, startScenarioRun) stamp origin: {kind: "app"} on the payload (#1817), set after the caller's spread so a payload cannot claim another. The engine records it on the run, and History reads it back: an unstamped run is other, indistinguishable from one a script started. The type is RunOrigin (types/domain.ts); listRuns takes the kind as origin and sends GET /runs?origin=. See engine/api-reference.md for what the engine validates.

executeRequest also stamps includeParsedBody: false (#2544), at the same choke point and after the same spread. The pane is built from bodyRaw, so the engine's parsed copy of a JSON body is a second tree that the daemon builds, serializes and holds on its heap and the renderer then parses and never reads; declining it answers body: null. The MCP server does not send it - its run_request result exposes the parsed body to the agent, so it keeps the engine's default (electron/mcp/tools.test.ts asserts the payload). The streaming send answers 202 with no body, so the flag is not part of it.

executeRequest budgets its abort timer as a worst case for the payload (#2836, executeBudgetMs in lib/execute-budget.ts). One POST /execute runs the pre-request script, the late OAuth 2.0 token fetch, the transfer and the test script in sequence, so the client arms the request timeout (the defaultTimeout setting, or the payload's own timeout if larger; 300 s when the config cache is cold) once for the transfer, again when auth.mode is oauth2 (the token fetch is bounded by the same request timeout), plus the scriptTimeout setting (60 s when cold) for every enabled script.pre / script.post element in elements, plus the 10 s grace. The engine gives each script element its own deadline, so a collection's script and the request's are two terms. A payload with neither OAuth nor a script is exactly the setting plus the grace, so a hung engine is declared dead as fast as before for the common send. The MCP client keeps a copy in electron/mcp/execute-budget.ts (the main process cannot import renderer modules); execute-budget.parity.test.ts holds the two to the same number. fetchOAuth2Token has no script to wait for and stays at the setting plus the grace.

executeRequest takes the builder's Cancel as signal (#3352), handed to httpClient.post, whose request() composes it with that abort timer the way stream() composes a caller's signal with its idle timer. A cancel rejects with stream()'s AbortError, never with the timeout's "Couldn't reach Vayu's engine in time.", and a signal that is already aborted puts nothing on the wire.

Aborting the fetch closes the connection, and the engine's buffered POST /execute watches for that (#3383): it cancels the transfer if it has not finished, about a second later at most, and records the run stopped rather than completed. A request already on the wire may still have reached its target, and the variable writes of its scripts still land. The builder's and the History copy's send paths therefore invalidate the Recent sends, History and variable queries for a cancelled send as they do for an answered one; only the response is dropped.

startLoadTest takes rows too, as a top-level data array (issue #993): the load dialog's file picker parses the file and sends the same array it previewed, and the engine binds one row per request the run sends. Omitted when no file was picked - a present-but-empty array is refused engine-side, so "no data set" has to be the absent key rather than [] - and never sent beside a scenario block, whose rows are scenario.data and bind per iteration.

failOnSchemaError rides the design-mode payload beside environmentId, from the dialog's Fail steps on schema errors switch (issue #720), and is omitted when off: the engine defaults it to false, so absent already says what the user asked for, and only a run that wanted the gate carries the key into its stored snapshot - where SampledSchemaValidation reads it back to say so. It is never sent on a load payload, whose executor validates after the run has drained and cannot demote a step on it.

stopOnError follows the same shape (issue #2526): top-level on the design-mode payload, from the dialog's Stop the iteration on a script error switch, omitted when off and never sent on a load payload, whose executor does not read it. Off, the engine's default, an errored step (a script that threw, a request that got no response) stays errored and the iteration walks on, as in Postman; on, every errored step ends its iteration. What an error that did end one cost comes back as stepsNotRun, which the renderer reads on three layers: the report's scenario.stepsNotRun (the run tab's header prints "N steps did not run" beside the iteration tally), and stepsNotRun on the step frame and on the stored row's trace (the step that ended its iteration prints "Ended this iteration: N steps did not run" in its expansion). Each is absent, never 0, when nothing was lost, and a report from before the field has none.

Adding a load mode beside the block makes it a scenario load run (issue

357): the same plan, driven by concurrency virtual users on the event loop.

The presence of mode is the whole discriminator, so a design-mode payload must carry none at all - not a falsy one - and RunCollectionDialog therefore spreads the load fields in rather than always sending them. The dialog offers the three closed-loop modes: constant_concurrency and ramp_up send duration (and, for the ramp, startConcurrency and rampUpDuration, camelCase with "Ns" strings), while iterations sends the top-level total of passes and no duration; the top-level iterations is distinct from scenario.iterations, which is sent only when Load test is off. constant_rps, and any non-zero rps/targetRps on any mode, is a 400: an open-loop arrival rate over a multi-step sequence is an arrival-rate executor the engine does not implement, and it is refused rather than quietly run closed-loop. Such a run's type is load, so it streams metrics ticks and not step events - the caller must attach loadTestService, not scenarioRunService.

A scenario run also takes a top-level elements override (issue #1495, wired into RunCollectionDialog by issue #1552): {timers?: "asConfigured" | "off", scripts?: "asMarked" | "allInline" | "allDeferred", includeScriptTime?: boolean}, documented in full at api-reference.md. It rides beside mode/scenario, never inside the scenario block, and RunCollectionDialog sends only the fields the user changed from the engine's own default - the same omitted-when-default rule failOnSchemaError follows. timers is wired to timer.pacing/timer.think end to end and applies to a design-mode run exactly as it does a load run, so the dialog offers that control regardless of Load test; scripts picks whether a script.* element runs inline on the event-loop worker or stays deferred to the post-run replay, and has no effect on a design-mode run (which already runs every script inline), which is why the dialog offers that one control only once Load test is on. Since issue #1594 the single-request startLoadTest payload has an elements attachment point too - its own step-level elements ride under requestElements instead (a distinct key, because this endpoint's own elements is the override block, not a script source) - and LoadTestConfigDialog sends the same elements: {scripts} override there once the user changes the dialog's Scripts control from its "asMarked" default, the one control the single-target payload's own preRequestScript warning needs: "allInline" is what makes a pre-request script actually reach the wire under load, since an unmarked one otherwise never runs on this path either. A disabled element is left out of requestElements (withoutDisabled, issue

3050): the pipeline skips it, and the engine no longer refuses a disabled

scenario-only kind there. An enabled timer.pacing, timer.throughput, control.* or metric.record, the request's own or inherited, never reaches the payload - the dialog blocks Start and offers the collection run instead. A collection's own script.setup / script.teardown (the collectionOnly kinds) is left out too (withoutInheritedCollectionOnly, issue #3070): a single-request run never takes a collection's lifecycle scripts, and the engine validates requestElements as a request's own. Send and code generation, which compose through POST /compose, keep them, and leave out the request's own disabled and incomplete draft elements instead (sendElementsParts, issue

3066; see Elements below). The load run does not: the engine validates its

requestElements, and the dialog's notices read the request's full list. LoadTestConfigDialog offers no Timers twin, but not because the engine ignores the override there - elements.timers applies to a single target's own timer.think exactly the way it does to a scenario step's - the dialog simply has no timer control of its own on this path to pair it with yet.

What comes back for one differs in two places worth knowing. GET /runs/:id returns the resolved manifest in place of the block that was sent ({source, collectionId, recursive, iterations, dataRowCount, dataFileName?, dataFileHash?, dataFileCastNumbers?, steps[]}, the two file keys present only when the run named its data file and the flag only when its numbers were cast, each step {index, requestId, name, method, url} with the stored url, never a composed one) - that is what the run tab's context bar reads, through run-scenario.ts. The paginated GET /runs list row cannot carry the manifest and instead carries summary.scenario ({collectionId, iterations, recursive, stepCount, dataFileName?, dataFileHash?, dataFileCastNumbers?}), present on any row whose snapshot carries a scenario block - so a scenario load run gets it too. The history row reads it because a run whose work is a sequence has no url or method for the ordinary row to show, and that is true of both executors.

A scenario load run's report carries the per-step breakdown the design-mode runner has no need for: scenario.steps[] ({index, name, requestId, method, executed, errors, httpErrors, noResponse, latency:{min,p50,p95,p99,max}}) plus virtualUsers and iterationsAbandoned. It stores no per-step results rows, so that array is the only per-step record such a run keeps.

It also carries scenario.assertions ({passed, failed}, #2820) when the run made at least one exact assertion: every assert.* outcome, required extract.* miss and inline pm.test call, counted on every completion. It counts assertions, where scenario.failed counts step executions in which one failed (#2824, once however many), and the report's error rate stays HTTP-only, so a run of 200s that failed every assertion reads a 0% error rate and a non-zero assertions.failed. Absent, never {0, 0}, for a run with no such assertion, a collection run and a report stored before the field. It is the report's top-level assertions.exact too (#3537), and the renderer reads that block, falling back to scenario.assertions from an older engine, through reportAssertionsOf (components/shared/run-assertions.ts): the verdict (reportOutcome) directly, RunKeyMetrics' fourth tile and the Overview's Assertions card through exactAssertionsOf.

A step's errors is the run's one error definition (a response outside 2xx/3xx, or no response) and equals httpErrors + noResponse. Only a noResponse execution, or a jump the run could not honour (#2974), ends its iteration; an HTTP error status does not. httpErrors and noResponse are optional in the renderer's type because a report stored before the engine split the tally lacks them; the Steps table shows the split in the Errors cell's tooltip when both are present and the bare count otherwise.

A step also carries tests ({sampled, passed, failed}) when its own post-request script was replayed against that step's sampled responses - the deferred per-step validation. The key is absent for a step that asserted nothing or whose script drew no sample, which is not the same claim as zero failures, so the table shows a dash there rather than a 0. The Tests cell reads tests.sampled against the step's deferred count ("23 of 2,270"), with the passed / failed split in its title; a step with no deferred (a report stored before the engine wrote it) keeps the plain passed / failed cell. The line above the table adds "Iterations cut short" when iterations - iterationsCompleted - iterationsAbandoned is above zero, the iterations a deadline or Stop ended.

A design run's list row carries one thing the detail route says at greater length: resultSummary ({statusCode, latencyMs}), the outcome of its single exchange. GET /runs/:id attaches the whole result instead, trace and bodies included, which is why the list carries the two numbers rather than that - and why the context bar's Recent sends section is one list call and no report fetch. A terminal collection run's row carries {passed, failed, skipped, errored, stopped, verdict} from its stored summary (#2954, stopped #3397: a step a Stop cut short, in no failure count), each key only when recorded; the renderer reads failed, errored and a verdict of "failed" (a completed run with any of them gets the failed glyph and a line naming the missed budgets and the step counts, #3458, #3539) and the MCP list_runs rows read the whole summary. A "passed" verdict changes nothing on the row. A load run's results are unbounded and are never read for one; once the run is terminal its row carries {rps, p95Ms, errorRate, verdict} from the run's stored summary instead (#2130, GET /runs), plus, on a run that asserted or errored, the stored assertions block ({exact, sampled, errored, teardownFailed}, #3537) with assertionsPassed and assertionsFailed summed over its two populations (#2820, #3458). The renderer reads the block (the row's verdict and its result line, through rowAssertionsOf), and an older engine's flat assertionsFailed as exact in its place; assertionsPassed has no renderer reader and is there for the MCP list_runs rows. A load run whose drain a Stop cut with requests outstanding also carries drainCut ({cancelled},

3538; absent otherwise), the report's summary.drainCut too: the run stays

completed and its verdict stays the stored budget one, and rowOutcome / reportOutcome read the cut as Not judged ahead of any met-budget reason (run-outcome.ts). A terminal capacity run's row also carries capacity ({stopReason, maxHealthyConcurrency, kneeConcurrency}, the last two omitted when the search found no such level, #2930), which the row's result line reads in place of the run-average rps; an engine that predates it sends none.

composeRequest (POST /compose, issue #226) resolves {{variables}} and inherit auth engine-side and returns the payload the other two accept unchanged - every send site composes first, so nothing is interpolated twice. For a request a pre-request script runs before, the answer keeps the names a scope answers written as {{name}} and lists them in deferredVariables (issue #2521; a ComposedRequest member, sorted, absent when none): the send resolves them after the script. The list describes the composition, not the request, so the composing hook drops it from the payload a send posts onward to /execute or /runs, and only the Code section, which calls apiService.composeRequest itself, reads it. A send also states nothing about hosts: only the MCP server attaches a targetPolicy to its sends.

GraphQL schema introspection is a send site too (lib/graphql/introspect.ts, issue #228): it composes the endpoint, overlays the introspection query onto the composed url / headers / auth, and executes that - which is how an endpoint whose credentials live in the Auth panel gets introspected at all. It sends the composed request's auth but neither its body nor its script parts.

A Send-with-row carries one extra field (issue #601): data, the row the UrlBar's caret picked, added beside the composed payload rather than passed through POST /compose. {{data.*}} survives composition by design, so the tokens are still written when /execute binds them against the row; composing the row in would be composing twice. Both send handlers take it - buffered and streaming - because the engine binds a row on either path, and a row silently dropped on one of them is the written-but-never-read defect. An ordinary Send passes no argument at all, so its payload is byte-identical to what it was.

The row's names do reach composition, though (issue #1007): buildSendBody sends dataColumns: Object.keys(row) on POST /compose, because a bare {{username}} is a name the scopes can answer and composition has to be told to leave it for the bind instead. Names only - a value there would be this row's value written into a payload composed once - and absent for an ordinary Send, so that path is still byte-identical. LoadTestConfigDialog carries the same field for a run given a data file (config.dataColumns, the picker's parsed column list rather than a re-union of the rows' keys), and a collection run sends none: the engine composes those steps itself and fills the set from the run's own rows.

It is the only send site that sets transient: true (issue #382), because it is the only one the user did not initiate. The engine then runs it in full and records nothing: no History entry, no result trace holding the credentials composition resolved, and no retention prune evicting a real run. It also carries the target's environmentId onto the execute payload, which is what scopes the engine's cookie jar - without it a cookie-session endpoint answered real requests and failed introspection alone. Every other send site omits the flag and is recorded as usual; see api-reference.md.

Run Management

// Paginated, filtered history (newest first). Rows carry a compact `summary`
// (url/method/mode/duration/concurrency/comment), not the full configSnapshot.
// `limit: 1` makes `pagination.total` a count of the runs the filters match,
// which is how Settings counts runs without downloading them (#2979).
// Older pages are read by cursor, not offset (#2978): pass the previous page's
// `pagination.nextBefore` as `before` (the engine owns its `<startTime>:<id>`
// spelling; null on the last page). `listRuns` sends its default `offset=0`
// only when there is no cursor, because the engine refuses `before` beside a
// non-zero offset (`before_with_offset`). `offset` stays for a caller that
// jumps to a page number; the MCP server keeps using it.
apiService.listRuns(params?: RunListParams): Promise<RunListResponse>
apiService.getRun(id): Promise<Run>            // full configSnapshot
apiService.getRunReport(id): Promise<RunReport>
// Response headers/bodies captured for a run's samples. Its own request, not
// fields on the report - see below.
apiService.getRunSamples(id, { limit?, offset? }): Promise<RunSamplesResponse>
apiService.stopRun(id): Promise<StopRunResponse>
apiService.deleteRun(id): Promise<void>

deleteRun on a run that is still in progress stops it engine-side first, so it takes as long as the stop does, and it rejects with a 409 if the run's worker has not finished writing in time - nothing is deleted in that case. Callers must handle that rejection: HistoryList turns it into a toast telling the user to retry. Settings' Clear run history does not loop over it: apiService.clearRuns() is one DELETE /runs, answering { deleted, keptPinned, deletedIds }, and the engine's pass keeps what retention keeps - a pinned baseline and a run still running or pending (#2429). A rejection is one failure toast and no tab is closed; the list is re-read either way, since batches the engine committed before failing are real. Naming a run through deleteRun still deletes it pinned. The wording of that toast is the caller's, keyed off statusCode, rather than the engine's message - which is a caller's choice now that httpClient reads the message on every error shape (issue #173), not a constraint.

Captured response bodies are fetched separately, and lazily. A load run stores the response headers and body for its failures, its slow outliers and a few exemplars of each status code; GET /runs/:id/report deliberately does not carry them, because that endpoint loads and JSON-parses every result row for the run on each fetch and the dashboard polls it. useRunSamplesQuery(runId, enabled) (queries/runs.ts) wraps getRunSamples and is enabled only once a reader expands a sample - passing true unconditionally would reintroduce exactly the cost the split exists to avoid. It returns a Map keyed by resultId, joined against report.results[].id.

The history Samples tab consumes it (the dashboard shows the same tab for a finished run, #2220) and renders CapturedResponseNotice (truncated / dropped for budget / binary) and CapturedDataWarning (the run stored responses verbatim, including anything credential-shaped). Both notices live in components/shared, beside the shell they annotate.

A sample's response.body is text only when response.bodyEncoding is absent or "utf8" (#3159). A body that is not valid UTF-8, or holds a zero byte, comes as "base64" of the stored bytes, the spelling /execute and the inbox use, and SampleRequestCard reads it through capturedBody (history/main/sample-body.ts) into decodeResponseBody with the sample's headers: a text type reads as text through its declared charset, any other type reaches the viewer as rawBytes and shows as binary rather than as base64. A body marked base64 that does not decode draws a "Couldn't read the body" notice, and the headers stay. This is separate from binary: true, which stores no bytes at all.

A sample carries the response side only, so its request headers are the composed ones. GET /runs/:id/samples returns response headers and body; what a sample viewer shows for the request comes from the run's composed request, not from a sent record, because the load transport keeps none. So a sampled capture can differ from the wire in the way the design-mode sentHeaders record exists to state (issue #664): the two headers the engine derives at send time - the body-implied Content-Type and the default User-Agent - do not appear, and a blank Content-Type or Cookie row is listed although neither is sent (any other blank row is sent empty, issue #3220, so it matches). For load samples this is recorded as permanent (issue #677 item 7): which completions are sampled is decided when they finish, so a record for the few that are kept would have to be built for every transfer. Design-mode traces store sentHeaders and do not diverge.

A sample whose transfer was a stream also carries response.events (issue

657) - {items, totalEvents, eventsTruncated}, parsed engine-side out of the

stored text/event-stream body. Both surfaces render it through the shared ResponseEvents, the component the request builder's Events tab uses, so a sampled stream reads the same way a sent one does. Absent - not an empty node - for every sample that did not stream, which is what gates the tab.

Scripting

apiService.getScriptCompletions(): Promise<ScriptCompletionsResponse>

OAuth 2.0

apiService.fetchOAuth2Token(data): Promise<OAuth2TokenResponse>        // POST   /oauth2/token
apiService.getOAuth2TokenStatus(cacheKey): Promise<OAuth2StatusResponse> // GET  /oauth2/token?key=
apiService.clearOAuth2Token(cacheKey): Promise<void>                   // DELETE /oauth2/token?key=

// Interactive Authorization Code flow (engine-hosted loopback + PKCE)
apiService.startOAuth2Authorize(data): Promise<OAuth2AuthorizeStartResponse>  // { attemptId, authorizeUrl, redirectUri, expiresAt }
apiService.getOAuth2AuthorizeStatus(attemptId): Promise<OAuth2AuthorizeStatus>
apiService.completeOAuth2Authorize(attemptId, callbackUrl): Promise<OAuth2AuthorizeStatus>

These back the OAuth 2.0 auth editor. TanStack Query wraps the non-interactive ones in queries/oauth.ts (useOAuth2TokenStatusQuery - polls status ~30s; useFetchOAuth2TokenMutation, useClearOAuth2TokenMutation). The token cacheKey is computed client-side by services/oauth/cache-key.ts, byte-identical to the engine so the app and engine agree on cache slots without a round-trip. The key reads the config's authorizationParams, tokenParams and refreshParams rows (issue

2536) beside the token URL, client id, credentials id and password-grant username, so

two audiences sent as rows are two cached tokens; a row whose key names a credential (client_assertion, X-Api-Key; services/oauth/credential-params.ts) is keyed by its key alone, so the key never carries the secret. scope, audience and resource themselves are still not in it. The interactive flow is orchestrated in services/oauth/authorize.ts (opens the system browser or an embedded Electron window, then polls the engine). The engine owns the deadline and reports it as expiresAt (epoch ms) on the start answer; the app keeps no clock of its own. The loopback poll runs until expiresAt plus EXPIRY_GRACE_MS, so the engine's own failed "Authorization timed out" answer arrives first, and the embedded window is handed the time remaining (timeoutMs on oauthOpenWindow, which the main process refuses unless it is a positive finite number).

runInteractiveAuthorization(config, signal?) stops on an AbortSignal: the poll delay and the embedded-window wait both end at once, every engine call is preceded by a check, and it rejects with InteractiveAuthCancelledError (a subclass of InteractiveAuthError that callers skip reporting). The renderer cannot close the embedded window or the system browser tab, so an abort stops waiting and ignores whatever the window answers later. TokenStatusRow passes the signal from stores/oauth-signin-store.ts, which keys one sign-in per token cache key.

HttpClient.delete takes an optional params argument so the token-clear call can pass ?key=.

SSE Client (services/sse-client.ts)

Server-Sent Events client for a run's live stream - load-test metrics, and a collection run's per-step progress.

Features

  • Single endpoint: Connects to /runs/:runId/live. The engine retains a replayable tick topic, so the client connects immediately after POST /runs with no attach race - it replays from offset 0 and tails to the complete event (even for sub-second runs). The client records the lastEventId of every metrics, step, plan and monitor frame (one id sequence; the complete frame carries none), and a connect to the run it already holds frames for opens ?lastEventId=<last id> so the engine resumes after it (issue #3571). A first attach, or an attach to another run, sends no parameter. A resume keeps the held metrics and start time; a start resets them.
  • No custom reconnect loop: The engine sends an explicit complete event at normal run end, carrying the run's terminal status (issue #2140). Transient CONNECTING errors are left to the browser's built-in EventSource retry. onClose is called as onClose(status, { frame }) and the second argument is what tells the two null statuses apart: a complete frame with no status (the engine's 60 s settle timeout, the rare case) is { frame: true }, and a CLOSED readyState with no frame at all is { frame: false }. Neither is a terminal status. The load-test service reads the stored report (GET /runs/:id/report) for both: a terminal metadata.status finishes the run. On running or pending, a bare frame is polled again every 500 ms for up to 30 s, since the engine ended the stream and the row is about to settle, and finishes the run when it does; a dropped connection is not waited on, because the run may well still be going. Either way, a report still live at the end shows the dashboard's "Lost the live metrics stream" callout and the user's Reconnect re-attaches, resuming after the last frame held (issues #1925, #3571). Nothing reconnects on its own. ScenarioRunService ignores the second argument.
  • Event Handling: metrics events, step events, monitor events, plan events, complete event, error handling
  • One client, and a hand-off when it changes hands: the client is a singleton, so a second connect takes the socket from whoever held it. That subscriber's onSuperseded runs first, before the new stream opens, so it can give up its wake lock and its OS progress claim (issue #1417). onClose is not used for this: a close says the run ended and the stored report is worth fetching, where a takeover says only that the app stopped watching a run the engine is still executing. disconnect() tells nobody - a subscriber hanging up on itself, and a stream that ended on the engine's complete frame, are not superseded by the next run to start
  • Metrics Parsing: mapSseMetrics() transforms the engine's camelCase blob to the frontend LoadTestMetrics shape (includes drops, queue-wait, percentiles, bytes, status-code map). It marks the tick live, maps a gate frame's secondSamples / secondP50Ms / secondP95Ms / secondP99Ms and every frame's cumulativeP50Ms / cumulativeP95Ms / cumulativeP99Ms, and leaves an absent key undefined and a null as null, never a 0 (issue #2385). The window's own latencyP50Ms / latencyP95Ms / latencyP99Ms follow the same rule: the engine sends them null for a window with no completion, and they stay null (issue #2386). latencySamples is not mapped; nothing in the app reads it. A gate frame's cumulativeLatency and cumulativePhases (the run-so-far latency distribution and the per-phase means and percentiles, issue #2782) map to cumulative_latency / cumulative_phases as sent: null is "nothing completed yet", absent is "not a gate frame" (for the phases also "phase histograms off"). They live on the gate frame alone, so the dashboard reads the latest frame carrying the key from its buffer, never the newest tick. Each phase carries {meanMs, p50Ms, p95Ms, p99Ms, maxMs, count}; the live view turns them into the report's timingBreakdown shape for the waterfall and the percentile table, and shows the latency distribution's count as "N completions so far". A scenario load run's gate frame also carries scenario ({iterations, iterationsCompleted, iterationsAbandoned, stepsExecuted, steps: [{index, name, executed, errors}]}, issue #2823), mapped as sent onto LoadTestMetrics.scenario: absent is "not a gate frame" or "not a scenario load", never a zeroed block. The live sequence panel reads it from the latest frame carrying it (utils/liveScenario.ts).
  • Capacity state: a capacity run's frames carry capacity: {level, levelElapsedMs, levelsJudged, stopReason?} from tick 0 (issue #2928), and mapSseMetrics() passes it through as LoadTestMetrics.capacity unchanged. Absent is "not a capacity run" (or an engine from before #2928), never a zeroed level; level 0 is a search that has not opened its first level, and stopReason appears only once the search has ended. A stored tick never carries it. No renderer component reads it yet (the live card is #2929); until it lands the only reader is MCP get_live_metrics
  • Step Parsing: parseStepEvent() narrows a scenario run's step payload and returns null for one it cannot read. A malformed event is dropped, never defaulted - the step list keys on (iteration, stepIndex), so a defaulted 0:0 would collide with the real first step's row rather than merely say nothing.
  • Monitor Parsing: parseMonitorEvent() narrows a monitor frame the same way and returns null for one it cannot read. A sample defaulted to timestamp: 0 would join onto the very start of the run's timeline and draw a reading at a moment it was never taken; individual non-numeric entries are dropped, because the rest of the scrape is still real data.

Usage

sseClient.connect(
  runId: string,
  onMessage: (metrics: LoadTestMetrics) => void,
  onError: (error: Error) => void,
  onClose: (status: SSETerminalStatus, info: { frame: boolean }) => void,
                                                  // how the run ended, or null; frame = the engine's
                                                  // `complete` arrived (false: the connection dropped)
  onStep?: (step: ScenarioStepEvent) => void,     // scenario runs only
  onMonitor?: (sample: MonitorSample) => void,    // runs with a `monitor` block only
  onPlan?: (plan: ScenarioRunPlanEvent) => void,  // scenario runs only
  onSuperseded?: () => void                       // another run took the client
);

sseClient.disconnect();
sseClient.isConnected(): boolean

Event Types

  • metrics: Real-time metrics update (JSON payload). Load runs only - a scenario run's work is sequential, so a per-tick aggregate would describe one request at a time.
  • step: One step execution of a scenario run - {iteration, stepIndex, name, outcome, statusCode, latencyMs}. Listened for only when onStep is passed, since a load run never emits one.
  • monitor: One scrape of the run's monitored endpoint - {timestamp, series}. Listened for only when onMonitor is passed. Interleaved with metrics ticks on one id space, so Last-Event-ID resume replays both in the order they happened.
  • complete: The run reached a terminal status
  • error: Connection error (triggers reconnection)
  • open: Connection established

API Endpoints (config/api-endpoints.ts)

Centralized endpoint configuration:

export const API_ENDPOINTS = {
  BASE_URL: ENGINE_BASE_URL, // http://127.0.0.1:<port>, from config/network.ts

  // Health & Config
  HEALTH: "/health",
  CONFIG: "/config",
  // What a send adds on its own, resolved from config by the engine.
  // `?scope=design|load` selects which send - see getRequestDefaults above.
  REQUEST_DEFAULTS: "/request-defaults",

  // Collections
  COLLECTIONS: "/collections",
  COLLECTION_BY_ID: (id: string) => `/collections/${id}`,

  // Requests
  REQUESTS: "/requests",
  REQUEST_BY_ID: (id: string) => `/requests/${id}`,

  // Batch reorder for both entity kinds - one drop, one call, one transaction
  REORDER: "/reorder",

  // Cookie jar - GET reads every scope, DELETE clears one or all
  COOKIES: "/cookies",

  // Workspace backup - one VACUUM INTO snapshot into `backups/` beside the
  // database, with retention. A verb path for the reason the inbox uses one:
  // the engine takes a snapshot and the file is not a row anything reads back.
  // There is no restore counterpart on purpose - restoring is a manual copy
  // with the engine stopped, which is why the card prints the path.
  WORKSPACE_BACKUP: "/workspace/backup",

  // Execution
  EXECUTE_REQUEST: "/execute",
  START_LOAD_TEST: "/runs",

  // OAuth 2.0
  OAUTH2_TOKEN: "/oauth2/token",
  OAUTH2_AUTHORIZE_START: "/oauth2/authorize/start",
  OAUTH2_AUTHORIZE_COMPLETE: "/oauth2/authorize/complete",
  OAUTH2_AUTHORIZE_STATUS: (id: string) => `/oauth2/authorize/${id}`,

  // Runs
  RUNS: "/runs",
  RUN_BY_ID: (id: string) => `/runs/${id}`,
  RUN_REPORT: (id: string) => `/runs/${id}/report`,
  RUN_STOP: (id: string) => `/runs/${id}/stop`,
  // Captured response headers/bodies, fetched only when a sample is expanded
  RUN_SAMPLES: (id: string, limit: number, offset: number) =>
    `/runs/${id}/samples?limit=${limit}&offset=${offset}`,

  // Webhook inbox - engine-hosted listener that records what is sent to it.
  // START is a verb path: an inbox lives for the engine process, so the
  // POST-creates/PUT-updates split does not apply to it.
  INBOX: "/inbox",
  INBOX_START: "/inbox/start",
  INBOX_STOP: (inboxId: string) => `/inbox/${inboxId}/stop`,
  // PUT patches the canned response; DELETE removes the inbox and its captures.
  INBOX_BY_ID: (inboxId: string) => `/inbox/${inboxId}`,
  INBOX_CAPTURES: (inboxId: string, limit: number, offset: number) =>
    `/inbox/${inboxId}/requests?limit=${limit}&offset=${offset}`,
  INBOX_CAPTURES_CLEAR: (inboxId: string) => `/inbox/${inboxId}/requests`,
  INBOX_LIVE: (inboxId: string) => `/inbox/${inboxId}/live`,

  // Collection mock server - a loopback listener answering the collection's
  // saved examples. Verb paths for the same reason the inbox uses them. No PUT
  // and no DELETE: the route table is a start-time snapshot, so changing what a
  // mock serves means starting another one, and stopping is what ends it.
  MOCK_SERVER: "/mock",
  MOCK_SERVER_START: "/mock/start",
  MOCK_SERVER_STOP: (mockId: string) => `/mock/${mockId}/stop`,
  MOCK_SERVER_ROUTES: (mockId: string) => `/mock/${mockId}/routes`,

  // Real-time stats (SSE)
  METRICS_LIVE: (runId: string) => `/runs/${runId}/live`,

  // Time-series metrics (JSON, paginated) - used to hydrate history. With
  // maxPoints the whole series in one response, downsampled when the run has
  // more ticks than that (#2547); the History charts ask for 2000.
  STATS_TIME_SERIES: (runId: string, limit = 5000, offset = 0, maxPoints?: number) =>
    maxPoints === undefined
      ? `/runs/${runId}/metrics?limit=${limit}&offset=${offset}`
      : `/runs/${runId}/metrics?maxPoints=${maxPoints}`,

  // Server vitals scraped during the run (JSON, paginated, same envelope).
  // Fetched by the history view only when the report says the run recorded some,
  // and with maxPoints (the same contract as STATS_TIME_SERIES, #2611): one
  // response, folded when the run scraped more than that; the History charts
  // ask for 2000.
  RUN_MONITOR: (runId: string, limit = 5000, offset = 0, maxPoints?: number) =>
    maxPoints === undefined
      ? `/runs/${runId}/monitor?limit=${limit}&offset=${offset}`
      : `/runs/${runId}/monitor?maxPoints=${maxPoints}`,
};

Note: the old STATS_STREAM SSE constant was removed - live metrics go through METRICS_LIVE only; /stats is now used solely for paginated historical reads.

Request Execution Flow

Single Request Execution

  1. User Action: Clicks "Send" in RequestBuilder
  2. Request Transformation: Frontend format → backend format (raw - no client-side {{variable}} resolution), built by buildComposeBody (modules/request-builder/utils/compose-body.ts, issue #2638). It is the one writer of the inline compose body: Send, the streaming Send, the load run and the History replay all build through it, and so does the context bar's Code section for the editor's draft, so a field added there reaches every one of them
  3. Composition: apiService.composeRequest() → POST /compose - the engine resolves {{variables}} and inherit auth against the request's collectionId chain and the active environmentId, and returns the execute-ready payload (issue #226), naming the collectionId whose chain it read (issue #3461)
  4. API Call: apiService.executeRequest() with the composed payload, unchanged → POST /execute, carrying stream: false explicitly; the composed collectionId is how the engine's scripts read the same chain when no saved row is linked
  5. Response Transformation: Backend format → frontend format
  6. Display: Response shown in ResponseViewer

stream is sent on every execute, never elided. It follows the same never-elide rule as httpVersion and the redirect policy, for a sharper reason: the endpoint's two answers are different shapes, so a caller that let an engine-side default decide would not know which one it was about to parse.

Streaming Request Execution (issue #574)

A request whose Event stream setting is on takes the same composition and a different answer. buildSendBody is shared with the buffered path - the two must put the identical request on the wire, or a stream would measure something Send does not - and only the last two steps differ:

  1. API Call: apiService.executeStreamRequest() → POST /execute with stream: true, answered 202 {runId, eventsUrl, status} at once. There is no exchange yet: the engine has created the run row and handed the transfer to a managed consumer worker.
  2. Tail: useExecutionEvents opens an EventSource on the answer's eventsUrl as given - the engine names where its own events are, and a second spelling of that path in api-endpoints.ts would be a copy that can disagree with the answer. Frames land in execution-events-store; the Events tab renders them live.
  3. Swap to stored truth: on the relay's complete frame the provider fetches GET /runs/:id/report and restore-response.ts maps the trace's events node onto the response, which is the record from then on. One fetch is enough: the engine sends complete only after the post-request script has run and the run row and trace are stored (#3239).

A different EventSource from the SSEClient singleton below. That client belongs to load and scenario runs, is a single connection whose lifetime is the dashboard's, and deliberately never reconnects. This one owns its retry, for the reason the inbox capture stream does (issue #506): EventSource treats any non-200 as fatal, and a reconnect landing inside the engine's stale-claim window meets a 409 run_events_in_use from the claim the previous socket still holds - so a single unlucky disconnect would otherwise end the stream for the life of the tab, silently. Resume travels as ?lastEventId=, which picks up at the frame after the one named, so a dropped consumer re-renders nothing.

An answer missing runId or eventsUrl is a malformed answer and throws, rather than leaving the pane on "streaming" with no run to stop. Refusals - stream with transient, or a stream cap on a payload that declares no stream - come back as a 400 the user has to read, so they are rendered as the response and raised as a toast. A script is no longer one of them: scripts run on a streaming send (issue #575), the pre-request half before the transfer and the post-request half once the stream has terminated.

The payload carries allowScriptRequests here for the same reason the buffered one does (issue #653): the asker is a user at the request editor pressing Send, and the Event stream setting describes the shape of the answer, not what that user's scripts may do. The engine reads the flag before it branches on stream, so a pm.sendRequest behaves identically with the toggle on and off. While only the buffered call sent it, the same button allowed a script-issued request one way and refused it the other.

The renderer sends the inline compose shape ({ request, collectionId, environmentId }) rather than compose-by-id, because Send executes the editor state - possibly unsaved, or a detached History replay copy that has no saved row at all. For the same reason the inline request carries the editor's path rows as params (issue #1764, composePathParams in modules/request-builder/utils/path-variables.ts): the engine fills the URL's :name segments from them. Only the path rows - the query is already in url - and always the key, [] for a request without any: the engine answers an absent params from the stored rows, which would let a row the editor removed fill a segment. Every member of a row is kept (a Postman import's type, description), only the editor id is dropped. All four inline sites send them: Send, a load test, a History replay and GraphQL introspection. requestId is attached to the execute payload afterwards to link the run to the saved request in History; environmentId scopes both composition and the engine's script context / variable persistence. The collection scope reaches the engine's script context through the composed answer's collectionId, which every one of these sites passes on by spreading the answer (issue #3461). A linked requestId's own collection wins, so it changes nothing for a Send of a saved request; an orphaned History replay composes with no collectionId and the answer carries none. useEngine.composeRequest strips only deferredVariables. useVariableResolver() still exists but is preview-only (tab titles, previews, unresolved-token painting) - see variable-resolution.

Auth (bearer/basic/api-key/oauth2) is resolved engine-side from the request's auth object - the app no longer builds Authorization headers itself. When a non-interactive OAuth 2.0 token can't be obtained, the response carries an errorCode of AUTH_REQUIRED (interactive sign-in needed) or AUTH_FAILED, and the request builder surfaces a toast pointing the user at the Auth tab.

headers is an ordered array of { name, value } lines (issue #2466): the Headers table's enabled rows with a key, in row order, a repeated name repeated and each row in the case typed with the spaces and tabs around its name trimmed (toHeaderRows), and POST /compose answers the same shape, so a repeat survives compose to execute. The older single-valued record ({ "Accept": "..." }) is still accepted by the engine, but the app no longer sends it: a record keeps one value per key and sends a different header from the one its table shows. The same holds for POST /runs.

The engine trims the spaces and tabs around every header name (Authorization goes out as Authorization, never as a wire line with a space before its colon) and then requires a token: a name with an interior space, a colon or a non-ASCII byte is a 400 with code invalid_header_name, quoting the name, from POST /compose, POST /execute and POST /runs alike. A name of only spaces and tabs is no name (empty_header_name). A bearer token and an API key's name and value are trimmed the same way when auth is resolved; see the API reference.

Example Request:

await apiService.executeRequest({
  method: "GET",
  url: "https://api.example.com/users",
  headers: [{ name: "Authorization", value: "Bearer {{token}}" }],
  elements: [
    {
      id: "el_1",
      kind: "script.pre",
      enabled: true,
      config: { script: "console.log('Pre-request');" },
      origin: { kind: "request", id: "req_123" }
    },
    {
      id: "el_2",
      kind: "script.post",
      enabled: true,
      config: {
        script: "pm.test('Status 200', () => pm.expect(pm.response.code).to.equal(200));"
      },
      origin: { kind: "request", id: "req_123" }
    }
  ],
  followRedirects: true,
  maxRedirects: 10,
  httpVersion: "auto",
  verifySSL: true,
  disableCookies: false,
  disabledSystemHeaders: [],
  disableUrlEncoding: false,
  requestId: "req_123",
  environmentId: "env_456"
});

elements (issue #1512) is the resolved, ordered list of typed behaviours to run - the collection chain's (root→leaf), then the request's own, minus whatever an inherit.disable entry at any level names (a folder's can name a root element, a collection's the request's own; POST /compose gathers the targets the same way, and the entries themselves are never forwarded), each stamped with its origin. A script is one of these now (kind: "script.pre" / "script.post", config.script the text) - it replaces the old preRequestScripts / postRequestScripts ScriptPart[] fields, which the engine now refuses outright (400 naming elements). The renderer builds the list from its editor state (elementsParts() in request-builder/utils/elements-parts.ts, generalizing the old scriptParts()) and it rides through POST /compose untouched - script text is never interpolated; the by-id compose path (used by MCP) resolves the same list engine-side (compose_elements). The engine runs each element at its kind's phase - see docs/engine/elements.md.

Send leaves out the request's own draft elements that cannot run (issue

3066). POST /execute validates inline elements and refuses the whole

request over one that fails its kind's schema, and an element just added has config: {}. So Send and the Code section (both build through buildComposeBody with onlyRunnable, sendElementsParts) omit a draft element that is switched off, or that fails the app's own check (elementNeeds in lib/elements.ts: missingRequiredKeys, validateElementConfig and missingOperand, the judgement behind the editor's "Needs ..." chip and the save gate). Only the request's own elements are judged; the collection chain's pass through as composed. The incomplete ones come back as leftOut and ride the response as ResponseState.leftOutElements - on a buffered send, a failed one (the handlers take it before the compose call, so a send that throws still says it), and a streamed one, which carries it in execution-events-store for both the live placeholder and the stored response that replaces it. The response's Elements section draws each as Not run - needs <fields>, so a check that did not run is never read as one that passed. The element's own row says the same before the send, collapsed or open, through the mark in the summary's place (describeNeeds, the wording notRunReason builds on): "Needs " for a missing key, <field>: <message> for a refused value. It reads elementNeeds live and shows for every element Send leaves out as incomplete; a switched-off element is left out too but is not flagged, its switch says so. A response restored from History carries none: it is not the send that composed the payload. With the catalogue not yet loaded, disabled elements and the operand rules still apply and a kind's required keys wait for the engine. The engine keeps validating: an element that reaches /execute invalid by another road (an MCP caller, a {{variable}} that resolves badly) is still a 400. A load run composes the chain without the filter.

Redirect policy, protocol and TLS verification are always sent, never elided - and the request's timeout is the deliberate exception. followRedirects, maxRedirects, httpVersion and verifySSL all come from the request's Settings tab and are included on every execute even when they equal the defaults. The engine defaults follow_redirects to true, so omitting a false would follow the 3xx the user asked to inspect - a bug the app shipped with for a long time, when nothing in the renderer sent these fields at all. verifySSL carries the same rule for a sharper reason: the engine verifies unless told otherwise, so an omitted false verifies the certificate the user turned verification off for, and the send fails against the one host the setting exists for. All four go out with startLoadTest(), so a load test exercises the same policy, protocol and trust the request was configured with - there is no separate, load-test-only protocol control; the Settings tab's picker is the only one, and it governs Send and load test alike. httpVersion is "auto" | "http1.1" | "http2": "auto" lets ALPN negotiate, "http1.1" forces HTTP/1.1, and "http2" attempts h2 over TLS with a silent fallback to 1.1 over plain http:// (curl's CURL_HTTP_VERSION_2TLS semantics).

timeout is the one Settings field that is not always sent (issue #2937). A request's own timeout is number | null, and buildComposeBody writes timeout onto the inline compose request only when it is a number. null means "use the defaultTimeout setting", and the engine can only read the live setting when the key is absent: sending today's value instead would pin it on the request, and POST /execute refuses a null. The composed payload carries the key on to /execute and /runs, so Send, a collection run and a load test wait as long as the Settings tab says. A History replay seeds it from the run's recorded body, and Save to request does not write it back.

Postman's protocol switches ride the same rule (issue #1765). disableCookies, disabledSystemHeaders and disableUrlEncoding come from the Settings tab too, and every Send, streaming Send, load run and History replay puts all three on the inline compose request through one helper, protocolSettings() in request-builder/utils/execute-mapping.ts, so the editor's value wins over the saved row's and composition carries them on to /execute and /runs. disableUrlEncoding also changes what the renderer writes: the Params table always reads the URL's query into rows without decoding it (parseQueryParams, issue #1771), and with the flag on joins a row the URL does not already carry back as typed rather than with Postman's query rule, so editing one row rebuilds exactly the query the others held. Turning the flag on or off writes only the flag: the URL and the rows stay as they are. With the flag on, the Sends line and the code snippets substitute path values raw, the Sends line writes a value a {{variable}} brings into the URL, and the literal text around it, as typed, and a query-located API key is appended raw, all matching what the engine sends. With the flag off, the Sends line and the snippets show the line Vayu sends, which is the URL written as Postman's toNodeUrl writes it (issue #2465; the engine's core::encode_url_as_postman, pinned by engine/tests/fixtures/query-encoding-conformance.json). A value a {{variable}} brings in is first encoded by the part of the URL it lands in (issues #1773 and #2465): the path by PATH_ENCODE_SET, the query by QUERY_ENCODE_SET, the fragment by FRAGMENT_ENCODE_SET, and the scheme and authority as they stand. The whole URL is then written: leading whitespace dropped, a backslash before the query a /, user info by USERINFO_ENCODE_SET, the host lowercased and a non-ASCII one written by its punycode name (the url.domainToASCII toNodeUrl calls; the renderer asks URL for it, and a host with no ASCII name stays as typed), and the path, each query key and value and the fragment by their sets, so a literal ", <, >, backtick, { or } in the path is %22 %3C %3E %60 %7B %7D and /a b is /a%20b. % is in no set, so an escape already in the text, a :name path value or a pre-signed URL's signature passes unchanged and nothing is encoded twice; a byte no set holds (+, |, ^, [, ], and a backtick or brace in the query) goes out as typed. A {{token}} is kept whole wherever it sits. resolveUrlTemplate and encodeUrlAsPostman in request-builder/utils/query-encoding.ts are the one writer; prepare.ts runs the same resolver, with the tokens left in place, so a snippet carries the line Vayu sends and not the one typed. The Sends line draws that URL with every secret variable value and auth credential (each encoded spelling too) replaced by ••••; the masking is at render, so what resolves and what is sent are unchanged (#1806). The imported protocolProfileBehavior object itself (postmanProtocolBehavior) is read by the Postman exporter only: GET /requests/:id returns it as the stored JSON text, which the app keeps as a string and never parses, so an import and a Duplicate (which copies that detail read) carry it byte for byte, and nothing sends it. The ordered headers lines every inline compose sends (toHeaderRows: enabled rows with a key, in row order, a repeated name repeated, issue #2466) lose each row's source, so beside them goes bodyModeHeaders (bodyModeHeaders() in request-builder/utils/key-value.ts): the names whose last row the body mode wrote (names compared without case), which a content-type opt-out removes on the wire while a Content-Type the user typed is always sent. A History replay puts the run's recorded list back on its seeded rows.

Example Response:

{
  status: 200,
  statusText: "OK",
  headers: { "content-type": "application/json" },
  body: null,  // { users: [...] } when the request leaves includeParsedBody unset; the app sends false
  bodyRaw: '{"users":[...]}',
  bodyEncoding: "utf8",
  httpVersion: "HTTP/1.1",
  httpVersionDowngraded: false,
  // authNotice: "auth mode 'ntlm' is not executed by Vayu; ..."  (absent here)
  warnings: [],  // [{ code: "cookie_not_sent", message: "..." }, ...]
  clientCertificate: "",
  bodyCapped: false,
  headerLines: [{ name: "Content-Type", value: "application/json" }],
  redirects: [],
  timing: { totalMs: 150, engineMs: 3.4, dnsMs: 10, connectMs: 20, ... },
  testResults: [
    { name: "Token was issued", passed: true, source: "pre", scope: "collection" },
    { name: "Status 200", passed: true, source: "test", scope: "request" }
  ],
  consoleLogs: [
    { source: "pre", scope: "collection", level: "log", message: "Pre-request" },
    { source: "test", scope: "request", level: "warn", message: "slow response" }
  ]
}

testResults entries name the script that asserted them, in execution order: pm.test runs in a pre-request script too, and the Tests pane groups the list by source so an assertion made before the request went out does not read as one about the response (issue #810). An entry restored from a trace written before that carries no source, and is read as the test script's.

Both lists also name the level that wrote an entry, in scope: collection (the root), folder (any collection below it) or request (issue #2522). A request runs every level's scripts and the engine reports all of them. scope is not the console level; it is absent on a trace stored before the field and on a send whose elements carry no origin, and absent reads as the request's own. The Tests list and the Console label an inherited level ("Collection", "Nested collection") and leave the request's own bare. An inline Send resolves the chain in the renderer (elements-parts.ts) and stamps each element's origin.scope itself - the root as collection, every level under it as folder - the same way the engine stamps a stored request's chain. A script that threw at an inherited level is named in preScriptError / postScriptError ("Collection pre-request script failed - ...").

consoleLogs entries name the script that wrote them and the console.* level that was called. A bare string is the pre-structured shape an older engine sidecar sends; console/parse-logs.ts decodes both and is the only place that knows the difference (see the engine API reference).

httpVersion here is the negotiated protocol ("HTTP/1.1" / "HTTP/2" / "" when nothing was negotiated) - an outcome, not an echo of the request's own httpVersion. The Raw tab in the response viewer prints it on the request/status line instead of a hardcoded HTTP/1.1.

httpVersionDowngraded says the request asked for http2 and the connection negotiated something older - the one thing neither httpVersion can say alone, since neither knows about the other. The engine computes it, and the renderer carries it as-is rather than comparing the negotiated protocol against the tab's current setting: a restored or replayed response sits beside request state that may have changed since, and the answer belongs to the exchange. ResponseStatusBar draws it as a warning beside the status chip, and only when it is true. A collection run's step card, whose viewer has no status bar, draws the same line from the step's trace. Load runs and collection runs both carry the whole-run count of requests that fell back as report.summary.httpVersionDowngraded: LoadTestDetail shows it next to the requested protocol - without it a run measured entirely over HTTP/1.1 still read "HTTP/2" there (#215) - and ScenarioRunView shows it in the run's header (#3262).

Load runs also carry report.summary.connectionReplays, the count of requests libcurl re-sent on a new connection after the server dropped or refused a reused one before answering (#2799). The app does not draw the number: the engine's connection_replayed entry in report.warnings is the surface, and RunWarnings renders it as a callout titled "Some requests were re-sent after a dropped connection" with the count in its message. The number is for MCP and export readers. The same list carries cookies_dropped (#3307): the Set-Cookie headers libcurl's cookie engine discarded across the run (count), titled "Some cookies the server set were dropped" in RunWarnings, the count again in the engine's message and no cookie name in it. Unlike httpVersionDowngraded, absent and 0 differ: 0 is a run that counted and saw none, absent a run stored before the count existed.

A constant-rate run with a timer.think carries think_timer_skipped_open_loop (#3541): the timer is skipped, not waited, because requests go out on a schedule. timers is the number of enabled timers skipped, RunWarnings titles it "Think timer skipped on a constant-rate run", and the Elements card tallies the element skipped.

authNotice is the engine's sentence for a request whose auth sent nothing: a mode it stores but does not execute (digest, ntlm, ..., issue #2474), or a bearer token or API key name that is empty (issue #3203). The request is still sent, without that credential. It is also the sentence for a request whose own Authorization header was sent in place of an OAuth 2.0 token it never fetched (issue #3202). The key is absent when there is nothing to say, on the live body and in the stored trace alike; the trace holds it on trace.request, so a failed exchange that received no header block, and so has no response node, still has it, and a streaming send carries it only there. responseFromExecuteResult and responseFromRunResult both set ResponseState.authNotice (an empty string reads as absent), held together by auth-notice-funnels.test.ts. ResponseViewer draws it as a warning Callout between the status band and the tabs, so it shows on every tab and on a 401 from the target, which is the response it explains.

warnings lists what the engine did to a design send that the response does not show (#3307), each as { code, message }: a jar cookie libcurl left off the Cookie line (cookie_not_sent, cookie_limit_reached) or a Set-Cookie it discarded unread (cookie_dropped_oversized, cookie_dropped_too_many). A warning never fails the send, and the message names a cookie by name, never by value. The live body always carries the array, [] when empty; the stored trace holds it at the top level of trace (beside clientCertificate, not under response) and only when non-empty, so a failed exchange that has no response node still has it. A streaming send's 202 carries none and no relay frame does either; its stored trace does, and the end-of-stream fetch of the run report (responseFromRunResult, the same swap that restores events) is what puts them on ResponseState, so the pane draws them when the stream ends and not before. Both funnels read it through receivedWarnings (lib/exchange-warnings.ts), which maps an empty list, an absent key and entries that are not a string code and message to undefined, so ResponseState.warnings is a non-empty list or absent and warnings-funnels.test.ts holds the two together. ResponseViewer draws one warning Callout per entry, from ExchangeWarnings, between the status band and the tabs, so it shows on every tab and on a status: 0 failure; a collection run's step card draws the same component above its response viewer. The title comes from the code and an unknown code gets a neutral one, since the engine adds codes without the app learning them first.

clientCertificate names the client-certificate registry entry the exchange presented, as host or host:port, and "" when none matched (issue #707) or the final hop was http://, where nothing is presented (#3260). It is the entry's own spelling, so a wildcard row reads as *.example.com rather than as the host that was dialled - which is the point: it says which row answered (issue #803). The renderer maps that empty string to undefined and ResponseStatusBar draws a chip only when there is one - the same show-it-only-when-it-happened rule the downgrade warning follows. Its tooltip says the certificate was offered, not accepted: the server decides, and the connection test's line says the same. Nothing on the request names a certificate (the engine matches one per transfer by host), which is exactly why the response has to say which was used: two calls to what looks like the same API can differ only in which registry entry matched. The stored trace carries the same value under the same key, so responseFromExecuteResult and responseFromRunResult agree - see client-certificate-funnels.test.ts.

timing.engineMs is Vayu's own cost for the exchange: the engine's elapsed time less the transfer, the user's scripts and an OAuth 2.0 token fetch (issue #2132,

2185; the engine's definition

is under One timing convention). It is optional - a stream, an auth-failure reply and rows stored before the key existed carry none - and the stored trace holds it flat as trace.engineMs where the live body nests it under timing, so timingFromTrace copies it across. ResponseStatusBar draws it as "in Vayu" beside the elapsed time and the Timing tab as its Vayu stat; neither shows a figure that is absent, and queueWaitMs (the sliver before libcurl) is never presented as it. engine-ms-funnels.test.ts holds the two funnels together.

bodyCapped says the engine stopped reading this response at maxDesignResponseBodyBytes (Settings → Limits, default 32MB), so body, bodyRaw and bodySize describe the prefix it read rather than what the server sent (issue #1157). The status and headers are the server's own, so this is a successful response carrying a flag. It is always present on the live body - absent means an engine too old to say, not "not capped" - and the stored trace carries the same key under trace.response.bodyCapped, written only when it happened, so responseFromExecuteResult normalises its false to undefined and the two funnels agree (body-capped-funnels.test.ts).

headerLines is the response's headers as received (issue #2460): one { name, value } per wire line, in order, the name in the server's case and the value trimmed by the engine, so a Set-Cookie sent twice is two entries and a comma inside one cookie's value is not mistaken for the boundary between two. headers beside it is the same headers folded (lowercased, repeats joined with ", ") and is unchanged. The live body always carries the key ([] when there were none); the stored trace writes trace.response.headerLines only when there were lines, and a load sample, a stream's open frame and any row stored before the key have none. Both funnels pass it through receivedHeaderLines (lib/header-lines.ts), which reads an empty list as an absent one, so the live and the restored ResponseState.headerLines agree (header-lines-funnels.test.ts). Absent is not filled in from headers: it is how the Cookies tab knows the set-cookie it holds is folded and must be split by the legacy parseSetCookie rather than read one cookie per line. The Headers and Raw tabs and the History step pane show the lines when there are some and headers when there are not (resolveHeaderLines); Save as example does the same, one row per received line, so a Set-Cookie pair stays two rows (issue #3422). It also saves a bodyCapped body as partial.

redirects is the redirect responses the send followed (issue #2461): one { status, statusText, headerLines, url?, schemeDowngrade? } per 3xx, in arrival order. url is the request that hop answered (the requested URL for the first hop, the previous hop's Location resolved against it after that), with the values of credential query parameters blanked engine-side; schemeDowngrade is true when that request went over https and the next over http (issue #2949). Both are absent on a hop from an engine or a stored trace from before the field, and a reader treats absent as unknown. headers and headerLines hold the final response only, so a Set-Cookie on the 302 that answers a login is readable nowhere else. The live body always carries the key ([] when nothing was followed, and always for followRedirects: false); the stored trace writes trace.response.redirects only when a hop was followed, and a load sample or a row stored before the key has none. Both funnels pass it through receivedRedirects (lib/header-lines.ts), the same empty-is-absent rule, so the live and restored ResponseState.redirects agree (redirects-funnels.test.ts). The Cookies tab reads it: with no cookie on any hop it is the one table it always was; once a hop set one it shows two groups, Set by this response (the final response's lines, as above) and Set during redirects, one sub-heading per hop that set a cookie ("302 Found, to /home": the hop's status, and its Location when it sent one) over that hop's table, each Set-Cookie line parsed on its own. The empty state ("No cookies in response") shows only when neither group has a cookie; the tab carries no count. A hop with schemeDowngrade: true is announced above both groups by a warning Callout ("Redirected from https to http") listing each such hop as "301 Moved Permanently from https://api.example.com/start, to /plain" - the resolved url when the engine sent one, then the Location - whether or not the hop set a cookie, because the common downgrade is a bare 301. The same "from " labels the hop's cookie sub-heading. the engine drops Authorization and Cookie across a scheme, host or port change; an API key sent as a header is not withheld, which is what the notice says. The rows say what the server sent and never that the jar stored it, because the engine withholds a hop's cookie when the redirect changes origin. GET /cookies and the Settings cookie card are what the jar holds.

The renderer keeps it strictly apart from bodyTruncated, which is maxTraceBodyBytes shortening a stored body after the whole of it was read: a re-send recovers from that one, while a capped read is reproduced by a re-send and only a bigger maxDesignResponseBodyBytes changes it. The response pane renders one Callout per fact and both can be on screen at once - "Body truncated for storage" tells the user to re-send, "Body capped while reading" tells them to raise the setting, and collapsing the two into one notice would give the wrong instruction to half the cases.

The pane reads the received text (bodyRaw), never the engine's parsed body, which is key-sorted, keeps only the last of a repeated key and has rounded any integer past 2^53 (issue #2459). The app does not even ask for it now: executeRequest sends includeParsedBody: false, so the answer's body is null (#2544; the engine leaves it null past 4 MiB whatever is asked). responseFromExecuteResult builds ResponseState.body - the string Pretty reads - by indenting bodyRaw with lib/json-format.ts, a single pass that copies every token through without parsing a value, so member order, duplicate keys and number spellings survive; text that is not well-formed JSON comes back as received. The stored trace takes the same path (paneBody, shared by responseFromRunResult), so a send reads the same live and from History (json-body-funnels.test.ts). Everything that takes the body out of the pane reads the text as received (receivedBody, request-builder/utils/response-bytes.ts) and not the indented copy: Copy, Download, Save as example and the Raw tab, which therefore print what the server sent.

A body's size is a UTF-8 byte count everywhere it is recorded. The live bodySize is one, and the stored trace carries the same number as trace.response.bodyBytes on every response (#3423; the original length when bodyTruncated, and a stream's wire count), so responseFromRunResult takes ResponseState.size from it and the two funnels agree. A row stored before that has bodyBytes only when the body was cut or streamed, and the restore then counts the held text's UTF-8 bytes (heldBodySize, never string.length, which counts UTF-16 code units and reads a multibyte body smaller than it was). json-body-funnels.test.ts drives a non-ASCII body through both.

A failure after the server answered restores with the server's headers. The engine stores trace.response beside error_type / error_message when the header block arrived before the transfer failed (an undecodable body, a timeout mid-body, a redirect limit), the way the live answer carries both. responseFromRunResult reads such a trace as the failed exchange - status 0, errorCode, errorMessage, so the pane is ClientErrorView as it was live - and keeps headers, headerLines, redirects, the protocol, the body and its size from the node (responseHeadFromTrace). A trace with an error and no response node keeps the shape it always had, headers: {}; a row with neither is null. Only the engine's own error_type / error_message mark the failure when a node is present: the result row's error column also holds a step's post-request script failure, for a response that did arrive. header-lines-funnels.test.ts holds the live and the restored failure together.

A third limit is the renderer's alone and reaches no wire field: LARGE_BODY_BYTES (2MB, shared/response-viewer/utils.ts). Above it paneBody stops indenting - it hands back bodyRaw, which is what would be displayed anyway - and ResponseBody stops formatting, hides the view toggle and shows the first 2MB of the raw body under its own notice. The request builder's Raw tab applies the same cap to the received text it prints (decided from that one string's length) and shows the same notice, since building the exchange and handing Monaco a multi-megabyte model is the same freeze (#3138). Copy and Download still take the whole received text. Both limits are about rendering cost, not about what arrived, and both count the decoded text below, never base64 characters.

bodyEncoding says how to read bodyRaw (issue #2458): "utf8" is the text itself, "base64" is a body that is not UTF-8 text (an image, a PDF, Latin-1, UTF-16) in standard padded base64, with body null and bodySize still the byte count. The stored trace writes trace.response.bodyEncoding: "base64" only when it applies and keeps the same base64 in trace.response.body; absent is text, as on every older row. Both funnels hand the body to one decoder, decodeResponseBody (request-builder/utils/response-bytes.ts), so the live and the restored pane hold the same state: the bytes go to ResponseState.rawBytes, and body / bodyRaw get their decoding - by the byte-order mark, else the declared charset, else UTF-8, through TextDecoder - for a text Content-Type, and nothing for any other. A BOM on a "utf8" body is part of the text, so it stays in bodyRaw (Raw, Copy and Download keep it); Pretty skips one leading BOM when it indents JSON, and a body that then fails to scan comes back whole, BOM included (#3140). A text type is text/*, a declared charset, or a subtype whose name (after any x-) or +suffix is one of the text syntaxes (json, xml, yaml, javascript, graphql and their kin), compared as whole tokens by mediaTypeOf: an Office document's vnd.openxmlformats-... subtype holds xml and is still a zip. The pane's detectBodyType reads the type through the same parts. A label the platform does not know, or bytes the charset cannot read, put a notice in rawBytes.notice that ResponseBody shows over the text. A non-text body has rawBytes.isText false and no text; the pane draws an image from its bytes through a Blob object URL, names a PDF or other bytes with their size, and Download writes the bytes as a Blob under the response's own Content-Type. Copy is off for such a body and the Raw tab prints one line in place of it; Save as example is off for any base64 body, since an example's body is UTF-8 text. Both disabled controls carry their reason. binary-body-funnels.test.ts holds the two funnels together.

report.sampling carries what each of the run's bounded stores thinned away - successTracesDropped / slowTracesDropped for the trace records behind report.results (slowTracesDropped thins the slow traces only: since issue

2399 report.slowRequests.count is the run's exact slow count and

slowRequests.tracesStored the sample of it that was kept), and responseSamplesDropped for the buffer post-run test scripts are graded on. That buffer is bounded twice, and one counter reports both: by count (max_response_samples), which displaces an incumbent and so keeps the graded set uniform over the run, and by bytes (max_response_sample_bytes), which stops admitting once the retained bodies fill it. The renderer now reads sampling.responseSampleBudgetSpent to tell which one applied (issue #1192): true means the byte budget ended at least one sample, so the graded set is drawn from the part of the run whose bodies fit rather than uniformly from the whole of it; false means only the count cap displaced anything, so the graded set stays uniform. The key is absent on a summary written before the marker existed, and absent keeps today's uniformity sentence rather than weakening it - only a target whose retained bodies average more than ~256 KiB reaches the budget at the defaults, so absent-as-uniform is the accurate message for nearly every older run. The renderer treats a non-zero count as "this list is a sample of a larger set": SampleRetentionNote (shared) renders under the dashboard's Sampled Requests, the history Samples tab and the Test validation card, and the sample-count badges say shown rather than captured, since results is capped at 100 for a single-request run by the report route irrespective of retention. That cap is a failures-first selection listed by time, not a uniform sample (#2210): the top-level resultsStored and resultsCap say how many rows the run stored and the cap applied, resultsStored > resultsCap is the only sign the array was cut, and the history Samples tab reads the pair as "N of M stored". Both are absent from an older engine, which is read as "say nothing", not "nothing was cut". The traces note therefore never calls results uniform; only the tested-response buffer's sentence does. sampling.errorsDropped has a reader of its own: the shared ErrorSummary card (history Overview) says under By error type that "N errors beyond the first M are not broken down by type" (issue #2400). It reads errorsDropped only when errors.types sums to less than the no-response count, which is a run stored before the engine kept exact per-type counts or a design-mode run; on any other run the types are exact past the error store's cap and the note stays silent. The Test validation card (titled Sampled replay when a scenario load report also carries scenario.assertions, which gets its own Assertions card counted on every response, #2820) also states its denominator: for a single-request run summary.totalRequests ("Tested N of M requests"), worded so it holds for requests that never got a response as well as for displaced ones, and for a scenario load run the responses that carried a deferred test script, the sum of deferred over its script.* elements ("Replayed N of the M responses that carried a test script (1 step)", #2824), because most requests of a sequence have no script to replay; samplesTested counts responses and testsPassed / testsFailed count assertions, and the card's labels say so (issue #2144). A report's elements[] row may carry deferred (absent from older reports): a post-request script left to the post-run replay, rendered as "N requests deferred to a post-run replay over M sampled responses" rather than "0 passed", where M is testValidation.samplesTested (a scenario step's tests.sampled; a row whose report does not carry one reads "replay of sampled responses"). An inline script.* row may also carry messages (the error it threw and each failing pm.test, {kind: "error" | "test", text}), console ({level, text}), each entry with count when it was seen more than once, and the messagesDropped / consoleDropped counts of the occurrences a full list turned away (#3127); each key is absent when empty (count when the entry was seen once), and the Elements card and the Steps tab list them under the row. The deferred replay's failures arrive on the synthetic results[] row as failures (each distinct message once), failureCounts (how often each failed), failuresDistinct and the occurrence totals totalFailed / totalPassed; the Test validation card shows each message once with x3 beside a repeat and says "Showing N of M distinct" when the engine kept fewer than it saw. A row from before #3127 has no failureCounts or failuresDistinct, and each of its entries counts as one. The replay's console lines ride on the aggregate instead: testValidation.console and consoleDropped on a single-request run, scenario.steps[].tests.console and consoleDropped per step on a scenario run (same {level, text, count?} lines and occurrence count as an inline row, each key absent when nothing was logged and on a report from before the field), drawn under "Console from the post-run replay over N sampled responses" by ReplayConsole.

An absent sampling is a run whose stored summary predates the counts, not a run that dropped nothing, so the note stays out rather than asserting a completeness it cannot verify - the same absent-vs-zero rule httpVersionDowngraded follows above.

report.auth follows that rule too. The engine refreshes a header-placed OAuth 2.0 token while a load run is going, and this section is what it did: refreshes[].atSeconds per renewal, plus refreshFailures and a lastError when one was refused. LoadTestDetail renders it as a one-line note in the header (authRefreshNote), a warning when a refresh failed - that failure is what explains 401s appearing partway through an otherwise healthy run. Absent means the run could never refresh (no OAuth 2.0 auth, a non-expiring or query-placed token, autoRefreshToken: false, or an older sidecar); present with an empty refreshes means it was watched and never needed to. A collection load run fills it too (#3199): the engine keeps one token current per distinct cache key its steps send and folds them into this one shape, so refreshes holds every renewal in order and refreshFailures is the sum. The same eligibility rule decides whether OAuth2LoadTestGuard still blocks a run longer than its token, in the request's load dialog and, once per distinct token, in RunCollectionDialog - isMidRunRefreshable mirrors the config-and-token cases of the engine's plan_oauth2_refresh, not what the engine decides from the composed request: a user-supplied Authorization header that beats the token, and for a collection step an auth that waited on its scripts or a different headerPrefix than the first step sharing its cache key. The guard is never handed the headers to see the first. The two must change together.

Load Test Execution

  1. User Action: Configures and starts load test
  2. Composition: the request half goes raw through apiService.composeRequest() → POST /compose, built by the same buildComposeBody Send uses (plus dataColumns and deferDynamicVariables) - so a load test measures the same composed request Send sends
  3. Request Transformation: composed request half + frontend LoadTestConfig → backend format
  4. API Call: apiService.startLoadTest() → POST /runs
  5. Response: { runId: "run_123", status: "running" }
  6. Dashboard Initialization: useDashboardStore().startRun(runId)
  7. SSE Connection: loadTestService.startMonitoring(runId) connects to /runs/:runId/live (a module singleton, so the stream outlives the view)
  8. Metrics Streaming: Real-time metrics update dashboard
  9. Completion: When test completes, fetch final report via GET /runs/:id/report

Example Load Test Request:

await apiService.startLoadTest({
  request: {
    method: "POST",
    url: "https://api.example.com/data",
    headers: [{ name: "Content-Type", value: "application/json" }],
    body: { mode: "json", content: '{"key": "value"}' }
  },
  followRedirects: true,
  maxRedirects: 10,
  // timeout: 1500,  // only when the request states one; never sent as a copy of the setting
  httpVersion: "auto",
  verifySSL: true,
  mode: "constant_rps",
  duration: "30s",
  targetRps: 100,
  concurrency: 50,
  requestId: "req_123",
  environmentId: "env_456",
  comment: "Stress test",
  // Optional pass/fail budgets. Omitted entirely when none were declared - the
  // engine rejects an empty object rather than starting an unjudged run.
  thresholds: { latencyP99Ms: 50, maxErrorRatePct: 0.1 },
  // Optional data rows, bound one per request sent. Omitted when the dialog's
  // picker holds no file.
  data: [{ id: "1" }, { id: "2" }],
  // The file those rows came from: its name and the SHA-256 of its bytes,
  // never its path (issue #2051), and whether its numbers were read as
  // numbers (issue #2540). Undefined exactly when `data` is.
  dataFileName: "users.csv",
  dataFileHash: "<64 lowercase hex>",
  dataFileCastNumbers: false
});

Streaming load runs. A load run of a request whose stream setting is on sends stream: true plus maxStreamDurationMs / maxStreamEvents (issue #576). The split is deliberate: whether a request streams is read off the request, because that is a property of the request and lives on its Settings tab, while how much of each stream this run measures comes from the load dialog's two cap fields, which appear only for a streaming request. The caps are always sent for such a run rather than elided as "the engine has defaults" - the engine's default is the user's sseMaxStreamDurationMs setting, which the dialog does not show, so eliding would leave the run bounded by a number the user was never told about while two others were on screen.

A collection run takes the caps without stream (issue #3235): the engine reads the flag off each stored request, so RunCollectionDialog sends top-level maxStreamDurationMs / maxStreamEvents (seconds converted to ms) only when a request it runs streams, for a design run and a load run alike, and never stream, which is a 400 there.

Under load a stream is bounded by construction, and reaching a cap is a successful completion, not a timeout - so a streaming run's clean error rate is not evidence the caps went unused. The report answers that with a stream section (RunReport.stream): the per-completion event distribution, the totals, a derived eventsPerSecond, capped - how many streams a cap ended rather than the server - and timeToFirstEvent (issue #3234), the wait from submitting the request to each stream's first event. That is not phases.firstByte, which ends at the response headers: a gateway that answers 200 at once and then thinks reads fast there and slow here. It is absent when no stream delivered a timed event. StreamMetrics (modules/dashboard/components/charts) renders it, as its own first-event row, and says plainly when every stream was capped, because those counts then measure the caps rather than the target. The section is undefined for a run that did not stream, which is not the same claim as a stream that delivered nothing, so a report without it renders exactly as it did before.

Budgets and the verdict. LoadTestConfig.thresholds (RunThresholds) rides through to POST /runs under the engine's own camelCase metric names, and the report comes back with thresholdValidation - one check per budget plus a verdict of "passed" / "failed" - which ThresholdVerdict (components/shared) renders on the dashboard report and the history Overview. It is the aggregate counterpart to testValidation: a pm.test script sees one response at a time and cannot assert a p99 or an error rate, so a run whose every assertion passed can still have missed its budget. undefined is a run that declared none - not a run that passed nothing - so a report without the section renders exactly as it did before budgets existed. The dialog seeds its p99 field from the client sloThresholdMs setting. The live dashboard draws a run's thresholds.latencyP99Ms as its SLO line (LoadTestRunConfig.latencyP99Ms, set by the request builder, the collection runner and loadConfigFromSnapshot), and a run with no p99 budget draws none: the setting is never the line. A Capacity discovery run does not send that seed (issue

2816): the engine judges latencyP99Ms on the run's pooled histogram, which

holds every over-budget level the search climbed through on purpose, so thresholds omits it and a run with no other budget reads "No budgets set". A p99 typed in the dialog, or carried from the last Start, is sent in every mode.

LoadTestConfigDialog also tells the engine which of those budgets the user did not set for this run (issue #2195): top-level carriedBudgets: string[] on POST /runs (StartLoadTestRequest), the thresholds keys still holding a value the memo or the Settings p99 threshold seed filled in and the user left alone, spelled as they are in thresholds (latencyP99Ms, custom.<name>.<stat>; the threshold seed only outside Capacity discovery, which does not send it). The engine only stores it and echoes it as metadata.configuration.carriedBudgets, which ThresholdVerdict reads to tag those rows "carried over"; the verdict itself is computed the same either way. The list is cut at the engine's 64-entry cap (each key may be up to 512 bytes of UTF-8). It is omitted when nothing was carried, and RunCollectionDialog and MCP never send it.

maxAssertionFailureRatePct (issue #1497) is the assertion budget. It is judged against two populations kept apart (issue #2892), not testValidation's per-response view: the exact tally of every assert.* element outcome, unmatched required extract.* and inline pm.test call, and the sampled pm.test replay over responses sampled at 1 in response_sample_rate. actual is the worse of the two failure rates, so a sampled test failing half the time is not diluted by thousands of passing inline assertions. An evaluated check carries both as assertionsExact / assertionsSampled ({passed, failed}) and, when the sampled one is non-empty, sampleRate; a report stored earlier has none of them. ThresholdVerdict reads them to add one muted line under the row, "Judged on the worse of N assertions on every response (X failed) and M assertions on responses sampled at 1 in R (Y failed).", and shows nothing extra when the sampled population is empty (a collection run, a load run with no test script), when the check is unmeasurable, or on an older report. thresholds.failRun: true (LoadTestConfigDialog's own Switch, beside the budget fields rather than in BUDGET_FIELDS - it is a flag over the budgets, not one itself) changes what a missed budget does: the run's terminal status becomes "failed" instead of "completed", so the history list and the taskbar failure cue pick it up, not only the verdict section. A collection run's list row is marked failed by a missed budget with or without that flag (#3539): its resultSummary.verdict is what the row reads, and ScenarioRunView draws the ThresholdVerdict card that names the budget.

A collection (design-mode) run is judged too (issue #1564): RunCollectionDialog's own Pass/fail budgets disclosure sends the identical thresholds block, top-level on the payload beside failOnSchemaError and elements, reusing budgets.ts's field table and payload builder rather than a second copy. It is not gated by the dialog's Load test switch - the engine evaluates thresholds for a design-mode run and a load run of the same folder alike - so the same thresholdValidation section and ThresholdVerdict rendering apply whichever executor ran the sequence: the history Overview for a load run, ScenarioRunView above its step list for a collection run. See POST /runs's thresholds section for how a collection run's error rate, latency percentiles and throughput are derived from the steps it actually sent.

Stream budgets (issue #3234): streamTimeToFirstEventP95Ms (a ceiling on stream.timeToFirstEvent.p95, ms) and streamEventsPerSecondMin (a floor on stream.eventsPerSecond) judge the report's stream section, which only a streaming request's load run and a collection run with a streaming step (#3235, design or load) have. On any other run the engine reports them not evaluated, and that counts as failed, so the dialog treats them as a property of the request: BUDGET_FIELDS marks them streamOnly, and budgetFieldsFor(streaming) is the one list the load dialog's fields, validation, closed-card summary and payload read. A request that does not stream is offered neither, validates and sends neither (a value the global memo holds for them stays in the memo for the next streaming request, and is not named as carried over). RunCollectionDialog reads the same list with anyStreams, whether a request the run sends streams, so it offers, checks and sends them only then. A streaming request's latency budgets read on each stream's full duration, from sending the request to the stream closing, and the section says so under the p99 field.

custom.<name>.<stat> budgets (issue #1579) are the only dynamic thing the block can carry: a ceiling on a value the run records itself through a metric.record element or a pm.metrics call, keyed by the name it was recorded under and one of p50, p95, p99, max, value, rate. RunThresholds holds them as a pattern index signature ([key: `custom.${string}`]: number | undefined), so the fixed fields keep their own types and failRun keeps its boolean. Both dialogs declare them as free-text rows (CustomBudgetRows.tsx) rather than as a picker of recorded names: the engine checks the key's shape and the value's sign and does not cross-check the name against the run's own metric.record elements - an unmatched name is reported evaluated: false rather than refused - which is the call MCP's thresholdsInput already made for this family (catchall). Like the fixed keys, these are not gated by RunCollectionDialog's Load test switch either - execute_scenario_run evaluates a design-mode run's custom metrics against the same declared budgets a load run's are judged against.

The engine range-checks this payload before it creates the run row and answers a violation with 400 invalid_run_config (accepted ranges are tabulated under POST /runs). The renderer's own limits live in LOAD_TEST_LIMITS (src/constants/load-test.ts) and must stay at or inside the engine's.

success_sample_rate is a period, not a percentage

The engine keeps a success trace when counter % success_sample_rate == 0 - one in every N. The dialog's control is a percentage, and the renderer converts between them with successSamplePeriod (constants/load-test.ts): 100% becomes a period of 1, 1% becomes 100, and the default 10% is the fixed point where the two units coincide. Sending the percentage straight through, as the renderer did before, inverts the slider - "100% - everything" kept 1%.

A 0 is a division by zero engine-side, so the control's floor is 1%. "Keep no success traces" is the Save timing breakdown toggle, which gates storage outright.

Dialog ceilings are a user setting

LOAD_TEST_LIMITS (constants/load-test.ts) holds the ranges the load dialog offers, and four of its ceilings are user-adjustable in Settings → Load testing (loadTestCeilings on client-settings-store). The dialog reads them through resolveLoadTestLimits, never off the constant.

These are the app's policy and sit inside the engine's own bounds, which are crash guards rather than throttles: a run's concurrency becomes an eager per-worker curl-handle pre-allocation, so the engine caps it at 10x event_loop::MAX_CONCURRENT. LOAD_TEST_CEILING_BOUNDS pins each settable ceiling at that guard, so no value on the settings screen can compose a run the engine rejects. The floors are not settable at all - below them the values are not "small", they are unusable (a concurrency of 0, a sample period of 0).

Error Handling

HTTP Errors

All HTTP errors are transformed to ApiError:

try {
  await apiService.executeRequest(...);
} catch (error) {
  if (error instanceof ApiError) {
    console.error(error.userFriendlyMessage);
    console.error(error.statusCode);
    console.error(error.errorCode);
  }
}

Network Errors

Network errors (timeout, connection failed) are caught and displayed:

if (error.isTimeout) {
  // Show timeout message
} else if (error.isNetworkError) {
  // Show network error message
}

SSE Errors

The SSE client does not reconnect by itself. EventSource cannot set Last-Event-ID on a fresh connection, so the user's Reconnect passes the last frame it held as ?lastEventId= instead; without it the engine would replay the topic from offset 0 and duplicate every tick already plotted (#3571).

  • Transient errors (CONNECTING): left to the browser's own retry, which does carry Last-Event-ID
  • Terminal errors (CLOSED): connection disposed and the close handler runs, which converges on GET /runs/:id/report

Connection Management

Health Checking

The app polls /health endpoint to verify engine connectivity, at one of two speeds depending on whether the last poll succeeded:

useHealthQuery() // TIMING.HEALTH_RECONNECT_POLL_INTERVAL_MS (1s) while erroring,
                 // TIMING.HEALTH_CHECK_INTERVAL_MS (30s) once connected

The window loads alongside the engine rather than after it, so an ordinary launch spends its first seconds starting rather than connected; polling that state at the 30s cadence could leave a launch showing it for half a minute after the engine was already serving. A poll that succeeds right after one that failed also triggers queryClient.invalidateQueries() once - an engine that stopped with nothing starting costs collections, runs and config their two retries, a connection refused by a closed port is an EngineUnreachableError rather than an ApiError, and refetchOnReconnect only fires on the browser's online/offline event, which localhost never changes - so nothing else would ever revisit their error state once the engine came back.

A launch does not spend those retries. While the start window below is open, the shared retry policy (shouldRetryQuery and queryRetryDelay in lib/query-client.ts, via isEngineStartFailure) keeps retrying a refused connection every QUERY_CACHE.ENGINE_START_RETRY_DELAY_MS (250ms) without counting it, so every query mounted at first paint - the collection tree, the Launcher, a restored tab's request or run - stays loading beside the Dock's "Starting…" and loads within that delay of the engine listening. It used to settle into "Couldn't reach Vayu's engine" panes a few hundred milliseconds to three seconds into an ordinary launch, and flash them until the reconnect refetch above replaced them. The failure still surfaces, on the same clock as the Dock: the first refused attempt after the window expires is not retried. requestDetailOptions and runDetailOptions bring their own retry, so they compose isEngineStartFailure in themselves.

A failed poll does not mean engineStatus becomes unreachable outright: engineStatusAfterFailedPoll (lib/engine-start-window.ts) reads starting while an engine is known to be coming up and is still inside TIMING.ENGINE_STARTUP_GRACE_MS (45s) of the moment it began, and unreachable otherwise - past that window, or after an engine that had answered stops answering with nothing starting. The moment it began is engineStartWindow on engine-store, opened by this hook on mount - which is when the main process spawns the engine and starts spending its own budget on the same wait - and again by useEngineRestart before it invokes the restart IPC, because a restart kills the daemon and spawns a fresh one that repeats the whole cold start with the port down for all of it (#1227). Measuring from the hook's mount alone called every such restart a failure, since an engine had answered: the one this one replaced. The restart opens the window and never writes engineStatus, so this hook remains the only thing that classifies; a restart the main process reports as failed closes the window again, and the next failed poll goes back to owing the user its reason.

A start failure the main process reports overrules that grace. When every engine port is held, useHealthQuery reads getEngineStartFailure() on a failed poll, and a sentence there makes the status unreachable at once and keeps it there between polls, instead of "Starting…" for 45s over an engine nobody is starting (issue #2118). The poll an engine answers clears it.

That 45s is the same budget the main process spends on a cold engine before it gives up and logs EngineNotReadyError (ENGINE_HEALTH_POLL_BUDGET_MS in electron/constants.ts) - it is the same question asked from the other side of the process boundary - and since the two files' tsconfigs share no module graph, health.test.ts reads the constant out of electron/constants.ts's source text and asserts it equals TIMING.ENGINE_STARTUP_GRACE_MS, so the two cannot drift apart unnoticed.

Health Response:

{
  status: "ok",
  version: "0.3.0",
  workers: 8,
  // Optional (issue #922): present only when this engine startup restored the
  // database from its backup or started fresh because it could not. Absent on a
  // clean start, which is also what a genuine first run gives.
  recovery?: {
    outcome: "restored_from_backup" | "started_fresh_quarantined"
           | "backup_also_corrupt" | "deleted_corrupt",
    at: 1755870000000,   // epoch ms
    databasePath: "/home/someone/.local/share/vayu/vayu.db",
    // Optional (issue #984): where the unopenable database was moved to, when
    // it was moved rather than deleted. Absent for `deleted_corrupt`.
    quarantinedPath?: "/home/someone/.local/share/vayu/vayu.db.corrupt-1755870000000"
  }
}

useHealthQuery mirrors recovery onto engine-store, and RecoveryBanner is its only reader - it is the one thing that tells the user their data was restored or wiped, and the only place the quarantined file and its sqlite3 ... .recover command are named. Its copy is a Record over the outcome union, so an outcome the engine adds without copy for it fails pnpm type-check rather than being announced as whichever branch came last.

Engine Startup

The Electron main process (electron/sidecar.ts) manages engine lifecycle: - Spawns engine process on app start, alongside creating the window rather than before it - first paint does not wait on the engine - Monitors health via /health endpoint, on a ramped poll that leaves a live-but-slow engine to the renderer's own health poll instead of quitting the app - Handles graceful shutdown on app quit

Best Practices

  1. Always use apiService: Don't call httpClient directly
  2. Handle errors: Always wrap API calls in try/catch
  3. Use user-friendly messages: Display error.userFriendlyMessage to users
  4. Transform data: Use service layer for format transformation
  5. Cache queries: Use TanStack Query for automatic caching
  6. Disconnect SSE: Always disconnect SSE when component unmounts

Testing

Mocking API Calls

Use TanStack Query's query client for testing:

import { QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient({
  defaultOptions: { queries: { retry: false } }
});

Mocking Services

Mock apiService methods:

jest.spyOn(apiService, 'executeRequest').mockResolvedValue(mockResponse);

Troubleshooting

Engine Not Responding

  1. Check the Dock: hovering "Engine connected" shows the address the app is using, and the disconnected state says why. "Another program is using port 9876, and the fallback ports are held too" means every candidate is held; free 9876 (Retry looks there alone) and press Retry. "Another Vayu engine" in its place means a Vayu engine serving another data directory holds 9876; the app never stops it, so stop it yourself and press Retry.
  2. Check if engine is running: curl <address from the Dock>/health (9876 unless the app fell back)
  3. Check engine logs in Electron console

SSE Not Connecting

  1. Verify load test is running (status: "running")
  2. Check browser console for SSE errors
  3. Verify endpoint: /runs/:runId/live or /runs/:runId/metrics

CORS Errors

The engine sends no CORS header and refuses any request carrying Origin; the renderer gets through only because the Electron shell's bridge (app/electron/engine-origin.ts) strips Origin and Referer from requests to exactly ENGINE_BASE_URL and adds the CORS response headers. A CORS error or a 403 naming browser origins therefore means: - The request did not go through ENGINE_BASE_URL (src/config/network.ts) - the same engine spelled localhost:<port> is outside the bridge's filter - The page is not running in the app's own window session (plain Chromium, or a window the bridge was never installed on); see "Driving the renderer without Electron" in app/CLAUDE.md for the bridge a test browser needs