Class: Zizq::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/zizq/configuration.rb

Overview

Global configuration for the Zizq client.

The configuration stores only client-level concerns: server URL, serialization format, and logger. Worker-specific settings (queues, threads, etc.) are passed directly to the Worker.

See: [‘Zizq::configure]`. See: [`Zizq::configuration]`.

Defined Under Namespace

Classes: Identity

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

: () -> void



61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/zizq/configuration.rb', line 61

def initialize #: () -> void
  @url = "http://localhost:7890"
  @format = :msgpack
  @logger = Logger.new($stdout, level: Logger::INFO)
  @tls = nil
  @worker = nil
  @read_timeout = 30
  @stream_idle_timeout = 30
  @enqueue_middleware = Middleware::Chain.new(Identity.new)
  @dequeue_middleware = Middleware::Chain.new(Zizq::Job)
end

Instance Attribute Details

#dequeue_middleware ⇒ Object (readonly)

Middleware chain for dequeue/dispatch. Each middleware receives a ‘Resources::Job` and a chain to continue.



59
60
61
 
# File 'lib/zizq/configuration.rb', line 59

def dequeue_middleware
  @dequeue_middleware
end

#enqueue_middleware ⇒ Object (readonly)

Middleware chain for enqueue. Each middleware receives an ‘EnqueueRequest` and a chain to continue.



55
56
57
 
# File 'lib/zizq/configuration.rb', line 55

def enqueue_middleware
  @enqueue_middleware
end

#format ⇒ Object

Choice of content-type encoding used in communication with the Zizq server.

One of: ‘:json`, `:msgpack` (default)



27
28
29
 
# File 'lib/zizq/configuration.rb', line 27

def format
  @format
end

#logger ⇒ Object

Logger instance to which to write log messages.



30
31
32
 
# File 'lib/zizq/configuration.rb', line 30

def logger
  @logger
end

#read_timeout ⇒ Object

Per-operation socket I/O timeout (seconds) for regular API calls (enqueue, queries, mutations). Each socket read/write is bounded by this value. A request whose handshake or any single read exceeds this raises ‘IO::TimeoutError`.

Default: 30.



38
39
40
 
# File 'lib/zizq/configuration.rb', line 38

def read_timeout
  @read_timeout
end

#stream_idle_timeout ⇒ Object

Per-operation socket I/O timeout (seconds) for the long-lived ‘#take_jobs` stream. The server sends heartbeats every ~3 seconds, so each read returns within that window and keeps the connection alive; the connection only times out if the server falls silent for longer than this. The Worker catches the resulting error and reconnects with backoff.

Should be comfortably above the server’s heartbeat interval to avoid false-positive disconnects.

Default: 30.



51
52
53
 
# File 'lib/zizq/configuration.rb', line 51

def stream_idle_timeout
  @stream_idle_timeout
end

#url ⇒ Object

Base URL of the Zizq server (default: “localhost:7890”).



21
22
23
 
# File 'lib/zizq/configuration.rb', line 21

def url
  @url
end

Instance Method Details

#dispatcher ⇒ Object

The job dispatcher. This is the terminal of the dequeue middleware chain. Defaults to ‘Zizq::Job` which finds and executes jobs written by mixing in the `Zizq::Job` module.



143
144
145
 
# File 'lib/zizq/configuration.rb', line 143

def dispatcher #: () -> Zizq::dispatcher
  @dequeue_middleware.terminal
end

#dispatcher=(dispatcher) ⇒ Object

Set the dispatcher to a custom dispatcher implementation.

A dispatcher is any object that responds to ‘#call` with a `Zizq::Resources::Job` instance and performs that job through some application-specific logic.

This is the terminal of the dequeue middleware chain.

Any errors raised by the dispatcher will result in the normal backoff/retry behaviour. Jobs are acknowledged automatically on success.



157
158
159
 
# File 'lib/zizq/configuration.rb', line 157

def dispatcher=(dispatcher) #: (Zizq::dispatcher) -> void
  @dequeue_middleware.terminal = dispatcher
end

#ssl_context ⇒ Object

