Skip to content

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 - returns std::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 - returns RouteResult, which is std::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_response turns one into the pair a core returns.
  • A payload parser - parse_mock_start, parse_inbox_start, parse_inbox_response_update, parse_live_resume_point - returns std::expected<Parsed, ParseError>, where Parsed is 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 one save_config_entry call 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 an update_*_locked function holding the read, the merge and the write, in the shape reorder_response established.
  • 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 a create_*_locked core 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 lock restore_deleted holds 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 same before_write test seam.
  • The import's globals merge - POST /import (issue #1906), the one caller that has to merge globals, because POST /globals replaces the whole set. merge_globals_locked reads the stored set, lays the imported variables over it and writes the result inside one with_lock, after the tree has committed; a POST /globals landing between a separate read and write would be overwritten. It takes the same before_write test 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 GET still reaches a GET route, which is why none has a side effect), and a program on another host can send any Host it 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 bind field 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, and with_lock holds 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 (a MissingRowError half-way through a reorder) publishes nothing, and a busy retry publishes once, for the attempt that landed. A write inside a with_lock composite 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 getaddrinfo on 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 /live consumer read them.
  • A Stop means what its phase says (issue #3341): RunContext carries a RunPhase (setup, sending, draining, summarising, settled; core/run_phase.hpp) and request_stop latches the phase the first Stop landed in. A Stop before the strategy returns (setup or sending) decides the outcome (stop_decides_outcome): the run ends stopped, 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, or failed by its failRun thresholds. What it cancelled is stored as the summary's drainCut (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 than timeout + 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 its RunStatus. It is published while the run is active (issue #3568), as phase on every live metrics frame (emit_live_tick) and on GET /runs/:id (get_run_response, from RunManager::get_run, so a retained or stored run has no phase key). A streaming run (stream: true) is not bounded by timeout: 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), or timeout + 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, as cancelled, outside the run's total and its error count, so requests_sent is 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/:id waits on before removing rows (see the API reference), and it sets RunContext::settled, which /runs/:runId/live waits on before its complete frame reads the status (issue #2140) - closed alone 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() calls request_stop on every active run (the same latch, so a run still sending ends stopped and 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 a shared_ptr to its own RunContext, 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 a Database that main is about to destroy. A run started while the drain is in progress is refused with a 503. 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 a monitor block (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 watch is_running and are joined together through RunContext::join_aux_threads - the worker has several exit paths, and a thread joined at only some of them outlives the Database it writes through. The join first sets RunContext::aux_cancel, the ClientConfig::cancel of 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_stop is not that flag because a natural end never sets it.
  • The run's own thread carries should_stop (#3371): every pm.sendRequest a 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 through ScriptSendInputs::cancel, and a single-request run's start-of-run token request takes it through build_request, because Stop and shutdown both raise it and both wait on that thread. A sequential run's every step takes it too, through ExchangeInputs::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 as stopped, never errored. A token request whose flag is already set is never sent, so a stopping server does not reach the endpoint. The auxiliary threads keep aux_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 run Stopped; a lifecycle or inline step script whose send it cancelled is skipped (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::stop and ExchangeInputs::stop carry it to ScriptContext::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 is ScriptResult::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 only RunContext::engine_stopping, which RunManager::shutdown raises through request_shutdown, ends it then.
  • Two kinds of worker, one lifecycle: start_run spawns the load executor plus its auxiliary threads, start_scenario_run spawns the sequential collection runner. Both go through the same spawn_run registration - 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-atomic counts[i] += 1; total_count += 1 and 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 request timeout set past an hour would have left a long completion out of every percentile and max. 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 and max read 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 exceed max.
  • Load percentiles and max round up, by at most 0.1% (issue #2791): every latency histogram is kept at HISTOGRAM_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_percentile and hdr_max both end in highest_equivalent_value, vendor/hdrhistogram/src/hdr_histogram.c). A percentile or max therefore 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 reports max 1000.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 is round(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 rank ceil(p/100 * n), so its max is the true slowest and its percentiles carry no bucket error. The two methods differ in rank as well as in rounding at small n: 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's second* 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 live cumulativeP*Ms and the gate frame's cumulativeLatency (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 by adopt_level_epoch() when the capacity search asks and read by level_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.phases and, through each phase's mean, its avg*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 its cumulativePhases, 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 own phase_histograms - leaves the bank unallocated, so the cost on the completion path is one null check. Written through hdr_record_value_atomic for 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-internal queue_wait are 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 (the maxInFlight cap, 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, and 0 where 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 relaxed fetch_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 an exchange (0) that frees the slot, and hands the same entries to the stored row's status_seconds and the gate frame's statusSeconds, 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 is set_load_start, given the instant RunContext::load_start_steady_ms holds, and nothing is counted per second before it. The run export is a third consumer, after the app's chart and the metrics route's maxPoints fold: run_export.cpp copies each tick's entries that status_second_entry_from_json accepts, so the document's timeSeries carries the same per-second counts, and run_export_html.cpp draws its status chart from them as responses per second, falling back to differencing the cumulative status_codes only for a run whose rows carry none (#2888)
  • A scenario load's sequence on the gate frame (issue #2823): execute_scenario_load publishes its ScenarioLoadState to the RunContext once it is built (publish_scenario_state, a leaf mutex held for the pointer swap alone, the event_loop pattern), and the gate frame copies the pointer under that lock and builds its scenario block (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_ticks row per second during the run (the complete tick object, built once at write time), and the whole-run runs.summary is written once at completion. The results go in chunks of RESULTS_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 still running while 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, through get_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 by errors_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 as error_types (#2400). Only the per-error detail is a prefix, which the report says as errors.withDetails. A run stored before #2400 has no error_types, and its breakdown still counts the stored records, so past the cap it covers the first maxStoredErrors.
  • 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.request writes are applied to the request before it is sent (see docs/engine/scripting.md)
  • Signing: pm.crypto.sha256 / .hmacSha256 plus the btoa / atob globals, so a pre-request script can sign the request it just rewrote. Backed by libsodium through utils/sha256.hpp (shared with PKCE) and utils/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 is pm.crypto, not crypto.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 same http/https scheme 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.

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 /cookies shows it, DELETE /cookies empties 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 but GET /cookies leaves 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_COOKIELIST exports and hands it back through CURLOPT_COOKIELIST, so domain matching, path matching, Secure and expiry stay inside libcurl's cookie engine. The parser and matcher in cookie_jar.cpp serve the read views (pm.cookies, pm.cookies.jar().get, GET /cookies), which need an answer without a transfer, and the URL-scoped removal jar().unset performs. They never decide what goes on the wire.
  • Not on the load path. EventLoop never 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 inline script.* element's pm.cookies reads that one VU's own list directly, with no lock and no CookieJar object (issue #1501); it stays read-only there, and pm.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_OUT frame (client.cpp) rather than from request_headers, and shows the Cookie line 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. A Cookie the request types joins that line rather than going out beside it (issue #2788): its rows ride CURLOPT_COOKIE, which libcurl writes after the jar's matches on the one line, so a request never carries two Cookie headers. The one exception is a line libcurl cuts at 8190 bytes, which drops the typed rows with it: request_headers records them before the transfer, so apply_cookie_notices removes them afterwards and the response carries a cookie_not_sent warning, as it carries cookie_limit_reached past 150 jar cookies. Both come from libcurl's CURLINFO_TEXT notices (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 a Set-Cookie line 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 carries cookie_dropped_oversized / cookie_dropped_too_many. A disableCookies send 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::send and 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 the 202 or a relay frame: the app reads them from GET /runs/:runId/report once the relay's complete arrives. The incoming rules are one copy, SetCookieLimits (http/set_cookie_limits.hpp), which the event loop's header_callback also runs, allocation-free, on a transfer that tracks cookies (a scenario load run's step): it counts what was dropped on Response::set_cookie_headers_dropped, handle_result sums that in the MetricsCollector, and the run reports one cookies_dropped warning with the count and no name. The outgoing caps are not detected under load, because reading libcurl's notices needs CURLOPT_VERBOSE on 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 same Cookie line 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 resolved Authorization header beside it - see Security for where the line between this and runs.config_snapshot falls. It is bounded by run retention, not by the process: DELETE /cookies empties 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.sendRequest beside another execute - so capture_jar_cookies hands CookieJar::reconcile the 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 a CookieWrite that 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 through CookieJar::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. Both POST /execute and POST /runs go through it.
  • auth_resolver (apply_auth / preflight_auth / plan_oauth2_refresh / plan_auth_refresh) - a typed Auth variant with an exhaustive per-mode handler: bearer/basic/api-key are injected inline; oauth2 delegates to the token client; a mode stored but not executed (digest, aws, ntlm, hawk, oauth1, edgegrid, jwt) sends the request without auth and sets Request::auth_notice, which the /execute answer and the stored trace carry as authNotice (#2474); a bearer token or API key name that is empty once trimmed writes nothing and sets it too (#3203). A user-supplied Authorization header always wins; against an oauth2 token placed in the header it wins before anything is fetched (#3202), at the build, at preflight_auth (which takes the run payload's headers) and in a late apply_auth, and sets an authNotice saying 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 typed Auth and 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 binds user-{{$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_auth in request_exchange), Postman's order. POST /execute decides it per send (plan_send_row_auth), a collection run per step when its plan resolves (ScenarioStep::auth_after_scripts, applied by execute_exchange on the sequential run and by resolve_load_residuals on the load run), and a single-request load run once, only when it declares requestElements (LoadAuthPlan::after_scripts), the one shape with a residual pass per submission. One without requestElements that names an environmentId or requestId defers 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_refresh decides afterwards whether the credential a single-request load run just resolved can be kept current past its expiry, and plan_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), the oauth_tokens cache (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 an invalid_grant or invalid_client refusal clears the row, and an unavailable endpoint on a refresh is an oauth2_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-hosted 127.0.0.1 loopback listener + PKCE (S256) and state, 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 the Server for a clean shutdown.
  • mock_issuer - the local OAuth 2.0 issuer (routes/mock_issuer.cpp): POST /mock-issuer/start binds another 127.0.0.1 listener serving /token and /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 /authorize with PKCE S256 verification, rotates refresh tokens, and can be flipped between healthy and slow / server_error / invalid_client while running. In-memory only and owned by the Server, 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-blank script.pre on the request, a folder or the collection), composition leaves every name a scope answers written and lists the names in the response's deferredVariables (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 inherit auth by walking the collection ancestor chain leaf→root (an explicit noauth terminates the walk, none is 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 inline request given alongside a requestId lays over the stored fields before resolution (how MCP's start_load_run overrides 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):

  1. Reconciliation: runs still running/pending were 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, so GET /runs reported them as running forever. They are marked failed; end_time keeps what the run recorded, or becomes start_time when it recorded none (a run that died while running, which a move to running leaves at 0), 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, flagged partial (#2895), so its report shows the totals it reached rather than zeros (see Database Schema).
  2. Pruning: run history is trimmed per kind - load and collection runs to maxRunsRetained, design Sends to maxDesignRunsRetained (#2429) - and every kind to runRetentionDays. Reconciliation runs first so an orphan is terminal, and therefore prunable, in the same startup.
  3. Trash retention: collections, requests, environments, saved examples and client certificates deleted more than trashRetentionDays ago 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, and POST /trash/:id/restore puts 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.

{ "mode": "constant_rps", "targetRps": 1000, "duration": "60s", "maxInFlight": 10000 }

2. constant_concurrency (closed-loop)

Holds a constant number of in-flight requests for the duration via the shared maintain_concurrency controller.

{ "mode": "constant_concurrency", "concurrency": 100, "duration": "60s" }

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.

{ "mode": "iterations", "concurrency": 10, "iterations": 1000 }

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 with SseParser about what an event is (a frame carrying no data field is not one), so a load run and a design run report the same count for the same stream; sse_frame_counter_test.cpp drives both over one table and asserts they match. The same callback stamps the write that completes the first event (issue #3234), measured from submitted_at like the latency, and the completion copies it to Response::stream_first_event_ms. It is the report's stream.timeToFirstEvent, and it cannot be read off libcurl: the start-transfer time ends at the response headers, which a gateway that answers 200 and then thinks sends long before its first event. Both caps, the stamp and what the ended stream reports live in one StreamTally (http/stream_tally.hpp), which the event loop's TransferData and Client each 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.

  • concurrency is 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 small ScopeOverlay of 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, and maintain_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): its ScopeOverlay keeps every environment, collection and globals write for the VU's life, so a control.once login'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_rps with a scenario is a 400, as is a non-zero rps/targetRps on 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 but constant_rps for the same reason (see Load Test Strategies). maxInFlight is 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 step errored, as on a collection run (#2947), without ending the iteration, so the summary's errored is not the sum of the steps' noResponse. Flow control follows the collection run's rules (#2974): finish_step drops the control.switch / control.loop jump of a step that errored, so the iteration walks on, and a jump it cannot honour (an unresolved target, the maxStepsPerIteration cap) ends the iteration as abandoned with the step errored, its error text in the log. A step that answered with an HTTP error status is counted in that step's errors (as httpErrors, #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 maxScenarioSteps bounds. They reach the report as summary.scenario.steps; a scenario load run stores no per-step results rows, 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.data claims 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's iterationInTest / 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's errors count 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 its dataRowIndex, which is what makes a failure attributable to a row when no per-step results rows exist.
  • A single-request load run binds rows too (issue #993). Its rows ride the payload's top-level data rather 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 its dataRowIndex. The credential half is split onto RunContext::load_auth rather 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_rows and bind_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 are 1 and 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 tests empty() 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_one runs step.before before binding and submitting; the completion runs step.after once the response is in hand, before the VU is released. extract.* / assert.* always run; a script.pre / script.post runs here only when its own config.inline is set or the run's elements.scripts override forces it - unmarked, a step's scripts still defer exactly as before this issue. Each VU writes through its own ScopeOverlay (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 view pm.environment.set writes through; the residual-token pass reads a cheap flattened-map-plus-overlay merge instead, which is what makes correlation (step 1's extract.json reaching step 2's {{token}}, for that VU alone) work under load. pm.execution still 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. See elements.md for 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_script element - 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 new scenario.steps[].elements per-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's max_response_samples budget 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.type is load, not scenario: it publishes metric ticks and reports RPS and percentiles like any load run, and scenario is 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 monitor block - 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 /execute with "stream": true), owned by SseStreamManager.

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 parsed body (#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 calls malloc_trim once 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.

  1. Quit Vayu (or stop vayu-engine).
  2. Copy the snapshot over db/vayu.db.
  3. Delete db/vayu.db-wal and db/vayu.db-shm if they are present - they belong to the database you just replaced, and leaving them behind reapplies its writes on top of the snapshot.
  4. 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 in app/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-accent and the other vayu-ui-* keys).
  • Three JSON files under the Electron userData folder (app/electron/json-store.ts): window-state.json (window size and position), response-cache-clear.json (the version that last cleared the response cache) and mcp-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 for vayu.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 Origin and one whose Host is 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 http and https leave the engine. libcurl speaks other protocols, file among 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 - and apply_transport_policy holds every handle to http,https for the one URL that gate cannot judge (a scheme libcurl guesses), while the engine's own redirect loop refuses a Location naming 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 binary body's file and a form-data file 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 iff FileAccessPolicy::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: its unresolved is ignored when a payload is parsed, never stored, and derived on every read for the editor to show. A src still holding {{ is refused, and no grant can name one. Scripts can never set a path: the residual pass does not resolve src. Both tables change only through POST/DELETE on /file-roots and /file-grants, which need the per-start grant secret the app passes as VAYU_GRANT_SECRET (http/grant_secret.hpp); an engine started without one refuses those writes and still honours the rows. The rule lives in http/file_ref.hpp (FilePlan) and http/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.md states what remains. A record of a send keeps bodyFile {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 (InstanceLock in daemon.cpp). On Linux and macOS it is a flock on the data directory plus one on vayu.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 Windows vayu.lock is 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_snapshot withholds the composed request's credentials before persistence (auth down 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 with use-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_snapshot records 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's targetPolicy is dropped, never stored, so sanitize_config_snapshot keeps auth down 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 own apikey auth, and masks every value of a variable marked secret, raw, percent-encoded, JSON-escaped and XML-escaped, wherever it landed in url, params, headers, body.content or body.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 of requestId'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 resolved Authorization headers and an apikey in the query string, and the sanitizer reads no plan. results.trace_data records 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, the Cookie line 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) and request.authHeaders, each absent when auth wrote none (#1835); the live POST /execute answer carries the same two keys at its top level, so run_request masks what it returns by the same rule (#1845). Beside them, authNotice says when auth sent nothing: a mode Vayu does not execute (#2474), or an empty bearer token or API key name (#3203); or when a typed Authorization header 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 / maxDesignRunsRetained and 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-js shim, through utils/digest.hpp; already in the binary as libcurl's TLS backend