rivven_schema/
lib.rs

1//! # Rivven Schema Registry
2//!
3//! A high-performance, Confluent-compatible Schema Registry for the Rivven
4//! event streaming platform.
5//!
6//! ## Features
7//!
8//! - **Confluent API Compatible**: Drop-in replacement for Confluent Schema Registry
9//! - **Multiple Schema Formats**: Avro, JSON Schema, Protobuf
10//! - **Schema Evolution**: Forward, backward, full, and transitive compatibility checking
11//! - **Schema Fingerprinting**: MD5 and SHA-256 for deduplication
12//! - **Storage Backends**: In-memory (dev), Broker-backed (production)
13//! - **External Registries**: Confluent Schema Registry client, AWS Glue integration
14//! - **High Performance**: In-memory caching with async operations
15//! - **Production Ready**: K8s health checks, graceful shutdown
16//!
17//! ## Architecture
18//!
19//! The Schema Registry is responsible for:
20//! - **Storing** schema definitions (as text strings)
21//! - **Versioning** schemas with subjects
22//! - **Checking compatibility** between schema versions
23//! - **Serving** schemas via REST API
24//!
25//! The registry does **NOT** encode/decode data — that's the job of producers
26//! and consumers. Use `rivven-connect` for codecs (Avro, Protobuf, JSON).
27//!
28//! ```text
29//! ┌─────────────────────────────────────────────────────────────┐
30//! │                    Rivven Schema Registry                    │
31//! ├─────────────────────────────────────────────────────────────┤
32//! │  REST API (Confluent-compatible)                            │
33//! │  ├── POST /subjects/{subject}/versions                      │
34//! │  ├── GET  /schemas/ids/{id}                                 │
35//! │  ├── GET  /subjects/{subject}/versions/{version}            │
36//! │  ├── POST /compatibility/subjects/{subject}/versions/{ver}  │
37//! │  ├── GET  /config                                           │
38//! │  └── GET  /health, /health/live, /health/ready              │
39//! ├─────────────────────────────────────────────────────────────┤
40//! │  Schema Management Layer                                     │
41//! │  ├── Schema Parsing (syntax validation)                     │
42//! │  ├── Compatibility Checking (all Confluent modes)           │
43//! │  ├── Fingerprint/ID Generation (MD5, SHA-256)               │
44//! │  └── Caching with deduplication                              │
45//! ├─────────────────────────────────────────────────────────────┤
46//! │  Storage Backends                                            │
47//! │  ├── Memory (development/testing)                           │
48//! │  ├── Broker (production - durable, replicated)              │
49//! │  └── External (Confluent, AWS Glue)                         │
50//! └─────────────────────────────────────────────────────────────┘
51//! ```
52//!
53//! ## Quick Start
54//!
55//! ### As a Library
56//!
57//! ```rust,ignore
58//! use rivven_schema::{SchemaRegistry, RegistryConfig, SchemaType};
59//!
60//! // Create an in-memory registry
61//! let config = RegistryConfig::memory();
62//! let registry = SchemaRegistry::new(config).await?;
63//!
64//! // Register a schema
65//! let avro_schema = r#"{"type": "record", "name": "User", "fields": [{"name": "id", "type": "long"}]}"#;
66//! let schema_id = registry.register("user-value", SchemaType::Avro, avro_schema).await?;
67//!
68//! // Retrieve the schema
69//! let schema = registry.get_by_id(schema_id).await?;
70//! println!("Schema: {}", schema.schema);
71//! ```
72//!
73//! ### As a Standalone Server
74//!
75//! ```bash
76//! # Start with in-memory storage (development/testing)
77//! rivven-schema serve --port 8081
78//! ```
79//!
80//! For production, use broker-backed storage (requires `broker` feature):
81//!
82//! ```rust,ignore
83//! use rivven_schema::{RegistryConfig, BrokerStorageConfig};
84//!
85//! let config = RegistryConfig::broker(
86//!     BrokerStorageConfig::new("localhost:9092")
87//!         .with_topic("_schemas")
88//!         .with_replication_factor(3)
89//! );
90//! ```
91//!
92//! ## Compatibility Modes
93//!
94//! | Mode | Description |
95//! |------|-------------|
96//! | `BACKWARD` | New schema can read old data (default) |
97//! | `BACKWARD_TRANSITIVE` | New schema can read all previous versions |
98//! | `FORWARD` | Old schema can read new data |
99//! | `FORWARD_TRANSITIVE` | All previous schemas can read new data |
100//! | `FULL` | Both backward and forward compatible |
101//! | `FULL_TRANSITIVE` | Full compatibility with all versions |
102//! | `NONE` | No compatibility checking |
103//!
104//! ## Confluent Wire Format
105//!
106//! When using Avro with Schema Registry, data is encoded with a 5-byte header:
107//!
108//! ```text
109//! [0x00][schema_id: 4 bytes big-endian][avro_binary_data]
110//! ```
111//!
112//! This is compatible with Kafka producers/consumers using Confluent serializers.
113//!
114//! ## Best Practices
115//!
116//! 1. **Use Avro in Production**: Schema evolution with compatibility checking
117//! 2. **Subject Naming**: Use `{topic}-key` and `{topic}-value` convention
118//! 3. **Compatibility Level**: Start with `BACKWARD` for safe evolution
119//! 4. **Versioning**: Never delete schemas, only deprecate
120//!
121//! ## Note on Codecs
122//!
123//! The Schema Registry does **not** include codecs for encoding/decoding data.
124//! That's the responsibility of producers and consumers (connectors).
125//! Use `rivven-connect` for Avro/Protobuf/JSON codecs with Confluent wire format.
126
127#[cfg(feature = "server")]
128pub mod auth;
129pub mod compatibility;
130pub mod config;
131pub mod error;
132pub mod fingerprint;
133#[cfg(feature = "metrics")]
134pub mod metrics;
135pub mod registry;
136#[cfg(feature = "server")]
137pub mod server;
138pub mod storage;
139pub mod types;
140pub mod validation;
141
142// Re-exports for convenience
143#[cfg(feature = "cedar")]
144pub use auth::check_subject_permission_cedar;
145#[cfg(feature = "server")]
146pub use auth::{AuthConfig, AuthState, SchemaPermission, ServerAuthState};
147pub use compatibility::{CompatibilityChecker, CompatibilityLevel, CompatibilityResult};
148#[cfg(feature = "broker")]
149pub use config::{BrokerAuthConfig, BrokerStorageConfig, BrokerTlsConfig};
150pub use config::{RegistryConfig, StorageConfig};
151pub use error::{error_codes, SchemaError, SchemaResult};
152pub use fingerprint::SchemaFingerprint;
153#[cfg(feature = "metrics")]
154pub use metrics::{create_shared_metrics, MetricsConfig, RegistryMetrics, SharedMetrics};
155pub use registry::SchemaRegistry;
156#[cfg(feature = "server")]
157pub use server::{RegistryMode, SchemaServer, ServerConfig, ServerState};
158#[cfg(feature = "broker")]
159pub use storage::BrokerStorage;
160pub use storage::{MemoryStorage, Storage, StorageBackend};
161pub use types::{
162    Schema, SchemaContext, SchemaId, SchemaMetadata, SchemaReference, SchemaType, SchemaVersion,
163    Subject, SubjectVersion, ValidationLevel, ValidationReport, ValidationResult, ValidationRule,
164    ValidationRuleType, ValidationSummary, VersionState,
165};
166pub use validation::{ValidationEngine, ValidationEngineConfig};
167
168// Re-export Cedar types when enabled
169#[cfg(feature = "cedar")]
170pub use rivven_core::{AuthzContext, CedarAuthorizer, RivvenAction, RivvenResource};
rivven_schema/lib.rs

rivven_schema/
lib.rs
