actr-protocol 0.4.10

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
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

// 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;
}

// Direction of an RpcEnvelope on the wire.
//
// Receivers route explicitly on this field instead of inferring
// request-vs-response from pending-state. Absence, DIRECTION_UNSPECIFIED,
// and unknown future values are invalid on the current wire protocol;
// receivers should warn and drop instead of guessing from local pending state.
//
// Senders MUST set this on every envelope they construct.
//
// Receivers trust this label without cross-checking pending state, so a
// mislabeled envelope is routed by its label: a request stamped Response is
// dropped if its request_id isn't pending, and a response stamped Request is
// enqueued as a new call. The orphan-drop log includes route_key to make
// such mislabels diagnosable.
enum Direction {
    DIRECTION_UNSPECIFIED = 0;  // Invalid default / missing direction sentinel
    DIRECTION_REQUEST = 1;      // A new RPC call addressed to a handler
    DIRECTION_RESPONSE = 2;     // A reply (success payload or ErrorResponse) to a prior request
}

// 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;

    // Envelope direction: Request or Response. See `Direction` above.
    optional Direction direction = 4;

    // 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