README
¶
sse
Server-Sent Events hub for real-time client communication with pattern-based broadcasting.
Install
go get github.com/kbukum/gokit
Quick Start
package main
import (
"net/http"
"github.com/kbukum/gokit/sse"
)
func main() {
hub := sse.NewHub()
go hub.Run()
// SSE endpoint
http.HandleFunc("/events", func(w http.ResponseWriter, r *http.Request) {
clientID := r.URL.Query().Get("id")
sse.ServeSSE(hub, w, r, clientID,
sse.WithUserID("user-123"),
sse.WithMetadata("role", "admin"),
)
})
// Broadcast to clients matching a pattern
hub.BroadcastToPattern("user-*", []byte(`{"type":"update","data":"hello"}`))
http.ListenAndServe(":8080", nil)
}
Key Types & Functions
| Name | Description |
|---|---|
Hub |
Manages SSE client connections and broadcasting |
Client |
Connected SSE client with metadata |
NewHub() / Run() |
Create and start the hub |
ServeSSE() |
HTTP handler for SSE connections |
BroadcastToPattern() |
Send data to clients matching a pattern |
Broadcaster |
Interface for broadcasting events |
WithUserID() / WithSessionID() / WithMetadata() |
Client options |
EventType* |
Constants: connected, keepalive, message, error, metric |
Documentation
¶
Overview ¶
Package sse provides Server-Sent Events (SSE) support for real-time streaming.
Package sse provides Server-Sent Events (SSE) infrastructure for real-time event delivery in gokit applications.
It includes client connection management, event broadcasting to multiple subscribers, and a hub for managing event channels.
Architecture ¶
- Hub: Central event router managing client subscriptions
- Broadcaster: Sends events to all connected clients
- Handler: HTTP handler for SSE endpoint
Usage ¶
hub := sse.NewHub()
go hub.Run()
handler := sse.NewHandler(hub)
router.GET("/events", handler.ServeHTTP)
Package sse provides Server-Sent Events (SSE) support for real-time streaming.
Index ¶
Constants ¶
const ( // EventTypeConnected is sent when a client successfully connects. EventTypeConnected = "connected" // EventTypeKeepAlive is used for keep-alive comments. EventTypeKeepAlive = "keepalive" // EventTypeMessage is a generic message event. EventTypeMessage = "message" // EventTypeError is sent when an error occurs. EventTypeError = "error" // EventTypeMetric is sent for metric/telemetry events. EventTypeMetric = "metric" )
Generic SSE event type constants (infrastructure only). Domain-specific event types should be defined in your application.
Variables ¶
This section is empty.
Functions ¶
func ServeSSE ¶
func ServeSSE(hub *Hub, w http.ResponseWriter, r *http.Request, clientID string, opts ...ClientOption)
ServeSSE handles an SSE connection for a specific client. This is the main entry point called from HTTP handlers.
Types ¶
type Broadcaster ¶
type Broadcaster interface {
// BroadcastToPattern sends data to all clients matching the given pattern.
// Pattern uses glob-style matching (e.g., "resource:*" or "resource:abc123").
BroadcastToPattern(pattern string, data []byte)
}
Broadcaster is an interface for broadcasting events to clients. This allows handlers to depend on an abstraction rather than a concrete Hub.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client represents a connected SSE client.
func NewClient ¶
func NewClient(id string, opts ...ClientOption) *Client
NewClient creates a new SSE client with optional metadata.
func (*Client) GetMetadata ¶
GetMetadata returns a specific metadata value.
func (*Client) Send ¶
Send sends data to the client's event channel. Returns false if the channel is full (client is slow).
type ClientOption ¶
type ClientOption func(*Client)
ClientOption configures a Client.
func WithMetadata ¶
func WithMetadata(key, value string) ClientOption
WithMetadata adds a metadata key-value pair to the client.
func WithSessionID ¶
func WithSessionID(sessionID string) ClientOption
WithSessionID sets the session ID metadata.
type Component ¶
type Component struct {
// contains filtered or unexported fields
}
Component wraps an SSE Hub as a lifecycle-managed component. Register it with the component registry so Start/Stop are handled automatically.
func NewComponent ¶
NewComponent creates a new SSE component with a fresh Hub.
func (*Component) Describe ¶
func (c *Component) Describe() component.Description
Describe returns infrastructure summary info for the bootstrap display.
func (*Component) Hub ¶
Hub returns the underlying Hub for event broadcasting and client management.
type ConnectedEvent ¶
type ConnectedEvent struct {
ClientID string `json:"client_id"`
UserID string `json:"user_id,omitempty"`
SessionID string `json:"session_id,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
ConnectedEvent is sent when a client successfully connects.
type Hub ¶
type Hub struct {
// contains filtered or unexported fields
}
Hub manages SSE client connections and message broadcasting.
func (*Hub) BroadcastToPattern ¶
BroadcastToPattern sends data to all clients matching the pattern. Pattern uses glob-style matching (e.g., "execution:*" or "execution:abc123").
func (*Hub) GetClientCount ¶
GetClientCount returns the number of connected clients.
func (*Hub) GetClientIDs ¶
GetClientIDs returns a list of all connected client IDs.
func (*Hub) Run ¶
func (h *Hub) Run()
Run starts the hub's main event loop. It blocks until Stop is called or the context is canceled. This should be run in a goroutine.
func (*Hub) Stop ¶
func (h *Hub) Stop()
Stop signals the hub to shut down. It closes all client connections and causes Run to return. Safe to call multiple times.
func (*Hub) Unregister ¶
Unregister removes a client from the hub.
Source Files