hiero-ledger · andrewb1269 · Nov 4, 2025 · Oct 16, 2025 · Oct 20, 2025 · Oct 20, 2025
@@ -76,8 +76,8 @@
       <DefaultRolloverStrategy max="10"/>
     </RollingFile>
 
-    <RollingFile name="BlockNodeCommsFile" fileName="output/blocknode-comms.log"
-               filePattern="output/blocknode-comms-%i.log">
+    <RollingFile name="BlockNodeCommsFile" fileName="output/block-node-comms.log"
+               filePattern="output/block-node-comms-%i.log">
       <PatternLayout>
           <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %-4L %c{1} - [%t] %m{nolookups}%n</pattern>
       </PatternLayout>

@@ -74,8 +74,8 @@
       <DefaultRolloverStrategy max="10"/>
     </RollingFile>
 
-    <RollingFile name="BlockNodeCommsFile" fileName="output/blocknode-comms.log"
-               filePattern="output/blocknode-comms-%i.log">
+    <RollingFile name="BlockNodeCommsFile" fileName="output/block-node-comms.log"
+               filePattern="output/block-node-comms-%i.log">
       <PatternLayout>
           <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %-4L %c{1} - [%t] %m{nolookups}%n</pattern>
       </PatternLayout>

@@ -82,8 +82,8 @@
       <DefaultRolloverStrategy max="10"/>
     </RollingFile>
 
-    <RollingFile name="BlockNodeCommsFile" fileName="output/blocknode-comms.log"
-               filePattern="output/blocknode-comms-%i.log">
+    <RollingFile name="BlockNodeCommsFile" fileName="output/block-node-comms.log"
+               filePattern="output/block-node-comms-%i.log">
       <PatternLayout>
           <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %-4L %c{1} - [%t] %m{nolookups}%n</pattern>
       </PatternLayout>

@@ -82,8 +82,8 @@
       <DefaultRolloverStrategy max="10"/>
     </RollingFile>
 
-    <RollingFile name="BlockNodeCommsFile" fileName="output/blocknode-comms.log"
-               filePattern="output/blocknode-comms-%i.log">
+    <RollingFile name="BlockNodeCommsFile" fileName="output/block-node-comms.log"
+               filePattern="output/block-node-comms-%i.log">
       <PatternLayout>
           <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %-4L %c{1} - [%t] %m{nolookups}%n</pattern>
       </PatternLayout>

@@ -82,8 +82,8 @@
       <DefaultRolloverStrategy max="10"/>
     </RollingFile>
 
-    <RollingFile name="BlockNodeCommsFile" fileName="output/blocknode-comms.log"
-               filePattern="output/blocknode-comms-%i.log">
+    <RollingFile name="BlockNodeCommsFile" fileName="output/block-node-comms.log"
+               filePattern="output/block-node-comms-%i.log">
       <PatternLayout>
           <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %-4L %c{1} - [%t] %m{nolookups}%n</pattern>
       </PatternLayout>

@@ -82,8 +82,8 @@
       <DefaultRolloverStrategy max="10"/>
     </RollingFile>
 
-    <RollingFile name="BlockNodeCommsFile" fileName="output/blocknode-comms.log"
-                   filePattern="output/blocknode-comms-%i.log">
+    <RollingFile name="BlockNodeCommsFile" fileName="output/block-node-comms.log"
+                   filePattern="output/block-node-comms-%i.log">
       <PatternLayout>
           <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %-4L %c{1} - [%t] %m{nolookups}%n</pattern>
       </PatternLayout>

@@ -82,8 +82,8 @@
       <DefaultRolloverStrategy max="10"/>
     </RollingFile>
 
-    <RollingFile name="BlockNodeCommsFile" fileName="output/blocknode-comms.log"
-               filePattern="output/blocknode-comms-%i.log">
+    <RollingFile name="BlockNodeCommsFile" fileName="output/block-node-comms.log"
+               filePattern="output/block-node-comms-%i.log">
       <PatternLayout>
           <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %-4L %c{1} - [%t] %m{nolookups}%n</pattern>
       </PatternLayout>

