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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
//! Durable-ops budget controller (TD-004).
use std::time::{Duration, Instant};
/// How the engine resolves budget pressure vs admitted latency.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum BudgetMode {
/// Deadline flushes always run (may overdraft). Default.
#[default]
LatencyPriority,
/// New produces may wait for tokens; admitted deadline flushes still complete.
BudgetPriority,
/// Refuse admission when predicted media ops cannot be reserved.
FailClosed,
}
/// Configuration for the media-ops budget controller.
#[derive(Clone, Copy, Debug)]
pub struct BudgetConfig {
/// Master switch. Default **true** (Fjord-first).
pub enabled: bool,
/// How deadline flushes interact with an empty token bucket.
pub mode: BudgetMode,
/// Hard cap on durable ops/sec (None = no hard cap beyond capacity×fraction).
pub budget_per_sec_cap: Option<f64>,
/// Soft floor on effective budget when set (must be ≤ cap).
pub budget_per_sec_floor: Option<f64>,
/// Fraction of capacity used as soft budget target.
pub budget_fraction: f64,
/// Capacity when no probe/EWMA is available (S3 default path).
pub default_capacity_per_sec: f64,
/// Token fill ratio above which early-flush (effective linger = 0) is allowed.
pub early_flush_fill_ratio: f64,
/// Suppress consecutive early-flushes for this long after one fires.
pub early_flush_cooldown: Duration,
/// Early-flush only when the mutable queue holds at most this many bytes.
/// Combined with [`Self::early_flush_idle`]: bulk continuous ingest should
/// not early-flush. `0` disables the byte gate (idle gate may still apply).
pub early_flush_max_queued_bytes: usize,
/// Early-flush only if no produce has been enqueued for at least this long
/// (true idle). Sustained produce keeps resetting the timer so bulk waits
/// full linger / `flush`. `ZERO` disables the idle gate.
pub early_flush_idle: Duration,
/// Max wait for tokens under [`BudgetMode::BudgetPriority`].
pub admission_timeout: Duration,
}
impl Default for BudgetConfig {
fn default() -> Self {
Self {
enabled: true,
mode: BudgetMode::LatencyPriority,
budget_per_sec_cap: None,
budget_per_sec_floor: None,
budget_fraction: 0.5,
// Conservative S3-class default; Local probe/EWMA will refine.
default_capacity_per_sec: 50.0,
early_flush_fill_ratio: 0.5,
early_flush_cooldown: Duration::from_millis(5),
// ~4 MiB: single-op / sparse OK when also idle.
early_flush_max_queued_bytes: 4 * 1024 * 1024,
// Require a quiet gap so continuous bulk cannot be sliced into 4MiB seals.
early_flush_idle: Duration::from_millis(10),
admission_timeout: Duration::from_millis(100),
}
}
}
impl BudgetConfig {
/// Validate floor ≤ cap when both set.
pub fn validate(&self) -> Result<(), String> {
if let (Some(cap), Some(floor)) = (self.budget_per_sec_cap, self.budget_per_sec_floor)
&& floor > cap
{
return Err(format!(
"budget_per_sec_floor ({floor}) > budget_per_sec_cap ({cap})"
));
}
if !(0.0..=1.0).contains(&self.budget_fraction) {
return Err("budget_fraction must be in [0, 1]".into());
}
if self.default_capacity_per_sec < 0.0 {
return Err("default_capacity_per_sec must be >= 0".into());
}
Ok(())
}
/// Compute effective durable_ops/sec from optional measurements.
pub fn effective_budget_per_sec(
&self,
startup_capacity: Option<f64>,
ongoing_capacity: Option<f64>,
) -> f64 {
let capacity = ongoing_capacity
.or(startup_capacity)
.unwrap_or(self.default_capacity_per_sec)
.max(0.0);
let mut effective = capacity * self.budget_fraction;
if let Some(cap) = self.budget_per_sec_cap {
effective = effective.min(cap);
}
if let Some(floor) = self.budget_per_sec_floor {
effective = effective.max(floor);
if let Some(cap) = self.budget_per_sec_cap {
effective = effective.min(cap);
}
}
effective
}
}
/// Runtime token-bucket + EWMA state (held under the engine queue lock or own mutex).
#[derive(Debug)]
pub struct BudgetRuntime {
pub config: BudgetConfig,
pub tokens: f64,
pub effective_budget_per_sec: f64,
pub last_refill: Instant,
pub predicted_media_ops: f64,
pub last_early_flush: Option<Instant>,
pub media_ops_total: u64,
pub overdraft_total: u64,
pub flushes_total: u64,
pub undersized_deadline_flushes: u64,
pub startup_capacity: Option<f64>,
pub ongoing_capacity: Option<f64>,
/// EWMA of observed media ops per flush.
media_ops_ewma: f64,
ewma_inited: bool,
}
impl BudgetRuntime {
pub fn new(config: BudgetConfig) -> Self {
let effective = config.effective_budget_per_sec(None, None);
Self {
config,
tokens: effective.max(1.0),
effective_budget_per_sec: effective,
last_refill: Instant::now(),
predicted_media_ops: 1.0,
last_early_flush: None,
media_ops_total: 0,
overdraft_total: 0,
flushes_total: 0,
undersized_deadline_flushes: 0,
startup_capacity: None,
ongoing_capacity: None,
media_ops_ewma: 1.0,
ewma_inited: false,
}
}
pub fn refill(&mut self, now: Instant) {
let dt = now.duration_since(self.last_refill).as_secs_f64();
if dt <= 0.0 {
return;
}
let burst = self.effective_budget_per_sec.max(1.0);
self.tokens = (self.tokens + dt * self.effective_budget_per_sec).min(burst);
self.last_refill = now;
}
pub fn fill_ratio(&self) -> f64 {
let burst = self.effective_budget_per_sec.max(1.0);
(self.tokens / burst).clamp(0.0, 1.0)
}
/// Whether headroom + idle allow early flush (effective linger 0).
///
/// - `queued_bytes` must be ≤ `early_flush_max_queued_bytes` (if that cap > 0)
/// - `last_enqueue` must be at least `early_flush_idle` ago (if idle > 0)
///
/// Sustained produce keeps `last_enqueue` fresh → no early-flush → linger/`flush` pack.
pub fn allow_early_flush(
&self,
now: Instant,
queued_bytes: usize,
last_enqueue: Option<Instant>,
) -> bool {
if !self.config.enabled {
return false;
}
let max_q = self.config.early_flush_max_queued_bytes;
if max_q > 0 && queued_bytes > max_q {
return false;
}
let idle_need = self.config.early_flush_idle;
if !idle_need.is_zero() {
let Some(last) = last_enqueue else {
return false;
};
if now.duration_since(last) < idle_need {
return false;
}
}
if self.fill_ratio() < self.config.early_flush_fill_ratio {
return false;
}
if let Some(last) = self.last_early_flush
&& now.duration_since(last) < self.config.early_flush_cooldown
{
return false;
}
true
}
pub fn note_early_flush(&mut self, now: Instant) {
self.last_early_flush = Some(now);
}
/// Consume media ops after a flush (always succeeds; may overdraft).
pub fn consume_after_flush(&mut self, media_ops: u64, now: Instant) {
self.refill(now);
let cost = media_ops as f64;
if cost <= self.tokens {
self.tokens -= cost;
} else {
self.overdraft_total += (cost - self.tokens).ceil() as u64;
self.tokens = 0.0;
}
self.media_ops_total += media_ops;
self.flushes_total += 1;
// EWMA of cost
const ALPHA: f64 = 0.2;
if !self.ewma_inited {
self.media_ops_ewma = cost.max(0.1);
self.ewma_inited = true;
} else {
self.media_ops_ewma = ALPHA * cost + (1.0 - ALPHA) * self.media_ops_ewma;
}
self.predicted_media_ops = self.media_ops_ewma.max(0.1);
// Ongoing capacity estimate from implied rate if we had overdraft recently — keep simple:
// if we observed media ops, capacity estimate ≈ max(default, ops in last sec proxy)
// Use inverse of nothing; leave ongoing for optional future. Bootstrap prediction only.
}
/// Admission check for Durable/Sequenced produces under fail_closed / budget_priority.
/// Returns false if produce should be rejected (fail_closed) or caller should wait.
pub fn can_admit_now(&mut self, now: Instant) -> bool {
if !self.config.enabled {
return true;
}
self.refill(now);
match self.config.mode {
BudgetMode::LatencyPriority => true,
BudgetMode::BudgetPriority | BudgetMode::FailClosed => {
self.tokens >= self.predicted_media_ops * 0.5
}
}
}
pub fn reserve_for_fail_closed(&mut self, now: Instant) -> bool {
if !self.config.enabled || self.config.mode != BudgetMode::FailClosed {
return true;
}
self.refill(now);
let need = self.predicted_media_ops;
if self.tokens >= need {
self.tokens -= need;
true
} else {
false
}
}
}
/// Why an effective value was chosen (for inspectability).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum EffectiveReason {
/// Operator config alone.
Configured,
/// Limited by config cap.
ConfigCap,
/// From startup probe.
StartupProbe,
/// From ongoing measurement.
Ongoing,
/// Library / profile default capacity.
DefaultCapacity,
/// Budget controller disabled.
Disabled,
}
/// One inspectable knob with layered sources.
#[derive(Clone, Debug, PartialEq)]
pub struct EffectiveKnob<T: Clone> {
/// Operator-configured value, if any.
pub configured: Option<T>,
/// Startup measurement, if any.
pub startup_measured: Option<T>,
/// Ongoing measurement, if any.
pub ongoing_measured: Option<T>,
/// Value currently in force.
pub effective: T,
/// Why `effective` was chosen.
pub reason: EffectiveReason,
}
/// Point-in-time controller + buffer view.
#[derive(Clone, Debug)]
pub struct PipelineSnapshot {
/// Effective durable-ops/sec budget.
pub budget_per_sec: EffectiveKnob<f64>,
/// Effective linger currently used for scheduling (0 = early flush).
pub effective_linger_ms: EffectiveKnob<u64>,
/// Operator max linger (ms).
pub max_linger_ms: u64,
/// Token fill ratio in [0, 1].
pub token_fill_ratio: f64,
/// Cumulative media ops consumed.
pub media_ops_total: u64,
/// Cumulative overdraft media ops.
pub overdraft_total: u64,
/// Successful flushes.
pub flushes_total: u64,
/// Deadline flushes that were under size soft target (counted when metered).
pub undersized_deadline_flushes: u64,
/// Predicted media ops per flush (EWMA).
pub predicted_media_ops: f64,
/// Whether budget controller is enabled.
pub budget_enabled: bool,
/// Active budget conflict mode.
pub budget_mode: BudgetMode,
}