-Possible States For A Hub Connection
-====================================
-
-This is a brief summary of possible states a hub connection may be setted.
-These ideas should later be implemented ina XML file with e.g. a StateXmlParser
-class with a XmlFileReader as a data source.
-
--------------------------------------------------------------------------------
- Initial state | Reason of change | New state
--------------------------------------------------------------------------------
- New peer | Appears as a simple connection | Connected
- Connected | Has dropped the connection | Disconnected
- Connected | Does not do anything within a timeout | Timed out
- Disconnected | Is purged from the connection list | Removed
- Timed out | Is being pinged | Pinged
- Pinged | Does not response on a ping | No response
- Pinged | Does reply slowly on a ping | Slowed down
- Pinged | Does reply fast on a ping | <prev. state>
- No response | Does still not response on X pings | Lost connection
- No response | Does reply on a ping | Slowed down
- Slowed down | Does not response on a ping | No response
- Slowed down | Does still response slow on X extra pings | Karma lose
- Slowed down | Does reply faster on a ping | <prev. state>
- Lost connect. | Is maybe disconnected/crashed/etc. | Disconnected
- Karma lose | Has lost some karma | <prev. state>
--------------------------------------------------------------------------------
-
-A previous state is a non-fatal state that the peer was before the trouble
+Possible node-internal states
+=============================
+
+These states are the node's own states and not a state of any other node, e.g.
+when you start the software, there is currently no state [instance], the
+node's state is 'null' (also null from $stateInstance is initially null).
+
+---------------+------------------------------------------------------+-------------
+ Initial state | Reason of change | New state
+---------------+------------------------------------------------------+-------------
+ Null | Node application has been initialized | Init
+ Init | Node has generated session id | Virgin
+ Virgin | Node has initialized all listeners, queues | Active
+ Active | Node has reached itself from outside (self-connect) | Reachable
+ Active | Node has attempted to announce itself to other nodes | Announced
+ Reachable | -"- -"- -"- -"- -"- | Announced
+---------------+------------------------------------------------------+-------------
+
+Possible states for a regular-node connection
+=============================================
+
+This is a brief summary of possible states a regular-node connection may be
+setted. These ideas should later be implemented in a XML file with e.g. a
+StateXmlParser class with a XmlFileReader as a data source.
+
+---------------+------------------------------------------------------+-------------
+ Initial state | Reason of change | New state
+---------------+------------------------------------------------------+-------------
+---------------+------------------------------------------------------+-------------
+
+A previous state is a non-fatal state that the node was before the "trouble"
started. This state is stored along with a timestamp to watch the overall
-performance of this hub reacting a troubleous peer.
+performance of this node reacting a troubleous node.
-Karma lose is being remembered in a summary for "productive" and addionally as
-a full list for debugging purposes.
+Karma lose or added karma is being remembered in a lose/add-seperated summary
+for "productive" and addionally as a full list for debugging purposes if the
+debug mode is enabled.
A "connection" should be interpreted as a incoming socket "connection". That
means in this state table we threat UDP "connections" as same as TCP
-connections to make things easier.
+connections to make things easier. Of, course the script will be the last one
+to seperate between these very different protocols.
-A "ping" is a small message that should be responded by a pinged peer within a
-time else the ping would loose some karma. When a "ping" is issued it should not
-be resend within a time period to not ping the peer to death.
+A "ping" is a small message that should be responded by a pinged node within a
+time period else the pinged node would loose some karma. When a "ping" is
+issued it should not be resend within a time period to not ping the node to
+death.
-So pings are not issued while there is no trouble with the peer. This does
-reduce network load for certain. Troubleous peers are being detected by the
+So pings are not issued while there is no trouble with the node. This does
+reduce network load for certain. Troubleous nodes are being detected by the
above state changes (see Connected->Timed out for example).
Some state changes are no *real* state changes. They are sometimes remarks
-attached to the peer connection. A good example is the state 'Karma lose' which
-a peer does never change to.
+attached to the node connection. A good example is the state 'Karma lose' which
+a node does never change to.
+
+A "list" should be interpreted as a DHT (Distributed Hash Table). All list and
+object transfers are being validated by final hashes for best reliablity.