The wire protocol, version 1

The bytes a TinyStore server and its clients exchange over any byte stream: a child's stdin and stdout, a Unix socket, a Windows named pipe, TCP or TLS. Read it to write a client in a language TinyStore has no SDK for, or to see what an SDK does on the wire; the Bun and Python SDKs are built to this page.

Frames, the profile, the handshake, the errors and every engine's methods, kv, jobs, blobs, sql, records and metrics, are built in server/wire, and why the server behaves as it does is its design. Every example on this page is a vector of testdata/wire/vectors.json, which the server and every SDK are tested against: a value in a typed notation, the bytes it is, and the bytes a decoder refuses, each named after the rule it breaks. Every message is also a vector of messages.json, its bytes and its fields by the names the tables below give them, with the methods' numbers and the errors' codes, so that an SDK checks each field of each message in one loop; the Go types write it, through a schema of each message's keys that TestMessageVectors holds.

#Frames

Everything is little-endian. A frame is a twelve-byte header and a body:

0             4      5       6          8             12
│ body length │ kind │ flags │ method   │ stream      │ body …
  u32           u8     u8      u16        u32

• The length is the body's. A frame is 12 + body length bytes; a body past the agreed maximum is refused before a byte of it is read.
• What is reserved is zero. An unknown kind, a flag this kind does not define, a method outside a REQUEST or a stream where the kind names none is a protocol error, and the connection ends.

END is 1: the sender's last frame on its stream. ERROR is 2, only beside END: the body is an error.

A method's high byte is its engine and its low byte the operation, so a new engine takes a new high byte and the frame stays as it is:

A HELLO from Bun:

16 00 00 00  01  00  00 00  00 00 00 00                                   a body of 22 bytes, HELLO
82                                                                        a map of two
   01 01                                                                  protocol: 1
   02 b1 74 69 6e 79 73 74 6f 72 65 2d 62 75 6e 2f 30 2e 31               client: "tinystore-bun/0.1"

#A connection

1. The client sends HELLO, and the server answers WELCOME, or GOAWAY and closes. Nothing comes before them, and the server waits five seconds for HELLO. The connection speaks the older of the client's newest protocol and the server's, which WELCOME names: a client newer than its server speaks the server's protocol, or closes when it no longer does, and only a client older than the oldest protocol the server speaks is refused.
2. The client opens streams with REQUEST, as many at once as WELCOME allows.
3. Either side may send PING; the other answers PONG with the same eight bytes.
4. The server ends the connection with GOAWAY. The client opens no stream after it; a REQUEST that crossed it on the way is answered unavailable without being run, so it may be sent again elsewhere; the streams already running finish, and the server closes. Stream numbers are reused, so no number could say which requests the server saw: each answer says it.

HELLO:

A body must fit the credit it is sent under, so the max body both sides agree is the smallest of the server's, the client's and the client's stream credit: a client granting 64 KiB a stream takes bodies of 64 KiB at most.

WELCOME:

A client that found the server through SERVE sends no REQUEST before the proof checks, compared in constant time: only the store directory's owner can read SERVE, so a process that took the endpoint of a server gone cannot answer, and a client whose proof fails reads SERVE again, as a stale one. HELLO carries nothing a stranger could use, since a local connection takes no token. A challenge of another length is a HELLO the server cannot take; a remote connection's challenge gets no proof, its server being the one its TLS certificate names. The vectors hold a proof, proofs, and a HELLO with a challenge.

A server that does not take the connection at all, past its connections or closing, still reads the HELLO and answers GOAWAY where the WELCOME belongs, with limit or unavailable.

GOAWAY:

#Finding a local server

A store directory has at most one server, since its LOCK lets one process open it. That server publishes how to reach it in <dir>/server/, which only the directory's owner may enter: mode 0700 and, on Windows, which lets anyone traverse a directory to a file whose path they know, a protected DACL naming its owner alone, which every file made in it inherits. SERVE there is a hint; LOCK is the truth.

