Changeset 31625 in project


Ignore:
Timestamp:
10/09/14 00:52:46 (6 years ago)
Author:
svnwiki
Message:

Anonymous wiki edit for IP [172.56.39.139]: Finishing docs (for now).

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/websockets

    r31623 r31625  
    55=== Description
    66
    7 {{websockets}} is a fast, lightweight, and simple implementation of the websockets protocol. It currently only supports version 13 and no extensions.
    8 
    9 {{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 does 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.
     7{{websockets}} is a fast, lightweight, and simple implementation of the websockets protocol. It currently only supports version 13 of the websocket protocol and no extensions.
     8
     9{{websockets}} includes 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 does 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.
    1010
    1111All high level procedures are thread safe. See the low level interface for details on which procedures are and are not thread safe at that level.
    1212
    13 All errors triggered by the library are of condition type {{websocket}} and all are continuable.
     13All errors triggered by the library are of condition type {{websocket}} and all are continuable (not that they should be continued in all cases).
     14
     15=== Author
     16
     17[[http://thintz.com|Thomas Hintz]] with contributions from Seth Alves.
     18
     19Please send an email to t@thintz.com or chicken-users@nongnu.org with questions, bug reports, or feature requests.
    1420
    1521=== Repository
     
    3238
    3339=== Quick start example
     40
     41Put these two files in the same folder.
    3442
    3543'''index.html'''
     
    4250        alert(evt.data);
    4351      };
    44       ws.send('Hello!');
     52      ws.onopen = function() {
     53        ws.send('Hello!');
     54      }
    4555    </script>
    4656  </body>
     
    5464
    5565(handle-not-found
    56   (lambda (path)
    57     (when (string= path "/web-socket")
    58       (with-websocket
    59         (lambda ()
    60           (send-message (string-append "you said: " (receive-message))))))
     66 (lambda (path)
     67   (when (string= path "/web-socket")
     68         (with-websocket
     69          (lambda ()
     70            (send-message (string-append "you said: " (receive-message))))))))
    6171
    6272(root-path ".")
     
    6474</enscript>
    6575
     76Then, in the same directory, run:
     77
     78<enscript>
     79csi -s echo.scm
     80</enscript>
     81
     82You should see an alert saying "you said: Hello!".
     83
    6684=== Parameters
    6785
    6886===== {{current-websocket}}
    6987<parameter>(current-websocket [websocket])</parameter>
    70 Only available with {{with-websocket}} or {{with-concurrent-websocket}}. {{current-websocket}} will be bound to a websocket object. Many procedures provide an optional argument for a websocket object and it is bound to {{current-websocket}} by default.
     88
     89Only available with {{with-websocket}} or {{with-concurrent-websocket}}. {{(current-websocket)}} will be bound to a websocket object. Many procedures provide an optional argument for a websocket object and it is bound to {{current-websocket}} by default.
    7190
    7291===== {{ping-interval}}
     
    7594How often to ping the client, in seconds, in the background. If {{0}} then automatic pinging will be disabled. This defaults to 15 seconds.
    7695
    77 If this is set to a value greater than 0 then a thread will run in the background sending ping messages to the client at the specified interval. This is used to keep connections open that will otherwise be closed. Often connections without a transmission will be killed after awhile, often after 60s. Receiving pongs in response to a ping will also reset the connection close timer.
     96If this is set to a value greater than 0 then a thread will run in the background sending ping messages to the client at the specified interval. This is used to keep connections open that will otherwise be closed. Often connections without a transmission will be killed after awhile a short while. Receiving pongs in response to a ping will also reset the connection close timer.
    7897
    7998pong responses to ping messages are not passed through to the user when using the high level API but they are used to update the timestamp that the connection timeout thread uses to decide if it should kill a connection.
     
    116135A 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.
    117136
    118 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.
     137All websocket specific errors are covered by this. The only error you may receive if this is {{#f}} is of type {{websocket}} and {{unexpected-error}} if something goes terribly wrong with the implementation and usually means there is a bug in the implementation. This does not affect errors that are caused by user code, they will always be passed on but the websocket will be properly with an error code of 1011 (unexpected-error).
    119138
    120139Note 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.
     
    126145The 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.
    127146
    128 The maximum frame size supported by {{websockets}} is {{1GiB}}.
     147The maximum frame size supported by the current {{websockets}} implementation is {{1GiB}}.
    129148
    130149
     
    134153The 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.
    135154
    136 The maximum message size supported by {{websockets}} is {{1GiB}}.
     155The maximum message size supported by the current {{websockets}} implementation is {{1GiB}}.
    137156
    138157=== High level interface
     
    171190It is thread safe.
    172191
     192If a message is of type {{binary}} then converting it to something possibly more "binary" like, such as a u8vector, could be done with the following. It will incur one copy of the data though.
     193
     194<enscript highlight="scheme">
     195(blob->u8vector/shared (string->blob msg))
     196</enscript>
     197
     198You could also use a string port to read the data in different fashions.
     199
     200<enscript highlight="scheme">
     201(with-input-from-string msg
     202  (lambda ()
     203    (read-byte)
     204    (read-u8vector))) ; etc
     205</enscript>
     206
    173207==== {{send-message}}
    174 <procedure>(send-message message-type #!optional (data "") (ws (current-websocket)))</procedure>
    175 
    176 Send a message to the client. {{message-type}} is one of the types listed under the {{message-types}} section. Usually this will be {{'text}} or {{'binary}} but any valid type is allowed. {{data}} is optional and defaults to an empty message. It can be a string or a u8vector that will be sent to the client. Note that currently u8vectors must be copied before being sent due to some CHICKEN internal limitations, strings will not. {{send-message}} also takes an optional {{websocket}} object that is bound to {{(current-websocket)}} by default.
     208<procedure>(send-message data #!optional (message-type 'text) (ws (current-websocket)))</procedure>
     209
     210Send a message to the client. {{data}} is a string or u8vector to be sent to the client. {{message-type}} is one of the types listed under the {{message-types}} section and defaults to {{'text}}. Usually this will be {{'text}} or {{'binary}} but any valid type is allowed. Note that if the {{data}} argument is a string it must be copied before being sent due to some CHICKEN internal limitations, strings will not. {{send-message}} also takes an optional {{websocket}} object that is bound to {{(current-websocket)}} by default.
    177211
    178212It is thread safe.
     
    302336
    303337Returns the optype (or message type) of the fragment as a symbol.
     338
     339=== Contributors
     340
     341Thanks to Seth Alves for developing the initial version.
     342
     343=== Versions
     344
     345==== 0.0.2
     346
     347Initial release
     348
     349=== License
     350
     351Copyright (c) 2014, Thomas Hintz, Seth Alves
     352All rights reserved.
     353
     354Redistribution and use in source and binary forms, with or without
     355modification, are permitted provided that the following conditions
     356are met:
     3571. Redistributions of source code must retain the above copyright
     358   notice, this list of conditions and the following disclaimer.
     3592. Redistributions in binary form must reproduce the above copyright
     360   notice, this list of conditions and the following disclaimer in the
     361   documentation and/or other materials provided with the distribution.
     3623. The name of the authors may not be used to endorse or promote products
     363   derived from this software without specific prior written permission.
     364
     365THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
     366OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
     367WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
     368ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
     369DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
     370DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
     371GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
     372INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
     373IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
     374OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
     375IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracChangeset for help on using the changeset viewer.