PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Public Attributes | List of all members
NetServer Class Reference

a network endpoint that can accept incoming connections More...

Public Member Functions

 NetServer (object opts=null)
 constructor for a NetServer, sets server options
 
number broadcast (object message, function filter=null)
 send a message to all connected clients
 
NetServer expectClient (string clientKey, string clientIpAddr= '*', int reservationTTL=FOREVER, boolean singleUse=false)
 make a connection reservation for a client
 
NetServer listen (function callback)
 listen and call a function when new connections are established
 
NetServer onError (function callback)
 set up callback for handling errors
 
 shutdown (boolean closeExisting=true, boolean kill=false)
 stop listening for new connections
 

Public Attributes

boolean allowDatagram
 when true, the server tries to establish UDP communications with the client
 
 connections
 an array of NetConnections made to this server - Read Only
 
number handshakeTimeout
 the number of milliseconds allowed for handshake. Default is 5000 (5 seconds)
 
boolean listening
 flag to indicate if the server is currently listening or not
 
boolean reservationRequired
 flag to indicate if reservations to the server are required or not
 
string serverAddr
 the address (interface) on which the server listens 0.0.0.0 means all interfaces on the computer
 
number serverPort
 the port on which the server listens
 

Detailed Description

a network endpoint that can accept incoming connections

Note
API Stability: 2 - Unstable. The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable. Backwards-compatibility will be maintained if reasonable.

Overview

NetServer is part of the PDG Engine's custom protocol for games. It handles protocol negotiation and optional connections. It provide a server that listens for connections with a client over both TCP (reliable transport with guaranteed delivery) and UDP (small and unreliable but fast).

NetServer doesn't actually handle network communication, it only listens for incoming connections. Once a connection is established, it creates a NetConnection object for each connected client that you can use to send and receive data.

In cases where your server consists of multiple processes (most game servers do, especially ones that expect to scale to handle a large number of users) a particular server process may be both a server and a client. For example, it might accept connections from players over the internet using a NetServer, but then connect (using a NetClient) to a central message distribution system to relay chat between players connected to different server nodes.

Authorization & Reservations

There are 5 different ways you can allow clients to connect:

  1. Wide Open - clients do not require any authorization or reservation to connect. Obviously this is the least secure, but is fine for server processes that are all behind a firewall, or peer to peer connections. This is the default setting for NetServer if no options are used.
  2. Common Key - clients all send the same static key. To do this, call expectClient() once with the static key and no other parameters. That will allow all clients to call NetClient.connect() with that static key. Attempts to connect without the key will be rejected by the NetServer
  3. Computed Key - clients and server each compute a key based on some common information that they all have, most likely the UTC date/time. This is nearly the same as a static key, except that the single key doesn't last forever. To do this, all expectClient() with the new key at a regular interval and set a reservationTTL for the keys. Make sure you pass "*" (any ip) for the clientIPAddr. You will probably want the TTL to be slightly longer than the new key interval to give clients a little extra time to connect with the previous computed key, to allow for differences in date/time between different systems.
  4. Per-Client reservation - Each client gets a unique key for their exclusive use during a session, set on the server side by calling expectClient(). Generally this happens when the user logs in. This is made stronger if the client's IP address is also part of the reservation. The reservation should have a time to live (TTL).
  5. Single Use Reservation - This is by far the most secure, especially when combined with IP address checking. Any time the client is going to connect to a server, it must be given a key, and the server must be told to expect that key using expectClient(). TTL should be short (10s of seconds) and the singleUse flag should be passed as true to expectClient().
Warning
NetClient, NetServer, and NetConnection all work together over a custom protocol. NetServer doesn't handle raw TCP nor any other protocol such as HTTP. There are perfectly fine Net and HTTP modules built-in to Node.js (and thus to PDG) for that.
See Also
expectClient
NetConnection
NetClient
Node.js Net module
Node.js HTTP module

Constructor & Destructor Documentation

NetServer ( object  opts = null)

constructor for a NetServer, sets server options

Construct a new NetServer with particular options or using default values if no options are specified.

