offline-protocol 0.30.0

//! A portable conformance suite for [`ProtocolStateStorage`] implementations.
//!
//! Swappable storage is only a property if it can be verified. Without a
//! suite, "bring your own backend" is a promise: an adapter that looks right
//! and returns `Ok` from every method can still lose records under an
//! overwrite, leak keys between categories, or truncate a value at some
//! internal limit, and the symptom arrives much later as data that quietly
//! is not there.
//!
//! Green here is the definition of "this backend is supported".
//!
//! The suite drives the trait directly rather than going through the
//! sealing chokepoint, because what is under test is the adapter's contract:
//! bytes in, the same bytes out, addressed by `(key_type, key_id)`. It
//! writes only under its own key types, and deletes everything it wrote.
//!
//! Key-type isolation is checked first, with point writes and point deletes
//! of ids nothing else uses, and a failure ends the run there. Every listed
//! delete after it trusts that listing a probe key type names only probe
//! records; on a backend that merges key types it names real records too,
//! and the cleanup would delete them. That makes the suite safe to run
//! against a live store whatever the backend does with key types. It is not
//! a promise for every defect: probe a new backend on a scratch instance
//! until it is green.

use crate::protocol_state_storage::{
    ProtocolStateError, ProtocolStateStorage, MAX_PROTOCOL_STATE_RECORD_TRANSFER_BYTES,
};

/// The key type every probe record is written under.
///
/// Deliberately not a real category: nothing else reads it, and a leftover
/// record from an interrupted run is inert.
pub const CONFORMANCE_KEY_TYPE: &str = "storage_conformance_probe";

/// A second key type, used to prove categories do not bleed into each other.
pub const CONFORMANCE_KEY_TYPE_OTHER: &str = "storage_conformance_probe_other";

/// A key type that ends with [`CONFORMANCE_KEY_TYPE`]. The second probe type
/// is related to the first by prefix only, and a backend that lists by the
/// tail of a name is caught only by one related by suffix.
const CONFORMANCE_KEY_TYPE_SUFFIXED: &str = "suffixed_storage_conformance_probe";

/// The id the isolation check writes under two probe key types. Nothing else
/// uses it, so a point write or delete of it cannot reach a real record even
/// on a backend that ignores the key type.
const ISOLATION_PROBE_ID: &str = "storage_conformance_isolation";

/// The id the isolation check writes under the other probe key types only,
/// to catch a listing that crosses key types.
const ISOLATION_LISTING_PROBE_ID: &str = "storage_conformance_isolation_listing";

/// The report types are the MLS suite's, re-exported, so the two suites
/// render one JSON shape and one reader serves both.
pub use offline_protocol_mls::storage_conformance::{ConformanceFailure, ConformanceReport};

fn expect_load(
    storage: &dyn ProtocolStateStorage,
    key_id: &str,
    expected: &[u8],
) -> std::result::Result<(), String> {
    match storage.load(CONFORMANCE_KEY_TYPE, key_id) {
        Ok(Some(actual)) if actual == expected => Ok(()),
        Ok(Some(actual)) => Err(format!(
            "loaded {} bytes, expected {} (contents differ)",
            actual.len(),
            expected.len()
        )),
        Ok(None) => Err("stored value loaded back as missing".to_string()),
        Err(err) => Err(format!("load failed: {err}")),
    }
}

