Quickstart

The current distribution is a source checkout. Published binaries and production configuration are not ready yet.

Prerequisites

Docker (recommended), or a current Rust toolchain and Git to build from source.

Run the broker

The quickest path is the published main image from GitHub Container Registry:

docker pull ghcr.io/axmouth/fibril-server:main
docker run --rm \
  -p 9876:9876 \
  -p 8081:8081 \
  -v fibril-server-data:/app/server_data \
  ghcr.io/axmouth/fibril-server:main

The main tag is a moving pre-release image. CI also publishes immutable sha-<commit> tags for exact builds.

As a backup, run from a source checkout instead:

git clone https://github.com/Axmouth/fibril.git
cd fibril
cargo run --release --bin fibril-server

Either way, the development server currently:

• listens for broker TCP traffic on 9876
• serves the early admin interface on 8081
• stores durable state under server_data/ (the fibril-server-data volume with Docker)
• uses development authentication defaults in the server binary

Do not expose this development server directly to the public internet.

Client shape

Fibril has Rust, TypeScript, and Python clients over the same broker surface: publishers, delayed publish, and manual-ack subscriptions. The examples are for the current pre-alpha source tree, not a stable package contract.

Rust

The Rust client lives in crates/client.

let client = ClientOptions::new()
    .auth("fibril", "fibril")
    .connect("127.0.0.1:9876")
    .await?;

let publisher = client.publisher("email.send")?;
publisher.publish("hello").await?;
publisher.publish_delayed("hello later", 30u64).await?;

let mut sub = client
    .subscribe("email.send")?
    .prefetch(32)
    .sub()
    .await?;

while let Some(msg) = sub.recv().await {
    process(msg.content()?).await?;
    msg.complete().await?;
}

TypeScript

The TypeScript client lives in clients/typescript. Delays are in milliseconds.

import { ClientOptions, NewMessage } from "@fibril/client";

const client = await new ClientOptions()
  .withAuth("fibril", "fibril")
  .connect("127.0.0.1:9876");

const publisher = client.publisher("email.send");
await publisher.publish(NewMessage.json({ body: "hello" }));
await publisher.publishDelayed(NewMessage.json({ body: "hello later" }), 30_000);

const sub = await client
  .subscribe("email.send")
  .prefetch(32)
  .sub();

for await (const msg of sub) {
  const body = msg.deserialize<{ body: string }>();
  await process(body);
  await msg.complete();
}

Python

The Python client lives in clients/python. Delays are seconds (a float or a timedelta). A synchronous fibril.blocking.BlockingClient mirrors the same API without async.

Async

from fibril import ClientOptions, NewMessage

client = await ClientOptions().with_auth("fibril", "fibril").connect("127.0.0.1:9876")

publisher = client.publisher("email.send")
await publisher.publish(NewMessage.json({"body": "hello"}))
await publisher.publish_delayed(NewMessage.json({"body": "hello later"}), 30)

sub = await client.subscribe("email.send").prefetch(32).sub()
async for msg in sub:
    await process(msg.deserialize())
    await msg.complete()

Blocking

from fibril import ClientOptions, NewMessage
from fibril.blocking import BlockingClient

client = BlockingClient.connect(
    "127.0.0.1:9876", ClientOptions().with_auth("fibril", "fibril")
)

publisher = client.publisher("email.send")
publisher.publish(NewMessage.json({"body": "hello"}))
publisher.publish_delayed(NewMessage.json({"body": "hello later"}), 30)

sub = client.subscribe("email.send").prefetch(32).sub()
for msg in sub:
    process(msg.deserialize())
    msg.complete()

The API is evolving. Treat examples as a guide to the current source tree rather than a stable package contract.

For more publishing, subscription, delayed publish, and message encoding examples, see client usage.

For startup config, runtime settings, and idle queue cleanup options, see configuration.

Try a cluster

To stand up a real multi-broker cluster locally and watch ownership, replication, and failover from the admin dashboard, see try a cluster with Docker in under a minute. Clustering is experimental.