diff --git a/EXTEND.md b/EXTEND.md index f81d785..76863a5 100644 --- a/EXTEND.md +++ b/EXTEND.md @@ -42,7 +42,7 @@ type PoolPlugin struct { **`Inbox`** The shared channel that delivers received messages to the pool's consumer. All peers in the pool deliver to the same inbox channel. Workers must include their peer ID in each `InboxMessage`. -**`Events`** The shared channel for lifecycle events. Workers emit `honeybee.EventConnected` and `honeybee.EventDisconnected` directly. All events include a timestamp in the `At` field. +**`Events`** The shared channel for lifecycle events. Workers emit `honeybee.EventConnected`, `honeybee.EventDisconnected`, and `honeybee.EventDialFailed` directly. All events include a timestamp in the `At` field. `EventDialFailed` events also carry a non-nil `Err` field containing the dialer error. **`InboxCounter`** An atomic counter owned by the pool. Workers must increment this once for each message forwarded to `Inbox`. The pool reads it in `Stats()`. @@ -66,7 +66,7 @@ The factory is set via `honeybee.WithWorkerFactory` on the pool config. ### Replacing the Worker -Satisfy the `Worker` interface and register your implementation via `honeybee.WithWorkerFactory`. Your worker is responsible for the full connection lifecycle: dialing and redialing, managing connection state, forwarding received messages to `pool.Inbox`, emitting `EventConnected` and `EventDisconnected` to `pool.Events`, and incrementing `pool.InboxCounter` for each message forwarded. +Satisfy the `Worker` interface and register your implementation via `honeybee.WithWorkerFactory`. Your worker is responsible for the full connection lifecycle: dialing and redialing, managing connection state, forwarding received messages to `pool.Inbox`, emitting `EventConnected`, `EventDisconnected`, and `EventDialFailed` to `pool.Events`, and incrementing `pool.InboxCounter` for each message forwarded. `DefaultWorker`'s source is the authoritative reference for how those responsibilities are met. diff --git a/README.md b/README.md index 7399be3..a971fc3 100644 --- a/README.md +++ b/README.md @@ -82,9 +82,11 @@ go func() { go func() { for ev := range pool.Events() { // ev.At is the event timestamp + // ev.Err is non-nil for EventDialFailed switch ev.Kind { case honeybee.EventConnected: case honeybee.EventDisconnected: + case honeybee.EventDialFailed: } } }() @@ -104,7 +106,7 @@ After a disconnect, the worker waits for `ReconnectDelay` before attempting the `Send` returns `ErrConnectionUnavailable` during the gap between a disconnect and the next successful reconnect. Callers should wait for `EventConnected` before retrying and maintain their own write buffers if needed. -Dial failures are handled internally by the worker's retry logic and documented in structured logs. These do not stop the pool; it continues retrying according to the connection's retry config. +Each failed dial attempt emits `EventDialFailed` on `pool.Events()` with the dialer error in `ev.Err`. These do not stop the pool; it continues retrying according to the connection's retry config. `EventDialFailed` is only sent when the peer fails to connect, not when dialing is stopped internally. ## Server-Side Usage