{"protocol": 1, "server": "0.4.0", "pid": 4212, "instance": "q1q0l3yZ3JvYw8g7oM2sYA",
 "secret": "Zm9vYmFyYmF6cXV4Zm9vYmFyYmF6cXV4Zm9vYmFyYmE",
 "endpoints": ["unix:///srv/app/data/server/tinystore.sock"], "sidecar": true}

• Written whole, under the lock. Only the store holding LOCK writes server/. A server removes a SERVE left behind before it listens, since the endpoint that file names may be another process's by now, writes its own once it listens, as a temporary file renamed into place, and removes it when it leaves, before it lets go of LOCK.
• Find or start. A client reads SERVE, connects to an endpoint and checks the proof. Any failure, no file, a refused connection or a proof that does not check, starts `tinystore serve --dir --local --log /server/serve.log`. That child takes `LOCK`, which means the old server is gone, and publishes itself; or it finds `LOCK` held and exits with code 3, and the client reads `SERVE` again until the winner answers, five seconds at most, starting one again when none does.
• The proof. A client that found its server through SERVE sends a HELLO with 16 random bytes as its challenge, and sends no REQUEST until WELCOME's proof equals the HMAC-SHA256 of the challenge keyed with the secret, compared in constant time. An endpoint's name is anyone's to take once its server is gone, a Windows pipe's above all, and only the directory's owner can read the secret. A client whose proof fails reads SERVE again, as a stale one.
• A reader delays a change and never fails it. On Windows a client holding SERVE open refuses its rename or removal, and so may a scanner; the server tries again eight times, from 1 to 64 ms apart.

How a client knows its server depends on the transport:

Where a local server listens:

• A Unix socket, <dir>/server/tinystore.sock, when that absolute path fits a sockaddr_un, 104 bytes on macOS and the BSDs and 108 on Linux; past it, the same name in a directory of the owner's own, $XDG_RUNTIME_DIR/tinystore-<hash>, or in the temporary directory without one. <hash> is the first eight bytes of the SHA-256 of the store's absolute path, in hex: eight, so that a socket under macOS's temporary directory still fits.
• A named pipe on Windows, pipe:tinystore-<hash>, created as the first instance of its name with a DACL naming its owner alone, which refuses remote clients. No local endpoint takes a token: its permission is the file system's, and a local connection is admin.

A remote server's tokens file gives each token one capability: admin may do anything, data reads and writes, and read reads only. A read connection may call only the methods the schema marks read, every other one being permission; its SQL runs on a reader and is a query, a statement that writes, attaches a file or sets a pragma being permission too; and its sql.open applies no migration. Its opens may still name a bucket, a queue or files the store did not have, as any first open does, and its reads of an idle key renew it, as any read does.

#Streams

A client names a stream with any number from 1 not in use. A number is in use from its REQUEST to the server's final frame on it, and may be named again after. A REQUEST on a number in use, or past the streams in flight, ends the connection.

• The server ends every stream once: RESPONSE·END or DATA·END, either with ERROR, a cancelled stream too. It takes the number out of use before that frame leaves, so a client may name it again the moment it arrives.
• A download's RESPONSE is its header, a message of the method's, {} when it has nothing to say; its items follow as DATA, and its last DATA·END is its trailer, a message saying where the next page begins.
• DATA carries bytes or items. A blob's bytes are raw; rows, jobs and series are a message each. The method says which. A DATA carries at least one byte, but the one that ends its stream.
• A transfer shares the connection. A sender splits bytes into frames of 64 KiB at most, so that no stream holds the connection longer than one such frame takes to send.
• CANCEL asks the server to stop. It answers with the final frame it would have sent, or with the error cancelled; a client may drop what arrives on a stream it cancelled. A client ends an upload early with CANCEL: ERROR is the server's alone.
• A frame for a stream no longer in use is dropped: a DATA the client sent before the final frame reached it, a CANCEL or a CREDIT that crossed it. The dropped DATA still gives its connection credit back.
• A body that is not its method's message fails its stream with invalid, naming the rule it broke; a frame that is not a frame ends the connection.

#Credit

A sender never sends more than it was granted, and a receiver grants only room it has, so a connection holds no more than its grants and the server's reader never waits.

• Client to server. Every REQUEST and DATA body counts against the connection's credit, and a DATA body against its stream's too. The server gives credit back with CREDIT as it lets go of bodies: on stream 0 for the connection, on a stream's number for that stream.
• Server to client. DATA bodies count against the stream credit HELLO stated, and the client grants more with CREDIT on the stream as it consumes them. A RESPONSE body is not counted: it is one message within the agreed body, and every collection travels as DATA instead, so a client holds at most its streams in flight times the agreed body in answers. Nor is the DATA·END·ERROR that fails a download, so that a stream always has room for its end. A client grants nothing for the connection: its CREDIT names a stream.
• A grant waits for half the window. A receiver grants what it let go of once half its window has gone, and not a frame for every frame it takes.
• A body past its credit ends the connection with GOAWAY and protocol, the connection's last frame.

64 KiB of credit on stream 5:

04 00 00 00  07  00  00 00  05 00 00 00                                   a body of 4 bytes, CREDIT, stream 5
00 00 01 00                                                               65,536

#Messages: the MessagePack profile

A message is one MessagePack value: a map from small unsigned integer keys to values, under these rules.

• Types. Nil, bool, integers, float 64, str, bin, array and map. A float 32, an extension type, the timestamp among them, or any other type byte is invalid.

• Integers. Each field says signed or unsigned and its range. A decoder takes any encoding of a value that fits, ce 00 00 01 2c for 300 as well as cd 01 2c, and refuses one that does not.

• A float keeps its value; bits that must survive are bin. A float field is a float 64: cb 80 00 00 00 00 00 00 00 is -0. The server keeps its bits, so cb 7f f8 00 00 00 00 00 01, a NaN whose payload is 1, comes back as it went; an SDK keeps the value, NaN, the infinities and -0 included, as far as its language does, and JavaScript promises no NaN's payload. A float whose bits are the data therefore travels as bin: a kv float value, a series' samples, an aggregate's values. A float field also takes an integer that a float 64 holds exactly, since a JavaScript encoder writes 3.0 as 3.

• Text is str, bytes are bin. A str is valid UTF-8, and neither stands for the other.

• Keys. A message's keys are unsigned integers; a field that is a map of names, an error's what or a series' labels, says so and has str keys. A key twice is invalid. A key the reader does not know is read past, its value still well formed and within bounds, and then it depends on the reader. A server refuses a request carrying one, unimplemented naming the field, since a field it skipped could change what the client asked, and the answer would be to another question. A client reading an answer, and a server reading HELLO, skip it. So a client leaves out a field at its zero value, and an older server takes everything a newer client sends that it would have sent anyway; and a server adds an answer field only where a client that skips it still reads the answer right, or else answers it only to a client that asked for it in a field of its request. An absent key is the field's default, and nil stands only where a field allows it.

• Bounds come before allocation. A length or a count past the bytes left in the body is invalid, since every element takes at least a byte; nesting deeper than 8 is invalid; a body is at most the agreed maximum.

• Time is an integer: unix milliseconds, unless a field says nanoseconds. Records keep nanoseconds, past what a JavaScript number holds, so an SDK reads such a field as a BigInt:

  1,790,000,000,123,456,789 ns → cf 18 d7 5b 84 2b 4e cd 15

  A duration is an integer of milliseconds.

• Columns of numbers are bin: a series' times and values, little-endian int64 and float64 one after another.

• Encoders are canonical, decoders are not. An encoder writes the shortest form of every integer, length and count, keys in ascending order, every float in eight bytes, so that a vector compares byte for byte; a decoder takes any valid form in any order.

• An SDK's codec is its own: a general library writes plain maps and reads 64-bit integers without rounding when told, but takes a float 32, an extension, a key twice or a value nested nine deep, which this profile refuses. The SDKs' codecs refuse every refused vector.

#Errors

An error is the final frame of its stream, with ERROR set:

The first nine are the root's sentinels, so that an SDK's error classes mean what errors.Is means in Go. A frame or a HELLO the server cannot take is a GOAWAY with protocol or unauthenticated, and the connection ends. A name's value in what is str, or bin where its bytes are not UTF-8, as a kv key of bytes may be.

