sse

README

SSE - Server-Sent Events Writer

sse is a lightweight Go library for writing Server-Sent Events (SSE). This library allows easy integration of SSE into web servers, providing real-time updates to connected clients.

Installation

To install the sse package, use the following command:

go get github.com/floriscornel/sse

Usage

Importing the Package

import (
    "net/http"
    "github.com/floriscornel/sse"
)

Creating a Server-Sent Events Writer

To create an SSE writer, use the NewResponseWriter function. This function requires an http.ResponseWriter and options to configure the SSE writer.

opts := sse.Options{
    ResponseStatus: http.StatusOK,
    Encoding:       sse.EncodeNone,
}

func handler(w http.ResponseWriter, r *http.Request) {
    sseWriter := sse.NewResponseWriter(w, opts)

    for {
        err := sseWriter.Write("message", map[string]string{"hello": "world"})
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        time.Sleep(2 * time.Second)
    }
}

http.HandleFunc("/events", handler)
log.Fatal(http.ListenAndServe(":8080", nil))

Encoding Options

The sse package supports various encoding options to compress the data sent to clients. Available encoding options include:

• EncodeNone
• EncodeDeflate
• EncodeCompress
• EncodeGzip
• EncodeBrotli
• EncodeZstd

Specify the desired encoding in the Options struct:

opts := sse.Options{
    ResponseStatus: http.StatusOK,
    Encoding:       sse.EncodeGzip,
}

Examples

You can find more examples in the examples directory. To run an example, navigate to the respective directory and execute the following command:

go run main.go

Example Structure

• ping: A simple example of sending periodic ping messages to the client.
• incremental-updates: Demonstrates sending incremental updates to the client with different event types.
• number-of-listeners: Implements a counter to track the number of connected clients.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

If you have any questions, feel free to reach out:

• Author: Floris Cornel
• Email: floris@cornel.email
• GitHub: github.com/floriscornel/sse

Documentation

Index

• Constants
• type Options
• type Writer
  • func NewResponseWriter(w http.ResponseWriter, opts Options) Writer

Constants

const (
	// No encoding applied
	EncodeNone = ""

	// Compress the data using the DEFLATE algorithm
	// See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding#deflate
	EncodeDeflate = "deflate"

	// Compress the data using the LZW algorithm
	// See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding#compress
	EncodeCompress = "compress"

	// Compress the data using the GZIP algorithm
	// See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding#gzip
	EncodeGzip = "gzip"

	// Compress the data using the Brotli algorithm
	// See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding#br
	EncodeBrotli = "br"

	// Compress the data using the Zstandard algorithm
	// See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding#zstd
	EncodeZstd = "zstd"
)

const (
	// NonceMax is the maximum value of the `id` field in SSE before it resets to 0.
	NonceMax = 1<<63 - 1
)

Types

type Options

type Options struct {
	ResponseStatus int
	Encoding       string
}

Options holds configuration for the SSE writer.

type Writer

type Writer interface {
	Write(event string, data interface{}) error
}

Writer is the interface for writing Server-Sent Events.

func NewResponseWriter

func NewResponseWriter(w http.ResponseWriter, opts Options) Writer

NewResponseWriter creates a new Writer for Server-Sent Events.