The sse-demo Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The sse-demo Reference Manual

This is the sse-demo Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 04:03:48 2022 GMT+0.

Table of Contents


1 Introduction

About

cl-sse is an partial implementation of the Server Side Events protocol as per https://www.w3.org/TR/eventsource/. It is a toolkit for Common Lisp service implementations that want to send or receive events according to the protocol. There is a small demo you can try with a browser (instructions below).

The protocol originated for use in browsers, where most browsers support a javascript EventSource implementation that can be used to receive pushed event dispatches from a web server.

With appreciation to https://gist.github.com/jareware/aae9748a1873ef8a91e5 for a browser eventsource example.

Modules

server.lisp

The server.lisp module is for the push piece of the protocol. You could probably make do with format, but this piece ensures that protocols are observed if you aren't familiar with SSE, though it does differ in that it requires an event name/type where the spec consider this optional.

client.lisp

The client.lisp module is for CL services that want to receive SSE pushes. SSE clients outside of javascript don't seem to be very common, but it definitely has uses. For example a server might use SSE to receive job dispatches in a microservice architecture. In fact, if you were to use SSE for job dispatches, browsers could easily be workers.

I was tempted to have the event properties be nil, instead of empty strings, when they weren't in the event, however I opted instead to follow the spec a bit more closely, for no particularly good reason. As there are no users of this code it's something of a moot point, it was mostly for example purposes.

demo.lisp

Shows SSE in action in a browser. Use as follows:

  1. (ql:quickload :sse-demo)
  2. (sse:demo/start-server) ; starts a hunchentoot server (in demo::http-server)
  3. Connect a browser to localhost:8080/sse and watch the demo unfold.

By connecting to the SSE page, the browser will execute some javascript code that connects to SSE service on the /events endpoint, and responds to a loop emitting sse events coming from the server. After receiving 10 events the server hangs up, and the browser re-acquires the /events endpoing and it starts over gain.

  1. When you're done, kill your browser tab, and (sse:demo/stop-server) to kill the web service.

2 Systems

The main system appears first, followed by any subsystem dependency.


Next: , Previous: , Up: Systems   [Contents][Index]

2.1 sse-demo

Use sse-server + a web service to serve SSE events to a browser.

Author

Dave Tenny

License

MIT

Version

0.1.0

Dependencies
  • sse-server (system).
  • hunchentoot (system).
  • easy-routes (system).
  • flexi-streams (system).
  • sse-server (system).
Source

sse-demo.asd.

Child Component

demo.lisp (file).


Previous: , Up: Systems   [Contents][Index]

2.2 sse-server

sse-server implements support for the sender side of Server Side Events

Author

Dave Tenny

License

MIT

Version

0.1.0

Dependencies
  • cl-ppcre (system).
  • trivial-escapes (system).
Source

sse-server.asd.

Child Component

server.lisp (file).


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 sse-demo/sse-demo.asd

Source

sse-demo.asd.

Parent Component

sse-demo (system).

ASDF Systems

sse-demo.

Packages

sse-demo-asd.


3.1.2 sse-server/sse-server.asd

Source

sse-server.asd.

Parent Component

sse-server (system).

ASDF Systems

sse-server.

Packages

sse-server-asd.


3.1.3 sse-demo/demo.lisp

Source

sse-demo.asd.

Parent Component

sse-demo (system).

Packages

sse-demo.

Public Interface
Internals

Previous: , Up: Lisp   [Contents][Index]

3.1.4 sse-server/server.lisp

Source

sse-server.asd.

Parent Component

sse-server (system).

Packages

sse-server.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 sse-demo

Serves up a web page that will emit events to an
EventSource enabled browser (which is most browsers that aren’t provided by Microsoft).

Source

demo.lisp.

Use List

common-lisp.

Public Interface
Internals

Next: , Previous: , Up: Packages   [Contents][Index]

4.2 sse-server-asd

Source

sse-server.asd.

Use List
  • asdf/interface.
  • common-lisp.

Next: , Previous: , Up: Packages   [Contents][Index]

4.3 sse-server

Functions to send SSE event data to a stream.
‘send-event!‘ sends a fully formed and blank-line terminated event.
‘send-comment‘ sends a comment, and may be generally useful before sending an event, or for debugging

Source

server.lisp.

Use List

common-lisp.

Public Interface
Internals

Previous: , Up: Packages   [Contents][Index]

4.4 sse-demo-asd

Source

sse-demo.asd.

Use List
  • asdf/interface.
  • common-lisp.

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: send-comment! (ostream str)

Write string to the output stream as an SSE comment (which start with ’:’). If the string embeds newlines, send it as multiple comment lines.

Package

sse-server.

Source

server.lisp.

Function: send-event! (ostream event data &key id retry fields)

Write event data to an output stream according to the SSE protocol requirements.

Arguments:
ostream - An output stream to which the event will be written.

;; Specially defined EventSource field names (per the spec)
;; These values are sent with field names matching the parameter name.
event - String naming the event-type.
Note that this has nothing to do with lisp types.
TBD: The spec will allow an event to consist only of data
so not clear this is in our best interest requiring an event (type) property. data - String data to be sent.
id - Optional integer/string sequence value for client lastEventID use.
retry - Optional integer/string specifying millisconds for the event stream’s reconnect time. Frankly I’m not sure about how this works other than it must be taken by the client and will be ignored if it can’t be parsed as an integer.

;; Optional/alternative user defined field names
fields - Optional alist of optional fields to be written as part of the event.
Alist keys represent the (string) field names, and values should be strings.
It is probably an error to have a field nameed ’event-type’.

No values should end in newlines, those are handled
by this function (but a :data value may embedded newlines).

Return value N/A. Signal error if there are any problems writing to ostream.

Package

sse-server.

Source

server.lisp.

Function: start-server (&key port)

Start the web service listening on the indicated port.

Package

sse-demo.

Source

demo.lisp.

Function: stop-server ()
Package

sse-demo.

Source

demo.lisp.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *http-server*
Package

sse-demo.

Source

demo.lisp.

Special Variable: *utf-8*
Package

sse-demo.

Source

demo.lisp.


Previous: , Up: Internals   [Contents][Index]

5.2.2 Ordinary functions

Function: events ()
Package

sse-demo.

Source

demo.lisp.

Function: root ()
Package

sse-demo.

Source

demo.lisp.

Function: send-field! (ostream field-name str)

Write data to ostream as lines of the form ’field-name: str’.
If str contains newlines, split it into pieces and write each line as a ’field-name: str’.

Package

sse-server.

Source

server.lisp.

Function: sse ()
Package

sse-demo.

Source

demo.lisp.

Function: string->sse-data (str)

Given a string containing logical newlines, generate a list of substrings for each line. Note that empty lines are not returned, e.g.:
#"abc\n", "abc" result in one line (note #" readtable dispatch for c-style escapes). #"\n", and "" result zero lines.
#"\n\n" results in zero lines.

CR, LF, and CRLF are treated as line separators.

Package

sse-server.

Source

server.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts