envelope.proto RawHistoryFolder

1// Directional envelopes and the connection preamble.
2//
3// The preamble is the fixed, bounded envelope understood before any other
4// payload. The first client frame is always PreambleRequest; the first
5// server frame is always PreambleResponse. Exact version equality is
6// mandatory; the preamble negotiates immutable per-connection ceilings once.
7syntax = "proto3";
8
9package vev.wire.v1;
10
11import "command.proto";
12import "navigation.proto";
13import "picker.proto";
14import "session.proto";
15import "terminal.proto";
16
17option go_package = "github.com/bnema/vev/internal/protocol/wire";
18
19// ProtocolEpoch identifies the current wire epoch. Bumped only for an
20// intentional clean break; ALPN and version checks bind to it. The numeric
21// value lives as wire.ProtocolEpoch in Go; it is documented here as the
22// schema authority (current value 1).
23
24// PreambleMagic is the fixed 4-byte magic opening every preamble. The
25// numeric value lives as wire.PreambleMagic in Go; it is documented here
26// as the schema authority (0x56455631, "VEV1").
27
28// PreambleRole names which side sends the preamble.
29message PreambleRole {
30  // Closed taxonomy: 1 = client, 2 = server.
31  uint32 role = 1;
32}
33
34// PreambleRequest is the client's first frame on every connection.
35message PreambleRequest {
36  uint32 magic = 1; // must equal PREAMBLE_MAGIC
37  uint32 epoch = 2; // must equal PROTOCOL_EPOCH
38  uint32 version = 3; // exact session protocol version
39  PreambleRole role = 4; // must be client
40  uint64 max_receive_envelope_bytes = 5; // advertised receive ceiling
41  uint64 output_data_limit = 6; // advertised Output data ceiling
42  uint32 capability_bits = 7; // optional capability flags
43}
44
45// PreambleRejectionCode is the closed preamble refusal taxonomy.
46message PreambleRejectionCode {
47  // Closed taxonomy: 1 = bad magic, 2 = epoch mismatch, 3 = version
48  // mismatch, 4 = wrong role, 5 = duplicate preamble, 6 = out of order,
49  // 7 = limit refused.
50  uint32 code = 1;
51}
52
53// PreambleResponse is the server's first frame: acceptance or typed refusal.
54message PreambleResponse {
55  uint32 magic = 1; // must equal PREAMBLE_MAGIC
56  uint32 epoch = 2;
57  uint32 version = 3;
58  PreambleRole role = 4; // must be server
59  uint64 max_receive_envelope_bytes = 5; // effective negotiated ceiling
60  uint64 output_data_limit = 6; // effective Output data ceiling
61  uint32 capability_bits = 7;
62  bool accepted = 8;
63  PreambleRejectionCode rejection = 9; // set only when accepted is false
64}
65
66// ClientEnvelope is the closed client-to-server union. Exactly one variant
67// must be set per envelope; sessionwire rejects empty, duplicate, and
68// wrong-direction payloads before generated unmarshal.
69message ClientEnvelope {
70  // 14 was the one-shot remote_preview_request; 27 was picker_preview_request.
71  reserved 14, 27;
72
73  oneof payload {
74    Hello hello = 1;
75    Input input = 2;
76    Resize resize = 3;
77    Detach detach = 4;
78    Ping ping = 5;
79    List list = 6;
80    Kill kill = 7;
81    Theme theme = 8;
82    Ack ack = 9;
83    ImagePush image_push = 10;
84    ClientNotice client_notice = 11;
85    CommandRequest command_request = 12;
86    OutputResetRequest output_reset_request = 13;
87    RouteAttentionSubscription route_attention_subscription = 15;
88    SamePeerSwitchRequest same_peer_switch_request = 16;
89    RecentRouteSnapshot recent_route_snapshot = 17;
90    RouteNavigationFailure route_navigation_failure = 18;
91    SessionCreationFailure session_creation_failure = 19;
92    UIFence ui_fence = 20;
93    NavigationInventoryRequest navigation_inventory_request = 21;
94    NavigationInventoryPublication navigation_inventory_publication = 22;
95    NavigationInventoryFailure navigation_inventory_failure = 23;
96    PickerClose picker_close = 25;
97    PickerSelection picker_selection = 26;
98    SuspendAttachment suspend_attachment = 29;
99    ActivateAttachment activate_attachment = 30;
100    SelectTab select_tab = 31;
101    RemotePreviewWatch remote_preview_watch = 32;
102    TerminalFocus terminal_focus = 33;
103  }
104}
105
106// ServerEnvelope is the closed server-to-client union. Exactly one variant
107// must be set per envelope.
108message ServerEnvelope {
109  // 29 and 30 mirror the client-direction attachment request tags; 27 was
110  // picker_preview.
111  reserved 27, 29, 30;
112
113  oneof payload {
114    Welcome welcome = 1;
115    ErrorMsg error = 2;
116    Output output = 3;
117    Detached detached = 4;
118    Pong pong = 5;
119    Sessions sessions = 6;
120    CommandResult command_result = 7;
121    AttachTarget attach_target = 8;
122    RemotePreview remote_preview = 9;
123    CommittedRouteIdentity committed_route_identity = 10;
124    RouteNavigationAction route_navigation_action = 11;
125    RouteCreateSessionAction route_create_session_action = 12;
126    RouteNavigationFailure route_navigation_failure = 13;
127    RoutePosition route_position = 14;
128    RouteRetired route_retired = 15;
129    SamePeerSwitchFailure same_peer_switch_failure = 16;
130    UIReceipt ui_receipt = 17;
131    UIViewUpdate ui_view_update = 18;
132    NavigationInventoryResponse navigation_inventory_response = 19;
133    NavigationInventoryDemand navigation_inventory_demand = 20;
134    NavigationInventorySelection navigation_inventory_selection = 21;
135    PickerOffer picker_offer = 22;
136    PickerSnapshot picker_snapshot = 23;
137    PickerClosed picker_closed = 24;
138    PickerResult picker_result = 25;
139    PickerFailure picker_failure = 26;
140    AttachmentSuspended attachment_suspended = 31;
141    AttachmentActivated attachment_activated = 32;
142    KillResult kill_result = 33;
143  }
144}