API Reference

Fila exposes two service groups on the same port (default 5555) via FIBP (Fila Binary Protocol). Protobuf message definitions are in proto/fila/v1/.

Hot-path service (fila.v1.FilaService)

Used by producers and consumers for message operations.

Enqueue

Enqueue one or more messages. Single-message enqueue is a batch of one.

rpc Enqueue(EnqueueRequest) returns (EnqueueResponse)

Request (EnqueueRequest):

EnqueueMessage:

Response (EnqueueResponse):

EnqueueResult:

Only one of message_id or error is set (protobuf oneof).

EnqueueErrorCode:

StreamEnqueue

Bidirectional streaming enqueue with sequence tracking. The client sends batches of messages on the request stream and receives per-batch results on the response stream. Sequence numbers allow the client to correlate responses with requests.

rpc StreamEnqueue(stream StreamEnqueueRequest) returns (stream StreamEnqueueResponse)

Request (stream, StreamEnqueueRequest):

Response (stream, StreamEnqueueResponse):

Consume

Open a server-streaming connection to receive messages. The broker delivers messages according to the DRR scheduler, respecting fairness groups and throttle limits.

rpc Consume(ConsumeRequest) returns (stream ConsumeResponse)

Request:

Response (stream, ConsumeResponse):

The stream stays open until the client disconnects. Messages are delivered as they become available — the stream blocks when no messages are ready.

Errors:

Ack

Acknowledge one or more messages. Removes acknowledged messages from the broker.

rpc Ack(AckRequest) returns (AckResponse)

Request (AckRequest):

AckMessage:

Response (AckResponse):

AckResult:

Only one of success or error is set (protobuf oneof).

AckErrorCode:

Nack

Reject one or more messages. Triggers the on_failure Lua hook (if configured) to decide retry vs. dead-letter.

rpc Nack(NackRequest) returns (NackResponse)

Request (NackRequest):

NackMessage:

Response (NackResponse):

NackResult:

Only one of success or error is set (protobuf oneof).

NackErrorCode:

Admin service (fila.v1.FilaAdmin)

Used by operators and the fila CLI for queue management, configuration, and diagnostics.

CreateQueue

Create a new queue with optional Lua hooks and visibility timeout.

rpc CreateQueue(CreateQueueRequest) returns (CreateQueueResponse)

Request:

QueueConfig:

Response:

Errors:

DeleteQueue

Delete a queue and all its messages.

rpc DeleteQueue(DeleteQueueRequest) returns (DeleteQueueResponse)

Request:

Errors:

ListQueues

List all queues with summary statistics.

rpc ListQueues(ListQueuesRequest) returns (ListQueuesResponse)

Response:

QueueInfo:

SetConfig

Set a runtime configuration key-value pair. Persisted across restarts.

rpc SetConfig(SetConfigRequest) returns (SetConfigResponse)

Request:

GetConfig

Retrieve a configuration value by key.

rpc GetConfig(GetConfigRequest) returns (GetConfigResponse)

Request:

Response:

Errors:

ListConfig

List configuration entries, optionally filtered by prefix.

rpc ListConfig(ListConfigRequest) returns (ListConfigResponse)

Request:

Response:

ConfigEntry:

GetStats

Get detailed statistics for a queue, including per-fairness-key and per-throttle-key breakdowns.

rpc GetStats(GetStatsRequest) returns (GetStatsResponse)

Request:

Response:

PerFairnessKeyStats:

PerThrottleKeyStats:

Errors:

Redrive

Move pending messages from a dead letter queue back to the source queue.

rpc Redrive(RedriveRequest) returns (RedriveResponse)

Request:

Response:

Only pending (non-leased) messages are redriven. Leased messages in the DLQ are skipped to avoid interfering with active consumers.

Errors:

Message types

Message

The core message envelope returned by Consume.

message Message {
  string id = 1;
  map<string, string> headers = 2;
  bytes payload = 3;
  MessageMetadata metadata = 4;
  MessageTimestamps timestamps = 5;
}

MessageMetadata

Scheduling metadata assigned by the broker (via Lua on_enqueue or defaults).

message MessageMetadata {
  string fairness_key = 1;
  uint32 weight = 2;
  repeated string throttle_keys = 3;
  uint32 attempt_count = 4;
  string queue_id = 5;
}

MessageTimestamps

message MessageTimestamps {
  google.protobuf.Timestamp enqueued_at = 1;
  google.protobuf.Timestamp leased_at = 2;
}