README
¶
Server-Send Events
Traditionally, a web page has to send a request to the server to receive new data; that is, the page requests data from the server. With server-sent events, it's possible for a server to send new data to a web page at any time, by pushing messages to the web page.
More information: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events
Server
On the server side, you can use the Handler function to automatically
create and handle SSE subscriptions based on incoming client HTTP requests.
// Handler
router := lib.NewServeMux()
router.HandleFunc("/sse", Handler(yourStreamSetupFunction))
// Server options
opts := []http.Option{
// SSE requires no timeout on "keep-alive" connections
http.WithIdleTimeout(0),
http.WithHandler(router),
http.WithPort(8080),
}
// Start server
srv, _ := http.NewServer(opts...)
go func() {
_ = srv.Start()
}()
Client
A client instance can be used to subscribe to a SSE stream on the server.
// Create client instance
cl, _ := NewClient(nil)
// Prepare a request and submit it to the server to obtain
// a subscription instance in return.
req, _ := PrepareRequest(context.Background(), "http://localhost:8080/sse", nil)
sub, err := cl.Subscribe(req)
// Handle incoming events
for ev := range sub.Receive() {
fmt.Printf("server event: %+v", ev)
}
Documentation
¶
Overview ¶
Package sse provides a "Server-Send Events" server/client implementation.
Traditionally, a web page has to send a request to the server to receive new data; that is, the page requests data from the server. With server-sent events, it's possible for a server to send new data to a web page at any time, by pushing messages to the web page.
More information: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
func Handler(setup func(req *http.Request) *Subscription) http.HandlerFunc
Handler provides a basic "Server-Send Events" handler implementation. The provided `setup` function allows to flexibly create streams and/or subscriptions based on the HTTP request contents, e.g., credentials, headers, query, etc.
- SSE requires no timeouts on "keep-alive" connections on the server side.
- If the subscription is closed by the server, the client connection will be closed as well.
- If the client connection drops, the subscription will be closed on the server as well.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client instances can be used to receive events published by a server via subscriptions. A single client can be used to open any number of subscriptions.
type Event ¶
type Event struct {
// contains filtered or unexported fields
}
Event instances are the minimal communication unit between the server/publisher and any clients/subscribers. https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#fields
func (Event) Decode ¶
Decode the event data into the provided `target` element. If `target` is `nil` or not a pointer this method returns `json.InvalidUnmarshalError`.
type Stream ¶
type Stream struct {
// contains filtered or unexported fields
}
Stream operators provide a simple pub/sub one-directional mechanism that allows a sender (i.e., server) to broadcast events to one or more subscribers (i.e., clients).
func NewStream ¶
func NewStream(name string, opts ...StreamOption) (*Stream, error)
NewStream returns a new stream operator with the provided name. A stream operator can be used on the server (i.e., sender) side to broadcast events and messages to connected subscribers.
func (*Stream) Close ¶
func (st *Stream) Close()
Close the stream and free any related resources. Once closed, all send operations on the stream instance are no-ops.
func (*Stream) SendEvent ¶
SendEvent broadcast an event with the provided `name` and `payload` to the stream clients.
func (*Stream) SendMessage ¶
func (st *Stream) SendMessage(payload interface{})
SendMessage broadcast a message with the provided `payload` to the stream clients.
func (*Stream) Subscribe ¶
func (st *Stream) Subscribe(ctx context.Context, id string) *Subscription
Subscribe will register a new client/receiver for the stream. The provided `id` value MUST be unique. If a subscriber already exists with the `id`, a reference to it will be returned.
func (*Stream) Unsubscribe ¶
Unsubscribe will terminate and remove an existing client/receiver. If no client exists for `id` this method returns `false`.
type StreamOption ¶
StreamOption provide a functional-style mechanism to adjust the behavior of a stream operator instance.
func WithLogger ¶
func WithLogger(logger xlog.Logger) StreamOption
WithLogger set the log handler for the stream operator. Logs are discarded by default.
func WithMessageRetry ¶
func WithMessageRetry(retry uint) StreamOption
WithMessageRetry adjust the `retry` message value, in milliseconds, set by the stream for all send messages and events. Default value is `2000`.
func WithSendTimeout ¶
func WithSendTimeout(timeout time.Duration) StreamOption
WithSendTimeout adjust the maximum time to wait for message delivery on send operations. Default value is 2 seconds.
type Subscription ¶
type Subscription struct {
// contains filtered or unexported fields
}
Subscription instances can be used to receive events published by the originating stream operator.
func (*Subscription) Done ¶
func (sb *Subscription) Done() <-chan struct{}
Done returns a channel that's closed when the subscription is being terminated. No further activity should be expected on `Receive`.
func (*Subscription) ID ¶
func (sb *Subscription) ID() string
ID returns the subscriber's unique identifier.
func (*Subscription) Receive ¶
func (sb *Subscription) Receive() <-chan Event
Receive any events published by the stream.
Source Files