Skip to content

qkc/slave 06: add PeerConn, Dispatcher, and peer routing - #39

Open
iteyelmp wants to merge 27 commits into
slave-05from
slave-06
Open

qkc/slave 06: add PeerConn, Dispatcher, and peer routing#39
iteyelmp wants to merge 27 commits into
slave-05from
slave-06

Conversation

@iteyelmp

@iteyelmp iteyelmp commented Jul 15, 2026

Copy link
Copy Markdown

Summary

This PR implements PeerConn, the communication-layer abstraction for virtual peer-to-peer connections on the slave, corresponding to Python's PeerShardConnection. A PeerConn represents one external cluster peer on one branch. It provides typed outbound commands/RPCs, inbound dispatch through the PeerHandler interface, and the peer-frame routing support required in MasterConn.

This PR is communication-layer only. Shard ownership, registration, creation/destruction, and cascade cleanup are intentionally left to the runtime layer.

Design

  • Virtual, socketless connection: A PeerConn owns no TCP socket. All traffic is tunneled through the shared MasterConn via virtualTransport, which stamps outbound frames with the connection's (branch, cluster_peer_id) and receives inbound frames forwarded by MasterConn.
  • Connection-level RPC state: Each PeerConn has its own RPC ID namespace and pending-request state, so multiple peer connections sharing one MasterConn remain independent.
  • Delegated business handling: Inbound commands and RPC requests are dispatched through the injected PeerHandler; PeerConn itself contains no shard/business logic.
  • Decoupled routing: PeerResolver abstracts peer lookup and branch validation, keeping peer ownership and registry management outside MasterConn.

Review Notes

  • cluster_peer_id == 0 is rejected at construction. In the Python implementation, 0 is reserved for master-local traffic and is never assigned to a peer connection, but PeerShardConnection does not reject it when constructed; the check only happens when writing a frame. Go validates this invariant at the PeerConn boundary instead, preventing an invalid peer connection from being created in the first place.

  • MasterConnPeerConn cascade cleanup is intentionally not implemented here. PeerConn lifecycle ownership belongs to the runtime layer, which will handle registration, destruction, and cascade cleanup.

  • An invalid forwarding branch closes the MasterConn. routeFrame validates the branch against the global configured shard set. A branch outside that set indicates an invalid frame on the master-slave channel, so the entire MasterConn is closed. A globally valid branch with no locally available PeerConn is instead dropped, matching Python's NULL_CONNECTION behavior.

  • Python permits writes through a locally closed virtual connection; Go intentionally rejects them. This was investigated and confirmed to be a Python lifecycle/cleanup artifact rather than a protocol requirement, so the behavior is deliberately not reproduced.

Full Codex 5.6 review completed.

@iteyelmp
iteyelmp changed the base branch from goshard/base to slave-05 July 16, 2026 09:48
iteyelmp added 2 commits July 16, 2026 17:54
# Conflicts:
#	qkc/cluster/slave/master_conn.go
@iteyelmp iteyelmp changed the title qkc/slave 05: add PeerConn, Dispatcher, and peer routing qkc/slave 06: add PeerConn, Dispatcher, and peer routing Jul 16, 2026
# Conflicts:
#	qkc/cluster/slave/master_conn.go
#	qkc/cluster/slave/master_conn_test.go
# Conflicts:
#	qkc/cluster/slave/master_conn.go
#	qkc/cluster/slave/master_conn_test.go
# Conflicts:
#	qkc/cluster/slave/master_conn.go
# Conflicts:
#	qkc/cluster/slave/master_conn.go
#	qkc/cluster/slave/master_conn_test.go
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant