fauna-api 1.0.856

The Fauna SDK for Rust: accounts, Drive, groups, calendar, chats, payments, Parrot and live rooms.
Documentation
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
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
//! The benchmarks themselves, which the server runs against Fauna as an admin's account: each
//! one makes what it needs (repositories, chats, timelines, workspaces), times or checks it the
//! way people use it, keeps its numbers and files through the run's `Sink`, and leaves nothing
//! behind. Only the server builds this (the `benchmarks` feature).

mod agent;
mod ant;
mod chat;
mod gallery;
mod machines;
mod marmot;
mod media;
mod seat;

use std::cmp::Reverse;
use std::collections::BTreeMap;
use std::fmt;
use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
use std::time::{Duration, Instant};

use futures_util::future::BoxFuture;

use super::{BenchmarkGroup, BenchmarkMeasurement};
use crate::ant::timeline::{self, GroupOptions as TimelineOptions};
use crate::authentification::CredentialsOrApiKey;
use crate::error::{Error, Result};
use crate::marmot::research::{self, GroupOptions as DatasetOptions};
use crate::marmot::workspace::{self, WorkspaceOptions};
use crate::parrot::chat as chats;
use crate::termite::os::{GroupOptions, MachineRoom};
use crate::termite::versioning::{self, CreateOptions, FileOrFiles, Repository};

pub use chat::MODEL;

/// How long a machine may take to save and stop.
const STOP_WAIT: Duration = Duration::from_secs(600);
/// How long a start or stop's phases may take to land after the machine's room saw it.
const PHASES_WAIT: Duration = Duration::from_secs(30);

/// One benchmark: what it is, what it may take, and how it runs.
pub trait Benchmark: Send + Sync {
    fn id(&self) -> &'static str;
    fn name(&self) -> &'static str;
    fn group(&self) -> BenchmarkGroup;
    fn about(&self) -> &'static str;
    /// The most it does, which its estimate prices.
    fn work(&self) -> Work;
    fn timeout(&self) -> Duration;
    /// What it found, in words, or why it failed. Its numbers go through `run.measure`, and a
    /// number that missed its gate fails it too.
    fn run<'a>(&'a self, run: &'a Run) -> BoxFuture<'a, Result<String>>;
}

/// Every benchmark, Machines first.
pub fn catalog() -> Vec<Arc<dyn Benchmark>> {
    vec![
        Arc::new(machines::Boots),
        Arc::new(machines::Memory),
        Arc::new(machines::InputLatency),
        Arc::new(machines::AppStream),
        Arc::new(machines::Saving),
        Arc::new(gallery::Gallery),
        Arc::new(gallery::Blender),
        Arc::new(chat::SignIn),
        Arc::new(chat::TestsVideo),
        Arc::new(chat::BlenderChat),
        Arc::new(ant::Simulation),
        Arc::new(marmot::Research),
    ]
}

/// The most a benchmark does, which its estimate prices.
#[derive(Debug, Clone, Copy, Default, PartialEq)]
pub struct Work {
    /// Machine agent steps.
    pub steps: f64,
    /// Turns of a chat's reply.
    pub turns: f64,
    /// Hours of machines that fit one small node, each alone in its pool and so paying that
    /// whole node, as a standard machine alone does.
    pub machine_hours: f64,
    /// What it caps its own spend at, like research's cost limit.
    pub dollars: f64,
}

/// What a machine's start or stop spent its time on, and its numbers, as Termite recorded them.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Phases {
    /// How a start came up: `cold boot`, `base snapshot`, `local resume` or `resume`.
    pub how: Option<String>,
    /// Each step's milliseconds, `total` among them.
    pub ms: BTreeMap<String, f64>,
    /// QEMU's resident memory as the start ended or the stop began, 0 when Termite can't read it.
    pub rss_bytes: u64,
    /// The memory snapshot a stop kept, in bytes.
    pub memory_bytes: u64,
}

