hxsocketsfiber

hxsocketsfiber

Go library providing WebSocket integration for HTMX applications using the Fiber framework. Simplifies real-time server-driven web apps.

Go, WebSockets, Fiber, HTMX
Started: 5/28/2024
Updated: 12/15/2024
go,library,websockets,htmx,fiber
GitHub

hxsocketsfiber Demo Real-time WebSocket communication demo

Overview

A custom Go library that bridges HTMX and WebSockets in Fiber applications, making it easy to build real-time, server-driven web applications. This library powers the WebSocket functionality in my HTMX 3D game and other real-time projects.

Features

  • Simple API - Clean, intuitive interface for WebSocket handling
  • Event-Based Architecture - Listen to specific WebSocket events with custom handlers
  • Client Management - Built-in client tracking and filtering
  • Fiber Integration - Seamless integration with the Fiber web framework
  • Thread-Safe - Concurrent client management with mutex protection
  • Connection Lifecycle - Hooks for client connect/disconnect events

API Design

Core Components

Server Management:

  • Listen(endpoint, handler) - Register event handlers for WebSocket endpoints
  • Mount(endpoint) - Attach WebSocket routes to your Fiber app
  • GetAllClients() - Retrieve all connected clients
  • GetClient(id) - Find specific client by ID
  • GetClientFilter(filter) - Query clients with custom filter function

Client Management:

  • Automatic client ID generation
  • Connection state tracking
  • Individual client messaging
  • Graceful disconnection handling

Lifecycle Hooks:

  • OnClientConnect - Called when a new client connects
  • OnClientDisconnect - Called when a client disconnects

Usage Example

import "github.com/DeaSTL/hxsocketsfiber"

// Create server
server := hx.NewServer(app)

// Listen for events
server.Listen("player-move", func(client *hx.Client, msg []byte) {
    // Handle player movement
    log.Printf("Player %s moved", client.ID)
})

// Mount WebSocket endpoint
server.Mount("/ws")

// Optional lifecycle hooks
server.OnClientConnect = func(client *hx.Client) {
    log.Printf("Client %s connected", client.ID)
}

Technical Implementation

Architecture

The library abstracts away the complexity of WebSocket management in Fiber applications:

  • Automatic upgrade handling for WebSocket connections
  • Thread-safe client registry with concurrent access protection
  • Event-based message routing to registered handlers
  • Clean separation between connection management and application logic

Design Philosophy

Built with the following principles:

  • Developer Experience - Simple, predictable API
  • Type Safety - Leverages Go's type system for compile-time safety
  • Performance - Efficient client lookup and message routing
  • Flexibility - Filter and query clients based on custom criteria

Real-World Usage

This library is used in production for:

  • HTMX 3D Game - Real-time multiplayer synchronization
  • WebSocket Demos - Teaching HTMX + WebSocket integration
  • Server-Driven Apps - Building reactive applications without heavy client-side JavaScript

Why This Library?

While Fiber has WebSocket support, hxsocketsfiber adds:

  • HTMX-specific patterns and conventions
  • Simplified event-based message handling
  • Built-in client management and filtering
  • Opinionated structure for server-driven real-time apps

Installation

go get github.com/DeaSTL/hxsocketsfiber

Related Projects