▼Net:   Networking Libraries
►3 Web  Socket
On this page:
3.1 Client API
ws-url?
wss-url?
ws-connect
3.2 Server API
ws-serve
3.3 Connections
framing-mode
ws-conn?
open-ws-conn?
ws-conn-line
ws-conn-closed?
ws-conn-headers
ws-send!
ws-recv
ws-close!
3.4 Example
  top  ← prev  up  next → 

3 WebSocket

 (require net/websocket)

The net/websocket library provides utilities to run and communicate with WebSocket servers, as specified in the WebSocket protocol IETF draft as of August 16th, 2010.

This module provides the exports from net/websocket/client and net/websocket/server.

3.1 Client API

 (require net/websocket/client)

procedure

(ws-url? x) → boolean?

  x : any/c
Returns true if x is a url? and has a url-scheme equal to ws or wss.

procedure

(wss-url? x) → boolean?

  x : any/c
Returns true if x is a url? and has a url-scheme equal to wss.

procedure

(ws-connect u [#:headers headers]) → open-ws-conn?

  u : ws-url?
  headers : (listof header?) = empty
Connects to the WebSocket server specified by u, providing headers as additional headers. Returns the connection handle.

This module also provides the exports from net/websocket/conn.

3.2 Server API

 (require net/websocket/server)

procedure

(ws-serve conn-handle    
  [#:conn-headers conn-headers    
  #:tcp@ tcp@    
  #:port port    
  #:listen-ip listen-ip    
  #:max-waiting max-waiting    
  #:timeout timeout    
  #:confirmation-channel confirm-ch]) → (-> void)
  conn-handle : (open-ws-conn? any/c . -> . void)
  conn-headers : (bytes? (listof header?) . -> . (values (listof header?) any/c))
   = (λ (b hs) (values empty (void)))
  tcp@ : (unit/c (import) (export tcp^)) = raw:tcp@
  port : tcp-listen-port? = 80
  listen-ip : (or/c string? false/c) = #f
  max-waiting : integer? = 4
  timeout : integer? = (* 60 60)
  confirm-ch : (or/c false/c async-channel?) = #f
Starts a WebSocket server where each new connection uses conn-headers to compute what headers the client receives based on the client’s request line and headers. conn-headers also returns a piece of state that will be passed to conn-handle as its second argument. After the connection handshake is finished, conn-handle receives the connection and is in sole control until the WebSocket connection completes.

All other arguments are used as in a Dispatching Server. Similarly, the return result is a function that shuts down the server, just like a dispatch server.

The #:tcp@ keyword is provided for building an SSL server.

This module also provides the exports from net/websocket/conn.

3.3 Connections

 (require net/websocket/conn)

WebSocket connection are synchronizable events.

parameter

(framing-mode) → (symbols 'old 'new)

(framing-mode mode) → void?
  mode : (symbols 'old 'new)
Controls whether framing is as before August 16th, 2010 or after. (Most Web browsers currently support only 'old and they are incompatible, so you must choose the correct one.) Defaults to 'old.

procedure

(ws-conn? x) → boolean?

  x : any/c
Returns true if x is a WebSocket connection.

procedure

(open-ws-conn? x) → boolean?

  x : any/c
Returns true if x is an open WebSocket connection.

procedure

(ws-conn-line ws) → bytes?

  ws : ws-conn?
Returns the request/response line of the WebSocket connection.

procedure

(ws-conn-closed? ws) → boolean?

  ws : ws-conn?
Returns true if the WebSocket connection has been closed.

procedure

(ws-conn-headers ws) → (listof header?)

  ws : ws-conn?
Returns the headers of the WebSocket connection.

WebSocket connection support only blocking calls:

procedure

(ws-send! ws s) → void

  ws : open-ws-conn?
  s : string?
Sends s over ws.

procedure

(ws-recv ws) → (or/c string? eof-object?)

  ws : open-ws-conn?
Receives a string from ws. Returns eof if the other end closes the connection.

procedure

(ws-close! ws) → void

  ws : open-ws-conn?
Closes ws.

3.4 Example

This is a WebSocket echo server compatible with the browser origin security model:

(ws-serve
 #:port 8080
 (λ (wsc _)
   (let loop ()
     (define m (ws-recv wsc))
     (printf "~a\n" m)
     (unless (eof-object? m)
       (ws-send! wsc m)
       (loop))))
 #:conn-headers
 (λ (_ hs)
   (define origin
     (header-value (headers-assq* #"Origin" hs)))
   (values
    (list
     (make-header #"Sec-WebSocket-Origin" origin)
     (make-header #"Sec-WebSocket-Location"
                  #"ws://localhost:8080/"))
    #f)))
  top  ← prev  up  next →