[ADC 1.0.2] State in ADC

[Pretorian]

The following is a suggested outline of the state in ADC. The text should simply be a rephrasing and restructuring of the state management in ADC and should not contain any modification to the actual state sequence. This does not take into account cologic's proposed changes.

The connecting party is known as the client and the other is known as the server.

State is shared between the client and the server while the server (implicitly) controls state transitions.

The states, in login order, are PROTOCOL (feature support discovery), IDENTIFY (user identification, static checks), VERIFY (password check), NORMAL (normal operation), and DATA (for binary transfers).

A command is valid only in NORMAL unless noted otherwise.

The VERIFY state for C-C connections is not mandated by this specification and should be announced as an extension.

It is always the client that sends the first CTM/RCM command that is given control of the connection once the NORMAL state has been reached.

Successful commands sent after a state transition indicate that the next state has been reached. For example, PROTOCOL begins a connection and state changes to IDENTIFY once the hub has sent the SID.

State description
|PROTOCOL |Feature support recovery
|IDENTIFY |User identification and static checks
|VERIFY |Password check (does not exist in C-C communication unless announced by an extension)
|NORMAL |Normal operation (end state)
|DATA |Binary transfers. The state changes back to NORMAL once the transfer is complete.

State always transitions from PROTOCOL to IDENTIFY and never from IDENTIFY to PROTOCOL. Likewise apply between IDENTIFY, VERIFY and NORMAL. This does not apply between NORMAL and DATA.

A STA is valid in all states (except DATA) and may require that messages are resent (i.e. that the state transition does not occur).

Any party may disconnect the connection if they receive invalid data or insufficient data. All implementations must therefore be prepared for a potential disconnection following each command, meaning that the following state is not achieved. A disconnection should be preceded by a STA or a QUI to indicate what was wrong.

Note that the hub's INF is not required to be sent in IDENTIFY. The hub's INF shall be sent in IDENTIFY or as its first command in NORMAL.

States
PROTOCOL
When the hub receives a SUP, it should reply with its own SUP followed by SID assignment. The hub transitions the state then to IDENTIFY.

When the server party receives a SUP in the client-client connection, it should reply with its own SUP. The server transitions the state then to IDENTIFY.

IDENTIFY
The hub may initiate this state by sending its own INF in this state but is not required. The client shall send its INF whereby the hub shall verify the PD and ID fields and other required fields deemed necessary by the hub. The hub transitions the state then to VERIFY if the user is registered or NORMAL if not.

The server party in the client-client connection shall send its INF whereby the client party shall send its INF. The server transitions the state then to NORMAL (or VERIFY if an extension implements this).

VERIFY
The hub shall send a GPA whereby the client will respond with a PAS. The server transitions the state then to NORMAL.

Client-client support for VERIFY must be signaled as an extension.

NORMAL
The hub shall send its INF if not done already. The server shall send the INF of all connected clients whereby the connecting client's INF shall be last. Normal operation may then commence with chatting and file sharing.

Normal operation may commence immediately in a client-client connection. Typically, the downloading party sends a GET whereby the other party sends a SND followed with a stream of data.

[Pretorian]

Addendums:

• Added initialization of state machine
• Added DATA state
• Changed the use of "whereby" to "whereupon" as it is probably easier to understand.

Changes are listed in bold. This does not take into account cologic's proposed changes.

The connecting party is known as the client and the other is known as the server.

State is shared between the client and the server while the server (implicitly) controls state transitions.

The states, in login order, are PROTOCOL (feature support discovery), IDENTIFY (user identification, static checks), VERIFY (password check), NORMAL (normal operation) and DATA (for binary transfers).

A command is valid only in NORMAL unless noted otherwise.

The VERIFY state for C-C connections is not mandated by this specification and should be announced as an extension.

It is always the client in a client-client connection that sends the first CTM/RCM command that is given control of the connection once the NORMAL state has been reached.

Successful commands sent after a state transition indicate that the next state has been reached. For example, PROTOCOL begins a connection and state changes to IDENTIFY once the hub has sent the SID.

State description
|PROTOCOL |Feature support recovery
|IDENTIFY |User identification and static checks
|VERIFY |Password check (does not exist in C-C communication unless announced by an extension)
|NORMAL |Normal operation (end state)
|DATA |Binary transfers. The state changes back to NORMAL once the transfer is complete.

State always transitions from PROTOCOL to IDENTIFY and never from IDENTIFY to PROTOCOL. Likewise apply between IDENTIFY, VERIFY and NORMAL. This does not apply between NORMAL and DATA.

A STA is valid in all states (except DATA) and may require that messages are resent (i.e. that the state transition does not occur).

