actr-protocol 0.3.0

Unified protocol, types, and URI parsing for Actor-RTC framework
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

// Copyright 2025 actr Project Authors
//
// Licensed under the Apache License, Version 2.0
// Package-level message envelopes

syntax = "proto2";

package actr;

import "actr.proto";

// Metadata key-value pair
message MetadataEntry {
    required string key = 1;
    required string value = 2;
}

// RpcEnvelope wraps State Path RPC messages
message RpcEnvelope {
    // Route key: "package.Service.Method"
    required string route_key = 1;

    // Payload for successful RPC (request or response)
    // Optional: when error is present, payload should be empty
    optional bytes payload = 2;

    // System-level error (envelope layer)
    // Examples: UnknownRoute, DeserializationError, Panic, InvalidStateTransition
    // Business errors should be in the response message payload
    optional ErrorResponse error = 3;

    // W3C trace context header values (for distributed tracing)
    optional string traceparent = 100;  // W3C trace context header value
    optional string tracestate = 101;  // W3C trace state header value

    required string request_id = 102;
    repeated MetadataEntry metadata = 103;
    required int64 timeout_ms = 104;
}

// DataStream - Application data stream packet (Fast Path)
//
// For streaming application data (non-media):
// - File transfer chunks
// - Game state updates
// - Custom protocol streams
message DataStream {
    required string stream_id = 1;
    required uint64 sequence = 2;
    required bytes payload = 3;
    repeated MetadataEntry metadata = 4;
    optional int64 timestamp_ms = 5;
}

// NOTE: MediaFrame is NOT needed as a protobuf message.
// Media streaming uses WebRTC native MediaStreamTrack API:
// - Each track is a separate RTP channel with its own ID
// - RTP headers already contain sequence numbers, timestamps, SSRC
// - No protobuf serialization overhead
// - MediaFrameRegistry maps track_id to native frame callbacks