Documentation
¶
Overview ¶
client.go
handler.go
history.go
sse/sse.go
Index ¶
- type BeforeWrite
- type Client
- type Config
- type Handler
- func (h *Handler) API() http.HandlerFunc
- func (h *Handler) Broadcast(event string, data any, exclude ...string)
- func (h *Handler) ClientHandler(clientID string) http.HandlerFunc
- func (h *Handler) Handle() http.HandlerFunc
- func (h *Handler) Hub() *Hub
- func (h *Handler) JoinRoom(clientID, room string)
- func (h *Handler) LeaveRoom(clientID, room string)
- func (h *Handler) SendToClient(clientID, event string, data any) error
- func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (h *Handler) Shutdown()
- type HandlerConfig
- type Hub
- func (h *Hub) Broadcast(event string, data interface{}, exclude ...string)
- func (h *Hub) GetStats() Stats
- func (h *Hub) HandleClientAck(clientID string, beatTime int64) error
- func (h *Hub) JoinRoom(clientID, room string)
- func (h *Hub) LeaveRoom(clientID, room string)
- func (h *Hub) NewClient(id string, metadata map[string]interface{}) *Client
- func (h *Hub) Register(client *Client)
- func (h *Hub) SendToClient(clientID string, event string, data interface{}) error
- func (h *Hub) SendToRoom(room string, event string, data interface{}, exclude ...string)
- func (h *Hub) SetStorage(s Storage)
- func (h *Hub) Shutdown()
- type MemoryStorage
- func (s *MemoryStorage) Cleanup(maxAge time.Duration)
- func (s *MemoryStorage) DelClientAck(clientID string) error
- func (s *MemoryStorage) GetClientAck(clientID string) (int64, error)
- func (s *MemoryStorage) RangeSince(clientID string, since int64, fn func(msg *Message) bool)
- func (s *MemoryStorage) Save(msg *Message)
- func (s *MemoryStorage) SetClientAck(clientID string, ts int64) error
- type Message
- type OnClientConnect
- type Option
- type RequestMutator
- type SSEClient
- type SSEClientOption
- func WithClientAck(ackURL string) SSEClientOption
- func WithSSEClientHeader(key, val string) SSEClientOption
- func WithSSEClientMaxRetry(n int) SSEClientOption
- func WithSSEClientOnConnect(fn func()) SSEClientOption
- func WithSSEClientOnDisconnect(fn func()) SSEClientOption
- func WithSSEClientOnError(fn func(error)) SSEClientOption
- func WithSSEClientOnMessage(fn func(event string, data []byte)) SSEClientOption
- func WithSSEClientReconnect(d time.Duration) SSEClientOption
- type Stats
- type Storage
- type WriteFlusher
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BeforeWrite ¶
type BeforeWrite func(wf WriteFlusher)
BeforeWrite 在每次 w.Write 之前调用,用于框架特定的 flush 操作 wf 是实现了 WriteFlusher 接口的原始 ResponseWriter
type Client ¶
type Client struct {
ID string
LastEventID string // 客户端上次收到的消息 ID(重连时从请求头获取)
Send chan []byte
Hub *Hub
Metadata map[string]interface{}
// contains filtered or unexported fields
}
Client 客户端连接
func (*Client) SendMessage ¶
SendMessage 发送消息
type Config ¶
type Config struct {
HeartbeatInterval int // Server→Client 心跳间隔秒数(0=关闭,默认30秒)
// --- todo: 请求栈有bug,暂不开启 2026-05-30
ClientAckTimeout int // Client ack 超时秒数(默认0=关闭双向保活)
ClientAckMaxTimes int // 连续失败多少次后主动断开(0=默认3次)
MessageBufferSize int
EnableLog bool
}
Config 配置
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler SSE HTTP 处理器(可路由挂载)
func (*Handler) ClientHandler ¶
func (h *Handler) ClientHandler(clientID string) http.HandlerFunc
ClientHandler 返回客户端用 SSE Handler(带自动重连)
func (*Handler) SendToClient ¶
SendToClient 发送消息给客户端
type HandlerConfig ¶
type HandlerConfig struct {
// 消息历史保留时间(默认 5 分钟)
HistoryDuration time.Duration
// 历史清理间隔(默认 1 分钟)
CleanupInterval time.Duration
// 初始连接超时
ConnectTimeout time.Duration
}
func DefaultHandlerConfig ¶
func DefaultHandlerConfig() *HandlerConfig
type Hub ¶
type Hub struct {
// contains filtered or unexported fields
}
Hub 连接管理中心
func (*Hub) HandleClientAck ¶
HandleClientAck 处理 client 发来的 ack
func (*Hub) SendToClient ¶
SendToClient 发送给指定客户端
func (*Hub) SendToRoom ¶
SendToRoom 发送给房间
func (*Hub) SetStorage ¶
SetStorage 设置 storage(供 Handler 使用同一个 storage)
type MemoryStorage ¶
type MemoryStorage struct {
// contains filtered or unexported fields
}
MemoryStorage 内存存储(环形缓冲)
func NewMemoryStorage ¶
func NewMemoryStorage(cap int) *MemoryStorage
func (*MemoryStorage) Cleanup ¶
func (s *MemoryStorage) Cleanup(maxAge time.Duration)
func (*MemoryStorage) DelClientAck ¶
func (s *MemoryStorage) DelClientAck(clientID string) error
DelClientAck 删除客户端 ack 记录
func (*MemoryStorage) GetClientAck ¶
func (s *MemoryStorage) GetClientAck(clientID string) (int64, error)
GetClientAck 获取客户端最后 ack 时间
func (*MemoryStorage) RangeSince ¶
func (s *MemoryStorage) RangeSince(clientID string, since int64, fn func(msg *Message) bool)
func (*MemoryStorage) Save ¶
func (s *MemoryStorage) Save(msg *Message)
func (*MemoryStorage) SetClientAck ¶
func (s *MemoryStorage) SetClientAck(clientID string, ts int64) error
SetClientAck 设置客户端最后 ack 时间
type Message ¶
type Message struct {
ID string
Event string
Data []byte
Timestamp time.Time
ClientID string // 发送目标(空=广播)
IsSystem bool // 是否系统消息(heartbeat等,不存入历史)
}
Message 存储的消息结构
type OnClientConnect ¶
type OnClientConnect func(clientID string)
OnClientConnect 客户端连接成功时的回调(可选) 参数为 clientID,可用于向该 client 发送初始数据
type Option ¶
type Option func(*Handler)
func WithBeforeWrite ¶
func WithBeforeWrite(fn BeforeWrite) Option
WithBeforeWrite 设置每次 w.Write 之前的回调,用于框架特定的 flush 操作 beego 用户示例:sse.WithBeforeWrite(func(wf sse.WriteFlusher) { wf.Flush() })
func WithConfig ¶
func WithConfig(cfg *HandlerConfig) Option
func WithOnClientConnect ¶
func WithOnClientConnect(fn OnClientConnect) Option
WithOnClientConnect 设置客户端连接成功时的回调 可用于向新连接的客户端发送初始数据(如配置同步)
func WithRequestMutator ¶
func WithRequestMutator(fn RequestMutator) Option
WithRequestMutator 设置请求预处理函数,用于 path 重写等框架适配
func WithStorage ¶
type RequestMutator ¶
RequestMutator 请求预处理函数,用于 path 重写等框架适配
type SSEClient ¶
type SSEClient struct {
// contains filtered or unexported fields
}
SSEClient SSE 客户端
func NewSSEClient ¶
func NewSSEClient(url string, opts ...SSEClientOption) *SSEClient
NewSSEClient 创建 SSE 客户端
type SSEClientOption ¶
type SSEClientOption func(*SSEClient)
func WithClientAck ¶
func WithClientAck(ackURL string) SSEClientOption
WithClientAck 开启客户端回复 ack(收到 server 心跳后自动回 ack)
func WithSSEClientHeader ¶
func WithSSEClientHeader(key, val string) SSEClientOption
func WithSSEClientMaxRetry ¶
func WithSSEClientMaxRetry(n int) SSEClientOption
sseClient断线重连接机制:0表示不重试 -1表示无限重试
func WithSSEClientOnConnect ¶
func WithSSEClientOnConnect(fn func()) SSEClientOption
func WithSSEClientOnDisconnect ¶
func WithSSEClientOnDisconnect(fn func()) SSEClientOption
func WithSSEClientOnError ¶
func WithSSEClientOnError(fn func(error)) SSEClientOption
func WithSSEClientOnMessage ¶
func WithSSEClientOnMessage(fn func(event string, data []byte)) SSEClientOption
func WithSSEClientReconnect ¶
func WithSSEClientReconnect(d time.Duration) SSEClientOption
type Stats ¶
type Stats struct {
TotalClients int `json:"total_clients"`
TotalRooms int `json:"total_rooms"`
RoomNames []string `json:"room_names"`
}
Stats Hub 统计信息
type Storage ¶
type Storage interface {
// Save 保存消息
Save(msg *Message)
// Range 遍历指定时间戳之后的消息
RangeSince(clientID string, since int64, fn func(msg *Message) bool)
// Cleanup 清理过期消息
Cleanup(maxAge time.Duration)
// 以下三个方法是可选实现,未实现则双向保活不生效
// SetClientAck 设置客户端最后 ack 时间
SetClientAck(clientID string, ts int64) error
// GetClientAck 获取客户端最后 ack 时间
GetClientAck(clientID string) (int64, error)
// DelClientAck 删除客户端 ack 记录
DelClientAck(clientID string) error
}
Storage 消息存储接口(插拔式)
type WriteFlusher ¶
type WriteFlusher interface {
http.ResponseWriter
http.Flusher
CloseNotify() <-chan bool
}
WriteFlusher 组合了标准库的 http.ResponseWriter, http.Flusher, http.CloseNotifier 用于 SSE 流式响应,让外部框架可以直接拿到原始 Writer 进行 flush 操作