fila-js

JavaScript/TypeScript client SDK for the Fila message broker.

Installation

npm install fila-client

Usage

import { Client } from "fila-client";

const client = new Client("localhost:5555");

// Enqueue a message.
const msgId = await client.enqueue(
  "my-queue",
  { tenant: "acme" },
  Buffer.from("hello world")
);
console.log("Enqueued:", msgId);

// Consume messages.
for await (const msg of client.consume("my-queue")) {
  console.log(`Received: ${msg.id} (attempt ${msg.attemptCount})`);

  try {
    // Process the message...
    await client.ack("my-queue", msg.id);
  } catch (err) {
    await client.nack("my-queue", msg.id, String(err));
  }
}

client.close();

TLS (system trust store)

If the Fila server uses a certificate signed by a public CA, enable TLS without providing a CA certificate — the OS system trust store is used automatically:

import { Client } from "@fila/client";

const client = new Client("localhost:5555", { tls: true });

TLS (custom CA certificate)

For self-signed or private CA certificates, pass the CA cert explicitly:

import * as fs from "fs";
import { Client } from "fila-client";

const client = new Client("localhost:5555", {
  caCert: fs.readFileSync("ca.pem"),
});

Mutual TLS (mTLS)

Client certificates work with both modes — system trust store or custom CA:

import * as fs from "fs";
import { Client } from "@fila/client";

// With custom CA:
const client = new Client("localhost:5555", {
  caCert: fs.readFileSync("ca.pem"),
  clientCert: fs.readFileSync("client.pem"),
  clientKey: fs.readFileSync("client.key"),
});

// With system trust store:
const client2 = new Client("localhost:5555", {
  tls: true,
  clientCert: fs.readFileSync("client.pem"),
  clientKey: fs.readFileSync("client.key"),
});

API key authentication

import { Client } from "@fila/client";

const client = new Client("localhost:5555", {
  apiKey: "my-api-key",
});

mTLS + API key

import * as fs from "fs";
import { Client } from "@fila/client";

const client = new Client("localhost:5555", {
  caCert: fs.readFileSync("ca.pem"),
  clientCert: fs.readFileSync("client.pem"),
  clientKey: fs.readFileSync("client.key"),
  apiKey: "my-api-key",
});

API

new Client(addr: string, options?: ClientOptions)

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

Options:

| Option | Type | Description | |-------------|-----------|---------------------------------------------------------------------| | tls | boolean | Enable TLS using the OS system trust store. Implied when caCert is set. | | caCert | Buffer | CA certificate PEM. Enables TLS with a custom CA when set. | | clientCert| Buffer | Client certificate PEM for mTLS. Requires TLS to be enabled. | | clientKey | Buffer | Client private key PEM for mTLS. Requires TLS to be enabled. | | apiKey | string | API key sent as Bearer token on every RPC call. |

client.enqueue(queue, headers, payload): Promise<string>

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

client.consume(queue): AsyncIterable<ConsumeMessage>

Open a streaming consumer. Returns an async iterable that yields messages as they become available. Nacked messages are redelivered on the same stream.

client.ack(queue, msgId): Promise<void>

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

client.nack(queue, msgId, error): Promise<void>

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

client.close(): void

Close the underlying gRPC channel.

Error Handling

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

import { QueueNotFoundError, MessageNotFoundError } from "fila-client";

try {
  await client.enqueue("missing-queue", null, Buffer.from("test"));
} catch (err) {
  if (err instanceof QueueNotFoundError) {
    // handle queue not found
  }
}

try {
  await client.ack("my-queue", "missing-id");
} catch (err) {
  if (err instanceof MessageNotFoundError) {
    // handle message not found
  }
}

License

AGPLv3