Documentation
¶
Overview ¶
Package sse provides utilities for working with Server Sent Events (SSE).
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var WriteTimeout = 5 * time.Second
WriteTimeout is the timeout for writing to the client.
Functions ¶
func Register ¶
func Register[I any](api huma.API, op huma.Operation, eventTypeMap map[string]any, f func(ctx context.Context, input *I, send Sender))
Register a new SSE operation. The `eventTypeMap` maps from event name to the type of the data that will be sent. The `f` function is called with the context, input, and a `send` function that can be used to send messages to the client. Flushing is handled automatically as long as the adapter's `BodyWriter` implements `http.Flusher`.
Example (Sse) ¶
package main
import (
"context"
"net/http"
"github.com/danielgtaylor/huma/v2"
"github.com/danielgtaylor/huma/v2/adapters/humago"
"github.com/danielgtaylor/huma/v2/sse"
)
func main() {
// 1. Define some message types.
type DefaultMessage struct {
Message string `json:"message"`
}
type UserEvent struct {
UserID int `json:"user_id"`
Username string `json:"username"`
}
type UserCreatedEvent UserEvent
type UserDeletedEvent UserEvent
// 2. Set up the API.
mux := http.NewServeMux()
api := humago.New(mux, huma.DefaultConfig("My API", "1.0.0"))
// 3. Register an SSE operation.
sse.Register(api, huma.Operation{
OperationID: "sse",
Method: http.MethodGet,
Path: "/sse",
}, map[string]any{
// Map each event name to a message type.
"message": &DefaultMessage{},
"userCreate": UserCreatedEvent{},
"userDelete": UserDeletedEvent{},
}, func(ctx context.Context, input *struct{}, send sse.Sender) {
// Use `send.Data` to send a message with the event type set to the
// corresponding registered type from the map above. For this example,
// it will send "message" as the type.
send.Data(DefaultMessage{Message: "Hello, world!"})
// Use `send` for more control, letting you set an ID and retry interval.
// The event type is still controlled by the map above and type passed
// as data below, in this case "userCreate" is sent.
send(sse.Message{
ID: 5,
Retry: 1000,
Data: UserCreatedEvent{UserID: 1, Username: "foo"},
})
// Example "userDelete" event type.
send.Data(UserDeletedEvent{UserID: 2, Username: "bar"})
// Unknown event type gets sent as the default. Still uses JSON encoding!
send.Data("unknown event")
})
}
Output:
Types ¶
type Message ¶
type Message struct {
ID int
Data any
Retry int
// Comment, if set, is written as one or more SSE comment lines (each line
// prefixed with a colon and ignored by clients). It may accompany an event
// or, when `Data` is nil, form a comment-only message such as a heartbeat
// used to keep the connection alive.
Comment string
}
Message is a single SSE message. There is no `event` field as this is handled by the `eventTypeMap` when registering the operation.
type Sender ¶
Sender is a send function for sending SSE messages to the client. It is callable but also provides a `sender.Data(...)` convenience method if you don't need to set the other fields in the message.
Source Files