Any party may disconnect the connection if they receive invalid data or insufficient data. All implementations must therefore be prepared for a potential disconnection following each command, meaning that the following state is not achieved. A disconnection should be preceded by a STA or a QUI to indicate what was wrong.

Note that the hub's INF is not required to be sent in IDENTIFY. The hub's INF shall be sent in IDENTIFY or as its first command in NORMAL.

The client initiates the connection and state machine by sending its own SUP.

States
PROTOCOL
When the hub receives a SUP, it should reply with its own SUP followed by SID assignment. The hub transitions the state then to IDENTIFY.

When the server party receives a SUP in the client-client connection, it should reply with its own SUP. The server transitions the state then to IDENTIFY.

IDENTIFY
The hub may initiate this state by sending its own INF in this state but is not required. The client shall send its INF whereupon the hub shall verify the PD and ID fields and other required fields deemed necessary by the hub. The hub transitions the state then to VERIFY if the user is registered or NORMAL if not.

The server party in the client-client connection shall send its INF whereupon the client party shall send its INF. The server transitions the state then to NORMAL (or VERIFY if an extension implements this).

VERIFY
The hub shall send a GPA whereupon the client will respond with a PAS. The server transitions the state then to NORMAL.

Client-client support for VERIFY must be signaled as an extension.

NORMAL
The hub shall send its INF if not done already. The server shall send the INF of all connected clients whereupon the connecting client's INF shall be last. Normal operation may then commence with chatting and file sharing.

Normal operation may commence immediately in a client-client connection. Typically, the downloading party sends a GET whereupon the other party sends a SND followed with a stream of data.

DATA
The client and hub may engage in a data transfer, usually required if the data is too large to send in basic commands. The state is initiated by GET from either party, followed by a SND from the opposite party and then the data. Once the data transfer is complete, the state moves back to NORMAL.

The DATA state functions similarly in client-client communication.

[Pretorian]

I was a bit too quick when it came to the DATA state. The following is a new change to it.

NORMAL
The hub shall send its INF if not done already. The server shall send the INF of all connected clients whereupon the connecting client's INF shall be last. Normal operation may then commence with chatting and file sharing.

Normal operation may commence immediately in a client-client connection. Typically, the downloading party sends a GET whereupon the other party sends a SND followed by a transition to the DATA state.

DATA
The DATA state is an actual binary transfer state, it does not have any commands or other content beyond streaming data.

The DATA state exist only in the client-client communication, an extension can be used to add binary transfers between a client and a hub. The DATA state commence after a SND command.

[Pretorian]

cologic's proposed changes:

IDENTIFY
The hub may initiate this state by sending its own INF in this state but is not required. The client shall send its INF whereupon the hub shall verify the PD and ID fields and other required fields deemed necessary by the hub. The hub transitions the state then to VERIFY if the user is registered or NORMAL if not.

The client party in the client-client connection shall send its INF whereupon the server party shall send its INF. The server transitions the state then to NORMAL (or VERIFY if an extension implements this).

[Pretorian]

As I noted on the dev hub, my intention is to remove all mentioning of the state in commands, which would mean that any ambiguity is removed.

Additionally, the example for the C-C connection needs to be updated to be according to cologic's proposed changes (switch place with the INF order).

[poy]

i feel there is some repetition between the "State description" table and §3. i would prefer if the table were moved in the place of §3 (along with the paragraph that follows the table, since it is also part of the generic description of the state machine).

to go even further, i would move the bottom part (which details the various states) after that paragraph; and group other, more specific remarks (about STA, CTM etc) in an "Other notes" section.

[poy]

about DATA, it would be useful to explicitly state when the transition from DATA back to NORMAL happens. is it when a null char is encountered, when bytes specified in a previous command have been consumed, when a timemout has expired?

[Pretorian]

Some editorial changes, incorporating poy's suggested changes. Added a small disclaimer in the top as well... Included an end state to DATA -- I don't know if it's applicable also with a timeout specified (what does current implementations do?).

ADC defines a state machine to control flow and processing of messages. The state machine described should be considered as best-effort. The receiving end must ensure, according to the state machine, that it does not parse or drop messages while it is in the process of another state where the message might be invalid.

State description
|PROTOCOL |Feature support recovery
|IDENTIFY |User identification and static checks
|VERIFY |Password check (does not exist in C-C communication unless announced by an extension)
|NORMAL |Normal operation (end state)
|DATA |Binary transfers. The state changes back to NORMAL once the transfer is complete.

The states presented are the login order, from top to bottom.

States
PROTOCOL
When the hub receives a SUP, it should reply with its own SUP followed by SID assignment. The hub transitions the state then to IDENTIFY.

When the server party receives a SUP in the client-client connection, it should reply with its own SUP. The server transitions the state then to IDENTIFY.

