Skip to content

Latest commit

 

History

History
145 lines (121 loc) · 7.93 KB

architecture.md

File metadata and controls

145 lines (121 loc) · 7.93 KB

Architecture

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.

Module and ownership boundaries

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.

Request execution

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.

Completion evidence

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 and transport

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.

Lifecycle

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.