Module heartbeat 

Composable heartbeat and timeout wrapper for any stream.

HeartbeatStream wraps any Stream<Item = Result<StreamEvent, ApiError>> and adds two behaviours:

1. Heartbeat callbacks — Fires a callback at regular intervals to report elapsed time and timeout status.
2. Hard timeout — Returns an ApiError if the stream exceeds a configured maximum duration.

It does not retry or fall back — that’s StreamHandler’s job. Use this when you need heartbeat/timeout on a stream you’ve already opened.

Architecture

┌────────────────────────────────────┐
│        HeartbeatStream<S>          │
│                                    │
│  poll_next():                      │
│    1. Check heartbeat interval     │
│       └─ fire callback if elapsed  │
│    2. Check hard timeout           │
│       └─ return ApiError if hit    │
│    3. Delegate to inner stream     │
└────────────────────────────────────┘

Quick Start

use loopctl::stream::heartbeat::{HeartbeatStream, HeartbeatConfig, HeartbeatData};
use std::time::Duration;
use std::sync::{Arc, Mutex};

let callbacks = Arc::new(Mutex::new(Vec::new()));
let cb = callbacks.clone();

let config = HeartbeatConfig::new(
    Duration::from_secs(30),  // heartbeat_interval
    Duration::from_secs(600), // timeout
    Box::new(move |data: HeartbeatData| {
        cb.lock().unwrap().push(data.elapsed);
    }),
);

Structs

HeartbeatConfig

Configuration for a HeartbeatStream.

HeartbeatData

Data emitted on each heartbeat callback.

HeartbeatStream

A stream wrapper that emits heartbeat callbacks and enforces a hard timeout.

Type Aliases

HeartbeatCallback

Callback type for heartbeat events.