IDENTIFY
The hub may initiate this state by sending its own INF in this state but is not required. The client should send its INF whereupon the hub shall verify the PD and ID fields and other required fields. The hub transitions the state then to VERIFY if the user is registered or NORMAL if not.

The client party in the client-client connection shall send its INF whereupon the server party shall send its INF. The server transitions the state then to NORMAL (or VERIFY if an extension implements this).

VERIFY
The hub shall send a GPA whereupon the client will respond with a PAS. The server transitions the state then to NORMAL.

Client-client support for VERIFY must be signaled as an extension.

NORMAL
The hub should send its INF if not done already. The server shall send the INF of all connected clients whereupon the connecting client's INF shall be last. Normal operation may then commence with chatting and file sharing.

Normal operation may commence immediately in a client-client connection. Typically, the downloading party sends a GET whereupon the other party sends a SND followed by a transition to the DATA state.

DATA
The DATA state is an actual binary transfer state, it does not have any commands or other content beyond streaming data.

The DATA state exist only in the client-client communication, an extension can be used to add binary transfers between a client and a hub. The DATA state commence after a SND command.

The state transitions back to NORMAL once the correct amount of bytes are transferred (specified by a previous command).

Notes
State always transitions from PROTOCOL to IDENTIFY and never from IDENTIFY to PROTOCOL. Likewise apply between IDENTIFY, VERIFY and NORMAL. This does not apply between NORMAL and DATA.

Successful commands sent after a state transition indicate that the next state has been reached. For example, PROTOCOL begins a connection and state changes to IDENTIFY once the hub sends the SID.

The state is shared between the client and the server while the server (implicitly) controls state transitions.

The connecting party is known as the client and the other is known as the server (or hub). The client initiates the connection and state machine by sending its own SUP.

A command is valid only in NORMAL unless noted otherwise.

A STA is valid in all states (except DATA) and may require that messages are resent (i.e. that the state transition does not occur).

It is always the client party in a client-client connection that sent the connection request (CTM/RCM) command that is given control of the connection once the NORMAL state has been reached.

Any party may disconnect the connection if they receive invalid data or insufficient data. All implementations must therefore be prepared for a potential disconnection following each command, meaning that the following state is not achieved. A disconnection should be preceded by a STA or a QUI to indicate what was wrong.

The hub's INF is optionally sent in IDENTIFY or in NORMAL.

[poy]

Included an end state to DATA -- I don't know if it's applicable also with a timeout specified (what does current implementations do?).

i've never seen a timeout transition from DATA back to NORMAL, and there's no reason to assume there would be one since the spec doesn't mention it. as far as i know, implementations simply disconnect if they encounter a timeout.

The state machine described should be considered as best-effort.

i don't like this mention: makes it sound like this state description isn't absolute (which it really is). i understand the meaning (that one should be prepared to receive wrong commands) but would prefer a different phrasing.

The connecting party is known as the client and the other is known as the server (or hub).

confusing. server or hub? i would just leave it as "server" here. imagine if an extension were to allow a "c-c" connection between a client & a hub where the hub is the connecting party...

A command is valid only in NORMAL unless noted otherwise.

since the intention is to remove state specs from individual message descriptions, let's specify them here. STA is mentioned, but not the rest. i can see the following messages which are valid outside of NORMAL: SUP, SID, INF, GPA, PAS, QUI.

[Pretorian]

The state machine described should be considered as best-effort.

i don't like this mention: makes it sound like this state description isn't absolute (which it really is). i understand the meaning (that one should be prepared to receive wrong commands) but would prefer a different phrasing.

Hm, perhaps one can remove that sentence as the same section already describe that implementations shall be prepared to manage this...

The connecting party is known as the client and the other is known as the server (or hub).

confusing. server or hub? i would just leave it as "server" here. imagine if an extension were to allow a "c-c" connection between a client & a hub where the hub is the connecting party...

1. I just added 'hub' as that's used elsewhere, perhaps the text should entirely use server, even in a client-hub context. 2. A "C-C" doesn't make sense from a C-H perspective... You'd just do a normal IGET/HGET etc.

A command is valid only in NORMAL unless noted otherwise.

since the intention is to remove state specs from individual message descriptions, let's specify them here. STA is mentioned, but not the rest. i can see the following messages which are valid outside of NORMAL: SUP, SID, INF, GPA, PAS, QUI.

Well, my intention was to keep each message's "State: IDENTIFY, NORMAL", just remove all the descriptive text regarding state. From that perspective I think the sentence shall be kept. Potentially we could add a "State: NORMAL" to all other commands. All extensions must be accordingly updated to indicate that they are valid in state NORMAL (unless they do so already). Otherwise, how about something like:

Messages are valid in the following states.
|PROTOCOL |SUP, SID, STA
|IDENTIFY |INF, STA
|NORMAL |INF, STA, GET, SND