completed inbound pool. Refactored to inbound/outbound semantics.

inbound/config.go

@@ -0,0 +1,176 @@
+// responderpool/config.go
+package inbound
+
+import (
+	"context"
+	"git.wisehodl.dev/jay/go-honeybee/transport"
+	"time"
+)
+
+// Worker Config
+
+type WorkerConfig struct {
+	MaxQueueSize int
+	DeadTimeout  time.Duration
+}
+
+type WorkerOption func(*WorkerConfig) error
+
+func NewWorkerConfig(options ...WorkerOption) (*WorkerConfig, error) {
+	conf := GetDefaultWorkerConfig()
+	if err := applyWorkerOptions(conf, options...); err != nil {
+		return nil, err
+	}
+	if err := ValidateWorkerConfig(conf); err != nil {
+		return nil, err
+	}
+	return conf, nil
+}
+
+func GetDefaultWorkerConfig() *WorkerConfig {
+	return &WorkerConfig{
+		MaxQueueSize: 0, // queue can grow indefinitely by default
+		DeadTimeout:  0, // eviction disabled by default
+	}
+}
+
+func applyWorkerOptions(config *WorkerConfig, options ...WorkerOption) error {
+	for _, option := range options {
+		if err := option(config); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func ValidateWorkerConfig(config *WorkerConfig) error {
+	if err := validateMaxQueueSize(config.MaxQueueSize); err != nil {
+		return err
+	}
+	if err := validateDeadTimeout(config.DeadTimeout); err != nil {
+		return err
+	}
+	return nil
+}
+
+func validateMaxQueueSize(value int) error {
+	if value < 0 {
+		return InvalidMaxQueueSize
+	}
+	return nil
+}
+
+func validateDeadTimeout(value time.Duration) error {
+	if value < 0 {
+		return InvalidDeadTimeout
+	}
+	return nil
+}
+
+// When MaxQueueSize is zero, queue limits are disabled.
+func WithMaxQueueSize(value int) WorkerOption {
+	return func(c *WorkerConfig) error {
+		if err := validateMaxQueueSize(value); err != nil {
+			return err
+		}
+		c.MaxQueueSize = value
+		return nil
+	}
+}
+
+// When DeadTimeout is zero, the watchdog is disabled.
+func WithDeadTimeout(value time.Duration) WorkerOption {
+	return func(c *WorkerConfig) error {
+		if err := validateDeadTimeout(value); err != nil {
+			return err
+		}
+		c.DeadTimeout = value
+		return nil
+	}
+}
+
+// Pool Config
+
+type WorkerFactory func(
+	ctx context.Context,
+	id string,
+	conn *transport.Connection,
+	config *WorkerConfig,
+) (Worker, error)
+
+type PoolConfig struct {
+	ConnectionConfig *transport.ConnectionConfig
+	WorkerConfig     *WorkerConfig
+	WorkerFactory    WorkerFactory
+}
+
+type PoolOption func(*PoolConfig) error
+
+func NewPoolConfig(options ...PoolOption) (*PoolConfig, error) {
+	conf := GetDefaultPoolConfig()
+	if err := applyPoolOptions(conf, options...); err != nil {
+		return nil, err
+	}
+	if err := ValidatePoolConfig(conf); err != nil {
+		return nil, err
+	}
+	return conf, nil
+}
+
+func GetDefaultPoolConfig() *PoolConfig {
+	return &PoolConfig{
+		ConnectionConfig: nil,
+		WorkerConfig:     nil,
+		WorkerFactory:    nil,
+	}
+}
+
+func applyPoolOptions(config *PoolConfig, options ...PoolOption) error {
+	for _, option := range options {
+		if err := option(config); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func ValidatePoolConfig(config *PoolConfig) error {
+	if config.ConnectionConfig != nil {
+		if err := transport.ValidateConnectionConfig(config.ConnectionConfig); err != nil {
+			return err
+		}
+	}
+	if config.WorkerConfig != nil {
+		if err := ValidateWorkerConfig(config.WorkerConfig); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func WithConnectionConfig(cc *transport.ConnectionConfig) PoolOption {
+	return func(c *PoolConfig) error {
+		if err := transport.ValidateConnectionConfig(cc); err != nil {
+			return err
+		}
+		c.ConnectionConfig = cc
+		return nil
+	}
+}
+
+func WithWorkerConfig(wc *WorkerConfig) PoolOption {
+	return func(c *PoolConfig) error {
+		if err := ValidateWorkerConfig(wc); err != nil {
+			return err
+		}
+		c.WorkerConfig = wc
+		return nil
+	}
+}
+
+func WithWorkerFactory(wf WorkerFactory) PoolOption {
+	return func(c *PoolConfig) error {
+		c.WorkerFactory = wf
+		return nil
+	}
+}

inbound/config_test.go

@@ -0,0 +1,188 @@
+// responderpool/config_test.go
+package inbound
+
+import (
+	"git.wisehodl.dev/jay/go-honeybee/transport"
+	"github.com/stretchr/testify/assert"
+	"testing"
+	"time"
+)
+
+func TestNewWorkerConfig(t *testing.T) {
+	conf, err := NewWorkerConfig()
+	assert.NoError(t, err)
+	assert.Equal(t, GetDefaultWorkerConfig(), conf)
+}
+
+func TestDefaultWorkerConfig(t *testing.T) {
+	conf := GetDefaultWorkerConfig()
+	assert.Equal(t, &WorkerConfig{
+		MaxQueueSize: 0,
+		DeadTimeout:  0,
+	}, conf)
+}
+
+func TestValidateWorkerConfig(t *testing.T) {
+	cases := []struct {
+		name    string
+		conf    WorkerConfig
+		wantErr error
+	}{
+		{
+			name: "valid defaults",
+			conf: *GetDefaultWorkerConfig(),
+		},
+		{
+			name: "zero dead timeout disabled",
+			conf: WorkerConfig{DeadTimeout: 0},
+		},
+		{
+			name: "positive dead timeout",
+			conf: WorkerConfig{DeadTimeout: 30 * time.Second},
+		},
+		{
+			name:    "negative max queue size",
+			conf:    WorkerConfig{MaxQueueSize: -1},
+			wantErr: InvalidMaxQueueSize,
+		},
+		{
+			name:    "negative dead timeout",
+			conf:    WorkerConfig{DeadTimeout: -1 * time.Second},
+			wantErr: InvalidDeadTimeout,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := ValidateWorkerConfig(&tc.conf)
+			if tc.wantErr != nil {
+				assert.ErrorIs(t, err, tc.wantErr)
+				return
+			}
+			assert.NoError(t, err)
+		})
+	}
+}
+
+func TestWithMaxQueueSize(t *testing.T) {
+	conf := &WorkerConfig{}
+
+	err := applyWorkerOptions(conf, WithMaxQueueSize(10))
+	assert.NoError(t, err)
+	assert.Equal(t, 10, conf.MaxQueueSize)
+
+	err = applyWorkerOptions(conf, WithMaxQueueSize(0))
+	assert.NoError(t, err)
+
+	err = applyWorkerOptions(conf, WithMaxQueueSize(-1))
+	assert.ErrorIs(t, err, InvalidMaxQueueSize)
+}
+
+func TestWithDeadTimeout(t *testing.T) {
+	conf := &WorkerConfig{}
+
+	err := applyWorkerOptions(conf, WithDeadTimeout(30*time.Second))
+	assert.NoError(t, err)
+	assert.Equal(t, 30*time.Second, conf.DeadTimeout)
+
+	err = applyWorkerOptions(conf, WithDeadTimeout(0))
+	assert.NoError(t, err)
+
+	err = applyWorkerOptions(conf, WithDeadTimeout(-1*time.Second))
+	assert.ErrorIs(t, err, InvalidDeadTimeout)
+}
+
+func TestNewPoolConfig(t *testing.T) {
+	conf, err := NewPoolConfig()
+	assert.NoError(t, err)
+	assert.Equal(t, GetDefaultPoolConfig(), conf)
+}
+
+func TestDefaultPoolConfig(t *testing.T) {
+	conf := GetDefaultPoolConfig()
+	assert.Equal(t, &PoolConfig{
+		ConnectionConfig: nil,
+		WorkerConfig:     nil,
+	}, conf)
+}
+
+func TestValidatePoolConfig(t *testing.T) {
+	cases := []struct {
+		name        string
+		conf        PoolConfig
+		wantErrText string
+	}{
+		{
+			name: "valid empty",
+			conf: PoolConfig{},
+		},
+		{
+			name: "valid defaults",
+			conf: *GetDefaultPoolConfig(),
+		},
+		{
+			name: "valid with configs",
+			conf: PoolConfig{
+				ConnectionConfig: &transport.ConnectionConfig{},
+				WorkerConfig:     &WorkerConfig{},
+			},
+		},
+		{
+			name: "invalid connection config",
+			conf: PoolConfig{
+				ConnectionConfig: &transport.ConnectionConfig{
+					Retry: &transport.RetryConfig{
+						InitialDelay: 10 * time.Second,
+						MaxDelay:     1 * time.Second,
+					},
+				},
+			},
+			wantErrText: "initial delay may not exceed maximum delay",
+		},
+		{
+			name: "invalid worker config",
+			conf: PoolConfig{
+				WorkerConfig: &WorkerConfig{MaxQueueSize: -1},
+			},
+			wantErrText: "maximum queue size cannot be negative",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := ValidatePoolConfig(&tc.conf)
+			if tc.wantErrText != "" {
+				assert.ErrorContains(t, err, tc.wantErrText)
+				return
+			}
+			assert.NoError(t, err)
+		})
+	}
+}
+
+func TestWithConnectionConfig(t *testing.T) {
+	conf := &PoolConfig{}
+
+	err := applyPoolOptions(conf, WithConnectionConfig(&transport.ConnectionConfig{}))
+	assert.NoError(t, err)
+	assert.NotNil(t, conf.ConnectionConfig)
+
+	err = applyPoolOptions(conf, WithConnectionConfig(&transport.ConnectionConfig{
+		Retry: &transport.RetryConfig{
+			InitialDelay: 10 * time.Second,
+			MaxDelay:     1 * time.Second,
+		},
+	}))
+	assert.Error(t, err)
+}
+
+func TestWithWorkerConfig(t *testing.T) {
+	conf := &PoolConfig{}
+
+	err := applyPoolOptions(conf, WithWorkerConfig(&WorkerConfig{DeadTimeout: 30 * time.Second}))
+	assert.NoError(t, err)
+	assert.Equal(t, 30*time.Second, conf.WorkerConfig.DeadTimeout)
+
+	err = applyPoolOptions(conf, WithWorkerConfig(&WorkerConfig{MaxQueueSize: -1}))
+	assert.Error(t, err)
+}

inbound/errors.go

@@ -0,0 +1,15 @@
+package inbound
+
+import "errors"
+
+var (
+	// Pool errors
+	PoolError       = errors.New("pool error")
+	ErrPoolClosed   = errors.New("pool is closed")
+	ErrPeerNotFound = errors.New("peer not found")
+	ErrPeerExists   = errors.New("peer already exists")
+
+	// Config errors
+	InvalidMaxQueueSize = errors.New("maximum queue size cannot be negative")
+	InvalidDeadTimeout  = errors.New("dead timeout cannot be negative")
+)

inbound/helpers_test.go

@@ -0,0 +1,67 @@
+package inbound
+
+import (
+	"git.wisehodl.dev/jay/go-honeybee/honeybeetest"
+	"git.wisehodl.dev/jay/go-honeybee/transport"
+	"github.com/stretchr/testify/assert"
+	"io"
+	"testing"
+)
+
+func setupTestSocket(t *testing.T) (
+	socket *honeybeetest.MockSocket,
+	incoming chan honeybeetest.MockIncomingData,
+	outgoing chan honeybeetest.MockOutgoingData,
+) {
+	t.Helper()
+
+	incoming = make(chan honeybeetest.MockIncomingData, 10)
+	outgoing = make(chan honeybeetest.MockOutgoingData, 10)
+	socket = honeybeetest.NewMockSocket()
+
+	socket.CloseFunc = func() error {
+		socket.Once.Do(func() { close(socket.Closed) })
+		return nil
+	}
+
+	socket.ReadMessageFunc = func() (int, []byte, error) {
+		select {
+		case data, ok := <-incoming:
+			if !ok {
+				return 0, nil, io.EOF
+			}
+			return data.MsgType, data.Data, data.Err
+		case <-socket.Closed:
+			return 0, nil, io.EOF
+		}
+	}
+
+	socket.WriteMessageFunc = func(msgType int, data []byte) error {
+		select {
+		case outgoing <- honeybeetest.MockOutgoingData{MsgType: msgType, Data: data}:
+			return nil
+		case <-socket.Closed:
+			return io.EOF
+		default:
+			return io.EOF
+		}
+	}
+
+	return
+}
+
+func setupTestConnection(t *testing.T) (
+	conn *transport.Connection,
+	socket *honeybeetest.MockSocket,
+	incoming chan honeybeetest.MockIncomingData,
+	outgoing chan honeybeetest.MockOutgoingData,
+) {
+	t.Helper()
+
+	socket, incoming, outgoing = setupTestSocket(t)
+
+	var err error
+	conn, err = transport.NewConnectionFromSocket(socket, nil, nil)
+	assert.NoError(t, err)
+	return
+}

inbound/pool.go

@@ -0,0 +1,297 @@
+package inbound
+
+import (
+	"context"
+	"fmt"
+	"git.wisehodl.dev/jay/go-honeybee/transport"
+	"git.wisehodl.dev/jay/go-honeybee/types"
+	"log/slog"
+	"sync"
+	"time"
+)
+
+// Types
+
+type PoolEventKind string
+
+const (
+	EventPeerDisconnected PoolEventKind = "disconnected"
+	EventPeerDropped      PoolEventKind = "dropped"
+	EventPeerEvicted      PoolEventKind = "evicted"
+)
+
+var workerToPoolEvent = map[WorkerExitKind]PoolEventKind{
+	ExitCleanDisconnect: EventPeerDisconnected,
+	ExitUnexpectedDrop:  EventPeerDropped,
+	ExitInactive:        EventPeerEvicted,
+}
+
+type OnExitFunction func(kind WorkerExitKind)
+
+type PoolEvent struct {
+	ID   string
+	Kind PoolEventKind
+}
+
+type InboxMessage struct {
+	ID         string
+	Data       []byte
+	ReceivedAt time.Time
+}
+
+type PoolPlugin struct {
+	Inbox  chan<- InboxMessage
+	Events chan<- PoolEvent
+	Logger *slog.Logger
+	OnExit OnExitFunction
+}
+
+// Pool
+
+type Peer struct {
+	id     string
+	conn   *transport.Connection
+	worker Worker
+	done   chan struct{}
+}
+
+type Pool struct {
+	ctx    context.Context
+	cancel context.CancelFunc
+
+	peers  map[string]*Peer
+	inbox  chan InboxMessage
+	events chan PoolEvent
+
+	config *PoolConfig
+	logger *slog.Logger
+
+	mu     sync.RWMutex
+	wg     sync.WaitGroup
+	closed bool
+}
+
+func NewPool(ctx context.Context, config *PoolConfig, logger *slog.Logger) (*Pool, error) {
+	if config == nil {
+		config = GetDefaultPoolConfig()
+	}
+
+	// If a custom factory is supplied, config.WorkerConfig is not used.
+	// The factory function should be non-blocking or else Connect() may cause
+	// deadlocks.
+	if config.WorkerFactory == nil {
+		config.WorkerFactory = func(
+			ctx context.Context,
+			id string,
+			conn *transport.Connection,
+			config *WorkerConfig,
+		) (Worker, error) {
+			return NewWorker(ctx, id, conn, config)
+		}
+	}
+
+	if err := ValidatePoolConfig(config); err != nil {
+		return nil, err
+	}
+
+	pctx, cancel := context.WithCancel(ctx)
+
+	return &Pool{
+		ctx:    pctx,
+		cancel: cancel,
+		peers:  make(map[string]*Peer),
+		inbox:  make(chan InboxMessage, 256),
+		events: make(chan PoolEvent, 10),
+		config: config,
+		logger: logger,
+	}, nil
+}
+
+func (p *Pool) Peers() []string {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+
+	ids := make([]string, 0, len(p.peers))
+	for id := range p.peers {
+		ids = append(ids, id)
+	}
+
+	return ids
+}
+
+func (p *Pool) Inbox() <-chan InboxMessage {
+	return p.inbox
+}
+
+func (p *Pool) Events() <-chan PoolEvent {
+	return p.events
+}
+
+func (p *Pool) Close() {
+	p.mu.Lock()
+	if p.closed {
+		p.mu.Unlock()
+		return
+	}
+
+	p.closed = true
+	p.cancel()
+
+	// remove all peers
+	p.peers = make(map[string]*Peer)
+
+	// close all connections
+	for _, peer := range p.peers {
+		peer.worker.Stop()
+		peer.conn.Close()
+	}
+
+	p.mu.Unlock()
+
+	go func() {
+		p.wg.Wait()
+		close(p.inbox)
+		close(p.events)
+	}()
+}
+
+func (p *Pool) Add(id string, socket types.Socket) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if p.closed {
+		return ErrPoolClosed
+	}
+
+	if _, exists := p.peers[id]; exists {
+		return ErrPeerExists
+	}
+
+	return p.addLocked(id, socket)
+}
+
+func (p *Pool) Replace(id string, socket types.Socket) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if p.closed {
+		return ErrPoolClosed
+	}
+
+	if peer, exists := p.peers[id]; exists {
+		p.removeLocked(peer)
+	} else {
+		return ErrPeerNotFound
+	}
+
+	return p.addLocked(id, socket)
+}
+
+func (p *Pool) Remove(id string) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if p.closed {
+		return ErrPoolClosed
+	}
+
+	peer, exists := p.peers[id]
+	if !exists {
+		return ErrPeerNotFound
+	}
+
+	p.removeLocked(peer)
+
+	return nil
+}
+
+func (p *Pool) Send(id string, data []byte) error {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+
+	if p.closed {
+		return ErrPoolClosed
+	}
+
+	peer, exists := p.peers[id]
+	if !exists {
+		return ErrPeerNotFound
+	}
+
+	return peer.worker.Send(data)
+}
+
+// addLocked constructs and registers a peer. Caller must hold p.mu write lock.
+func (p *Pool) addLocked(id string, socket types.Socket) error {
+	conn, err := transport.NewConnectionFromSocket(
+		socket, p.config.ConnectionConfig, p.logger)
+	if err != nil {
+		return err
+	}
+
+	// The worker factory must be non-blocking to avoid deadlocks
+	wctx, cancel := context.WithCancel(p.ctx)
+	worker, err := p.config.WorkerFactory(wctx, id, conn, p.config.WorkerConfig)
+	if err != nil {
+		cancel()
+		conn.Close()
+		return fmt.Errorf("%w: %w", PoolError, err)
+	}
+
+	var once sync.Once
+	onExit := func(kind WorkerExitKind) {
+		once.Do(func() {
+			p.mu.Lock()
+			delete(p.peers, id)
+			p.mu.Unlock()
+
+			conn.Close()
+
+			select {
+			case p.events <- PoolEvent{ID: id, Kind: workerToPoolEvent[kind]}:
+			case <-p.ctx.Done():
+				return
+			}
+		})
+	}
+
+	var logger *slog.Logger
+	if p.logger != nil {
+		logger = p.logger.With("id", id)
+	}
+
+	pool := PoolPlugin{
+		Inbox:  p.inbox,
+		Events: p.events,
+		Logger: logger,
+		OnExit: onExit,
+	}
+
+	peer := &Peer{
+		id:     id,
+		conn:   conn,
+		worker: worker,
+		done:   make(chan struct{}),
+	}
+
+	p.wg.Add(1)
+	go func() {
+		defer cancel()
+		defer close(peer.done)
+		worker.Start(pool, &p.wg)
+	}()
+
+	p.peers[id] = peer
+
+	return nil
+}
+
+// removeLocked closes and unregisters a peer. Caller must hold p.mu write lock.
+func (p *Pool) removeLocked(peer *Peer) {
+	delete(p.peers, peer.id)
+	peer.worker.Stop()
+	go func() {
+		<-peer.done
+		peer.conn.Close()
+	}()
+}

inbound/pool_test.go

@@ -0,0 +1,395 @@
+package inbound
+
+import (
+	"context"
+	"fmt"
+	"git.wisehodl.dev/jay/go-honeybee/honeybeetest"
+	"github.com/gorilla/websocket"
+	"github.com/stretchr/testify/assert"
+	"slices"
+	"testing"
+	"time"
+)
+
+// Helpers
+
+func setupPool(t *testing.T) *Pool {
+	t.Helper()
+	pool, err := NewPool(context.Background(), nil, nil)
+	assert.NoError(t, err)
+	return pool
+}
+
+func expectEvent(
+	t *testing.T,
+	events <-chan PoolEvent,
+	expectedURL string,
+	expectedKind PoolEventKind,
+) {
+	t.Helper()
+	honeybeetest.Eventually(t, func() bool {
+		select {
+		case e := <-events:
+			return e.ID == expectedURL && e.Kind == expectedKind
+		default:
+			return false
+		}
+	}, fmt.Sprintf("expected event: URL=%q, Kind=%q", expectedURL, expectedKind))
+}
+
+// Tests
+
+func TestPoolAdd(t *testing.T) {
+	t.Run("successfully adds peer", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		err := pool.Add("peer-1", socket)
+		assert.NoError(t, err)
+	})
+
+	t.Run("peer appears in Peers after add", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		err := pool.Add("peer-1", socket)
+		assert.NoError(t, err)
+
+		assert.Contains(t, pool.Peers(), "peer-1")
+	})
+
+	t.Run("duplicate id returns ErrPeerExists", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket1, _, _ := setupTestSocket(t)
+		socket2, _, _ := setupTestSocket(t)
+
+		err := pool.Add("peer-1", socket1)
+		assert.NoError(t, err)
+
+		err = pool.Add("peer-1", socket2)
+		assert.ErrorIs(t, err, ErrPeerExists)
+	})
+
+	t.Run("closed pool returns ErrPoolClosed", func(t *testing.T) {
+		pool := setupPool(t)
+		pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		err := pool.Add("peer-1", socket)
+		assert.ErrorIs(t, err, ErrPoolClosed)
+	})
+}
+
+func TestPoolReplace(t *testing.T) {
+	t.Run("replaces existing peer", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket1, _, _ := setupTestSocket(t)
+		socket2, _, _ := setupTestSocket(t)
+
+		err := pool.Add("peer-1", socket1)
+		assert.NoError(t, err)
+
+		err = pool.Replace("peer-1", socket2)
+		assert.NoError(t, err)
+
+		assert.Contains(t, pool.Peers(), "peer-1")
+	})
+
+	t.Run("unknown id returns ErrPeerNotFound", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		err := pool.Replace("unknown", socket)
+		assert.ErrorIs(t, err, ErrPeerNotFound)
+	})
+
+	t.Run("closed pool returns ErrPoolClosed", func(t *testing.T) {
+		pool := setupPool(t)
+		pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		err := pool.Replace("peer-1", socket)
+		assert.ErrorIs(t, err, ErrPoolClosed)
+	})
+
+	t.Run("no event emitted for replaced peer", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket1, _, _ := setupTestSocket(t)
+		socket2, _, _ := setupTestSocket(t)
+
+		err := pool.Add("peer-1", socket1)
+		assert.NoError(t, err)
+
+		err = pool.Replace("peer-1", socket2)
+		assert.NoError(t, err)
+
+		honeybeetest.Never(t, func() bool {
+			select {
+			case <-pool.Events():
+				return true
+			default:
+				return false
+			}
+		}, "no event expected on replace")
+	})
+}
+
+func TestPoolRemove(t *testing.T) {
+	t.Run("removes known peer", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		err := pool.Add("peer-1", socket)
+		assert.NoError(t, err)
+
+		err = pool.Remove("peer-1")
+		assert.NoError(t, err)
+
+		assert.NotContains(t, pool.Peers(), "peer-1")
+	})
+
+	t.Run("unknown id returns ErrPeerNotFound", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		err := pool.Remove("unknown")
+		assert.ErrorIs(t, err, ErrPeerNotFound)
+	})
+
+	t.Run("closed pool returns ErrPoolClosed", func(t *testing.T) {
+		pool := setupPool(t)
+		pool.Close()
+
+		err := pool.Remove("peer-1")
+		assert.ErrorIs(t, err, ErrPoolClosed)
+	})
+
+	t.Run("no event emitted on remove", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		err := pool.Add("peer-1", socket)
+		assert.NoError(t, err)
+
+		err = pool.Remove("peer-1")
+		assert.NoError(t, err)
+
+		honeybeetest.Never(t, func() bool {
+			select {
+			case e := <-pool.Events():
+				fmt.Printf("got event: %v", e)
+				return true
+			default:
+				return false
+			}
+		}, "no event expected on remove")
+	})
+}
+
+func TestPoolSend(t *testing.T) {
+	t.Run("data reaches socket", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, _, outgoing := setupTestSocket(t)
+		err := pool.Add("peer-1", socket)
+		assert.NoError(t, err)
+
+		err = pool.Send("peer-1", []byte("hello"))
+		assert.NoError(t, err)
+
+		honeybeetest.ExpectWrite(t, outgoing, websocket.TextMessage, []byte("hello"))
+	})
+
+	t.Run("unknown id returns ErrPeerNotFound", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		err := pool.Send("unknown", []byte("hello"))
+		assert.ErrorIs(t, err, ErrPeerNotFound)
+	})
+
+	t.Run("closed pool returns ErrPoolClosed", func(t *testing.T) {
+		pool := setupPool(t)
+		pool.Close()
+
+		err := pool.Send("peer-1", []byte("hello"))
+		assert.ErrorIs(t, err, ErrPoolClosed)
+	})
+}
+
+func TestPoolClose(t *testing.T) {
+	t.Run("inbox and events channels close after pool close", func(t *testing.T) {
+		pool := setupPool(t)
+		pool.Close()
+
+		_, ok := <-pool.Inbox()
+		assert.False(t, ok)
+		_, ok = <-pool.Events()
+		assert.False(t, ok)
+	})
+
+	t.Run("add after close returns ErrPoolClosed", func(t *testing.T) {
+		pool := setupPool(t)
+		pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		err := pool.Add("peer-1", socket)
+		assert.ErrorIs(t, err, ErrPoolClosed)
+	})
+
+	t.Run("close is idempotent", func(t *testing.T) {
+		pool := setupPool(t)
+		pool.Close()
+		pool.Close()
+	})
+}
+
+func TestPoolPeers(t *testing.T) {
+	t.Run("reflects active peers after add", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket1, _, _ := setupTestSocket(t)
+		socket2, _, _ := setupTestSocket(t)
+
+		pool.Add("peer-1", socket1)
+		pool.Add("peer-2", socket2)
+
+		peers := pool.Peers()
+		assert.Contains(t, peers, "peer-1")
+		assert.Contains(t, peers, "peer-2")
+	})
+
+	t.Run("loses entry after remove", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		pool.Add("peer-1", socket)
+		pool.Remove("peer-1")
+
+		assert.NotContains(t, pool.Peers(), "peer-1")
+	})
+
+	t.Run("loses entry after peer self-disconnects", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, incoming, _ := setupTestSocket(t)
+		pool.Add("peer-1", socket)
+
+		close(incoming)
+
+		honeybeetest.Eventually(t, func() bool {
+			return !slices.Contains(pool.Peers(), "peer-1")
+		}, "expected peer to be removed after self-disconnect")
+	})
+}
+
+func TestPoolEvents(t *testing.T) {
+	t.Run("EventPeerDisconnected emitted on clean close", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, incoming, _ := setupTestSocket(t)
+		pool.Add("peer-1", socket)
+
+		incoming <- honeybeetest.MockIncomingData{
+			Err: &websocket.CloseError{Code: websocket.CloseNormalClosure},
+		}
+
+		expectEvent(t, pool.Events(), "peer-1", EventPeerDisconnected)
+
+		honeybeetest.Eventually(t, func() bool {
+			return !slices.Contains(pool.Peers(), "peer-1")
+		}, "expected peer auto-removed")
+	})
+
+	t.Run("EventPeerDropped emitted on unexpected close", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, incoming, _ := setupTestSocket(t)
+		pool.Add("peer-1", socket)
+
+		incoming <- honeybeetest.MockIncomingData{
+			Err: &websocket.CloseError{Code: websocket.CloseProtocolError},
+		}
+
+		expectEvent(t, pool.Events(), "peer-1", EventPeerDropped)
+
+		honeybeetest.Eventually(t, func() bool {
+			return !slices.Contains(pool.Peers(), "peer-1")
+		}, "expected peer auto-removed")
+	})
+
+	t.Run("EventPeerEvicted emitted on watchdog timeout", func(t *testing.T) {
+		config, err := NewPoolConfig(
+			WithWorkerConfig(&WorkerConfig{DeadTimeout: 20 * time.Millisecond}),
+		)
+		assert.NoError(t, err)
+
+		pool, err := NewPool(context.Background(), config, nil)
+		assert.NoError(t, err)
+		defer pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		pool.Add("peer-1", socket)
+
+		expectEvent(t, pool.Events(), "peer-1", EventPeerEvicted)
+
+		honeybeetest.Eventually(t, func() bool {
+			return !slices.Contains(pool.Peers(), "peer-1")
+		}, "expected peer auto-removed")
+	})
+
+	t.Run("no event emitted on Remove", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket, _, _ := setupTestSocket(t)
+		pool.Add("peer-1", socket)
+		pool.Remove("peer-1")
+
+		honeybeetest.Never(t, func() bool {
+			select {
+			case <-pool.Events():
+				return true
+			default:
+				return false
+			}
+		}, "no event expected on Remove")
+	})
+
+	t.Run("no event emitted on Replace of old peer", func(t *testing.T) {
+		pool := setupPool(t)
+		defer pool.Close()
+
+		socket1, _, _ := setupTestSocket(t)
+		socket2, _, _ := setupTestSocket(t)
+
+		pool.Add("peer-1", socket1)
+		pool.Replace("peer-1", socket2)
+
+		honeybeetest.Never(t, func() bool {
+			select {
+			case <-pool.Events():
+				return true
+			default:
+				return false
+			}
+		}, "no event expected on Replace")
+	})
+}

