[ADC 1.0.2] State in ADC

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.

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.

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.

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).

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).

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.

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?

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.

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.

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.

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…

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.

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

  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.

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

sounds good.

i was thinking of an extension that could let a hub “test ports” or check file lists without requiring a bot. the hub would be allowed to send a RCM and establish a C-C-like conn with the client… but that’s going far and i’m not sure it even makes sense. :slight_smile:

i thought you were planning on removing these “States: X” statements, in which case a clarification would have been necessary in this new section on states. as it is, such a table can easily be derived from other parts of the spec; but it can’t hurt to have it as a bonus.
i have no opinion on the “all NORMAL-only except” clause other than the fact that it is easy to miss.

I will be pushing the following to the SVN, if no one objects, on the coming Monday the 14th.

Three changes compared to the previous block-quote; removed the ‘best-effort’ sentence, removed the “NORMAL is default unless noted” and added the command/state matrix.

State management

ADC defines a state machine to control flow and processing of messages. 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 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.

BASE commands and state matrix:
State Commands
|PROTOCOL |STA, SUP, SID
|IDENTIFY |STA, INF, QUI
|VERIFY |STA, GPA, PAS, QUI
|NORMAL |STA, SUP, INF, MSG, SCH, RES, CTM, RCM, QUI, GET, GFI, SND

My idea is to replace the items 5.1 and 5.2 (Client-Hub/Client communication) with “5.1 State management”.

In addition to the above new block, the following (explicit) content will be removed;

BASE Messages: The server always controls state transitions.



Client-hub communication and Client-client communication



INF: When the hub receives this message in PROTOCOL state, it should reply in kind, assign a SID to the client, optionally send an INF about itself, and move to the IDENTIFY state. When the server receives this message in a client-client connection in the PROTOCOL state, it should reply in kind, send an INF about itself, and move to the IDENTIFY state.



SID: The hub must send this command after SUP but before INF in the PROTOCOL state. The client, when it receives it, should send an INF about itself.



INF: When a hub receives this message in the IDENTIFY state, it should verify the PD and ID fields, and proceed to the VERIFY state by sending a PAS request or NORMAL state by sending its own INF (unless it already did so previously), then the INF of all connected clients in NORMAL state, and last the INF of the connecting client. When the server receives this during client-client communication in IDENTIFY state, it should verify the ID and TO fields, send an INF about itself and pass to the NORMAL state.



PAS: When validated, this transitions the server into NORMAL state.



SND: Transitions to DATA state […] and then will transition back to NORMAL state

I will add a “State: X” to each message type so that it is explicit always.

In 6.2. (Client-Client connection), the example will be changed: the two INFs will switch order. (Client sends INF first.)

I have not received any complaints and have as such pushed these changes to the SVN.

This is now pushed to ADC 1.0.2. I am closing this thread since it is implemented; please start another thread if you want to discuss it further.