Build an OpenSSL::SSL::SSLContext from the TLS options, or nil if no TLS options are configured.



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/zizq/configuration.rb', line 184

def ssl_context #: () -> OpenSSL::SSL::SSLContext?
  tls = @tls
  return nil unless tls
  return nil if tls.to_h.values.all?(&:nil?)

  ctx = OpenSSL::SSL::SSLContext.new

  if (ca = tls.ca)
    store = OpenSSL::X509::Store.new
    store.add_cert(load_cert(ca))
    ctx.cert_store = store
    ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
  end

  if (client_cert = tls.client_cert)
    ctx.cert = load_cert(client_cert)
  end

  if (client_key = tls.client_key)
    ctx.key = load_key(client_key)
  end

  ctx
end

#tls ⇒ Object

TLS settings for connecting to the server over HTTPS.

Configure via the ‘c.tls` accessors inside a `Zizq.configure` block:

Zizq.configure do |c|
  c.tls.ca          = "/path/to/server-ca-cert.pem"
  c.tls.client_cert = "/path/to/client-cert.pem"
  c.tls.client_key  = "/path/to/client-key.pem"
end

All values may be PEM-encoded strings or file paths. Set ‘c.tls = nil` to explicitly disable TLS.

Note: Mutual TLS support requires a Zizq Pro license on the server.



89
90
91
 
# File 'lib/zizq/configuration.rb', line 89

def tls #: () -> TlsConfiguration
  @tls ||= TlsConfiguration.new
end

#tls=(value) ⇒ Object

: ((Hash[Symbol, String?] | TlsConfiguration)?) -> void



93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/zizq/configuration.rb', line 93

def tls=(value) #: ((Hash[Symbol, String?] | TlsConfiguration)?) -> void
  case value
  when nil
    @tls = nil
  when TlsConfiguration
    @tls = value
  when Hash
    @tls = TlsConfiguration.new(**value)
  else
    raise ArgumentError,
      "Zizq.configure: tls= expects a Hash, Zizq::TlsConfiguration, or nil " \
      "(got #{value.class})"
  end
end

#validate! ⇒ Object

Validates that required configuration is present.

Raises:

  • (ArgumentError) 


162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/zizq/configuration.rb', line 162

def validate! #: () -> void
  raise ArgumentError, "Zizq.configure: url is required" if url.empty?

  unless %i[msgpack json].include?(format)
    raise ArgumentError, "Zizq.configure: format must be :msgpack or :json, got #{format.inspect}"
  end

  unless read_timeout.is_a?(Numeric) && read_timeout > 0
    raise ArgumentError, "Zizq.configure: read_timeout must be a positive number, got #{read_timeout.inspect}"
  end

  unless stream_idle_timeout.is_a?(Numeric) && stream_idle_timeout > 0
    raise ArgumentError, "Zizq.configure: stream_idle_timeout must be a positive number, got #{stream_idle_timeout.inspect}"
  end

  tls = @tls
  validate_tls!(tls) if tls
end

#worker ⇒ Object

Defaults for ‘Zizq::Worker` instances. Apps populate this in their `Zizq.configure` block:

Zizq.configure do |c|
  c.worker.queues = ["emails"]
  c.worker.fiber_count = 25
end

Anything left unset here falls through to the Worker’s hardcoded defaults; anything explicitly passed to ‘Worker.new` (or set via `zizq-worker` CLI flags / env vars) overrides whatever is configured here.



120
121
122
 
# File 'lib/zizq/configuration.rb', line 120

def worker #: () -> WorkerConfiguration
  @worker ||= WorkerConfiguration.new
end

#worker=(value) ⇒ Object

: ((Hash[Symbol, untyped] | WorkerConfiguration)?) -> void



124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/zizq/configuration.rb', line 124

def worker=(value) #: ((Hash[Symbol, untyped] | WorkerConfiguration)?) -> void
  case value
  when nil
    @worker = nil
  when WorkerConfiguration
    @worker = value
  when Hash
    @worker = WorkerConfiguration.new(**value)
  else
    raise ArgumentError,
      "Zizq.configure: worker= expects a Hash, Zizq::WorkerConfiguration, or nil " \
      "(got #{value.class})"
  end
end