The hunchensocket Reference Manual

This is the hunchensocket Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:43:39 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 hunchensocket

WebSockets for Hunchentoot

Author

capitaomorte

License

MIT

Version

1.0.0

Dependencies
  • hunchentoot (system).
  • alexandria (system).
  • cl-base64 (system).
  • sha1 (system).
  • flexi-streams (system).
  • chunga (system).
  • trivial-utf-8 (system).
  • trivial-backtrace (system).
  • bordeaux-threads (system).
  • cl-fad (system).
Source

hunchensocket.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 hunchensocket/hunchensocket.asd

Source

hunchensocket.asd.

Parent Component

hunchensocket (system).

ASDF Systems

hunchensocket.


3.1.2 hunchensocket/package.lisp

Source

hunchensocket.asd.

Parent Component

hunchensocket (system).

Packages

hunchensocket.


3.1.3 hunchensocket/hunchensocket.lisp

Dependency

package.lisp (file).

Source

hunchensocket.asd.

Parent Component

hunchensocket (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 hunchensocket

Source

package.lisp.

Use List
  • alexandria.
  • bordeaux-threads.
  • cl-ppcre.
  • common-lisp.
  • flexi-streams.
  • hunchentoot.
  • trivial-utf-8.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


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.


5.1.2 Ordinary functions

Function: close-connection (client &key data status reason)
Package

hunchensocket.

Source

hunchensocket.lisp.

Function: send-binary-message (client message)

MESSAGE is an array of octets

Package

hunchensocket.

Source

hunchensocket.lisp.

Function: send-text-message (client message)

MESSAGE is a string

Package

hunchensocket.

Source

hunchensocket.lisp.


5.1.3 Generic functions

Generic Function: binary-message-received (resource client binary)
Package

hunchensocket.

Source

hunchensocket.lisp.

Generic Function: check-message (resource client opcode fragment-length total-length)
Package

hunchensocket.

Source

hunchensocket.lisp.

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.

Methods
Method: client-connected (resource client)
Generic Function: client-disconnected (resource client)
Package

hunchensocket.

Source

hunchensocket.lisp.

Methods
Method: client-disconnected (resource client)
Generic Reader: client-request (object)
Package

hunchensocket.

Methods
Reader Method: client-request ((websocket-client websocket-client))

automatically generated reader method

Source

hunchensocket.lisp.

Target Slot

request.

Generic Reader: clients (object)
Package

hunchensocket.

Methods
Reader Method: clients ((websocket-resource websocket-resource))

automatically generated reader method

Source

hunchensocket.lisp.

Target Slot

clients.

Generic Function: text-message-received (resource client message)
Package

hunchensocket.

Source

hunchensocket.lisp.

Generic Reader: websocket-resource (object)
Generic Writer: (setf websocket-resource) (object)
Package

hunchensocket.

Methods
Reader Method: websocket-resource ((websocket-request websocket-request))
Writer Method: (setf websocket-resource) ((websocket-request websocket-request))

Message handler of the current request

Source

hunchensocket.lisp.

Target Slot

handler.


5.1.4 Standalone methods

Method: acceptor-dispatch-request ((acceptor websocket-acceptor) (request websocket-request))

Attempt WebSocket connection, else fall back to HTTP

Package

hunchentoot.

Source

hunchensocket.lisp.

Method: initialize-instance :after ((resource websocket-resource) &key client-class)
Source

hunchensocket.lisp.

Method: initialize-instance :after ((client websocket-client) &key &allow-other-keys)
Source

hunchensocket.lisp.

Method: initialize-instance :after ((reply websocket-reply) &rest initargs)

Set the reply’s external format to Unix EOL / UTF-8 explicitly.

Source

hunchensocket.lisp.

Method: print-object ((obj websocket-resource) stream)
Source

hunchensocket.lisp.

Method: process-connection :around ((*acceptor* websocket-acceptor) socket)

Sprinkle the current connection with dynamic bindings.

Package

hunchentoot.

Source

hunchensocket.lisp.

Method: process-request :after ((request websocket-request))

After HTTP processing REQUEST, maybe hijack into WebSocket loop.

Package

hunchentoot.

Source

hunchensocket.lisp.


5.1.5 Classes

Class: websocket-acceptor
Package

hunchensocket.

Source

hunchensocket.lisp.

Direct superclasses

acceptor.

Direct subclasses

websocket-ssl-acceptor.

Direct methods
Direct Default Initargs
InitargValue
:request-class(quote websocket-request)
:reply-class(quote websocket-reply)
Direct slots
Slot: websocket-timeout

Custom WebSocket timeout override.

Initform

300

Initargs

:websocket-timeout

Readers

websocket-timeout.

Writers

(setf websocket-timeout).

Class: websocket-client
Package

hunchensocket.

Source

hunchensocket.lisp.

Direct methods
Direct slots
Slot: input-stream
Initform

(error "must make clients with input streams")

Initargs

hunchensocket::input-stream

Slot: output-stream
Initform

(error "must make clients with output streams")

Initargs

hunchensocket::output-stream

Slot: request
Package

hunchentoot.

Initform

(error "must make clients with requests")

Initargs

hunchentoot:request

Readers

client-request.

Writers

This slot is read-only.

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.

Direct methods
Direct slots
Slot: clients
Readers

clients.

Writers

This slot is read-only.

Slot: client-class
Initform

(quote hunchensocket:websocket-client)

Initargs

:client-class

Slot: lock
Package

bordeaux-threads.

Initform

(bordeaux-threads:make-lock)

Class: websocket-ssl-acceptor

Special WebSocket SSL acceptor

Package

hunchensocket.

Source

hunchensocket.lisp.

Direct superclasses

5.2 Internals


5.2.1 Constants

Constant: +binary-frame+
Package

hunchensocket.

Source

hunchensocket.lisp.

Constant: +connection-close+
Package

hunchensocket.

Source

hunchensocket.lisp.

Constant: +continuation-frame+
Package

hunchensocket.

Source

hunchensocket.lisp.

Constant: +ping+
Package

hunchensocket.

Source

hunchensocket.lisp.

Constant: +pong+
Package

hunchensocket.

Source

hunchensocket.lisp.

Constant: +text-frame+
Package

hunchensocket.

Source

hunchensocket.lisp.

Constant: +websocket-magic-key+

Fixed magic WebSocket UUIDv4 key use in handshakes

Package

hunchensocket.

Source

hunchensocket.lisp.


5.2.2 Special variables

Special Variable: *websocket-socket*

The currently active WebSocket socket

Package

hunchensocket.

Source

hunchensocket.lisp.


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.


5.2.4 Ordinary functions

Function: call-with-new-client-for-resource (client resource fn)
Package

hunchensocket.

Source

hunchensocket.lisp.

Function: control-frame-p (opcode)
Package

hunchensocket.

Source

hunchensocket.lisp.

Function: find-websocket-resource (request)

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

Package

hunchensocket.

Source

hunchensocket.lisp.

Function: handle-frame (resource client frame)
Package

hunchensocket.

Source

hunchensocket.lisp.

Function: mask-unmask (data masking-key)
Package

hunchensocket.

Source

hunchensocket.lisp.

Function: read-application-data (stream frame)
Package

hunchensocket.

Source

hunchensocket.lisp.

Function: read-frame (stream &key read-payload-p)
Package

hunchensocket.

Source

hunchensocket.lisp.

Function: read-frame-from-client (client)

Read a text or binary message from CLIENT.

Package

hunchensocket.

Source

hunchensocket.lisp.

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.

Function: read-n-bytes-into-sequence (stream n)

Return an array of N bytes read from stream

Package

hunchensocket.

Source

hunchensocket.lisp.

Function: read-unsigned-big-endian (stream n)

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

Package

hunchensocket.

Source

hunchensocket.lisp.

Function: send-frame (client opcode data)
Package

hunchensocket.

Source

hunchensocket.lisp.

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.

Function: websocket-uri (request host &optional ssl)

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

Package

hunchensocket.

Source

hunchensocket.lisp.

Function: write-frame (stream opcode &optional data)
Package

hunchensocket.

Source

hunchensocket.lisp.


5.2.5 Generic functions

Generic Reader: frame-data (object)
Package

hunchensocket.

Methods
Reader Method: frame-data ((frame frame))

automatically generated reader method

Source

hunchensocket.lisp.

Target Slot

data.

Generic Writer: (setf frame-data) (object)
Package

hunchensocket.

Methods
Writer Method: (setf frame-data) ((frame frame))

automatically generated writer method

Source

hunchensocket.lisp.

Target Slot

data.

Generic Reader: frame-opcode (object)
Package

hunchensocket.

Methods
Reader Method: frame-opcode ((frame frame))

automatically generated reader method

Source

hunchensocket.lisp.

Target Slot

opcode.

Generic Writer: (setf frame-opcode) (object)
Package

hunchensocket.

Methods
Writer Method: (setf frame-opcode) ((frame frame))

automatically generated writer method

Source

hunchensocket.lisp.

Target Slot

opcode.

Generic Reader: frame-payload-length (object)
Package

hunchensocket.

Methods
Reader Method: frame-payload-length ((frame frame))

automatically generated reader method

Source

hunchensocket.lisp.

Target Slot

payload-length.

Generic Writer: (setf frame-payload-length) (object)
Package

hunchensocket.

Methods
Writer Method: (setf frame-payload-length) ((frame frame))

automatically generated writer method

Source

hunchensocket.lisp.

Target Slot

payload-length.

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.

Generic Reader: websocket-error-status (condition)
Package

hunchensocket.

Methods
Reader Method: websocket-error-status ((condition websocket-error))
Source

hunchensocket.lisp.

Target Slot

error-status.

Generic Reader: websocket-timeout (object)
Generic Writer: (setf websocket-timeout) (object)
Package

hunchensocket.

Methods
Reader Method: websocket-timeout ((websocket-acceptor websocket-acceptor))
Writer Method: (setf websocket-timeout) ((websocket-acceptor websocket-acceptor))

Custom WebSocket timeout override.

Source

hunchensocket.lisp.

Target Slot

websocket-timeout.


5.2.6 Conditions

Condition: websocket-error

Superclass for all errors related to Websocket.

Package

hunchensocket.

Source

hunchensocket.lisp.

Direct superclasses

simple-error.

Direct methods

websocket-error-status.

Direct slots
Slot: error-status
Initargs

:status

Readers

websocket-error-status.

Writers

This slot is read-only.


5.2.7 Classes

Class: frame
Package

hunchensocket.

Source

hunchensocket.lisp.

Direct methods
Direct slots
Slot: opcode
Initargs

:opcode

Readers

frame-opcode.

Writers

(setf frame-opcode).

Slot: data
Readers

frame-data.

Writers

(setf frame-data).

Slot: finp
Initargs

:finp

Slot: payload-length
Initargs

:payload-length

Readers

frame-payload-length.

Writers

(setf frame-payload-length).

Slot: masking-key
Initargs

:masking-key

Class: websocket-reply
Package

hunchensocket.

Source

hunchensocket.lisp.

Direct superclasses

reply.

Direct methods

initialize-instance.

Class: websocket-request
Package

hunchensocket.

Source

hunchensocket.lisp.

Direct superclasses

request.

Direct methods
Direct slots
Slot: handler

Message handler of the current request

Readers

websocket-resource.

Writers

(setf websocket-resource).


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   B   C   F   G   H   I   M   P   R   S   T   W  
Index Entry  Section

(
(setf frame-data): Private generic functions
(setf frame-data): Private generic functions
(setf frame-opcode): Private generic functions
(setf frame-opcode): Private generic functions
(setf frame-payload-length): Private generic functions
(setf frame-payload-length): Private generic functions
(setf websocket-resource): Public generic functions
(setf websocket-resource): Public generic functions
(setf websocket-timeout): Private generic functions
(setf websocket-timeout): Private generic functions

A
acceptor-dispatch-request: Public standalone methods

B
binary-message-received: Public generic functions

C
call-with-new-client-for-resource: Private ordinary functions
check-message: Public generic functions
check-message: Public generic functions
check-message: Public generic functions
client-connected: Public generic functions
client-connected: Public generic functions
client-disconnected: Public generic functions
client-disconnected: Public generic functions
client-request: Public generic functions
client-request: Public generic functions
clients: Public generic functions
clients: Public generic functions
close-connection: Public ordinary functions
control-frame-p: Private ordinary functions

F
find-websocket-resource: Private ordinary functions
frame-data: Private generic functions
frame-data: Private generic functions
frame-opcode: Private generic functions
frame-opcode: Private generic functions
frame-payload-length: Private generic functions
frame-payload-length: Private generic functions
Function, call-with-new-client-for-resource: Private ordinary functions
Function, close-connection: Public ordinary functions
Function, control-frame-p: Private ordinary functions
Function, find-websocket-resource: Private ordinary functions
Function, handle-frame: Private ordinary functions
Function, mask-unmask: Private ordinary functions
Function, read-application-data: Private ordinary functions
Function, read-frame: Private ordinary functions
Function, read-frame-from-client: Private ordinary functions
Function, read-handle-loop: Private ordinary functions
Function, read-n-bytes-into-sequence: Private ordinary functions
Function, read-unsigned-big-endian: Private ordinary functions
Function, send-binary-message: Public ordinary functions
Function, send-frame: Private ordinary functions
Function, send-text-message: Public ordinary functions
Function, websocket-error: Private ordinary functions
Function, websocket-uri: Private ordinary functions
Function, write-frame: Private ordinary functions

G
Generic Function, (setf frame-data): Private generic functions
Generic Function, (setf frame-opcode): Private generic functions
Generic Function, (setf frame-payload-length): Private generic functions
Generic Function, (setf websocket-resource): Public generic functions
Generic Function, (setf websocket-timeout): Private generic functions
Generic Function, binary-message-received: Public generic functions
Generic Function, check-message: Public generic functions
Generic Function, client-connected: Public generic functions
Generic Function, client-disconnected: Public generic functions
Generic Function, client-request: Public generic functions
Generic Function, clients: Public generic functions
Generic Function, frame-data: Private generic functions
Generic Function, frame-opcode: Private generic functions
Generic Function, frame-payload-length: Private generic functions
Generic Function, handle-handshake: Private generic functions
Generic Function, text-message-received: Public generic functions
Generic Function, websocket-error-status: Private generic functions
Generic Function, websocket-resource: Public generic functions
Generic Function, websocket-timeout: Private generic functions

H
handle-frame: Private ordinary functions
handle-handshake: Private generic functions
handle-handshake: Private generic functions

I
initialize-instance: Public standalone methods
initialize-instance: Public standalone methods
initialize-instance: Public standalone methods

M
Macro, with-new-client-for-resource: Private macros
mask-unmask: Private ordinary functions
Method, (setf frame-data): Private generic functions
Method, (setf frame-opcode): Private generic functions
Method, (setf frame-payload-length): Private generic functions
Method, (setf websocket-resource): Public generic functions
Method, (setf websocket-timeout): Private generic functions
Method, acceptor-dispatch-request: Public standalone methods
Method, check-message: Public generic functions
Method, check-message: Public generic functions
Method, client-connected: Public generic functions
Method, client-disconnected: Public generic functions
Method, client-request: Public generic functions
Method, clients: Public generic functions
Method, frame-data: Private generic functions
Method, frame-opcode: Private generic functions
Method, frame-payload-length: Private generic functions
Method, handle-handshake: Private generic functions
Method, initialize-instance: Public standalone methods
Method, initialize-instance: Public standalone methods
Method, initialize-instance: Public standalone methods
Method, print-object: Public standalone methods
Method, process-connection: Public standalone methods
Method, process-request: Public standalone methods
Method, websocket-error-status: Private generic functions
Method, websocket-resource: Public generic functions
Method, websocket-timeout: Private generic functions

P
print-object: Public standalone methods
process-connection: Public standalone methods
process-request: Public standalone methods

R
read-application-data: Private ordinary functions
read-frame: Private ordinary functions
read-frame-from-client: Private ordinary functions
read-handle-loop: Private ordinary functions
read-n-bytes-into-sequence: Private ordinary functions
read-unsigned-big-endian: Private ordinary functions

S
send-binary-message: Public ordinary functions
send-frame: Private ordinary functions
send-text-message: Public ordinary functions

T
text-message-received: Public generic functions

W
websocket-error: Private ordinary functions
websocket-error-status: Private generic functions
websocket-error-status: Private generic functions
websocket-resource: Public generic functions
websocket-resource: Public generic functions
websocket-timeout: Private generic functions
websocket-timeout: Private generic functions
websocket-uri: Private ordinary functions
with-new-client-for-resource: Private macros
write-frame: Private ordinary functions


A.3 Variables

Jump to:   *   +  
C   D   E   F   H   I   L   M   O   P   R   S   W  
Index Entry  Section

*
*websocket-dispatch-table*: Public special variables
*websocket-socket*: Private special variables

+
+binary-frame+: Private constants
+connection-close+: Private constants
+continuation-frame+: Private constants
+ping+: Private constants
+pong+: Private constants
+text-frame+: Private constants
+websocket-magic-key+: Private constants

C
client-class: Public classes
clients: Public classes
Constant, +binary-frame+: Private constants
Constant, +connection-close+: Private constants
Constant, +continuation-frame+: Private constants
Constant, +ping+: Private constants
Constant, +pong+: Private constants
Constant, +text-frame+: Private constants
Constant, +websocket-magic-key+: Private constants

D
data: Private classes

E
error-status: Private conditions

F
finp: Private classes

H
handler: Private classes

I
input-stream: Public classes

L
lock: Public classes

M
masking-key: Private classes

O
opcode: Private classes
output-stream: Public classes

P
payload-length: Private classes
pending-fragments: Public classes
pending-opcode: Public classes

R
request: Public classes

S
Slot, client-class: Public classes
Slot, clients: Public classes
Slot, data: Private classes
Slot, error-status: Private conditions
Slot, finp: Private classes
Slot, handler: Private classes
Slot, input-stream: Public classes
Slot, lock: Public classes
Slot, masking-key: Private classes
Slot, opcode: Private classes
Slot, output-stream: Public classes
Slot, payload-length: Private classes
Slot, pending-fragments: Public classes
Slot, pending-opcode: Public classes
Slot, request: Public classes
Slot, state: Public classes
Slot, websocket-timeout: Public classes
Slot, write-lock: Public classes
Special Variable, *websocket-dispatch-table*: Public special variables
Special Variable, *websocket-socket*: Private special variables
state: Public classes

W
websocket-timeout: Public classes
write-lock: Public classes