Skip to main content

stateknot_runtime/
driver_schema.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Versioned public-safe journal schema used by the durable graph driver.
5
6use serde_json::Value;
7use stateknot_core::{Digest, SchemaId, SchemaIdError, SchemaReference, Version};
8use thiserror::Error;
9
10use crate::{JsonSchemaRegistryBuilder, JsonSchemaRegistryError};
11
12/// Stable identity of the v1 durable graph-driver event-data schema.
13pub const STANDARD_GRAPH_DRIVER_EVENT_SCHEMA_ID: &str =
14    "https://stknot.com/schemas/runtime/graph-driver-event/1.0.0";
15
16const DOCUMENT: &str = include_str!("../schemas/graph-driver-event-1.0.0.json");
17
18/// Returns the immutable reference and owned JSON Schema document shipped with
19/// this runtime release.
20///
21/// The reference digest is computed from RFC 8785 bytes, so modifying the
22/// embedded document without changing its URI/version changes the returned
23/// reference and is rejected by any deployment that pinned the prior value.
24///
25/// # Errors
26///
27/// Returns [`StandardGraphDriverSchemaError`] only if the release artifact is
28/// internally malformed.
29pub fn standard_graph_driver_event_schema()
30-> Result<(SchemaReference, Value), StandardGraphDriverSchemaError> {
31    let document = serde_json::from_str::<Value>(DOCUMENT)
32        .map_err(|_| StandardGraphDriverSchemaError::EmbeddedDocument)?;
33    let canonical = serde_json_canonicalizer::to_vec(&document)
34        .map_err(|_| StandardGraphDriverSchemaError::Canonicalization)?;
35    let id = STANDARD_GRAPH_DRIVER_EVENT_SCHEMA_ID
36        .parse::<SchemaId>()
37        .map_err(StandardGraphDriverSchemaError::identifier)?;
38    let reference = SchemaReference::new(id, Version::new(1, 0, 0), Digest::sha256(canonical));
39    Ok((reference, document))
40}
41
42/// Registers the standard graph-driver event schema in a startup registry.
43///
44/// # Errors
45///
46/// Returns an embedded-definition error or the registry's ordinary duplicate,
47/// resource, dialect, digest, and reference-resolution failures.
48pub fn register_standard_graph_driver_event_schema(
49    builder: &mut JsonSchemaRegistryBuilder,
50) -> Result<SchemaReference, StandardGraphDriverSchemaRegistrationError> {
51    let (reference, document) = standard_graph_driver_event_schema()?;
52    builder.register(reference.clone(), document)?;
53    Ok(reference)
54}
55
56/// Internal release-artifact failure for the embedded standard schema.
57#[derive(Clone, Debug, Eq, Error, PartialEq)]
58#[non_exhaustive]
59pub enum StandardGraphDriverSchemaError {
60    /// The embedded JSON document cannot be parsed.
61    #[error("embedded graph-driver event schema is invalid JSON")]
62    EmbeddedDocument,
63    /// The embedded document cannot be represented as RFC 8785 bytes.
64    #[error("embedded graph-driver event schema cannot be canonicalized")]
65    Canonicalization,
66    /// The embedded stable HTTPS identifier is invalid.
67    #[error("embedded graph-driver event schema identifier is invalid: {source}")]
68    Identifier {
69        /// Exact identifier validation error.
70        #[source]
71        source: SchemaIdError,
72    },
73}
74
75impl StandardGraphDriverSchemaError {
76    const fn identifier(source: SchemaIdError) -> Self {
77        Self::Identifier { source }
78    }
79}
80
81/// Startup failure while adding the standard driver schema to a registry.
82#[derive(Clone, Debug, Eq, Error, PartialEq)]
83#[non_exhaustive]
84pub enum StandardGraphDriverSchemaRegistrationError {
85    /// The embedded release artifact was malformed.
86    #[error(transparent)]
87    Definition(#[from] StandardGraphDriverSchemaError),
88    /// The target registry rejected the immutable resource.
89    #[error(transparent)]
90    Registry(#[from] JsonSchemaRegistryError),
91}
92
93#[cfg(test)]
94mod tests {
95    use super::*;
96    use crate::JsonSchemaRegistryLimits;
97
98    #[test]
99    fn standard_schema_is_digest_pinned_and_registry_valid() {
100        let (reference, document) = standard_graph_driver_event_schema().unwrap();
101        assert_eq!(
102            reference.id().as_str(),
103            STANDARD_GRAPH_DRIVER_EVENT_SCHEMA_ID
104        );
105        assert_eq!(reference.version(), Version::new(1, 0, 0));
106
107        let mut builder = JsonSchemaRegistryBuilder::new(JsonSchemaRegistryLimits::default());
108        builder.register(reference.clone(), document).unwrap();
109        let registry = builder.build().unwrap();
110        assert!(registry.contains(&reference));
111    }
112}