Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 52 additions & 1 deletion content/docs/sdk/node/intro.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ cargo run --bin iggy-server -- --fresh --with-default-root-credentials

The environment variables make the server reachable through the published port (it binds to `127.0.0.1` inside the container by default) and set the root credentials the samples log in with. Without `--with-default-root-credentials` (or the `IGGY_ROOT_USERNAME` / `IGGY_ROOT_PASSWORD` variables), a first boot generates a random root password instead of `iggy`/`iggy`. For source runs, `--fresh` deletes existing local server data. Explicit credential environment variables take precedence over the default-root flag; bootstrap settings do not replace credentials already stored in recovered data.

Save the following snippets as `producer.mjs` and `consumer.mjs` in the project where you installed the SDK. Run `node producer.mjs` before `node consumer.mjs`.
Save the following snippets as `producer.mjs` and `consumer.mjs` in the project where you installed the SDK. Run `node producer.mjs` before `node consumer.mjs`. A consumer group sample follows them.

### Producer

Expand Down Expand Up @@ -121,6 +121,57 @@ await client.destroy();

The poll response does not wait for the auto-commit to finish. The sample processes messages after polling, so auto-commit does not confirm that the application handled each message.

### Consumer group

A consumer group lets several consumers share a topic. The server assigns partitions to the members and stores the group's offset. Save this as `consumer-group.mjs`:

```typescript
import { Client, PollingStrategy, Consumer } from 'apache-iggy';

const STREAM_NAME = 'sample-stream';
const TOPIC_NAME = 'sample-topic';
const GROUP_NAME = 'sample-group';

const client = new Client({
transport: 'TCP',
options: { port: 8090, host: '127.0.0.1' },
credentials: { username: 'iggy', password: 'iggy' },
});

// Creates the group if it is missing, then joins it.
const group = await client.group.ensureAndJoin(STREAM_NAME, TOPIC_NAME, GROUP_NAME);

// The server assigns partitions to each group member, so partitionId is null.
const polledMessages = await client.message.poll({
streamId: STREAM_NAME,
topicId: TOPIC_NAME,
consumer: Consumer.Group(group.id),
partitionId: null,
pollingStrategy: PollingStrategy.Next,
count: 10,
autocommit: true,
});

for (const message of polledMessages.messages) {
const payload = message.payload.toString('utf8');
console.log(`Offset: ${message.headers.offset}, Payload: ${payload}`);
}

await client.destroy();
```

The group's offset is separate from the single consumer's, so the first run of `node consumer-group.mjs` reads the topic from offset 0 even after `consumer.mjs` has run.

### Running the samples again

All three samples can be run again without changes:

- `node producer.mjs` finds the existing stream and topic and appends ten more messages.
- `node consumer.mjs` prints only the new messages, because `PollingStrategy.Next` continues after the stored offset. With nothing new to read, it prints nothing.
- `node consumer-group.mjs` does the same from the group's stored offset.

To start again with an empty server, stop the container and run the `docker run` command again. `--rm` removes the container and its data.

## Configuration

The client constructor accepts a few options:
Expand Down
Loading