117 lines
2.5 KiB
Markdown
117 lines
2.5 KiB
Markdown
# go-honeybee - WebSocket Connection Management for Go
|
|
|
|
Source: https://git.wisehodl.dev/jay/go-honeybee
|
|
|
|
Mirror: https://github.com/wisehodl/go-honeybee
|
|
|
|
## What this library does
|
|
|
|
`go-honeybee` provides reliable WebSocket connection primitives with automatic reconnection. It manages connection lifecycle, exponential backoff retry, and thread-safe message handling.
|
|
|
|
## What this library does not do
|
|
|
|
`go-honeybee` does not implement protocol-specific message parsing, subscription management, or connection pooling (yet). It provides the foundation for building protocol implementations (like Nostr clients) on top of stable WebSocket connections.
|
|
|
|
## Installation
|
|
|
|
Add `go-honeybee` to your project:
|
|
|
|
```bash
|
|
go get git.wisehodl.dev/jay/go-honeybee
|
|
```
|
|
|
|
If the primary repository is unavailable, use the `replace` directive in your go.mod:
|
|
|
|
```
|
|
replace git.wisehodl.dev/jay/go-honeybee => github.com/wisehodl/go-honeybee latest
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Connection
|
|
|
|
```go
|
|
import "git.wisehodl.dev/jay/go-honeybee"
|
|
|
|
// Create connection
|
|
conn, err := honeybee.NewConnection("wss://relay.example.com", nil)
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
defer conn.Close()
|
|
|
|
// Connect with default retry disabled
|
|
if err := conn.Connect(); err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
// Handle messages
|
|
go func() {
|
|
for msg := range conn.Incoming() {
|
|
// Process incoming message
|
|
}
|
|
}()
|
|
|
|
// Handle errors
|
|
go func() {
|
|
for err := range conn.Errors() {
|
|
log.Printf("Connection error: %v", err)
|
|
}
|
|
}()
|
|
|
|
// Send message
|
|
conn.Send([]byte(`{"type":"subscribe"}`))
|
|
```
|
|
|
|
### Retry When Connecting
|
|
|
|
```go
|
|
config := &honeybee.Config{
|
|
Retry: &honeybee.RetryConfig{
|
|
MaxRetries: 0, // 0 = infinite
|
|
InitialDelay: 1 * time.Second,
|
|
MaxDelay: 30 * time.Second,
|
|
JitterFactor: 0.5,
|
|
},
|
|
}
|
|
|
|
conn, err := honeybee.NewConnection("wss://relay.example.com", config)
|
|
```
|
|
|
|
### Configuration Options
|
|
|
|
```go
|
|
config, err := honeybee.NewConfig(
|
|
honeybee.WithRetry(),
|
|
honeybee.WithReadTimeout(30 * time.Second),
|
|
honeybee.WithWriteTimeout(10 * time.Second),
|
|
)
|
|
|
|
conn, err := honeybee.NewConnection("wss://relay.example.com", config)
|
|
```
|
|
|
|
## Connection States
|
|
|
|
Connections transition through these states:
|
|
|
|
- `StateDisconnected` - Initial state, no socket
|
|
- `StateConnecting` - Connection attempt in progress
|
|
- `StateConnected` - Active connection, messages flowing
|
|
- `StateClosed` - Connection terminated
|
|
|
|
Check current state with `conn.State()`.
|
|
|
|
## Testing
|
|
|
|
Run tests with:
|
|
|
|
```bash
|
|
go test ./...
|
|
```
|
|
|
|
Run with race detector:
|
|
|
|
```bash
|
|
go test -race ./...
|
|
```
|