fauna-api 1.0.861

The Fauna SDK for Rust: accounts, Drive, groups, calendar, chats, payments, Parrot and live rooms.
Documentation
use std::sync::Arc;

use chrono::{DateTime, Utc};
use futures_util::{SinkExt, StreamExt};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use tokio::sync::mpsc;
use tokio_tungstenite::tungstenite::Message;

use crate::authentification::{Credentials, CredentialsOrApiKey};
use crate::billing::PageQuery;
use crate::drive::{DriveAuthorization, File};
use crate::error::Result;
use crate::http::{client, encode, ok, websocket};
use crate::private::production::get_url;
use crate::tickets::{optional, parse_date};

// The Production tab's Benchmarks: an admin picks benchmarks and what they may spend, and Fauna
// runs them against itself as the admin's account. Each benchmark keeps its results numbered
// (`index`), their files in Fauna's own storage, opened through access codes.

#[cfg(feature = "benchmarks")]
pub mod suite;

/// Machines time Termite on its own; Product times what people do with Fauna's products.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum BenchmarkGroup {
    #[default]
    Machines,
    Product,
}

/// Waiting its turn, running, or how it ended.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum BenchmarkStatus {
    #[default]
    Queued,
    Running,
    Passed,
    Failed,
    Skipped,
}

/// One number a benchmark measured. `gate` says what it's held to and `passed` whether it held.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct BenchmarkMeasurement {
    pub name: String,
    pub value: f64,
    pub unit: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub gate: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub passed: Option<bool>,
}

impl BenchmarkMeasurement {
    pub fn from_json(json: &Value) -> BenchmarkMeasurement {
        BenchmarkMeasurement {
            name: json["name"].as_str().unwrap_or_default().to_string(),
            value: json["value"].as_f64().unwrap_or(0.0),
            unit: json["unit"].as_str().unwrap_or_default().to_string(),
            gate: optional(&json["gate"]),
            passed: json["passed"].as_bool(),
        }
    }
}

/// One benchmark's result in a run, `index` among that benchmark's results. Its files open
/// through access codes; `folder` downloads all of them as a zip. Dollars throughout.
#[derive(Debug, Clone)]
pub struct BenchmarkResult {
    pub id: String,
    pub run: String,
    pub benchmark: String,
    pub index: u64,
    pub status: BenchmarkStatus,
    /// How far along it is, from 0 to 1.
    pub fraction: f64,
    pub note: String,
    pub measurements: Vec<BenchmarkMeasurement>,
    pub estimate: f64,
    pub cost: f64,
    /// What its files hold.
    pub bytes: u64,
    pub files: Vec<File>,
    pub folder: Option<File>,
    pub reason: Option<String>,
    pub started_at: Option<DateTime<Utc>>,
    pub finished_at: Option<DateTime<Utc>>,
}

impl BenchmarkResult {
    pub fn from_json(json: &Value, credentials: &Credentials) -> BenchmarkResult {
        let file = |row: &Value| {
            File::from_json(
                row,
                DriveAuthorization::AccessCode {
                    authorization: CredentialsOrApiKey::Credentials(credentials.clone()),
                    access_code: row["accessCode"].as_str().unwrap_or_default().to_string(),
                },
            )
        };
        BenchmarkResult {
            id: text_id(&json["id"]),
            run: text_id(&json["run"]),
            benchmark: json["benchmark"].as_str().unwrap_or_default().to_string(),
            index: json["index"].as_u64().unwrap_or(0),
            status: serde_json::from_value(json["status"].clone()).unwrap_or_default(),
            fraction: json["fraction"].as_f64().unwrap_or(0.0),
            note: json["note"].as_str().unwrap_or_default().to_string(),
            measurements: json["measurements"]
                .as_array()
                .map(|rows| rows.iter().map(BenchmarkMeasurement::from_json).collect())
                .unwrap_or_default(),
            estimate: json["estimate"].as_f64().unwrap_or(0.0),
            cost: json["cost"].as_f64().unwrap_or(0.0),
            bytes: json["bytes"].as_u64().unwrap_or(0),
            files: json["files"]
                .as_array()
                .map(|rows| rows.iter().map(file).collect())
                .unwrap_or_default(),
            folder: json.get("folder").filter(|row| row.is_object()).map(file),
            reason: optional(&json["reason"]),
            started_at: parse_date(&json["startedAt"]),
            finished_at: parse_date(&json["finishedAt"]),
        }
    }
}

