> ## Documentation Index
> Fetch the complete documentation index at: https://stars-components.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# @wolfstar/plugin-broker

> Changelog for @wolfstar/plugin-broker: distribute gateway events across processes over Redis Streams.

Changes to [`@wolfstar/plugin-broker`](https://github.com/wolfstar-project/plugins/tree/main/packages/plugin-broker). The plugin distributes gateway events across processes over [Redis Streams](https://redis.io/docs/latest/develop/data-types/streams/), with consumer-group semantics and at-least-once delivery. For the weekly summary across all packages, see the [changelog overview](https://stars-components.js.org/documentation/changelog/index.md).

## `0.7.0` (2026-10-20)

### New features

* **Own `stars.config` key** — The module sets `meta.configKey`, so you can write its options under the top-level `broker` key of `stars.config` instead of the `[specifier, options]` tuple of `modules`. The tuple still works and is merged over the key. The key is typed in `defineConfig` once the module is imported in `stars.config.ts`. ([#259](https://github.com/wolfstar-project/plugins/pull/259))

### Updates

* **New optional peer** — `@wolfstar/schema` (`^0.9.0`) is a new optional peer that carries the `StarsConfig` type the keys extend.
* **Dependencies** — Updated `@wolfstar/plugin-cache` to `0.8.0`.

### Migration

* **`@wolfstar/kit` peer raised** — The `@wolfstar/kit` peer range moves from `^0.1.0` to `^0.2.0`, the first version that reads `configKey`. If your project uses `@wolfstar/kit` 0.1, update it.

## `0.6.0` (2026-10-17)

### New features

* **Worker-only dispatch listeners** — `forwardGatewayDispatches` marks a `GatewayClient` as forwarding (`forwardsDispatches`) until its stop function is called, through the new optional `GatewayDispatchEmitterLike#markDispatchesForwarded`. Listeners registered with `RegisterAsDispatchListener` from `@wolfstar/plugin-gateway` then run on the workers only. Emitters without it forward as before. ([#245](https://github.com/wolfstar-project/plugins/pull/245))

### Bug fixes

* **`guildDelete` for guilds dropped on `READY`** — When a `READY` no longer lists a cached guild (the bot left it while offline), its `GUILD_DELETE` is now forwarded like any other dispatch, so a worker's `guildDelete` listeners clean these guilds up too. ([#247](https://github.com/wolfstar-project/plugins/pull/247))

## `0.5.1` (2026-10-07)

### Updates

* **Dependencies** — Updated `@wolfstar/plugin-cache` to `0.7.0`.

## `0.5.0` (2026-10-05)

### New features

* **`/module` and `/plugin` entrypoints** — Adds `@wolfstar/plugin-broker/module` and `@wolfstar/plugin-broker/plugin`. List the module in `modules` in `stars.config`, or pass the `definePlugin` factory to `plugins`. Both need `@wolfstar/http-framework` 6.1 (and `@wolfstar/kit` for the module). `./register` is unchanged and still supports framework v3, v5, and v6. ([#192](https://github.com/wolfstar-project/plugins/pull/192))

### Updates

* **Dependencies** — Updated `@wolfstar/plugin-cache` to `0.6.0`.

## `0.4.1` (2026-10-04)

### Updates

* **`http-framework` 6 support** — The peer range now accepts [`@wolfstar/http-framework`](https://stars-components.js.org/documentation/changelog/stars-components/http-framework) `^6.0.0`. ([#176](https://github.com/wolfstar-project/plugins/pull/176))

## `0.4.0` (2026-10-02)

### New features

* **`replayGatewayDispatches`** — Replays the dispatches that `forwardGatewayDispatches` publishes on a `GatewayClient` that never connects to Discord. Your workers can run `EventGatewayListener` pieces with the same structures and previous state (`old` arguments) as the gateway process. ([#168](https://github.com/wolfstar-project/plugins/pull/168))
* **Entry metadata** — Stream entries gain optional `state` (the previous state of the dispatch's entity, encoded like the payload), `shard`, and `sequence` (the gateway sequence number) fields. Pass them to `publish` as `options` and read them from `BrokerMessage`. Entries without them, and consumers unaware of them, work as before.

### Updates

* **Dependencies** — Updated `@wolfstar/plugin-cache` to `0.5.1`.

## `0.3.1`

### Updates

* **Cache alignment** — Updated to [`@wolfstar/plugin-cache`](https://stars-components.js.org/documentation/changelog/plugins/plugin-cache) `0.5.0`.

## `0.3.0`

### New features

* **Claim idle entries** — `claimIdle` claims (`XAUTOCLAIM`) entries that any consumer of the group left pending for too long, for example one that crashed and never restarted under the same name.
* **Dead-letter stream** — `maxDeliveries` moves an entry that keeps failing to a dead-letter stream instead of retrying it forever. Set the stream with `deadLetterStream` (`<stream>:dead` by default).
* **Graceful shutdown** — `shutdownSignals` stops the consumer on the given process signals. The consumer awaits the in-flight entry before letting the signal end the process.
* **`forwardGatewayDispatches`** — Publishes every dispatch a [`@wolfstar/plugin-gateway`](https://stars-components.js.org/documentation/changelog/plugins/plugin-gateway) `GatewayClient` receives onto a broker, once it is written to the client's cache.

### Bug fixes

* **Pending entries drain** — A consumer could never drain its own pending entries: an entry that failed again was re-read forever, so the consumer never moved on to new entries. It now moves on.
* **Trimmed entries** — An entry trimmed from the stream while pending is now acknowledged instead of failing to decode.

## `0.2.0`

### New features

* **New package** — `@wolfstar/plugin-broker` distributes gateway events across processes over Redis Streams. `createBroker` publishes events. `ClientOptions.broker` configures a `BrokerConsumer`, started automatically once the client starts listening. The consumer reads events through a consumer group and redelivers a restarted consumer's own pending entries.
* **`BrokerListener` pieces** — Loaded from the `listeners` directory, like `EventGatewayListener` in `@wolfstar/plugin-gateway`. Listeners are typed per event through an augmentable `BrokerEvents` map. An entry is acknowledged only once every matching listener has resolved, so a throwing listener leaves its entry pending.
* **Pluggable payload codec** — Payloads are encoded with a `CacheCodec` from [`@wolfstar/plugin-cache`](https://stars-components.js.org/documentation/changelog/plugins/plugin-cache) (`jsonCodec()` by default).

### Updates

* **Dependencies** — Updated [`@wolfstar/plugin-cache`](https://stars-components.js.org/documentation/changelog/plugins/plugin-cache) to `0.4.0`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.