lexe_common/constants/
timeout.rs

1//! Timeout constants, organized into nested modules named after the API trait,
2//! service, or struct whose timeouts it holds.
3//!
4//! `const_assert!`s are used to enforce our timeout hierarchies; e.g. each
5//! timeout along a request chain must be shorter than the one enclosing it.
6//!
7//! Principles for tuning:
8//!
9//! - When a timeout increase is needed: prefer to raise the timeout for a
10//!   specific server or client method that needs it, rather than the global
11//!   default.
12//! - Be careful when decreasing timeouts baked into enclave programs - if it
13//!   cannot be overridden via CLI, there is no way to backtrack if the decrease
14//!   was too aggressive. Wire through a CLI arg before decreasing the timeout.
15
16use std::time::Duration;
17
18use lexe_std::const_assert;
19
20/// The minimum tolerance every service should have for transient errors caused
21/// by restarts of this service's dependencies.
22///
23/// Notably, channel manager and channel monitor persists will try for up to
24/// this long before initiating a node shutdown.
25pub const TRANSIENT_ERROR_TOLERANCE: Duration = Duration::from_secs(30);
26
27/// Defaults for Lexe API servers.
28pub mod server {
29    use super::*;
30
31    /// The grace period passed to `axum_server::Handle::graceful_shutdown`
32    /// during which new connections are refused and we wait for existing
33    /// connections to terminate before initiating a hard shutdown.
34    pub const SHUTDOWN_GRACE_PERIOD: Duration = Duration::from_secs(3);
35
36    /// The maximum time we'll wait for a server to complete shutdown.
37    pub const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(5);
38
39    /// The default maximum time a server can spend handling a request.
40    pub const DEFAULT_HANDLER_TIMEOUT: Duration = Duration::from_secs(25);
41
42    const_assert!(SHUTDOWN_TIMEOUT.as_secs() > SHUTDOWN_GRACE_PERIOD.as_secs());
43}
44
45/// Defaults for Lexe `RestClient`s.
46pub mod client {
47    use super::*;
48
49    /// The default request timeout for Lexe `RestClient`s.
50    pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
51
52    const_assert!(
53        DEFAULT_TIMEOUT.as_secs() > server::DEFAULT_HANDLER_TIMEOUT.as_secs()
54    );
55}
56
57/// Timeouts for `UserNode`s.
58pub mod usernode {
59    use super::*;
60
61    /// Default sync timeout for user nodes (BDK/LDK sync).
62    //
63    // (2026-07-24): 30s -> 15s. The const was created at 30s despite 15s being
64    // the documented default; prod doesn't override it.
65    pub const DEFAULT_SYNC_TIMEOUT: Duration = Duration::from_secs(15);
66
67    /// The amount of time user node tasks have to finish after a graceful
68    /// shutdown signal is received before the task is forced to exit.
69    pub const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(35);
70
71    // The meganode's `run_user` handler (bounded by the default
72    // `server::DEFAULT_HANDLER_TIMEOUT`) blocks on the usernode's boot sync
73    // before responding.
74    const_assert!(
75        DEFAULT_SYNC_TIMEOUT.as_secs()
76            < server::DEFAULT_HANDLER_TIMEOUT.as_secs()
77    );
78    const_assert!(
79        SHUTDOWN_TIMEOUT.as_secs() > server::SHUTDOWN_TIMEOUT.as_secs()
80    );
81    // A shutting-down node must still afford a full critical-persist attempt.
82    const_assert!(
83        TRANSIENT_ERROR_TOLERANCE.as_secs() < SHUTDOWN_TIMEOUT.as_secs()
84    );
85}
86
87/// Timeouts for in-enclave `UserRunner`.
88pub mod userrunner {
89    use super::*;
90
91    /// The amount of time the user runner has to finish after a graceful
92    /// shutdown signal is received before the program is forced to exit.
93    pub const SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(37);
94
95    const_assert!(
96        SHUTDOWN_TIMEOUT.as_secs() > usernode::SHUTDOWN_TIMEOUT.as_secs()
97    );
98}
99
100/// Timeouts for `UserNodeProvisionApi` (User -> Node).
101pub mod user_node_provision_api {
102    use super::*;
103
104    /// `NodeClient`'s request timeout for provisioning. Generous because the
105    /// provision handler does the Google Drive OAuth exchange and GVFS setup.
106    pub const CLIENT_TIMEOUT: Duration = Duration::from_secs(30);
107
108    const_assert!(
109        CLIENT_TIMEOUT.as_secs() > server::DEFAULT_HANDLER_TIMEOUT.as_secs()
110    );
111}
112
113/// Timeouts for `UserNodeRunApi` (User -> Node).
114pub mod user_node_run_api {
115    use super::*;
116
117    /// Handling timeout for the node's user-facing server. Generous because
118    /// `[preflight_]pay_invoice` may compute `max_flow`, which takes ~30s at
119    /// 10 iterations and ~50s at 17 iterations.
120    /// See `compute_max_flow_to_recipient` for more details.
121    pub const SERVER_HANDLER_TIMEOUT: Duration = Duration::from_secs(60);
122
123    /// Timeouts for endpoints which may compute `max_flow`.
124    pub mod max_flow {
125        use super::*;
126
127        /// Client timeout for endpoints which may compute `max_flow`.
128        pub const CLIENT_TIMEOUT: Duration = Duration::from_secs(62);
129
130        const_assert!(
131            CLIENT_TIMEOUT.as_secs()
132                > user_node_run_api::SERVER_HANDLER_TIMEOUT.as_secs()
133        );
134    }
135}
lexe_common/constants/timeout.rs

lexe_common/constants/
timeout.rs
