Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mscdex/grappler

A minimalistic server for "comet" connections in Node.js.
https://github.com/mscdex/grappler

Last synced: 3 months ago
JSON representation

A minimalistic server for "comet" connections in Node.js.

Awesome Lists containing this project

README 

        
Grappler

========



Grappler is a minimalistic server for "comet" connections that exposes a single, consistent API across all transports.

Grappler currently supports the following transports (each with a list of currently known supported browsers):



* WebSockets (with Flash policy support -- watches for policy requests on the same port as the grappler server)

  * Firefox 4, Chrome 4+, Safari 5, or any browser that supports at least Flash 9.x

* XHR Multipart Streaming

  * Firefox 3+, Safari 5 (maybe 4.0 also?), Chrome 1+

* Server-Sent Events

  * Chrome 6+, Safari 5, Opera 9.x-10.x (DOM only)

* XHR Long Polling

  * Any browser that supports XMLHttpRequest*



\* - Some browsers' XMLHttpRequest implementations contain unexpected quirks (e.g. the built-in web browser for Android 1.6)



Requirements

============



* Node.JS (tested with v0.4.2 -- may work with older versions)

* A client supporting one of the aforementioned transports.

* For HTTP (non-WebSocket) clients, cookies must be enabled for clients ONLY if they are going to send messages (i.e. via POST) to the server.



Example (broadcast echo)

========================



1. Run examples/echo/server.js.

2. Visit the demo server's page in one or more browsers: http://127.0.0.1:8080/demo.htm



API

===



Grappler exports one main object: `Server`.



lib/common.js exports `LOG` and `STATE` objects, which contain constants used for

when logging messages and checking the state of a client respectively.



The `LOG` object is:



    {

      INFO: 1,

      WARN: 2,

      ERROR: 3

    }



The `STATE` object is:



    {

      ACCEPTED: 1, // internal use only

      TEMP: 2, // internal use only

      PROTO_HTTP: 4, // client is HTTP-based

      PROTO_WEBSOCKET: 8 // client is WebSocket-based

    }



## Server



### Constructor: new Server([options], [fnHandleNormalHTTP], [fnAcceptClient])



Creates a new instance of a grappler server.



`options` is an object with the following default values:



    {

      // A callback for receiving "debug" information. It is called with two arguments: message and message level.

      // Message level is one of the values in the `LOG` object.

      logger: function(msg, msgLevel) {},



      // A string or array of strings which denote who is allowed to connect to this grappler Server instance.

      // The format of the string is: "hostname:port", "hostname", or an asterisk substituted for either the hostname

      // or port, or both, to act as a wildcard.

      origins: "*:*",

      

      // An integer value in milliseconds representing the interval in which a ping is sent to an HTTP client for those

      // transports that need to do so.

      pingInterval: 3000,



      // A storage provider used to store client objects. The default is to use 'object', a simple hash. Other available

      // storage providers can be found in lib/storage. The value here is the name without the 'storage' prefix and file extension.

      storage: 'object'

    }



`fnHandleNormalHTTP` is a callback which is able to override grappler for an incoming HTTP connection.

If no headers are sent, then grappler takes control of the connection. The arguments provided to this callback are the

same for `http.Server`'s `request` event, that is: http.ServerRequest and http.ServerResponse objects. It should be

noted that if you want grappler to automatically handle all incoming HTTP connections but want to specify a callback

for `fnAcceptClient`, you need to specify a `false` value for `fnHandleNormalHTTP`.



`fnAcceptClient` is a callback that is executed the moment a client connects. The main purpose of this callback is to

have the chance to immediately deny a client further access to the grappler server. For example, your application may

maintain a blacklist or may automatically blacklist/throttle back a certain IP after x connections in a certain amount of time.

If this callback returns `false`, the connection will automatically be dropped, otherwise the connection will be permitted.

The callback receives one argument, which is the `net.Stream` object representing the connection.



### Event: connection



`function(client) { }`



This event is emitted every time a new client has successfully connected to the system.

`client` is an instance of `HttpClient`.



### Event: error



`function(err) { }`



Emitted when an unexpected error occurs.



### listen(port, [host])



Starts the server listening on the specified `port` and `host`. If `host` is omitted, the server will listen on any IP address.



### broadcast(data[, encoding])



Sends `data` to every connected client using an optional `encoding`.



### shutdown()



Shuts down the server by no longer listening for incoming connections and severing any existing client connections.



## HttpClient



There is one other important object that is used in grappler, and that is the `HttpClient` object.

`HttpClient` represents a user connected to the server and can be used to interact with that user.



### Event: drain



`function() { }`



Emitted when the client's write buffer becomes empty.



### Event: close



`function() { }`



Emitted when the client has disconnected.



### state



A bit field containing the current state of the client. See the previously mentioned `STATE` object for valid bits.



### remoteAddress



The IP address of the client.



### write(data[, encoding])



Sends `data` using an optional `encoding` to the client.

This function returns `true` if the entire data was flushed successfully to the kernel

buffer. Otherwise, it will return `false` if all or part of the data was queued in user memory.

`drain` will be emitted when the kernel buffer is free again.



### broadcast(data[, encoding])



Sends `data` to all other connected clients using an optional `encoding`.



### disconnect()



Forcefully severs the client's connection to the server.