second-brain-api 0.13.5

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
mod common;

use std::sync::Arc;

use axum::http::StatusCode;
use tower::ServiceExt;
use uuid::Uuid;

use common::{app_with_store, json_body, post_json};
use second_brain_core::schema::{Entity, Memory, MemoryType, RelationType};
use second_brain_core::sqlite_store::SqliteStore;
use second_brain_core::store::{Store, StoreAdmin};

fn memory(store: &SqliteStore, content: &str) -> Uuid {
    let m = Memory::new(
        content.to_string(),
        MemoryType::Semantic,
        "api".to_string(),
        String::new(),
    );
    store.store_memory(&m).unwrap();
    m.id
}

fn entity(store: &SqliteStore, name: &str) -> Uuid {
    let e = Entity::new(name.to_string(), "technology".to_string());
    store.store_entity(&e).unwrap();
    e.id
}

async fn associate(
    app: &axum::Router,
    from: &str,
    to: &str,
    relation: &str,
) -> (StatusCode, serde_json::Value) {
    let response = app
        .clone()
        .oneshot(post_json(
            "/v1/associate",
            serde_json::json!({"from_id": from, "to_id": to, "relation": relation}),
        ))
        .await
        .unwrap();
    let status = response.status();
    let body = if status == StatusCode::CREATED {
        json_body(response).await
    } else {
        serde_json::json!({ "error": json_body(response).await["error"] })
    };
    (status, body)
}

fn has_relation(
    store: &Arc<SqliteStore>,
    from: Uuid,
    to: Uuid,
    relation_type: RelationType,
) -> bool {
    store
        .get_relations(from, Some(relation_type))
        .unwrap()
        .iter()
        .any(|r| r.to_id == to)
}

#[tokio::test]
async fn two_memories_are_linked_by_id() {
    let (app, store) = app_with_store();
    let a = memory(&store, "a");
    let b = memory(&store, "b");

    let (status, body) = associate(&app, &a.to_string(), &b.to_string(), "reinforces").await;

    assert_eq!(status, StatusCode::CREATED, "{body}");
    assert!(has_relation(&store, a, b, RelationType::Reinforces));
}

#[tokio::test]
async fn an_entity_is_reachable_by_name() {
    let (app, store) = app_with_store();
    let a = memory(&store, "uses the borrow checker");
    let rust = entity(&store, "rust");

    let (status, body) = associate(&app, &a.to_string(), "rust", "relates_to").await;

    assert_eq!(status, StatusCode::CREATED, "{body}");
    assert_eq!(body["to_id"], rust.to_string());
    assert!(
        has_relation(&store, a, rust, RelationType::Mentions),
        "a memory-to-entity edge must be a mentions edge, the only kind sync and repair keep"
    );
    assert_eq!(store.prune_dangling_relations().unwrap(), 0);
    assert!(has_relation(&store, a, rust, RelationType::Mentions));
}

#[tokio::test]
async fn an_entity_cannot_be_the_source_of_a_link() {
    let (app, store) = app_with_store();
    let a = memory(&store, "a");
    entity(&store, "rust");

    let (status, _) = associate(&app, "rust", &a.to_string(), "relates_to").await;
    assert_eq!(status, StatusCode::BAD_REQUEST);
    assert!(store.get_relations(a, None).unwrap().is_empty());
}

#[tokio::test]
async fn only_relates_to_may_point_at_an_entity() {
    let (app, store) = app_with_store();
    let a = memory(&store, "a");
    entity(&store, "rust");

    for relation in ["contradicts", "reinforces"] {
        let (status, _) = associate(&app, &a.to_string(), "rust", relation).await;
        assert_eq!(status, StatusCode::BAD_REQUEST, "{relation}");
    }
    assert!(store.get_relations(a, None).unwrap().is_empty());
}

