jay/go-honeybee
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README and CONFIG for post-refactor API

Browse Source
This commit is contained in:
Jay
2026-06-06 20:42:31 -04:00
parent fe119b3f36
commit 60de9534dc
2 changed files with 79 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONFIG.md
+39 -111
View File
@@ -1,146 +1,74 @@
# Configuration
All configuration is done through option functions applied at construction time. Invalid values return errors at application time; configs produced through `NewXConfig` constructors are validated at construction and cannot be saved in an invalid state.
There are three config scopes. `ConnectionConfig` governs a single WebSocket connection: its write behavior, ping interval, buffers, and retry policy. `WorkerConfig` governs a single worker's behavior. `PoolConfig` bundles a connection config, a worker config, and an optional worker factory — it is a thin container.
Logging can be controlled independently at the pool, worker, and connection levels. Each scope has a `LoggingEnabled` flag and a `LogLevel` override. When `LoggingEnabled` is false, no logger is constructed for that scope regardless of what handler is passed to the pool. When `LogLevel` is set, it overrides the handler's own level filter for that scope only, using a wrapping handler that enforces the minimum level before delegating. When `LogLevel` is nil, the handler's own level filtering applies unchanged.
All configuration uses option functions applied at construction time. Validation occurs at constructor time; a config value returned by a constructor is guaranteed to be valid. `PoolConfig` is the outermost scope and contains a `WorkerConfig`. `WorkerConfig` contains a `ConnectionConfig` and a `RetryConfig`. `RetryConfig` validation is skipped entirely when `RetryDisabled` is set on `WorkerConfig`, making the zero value of `RetryConfig` safe in that case. Logging is not config-controlled; pass an `slog.Handler` to pool, worker, and connection constructors directly.
## Defaults
| Scope | Setting | Default | Disabled by | Notes |
|---|---|---|---|---|
| Pool | `InboxBufferSize` | 256 | — | Must be positive |
| Pool | `EventsBufferSize` | 10 | — | Must be positive |
| Pool | `RequestHeader` | `User-Agent: honeybee/0.1.0` | `WithRequestHeader(nil)` | Cloned per dial call |
| Worker | `KeepaliveTimeout` | 60s | `0` | 0 disables keepalive |
| Worker | `ReconnectDelay` | 2s | `0` | 0 means reconnect immediately |
| Worker | Retry | enabled | `WithRetryDisabled()` | Skips RetryConfig validation when disabled |
| Connection | `WriteTimeout` | 30s | `0` | Per-message write deadline |
| Connection | `RequestHeader` | User-Agent | — | honeybee/0.1.0 |
| Connection | `PingInterval` | 20s | `0` | ±10% jitter applied per interval |
| Connection | `IncomingBufferSize` | 100 | — | Must be positive |
| Connection | `ErrorsBufferSize` | 10 | — | Must be positive |
| Connection | `LoggingEnabled` | true | `false` | |
| Connection | `LogLevel` | nil | — | nil defers to handler's own filter |
| Retry | enabled | yes | `WithRetryDisabled()` | Governs `Connect()` only |
| Retry | `MaxRetries` | 0 | — | 0 means infinite |
| Retry | `InitialDelay` | 1s | — | Must be positive |
| Retry | `MaxDelay` | 60s | — | Must be ≥ InitialDelay |
| Retry | `MaxDelay` | 60s | — | Must be ≥ `InitialDelay` |
| Retry | `JitterFactor` | 0.2 | `0.0` | Range [0.0, 1.0] |
| Pool | `InboxBufferSize` | 256 | — | Must be positive |
| Pool | `EventsBufferSize` | 10 | — | Must be positive |
| Pool | `LoggingEnabled` | true | `false` | |
| Pool | `LogLevel` | nil | — | |
| Worker | `KeepaliveTimeout` | 60s | `0` | 0 disables keepalive |
| Worker | `ReconnectDelay` | 2s | `0` | 0 means reconnect immediately |
| Worker | `LoggingEnabled` | true | `false` | |
| Worker | `LogLevel` | nil | — | |
## Connection Options
`ConnectionConfig` is defined in the `transport` package. Import `git.wisehodl.dev/jay/go-honeybee/transport` to construct one, then pass it to a pool via `honeybee.WithConnectionConfig`.
These options are passed to `transport.NewConnectionConfig`.
### Write Behavior
**`WithWriteTimeout(duration)`**
Sets a per-message write deadline. Applied before every call to `WriteMessage`. When set to zero, no deadline is applied. Must not be negative.
**`WithCloseHandler(func(code int, text string) error)`**
Installs a close handler on the underlying socket. Called when the remote peer sends a close frame.
**`WithRequestHeader(http.Header)`**
Sets custom HTTP headers to be sent during the WebSocket handshake. The default includes `User-Agent: honeybee/0.1.0`.
### Ping
**`WithPingInterval(duration)`**
Sets the interval at which the connection sends WebSocket ping frames. A ±10% jitter is applied to each interval to avoid synchronized pings across many connections. When set to zero, pings are disabled entirely, and only data messages and outbound sends generate heartbeat signals. Must not be negative.
### Buffers
**`WithIncomingBufferSize(int)`**
Sets the capacity of the channel that buffers inbound messages between the reader goroutine and the consumer. Must be at least 1.
**`WithErrorsBufferSize(int)`**
Sets the capacity of the channel that carries connection-level errors to the consumer. Must be at least 1.
### Dialer
**`WithConnectionDialer(types.Dialer)`**
Overrides the dialer used to establish the WebSocket connection. When not set, the connection uses the default dialer. Useful in tests or when routing connections through a custom transport.
### Retry
The retry policy governs the `Connect()` call only. It does not affect worker reconnection, which is controlled by `ReconnectDelay` on the worker config.
**`WithRetryDisabled()`**
Disables retry entirely. `Connect()` returns on the first dial failure.
**`WithRetryMaxRetries(int)`**
Caps the number of retry attempts. Zero means retry indefinitely. Must not be negative.
**`WithRetryInitialDelay(duration)`**
Sets the delay before the second dial attempt. The first retry is always immediate. Must be positive.
**`WithRetryMaxDelay(duration)`**
Caps the exponential backoff delay. Must be positive and at least as large as `InitialDelay`.
**`WithRetryJitterFactor(float64)`**
Adds randomization to each backoff delay. A value of 0.2 means the delay varies within ±10% of the base. Range: 0.0 to 1.0.
### Logging
**`WithConnectionLoggingEnabled(bool)`**
Enables or disables logging for the connection. When false, no logger is constructed regardless of the handler passed to the pool.
**`WithConnectionLogLevel(slog.Level)`**
Overrides the minimum log level for connection-scoped records. Does not affect pool or worker logging.
## Pool Options
Import `git.wisehodl.dev/jay/go-honeybee`.
These are passed to `honeybee.NewPoolConfig`. Import `git.wisehodl.dev/jay/go-honeybee`.
### Pool
**`WithInboxBufferSize(int)`** — sets the capacity of the shared inbox channel. Must be at least 1.
These are passed to `honeybee.NewPoolConfig`.
**`WithEventsBufferSize(int)`** — sets the capacity of the events channel. Must be at least 1.
**`honeybee.WithInboxBufferSize(int)`**
Sets the capacity of the pool's shared inbox channel. Must be at least 1.
**`WithWorkerConfig(WorkerConfig)`** — supplies the worker configuration applied to every peer the pool manages. Accepted by value.
**`honeybee.WithEventsBufferSize(int)`**
Sets the capacity of the pool's events channel. Must be at least 1.
**`WithRequestHeader(http.Header)`** — sets HTTP headers sent during the WebSocket handshake for every dial. The pool clones the header at option application time, so subsequent mutations to the original do not affect dial behavior. Pass `nil` to send no custom headers.
**`honeybee.WithPoolLoggingEnabled(bool)`**
Enables or disables pool-level logging.
**`WithDialFunc(func(context.Context) (types.Socket, error))`** — a per-call option passed to `pool.Connect`, not to `NewPoolConfig`. Overrides the pool's default dialer for a single connection. When provided, the pool's dialer and request header are not used for that connection.
**`honeybee.WithPoolLogLevel(slog.Level)`**
Overrides the minimum log level for pool-scoped records only.
## Worker Options
### Worker
These are passed to `honeybee.NewWorkerConfig`. Import `git.wisehodl.dev/jay/go-honeybee`.
These are passed to `honeybee.NewWorkerConfig` or embedded in the pool config.
**`WithConnectionConfig(transport.ConnectionConfig)`** — supplies the connection-level configuration (timeouts, buffers, ping interval). Import `git.wisehodl.dev/jay/go-honeybee/transport` to construct one.
**`honeybee.WithKeepaliveTimeout(duration)`**
Enables the keepalive mechanism. When no heartbeat (inbound data, outbound send, or pong reply) is observed within this duration, the current connection is closed and a new one is dialed. When set to zero, keepalive is disabled. Must not be negative.
**`WithRetryConfig(transport.RetryConfig)`** — supplies the retry policy used when dialing. Has no effect when `WithRetryDisabled` is also applied.
**`honeybee.WithReconnectDelay(duration)`**
Sets the delay between a disconnect and the next dial attempt. Applies after every session end, including those triggered by keepalive. The default of 2 seconds prevents tight reconnect loops against unavailable peers. Set to zero in tests or when immediate reconnection is required. Must not be negative.
**`WithRetryDisabled()`** — disables dial retry. The first dial failure is terminal for that connection attempt.
**`honeybee.WithWorkerLoggingEnabled(bool)`**
Enables or disables worker-level logging.
**`WithKeepaliveTimeout(duration)`** — enables the keepalive mechanism. When no heartbeat is observed within this duration, the connection is closed and a new dial is attempted. Set to zero to disable. Must not be negative.
**`honeybee.WithWorkerLogLevel(slog.Level)`**
Overrides the minimum log level for worker-scoped records only.
**`WithReconnectDelay(duration)`** — sets the wait between a disconnect and the next dial attempt. The default prevents tight reconnect loops against unavailable peers. Set to zero in tests or when immediate reconnection is required. Must not be negative.
### Per-connection
## Connection Options
**`honeybee.WithDialer(types.Dialer)`**
Overrides the dialer for a single `Connect` call. Passed as a variadic option: `pool.Connect(id, honeybee.WithDialer(d))`. When provided, it takes precedence over the dialer resolved from `ConnectionConfig`. Existing callers that pass no options are unaffected.
These are passed to `transport.NewConnectionConfig`. Import `git.wisehodl.dev/jay/go-honeybee/transport`.
### Wiring
**`WithWriteTimeout(duration)`** — sets a per-message write deadline. Applied before every `WriteMessage` call. Set to zero to disable. Must not be negative.
**`honeybee.WithConnectionConfig(transport.ConnectionConfig)`**
Supplies a connection config used when dialing each peer. Accepted by value; the pool stores its own copy.
**`WithPingInterval(duration)`** — sets the interval between WebSocket ping frames. A ±10% jitter is applied to each interval. Set to zero to disable pings entirely. Must not be negative.
**`honeybee.WithWorkerConfig(honeybee.WorkerConfig)`**
Supplies a worker config applied to every worker the pool creates. Accepted by value; the pool stores its own copy.
**`WithIncomingBufferSize(int)`** — sets the capacity of the channel buffering inbound messages. Must be at least 1.
**`honeybee.WithWorkerFactory(honeybee.WorkerFactory)`**
Replaces the default worker constructor. See [EXTEND.md](EXTEND.md) for the factory contract.
**`WithErrorsBufferSize(int)`** — sets the capacity of the channel carrying connection-level errors. Must be at least 1.
## Retry Options
These are passed to `transport.NewRetryConfig`. Import `git.wisehodl.dev/jay/go-honeybee/transport`. The resulting `RetryConfig` is then passed to `NewWorkerConfig` via `WithRetryConfig`.
**`WithMaxRetries(int)`** — caps the number of dial attempts after the first. Zero means retry indefinitely. Must not be negative.
**`WithInitialDelay(duration)`** — sets the delay before the second attempt. The first retry is always immediate. Must be positive.
**`WithMaxDelay(duration)`** — caps the exponential backoff delay. Must be positive and at least as large as `InitialDelay`.
**`WithJitterFactor(float64)`** — adds randomization to each backoff delay. A value of 0.2 varies the delay within ±10% of the computed base. Range: 0.0 to 1.0.
README.md
+40 -29
View File
@@ -5,19 +5,16 @@ WebSocket connection and pool primitives in Go. Built for Nostr.
## Library Map
```txt
honeybee.go Pool, Worker, public types
pool.go Pool, public types
worker.go Worker, WorkerConfig
transport/ single-connection primitives and helpers
connection.go Connection, state machine, reader goroutine, pinger
config.go ConnectionConfig, RetryConfig, options
connection.go Connection, reader goroutine, pinger
retry.go exponential backoff with jitter
socket.go Dialer interface, AcquireSocket
socket.go Dialer interface, DialWithRetry
url.go parsing and normalization
watchdog.go IdleWatchdog helper
logging/ structured log construction
logging.go logger constructors, ForcedLevelHandler
types/ shared interfaces (Dialer, Socket, ReceivedMessage)
honeybeetest/ test helpers and mocks for consumers
```
@@ -28,14 +25,12 @@ Honeybee is a minimal, general-purpose WebSocket transport library.
- Client-Side: Manage a pool of outbound peer connections that reconnect automatically and surface lifecycle events.
- Server-Side: Wrap already-upgraded sockets in the connection primitive, which provides a ping-based heartbeat, automated read-loop, concurrent-safe writes, and classified disconnect errors.
- The same connection primitive may also be used directly on the client side when pool semantics are not needed, providing automated dialing retry with exponential backoff and jitter.
- Exposes a means to completely replace the internal pool worker to inject custom behavior.
- The same primitives may also be used directly on the client side when pool semantics are not needed: `transport.DialWithRetry` acquires a socket with configurable exponential backoff and jitter, and the resulting socket can be wrapped in `transport.NewConnection` for the same read-loop, heartbeat, and write primitives without pool semantics.
## What This Library Does Not Do
Honeybee is a pure transport layer, but it is also a deliberately simple one. Honeybee does not provide advanced features, relying on its extensibility features to allow you to customize it.
Honeybee is a pure transport layer, but it is also a deliberately simple one. Honeybee does not provide:
Honeybee does not provide:
- interpretation of message content. All messages are treated equally.
- message queuing, buffering, prioritization, batching, or coalescing.
@@ -87,6 +82,7 @@ go func() {
case honeybee.EventConnected:
case honeybee.EventDisconnected:
case honeybee.EventDialFailed:
case honeybee.EventRetired:
}
}
}()
@@ -106,19 +102,21 @@ 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.
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.
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 worker's retry config. `EventDialFailed` is only sent when the peer fails to connect, not when dialing is stopped internally.
When a peer's retry policy is exhausted, the worker deregisters itself from the pool and emits `EventRetired` on `pool.Events()`. The default `RetryConfig` sets `MaxRetries` to zero, which means infinite retries — so in default operation `EventRetired` is structurally unreachable. It will only appear if you explicitly configure a positive `MaxRetries` via `WithRetryConfig`.
## Server-Side Usage
### Connection
Use `transport.NewConnectionFromSocket` when your HTTP upgrade handler gives you an open socket. The connection starts in `StateConnected`; do not call `Connect`.
Use `transport.NewConnection` when your HTTP upgrade handler gives you an open socket.
```go
import "git.wisehodl.dev/jay/go-honeybee/transport"
// wsConn is a *websocket.Conn from your upgrade handler
conn, err := transport.NewConnectionFromSocket(wsConn, nil, logger)
conn, err := transport.NewConnection(ctx, wsConn, nil, handler)
if err != nil { /* handle error */ }
defer conn.Close()
@@ -146,7 +144,7 @@ When the reader exits, exactly one classified error reaches `Errors()` before th
- `ErrPeerClosedUnexpected` for abnormal close codes
- `ErrReadError` for anything else
Pass an `*slog.Logger` as the third argument to get structured logs. Pass nil to disable logging entirely.
Pass an `slog.Handler` as the fourth argument to enable structured logging. Pass `nil` to disable it.
### IdleWatchdog
@@ -199,19 +197,36 @@ When no activity signal arrives within the timeout, `onTimeout` is called once a
## Bare Connection
Use `transport.NewConnection` when you need a single outbound connection without pool semantics — for example, a one-shot query or a custom use-case. It adds several conveniences over a raw socket: a retry loop with exponential backoff, concurrent-safe writes, automatic write deadline enforcement, classified disconnect errors, and observable connection state.
Use `transport.DialWithRetry` and `transport.NewConnection` together when you need a single outbound connection without pool semantics — for example, a one-shot query or a standalone client.
First, acquire a socket. Then wrap it in a connection:
```go
import "git.wisehodl.dev/jay/go-honeybee/transport"
conn, err := transport.NewConnection("wss://example.com", nil, nil)
if err != nil { /* handle error */ }
// Step 1: dial with retry
retryCfg, _ := transport.NewRetryConfig() // or configure via WithMaxRetries, etc.
mgr := transport.NewRetryManager(retryCfg)
if err := conn.Connect(ctx); err != nil { /* handle error */ }
onError := func(err error) {
// called for each failed attempt; use to log or surface per-attempt errors
}
dialFn := func(ctx context.Context) (types.Socket, error) {
socket, _, err := myDialer.DialContext(ctx, "wss://example.com", nil)
return socket, err
}
socket, err := transport.DialWithRetry(ctx, mgr, dialFn, onError, nil)
if err != nil { /* context cancelled or retry policy exhausted */ }
// Step 2: wrap the socket
conn, err := transport.NewConnection(ctx, socket, nil, nil)
if err != nil { /* handle error */ }
defer conn.Close()
go func() {
for data := range conn.Incoming() { // data: []byte
for data := range conn.Incoming() {
// process incoming messages
}
}()
@@ -226,7 +241,9 @@ go func() {
conn.Send([]byte("hello"))
```
The connection goes through four states: `StateDisconnected`, `StateConnecting`, `StateConnected`, `StateClosed`. Transitions are atomic and observable via `conn.State()`. Once closed, the connection should not be reused; construct a new one with the same URL and reconnect.
Pass `nil` for `mgr` to disable retry — the first dial failure is then terminal. Pass `nil` for `onError` to ignore per-attempt errors. Context cancellation terminates the retry loop at any point.
For `RetryConfig` and `RetryManager` construction options, see CONFIG.md.
`Send` is safe for concurrent callers. `Close` is idempotent and safe to call from any goroutine.
@@ -242,7 +259,7 @@ Connections send periodic WebSocket ping frames and listen for the corresponding
Pong-derived heartbeats reset the keepalive timer alongside data messages and sends. A peer that sends no data but responds to pings will not be disconnected and reconnected by the keepalive mechanism.
The ping interval is configured via `transport.WithPingInterval` on the `transport.ConnectionConfig`. Import `git.wisehodl.dev/jay/go-honeybee/transport` to construct a `ConnectionConfig`, then pass it to the pool by value via `honeybee.WithConnectionConfig`, or supply it directly to `NewConnection` and `NewConnectionFromSocket`. The default is 20 seconds. Set to zero to disable pings entirely, in which case only data messages and outbound sends generate heartbeats.
The ping interval is configured via `transport.WithPingInterval` on the `transport.ConnectionConfig`. Import `git.wisehodl.dev/jay/go-honeybee/transport` to construct a `ConnectionConfig`, then wrap it in a `WorkerConfig` via `honeybee.WithConnectionConfig`, and pass the `WorkerConfig` to `NewPoolConfig` via `honeybee.WithWorkerConfig`. You can also supply the `ConnectionConfig` directly to `transport.NewConnection`. The default is 20 seconds. Set to zero to disable pings entirely, in which case only data messages and outbound sends generate heartbeats.
## Statistics
@@ -266,15 +283,9 @@ connStats := conn.Stats() // conn is a *transport.Connection
// connStats.TotalReceived, connStats.TotalSent, connStats.TotalHeartbeats
```
## Extending Pools
The pool owns peer registration, event plumbing, and lifecycle. The worker owns what happens on the wire. The default worker can be replaced entirely via `WorkerFactory`.
See EXTEND.md for the worker interface contract, the `PoolPlugin` fields, and extension patterns.
## Configuration
All configuration is done through option functions applied at construction time. There are three config scopes: `ConnectionConfig`, `WorkerConfig`, and `PoolConfig`. Logging can be enabled and its minimum level overridden independently at the pool, worker, and connection levels.
All configuration is done through option functions applied at construction time. `PoolConfig` is the top-level scope and embeds a `WorkerConfig`. `WorkerConfig` embeds both a `ConnectionConfig` and a `RetryConfig`. Consumers configure connection and retry behavior through this chain. Logging is not config-controlled; pass an `slog.Handler` to pool, worker, and connection constructors directly.
See CONFIG.md for the full option reference and defaults table.