Class: Zizq::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/zizq/configuration.rb,
sig/generated/zizq/configuration.rbs

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: FlushingIO, Identity

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

: () -> void



72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/zizq/configuration.rb', line 72

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

Instance Attribute Details

#dequeue_middleware ⇒ Middleware::Chain[Resources::Job, void] (readonly)

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

Returns:



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

def dequeue_middleware
  @dequeue_middleware
end

#enqueue_middleware ⇒ Middleware::Chain[EnqueueRequest, EnqueueRequest] (readonly)

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

Returns:



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

def enqueue_middleware
  @enqueue_middleware
end

#format ⇒ Zizq::format

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

One of: :json, :msgpack (default)

Returns:

  • (Zizq::format) 


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

def format
  @format
end

#logger ⇒ Logger

Logger instance to which to write log messages.

Returns:

  • (Logger) 


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

def logger
  @logger
end

#read_timeout ⇒ Numeric

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.

Returns:

  • (Numeric) 


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

def read_timeout
  @read_timeout
end

#stream_idle_timeout ⇒ Numeric

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.

Returns:

  • (Numeric) 


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

def stream_idle_timeout
  @stream_idle_timeout
end

#test_mode ⇒ Boolean

When truthy, Zizq.client lazily resolves to a Zizq::Test::Client that buffers enqueues in memory rather than dispatching to a real server. Useful inside test suites — set it once in your test helper and the rest of the app's code uses Zizq.enqueue / Zizq.enqueue_bulk unchanged. Read operations (Zizq.query, Zizq.queues, Client#get_job, etc.) raise rather than silently returning empty results, so missing test setup is obvious.

Returns:

  • (Boolean) 


70
71
72
 
# File 'lib/zizq/configuration.rb', line 70

def test_mode
  @test_mode
end

#url ⇒ String

Base URL of the Zizq server (default: "http://localhost:7890").

Returns:

  • (String) 


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

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.

Returns:

  • (Object) 


155
156
157
 
# File 'lib/zizq/configuration.rb', line 155

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.

Parameters:

  • dispatcher (Object)

Returns:

  • (Object) 


169
170
171
 
# File 'lib/zizq/configuration.rb', line 169

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

#load_cert(pem_or_path) ⇒ Object

Load a certificate from a PEM string or file path.

Parameters:

  • pem_or_path (Object)

Returns:

  • (Object) 


267
268
269
 
# File 'lib/zizq/configuration.rb', line 267

def load_cert(pem_or_path) #: (String) -> OpenSSL::X509::Certificate
  OpenSSL::X509::Certificate.new(resolve_pem(pem_or_path))
end

#load_key(pem_or_path) ⇒ Object

Load a private key from a PEM string or file path.

Parameters:

  • pem_or_path (Object)

Returns:

  • (Object) 


272
273
274
 
# File 'lib/zizq/configuration.rb', line 272

def load_key(pem_or_path) #: (String) -> OpenSSL::PKey::PKey
  OpenSSL::PKey.read(resolve_pem(pem_or_path))
end

#resolve_pem(value) ⇒ Object

If the value looks like PEM data, return it as-is; otherwise treat it as a file path and read the contents.

Parameters:

  • value (Object)

Returns:

  • (Object) 


278
279
280
281
282
283
284
 
# File 'lib/zizq/configuration.rb', line 278

def resolve_pem(value) #: (String) -> String
  if value.include?("-----BEGIN ")
    value
  else
    File.read(value)
  end
end

#ssl_context ⇒ Object

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

Returns:

  • (Object) 


196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/zizq/configuration.rb', line 196

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.

Returns:

  • (Object) 


101
102
103
 
# File 'lib/zizq/configuration.rb', line 101

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

#tls=(value) ⇒ Object

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

Parameters:

  • value (Object)

Returns:

  • (Object) 


105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/zizq/configuration.rb', line 105

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.

Returns:

  • (Object) 


174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/zizq/configuration.rb', line 174

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

#validate_tls!(tls) ⇒ Object

: (TlsConfiguration) -> void

Parameters:

  • tls (Object)

Returns:

  • (Object) 


256
257
258
259
260
261
262
263
264
 
# File 'lib/zizq/configuration.rb', line 256

def validate_tls!(tls) #: (TlsConfiguration) -> void
  if tls.client_cert && !tls.client_key
    raise ArgumentError, "Zizq.configure: tls.client_key is required when tls.client_cert is set"
  end

  if tls.client_key && !tls.client_cert
    raise ArgumentError, "Zizq.configure: tls.client_cert is required when tls.client_key is set"
  end
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.

Returns:

  • (Object) 


132
133
134
 
# File 'lib/zizq/configuration.rb', line 132

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

#worker=(value) ⇒ Object

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

Parameters:

  • value (Object)

Returns:

  • (Object) 


136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/zizq/configuration.rb', line 136

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