@@ -6,7 +6,7 @@
 2. [Definitions](#definitions)
 3. [Component Responsibilities](#component-responsibilities)
 4. [Component Interaction](#component-interaction)
-5. [State Management](#state-management)
+5. [Lifecycle](#lifecycle)
 6. [State Machine Diagrams](#state-machine-diagrams)
 7. [Error Handling](#error-handling)
 
@@ -29,6 +29,7 @@ It manages connection state, handles communication, and reports errors to the `B
 
 - Establish and maintain the connection transport.
 - Handle incoming and outgoing message flow.
+- Detect unresponsive block nodes via configurable timeouts on pipeline operations.
 - Report connection errors promptly.
 - Coordinate with `BlockNodeConnectionManager` on lifecycle events.
 - Notify the block buffer when a block has been acknowledged and therefore eligible to be pruned.
@@ -129,6 +130,7 @@ stateDiagram-v2
     ACTIVE --> CLOSING : ResendBlock unavailable
     ACTIVE --> CLOSING : gRPC onError
     ACTIVE --> CLOSING : Stream failure
+    ACTIVE --> CLOSING : Pipeline operation timeout
     ACTIVE --> CLOSING : Manual close
     ACTIVE --> ACTIVE : BlockAcknowledgement
     ACTIVE --> ACTIVE : SkipBlock
@@ -227,4 +229,49 @@ The connection implements a configurable rate limiting mechanism for EndOfStream
 
 <dt>blockNode.maxRequestDelay</dt>
 <dd>The maximum amount of time between attempting to send block items to a block node, regardless of the number of items ready to send.</dd>
+
+<dt>pipelineOperationTimeout</dt>
+<dd>The maximum duration allowed for pipeline onNext() and onComplete() operations before considering the block node unresponsive. Default: 30 seconds.</dd>
 </dl>
+
+### Pipeline Operation Timeout
+
+To detect unresponsive block nodes during message transmission and connection establishment, the connection implements configurable timeouts for pipeline operations.
+
+#### Timeout Behavior
+
+Pipeline operations (`onNext()`, `onComplete()`, and pipeline creation) are potentially blocking I/O operations that are executed on a dedicated virtual thread executor with timeout enforcement using `Future.get(timeout)`. The executor is provided via dependency injection through the constructor, allowing for flexible configuration and easier testing.
+
+- **Pipeline creation timeout**: When establishing the gRPC connection via `createRequestPipeline()`, both the gRPC client creation and bidirectional stream setup are executed with timeout protection. If the operation does not complete within the configured timeout period:
+  - The Future is cancelled to interrupt the blocked operation
+  - The timeout metric is incremented
+  - A `RuntimeException` is thrown with the underlying `TimeoutException`
+  - The connection remains in UNINITIALIZED state
+  - The connection manager's error handling will schedule a retry with exponential backoff
+- **onNext() timeout**: When sending block items via `sendRequest()`, the operation is submitted to the connection's dedicated executor and the calling thread blocks waiting for completion with a timeout. If the operation does not complete within the configured timeout period:
+  - The Future is cancelled to interrupt the blocked operation
+  - The timeout metric is incremented
+  - `handleStreamFailure()` is triggered (only if connection is still ACTIVE)
+  - The connection follows standard failure handling with exponential backoff retry
+  - The connection manager will select a different block node for the next attempt if one is available
+  - `TimeoutException` is caught and handled internally
+- **onComplete() timeout**: When closing the stream via `closePipeline()`, the operation is submitted to the same dedicated executor with the same timeout mechanism. If the operation does not complete within the configured timeout period:
+  - The Future is cancelled to interrupt the blocked operation
+  - The timeout metric is incremented
+  - Since the connection is already in CLOSING state, only the timeout is logged
+  - The connection completes the close operation normally
+
+**Note**: The dedicated executor (typically a virtual thread executor in production) is provided during construction and properly shut down when the connection closes with a 5-second grace period for termination, ensuring no resource leaks. If tasks don't complete within the grace period, `shutdownNow()` is called to forcefully terminate them.
+
+#### Exception Handling
+
+The implementation handles multiple exception scenarios across all timeout-protected operations:
+- **TimeoutException**: Pipeline operation exceeded the timeout - triggers failure handling for `onNext()` and pipeline creation, logged for `onComplete()`
+- **InterruptedException**: Thread was interrupted while waiting - interrupt status is restored via `Thread.currentThread().interrupt()` before propagating the exception (for `onNext()` and pipeline creation) or logging it (for `onComplete()` and executor shutdown)
+- **ExecutionException**: Error occurred during pipeline operation execution - the underlying cause is unwrapped and re-thrown (for `onNext()` and pipeline creation) or logged (for `onComplete()`)
+
+All exception scenarios include appropriate DEBUG-level logging with context information to aid in troubleshooting.
+
+#### Metrics
+
+A new metric `conn_pipelineOperationTimeout` tracks the total number of timeout events for pipeline creation, `onNext()`, and `onComplete()` operations, enabling operators to monitor block node responsiveness and connection establishment issues.