inbound/worker.go

@@ -0,0 +1,235 @@
+package inbound
+
+import (
+	"container/list"
+	"context"
+	"errors"
+	"git.wisehodl.dev/jay/go-honeybee/transport"
+	"sync"
+	"time"
+)
+
+type Worker interface {
+	Start(pool PoolPlugin, wg *sync.WaitGroup)
+	Stop()
+	Send(data []byte) error
+}
+
+type WorkerExitKind string
+
+const (
+	ExitCleanDisconnect WorkerExitKind = "disconnected"
+	ExitUnexpectedDrop  WorkerExitKind = "dropped"
+	ExitInactive        WorkerExitKind = "inactive"
+)
+
+type ReceivedMessage struct {
+	data       []byte
+	receivedAt time.Time
+}
+
+type DefaultWorker struct {
+	id        string
+	conn      *transport.Connection
+	heartbeat chan struct{}
+	config    *WorkerConfig
+	ctx       context.Context
+	cancel    context.CancelFunc
+}
+
+func NewWorker(
+	ctx context.Context,
+	id string,
+	conn *transport.Connection,
+	config *WorkerConfig,
+) (*DefaultWorker, error) {
+	if config == nil {
+		config = GetDefaultWorkerConfig()
+	}
+	if err := ValidateWorkerConfig(config); err != nil {
+		return nil, err
+	}
+
+	wctx, cancel := context.WithCancel(ctx)
+	return &DefaultWorker{
+		id:        id,
+		conn:      conn,
+		heartbeat: make(chan struct{}),
+		config:    config,
+		ctx:       wctx,
+		cancel:    cancel,
+	}, nil
+}
+
+func (w *DefaultWorker) Start(pool PoolPlugin, wg *sync.WaitGroup) {
+	messages := make(chan ReceivedMessage, 256)
+
+	var owg sync.WaitGroup
+	owg.Add(3)
+
+	go func() {
+		defer owg.Done()
+		RunReader(w.ctx, pool.OnExit, w.conn, messages, w.heartbeat)
+	}()
+
+	go func() {
+		defer owg.Done()
+		RunForwarder(w.id, w.ctx, messages, pool.Inbox, w.config.MaxQueueSize)
+	}()
+
+	go func() {
+		defer owg.Done()
+		RunWatchdog(w.ctx, pool.OnExit, w.heartbeat, w.config.DeadTimeout)
+	}()
+
+	owg.Wait()
+	wg.Done()
+}
+
+func (w *DefaultWorker) Stop() {
+	w.cancel()
+}
+
+func (w *DefaultWorker) Send(data []byte) error {
+	if err := w.conn.Send(data); err != nil {
+		return err
+	}
+
+	select {
+	case w.heartbeat <- struct{}{}:
+	case <-w.ctx.Done():
+	}
+
+	return nil
+}
+
+func RunReader(
+	ctx context.Context,
+	onPeerClose OnExitFunction,
+
+	conn *transport.Connection,
+	messages chan<- ReceivedMessage,
+	heartbeat chan<- struct{},
+) {
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case data, ok := <-conn.Incoming():
+			if !ok {
+				// determine exit kind
+				// by default, the peer dropped unexpectedly
+				kind := ExitUnexpectedDrop
+				select {
+				// the peer-side error is sent before the connection is closed,
+				// so a non-blocking call here is correct
+				// if an error is not sent, then assume the default event kind
+				case err := <-conn.Errors():
+					if errors.Is(err, transport.ErrPeerClosedClean) {
+						kind = ExitCleanDisconnect
+					}
+				default:
+				}
+
+				onPeerClose(kind)
+				return
+			}
+
+			messages <- ReceivedMessage{data: data, receivedAt: time.Now()}
+
+			select {
+			case heartbeat <- struct{}{}:
+			case <-ctx.Done():
+				return
+			}
+		}
+	}
+}
+
+func RunForwarder(
+	id string,
+	ctx context.Context,
+	messages <-chan ReceivedMessage,
+	inbox chan<- InboxMessage,
+	maxQueueSize int,
+) {
+	queue := list.New()
+
+	for {
+		var out chan<- InboxMessage
+		var next ReceivedMessage
+
+		// enable inbox if it is populated
+		if queue.Len() > 0 {
+			out = inbox
+
+			// read the first message in the queue
+			next = queue.Front().Value.(ReceivedMessage)
+		}
+
+		select {
+		case <-ctx.Done():
+			return
+		case msg := <-messages:
+			// limit queue size if maximum is configured
+			if maxQueueSize > 0 && queue.Len() >= maxQueueSize {
+				// drop oldest message
+				queue.Remove(queue.Front())
+			}
+			// add new message
+			queue.PushBack(msg)
+		// send next message to inbox
+		case out <- InboxMessage{
+			ID:         id,
+			Data:       next.data,
+			ReceivedAt: next.receivedAt,
+		}:
+			// drop message from queue
+			queue.Remove(queue.Front())
+		}
+	}
+}
+
+func RunWatchdog(
+	ctx context.Context,
+	onInactive OnExitFunction,
+	heartbeat <-chan struct{},
+	timeout time.Duration,
+) {
+	// disable watchdog timeout if not configured
+	if timeout <= 0 {
+		// drain heartbeats
+		// wait for cancel and exit
+		for {
+			select {
+			case <-heartbeat:
+			case <-ctx.Done():
+				return
+			}
+		}
+	}
+
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-heartbeat:
+			// drain the timer channel and reset
+			if !timer.Stop() {
+				select {
+				case <-timer.C:
+				default:
+				}
+			}
+			timer.Reset(timeout)
+		// timer completed
+		case <-timer.C:
+			// signal peer is inactive
+			onInactive(ExitInactive)
+			return
+		}
+	}
+}

