Module keyspec 

Where a command’s keys are, and what it does to each of them.

Why the old triple was not enough

Until now the answer was three numbers on every table row: the first argument that is a key, the last, and how far apart they sit. That triple is Redis’s own legacy answer, it is what COMMAND INFO has reported since 2.8, and it is wrong often enough to matter. ZUNIONSTORE dst 2 a b has three keys and the triple names one of them. XREAD COUNT 2 STREAMS a b 0 0 has two and the triple names none. SORT k STORE d has two and the triple names one.

Nothing minded very much while the only caller was COMMAND GETKEYS, where a wrong answer is a cluster client routing to the wrong node and a real but distant problem. The ACL is a different matter. A user given ~cache:* and nothing else must not be able to reach secret through ZUNIONSTORE, and a permission check built on a key finder that misses keys is not a permission check. So this is the model Redis replaced the triple with in 7.0, copied rather than approximated, and the triple stays beside it because COMMAND INFO still reports it.

The model

A command has a list of key specs and each one is two questions. Where does this run of keys start, which is Begin, and how far does it go, which is Find. ZUNIONSTORE has two: one key at argument one, and a counted run starting at argument two. SMOVE has two, one for each end of the move, which is how the source can be a delete and the destination an insert.

Beside them are the flags, and those are the half the ACL reads. RO, RW, OW and RM say how the value is touched, and access, update, insert and delete say what a caller has to be allowed to do: a key with access needs read permission and a key with any of the other three needs write permission. That is why SET k v needs only write while INCR k needs both, which is not a rule anybody would guess and is not derivable from the command flags. It comes off the reference one command at a time.

What incomplete means

Three specs cannot be trusted on their own and say so. SORT’s BY, GET and STORE keys are Begin::Unknown, because the first two are patterns that name keys only after the sorted value has been read and the third can appear anywhere. XREAD and XREADGROUP look for the word STREAMS, which a stream could be called. MIGRATE and the two GEORADIUS writes look for a keyword that may appear twice.

A spec carrying incomplete, or one whose search is unknown, means the answer this module gives is a floor rather than the whole of it. COMMAND GETKEYS fills the rest in per command, and the ACL treats a command with one as needing permission over every key, which is the safe way round: a user who may reach every key is allowed and one who may not is refused.

Structs

Access

What a caller has to be allowed to do with a key.

KeySpec

One run of keys in a command’s arguments.

Run

One run of keys, resolved against the arguments a client actually sent.

Enums

Begin

Where a run of keys starts.

Find

How far a run of keys goes.

Constants

BITFIELD_KEY

This command allows both access and modification of the key

BYMEMBER_STORE

Incomplete because duplicate STORE options use last-wins; fall back to georadiusGetKeys

BYMEMBER_STOREDIST

Incomplete because duplicate STOREDIST options use last-wins; fall back to georadiusGetKeys

DELEX_KEY

RW, delete, variable_flags.

GEORADIUS_STORE

Incomplete because duplicate STORE options use last-wins; fall back to georadiusGetKeys

GEORADIUS_STOREDIST

Incomplete because duplicate STOREDIST options use last-wins; fall back to georadiusGetKeys

MIGRATE_KEYS

RW, access, delete, incomplete.

NOT_KEY_AT1

not_key.

NOT_KEY_AT1_RM1_1_0

not_key.

OW_INSERT_AT1

OW, insert.

OW_INSERT_AT2

OW, insert.

OW_INSERT_AT1_RM1_2_0

OW, insert.

OW_UPDATE_AT1

OW, update.

OW_UPDATE_AT2

OW, update.

OW_UPDATE_AT1_COUNTED

OW, update.

OW_UPDATE_AT1_RM1_2_0

OW, update.

RM_DELETE_AT1_RM1_1_0

RM, delete.

RO_ACCESS_AT1

RO, access.

RO_ACCESS_AT2

RO, access.

RO_ACCESS_AT1_COUNTED

RO, access.

RO_ACCESS_AT1_R1_1_0

RO, access.

RO_ACCESS_AT1_RM1_1_0

RO, access.

RO_ACCESS_AT1_RM2_1_0

RO, access.

RO_ACCESS_AT2_COUNTED

RO, access.

RO_ACCESS_AT2_RM1_1_0

RO, access.

RO_ACCESS_AT3_RM1_1_0

RO, access.

RO_AT1

RO.

RO_AT2

RO.

RO_AT1_RM1_1_0

RO.

RW_ACCESS_AT2

RW, access.

RW_ACCESS_AT1_RM1_1_0

RW because it may change the internal representation of the key, and propagate to replicas

RW_ACCESS_DELETE_AT1

RW, access, delete.

RW_ACCESS_DELETE_AT3

RW, access, delete.

RW_ACCESS_DELETE_AT1_COUNTED

RW, access, delete.

RW_ACCESS_DELETE_AT1_RM2_1_0

RW, access, delete.

RW_ACCESS_DELETE_AT2_COUNTED

RW, access, delete.

RW_ACCESS_INSERT_AT1

RW, access, insert.

RW_ACCESS_UPDATE_AT1

RW, access, update.

RW_ACCESS_UPDATE_AT2

RW, access, update.

RW_ACCESS_UPDATE_AT1_R1_1_0

RW, access, update.

RW_ACCESS_UPDATE_AT1_RM1_3_0

RW, access, update.

RW_ACCESS_UPDATE_AT1_TTL

RW and UPDATE because it changes the TTL

RW_ACCESS_UPDATE_AT2_COUNTED

RW, access, update.

RW_DELETE_AT1

RW, delete.

RW_DELETE_AT2

RW, delete.

RW_INSERT_AT1

RW, insert.

RW_INSERT_AT2

RW, insert.

RW_UPDATE_AT1

RW, update.

RW_UPDATE_AT2

RW, update.

RW_UPDATE_AT1_TRIMMING

UPDATE instead of INSERT because of the optional trimming feature

RW_UPDATE_DELETE_AT1

RW, update, delete.

SCRIPT_KEYS_RO

We cannot tell how the keys will be used so we assume the worst, RO and ACCESS

SCRIPT_KEYS_RW

We cannot tell how the keys will be used so we assume the worst, RW and UPDATE

SET_KEY

RW and ACCESS due to the optional GET argument

SORT_BY_AND_GET

For the optional BY/GET keyword. It is marked ‘unknown’ because the key names derive from the content of the key we sort

SORT_STORE

For the optional STORE keyword. It is marked ‘unknown’ because the keyword can appear anywhere in the argument array

XREADGROUP_STREAMS

Incomplete because a consumer/group named STREAMS (or options before GROUP) can shift the STREAMS keyword; fall back to xreadGetKeys

XREAD_STREAMS

Incomplete because a stream key named STREAMS (or options before it) can shift the STREAMS keyword; fall back to xreadGetKeys

Functions

access_of

What a caller needs over a key carrying flags.

find

Every key spec names in args, handed to each a run at a time.

of_sub

The key specs for container sub, empty for a subcommand that has none.

takes_keys

Whether this command ever names a key, whatever it is sent.