# GoEventBus Examples

Runnable examples live under this directory. Run them from the repository root with `go run ./examples/<name>`.

## Intelligent routing

### `routing_rules`

Deterministic routing with `EventRule`.

```bash
go run ./examples/routing_rules
```

Flow:

```text
state -> rule match -> selected projection -> Subscribe -> Publish
```

No cache and no network request are needed.

### `routing_cache`

Shows how `MemoryDecisionCache` avoids repeated fallback decisions.

```bash
go run ./examples/routing_cache
```

The example submits the same state twice. The fallback selector is called once; the second decision is served from cache.

Flow:

```text
first call:  state -> cache miss -> fallback -> cache write
second call: state -> cache hit
```

### `routing_jev`

Full intelligent routing with deterministic rules, TTL cache, and Jev fallback through OpenRouter.

```bash
OPENROUTER_API_KEY=... go run ./examples/routing_jev
```

Flow:

```text
rules -> cache -> Jev -> cache write -> DecideAndSubscribe -> local queue
```

When the store is created with `WithRedis(...)` or `WithRabbitMQ(...)`, the
same `DecideAndSubscribe` call publishes the selected event to that broker
instead of enqueueing it locally.

The example exits without making a request when `OPENROUTER_API_KEY` is not set.

### `transaction_jev`

Uses the same Rules / Cache / Jev selector pipeline inside a transaction.
`DecideAndPublish` resolves the projection immediately and buffers the selected
event. On commit, local stores run regular handlers synchronously; stores created
with `WithRedis(...)`, `WithRabbitMQ(...)`, or `WithProvider(...)` publish the
buffered events to that provider instead.

```bash
OPENROUTER_API_KEY=... go run ./examples/transaction_jev
```

Flow:

```text
state -> rules/cache/Jev -> selected event -> transaction buffer -> Commit -> local handler OR broker
```

### `schedule_jev`

Uses Rules / Cache / Jev to resolve the event type before starting a timer.
The decision is made immediately; the selected event is dispatched only when
the timer fires.

```bash
OPENROUTER_API_KEY=... go run ./examples/schedule_jev
```

Flow:

```text
state -> rules/cache/Jev -> selected event -> timer -> Subscribe -> Publish -> handler
```

## Core event bus

| Example | Purpose |
|---|---|
| `hello_world` | Minimal direct event dispatch |
| `publisher` | Publishing multiple event types |
| `goroutines-subscribe-publisher` | Concurrent producers and publisher loop |
| `middleware` | Middleware and lifecycle hooks |
| `drop_oldest` | `DropOldest` back-pressure |
| `return_error` | `ReturnError` back-pressure |
| `publisher_timeout` | Blocking publisher timeout |
| `handler_timeout` | Handler context timeout |
| `fasthttp` | fasthttp integration |
| `redis` | Redis Streams configured directly on `NewEventStore` |
| `rabbitmq` | RabbitMQ configured directly on `NewEventStore` |
| `transaction_jev` | Rules/Cache/Jev event selection buffered until transaction commit |
| `schedule_jev` | Rules/Cache/Jev event selection before delayed scheduling |

## Broker-backed stores

Redis Streams and RabbitMQ are EventStore options, so application code does not
need to keep a separate provider variable:

```go
store := GoEventBus.NewEventStore(
    &dispatcher,
    1024,
    GoEventBus.Block,
    GoEventBus.WithRedis(redisConfig),
)
```

Use `store.PublishToProvider(ctx, event)` to send an event to the configured
broker and `store.Consume(ctx)` to consume broker events into the local
dispatcher.

Run the examples with a broker available locally:

```bash
go run ./examples/redis
go run ./examples/rabbitmq
```

## Choosing a routing path

Use direct `Subscribe` when your application already knows the projection
and is dispatching locally.

Use `PublishToProvider` when the projection is already known but the store is
broker-backed.

Use `DecideAndSubscribe` when the event type must be selected first. With
Redis or RabbitMQ configured on `NewEventStore`, the selected event is sent to
the broker automatically.

Use rules when the decision is deterministic.

Use cache when equivalent routing decisions repeat.

Use Jev when the input is ambiguous and the application needs to choose one event type from a bounded candidate set.