inbound/worker_forwarder_test.go

@@ -0,0 +1,103 @@
+package inbound
+
+import (
+	"context"
+	"git.wisehodl.dev/jay/go-honeybee/honeybeetest"
+	"github.com/stretchr/testify/assert"
+	"testing"
+	"time"
+)
+
+func TestRunForwarder(t *testing.T) {
+	t.Run("message passes through to inbox", func(t *testing.T) {
+		id := "wss://test"
+		messages := make(chan ReceivedMessage, 1)
+		inbox := make(chan InboxMessage, 1)
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		go RunForwarder(id, ctx, messages, inbox, 0)
+
+		messages <- ReceivedMessage{data: []byte("hello"), receivedAt: time.Now()}
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case msg := <-inbox:
+				return string(msg.Data) == "hello" && msg.ID == "wss://test"
+			default:
+				return false
+			}
+		}, "expected message")
+	})
+
+	t.Run("oldest message dropped when queue is full", func(t *testing.T) {
+		id := "wss://test"
+		messages := make(chan ReceivedMessage, 1)
+		inbox := make(chan InboxMessage, 1)
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		gate := make(chan struct{})
+		gatedInbox := make(chan InboxMessage)
+
+		// gate the inbox from receiving messages until the gate is opened
+		go func() {
+			<-gate
+			for msg := range gatedInbox {
+				inbox <- msg
+			}
+		}()
+
+		go RunForwarder(id, ctx, messages, gatedInbox, 2)
+
+		// send three messages while the gated inbox is blocked
+		messages <- ReceivedMessage{data: []byte("first"), receivedAt: time.Now()}
+		messages <- ReceivedMessage{data: []byte("second"), receivedAt: time.Now()}
+		messages <- ReceivedMessage{data: []byte("third"), receivedAt: time.Now()}
+
+		// allow time for the first message to be dropped
+		time.Sleep(20 * time.Millisecond)
+
+		// close the gate, draining messages into the inbox
+		close(gate)
+
+		// receive messages from the inbox
+		var received []string
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case msg := <-inbox:
+				received = append(received, string(msg.Data))
+			default:
+			}
+			return len(received) == 2
+		}, "expected messages")
+
+		// first message was dropped
+		assert.Equal(t, []string{"second", "third"}, received)
+
+	})
+
+	t.Run("exits on context cancellation", func(t *testing.T) {
+		id := "wss://test"
+		messages := make(chan ReceivedMessage, 1)
+		inbox := make(chan InboxMessage, 1)
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		done := make(chan struct{})
+		go func() {
+			RunForwarder(id, ctx, messages, inbox, 0)
+			close(done)
+		}()
+
+		cancel()
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case <-done:
+				return true
+			default:
+				return false
+			}
+		}, "expected done signal")
+	})
+}

