Class: Valkey::Route

Inherits:
Object
  • Object
show all
Defined in:
lib/valkey/route.rb

Overview

Represents a cluster routing directive. Passed as route: to commands that support explicit cluster routing (no-key commands like DBSIZE, INFO, PING, FLUSHALL, FUNCTION_*, etc.).

When route: is provided the command response type depends on the route: single-node routes return the value directly, multi-node routes return a Hash of "host:port" => value.

Examples:

client.dbsize(route: Valkey::Route.all_primaries)
client.ping(route: Valkey::Route.random)
client.info(route: Valkey::Route.all_nodes)

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.all_nodes ⇒ Route

Note:

Don't use with write commands — they could be routed to replicas and fail.

Route to all nodes (primaries + replicas).

Returns:



23
24
25
 
# File 'lib/valkey/route.rb', line 23

def all_nodes
  new(:all_nodes)
end

.all_primaries ⇒ Route

Route to all primary nodes.

Returns:



29
30
31
 
# File 'lib/valkey/route.rb', line 29

def all_primaries
  new(:all_primaries)
end

.by_address(host, port) ⇒ Route

Route to a specific node by address.

Parameters:

  • host (String) —

    hostname or IP

  • port (Integer) —

    port number

Returns:



60
61
62
 
# File 'lib/valkey/route.rb', line 60

def by_address(host, port)
  new(:by_address, hostname: host.to_s, port: port.to_i)
end

.random ⇒ Route

Note:

Don't use with write commands — they could be randomly routed to a replica and fail.

Route to a random node.

Returns:



36
37
38
 
# File 'lib/valkey/route.rb', line 36

def random
  new(:random)
end

.slot_id(slot_id, slot_type = :primary) ⇒ Route

Route to a specific slot by ID.

Parameters:

  • slot_id (Integer) —

    slot number (0–16383)

  • slot_type (Symbol) (defaults to: :primary) —

    :primary or :replica

Returns:



44
45
46
 
# File 'lib/valkey/route.rb', line 44

def slot_id(slot_id, slot_type = :primary)
  new(:slot_id, slot_id: slot_id.to_i, slot_type: slot_type)
end

.slot_key(key, slot_type = :primary) ⇒ Route

Route to the node owning a specific key's slot.

Parameters:

  • key (String) —

    the key whose slot determines routing

  • slot_type (Symbol) (defaults to: :primary) —

    :primary or :replica

Returns:



52
53
54
 
# File 'lib/valkey/route.rb', line 52

def slot_key(key, slot_type = :primary)
  new(:slot_key, slot_key: key.to_s, slot_type: slot_type)
end

Instance Method Details

#to_ffi ⇒ Array(Bindings::RouteInfo, Array)

Build the FFI RouteInfo struct for passing to command_with_route_info.

Returns both the struct and any pinned memory buffers that must remain alive until the FFI call completes.

TODO: Refactor to return a struct (https://github.com/valkey-io/valkey-glide-ruby/issues/179)

Returns:



73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/valkey/route.rb', line 73

def to_ffi
  info = Bindings::RouteInfo.new
  info[:route_type] = @route_type
  info[:slot_id] = @slot_id || 0
  info[:slot_type] = @slot_type || :primary
  info[:port] = @port || 0

  pinned = [] # prevent GC of string buffers during FFI call
  info[:slot_key] = pin_string(@slot_key, pinned)
  info[:hostname] = pin_string(@hostname, pinned)

  [info, pinned]
end