/// Run the suite.
///
/// Never panics: an adapter that misbehaves produces failures in the report,
/// because the whole point is to hand an adapter author a list of what to
/// fix rather than a stack trace.
pub fn run(storage: &dyn ProtocolStateStorage) -> ConformanceReport {
    let mut report = ConformanceReport::new();

    // 1. Key types are separate namespaces, checked before anything is
    // deleted. The data layer keeps documents, their delta logs and space
    // indexes in three of them; a backend that merges them would serve a
    // delta where a document was asked for. It is also the one defect that
    // turns this suite destructive (see the module doc), so a failure ends
    // the run here.
    let isolation = key_types_are_isolated(storage);
    let isolated = isolation.is_ok();
    report.check("key_types_are_separate_namespaces", isolation);
    if !isolated {
        return report;
    }

    // Anything left from an interrupted earlier run would make the listing
    // checks report failures that are not the adapter's fault.
    cleanup(storage);

    // 2. The basic contract.
    let outcome = storage
        .store(CONFORMANCE_KEY_TYPE, "basic", b"hello")
        .map_err(|err| format!("store failed: {err}"))
        .and_then(|()| expect_load(storage, "basic", b"hello"));
    report.check("store_then_load", outcome);

    // 3. Values are bytes, not text. A backend that round-trips through a
    // string type mangles these, and the failure is invisible until a
    // sealed record (which is ciphertext) comes back wrong.
    let binary: Vec<u8> = (0u8..=255).collect();
    let outcome = storage
        .store(CONFORMANCE_KEY_TYPE, "binary", &binary)
        .map_err(|err| format!("store failed: {err}"))
        .and_then(|()| expect_load(storage, "binary", &binary));
    report.check("binary_values_round_trip", outcome);

    // 4. An empty value is a value, and must not read back as absent.
    let outcome = storage
        .store(CONFORMANCE_KEY_TYPE, "empty", b"")
        .map_err(|err| format!("store failed: {err}"))
        .and_then(|()| expect_load(storage, "empty", b""));
    report.check("empty_value_is_not_missing", outcome);

    // 5. A second store replaces; it does not append or refuse.
    let outcome = storage
        .store(CONFORMANCE_KEY_TYPE, "overwrite", b"first")
        .and_then(|()| storage.store(CONFORMANCE_KEY_TYPE, "overwrite", b"second"))
        .map_err(|err| format!("store failed: {err}"))
        .and_then(|()| expect_load(storage, "overwrite", b"second"));
    report.check("store_overwrites", outcome);

    // 6. A key that was never written reads as missing, not as an error.
    let outcome = match storage.load(CONFORMANCE_KEY_TYPE, "never_written") {
        Ok(None) => Ok(()),
        Ok(Some(_)) => Err("a key that was never written returned a value".to_string()),
        Err(ProtocolStateError::NotFound(_)) => {
            Err("absent keys must load as Ok(None), not NotFound".to_string())
        }
        Err(err) => Err(format!("load of an absent key failed: {err}")),
    };
    report.check("absent_key_loads_as_none", outcome);

    // 7. Delete removes, and deleting again is not an error. The data layer
    // deletes folded delta records after a crash may already have taken
    // them, so a delete that fails on an absent key turns a clean recovery
    // into a spurious failure.
    let outcome = storage
        .store(CONFORMANCE_KEY_TYPE, "deletable", b"x")
        .and_then(|()| storage.delete(CONFORMANCE_KEY_TYPE, "deletable"))
        .map_err(|err| format!("store/delete failed: {err}"))
        .and_then(|()| match storage.load(CONFORMANCE_KEY_TYPE, "deletable") {
            Ok(None) => Ok(()),
            Ok(Some(_)) => Err("value survived a delete".to_string()),
            Err(err) => Err(format!("load after delete failed: {err}")),
        })
        .and_then(
            |()| match storage.delete(CONFORMANCE_KEY_TYPE, "deletable") {
                Ok(()) => Ok(()),
                Err(err) => Err(format!("second delete must succeed, got: {err}")),
            },
        );
    report.check("delete_removes_and_is_idempotent", outcome);

    // 8. Listing names what is there, and only within its own key type.
    let outcome = (|| -> std::result::Result<(), String> {
        storage
            .store(CONFORMANCE_KEY_TYPE, "shared_id", b"mine")
            .and_then(|()| storage.store(CONFORMANCE_KEY_TYPE_OTHER, "shared_id", b"theirs"))
            .map_err(|err| format!("store failed: {err}"))?;
        let keys = storage
            .list_keys(CONFORMANCE_KEY_TYPE)
            .map_err(|err| format!("list_keys failed: {err}"))?;
        for expected in ["basic", "binary", "empty", "overwrite", "shared_id"] {
            if !keys.iter().any(|key| key == expected) {
                return Err(format!("list_keys omitted {expected:?}"));
            }
        }
        if keys.iter().any(|key| key == "deletable") {
            return Err("list_keys named a deleted record".to_string());
        }
        let other = storage
            .list_keys(CONFORMANCE_KEY_TYPE_OTHER)
            .map_err(|err| format!("list_keys failed: {err}"))?;
        if other.len() != 1 || other.first().map(String::as_str) != Some("shared_id") {
            return Err(format!("list_keys leaked across key types: {other:?}"));
        }
        Ok(())
    })();
    report.check("list_keys_is_accurate_and_scoped", outcome);

    // 9. Listing an untouched key type is empty, not an error.
    let outcome = match storage.list_keys("storage_conformance_probe_unused") {
        Ok(keys) if keys.is_empty() => Ok(()),
        Ok(keys) => Err(format!("an unused key type listed {} keys", keys.len())),
        Err(err) => Err(format!("list_keys on an unused key type failed: {err}")),
    };
    report.check("unused_key_type_lists_empty", outcome);

    // 10. Key ids as the SDK actually composes them. Document records are
    // keyed `{space}/{doc}` and delta records `{space}/{doc}/{seq}`, so a
    // backend that treats a key id as a filesystem path, or rejects the
    // separator, breaks the data layer specifically.
    let composed = "space-1/doc.name_2/000000000000002a";
    let outcome = storage
        .store(CONFORMANCE_KEY_TYPE, composed, b"composed")
        .map_err(|err| format!("store with a composed key failed: {err}"))
        .and_then(|()| expect_load(storage, composed, b"composed"))
        .and_then(|()| {
            let keys = storage
                .list_keys(CONFORMANCE_KEY_TYPE)
                .map_err(|err| format!("list_keys failed: {err}"))?;
            if keys.iter().any(|key| key == composed) {
                Ok(())
            } else {
                Err("list_keys did not return a composed key verbatim".to_string())
            }
        });
    report.check("composed_key_ids_round_trip", outcome);

    // 11. The longest key id the SDK can actually write: a delta record for a
    // maximum-length space and document name, which is
    // `{128}/{128}/{16 hex}` = 274 bytes. Probing anything shorter lets a
    // backend with a limit in between pass here and fail in production on
    // exactly the record type whose loss is silent.
    // 128 is `offline_protocol_data::MAX_NAME_LEN`, written as a literal
    // because this suite must still compile with the data layer switched off.
    let long_key = format!("{}/{}/{:016x}", "s".repeat(128), "d".repeat(128), u64::MAX);
    let outcome = storage
        .store(CONFORMANCE_KEY_TYPE, &long_key, b"long")
        .map_err(|err| format!("store with a long key failed: {err}"))
        .and_then(|()| expect_load(storage, &long_key, b"long"));
    report.check("long_key_ids_round_trip", outcome);

    // 12. A record at the size the SDK is allowed to write. A sealed record
    // may reach the record cap plus the seal's overhead, and the provider's
    // own ceiling is the documented superset of that.
    let large = vec![0xa5u8; MAX_PROTOCOL_STATE_RECORD_TRANSFER_BYTES / 2];
    let outcome = storage
        .store(CONFORMANCE_KEY_TYPE, "large", &large)
        .map_err(|err| format!("store of a large record failed: {err}"))
        .and_then(|()| expect_load(storage, "large", &large));
    report.check("large_records_round_trip", outcome);

    // 13. Everything written can be found and removed. This is the logout
    // contract: an application pointing documents at a custom backend needs
    // wiping to actually empty it.
    let outcome = (|| -> std::result::Result<(), String> {
        cleanup(storage);
        for key_type in [CONFORMANCE_KEY_TYPE, CONFORMANCE_KEY_TYPE_OTHER] {
            let remaining = storage
                .list_keys(key_type)
                .map_err(|err| format!("list_keys failed: {err}"))?;
            if !remaining.is_empty() {
                return Err(format!(
                    "{} records survived a listed delete in {key_type}",
                    remaining.len()
                ));
            }
        }
        Ok(())
    })();
    report.check("listed_records_can_all_be_deleted", outcome);

    report
}

