The hunchensocket Reference Manual

Table of Contents

The hunchensocket Reference Manual

This is the hunchensocket Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 16:26:07 2021 GMT+0.

1 Introduction

Hunchensocket - WebSockets for Hunchentoot

Hunchensocket is a Common Lisp implementation of WebSockets realized as an extension to [Edi Weitz'] edi excellent Hunchentoot web server. Hunchensocket implements a compliant RFC6455 server.

Note that Alexander Kahl, the original author, has desactivated his old version that only supports the drafts of the protocol.

Installation

Hunchensocket is in Quicklisp, so if you have that setup just do (ql:quickload :hunchensocket).

Quicklisp is also good to use the trunk alongside with other dependencies, perhaps to test a new feature or a bugfix:

$ cd ~/Source/Lisp/
$ git clone https://github.com/joaotavora/hunchensocket.git

(push "~/Source/Lisp" ql:*local-project-directories*)
(ql:quickload :hunchensocket) ;; use local hunchensocket and pull
                              ;; dependencies from quicklisp

A chat server in 30 lines

First define classes for rooms and users. Make these subclasses of websocket-resource and websocket-client.

(defpackage :my-chat (:use :cl))
(in-package :my-chat)

(defclass chat-room (hunchensocket:websocket-resource)
  ((name :initarg :name :initform (error "Name this room!") :reader name))
  (:default-initargs :client-class 'user))

(defclass user (hunchensocket:websocket-client)
  ((name :initarg :user-agent :reader name :initform (error "Name this user!"))))

Define a list of rooms. Notice that hunchensocket:*websocket-dispatch-table* works just like hunchentoot:*dispatch-table*, but for websocket specific resources.

(defvar *chat-rooms* (list (make-instance 'chat-room :name "/bongo")
                           (make-instance 'chat-room :name "/fury")))

(defun find-room (request)
  (find (hunchentoot:script-name request) *chat-rooms* :test #'string= :key #'name))

(pushnew 'find-room hunchensocket:*websocket-dispatch-table*)

OK, now a helper function and the dynamics of a chat room.

(defun broadcast (room message &rest args)
  (loop for peer in (hunchensocket:clients room)
        do (hunchensocket:send-text-message peer (apply #'format nil message args))))

(defmethod hunchensocket:client-connected ((room chat-room) user)
  (broadcast room "~a has joined ~a" (name user) (name room)))

(defmethod hunchensocket:client-disconnected ((room chat-room) user)
  (broadcast room "~a has left ~a" (name user) (name room)))

(defmethod hunchensocket:text-message-received ((room chat-room) user message)
  (broadcast room "~a says ~a" (name user) message))  

Finally, start the server. hunchensocket:websocket-acceptor works just like hunchentoot:acceptor, and you can probably also use hunchensocket:websocket-ssl-acceptor.

(defvar *server* (make-instance 'hunchensocket:websocket-acceptor :port 12345))
(hunchentoot:start *server*)

Now open two browser windows on http://www.websocket.org/echo.html, enter ws://localhost:12345/bongo as the host and play around chatting with yourself.

License

See COPYING for license details.

Design

Main sources of inspiration:

• Original implementation by Alexander Kahl, which cleverly hijacks the Hunchentoot connection after the HTTP response and keeps the connection alive, just like in a Head request.
• clws's API because it explicitly defines websocket "resources"
• Hunchentoot's's API because it uses CLOS

2 Systems

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

2.1 hunchensocket

Author

capitaomorte

License

MIT

Description

WebSockets for Hunchentoot

Version

1.0.0

Dependencies

• hunchentoot
• alexandria
• ironclad
• flexi-streams
• chunga
• trivial-utf-8
• trivial-backtrace
• bordeaux-threads
• cl-fad

Source

hunchensocket.asd (file)

Components

• package.lisp (file)
• hunchensocket.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 hunchensocket.asd

Location

hunchensocket.asd

Systems

hunchensocket (system)

3.1.2 hunchensocket/package.lisp

Parent

hunchensocket (system)

Location

package.lisp

Packages

hunchensocket

3.1.3 hunchensocket/hunchensocket.lisp

Dependency

package.lisp (file)

Parent

hunchensocket (system)

Location

hunchensocket.lisp

Exported Definitions

• *websocket-dispatch-table* (special variable)
• binary-message-received (generic function)
• check-message (generic function)
• check-message (method)
• check-message (method)
• client-connected (generic function)
• client-connected (method)
• client-disconnected (generic function)
• client-disconnected (method)
• client-request (method)
• clients (method)
• close-connection (function)
• send-binary-message (function)
• send-text-message (function)
• text-message-received (generic function)
• websocket-acceptor (class)
• websocket-client (class)
• websocket-resource (method)
• (setf websocket-resource) (method)
• websocket-resource (class)
• websocket-ssl-acceptor (class)

Internal Definitions

• *websocket-socket* (special variable)
• +binary-frame+ (constant)
• +connection-close+ (constant)
• +continuation-frame+ (constant)
• +ping+ (constant)
• +pong+ (constant)
• +text-frame+ (constant)
• +websocket-magic-key+ (constant)
• call-with-new-client-for-resource (function)
• control-frame-p (function)
• find-websocket-resource (function)
• frame (class)
• frame-data (method)
• (setf frame-data) (method)
• frame-opcode (method)
• (setf frame-opcode) (method)
• frame-payload-length (method)
• (setf frame-payload-length) (method)
• handle-frame (function)
• handle-handshake (method)
• mask-unmask (function)
• read-application-data (function)
• read-frame (function)
• read-frame-from-client (function)
• read-handle-loop (function)
• read-n-bytes-into-sequence (function)
• read-unsigned-big-endian (function)
• send-frame (function)
• websocket-error (function)
• websocket-error (condition)
• websocket-error-status (method)
• websocket-reply (class)
• websocket-request (class)
• websocket-timeout (method)
• (setf websocket-timeout) (method)
• websocket-uri (function)
• with-new-client-for-resource (macro)
• write-frame (function)

4 Packages

Packages are listed by definition order.

4.1 hunchensocket

Source

package.lisp (file)

Use List

• bordeaux-threads
• trivial-utf-8
• flexi-streams
• cl-ppcre
• hunchentoot
• alexandria
• common-lisp

Exported Definitions

• *websocket-dispatch-table* (special variable)
• binary-message-received (generic function)
• check-message (generic function)
• check-message (method)
• check-message (method)
• client-connected (generic function)
• client-connected (method)
• client-disconnected (generic function)
• client-disconnected (method)
• client-request (generic function)
• client-request (method)
• clients (generic function)
• clients (method)
• close-connection (function)
• send-binary-message (function)
• send-text-message (function)
• text-message-received (generic function)
• websocket-acceptor (class)
• websocket-client (class)
• websocket-resource (generic function)
• websocket-resource (method)
• (setf websocket-resource) (method)
• (setf websocket-resource) (generic function)
• websocket-resource (class)
• websocket-ssl-acceptor (class)

Internal Definitions

• *websocket-socket* (special variable)
• +binary-frame+ (constant)
• +connection-close+ (constant)
• +continuation-frame+ (constant)
• +ping+ (constant)
• +pong+ (constant)
• +text-frame+ (constant)
• +websocket-magic-key+ (constant)
• call-with-new-client-for-resource (function)
• control-frame-p (function)
• find-websocket-resource (function)
• frame (class)
• frame-data (generic function)
• frame-data (method)
• (setf frame-data) (method)
• (setf frame-data) (generic function)
• frame-opcode (generic function)
• frame-opcode (method)
• (setf frame-opcode) (method)
• (setf frame-opcode) (generic function)
• frame-payload-length (generic function)
• frame-payload-length (method)
• (setf frame-payload-length) (method)
• (setf frame-payload-length) (generic function)
• handle-frame (function)
• handle-handshake (generic function)
• handle-handshake (method)
• mask-unmask (function)
• read-application-data (function)
• read-frame (function)
• read-frame-from-client (function)
• read-handle-loop (function)
• read-n-bytes-into-sequence (function)
• read-unsigned-big-endian (function)
• send-frame (function)
• websocket-error (function)
• websocket-error (condition)
• websocket-error-status (generic function)
• websocket-error-status (method)
• websocket-reply (class)
• websocket-request (class)
• websocket-timeout (generic function)
• websocket-timeout (method)
• (setf websocket-timeout) (method)
• (setf websocket-timeout) (generic function)
• websocket-uri (function)
• with-new-client-for-resource (macro)
• write-frame (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *websocket-dispatch-table*

List of handler closures that will be queried for new connections

Package

hunchensocket

Source

hunchensocket.lisp (file)

5.1.2 Functions

Function: close-connection CLIENT &key DATA STATUS REASON

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: send-binary-message CLIENT MESSAGE

MESSAGE is an array of octets

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: send-text-message CLIENT MESSAGE

MESSAGE is a string

Package

hunchensocket

Source

hunchensocket.lisp (file)

5.1.3 Generic functions

Generic Function: binary-message-received RESOURCE CLIENT BINARY

Package

hunchensocket

Source

hunchensocket.lisp (file)

Generic Function: check-message RESOURCE CLIENT OPCODE FRAGMENT-LENGTH TOTAL-LENGTH

Package

hunchensocket

Source

hunchensocket.lisp (file)

Methods

Method: check-message (RESOURCE websocket-resource) (CLIENT websocket-client) OPCODE LENGTH TOTAL

Method: check-message (RESOURCE websocket-resource) (CLIENT websocket-client) (OPCODE (eql 2)) LENGTH TOTAL

Generic Function: client-connected RESOURCE CLIENT

Package

hunchensocket

Source

hunchensocket.lisp (file)

Methods

Method: client-connected RESOURCE CLIENT

Generic Function: client-disconnected RESOURCE CLIENT

Package

hunchensocket

Source

hunchensocket.lisp (file)

Methods

Method: client-disconnected RESOURCE CLIENT

Generic Function: client-request OBJECT

Package

hunchensocket

Methods

Method: client-request (WEBSOCKET-CLIENT websocket-client)

automatically generated reader method

Source

hunchensocket.lisp (file)

Generic Function: clients OBJECT

Package

hunchensocket

Methods

Method: clients (WEBSOCKET-RESOURCE websocket-resource)

automatically generated reader method

Source

hunchensocket.lisp (file)

Generic Function: text-message-received RESOURCE CLIENT MESSAGE

Package

hunchensocket

Source

hunchensocket.lisp (file)

Generic Function: websocket-resource OBJECT

Generic Function: (setf websocket-resource) NEW-VALUE OBJECT

Package

hunchensocket

Methods

Method: websocket-resource (WEBSOCKET-REQUEST websocket-request)

Method: (setf websocket-resource) NEW-VALUE (WEBSOCKET-REQUEST websocket-request)

Message handler of the current request

Source

hunchensocket.lisp (file)

5.1.4 Classes

Class: websocket-acceptor ()

Package

hunchensocket

Source

hunchensocket.lisp (file)

Direct superclasses

acceptor (class)

Direct subclasses

websocket-ssl-acceptor (class)

Direct methods

• acceptor-dispatch-request (method)
• handle-handshake (method)
• process-connection (method)
• websocket-timeout (method)
• websocket-timeout (method)

Direct slots

Slot: websocket-timeout

Custom WebSocket timeout override.

Initargs

:websocket-timeout

Initform

300

Readers

websocket-timeout (generic function)

Writers

(setf websocket-timeout) (generic function)

Direct Default Initargs

Initarg	Value
:request-class	(quote hunchensocket::websocket-request)
:reply-class	(quote hunchensocket::websocket-reply)

Class: websocket-client ()

Package

hunchensocket

Source

hunchensocket.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• check-message (method)
• check-message (method)
• initialize-instance (method)
• client-request (method)

Direct slots

Slot: input-stream

Initargs

hunchensocket::input-stream

Initform

(error "must make clients with input streams")

Slot: output-stream

Initargs

hunchensocket::output-stream

Initform

(error "must make clients with output streams")

Slot: request

Initargs

hunchentoot:request

Initform

(error "must make clients with requests")

Readers

client-request (generic function)

Slot: write-lock

Initform

(bordeaux-threads:make-lock)

Slot: state

Initform

:disconnected

Slot: pending-fragments

Slot: pending-opcode

Class: websocket-resource ()

Package

hunchensocket

Source

hunchensocket.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• initialize-instance (method)
• check-message (method)
• check-message (method)
• print-object (method)
• clients (method)

Direct slots

Slot: clients

Readers

clients (generic function)

Slot: client-class

Initargs

:client-class

Initform

(quote hunchensocket:websocket-client)

Slot: lock

Initform

(bordeaux-threads:make-lock)

Class: websocket-ssl-acceptor ()

Special WebSocket SSL acceptor

Package

hunchensocket

Source

hunchensocket.lisp (file)

Direct superclasses

• ssl-acceptor (class)
• websocket-acceptor (class)

5.2 Internal definitions

5.2.1 Constants

Constant: +binary-frame+

Package

hunchensocket

Source

hunchensocket.lisp (file)

Constant: +connection-close+

Package

hunchensocket

Source

hunchensocket.lisp (file)

Constant: +continuation-frame+

Package

hunchensocket

Source

hunchensocket.lisp (file)

Constant: +ping+

Package

hunchensocket

Source

hunchensocket.lisp (file)

Constant: +pong+

Package

hunchensocket

Source

hunchensocket.lisp (file)

Constant: +text-frame+

Package

hunchensocket

Source

hunchensocket.lisp (file)

Constant: +websocket-magic-key+

Fixed magic WebSocket UUIDv4 key use in handshakes

Package

hunchensocket

Source

hunchensocket.lisp (file)

5.2.2 Special variables

Special Variable: *websocket-socket*

The currently active WebSocket socket

Package

hunchensocket

Source

hunchensocket.lisp (file)

5.2.3 Macros

Macro: with-new-client-for-resource (CLIENT-SYM &key INPUT-STREAM OUTPUT-STREAM RESOURCE REQUEST) &body BODY

Package

hunchensocket

Source

hunchensocket.lisp (file)

5.2.4 Functions

Function: call-with-new-client-for-resource CLIENT RESOURCE FN

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: control-frame-p OPCODE

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: find-websocket-resource REQUEST

Find the resource for REQUEST by looking up *WEBSOCKET-DISPATCH-TABLE*.

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: handle-frame RESOURCE CLIENT FRAME

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: mask-unmask DATA MASKING-KEY

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: read-application-data STREAM FRAME

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: read-frame STREAM &key READ-PAYLOAD-P

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: read-frame-from-client CLIENT

Read a text or binary message from CLIENT.

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: read-handle-loop RESOURCE CLIENT &optional VERSION

Implements the main WebSocket loop for supported protocol versions. Framing is handled automatically, CLIENT handles the actual payloads.

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: read-n-bytes-into-sequence STREAM N

Return an array of N bytes read from stream

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: read-unsigned-big-endian STREAM N

Read N bytes from stream and return the big-endian number

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: send-frame CLIENT OPCODE DATA

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: websocket-error STATUS FORMAT-CONTROL &rest FORMAT-ARGUMENTS

Signals an error of type HUNCHENTOOT-SIMPLE-ERROR with the provided format control and arguments.

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: websocket-uri REQUEST HOST &optional SSL

Form WebSocket URL (ws:// or wss://) URL.

Package

hunchensocket

Source

hunchensocket.lisp (file)

Function: write-frame STREAM OPCODE &optional DATA

Package

hunchensocket

Source

hunchensocket.lisp (file)

5.2.5 Generic functions

Generic Function: frame-data OBJECT

Generic Function: (setf frame-data) NEW-VALUE OBJECT

Package

hunchensocket

Methods

Method: frame-data (FRAME frame)

automatically generated reader method

Source

hunchensocket.lisp (file)

Method: (setf frame-data) NEW-VALUE (FRAME frame)

automatically generated writer method

Source

hunchensocket.lisp (file)

Generic Function: frame-opcode OBJECT

Generic Function: (setf frame-opcode) NEW-VALUE OBJECT

Package

hunchensocket

Methods

Method: frame-opcode (FRAME frame)

automatically generated reader method

Source

hunchensocket.lisp (file)

Method: (setf frame-opcode) NEW-VALUE (FRAME frame)

automatically generated writer method

Source

hunchensocket.lisp (file)

Generic Function: frame-payload-length OBJECT

Generic Function: (setf frame-payload-length) NEW-VALUE OBJECT

Package

hunchensocket

Methods

Method: frame-payload-length (FRAME frame)

automatically generated reader method

Source

hunchensocket.lisp (file)

Method: (setf frame-payload-length) NEW-VALUE (FRAME frame)

automatically generated writer method

Source

hunchensocket.lisp (file)

Generic Function: handle-handshake ACCEPTOR REQUEST REPLY

Package

hunchensocket

Methods

Method: handle-handshake (ACCEPTOR websocket-acceptor) REQUEST REPLY

Analyse REQUEST for WebSocket handshake.

Destructively modify REPLY accordingly in case of success, exit non-locally with an error instead.

Source

hunchensocket.lisp (file)

Generic Function: websocket-error-status CONDITION

Package

hunchensocket

Methods

Method: websocket-error-status (CONDITION websocket-error)

Source

hunchensocket.lisp (file)

Generic Function: websocket-timeout OBJECT

Generic Function: (setf websocket-timeout) NEW-VALUE OBJECT

Package

hunchensocket

Methods

Method: websocket-timeout (WEBSOCKET-ACCEPTOR websocket-acceptor)

Method: (setf websocket-timeout) NEW-VALUE (WEBSOCKET-ACCEPTOR websocket-acceptor)

Custom WebSocket timeout override.

Source

hunchensocket.lisp (file)

5.2.6 Conditions

Condition: websocket-error ()

Superclass for all errors related to Websocket.

Package

hunchensocket

Source

hunchensocket.lisp (file)

Direct superclasses

simple-error (condition)

Direct methods

websocket-error-status (method)

Direct slots

Slot: error-status

Initargs

:status

Readers

websocket-error-status (generic function)

5.2.7 Classes

Class: frame ()

Package

hunchensocket

Source

hunchensocket.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• frame-payload-length (method)
• frame-payload-length (method)
• frame-data (method)
• frame-data (method)
• frame-opcode (method)
• frame-opcode (method)

Direct slots

Slot: opcode

Initargs

:opcode

Readers

frame-opcode (generic function)

Writers

(setf frame-opcode) (generic function)

Slot: data

Readers

frame-data (generic function)

Writers

(setf frame-data) (generic function)

Slot: finp

Initargs

:finp

Slot: payload-length

Initargs

:payload-length

Readers

frame-payload-length (generic function)

Writers

(setf frame-payload-length) (generic function)

Slot: masking-key

Initargs

:masking-key

Class: websocket-reply ()

Package

hunchensocket

Source

hunchensocket.lisp (file)

Direct superclasses

reply (class)

Direct methods

initialize-instance (method)

Class: websocket-request ()

Package

hunchensocket

Source

hunchensocket.lisp (file)

Direct superclasses

request (class)

Direct methods

• acceptor-dispatch-request (method)
• process-request (method)
• websocket-resource (method)
• websocket-resource (method)

Direct slots

Slot: handler

Message handler of the current request

Readers

websocket-resource (generic function)

Writers

(setf websocket-resource) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types