Installation & Setup

Note

If you have not yet installed the Zizq server, follow the Getting Started guide first.

The official Zizq Ruby Client is available through RubyGems. Add it to your application’s Gemfile.

gem 'zizq', '~> 0.3.6'

Or install it manually:

$ gem install zizq -v 0.3.6

Versioning

Zizq client libraries are versioned with the same version numbers as the Zizq server, which follows the SemVer structure [MAJOR].[MINOR].[PATCH].

Whenever a new major or minor version of the server is released, client libraries with the same major and minor version numbers are also released. In short, as long as the major versions match between the client and server, the client should generally have an equal or lower minor version number than the server. The client should never exceed the server version.

It is safe to assume that a server version with the same major version number as the client and an equal or higher minor version number are fully compatible.
A client with a different major version number to the server should be assumed to be incompatible.
A client with the same major version number as the server but a higher minor version number may have support for newer features than the server has implemented and therefore those newer features may not work.
The patch version numbers do not impact functionality at all.

For access to the latest features applications should generally match the major and minor version numbers between the server and the client.

Examples:

Server Version	Client Version	Supported
0.1.0	0.1.0	✅
0.5.12	0.3.7	✅
1.0.1	0.12.2	❌
0.5.12	0.5.23	✅
0.5.12	0.6.0	❌

Configuration

Once installed you can load Zizq into your application by requiring "zizq".

require "zizq"

Out of the box, Zizq will communicate with the server on http://localhost:7890, which is the default host and port. This should be sufficient for local development, though you’ll need to configure the client for other environments.

Tip

The best-practice way to do this is by specifying environment variables that your application reads and uses to set each configuration option. That is left as an exercise for the reader. Examples here are hard-coded for clarity.

Configuration is done by calling Zizq.configure { ... } wherever your application typically bootstraps itself. In a Rails app this would be in a config/initializers/zizq.rb file. In a Sinatra app this could be at the top if your app.rb or even in your config.ru file.

Zizq.configure do |c|
  c.url = "https://host.your.network:7890"
  c.tls.ca = "/path/to/server-ca-cert.pem"
  c.logger = Logger.new("log/zizq.log")
end

Caution

If your server is exposed directly to the internet, it should be using Mutual TLS otherwise anybody can communicate with it.

Options

Option	Description
`url` String	The base URL of the Zizq server. Default: `http://localhost:7890`
`tls` Zizq::TlsConfiguration	TLS settings for connecting to a TLS-secured server. Set fields via the accessors below — e.g. `c.tls.ca = "/path/to/cert.pem"`. All values may be PEM-encoded strings or file paths.
`tls.ca` String	The path to a PEM formatted file containing the server's certificate authority (for manually generated certificates, such as those generated by `zizq tls`). Also supports being given the entire PEM data as a string.
`tls.client_cert` String	The path to a PEM formatted file containing the client certificate for Mutual TLS authentication if enabled on the server. Also supports being given the entire PEM data as a string. Requires a Pro license.
`tls.client_key` String	The path to a PEM formatted file containing the private key for Mutual TLS authentication if enabled on the server. Also supports being given the entire PEM data as a string.
`format` Symbol	The communication format used between the Zizq client and the server. One of: `:json` `:msgpack` Default: `:msgpack`.
`logger` Logger	The logger instance for the Zizq client to to use when writing logs. Default: `Logger.new(STDOUT)`
`read_timeout` Numeric	Per-operation socket I/O timeout (seconds) for regular API calls (e.g. enqueue, queries, mutations). A request whose dial handshake or any single read exceeds this raises `IO::TimeoutError`. Default: `30`.
`stream_idle_timeout` Numeric	Per-operation socket I/O timeout (seconds) for long-lived streaming connections used by the `Zizq::Worker` to receive jobs. The server sends heartbeats periodically, so each read returns within the heartbeat window, keeping the connection alive; the connection only times out if the server falls silent for longer than this timeout. The worker catches the resulting error and reconnects with backoff. Set well in excess of the server's heartbeat interval to avoid false-positive disconnects. Default: `30`.
`dispatcher` Object	A custom `Dispatcher` implementation for low-level job dispatch. This is any object that implements a `#dispatch` method to process a job from the Zizq server. Default: `Zizq::Job`.
`enqueue_middleware` Zizq::Middleware::Chain	The middleware chain used for all job enqueues. Middlewares can be registered in the chain with `enqueue_middleware.use(middleware)`.
`dequeue_middleware` Zizq::Middleware::Chain	The middleware chain used for all job dequeues. Middlewares can be registered in the chain with `dequeue_middleware.use(middleware)`.
`worker` Zizq::WorkerConfiguration	Defaults applied to every `Zizq::Worker` instance (and to runs of the `zizq-worker` executable). Set fields via the accessors below — e.g. `c.worker.queues = ["emails"]`. Any unset field falls through to `Zizq::Worker`'s hardcoded defaults; any kwarg passed to `Zizq::Worker.new` overrides whatever is set here. See Running Workers for details.
`worker.queues` Array[String]	Queues the worker will consume from. An empty array (the fallback default) means all queues.
`worker.thread_count` Integer	Number of worker threads. Fallback default: `1`.
`worker.fiber_count` Integer	Number of fibers per worker thread. Any value greater than `1` runs handlers inside an `Async` reactor — leave at `1` if your application isn't fiber-safe. Fallback default: `1`.
`worker.prefetch` Integer	Number of jobs the worker dequeues from the server at once without receiving acknowledgements. Should be at least `thread_count * fiber_count`. Fallback default: `2 * thread_count * fiber_count`.
`worker.retry_min_wait` Numeric	Minimum reconnect backoff in seconds when the worker loses its connection to the server. Fallback default: `1`.
`worker.retry_max_wait` Numeric	Maximum reconnect backoff in seconds. Fallback default: `30`.
`worker.retry_multiplier` Numeric	Multiplicative factor applied to the reconnect backoff between successive attempts. Fallback default: `2`.

Keyboard shortcuts

Zizq Ruby Client

Installation & Setup

Versioning

Configuration

Options