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 asAPI_ENDPOINTS.BASE_URLbyconfig/api-endpoints.ts.http://127.0.0.1:9876unless the app fell back to another port - Request Timeout: 30 seconds default
- Error Transformation: Converts HTTP errors to
ApiErrorwith 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 ownCache-Control: no-storeon 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):
Backend Format (camelCase):
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.
Cookie jar¶
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 withidstripped (withoutIdinapi.ts). The engine assigns every id and answers a create carrying one with a400, and theCreate*Requesttypes declareid?: 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 wireparentId/collectionIdacross a tree before anything was persisted; it sends oneapplyImportcall now, see below.)updateX(data)takesdata.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 explicitnullresets it to the default. Theidis not repeated in the body; a bodyiddisagreeing with the path is a400.
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 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¶
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¶
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.deletetakes an optionalparamsargument 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 afterPOST /runswith no attach race - it replays from offset 0 and tails to thecompleteevent (even for sub-second runs). The client records thelastEventIdof everymetrics,step,planandmonitorframe (one id sequence; thecompleteframe carries none), and aconnectto 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
completeevent at normal run end, carrying the run's terminalstatus(issue #2140). TransientCONNECTINGerrors are left to the browser's built-inEventSourceretry.onCloseis called asonClose(status, { frame })and the second argument is what tells the twonullstatuses apart: acompleteframe with no status (the engine's 60 s settle timeout, the rare case) is{ frame: true }, and aCLOSEDreadyState 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 terminalmetadata.statusfinishes the run. Onrunningorpending, 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.ScenarioRunServiceignores the second argument. - Event Handling:
metricsevents,stepevents,monitorevents,planevents,completeevent,errorhandling - One client, and a hand-off when it changes hands: the client is a singleton, so a second
connecttakes the socket from whoever held it. That subscriber'sonSupersededruns first, before the new stream opens, so it can give up its wake lock and its OS progress claim (issue #1417).onCloseis 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'scompleteframe, are not superseded by the next run to start - Metrics Parsing:
mapSseMetrics()transforms the engine's camelCase blob to the frontendLoadTestMetricsshape (includes drops, queue-wait, percentiles, bytes, status-code map). It marks the ticklive, maps a gate frame'ssecondSamples/secondP50Ms/secondP95Ms/secondP99Msand every frame'scumulativeP50Ms/cumulativeP95Ms/cumulativeP99Ms, and leaves an absent keyundefinedand anullasnull, never a0(issue #2385). The window's ownlatencyP50Ms/latencyP95Ms/latencyP99Msfollow the same rule: the engine sends themnullfor a window with no completion, and they staynull(issue #2386).latencySamplesis not mapped; nothing in the app reads it. A gate frame'scumulativeLatencyandcumulativePhases(the run-so-far latency distribution and the per-phase means and percentiles, issue #2782) map tocumulative_latency/cumulative_phasesas sent:nullis "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'stimingBreakdownshape for the waterfall and the percentile table, and shows the latency distribution'scountas "N completions so far". A scenario load run's gate frame also carriesscenario({iterations, iterationsCompleted, iterationsAbandoned, stepsExecuted, steps: [{index, name, executed, errors}]}, issue #2823), mapped as sent ontoLoadTestMetrics.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), andmapSseMetrics()passes it through asLoadTestMetrics.capacityunchanged. Absent is "not a capacity run" (or an engine from before #2928), never a zeroed level;level0is a search that has not opened its first level, andstopReasonappears 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 MCPget_live_metrics - Step Parsing:
parseStepEvent()narrows a scenario run'ssteppayload and returnsnullfor one it cannot read. A malformed event is dropped, never defaulted - the step list keys on(iteration, stepIndex), so a defaulted0:0would collide with the real first step's row rather than merely say nothing. - Monitor Parsing:
parseMonitorEvent()narrows amonitorframe the same way and returnsnullfor one it cannot read. A sample defaulted totimestamp: 0would 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 whenonStepis passed, since a load run never emits one.monitor: One scrape of the run's monitored endpoint -{timestamp, series}. Listened for only whenonMonitoris passed. Interleaved withmetricsticks on one id space, soLast-Event-IDresume replays both in the order they happened.complete: The run reached a terminal statuserror: 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_STREAMSSE constant was removed - live metrics go throughMETRICS_LIVEonly;/statsis now used solely for paginated historical reads.
Request Execution Flow¶
Single Request Execution¶
- User Action: Clicks "Send" in RequestBuilder
- Request Transformation: Frontend format → backend format (raw - no
client-side
{{variable}}resolution), built bybuildComposeBody(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 - Composition:
apiService.composeRequest()→POST /compose- the engine resolves{{variables}}andinheritauth against the request'scollectionIdchain and the activeenvironmentId, and returns the execute-ready payload (issue #226), naming thecollectionIdwhose chain it read (issue #3461) - API Call:
apiService.executeRequest()with the composed payload, unchanged →POST /execute, carryingstream: falseexplicitly; the composedcollectionIdis how the engine's scripts read the same chain when no saved row is linked - Response Transformation: Backend format → frontend format
- 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:
- API Call:
apiService.executeStreamRequest()→POST /executewithstream: true, answered202 {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. - Tail:
useExecutionEventsopens anEventSourceon the answer'seventsUrlas given - the engine names where its own events are, and a second spelling of that path inapi-endpoints.tswould be a copy that can disagree with the answer. Frames land inexecution-events-store; the Events tab renders them live. - Swap to stored truth: on the relay's
completeframe the provider fetchesGET /runs/:id/reportandrestore-response.tsmaps the trace'seventsnode onto the response, which is the record from then on. One fetch is enough: the engine sendscompleteonly 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 <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 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¶
- User Action: Configures and starts load test
- Composition: the request half goes raw through
apiService.composeRequest()→POST /compose, built by the samebuildComposeBodySend uses (plusdataColumnsanddeferDynamicVariables) - so a load test measures the same composed request Send sends - Request Transformation: composed request half + frontend
LoadTestConfig→ backend format - API Call:
apiService.startLoadTest()→POST /runs - Response:
{ runId: "run_123", status: "running" } - Dashboard Initialization:
useDashboardStore().startRun(runId) - SSE Connection:
loadTestService.startMonitoring(runId)connects to/runs/:runId/live(a module singleton, so the stream outlives the view) - Metrics Streaming: Real-time metrics update dashboard
- 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 carryLast-Event-ID - Terminal errors (
CLOSED): connection disposed and the close handler runs, which converges onGET /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¶
- Always use
apiService: Don't callhttpClientdirectly - Handle errors: Always wrap API calls in try/catch
- Use user-friendly messages: Display
error.userFriendlyMessageto users - Transform data: Use service layer for format transformation
- Cache queries: Use TanStack Query for automatic caching
- 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:
Troubleshooting¶
Engine Not Responding¶
- 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.
- Check if engine is running:
curl <address from the Dock>/health(9876 unless the app fell back) - Check engine logs in Electron console
SSE Not Connecting¶
- Verify load test is running (
status: "running") - Check browser console for SSE errors
- Verify endpoint:
/runs/:runId/liveor/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