hyperi-rustlib 2.8.9

There's plenty of sage advice out there about how to run Rust services in production at scale — config cascades, structured logging, masking secrets, multi-backend secrets management, Prometheus, OpenTelemetry, Kafka transports, tiered disk-spillover sinks, adaptive worker pools, graceful shutdown — but almost none of it as code you can just install and use. This is that code. Opinionated, drop-in, working out of the box. The patterns from blog posts, watercooler chats and beers with your Google mates as actual library — not a framework you assemble from twenty crates and 8 weeks of munging.
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

// Project:   hyperi-rustlib
// File:      src/governor/mod.rs
// Purpose:   Unified self-regulation pressure governor
// Language:  Rust
//
// License:   BUSL-1.1
// Copyright: (c) 2026 HYPERI PTY LIMITED

//! Unified self-regulation governor.
//!
//! Combines a set of [`PressureSource`]s into a single normalised
//! [`level`](UnifiedPressure::level) and a hysteretic
//! [`should_hold`](UnifiedPressure::should_hold) latch that downstream
//! stages consult to decide whether to pause inbound work. Feature-gated
//! (`governor`) and **ON by default** (opt-out `self_regulation.enabled =
//! false`).
//!
//! The pieces: [`UnifiedPressure`] (the latch over the sources),
//! [`InboundGate`] (turns the latch into pause/resume EDGES on the inbound
//! source -- never the sink), [`ByteBudgetController`] (the AIMD lever sizing
//! the streaming sub-block budget), [`SelfRegulationConfig`] (the cascade
//! `self_regulation` section), and [`SelfRegulationGovernor`] (the built
//! bundle the runtime threads into transports + driver).
//!
//! Full picture in the docs: `docs/SELF-REGULATION.md` (the three brains --
//! memory is the HARD source of truth, CPU deliberately dropped),
//! `docs/BACKPRESSURE.md` (gate the source, never the sink), and
//! `docs/KAFKA-PATH.md` (the three batch sizes + the rho ~ 0.7 loop).
//!
//! # Design invariants
//!
//! - **HARD signals are never masked.** A HARD source (e.g. the memory
//!   guard) contributes its raw reading to the level with no weight applied.
//!   A saturated SOFT signal can never lower the level below what the HARD
//!   signal demands, nor can a missing HARD signal be hidden by a busy SOFT
//!   one. This is the never-OOM guarantee: the memory signal always gets
//!   through.
//! - **SOFT signals are weighted.** Each SOFT source's reading is scaled by
//!   its [`weight`](PressureSource::weight) before competing for the level.
//!   A low-weight SOFT source at full saturation cannot force a hold the
//!   HARD signal would not.
//! - **Hysteresis prevents flapping.** The latch arms at `pause_above` and
//!   releases at `resume_below`; between the two it holds its current state,
//!   so a reading oscillating around a single threshold cannot rapidly
//!   toggle pause/resume.
//!
//! New source kinds (e.g. a future CPU source) plug in via
//! [`UnifiedPressure::add_source`] with zero change to the gate API.

mod budget;
mod config;
mod gate;
mod runtime;
mod source;

pub use budget::{ByteBudgetConfig, ByteBudgetController};
pub use config::{SelfRegulationConfig, SelfRegulationProfile};
pub use gate::{Admit, GateActuator, InboundGate, NoopActuator, ObservingActuator};
pub use runtime::SelfRegulationGovernor;
pub use source::{
    Hysteresis, MemoryPressureSource, Pressure, PressureSource, UnifiedPressure,
    UnifiedPressureSnapshot,
};