runtara-protocol 1.3.2

Wire protocol layer for runtara (QUIC transport and Protobuf messages)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# runtara-protocol

[![Crates.io](https://img.shields.io/crates/v/runtara-protocol.svg)](https://crates.io/crates/runtara-protocol)
[![Documentation](https://docs.rs/runtara-protocol/badge.svg)](https://docs.rs/runtara-protocol)
[![License](https://img.shields.io/crates/l/runtara-protocol.svg)](LICENSE)

Wire protocol layer for the [Runtara](https://runtara.com) durable execution platform. Provides QUIC transport and Protobuf message definitions for communication between workflow instances and the execution engine.

## Overview

This crate is the foundation layer used by all other Runtara crates. It provides:

- **QUIC Transport**: Fast, secure communication using the Quinn library
- **Protobuf Messages**: Type-safe message definitions generated by prost
- **TLS Support**: Built-in certificate generation and verification
- **Connection Management**: Client and server connection utilities

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
runtara-protocol = "1.0"
```

## Usage

### Creating a QUIC Client

```rust
use runtara_protocol::quic::{QuicClient, ClientConfig};

// Configure the client
let config = ClientConfig {
    server_addr: "127.0.0.1:8001".parse()?,
    server_name: "localhost".to_string(),
    skip_cert_verification: false,
};

// Create and connect
let client = QuicClient::new(config)?;
let connection = client.connect().await?;
```

### Sending Protocol Messages

```rust
use runtara_protocol::instance::{RegisterRequest, RegisterResponse};
use runtara_protocol::send_request;

// Create a register request
let request = RegisterRequest {
    instance_id: "my-instance".to_string(),
    tenant_id: "tenant-123".to_string(),
    ..Default::default()
};

// Send and receive response
let response: RegisterResponse = send_request(&connection, request).await?;
```

### Creating a QUIC Server

```rust
use runtara_protocol::quic::{QuicServer, ServerConfig};

let config = ServerConfig {
    bind_addr: "0.0.0.0:8001".parse()?,
    ..Default::default()
};

let server = QuicServer::new(config)?;

while let Some(connection) = server.accept().await {
    tokio::spawn(async move {
        // Handle connection
    });
}
```

## Protocol Definitions

The crate includes Protobuf definitions for:

- **Instance Protocol** (`instance.proto`): Communication between workflow instances and runtara-core
  - Register, checkpoint, signal polling, completion
- **Environment Protocol** (`environment.proto`): Management SDK to runtara-environment
  - Image registration, instance lifecycle, status queries
- **Management Protocol** (`management.proto`): Internal communication between environment and core
  - Health, signals, instance status, checkpoint listing/fetch
  - Instance lifecycle and image registration are **not** exposed here; they live in `environment.proto`

## Related Crates

- [`runtara-sdk`](https://crates.io/crates/runtara-sdk) - High-level SDK built on this protocol
- [`runtara-management-sdk`](https://crates.io/crates/runtara-management-sdk) - Management client using this protocol

## License

This project is licensed under [AGPL-3.0-or-later](LICENSE).