runtara_protocol/lib.rs
1// Copyright (C) 2025 SyncMyOrders Sp. z o.o.
2// SPDX-License-Identifier: AGPL-3.0-or-later
3//! Runtara Protocol - QUIC + Protobuf communication layer
4//!
5//! This crate provides the wire protocol for communication between:
6//! - Instances and runtara-core (instance protocol)
7//! - External clients and runtara-core (management protocol)
8//!
9//! # Architecture
10//!
11//! ```text
12//! ┌─────────────────────────────────────────────────────────────┐
13//! │ runtara-protocol │
14//! ├─────────────────────────────────────────────────────────────┤
15//! │ RPC Layer: Request/Response + Bidirectional Streaming │
16//! ├─────────────────────────────────────────────────────────────┤
17//! │ Serialization: Protobuf (prost) │
18//! ├─────────────────────────────────────────────────────────────┤
19//! │ Transport: QUIC (quinn) │
20//! └─────────────────────────────────────────────────────────────┘
21//! ```
22//!
23//! # Protocols
24//!
25//! ## Instance Protocol (`instance_proto`)
26//!
27//! Used by instances to communicate with runtara-core:
28//! - Registration, checkpointing, sleep/wake
29//! - Events (started, progress, completed, failed)
30//! - Signal polling and acknowledgment
31//!
32//! ## Management Protocol (`management_proto`)
33//!
34//! Used by external clients to manage runtara-core:
35//! - Health checks
36//! - Send signals to instances
37//! - Query instance status
38//! - List instances
39//!
40//! # Usage
41//!
42//! ## Instance Client (scenarios)
43//!
44//! ```ignore
45//! use runtara_protocol::{RuntaraClient, RuntaraClientConfig, instance_proto};
46//!
47//! let client = RuntaraClient::localhost()?;
48//! client.connect().await?;
49//!
50//! let request = instance_proto::RegisterInstanceRequest {
51//! instance_id: "my-instance".to_string(),
52//! tenant_id: "tenant-1".to_string(),
53//! checkpoint_id: None,
54//! };
55//!
56//! let rpc_request = instance_proto::RpcRequest {
57//! request: Some(instance_proto::rpc_request::Request::RegisterInstance(request)),
58//! };
59//!
60//! let response: instance_proto::RpcResponse = client.request(&rpc_request).await?;
61//! ```
62//!
63//! ## Management Client
64//!
65//! ```ignore
66//! use runtara_protocol::{RuntaraClient, management_proto};
67//!
68//! let client = RuntaraClient::localhost()?;
69//! client.connect().await?;
70//!
71//! let request = management_proto::HealthCheckRequest {};
72//! let rpc_request = management_proto::RpcRequest {
73//! request: Some(management_proto::rpc_request::Request::HealthCheck(request)),
74//! };
75//!
76//! let response: management_proto::RpcResponse = client.request(&rpc_request).await?;
77//! ```
78
79pub mod client;
80pub mod frame;
81pub mod server;
82
83// Re-export generated protobuf types for instance protocol
84pub mod instance_proto {
85 include!(concat!(env!("OUT_DIR"), "/runtara.instance.rs"));
86}
87
88// Re-export generated protobuf types for management protocol (internal API for Core)
89pub mod management_proto {
90 include!(concat!(env!("OUT_DIR"), "/runtara.management.rs"));
91}
92
93// Re-export generated protobuf types for environment protocol (main management API)
94pub mod environment_proto {
95 include!(concat!(env!("OUT_DIR"), "/runtara.environment.rs"));
96}
97
98// Re-export main types
99pub use client::{ClientError, RuntaraClient, RuntaraClientConfig};
100pub use frame::{Frame, FrameError, FramedStream, MessageType};
101pub use server::{
102 ConnectionHandler, RuntaraServer, RuntaraServerConfig, ServerError, StreamHandler,
103};