Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_net/src/lens/shot.rs

13.7 KiB, 1 run

created by r1870400018:69925, 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 bounded store of pictures taken on request, the screenshot half of a debug lens.
2//!
3//! Written for Daimond's Lens (D-20261006-14), where the owner asks one of his own devices for a
4//! picture of its screen and the device answers with a PNG or with the reason it will not. The
5//! exchange is three files under one directory, so a reader on another machine needs nothing but
6//! a copy of it (Daimond's `dev/lens.mjs` pulls it with rsync):
7//!
8//! * `want/<device>` holds the id of an ask (`Shots::ask`, or any writer that puts the id there).
9//! * `out/<account>.<device>` holds the ask last handed to that account's device and when, which
10//! is both the rate floor and the proof an answer was asked for.
11//! * `<stamp>.<account>.<device>.<id>.png` is a picture and `….refused` a refusal, written whole
12//! under a `.part` name and renamed, so a copy taken mid-write never holds half a picture.
13//!
14//! Every segment passes `sanitise`, whose alphabet holds no `.`, so a name splits unambiguously.
15//! An answer is accepted once, only for the id handed out, and only within `answer_ms`; a
16//! device asked again inside `floor_ms` is refused on the device's behalf and never troubled.
17
18use super::sink::{
19 sanitise,
20 stamp,
21 STAMP_LEN,
22};
23
24use oxedyne_fe2o3_core::prelude::*;
25
26use std::{
27 fs,
28 io::Write,
29 path::{
30 Path,
31 PathBuf,
32 },
33 time::SystemTime,
34};
35
36
37const PNG_MAGIC: &[u8] = b"\x89PNG\r\n\x1a\n";
38const PICTURE_EXT: &str = "png";
39const REFUSED_EXT: &str = "refused";
40const PART_EXT: &str = "part";
41const WANT_DIR: &str = "want";
42const OUT_DIR: &str = "out";
43const MAX_REASON: usize = 200; // bytes of a refusal's reason kept
44
45#[derive(Clone, Debug)]
46pub struct ShotGates {
47 pub max_bytes: usize, // the largest picture accepted
48 pub max_total: u64, // the most bytes of pictures and refusals the directory may hold
49 pub keep_ms: u64, // how long a picture or refusal is kept
50 pub floor_ms: u64, // the shortest gap between two asks handed to one account's device
51 pub answer_ms: u64, // how long an ask handed out may still be answered
52 pub want_ms: u64, // how long an ask nobody collected waits
53}
54
55impl ShotGates {
56
57 /// Daimond's numbers: a 3 MiB picture, 7 days, one ask a minute, two minutes to answer it.
58 pub fn daimond() -> Self {
59 Self {
60 max_bytes: 3 * 1024 * 1024,
61 max_total: 500 * 1024 * 1024,
62 keep_ms: 7 * 86_400_000,
63 floor_ms: 60_000,
64 answer_ms: 120_000,
65 want_ms: 600_000,
66 }
67 }
68}
69
70impl Default for ShotGates {
71 fn default() -> Self { Self::daimond() }
72}
73
74/// What a device is told when it asks whether a picture is wanted.
75#[derive(Clone, Debug, Eq, PartialEq)]
76pub enum Ask {
77 Nothing, // no ask waits for this device
78 Take(String), // take a picture and answer it under this id
79 TooSoon(String, u64), // the ask with this id was refused, the floor lifts in this many ms
80}
81
82/// A device's answer to an ask.
83#[derive(Clone, Copy, Debug)]
84pub enum Answer<'a> {
85 Picture(&'a [u8]),
86 Refused(&'a str),
87}
88
89/// Why an answer was turned away. Nothing was written.
90#[derive(Clone, Debug, Eq, PartialEq)]
91pub enum ShotRefusal {
92 Unasked, // 409, the id was not handed to this device, was answered or expired
93 NotPicture, // 415, the body is not a PNG
94 TooLarge, // 413
95}
96
97impl ShotRefusal {
98
99 pub fn status(&self) -> u16 {
100 match self {
101 Self::Unasked => 409,
102 Self::NotPicture => 415,
103 Self::TooLarge => 413,
104 }
105 }
106
107 pub fn message(&self) -> String {
108 match self {
109 Self::Unasked => "No picture was asked of this device under that id.".to_string(),
110 Self::NotPicture => "A picture must be a PNG.".to_string(),
111 Self::TooLarge => "The picture is too large.".to_string(),
112 }
113 }
114}
115
116/// The result of an answer: the file written, or the reason none was.
117#[derive(Clone, Debug, Eq, PartialEq)]
118pub enum Filed {
119 Stored(PathBuf),
120 Refused(ShotRefusal),
121}
122
123/// The store. It holds no state of its own beyond its directory, so two processes may share one.
124#[derive(Clone, Debug)]
125pub struct Shots {
126 dir: PathBuf,
127 gates: ShotGates,
128}
129
130impl Shots {
131
132 pub fn new<P: Into<PathBuf>>(dir: P, gates: ShotGates) -> Self {
133 Self { dir: dir.into(), gates }
134 }
135
136 pub fn dir(&self) -> &Path { &self.dir }
137
138 pub fn gates(&self) -> &ShotGates { &self.gates }
139
140 /// Asks `device` for a picture under `id`, replacing any ask not yet collected.
141 pub fn ask(&self, device: &str, id: &str) -> Outcome<()> {
142 let path = self.dir.join(WANT_DIR).join(sanitise(device));
143 write_whole(&path, sanitise(id).as_bytes())
144 }
145
146 /// Collects the ask waiting for `account`'s `device`, if any. An ask is collected once: it is
147 /// either handed out, or refused on the device's behalf when the last one was handed out
148 /// less than `floor_ms` ago, and that refusal is filed under the ask's id for the asker.
149 pub fn take(&self, account: &str, device: &str, now_ms: u64) -> Outcome<Ask> {
150 let want = self.dir.join(WANT_DIR).join(sanitise(device));
151 let id = match fs::read_to_string(&want) {
152 Ok(s) => sanitise(s.trim()),
153 Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Ask::Nothing),
154 Err(e) => return Err(err!(e, "While reading the ask {:?}.", want; IO, File, Read)),
155 };
156 res!(fs::remove_file(&want), IO, File);
157 let out = self.out_path(account, device);
158 if let Some((_, at)) = res!(read_out(&out)) {
159 let since = now_ms.saturating_sub(at);
160 if since < self.gates.floor_ms {
161 let wait = self.gates.floor_ms - since;
162 let reason = fmt!("rate: the next picture may be taken in {} s", (wait + 999) / 1_000);
163 res!(self.file(account, device, &id, REFUSED_EXT, reason.as_bytes(), now_ms));
164 return Ok(Ask::TooSoon(id, wait));
165 }
166 }
167 res!(write_whole(&out, fmt!("{} {}", id, now_ms).as_bytes()));
168 Ok(Ask::Take(id))
169 }
170
171 /// Files `account`'s `device`'s answer to the ask handed out under `id`.
172 pub fn answer(
173 &self,
174 account: &str,
175 device: &str,
176 id: &str,
177 answer: Answer,
178 now_ms: u64,
179 )
180 -> Outcome<Filed>
181 {
182 let id = sanitise(id);
183 let out = self.out_path(account, device);
184 let at = match res!(read_out(&out)) {
185 Some((handed, at)) if handed == id && now_ms.saturating_sub(at) <= self.gates.answer_ms => at,
186 _ => return Ok(Filed::Refused(ShotRefusal::Unasked)),
187 };
188 let (ext, body) = match answer {
189 Answer::Picture(png) => {
190 if png.len() > self.gates.max_bytes {
191 return Ok(Filed::Refused(ShotRefusal::TooLarge));
192 }
193 if !png.starts_with(PNG_MAGIC) {
194 return Ok(Filed::Refused(ShotRefusal::NotPicture));
195 }
196 (PICTURE_EXT, png.to_vec())
197 }
198 Answer::Refused(reason) => (REFUSED_EXT, clip(&scrub(reason), MAX_REASON).into_bytes()),
199 };
200 // Consumed: the id is struck out but the instant stays, so the floor still holds.
201 res!(write_whole(&out, fmt!("- {}", at).as_bytes()));
202 let path = res!(self.file(account, device, &id, ext, &body, now_ms));
203 res!(self.prune(now_ms));
204 Ok(Filed::Stored(path))
205 }
206
207 /// The picture or refusal filed for `device` under `id`, if there is one.
208 pub fn find(&self, device: &str, id: &str) -> Outcome<Option<PathBuf>> {
209 let tail_png = fmt!(".{}.{}.{}", sanitise(device), sanitise(id), PICTURE_EXT);
210 let tail_ref = fmt!(".{}.{}.{}", sanitise(device), sanitise(id), REFUSED_EXT);
211 for name in res!(names(&self.dir)) {
212 if name.ends_with(&tail_png) || name.ends_with(&tail_ref) {
213 return Ok(Some(self.dir.join(name)));
214 }
215 }
216 Ok(None)
217 }
218
219 /// Removes what has outlived the gates: pictures and refusals older than `keep_ms` by the
220 /// stamp in their names, then the oldest of them until the rest fit `max_total`, and asks,
221 /// hand-outs and abandoned `.part` files by modification time. Returns how many went.
222 pub fn prune(&self, now_ms: u64) -> Outcome<usize> {
223 let mut gone = 0;
224 let cut = stamp(now_ms.saturating_sub(self.gates.keep_ms));
225 let mut kept: Vec<(String, u64)> = Vec::new();
226 for name in res!(names(&self.dir)) {
227 let path = self.dir.join(&name);
228 if name.ends_with(&fmt!(".{}", PART_EXT)) {
229 if res!(older_than(&path, now_ms, self.gates.want_ms)) {
230 gone += res!(remove(&path));
231 }
232 continue;
233 }
234 let filed = name.ends_with(&fmt!(".{}", PICTURE_EXT))
235 || name.ends_with(&fmt!(".{}", REFUSED_EXT));
236 if !filed || name.len() <= STAMP_LEN || !super::sink::is_stamp(&name[..STAMP_LEN]) {
237 continue; // Not ours, and nothing here should guess at its age.
238 }
239 if name[..STAMP_LEN] < *cut.as_str() {
240 gone += res!(remove(&path));
241 } else {
242 let len = res!(fs::metadata(&path), IO, File).len();
243 kept.push((name, len));
244 }
245 }
246 kept.sort();
247 let mut total: u64 = kept.iter().map(|(_, n)| *n).sum();
248 for (name, len) in kept {
249 if total <= self.gates.max_total {
250 break;
251 }
252 gone += res!(remove(&self.dir.join(&name)));
253 total -= len;
254 }
255 for (sub, age) in [(WANT_DIR, self.gates.want_ms), (OUT_DIR, self.gates.want_ms.max(self.gates.floor_ms))] {
256 let dir = self.dir.join(sub);
257 for name in res!(names(&dir)) {
258 let path = dir.join(name);
259 if res!(older_than(&path, now_ms, age)) {
260 gone += res!(remove(&path));
261 }
262 }
263 }
264 Ok(gone)
265 }
266
267 fn out_path(&self, account: &str, device: &str) -> PathBuf {
268 self.dir.join(OUT_DIR).join(fmt!("{}.{}", sanitise(account), sanitise(device)))
269 }
270
271 // Writes `<stamp>.<account>.<device>.<id>.<ext>` whole.
272 fn file(&self, account: &str, device: &str, id: &str, ext: &str, body: &[u8], now_ms: u64)
273 -> Outcome<PathBuf>
274 {
275 let name = fmt!("{}.{}.{}.{}.{}",
276 stamp(now_ms), sanitise(account), sanitise(device), sanitise(id), ext);
277 let path = self.dir.join(name);
278 res!(write_whole(&path, body));
279 Ok(path)
280 }
281}
282
283// Writes under a `.part` name, then renames, so a reader sees all of the file or none of it.
284fn write_whole(path: &Path, body: &[u8]) -> Outcome<()> {
285 if let Some(parent) = path.parent() {
286 res!(fs::create_dir_all(parent), IO, File);
287 }
288 let part = path.with_extension(match path.extension() {
289 Some(e) => fmt!("{}.{}", e.to_string_lossy(), PART_EXT),
290 None => PART_EXT.to_string(),
291 });
292 {
293 let mut f = res!(fs::File::create(&part), IO, File, Write);
294 res!(f.write_all(body), IO, File, Write);
295 res!(f.sync_all(), IO, File, Write);
296 }
297 res!(fs::rename(&part, path), IO, File, Write);
298 Ok(())
299}
300
301// `<id> <ms>`, the ask last handed out and when; the id is `-` once answered.
302fn read_out(path: &Path) -> Outcome<Option<(String, u64)>> {
303 let s = match fs::read_to_string(path) {
304 Ok(s) => s,
305 Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
306 Err(e) => return Err(err!(e, "While reading the hand-out {:?}.", path; IO, File, Read)),
307 };
308 let mut it = s.split_whitespace();
309 match (it.next(), it.next().and_then(|t| t.parse::<u64>().ok())) {
310 (Some(id), Some(at)) => Ok(Some((id.to_string(), at))),
311 _ => Ok(None), // A torn record is no hand-out.
312 }
313}
314
315// The plain files directly under `dir`, sorted; none when it does not exist yet.
316fn names(dir: &Path) -> Outcome<Vec<String>> {
317 let rd = match fs::read_dir(dir) {
318 Ok(rd) => rd,
319 Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
320 Err(e) => return Err(err!(e, "While listing {:?}.", dir; IO, File, Read)),
321 };
322 let mut out = Vec::new();
323 for ent in rd {
324 let ent = res!(ent, IO, File, Read);
325 let ft = res!(ent.file_type(), IO, File, Read);
326 if ft.is_file() {
327 out.push(ent.file_name().to_string_lossy().to_string());
328 }
329 }
330 out.sort();
331 Ok(out)
332}
333
334fn older_than(path: &Path, now_ms: u64, age_ms: u64) -> Outcome<bool> {
335 let mt = res!(res!(fs::metadata(path), IO, File).modified());
336 let ms = match mt.duration_since(SystemTime::UNIX_EPOCH) {
337 Ok(d) => d.as_millis() as u64,
338 Err(_) => 0,
339 };
340 Ok(now_ms.saturating_sub(ms) > age_ms)
341}
342
343// Removes a file another pruner may have removed first.
344fn remove(path: &Path) -> Outcome<usize> {
345 match fs::remove_file(path) {
346 Ok(()) => Ok(1),
347 Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(0),
348 Err(e) => Err(err!(e, "While removing {:?}.", path; IO, File)),
349 }
350}
351
352fn scrub(s: &str) -> String {
353 s.chars().map(|c| if c.is_control() { ' ' } else { c }).collect()
354}
355
356fn clip(s: &str, n: usize) -> String {
357 if s.len() <= n {
358 return s.to_string();
359 }
360 let mut end = n;
361 while !s.is_char_boundary(end) {
362 end -= 1;
363 }
364 s[..end].to_string()
365}