Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/man-page-build-install.yml
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,12 @@ jobs:
repository: valkey-io/valkey-search
path: valkey-search

- name: Checkout valkey-large-object
uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
with:
repository: valkey-io/valkey-large-object
path: valkey-large-object

- name: Checkout valkey-json
uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
with:
Expand All @@ -111,6 +117,7 @@ jobs:
VALKEY_BLOOM_ROOT=$GITHUB_WORKSPACE/valkey-bloom \
VALKEY_JSON_ROOT=$GITHUB_WORKSPACE/valkey-json \
VALKEY_SEARCH_ROOT=$GITHUB_WORKSPACE/valkey-search \
VALKEY_LARGE_OBJECT_ROOT=$GITHUB_WORKSPACE/valkey-large-object \
-j;

- name: Verify man pages build
Expand Down
16 changes: 12 additions & 4 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ VALKEY_ROOT ?= ../valkey
VALKEY_BLOOM_ROOT ?= ../valkey-bloom
VALKEY_JSON_ROOT ?= ../valkey-json
VALKEY_SEARCH_ROOT ?= ../valkey-search
VALKEY_LARGE_OBJECT_ROOT ?= ../valkey-large-object

# Where to install man pages
INSTALL_MAN_DIR ?= /usr/local/share/man
Expand Down Expand Up @@ -45,6 +46,10 @@ ifeq ("$(wildcard $(VALKEY_SEARCH_ROOT))","")
$(info Valkey Search variable pointed to nothing, skipping valkey-search commands)
endif

ifeq ("$(wildcard $(VALKEY_LARGE_OBJECT_ROOT))","")
$(info Valkey Large Object variable pointed to nothing, skipping valkey-large-object commands)
endif

