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 | |
| 15 | use crate::srv::publish::store::{ |
| 16 | self, |
| 17 | Edit, |
| 18 | }; |
| 19 | |
| 20 | use oxedyne_fe2o3_core::prelude::*; |
| 21 | use oxedyne_fe2o3_iop_crypto::enc::Encrypter; |
| 22 | use oxedyne_fe2o3_iop_db::api::{ |
| 23 | Database, |
| 24 | ScanOpts, |
| 25 | }; |
| 26 | use oxedyne_fe2o3_iop_hash::api::Hasher; |
| 27 | use oxedyne_fe2o3_jdat::{ |
| 28 | prelude::*, |
| 29 | id::NumIdDat, |
| 30 | }; |
| 31 | |
| 32 | use std::sync::{ |
| 33 | Arc, |
| 34 | RwLock, |
| 35 | }; |
| 36 | |
| 37 | |
| 38 | // The span the comment and sign-up limiters have always counted over. |
| 39 | pub const HOUR_SECS: u64 = 3600; |
| 40 | |
| 41 | // Rows judged under one write guard when expiring, so a sweep never holds the writers for long. |
| 42 | const 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)] |
| 46 | pub 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 | |
| 52 | impl 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. |
| 66 | pub 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. |
| 77 | pub 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. |
| 94 | pub 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. |
| 120 | pub 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. |
| 147 | pub 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. |
| 176 | pub 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. |
| 195 | fn 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. |
| 217 | pub 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. |
| 233 | pub 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)] |
| 300 | mod 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 | } |