Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_steel/src/srv/publish/rate.rs

11.3 KiB, 1 run

created by r1870400018:68854, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! A windowed counter for the acts a stranger can repeat.
2//!
3//! One row of three numbers, `[last, count, window_start]`, under a key the caller chooses. It limits
4//! two things at once: how soon after the last act the next may come (`interval_secs`), and how many
5//! may land within a span (`max` in `span_secs`). The comment limiter, the sign-up limiter and the
6//! per-recipient confirmation limit are all this counter with different keys and windows.
7//!
8//! The row is read, changed and written back under [`store::update`](super::store::update)'s write
9//! guard. With only a read guard, thirty-two requests arriving together each read the same count and
10//! every one of them was let through.
11//!
12//! [Written with AI entirely](https://need2know.ai/entirely-ai/code)\
13//! Anthropic Claude
14
15use crate::srv::publish::store::{
16 self,
17 Edit,
18};
19
20use oxedyne_fe2o3_core::prelude::*;
21use oxedyne_fe2o3_iop_crypto::enc::Encrypter;
22use oxedyne_fe2o3_iop_db::api::{
23 Database,
24 ScanOpts,
25};
26use oxedyne_fe2o3_iop_hash::api::Hasher;
27use oxedyne_fe2o3_jdat::{
28 prelude::*,
29 id::NumIdDat,
30};
31
32use std::sync::{
33 Arc,
34 RwLock,
35};
36
37
38// The span the comment and sign-up limiters have always counted over.
39pub const HOUR_SECS: u64 = 3600;
40
41// Rows judged under one write guard when expiring, so a sweep never holds the writers for long.
42const EXPIRE_CHUNK: usize = 256;
43
44/// How often one key may act. A bound of 0 is that bound switched off.
45#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
46pub struct Window {
47 pub interval_secs: u64, // the shortest gap between two acts
48 pub max: u32, // the most acts within one span
49 pub span_secs: u64, // how long a count runs before it starts again
50}
51
52impl Window {
53
54 /// A window that counts over an hour, as the comment and sign-up limiters do.
55 pub fn hourly(interval_secs: u64, max: u32) -> Self {
56 Self { interval_secs, max, span_secs: HOUR_SECS }
57 }
58
59 /// Are both bounds off, so that the key may always act and nothing need be read?
60 pub fn is_off(&self) -> bool {
61 self.interval_secs == 0 && self.max == 0
62 }
63}
64
65/// Seconds since the epoch, or 0 where the clock is before it.
66pub fn now_secs() -> u64 {
67 std::time::SystemTime::now()
68 .duration_since(std::time::UNIX_EPOCH)
69 .map(|d| d.as_secs())
70 .unwrap_or(0)
71}
72
73/// Whether the key may act now, and the record of its having done so.
74///
75/// When both bounds are off nothing is read and nothing is written. A refusal writes nothing either,
76/// so a flood of refused requests does not become a flood of writes.
77pub fn allow<
78 const UIDL: usize,
79 UID: NumIdDat<UIDL>,
80 ENC: Encrypter,
81 KH: Hasher,
82 DB: Database<UIDL, UID, ENC, KH>,
83>(
84 db: &(Arc<RwLock<DB>>, UID),
85 key: &str,
86 w: &Window,
87)
88 -> Outcome<bool>
89{
90 allow_at(db, key, w, now_secs())
91}
92
93/// As [`allow`], at a time the caller names.
94pub fn allow_at<
95 const UIDL: usize,
96 UID: NumIdDat<UIDL>,
97 ENC: Encrypter,
98 KH: Hasher,
99 DB: Database<UIDL, UID, ENC, KH>,
100>(
101 db: &(Arc<RwLock<DB>>, UID),
102 key: &str,
103 w: &Window,
104 now: u64,
105)
106 -> Outcome<bool>
107{
108 if w.is_off() {
109 return Ok(true);
110 }
111 store::exclusive(db, |dbr, user| allow_in(dbr, user, key, w, now))
112}
113
114/// As [`allow_at`], on a database already write-locked by [`store::exclusive`].
115///
116/// For a caller that must count and change something else in the same step, as the per-recipient
117/// confirmation limit does beside the subscriber record. Inside the guard it must be this and never
118/// [`allow`]: a std `RwLock` is not re-entrant, and `allow` would wait on the guard its own caller
119/// holds.
120pub fn allow_in<
121 const UIDL: usize,
122 UID: NumIdDat<UIDL>,
123 ENC: Encrypter,
124 KH: Hasher,
125 DB: Database<UIDL, UID, ENC, KH>,
126>(
127 dbr: &DB,
128 user: UID,
129 key: &str,
130 w: &Window,
131 now: u64,
132)
133 -> Outcome<bool>
134{
135 if w.is_off() {
136 return Ok(true);
137 }
138 store::edit_in(dbr, user, &dat!(key.to_string()), |old| -> Outcome<(Edit, bool)> {
139 Ok(step(old, w, now))
140 })
141}
142
143/// Would one more act be allowed at `now`? Reads the row and writes nothing, on a database already locked.
144///
145/// For a caller that counts only when the act has happened, as the per-recipient limit does: the
146/// check comes before the act and [`allow_at`] counts it after.
147pub fn permits_in<
148 const UIDL: usize,
149 UID: NumIdDat<UIDL>,
150 ENC: Encrypter,
151 KH: Hasher,
152 DB: Database<UIDL, UID, ENC, KH>,
153>(
154 dbr: &DB,
155 key: &str,
156 w: &Window,
157 now: u64,
158)
159 -> Outcome<bool>
160{
161 if w.is_off() {
162 return Ok(true);
163 }
164 let old = match res!(dbr.get(&dat!(key.to_string()), None)) {
165 Some((v, _)) => Some(v),
166 None => None,
167 };
168 Ok(step(old, w, now).1)
169}
170
171/// The count a stored row holds, and what one more act at `now` does to it.
172///
173/// A new window resets the count. The window runs from the act that opened it, not rolling: a rolling
174/// window needs every timestamp kept, and this needs three numbers. A row of any other shape reads as
175/// no row, so a store holding something else at the key starts the count afresh.
176pub fn step(old: Option<Dat>, w: &Window, now: u64) -> (Edit, bool) {
177 let (last, count, start) = read_row(&old);
178 let (count, start) = if now.saturating_sub(start) >= w.span_secs {
179 (0, now)
180 } else {
181 (count, start)
182 };
183 if (w.interval_secs > 0 && now.saturating_sub(last) < w.interval_secs)
184 || (w.max > 0 && count >= w.max)
185 {
186 return (Edit::Keep, false);
187 }
188 let row = Dat::List(vec![dat!(now), dat!((count as u64) + 1), dat!(start)]);
189 (Edit::Set(row), true)
190}
191
192
193// The three numbers a stored row holds: the last act, the count, and where the window began. A row
194// of any other shape, or none, reads as all zeroes.
195fn read_row(old: &Option<Dat>) -> (u64, u32, u64) {
196 match old {
197 Some(Dat::List(v)) if v.len() == 3 => {
198 let n = |i: usize| match v.get(i) {
199 Some(Dat::U64(x)) => *x,
200 Some(Dat::U32(x)) => *x as u64,
201 Some(Dat::U16(x)) => *x as u64,
202 Some(Dat::U8(x)) => *x as u64,
203 _ => 0,
204 };
205 (n(0), n(1).min(u32::MAX as u64) as u32, n(2))
206 },
207 _ => (0, 0, 0),
208 }
209}
210
211/// Has a stored row outlived its window, so that it no longer limits anything?
212///
213/// It has once the window it counted in and the interval after the last act have both passed, which
214/// is a time `span_secs + interval_secs` after the later of the last act and the window's start. Past
215/// that, [`step`] would open a new window and count from nothing, so deleting the row changes no
216/// answer. A row of any other shape is spent already, since `step` reads it as no row at all.
217pub fn spent(old: &Option<Dat>, w: &Window, now: u64) -> bool {
218 let (last, _, start) = read_row(old);
219 now.saturating_sub(last.max(start)) >= w.span_secs.saturating_add(w.interval_secs)
220}
221
222/// Deletes every row under the given prefixes that has outlived that prefix's window, and says how
223/// many went.
224///
225/// The keys are found by one `scan`, for the longest prefix the sets share, and that scan **walks
226/// every index file of the store**: what it costs is the size of the store however few rows match,
227/// and the database holds it to the request deadline rather than letting it stall. It is for a
228/// background task, never a request, and it is made once for all the sets so a store is not walked
229/// for each. The scan holds the read guard and no more; each row is then judged again under the
230/// write guard, in chunks, so a row a request has counted since the scan is kept, and no write waits
231/// on the whole sweep. A scan that cannot finish in time is an error for the caller to log and try
232/// again, and nothing is lost by it: a spent row only occupies space.
233pub fn expire_rows<
234 const UIDL: usize,
235 UID: NumIdDat<UIDL>,
236 ENC: Encrypter,
237 KH: Hasher,
238 DB: Database<UIDL, UID, ENC, KH>,
239>(
240 db: &(Arc<RwLock<DB>>, UID),
241 sets: &[(&str, Window)],
242 now: u64,
243)
244 -> Outcome<usize>
245{
246 let (db_arc, _) = db;
247 let mut shared: Option<&str> = None;
248 for (prefix, _) in sets {
249 shared = Some(match shared {
250 None => *prefix,
251 Some(sofar) => {
252 let n: usize = sofar.chars().zip(prefix.chars()).take_while(|(a, b)| a == b)
253 .map(|(a, _)| a.len_utf8()).sum();
254 &sofar[..n]
255 },
256 });
257 }
258 let shared = match shared {
259 Some(p) => p,
260 None => return Ok(0),
261 };
262 let found = {
263 let guard = lock_read!(db_arc);
264 res!(guard.scan(&ScanOpts::with_str_prefix(shared), None))
265 };
266 let mut rows: Vec<(Dat, Window)> = Vec::new();
267 for (key, _, _) in found {
268 let w = match &key {
269 Dat::Str(k) => sets.iter().find(|(p, _)| k.starts_with(p)).map(|(_, w)| *w),
270 _ => None,
271 };
272 if let Some(w) = w {
273 rows.push((key, w));
274 }
275 }
276 let mut gone = 0;
277 for chunk in rows.chunks(EXPIRE_CHUNK) {
278 gone += res!(store::exclusive(db, |dbr, user| -> Outcome<usize> {
279 let mut n = 0;
280 for (key, w) in chunk {
281 // A key the scan listed that the database reads as absent is a deleted row: nothing to
282 // delete, and `edit_in` leaves it alone.
283 let cleared = res!(store::edit_in(dbr, user, key, |old| -> Outcome<(Edit, bool)> {
284 if old.is_some() && spent(&old, w, now) {
285 return Ok((Edit::Clear, true));
286 }
287 Ok((Edit::Keep, false))
288 }));
289 if cleared {
290 n += 1;
291 }
292 }
293 Ok(n)
294 }));
295 }
296 Ok(gone)
297}
298
299#[cfg(test)]
300mod tests {
301 use super::*;
302
303 const T0: u64 = 1_800_000_000;
304
305 // The row a step wrote, as the three numbers it holds.
306 fn row_of(e: &Edit) -> Option<Dat> {
307 match e {
308 Edit::Set(d) => Some(d.clone()),
309 _ => None,
310 }
311 }
312
313 /// Acts up to the maximum are allowed within a span, and the next is refused with no write.
314 #[test]
315 fn test_a_count_stops_at_the_maximum_00() -> Outcome<()> {
316 let w = Window { interval_secs: 0, max: 3, span_secs: 100 };
317 let mut row = None;
318 for i in 0..3u64 {
319 let (e, ok) = step(row, &w, T0 + i);
320 assert!(ok, "act {} was refused", i);
321 row = row_of(&e);
322 assert!(row.is_some());
323 }
324 let (e, ok) = step(row.clone(), &w, T0 + 10);
325 assert!(!ok, "the fourth act was allowed");
326 assert!(matches!(e, Edit::Keep), "a refusal wrote");
327 Ok(())
328 }
329
330 /// The span is the caller's: a count over a day is still full after an hour, and fresh after a day.
331 #[test]
332 fn test_the_span_is_a_parameter_01() -> Outcome<()> {
333 let day = Window { interval_secs: 0, max: 1, span_secs: 86_400 };
334 let hour = Window::hourly(0, 1);
335 let (e, ok) = step(None, &day, T0);
336 assert!(ok);
337 let row = row_of(&e);
338 // An hour and a second on: the hourly window has turned over and the daily one has not.
339 assert!(!step(row.clone(), &day, T0 + 3_601).1, "a day's count was reset after an hour");
340 let (e, ok) = step(None, &hour, T0);
341 assert!(ok);
342 assert!(step(row_of(&e), &hour, T0 + 3_601).1, "an hour's count was not reset");
343 // And the daily one turns over after the day.
344 assert!(step(row, &day, T0 + 86_400).1, "a day's count was not reset after a day");
345 Ok(())
346 }
347
348 /// The interval refuses an act that follows the last too soon, whatever the count.
349 #[test]
350 fn test_the_interval_refuses_a_quick_repeat_02() -> Outcome<()> {
351 let w = Window::hourly(60, 0);
352 let (e, ok) = step(None, &w, 5_000);
353 assert!(ok);
354 let row = row_of(&e);
355 assert!(!step(row.clone(), &w, 5_030).1);
356 assert!(step(row, &w, 5_060).1);
357 Ok(())
358 }
359
360 /// A row written before this module existed reads the same: three unsigned numbers.
361 #[test]
362 fn test_an_existing_row_still_reads_03() -> Outcome<()> {
363 let old = Dat::List(vec![dat!(1_000u64), dat!(5u64), dat!(900u64)]);
364 let w = Window::hourly(0, 5);
365 let (e, ok) = step(Some(old), &w, 1_100);
366 assert!(!ok, "a full count was forgotten");
367 assert!(matches!(e, Edit::Keep));
368 // A row of some other shape is no row.
369 let (_, ok) = step(Some(dat!("junk")), &w, 1_100);
370 assert!(ok);
371 Ok(())
372 }
373}