graph_r/
lib.rs

1// Author: spicyzhug@gmail.com
2// Copyright: lituus-io, all rights reserved
3//
4//! # graph-r
5//!
6//! An embedded, persistent knowledge graph that acts as the durable backend
7//! for `link-r`: link-r acquires and ranks (crawl, extract, hybrid search);
8//! graph-r remembers and serves (historical graph, adaptive freshness,
9//! token-budgeted local lookups). The two share one foreign key — the 64-bit
10//! xxh3 of a canonical URL — so a link-r index can be absorbed and then
11//! discarded while every lookup keeps resolving.
12//!
13//! ## Design tenets
14//!
15//! - **Zero-copy reads.** The base snapshot is an mmapped, checksummed,
16//!   sectioned file; lookups binary-search fixed-width records in place.
17//! - **Readers never block.** Snapshots pin a generation lock-free; writers
18//!   (any number, across processes) take turns appending to a WAL under a
19//!   commit-scoped lock and publish into an append-only overlay; compaction
20//!   swaps generations under readers without pausing them.
21//! - **Lifetimes over `Arc`.** [`Snapshot`], [`NodeRef`], hits, and iterators
22//!   are borrow guards tied to the [`Store`]; nothing is reference-counted.
23//! - **Determinism.** Compaction is byte-reproducible; ranking, communities,
24//!   and query output are fully ordered with explicit tie-breaks.
25//! - **References, never bodies.** Nodes hold compact lookup metadata (title,
26//!   snippet, anchors, freshness); document bodies and dense vectors stay in
27//!   link-r or at the source URL. Lookups answer with URLs + anchors, which
28//!   is what keeps repeat token spend near zero.
29//!
30//! ## Quick start
31//!
32//! The link-r ingest path is link-r's `graph` feature (`link_r::bridge`),
33//! and object-store mirroring is objstore-r's `mirror` feature; both build
34//! on this crate's core, so none of them is a dependency here:
35//!
36//! ```toml
37//! uu-graph-r = "0.6"
38//! uu-link-r = { version = "0.4", features = ["graph"] }
39//! ```
40#![deny(unsafe_code)]
41#![deny(missing_docs)]
42#![deny(missing_debug_implementations)]
43#![deny(rust_2018_idioms)]
44#![deny(unreachable_pub)]
45#![warn(clippy::all, clippy::pedantic, clippy::cargo)]
46#![allow(
47    clippy::module_name_repetitions,
48    clippy::missing_errors_doc,
49    clippy::missing_panics_doc,
50    clippy::multiple_crate_versions,
51    clippy::cast_possible_truncation,
52    clippy::cast_precision_loss,
53    clippy::cast_sign_loss,
54    clippy::cast_possible_wrap
55)]
56
57// Core (always built; xxh3 is the only dependency): hashing, keys, byte
58// codecs, the checksummed container, errors and file primitives.
59pub mod bytesio;
60pub mod container;
61pub mod error;
62pub mod fsio;
63pub mod hash;
64pub mod key;
65pub mod text;
66
67/// Zero-copy read-only images (feature `mmap`).
68#[cfg(feature = "mmap")]
69pub mod mmap;
70
71// The embedded graph store (feature `store`, on by default).
72#[cfg(feature = "store")]
73mod compact;
74#[cfg(feature = "store")]
75pub mod format;
76#[cfg(feature = "store")]
77mod overlay;
78#[cfg(feature = "store")]
79pub mod query;
80#[cfg(feature = "store")]
81pub mod rank;
82#[cfg(feature = "store")]
83pub mod snapshot;
84#[cfg(feature = "store")]
85pub mod store;
86#[cfg(feature = "store")]
87pub mod traverse;
88#[cfg(feature = "store")]
89pub mod ttl;
90#[cfg(feature = "store")]
91pub mod writer;
92
93pub use error::{Error, Result};
94pub use key::{EdgeType, NodeId, SegKey, UrlKey};
95#[cfg(feature = "store")]
96pub use query::{Anchor, Hit, QueryOpts, TokenBudget};
97#[cfg(feature = "store")]
98pub use snapshot::{DueItem, NodeRef, SegRef, Snapshot};
99#[cfg(feature = "store")]
100pub use store::{CommitLock, Config, Durability, Store};
101#[cfg(feature = "store")]
102pub use traverse::{Direction, EdgeRef, Hop, LendingIterator, Neighbors, Walk};
103#[cfg(feature = "store")]
104pub use ttl::{Outcome, TtlConfig};
105#[cfg(feature = "store")]
106pub use writer::{DocRecord, SegmentRecord, Touch, Txn, Writer};
107
108/// Convenient single-line import of the working set.
109#[cfg(feature = "store")]
110pub mod prelude {
111    pub use crate::{
112        Config, DocRecord, Durability, EdgeType, Error, Hit, LendingIterator, NodeId, NodeRef,
113        Outcome, QueryOpts, Result, SegmentRecord, Snapshot, Store, TokenBudget, Touch, TtlConfig,
114        Txn, UrlKey, Writer,
115    };
116}
graph_r/lib.rs

graph_r/
lib.rs
