openzeppelin_relayer/constants/
plugins.rs

1// =============================================================================
2// Plugin Configuration Constants
3// =============================================================================
4//
5// All constants below can be overridden via environment variables.
6// See docs/plugins/index.mdx for the full configuration guide.
7//
8// Environment Variable Naming Convention:
9//   PLUGIN_POOL_*  → Pool server & connection pool settings
10//   PLUGIN_SOCKET_* → Shared socket service settings
11//   PLUGIN_TRACE_*  → Trace collection settings
12//
13// =============================================================================
14
15/// Default plugin execution timeout in seconds.
16/// Override in config.json per-plugin: `"timeout": 60`
17pub const DEFAULT_PLUGIN_TIMEOUT_SECONDS: u64 = 300; // 5 minutes
18
19/// Extra seconds added to the Rust-side timeout so both Node.js timeout layers
20/// fire first. The timeout hierarchy for a plugin with timeout T is:
21///   1. Handler (pool-executor.ts):    T      — structured TIMEOUT response
22///   2. Worker-pool safety net:        T + 2s — catches stuck workers
23///   3. Rust backstop (this buffer):   T + 4s — catches hung Node.js process
24pub const PLUGIN_TIMEOUT_BUFFER_SECONDS: u64 = 4;
25
26/// Timeout for admin pool requests (precompile, cache, invalidate) in seconds.
27/// These are fast operations that don't need the full plugin timeout.
28pub const ADMIN_REQUEST_TIMEOUT_SECS: u64 = 30;
29
30// =============================================================================
31// Plugin Pool Server Configuration
32// These constants are the source of truth. The TypeScript pool-server.ts and
33// worker-pool.ts files should use matching values.
34// =============================================================================
35
36/// Maximum concurrent connections from Rust to the Node.js pool server.
37/// Env: PLUGIN_POOL_MAX_CONNECTIONS
38/// Increase for high concurrency (3000+ VUs).
39pub const DEFAULT_POOL_MAX_CONNECTIONS: usize = 2048;
40
41/// Minimum worker threads in Node.js pool (floor).
42/// Internal constant, not user-configurable.
43pub const DEFAULT_POOL_MIN_THREADS: usize = 2;
44
45/// Maximum worker threads floor (minimum threads even on small machines).
46/// Internal constant, not user-configurable.
47pub const DEFAULT_POOL_MAX_THREADS_FLOOR: usize = 8;
48
49/// Concurrent tasks per worker thread in Node.js pool.
50/// Internal constant, not user-configurable.
51pub const DEFAULT_POOL_CONCURRENT_TASKS_PER_WORKER: usize = 20;
52
53/// Headroom multiplier for calculating concurrent tasks per worker.
54/// Applied to base task calculation to provide buffer for:
55///   - Queue buildup during traffic spikes
56///   - Variable plugin execution latency
57///   - Temporary load imbalances across workers
58///     Internal constant, not user-configurable.
59pub const CONCURRENT_TASKS_HEADROOM_MULTIPLIER: f64 = 1.2;
60
61/// Maximum concurrent tasks per worker thread (hard cap).
62/// This cap prevents excessive memory usage and GC pressure per worker.
63/// Validated through load testing as a stable upper bound.
64/// Internal constant, not user-configurable.
65pub const MAX_CONCURRENT_TASKS_PER_WORKER: usize = 250;
66
67/// Worker idle timeout in milliseconds.
68/// Internal constant, not user-configurable.
69pub const DEFAULT_POOL_IDLE_TIMEOUT_MS: u64 = 60000; // 60 seconds
70
71/// Socket connection backlog for the pool server.
72/// Env: PLUGIN_POOL_SOCKET_BACKLOG (internal, rarely needs tuning)
73pub const DEFAULT_POOL_SOCKET_BACKLOG: u32 = 2048;
74
75/// Maximum queued requests before rejection.
76/// Env: PLUGIN_POOL_MAX_QUEUE_SIZE
77/// Increase for high concurrency (3000+ VUs).
78pub const DEFAULT_POOL_MAX_QUEUE_SIZE: usize = 5000;
79
80/// Wait time (ms) when queue is full before rejecting.
81/// Env: PLUGIN_POOL_QUEUE_SEND_TIMEOUT_MS
82/// Increase for bursty traffic patterns.
83pub const DEFAULT_POOL_QUEUE_SEND_TIMEOUT_MS: u64 = 500;
84
85/// Minimum seconds between health checks.
86/// Env: PLUGIN_POOL_HEALTH_CHECK_INTERVAL_SECS
87/// Prevents health check storms under high load.
88pub const DEFAULT_POOL_HEALTH_CHECK_INTERVAL_SECS: u64 = 5;
89
90/// Retry attempts when connecting to pool server.
91/// Env: PLUGIN_POOL_CONNECT_RETRIES
92/// Increase for high concurrency scenarios.
93pub const DEFAULT_POOL_CONNECT_RETRIES: usize = 15;
94
95// =============================================================================
96// Shared Socket Service Configuration
97// Controls the Unix socket for plugin ↔ relayer communication.
98// =============================================================================
99
100/// Maximum concurrent plugin connections to the relayer.
101/// Env: PLUGIN_SOCKET_MAX_CONCURRENT_CONNECTIONS
102/// Should be >= PLUGIN_POOL_MAX_CONNECTIONS.
103pub const DEFAULT_SOCKET_MAX_CONCURRENT_CONNECTIONS: usize = 4096;
104
105/// Trace collection timeout (milliseconds).
106/// Env: PLUGIN_TRACE_TIMEOUT_MS
107/// Short timeout since traces arrive immediately after plugin execution.
108pub const DEFAULT_TRACE_TIMEOUT_MS: u64 = 100;
openzeppelin_relayer/constants/plugins.rs

openzeppelin_relayer/constants/
plugins.rs
