================================================================================
 GNARLY
================================================================================

This project is an attempt at a UDP network library. Primarily aimed at games.

Very much /work in progress/.

See network/README for a detailed overview of how each packet is constructed.
See client/README and the client code for an example of how it all works.

================================================================================
 FEATURES
================================================================================

- Full IPv4 and IPv6 support
- NAT client resolution: Multiple clients connecting from behind a NAT router
  and sharing the same public IP can accurately be identified. Not by using the
  connecting portnumber, because this can be cycled inbetween packets by some
  NAT routers. We use the public IP + the lower 2 bytes of the client's private
  IP to generate a unique 24 byte peer id. See network/README for details on
  how this works exactly.

- Packet compression and encryption can be enabled/disabled.
  You can set (de)compression and (en/de)cryption handlers if you wish to use
  your own versions of either of these. Note that compression and encryption
  operates on the full dataset supplied to the Send routine. Any data that
  requires fragmentation is compressed/encrypted as a whole and then cut into
  smaller chunks. The library will reassemble the packets on the receiving end
  and only then decompress/decrypt it all.

- Customizable packet size limit. Defaults to 576 bytes. This includes the
  22 byte UDP header and a 5 or 7 byte (depending on which flags are set) header
  we use in this library internally.

- Latency tracking for 'connected' peers as well as a timeout mechanism based on
  a customizable timeout value. Both newly connecting peers and those that
  time out generate messages you can intercept and act on. Refer to
  client/client.go to see how this works. This operates by sending PING packets
  to known peers at regular (customizable) intervals. We chose the ping option
  over sending a timestamp in every packet, because it would add a considerable
  amount of space overhead (8 bytes) in regular packet traffic. This space is
  better put to use in other tasks; like sending actual game data.

- Supports packet fragmentation. If a chunk of data you want to send exceeds
  the maximum packet size, the library will automatically create multiple
  sequentially tagged packets and has the ability to cache them on the receiving
  end in order to reconstruct the original data. This mechanism also guarantees
  that the multi-packet dataset is rebuilt in the correct order.
 
  All if this is completely transparent to the host application. All it will
  deal with is sending any arbitrarilly sized chunk of data and receive it on
  the other end. It will never know how many packets where involved. The client
  simply hooks up a function which accepts a peerid, a message type and the
  actual completly reassembled, uncompressed and decrypted dataset; ready for
  use.

================================================================================
TODO
================================================================================

- Implement our own default compression and encryption routines. Currently these
  are just empty placeholder functions. The mechanism to make these work on
  packets is in place and operational; these functions just need something to
  do.

- Implement proper packet acknowledgement. Ideally ACK's should piggyback on
  other packets.

- Write some decent benchmarks.

--------------------------------------------------------------------------------
 USAGE
--------------------------------------------------------------------------------

 In order to start using this repository, make sure you have the latest Go
 buildtools installed and follow these steps:

 $ cd /path/to/codelib
 $ git clone http://github.com/term1nal/gnarly.git
 $ cd gnarly
 $ make

--------------------------------------------------------------------------------
 LICENSE
--------------------------------------------------------------------------------

This code is subject to a 1-clause BSD license.
The contents of which can be found in the LICENSE file.