#[tokio::test]
async fn an_unknown_memory_id_is_a_404_and_writes_nothing() {
    let (app, store) = app_with_store();
    let a = memory(&store, "a");
    let ghost = Uuid::new_v4();

    let (status, body) = associate(&app, &a.to_string(), &ghost.to_string(), "relates_to").await;

    assert_eq!(status, StatusCode::NOT_FOUND, "{body}");
    assert!(body["error"].as_str().unwrap().contains(&ghost.to_string()));
    assert!(store.get_relations(a, None).unwrap().is_empty());
    assert!(store.get_relations(ghost, None).unwrap().is_empty());
}

#[tokio::test]
async fn an_unknown_entity_name_is_a_404() {
    let (app, store) = app_with_store();
    let a = memory(&store, "a");

    let (status, body) = associate(&app, &a.to_string(), "no-such-entity", "relates_to").await;

    assert_eq!(status, StatusCode::NOT_FOUND, "{body}");
    assert!(body["error"].as_str().unwrap().contains("no-such-entity"));
}

#[tokio::test]
async fn an_unknown_relation_is_a_400_rather_than_relates_to() {
    let (app, store) = app_with_store();
    let a = memory(&store, "a");
    let b = memory(&store, "b");

    let (status, body) = associate(&app, &a.to_string(), &b.to_string(), "similar_to").await;

    assert_eq!(status, StatusCode::BAD_REQUEST, "{body}");
    assert!(body["error"].as_str().unwrap().contains("similar_to"));
    assert!(store.get_relations(a, None).unwrap().is_empty());
}

#[tokio::test]
async fn supersedes_retires_the_target_from_recall() {
    let (app, store) = app_with_store();
    let newer = memory(&store, "the port is 8080");
    let older = memory(&store, "the port is 7200");

    let (status, body) =
        associate(&app, &newer.to_string(), &older.to_string(), "supersedes").await;

    assert_eq!(status, StatusCode::CREATED, "{body}");
    assert!(has_relation(&store, newer, older, RelationType::Supersedes));
    assert_eq!(
        store.get_memory(older).unwrap().unwrap().superseded_by,
        Some(newer)
    );
    assert_eq!(
        store.get_memory(newer).unwrap().unwrap().superseded_by,
        None
    );
}

#[tokio::test]
async fn superseding_twice_leaves_the_first_successor() {
    let (app, store) = app_with_store();
    let first = memory(&store, "first");
    let second = memory(&store, "second");
    let older = memory(&store, "older");

    associate(&app, &first.to_string(), &older.to_string(), "supersedes").await;
    let (status, body) =
        associate(&app, &second.to_string(), &older.to_string(), "supersedes").await;

    assert_eq!(status, StatusCode::CONFLICT, "{body}");
    assert_eq!(
        store.get_memory(older).unwrap().unwrap().superseded_by,
        Some(first)
    );
    assert!(!has_relation(
        &store,
        second,
        older,
        RelationType::Supersedes
    ));
}

#[tokio::test]
async fn supersedes_needs_two_distinct_memories() {
    let (app, store) = app_with_store();
    let a = memory(&store, "a");
    let rust = entity(&store, "rust");

    let (status, _) = associate(&app, &a.to_string(), "rust", "supersedes").await;
    assert_eq!(status, StatusCode::BAD_REQUEST);
    let (status, _) = associate(&app, &a.to_string(), &a.to_string(), "supersedes").await;
    assert_eq!(status, StatusCode::BAD_REQUEST);

    assert_eq!(store.get_memory(a).unwrap().unwrap().superseded_by, None);
    assert!(store.get_relations(a, None).unwrap().is_empty());
    assert!(store.get_relations(rust, None).unwrap().is_empty());
}

#[tokio::test]
async fn a_superseded_memory_cannot_supersede_another() {
    let (app, store) = app_with_store();
    let winner = memory(&store, "winner");
    let loser = memory(&store, "loser");
    let bystander = memory(&store, "bystander");
    associate(&app, &winner.to_string(), &loser.to_string(), "supersedes").await;

    let (status, body) = associate(
        &app,
        &loser.to_string(),
        &bystander.to_string(),
        "supersedes",
    )
    .await;

    assert_eq!(status, StatusCode::CONFLICT, "{body}");
    assert_eq!(
        store.get_memory(bystander).unwrap().unwrap().superseded_by,
        None
    );
}