/// `Running` until its last benchmark ends, then `Done`, or `Failed` when the run itself broke.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum BenchmarkRunStatus {
    #[default]
    Running,
    Done,
    Failed,
}

/// One click of Run: who started it, what it may spend and has spent, and each benchmark's result.
#[derive(Debug, Clone)]
pub struct BenchmarkRun {
    pub id: String,
    pub by: String,
    pub limit: f64,
    pub spent: f64,
    pub status: BenchmarkRunStatus,
    pub reason: Option<String>,
    pub created_at: DateTime<Utc>,
    pub finished_at: Option<DateTime<Utc>>,
    pub results: Vec<BenchmarkResult>,
}

impl BenchmarkRun {
    pub fn from_json(json: &Value, credentials: &Credentials) -> BenchmarkRun {
        BenchmarkRun {
            id: text_id(&json["id"]),
            by: json["by"].as_str().unwrap_or_default().to_string(),
            limit: json["limit"].as_f64().unwrap_or(0.0),
            spent: json["spent"].as_f64().unwrap_or(0.0),
            status: serde_json::from_value(json["status"].clone()).unwrap_or_default(),
            reason: optional(&json["reason"]),
            created_at: parse_date(&json["createdAt"]).unwrap_or_default(),
            finished_at: parse_date(&json["finishedAt"]),
            results: json["results"]
                .as_array()
                .map(|rows| {
                    rows.iter()
                        .map(|row| BenchmarkResult::from_json(row, credentials))
                        .collect()
                })
                .unwrap_or_default(),
        }
    }
}

/// A benchmark to run: what it times, what it's estimated to cost, how many results it has and
/// its newest.
#[derive(Debug, Clone)]
pub struct Benchmark {
    pub id: String,
    pub name: String,
    pub group: BenchmarkGroup,
    pub about: String,
    pub estimate: f64,
    pub count: u64,
    pub latest: Option<BenchmarkResult>,
}

impl Benchmark {
    pub fn from_json(json: &Value, credentials: &Credentials) -> Benchmark {
        Benchmark {
            id: text_id(&json["id"]),
            name: json["name"].as_str().unwrap_or_default().to_string(),
            group: serde_json::from_value(json["group"].clone()).unwrap_or_default(),
            about: json["about"].as_str().unwrap_or_default().to_string(),
            estimate: json["estimate"].as_f64().unwrap_or(0.0),
            count: json["count"].as_u64().unwrap_or(0),
            latest: json
                .get("latest")
                .filter(|row| row.is_object())
                .map(|row| BenchmarkResult::from_json(row, credentials)),
        }
    }
}

/// Every benchmark, and the run going now.
#[derive(Debug, Clone)]
pub struct Benchmarks {
    pub benchmarks: Vec<Benchmark>,
    pub running: Option<BenchmarkRun>,
}

impl Benchmarks {
    pub fn from_json(json: &Value, credentials: &Credentials) -> Benchmarks {
        Benchmarks {
            benchmarks: json["benchmarks"]
                .as_array()
                .map(|rows| {
                    rows.iter()
                        .map(|row| Benchmark::from_json(row, credentials))
                        .collect()
                })
                .unwrap_or_default(),
            running: json
                .get("running")
                .filter(|row| row.is_object())
                .map(|row| BenchmarkRun::from_json(row, credentials)),
        }
    }
}

fn text_id(id: &Value) -> String {
    match id {
        Value::String(id) => id.clone(),
        id => id.to_string(),
    }
}

pub async fn benchmarks(credentials: &Credentials) -> Result<Benchmarks> {
    let response = client()
        .get(format!("{}/benchmarks", get_url()))
        .header("Authorization", format!("Token {}", credentials.token))
        .send()
        .await?;
    let json: Value = ok(response).await?.json().await?;
    Ok(Benchmarks::from_json(&json, credentials))
}

/// Runs `benchmarks` one after another, cheapest first, as your account, spending at most
/// `limit` dollars (up to 100). One run goes at a time.
pub async fn run_benchmarks(
    credentials: &Credentials,
    benchmarks: &[String],
    limit: f64,
) -> Result<BenchmarkRun> {
    let response = client()
        .post(format!("{}/benchmarks", get_url()))
        .header("Authorization", format!("Token {}", credentials.token))
        .json(&json!({ "benchmarks": benchmarks, "limit": limit }))
        .send()
        .await?;
    let json: Value = ok(response).await?.json().await?;
    Ok(BenchmarkRun::from_json(&json, credentials))
}

