fila-ruby

Ruby client SDK for the Fila message broker.

Installation

gem install fila-client

Or add to your Gemfile:

gem"fila-client"

Usage

require"fila"client=Fila::Client.new("localhost:5555")# Enqueue a message.msg_id=client.enqueue(queue: "my-queue",headers: {"tenant"=>"acme"},payload: "hello world")puts"Enqueued: #{msg_id}"# Consume messages (block form).client.consume(queue: "my-queue")do |msg|
puts"Received: #{msg.id} (attempt #{msg.attempt_count})"begin# Process the message...client.ack(queue: "my-queue",msg_id: msg.id)rescue=>eclient.nack(queue: "my-queue",msg_id: msg.id,error: e.message)endendclient.close

TLS (system trust store)

require"fila"# TLS using the OS system trust store (e.g., server uses a public CA).client=Fila::Client.new("localhost:5555",tls: true)

TLS (custom CA)

require"fila"# TLS with an explicit CA certificate (e.g., private/self-signed CA).client=Fila::Client.new("localhost:5555",ca_cert: File.read("ca.pem"))

mTLS (mutual TLS)

require"fila"# Mutual TLS with system trust store.client=Fila::Client.new("localhost:5555",tls: true,client_cert: File.read("client.pem"),client_key: File.read("client-key.pem"))# Mutual TLS with explicit CA certificate.client=Fila::Client.new("localhost:5555",ca_cert: File.read("ca.pem"),client_cert: File.read("client.pem"),client_key: File.read("client-key.pem"))

API Key Authentication

require"fila"# API key sent as Bearer token on every request.client=Fila::Client.new("localhost:5555",api_key: "fila_your_api_key_here")

mTLS + API Key

require"fila"# Full security: mTLS transport + API key authentication.client=Fila::Client.new("localhost:5555",ca_cert: File.read("ca.pem"),client_cert: File.read("client.pem"),client_key: File.read("client-key.pem"),api_key: "fila_your_api_key_here")

API

Fila::Client.new(addr, tls: false, ca_cert: nil, client_cert: nil, client_key: nil, api_key: nil)

Connect to a Fila broker at the given address (e.g., "localhost:5555").

Parameter	Type	Description
addr	String	Broker address in "host:port" format
tls:	Boolean	Enable TLS using the OS system trust store (default: false)
ca_cert:	String or nil	PEM-encoded CA certificate for TLS (implies tls: true)
client_cert:	String or nil	PEM-encoded client certificate for mTLS
client_key:	String or nil	PEM-encoded client private key for mTLS
api_key:	String or nil	API key for Bearer token authentication

When no TLS/auth options are provided, the client connects over plaintext (backward compatible). When tls: true is set without ca_cert:, the OS system trust store is used for server certificate verification.

client.enqueue(queue:, headers:, payload:)

Enqueue a message. Returns the broker-assigned message ID (UUIDv7).

client.consume(queue:) { |msg| ... }

Open a streaming consumer. Yields Fila::ConsumeMessage objects as they become available. If no block is given, returns an Enumerator. Nacked messages are redelivered on the same stream.

client.ack(queue:, msg_id:)

Acknowledge a successfully processed message. The message is permanently removed.

client.nack(queue:, msg_id:, error:)

Negatively acknowledge a failed message. The message is requeued or routed to the dead-letter queue based on the queue's configuration.

client.close

Close the underlying gRPC channel.

Error Handling

Per-operation error classes are raised for specific failure modes:

beginclient.enqueue(queue: "missing-queue",payload: "test")rescueFila::QueueNotFoundError=>e# handle queue not foundendbeginclient.ack(queue: "my-queue",msg_id: "missing-id")rescueFila::MessageNotFoundError=>e# handle message not foundend

License

AGPLv3