> ## Documentation Index
> Fetch the complete documentation index at: https://abxbus.archivebox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Middleware integrations for EventBus lifecycle hooks across runtimes.

Middlewares can observe event lifecycle transitions, react to handler registration changes, and add cross-cutting behavior around event execution.

## Quick setup

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from abxbus import EventBus
    from abxbus.middlewares import LoggerEventBusMiddleware, WALEventBusMiddleware

    bus = EventBus(
        name='MyBus',
        middlewares=[
            WALEventBusMiddleware('./events.jsonl'),
            LoggerEventBusMiddleware('./events.log'),
        ],
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    import { BaseEvent, EventBus, type EventStatus } from 'abxbus'
    import type { EventBusMiddleware } from 'abxbus/middlewares'

    class LoggingMiddleware implements EventBusMiddleware {
      async onEventChange(eventbus: EventBus, event: BaseEvent, status: EventStatus): Promise<void> {
        if (status === 'completed') {
          console.log(`[${eventbus.label}] ${event.event_type}#${event.event_id.slice(-4)}`)
        }
      }
    }

    const bus = new EventBus('MyBus', {
      middlewares: [LoggingMiddleware],
    })
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    bus := abxbus.NewEventBus("MyBus", &abxbus.EventBusOptions{
    	Middlewares: []abxbus.EventBusMiddleware{},
    })
    ```

    Go currently ships the middleware interface only. Middleware implementations that require optional third-party packages are not included in the core Go module so those dependencies do not become hard requirements.
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // Not implemented in the Rust crate yet.
    // Use typed event JSON serialization with an external transport for now.
    ```
  </Tab>
</Tabs>

## Middleware interface

Use three optional hooks:

* Event lifecycle: `on_event_change` / `onEventChange`
* Handler-result lifecycle: `on_event_result_change` / `onEventResultChange`
* Handler registration lifecycle: `on_bus_handlers_change` / `onBusHandlersChange`

See [EventBusMiddleware](../api/eventbusmiddleware) for full signatures and custom middleware examples.

## Lifecycle

Middleware hooks receive lifecycle statuses in strict order:

* Event hooks: `pending` -> `started` -> `completed`
* Event-result hooks: `pending` -> `started` -> `completed`
* Handler registration hooks: called when handlers are added or removed via `on(...)` and `off(...)`

`status` passed to lifecycle hooks is never `error`. Handler failures are exposed on `event_result.status` and `event_result.error` during the `completed` callback.

## Built-in classes

<Tabs>
  <Tab title="Python">
    * [OtelTracingMiddleware](./middleware-otel-tracing)
    * [AutoErrorEventMiddleware](./middleware-auto-error)
    * [AutoReturnEventMiddleware](./middleware-auto-return)
    * [AutoHandlerChangeEventMiddleware](./middleware-auto-handler-change)
    * [WALEventBusMiddleware](./middleware-wal)
    * [LoggerEventBusMiddleware](./middleware-logger)
    * [SQLiteHistoryMirrorMiddleware](./middleware-sqlite-history-mirror)
  </Tab>

  <Tab title="TypeScript">
    * [OtelTracingMiddleware](./middleware-otel-tracing) via `abxbus/OtelTracingMiddleware`
  </Tab>

  <Tab title="Go">
    * Middleware interface only.
  </Tab>
</Tabs>