Text file with possible hub/peer states added (uncomplete)

[hub-docs.git] / misc / possible_hub_states.txt

diff --git a/misc/possible_hub_states.txt b/misc/possible_hub_states.txt
new file mode 100644 (file)
index 0000000..1980ab8
--- /dev/null
+++ b/misc/possible_hub_states.txt
@@ -0,0 +1,49 @@
+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
+started. This state is stored along with a timestamp to watch the overall
+performance of this hub reacting a troubleous peer.
+
+Karma lose is being remembered in a summary for "productive" and addionally as
+a full list for debugging purposes.
+
+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.
+
+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.
+
+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
+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.