The sse-demo Reference Manual

Table of Contents

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 3.0 "Montgomery Scott" on Wed Oct 13 10:11:18 2021 GMT+0.


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

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.

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

2 Systems

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


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

2.1 sse-demo

Author

Dave Tenny

License

MIT

Description

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

Version

0.1.0

Dependencies
Source

sse-demo.asd (file)

Component

demo.lisp (file)


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

2.2 sse-server

Author

Dave Tenny

License

MIT

Description

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

Version

0.1.0

Dependencies
Source

sse-server.asd (file)

Component

server.lisp (file)


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

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 files   [Contents][Index]

3.1.1 sse-demo.asd

Location

sse-demo.asd

Systems

sse-demo (system)

Packages

sse-demo-asd


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

3.1.2 sse-server.asd

Location

sse-server.asd

Systems

sse-server (system)

Packages

sse-server-asd


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

3.1.3 sse-demo/demo.lisp

Parent

sse-demo (system)

Location

demo.lisp

Packages

sse-demo

Exported Definitions
Internal Definitions

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

3.1.4 sse-server/server.lisp

Parent

sse-server (system)

Location

server.lisp

Packages

sse-server

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 sse-demo-asd

Source

sse-demo.asd

Use List

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

4.2 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 (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

4.3 sse-server-asd

Source

sse-server.asd

Use List

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

4.4 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 (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 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 (file)

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 (file)

Function: start-server &key PORT

Start the web service listening on the indicated port.

Package

sse-demo

Source

demo.lisp (file)

Function: stop-server ()
Package

sse-demo

Source

demo.lisp (file)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *http-server*
Package

sse-demo

Source

demo.lisp (file)

Special Variable: *utf-8*
Package

sse-demo

Source

demo.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: events ()
Package

sse-demo

Source

demo.lisp (file)

Function: root ()
Package

sse-demo

Source

demo.lisp (file)

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 (file)

Function: sse ()
Package

sse-demo

Source

demo.lisp (file)

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 (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, sse-demo.asd: The sse-demo․asd file
File, Lisp, sse-demo/demo.lisp: The sse-demo/demo․lisp file
File, Lisp, sse-server.asd: The sse-server․asd file
File, Lisp, sse-server/server.lisp: The sse-server/server․lisp file

L
Lisp File, sse-demo.asd: The sse-demo․asd file
Lisp File, sse-demo/demo.lisp: The sse-demo/demo․lisp file
Lisp File, sse-server.asd: The sse-server․asd file
Lisp File, sse-server/server.lisp: The sse-server/server․lisp file

S
sse-demo.asd: The sse-demo․asd file
sse-demo/demo.lisp: The sse-demo/demo․lisp file
sse-server.asd: The sse-server․asd file
sse-server/server.lisp: The sse-server/server․lisp file

Jump to:   F   L   S  

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

A.2 Functions

Jump to:   E   F   R   S  
Index Entry  Section

E
events: Internal functions

F
Function, events: Internal functions
Function, root: Internal functions
Function, send-comment!: Exported functions
Function, send-event!: Exported functions
Function, send-field!: Internal functions
Function, sse: Internal functions
Function, start-server: Exported functions
Function, stop-server: Exported functions
Function, string->sse-data: Internal functions

R
root: Internal functions

S
send-comment!: Exported functions
send-event!: Exported functions
send-field!: Internal functions
sse: Internal functions
start-server: Exported functions
stop-server: Exported functions
string->sse-data: Internal functions

Jump to:   E   F   R   S  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*http-server*: Internal special variables
*utf-8*: Internal special variables

S
Special Variable, *http-server*: Internal special variables
Special Variable, *utf-8*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   P   S  
Index Entry  Section

P
Package, sse-demo: The sse-demo package
Package, sse-demo-asd: The sse-demo-asd package
Package, sse-server: The sse-server package
Package, sse-server-asd: The sse-server-asd package

S
sse-demo: The sse-demo system
sse-demo: The sse-demo package
sse-demo-asd: The sse-demo-asd package
sse-server: The sse-server system
sse-server: The sse-server package
sse-server-asd: The sse-server-asd package
System, sse-demo: The sse-demo system
System, sse-server: The sse-server system

Jump to:   P   S