A conflict on stream 7:

2c 00 00 00  04  03  00 00  07 00 00 00                                   a body of 44 bytes, RESPONSE, END and ERROR, stream 7
83                                                                        a map of three
   01 a8 63 6f 6e 66 6c 69 63 74                                          code: "conflict"
   02 ad 73 74 61 74 65 20 63 68 61 6e 67 65 64                           message: "state changed"
   03 81 a6 62 75 63 6b 65 74 a8 73 65 73 73 69 6f 6e 73                  what: {"bucket": "sessions"}

#Versions

A server and its clients upgrade apart: a remote server deployed once while the applications' SDKs move on, or a sidecar still serving a directory after its application's SDK was updated. So each side promises what it does with an older or a newer one:

• A connection speaks the older protocol of its two sides. HELLO says the newest the client speaks and WELCOME the one the connection speaks; a server refuses only a client older than the oldest protocol it still speaks. A protocol moves only for what a field cannot carry: frames, the handshake, credit.
• Within a protocol a message grows by fields, and a request is understood whole or refused. A field the server does not know is unimplemented, naming the field and the server's version, so a newer client using something new learns which server to upgrade rather than reading an answer to another question. A client leaves a field out at its zero value, so one using nothing new talks to any server of its protocol.
• An answer grows only by what a client may skip. A field whose meaning a client must know is answered only to a client that asked for it with a field of its request, which an older server refuses.
• A method is added, never repurposed. An older server answers a newer method unimplemented, naming its version. From v0.1.0 on, a message never changes meaning and a field's number is never reused.

A client that finds a sidecar of an older release than its own replaces it:

1. The client sends server.stop. The sidecar answers, lets its running streams finish, and gives back SERVE and LOCK.
2. The client starts its own binary, as it does when no sidecar runs, and prints one line about it on stderr.
3. Every other client of the old sidecar gets GOAWAY and connects to the new sidecar when it connects again.

A client doesn't replace a server that SERVE doesn't call a sidecar, such as a Go program's own server or one that a person runs. It also keeps a sidecar that refuses to stop. In both cases, it prints a warning once on stderr.

#Methods

Each engine's messages are fixed on this page with its slice, before its code: numbers, keys, types, shapes and vectors. A call answers with one message; whatever returns a collection is a download, its items DATA under credit and its last DATA saying where the next page begins. What each will carry:

The values they carry:

• the server's own call carries nothing, {} each way;
• a kv value is nil, an integer or bin, as its row keeps it, a bin's first byte the kind that wrote it (1 text, 2 bytes, 3 JSON, 4 a float's eight bytes), and a version is an opaque bin compared only for equality;
• a job's value is its JSON as str;
• an SQL value is one of SQLite's five: nil, an integer, a float, str or bin;
• a record's attribute keeps its JSON spelling as str;
• a series' samples, and an aggregate's buckets and values, are bin columns.
• a search's document is its JSON as str, and a vector bin, four bytes a little-endian float a dimension.

#the server

The server's own methods take the range below the engines', 0x00xx.

A stop is an admin connection's alone, permission to a data connection, and a server whose program said nothing of stopping refuses it with permission too: a program serving its own store decides when that store's server stops. tinystore serve stops at one, as it does at Ctrl+C, which is how tinystore stop ends a sidecar and how an SDK newer than the sidecar it found replaces it with its own binary, as Versions says.

Only an admin connection can ask for a backup. The server first opens each engine whose file is in the directory. It copies each database that no client has opened, without opening it. Then it sends what the backup package writes: a copy of every engine's file, and a manifest of their sizes and checksums, which a restore checks. files, an array of str, names files of the application's by their paths inside the store's directory, which the zip holds beside the engines' with the engine host; a path outside the directory, or an engine's own, is invalid.

