Skip to main content

Getting Started

This guide walks through FLUX end-to-end using both SDKs.

Requirements​

  • Go 1.24+
  • Node.js 18+
  • npm or pnpm

Start Broker​

From flux/core:

go run ./cmd/broker

Default listen address: localhost:9092.

Build TypeScript SDK​

cd ../packages/sdk/typescript
npm install
npm run build

Install Python SDK​

cd ../packages/sdk/python
pip install .

1) Produce Records (TypeScript)​

import { FLUXClient } from '@flux/typescript-sdk';

const client = new FLUXClient({ host: '127.0.0.1', port: 9092 });
await client.connect();

await client.produce('orders', 'user1', 'created', '1');
await client.produce('orders', 'user1', 'paid', '1');

2) Consumer Group Lifecycle (TypeScript)​

const join = await client.join('analytics', 'orders', 'consumer-a', 'round_robin');
const sync = await client.sync('analytics', 'orders', 'consumer-a', join.generation);
await client.heartbeat('analytics', 'orders', 'consumer-a', sync.generation);

3) Consume and Commit​

for (const partition of sync.assigned) {
  const start = await client.offset('analytics', 'orders', partition);
  const messages = await client.consume('orders', partition, start);
  if (messages.length > 0) {
    const nextOffset = messages[messages.length - 1].offset + 1;
    await client.commit('analytics', 'orders', 'consumer-a', sync.generation, partition, nextOffset);
  }
}

4) Leave and Close​

await client.leave('analytics', 'orders', 'consumer-a', sync.generation);
await client.close();

4.1) Basic Python SDK Flow​

from flux_sdk import FLUXClient

client = FLUXClient(host="127.0.0.1", port=9092)
client.connect()

produced = client.produce("orders", "user1", "created", acks="1")
messages = client.consume("orders", produced.partition, 0)
print(messages)

client.close()

5) Run the Included Example​

cd packages/sdk/typescript
npm run build
npx tsc --module commonjs --target es2020 --outDir examples/dist examples/basic-usage.ts
node examples/dist/basic-usage.js

5.1) Operator/Admin Flow (Separate from App Runtime)​

Admin control-plane APIs are typically used by platform/operator tooling, not normal app producer/consumer paths.

TypeScript admin example:

cd packages/sdk/typescript
npx tsc --module commonjs --target es2020 --outDir examples/dist examples/admin-usage.ts
node examples/dist/admin-usage.js

6) Validate Persistence​

  1. produce and commit some offsets
  2. stop broker
  3. start broker again
  4. read previously committed offsets/messages

Persisted files include:

  • offsets.json
  • groups.json
  • segment and index files

7) Run Core Tests​

cd ../../core
go test ./...

Optional: Low-Level Protocol Debugging​

For low-level troubleshooting, inspect Protocol. Normal application usage should go through TypeScript SDK methods.