ifeq ("$(shell which pandoc)","")
$(error Please install pandoc)
endif
Expand Down Expand Up @@ -73,10 +78,12 @@ commands_json_files = $(wildcard $(VALKEY_ROOT)/src/commands/*.json)
bloom_commands_json_files = $(wildcard $(VALKEY_BLOOM_ROOT)/src/commands/*.json)
valkey_json_commands_json_files = $(wildcard $(VALKEY_JSON_ROOT)/src/commands/*.json)
valkey_search_commands_json_files = $(wildcard $(VALKEY_SEARCH_ROOT)/src/commands/*.json)
valkey_large_object_commands_json_files = $(wildcard $(VALKEY_LARGE_OBJECT_ROOT)/src/commands/*.json)
existing_commands = $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md) \
$(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md) \
$(valkey_json_commands_json_files:$(VALKEY_JSON_ROOT)/src/commands/%.json=commands/%.md) \
$(valkey_search_commands_json_files:$(VALKEY_SEARCH_ROOT)/src/commands/%.json=commands/%.md)
$(valkey_search_commands_json_files:$(VALKEY_SEARCH_ROOT)/src/commands/%.json=commands/%.md) \
$(valkey_large_object_commands_json_files:$(VALKEY_LARGE_OBJECT_ROOT)/src/commands/%.json=commands/%.md)

topics = $(wildcard topics/*)
commands = $(filter $(existing_commands),$(documented_commands))
Expand All @@ -91,7 +98,8 @@ json_for_documented_commands = \
$(patsubst commands/%.md,$(VALKEY_ROOT)/src/commands/%.json,$(filter $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \
$(patsubst commands/%.md,$(VALKEY_BLOOM_ROOT)/src/commands/%.json,$(filter $(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \
$(patsubst commands/%.md,$(VALKEY_JSON_ROOT)/src/commands/%.json,$(filter $(valkey_json_commands_json_files:$(VALKEY_JSON_ROOT)/src/commands/%.json=commands/%.md),$(commands)))\
$(patsubst commands/%.md,$(VALKEY_SEARCH_ROOT)/src/commands/%.json,$(filter $(valkey_search_commands_json_files:$(VALKEY_SEARCH_ROOT)/src/commands/%.json=commands/%.md),$(commands)))
$(patsubst commands/%.md,$(VALKEY_SEARCH_ROOT)/src/commands/%.json,$(filter $(valkey_search_commands_json_files:$(VALKEY_SEARCH_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \
$(patsubst commands/%.md,$(VALKEY_LARGE_OBJECT_ROOT)/src/commands/%.json,$(filter $(valkey_large_object_commands_json_files:$(VALKEY_LARGE_OBJECT_ROOT)/src/commands/%.json=commands/%.md),$(commands)))

$(BUILD_DIR)/.commands-per-group.json: $(VALKEY_ROOT)/src/commands/. utils/build-command-groups.py | $(BUILD_DIR)
utils/build-command-groups.py $(json_for_documented_commands) > $@~~
Expand Down Expand Up @@ -175,7 +183,7 @@ programs = $(progs:valkey-%=topics/%.md)
configs = topics/valkey.conf.md

# Define the base directories where valkey commands can come from
VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_BLOOM_ROOT) $(VALKEY_SEARCH_ROOT)
VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_BLOOM_ROOT) $(VALKEY_SEARCH_ROOT) $(VALKEY_LARGE_OBJECT_ROOT)

man1_src = $(filter $(programs),$(topics_md))
man3_src = $(commands)
Expand Down Expand Up @@ -205,7 +213,7 @@ $(MAN_DIR)/man1/valkey-%.1.gz: topics/%.md $(man_scripts)
--version $(VERSION) --date $(DATE) \$< \
| utils/links-to-man.py - | $(to_man) > $@
$(MAN_DIR)/man3/%.3valkey.gz: commands/%.md $(BUILD_DIR)/.commands-per-group.json $(man_scripts)
$(eval VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_JSON_ROOT) $(VALKEY_BLOOM_ROOT) $(VALKEY_SEARCH_ROOT))
$(eval VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_JSON_ROOT) $(VALKEY_BLOOM_ROOT) $(VALKEY_SEARCH_ROOT) $(VALKEY_LARGE_OBJECT_ROOT))
$(eval FINAL_ROOT := $(firstword $(foreach root,$(VALKEY_ROOTS),$(if $(wildcard $(root)/src/commands/$*.json),$(root)))))
$(if $(FINAL_ROOT),,$(eval FINAL_ROOT := $(lastword $(VALKEY_ROOTS))))
utils/preprocess-markdown.py --man --page-type command \
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,14 @@ This repo comes with a Makefile to build and install man pages.
```bash
make VALKEY_ROOT=path/to/valkey VALKEY_BLOOM_ROOT=path/to/valkey-bloom \
VALKEY_JSON_ROOT=path/to/valkey-json VALKEY_SEARCH_ROOT=path/to/valkey-search \
VALKEY_LARGE_OBJECT_ROOT=path/to/valkey-large-object \
sudo make install INSTALL_MAN_DIR=/usr/local/share/man
```

Prerequisites: GNU Make, Python 3, Python 3 YAML (pyyaml), Pandoc.
Additionally, the scripts need access to the valkey code repo,
where metadata files about the commands are stored. Additionally,
access to `valkey-bloom`, `valkey-json` and `valkey-search` repos is optional.
access to `valkey-bloom`, `valkey-json`, `valkey-search` and `valkey-large-object` repos is optional.

The pages are generated under `_build/man/` by default. The default install
location is `/usr/local/share/man` (in the appropriate subdirectories).
Expand Down
59 changes: 59 additions & 0 deletions commands/blob.info.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
Returns metadata about the large object stored at `key`.
The command does not transfer the payload.

If you do not give a field, the command returns all the fields as a flat array of field names and values.
If you give one field, the command returns only the value of that field.
The field name is not case-sensitive.

The fields are:

* `LEN` - The length of the object, in bytes, as the client stored it.
It does not include DRAM allocation overhead (`Dram` mode) or file system overhead (`Tiered` mode).
* `CRC` - The CRC32C (Castagnoli) checksum of the payload, as an unsigned 32-bit integer.
The server calculates this value when it stores the object.
* `TIER` - The storage tier of the object: `dram` or `disk`.

In the `Dram` operating mode, `TIER` is always `dram`.
In the `Tiered` operating mode, `TIER` is `dram` only when a cached copy of the object is ready in DRAM.
Otherwise, `TIER` is `disk`.
For more information about the operating modes, see [Valkey Large Object - Overview](../topics/large-object.md).

If `key` does not exist, the command returns nil.
If `key` holds a value of a different type, the command returns a `WRONGTYPE` error.

Clients can compare `LEN` and `CRC` with the values that [`BLOB.RDMA_GET`](blob.rdma_get.md) returns, or with a checksum that they calculate after [`BLOB.TCP_GET`](blob.tcp_get.md).

## Reply

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Not doc related) Although I don't think it's documented anywhere. Is there a reason the return type here changes depending on requests? This makes client logic more

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, it makes client code harder. There is no strong reason for it. valkey-io/valkey-large-object#214 covers it: either remove the field argument or always return a map with the requested fields. The docs describe the current behavior.


One of the following:

* Array: when no field is given, a flat array of field names and values: `len` and the object length as an integer, `crc` and the CRC32C checksum as an integer, and `tier` and the storage tier (`dram` or `disk`).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A map would be the more reasonable response type here.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. Today the module returns a flat array, also in RESP3 (valkey-cli -3 shows the same 6-element array). This is an API change in the module, so I opened valkey-io/valkey-large-object#214 to return a map. The docs describe the current reply until that change ships.

* Integer: the object length in bytes when `LEN` is given, or the CRC32C checksum when `CRC` is given.
* `dram` or `disk`: the storage tier when `TIER` is given.
* Null: if the key does not exist.

An error occurs if the field is not valid, if `largeobj.enabled` is `no`, or if the key holds a value of a different type.

## Examples

```
127.0.0.1:6379> BLOB.TCP_SET mykey "hello world"
OK
127.0.0.1:6379> BLOB.INFO mykey
1) len
2) (integer) 11
3) crc
4) (integer) 3381945770
5) tier
6) dram
127.0.0.1:6379> BLOB.INFO mykey LEN
(integer) 11
127.0.0.1:6379> BLOB.INFO mykey crc
(integer) 3381945770
127.0.0.1:6379> BLOB.INFO mykey TIER
dram
127.0.0.1:6379> BLOB.INFO mykey SIZE
(error) ERR invalid information field
127.0.0.1:6379> BLOB.INFO nosuchkey
(nil)
```
81 changes: 81 additions & 0 deletions commands/blob.rdma_get.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
Writes the payload of the large object stored at `key` directly into client memory with RDMA.
The payload does not go through the Valkey connection.

The connection must have an RDMA session.
To start a session, use [`BLOB.RDMA_HELLO`](blob.rdma_hello.md).

Each `region` is a triple that identifies a client memory region that the client registered with its libfabric endpoint:

* `rkey` - The remote key of the registered memory region.
* `addr` - The start address in the region.
This is a virtual address, or an offset into the registered memory when the fabric provider does not use virtual addresses.
`0` is a valid value.
* `len` - The number of bytes that the server can write into the region.
The value must be more than `0`.

All values are unsigned decimal integers.
You can give up to 256 regions.
The server writes the object bytes into the regions in the order that you give them, and fills each region before it continues to the next one.

The total length of all the regions must be equal to or more than the object length.
The regions can be larger than the object.
The reply gives the object length, so that the client knows where the valid data ends.

The server replies only after all the RDMA writes are complete.
The reply is a two-element array: the object length in bytes, and the CRC32C (Castagnoli) checksum that the server stored for the object.
The client can calculate the checksum of the received bytes and compare it with this value.

If `key` does not exist, the command returns nil.
The server looks up the key before it parses the regions and before it checks the session.
Thus, a missing key returns nil even when the connection has no RDMA session.
In `Tiered` mode, if too many disk operations run at the same time for the disk staging buffers, the command returns `ERR disk staging buffer pool exhausted; retry later`.
The error is temporary: a retry later can succeed, after operations in progress finish.
If `key` holds a value of a different type, the command returns a `WRONGTYPE` error.

This is a blocking command, so it cannot run in transactions, scripts, functions, or module calls (see [Limitations](../topics/large-object.md#limitations)).

To read the payload over TCP instead, use [`BLOB.TCP_GET`](blob.tcp_get.md).
To get only the length and checksum, use [`BLOB.INFO`](blob.info.md).
If the server cannot post the transfer for 1 second (for example, because the client endpoint is gone), the command fails with `ERR RDMA write failed`.
There is no other server-side timeout for the transfer.
To stop a transfer, close the connection.
For more information, see [Valkey Large Object - RDMA Transfers](../topics/large-object-rdma.md).

## Reply

One of the following:

* Array: a two-element array, after all the RDMA writes are complete: the object length in bytes as an integer, and the CRC32C checksum of the object as an integer.
* Null: if the key does not exist.

An error occurs if the memory regions are not valid or are too small for the object, if the connection has no RDMA session, if the RDMA write or a disk read fails, or if the key holds a value of a different type. See [Errors](../topics/large-object-rdma.md#errors) for all errors.

## Examples

You cannot do the transfer from `valkey-cli`.
The command needs a client that has a libfabric endpoint and registered memory, and that has an RDMA session on the connection.
The example shows the command shape and the reply.
In this example, the key holds a 1MB (1048576 bytes) object of zero bytes.
The first command writes the object into one region.
The second command writes the object into two regions of 512KB each.

```
127.0.0.1:6379> BLOB.RDMA_GET mykey 4242 140237318455296 1048576
1) (integer) 1048576
2) (integer) 338267154
127.0.0.1:6379> BLOB.RDMA_GET mykey 4242 140237318455296 524288 4243 140237320552448 524288
1) (integer) 1048576
2) (integer) 338267154
127.0.0.1:6379> BLOB.RDMA_GET mykey 4242 140237318455296 4096
(error) ERR client memory address length 4096 smaller than object length 1048576
127.0.0.1:6379> BLOB.RDMA_GET nosuchkey 4242 140237318455296 1048576
(nil)
```

On a connection without an RDMA session, an existing key with regions that are large enough returns the session error.
The server checks the regions before the session:

```
127.0.0.1:6379> BLOB.RDMA_GET mykey 999 0 1048576
(error) ERR no RDMA session (call BLOB.RDMA_HELLO first)
```
67 changes: 67 additions & 0 deletions commands/blob.rdma_hello.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
Establishes an RDMA session for the current connection.
A client must send this command once on a connection before it can use [`BLOB.RDMA_SET`](blob.rdma_set.md) or [`BLOB.RDMA_GET`](blob.rdma_get.md) on that connection.

`client-rdma-address` is the fabric address of the client endpoint, encoded as hexadecimal text.
The client gets this address from its libfabric endpoint.
When `largeobj.fabric-provider` is `EfaDirect`, the address must be exactly 32 bytes (64 hexadecimal characters).
When `largeobj.fabric-provider` is `Emulated`, the address must be a socket address: 16 bytes for IPv4 (`sockaddr_in`) or 28 bytes for IPv6 (`sockaddr_in6`).
The command takes exactly one argument.
With no argument or more than one argument, it returns an error.

The server adds the client address to each of its fabric services.
The reply is an array with one hexadecimal fabric address for each server fabric service.
The client must add all the returned addresses to its own address vector before the first transfer.

The session belongs to the connection.
The server removes the session when the connection closes.
A connection can have only one session: a second `BLOB.RDMA_HELLO` on the same connection returns an error.
To use a new client endpoint, open a new connection.

If the RDMA fabric did not start on the server, the command returns an error.
In that case, only the TCP commands, [`BLOB.TCP_SET`](blob.tcp_set.md) and [`BLOB.TCP_GET`](blob.tcp_get.md), are available.

For the full RDMA flow and the fabric configuration, see [Valkey Large Object - RDMA Transfers](../topics/large-object-rdma.md).

## Reply

Array of strings: one string for each server fabric service, with the hexadecimal fabric address of that service.

An error occurs if RDMA is not available on the server, if the client address is not valid for the fabric provider, or if the connection already has an RDMA session. See [Errors](../topics/large-object-rdma.md#errors) for all errors.

## Examples

A useful `BLOB.RDMA_HELLO` needs a client that has a libfabric endpoint.
`valkey-cli` can send the command, but it cannot do the RDMA transfers that follow.
The example shows the command shape and the reply, with example addresses.

```
127.0.0.1:6379> BLOB.RDMA_HELLO 0a1b2c3d4e5f60718293a4b5c6d7e8f900112233445566778899aabbccddeeff
1) "fe80000000000000049a1ffffe2b3c4d0b000000c5a3d1e20000000000000000"
2) "fe80000000000000049a1ffffe2b3c4e0c000000d7b4e2f30000000000000000"
127.0.0.1:6379> BLOB.RDMA_HELLO 0a1b2c3d4e5f60718293a4b5c6d7e8f900112233445566778899aabbccddeeff
(error) ERR RDMA session already established
```

These errors do not need an RDMA client.
The server in this example uses the `EfaDirect` fabric provider:

```
127.0.0.1:6379> BLOB.RDMA_HELLO zz
(error) ERR invalid rdma address hex
127.0.0.1:6379> BLOB.RDMA_HELLO 0a1b
(error) ERR rdma address must be 32 bytes
127.0.0.1:6379> BLOB.RDMA_HELLO 0a1b extra
(error) ERR wrong number of arguments for 'BLOB.RDMA_HELLO' command
```

With the `Emulated` fabric provider, `valkey-cli` can open a session.
The reply has one address for each server fabric service, here one:

```
127.0.0.1:6379> BLOB.RDMA_HELLO 0a1b
(error) ERR rdma address is not a valid sockaddr
127.0.0.1:6379> BLOB.RDMA_HELLO 02001f907f0000010000000000000000
1) "020098ff7f0000010000000000000000"
127.0.0.1:6379> BLOB.RDMA_HELLO 02001f907f0000010000000000000000
(error) ERR RDMA session already established
```
Loading
Loading