/// Where a run's benchmark puts what it learns. The server keeps it.
pub trait Sink: Send + Sync {
    /// How far along the benchmark is, from 0 to 1, and what it's doing.
    fn progress(&self, fraction: f64, note: &str);
    fn measure(&self, measurement: BenchmarkMeasurement);
    /// Keeps a file of the benchmark's result.
    fn file<'a>(
        &'a self,
        name: &'a str,
        content_type: &'a str,
        bytes: Vec<u8>,
    ) -> BoxFuture<'a, Result<()>>;
    /// What Termite recorded of machine `machine`'s latest `event` (`start` or `stop`), once it
    /// has.
    fn phases<'a>(&'a self, machine: u64, event: &'a str) -> BoxFuture<'a, Option<Phases>>;
}

/// What a benchmark works with: Fauna as the run's key, names that tell the run's things apart,
/// the run's sink, and what it made.
pub struct Run {
    pub key: CredentialsOrApiKey,
    tag: String,
    sink: Arc<dyn Sink>,
    made: Ledger,
}

impl Run {
    pub fn new(key: CredentialsOrApiKey, tag: String, sink: Arc<dyn Sink>) -> Run {
        Run {
            made: Ledger::new(key.clone()),
            key,
            tag,
            sink,
        }
    }

    /// `what`, named for this run.
    pub fn named(&self, what: &str) -> String {
        format!("Benchmark {} {what}", self.tag)
    }

    pub fn progress(&self, fraction: f64, note: &str) {
        self.sink.progress(fraction.clamp(0.0, 1.0), note);
    }

    pub fn measure(&self, measurement: BenchmarkMeasurement) {
        self.sink.measure(measurement);
    }

    pub async fn file(&self, name: &str, content_type: &str, bytes: Vec<u8>) -> Result<()> {
        self.sink.file(name, content_type, bytes).await
    }

    /// What Termite recorded of `machine`'s latest `event`, waiting for it to land.
    pub async fn phases(&self, machine: u64, event: &str) -> Result<Phases> {
        let deadline = Instant::now() + PHASES_WAIT;
        loop {
            if let Some(phases) = self.sink.phases(machine, event).await {
                return Ok(phases);
            }
            if Instant::now() > deadline {
                return fail(format!(
                    "Termite recorded no {event} of machine {machine} within {} s.",
                    PHASES_WAIT.as_secs()
                ));
            }
            tokio::time::sleep(Duration::from_secs(1)).await;
        }
    }

    /// A new repository of the key's person, deleted with the run.
    pub async fn repository(&self, what: &str) -> Result<Repository> {
        let options = CreateOptions {
            name: Some(self.named(what)),
            group: None,
        };
        let repository = versioning::create(&self.key, options).await?;
        self.made.add(Made::Repository(repository.id));
        Ok(repository)
    }

    pub(crate) fn made(&self, made: Made) {
        self.made.add(made);
    }

    /// Saves and stops every machine of the run's repositories, so what they cost settles.
    pub async fn stop_machines(&self) {
        self.made.stop_machines().await;
    }

    /// Deletes everything the benchmark made: what couldn't be deleted, and why.
    pub async fn clear(&self) -> Vec<String> {
        self.made.clear().await
    }
}

/// Something a benchmark made, deleted at its end.
#[derive(Debug, Clone, PartialEq)]
pub(crate) enum Made {
    Chat(String),
    Timeline(String),
    Dataset { workspace: String, id: String },
    Workspace(String),
    Repository(u64),
}

impl Made {
    /// Where it goes in the teardown: whatever uses a repository before the repository.
    fn rank(&self) -> u8 {
        match self {
            Made::Chat(_) => 0,
            Made::Timeline(_) => 1,
            Made::Dataset { .. } => 2,
            Made::Workspace(_) => 3,
            Made::Repository(_) => 4,
        }
    }

