Skip to main content

laser_wire/
limits.rs

1// Wire caps, enforced client-side so an oversized op fails fast instead of
2// round-tripping, and server-side so a hostile client cannot inflate state.
3
4/// Hard ceiling on rows in a single query reply. A `limit` above it is
5/// rejected with `QueryError::TooLarge`, and a `0` limit defaults to a full
6/// page. Callers page through larger result sets with `offset`.
7pub const MAX_PAGE_SIZE: usize = 1000;
8/// Page size a streaming reader pulls when the caller has not set an explicit
9/// limit. Large enough to amortize round-trips, small enough that an
10/// unbounded scan does not spike memory.
11pub const DEFAULT_STREAM_PAGE_SIZE: usize = 100;
12/// Hard cap on the number of `agdx.idx.*` headers a single record may carry.
13/// Total header byte size is already capped, but a buggy producer could stamp
14/// dozens of tiny indexed scalars under the byte budget and slow the
15/// projector. 32 covers every legitimate analytics row with head-room.
16pub const MAX_INDEX_ENTRIES_PER_RECORD: usize = 32;
17/// Cap on the payload bytes the projector **inlines into a materialized row**
18/// (when `inline_payload` is set). This bounds only the copy kept alongside the
19/// indexed row in the read-model backend, never the original message: the Iggy
20/// log always retains the full bytes and a fetch can replay them. Held at
21/// [`MAX_VALUE_BYTES`] (8 MiB) so a single inlined body and a single KV value
22/// share one "max opaque value" ceiling. A body above it still indexes and
23/// still lives in the log. It is just not duplicated into the row, so a typed
24/// fetch decodes from the log (or a claim-check [`ContentType::Ref`] body). The
25/// cap exists because multi-MB BLOBs per row bloat the embedded query DB and
26/// slow scans.
27///
28/// [`ContentType::Ref`]: crate::content::ContentType::Ref
29pub const MAX_PROJECTOR_PAYLOAD_BYTES: usize = MAX_VALUE_BYTES;
30
31// KV caps. Keys are arbitrary bytes (text, binary, anything), at
32// most 512 bytes. Values are arbitrary opaque bytes, capped at 8 MiB:
33// generous for session, flag, counter, cached-JSON, and chunked working state,
34// yet well under the frame ceiling so a set request and a get reply each ride
35// one socket frame with envelope head-room.
36/// Maximum KV key length, in bytes.
37pub const MAX_KEY_BYTES: usize = 512;
38/// Maximum KV value size, in bytes.
39pub const MAX_VALUE_BYTES: usize = 8 * 1024 * 1024;
40/// Hard ceiling on a KV scan page (LaserData Cloud clamps to it).
41pub const MAX_SCAN_LIMIT: usize = 1000;
42/// KV scan page size when the caller sets none.
43pub const DEFAULT_SCAN_LIMIT: usize = 100;
44/// The namespace a KV call without an explicit one binds to. A namespace is a
45/// logical bucket: keys are unique within it, scans are scoped to it, and one
46/// user's namespaces stay isolated from another's.
47pub const DEFAULT_NAMESPACE: &str = "default";
48/// Maximum KV (and memory) namespace length, in bytes. A namespace is a
49/// caller-chosen bucket name that flows into grant matching and scan scoping,
50/// so it is bounded and control-character-free, while its charset stays open
51/// (namespaces legitimately carry `/`-style hierarchy).
52pub const MAX_NAMESPACE_BYTES: usize = 128;
53/// Maximum UTF-8 byte length of a session label.
54pub const MAX_SESSION_LABEL_BYTES: usize = 256;
55/// Maximum UTF-8 bytes of a session list's text filter.
56pub const MAX_SESSION_TEXT_QUERY_BYTES: usize = 1024;
57/// Maximum UTF-8 bytes of a session list's opaque page cursor.
58pub const MAX_SESSION_CURSOR_BYTES: usize = 512;
59/// Most session ids one heartbeat record lists. A process with more leases in
60/// one stream splits them over several records.
61pub const MAX_HEARTBEAT_SESSIONS: usize = 2048;
62pub const MAX_STATE_PATCH_OPS: usize = 256;
63pub const MAX_STATE_DOCUMENT_BYTES: usize = 8 * 1024 * 1024;
64pub const MAX_MANIFEST_FRAGMENTS: usize = 1024;
65/// Maximum lease holder identity length, in bytes. A holder id is a stable
66/// node or worker identifier that flows into lease matching and audit events,
67/// so it is required to be non-empty and length-bounded. Its charset is open.
68pub const MAX_HOLDER_ID_BYTES: usize = 128;
69/// Shortest lease (and renewal) lifetime a request may ask for, in
70/// microseconds. Unlike a scan limit, a lease TTL is not clamped up by the
71/// store: a grant is only ever shorter than the request, so a floor is the only
72/// place the contract can keep a lease long enough to survive one round trip
73/// plus the holder's own renewal cadence. Below it, a holder would trip its
74/// deadline before it could renew, which is a caller bug worth rejecting
75/// locally rather than a lease worth granting.
76pub const MIN_LEASE_TTL_MICROS: u64 = 1_000_000;
77/// Longest lease (and renewal) lifetime a request may ask for, in
78/// microseconds. A lease is a bounded-TTL lock whose whole purpose is that a
79/// dead holder's ownership expires; an unbounded request would let one crashed
80/// holder park a key for hours. The ceiling matches
81/// [`crate::authz::MAX_OPERATOR_ASSERTION_TTL_MICROS`]: the same "how long
82/// may one unattended grant outlive the process that asked for it" question.
83/// The store may still grant less (`granted_ttl_micros`), so this bounds the
84/// *request*, and a holder needing longer renews.
85pub const MAX_LEASE_TTL_MICROS: u64 = 5 * 60 * 1_000_000;
86
87// Fork caps. A fork id is a caller-chosen name (e.g. `"experiment-2026-q2"`),
88// so its length is a validatable input cap like a KV key: the client rejects an
89// over-long id before the round-trip. Per-deployment resource ceilings (how
90// many forks may exist) are NOT here: those are a managed-side policy a client
91// cannot validate against, surfaced only as a `ForkError`.
92/// Maximum fork id length, in bytes.
93pub const MAX_FORK_ID_BYTES: usize = 128;
94
95// Authorization caps. A role name is an admin-chosen identifier that flows
96// into grant matching, audit events, and console rendering, so it shares the
97// fork-id shape: a strict safelist plus a byte cap every tier validates the
98// same way. 64 matches the common RBAC-identifier norm.
99/// Maximum role name length, in bytes.
100pub const MAX_ROLE_NAME_BYTES: usize = 64;
101
102/// Ceiling on one `[len: u32 LE][bytes]` frame on the managed-command sockets,
103/// enforced by both the server and LaserData Cloud. A reply above it is replaced by
104/// a structured too-large error rather than truncated. The `u32` length prefix
105/// addresses far more (4 GiB), so this is a deliberate per-frame memory bound on
106/// the whole-frame buffer, not a transport limit. Every consumer of the managed
107/// sockets (the server-side dispatch, the streaming server sidecar, the reply-byte budget)
108/// MUST source this one constant rather than redefining its own frame cap, so
109/// the layers cannot disagree and a reply admitted by one is not rejected by the
110/// next. Changing it moves all of them in lockstep.
111pub const MAX_FRAME_BYTES: usize = 64 * 1024 * 1024;
112/// Hard ceiling on a single query reply's serialized bytes. A reply rides the
113/// managed-command socket as one `[len: u32 LE][bytes]` frame, buffered whole,
114/// so it is bounded by [`MAX_FRAME_BYTES`] by construction (the two are held
115/// equal on purpose so anything a backend admits to a reply, the socket can
116/// frame). Larger result sets are not returned as one oversized reply: they
117/// page via [`MAX_PAGE_SIZE`] rows plus `offset`. Raising this means raising
118/// `MAX_FRAME_BYTES` in lockstep across the server, LaserData Cloud, and the
119/// socket buffer, since it is the same frame.
120pub const MAX_QUERY_REPLY_BYTES: usize = MAX_FRAME_BYTES;
121/// Maximum UTF-8 bytes in an operational index name or query engine label.
122pub const MAX_QUERY_NAME_BYTES: usize = 255;
123/// Maximum UTF-8 bytes in a projection id.
124pub const MAX_PROJECTION_ID_BYTES: usize = 255;
125/// Maximum UTF-8 bytes in a projection's human-readable name.
126pub const MAX_PROJECTION_NAME_BYTES: usize = 255;
127/// Maximum UTF-8 bytes in an index field's name, JSON pointer, or vector field pointer.
128pub const MAX_INDEX_FIELD_BYTES: usize = 255;
129/// Maximum UTF-8 bytes in a writer schema's name.
130pub const MAX_SCHEMA_NAME_BYTES: usize = 255;
131/// Maximum UTF-8 bytes in one read-only raw SQL statement.
132pub const MAX_RAW_SQL_BYTES: usize = 64 * 1024;
133/// Maximum number of positional raw SQL parameters.
134pub const MAX_QUERY_PARAMETERS: usize = 1024;
135/// Maximum UTF-8 bytes in an opaque query page cursor.
136pub const MAX_QUERY_CURSOR_BYTES: usize = 512;
137/// Maximum predicate nodes in one structured filter tree.
138pub const MAX_QUERY_PREDICATES: usize = 4096;
139/// Maximum selected, grouped, sorted, or exact-match fields in one query.
140pub const MAX_QUERY_FIELDS: usize = 4096;
141/// Maximum vector dimensions accepted by the generic query contract.
142pub const MAX_VECTOR_DIMENSIONS: usize = 65_536;
143
144/// The most managed requests one mixed-operation batch
145/// ([`AGDX_BATCH_CODE`](crate::codes::AGDX_BATCH_CODE)) may carry. Bounds the
146/// server work one frame can demand. The assembled reply is additionally
147/// bounded by [`MAX_FRAME_BYTES`] like any other.
148pub const MAX_BATCH_OPS: usize = 64;
149
150// Agent Data Exchange Protocol (AGDX) envelope caps, sized to sit inside the existing cap
151// family. The metadata caps are the load-bearing ones: that field is
152// bridge-injected, so a hostile or buggy edge gets a publish-time rejection
153// instead of inflating every record on a topic.
154/// Cap on the envelope's vocabulary strings (`operation`, `tool`,
155/// `finish_reason`), each.
156pub const MAX_AGENT_STRING_BYTES: usize = 256;
157/// Cap on a producer-supplied idempotency key.
158pub const MAX_IDEMPOTENCY_KEY_BYTES: usize = 64;
159/// Max entries in an envelope's `metadata` map.
160pub const MAX_METADATA_ENTRIES: usize = 32;
161/// Max bytes in one `metadata` key.
162pub const MAX_METADATA_KEY_BYTES: usize = 256;
163/// Max bytes in one `metadata` value (scalar/text size).
164pub const MAX_METADATA_VALUE_BYTES: usize = 1024;
165/// Max total bytes across the whole `metadata` map.
166pub const MAX_METADATA_TOTAL_BYTES: usize = 8192;
167/// Cap on a [`BodyRef`](crate::agent::BodyRef) `reference` string (a URI,
168/// object key, or KV key naming where the externalized body lives).
169pub const MAX_BODY_REFERENCE_BYTES: usize = 1024;
170/// Max capability entries on an [`AgentCard`](crate::agent::AgentCard).
171pub const MAX_CARD_CAPABILITIES: usize = 64;
172/// Ceiling on a connection's advertised metadata (`AGDX_SET_CLIENT_METADATA`).
173/// The metadata is an opaque byte payload any client may set, not agent-only: an
174/// agent advertises its card under the AGDX schema, a regular app sets whatever
175/// blob its own tooling and the console interpret. The ceiling bounds the
176/// per-connection state the streaming server holds and, because the discovery
177/// read (`AGDX_GET_CLIENTS_METADATA`) returns a page of N connections at once, it
178/// also bounds a page at `N * this`. 64 KiB is generous for any card or app blob
179/// while keeping a page well under the frame cap even at the max page size.
180pub const MAX_CLIENT_METADATA: usize = 64 * 1024;
181
182// Memory and graph caps, sized inside the existing cap family. A memory body
183// shares the opaque-value ceiling. A recall page shares the query page cap.
184/// Max bytes in one memory item's body (shares the opaque-value ceiling).
185pub const MAX_MEMORY_BODY_BYTES: usize = MAX_VALUE_BYTES;
186/// Max items a single recall returns (shares the query page cap).
187pub const MAX_RECALL_LIMIT: usize = MAX_PAGE_SIZE;
188
189/// Byte cap on a lexical search's query text (`TextQuery.query`).
190pub const MAX_TEXT_QUERY_BYTES: usize = 1024;
191/// Recall page size when the caller sets none.
192pub const DEFAULT_RECALL_LIMIT: usize = DEFAULT_STREAM_PAGE_SIZE;
193/// Max tags on one memory item.
194pub const MAX_MEMORY_TAGS: usize = 16;
195/// Max bytes in one memory tag.
196pub const MAX_MEMORY_TAG_BYTES: usize = 64;
197/// Max bytes in a memory item id, its kind word, or a forget or feedback target.
198pub const MAX_MEMORY_ID_BYTES: usize = 255;
199/// Maximum graph name length, in bytes. Bounded and control-character-free
200/// like a namespace: the name keys the projection registry and every
201/// traversal request.
202pub const MAX_GRAPH_NAME_BYTES: usize = 128;
203/// Hard ceiling on the hop depth a single graph traversal may request.
204pub const MAX_GRAPH_TRAVERSE_DEPTH: u32 = 8;
205/// Hard ceiling on nodes plus edges in one graph reply.
206pub const MAX_GRAPH_RESULT_ELEMENTS: usize = 10_000;
207/// Max labels on one graph node.
208pub const MAX_GRAPH_NODE_LABELS: usize = 16;
209/// Max bytes in one graph node label or edge type.
210pub const MAX_GRAPH_LABEL_BYTES: usize = 128;
211/// Max encoded bytes of a node or edge `source` provenance reference. A source
212/// names a stream, topic, key, or id, all of which are bounded inputs already,
213/// so this is a defensive ceiling against a hostile or buggy upsert inflating
214/// per-element state. Sized at two key-lengths, since the largest variant (a
215/// key-value source) names both a namespace and a key, far under the opaque
216/// value ceiling, as a source ref is a short pointer, not a payload.
217pub const MAX_SOURCE_REF_BYTES: usize = 2 * MAX_KEY_BYTES;
218
219// Consumer-filter caps. A filter is evaluated per record on a streaming server
220// shard, so its size and shape are bounded before it compiles.
221/// Maximum encoded writer schema used by a consumer-filter decoder.
222pub const MAX_FILTER_SCHEMA_BYTES: usize = 1024 * 1024;
223/// Maximum nesting in an Avro writer-schema document.
224pub const MAX_FILTER_SCHEMA_DEPTH: usize = 64;
225/// Max encoded bytes of one consumer filter.
226pub const MAX_FILTER_BYTES: usize = 8192;
227/// Max expression nodes in one filter, literals inside lists included.
228pub const MAX_FILTER_NODES: usize = 128;
229/// Max nesting depth of a filter expression.
230pub const MAX_FILTER_DEPTH: usize = 8;
231/// Max JSON nesting depth a payload decoder accepts. Every server bound and
232/// SDK guard uses this one value. It stays below the `serde_json` recursion
233/// limit, so an over-deep payload is reported as `too_deep`, not `malformed`.
234pub const MAX_FILTER_PARSE_DEPTH: usize = 127;
235/// Max segments in one field path.
236pub const MAX_FILTER_PATH_SEGMENTS: usize = 16;
237/// Max bytes in one field path or header key.
238pub const MAX_FILTER_PATH_BYTES: usize = 256;
239/// Max items in one `in` list.
240pub const MAX_FILTER_LIST_ITEMS: usize = 64;
241/// Max bytes in one string literal.
242pub const MAX_FILTER_STRING_BYTES: usize = 1024;
243/// Max bytes in a saved filter's name.
244pub const MAX_FILTER_NAME_BYTES: usize = 128;
245/// Max bytes in a saved filter's description.
246pub const MAX_FILTER_DESCRIPTION_BYTES: usize = 1024;
247/// Max bytes in a stream, topic, consumer, or group name a filtered read names.
248pub const MAX_FILTER_SOURCE_NAME_BYTES: usize = 255;
249/// Max records one filtered page returns.
250pub const MAX_FILTERED_PAGE_RECORDS: u32 = 1000;
251/// Max reply bytes one filtered page may carry.
252pub const MAX_FILTERED_PAGE_BYTES: u32 = 8 * 1024 * 1024;
253/// Max source records one filtered page may ask to examine. The server
254/// lowers it to its own budget.
255pub const MAX_FILTERED_PAGE_EXAMINED: u32 = 100_000;
256/// Max milliseconds a filtered wait is held by the server.
257pub const MAX_FILTERED_WAIT_MS: u32 = 20_000;
258/// Max partitions one filtered wait names.
259pub const MAX_FILTERED_WAIT_PARTITIONS: usize = 1024;
260/// Max waits one filtered wait cancel names.
261pub const MAX_FILTERED_WAIT_CANCEL_IDS: usize = 64;
262/// Max records one preview may examine.
263pub const MAX_FILTER_PREVIEW_EXAMINED: u32 = 10_000;
264/// Max records one preview returns.
265pub const MAX_FILTER_PREVIEW_RECORDS: u32 = 100;
266/// Max payload bytes a preview record carries as text.
267pub const MAX_FILTER_PREVIEW_PAYLOAD_BYTES: usize = 4096;
268/// Max payload bytes a supplied test sample may carry.
269pub const MAX_FILTER_SAMPLE_BYTES: usize = 1024 * 1024;
270/// Max headers a supplied test sample may carry.
271pub const MAX_FILTER_SAMPLE_HEADERS: usize = 64;
272/// Max page size of a catalog list.
273pub const MAX_FILTER_CATALOG_PAGE: u32 = 200;