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

update docs

Browse Source
This commit is contained in:
Jay
2026-06-07 09:24:19 -04:00
parent df14aeddaf
commit 9dadaf6b6d
2 changed files with 21 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONFIG.md
+8 -8
View File
@@ -1,6 +1,6 @@
# Configuration # Configuration
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. 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 `SessionConfig`. `SessionConfig` contains a `ConnectionConfig` and a `RetryConfig`. `RetryConfig` validation is skipped entirely when `RetryDisabled` is set on `SessionConfig`, making the zero value of `RetryConfig` safe in that case. Logging is not config-controlled; pass an `slog.Handler` to pool, session, and connection constructors directly.
## Defaults ## Defaults
@@ -9,9 +9,9 @@ All configuration uses option functions applied at construction time. Validation
| Pool | `InboxBufferSize` | 256 | — | Must be positive | | Pool | `InboxBufferSize` | 256 | — | Must be positive |
| Pool | `EventsBufferSize` | 10 | — | Must be positive | | Pool | `EventsBufferSize` | 10 | — | Must be positive |
| Pool | `RequestHeader` | `User-Agent: honeybee/0.1.0` | `WithRequestHeader(nil)` | Cloned per dial call | | Pool | `RequestHeader` | `User-Agent: honeybee/0.1.0` | `WithRequestHeader(nil)` | Cloned per dial call |
| Worker | `KeepaliveTimeout` | 60s | `0` | 0 disables keepalive | | Session | `KeepaliveTimeout` | 60s | `0` | 0 disables keepalive |
| Worker | `ReconnectDelay` | 2s | `0` | 0 means reconnect immediately | | Session | `ReconnectDelay` | 2s | `0` | 0 means reconnect immediately |
| Worker | Retry | enabled | `WithRetryDisabled()` | Skips RetryConfig validation when disabled | | Session | Retry | enabled | `WithRetryDisabled()` | Skips RetryConfig validation when disabled |
| Connection | `WriteTimeout` | 30s | `0` | Per-message write deadline | | Connection | `WriteTimeout` | 30s | `0` | Per-message write deadline |
| Connection | `PingInterval` | 20s | `0` | ±10% jitter applied per interval | | Connection | `PingInterval` | 20s | `0` | ±10% jitter applied per interval |
| Connection | `IncomingBufferSize` | 100 | — | Must be positive | | Connection | `IncomingBufferSize` | 100 | — | Must be positive |
@@ -29,15 +29,15 @@ These are passed to `honeybee.NewPoolConfig`. Import `git.wisehodl.dev/jay/go-ho
**`WithEventsBufferSize(int)`** — sets the capacity of the events channel. Must be at least 1. **`WithEventsBufferSize(int)`** — sets the capacity of the events channel. Must be at least 1.
**`WithWorkerConfig(WorkerConfig)`** — supplies the worker configuration applied to every peer the pool manages. Accepted by value. **`WithSessionConfig(SessionConfig)`** — supplies the session configuration applied to every peer the pool manages. Accepted by value.
**`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. **`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.
**`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. **`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.
## Worker Options ## Session Options
These are passed to `honeybee.NewWorkerConfig`. Import `git.wisehodl.dev/jay/go-honeybee`. These are passed to `honeybee.NewSessionConfig`. Import `git.wisehodl.dev/jay/go-honeybee`.
**`WithConnectionConfig(transport.ConnectionConfig)`** — supplies the connection-level configuration (timeouts, buffers, ping interval). Import `git.wisehodl.dev/jay/go-honeybee/transport` to construct one. **`WithConnectionConfig(transport.ConnectionConfig)`** — supplies the connection-level configuration (timeouts, buffers, ping interval). Import `git.wisehodl.dev/jay/go-honeybee/transport` to construct one.
@@ -63,7 +63,7 @@ These are passed to `transport.NewConnectionConfig`. Import `git.wisehodl.dev/ja
## Retry Options ## 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`. These are passed to `transport.NewRetryConfig`. Import `git.wisehodl.dev/jay/go-honeybee/transport`. The resulting `RetryConfig` is then passed to `NewSessionConfig` via `WithRetryConfig`.
**`WithMaxRetries(int)`** — caps the number of dial attempts after the first. Zero means retry indefinitely. Must not be negative. **`WithMaxRetries(int)`** — caps the number of dial attempts after the first. Zero means retry indefinitely. Must not be negative.
README.md
+13 -13
View File
@@ -6,7 +6,7 @@ WebSocket connection and pool primitives in Go. Built for Nostr.
```txt ```txt
pool.go Pool, public types pool.go Pool, public types
worker.go Worker, WorkerConfig session.go SessionConfig
transport/ single-connection primitives and helpers transport/ single-connection primitives and helpers
connection.go Connection, reader goroutine, pinger connection.go Connection, reader goroutine, pinger
@@ -68,9 +68,9 @@ if err := pool.Connect("wss://peer.example.com"); err != nil { /* handle error *
go func() { go func() {
for msg := range pool.Inbox() { for msg := range pool.Inbox() {
// msg.ID is the normalized URL // msg.URL is the normalized URL
// msg.Data is the payload // msg.Data is the payload
// msg.ReceivedAt is the timestamp // msg.ReceivedAt is the timestamp
} }
}() }()
@@ -96,15 +96,15 @@ pool.Send("wss://peer.example.com", []byte("hello"))
Every time a connection is established, `honeybee.EventConnected` is emitted. Every time a connection drops for any reason, `honeybee.EventDisconnected` is emitted. A peer that reconnects three times produces three Connected/Disconnected pairs. Every time a connection is established, `honeybee.EventConnected` is emitted. Every time a connection drops for any reason, `honeybee.EventDisconnected` is emitted. A peer that reconnects three times produces three Connected/Disconnected pairs.
Keepalive is configured via `honeybee.WithKeepaliveTimeout`. The worker records a heartbeat on every inbound message, every successful send, and every received pong. If no heartbeats arrive before the keepalive timer fires, the connection is proactively disconnected and reconnected. When set to zero, keepalive is disabled. Keepalive is configured via `honeybee.WithKeepaliveTimeout`. The session records a heartbeat on every inbound message, every successful send, and every received pong. If no heartbeats arrive before the keepalive timer fires, the connection is proactively disconnected and reconnected. When set to zero, keepalive is disabled.
After a disconnect, the worker waits for `ReconnectDelay` before attempting the next connection. The default is 2 seconds. Set to zero in tests or when you need immediate reconnection. After a disconnect, the session waits for `ReconnectDelay` before attempting the next connection. The default is 2 seconds. Set to zero in tests or when you need immediate reconnection.
`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. `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 worker'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 session'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`. When a peer's retry policy is exhausted, the session 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 ## Server-Side Usage
@@ -255,15 +255,15 @@ When the reader exits, exactly one classified error reaches `Errors()` before th
## Ping-Pong Heartbeats ## Ping-Pong Heartbeats
Connections send periodic WebSocket ping frames and listen for the corresponding pong replies. A received pong registers as a heartbeat signal within the worker. Connections send periodic WebSocket ping frames and listen for the corresponding pong replies. A received pong registers as a heartbeat signal within the session.
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. 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 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. 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 `SessionConfig` via `honeybee.WithConnectionConfig`, and pass the `SessionConfig` to `NewPoolConfig` via `honeybee.WithSessionConfig`. 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 ## Statistics
Pools, workers, and connections expose counters and channel depths that can be sampled at any time. All values are snapshots; counters are monotonically increasing and are not reset between reconnects. Pools and connections expose counters and channel depths that can be sampled at any time. All values are snapshots; counters are monotonically increasing and are not reset between reconnects.
```go ```go
// Pool-level snapshot // Pool-level snapshot
@@ -276,7 +276,7 @@ stats := pool.Stats()
// Single peer // Single peer
peerStats, err := pool.PeerStats(peerID) peerStats, err := pool.PeerStats(peerID)
// peerStats.Worker — channel depths, processed/sent counts // peerStats.Session — channel depths, processed/sent counts
// Bare connection (transport package) // Bare connection (transport package)
connStats := conn.Stats() // conn is a *transport.Connection connStats := conn.Stats() // conn is a *transport.Connection
@@ -285,7 +285,7 @@ connStats := conn.Stats() // conn is a *transport.Connection
## Configuration ## Configuration
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. All configuration is done through option functions applied at construction time. `PoolConfig` is the top-level scope and embeds a `SessionConfig`. `SessionConfig` 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, session, and connection constructors directly.
See CONFIG.md for the full option reference and defaults table. See CONFIG.md for the full option reference and defaults table.