inbound/worker_reader_test.go

@@ -0,0 +1,212 @@
+package inbound
+
+import (
+	"context"
+	"git.wisehodl.dev/jay/go-honeybee/honeybeetest"
+	"git.wisehodl.dev/jay/go-honeybee/transport"
+	"github.com/gorilla/websocket"
+	"github.com/stretchr/testify/assert"
+	"io"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestRunReader(t *testing.T) {
+	t.Run("message forwarded with correct data and non-zero receivedAt", func(t *testing.T) {
+		conn, _, incoming, _ := setupTestConnection(t)
+		defer conn.Close()
+
+		messages := make(chan ReceivedMessage, 1)
+		heartbeat := make(chan struct{}, 1)
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		go RunReader(ctx, func(WorkerExitKind) {}, conn, messages, heartbeat)
+
+		before := time.Now()
+		incoming <- honeybeetest.MockIncomingData{MsgType: websocket.TextMessage, Data: []byte("hello")}
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case msg := <-messages:
+				return string(msg.data) == "hello" && msg.receivedAt.After(before)
+			default:
+				return false
+			}
+		}, "expected message")
+	})
+
+	t.Run("heartbeat sent per forwarded message", func(t *testing.T) {
+		conn, _, incoming, _ := setupTestConnection(t)
+		defer conn.Close()
+
+		messages := make(chan ReceivedMessage, 10)
+		heartbeat := make(chan struct{}, 10)
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		count := atomic.Int32{}
+		go func() {
+			for range heartbeat {
+				count.Add(1)
+			}
+		}()
+		go func() {
+			for range messages {
+			}
+		}()
+		go RunReader(ctx, func(WorkerExitKind) {}, conn, messages, heartbeat)
+
+		const n = 3
+		for i := 0; i < n; i++ {
+			incoming <- honeybeetest.MockIncomingData{MsgType: websocket.TextMessage, Data: []byte("msg")}
+		}
+
+		honeybeetest.Eventually(t, func() bool {
+			return count.Load() == n
+		}, "expected heartbeats")
+	})
+
+	t.Run("clean close calls onPeerClose with ExitCleanDisconnect", func(t *testing.T) {
+		mock := honeybeetest.NewMockSocket()
+		mock.CloseFunc = func() error {
+			mock.Once.Do(func() { close(mock.Closed) })
+			return nil
+		}
+		mock.ReadMessageFunc = func() (int, []byte, error) {
+			return 0, nil, &websocket.CloseError{Code: websocket.CloseNormalClosure}
+		}
+
+		conn, err := transport.NewConnectionFromSocket(mock, nil, nil)
+		assert.NoError(t, err)
+
+		messages := make(chan ReceivedMessage, 1)
+		heartbeat := make(chan struct{}, 1)
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		var gotKind WorkerExitKind
+		done := make(chan struct{})
+		go RunReader(ctx, func(kind WorkerExitKind) {
+			gotKind = kind
+			close(done)
+		}, conn, messages, heartbeat)
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case <-done:
+				return true
+			default:
+				return false
+			}
+		}, "expected onPeerClose")
+
+		assert.Equal(t, ExitCleanDisconnect, gotKind)
+	})
+
+	t.Run("unexpected close calls onPeerClose with ExitUnexpectedDrop", func(t *testing.T) {
+		mock := honeybeetest.NewMockSocket()
+		mock.CloseFunc = func() error {
+			mock.Once.Do(func() { close(mock.Closed) })
+			return nil
+		}
+		mock.ReadMessageFunc = func() (int, []byte, error) {
+			return 0, nil, &websocket.CloseError{Code: websocket.CloseProtocolError}
+		}
+
+		conn, err := transport.NewConnectionFromSocket(mock, nil, nil)
+		assert.NoError(t, err)
+
+		messages := make(chan ReceivedMessage, 1)
+		heartbeat := make(chan struct{}, 1)
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		var gotKind WorkerExitKind
+		done := make(chan struct{})
+		go RunReader(ctx, func(kind WorkerExitKind) {
+			gotKind = kind
+			close(done)
+		}, conn, messages, heartbeat)
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case <-done:
+				return true
+			default:
+				return false
+			}
+		}, "expected onPeerClose")
+
+		assert.Equal(t, ExitUnexpectedDrop, gotKind)
+	})
+
+	t.Run("read error calls onPeerClose with ExitUnexpectedDrop", func(t *testing.T) {
+		mock := honeybeetest.NewMockSocket()
+		mock.CloseFunc = func() error {
+			mock.Once.Do(func() { close(mock.Closed) })
+			return nil
+		}
+		mock.ReadMessageFunc = func() (int, []byte, error) {
+			return 0, nil, io.EOF
+		}
+
+		conn, err := transport.NewConnectionFromSocket(mock, nil, nil)
+		assert.NoError(t, err)
+
+		messages := make(chan ReceivedMessage, 1)
+		heartbeat := make(chan struct{}, 1)
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		var gotKind WorkerExitKind
+		done := make(chan struct{})
+		go RunReader(ctx, func(kind WorkerExitKind) {
+			gotKind = kind
+			close(done)
+		}, conn, messages, heartbeat)
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case <-done:
+				return true
+			default:
+				return false
+			}
+		}, "expected onPeerClose")
+
+		assert.Equal(t, ExitUnexpectedDrop, gotKind)
+	})
+
+	t.Run("ctx.Done exits without calling onPeerClose", func(t *testing.T) {
+		conn, _, _, _ := setupTestConnection(t)
+		defer conn.Close()
+
+		messages := make(chan ReceivedMessage, 1)
+		heartbeat := make(chan struct{}, 1)
+		ctx, cancel := context.WithCancel(context.Background())
+
+		called := atomic.Bool{}
+		done := make(chan struct{})
+		go func() {
+			RunReader(ctx, func(WorkerExitKind) {
+				called.Store(true)
+			}, conn, messages, heartbeat)
+			close(done)
+		}()
+
+		cancel()
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case <-done:
+				return true
+			default:
+				return false
+			}
+		}, "expected RunReader to exit")
+
+		assert.False(t, called.Load())
+	})
+}

