praxis-proxy-protocol 0.7.3

HTTP, TCP, and protocol adapters for Praxis
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

// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2026 Praxis Contributors

//! Process-wide connection limit.
//!
//! Complements per-listener `max_connections` with a global
//! ceiling across all listeners. Initialized once at server
//! startup from [`RuntimeConfig::max_connections`].
//!
//! [`RuntimeConfig::max_connections`]: praxis_core::config::RuntimeConfig::max_connections

use std::sync::{Arc, OnceLock};

use tokio::sync::{OwnedSemaphorePermit, Semaphore};

// -----------------------------------------------------------------------------
// Global Semaphore
// -----------------------------------------------------------------------------

/// Process-wide connection semaphore.
static GLOBAL_LIMIT: OnceLock<Arc<Semaphore>> = OnceLock::new();

/// Initialize the global connection limit.
///
/// Called once during server startup. Subsequent calls are no-ops.
pub fn init_global_limit(max: usize) {
    GLOBAL_LIMIT.get_or_init(|| Arc::new(Semaphore::new(max)));
}

/// Try to acquire a global connection permit.
///
/// Returns one of three states:
///
/// - `(false, None)` — no global limit is configured.
/// - `(false, Some(permit))` — permit was acquired.
/// - `(true, None)` — limit is exhausted.
pub fn try_acquire_global() -> (bool, Option<OwnedSemaphorePermit>) {
    let Some(sem) = GLOBAL_LIMIT.get() else {
        return (false, None);
    };

    if let Ok(permit) = Arc::clone(sem).try_acquire_owned() {
        (false, Some(permit))
    } else {
        (true, None)
    }
}

// -----------------------------------------------------------------------------
// Tests
// -----------------------------------------------------------------------------

#[cfg(test)]
#[expect(clippy::allow_attributes, reason = "blanket test suppressions")]
#[allow(clippy::unwrap_used, clippy::expect_used, clippy::indexing_slicing, reason = "tests")]
mod tests {
    use super::*;

    #[test]
    fn global_limit_lifecycle() {
        let (exceeded, permit) = try_acquire_global();
        assert!(!exceeded, "uninitialized global should not report exceeded");
        assert!(permit.is_none(), "uninitialized global should return no permit");

        init_global_limit(2);

        let (exceeded, first) = try_acquire_global();
        assert!(!exceeded, "first acquire should not exceed limit");
        let first = first.expect("first acquire should return a permit");

        let (exceeded, second) = try_acquire_global();
        assert!(!exceeded, "second acquire should not exceed limit");
        let second = second.expect("second acquire should return a permit");

        let (exceeded, permit) = try_acquire_global();
        assert!(exceeded, "third acquire should exceed limit of 2");
        assert!(permit.is_none(), "exhausted limit should return no permit");

        init_global_limit(100);

        let (exceeded, still_none) = try_acquire_global();
        assert!(exceeded, "limit should still be 2 after re-init");
        assert!(still_none.is_none(), "re-init should be a no-op");

        drop(first);

        let (exceeded, reclaimed) = try_acquire_global();
        assert!(!exceeded, "acquire after drop should not exceed limit");
        assert!(reclaimed.is_some(), "released slot should yield a permit");

        drop(second);
    }
}