github_mcp/validation/
validator.rs

1// GitHub v3 REST API MCP server — generated by mcpify. Do not hand-edit.
2//
3// jsonschema-based input/output validation. Schemas themselves are NOT
4// embedded directly in this file's logic — they're loaded from a bundled
5// zstd asset. Concatenating the per-version JSON before compression lets
6// zstd reuse GitHub's shared schema vocabulary and keeps the published
7// crate below crates.io's upload limit without dropping API versions.
8//
9// The asset is zstd-compressed: every operation's schema embeds a full
10// copy of the spec's `$defs` library (a deliberate generator tradeoff —
11// see `mcpify`'s `openapi::schema_resolve` — simpler than cross-schema
12// `$ref` resolution, at the cost of file size), and a long-distance-
13// matching compressor collapses that duplication (measured ~190 MB down
14// to tens of KB on a real spec) without requiring any change to the JSON
15// Schema shape itself. The bundle is decompressed transiently when a
16// version is first requested; only that version remains in the cache.
17
18use std::collections::HashMap;
19use std::sync::{Mutex, OnceLock};
20
21use serde::Deserialize;
22use serde_json::Value;
23
24use crate::core::errors::McpifyError;
25
26#[derive(Debug, Deserialize)]
27struct OperationSchemas {
28    #[serde(rename = "inputSchema")]
29    input_schema: Value,
30    #[serde(rename = "outputSchema")]
31    output_schema: Value,
32}
33
34const SCHEMAS_BUNDLE: &[u8] = include_bytes!("generated_schemas_bundle.json.zst");
35
36// Byte ranges in the decompressed concatenation, in bundle build order.
37// mcpify:versions:begin
38fn schemas_range_for(api_version: &str) -> Option<std::ops::Range<usize>> {
39    match api_version {
40        "gh-2026-03-10" => Some(0..9_892_489),
41        "ghec-2026-03-10" => Some(9_892_489..20_491_342),
42        "ghes-3.21" => Some(20_491_342..31_436_856),
43        "ghes-3.20" => Some(31_436_856..41_925_923),
44        _ => None,
45    }
46}
47// mcpify:versions:end
48
49fn schemas_by_operation(api_version: &str) -> &'static HashMap<String, OperationSchemas> {
50    static SCHEMAS: OnceLock<Mutex<HashMap<String, &'static HashMap<String, OperationSchemas>>>> =
51        OnceLock::new();
52    static EMPTY: OnceLock<HashMap<String, OperationSchemas>> = OnceLock::new();
53    let empty = EMPTY.get_or_init(HashMap::new);
54
55    let cache = SCHEMAS.get_or_init(|| Mutex::new(HashMap::new()));
56    let mut cache = cache.lock().unwrap();
57    if let Some(schemas) = cache.get(api_version) {
58        return schemas;
59    }
60
61    let Some(range) = schemas_range_for(api_version) else {
62        return empty;
63    };
64    let parsed: HashMap<String, OperationSchemas> = zstd::decode_all(SCHEMAS_BUNDLE)
65        .ok()
66        .and_then(|json| {
67            json.get(range)
68                .and_then(|slice| serde_json::from_slice(slice).ok())
69        })
70        .unwrap_or_default();
71    let leaked: &'static HashMap<String, OperationSchemas> = Box::leak(Box::new(parsed));
72    cache.insert(api_version.to_string(), leaked);
73    leaked
74}
75
76fn validate_against(
77    cache: &Mutex<HashMap<String, jsonschema::Validator>>,
78    operation_id: &str,
79    schema: &Value,
80    data: &Value,
81) -> Result<(), Vec<String>> {
82    let mut cache = cache.lock().unwrap();
83    let validator = cache.entry(operation_id.to_string()).or_insert_with(|| {
84        jsonschema::validator_for(schema).unwrap_or_else(|_| {
85            jsonschema::validator_for(&Value::Object(Default::default())).unwrap()
86        })
87    });
88
89    if validator.is_valid(data) {
90        return Ok(());
91    }
92    let errors = validator
93        .iter_errors(data)
94        .map(|error| error.to_string())
95        .collect::<Vec<_>>();
96    Err(errors)
97}
98
99/// Returns `Err` if `data` doesn't satisfy `operation_id`'s input schema,
100/// for the given `api_version`.
101pub fn validate_input(
102    api_version: &str,
103    operation_id: &str,
104    data: &Value,
105) -> Result<(), McpifyError> {
106    static CACHE: OnceLock<Mutex<HashMap<String, jsonschema::Validator>>> = OnceLock::new();
107    let cache = CACHE.get_or_init(|| Mutex::new(HashMap::new()));
108
109    let empty = Value::Object(Default::default());
110    let schema = schemas_by_operation(api_version)
111        .get(operation_id)
112        .map(|schemas| &schemas.input_schema)
113        .unwrap_or(&empty);
114
115    let cache_key = format!("{api_version} {operation_id}");
116    validate_against(cache, &cache_key, schema, data).map_err(|errors| McpifyError::Validation {
117        message: format!("invalid input for '{operation_id}'"),
118        details: Some(serde_json::json!(errors)),
119    })
120}
121
122/// Returns `Err` if `data` doesn't satisfy `operation_id`'s output schema
123/// — surfaces upstream API drift as a structured error rather than
124/// silently returning a mismatched response (architecture.md's `call`
125/// pipeline). Validates against the given `api_version`'s schema.
126pub fn validate_output(
127    api_version: &str,
128    operation_id: &str,
129    data: &Value,
130) -> Result<(), McpifyError> {
131    static CACHE: OnceLock<Mutex<HashMap<String, jsonschema::Validator>>> = OnceLock::new();
132    let cache = CACHE.get_or_init(|| Mutex::new(HashMap::new()));
133
134    let empty = Value::Object(Default::default());
135    let schema = schemas_by_operation(api_version)
136        .get(operation_id)
137        .map(|schemas| &schemas.output_schema)
138        .unwrap_or(&empty);
139
140    let cache_key = format!("{api_version} {operation_id}");
141    validate_against(cache, &cache_key, schema, data).map_err(|errors| McpifyError::Validation {
142        message: format!("unexpected response shape for '{operation_id}'"),
143        details: Some(serde_json::json!(errors)),
144    })
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150
151    // These tests deliberately use an operationId that generated_schemas.json
152    // never declares — they exercise the "no schema found" fallback (an
153    // always-valid `{}` schema), rather than any spec-dependent content
154    // this project's own generation happened to produce.
155
156    #[test]
157    fn an_unknown_operation_id_falls_back_to_an_always_valid_schema() {
158        assert!(
159            validate_input(
160                "gh-2026-03-10",
161                "__unknown_operation__",
162                &serde_json::json!({"anything": true})
163            )
164            .is_ok()
165        );
166        assert!(
167            validate_output(
168                "gh-2026-03-10",
169                "__unknown_operation__",
170                &serde_json::json!(42)
171            )
172            .is_ok()
173        );
174    }
175
176    #[test]
177    fn an_unknown_api_version_also_falls_back_to_an_always_valid_schema() {
178        assert!(
179            validate_input(
180                "__unknown_version__",
181                "__unknown_operation__",
182                &serde_json::json!({"anything": true})
183            )
184            .is_ok()
185        );
186    }
187
188    #[test]
189    fn bundled_schemas_decode_for_every_known_version() {
190        for version in ["gh-2026-03-10", "ghec-2026-03-10", "ghes-3.21", "ghes-3.20"] {
191            assert!(!schemas_by_operation(version).is_empty(), "{version}");
192        }
193    }
194
195    #[test]
196    fn validate_against_reports_every_schema_violation() {
197        static CACHE: OnceLock<Mutex<HashMap<String, jsonschema::Validator>>> = OnceLock::new();
198        let cache = CACHE.get_or_init(|| Mutex::new(HashMap::new()));
199        let schema = serde_json::json!({
200            "type": "object",
201            "required": ["name"],
202            "properties": { "name": { "type": "string" } },
203        });
204
205        let ok = validate_against(
206            cache,
207            "test_op_ok",
208            &schema,
209            &serde_json::json!({"name": "widget"}),
210        );
211        assert!(ok.is_ok());
212
213        let err = validate_against(cache, "test_op_missing", &schema, &serde_json::json!({}));
214        assert!(err.is_err());
215    }
216
217    #[test]
218    fn validate_against_falls_back_to_an_always_valid_schema_when_compilation_fails() {
219        static CACHE: OnceLock<Mutex<HashMap<String, jsonschema::Validator>>> = OnceLock::new();
220        let cache = CACHE.get_or_init(|| Mutex::new(HashMap::new()));
221        // "not-a-real-type" isn't a recognized JSON Schema `type` value, so
222        // `jsonschema::validator_for` fails to compile it — exercising the
223        // always-valid-empty-schema fallback rather than a real validator.
224        let uncompilable_schema = serde_json::json!({"type": "not-a-real-type"});
225
226        let result = validate_against(
227            cache,
228            "test_op_uncompilable_schema",
229            &uncompilable_schema,
230            &serde_json::json!({"anything": true}),
231        );
232        assert!(result.is_ok());
233    }
234}
github_mcp/validation/validator.rs

github_mcp/validation/
validator.rs
