In-memory server for agentsPostino Port 2790 v0.1.0

Reference

Command reference

Every command is an array: the name (case does not matter), then its arguments. Send it to POST /api/db, the db MCP tool, or postino db. Arguments may be strings or numbers. Keys and values are text: a JSON string holds any Unicode text but not arbitrary bytes, so encode binary data first, as base64 say.

Square brackets mark optional parts, | separates alternatives, and ... means the previous part repeats.

Replies

ReplyJSONCLI
status"OK"OK
text"value"value
integer3(integer) 3
nothingnull(nil)
list["a", "b"]numbered lines
field-value map{"field": "value"}field: "value" lines
errorHTTP 400, {"ok": false, "error": "..."}(error) ...

Errors begin with a code word: ERR for invalid usage, WRONGTYPE when the key holds another type, NOGROUP when a consumer group is missing, BUSYGROUP when it already exists, OOM when a limit or the memory limit is reached, IOERR (HTTP 503) when the journal can't be written, READONLY (HTTP 503) when a request failed partway through a change and the server takes no more until it restarts, and NOPERM when a key or channel is outside the token's scope or the command needs the administrator token.

A command that fails changes nothing. A move whose destination can't take the element leaves it in the source, and an MSET that would pass the key limit writes none of its keys. The one exception is a write made as the journal starts failing, on a full disk say: its change is made, and reaches the disk once the disk takes it. What it returned still comes back, so the item an LPOP removed isn't lost: in the result of an IOERR response, or as an ordinary reply when the server was journaling it together with other changes. The writes after it are refused until the disk takes them.

A response carries at most 64 MiB. A read that would return more, alone or with the rest of its batch, fails instead, so read big collections in parts with a range, COUNT, or SCAN. Commands that remove what they return, such as LPOP with a count or XREADGROUP with >, always return it.

Keys

CommandReply
DEL key [key ...], UNLINK key [key ...]number of keys removed
EXISTS key [key ...]number of the keys that exist
TYPE keystring, list, hash, set, zset, stream, or none
EXPIRE key seconds [NX | XX | GT | LT]1 if the expiry was set, 0 otherwise
PEXPIRE key milliseconds [NX | XX | GT | LT]as EXPIRE
EXPIREAT key unix-seconds [...], PEXPIREAT key unix-ms [...]as EXPIRE
TTL key, PTTL keyseconds or milliseconds left; -1 without expiry; -2 if missing
EXPIRETIME key, PEXPIRETIME keythe expiry as a Unix time; -1 or -2 as above
PERSIST key1 if an expiry was removed
RENAME key newkeyOK; replaces newkey
RENAMENX key newkey1, or 0 if newkey exists
KEYS patternmatching key names, in order; a pattern with a fixed start such as task:* visits only those keys. Sent alone it looks at a thousand keys at a time, letting other requests run in between, so a key added or removed meanwhile may or may not be listed; in a batch it runs whole, and fails past 10,000 keys
SCAN cursor [MATCH pattern] [COUNT n] [TYPE type][next-cursor, [keys...]]; start with 0, pass back the cursor you get, and stop when it is 0 again. Each call takes the next COUNT keys (10 by default, 1,000 at most), which MATCH and TYPE then choose among
DBSIZEnumber of keys; one that has just expired may count until the server removes it, usually within a second
FLUSHDB, FLUSHALLOK; removes every key (administrator only)

Sent alone, KEYS, SCAN, and DBSIZE for a token with a scope look at a thousand keys at a time, counting the keys they pass over out of the token's reach, and let other requests run in between. In a batch, which runs whole, they fail past 10,000 keys.

NX sets an expiry only when there is none, XX only when there is one, GT only if the new one is later, LT only if earlier. An expiry in the past deletes the key. An expiry that doesn't fit in 64 bits of milliseconds fails with ERR invalid expire time.

