Pr/step 1 init setup & ADR 001: Relationship State Machine

[Jackylee2233]

ADR 001: Relationship State Machine

Status

Proposed

Context

The current TSP SDK implementation lacks a formal state machine for managing relationship lifecycles. This leads to several issues:

1. Undefined States: The ReverseUnidirectional status is defined but rarely used, leading to ambiguity when a node receives a relationship request.
2. Concurrency Issues: If two nodes request a relationship with each other simultaneously, both end up in a Unidirectional state, with no clear resolution path.
3. No Timeouts: There is no mechanism to handle lost messages or unresponsive peers during the handshake process.
4. Idempotency: Duplicate control messages are not handled consistently.

Decision

We will implement a formal RelationshipMachine to govern state transitions.

1. State Machine Definition

The state machine will transition based on RelationshipEvents.

Current State	Event	New State	Action/Notes
Unrelated	SendRequest	Unidirectional	Store thread_id
Unrelated	ReceiveRequest	ReverseUnidirectional	Store thread_id
Unidirectional	ReceiveAccept	Bidirectional	Verify thread_id matches.
ReverseUnidirectional	SendAccept	Bidirectional	Verify thread_id matches.
Bidirectional	SendCancel	Unrelated
Bidirectional	ReceiveCancel	Unrelated
Unidirectional	SendRequest	Unidirectional	Idempotent (retransmission)
Unidirectional	ReceiveRequest	Conflict Resolution	See Concurrency Handling

2. Concurrency Handling

When a node in Unidirectional state (sent a request) receives a RequestRelationship from the target (meaning they also sent a request):

• Compare thread_ids: The request with the lower thread_id (lexicographically) wins.
• If my thread_id < their thread_id: I ignore their request (or reject it). I expect them to accept my request.
• If my thread_id > their thread_id: I accept their request. I cancel my pending request state and transition to ReverseUnidirectional (effectively accepting their flow).

3. Timeout & Retry

• Timeout: A request_timeout field will be added to VidContext. If a Unidirectional state persists beyond the timeout (e.g., 60s), it transitions back to Unrelated.
• Retry: Before timing out, the system may attempt retransmissions.

4. Idempotency

• Duplicate Request: If in ReverseUnidirectional or Bidirectional and receive the same RequestRelationship (same thread_id), ignore it or resend the previous response.
• Duplicate Accept: If in Bidirectional and receive AcceptRelationship with the same thread_id, ignore it.

Consequences

• Robustness: Relationship establishment will be reliable under network jitter and concurrency.
• Complexity: The store.rs logic will become more complex.
• Breaking Changes: Existing tests that manually manipulate state might fail and need updating to respect the state machine.

[wenjing]

Thanks @Jackylee2233 for the PR. Here are my preliminary feedback for each of the issues separately. Let's assume the local endpoint is Alice and the remote endpoint is Bob.

(1) the state "ReverseUnidirectional".
This state means Alice received a relationship request from Bob and is valid. The SDK passes this up to the application layer to decide what to do next. The application layer may decide to respond to accept, thereby creating a bidirectional relationship, but it can also stay silent for a long time (to make decisions) or forever. It is not an invalid state to be in. (Note: relationships are NOT connections). The SDK does not provide a convenient function for the application to transition to this state. That can be improved. But the SDK does provide a generic state setting function that the application can use. Also, another problem is that the testing code does not exercise this path. That's something to improve as well. Baseline, this state is valid but the two improvements are good to have.

(2) Concurrency when two relationship requests collide <A,B> and <B,A>, if both use the same VID pair exactly.
This is a problem that the current code deviates from the Spec:
The official TSP Specification handles this in Section 7.1.3: Race Condition of TSP_RFI:
"The rule is that the TSP_RFI with the lower value of Digest using lexicographical comparison. Both endpoints will keep the TSP_RFI with lower Digest and discard the other."
So fixing this is important.

(3) Timeout from Unidirectional to Unrelated
If I'm reading your writeup correct, the timeout is to automatically move from Unidirectional state to Unrelated state. If so, then it is a misunderstanding. A Unidirectional state is not necessarily a temporary state. It can be a long term or even forever state. Such a timeout therefore is not correct. However, if the application layer wants such a timeout, it can of course implement it. The SDK can't know for sure what the application wants and should not implement such a timeout. By the way, a relationship is just a local metadata entry, it does NOT consume connection resources - if we assume the HTTP or TCP has timeout to teardown unused connections. Again, that's the transport layer issue we could double check.

(4) Idempotency in handling TSP relationship messages
It seems to me the only potential issue is when the local endpoint receives AcceptRelationship when it's already in Bidirectional state. If so, then it's not a big issue. Current code returns an error code to the application, but that's ok, it's up to the application to handle that. The SDK does not do anything else. Maybe we could drop that error code or change to an alert only or silently drop. It seems not too bad to alert the application of duplicate accepts - unless we see more serious issues.

Final note: Could you please rewrite commit messages in English to be consistent with the rest of the project? AI translates are perfectly ok.