RedisServerWrapper.Server (redis_server_wrapper v0.7.4)

Copy Markdown View Source

GenServer managing a single redis-server process.

Starts redis-server with a generated config file, tracks the OS PID, and sends SHUTDOWN NOSAVE on terminate (unless detached).

Usage

{:ok, pid} = RedisServerWrapper.Server.start_link(port: 6400, password: "secret")
RedisServerWrapper.Server.ping(pid)
RedisServerWrapper.Server.run(pid, ["SET", "key", "value"])
RedisServerWrapper.Server.stop(pid)

Options

Typed options from RedisServerWrapper.Config are supported, subject to Server-owned lifecycle fields. In particular, Server owns :daemonize, :pidfile, and :dir, and interprets :timeout as its startup timeout rather than Redis's idle-client directive. The shipped configuration guide is the authoritative option matrix.

  • :redis_server_bin - path to redis-server binary (default: "redis-server")
  • :redis_cli_bin - path to redis-cli binary (default: "redis-cli")
  • :username - optional named ACL user paired with :password
  • :port - plaintext TCP port; use 0 to disable plaintext TCP
  • :unixsocket - Unix socket path used when TCP and TLS are disabled
  • :tls_port - TLS listener and lifecycle connection port
  • :tls_cert_file, :tls_key_file - Redis TLS server identity
  • :tls_ca_cert_file or :tls_ca_cert_dir - trusted CA for Redis and redis-cli
  • :tls_client_cert_file, :tls_client_key_file - optional redis-cli identity
  • :tls_server_name - optional redis-cli SNI name
  • :tls_insecure - explicitly disable redis-cli certificate verification
  • :distribution - :core (default), :full, or :legacy_stack. Only explicit :legacy_stack selection enables legacy Stack module discovery; caller-provided :loadmodule entries always remain explicit.
  • :name - GenServer name registration
  • :timeout - startup timeout in ms (default: 10_000)
  • :loadmodule - Redis modules to load; accepts module paths or {path, [args]} tuples (default: [])
  • :managed - controls how the redis-server OS process is tied to the BEAM:
    • true (default) - redis-server runs as a Port tied to the BEAM lifecycle. When the BEAM exits, the port closes and redis-server receives SIGHUP. Teardown runs in terminate/2, which is skipped on a :brutal_kill supervisor shutdown or a hard BEAM death, so the OS process can be stranded.
    • :forcola - redis-server runs in the foreground under a Forcola.Daemon, which guarantees the OS process group is killed and confirmed dead on owner death or supervisor shutdown, including the paths where terminate/2 never runs. Requires the optional :forcola dependency ({:forcola, "~> 0.3"}); start_link returns {:error, :forcola_not_available} if it is missing.
    • false - redis-server daemonizes independently (legacy behavior); the caller owns the OS process lifecycle.

Summary

Types

distribution()
managed()
t()

Functions

alive?(server)

Returns true if the redis-server OS process is still alive.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

cli(server)

Returns the Cli struct for direct use.

default_server_bin(distribution \\ :core)

Returns the default redis-server binary for a distribution.

detach(server)

Detaches the server -- the redis-server OS process will NOT be stopped when this GenServer terminates. Returns {:error, :managed_server} in managed mode.

info(server)

Returns connection and process information.

ping(server)

Pings the server. Returns true if alive.

run(server, args)

Runs an arbitrary redis-cli command against this server.

start(opts \\ [])

Starts a redis-server process without linking.

start_link(opts \\ [])

Starts and links a redis-server process.

stop(server)

Gracefully stops the GenServer (which stops redis-server unless detached).

Types

distribution()

@type distribution() :: :core | :full | :legacy_stack

managed()

@type managed() :: boolean() | :forcola

t()

@type t() :: %RedisServerWrapper.Server{
  cli: RedisServerWrapper.Cli.t(),
  config: RedisServerWrapper.Config.t(),
  daemon: pid() | nil,
  detached: boolean(),
  distribution: distribution(),
  managed: managed(),
  node_dir: String.t() | nil,
  pid: non_neg_integer() | nil,
  port_ref: port() | nil,
  redis_server_bin: String.t()
}

Functions

alive?(server)

@spec alive?(GenServer.server()) :: boolean()

Returns true if the redis-server OS process is still alive.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

cli(server)

@spec cli(GenServer.server()) :: RedisServerWrapper.Cli.t()

Returns the Cli struct for direct use.

default_server_bin(distribution \\ :core)

@spec default_server_bin(distribution()) :: String.t()

Returns the default redis-server binary for a distribution.

Core and Redis 8 Full use redis-server from PATH. Legacy Redis Stack is opt-in and uses REDIS_LEGACY_STACK_SERVER_BIN when set, otherwise redis-stack-server.

detach(server)

@spec detach(GenServer.server()) :: :ok | {:error, :managed_server}

Detaches the server -- the redis-server OS process will NOT be stopped when this GenServer terminates. Returns {:error, :managed_server} in managed mode.

info(server)

@spec info(GenServer.server()) :: map()

Returns connection and process information.

ping(server)

@spec ping(GenServer.server()) :: boolean()

Pings the server. Returns true if alive.

run(server, args)

@spec run(GenServer.server(), [String.t()]) ::
  {:ok, String.t()} | {:error, String.t()}

Runs an arbitrary redis-cli command against this server.

start(opts \\ [])

@spec start(keyword()) :: GenServer.on_start()

Starts a redis-server process without linking.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts and links a redis-server process.

stop(server)

@spec stop(GenServer.server()) :: :ok

Gracefully stops the GenServer (which stops redis-server unless detached).