Vayu Engine Architecture¶
Overview¶
The Vayu Engine is a high-performance C++ daemon that executes HTTP requests and load tests. It uses a sidecar architecture pattern, running as a separate process from the Electron UI and communicating via HTTP on localhost:9876 (configurable).
System Architecture¶
┌─────────────────────────────────────────────────────────────┐
│ Vayu Engine (C++) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌─────────────────────────────┐ │
│ │ HTTP Server │ │ Event Loop │ │
│ │ (cpp-httplib) │ │ (curl_multi) │ │
│ │ Port: 9876 │ │ • Multi-worker │ │
│ │ │ │ • Lock-free SPSC queues │ │
│ └────────┬─────────┘ │ • Connection pooling │ │
│ │ └──────────┬──────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────┐ ┌─────────────────────────────┐ │
│ │ Route Handlers │ │ Metrics Collector │ │
│ │ • Collections │ │ • In-memory aggregation │ │
│ │ • Requests │ │ • Batch DB writes │ │
│ │ • Environments │ │ • Real-time stats │ │
│ │ • Execution │ └──────────┬──────────────────┘ │
│ │ • Metrics │ │ │
│ └────────┬─────────┘ ▼ │
│ │ ┌─────────────────────────────┐ │
│ ▼ │ Script Engine (QuickJS) │ │
│ ┌──────────────────┐ │ • Pre-request scripts │ │
│ │ Run Manager │ │ • Test scripts │ │
│ │ • Active runs │ │ • Postman-compatible API │ │
│ │ • Lifecycle │ └─────────────────────────────┘ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SQLite Database (sqlite_orm) │ │
│ │ • Collections • Requests • Environments │ │
│ │ • Runs • Metrics • Results │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Core Components¶
HTTP Server (cpp-httplib)¶
The HTTP server handles all API requests from the Electron UI. It runs on 127.0.0.1:9876 by default (configurable via --port).
Key Features: - RESTful API endpoints for collections, requests, environments, and runs - Server-Sent Events (SSE) for real-time metrics streaming - Requests served on cpp-httplib's default thread pool, so two clients - the app and an MCP agent - are genuinely concurrent inside the daemon
How a route says no¶
Three shapes, and the difference between them is the point:
- A testable core -
create_collection_response,import_apply_response- returnsstd::pair<int, nlohmann::json>. Success and failure are both something to send, so the pair is the response, and the handler around it only writes it to the wire.error_response (status, message)builds the failing one. - A field applier or guard -
apply_json_field,reject_client_supplied_id,apply_request_fields- returnsRouteResult, which isstd::expected<void, RouteError>: nothing on success, and on failure the{status, body}the caller should answer with.route_error (status, message)builds the refusal;as_responseturns one into the pair a core returns. - A payload parser -
parse_mock_start,parse_inbox_start,parse_inbox_response_update,parse_live_resume_point- returnsstd::expected<Parsed, ParseError>, whereParsedis the validated request itself. The value is the return, never an out-parameter: a half-filled request a caller forgot to check for is then unreachable rather than merely unlikely (issues #926, #954).
These used to be std::optional<std::pair<int, nlohmann::json>>, where an
empty optional meant success (issue #901). That reads backwards at every call
site - if (err) is the failure path, return std::nullopt means "fine" - and
a dropped return value silently means "no error", which is why the two most
dangerous of them carried [[nodiscard]] by hand. std::expected puts the
direction in the type: if (auto outcome = f (...); !outcome) return outcome;
propagates, and the response is reachable only through .error ().
All error bodies, either way, come from error_body - one shape,
{"error": {"code", "message"}}, which the app's http-client reads.
A core that reads, decides and writes holds one lock¶
Database takes its mutex per call, which is enough while a write depends only
on its own arguments. It is not enough for a core that reads a row, decides
something from it and then writes: between the read and the write another
client's write can move the ground. Database::with_lock (issue #386) scopes
the mutex around the whole composite, and because the mutex is recursive the
lambda calls the same public get_* / save_* methods everything else does.
These shapes need it, and all of them are in the code today:
- The validate-then-commit batch -
POST /reorder,POST /import/apply,POST /specs/sync,POST /specs/bind,POST /config(issue #1453). The validation the write is based on has to still be true when the write lands.POST /config's batch also needs its own transaction (Database::save_config_entries) rather than onesave_config_entrycall per row: the mutex stops a reader from landing mid-batch, but only a transaction stops a mid-batch failure from leaving the rows before it written. - The merge-patch update - every
PUT /<resource>/:id(issue #1440). The write carries each field the body did not name, read a moment earlier, so a read not held to its write loses whichever of two concurrent updates read first - whole fields, with neither request failing. Each of those cores is a thin wrapper over anupdate_*_lockedfunction holding the read, the merge and the write, in the shapereorder_responseestablished. - The uniqueness-checked create -
POST /client-certificates(issue #1455), the one create with a cross-row invariant to protect. Proving no other row already claims a candidate's host and port is only as good as the window between that proof and the write, so the create holds the lock across both, in acreate_*_lockedcore of the same shape as the merge-patch update's. A certificate's restore from the trash (#2973) asks the same question (client_certificate_for_target) under the lockrestore_deletedholds for its write. - The script-variable write-back -
persist_script_variables(issue #1878), which a design send, a stream and a sequential collection run call once when they end. The scopes were loaded when the run started, possibly minutes earlier, so what it writes is the run's delta against that load applied onto a fresh read of each row, and the fresh read, the merge and the write are one lock scope; a snapshot written back would revert every edit another client made while the run was in flight. It takes the samebefore_writetest seam. - The import's globals merge -
POST /import(issue #1906), the one caller that has to merge globals, becausePOST /globalsreplaces the whole set.merge_globals_lockedreads the stored set, lays the imported variables over it and writes the result inside onewith_lock, after the tree has committed; aPOST /globalslanding between a separate read and write would be overwritten. It takes the samebefore_writetest seam.
The same shape holds where the state being merged is not a Database row at
all: PUT /inbox/:id (issue #1454) merge-patches an inbox's canned
response, which lives in InboxManager's own map, guarded by its own mutex.
InboxManager::update_response takes a merge function and runs the read, the
merge and the write under one acquisition of that lock - Database::with_lock
has nothing to scope here, since no database call is involved - mirroring
MockIssuerManager::update, which already held its equivalent composite this
way.
Both wrappers take an optional before_write seam, invoked inside the scope
immediately before the commit. It is what lets a test drive a genuinely
concurrent writer into the window rather than asserting the absence of a race by
timing (tests/competing_writer.hpp).
Hold the lock only for a bounded composite: /health, the runs poll and SSE
serialize on it too, so everything waits for the whole of it. A merge is
microseconds, and anything unbounded - a transfer, a wait on another thread -
never belongs inside. The file reads in a lock scope are
PUT /client-certificates/:id and POST /client-certificates (#1455), whose
usability check reads the first page of the file the merged (or, for the
create, the staged) row names: the check runs on that row, so hoisting it out
would either give up the atomicity or re-open the window between the check and
the write it exists to guard. Both are called out at their site, and they are
the shape of exception to argue for - bounded, local, and load-bearing - not a
precedent for reaching further.
One read that takes no lock¶
Database::get_run_snapshot (#2679) is the one read that does not take the
DB mutex: it reads a run row through a second, read-only connection with a
small mutex of its own, which WAL lets read the last commit while the main
connection writes. A bounded writer still holds the DB mutex for longer than a
poll should wait (a results chunk whose commit runs the automatic WAL
checkpoint); this read waits for none of it. What it gives up is composing
with anything: it sees only what was committed before it, never a write in
flight, and no lock scope can include it. A read that decides a write is
get_run under the DB mutex. runs has the connection's
settings.
Listeners¶
This is the engine's whole listener inventory. The management API is the only long-lived one; four more are opened on demand, and the rule that separates them is where each may bind.
| Listener | Bind | Opened by | Serves |
|---|---|---|---|
| Management API | 127.0.0.1:9876 (configurable port) |
Daemon startup | Every route in api-reference.md |
| OAuth 2.0 loopback callback | 127.0.0.1, ephemeral port |
POST /oauth2/authorize/start in loopback mode (at most 16 unsettled) |
One /callback path, until the attempt settles or its 5-minute TTL expires, polled or not |
| Mock OAuth 2.0 issuer | 127.0.0.1, ephemeral port |
POST /mock-issuer/start (at most 8) |
/token and /authorize, until stopped |
| Webhook inbox | 127.0.0.1 by default; wider only on explicit confirmation |
POST /inbox/start |
Records any method on any path, answers a canned response; CORS per allowedOrigins |
| Collection mock server | 127.0.0.1, ephemeral port unless one is named |
POST /mock/start (at most 8) |
A collection's saved example responses, on the paths its requests describe, until stopped; CORS per allowedOrigins |
Every management API response also carries Cache-Control: no-store (#1507, server.cpp): every
route answers a live read of state that changes under the client, so nothing here is valid to replay
from a browser's disk cache. The mock server and inbox listeners are separate ManagedListener-owned
servers of their own (see the table above) and do not set it.
The management API serves no browser (admit_management_request, server.cpp): it sends no
CORS header, refuses a Host that is not a loopback spelling of its own port (DNS rebinding), and
refuses any request carrying Origin; an OPTIONS that passes the Host check is answered 204
with nothing else. The Electron shell strips the renderer's Origin and supplies the renderer's
CORS headers itself. See Who may call the API.
A mock server and an inbox do answer browsers, under a CorsPolicy fixed when the listener
starts (routes.hpp, issue #2367). With no allowedOrigins, the default, every response is
Access-Control-Allow-Origin: * and never carries credentials, so every page in the browser can
read it and none can read one sent with the user's cookies. With a list, a listed Origin is
echoed with Access-Control-Allow-Credentials: true and every other origin gets no CORS header at
all. The policy decides what a page can read, not what it can send: any page can still make a
mock or an inbox answer a request.
A mock with a list also answers 403 to a Host that is not a loopback spelling of its own port
(names_this_listener, routes.hpp, the management API's rule), against DNS rebinding; a mock
with no list and the inbox, which may bind wide, answer any Host.
The inbox is the only one that may bind beyond loopback, and the two reasons the others may not are different reasons:
- The management API has no route authentication - its Host and Origin checks keep browser
pages from reading or changing anything (a scriptless
GETstill reaches aGETroute, which is why none has a side effect), and a program on another host can send anyHostit likes - so anything that can reach it can read every stored request, every credential the database holds, and start runs against arbitrary targets. - A mock issuer hands out bearer tokens, and the OAuth callback carries an authorization code; publishing either would publish a credential.
- An inbox serves none of that - it accepts a request, stores it, and replies with what the user configured - so exposing it to a LAN exposes capture-and-echo and nothing more. A webhook source on another host is a real case; a management API on another host is not one worth the blast radius.
- A mock server re-serves stored response bodies verbatim, and a recorded response carries
whatever the real one carried - a session cookie, a token, a customer record. That is closer to
publishing the request store than to publishing an echo, so it has no
bindfield at all rather than a confirmation gate.
Even so, wide is never the default: bind outside 127.0.0.0/8 and ::1 is refused unless the
caller sends "confirmNonLoopback": true, and the inbox then reports loopback: false on every
read so the UI can badge it. A capture is stored in plaintext like the rest of the request store -
a webhook payload can carry a signature or a token, and nothing here treats it as credential-grade.
Streaming consumers¶
A streaming request (POST /execute with "stream": true, issue #573) is the one worker in
the engine that owns a curl transfer without being a run in RunManager. SseStreamManager
(engine/include/vayu/http/sse_stream.hpp) holds one thread per live stream: the thread performs
the transfer, parses SSE frames into a bounded per-run ring, and calls back into the route's
record_design_result when it terminates. GET /runs/:runId/events relays the ring; a finished
stream stays readable for liveRetentionMs and is then swept, its thread joined.
It runs the listener lifecycle discipline even though it owns no listener, and for the same
reason: its workers write run rows through Database and read the design-mode cookie jar, both of
which must outlive them. So the manager is a member of Server declared before server_, and its
destructor signals every worker to stop and then joins them all - signal first, join second, so
teardown costs one stream's stop latency rather than the sum.
Each on-demand listener is owned by a manager that is a member of Server, declared before
server_ (engine/include/vayu/http/server.hpp). Members are destroyed in reverse order, so the
route lambdas holding references to a manager are gone before its destructor stops and joins the
listener threads - and the Database those threads write to, being external to Server, is still
alive at that point. That order is the backstop: Server::stop() shuts every manager down itself,
before the daemon's curl_global_cleanup (see Thread Model). A handler that paces
its answer (a mock's latencyMs, an inbox's delayMs, an issuer's slow mode) waits on its entry's
stop signal rather than sleeping, and an OAuth callback's token exchange is cancelled by it, so a
stop, a delete, a cancel or a shutdown ends the wait at once instead of joining it out (#3345); the
paced answer then goes out without the rest of its delay. All four managers run that lifecycle -
bind, wait for the accept loop, stop, join, release - through one shared ManagedListener
(engine/include/vayu/http/managed_listener.hpp), and keep their records in one shared
ListenerRegistry (engine/include/vayu/http/listener_registry.hpp, #3345), so a fix to either
reaches every listener rather than one of four copies. The registry counts starts still in progress
against a manager's cap under the same lock as the running entries, so simultaneous starts cannot
overshoot it; it tears an erased entry down outside that lock, so a handler still running holds up
only the caller that stopped it; and its shutdown() is terminal, signalling every entry before it
joins any. What stays per-manager is the route registration, the error each bind failure answers
with, the OAuth attempt reaper, and the records that outlive their listener. A stopped inbox's
listener is torn down under the registry's lock because the record stays in it. A settled OAuth
attempt's result moves out of the registry instead: the authorize manager owns a reaper thread
(#3347) that fails each attempt still pending at its deadline, copies every settled result aside for
the 10-minute polling window and retires the listener outside the lock, so an attempt nobody polls
frees its port, the cap counts only unsettled attempts, and GET /oauth2/authorize/:id reads
without writing. Server::stop() shuts the authorize manager down before joining the management
API's handlers, the one manager it does, because an embedded completion's token exchange runs on
one of those handlers and watches its attempt's cancel. Since #1140 a manager may hand the ManagedListener the
httplib::Server those routes are registered on, too: the inbox hands it a subclass that routes
every request as one path, so that a path too long for cpp-httplib's regex matcher still reaches its
capture, and the other three take the plain server the listener builds for itself. The mock server
is the one built on the helper rather
than ported to it: #505 extracted it before this listener existed, which was the whole point of
extracting it when the third one landed.
That shared listener is also what keeps two of them off one port. Every live listener claims its
address:port there, and an explicitly requested port a live listener already holds is refused
before the bind, naming the holder. The bind cannot report it: cpp-httplib sets SO_REUSEPORT, so
on Linux a second bind on the same 127.0.0.1:port succeeds and the kernel load-balances arriving
connections across both accept loops - two inboxes on one port, each capturing a random half of the
webhooks and neither list showing the rest. An ephemeral request needs no check, since the kernel
does not hand out a port it is already using.
The same helper bounds the connections a listener holds (constants::listener): 8 worker threads
that grow to 32 for a burst, and a queue of 64 accepted connections waiting for one. cpp-httplib's
default queue is unbounded, and a listener shares the process's file descriptors with the management
API, every libcurl transfer and the database, so an inbox bound past loopback could otherwise be held
open by idle connections until a descriptor ran out and every send failed with a misleading "Out of
memory". httplib runs a whole connection as one task, so a connection past thread plus queue is
refused at accept and closed. The management API's own server is not on this helper and keeps
cpp-httplib's defaults.
The management API answers that same SO_REUSEPORT problem the other way round, because it is the
one listener whose port is a contract rather than a detail: it clears the option (Windows, which
has no SO_REUSEPORT and lets SO_REUSEADDR step over a live listener, gets SO_EXCLUSIVEADDRUSE
instead), so a port anything else holds fails the bind rather than splitting the engine's own
traffic. Server::start() binds before it serves and returns that outcome, and the daemon prints
the reason to stderr and exits 1 (#983). It was listen() before, which folds the bind into the
serve loop and reports failure only through a return false on a detached thread - so a taken port
printed the listening banner, unwound through the graceful-shutdown path and exited 0.
Change feed¶
GET /changes (#3420, api-reference.md) tells every client about
every committed write of a collection, request, example, environment, the globals or a trash entry,
so a row one client changed (the stdio MCP server, vayu-cli, a script, a second window) does not
stay stale in another's cache. Database owns the feed (engine/include/vayu/db/change_feed.hpp)
and is its only producer: each public write of those kinds publishes once its own transaction has
committed, from inside the method, with the DB mutex still held.
Three rules make that the whole story:
- No write runs inside another's transaction. Every multi-row write (
import_apply,apply_reorder,spec_sync_apply, a cascade) is one transaction inside one method, andwith_lockholds the mutex without opening one. So "after its own commit" is "committed": a batch collects its rows' changes while it writes and publishes them only once the transaction returns, so a rollback (aMissingRowErrorhalf-way through a reorder) publishes nothing, and a busy retry publishes once, for the attempt that landed. A write inside awith_lockcomposite that later throws stays committed, and so does its event. - No public write calls another, so nothing publishes twice; a cascade publishes one change, on the root it was asked about.
- Publishing is an append under the feed's own small mutex, a leaf lock: it is taken with the DB mutex held, which numbers events in commit order, and nothing holding it takes the DB mutex or touches a socket. The relay reads the ring under that mutex alone, so a stream never waits on the DB mutex and never holds it.
The feed is a bounded ring (change_feed::MAX_RETAINED_EVENTS); a reader whose resume point it no
longer covers is sent a reset and refetches everything. It owns no thread: each stream is a
management-API handler polling the ring on the relay cadence GET /runs/:id/events uses, at most
change_feed::MAX_READERS at once, and it ends on server_stopping like every other relay. A
stream is admitted only on a single-use subscription id that POST /changes/subscriptions issues
(ChangeFeed::issue_subscription, libsodium random, at most MAX_PENDING_SUBSCRIPTIONS unspent):
a page can send no POST without an Origin, so it cannot hold the slots a plain GET would take. The
feed lives in the Database, which outlives Server::stop()'s handler join, so nothing has to be
drained before it. The startup repair passes rewrite rows before the engine listens and publish
nothing; a client resuming from an earlier process is reset anyway, because ids start from the
process's start time.
Event Loop (curl_multi)¶
The event loop manages concurrent HTTP request execution using libcurl's multi interface.
Architecture:
- Multi-worker design: One event loop per CPU core (auto-detected)
- SPSC queues: Lock-free single-producer single-consumer queues for request submission
- Rate limiting: none in the workers. A constant_rps run is paced by its pacing
thread alone (run_rate_limited, see Load Test Strategies). A
second schedule in the worker would drift from the pacer's absolute one and put its wait
into each request's queue wait and latency (#2801, #2911), so a worker takes whatever its
queue holds, up to max_concurrent
- Connection pooling: Reuses connections with keep-alive
- DNS caching: 5-minute cache to avoid resolver saturation
DNS pre-resolution. Hostnames are resolved once and pinned onto each
transfer with CURLOPT_RESOLVE, which keeps a high-RPS run from saturating the
system resolver. Three rules make that safe:
- Entries expire after
dnsCacheTimeout(default 300s). curl treats a pinned address as authoritative, so an entry that never expired would survive a DNS change - a blue/green deploy of the target - and fail every request for the rest of the daemon's life. The cache is a process-wide static shared by every worker and every run, which is what made that permanent. - Failed lookups are remembered for 5s. Resolution is a blocking
getaddrinfoon the worker thread, so it stalls every in-flight transfer that worker owns; without a negative entry an unresolvable host paid that cost on every single request. Moving resolution off the IO thread entirely is the deeper fix and is not done. - IP-literal URLs are never pinned -
http://127.0.0.1/,http://[::1]:8080/- since there is nothing to resolve. Parsing an authority also handles userinfo (http://user:pass@host/), whose colon is not a port separator.
Configuration:
- Max concurrent requests per worker: 1000 (configurable)
- Max connections per host: 200 per worker (eventLoopMaxPerHost), raised
by a load run to each worker's share of its virtual users,
ceil(concurrency / workers) (effective_max_per_host, #2394), and reported
as a per_host_limit_raised run warning when it was for a run that asked for
virtual users, one whose config carries concurrency (#2801). A run that sets
none, which is every constant_rps run the app starts, is sized from
eventLoopMaxConcurrent and raised without a warning. Below that share libcurl
queues the rest of a worker's transfers while the run counts them in flight;
that wait is libcurl's CURLINFO_QUEUE_TIME_T, taken off the wire time and
counted as queue wait (detail::curl_queue_seconds)
- Poll timeout: 1ms (kept short because a submission interrupts the poll via
curl_multi_wakeup; on Windows see Timer resolution below for what makes
a 1ms wait 1ms)
- TCP keep-alive: 60s idle, 30s probe interval
- Max response body per transfer: 32MB (maxResponseBodyBytes); a larger
response fails that request rather than being buffered, since every in-flight
request holds its own body
Timer resolution (Windows). Windows waits at a ~15.6ms granularity by
default, so both the 1ms poll above and the pacing loop's sleep_for leg
(below ~500 RPS - a faster tick spins its remainder out instead) would return
roughly fifteen times late. timeBeginPeriod(1) buys 1ms, and the engine holds
that request only while a run is sending: the event loop itself holds a
refcounted platform::HighResolutionTimerScope for its lifetime, and
release_execution_resources destroys the loop as the run is retained. The
sidecar is resident for a whole app session and idle for nearly all of it, so
the request is scoped to runs rather than to the process - a process-lifetime
request is the classic Windows idle-power finding. A design-mode scenario run
builds no loop and asks for nothing. Nesting is why it is refcounted:
overlapping runs take it once between them, under a mutex that moves the count
and the OS call together, so one run finishing cannot hand the resolution back
under another that is still sending. Nothing on Linux or macOS is affected; the
scope compiles to a counter there.
Run Manager¶
Manages the lifecycle of load test runs:
- Run registration: Tracks active runs by ID
- Run context: Stores configuration, event loop, metrics collector, and an in-memory tick topic (ring of wire-ready metric snapshots) per run
- Retained finished runs: Completed/failed/stopped runs are moved to a separate retained
map rather than unregistered immediately, so a late SSE client still receives the full metric
series. A TTL sweep evicts them after
liveRetentionMs(default 60s). The tick topic is what is retained, not the machinery that filled it: the move releases the run's event loop - its curl handle pools, its multi handles and the connections they cache against the target, its submission queues - along with the bound data rows and the scenario plan, so a finished run holds none of them for the window (issue #1154). The counters and histograms behind the summary stay, because the report and a late/liveconsumer read them. - A Stop means what its phase says (issue #3341):
RunContextcarries aRunPhase(setup,sending,draining,summarising,settled;core/run_phase.hpp) andrequest_stoplatches the phase the first Stop landed in. A Stop before the strategy returns (setuporsending) decides the outcome (stop_decides_outcome): the run endsstopped, its queued backlog is thrown away and in-flight transfers are cancelled, so a stop is not paced by the upstream. A Stop after the strategy returned on its own (draining) decides nothing: it cancels the natural-end drain at once, the in-flight transfers are counted as cancelled, and the run keeps its own end -completed, orfailedby itsfailRunthresholds. What it cancelled is stored as the summary'sdrainCut(RunContext::drain_cut, issue #3538): those are the run's slowest requests and in none of its figures, so every verdict reader takes such a run as not judged unless a budget already failed it, while its status stays its own end. A run that reaches the end of its duration with no Stop waits for genuine in-flight requests, but no longer thantimeout+ 2s. A sequential collection run has no drain. The phase and the latch are one atomic byte (RunPhaseLatch) that only compare-exchange loops write, so the worker's advance and a Stop's latch are totally ordered. The phase is memory only: it is not stored, there is no schema change, and a stored run carries only itsRunStatus. It is published while the run is active (issue #3568), asphaseon every livemetricsframe (emit_live_tick) and onGET /runs/:id(get_run_response, fromRunManager::get_run, so a retained or stored run has nophasekey). A streaming run (stream: true) is not bounded bytimeout: its bound is the stream's duration cap (maxStreamDurationMs) plus the 5s backstop grace plus 2s (natural_end_drain_ms, issue #2834), so the drain never cuts a healthy stream short of its cap. A collection run waits for the longer of the two: its longest streaming step's cap the same way (longest_stream_bounds, issue #3235), ortimeout+ 2s for its ordinary steps (collection_natural_end_drain_ms). A request the drain deadline cancels with no Stop is recorded as an error; one a user stop cancels, in either phase, is not (issue #2136) - it is counted apart, ascancelled, outside the run's total and its error count, sorequests_sentis always the total plus the cancelled count. - The move to the retained map is the "worker is finished" signal: it happens after the
final metrics flush and status update, which is what
DELETE /runs/:idwaits on before removing rows (see the API reference), and it setsRunContext::settled, which/runs/:runId/livewaits on before itscompleteframe reads the status (issue #2140) -closedalone flips when the last tick lands, before that tail. It is not the "worker thread has exited" signal - the move is the worker's last statement, and the thread is still unwinding after it. - Graceful shutdown drains, then joins:
RunManager::shutdown()callsrequest_stopon every active run (the same latch, so a run still sending endsstoppedand one in its natural-end drain has the drain cut short and keeps its own end), waits up to 5s (RUN_SHUTDOWN_GRACE_MS) for them to reach a terminal status, and then joins every worker thread. The manager owns those thread handles - a worker holds ashared_ptrto its ownRunContext, so a context that owned its thread could end up joining itself. The wait is bounded; the join is not, because abandoning a worker leaves it writing through references to aDatabasethatmainis about to destroy. A run started while the drain is in progress is refused with a503. The recovery backup's shutdown refresh that follows is budgeted against what the drain leaves of the app's 5 s window (SHUTDOWN_WINDOW_MS), so a long drain shortens or skips it rather than pushing the engine into the app's kill. - Finished workers are reaped on the next
start_run: a thread cannot join itself, so its handle outlives it until another thread collects it. - Per-run auxiliary threads: a load run has a metrics thread
(
collect_metrics), a scrape thread when it declares amonitorblock (collect_monitor) and, for each header-placed expiring oauth2 token it sends, an auth-refresh watchdog (run_auth_refresh, see below): at most one for a single request, one per distinct token-cache key for a collection. All watchis_runningand are joined together throughRunContext::join_aux_threads- the worker has several exit paths, and a thread joined at only some of them outlives theDatabaseit writes through. The join first setsRunContext::aux_cancel, theClientConfig::cancelof the scrape's and every refresh's transfer, so neither holds the summary, the terminal status or a shutdown for its network timeout (#3343): a cancelled transfer ends at its next libcurl progress tick, about a second, and counts as neither a failed scrape nor a failed refresh.should_stopis not that flag because a natural end never sets it. - The run's own thread carries
should_stop(#3371): everypm.sendRequesta load run's scripts make (script.setup/script.teardown, the inline step scripts, the deferred replay), and a sequential collection run's setup and teardown, takes it throughScriptSendInputs::cancel, and a single-request run's start-of-run token request takes it throughbuild_request, because Stop and shutdown both raise it and both wait on that thread. A sequential run's every step takes it too, throughExchangeInputs::cancel(run_step_exchange, #3397): the step's send, its late OAuth 2.0 token request and its scripts'pm.sendRequest, so Stop and shutdown end the step in flight at the next progress tick instead of after its timeout, and the runner records that step asstopped, nevererrored. A token request whose flag is already set is never sent, so a stopping server does not reach the endpoint. The auxiliary threads keepaux_cancel: a replay or teardown after a natural end must still send. A call it cancels is the run ending, never a failure: a cancelled token request ends the runStopped; a lifecycle or inline step script whose send it cancelled isskipped(so a cut-short setup does not fail the run), and an inline one's tests and throw stay out of the step's result, so no tally counts them; the replay leaves such a sample untallied (ScriptResult::send_cancelled). The same flag ends the script itself (#3460):ScriptSendInputs::stopandExchangeInputs::stopcarry it toScriptContext::stop, which the QuickJS interrupt handler reads beside the deadline and the async drain before every job, so a looping script ends at its next poll and isScriptResult::cancelled, recorded like a cancelled send. The replay also checks the flag before every sample and script, so a Stop or shutdown during it settles within the Stop's grace and one latched before it replays nothing; a replayed script that timed out is not run against the samples after it. Teardown is the deliberate exception (RunContext::teardown_stop): a Stop latched before it began leaves it to run, its sends cancelled at once, and onlyRunContext::engine_stopping, whichRunManager::shutdownraises throughrequest_shutdown, ends it then. - Two kinds of worker, one lifecycle:
start_runspawns the load executor plus its auxiliary threads,start_scenario_runspawns the sequential collection runner. Both go through the samespawn_runregistration - the shutting-down check, the reap and the handle insert all happen under one lock, and a copy of that reasoning per run kind is exactly how a worker outlives a drain that already declared its state safe to destroy.
Metrics Collector¶
High-performance in-memory metrics collection optimized for 60k+ RPS:
- Pre-allocated storage: Avoids reallocation during tests
- Lock-free atomics + HdrHistogram: Zero-contention counter updates; latency recorded in an
HdrHistogram (µs resolution). Every event-loop worker records on its own thread, so both the
cumulative histogram and the rolling interval recorder are written through the library's
atomic entry points (
hdr_record_value_atomic/hdr_interval_recorder_record_value_atomic). The plain variants are a non-atomiccounts[i] += 1; total_count += 1and lose samples under concurrency - silently, since the run still reports percentiles, just computed from fewer samples than it served. The interval recorder's phaser orders the once-per-tick reader against writers; it is not mutual exclusion between writers, so it does not make the plain write safe. - Every latency histogram tops out at one hour (
HISTOGRAM_MAX_LATENCY_US, issue #2790): the run's, the rolling window's, the five phases', each plan step's and each transaction's. The library refuses a value above its ceiling and counts nothing, so a requesttimeoutset past an hour would have left a long completion out of every percentile andmax. Each record site clamps (histogram_latency_us/clamp_to_histogram_ceiling,core/metrics_collector.hpp), so such a completion lands in the top bucket: percentiles andmaxread one hour, and the histogram's count is still the number of completions. The mean, a sum rather than a histogram read, keeps the true duration, so it can exceedmax. - Load percentiles and
maxround up, by at most 0.1% (issue #2791): every latency histogram is kept atHISTOGRAM_SIGNIFICANT_FIGURES= 3, so a recorded value shares a bucket with its neighbours, and the library reports a bucket by its highest equivalent value (hdr_value_at_percentileandhdr_maxboth end inhighest_equivalent_value,vendor/hdrhistogram/src/hdr_histogram.c). A percentile ormaxtherefore never reads below the sample it stands for and can read above it by up to one bucket - under 0.1% of the value (the bucket is 512 µs at 1 s, 256 µs at 500 ms). One request of exactly 1000.000 ms reportsmax1000.447 ms; a p99 of exactly 500 ms reports 500.223 ms. The minimum is the one figure rounded the other way, down to the bucket's lowest value. The rank isround(p/100 * n), at least 1, over the bucket counts. The sequential collection runner does not use the histogram:percentiles_from_latencies(core/scenario_runner.cpp) sorts the step latencies and reads the exact value at rankceil(p/100 * n), so itsmaxis the true slowest and its percentiles carry no bucket error. The two methods differ in rank as well as in rounding at smalln: the p95 of 11 samples is rank 10 through the histogram and rank 11 in the runner. Compare a collection run with a load run only to that tolerance. - One reader merges the windows: each window the metrics thread samples is added, before the
recorder recycles it, into three more histograms only that thread touches, so they take plain
calls. One is the open second, which
take_second_percentiles()reads and resets at the 1 Hz gate for the stored row and the gate frame'ssecond*keys (issue #2385): percentiles cannot be merged after the fact, so a row built from the last 100 ms window held a tenth of its second. Another is the run so far, behind the livecumulativeP*Msand the gate frame'scumulativeLatency(issue #2782); reading the cumulative histogram itself mid-run would be a plain read racing the workers' atomic writes. The third is the capacity level (issue #2388), restarted byadopt_level_epoch()when the capacity search asks and read bylevel_latency()for the published tick; see the capacity feedback path below. - Per-phase histogram bank: five more HdrHistograms (DNS, connect, TLS, first-byte, download),
fed by every successful completion and read after the drain, behind the report's
timingBreakdown.phasesand, through each phase's mean, itsavg*Ms(issue #2782). Deliberately not gated on the trace-retention decision: a trace is stored for about 1% of completions, and escaping that biased sample is the whole point. The gate frame also reads the bank once a second for itscumulativePhases, while the workers still write. It copies each phase's counts with atomic loads into one reader-owned histogram and runs hdr's plain readers on the copy, recounting its total from what was copied, so a phase's figures and its count are one reading; hdr's readers on the live bank would be plain reads racing the workers' atomic adds. Off -phaseHistograms, or a run's ownphase_histograms- leaves the bank unallocated, so the cost on the completion path is one null check. Written throughhdr_record_value_atomicfor the same reason the two above are. - Perceived latency: Latency is measured as
completion − submitted_at(the full time a request spent inside the engine), not just libcurl's wire time. Wire time and the generator-internalqueue_waitare tracked separately. A latency sample is any request whose transfer ran: an answer of any status, or a failure after the transfer began (a timeout, reset, DNS or TLS failure, the body cap), whose duration is the time until it gave up. A request a Stop cancelled or one refused before the wire (themaxInFlightcap, an invalid URL, a refused header, a data-binding failure) has no duration and is not a sample. The percentiles, the max and the mean share this one population (the mean divides by the sample count, not by successes). A stored error row (results.latency_ms) carries the same duration, and0where there is none; see Latency population. - Rich counters: bytes sent/received, dropped requests (backpressure), queue-wait average, peak in-flight, and a full per-status-code distribution
- Status classes by completion second (issue #2866,
core/status_seconds.hpp): beside the cumulative per-code distribution, each completion reads the steady clock on its own thread and adds one to its class (2xx, 3xx, 4xx, 5xx, or error: code 0 and anything outside 200-599) in the slot of the second since load start it completed in, one relaxedfetch_add. The slots are a ring of 128 seconds, fixed at 5 KiB however long the run. The gate drains each second 250 ms after it ends (CLOSE_MARGIN_MS), with anexchange (0)that frees the slot, and hands the same entries to the stored row'sstatus_secondsand the gate frame'sstatusSeconds, so a chart draws a rate no tick's timing moves. The margin is the window between a worker's clock read and its increment: a worker stalled longer than it increments a second already emitted, and the next gate that emits finds the count by sweeping the previous 64 emitted seconds and adds it to its first entry, about a second late. A metrics thread more than 128 s behind reads two seconds that share a slot as the older one; neither case loses or double-counts a response. The collector's origin isset_load_start, given the instantRunContext::load_start_steady_msholds, and nothing is counted per second before it. The run export is a third consumer, after the app's chart and the metrics route'smaxPointsfold:run_export.cppcopies each tick's entries thatstatus_second_entry_from_jsonaccepts, so the document'stimeSeriescarries the same per-second counts, andrun_export_html.cppdraws its status chart from them as responses per second, falling back to differencing the cumulativestatus_codesonly for a run whose rows carry none (#2888) - A scenario load's sequence on the gate frame (issue #2823):
execute_scenario_loadpublishes itsScenarioLoadStateto theRunContextonce it is built (publish_scenario_state, a leaf mutex held for the pointer swap alone, theevent_looppattern), and the gate frame copies the pointer under that lock and builds itsscenarioblock (build_scenario_live_progress) from the state's relaxed atomics and its step labels, which are copied off the plan at construction because retention releases the plan. It never reads a step's histogram: those are plain hdr reads racing the workers' atomic records, so per-step latency stays a report figure. Retention drops the published pointer with the event loop; the metrics thread has been joined by then - Batch DB writes: Per-request results written after test completion; the metrics thread
persists one wide
metric_ticksrow per second during the run (the complete tick object, built once at write time), and the whole-runruns.summaryis written once at completion. The results go in chunks ofRESULTS_WRITE_CHUNK_ROWS(250), one transaction and one DB mutex acquisition each, with a 1 ms pause off the mutex between chunks (#2548): the run is stillrunningwhile it flushes, and a 10,000-row flush written whole held the mutex for 240-400 ms, so a live report poll waited out all of it. The poll now waits for no chunk: it reads only the run row, throughget_run_snapshot, which takes no DB mutex (#2679, One read that takes no lock). A result and its captured body share a chunk; a failure part-way keeps the chunks before it (results) - Bounded error storage: Error counts and the status-code distribution are exact, but only
the first
maxStoredErrors(default 10,000) individual records are kept; the rest are counted byerrors_dropped()and logged once. A fully-failing target produces errors at close to the completion rate, each carrying a message and a trace blob, so an unlimited store grows for the whole run and then flushes as an enormous write. Success results are sampled. The per-type error breakdown is exact too: the collector counts each error by type (error_type_counts) before the store's cap is checked, and the run summary stores those counts aserror_types(#2400). Only the per-error detail is a prefix, which the report says aserrors.withDetails. A run stored before #2400 has noerror_types, and its breakdown still counts the stored records, so past the cap it covers the firstmaxStoredErrors. - Response sampling: Stores samples for deferred script validation
Script Engine (QuickJS)¶
JavaScript execution engine for pre-request and test scripts:
- Postman-compatible API:
pm.test(),pm.expect(),pm.response, etc. - Mutable request: a pre-request script's
pm.requestwrites are applied to the request before it is sent (seedocs/engine/scripting.md) - Signing:
pm.crypto.sha256/.hmacSha256plus thebtoa/atobglobals, so a pre-request script can sign the request it just rewrote. Backed by libsodium throughutils/sha256.hpp(shared with PKCE) andutils/encoding.hpp- the engine hand-maintains no hash, HMAC or alphabet table. Synchronous: Web Crypto covers algorithms the sandbox does not implement, so the surface ispm.crypto, notcrypto.subtle. - Memory limit: 64MB per script execution
- Timeout: 5 seconds per script
- Sandboxed: No filesystem access; the one way out to the network is
pm.sendRequest, held to the samehttp/httpsscheme rule as a request (Security)
Platform Support: one engine everywhere - QuickJS-NG (the actively
maintained fork), vendored in engine/vendor/quickjs-ng and built via its own
CMake on all three platforms. Until #226's review, Linux/macOS ran Bellard's
original QuickJS while Windows ran NG (the original does not compile under
MSVC) - two interpreters behind one pm.* surface, so an engine-level
behaviour difference was a Windows-vs-Unix script divergence. The original
copy is deleted.
Cookie Jar¶
http::CookieJar (include/vayu/http/cookie_jar.hpp), owned by http::Server
and reached by route handlers through RouteContext::cookie_jar. It is what
makes a session survive from one design-mode request to the next.
- Scope: one jar per environment, plus one for requests sent with no environment selected. The environment is the axis that separates staging from production, and cookies ignore port and scheme - so two local services on different ports would otherwise share a session cookie.
- Lifetime: the process. In memory only; a stored jar is credential-grade
material and would need the treatment auth tokens already have rather than a
new path beside the request store.
GET /cookiesshows it,DELETE /cookiesempties it, and the app surfaces both in Settings → General → Cookies. An environment's jar follows the environment through the trash (issue #3349): trashing keeps it butGET /cookiesleaves it out, a restore lists it again, and a purge (DELETE /trash/:id) drops it. The jar has no database, so the route filters by the live environment ids it reads per request. - Storage: libcurl's own lines. The jar holds what
CURLINFO_COOKIELISTexports and hands it back throughCURLOPT_COOKIELIST, so domain matching, path matching,Secureand expiry stay inside libcurl's cookie engine. The parser and matcher incookie_jar.cppserve the read views (pm.cookies,pm.cookies.jar().get,GET /cookies), which need an answer without a transfer, and the URL-scoped removaljar().unsetperforms. They never decide what goes on the wire. - Not on the load path.
EventLoopnever touches the jar: a shared jar across workers is either a lock on the hot path or per-worker jars that do not actually share. A scenario load run does carry cookies - it has to, since its whole point is a sequence where step 2 uses what step 1 established - but each virtual user owns a private list seeded onto its own transfer and cleared at each iteration boundary, and the environment jar is untouched (see "Scenario load runs" under Load Test Strategies). One session shared between 1,000 virtual users is not the thing being measured. An inlinescript.*element'spm.cookiesreads that one VU's own list directly, with no lock and noCookieJarobject (issue #1501); it stays read-only there, andpm.cookies.jar()'s writes still throw under every load-run script. - Threading: one mutex around the scope map; every accessor copies out, so no reference into the storage escapes to a caller.
- Shown as sent. Because libcurl attaches the matching cookies itself, the
composed header map never sees them - so the raw-request view is built from
the transfer's last
CURLINFO_HEADER_OUTframe (client.cpp) rather than fromrequest_headers, and shows theCookieline the wire carried, value plain. The verbose transfer log keeps its redaction (debug_redact.hpp): a log gets exported and shared, the raw view is read on the machine whose Settings already display the same value. A script-written cookie is on that frame too, since it goes out on the same transfer. ACookiethe request types joins that line rather than going out beside it (issue #2788): its rows rideCURLOPT_COOKIE, which libcurl writes after the jar's matches on the one line, so a request never carries twoCookieheaders. The one exception is a line libcurl cuts at 8190 bytes, which drops the typed rows with it:request_headersrecords them before the transfer, soapply_cookie_noticesremoves them afterwards and the response carries acookie_not_sentwarning, as it carriescookie_limit_reachedpast 150 jar cookies. Both come from libcurl'sCURLINFO_TEXTnotices (issue #3307), read before the verbosity gate because they are the response's, not the log's. The incoming side has no notice to read: libcurl discards aSet-Cookieline over 5000 bytes, a cookie whose name and value pass 4096 and every cookie past the 50th of a response without a word, so the header callback counts the lines (IncomingCookieWatch) when the send has a jar, and the response carriescookie_dropped_oversized/cookie_dropped_too_many. AdisableCookiessend has no jar, libcurl's engine is off and nothing is reported. Both design drivers report all four from one copy,http/cookie_warnings.hpp:Client::sendand the streaming consumer (sse_stream.cpp, #3315), which turns libcurl's debug stream on for the notices alone and keeps no frame. A stream's warnings land on its stored trace, never on the202or a relay frame: the app reads them fromGET /runs/:runId/reportonce the relay'scompletearrives. The incoming rules are one copy,SetCookieLimits(http/set_cookie_limits.hpp), which the event loop'sheader_callbackalso runs, allocation-free, on a transfer that tracks cookies (a scenario load run's step): it counts what was dropped onResponse::set_cookie_headers_dropped,handle_resultsums that in theMetricsCollector, and the run reports onecookies_droppedwarning with the count and no name. The outgoing caps are not detected under load, because reading libcurl's notices needsCURLOPT_VERBOSEon every transfer. - History keeps that frame too, cookies included. The jar itself is never
persisted, but a design or scenario run stores the message its transfer sent
as
trace_data.request.rawRequest(build_result_trace), so reopening the run shows the sameCookieline the live view did instead of a session-less request rebuilt from the composed headers (issue #348). That is a deliberate write of credential-grade material, into the node that already stores the resolvedAuthorizationheader beside it - see Security for where the line between this andruns.config_snapshotfalls. It is bounded by run retention, not by the process:DELETE /cookiesempties the jar and does not touch stored runs. - A transfer writes back its own changes, not the whole scope (issue
#1888). Transfers in one scope overlap - a stream beside a send,
pm.sendRequestbeside another execute - socapture_jar_cookieshandsCookieJar::reconcilethe scope's lines the handle was seeded from beside what it held at the end, and under one lock the jar applies only the difference, keyed by (name, domain, path): a cookie added or changed is written, one seeded but no longer held (the server expired it) is removed, and one the transfer never saw - another transfer's - is kept. Contents are compared parsed, so libcurl re-spelling a line it was given is not a change. - Script writes are staged, not applied in place (
pm.cookies.jar(), issue #337). A write becomes aCookieWritethat the execution's next transfer applies on top of the stored lines when it seeds its handle (ClientConfig::cookie_writes) - the request carries it, and because the seeded-from lines are read before the writes, that transfer's capture sees the write as one of its own changes and persists it. A write with no transfer left to ride, a post-request script's, is applied by the route throughCookieJar::apply. Either path applies it exactly once.
pm.sendRequest shares the jar of the execute it runs inside, so a pre-request
script can log in and leave the session where the real request will find it; it
also carries any write staged before it.
pm.cookies.jar() is limited to the request's site (issues #2358 reads,
2631 writes): the URL a script names must domain-match the request's host in¶
either direction (hosts_domain_related) or match a host the execution has
called through pm.sendRequest (ContextData::addressed_hosts), and reads and
writes ask one helper (jar_host_in_scope, pm_cookies.cpp) so they cannot
drift. A read outside it answers undefined / []; a set, unset or
clear(url) outside it stages nothing; both leave a console warning. A set
is also held to its cookie's domain, which is where the cookie is sent and so
can differ from the URL. The jar keeps every host's session for the
environment, so the limit is what stops a script reading, planting or deleting
one it has no business with. Redirect targets are not compared.
Auth Resolution & OAuth 2.0¶
The engine resolves request auth server-side - the persisted auth object is
applied to the outgoing request rather than being left to the UI. This lives in
vayu_core (so both the design and load paths share it):
request_builder(build_request) - the single request-construction pipeline: deserialize the payload, apply the resolved timeout, then resolve auth. BothPOST /executeandPOST /runsgo through it.auth_resolver(apply_auth/preflight_auth/plan_oauth2_refresh/plan_auth_refresh) - a typedAuthvariant with an exhaustive per-mode handler: bearer/basic/api-key are injected inline;oauth2delegates to the token client; a mode stored but not executed (digest,aws,ntlm,hawk,oauth1,edgegrid,jwt) sends the request without auth and setsRequest::auth_notice, which the/executeanswer and the stored trace carry asauthNotice(#2474); a bearer token or API key name that is empty once trimmed writes nothing and sets it too (#3203). A user-suppliedAuthorizationheader always wins; against anoauth2token placed in the header it wins before anything is fetched (#3202), at the build, atpreflight_auth(which takes the run payload's headers) and in a lateapply_auth, and sets anauthNoticesaying so. Credentials carrying a{{data.*}}or a{{$vu}}/{{$iteration}}token are the first case auth is not resolved into the plan (a credential awaiting a script is the second, below): the value has to be bound before the credential is encoded, so the step keeps its typedAuthand applies it per iteration (bind_step_iteration, see Scenario runs). What is deferred is decided by the credentials, not by the run's shape (issue #1055): a build defers because these credentials carry a token, so a run with no data set at all still bindsuser-{{$vu}}. An OAuth 2.0 config carrying either kind is refused by name instead - its token is acquired once, before any iteration exists, so no bind can reach it. A credential still holding a name no scope answered at compose is deferred too, for a script to define (#2473): the row and identity are joined into it without applying it (bind_iteration_holding_auth), and it is resolved against the scopes the script left and applied after the residual-token pass (apply_late_authinrequest_exchange), Postman's order.POST /executedecides it per send (plan_send_row_auth), a collection run per step when its plan resolves (ScenarioStep::auth_after_scripts, applied byexecute_exchangeon the sequential run and byresolve_load_residualson the load run), and a single-request load run once, only when it declaresrequestElements(LoadAuthPlan::after_scripts), the one shape with a residual pass per submission. One withoutrequestElementsthat names anenvironmentIdorrequestIddefers the build too, and its start-of-run pass resolves the credentials against those scopes and applies them once to the shared request (#3288). A step or run whose credentials hold no such name pays nothing per iteration.plan_auth_refreshdecides afterwards whether the credential a single-request load run just resolved can be kept current past its expiry, andplan_scenario_auth_refresh(core/auth_refresh.cpp) the same for each step of a collection load run - see the run lifecycle below.oauth_client(acquire_token) - grant handling (client_credentials, password, authorization_code), theoauth_tokenscache (expiry skew min(45s, lifetime/2), refresh-token rotation, one refresh in flight per cache key and a compare-before-delete on a refused refresh, #3344; only aninvalid_grantorinvalid_clientrefusal clears the row, and an unavailable endpoint on a refresh is anoauth2_network_error, #3360), and RFC 6749 client auth. An interactive call skips the cache and always exchanges its code. It never logs token bodies/headers.oauth_authorize- the interactive Authorization Code manager: an engine-hosted127.0.0.1loopback listener + PKCE (S256) andstate, so the entire flow (including the code exchange) stays in-process; the app only opens the browser. Its reaper thread expires attempts at their TTL whether or not anyone polls (#3347). Owned by theServerfor a clean shutdown.mock_issuer- the local OAuth 2.0 issuer (routes/mock_issuer.cpp):POST /mock-issuer/startbinds another127.0.0.1listener serving/tokenand/authorize, so auth flows are exercisable offline with no real identity provider. It mints HS256 JWTs with a random per-issuer key (libsodium again), auto-approves/authorizewith PKCE S256 verification, rotates refresh tokens, and can be flipped between healthy andslow/server_error/invalid_clientwhile running. In-memory only and owned by theServer, on the same reverse-member-order rule as the authorize manager.
Listener inventory. Both auth listeners are spawned, loopback-bound and
short-lived - the interactive-auth callback (one per attempt, 5-minute TTL, at most 16 at once) and
mock issuers (at most 8, until stopped) - and neither may ever bind wider than
127.0.0.1, because one carries an authorization code and the other hands out
bearer tokens. The full inventory, including the one listener that may bind
wider and why, is above.
PKCE hashing uses libsodium (crypto_hash_sha256, and sodium_bin2base64's
URL-safe unpadded variant for the challenge itself; no OpenSSL). See
the API reference for the /oauth2/* routes.
Request composition boundary (engine-owned via POST /compose)¶
The engine owns request composition since issue #226.
POST /compose (routes/compose.cpp → compose_request_core in
src/http/request_composer.cpp) takes a requestId (a saved request) and/or
an inline unresolved request, plus collectionId / environmentId scope
ids, and returns the execute-ready payload that POST /execute and POST
/runs accept unchanged. Composition:
- builds the effective variable map (globals < collection chain root→leaf <
environment, enabled definitions only) and interpolates
{{variables}}into the URL, header keys/values, body content/fields, and the auth block - raw stored strings, an unknown name kept braced whether or not it is a$name(issue #1009), a substituted value that carries tokens of its own resolved through them to a bound of 8 levels, dynamic variables ({{$guid}}, …) generated per occurrence - unless the caller asked for them to be deferred (deferDynamicVariables), which a composition made for a run does, so the run generates a fresh value per iteration instead of repeating one (issue #995). When a pre-request script runs before the send (an enabled, non-blankscript.preon the request, a folder or the collection), composition leaves every name a scope answers written and lists the names in the response'sdeferredVariables(issue #2521), for the send to resolve after that script. A collection run's plan asks the same of every step when any element in it writes a variable before some send (VariableDeferral::Always, below); - resolves
inheritauth by walking the collection ancestor chain leaf→root (an explicitnoauthterminates the walk,noneis stepped over), and resolves variables inside the winning block before any OAuth 2.0 cache key can be derived from it - at composition for a run, after the pre-request script for a Send or a sequential run's step, where the key is computed from the resolved config either way; - for a
requestId, assembles the whole payload from the stored row: flattened enabled headers, body, execution options, and the ordered script-part lists from the chain plus the request's own. An inlinerequestgiven alongside arequestIdlays over the stored fields before resolution (how MCP'sstart_load_runoverrides work).
Composition is pure - nothing is sent, no run row is created - and it is
still the only place a payload is composed: an execution endpoint never
composes one, so a payload that skipped composition is sent as supplied.
Decision D1 of #226 is now: a name resolves at compose, except where a
pre-request script can change its value (issue #2521), when it resolves after
that script - Postman's order. Whether one runs is read from the composed
elements (no caller flag), so a request nothing scripts is interpolated once,
before the send, as it always was.
The second resolution is narrower than a second composition:
resolve_residual_tokens resolves the names composition left written - a name
it could not answer, which keeps its braces (#1009) rather than becoming
"" (#1008), and every name a scope answers in a request a pre-request script
runs before (#2521) - once, after that script and before the send, so
pm.environment.set("token", …) does reach {{token}} in the same send, on
every run. A value composition substituted is finished text and is never
revisited, which is what keeps "resolved once" true of every value that had an
answer. What composition resolves whatever a script does: {{data.*}} and the
bound row's names, $ names, a name whose value reaches one of those, and a
file path (the pass never resolves a path). The one thing this costs: an ad-hoc
payload posted straight to /execute with a literal {{...}} in it is no
longer inert - if the run's scopes define that name, the send now carries its
value. A name nothing defines still goes out written as it stands, and a load
run runs the pass per submission only where it has scopes to read, and counts
rather than refuses; a single-request run whose submissions are not copied
(no requestElements, or only response-reading ones with nothing to bind or
apply per submission, #3288) that names an environmentId or requestId runs
it once instead, at start, over the request every submission shares
(resolve_load_template_tokens, #3253), leaving the bind's own tokens for each
submission. An OAuth 2.0 config defers like the rest on a Send and a
sequential run's step: it is resolved after the script and its token acquired
then (apply_late_auth, with the token cache), so a script reaches the token
request. A load run acquires once, before any script. What the pass can refuse is what resolving a
header name can produce, both rules held in
engine/include/vayu/http/header_names.hpp: a name landing on one the request
already carries (#1051), where the rows show two different names and the
request would carry one header twice; and a name landing on nothing at all (#1084),
where what would go out is a ": value" line no name owns. Either is stopped
rather than sent - in composition's words and under composition's refusal
code, as a statusCode: 0 response carrying the reason (a 400 on the
streaming path, which has not answered yet, which is why the refusal carries
the code as well as the error). The two rules read a name over different
reaches, decided rather than inherited (#1095): the empty-name rule reads
every header name, so a name a script has just emptied and an empty key
posted straight to POST /execute are refused here too, while the collision
rule reads only the names that still held a token - a request that arrives
already resolved cannot carry a collision to find, two names that are already
equal being already one key. The same pass also trims the spaces and tabs
around every name and refuses one that is not an RFC 9110 token once trimmed
(#2467, invalid_header_name), which is how a name a script defined is judged;
it reads every name for that rule as it does for the empty one, and a token
nothing answered is left written while the text around it is judged. A header
value a variable would end or cut is refused here too for a scripted request,
whose variables composition no longer substitutes (unsendable_header, #738's
rule, #2521), and so is a bearer token or header-placed api key the late auth
resolves (apply_late_auth, #3203); the buffered answer carries each refusal's code as
refusalCode. An unresolved {"mode":"inherit"} reaching an execution endpoint
is treated as no auth and logged as a warning - it means a client skipped
composition.
Clients: the renderer sends its editor state through the inline shape (Send,
load test, and History's replay - editor state can be unsaved or a detached
copy, which is why compose-by-id alone would not do); MCP composes saved
requests by id and checks its allowlist early against the composed URL, then
attaches the same rule to every send as targetPolicy (issue #2521), which the
engine applies to the URL it is about to send - after the pre-request script
and the residual pass - to the host of an OAuth 2.0 token endpoint, before
the token is requested, and to a load run's monitor.url, as the scrape will
dial it, when the run is validated (#3121). It does not cover a redirect hop or a script's
pm.sendRequest. The renderer
keeps a preview-only copy of the substitution rules
(app/src/lib/variable-resolution.ts) for tab titles, previews and the
unresolved-token painting; the shared conformance fixture
(engine/tests/fixtures/variable-resolution-conformance.json) holds it to the
engine's behaviour.
Script composition on POST /execute and the sequential run: a script is a
script.pre / script.post element (#1514's cut-over off #1513's two
script columns), resolved the same way every other element kind is - the
collection chain's elements root-to-leaf, then the request's own, minus
anything disabled or named by an inherit.disable entry, each stamped with
its origin (compose_elements engine-side for the by-id path; a client on the
inline path sends its own elements array and it overlays the resolved chain
field by field). preRequestScript(s) / postRequestScript(s) / tests are
refused with a 400 naming elements on POST /execute and on the stored
resources alike - a clean cut, not a transitional alias. Each script.pre /
script.post element runs as its own script, in its own fresh
ScriptContext, at ElementPipeline's step.before / step.after - there is
no longer a blank-line join across a chain's script elements; state that must
carry from one to the next goes through pm.environment /
pm.collectionVariables / pm.globals / pm.iterationData, or, for a
pm.request edit, through the one Request object every element at the step
shares. Script text is never interpolated - a {{...}} inside a script is
user JavaScript, not a template. A load run's deferred replay keeps the same
rule (#3125): each un-inlined script.post element (a single-request run's
RunContext::test_scripts, a scenario step's find_step_post_scripts) is
replayed as its own script against every sample, never a joined text. The
replay starts from a copy of the scopes script.setup left (ReplayBase,
3460: RunContext::lifecycle_scopes, or ScenarioLoadState::lifecycle_scopes),¶
never a fresh read of the stored rows, and teardown reads the original. Each
sample's pm.request is re-derived from the request the run built and the
row and identity the sample recorded (request_as_submitted,
step_request_as_submitted), so nothing is retained per sample - see
scripting.md.
Database (SQLite)¶
Persistent storage using sqlite_orm:
Schema:
- collections: Folder hierarchy for organizing requests
- requests: Saved HTTP requests with headers, body, scripts
- environments: Variable sets for different environments
- globals: Singleton global variables
- runs: Test execution records (design mode or load test)
- metrics: Time-series metrics (RPS, latency percentiles, bytes, dropped, status codes, …)
- results: Individual request results (errors + sampled successes)
- oauth_tokens: Cached OAuth 2.0 access/refresh tokens (keyed by config identity)
- config_entries: Engine configuration registry (read/written via /config)
See Database Schema for the full column list.
Startup housekeeping (Database::init(), before the sweeper and HTTP server start):
- Reconciliation: runs still
running/pendingwere abandoned by a previous process (a crash or a kill - a graceful shutdown stops and joins every worker, so it writes a terminal status) - nothing else would ever move them off those statuses, soGET /runsreported them as running forever. They are markedfailed;end_timekeeps what the run recorded, or becomesstart_timewhen it recorded none (a run that died whilerunning, which a move torunningleaves at0), since when the process died is unknowable at restart and the restart time would span the downtime. A load run that stored no summary but wrote metric ticks is given one from its last tick in the same transaction, flaggedpartial(#2895), so its report shows the totals it reached rather than zeros (see Database Schema). - Pruning: run history is trimmed per kind - load and collection runs to
maxRunsRetained, design Sends tomaxDesignRunsRetained(#2429) - and every kind torunRetentionDays. Reconciliation runs first so an orphan is terminal, and therefore prunable, in the same startup. - Trash retention: collections, requests, environments, saved examples
and client certificates deleted more than
trashRetentionDaysago are destroyed for good (issue #988, environments #2970, examples #2971, client certificates #2973) - the subtree, its requests and their examples, or the environment's, example's or certificate's one row. Until then a delete is only a stamp, andPOST /trash/:id/restoreputs it back.
All three passes are best-effort: a failure is logged and never blocks startup.
Request Flow¶
Design Mode (Single Request)¶
1. POST /execute
↓
2. Build request: parse JSON + apply timeout + resolve auth (bearer/basic/
apikey/oauth2). Auth is resolved BEFORE the script so pm.request is accurate,
except a credential still holding an unanswered {{name}} (#2473), which
waits for step 4b
↓
3. Create Run record (type: Design)
↓
4. Execute pre-request script (if provided). Its pm.request edits - method, url,
headers, body, auth - are written back into the request, so they override the
auth resolved in step 2 (an assigned pm.request.auth takes that credential off)
↓
4b. Resolve the tokens compose left against the scopes the script wrote, then
apply any auth that waited (a header the request carries still wins, and a
script-assigned pm.request.auth means none is applied)
↓
5. Send HTTP request via libcurl, through the environment's cookie jar - stored
cookies go out, Set-Cookie comes back in (see Cookie Jar below)
↓
6. Execute test script (if provided)
↓
7. Save result to database
↓
8. Return response with test results
Scenario Mode (Collection Run)¶
A third runs.type, scenario: an ordered sequence rather than a single
request. POST /runs with a scenario block resolves the collection into an
immutable, fully composed plan before the run row exists, then answers
202 {runId} and runs it on a worker thread.
1. POST /runs (with a "scenario" block)
↓
2. Resolve the collection into an ordered ScenarioPlan - every step composed
through the POST /compose path, once, before anything is sent. Any failure
here is a 400 and leaves no run row behind
↓
3. Create Run record (type: Scenario). config_snapshot carries the step
manifest, never the composed plan (see db-schema.md)
↓
4. Start worker thread (execute_scenario_run). No event loop, no metrics thread
↓
5. Load the variable scopes once; build one script engine for the run
↓
6. Per iteration, per step: the design-mode exchange (pre-request script → send
through the environment cookie jar → test script), then a step result and a
`step` SSE event on the same retained tick topic a load run publishes into
↓
7. On completion: persist script-set variables once, batch-write the bounded
step results, write the scenario summary, reach a terminal status, retain
The plan is shared with the load path; the executor is not. Steps go through
http::Client, not the event loop, because design-mode fidelity needs the
cookie jar and inline per-step scripts and the event loop deliberately has
neither. Step 6 is literally the POST /execute handler's body - both call
execute_exchange (http/request_exchange.cpp) - so a step and a Send of the
same request cannot drift apart.
What the sequence carries between steps:
- Variables mutate in memory across every step and iteration, and are written back once, at run end, through the same diff-based persist a Send uses. Per-step persistence would be N x M diff-and-write cycles against the DB mutex for a value only this run's later steps read.
- Cookies are the environment's jar, unchanged - which is what makes "log in on step 1, reuse the session on step 2" free.
- Nothing else. There is no scenario-scoped variable bag: a fourth scope would need precedence rules, a persistence story and a UI, to hold what the environment scope already holds for the run's lifetime.
The plan is composed once, but its values are not always fixed then (issue
2521). resolve_scenario reads every step's composed elements before it¶
composes any step (plan_variable_deferral), and when one holds a kind the
registry marks writes_variables at a phase before some send - script.pre,
script.post, script.setup or any extract.*; not script.teardown, which
runs after the last send - every step is composed with
VariableDeferral::Always: each name a scope answers stays written in the plan,
scripted step or not, and is resolved immediately before that step's send
against the scopes as the earlier steps' scripts and extractors left them (the
sequential runner's execute_exchange, the load executor's per-VU residual
pass). So a login whose test script or extractor stores a token is followed by
a step whose Bearer {{token}} sends it. A plan with no such element resolves
its values at composition, as it always did. Fixing the structure once is what
keeps a collection edited mid-run from changing the sequence underneath itself,
and it is what makes the load-mode executor (a per-VU state machine) possible
without SQLite on its hot path.
Data rows bind per iteration. A scenario.data array - rows the app parsed
from a CSV, TSV, JSON or JSONL file, sent inline, because the sandbox has no
filesystem and the engine reads a user's file only under the request-body
trust rule (see Security) - binds row
i % rows to iteration i, read by the run's scripts as pm.iterationData.
The rows ride the ScenarioExecution the worker holds and are never
persisted: the snapshot keeps the row
count (dataRowCount) plus the file's name and content hash (dataFileName,
dataFileHash) and how it was read (dataFileCastNumbers, issue #2540), never
its path or rows, and every step's stored row and step event keeps
dataRowIndex, so which row a wrapped pass re-used stays answerable without
storing the row itself.
A step's outcome is passed, failed, skipped, errored or stopped, counted
separately everywhere - a skipped step counted as a pass is the false-pass class
this project has already spent an issue eliminating. An errored step ends its
iteration unless the only thing wrong was a script that threw after the exchange
completed (issue #2526): that step keeps its errored row and the iteration
walks on to the next plan position, as Postman's runner does, with the script's
own redirect ignored. A transport
failure and a data row that would not bind continue the same way. Only the
runner's own refusals (an unresolved or ambiguous target, the cycle cap) end
the iteration, and the run option stopOnError: true makes every errored
step end it. Either way the
next iteration still runs and the run still reaches completed; an iteration
an error ended reports what it cost as stepsNotRun. A stop ends the step in
flight and is otherwise honoured between steps: the step it cut short is
stopped (#3397), a fifth outcome in no failure tally, which ends the run
without counting stepsNotRun, reading flow control or closing a
transaction.
Flow control is design-mode only. A script returns an intent -
pm.execution.setNextRequest(name), setNextRequest(null),
skipRequest() - and the runner decides; the script never jumps. An unknown or
ambiguous target fails the step by name rather than guessing, and
maxStepsPerIteration bounds a cycle. pm.execution throws wherever there is
no live sequence to redirect - a single Send, and every load run, including a
scenario one, whose scripts are deferred and run against responses that already
came back.
Non-goals, so none of them arrives sideways¶
Recorded here rather than left to be re-derived: JMeter's while / interleave
controllers, and any nested sub-flow shape (control.if / .once /
.switch / .throughput / .loop, #1515, each name a condition or a jump
against the flat plan setNextRequest already walks - no controller owns a
child list of its own); k6's open-model and arrival-rate executors for
scenarios; distributed load; the engine reading data files from disk (the
sandbox has no filesystem, and a user-supplied path would be a new trust
boundary); parallel steps within an iteration (an iteration is ordered -
that is the whole primitive); a scenario-level test script asserting
across steps; and replacing run_collection_smoke (an unordered,
share-nothing, agent-facing matrix is a different tool and stays). As of
1495, a scenario load run's producer and completion hooks run every¶
declarative kind (extract.*, assert.*, timer.*) inline, per virtual
user, through a per-user scope overlay and the residual-token pass; a
script.* element stays deferred - replayed against the sampled responses
after the run drains, exactly as it did before elements existed - unless it
is marked inline or the run's elements.scripts override says so, in
which case it runs at completion time on a per-worker QuickJS engine (no
shared pool, no lock). Since #1594, a single-target POST /runs (no
scenario block) runs the same pipeline on its own request, per submission,
through requestElements - the mechanism is the same shape, a per-submission
ScopeOverlay standing in for the scenario path's per-VU one, since a single
target has no persistent virtual-user object to hold state on between
submissions. control.*, timer.pacing and timer.throughput stay a
scenario-only concern: validate_request_elements_run_override refuses them
outright (when enabled; a disabled entry is skipped by the pipeline) rather
than accepting a kind that would silently no-op or misfire - a lone request
has no sequence for a jump, skip or transaction to act on, and no per-VU or
shared pacing state for the kind to read.
Two things were deliberately left open: whether a stored scenario entity ever lands (the seam exists; the demand does not), and a retry policy for a step that errored. Continue-on-failure was the third until imported Postman collections supplied the demand (issue #2526): it now covers a script error only, because a step after a transport failure nearly always reads the response that never arrived.
Load Test Mode¶
1. POST /runs
↓
2. Parse config + pre-flight auth (oauth2 tokens acquired & cache warmed;
409 up front if interactive sign-in is required)
↓
3. Create Run record (type: Load)
↓
4. Create RunContext (the worker builds, starts and *publishes* the
EventLoop itself, inside execute_load_test)
↓
5. Start worker thread (execute_load_test); phase `setup`
↓
6. Start metrics thread (collect_metrics), and - for each refreshable oauth2
token the run sends - an auth-refresh watchdog (run_auth_refresh)
↓
7. script.setup runs, then phase `sending`: the strategy submits requests
via SPSC queue → event loop
↓
8. The strategy returns on its own (phase `draining`), or a Stop that
latched while sending ended it. A Stop that latched while sending
cancels at once (stop(false): backlog discarded, in-flight cancelled)
and the run will end `stopped`. Otherwise the loop drains to its
natural-end deadline (stop(true, deadline)); a Stop landing in this
drain cancels it through RunContext::request_stop, counts the
in-flight transfers as cancelled, and leaves the run's own end
(`completed`, or `failed` by failRun) standing
↓
9. Event loop has let go: phase `summarising`; summary and final
status written
↓
10. Metrics collector aggregates results in-memory; metrics thread
writes per-tick snapshots into the retained tick topic, and at
the 1 Hz gate one DB row holding that second's merged percentiles
(runs beside steps 7-9, from step 6 on)
↓
11. Client streams ticks via SSE (/runs/:runId/live), replayed
from the oldest retained tick then tailed to the `complete` event,
which waits until the run has written its terminal status
(RunContext::settled)
↓
12. On completion: batch-write results to DB; event loop, data rows
and plan released; run retained (TTL) so late clients still get
the full series; phase `settled` (RunManager::retain_run)
The phase lives only in memory (RunContext, core/run_phase.hpp): the database
keeps the RunStatus alone and the schema is unchanged. A sequential collection
run moves sending to summarising with no draining between, so a Stop on it
always decides the outcome. POST /runs/:runId/stop on an active load run
answers the stored status once the worker has written a terminal one, stopped
when the Stop decided the outcome, and running for a Stop that landed in the
drain before the worker wrote its own verdict.
The metrics thread's exit is gated on is_running, not on should_stop. A stop
request only asks the worker to stop; the worker then blocks in event_loop->stop
- cancelling for a Stop that latched while sending, draining to a deadline at the
natural end (a Stop in that drain cuts it short) - and
clears is_running afterwards. Exiting on should_stop emitted the final tick
and set closed while requests were still settling, so the live view froze at
the stop click while the stored report - written after the worker returned -
counted everything that landed in between.
The metrics thread also starts before the worker has built the event loop, so
the loop's pointer crosses threads: the worker constructs and starts it, then
hands it over through RunContext::publish_event_loop, and the metrics thread
reads it only through active_transfer_count() - a null check plus the
active_count() call inside the same small mutex, answering zero before
publication. The lock is what orders the reader against the constructor's
writes; a bare null check tests a value and orders nothing (#956). The strategy
thread and the event-loop workers deliberately read the pointer without that
lock - their reads are ordered by program order on the publishing thread and by
the submit queue's hand-off, and a lock there would sit on the hot submission
path.
Auth outlives its token. A run resolves auth once, before the strategy
starts, so a run longer than its OAuth 2.0 access token used to turn into a 401
storm the report never explained. The watchdog closes that: it sleeps until
oauth2RefreshLeadMs (default 60s) before the token expires, re-acquires it with
a forced refresh, and publishes the new Authorization value on its
AuthRefreshState. Its five oauth2Refresh* settings are read once, when the
run arms its watchdogs (read_auth_refresh_tuning), so a run's schedule cannot
change under it half way through. The submitting thread - the strategy, which
is the event loop's sole producer - puts it on the request it submits, and
EventLoop::submit copies that request wholesale into each transfer. So the
swap needs no lock on the submission path and cannot race a transfer already
queued. A single-request run keeps one Request and rewrites its header when
the cell's generation moves (sync_auth_header). A collection load run
(#3199) copies each step's request fresh from the plan, so
ScenarioLoadDriver::submit_one writes the current value onto every
submission of an armed step, before its bind and its step.before elements
(AuthHeaderCache, which takes the cell's lock only when the generation
moves). Its steps are armed by plan_scenario_auth_refresh: one
AuthRefreshState and one watchdog per distinct token-cache key, never two on
one cache row (each forced refresh would spend a rotating refresh token), each
refresh bounded by the shortest timeout among the steps sharing it, and a step
armed only where the plan placed the token on Authorization itself
(ScenarioStep::oauth2_config, Request::auth_header). The report's auth
section folds every credential into the one shape (AuthRefreshState::summarize).
Runs and steps it deliberately leaves alone (query-placed tokens,
autoRefreshToken: false, authorization_code with no refresh token,
non-expiring tokens, a user-supplied Authorization (no token is fetched for it
at all, #3202), a step whose auth waited
on its scripts) behave exactly as they did before it existed - see
plan_oauth2_refresh. A refresh that fails is retried with a backoff and
recorded in the report's auth section; it never fails the run.
The tick topic itself is a bounded ring. Run duration is user-controlled with no
upper bound, so an append-only buffer is a slow OOM on an overnight soak. The
bound is expressed as a duration - liveReplayWindowMs (default 5 min, 0
= full run) - and live_ring_size() converts it to a tick count against the
run's cadence, liveTickIntervalMs, clamping to liveMaxRetainedTicks
(default 50,000, matching the renderer's own ceiling - it reads the same key). That same entry is the
app's live-chart window - the dashboard's picker reads and writes it through
/config - so the retained span and the displayed span are one number, not two
that have to be kept aligned. A fixed count would be the wrong unit:
the cadence spans 10–1000ms, so 3000 ticks is 30 seconds at one end and 50
minutes at the other, and the dashboard's live-window setting the ring has to
serve is itself a duration. collect_metrics reads the pair once, before tick
0; a mid-run change would leave ids the dashboard already holds pointing into a
differently-sized window. published_count keeps counting past an eviction, so
SSE event ids stay monotonic and a Last-Event-ID resume from before the window
is fast-forwarded to the oldest retained tick rather than replaying from 0.
Load Test Strategies¶
Five load test modes are supported (LoadTestType in types.hpp). Four are closed-loop -
the engine holds in-flight requests at a target and issues a new request as each completes, so
throughput is a result (concurrency ÷ latency), not an input. One is open-loop.
The mode chooses the loop, never the rate (#2396). rps / targetRps is constant_rps's field
alone: POST /runs refuses a positive one on any other mode, and open_loop_rate
(load_strategy.hpp) answers 0 for every other mode, so a rate in a stored config does not open
constant_concurrency's loop. The event-loop workers hold no token bucket (#2801, #2911). A body
with no mode is constant_rps, the way LoadStrategy::create reads it.
1. constant_rps (open-loop)¶
Dispatches at a fixed targetRps regardless of how fast responses return. maxInFlight caps how
many requests may be outstanding before new ones are dropped (and counted as dropped_requests).
The pacing thread is the run's only limiter (#2801). A stalled pacer's next tick sends what the
schedule owed up to MAX_CATCH_UP_BACKLOG (100 ms) past the instant the tick was due and skips the
rest (#2911): split_tick_backlog (core/load_pacing.hpp) makes the split, and the skips are
counted apart from the drops (MetricsCollector::record_skipped_batch, with the schedule time they
cover). What is sent still passes the maxInFlight headroom. sent + skipped + dropped is exactly
requests_owed_by (targetRps, duration) for a run that reaches its deadline.
2. constant_concurrency (closed-loop)¶
Holds a constant number of in-flight requests for the duration via the shared
maintain_concurrency controller.
3. ramp_up (closed-loop)¶
Interpolates the concurrency target from startConcurrency to concurrency over
rampUpDuration, then holds for the remainder of duration (which is total test time).
{ "mode": "ramp_up", "startConcurrency": 1, "concurrency": 100,
"rampUpDuration": "10s", "duration": "60s" }
4. iterations (closed-loop, bounded)¶
Issues a fixed total number of requests at the target concurrency, then stops - exact count at run end.
5. capacity (closed-loop, adaptive)¶
Steps the concurrency target up while latency and errors hold, and stops itself at the knee. It answers "what can this service sustain" without a human bisecting concurrency by hand.
{ "mode": "capacity", "startConcurrency": 1, "concurrency": 512,
"sloMs": 200, "stepDuration": "5s", "duration": "5m" }
Each level is held for stepDuration, then judged on its p99 - the percentile of
every completion sampled after its settle ticks, from one histogram, never a mean
of 100 ms window percentiles (#2388) - and its mean throughput over the same
ticks, and on its error share: the requests it completed over those ticks that
were errors, counted from the same status distribution the live frame reports
(#2815). A level breaches when its p99 is over sloMs or its error share is over
constants::capacity::ERROR_RATE_PCT (1%). Healthy levels step up 25% (at least
+1); a single breaching window holds the level and re-measures rather than
ending the search. The stop reasons are slo_exceeded (two consecutive
breaching windows, the last over sloMs), errors_exceeded (the same, the last
inside sloMs and over the error limit), plateau (two step-ups bought under 5%
more throughput), cap_reached, deadline and stopped, and the report's
capacity section names which fired. A plateau stop also reports
saturation*, the lowest healthy level within 5% of the best healthy
throughput: maxHealthy* is the last level tried, which overshoots it.
Bounded streams under load¶
A load run may consume text/event-stream responses (POST /runs with
"stream": true, issue #576; a collection load run, for each step whose stored
request has stream set, issue #3235), and the design principle is one line:
under load, every SSE stream is bounded by construction.
That follows from the refill loop below rather than from taste. The loop is
completion-driven - in_flight = requests_sent − completed, refilled per
completion - so a transfer that never completes does not merely skew a number:
it leaks its concurrency slot for the rest of the run, and a run of N endless
streams stops sending anything at all once N reaches the target. So a
streaming request carries Request::stream_bounds, and both caps are always
set - the payload's, or the sseMaxStreamDurationMs / sseMaxStreamEvents
settings - with no zero-means-unbounded spelling for either. A collection run's
plan gives the bounds to each streaming step, reading the flag off the stored
row (vayu::Request has no mirror of it), so both executors receive the step
already bounded:
the event loop under load, and the single-request Client for a sequential run,
which ends the stream by the same two caps.
The two caps are enforced in the two places that can see them:
- Events in the curl write callback, by
SseFrameCounter(http/sse_frame_counter.hpp) - a few-byte state machine that counts frames without assembling one. It agrees withSseParserabout what an event is (a frame carrying nodatafield is not one), so a load run and a design run report the same count for the same stream;sse_frame_counter_test.cppdrives both over one table and asserts they match. The same callback stamps the write that completes the first event (issue #3234), measured fromsubmitted_atlike the latency, and the completion copies it toResponse::stream_first_event_ms. It is the report'sstream.timeToFirstEvent, and it cannot be read off libcurl: the start-transfer time ends at the response headers, which a gateway that answers200and then thinks sends long before its first event. Both caps, the stamp and what the ended stream reports live in oneStreamTally(http/stream_tally.hpp), which the event loop'sTransferDataandClienteach keep one of (#3235). - Duration in the progress callback, which libcurl runs at least once a second whether or not bytes arrive - which is the only place a stream that has gone quiet can be ended. The whole-transfer timeout is moved to a grace period past the duration cap, so it backstops the callback rather than racing it.
Either cap ends the transfer through libcurl's documented abort, and the
completion path turns that back into a success carrying the response's real
status code. That is the point of the cap - it is the stream's intended end -
and it is what keeps handle_result-exactly-once and the refill loop untouched.
maxResponseBodyBytes is unchanged and still an error: it is a refusal to
buffer, not an ending, and the event cap bounds how many events arrive rather
than how large one is.
The live frames count events as they arrive (issue #3236), because a run of
two-minute streams completes nothing for two minutes and every
completion-driven figure on the dashboard reads zero until then. The write
callback adds what each chunk completed to a run-wide atomic, and the
completion adds the unterminated last frame SseFrameCounter::finish counts
(StreamTally::feed / report, the only two places the counter is fed). The
http layer knows nothing of the collector: the counters (LiveStreamCounts,
an event tally and an open-stream gauge) are owned by the run's
MetricsCollector, allocated only for a load run that streams with
stream_metrics on, and reach each streaming transfer as StreamBounds::live,
so a non-streaming transfer never sees them and a streaming one pays a null
check and one relaxed fetch_add per chunk that completed an event. A load run
streams when it is a POST /runs run with stream, whose every transfer
carries the counters from RunContext::stream_bounds, or a collection run
whose plan has a streaming step (issue #3304, longest_stream_bounds non-empty,
read by the RunContext constructor from the plan it is built with), whose
streaming steps are handed them per submission in
ScenarioLoadDriver::submit_one while its ordinary steps never are. The tally
is kept apart from the completion counters behind the report's stream
section, which record_stream_completion feeds, so nothing is counted twice;
once the run settles the two agree, except that a stream a Stop cancelled
delivered events the live total counts and the report does not.
get_current_stats reads the tally as streamEvents and the gauge as
streamsOpen: StreamTally::start raises the gauge and report lowers it
before the completion is handed on, or the tally's destructor does for a
transfer that is cancelled or discarded unreported, so it counts streaming
transfers alone (never activeConnections, which on a mixed collection also
counts the ordinary steps) and reads 0 once the run settles. The trailing
window turns the tally into eventsPerSecond beside currentRps; and a gate
frame adds streamTimeToFirstEvent from the completed streams' histogram, read
through a snapshot as cumulativePhases is. All four are live only, never
stored. A design collection run has no metrics thread and no live frames, so
its streaming steps are counted only in its report.
POST /execute is deliberately not affected. With stream it is still
SseStreamManager's one-thread-per-stream model with no whole-transfer
deadline; only the flag's spelling is shared, through read_stream_flag. A
sequential collection run's streaming step is the other design-side sender
(#3235): Client::send honours stream_bounds with the load path's rules
(whole-transfer timeout the cap plus the grace, a cap ending it as a success),
the runner passes it RunContext::should_stop as its cancel, as it does for
every step (#3397), so a stop ends the stream once answered, its step trace gains the events node parsed back from
the body (buffered_stream_events_node), and its completion feeds the run's
MetricsCollector, whose stream_totals the sequential summary stores through
the same build_stream_summary_payload a load run's uses.
Closed-loop controller¶
constant_concurrency, ramp_up, iterations and capacity share a maintain_concurrency
loop driven by a pure compute_refill_deficit primitive: each tick, refill exactly
target − in_flight new requests (where in_flight = requests_sent − (completed + cancelled)). On stop the
controller is notified for prompt cancellation rather than waiting for in-flight requests to drain.
Between ticks the loop blocks on refill_cv with a 50ms safety-net timeout, woken early by a
completion (notify_refill) - the actual wait, not a poll, so a run with headroom to fill sends
again within the tick rather than a full 50ms later.
The target is read only when the loop wakes, so a run can end with no wake in its last tick. A
caller whose run ends on the clock (both ramp_up callers) passes that end as run_end_ms, and a
loop the clock ended refills once more toward the target at run_end_ms - 1; a stop, or a loop
that left on its own predicate first, sends nothing after it. That last refill is why a ramp as
long as the run reaches concurrency (#2913).
A scenario run's virtual users add a second reason in_flight can sit below target: a VU a
timer.pacing or timer.think element deferred (issue #1498) is not in flight either, so the
plain target − in_flight predicate above cannot tell "wait for a completion" and "wait for this
VU's deferral to end" apart - both look identical. Left alone that reads as permanent headroom and
the loop spins the 50ms wait away on every tick, pinning a full core for a run whose own request
rate is a handful a second (issue #1596). ScenarioLoadDriver::deferred_wait_ms answers which case
it is: when the last scan found only deferred VUs (as opposed to none ready because everyone is
already in flight or retired, which the plain predicate already handles), the wait is bounded to
the soonest deferral instead, on a predicate that only a real completion or should_stop satisfies.
A step a controller skips (control.if, control.once, control.throughput) is the third: it
puts nothing in flight either. ScenarioLoadDriver::submit_one walks a claimed VU on past a
skipped step to its next send, so a skipped login in front of the request that does go out costs
no wait, and stops after one whole iteration with nothing sent. A refill pass that was owed work
and left requests_sent unchanged then takes the same bounded wait, one 50ms tick or until a
completion or should_stop (#3540): a plan whose every step is skipped iterates about once per
VU per tick rather than pinning a core.
The target_fn invariant, restated. Every mode but capacity passes a
target_fn that is a pure function of elapsed_ms and constants fixed when the
run started - which is what makes a ramp reproducible and a constant run flat.
capacity is the deliberate exception: its target is a function of what the run
has measured, so the invariant is now "the target depends only on elapsed time
and the published metric tick", and nothing else.
That feedback path has exactly one shape, and it matters which. The strategy
must not call MetricsCollector::sample_window_percentiles(): that call is
single-reader and resets the rolling window on read, and the metrics thread
already consumes it once per tick in emit_live_tick. A second consumer would
silently halve both readers' sample counts, and neither the live chart nor the
search would look wrong; the stored rows, which take_second_percentiles()
merges from the same windows, would lose the same share. So the metrics thread publishes what it already
computed - RunContext::publish_live_tick(), one writer - and the strategy
copies it out through latest_live_tick(). A guard in
capacity_controller_test.cpp pins the single production caller of those
calls and of the level histogram's two, because the wrong version still runs;
it just measures less.
What the tick carries for the search is the level: every window the metrics
thread has sampled since the search last asked for a fresh level histogram
(#2388). The asking crosses threads, so it is an epoch rather than a call: on
the level's last settle tick (SETTLE_TICKS) the search bumps
RunContext::request_level_reset(), the metrics thread compares
requested_level_epoch() with the one it holds before sampling each window and
resets the histogram on a change, and every tick publishes the epoch it applied
beside the level's p99, sample count and the completions and failures counted
since the same epoch change (#2815). The search reads only ticks carrying
the epoch it asked for: one produced in between still holds the settle ticks.
Requesting on the last settle tick rather than when the level opens is what
keeps the transition out without the metrics thread knowing SETTLE_TICKS.
A level whose histogram holds no sample and that counted no failure is not
judged and stays open: an empty histogram's percentiles are zeros, and reading
those as "answered instantly" would climb straight past the limit the search
exists to find. A counted failure is judged even with no latency behind it (a
refused connection records none). A level that has samples but has counted no
completion is not judged either (#2815): the status snapshot the counts are
taken from can lag the histogram by a tick, and a share of nothing reads as 0%
errors, which would step a level failing every request up. The controller's
policy itself lives in
core/capacity_controller.hpp as pure functions over a level history - no clock,
no collector, no run context - so it is unit-tested without a server.
The path also runs the other way, for display only (#2928). The search publishes
where it stands through RunContext::publish_capacity_progress(): the level
being measured, the steady-clock instant it opened, how many levels are judged
and, once the search has ended, the stop reason. The metrics thread reads it on
every tick into the live frame's capacity block, computing the time in level
against its own tick clock; the search's own elapsed_ms runs from
maintain_concurrency's start, an origin the metrics thread does not have. The
four are one struct under one mutex rather than an atomic each, so a frame
cannot pair a new level with the previous one's start or judged count. It is
written when a level opens and in CapacitySearch::finish, which, when the
search named no reason of its own, resolves the end to stopped only if a Stop
decided the outcome (stop_decides_outcome: the operator stopped before the
search ended) and to deadline otherwise, before the worker clears
is_running, so the final frame names the reason the report does. Nothing in the search reads it back, so the
invariant above still holds.
Scenario load runs - the virtual-user state machine¶
A POST /runs payload carrying both a scenario block and a load mode runs
that collection as a load test (core/scenario_load.cpp). The plan is the same
object the design-mode sequential runner consumes - resolved once, before the run
row exists - and the executor is the only thing that differs.
concurrencyis the number of virtual users, which is what k6 and JMeter mean by it. A VU is a small value, not a thread: a cursor into the shared plan, its own cookies, and (since #1495) a smallScopeOverlayof the names it has written - about 200 bytes per written variable, so 1,000 VUs cost kilobytes, never the size of the run's whole scope. On each completion the callback advances that VU's state machine, andmaintain_concurrency's refill issues "the next step of VU k" in place of "another copy of the one request". The controller, the SPSC submission path and the single-producer discipline are unchanged.- Cookie state is per-VU, never the shared jar - see the Cookie Jar section's
"Not on the load path" bullet, which this strengthens rather than contradicts.
Each VU's list is seeded onto its own transfer and read back from it
(
Request::track_cookies), and emptied at every iteration boundary: a new iteration is a new user, not the same one logging in twice. The variables a VU saved are not (#3044): itsScopeOverlaykeeps every environment, collection and globals write for the VU's life, so acontrol.oncelogin's token reaches each later iteration, and only the run-local scope is emptied beside the cookies. An extractor's miss unsets a name there just as long, as a tombstone that hides the run's stored value of it from that VU alone (#3053). - Closed-loop only.
constant_rpswith ascenariois a400, as is a non-zerorps/targetRpson any mode - an open-loop arrival rate over a multi-step sequence is an arrival-rate executor, a named non-goal. The single-request path refuses a rate on every mode butconstant_rpsfor the same reason (see Load Test Strategies).maxInFlightis moot: in-flight is bounded by the VU count by construction, so setting it logs a warning and does nothing. - A step that got no response ends its iteration, and the VU starts the
next one. A VU stranded on a failing step would permanently shrink effective
concurrency for the rest of the run. This path does not read
stopOnError: the key is the sequential runner's, and here a missing response ends an iteration - a script error, inline or deferred, never has. An inline script that threw still makes its steperrored, as on a collection run (#2947), without ending the iteration, so the summary'serroredis not the sum of the steps'noResponse. Flow control follows the collection run's rules (#2974):finish_stepdrops thecontrol.switch/control.loopjump of a step that errored, so the iteration walks on, and a jump it cannot honour (an unresolved target, themaxStepsPerIterationcap) ends the iteration as abandoned with the steperrored, its error text in the log. A step that answered with an HTTP error status is counted in that step'serrors(ashttpErrors, #2134) and the iteration carries on: a response arrived, so the next step has something to follow. - Per-step latency histograms, one per plan step, allocated once from the
plan's step count - which is what
maxScenarioStepsbounds. They reach the report assummary.scenario.steps; a scenario load run stores no per-stepresultsrows, so that breakdown is the only per-step record it keeps. A step takes a duration on the run histogram's terms: an answered step and a failed step whose transfer ran (a timeout) both record one, a step that never reached the wire records none, so a step's p99 and the run's agree. - Data rows bind per iteration, from one shared cursor. A run sent with
scenario.dataclaims a row per virtual-user iteration off a single run-wide cursor, wrapping when the rows run out, and every step of that iteration binds the same row - a checkout that used a different row than its login is not a user. Shared rather than per-VU is what makes distinct credentials per user work: two VUs must not both be handed row 0. It is k6'siterationInTest/ JMeter's "All threads" parity, and it costs one increment per iteration on the producer thread, which is the only thread that claims. Each step's{{data.column}}tokens are split once, at plan resolution (ScenarioStep::data_template) and only joined per row afterwards, so a plan carrying no data tokens does no per-iteration work at all. A token naming a column its bound row does not carry fails that step loudly - nothing is sent, the step'serrorscount moves, and the run's error list carries the sentence naming the token, the row and the row's columns (DATA_BINDING_FAILED). Every retained result carries itsdataRowIndex, which is what makes a failure attributable to a row when no per-stepresultsrows exist. - A single-request load run binds rows too (issue #993). Its rows ride the
payload's top-level
datarather than a scenario block, and one is claimed per submission off the same kind of run-wide cursor, wrapping the same way - a single request has no sequence for an iteration to span, so the unit of a claim is the request. The templates are split once, when the run's one request is built (RunContext::load_template), the credentials defer exactly as a step's do, and every retained result carries itsdataRowIndex. The credential half is split ontoRunContext::load_authrather than onto the row set (issue #1055), for the reason the request's template is: a credential carrying{{$vu}}defers on a run that has no rows, so a set that exists only where rows do is the wrong place to keep it. A run without rows carries no set at all, which is the throughput guard stated structurally: the strategies test one pointer and two empty templates, and otherwise submit the shared request they always did. The validation, the binder and the escaping are the scenario path's own functions rather than copies -read_data_rowsandbind_iteration. - The iteration's identity binds beside its row (issue #994).
{{$vu}}and{{$iteration}}are a second reserved namespace, and they are bound at the same point, out of the same template: a field carrying one of each is one string, so the split keeps both and the join resolves each where its value lives - the identity from the iteration, everything else from the row. On the scenario path the values are the virtual user's own number (1-based) and its iteration; on the single-request path they are1and the submission index, which is the same counter the row cursor claims from, so the two cannot disagree about which submission this was. A design-mode collection run is user 1 walking its passes, and a single send is a run of one. This is template substitution, not a script hook: two integers written into fields a compose-time scan already located, which is why it sits here rather than in the element-pipeline bullet below (issue #1495). A request that spells neither token has an empty template and is walked for nothing - the executor testsempty()and submits the shared request it always did. What every run does now pay is one unsynchronised increment per submission on the producer thread, which is what lets any load run tell a deferred script the iteration and the user a sampled response was sent as (pm.info.iteration/pm.info.vu). - The element pipeline runs here too, per VU (issue #1495).
submit_onerunsstep.beforebefore binding and submitting; the completion runsstep.afteronce the response is in hand, before the VU is released.extract.*/assert.*always run; ascript.pre/script.postruns here only when its ownconfig.inlineis set or the run'selements.scriptsoverride forces it - unmarked, a step's scripts still defer exactly as before this issue. Each VU writes through its ownScopeOverlay(a handful of names, never the run's shared scopes two VUs could race on), materialized against the base scopes only when an inline script actually needs the mutable viewpm.environment.setwrites through; the residual-token pass reads a cheap flattened-map-plus-overlay merge instead, which is what makes correlation (step 1'sextract.jsonreaching step 2's{{token}}, for that VU alone) work under load.pm.executionstill throws in a load run for the reason the flow-control section gives: an inline element can write state and mutate the request, never redirect the sequence. Seeelements.mdfor the full mechanics, including what is deliberately still unwired (elements.timers, the single-request path below). - Un-inlined scripts stay deferred, keyed per step. After the run drains,
each step's own
post_scriptelement - the ones that did not run inline this run - is replayed against the responses that step produced, and the tallies land on that step's entry in the breakdown (scenario.steps[].tests, beside the newscenario.steps[].elementsper-element tally). Sampling is per step index for the same reason - one flat run-wide reservoir lets the hot first step swamp the budget and never samples the last step of a long plan. The run'smax_response_samplesbudget is split evenly across the steps that carry a deferred script (not across every step), floored at one apiece; a step with no deferred script is never sampled and never counted as a thinned sample. The byte budget beside it (max_response_sample_bytes) is deliberately not split: those bodies are resident in one process, so a forty-step plan must not multiply the ceiling by forty, and a step that drops a sample over it is counted like any other thinned one. - The run's
runs.typeisload, notscenario: it publishes metric ticks and reports RPS and percentiles like any load run, andscenariois what the app reads to render a step list instead of the dashboard.
{ "mode": "constant_concurrency", "concurrency": 50, "duration": "60s",
"scenario": { "source": "collection", "collectionId": "col_1" } }
Thread Model¶
- Main Thread: HTTP server, request routing
- Worker Threads: One per active load test (executes load strategy)
- Metrics Thread: One per active load test (aggregates and streams metrics)
- Monitor Thread: One per load test that declared a
monitorblock - it scrapes the target's metrics endpoint on its own interval. Separate from the metrics thread because that one is a fixed-cadence sampler with no deadline compensation: a blocking HTTP call inside it would delay every subsequent tick by the scrape's latency, and a hanging endpoint would end live metrics for the whole run. -
Event Loop Threads: One per CPU core (handles curl_multi I/O)
-
Stream Consumer Threads: One per live streaming request (
POST /executewith"stream": true), owned bySseStreamManager.
Shutdown unwinds that in a fixed order, because every one of these threads
holds references to state main owns: HTTP server stopped and its stream
consumers drained (Server::stop() sets the flag every handler reads as
RouteContext::server_stopping, which cancels each outbound transfer a
handler is making - the /execute send and its pm.sendRequests, an OAuth
token request, an import fetch, a connection test - and ends each SSE relay
(/runs/:id/live, /runs/:id/events, /inbox/:id/live, /changes); it shuts the OAuth
authorization manager down, which cancels an embedded completion's token
exchange, made on a management handler, through its attempt (#3347); it then
closes the listener and joins its accept loop's thread, which returns only
once httplib has joined every handler, so each request in flight has answered
first, also when the loop had already ended on its own, which is what the
daemon's wait reads as a reason to shut down (#2667); then it calls
shutdown() on the other three listener managers - mock servers, inboxes,
mock issuers - each of which, like the OAuth one, signals every entry, ending
a paced answer's wait and cancelling a callback's token exchange, before
joining any (#3345); then
SseStreamManager::shutdown(), which signals every stream and joins its
worker) → run workers signalled and joined (each stops its event loop first,
then joins its metrics, monitor and auth-refresh threads, cancelling a scrape
or a token refresh still in flight, #3343) → the start-of-session
recovery backup refresh interrupted and joined → the recovery backup refreshed
once more, bounded by a deadline
(Database::refresh_recovery_backup_on_shutdown, #2421) → curl_global_cleanup
→ Database / RunManager destroyed at scope exit → the instance lock
released. No thread is detached (#2683): a cancelled transfer ends at its
next libcurl progress tick, about a second, and reports Cancelled.
The stream drain and the listener shutdowns belong to stop() rather than to
~Server because curl_global_cleanup runs between the two: a consumer
joined only by the member destructor would still be inside a curl transfer
while curl's global state was torn down, and still writing its run row through
a Database that is about to be destroyed - the #125 defect in the one worker
RunManager does not own (#646). An OAuth callback is in the same position
during its token exchange, and every listener's handler writes through the
Database (#3345). The three that can run after the management API's own
handlers are joined do, so no route is left to start or stop a listener under
them; the OAuth manager's shutdown is terminal, so a route that still reaches
it is only refused. Any other
owner of an SseStreamManager or a listener manager owes the same order: shut
it down before the Database and CookieJar its threads reach through go
away.
Performance Characteristics¶
- Throughput: 60,000+ requests per second (on capable hardware)
- Latency: P99 < 50ms overhead
- Memory: Pre-allocated buffers minimize allocations during tests. A
design send whose body is past 4 MiB (
MAX_PARSED_RESPONSE_BODY_BYTES) answers without the parsedbody(#2544). Two glibc settings keep what a large send allocated from staying resident for the session in the HTTP worker thread's arena: the daemon fixes the mmap threshold at 4 MiB at start (platform::return_large_frees_to_os,OWN_MAPPING_MIN_BYTES), so a block that large is unmapped when freed, and a buffered design send whose body was past 1 MiB callsmalloc_trimonce it has answered (platform::release_free_heap,RELEASE_HEAP_AFTER_BODY_BYTES), which returns the pages a parsed body's freed nodes hold. The load path does neither per request. - Database: Batch writes avoid contention during high-RPS tests
Configuration¶
Default configuration values (from constants.hpp):
| Setting | Default | Description |
|---|---|---|
| Port | 9876 | HTTP server port |
| Max Concurrent | 1000 | Per worker event loop |
| Max Per Host | 200 | Connections per hostname, per worker; a load run raises it to cover its virtual users |
| Poll Timeout | 10ms | Event loop poll interval |
| DNS Cache | 300s | DNS cache timeout (curl's cache and the pre-resolution pin cache) |
| Max Response Body | 32MB | Per load-test transfer; larger fails the request |
| Script Memory | 64MB | Per QuickJS runtime, held by the engine's script heap (scriptMemoryLimit, 1 MiB to 256 MiB) |
| Script Timeout | 5s | Script execution timeout (1ms to 60s; there is no "no limit") |
| Script Stack | 256KB | QuickJS stack size (64KB to 256KB, lowered only) |
| Stats Interval | 100ms | Metrics collection interval |
Data Directory Structure¶
data/
├── db/
│ ├── vayu.db # SQLite database
│ ├── vayu.db.bak # Re-snapshotted once listening and at a clean shutdown - crash recovery, not a user backup
│ ├── ca-bundle.pem # The merged CA bundle written when custom certificates are configured
│ └── backups/
│ ├── vayu-<stamp>.db # On-demand snapshots (UTC, %Y%m%d-%H%M%S-mmm)
│ └── vayu-<stamp>-pre-v<N>.db # Saved before an update migrated the workspace from schema N
├── logs/
│ ├── engine_<stamp>.log # One file per daemon start (UTC timestamps inside, %Y%m%d_%H%M%S in the name)
│ ├── engine_<stamp>.log.1 # The rotated half of a file that reached the size cap
│ └── cli_<stamp>.log # vayu-cli writes here too, under its own data directory
└── vayu.lock # The running engine's PID; the single-instance guard is on data/ itself (POSIX)
On Linux and macOS the daemon runs vayu::platform::prepare_data_directory
(platform.hpp) before the logger or the database open (#1781, #1802):
umask 077 for the whole process, then data/ (whatever --data-dir names),
logs/ and db/ made or tightened to 0700, then a pass that sets 0600 on
every file wider than that among vayu.lock and the regular files directly in
db/, db/backups/ and logs/, and 0700 on db/backups/. The pass is an
allowlist, not a walk of the data directory, so a --data-dir that also holds
other files leaves them as they were; symlinks and anything not a regular file
are skipped, and a path it cannot change is skipped rather than refusing to
start. On Windows the directories get a protected DACL that files created
afterwards inherit, and there is no pass over existing files.
tests/platform_test.cpp covers the pass and scans daemon.cpp for the call.
Workspace backups¶
vayu.db holds what a person has built - collections, requests, environments,
stored credentials and run history - and until issue #987 there was no copy of
it the user controlled. The .bak beside it is not one: it is rewritten
once the engine listens and again at a clean shutdown, so it exists to give a
corrupt file something to restore from, not to let anyone go back to last week.
POST /workspace/backup (or vayu-cli backup) writes one snapshot into
db/backups/. It runs SQLite's VACUUM INTO, which is why it is safe while
the engine is working: copying vayu.db by hand is not, because the -wal
beside it holds committed transactions the main file does not, so the copy is a
database missing its most recent writes. VACUUM INTO reads one consistent
snapshot and writes a defragmented database that is complete on its own. That
is the whole of what a backup holds: the database, and nothing the app keeps
for itself (below).
Names are UTC and fixed-width so they sort chronologically as text. After each
backup the newest maxBackupsRetained snapshots are kept (default 5, 0 =
unlimited) and older ones removed - only files matching vayu-<stamp>.db or
vayu-<stamp>-<label>.db, so a copy you put in that directory yourself is
left alone. A second backup requested while one is running is refused with
409 rather than queued.
The engine writes into the same directory on its own, under the same count:
vayu-<stamp>-pre-v<N>.db before an update migrates the workspace from schema
version N, and vayu-<stamp>-pre-repair.db before a one-time repair pass
rewrites stored rows (db-schema.md).
A start that cannot write the first refuses to migrate rather than migrate
without it.
Restoring¶
There is deliberately no restore endpoint: a running engine overwriting the database file it holds open is the failure this feature exists to spare you. Restore by hand, with the engine stopped.
- Quit Vayu (or stop
vayu-engine). - Copy the snapshot over
db/vayu.db. - Delete
db/vayu.db-walanddb/vayu.db-shmif they are present - they belong to the database you just replaced, and leaving them behind reapplies its writes on top of the snapshot. - Start Vayu again.
The tabs and other state the app keeps for itself are not in the snapshot.
An in-place restore on the same machine leaves them as they were, and they may
name rows the snapshot lacks. On a new machine, or after a profile reset, they
start empty (below). The collections, requests
and environments are all there, and so is each collection's spec-file and
data-file binding (issue #2765): the Spec and Data tabs show the bound paths as
they were written. A path names a file on the machine that picked it, so after
a restore elsewhere the file is usually absent - the tab shows the path struck
through, with the reason, once it fails to read. The binding is not itself
permission to read a file: the app opens a path only under a file grant
(file_grants, which the snapshot carries too), so a restored binding opens
only a file that was picked at that same path, and any other asks to be picked
again.
Going back to an older Vayu. An older engine refuses a workspace a newer
one migrated. The vayu-<stamp>-pre-v<N>.db the update saved is the workspace
as schema version N held it: install the older release, then restore that
snapshot with the steps above. Anything written since the update is not in it.
Putting a quarantined file back. A start that judged vayu.db corrupt
moved it to vayu.db.corrupt-<ms> before restoring vayu.db.bak or starting
fresh (db-schema.md). The .bak holds
the last clean shutdown at best, and less after a session that ended in a crash
or one whose final refresh ran out of time, so when the quarantined file was
healthy after all, it is the newer copy: with the engine stopped, copy vayu.db.corrupt-<ms> over
db/vayu.db, and its -wal and -shm, when the set has them, over
db/vayu.db-wal and db/vayu.db-shm (deleting those two if the set has none).
Unlike a snapshot, the set's sidecars are part of it: its -wal holds the
writes the main file had not taken yet. Anything written since the recovery is
replaced along with the database it was written to, and only the newest two
sets are kept, so a later recovery can prune this one. Since #2420 a database
that was merely locked or on a full disk is refused rather than quarantined, so
this is for a file the engine genuinely could not read, or one an older engine
quarantined.
What a backup does not hold¶
The snapshot is vayu.db. The app keeps some state outside it, in two places
the engine never sees, and a restore does not write either:
- The renderer's
localStorage(keys inapp/src/constants/storage-keys.ts): open tabs (vayu.tabs), the active environment and collection (vayu.session), shell layout (vayu.layout), the last load-test configuration (vayu:lastLoadTestConfig), which inboxes may notify (vayu.inbox-notify), client settings (vayu.client-settings), the host-sleep intervals recorded under a run (vayu.host-sleeps), the recovery notice already seen (vayu.recovery-notice) and the appearance preferences (vayu-theme-source,vayu-color-scheme,vayu-match-system-accent,vayu-system-accentand the othervayu-ui-*keys). - Three JSON files under the Electron
userDatafolder (app/electron/json-store.ts):window-state.json(window size and position),response-cache-clear.json(the version that last cleared the response cache) andmcp-config.json(the MCP allowlist, caps and on/off switch). A file that does not parse reads as empty, and the first write over it moves it to<name>.json.corrupt-<epoch-ms>beside it (one copy per file, as the engine does forvayu.db).
What that costs depends on where the snapshot is restored. On the same machine
the app state is untouched: it keeps whatever it held, and a tab may point at a
collection the snapshot does not have. On a new machine, after a profile reset
or after an uninstall with --purge, the app state is gone: saved load-test
values, notification opt-ins and open tabs are empty, and the MCP allowlist and
caps start at their locked-down defaults, the safe direction. A spec document's
text, a collection's binding to it and the location of each collection's
picked spec file and data file (collections.spec_file / data_file, issue
2765) are in the database and survive, so the Spec and Data tabs name the same¶
files as before; a file that is not at its path on this machine reads as unresolved until it is picked again.
Before #2765 the two file bindings were localStorage keys
(vayu.spec-files, vayu.data-files). The first launch of a release that
stores them on the row moves each binding onto the collection it named, if the
engine still lists that collection and it holds no binding yet, and removes the
key once every move has landed. A binding of a collection that was deleted or
in the trash at that launch is not moved.
Logging¶
vayu-engine and vayu-cli each write one file under <data-dir>/logs/
(engine_<stamp>.log, cli_<stamp>.log), one JSON record per line, plus a
text rendering on the console; the Electron app's own port of the same record
and redaction rule (electron/log.ts, issue #1558) writes app_<stamp>.log
alongside them. logLevel (default info) is the floor for the engine's and
the app's files, vayu-cli always writing at that default;
maxLogFileBytes its rotation cap, and the newest 10 per-prefix files survive
a start. Every
route's request line comes from one hook, install_request_logger
(http/request_log.hpp), installed on both httplib::Server instances the
engine owns - the management API and the webhook inbox's listener, never the
mock server's, which routes an arbitrarily long path through its own
pre-routing handler (issue #1139). See Engine Logging for the
record shape, the category list, the redaction rule and the file layout
(issues #1510, #1557).
Security¶
- Local-only binding: the management API only listens on
127.0.0.1. A webhook inbox is the single listener that may bind wider, and only when the caller confirms it explicitly; it serves no engine route. - No browser: the management API sends no CORS header and refuses, before any route, a
request carrying
Originand one whoseHostis not a loopback name for its own port, which is what keeps a DNS-rebinding page out (Listeners). - Script sandboxing: QuickJS contexts have no filesystem access. Their one
network path is
pm.sendRequest, which goes through the same send gate and scheme rule as a request (next bullet) - Only
httpandhttpsleave the engine. libcurl speaks other protocols,fileamong them, so the send gate (validate_transferable) refuses any other scheme on the URL every driver is about to hand a handle - after variables, the pre-request script and the residual pass - andapply_transport_policyholds every handle tohttp,httpsfor the one URL that gate cannot judge (a scheme libcurl guesses), while the engine's own redirect loop refuses aLocationnaming another scheme before making the hop (resolve_redirect_target). One rule for Send, runs, streams,pm.sendRequest, import fetch and OAuth. See api-reference.md. - Request-body files: one trust rule. The engine reads a file from this
machine for exactly two body shapes - a
binarybody'sfileand aform-datafile part - and sends one only when it lies under a folder the user allowed in Settings (file_roots) or is a file a person picked (file_grants, #2356). A reference is sendable iffFileAccessPolicy::allows (src): containment is decided on canonical paths component by component, so a symlink escaping an allowed folder is outside it, and a grant is the canonical path recorded at the pick, matched exactly, so a link re-pointed afterwards names another file. Nothing a request body says changes the answer: itsunresolvedis ignored when a payload is parsed, never stored, and derived on every read for the editor to show. Asrcstill holding{{is refused, and no grant can name one. Scripts can never set a path: the residual pass does not resolvesrc. Both tables change only throughPOST/DELETEon/file-rootsand/file-grants, which need the per-start grant secret the app passes asVAYU_GRANT_SECRET(http/grant_secret.hpp); an engine started without one refuses those writes and still honours the rows. The rule lives inhttp/file_ref.hpp(FilePlan) andhttp/file_access_policy.hpp, runs once per design send after the residual pass and once per run at plan time (every distinct data-bound path included), and refuses before any transfer; the send gate (validate_transferable) refuses a binary body or file part no plan checked. The file the check approves is opened by it, on the canonical path the policy approved and without following a final symlink, and nothing reads the path again: a binary body's inline bytes and hash come through that open file, a larger binary body streams from it, and a form-data file part is read from it per transfer (#2416, #2678), so a link re-pointed after the check, or between a run's iterations, is not followed (a path a data row binds is opened per submission, through the check again);engine/CLAUDE.mdstates what remains. A record of a send keepsbodyFile {fileName, size, sha256}, never the bytes or the path. See api-reference.md. - Single instance: one engine per data directory, held from before the
database opens until after it closes (
InstanceLockindaemon.cpp). On Linux and macOS it is aflockon the data directory plus one onvayu.lock, so deleting the file does not let a second engine in (issue #2422); a filesystem that cannot lock a directory falls back to the file alone and logs a warning. On Windowsvayu.lockis held with share mode 0 and cannot be deleted while held. See lock-file-handling.md. - Secret handling (v1 posture): auth credentials and cached OAuth 2.0 tokens
are stored in plaintext in SQLite;
runs.config_snapshotwithholds the composed request's credentials before persistence (authdown to{mode}, a credential header's value and every secret variable's value written as<redacted>, issue #1803); and every log record is redacted by key before either sink sees it - a secret-named field becomes<redacted>, a URL-named field is stripped to scheme/host/path (issue #1557, Engine Logging), which is what curl verbose logs go through too. Token request bodies/responses are never logged. On-disk encryption (safeStorage) is still deferred, and so is OS-keychain storage (out of scope for the transport epic, #704 decision 6; the app runs Chromium withuse-mock-keychain). Mid-run token refresh is not deferred: the refresh watchdog ships, and re-acquires a load run's OAuth 2.0 tokens (a collection load run's included) before they expire. - Where the redaction line falls, and why it is not one line. Two columns of
a run row answer two different questions, and the split is deliberate:
runs.config_snapshotrecords the request composed, with its credentials withheld: the payload arrives with every{{variable}}composition could answer already resolved (a scripted request's names stay written, #2521), and the caller'stargetPolicyis dropped, never stored, sosanitize_config_snapshotkeepsauthdown to{mode}, writes<redacted>for the value of every header named in the shared secret set (Authorization,Cookie,X-Api-Key, ...) or by the request's ownapikeyauth, and masks every value of a variable marked secret, raw, percent-encoded, JSON-escaped and XML-escaped, wherever it landed inurl,params,headers,body.contentorbody.fields(issue #1803). Composition answers with values, not provenance, so the secret values are read from the scopes the payload names (globals,environmentId, the collection chain ofrequestId's request; for a scenario, the chains of its collection and of every folder a step sits in, #3270), and a value under four characters is not masked. A scenario run stores the uncomposed URL besides - a composed plan carries resolvedAuthorizationheaders and anapikeyin the query string, and the sanitizer reads no plan.results.trace_datarecords what was sent, which is the only thing it is for: it stores the resolved request headers - both as composed and, since issue #664, as the transfer issued them (request.sentHeaders) - and since issue #348 the wire message itself (request.rawRequest, theCookieline included). Both are credential-grade, both are plaintext under the v1 posture above, and a trace that hid what went out would have no reason to exist, so the engine and History keep them raw by decision; the MCP server masks a secret variable's value and a credential header's value in them on the way to an agent (<redacted>, unless the user turned on Reveal secrets to agents, mcp.md, #1809). The trace names what auth wrote so that masking has something to go on -request.authQueryParam(the raw name of the query parameter auth appended) andrequest.authHeaders, each absent when auth wrote none (#1835); the livePOST /executeanswer carries the same two keys at its top level, sorun_requestmasks what it returns by the same rule (#1845). Beside them,authNoticesays when auth sent nothing: a mode Vayu does not execute (#2474), or an empty bearer token or API key name (#3203); or when a typedAuthorizationheader spared an OAuth 2.0 token its fetch (#3202); it carries no credential and is not masked. What bounds their lifetime is run retention (maxRunsRetained/maxDesignRunsRetainedand the prune pass), not the process - so clearing the cookie jar does not clear the runs that recorded it.
Dependencies¶
- libcurl: HTTP client library
- cpp-httplib: HTTP server library
- nlohmann-json: JSON parsing/serialization
- sqlite3: Embedded database
- sqlite-orm: C++ ORM for SQLite
- QuickJS: JavaScript engine (vendored)
- libsodium: SHA-256, HMAC-SHA256, base64 and hex, and the CSPRNG behind
require('uuid')(ISC) - OpenSSL (libcrypto): MD5, SHA-1, the SHA-2 family and their HMACs for the
crypto-jsshim, throughutils/digest.hpp; already in the binary as libcurl's TLS backend