Patterns use *, ?, [abc], [^a], [a-z], and \ to escape; a [ that is never closed matches nothing. A pattern is at most 256 bytes. Matching takes time proportional to the key, whatever the pattern.

Strings and counters

CommandReply
GET keythe value, or null
SET key value [NX | XX | IFEQ current] [GET] [EX s | PX ms | EXAT ts | PXAT ms-ts | KEEPTTL]OK, or null if a condition failed; with GET, the old value
SETNX key value1 if set, 0 if the key exists
SETEX key seconds value, PSETEX key ms valueOK
GETSET key valuethe old value
GETDEL keythe value, then deletes the key
GETEX key [EX s | PX ms | EXAT ts | PXAT ms-ts | PERSIST]the value, changing its expiry
MGET key [key ...]values, with null for missing keys
MSET key value [key value ...]OK
MSETNX key value [key value ...]1 if all were set, 0 if any key existed (then none is set)
APPEND key valuethe new length
STRLEN keythe length in bytes
INCR key, DECR keythe new value
INCRBY key n, DECRBY key nthe new value
INCRBYFLOAT key nthe new value as text
DELIFEQ key value1 if the key held exactly value and was deleted, otherwise 0

IFEQ and DELIFEQ make compare-and-set and safe lock release a single command. SET without KEEPTTL clears an existing expiry. Values are limited to 16 MiB. Counters are 64-bit signed integers.

Hashes

CommandReply
HSET key field value [field value ...]number of new fields
HMSET key field value [field value ...]OK
HSETNX key field value1 if set, 0 if the field exists
HGET key fieldthe value, or null
HMGET key field [field ...]values, with null for missing fields
HGETALL keya map of every field
HDEL key field [field ...]number of fields removed
HEXISTS key field1 or 0
HLEN keynumber of fields
HKEYS key, HVALS keyfield names or values, sorted by field
HINCRBY key field nthe new value
HINCRBYFLOAT key field nthe new value as text

Lists

CommandReply
LPUSH key value [value ...], RPUSH key value [value ...]the new length
LPUSHX key value [...], RPUSHX key value [...]the new length, or 0 if the list does not exist
LPOP key [count], RPOP key [count]the value (or a list with count), null if empty
LLEN keythe length
LRANGE key start stopthe elements in the range; negative indexes count from the end
LINDEX key indexthe element, or null
LSET key index valueOK
LREM key count valuenumber removed: the first count matches, the last ones if negative, all if 0
LTRIM key start stopOK; keeps only the range
LINSERT key BEFORE | AFTER pivot valuethe new length, or -1 if pivot is missing
LMOVE source destination LEFT | RIGHT LEFT | RIGHTthe moved element, or null
RPOPLPUSH source destinationas LMOVE source destination RIGHT LEFT
BLPOP key [key ...] timeout, BRPOP key [key ...] timeout[key, value] from the first non-empty list, or null after timeout seconds
BLMOVE source destination LEFT | RIGHT LEFT | RIGHT timeoutthe moved element, or null

Sets

CommandReply
SADD key member [member ...]number of new members
SREM key member [member ...]number removed
SMEMBERS keyevery member, sorted
SISMEMBER key member1 or 0
SMISMEMBER key member [member ...]1 or 0 for each
SCARD keynumber of members
SPOP key [count]removes and returns random members
SRANDMEMBER key [count]random members without removing them; a negative count allows repeats, up to POSTINO_MAX_ELEMENTS of them
SINTER key [key ...], SUNION key [key ...], SDIFF key [key ...]the intersection, union, or difference
SMOVE source destination member1 if moved, or if the member is already in a set moved onto itself

Sorted sets

CommandReply
ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member ...]number added (with CH, added or changed); with INCR, the new score
ZREM key member [member ...]number removed
ZSCORE key memberthe score, or null
ZMSCORE key member [member ...]the scores
ZINCRBY key increment memberthe new score
ZCARD keynumber of members
ZCOUNT key min maxmembers with a score in the range
ZRANK key member, ZREVRANK key memberthe position from the lowest or the highest score
ZRANGE key start stop [BYSCORE] [REV] [LIMIT offset count] [WITHSCORES]members by position, or by score with BYSCORE
ZREVRANGE key start stop [WITHSCORES]members by position, highest first
ZRANGEBYSCORE key min max [WITHSCORES] [LIMIT offset count]members by score
ZREVRANGEBYSCORE key max min [WITHSCORES] [LIMIT offset count]members by score, highest first
ZPOPMIN key [count], ZPOPMAX key [count][member, score, ...]
BZPOPMIN key [key ...] timeout, BZPOPMAX key [key ...] timeout[key, member, score], or null after timeout seconds
ZREMRANGEBYSCORE key min maxnumber removed
ZREMRANGEBYRANK key start stopnumber removed

