hot.dev/redis / ::redis

Redis client for Hot.

Speaks the RESP protocol directly over ::hot::tcp (with optional ::hot::tls), so no native driver is required. Supports authentication, database selection, RESP2/RESP3, and arbitrary commands with typed replies.

A connection is a runtime-owned socket handle; it lives for the duration of the run or task that opened it.

Error contract: expected failures — connection refused, TLS negotiation, AUTH/SELECT, Redis error replies — return a Result.Err; branch with is-err / if-err. A socket failure mid-protocol (the connection drops between command and reply) halts the run instead: the connection state is unusable and the recovery unit is the run or task, not the command.

Quick start

conn ::redis/connect({host: "localhost", port: 6379})

::redis/set(conn, "greeting", "hello")
::redis/get(conn, "greeting")        // "hello"
::redis/incr(conn, "counter")        // 1

// Arbitrary commands
::redis/command(conn, ["LPUSH", "queue", "a", "b"])
::redis/command(conn, ["LRANGE", "queue", "0", "-1"])  // ["b", "a"]

::redis/close(conn)

Functions

close

fn (conn: RedisConnection): Bool

Close the connection (send QUIT and shut down the socket). Safe to call more than once.

command

fn (conn: RedisConnection, args: Vec): Any

Send a command (a Vec of arguments) and return the decoded reply.

Bytes arguments are sent as-is (binary-safe); other arguments are coerced to strings. Replies decode to Str/Int/Dec/Bool/Vec/Map/null per RESP; a bulk value that is not valid UTF-8 decodes to Bytes. Redis error replies decode to a Result.Err with the message; branch on it with is-err / if-err. An unhandled error halts at first use with the same message.

Example

::redis/command(conn, ["SET", "k", "v"])          // "OK"
::redis/command(conn, ["INCRBY", "n", "5"])       // 5
::redis/command(conn, ["MGET", "a", "b"])         // ["1", null]

connect

fn (options: Map): RedisConnection

Open a Redis connection, optionally authenticating, selecting a database, and negotiating RESP3.

Returns a RedisConnection, or a Result.Err carrying the error details when the connection, TLS negotiation, AUTH, or SELECT fails. Branch on it with is-err / if-err; an unhandled error halts at first use with the same message.

Example

conn ::redis/connect({host: "localhost", port: 6379, password: "secret", db: 1})
if-err(conn, (e) { ... fall back ... })

See RedisOptions for the accepted fields.

del

fn (conn: RedisConnection, keys: Vec): Int

Delete one or more keys. Returns the number removed.

exists

fn (conn: RedisConnection, keys: Vec): Int

Return the number of the given keys that exist.

expire

fn (conn: RedisConnection, key: Str, seconds: Int): Int

Set a seconds TTL on key. Returns 1 if set, 0 if the key does not exist.

get

fn (conn: RedisConnection, key: Str): Any

Get the value of key, or null if it does not exist. Values decode to Str, or to Bytes when they are not valid UTF-8.

incr

fn (conn: RedisConnection, key: Str): Int

Increment the integer at key by one and return the new value.

maybe-auth

fn (conn: RedisConnection, username, password, resp3: Bool): Any

maybe-select

fn (conn: RedisConnection, db: Int): Any

negotiate-tls

fn (socket, tls-opts: Map, host: Str): Any

ping

fn (conn: RedisConnection): Str

Ping the server. Returns "PONG".

set

fn (conn: RedisConnection, key: Str, value: Any): Str

Set key to value. A Bytes value is stored as-is (binary-safe); other values are coerced to strings. Returns "OK".

Example

::redis/set(conn, "session:42", token)

set-ex

fn (conn: RedisConnection, key: Str, value: Any, seconds: Int): Str

Set key to value with an expiry in seconds, like set. Returns "OK".

Types

RedisConnection

RedisConnection type {
    socket: Any
}

An open Redis connection.

Fields

• socket — The underlying ::hot::tcp connection

RedisOptions

RedisOptions type {
    host: Str?,
    port: Int?,
    username: Str?,
    password: Str?,
    db: Int?,
    resp3: Bool?,
    tls: Map?,
    timeout: Int?
}

Connection options.

Fields

• host — Server host (default "127.0.0.1")
• port — Server port (default 6379)
• username — ACL username (RESP3/Redis 6+, optional)
• password — Password for AUTH (optional)
• db — Database index to SELECT (default 0)
• resp3 — Negotiate RESP3 with HELLO 3 (default false)
• tls — When set, upgrade the connection with ::hot::tls/upgrade
• timeout — Connect/read timeout in milliseconds