Server Sent Events

This module implements the server side of Server Sent Events, SSE. See [mozilla SSE][mozilla_sse] as well as [whatwg][whatwg html spec] for detailed description of the protocol, and a simple web browser client example.

SSEMessage.encode() returns the same wire representation used by send_message, through the shared net.http.SSEEvent encoder. It normalizes data line endings and removes CR/LF from the ID and event name. Empty fields are omitted, so a message with empty data does not dispatch a browser event. Use nonempty data when sending a message to an event listener.

Usage

With SSE we want to keep the connection open, so we are able to keep sending events to the client. But if we hold the connection open indefinitely veb isn't able to process any other requests.

We can let veb know that it can continue processing other requests and that we will handle the connection ourself by calling ctx.takeover_conn() and returning an empty result with veb.no_result(). veb will not close the connection and we can handle the connection in a separate thread.

Example:

import veb.sse

// endpoint handler for SSE connections
fn (app &App) sse(mut ctx Context) veb.Result {
    // let veb know that the connection should not be closed
    ctx.takeover_conn()
    // handle the connection in a new thread
    spawn handle_sse_conn(mut ctx)
    // we will send a custom response ourself, so we can safely return an empty result
    return veb.no_result()
}

fn handle_sse_conn(mut ctx Context) {
    // pass veb.Context
    mut sse_conn := sse.start_connection(mut ctx.Context)

    // send a message every second 3 times
    for _ in 0.. 3 {
        time.sleep(time.second)
        sse_conn.send_message(data: 'ping') or { break }
    }
    // close the SSE connection
    sse_conn.close()
}

Javascript code:

const eventSource = new EventSource('/sse');

eventSource.addEventListener('message', (event) => {
    console.log('received message:', event.data);
});

eventSource.addEventListener('close', () => {
    console.log('closing the connection');
    // prevent browser from reconnecting
    eventSource.close();
});

[mozilla_sse]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events [whatwg html spec]: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events

fn start_connection(mut ctx veb.Context) &SSEConnection

start an SSE connection

struct SSEConnection {
pub mut:
	conn &net.TcpConn @[required]
}

fn (mut sse SSEConnection) send_message(message SSEMessage) !

send_message sends a single message to the http client that listens for SSE. It does not close the connection, so you can use it many times in a loop.

fn (mut sse SSEConnection) close()

send a 'close' event and close the tcp connection.

struct SSEMessage {
pub mut:
	id    string
	event string
	data  string
	retry int
}

fn (m SSEMessage) encode() string

encode serializes the message to the SSE wire format. It delegates to the shared http.SSEEvent encoder, so veb.sse frames events exactly like every other SSE producer in vlib.