hyperion-framework 0.5.0

A lightweight component-based TCP framework for building service-oriented Rust applications with CLI control, async messaging, and lifecycle management.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

// -------------------------------------------------------------------------------------------------
// Hyperion Framework
// https://github.com/robert-hannah/hyperion-framework
//
// A lightweight component-based TCP framework for building service-oriented Rust applications with
// CLI control, async messaging, and lifecycle management.
//
// Copyright 2025 Robert Hannah
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// -------------------------------------------------------------------------------------------------

// Standard =
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};

// Package
use tokio::sync::Notify;

// Local
use crate::containerisation::container_state::ContainerState;

/// Called by the receiver watchdog when no heartbeat request has arrived within the timeout window.
pub trait HeartbeatTimeoutHandler: Send + Sync + 'static {
    fn on_timeout(&self);
}

/// Called by the sender on every heartbeat tick where a target has not responded within
/// `response_timeout_ms`. Fires repeatedly while the target remains silent.
pub trait HeartbeatMissedHandler: Send + Sync + 'static {
    fn on_missed(&self, target: &str);
}

/// Wraps a `FnMut(&str)` closure as a `HeartbeatMissedHandler`.
pub struct FnMissedHandler(Box<dyn Fn(&str) + Send + Sync>);

impl FnMissedHandler {
    pub fn new(f: impl Fn(&str) + Send + Sync + 'static) -> Self {
        Self(Box::new(f))
    }
}

impl HeartbeatMissedHandler for FnMissedHandler {
    fn on_missed(&self, target: &str) {
        (self.0)(target);
    }
}

/// Wraps a closure as a `HeartbeatTimeoutHandler`, allowing per-component custom behaviour to be
/// defined inline in `main.rs` without needing a dedicated struct.
pub struct FnHandler(Box<dyn Fn() + Send + Sync>);

impl FnHandler {
    pub fn new(f: impl Fn() + Send + Sync + 'static) -> Self {
        Self(Box::new(f))
    }
}

impl HeartbeatTimeoutHandler for FnHandler {
    fn on_timeout(&self) {
        (self.0)();
    }
}

/// Convenience handler: initiates a graceful container shutdown.
pub struct ShutdownOnTimeout {
    container_state: Arc<AtomicUsize>,
    container_state_notify: Arc<Notify>,
}

impl ShutdownOnTimeout {
    pub fn new(container_state: Arc<AtomicUsize>, container_state_notify: Arc<Notify>) -> Self {
        Self {
            container_state,
            container_state_notify,
        }
    }
}

impl HeartbeatTimeoutHandler for ShutdownOnTimeout {
    fn on_timeout(&self) {
        log::warn!(
            "HeartbeatReceiver: timeout — no request received within window. Initiating shutdown."
        );
        self.container_state
            .store(ContainerState::ShuttingDown as usize, Ordering::SeqCst);
        self.container_state_notify.notify_waiters();
    }
}