A clock is {1: at, 2: advance}. at is a time in unix milliseconds, and advance is a duration in milliseconds. Only a private server started with tinystore serve --stdio --clock <time> has a clock that moves, and the store runs on it instead of the system's clock. An SDK starts such a server when you open a store with private and clock. Only an admin connection can move the clock, and only forward. The server answers invalid to a time before the clock's, a negative duration, both fields at once, or a clock call to a server that runs on the system's clock.

#kv

kv.open answers a handle on a bucket of values, on counters, on a config, on a limiter, on once's answers or on a quota, and every other call carries it. A handle holds kv.Raw values, so the server reads what any bucket wrote.

A bucket:

A window is {1: name, 2: limit, 3: per}: a key may use up to limit every per milliseconds from its first use, the name [a-z][a-z0-9_]{0,31}.

A handle is {1: uint}. A call:

A key is text: a str, a bin, or an integer, which is its decimal spelling, so that 42 and "42" name one key. The server writes a key as str, or as bin when it is not UTF-8. An entry:

A limiter answers kv.allow with an allowance, {1: ok, 2: left, 3: retry after}: whether the requests pass, how many more would pass now, and how many milliseconds until they would, rounded up, when they do not. More requests than the burst at once are invalid. A quota's allowance adds 4: windows, each {1: name, 2: used, 3: limit, 4: left, 5: reset at} in the order its open gave them, reset at in unix milliseconds and absent for a window not started; its kv.allow counts in every window or in none, and more uses than a window's limit are invalid.

kv.configure is {1: handle, 2: set, 3: reset}, set an array of str, a path and its JSON each, and reset the paths to forget; the server keeps both in one transaction, checking only that a value is JSON within the config's bounds, since the types are the client's. kv.watch answers {}, then {1: changes, 2: fields} a DATA, fields a path and its JSON each, now and after each change, whoever made it: a watcher behind is sent the latest fields, never a state the config did not have. It ends when the client cancels it, when the client's side of the connection ends, or with the server.

kv.run lets one run of a key go at a time, every client's: another kv.run of the key waits until that run ends, then is answered what it kept, or is handed the run when it kept nothing. The client that is handed a run, {} as its RESPONSE, runs its function and sends an entry as its last DATA: found with the value to keep, or not found when the function failed, which keeps nothing. A client that cancels or leaves keeps nothing either, and the next run of the key is handed over again.

A page, a scan's trailer, is {1: more, 2: after}: more says the limit or the page's 4 MiB of values ended it before the branch did, and after is the key the next page begins after. Calls are {1: [call…]}, each call's map holding its method under key 0, and results {1: [entry…]}.

kv.get of token under the owner 7, on handle 1, and its answer:

0e 00 00 00  03  01  02 01  01 00 00 00                                   a body of 14 bytes, REQUEST, END, 0x0102, stream 1
83                                                                        a map of three
   01 01                                                                  handle: 1
   02 91 a1 37                                                            owners: ["7"]
   03 a5 74 6f 6b 65 6e                                                   key: "token"

19 00 00 00  04  01  00 00  01 00 00 00                                   a body of 25 bytes, RESPONSE, END, stream 1
84                                                                        a map of four
   01 c3                                                                  found: true
   02 c4 05 68 65 6c 6c 6f                                                value: bin "hello"
   03 c4 01 31                                                            version: bin "1"
   04 cf 00 00 01 a0 c4 50 6c 00                                          expires: 1,790,000,000,000

#jobs

jobs.open answers a handle on a queue of JSON values, or on a schedule, the queue of one repeating job under its name; every other call carries it. A job's value is its JSON as str, checked before it is kept; a schedule's is {}.

A queue:

A repeat is {1: cron, 2: zone}, five cron fields and the zone's name, or {3: every, 4: spread}, milliseconds, at least a second; spread true runs each key's job at a phase of its own within the interval, which the job's repeat text then shows, @every 30s +6178ms. A job, a batch's item:

A batch is {1: handle, 2: [job…]}; a change is a job's fields with the handle under key 6; a key is {1: handle, 2: key}. An entry:

A job a work loop claimed ahead for a busy worker is waiting, 0 ahead, until a worker has it. A lease is {1: handle, 2: lease}, milliseconds, the queue's when absent. A held job is {1: found, 2: job, 3: key, 4: value, 5: at, 6: attempt, 7: cancelled}, job being the number its outcome names: a claim's lives on its connection until it is settled, and a work stream's on its stream. An outcome:

A progress settles nothing: the job stays in its worker's hands, claimed or on a work stream, and a report that is not JSON is invalid. The server keeps the last one in memory, 4 KiB of JSON at most, a larger one dropped and logged, so the SDKs refuse one past it before it leaves.

Outcomes are {1: [outcome…]} and settled {1: [nil or error…]}; settling a claimed job a cancel took is conflict. A query is {1: handle, 2: prefix, 3: state, 4: after, 5: limit}, state 1, 2 or 3, and a page {1: more, 2: after}, as jobs.Query and jobs.Page are.

Workers are {1: handle, 2: workers, 3: timeout, 4: until idle, 5: cancels}: the queue's own Work loop runs for the stream, workers at once, 1 when absent and at most the streams in flight, each job timeout milliseconds in the client's hands, a minute when absent, and with until idle only until no job is due and none runs, as a test wants it. Each job it hands a handler goes out as a held job; the client settles it by sending its outcome as DATA on the same stream, and ends its side with DATA·END once it takes no more. An extend is not one of those outcomes: the loop extends its leases itself, and ends the stream invalid on one rather than take it as an ack. A progress is, and leaves the job in the client's hands. When that side ends, or the client cancels or leaves, the jobs in its hands fail that attempt, as a worker whose process died fails it, and only after their handlers return does the loop stop, so that the jobs it claimed ahead and never handed over go back uncounted. The server's DATA·END, {}, follows.

A cancel that takes a job in the client's hands sends it again as {2: job, 7: true} on a stream that asked with cancels, so that its handler stops; a stream that did not ask is told nothing. Either way the outcome the client sends for that job settles nothing, and the stream goes on.

A held job's number is its connection's, the same for a claim's and a work stream's, so that jobs.step and jobs.keep name either; a work stream's job is settled on its stream alone, and jobs.settle of one is invalid. An answer names a step of the held job's run:

and kept is {1: found, 2: answer}. A step kept by an attempt whose lease another claim took is conflict, and nothing is kept; a run that ends takes its steps along, and a repeating job's next run starts without them. A worker asks jobs.step before it runs a step and sends jobs.keep once it has, so that the attempt after a retry or a lost worker gets the answer back without running the step again.

jobs.watch answers {}, then the job under the key as an entry a DATA, now and each time its state, place, attempt, time, progress or error changes, and ends after the entry in which the job ended: done, failed or cancelled. A key that names no job ends it at once. A watcher behind a busy queue is sent the latest entry, read at most five times a second, never every change. It follows the job it found, so a later job under the key is another watch's, and it also ends when the client cancels it, when the client's side of the connection ends, or with the server.

#blobs

blobs.open answers a handle on a bucket; every other call carries it, the owners a call names being the folder under the bucket's root it works in.

A bucket is {1: name, 2: default ttl, 3: max size}, milliseconds and bytes. A call:

A method refuses an option it does not take, as the engine's call does. An object:

A total is {1: objects, 2: bytes} and a page {1: more, 2: after}. A put that does not commit leaves nothing: a client that cancels it, a stream shorter or longer than its size, and a connection lost halfway. A get read whole is checked against the object's hash, and one whose bytes changed ends with DATA·END·ERROR and corrupt instead of its last bytes; a range is not checked.

#sql

sql.open answers a handle on a database by its name, and every other call carries it. The first open of a name in the server opens it: an admin connection's applies the migrations it carries, and a data connection's finds them applied, or is refused with permission and makes no file. A database opens once a store, so every later open, and an open of a database the embedding program passed the server, checks the migrations it carries against those the file applied: one the file has not applied is permission for a data connection and in_use for an admin one, since a database applies its migrations as it opens, and one changed after it was applied is invalid. A first open without migrations is invalid; a later one may carry none.

A database:

A statement:

