aeo-graph-explorer 0.1.1

HTTP graph-query service over AEO Protocol crawls. Ingests aeo-crawler JSON Lines, builds an in-memory typed graph, exposes /nodes /neighbors /shortest-path /find-by-claim. Layer 5 of the AEO Reference Stack. Optional audit-stream-py integration via the `audit-stream` feature.
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

//! # aeo-graph-explorer
//!
//! HTTP graph-query service over AEO Protocol crawls.
//!
//! ## The fifth layer of the AEO Reference Stack
//!
//! ```text
//! 1. SDKs       aeo-sdk-python / -typescript / -rust / -go / -swift
//! 2. CLI        aeo-cli
//! 3. Crawler    aeo-crawler                 produces JSONL
//! 4. Validator  aeo-validator-service       always-on validation + drift
//! 5. Explorer   aeo-graph-explorer-rs       <- this repo
//! ```
//!
//! ## What it does
//!
//! `aeo-crawler` BFS-walks an AEO graph from a seed URL and dumps one node
//! per JSON line. That's a great pipeline output and a terrible query
//! interface. This crate ingests the JSONL into a typed petgraph + an
//! `axum` HTTP layer, so callers can ask:
//!
//! - `GET /nodes` — list every entity in the graph.
//! - `GET /nodes/{id}` — fetch one entity's full AEO doc.
//! - `GET /nodes/{id}/neighbors` — declared peers + reverse references.
//! - `GET /shortest-path?from=X&to=Y` — does a citation chain connect them?
//! - `GET /find-by-claim?predicate=...&value=...` — pull entities whose
//!   claims match a predicate/value pair.
//! - `POST /ingest` — load a JSONL document and rebuild the graph atomically.
//!
//! ## Design
//!
//! - Graph is `petgraph::Graph<AeoNode, EdgeKind>`; cheap to walk, cheap to
//!   serialize. Edge kinds (`DeclaresPeer`, `CitesAuthority`) are typed so
//!   future endpoints can answer "what authorities does X chain through?"
//!   without re-walking.
//! - The whole graph lives behind a `tokio::sync::RwLock` so an `/ingest`
//!   atomically replaces it. Read paths take a snapshot and never block
//!   each other.
//! - No database. Crawls are small (thousands of nodes, not millions) and
//!   the right tool for "give me a queryable view of a recent crawl" is an
//!   in-memory graph.
//!
//! ## Composes with
//!
//! - **[aeo-crawler](https://github.com/mizcausevic-dev/aeo-crawler)** —
//!   produces the JSONL this service ingests.
//! - **[aeo-validator-service](https://github.com/mizcausevic-dev/aeo-validator-service)**
//!   — call `POST /watches` for every node returned by `/nodes` to set up
//!   drift tracking across the whole graph.
//! - **[incident-correlation-rs](https://github.com/mizcausevic-dev/incident-correlation-rs)**
//!   — when an incident lands, ask `/find-by-claim` for everyone declaring
//!   the affected entity, then seed the correlator with the result.

#![warn(missing_docs)]
#![warn(rust_2018_idioms)]
#![warn(clippy::pedantic)]
#![allow(clippy::module_name_repetitions)]
#![allow(clippy::missing_errors_doc)]
#![allow(clippy::missing_panics_doc)]
#![allow(clippy::must_use_candidate)]
#![allow(clippy::doc_markdown)]

pub mod app;
pub mod error;
pub mod graph;
pub mod model;
pub mod query;

/// Optional audit-stream-py producer. Gated behind the `audit-stream`
/// Cargo feature (on by default for the binary service).
#[cfg(feature = "audit-stream")]
pub mod audit_stream;

pub use app::{build_router, AppState};
pub use error::GraphError;
pub use graph::{AeoGraph, EdgeKind};
pub use model::{AeoClaim, AeoEntity, AeoNode};
pub use query::{
    find_by_claim, neighbors, shortest_path, ClaimMatch, NeighborView, PathHop, PathResult,
};