# 4-RRC: Hub and Client State Machines _Version: 0.1.1_ Up to this point, RRC has described what messages exist and what they mean. That is not enough to prevent chaos. Without shared expectations about order and timing, different implementations will accept different nonsense and politely call it “flexibility.” This document defines the states a client and a hub can be in during a session, what messages are valid in each state, and what happens when those expectations are violated. It does not attempt to predict every possible mistake. It defines enough structure that mistakes are survivable instead of protocol-ending. ## The Only Thing That Matters First: The Link Everything in RRC is scoped to a single Reticulum Link. There is no global session, no reconnection continuity, and no implied memory across Links. If the Link exists, a session exists. If the Link closes, the session is over immediately and completely. No cleanup messages are required. No apology is expected. All state described in this document lives entirely within the lifetime of a single Link. ## Client Session States A client progresses through a small number of conceptual states after opening a Link. These states are not transmitted on the wire. They are internal expectations that guide behavior. When the Link is first established, the client is in the Connected state. At this point, the client has cryptographic identity and transport, but no application-level acknowledgment. The only sensible thing to do in this state is to send a HELLO. Once the client sends HELLO, it enters the Awaiting Welcome state. In this state, the client should not attempt to join rooms or send chat messages. It may wait, retry after a timeout, or give up entirely if the hub remains silent. If the client receives a WELCOME, it transitions into the Active state. This is the normal operating mode. In this state, the client may join rooms, leave rooms, send messages, and respond to PINGs. If the client receives an ERROR that clearly indicates refusal or fatal failure, or if the Link closes for any reason, the client enters the Disconnected state. At that point, the session is over. Any attempt to salvage state from it is wishful thinking. ## Client Behavior Rules A client must not send any message other than HELLO before it has received WELCOME. Doing so is considered impolite at best, and grounds for disconnection at worst. Once in the Active state, the client may send JOIN and PART messages freely, subject to whatever limits the hub enforces. It may send MSG and NOTICE messages only for rooms it believes it has joined. If it guesses wrong, the hub will correct it, possibly harshly. A client must respond to PING messages with PONG within a reasonable amount of time. What qualifies as reasonable depends on the network and the patience of the hub. If the client is busy or frozen, silence will eventually be interpreted as absence. If the Link closes, the client must treat all room membership as invalid. Reconnecting creates a new session, not a continuation of the old one. ## Hub Session States The hub also has a simple internal state per Link. When a Link is first established, the hub is in the Awaiting Hello state. In this state, the hub expects exactly one thing: a HELLO message. Anything else is unexpected. If the hub receives a valid HELLO and chooses to accept the session, it transitions to the Active state and sends WELCOME. If it chooses not to accept the session, it may send ERROR and close the Link, or simply close the Link without explanation if it is feeling minimalist. Once in the Active state, the hub processes room membership and message routing for that client. This state persists until the Link closes. When the Link closes, the hub immediately enters the Disconnected state for that client. All room memberships associated with that Link are removed. No PART or PARTED messages are generated implicitly. The disappearance speaks for itself. ## Hub Behavior Rules Before sending WELCOME, the hub must not process JOIN, PART, MSG, or NOTICE messages. It may ignore them or treat them as protocol errors. After sending WELCOME, the hub may accept JOIN requests and update room membership accordingly. If a JOIN references a room that does not yet exist, the hub creates it on demand. When processing PART, the hub removes the client from the specified room. If the client was not a member of that room, the hub may ignore the request or respond with ERROR. Either response is acceptable. When processing MSG or NOTICE, the hub forwards the message to all currently connected members of the specified room. The hub does not modify the message body. It does not store the message. It does not retry delivery. Once forwarding is complete, the message ceases to exist as far as the hub is concerned. If a client sends MSG or NOTICE for a room it is not a member of, the hub may reject the message, ignore it, or send ERROR. Disconnecting the client is allowed if the behavior is repeated or abusive. The hub may send PING messages at any time while the session is Active. If the client fails to respond, the hub may close the Link and reclaim its memory. ## Room State and Membership Semantics Room membership exists only as a mapping between active Links and room names. There is no separate room lifecycle state machine. If a room has zero members, it effectively does not exist. If someone joins it later, it exists again. This transition does not require explicit handling. Room membership is not ordered, not authoritative, and not guaranteed to be synchronized across clients. Any member list provided by the hub is a snapshot, not a promise. ## Message Ordering Expectations Within a single Link, messages arrive in order. RRC relies on this and does not add its own sequencing rules. Across Links, no ordering is implied. Two clients joining a room at nearly the same time may see events in different orders. This is normal and acceptable. Clients must not assume that JOINED events, member lists, or notices reflect a globally consistent view of the room. They reflect the hub’s best effort at that moment. ## Handling Bad Behavior If a client sends malformed messages, unknown message types, or messages missing required envelope fields, the hub may ignore them. It may also respond with ERROR if it wants to be helpful. If a client persistently violates protocol expectations, sends messages too quickly, or behaves like an automated annoyance, the hub may close the Link without warning. No appeal process is defined by the protocol. ## Failure Is Normal RRC assumes unreliable networks, intermittent clients, and imperfect clocks. Disconnects are expected. Lost messages are expected. Reordering across sessions is expected. The protocol is designed so that these failures result in silence rather than corruption. Silence is easier to reason about.