sse

Documentation

Overview

Package sse provides utilities for working with Server Sent Events (SSE).

Index

• Variables
• func Register[I any](api huma.API, op huma.Operation, eventTypeMap map[string]any, ...)
• type Message
• type Sender
  • func (s Sender) Data(data any) error

Examples

• Register (Sse)

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)

// 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.
router := chi.NewMux()
api := humachi.New(router, 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")
})

Types

type Message

type Message struct {
	ID    int
	Data  any
	Retry int
}

Message is a single SSE message. There is no `event` field as this is handled by the `eventTypeMap` when registering the operation.

type Sender

type Sender func(Message) error

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.

func (Sender) Data

func (s Sender) Data(data any) error

Data sends a message with the given data to the client. This is equivalent to calling `sender(Message{Data: data})`.