An argument is nil, an integer, a float, str, bin, or a bool, which SQLite keeps as 1 or 0; a NaN is invalid, since SQLite would keep NULL. A value that comes back is one of SQLite's five, nil, an integer, a float, str or bin, bin also carrying TEXT that is not UTF-8, and it is what the row keeps: a time held as text travels as its text, whatever its column declares.

Done is {1: changes, 2: last id}, the columns {1: [name…]} and a row {1: [value…]}. Statements are {1: handle, 2: [statement…], 3: read, 4: [jobs…], 5: [kv…]} and their results {1: [result…]}, a result being done, or {3: columns, 4: [[value…]…]} for a statement that returned rows.

Each item of jobs has the shape of an enqueue's request, {1: handle, 2: [job…]}, and its queue must be opened in this database. The transaction writes the jobs after the statements, so a job commits with the rows it is about, or not at all. A job has no result. When a job fails, what names it as call, counted after the statements. A job in a view, or on a queue that lives in another file, is invalid.

Each item of kv is {1: handle, 2: [call…]}, with the calls of kv.batch: each has its method under key 0 and the fields of a KV call. Its outer handle identifies the bucket. The calls may set, delete or clear keys in a bucket opened in this database, and run after the statements and jobs. A key change has no result. A read, a set-if-absent, a change in a view, or a bucket in another file is invalid. A failure's what.call counts key changes after the statements and jobs.

A message past the agreed body is limit: a row a query downloads, or a batch's results, which travel in one message. A query holds its rows in the server's memory, 64 MiB of them at most, before the first leaves.

A data connection's statement, each of a batch's included, runs only once the check server.md describes lets it, and one it refuses is permission; it runs 30 seconds at most, past which it is limit. An admin connection's runs as it is.

sql.exec of an insert on handle 1, and its answer:

31 00 00 00  03  01  02 04  03 00 00 00                                   a body of 49 bytes, REQUEST, END, 0x0402, stream 3
83                                                                        a map of three
   01 01                                                                  handle: 1
   02 d9 24 69 6e 73 65 72 74 20 69 6e 74 6f 20 6e 6f 74 65 73 20 28 74   sql: "insert into notes (title) values (?)"
      69 74 6c 65 29 20 76 61 6c 75 65 73 20 28 3f 29
   03 91 a4 6d 69 6c 6b                                                   args: ["milk"]

05 00 00 00  04  01  00 00  03 00 00 00                                   a body of 5 bytes, RESPONSE, END, stream 3
82                                                                        a map of two
   01 01                                                                  changes: 1
   02 07                                                                  last id: 7

#records

Records are one log of the store's, and each call names the streams it is about, so none opens a handle.

A record:

["user", "42", "tags", "[\"a\"]"] is two fields, user and tags, whose values are JSON spelled as they were given, 1.2300, -0 and a big integer coming back byte for byte; keys keep their order and may repeat. A text, a stream, a name, a body, a key or a value, whose bytes are not UTF-8, as another program's output may be, travels as bin and comes back byte for byte.

A query:

A page, a read's trailer, is {1: more, 2: from, 3: to}: more says the limit or the budget ended the page before the range did, and from and to are the range the next page reads, the query's own with one end moved past this page. A page never splits a timestamp; more records at one time than a page holds is limit.

A cursor is {1: segment, 2: row, 3: limit, 4: expired}: follow's request names the place the records it asks for begin at, {} being the oldest segment kept, and the records it takes at most; its trailer the place the next follow begins at, and the segments retention or a drop removed before the cursor reached them. A record reaches follow once its head is sealed, a segment's worth or the server's seal age, an hour unless it says otherwise, after it arrived; read sees it at once.

records.lines is {1: stream}, then the program's output in DATA frames: each line becomes a record of the stream as Go's Lines makes it, a stack trace's lines joined, a JSON or logfmt line's fields kept, its level found where its program writes it. The upload's end hands over the record the writer holds, a line cut short included, and its answer follows; a line longer than a record holds is dropped and counted in the engine's stats.

