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