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 More...
number	broadcast (object message, function filter=null)
	send a message to all connected clients More...
NetServer	expectClient (string clientKey, string clientIpAddr= '*', int reservationTTL=FOREVER, boolean singleUse=false)
	make a connection reservation for a client More...
NetServer	listen (function callback)
	listen and call a function when new connections are established More...
NetServer	onError (function callback)
	set up callback for handling errors More...
	shutdown (boolean closeExisting=true, boolean kill=false)
	stop listening for new connections More...

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

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

opts	a 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

message	the message to send
filter	the 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

callback

the 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

callback

the 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

closeExisting	flag for whether existing connections should be closed or not (defaults to true if not passed)
kill	flag 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

closeExisting

flag 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().