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 => e
    client.nack(queue: "my-queue", msg_id: msg.id, error: e.message)
  end
end

client.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:

begin
  client.enqueue(queue: "missing-queue", payload: "test")
rescue Fila::QueueNotFoundError => e
  # handle queue not found
end

begin
  client.ack(queue: "my-queue", msg_id: "missing-id")
rescue Fila::MessageNotFoundError => e
  # handle message not found
end

License

AGPLv3