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:

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

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

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

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:

go test ./...

Run with race detector:

go test -race ./...