/// `benchmark`'s results, newest first.
pub async fn results(
    credentials: &Credentials,
    benchmark: &str,
    query: PageQuery,
) -> Result<Vec<BenchmarkResult>> {
    let response = client()
        .get(format!(
            "{}/benchmarks/{}?cursor={}&max={}",
            get_url(),
            encode(benchmark),
            query.cursor,
            query.max
        ))
        .header("Authorization", format!("Token {}", credentials.token))
        .send()
        .await?;
    let rows: Vec<Value> = ok(response).await?.json().await?;
    Ok(rows
        .iter()
        .map(|row| BenchmarkResult::from_json(row, credentials))
        .collect())
}

/// Deletes `benchmark`'s result `index` and its files. A result whose run is going stays.
pub async fn remove_result(credentials: &Credentials, benchmark: &str, index: u64) -> Result<()> {
    let response = client()
        .delete(format!(
            "{}/benchmarks/{}/{index}",
            get_url(),
            encode(benchmark)
        ))
        .header("Authorization", format!("Token {}", credentials.token))
        .send()
        .await?;
    ok(response).await?;
    Ok(())
}

/// A run's room hooks: the run as it was when the room opened, then the run and each result as
/// they change. Fauna closes the room once the run ends. Every method defaults to a no-op, like
/// the optional members of the TypeScript `BenchmarkRunHooks`.
pub trait BenchmarkRunHooks: Send + Sync {
    fn on_connection(&self, _run: &BenchmarkRun) {}
    fn on_run(&self, _run: &BenchmarkRun) {}
    fn on_result(&self, _result: &BenchmarkResult) {}
    fn on_error(&self, _message: &str) {}
    fn on_close(&self) {}
}

impl BenchmarkRunHooks for () {}

/// One run as it goes.
pub struct BenchmarkRunRoom {
    closing: mpsc::UnboundedSender<()>,
}

impl BenchmarkRunRoom {
    /// Opens run `id`'s room; resolves once it's open.
    pub async fn connect(
        credentials: &Credentials,
        id: &str,
        hooks: Option<Arc<dyn BenchmarkRunHooks>>,
    ) -> Result<BenchmarkRunRoom> {
        let hooks = hooks.unwrap_or_else(|| Arc::new(()));
        let params = json!({ "Authorization": format!("Token {}", credentials.token) });
        let url = format!(
            "{}/benchmarks/live?run={}&authorization={}",
            websocket(&get_url()),
            encode(id),
            encode(&params.to_string())
        );
        let (stream, _) = tokio_tungstenite::connect_async(url).await?;
        let (mut write, mut read) = stream.split();
        let (closing, mut closed) = mpsc::unbounded_channel::<()>();
        let credentials = credentials.clone();
        tokio::spawn(async move {
            loop {
                tokio::select! {
                    Some(()) = closed.recv() => {
                        let _ = write.close().await;
                        break;
                    }
                    message = read.next() => match message {
                        Some(Ok(Message::Text(text))) => deliver(hooks.as_ref(), &credentials, text.as_str()),
                        Some(Ok(Message::Close(_))) | None => break,
                        Some(Ok(_)) => {}
                        Some(Err(_)) => {
                            hooks.on_error("WebSocket connection failed");
                            break;
                        }
                    },
                }
            }
            hooks.on_close();
        });
        Ok(BenchmarkRunRoom { closing })
    }

    pub fn close(&self) {
        let _ = self.closing.send(());
    }
}

fn deliver(hooks: &dyn BenchmarkRunHooks, credentials: &Credentials, text: &str) {
    let Ok(packet) = serde_json::from_str::<Value>(text) else {
        return;
    };
    match packet["event"].as_str() {
        Some("connection") => {
            hooks.on_connection(&BenchmarkRun::from_json(&packet["run"], credentials))
        }
        Some("run") => hooks.on_run(&BenchmarkRun::from_json(&packet["run"], credentials)),
        Some("result") => {
            hooks.on_result(&BenchmarkResult::from_json(&packet["result"], credentials))
        }
        Some("error") => hooks.on_error(packet["message"].as_str().unwrap_or_default()),
        _ => {}
    }
}