inbound/worker_test.go

@@ -0,0 +1,228 @@
+package inbound
+
+import (
+	"context"
+	"fmt"
+	"git.wisehodl.dev/jay/go-honeybee/honeybeetest"
+	"git.wisehodl.dev/jay/go-honeybee/transport"
+	"github.com/gorilla/websocket"
+	"github.com/stretchr/testify/assert"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+type workerTestVars struct {
+	worker   *DefaultWorker
+	conn     *transport.Connection
+	incoming chan honeybeetest.MockIncomingData
+	outgoing chan honeybeetest.MockOutgoingData
+	pool     PoolPlugin
+	inbox    chan InboxMessage
+	events   chan PoolEvent
+	exitKind *atomic.Value
+	wg       *sync.WaitGroup
+}
+
+func setupWorkerTest(t *testing.T) workerTestVars {
+	t.Helper()
+
+	conn, _, incoming, outgoing := setupTestConnection(t)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	var err error
+	worker, err := NewWorker(ctx, "peer-1", conn, nil)
+	assert.NoError(t, err)
+	worker.cancel = cancel
+
+	inbox := make(chan InboxMessage, 256)
+	events := make(chan PoolEvent, 10)
+	exitKind := &atomic.Value{}
+
+	var once sync.Once
+	pool := PoolPlugin{
+		Inbox:  inbox,
+		Events: events,
+		OnExit: func(kind WorkerExitKind) {
+			once.Do(func() { exitKind.Store(kind) })
+		},
+	}
+
+	wg := &sync.WaitGroup{}
+	wg.Add(1)
+
+	return workerTestVars{
+		worker:   worker,
+		conn:     conn,
+		incoming: incoming,
+		outgoing: outgoing,
+		pool:     pool,
+		inbox:    inbox,
+		events:   events,
+		exitKind: exitKind,
+		wg:       wg,
+	}
+}
+
+func TestWorkerStart(t *testing.T) {
+	t.Run("socket data arrives on inbox", func(t *testing.T) {
+		v := setupWorkerTest(t)
+		defer v.worker.Stop()
+
+		go v.worker.Start(v.pool, v.wg)
+
+		v.incoming <- honeybeetest.MockIncomingData{
+			MsgType: websocket.TextMessage,
+			Data:    []byte("hello"),
+		}
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case msg := <-v.inbox:
+				return msg.ID == "peer-1" && string(msg.Data) == "hello"
+			default:
+				return false
+			}
+		}, "expected message on inbox")
+	})
+
+	t.Run("clean peer close calls OnExit with ExitCleanDisconnect", func(t *testing.T) {
+		v := setupWorkerTest(t)
+		defer v.worker.Stop()
+
+		go v.worker.Start(v.pool, v.wg)
+
+		v.incoming <- honeybeetest.MockIncomingData{
+			Err: &websocket.CloseError{Code: websocket.CloseNormalClosure},
+		}
+
+		honeybeetest.Eventually(t, func() bool {
+			val := v.exitKind.Load()
+			return val != nil && val.(WorkerExitKind) == ExitCleanDisconnect
+		}, "expected ExitCleanDisconnect")
+	})
+
+	t.Run("unexpected peer close calls OnExit with ExitUnexpectedDrop", func(t *testing.T) {
+		v := setupWorkerTest(t)
+		defer v.worker.Stop()
+
+		go v.worker.Start(v.pool, v.wg)
+
+		v.incoming <- honeybeetest.MockIncomingData{
+			Err: &websocket.CloseError{Code: websocket.CloseProtocolError},
+		}
+
+		honeybeetest.Eventually(t, func() bool {
+			val := v.exitKind.Load()
+			return val != nil && val.(WorkerExitKind) == ExitUnexpectedDrop
+		}, "expected ExitUnexpectedDrop")
+	})
+
+	t.Run("watchdog timeout calls OnExit with ExitInactive", func(t *testing.T) {
+		conn, _, _, _ := setupTestConnection(t)
+
+		ctx, cancel := context.WithCancel(context.Background())
+		worker, err := NewWorker(ctx, "peer-1", conn, &WorkerConfig{
+			DeadTimeout: 20 * time.Millisecond,
+		})
+		assert.NoError(t, err)
+		worker.cancel = cancel
+		defer worker.Stop()
+
+		exitKind := &atomic.Value{}
+		var once sync.Once
+		pool := PoolPlugin{
+			Inbox:  make(chan InboxMessage, 256),
+			Events: make(chan PoolEvent, 10),
+			OnExit: func(kind WorkerExitKind) {
+				once.Do(func() { exitKind.Store(kind) })
+			},
+		}
+
+		var wg sync.WaitGroup
+		wg.Add(1)
+		go worker.Start(pool, &wg)
+
+		honeybeetest.Eventually(t, func() bool {
+			val := exitKind.Load()
+			return val != nil && val.(WorkerExitKind) == ExitInactive
+		}, "expected ExitInactive")
+	})
+}
+
+func TestWorkerStop(t *testing.T) {
+	v := setupWorkerTest(t)
+
+	go v.worker.Start(v.pool, v.wg)
+
+	v.worker.Stop()
+
+	done := make(chan struct{})
+	go func() { v.wg.Wait(); close(done) }()
+
+	honeybeetest.Eventually(t, func() bool {
+		select {
+		case <-done:
+			return true
+		default:
+			return false
+		}
+	}, "expected wg to drain")
+
+	// does not call onExit
+	assert.Nil(t, v.exitKind.Load())
+}
+
+func TestWorkerSend(t *testing.T) {
+	t.Run("Send delivers data to socket", func(t *testing.T) {
+		v := setupWorkerTest(t)
+		defer v.worker.Stop()
+
+		go v.worker.Start(v.pool, v.wg)
+
+		err := v.worker.Send([]byte("hello"))
+		assert.NoError(t, err)
+
+		honeybeetest.ExpectWrite(t, v.outgoing, websocket.TextMessage, []byte("hello"))
+	})
+
+	t.Run("Send produces heartbeats", func(t *testing.T) {
+		v := setupWorkerTest(t)
+		defer v.worker.Stop()
+
+		count := atomic.Int32{}
+		go func() {
+			for range v.worker.heartbeat {
+				count.Add(1)
+			}
+		}()
+
+		// do not start the worker, allow heartbeats to be drained manually
+
+		for i := 0; i < 3; i++ {
+			err := v.worker.Send([]byte(fmt.Sprintf("msg-%d", i)))
+			assert.NoError(t, err)
+		}
+
+		honeybeetest.Eventually(t, func() bool {
+			return count.Load() == 3
+		}, "expected heartbeats")
+	})
+
+	t.Run("Send returns error after connection closed", func(t *testing.T) {
+		v := setupWorkerTest(t)
+		defer v.worker.Stop()
+
+		go v.worker.Start(v.pool, v.wg)
+
+		v.conn.Close()
+
+		honeybeetest.Eventually(t, func() bool {
+			return v.conn.State() == transport.StateClosed
+		}, "expected connection closed")
+
+		err := v.worker.Send([]byte("hello"))
+		assert.Error(t, err)
+	})
+}

