1// copied from https://github.com/google/quic-trace/
2// Only changed the package name.
3
4syntax = "proto2";
5
6package pb;
7
8option go_package = ".;pb";
9
10enum FrameType {
11  UNKNOWN_FRAME = 0;
12
13  STREAM = 1;
14  ACK = 2;
15  RESET_STREAM = 3;
16  CONNECTION_CLOSE = 4;
17  MAX_DATA = 5;
18  MAX_STREAM_DATA = 6;
19  PING = 7;
20  BLOCKED = 8;
21  STREAM_BLOCKED = 9;
22  PADDING = 10;
23  CRYPTO = 11;
24};
25
26// Metadata for STREAM frames.
27message StreamFrameInfo {
28  optional uint64 stream_id = 1;
29  optional bool fin = 2;
30  optional uint64 length = 3;
31  optional uint64 offset = 4;
32};
33
34// Metadata for CRYPTO frames.
35message CryptoFrameInfo {
36  optional uint64 length = 1;
37  optional uint64 offset = 2;
38}
39
40// The intervals are closed, i.e. the interval represented here is
41// [first_packet, last_packet].
42message AckBlock {
43  optional uint64 first_packet = 1;
44  optional uint64 last_packet = 2;
45};
46
47// Metadata for ACK frames.
48message AckInfo {
49  repeated AckBlock acked_packets = 1;
50  optional uint64 ack_delay_us = 2;
51};
52
53// Metadata for RST_STREAM frames.
54message ResetStreamInfo {
55  optional uint64 stream_id = 1;
56  optional uint32 application_error_code = 2;
57  optional uint64 final_offset = 3;
58};
59
60// Metadata for CONNECTION_CLOSE frames.
61// Close_type will indicate whether the close is a Google QUIC close,
62// IETF QUIC Transport CONNECTION CLOSE, or IETF QUIC Application
63// Connection Close, frame.
64enum CloseType {
65  GOOGLE_QUIC_CONNECTION_CLOSE = 0;
66  IETF_QUIC_TRANSPORT_CONNECTION_CLOSE = 1;
67  IETF_QUIC_APPLICATION_CONNECTION_CLOSE = 2;
68};
69
70// Metadata for CONNECTION_CLOSE/APPLICATION_CLOSE frames.
71message CloseInfo {
72  optional uint32 error_code = 1;
73  optional string reason_phrase = 2;
74  optional CloseType close_type = 3;
75  optional uint64 transport_close_frame_type = 4;
76};
77
78// Metadata for MAX_DATA/MAX_STREAM_DATA frames.
79message FlowControlInfo {
80  optional uint64 max_data = 1;
81  optional uint64 stream_id = 2;
82};
83
84// A message representing a frame, either sent or received.
85message Frame {
86  optional FrameType frame_type = 1;
87
88  optional StreamFrameInfo stream_frame_info = 2;
89  optional AckInfo ack_info = 3;
90  optional ResetStreamInfo reset_stream_info = 4;
91  optional CloseInfo close_info = 5;
92  optional FlowControlInfo flow_control_info = 6;
93  optional CryptoFrameInfo crypto_frame_info = 7;
94};
95
96// Metadata that represents transport stack's understanding of the current state
97// of the transport channel.
98message TransportState {
99  optional uint64 min_rtt_us = 1;
100  // Smoothed RTT, usually computed using EWMA.
101  optional uint64 smoothed_rtt_us = 2;
102  // The latest RTT measureent available.
103  optional uint64 last_rtt_us = 3;
104
105  optional uint64 in_flight_bytes = 4;
106  optional uint64 cwnd_bytes = 5;
107  // Pacing rate, in bits per second.
108  optional uint64 pacing_rate_bps = 6;
109
110  // Any arbitrary information about congestion control state that is not
111  // representable via parameters above.
112  optional string congestion_control_state = 7;
113};
114
115// Documents external network parameters supplied to the sender.  Typically not
116// all of those would be supplied (e.g. if bandwidth and RTT are supplied, you
117// can infer the suggested CWND), but there are no restrictions on which fields
118// may or may not be set.
119message ExternalNetworkParameters {
120  optional uint64 bandwidth_bps = 1;  // in bits per second
121  optional uint64 rtt_us = 2;
122  optional uint64 cwnd_bytes = 3;
123};
124
125enum EncryptionLevel {
126  ENCRYPTION_UNKNOWN = 0;
127
128  ENCRYPTION_INITIAL = 1;
129  ENCRYPTION_0RTT = 2;
130  ENCRYPTION_1RTT = 3;
131  ENCRYPTION_HANDSHAKE = 4;
132};
133
134enum EventType {
135  UNKNOWN_EVENT = 0;
136
137  PACKET_SENT = 1;
138  PACKET_RECEIVED = 2;
139  PACKET_LOST = 3;
140
141  // An APPLICATION_LIMITED event occurs when the sender is capable of sending
142  // more data and tries to send it, but discovers that it does not have any
143  // outstanding data to send.  Such events are important to some congestion
144  // control algorithms (for example, BBR) since they are trying to measure the
145  // largest achievable throughput, but it is impossible to measure it when the
146  // application does not send anything.
147  APPLICATION_LIMITED = 4;
148
149  // Record when external information about expected network conditions
150  // (available bandwidth, RTT, congestion window, etc) is supplied to the
151  // sender.
152  EXTERNAL_PARAMETERS = 5;
153};
154
155enum TransmissionReason {
156  // Indicates that there was not any particular special reason the packet was
157  // sent.
158  NORMAL_TRANSMISSION = 0;
159
160  // Indicates that the packet sent is a tail loss probe, cf.
161  // https://tools.ietf.org/html/draft-ietf-quic-recovery-14#section-4.3.2
162  TAIL_LOSS_PROBE = 1;
163
164  // Indicates that the packet is sent due to retransmission timeout, cf
165  // https://tools.ietf.org/html/draft-ietf-quic-recovery-14#section-4.3.3
166  RTO_TRANSMISSION = 2;
167
168  // Indicates that the packet is sent in order to probe whether there is extra
169  // bandwidth available in cases where the sender needs an estimate of
170  // available bandwidth, but the application does not provide enough data for
171  // such estimate to become naturally available.  This is usually only used in
172  // real-time protocols.
173  PROBING_TRANSMISSION = 3;
174};
175
176// An event that has occurred over duration of the connection.
177message Event {
178  optional uint64 time_us = 1;
179  optional EventType event_type = 2;
180
181  optional uint64 packet_number = 3;
182  repeated Frame frames = 4;
183  optional uint64 packet_size = 5;
184  optional EncryptionLevel encryption_level = 6;
185  // State of the transport stack after the event has happened.
186  optional TransportState transport_state = 7;
187  // For event_type = EXTERNAL_PARAMETERS, record parameters specified.
188  optional ExternalNetworkParameters external_network_parameters = 8;
189
190  // For sent packets, indicate if there is a special reason for why the packet
191  // in question was transmitted.
192  optional TransmissionReason transmission_reason = 9
193      [default = NORMAL_TRANSMISSION];
194};
195
196message Trace {
197  // QUIC version tag, as represented on wire.  Should be always 4 bytes long.
198  optional bytes protocol_version = 1;
199
200  // Source and destination connection ID.  If multiple connection IDs are used,
201  // record the first one used with short-form header.
202  optional bytes source_connection_id = 2;
203  optional bytes destination_connection_id = 3;
204
205  repeated Event events = 4;
206};
207