/// The isolation check: the same id under two key types, and an id under
/// two others that must not appear in the first one's listing.
///
/// Only a collision fails it. A value that comes back wrong in another way
/// is the round-trip checks' to report, and a listing that fails is the
/// listing checks'; neither is evidence that a listed delete would reach
/// outside the probe key types. The probe records are removed with point
/// deletes whatever the outcome.
fn key_types_are_isolated(storage: &dyn ProtocolStateStorage) -> std::result::Result<(), String> {
    let outcome = (|| -> std::result::Result<(), String> {
        storage
            .store(CONFORMANCE_KEY_TYPE_OTHER, ISOLATION_PROBE_ID, b"theirs")
            .and_then(|()| storage.store(CONFORMANCE_KEY_TYPE, ISOLATION_PROBE_ID, b"mine"))
            .and_then(|()| {
                storage.store(CONFORMANCE_KEY_TYPE_OTHER, ISOLATION_LISTING_PROBE_ID, b"x")
            })
            .and_then(|()| {
                storage.store(CONFORMANCE_KEY_TYPE_SUFFIXED, ISOLATION_LISTING_PROBE_ID, b"x")
            })
            .map_err(|err| {
                format!("store failed, so isolation could not be checked and nothing was deleted: {err}")
            })?;
        if let Ok(Some(other)) = storage.load(CONFORMANCE_KEY_TYPE_OTHER, ISOLATION_PROBE_ID) {
            if other == b"mine" {
                return Err(
                    "the same key id in two key types collided: a write under one \
                            replaced the other"
                        .to_string(),
                );
            }
        }
        if let Ok(listed) = storage.list_keys(CONFORMANCE_KEY_TYPE) {
            if listed.iter().any(|key| key == ISOLATION_LISTING_PROBE_ID) {
                return Err("list_keys named a record written under another key type".to_string());
            }
        }
        Ok(())
    })();
    for (key_type, key_id) in [
        (CONFORMANCE_KEY_TYPE, ISOLATION_PROBE_ID),
        (CONFORMANCE_KEY_TYPE_OTHER, ISOLATION_PROBE_ID),
        (CONFORMANCE_KEY_TYPE_OTHER, ISOLATION_LISTING_PROBE_ID),
        (CONFORMANCE_KEY_TYPE_SUFFIXED, ISOLATION_LISTING_PROBE_ID),
    ] {
        let _ = storage.delete(key_type, key_id);
    }
    outcome
}

/// Remove every record the suite writes, in both key types.
fn cleanup(storage: &dyn ProtocolStateStorage) {
    for key_type in [CONFORMANCE_KEY_TYPE, CONFORMANCE_KEY_TYPE_OTHER] {
        if let Ok(keys) = storage.list_keys(key_type) {
            for key in keys {
                let _ = storage.delete(key_type, &key);
            }
        }
    }
}

/// Run the suite and render the report as JSON.
///
/// The shape the bindings use: one implementation of the checks, reachable
/// from every language, instead of four that drift.
pub fn run_json(storage: &dyn ProtocolStateStorage) -> String {
    let report = run(storage);
    serde_json::to_string(&report).unwrap_or_else(|err| {
        format!(
            "{{\"passed\":[],\"failures\":[{{\"check\":\"report_serialization\",\"detail\":\"{}\"}}]}}",
            err.to_string().replace('"', "'")
        )
    })
}