You are looking at historical revision 31611 of this page. It may differ significantly from its current revision.

websockets

Description

websockets is a fast, lightweight, and simple implementation of the websockets protocol. It currently only supports version 13 and no extensions.

websockets provides both a high level and low level API. The high level API provides both a blocking and concurrent interface. Note that contrary to most or even all other websocket implementations it does not provide an asynchronous interface but it however provide a concurrent backed interface. See the section on the high level interface for more details. The low level API provides all of the primitives for working directly with websocket connections, messages, and fragments. It can be used for special circumstances, like when more fine grained control is desired for accepting or processing fragments, or for building a different high level API. The provided high level API is based on the exposed low level API.

Repository

The git repository for the websockets source code is hosted by bitbucket: https://bitbucket.org/thomashintz/websockets.

Requirements

The following eggs are required:

• spiffy
• intarweb
• uri-common
• base64
• simple-sha1
• srfi-18
• srfi-13
• mailbox

Parameters

ping-interval

[parameter] (ping-interval [number])

How often to ping the client in the background. If 0 then automatic pinging will be disabled. This defaults to 15 seconds.

close-timeout

[parameter] (close-timeout [number])

How long to wait for the client to respond to a connection close request before timing out. If 0 then the connection timeout will be disabled. The default value is 5 seconds.

connection-timeout

[parameter] (connection-timeout [number])

The length of time without a response (of any kind) from the client before the connection to the client will be cut off. If 0 then the connection will never be timed out by the websocket (something else can, of course, timeout causing the websocket connection to fail anyways).

accept-connection

[parameter] (accept-connection [procedure])

A one-argument (URL path of the current page) procedure which tells whether to accept the websocket connection. If #t accept, #f reject. IT IS HIGHLY RECOMMENDED that this parameter be set otherwise it opens up your application to potential security vulnerabilities. You will probably want to verify it is coming from a specific source. The default is to accept all connections.

access-denied

[parameter] (access-denied [procedure])

A procedure to be called when the origin header value is rejected by the accept-connection procedure.

The default is:

(lambda () (send-status 'forbidden "<h1>Access denied</h1>"))

drop-incoming-pings

[parameter] (drop-incoming-pings [boolean])

Clients should usually not initiate pings so the default is to drop all incoming pings without responding with a pong. This defaults to #t. Set this to #f to respond to incoming pings with a pong.

propagate-common-errors

[parameter] (propagate-common-errors [boolean])

A lot of errors that occur in the lifecycle of a websocket connection are more-or-less expected and it often is not interesting to receive and deal with these errors. The default is to correctly close the connection when an error occurs with the required opcode but the error is then not signaled to the user. The default is #f. Set to #t to receive all errors.

All websocket specific errors are covered by this. The only error you may receive if this is #f is of type websocket and unexpected-error either when things go terribly wrong in the implementation or an error is triggered in user code. <a name="high-level"></a> Note that this parameter is only relevant when using with-websocket or with-concurrent-websocket. If you don't use one of those then all errors will be propagated.

max-frame-size

[parameter] (max-frame-size [number])

The maximum allowed frame payload size. The default is 1MiB. If a frame exceeds this size then its payload will not be read and the connection will be dropped immediately. This signals a message-too-large error.

The maximum frame size supported by websockets is 1GiB.

max-message-size

[parameter] (max-message-size [number])

The maximum allowed total message size. The default is 1MiB. If a frame will cause the max-message-size to be exceeded then its payload is not read and the connection is dropped immediately. This signals a message-too-large error.

The maximum message size supported by websockets is 1GiB.