Weir has one process per server. A Node owns its Store runtimes, the application listener, diagnostics and the memory-pressure guard. Lua evaluates inside that same process.
client -> Weir address -> any replica: Execute -> local backend
Every replica behind an address hosts the same Stores and shares nothing with the others. A request naming a Store the server does not host fails with NotFound. Backend configuration and authentication remain local. See protocols.
| Component | Responsibility |
|---|---|
cmd/weir |
CLI, signals and process lifecycle |
internal/app |
Configuration, resource assembly, diagnostics and Node shutdown |
internal/server |
StoreService, transport admission and per-record admission and publication |
internal/store |
Queueing, batch selection and execution slots |
internal/execution |
Prepared plans and the MongoDB/Search adapter contract |
internal/backend |
Native backend encoding, execution and completion evidence |
internal/luaengine |
Restricted VM and value conversion |
internal/overload |
Live memory sampling, admission hysteresis and the container-derived Go memory limit |
The independent weir-protocol module owns public schemas and shared validation.
The independent weir-go SDK depends on it. Server acceptance tests consume the
SDK; the production server does not import the SDK. No code is generated in this
repository.
Execute is a finite bidirectional stream selecting one Store and one operation kind. Each Read/Mutate request carries one resource and a consecutive one-based ordinal. Receiving and publication proceed concurrently: each result is sent as its record completes, packed into one message with any other result already waiting, and a stream holds at most the protocol's 32 records without results. The server does not retain a whole-call request/result table.
Validated records enter one Store scheduler. It combines compatible records from one or several streams using count and byte targets. Reads and mutations form separate batches. Writes can collect until their oldest admission reaches the configured wait; reads use already queued work. Queue capacity returns at dispatch. Active execution slots return when backend execution finishes. Batches that are not full run below an adaptive limit that halves when executions queue at the backend, so records wait in Weir and form larger batches instead. See batching for grouping, the adaptive limit and backpressure.
Same-resource mutations within a stream execute in input order: one at a time, or together in one batch where the adapter folds them. Each plan keeps its own record context, bounded by the record's timeout, its stream and any cancel request naming it, and each result returns to the stream that submitted it under its ordinal, so equal ordinals in different RPCs cannot collide. A stream sends each result when its record completes. Canceling one record leaves other batch members active. Shared execution uses the latest participating deadline; an unbounded record keeps it unbounded. Canceling every record stops shared backend work.
Native is a singleton invocation that bypasses the record queue and execution slots. Each Store runs at most 64 Native commands; further ones wait for a free slot until their caller gives up. A Native command lasts until its caller has read the response or the output watchdog ends the RPC, so slow Native consumers delay only other Native commands, never typed work. The client sends one command, half-closes input and consumes metadata/body events plus NativeEnd. Success requires the terminal event and final gRPC OK. Native bypasses typed target qualification and forwards the backend's request/response formats. It preserves backend pagination, cursors, sessions and permissions.
Read failures and mutation outcomes are individual typed results; transport failure is gRPC status. Confirmed item results survive a later stream failure.
| Outcome | Required evidence |
|---|---|
NOT_STARTED |
No backend attempt |
NOT_APPLIED |
Definite rejection or no-send evidence |
APPLIED |
Validated application acknowledgement |
UNKNOWN |
Application cannot be determined |
A failure may accompany APPLIED when application is confirmed but the requested completion guarantee fails. Neither server nor SDK automatically replays possible writes. Mutate is not an application transaction; a later invalid request does not undo earlier effects. There is no durable deduplication or exactly-once claim.
MongoDB Lua groups use short snapshot transactions. A confirmed abort can allow a fresh read/evaluation/write attempt. An ambiguous commit can only retry confirmation of that same commit. A group that runs out of attempts on write conflicts is halved until only the contended records fail. Search uses real-time reads and version-conditional writes; only confirmed conflicts allow reevaluation of affected items. Neither adapter adds revision fields to business documents. Query visibility is requested explicitly and remains part of completion.
Memory use is bounded by static limits rather than per-byte accounting. Every
request and response message is at most 64 MiB. Each Store bounds its queue by
operation count and request bytes, its batches by count and bytes, and its
concurrent adapter invocations by max_in_flight. Each record stream holds at
most 32 outstanding records. Size the container for these
limits and the largest documents you serve; batching shows the
calculation.
Memory pressure closes admission: once live memory reaches 80% of the Go memory
limit, new RPCs end with gRPC UNAVAILABLE before any request is read and new
records receive NOT_STARTED with Failure UNAVAILABLE, as during a drain, until
it falls to 70%. A NOT_STARTED record may be sent again. UNAVAILABLE alone
does not show that work never began: UNKNOWN outcomes and broken connections
carry it too. The CLI sets that limit to 90% of the container's cgroup v2 memory limit unless
GOMEMLIMIT is set. Container/OS memory limits remain the hard boundary; see
operations.
Lua programs run within the caller's deadline and the VM's call-depth and stack limits. Compiled programs are cached per process, bounded at 256 programs and an estimated 16 MiB. There is no per-evaluation memory or instruction limit, so transforms must be trusted. See Lua.
The application listener serves only StoreService, over plaintext gRPC on an isolated network. A stalled input or output cancels only its RPC after the stall timeout: the handler and its Store work end at once, but gRPC keeps the stream's last unsent message until the client reads it or the connection closes. HTTP/2 flow control uses fixed windows of 1 MiB per stream and 16 MiB per connection rather than gRPC's bandwidth estimation, which pings each client every round trip while data flows. Keepalive pings and the idle and handshake timeouts close unresponsive connections. Clients may ping as often as every 5 seconds, with or without streams, to find a server they can no longer reach; faster pings end the connection. Every connection ends with GOAWAY after about five minutes so clients re-resolve their address; running streams finish first. Confirmed write evidence remains valid.
Startup loads the configuration file, then qualifies local backends and binds listeners within 30s. Partial startup closes already owned resources. Diagnostics readiness tracks lifecycle rather than backend health or Store load.
Shutdown stops new admission and drains admitted work to its deadline. Cancellation then stops owned work; bounded cleanup joins runtimes and closes backend connections, listeners and diagnostics. Cancellation never proves a sent write was not applied. Remote transaction locks can outlive local cancellation or best-effort session cleanup. See operations.