🔥 BlazeWave Pulse

Ultra-high-performance, event-driven WebSocket server framework 🚀

English | 中文

📖 Introduction

BlazeWave Pulse is a production-ready WebSocket server framework built on top of BlazeWave. It provides enterprise-grade real-time communication capabilities with binary protocol optimization, intelligent session management, and comprehensive broadcasting features.

BlazeWave vs BlazeWave Pulse

BlazeWave is a high-performance, event-driven WebSocket library designed as a network infrastructure layer. It provides the core networking primitives, zero-copy I/O operations, and low-level WebSocket protocol handling. BlazeWave focuses on raw performance and minimal overhead, offering developers the fundamental building blocks for WebSocket communication.

BlazeWave Pulse is an enterprise-grade application framework built on top of BlazeWave. It provides higher-level abstractions including session management, broadcasting systems, event handling, and production-ready features. While BlazeWave handles the network transport layer, BlazeWave Pulse handles the application logic layer.

BlazeWave Pulse is not meant to replace BlazeWave, but rather to provide developers with a ready-to-use solution for building real-time applications. It leverages BlazeWave's performance advantages while adding the enterprise features needed for production deployments. Developers can use BlazeWave Pulse to quickly build chat systems, real-time collaboration tools, live streaming applications, and other WebSocket-based services without dealing with low-level networking complexities.

✨ Features

• 🚀 Ultra-High Performance: Built on BlazeWave's zero-copy architecture, achieving exceptional performance through minimized memory allocation, reduced GC pressure, and optimized I/O operations
• ⚡ Smart Memory Management: Cache-line aligned lock-free ring buffers with dynamic pool selection for optimal load distribution across CPU cores
• 🎯 Event-Driven Architecture: Intuitive and flexible event system with middleware support, simplifying real-time application development
• 🛡️ Production Ready: Hash-distributed bucket session management (FNV-1a algorithm), built-in heartbeat mechanism ensuring connection health
• 🔧 Developer Friendly: Clean and type-safe API, binary protocol optimization, extensive examples and demos
• 🌐 Real-time Broadcasting: Multiple broadcasting strategies (all, tags, specific sessions) with session metadata and tagging system
• 📊 Connection Management: Unified WebSocket connection lifecycle handling, protocol compliance guarantee, graceful error handling

🏗️ Architecture Components

🏗️ BlazeWave Pulse Architecture Design

┌─────────────────────────────────────────────────────────────────────────────┐
│                        BlazeWave Pulse Core Architecture                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────────┐         │
│  │  Application    │    │   Session       │    │   Protocol       │         │
│  │ • Event System  │◄──►│ • Bucket Mgmt   │◄──►│ • Binary Proto   │         │
│  │ • Broadcasting  │    │ • Ring Buffer   │    │ • Message Pool   │         │
│  │ • Middleware    │    │ • Hash Dist.    │    │ • Zero-Copy I/O  │         │
│  └─────────────────┘    └─────────────────┘    └──────────────────┘         │
│           │                       │                       │                 │
│           ▼                       ▼                       ▼                 │
│  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────────┐         │
│  │ Infrastructure  │    │ Optimization    │    │ Network Layer    │         │
│  │ • Dynamic Pools │    │ • Round-Robin   │    │ • BlazeWave Core │         │
│  │ • Load Balance  │    │ • Cache-Line    │    │ • WebSocket      │         │
│  │ • Zero-Contention│   │ • Lock-Free     │    │ • HTTP Upgrade   │         │
│  └─────────────────┘    └─────────────────┘    └──────────────────┘         │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

📦 Installation

go get github.com/heyehang/blazewave-pulse

🚀 Quick Start

Basic Server Setup

package main

import (
    "context"
    "log"
    "net/http"
    "github.com/heyehang/blazewave-pulse"
)