    async fn delete(&self, key: &CredentialsOrApiKey) -> Result<()> {
        match self {
            Made::Chat(id) => chats::delete_chat(key, id, None).await?,
            Made::Timeline(id) => {
                timeline::delete_timeline(key, id, TimelineOptions::default()).await?
            }
            Made::Dataset { workspace, id } => {
                research::list_datasets(key, workspace, DatasetOptions::default())
                    .await?
                    .into_iter()
                    .find(|dataset| &dataset.id == id)
                    .ok_or_else(|| Error::Message("it isn't in its workspace".into()))?
                    .remove()
                    .await?
            }
            Made::Workspace(id) => {
                workspace::remove_workspace(key, id, WorkspaceOptions::default()).await?
            }
            Made::Repository(id) => {
                stopped(key, *id).await?;
                versioning::get(key, *id, versioning::GroupOptions::default())
                    .await?
                    .delete()
                    .await?
            }
        }
        Ok(())
    }
}

impl fmt::Display for Made {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Made::Chat(id) => write!(f, "chat {id}"),
            Made::Timeline(id) => write!(f, "Ant timeline {id}"),
            Made::Dataset { workspace, id } => {
                write!(f, "Marmot dataset {id} in workspace {workspace}")
            }
            Made::Workspace(id) => write!(f, "Marmot workspace {id}"),
            Made::Repository(id) => write!(f, "repository {id}"),
        }
    }
}

/// The teardown's order: by rank, the newest of each kind first.
fn teardown(made: Vec<Made>) -> Vec<Made> {
    let mut ordered: Vec<(usize, Made)> = made.into_iter().enumerate().collect();
    ordered.sort_by_key(|(at, made)| (made.rank(), Reverse(*at)));
    ordered.into_iter().map(|(_, made)| made).collect()
}

struct Ledger {
    key: CredentialsOrApiKey,
    made: Mutex<Vec<Made>>,
}

impl Ledger {
    fn new(key: CredentialsOrApiKey) -> Ledger {
        Ledger {
            key,
            made: Mutex::default(),
        }
    }

    fn add(&self, made: Made) {
        lock(&self.made).push(made);
    }

    async fn stop_machines(&self) {
        let repositories: Vec<u64> = lock(&self.made)
            .iter()
            .filter_map(|made| match made {
                Made::Repository(id) => Some(*id),
                _ => None,
            })
            .collect();
        for id in repositories {
            let _ = stopped(&self.key, id).await;
        }
    }

    async fn clear(&self) -> Vec<String> {
        let made = std::mem::take(&mut *lock(&self.made));
        let mut left = Vec::new();
        for made in teardown(made) {
            if let Err(err) = made.delete(&self.key).await {
                left.push(format!("{made}: {err}"));
            }
        }
        left
    }
}

pub(crate) fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
    mutex.lock().unwrap_or_else(PoisonError::into_inner)
}

pub(crate) fn fail<T>(text: impl Into<String>) -> Result<T> {
    Err(Error::Message(text.into()))
}

pub(crate) fn ensure(holds: bool, text: impl FnOnce() -> String) -> Result<()> {
    if holds { Ok(()) } else { fail(text()) }
}

/// Saves and stops `repository`'s machine, and waits until it's gone.
pub(crate) async fn stopped(key: &CredentialsOrApiKey, repository: u64) -> Result<()> {
    // A repository with no live machine refuses the stop, and is already where this waits for.
    let _ = MachineRoom::shutdown(key, repository, GroupOptions::default()).await;
    let deadline = Instant::now() + STOP_WAIT;
    loop {
        let found = versioning::get(key, repository, versioning::GroupOptions::default()).await?;
        if found.machine.is_none() {
            return Ok(());
        }
        if Instant::now() > deadline {
            return fail(format!(
                "Repository {repository}'s machine didn't stop within {} minutes.",
                STOP_WAIT.as_secs() / 60
            ));
        }
        tokio::time::sleep(Duration::from_secs(5)).await;
    }
}

