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 Sat Dec 03 20:41:59 2022 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


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).


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.


3.1 Lisp


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

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.


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

4.2 sse-server-asd

Source

sse-server.asd.

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

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

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.


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


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.


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


A.1 Concepts