func main() {
    // Create BlazeWave Pulse server with default configuration
    pulse := blazewavepulse.New()
    
    // Register event handlers
    pulse.OnConnect(func(ctx context.Context, session *blazewavepulse.Session) error {
        log.Printf("New session connected: %s", session.Key())
        return nil
    })
    
    pulse.OnBinaryMessage(func(ctx context.Context, session *blazewavepulse.Session, proto *blazewavepulse.Proto) error {
        log.Printf("Received message: op=%d, seq=%d, body=%s", 
            proto.Operation, proto.Sequence, string(proto.Body))
        
        // Echo back to all sessions
        return pulse.Broadcast(ctx, proto)
    })
    
    pulse.OnClose(func(ctx context.Context, session *blazewavepulse.Session, code blazewave.StatusCode, reason string) error {
        log.Printf("Session disconnected: %s", session.Key())
        return nil
    })
    
    // Setup HTTP handler
    http.HandleFunc("/ws", func(w http.ResponseWriter, r *http.Request) {
        if err := pulse.HandleRequest(w, r); err != nil {
            log.Printf("WebSocket upgrade failed: %v", err)
        }
    })
    
    log.Println("BlazeWave Pulse server starting on :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Advanced Configuration

package main

import (
    "time"
    "github.com/heyehang/blazewave-pulse"
)

func main() {
    // Custom configuration
    config := &blazewavepulse.Config{
        BucketCount:       64,                    // 64 buckets for better distribution
        HeartbeatInterval: 30 * time.Second,      // 30s heartbeat interval
        HeartbeatTimeout:  10 * time.Second,      // 10s heartbeat timeout
        SessionConfig: &blazewavepulse.SessionConfig{
            WriteLoopSleepDuration: 50 * time.Microsecond, // Optimized sleep duration
            RingConfig: &blazewavepulse.RingConfig{
                RingSize: 15, // Larger ring buffer for high-throughput scenarios
            },
        },
    }
    
    // Create server with custom configuration
    pulse := blazewavepulse.NewBlazeWavePulse(config)
    
    // ... rest of the setup
}

Broadcasting Examples

// Broadcast to all sessions
proto := &blazewavepulse.Proto{
    Version:   1,
    Operation: 1, // MESSAGE
    Sequence:  1,
    Body:      []byte(`{"message": "Hello, World!"}`),
}
pulse.Broadcast(ctx, proto)

// Broadcast to specific sessions
sessionKeys := []string{"session1", "session2", "session3"}
pulse.BroadcastToSessionKeys(ctx, proto, sessionKeys)

// Broadcast to sessions with specific tags
pulse.BroadcastToSessionTags(ctx, proto, "premium", "vip")

// Broadcast to all except one session
pulse.BroadcastOthers(ctx, proto, "excludeSessionKey")

// Send to specific session
pulse.SendToSessionKey(ctx, "targetSessionKey", proto)

📊 Performance Benchmarks

For detailed performance benchmark reports, metrics, and flame graph analysis, please refer to:

📊 Complete Performance Benchmark Report

🔧 API Reference

Core Types

// BlazeWavePulse - Main server instance
type BlazeWavePulse struct { ... }

// Session - Represents a client session
type Session struct { ... }

// Proto - Binary protocol message
type Proto struct {
    Version   int32  `json:"ver"`
    Operation int32  `json:"op"`
    Sequence  int32  `json:"seq"`
    Body      []byte `json:"body"`
}

// Config - Server configuration
type Config struct {
    BucketCount       int
    HeartbeatInterval time.Duration
    HeartbeatTimeout  time.Duration
    SessionConfig     *SessionConfig
}

Key Methods

// Server lifecycle
func New() *BlazeWavePulse
func NewBlazeWavePulse(config *Config, options ...BlazeWavePulseOption) *BlazeWavePulse

// Request handling
func (bwp *BlazeWavePulse) HandleRequest(w http.ResponseWriter, r *http.Request) error
func (bwp *BlazeWavePulse) HandleRequestWithProperties(w http.ResponseWriter, r *http.Request, tags map[string]struct{}, metaData map[string]any) error

// Broadcasting
func (bwp *BlazeWavePulse) Broadcast(ctx context.Context, proto *Proto) error
func (bwp *BlazeWavePulse) BroadcastOthers(ctx context.Context, proto *Proto, excludeSessionKey string) error
func (bwp *BlazeWavePulse) BroadcastToSessionKeys(ctx context.Context, proto *Proto, sessionKeys []string, tags ...string) error
func (bwp *BlazeWavePulse) BroadcastToSessionTags(ctx context.Context, proto *Proto, tags ...string) error

// Session management
func (bwp *BlazeWavePulse) GetSession(key string) (*Session, bool)
func (bwp *BlazeWavePulse) CloseSession(key string)
func (bwp *BlazeWavePulse) GetSessionCount() int
func (bwp *BlazeWavePulse) GetAllSessions() map[string]*Session

// Event handlers
func (bwp *BlazeWavePulse) OnConnect(handlers ...func(ctx context.Context, session *Session) error)
func (bwp *BlazeWavePulse) OnBinaryMessage(handlers ...func(ctx context.Context, session *Session, proto *Proto) error)
func (bwp *BlazeWavePulse) OnClose(handlers ...func(ctx context.Context, session *Session, code blazewave.StatusCode, reason string) error)

📚 Available Demo

Check out our interactive examples:

• Chat Demo: Real-time chat application with user management
• 
• Shared Mascot: Collaborative mascot movement demo
• 
• More Examples: Complete list of available demos

🙏 Acknowledgments

• Built on top of BlazeWave - The high-performance WebSocket library
• Inspired by modern real-time communication patterns
• Designed for production-scale applications

⭐ Star History

---

BlazeWave Pulse - Where Performance Meets Real-Time ⚡