reddb_wire/
knowledge.rs

1//! Agent-facing connection-model knowledge reference.
2//!
3//! Supported URI schemes are generated from the connection layer's
4//! [`crate::conn_string::SUPPORTED_SCHEMES`] catalog. The deployment topology
5//! guidance is hand-authored narrative per ADR 0061.
6
7use crate::conn_string::{ConnectionScheme, SUPPORTED_SCHEMES};
8
9/// Canonical URI for the connection-model knowledge resource served over MCP.
10pub const RESOURCE_URI: &str = "reddb://knowledge/connections";
11
12/// Short human title for the connection knowledge resource.
13pub const RESOURCE_TITLE: &str = "RedDB Connection Model";
14
15/// One-line description of the connection knowledge resource.
16pub const RESOURCE_DESCRIPTION: &str =
17    "Generated URI scheme/transport catalog plus the RedDB deployment topology guide.";
18
19/// Markers delimiting the generated connection block inside `docs/llms.txt`.
20pub const LLMS_BEGIN_MARKER: &str = "<!-- BEGIN GENERATED: connections -->";
21/// Closing marker for the generated connection block in `docs/llms.txt`.
22pub const LLMS_END_MARKER: &str = "<!-- END GENERATED: connections -->";
23
24struct Topology {
25    name: &'static str,
26    summary: &'static str,
27}
28
29const TOPOLOGIES: &[Topology] = &[
30    Topology {
31        name: "Embedded / standalone",
32        summary: "`memory://` and `file://` run the engine in the caller's process; \
33a standalone server exposes the same engine over RedWire, gRPC, and HTTP.",
34    },
35    Topology {
36        name: "Serverless",
37        summary: "Serverless callers usually keep no local state and connect to a managed \
38endpoint. Prefer `reds://` when RedWire is reachable; use HTTPS/gRPC only when the platform \
39requires those transports.",
40    },
41    Topology {
42        name: "Primary-replica",
43        summary: "A primary accepts writes while replicas serve read traffic after replication. \
44Multi-host remote URIs express primary-first routing, with `?route=primary` available when reads \
45must stay on the primary.",
46    },
47    Topology {
48        name: "Cluster",
49        summary: "Cluster deployments coordinate multiple RedDB nodes behind the same logical \
50database. RedWire (`red://` / `reds://`) is the principal data-plane transport; gRPC and HTTP are \
51compatibility/admin surfaces, not the only way to connect.",
52    },
53];
54
55/// Full Markdown body served by the MCP resource.
56pub fn connection_reference_markdown() -> String {
57    let mut out = String::new();
58    push_intro(&mut out);
59    push_supported_schemes(&mut out);
60    push_topologies(&mut out);
61    out
62}
63
64/// The connection block as embedded in `docs/llms.txt`.
65pub fn connection_llms_section() -> String {
66    format!(
67        "{LLMS_BEGIN_MARKER}\n{}\n{LLMS_END_MARKER}",
68        connection_reference_markdown().trim_end()
69    )
70}
71
72fn push_intro(out: &mut String) {
73    out.push_str("# RedDB Connection Model\n\n");
74    out.push_str(
75        "RedWire (`red://` / `reds://`) is RedDB's principal transport. \
76gRPC, HTTP(S), browser WebSocket variants, `memory://`, and `file://` are supported connection \
77surfaces, but agents should not collapse the model to \"only gRPC\" or \"only WebSocket\".\n\n",
78    );
79}
80
81fn push_supported_schemes(out: &mut String) {
82    out.push_str("## Supported URI Schemes and Transports\n\n");
83    out.push_str("| URI scheme | Transport | Mode | Example | Notes |\n");
84    out.push_str("|---|---|---|---|---|\n");
85    for scheme in SUPPORTED_SCHEMES {
86        push_scheme_row(out, *scheme);
87    }
88    out.push('\n');
89}
90
91fn push_scheme_row(out: &mut String, scheme: ConnectionScheme) {
92    out.push_str("| `");
93    out.push_str(scheme.uri_prefix());
94    out.push_str("` | ");
95    out.push_str(scheme.transport());
96    out.push_str(" | ");
97    out.push_str(scheme.mode());
98    out.push_str(" | `");
99    out.push_str(scheme.example());
100    out.push_str("` | ");
101    out.push_str(scheme.notes());
102    out.push_str(" |\n");
103}
104
105fn push_topologies(out: &mut String) {
106    out.push_str("## Deployment Topologies\n\n");
107    for topology in TOPOLOGIES {
108        out.push_str("### ");
109        out.push_str(topology.name);
110        out.push_str("\n\n");
111        out.push_str(topology.summary);
112        out.push_str("\n\n");
113    }
114}
115
116#[cfg(test)]
117mod tests {
118    use super::*;
119
120    #[test]
121    fn supported_scheme_examples_parse() {
122        for scheme in SUPPORTED_SCHEMES {
123            crate::conn_string::parse(scheme.example()).unwrap_or_else(|err| {
124                panic!("{} example did not parse: {err}", scheme.uri_prefix())
125            });
126        }
127    }
128
129    #[test]
130    fn reference_lists_supported_schemes_from_connection_layer() {
131        let markdown = connection_reference_markdown();
132        for scheme in SUPPORTED_SCHEMES {
133            let needle = format!("`{}`", scheme.uri_prefix());
134            assert!(markdown.contains(&needle), "missing {needle}");
135        }
136    }
137
138    #[test]
139    fn reference_covers_principal_transport_and_topologies() {
140        let markdown = connection_reference_markdown();
141        assert!(markdown.contains("principal transport"));
142        assert!(markdown.contains("RedWire (`red://` / `reds://`)"));
143        for topology in TOPOLOGIES {
144            assert!(
145                markdown.contains(topology.name),
146                "missing {}",
147                topology.name
148            );
149        }
150    }
151
152    #[test]
153    fn llms_section_wraps_reference() {
154        let section = connection_llms_section();
155        assert!(section.starts_with(LLMS_BEGIN_MARKER));
156        assert!(section.ends_with(LLMS_END_MARKER));
157        let reference = connection_reference_markdown();
158        assert!(section.contains(reference.trim_end()));
159    }
160}
reddb_wire/knowledge.rs

reddb_wire/
knowledge.rs