Members with equal scores are ordered by name. Score bounds accept -inf, +inf, and ( before a number to exclude it. With REV, ZRANGE ... BYSCORE takes the maximum first.

Score ranges visit only the members in range. Ranks are counted from the lowest score, so ZRANK, ZREVRANK, ZRANGE by index, and ZREMRANGEBYRANK take time in proportion to the rank they reach.

Streams

CommandReply
XADD key [NOMKSTREAM] [MAXLEN | MINID [= | ~] threshold] * | id field value [field value ...]the new entry's id
XLEN keynumber of entries
XRANGE key start end [COUNT n][[id, [field, value, ...]], ...], oldest first
XREVRANGE key end start [COUNT n]the same, newest first
XDEL key id [id ...]number removed
XTRIM key MAXLEN | MINID [= | ~] thresholdnumber removed
XREAD [COUNT n] [BLOCK ms] STREAMS key [key ...] id [id ...][[key, entries], ...] after each id, or null
XGROUP CREATE key group id | $ [MKSTREAM]OK
XGROUP SETID key group id | $OK
XGROUP DESTROY key group1 if removed
XGROUP CREATECONSUMER key group consumer1 if created
XGROUP DELCONSUMER key group consumernumber of pending entries it held
XREADGROUP GROUP group consumer [COUNT n] [BLOCK ms] [NOACK] STREAMS key [key ...] id [id ...]as XREAD
XACK key group id [id ...]number acknowledged
XPENDING key group[count, first-id, last-id, [[consumer, count], ...]]
XPENDING key group [IDLE ms] start end count [consumer][[id, consumer, idle-ms, deliveries], ...]
XCLAIM key group consumer min-idle-ms id [id ...] [IDLE ms] [TIME ms] [RETRYCOUNT n] [FORCE] [JUSTID]the claimed entries (or ids)
XAUTOCLAIM key group consumer min-idle-ms start [COUNT n] [JUSTID][next-start, claimed, deleted-ids]
XINFO STREAM keya map: length, last id, entries added, groups, first and last entry
XINFO GROUPS keya map per group: consumers, pending, last delivered id, lag
XINFO CONSUMERS key groupa map per consumer: pending, idle, inactive
XINFO HELPthe XINFO subcommands

Ids are <milliseconds>-<sequence>. In XADD, * generates the next id and <ms>-* generates the sequence. In ranges, - and + are the smallest and largest ids, an id without a sequence covers that whole millisecond, and ( excludes the id. In XREAD, $ means the newest entry at the time of the call.

In XREADGROUP, the id > asks for entries no member of the group has received. They become pending for this consumer until acknowledged, unless NOACK is given. Any other id replays this consumer's pending entries after it, which is how a restarted worker recovers what it had started. Groups and their consumers are created and tracked per stream; reading creates the consumer. Each stream may be named once per command.

MAXLEN and MINID trim exactly; ~ is accepted and behaves like =. XADD checks the stream's length after the trim against POSTINO_MAX_ELEMENTS, so a MAXLEN above the limit doesn't get around it. The largest id is 18446744073709551615-18446744073709551615; once a stream holds it, XADD with * fails.

A consumer's idle time, reported by XINFO CONSUMERS, isn't journaled when a read delivers nothing new. After a restart it counts from the consumer's last change.

Channels

CommandReply
PUBLISH channel messagenumber of subscribers that received it
PUBSUB CHANNELS [pattern]channels with at least one subscriber
PUBSUB NUMSUB [channel ...][channel, count, ...]
PUBSUB NUMPATnumber of pattern subscriptions; for a scoped token, those of clients with the same scope

Channel names and patterns are at most 256 bytes. Subscribing is a long-lived connection: GET /api/subscribe (see HTTP API) or postino subscribe.

Server

CommandReply
PING [message]PONG, or the message
ECHO messagethe message
TIME[unix-seconds, microseconds]
INFOa map: version, keys, keys with an expiry, streams, approximate bytes (a big collection's estimated from its first 128 elements), subscriptions, agents, rooms; like KEYS, it looks at a thousand keys at a time sent alone, and fails past 10,000 in a batch
COMMANDthe names of every command
COMMAND COUNThow many there are

Blocking

BLPOP, BRPOP, BLMOVE, BZPOPMIN, BZPOPMAX, XREAD BLOCK, and XREADGROUP BLOCK (with >) wait when there is nothing to return. Their timeout is in seconds, except BLOCK, which takes milliseconds; a fraction of a second is rounded up to the next millisecond. A timeout of 0 waits as long as the transport allows, which over HTTP and MCP is 60 seconds. Inside an atomic batch they never wait.