Available options are:

  1. serverAddr - a string with the IP address (or hostname), defaults to 0.0.0.0 (all interfaces)
  2. serverPort - a string with the port to use (defaults to 5000)
  3. fixedPort - if false, indicate if we should try sequential ports if the one we asked for is already in use (defaults to false)
  4. noDatagram - flag to indicate that we should not try to establish UDP communication with the client (defaults to false)
  5. reservationRequired - flag indicating whether clients must be authenticated or not (defaults to false)
  6. handshakeTimeout - number of milliseconds to wait for handshake to complete. Connection is killed if handshake not complete by that time. Default is 5000 (5 seconds). Shorter times offer better protection against Denial of Service attacks.
Parameters
optsa Javascript object with the options above
var myServer = new pdg.NetServer( { serverPort: 6160, noDatagram = true } );

Member Function Documentation

broadcast ( object  message,
function  filter = null 
)

send a message to all connected clients

Go through all the NetConnections in the connections array send the message to each of them. If a filter function is used, instead of sending to all, only send to the ones that filter function returns true for.

The filter function should take one parameter, a Net Connection, and should return true if the connection passes the filter, and false if it is excluded by the filter.

Parameters
messagethe message to send
filterthe filter function. If not passed, all connections will be sent the message.
Returns
the number of connections that were actually sent a message
expectClient ( string  clientKey,
string  clientIpAddr = '*',
int  reservationTTL = FOREVER,
boolean  singleUse = false 
)

make a connection reservation for a client

When a server is created with the reservationRequired flag set to true, the server needs to know how clients are authorized. Use this to make specific reservations for clients by unique key and/or IP address; or a general reservation for all clients using a shared key, perhaps computed based on UTC date and time.

Parameters
clientKey- the key the client(s) must provide
clientIpAddr- the IP address the client is allowed to connect from (defaults to '*', which means any IP address will be accepted)
reservationTTL- how long this reservation is valid (defaults to forever)
singleUse- flag to indicate if the reservation becomes invalid after it is used (default to false, can be used multiple times until expiration)
Returns
itself for call chaining
listen ( function  callback)

listen and call a function when new connections are established

Starts a listening port for incoming connections, and with each new connection calls the provided callback with a newly created NetConnection.

The callback will be invoked with one parameter, a NetConnection.

myServer.listen( function(myConnection) {
myConnection.send('sorry, too busy to talk');
myConnection.close();
});
Parameters
callbackthe callback function
Returns
itself for call chaining
See Also
NetConnection
onError ( function  callback)

set up callback for handling errors

These will be errors with the listening port, not with the connections themselves; those go to the connection object. The exception is IP mismatch on incoming connections – those don't generate any errors to avoid spending unnecessary resources in the event of denial of service attacks.

Parameters
callbackthe callback function to be notified of errors
Returns
itself for call chaining
shutdown ( boolean  closeExisting = true,
boolean  kill = false 
)

stop listening for new connections

This will also do a clean shutdown of all existing connections made through it, unless you tell it not to by passing false for closeExisting.

Parameters
closeExistingflag for whether existing connections should be closed or not (defaults to true if not passed)
killflag for whether existing connections should be killed. True means kill, false means allow to drain normally (defaults to false if not passed).

This will also do a clean shutdown of all existing connections made through it, unless you tell it not to by passing false for closeExisting.

Parameters
closeExistingflag for whether existing connections should be closed or not (defaults to true if not passed)

Member Data Documentation

allowDatagram

when true, the server tries to establish UDP communications with the client

This is set based on what you pass in for noDatagram at NetServer initialization. It can be changed at any time to affect new incoming connections. Changes will not affect existing connections.

connections

an array of NetConnections made to this server - Read Only

handshakeTimeout

the number of milliseconds allowed for handshake. Default is 5000 (5 seconds)

The connection will be dropped if handshake has not completed in this time. This is to help prevent denial of service attacks.

This can be changed at any time to affect the timeout for new incoming connections. Changes will not affect existing connections.

The connection will be dropped if handshake has not completed in this time. This is to help prevent denial of service attacks.

listening

flag to indicate if the server is currently listening or not

flag to indicate if the server is currently listening or not - Read Only

reservationRequired

flag to indicate if reservations to the server are required or not

This can be changed at any time to affect new incoming connection. Changes will not affect existing connections.

serverAddr

the address (interface) on which the server listens 0.0.0.0 means all interfaces on the computer

the address (interface) on which the server listens

This can be changed at any time before calling listen(). It should be considered Read Only after calling listen().

0.0.0.0 means all interfaces on the computer

serverPort

the port on which the server listens

This can be changed at any time before calling listen(). It should be considered Read Only after calling listen().

User Comments