/// A file's text, through the repository's file routes (from its saved layers once it stopped).
pub(crate) async fn read(repository: &Repository, path: &str) -> Result<String> {
    match repository.open(Some(path)).await? {
        FileOrFiles::File(mut file) => Ok(file.text().await?),
        FileOrFiles::Files(_) => fail(format!("{path} is a folder.")),
    }
}

/// A file's bytes, through the repository's file routes.
pub(crate) async fn bytes(repository: &Repository, path: &str) -> Result<Vec<u8>> {
    match repository.open(Some(path)).await? {
        FileOrFiles::File(mut file) => file.download(false, None).await,
        FileOrFiles::Files(_) => fail(format!("{path} is a folder.")),
    }
}

/// `n` random lowercase hex digits.
pub(crate) fn nonce(n: usize) -> String {
    uuid::Uuid::new_v4().simple().to_string()[..n].to_string()
}

/// At most the first 400 characters of `text`, for a failure's reason.
pub(crate) fn short(text: &str) -> String {
    let mut chars = text.trim().chars();
    let head: String = chars.by_ref().take(400).collect();
    if chars.next().is_some() {
        format!("{head}...")
    } else {
        head
    }
}

pub(crate) fn tenths(n: f64) -> f64 {
    (n * 10.0).round() / 10.0
}

/// Milliseconds from `from` to `at`.
pub(crate) fn since(from: Instant, at: Instant) -> f64 {
    tenths(at.saturating_duration_since(from).as_secs_f64() * 1000.0)
}

/// A measurement with no gate.
pub(crate) fn number(name: &str, value: f64, unit: &str) -> BenchmarkMeasurement {
    BenchmarkMeasurement {
        name: name.to_string(),
        value,
        unit: unit.to_string(),
        gate: None,
        passed: None,
    }
}

/// A measurement held to `gate`, in words, which it `passed` or didn't.
pub(crate) fn gated(
    name: &str,
    value: f64,
    unit: &str,
    gate: String,
    passed: bool,
) -> BenchmarkMeasurement {
    BenchmarkMeasurement {
        gate: Some(gate),
        passed: Some(passed),
        ..number(name, value, unit)
    }
}

/// Mebibytes, to the tenth.
pub(crate) fn mib(bytes: u64) -> f64 {
    tenths(bytes as f64 / f64::from(1 << 20))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn deletes_what_uses_a_repository_before_the_repository() {
        let made = vec![
            Made::Repository(1),
            Made::Chat("10".into()),
            Made::Repository(2),
            Made::Chat("11".into()),
            Made::Workspace("w".into()),
            Made::Dataset {
                workspace: "w".into(),
                id: "d".into(),
            },
            Made::Repository(3),
            Made::Timeline("t".into()),
        ];
        assert_eq!(
            teardown(made),
            [
                Made::Chat("11".into()),
                Made::Chat("10".into()),
                Made::Timeline("t".into()),
                Made::Dataset {
                    workspace: "w".into(),
                    id: "d".into(),
                },
                Made::Workspace("w".into()),
                Made::Repository(3),
                Made::Repository(2),
                Made::Repository(1),
            ]
        );
        assert_eq!(
            Made::Dataset {
                workspace: "w".into(),
                id: "d".into()
            }
            .to_string(),
            "Marmot dataset d in workspace w"
        );
    }

    #[test]
    fn every_benchmark_has_its_own_id() {
        let ids: Vec<&str> = catalog().iter().map(|b| b.id()).collect();
        let mut unique = ids.clone();
        unique.sort();
        unique.dedup();
        assert_eq!(ids.len(), unique.len(), "{ids:?}");
        assert!(!ids.contains(&"live"), "live is the run's socket");
    }

    #[test]
    fn shortens_long_text_and_rounds_to_tenths() {
        assert_eq!(short("  done  "), "done");
        assert_eq!(short(&"a".repeat(500)), format!("{}...", "a".repeat(400)));
        assert_eq!(nonce(6).len(), 6);
        assert_eq!(tenths(1.26), 1.3);
        assert_eq!(mib(3 << 20), 3.0);
    }
}