A damage is {1: stream, 2: segment, 3: head row, 4: from, 5: to, 6: reason}: a sealed segment, dropped whole, or a head row, the other absent; the times it held, unix nanoseconds; the invariant its bytes broke. A read or a follow that meets one ends with corrupt, its what naming it by the same names, segment or head row, stream, from, to and reason, and a drop of one that still reads is conflict.

records.append of one click on stream 5:

2a 00 00 00  03  01  01 05  05 00 00 00                                   a body of 42 bytes, REQUEST, END, 0x0501, stream 5
81                                                                        a map of one
   01 91                                                                  records: an array of one
      84                                                                  a map of four
         01 cf 18 d7 5b 84 2b 4e cd 15                                    at: 1,790,000,000,123,456,789 ns
         02 a3 77 65 62                                                   stream: "web"
         03 a5 63 6c 69 63 6b                                             name: "click"
         09 92 a7 65 6c 65 6d 65 6e 74 a5 22 62 75 79 22                  attrs: ["element", "\"buy\""]

#metrics

Metrics are one store of series, each named by its labels, so none opens a handle.

A description is what a metric's name means. It belongs to the name, and every series of the name shares it:

A describe with neither a unit nor help removes the name's description.

A plan is what a read, or an aggregate when the range names an operation, would spend, found in one snapshot from the series, their block directories and their heads, with no payload fetched and no sample decoded:

A series:

The wire carries a series' name as the store keeps it, its label __name__; the Go API and every SDK give it apart from the labels, as name, and refuse a label of the application's beginning with __.

The two columns hold as many values each. A series longer than half a body holds comes in several DATA, one after another, each with its labels and kind, its samples going on in time order; a client joins them. Ingest keeps the value given last for a time repeated.

A range:

A condition:

A range finds its series by a matcher, a one_of or a prefix: a range of none_of alone is invalid, since it would scan every series. A condition of a kind the server does not have is unimplemented, what naming it, as is an operation, what naming it as op.

The server reads a range whole, within its limits, before the first series leaves, so that a slow client holds none of the engine's readers; a read or an aggregate that fails sends no series.

An aggregate's item is a series, keys 1 and 2, and its buckets as columns, as many values each:

An increase, a rate and a delta count each step between samples in the bucket where it ends, the first bucket's from the last sample up to the lookback before from, so the buckets add up to the range; only a bucket holding samples is answered.

Drop removes one series and everything it holds, whether it still reads or not, the labels naming it exactly; unreadable groups counts the groups removed without the payload rows their directory no longer names.

metrics.ingest of one sample of cpu{host="web-1"} on stream 9:

3b 00 00 00  03  01  01 06  09 00 00 00                                   a body of 59 bytes, REQUEST, END, 0x0601, stream 9
81                                                                        a map of one
   01 91                                                                  series: an array of one
      84                                                                  a map of four
         01 82                                                            labels: a map of two names
            a8 5f 5f 6e 61 6d 65 5f 5f a3 63 70 75                        __name__: "cpu"
            a4 68 6f 73 74 a5 77 65 62 2d 31                              host: "web-1"
         02 a5 67 61 75 67 65                                             kind: "gauge"
         03 c4 08 00 6c 50 c4 a0 01 00 00                                 times: [1,790,000,000,000]
         04 c4 08 00 00 00 00 00 00 e0 3f                                 values: [0.5]

#search

An index opens a handle, as a bucket does; its documents are JSON as str, and a vector is bin, its floats little-endian, four bytes a dimension. protocol/search.wire holds every message.

A set on an index with vectors gives vector, or noVector: true for a document only its words find; one that says neither is invalid.

A table's index opens with database, a handle sql.open gave, and table, with key and vectorColumn where it needs them: its fields and filters are columns of the table. Its search answers columns once and each hit's row, a cell a column, as sql.Rows carries rows, and value null. A set, setMany, delete or get on it is invalid, since the table owns the rows, and dropIndex names the database beside the name.

search's where

A search's where is a JSON list of conditions, every one of which a document passes, as the Bun SDK writes its where object:

A value is text, a number or a boolean: the text "50" never passes for the number 50, and an integer past 2⁵³ is written as its digits and matched exactly. A path the index was not opened with is invalid.