feat: implement protocol state timeouts (#1235)

Add timeout constants for ChainSync, BlockFetch, TxSubmission, Handshake,
and Keepalive protocols to prevent resource leaks. Values based on
Ouroboros Network Specification with comprehensive unit tests.

Signed-off-by: Chris Gianelloni <wolf31o2@blinklabs.io>

Author: wolf31o2

protocol/PROTOCOL_LIMITS.md

@@ -19,11 +19,18 @@ All limits are based on the [Ouroboros Network Specification](https://ouroboros-
 - `DefaultRecvQueueSize = 50` - Conservative default for receive queue size
 - `MaxPendingMessageBytes = 102400` - Maximum pending message bytes (100KB)
 
+**State timeout constants:**
+- `IdleTimeout = 60s` - Timeout for client to send next request
+- `CanAwaitTimeout = 300s` - Timeout for server to provide next block or await
+- `IntersectTimeout = 5s` - Timeout for server to respond to intersect request
+- `MustReplyTimeout = 300s` - Timeout for server to provide next block
+
 **Enforcement:**
 - Client-side pipeline tracking with disconnect on violation
 - Configuration validation with panic on invalid values
 - Server-side queue size limits enforced by protocol framework
 - Per-state pending message byte limits enforced with connection teardown on violation
+- State transition timeouts enforced with connection teardown on timeout
 
 **Files modified:**
 - `protocol/chainsync/chainsync.go` - Added constants, validation, and documentation
@@ -36,10 +43,16 @@ All limits are based on the [Ouroboros Network Specification](https://ouroboros-
 - `DefaultRecvQueueSize = 256` - Default receive queue size
 - `MaxPendingMessageBytes = 5242880` - Maximum pending message bytes (5MB)
 
+**State timeout constants:**
+- `IdleTimeout = 60s` - Timeout for client to send block range request
+- `BusyTimeout = 5s` - Timeout for server to start batch or respond no blocks
+- `StreamingTimeout = 60s` - Timeout for server to send next block in batch
+
 **Enforcement:**
 - Configuration validation with panic on invalid values
 - Queue size limits enforced by protocol framework
 - Per-state pending message byte limits enforced with connection teardown on violation
+- State transition timeouts enforced with connection teardown on timeout
 
 **Files modified:**
 - `protocol/blockfetch/blockfetch.go` - Added constants, validation, and documentation
@@ -53,15 +66,41 @@ All limits are based on the [Ouroboros Network Specification](https://ouroboros-
 - `DefaultAckLimit = 1000` - Reasonable default for transaction acknowledgments
 - Pending message byte limits: Not enforced (0 = no limit)
 
+**State timeout constants:**
+- `InitTimeout = 30s` - Timeout for client to send init message
+- `IdleTimeout = 300s` - Timeout for server to send tx request when idle
+- `TxIdsBlockingTimeout = 60s` - Timeout for client to reply with tx IDs (blocking)
+- `TxIdsNonblockingTimeout = 30s` - Timeout for client to reply with tx IDs (non-blocking)
+- `TxsTimeout = 120s` - Timeout for client to reply with full transactions
+
 **Enforcement:**
 - Server-side validation with disconnect on excessive request counts
 - Client-side validation with disconnect on excessive received counts
+- State transition timeouts enforced with connection teardown on timeout
 
 **Files modified:**
 - `protocol/txsubmission/txsubmission.go` - Added constants and documentation
 - `protocol/txsubmission/server.go` - Added request count validation
 - `protocol/txsubmission/client.go` - Added received count validation
 
+### Handshake Protocol
+
+**State timeout constants:**
+- `ProposeTimeout = 5s` - Timeout for client to propose protocol version
+- `ConfirmTimeout = 5s` - Timeout for server to confirm or refuse version
+
+**Files modified:**
+- `protocol/handshake/handshake.go` - Added timeout constants and StateMap integration
+
+### Keepalive Protocol
+
+**State timeout constants:**
+- `ClientTimeout = 60s` - Timeout for client to send keepalive request
+- `ServerTimeout = 10s` - Timeout for server to respond to keepalive
+
+**Files modified:**
+- `protocol/keepalive/keepalive.go` - Added timeout constants and StateMap integration
+
 ## Protocol Violation Errors
 
 **New error types defined in `protocol/error.go`:**
@@ -74,10 +113,16 @@ These errors cause connection termination as per the network specification.
 
 ## Other Mini-Protocols
 
-The following protocols were evaluated and determined not to need additional queue limits:
-- **KeepAlive** - Simple ping/pong protocol with minimal state
-- **LocalStateQuery** - Request-response protocol with no pipelining
-- **LocalTxSubmission** - Simple request-response for single transaction submission
+All remaining protocols have appropriate timeout implementations:
+
+- **LocalStateQuery** - Has AcquireTimeout (5s) and QueryTimeout (180s) for database queries
+- **LocalTxMonitor** - Has AcquireTimeout (5s) and QueryTimeout (30s) for mempool monitoring  
+- **LocalTxSubmission** - Has Timeout (30s) for local transaction submission
+- **PeerSharing** - Has Timeout (5s) for peer discovery requests
+- **LeiosFetch** - Has Timeout (5s) for Leios block/transaction/vote fetching
+- **LeiosNotify** - Has Timeout (60s) for Leios block/vote notifications
+- **Handshake** - Has ProposeTimeout (5s) and ConfirmTimeout (5s) for protocol negotiation
+- **Keepalive** - Has ClientTimeout (60s) and ServerTimeout (10s) for connection health
 
 ## Validation and Testing
 
@@ -86,19 +131,44 @@ The following protocols were evaluated and determined not to need additional que
 - Tests configuration validation and panic behavior  
 - Verifies protocol violation errors are defined
 - Ensures default values are reasonable and within limits
+- Comprehensive timeout validation for all 11 mini-protocols
+- Verifies StateMap entries use correct timeout constants
+
+## Protocol State Timeouts
+
+### Implementation
+
+Each protocol state can define a timeout value that is enforced by the protocol framework. When a state transition takes too long, the connection is automatically terminated to prevent hanging connections and ensure protocol compliance.
+
+### Timeout Values
+
+The timeout values are based on the Ouroboros Network Specification and real-world network conditions:
+
+- **Short timeouts (5-30s)**: For rapid protocol handshakes and responses
+- **Medium timeouts (60-120s)**: For normal message exchanges and client requests  
+- **Long timeouts (300s)**: For waiting on new blocks or mempool queries
+
+### Timeout Behavior
+
+- Timeouts are set when entering a state with `StateMapEntry.Timeout > 0`
+- If no state transition occurs within the timeout period, the protocol terminates
+- Connection teardown includes proper error logging for debugging
+- Terminal states (`AgencyNone`) do not have timeouts
 
 ## Behavior Changes
 
 **Before:**
 - No enforced limits on pipeline depth or queue sizes
 - Potential for memory exhaustion from excessive pipelining
 - No disconnect on protocol violations
+- No state transition timeouts
 
 **After:**
 - Strict limits enforced as per network specification
 - Automatic connection termination on limit violations
 - Comprehensive logging of violations before disconnect
 - Configuration validation prevents invalid setups
+- State transition timeouts prevent hanging connections
 
 ## Usage Examples
 

protocol/blockfetch/blockfetch.go

@@ -40,6 +40,7 @@ var StateMap = protocol.StateMap{
 	StateIdle: protocol.StateMapEntry{
 		Agency:                  protocol.AgencyClient,
 		PendingMessageByteLimit: MaxPendingMessageBytes,
+		Timeout:                 IdleTimeout, // Timeout for client to send block range request
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:  MessageTypeRequestRange,
@@ -54,6 +55,7 @@ var StateMap = protocol.StateMap{
 	StateBusy: protocol.StateMapEntry{
 		Agency:                  protocol.AgencyServer,
 		PendingMessageByteLimit: MaxPendingMessageBytes,
+		Timeout:                 BusyTimeout, // Timeout for server to start batch or respond no blocks
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:  MessageTypeStartBatch,
@@ -68,6 +70,7 @@ var StateMap = protocol.StateMap{
 	StateStreaming: protocol.StateMapEntry{
 		Agency:                  protocol.AgencyServer,
 		PendingMessageByteLimit: MaxPendingMessageBytes,
+		Timeout:                 StreamingTimeout, // Timeout for server to send next block in batch
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:  MessageTypeBlock,
@@ -107,6 +110,13 @@ const (
 	MaxPendingMessageBytes = 5242880 // Max pending message bytes (5MB)
 )
 
+// Protocol state timeout constants per network specification
+const (
+	IdleTimeout      = 60 * time.Second // Timeout for client to send block range request
+	BusyTimeout      = 5 * time.Second  // Timeout for server to start batch or respond no blocks
+	StreamingTimeout = 60 * time.Second // Timeout for server to send next block in batch
+)
+
 // Callback context
 type CallbackContext struct {
 	ConnectionId connection.ConnectionId

protocol/chainsync/chainsync.go

@@ -45,6 +45,7 @@ var StateMap = protocol.StateMap{
 	stateIdle: protocol.StateMapEntry{
 		Agency:                  protocol.AgencyClient,
 		PendingMessageByteLimit: MaxPendingMessageBytes,
+		Timeout:                 IdleTimeout, // Timeout for client to send next request
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:   MessageTypeRequestNext,
@@ -64,6 +65,7 @@ var StateMap = protocol.StateMap{
 	stateCanAwait: protocol.StateMapEntry{
 		Agency:                  protocol.AgencyServer,
 		PendingMessageByteLimit: MaxPendingMessageBytes,
+		Timeout:                 CanAwaitTimeout, // Timeout for server to provide next block or await
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:   MessageTypeRequestNext,
@@ -99,6 +101,7 @@ var StateMap = protocol.StateMap{
 	stateIntersect: protocol.StateMapEntry{
 		Agency:                  protocol.AgencyServer,
 		PendingMessageByteLimit: MaxPendingMessageBytes,
+		Timeout:                 IntersectTimeout, // Timeout for server to respond to intersect request
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:  MessageTypeIntersectFound,
@@ -113,6 +116,7 @@ var StateMap = protocol.StateMap{
 	stateMustReply: protocol.StateMapEntry{
 		Agency:                  protocol.AgencyServer,
 		PendingMessageByteLimit: MaxPendingMessageBytes,
+		Timeout:                 MustReplyTimeout, // Timeout for server to provide next block
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:   MessageTypeRollForward,
@@ -224,6 +228,14 @@ const (
 	MaxPendingMessageBytes = 102400 // Max pending message bytes (100KB)
 )
 
+// Protocol state timeout constants per network specification
+const (
+	IdleTimeout      = 60 * time.Second  // Timeout for client to send next request
+	CanAwaitTimeout  = 300 * time.Second // Timeout for server to provide next block or await
+	IntersectTimeout = 5 * time.Second   // Timeout for server to respond to intersect request
+	MustReplyTimeout = 300 * time.Second // Timeout for server to provide next block
+)
+
 // Callback context
 type CallbackContext struct {
 	ConnectionId connection.ConnectionId

protocol/handshake/handshake.go

@@ -28,6 +28,12 @@ const (
 	ProtocolId   = 0
 )
 
+// Protocol state timeout constants per network specification
+const (
+	ProposeTimeout = 5 * time.Second // Timeout for client to propose versions
+	ConfirmTimeout = 5 * time.Second // Timeout for server to accept or refuse versions
+)
+
 var (
 	statePropose = protocol.NewState(1, "Propose")
 	stateConfirm = protocol.NewState(2, "Confirm")
@@ -37,7 +43,8 @@ var (
 // Handshake protocol state machine
 var StateMap = protocol.StateMap{
 	statePropose: protocol.StateMapEntry{
-		Agency: protocol.AgencyClient,
+		Agency:  protocol.AgencyClient,
+		Timeout: ProposeTimeout, // Timeout for client to propose versions
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:  MessageTypeProposeVersions,
@@ -46,7 +53,8 @@ var StateMap = protocol.StateMap{
 		},
 	},
 	stateConfirm: protocol.StateMapEntry{
-		Agency: protocol.AgencyServer,
+		Agency:  protocol.AgencyServer,
+		Timeout: ConfirmTimeout, // Timeout for server to accept or refuse versions
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:  MessageTypeAcceptVersion,

protocol/keepalive/keepalive.go

@@ -32,6 +32,12 @@ const (
 	DefaultKeepAliveTimeout = 10
 )
 
+// Protocol state timeout constants per network specification
+const (
+	ClientTimeout = 60 * time.Second // Timeout for client to send keep-alive
+	ServerTimeout = 10 * time.Second // Timeout for server to respond to keep-alive
+)
+
 var (
 	StateClient = protocol.NewState(1, "Client")
 	StateServer = protocol.NewState(2, "Server")
@@ -40,7 +46,8 @@ var (
 
 var StateMap = protocol.StateMap{
 	StateClient: protocol.StateMapEntry{
-		Agency: protocol.AgencyClient,
+		Agency:  protocol.AgencyClient,
+		Timeout: ClientTimeout, // Timeout for client to send keep-alive
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:  MessageTypeKeepAlive,
@@ -53,7 +60,8 @@ var StateMap = protocol.StateMap{
 		},
 	},
 	StateServer: protocol.StateMapEntry{
-		Agency: protocol.AgencyServer,
+		Agency:  protocol.AgencyServer,
+		Timeout: ServerTimeout, // Timeout for server to respond to keep-alive
 		Transitions: []protocol.StateTransition{
 			{
 				MsgType:  MessageTypeKeepAliveResponse,