Initial, very dirty, docs on RAET

I need to push where I am here, but I am out of time today to get more
in.

RAET works! Albeit just barely, it is very KDE 4.0, still
needs much work, but we want it in the hands of the people!

doc/topics/transports/raet/index.rst

@@ -0,0 +1,112 @@
+==================
+The RAET Transport
+==================
+
+.. note::
+
+    The RAET transport is in very early development, it is functional but no
+    promises are yet made as to it's reliability or security.
+
+    This document is also not yet complete
+
+.. versionadded:: Helium
+
+The Reliable Asynchronous Event Transport, or RAET, is an alternative transport
+medum developed specifically with Salt in mind. It has been developed to
+allow queueing to happen up on the application layer and comes with socket
+layer encryption. It also abstreacts a great deal of control over the socket
+layer and makes it easy to bubble up errors and exceptions.
+
+RAET also offers very powerful message routing capabilities, allowing for
+messages to be routed between processes on a single machine all the way up to
+processes on multiple machines. Messages can also be restricted, allowing
+processes to be sent messages of specific types from specific sources
+allowing for trust to be established.
+
+Why?
+====
+
+Customer and User Request
+-------------------------
+
+Why make an alternative transport for Salt? There are many reasons, but the
+primary motivation came from customer requests, many large companies came with
+requests to run Salt over an alternative transport, the reasoning was varried,
+from performance and scaling concerns to licencing concerns. These customers
+have partnered with SaltStack to make RAET a reality.
+
+Networking Flexibility
+----------------------
+
+forthcoming
+
+RAET and ZeroMQ
+===============
+
+When using RAET, ZeroMQ is not required. RAET is a complete networking
+replacement. It is noteworthy that RAET is not a ZeroMQ replacement in a
+general sense, the ZeroMQ constructs are not reproduced in RAET, but they are
+instead implimented in such a way that is specific to Salt's needs.
+
+RAET is primarily an async communication layer over truly async connections,
+defaulting to UDP. ZeroMQ is over TCP and abstracts async constructs within the
+socket layer.
+
+Salt is not dropping ZeroMQ support and has no immediate plans to do so.
+
+Encryption
+==========
+
+The RAET system in Salt defaults to using CurveCP encryption, the
+specifications for which can be found here:
+http://curvecp.org
+
+RAET does maintain a few minor differences, primarily in the formatting of the
+header and the inline distribution of long term keys. A more complete
+explanation of differences can be found here:
+<forthcoming>
+
+Using RAET in Salt
+==================
+
+Using RAET in Salt is easy, the main difference is that the core dependecies
+change, insead of needing pycrypto, M2Crypto, ZeroMQ and PYZMQ, the packages
+libsodium, pynacl and ioflo are required. Encryption is handled very cleanly
+by libsodium and pynacl, while the queueing and flo control is handled by
+ioflo. Distribution packages are forthcoming, but libsodium can be easily
+installed from source, or many distributions do ship packages for it.
+The pynacl and ioflo packages can be easily installed from pypi, distribution
+packages are in the works.
+
+Once the new deps are installed the latest Salt git code needs to be installed.
+As of this writing RAET is nto available in a stable release of Salt, it must
+be installed a git clone:
+
+.. code_block:: bash
+
+    git clone https://github.com/saltstack/salt.git
+    cd salt
+    python2 setup.py install
+
+.. note::
+
+    This will install Salt directly from git HEAD, there is nto promise that
+    git HEAD is in a functional state.
+
+Once installed, modify the configuration files for the minion and master to
+set the transport to raet:
+
+/etc/salt/master:
+.. code_block:: yaml
+
+    transport: raet
+
+/etc/salt/minion:
+.. code_block:: yaml
+
+    transport: raet
+
+Now start salt as it would normally be started, the minion will connect to the
+master and share long term keys, which can then in turn be managed via
+salt-key. Remote execution and salt states will function in the same way as
+with Salt over ZeroMQ.

doc/topics/transports/raet/programming_intro.rst

@@ -0,0 +1,39 @@
+=========================
+Intro to RAET Programming
+=========================
+
+.. note::
+
+    This page is still under construction
+
+The first thing to cover is that RAET does not present a socket api, it
+presents and queueing api, all messages in RAET are made available to via
+queues. This is the single most differentiating factor with RAET vs other
+networking libraries, instead of making a socket, a stack is created.
+Instead of calling send() or recv(), messages are placed on the stack to be
+sent and messages that are recived appear on the stack.
+
+Different kinds of stacks are also available, currently two stacks exist,
+the UDP stack, and the UXD stack. The UDP stack is used to communicate over
+udp sockets, and the UXD stack is used to communicate over Unix Domain
+Sockets.
+
+The UDP stack runs a context for communicating over networks, while the
+UXD stack has contexts for communicating between processes.
+
+UDP Stack Messages
+==================
+
+To create a UDP stack in RAET, simply create the stack, manage the queues,
+and process messages:
+
+.. code-block:: python
+
+    from salt.transport.road.raet import stacking
+    from salt.transport.road.raet import estating
+
+    udp_stack = stacking.StackUdp(ha=('127.0.0.1', 7870))
+    r_estate = estating.Estate(stack=stack, name='foo', ha=('192.168.42.42', 7870))
+    msg = {'hello': 'world'}
+    udp_stack.transmit(msg, udp_stack.estates[r_estate.name])
+    udp_stack.serviceAll()