inbound/worker_watchdog_test.go

@@ -0,0 +1,135 @@
+package inbound
+
+import (
+	"context"
+	"git.wisehodl.dev/jay/go-honeybee/honeybeetest"
+	"github.com/stretchr/testify/assert"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestRunWatchdog(t *testing.T) {
+	t.Run("heartbeat resets timer, onInactive not called", func(t *testing.T) {
+		heartbeat := make(chan struct{})
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		called := atomic.Bool{}
+		go RunWatchdog(ctx, func(WorkerExitKind) { called.Store(true) }, heartbeat, 200*time.Millisecond)
+
+		for i := 0; i < 5; i++ {
+			time.Sleep(20 * time.Millisecond)
+			heartbeat <- struct{}{}
+		}
+
+		honeybeetest.Never(t, func() bool {
+			return called.Load()
+		}, "unexpected onInactive call")
+	})
+
+	t.Run("timeout fires onInactive exactly once", func(t *testing.T) {
+		heartbeat := make(chan struct{})
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		var gotKind WorkerExitKind
+		count := atomic.Int32{}
+		done := make(chan struct{})
+		go RunWatchdog(ctx, func(kind WorkerExitKind) {
+			count.Add(1)
+			gotKind = kind
+			close(done)
+		}, heartbeat, 20*time.Millisecond)
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case <-done:
+				return true
+			default:
+				return false
+			}
+		}, "expected onInactive")
+
+		assert.Equal(t, int32(1), count.Load())
+		assert.Equal(t, ExitInactive, gotKind)
+	})
+
+	t.Run("ctx.Done exits without calling onInactive", func(t *testing.T) {
+		heartbeat := make(chan struct{})
+		ctx, cancel := context.WithCancel(context.Background())
+
+		called := atomic.Bool{}
+		done := make(chan struct{})
+		go func() {
+			RunWatchdog(ctx, func(WorkerExitKind) { called.Store(true) }, heartbeat, 20*time.Second)
+			close(done)
+		}()
+
+		cancel()
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case <-done:
+				return true
+			default:
+				return false
+			}
+		}, "expected RunWatchdog to exit")
+
+		assert.False(t, called.Load())
+	})
+
+	t.Run("zero timeout exits on ctx.Done without firing onInactive", func(t *testing.T) {
+		heartbeat := make(chan struct{})
+		ctx, cancel := context.WithCancel(context.Background())
+
+		called := atomic.Bool{}
+		done := make(chan struct{})
+		go func() {
+			RunWatchdog(ctx, func(WorkerExitKind) { called.Store(true) }, heartbeat, 0)
+			close(done)
+		}()
+
+		cancel()
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case <-done:
+				return true
+			default:
+				return false
+			}
+		}, "expected RunWatchdog to exit")
+
+		assert.False(t, called.Load())
+	})
+
+	t.Run("disabled keepalive drains heartbeats without blocking", func(t *testing.T) {
+		heartbeat := make(chan struct{})
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		done := make(chan struct{})
+		go func() {
+			RunWatchdog(ctx, func(WorkerExitKind) {}, heartbeat, 0)
+			close(done)
+		}()
+
+		// these must not block
+		for i := 0; i < 5; i++ {
+			heartbeat <- struct{}{}
+		}
+
+		cancel()
+
+		honeybeetest.Eventually(t, func() bool {
+			select {
+			case <-done:
+				return true
+			default:
+				return false
+			}
+		}, "expected RunWatchdog to exit")
+	})
+}