quiche_apps/
args.rs

1// Copyright (C) 2020, Cloudflare, Inc.
2// All rights reserved.
3//
4// Redistribution and use in source and binary forms, with or without
5// modification, are permitted provided that the following conditions are
6// met:
7//
8//     * Redistributions of source code must retain the above copyright notice,
9//       this list of conditions and the following disclaimer.
10//
11//     * Redistributions in binary form must reproduce the above copyright
12//       notice, this list of conditions and the following disclaimer in the
13//       documentation and/or other materials provided with the distribution.
14//
15// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
16// IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
17// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
19// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
22// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
23// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
24// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26
27use super::common::alpns;
28
29pub trait Args {
30    fn with_docopt(docopt: &docopt::Docopt) -> Self;
31}
32
33/// Contains commons arguments for creating a quiche QUIC connection.
34pub struct CommonArgs {
35    pub alpns: Vec<&'static [u8]>,
36    pub max_data: u64,
37    pub max_window: u64,
38    pub max_stream_data: u64,
39    pub max_stream_window: u64,
40    pub max_streams_bidi: u64,
41    pub max_streams_uni: u64,
42    pub idle_timeout: u64,
43    pub early_data: bool,
44    pub dump_packet_path: Option<String>,
45    pub no_grease: bool,
46    pub cc_algorithm: String,
47    pub disable_hystart: bool,
48    pub dgrams_enabled: bool,
49    pub dgram_count: u64,
50    pub dgram_data: String,
51    pub max_active_cids: u64,
52    pub enable_active_migration: bool,
53    pub max_field_section_size: Option<u64>,
54    pub qpack_max_table_capacity: Option<u64>,
55    pub qpack_blocked_streams: Option<u64>,
56    pub initial_cwnd_packets: u64,
57}
58
59/// Creates a new `CommonArgs` structure using the provided [`Docopt`].
60///
61/// The `Docopt` usage String needs to include the following:
62///
63/// --http-version VERSION      HTTP version to use.
64/// --max-data BYTES            Connection-wide flow control limit.
65/// --max-window BYTES          Connection-wide max receiver window.
66/// --max-stream-data BYTES     Per-stream flow control limit.
67/// --max-stream-window BYTES   Per-stream max receiver window.
68/// --max-streams-bidi STREAMS  Number of allowed concurrent streams.
69/// --max-streams-uni STREAMS   Number of allowed concurrent streams.
70/// --dump-packets PATH         Dump the incoming packets in PATH.
71/// --no-grease                 Don't send GREASE.
72/// --cc-algorithm NAME         Set a congestion control algorithm.
73/// --disable-hystart           Disable HyStart++.
74/// --dgram-proto PROTO         DATAGRAM application protocol.
75/// --dgram-count COUNT         Number of DATAGRAMs to send.
76/// --dgram-data DATA           DATAGRAM data to send.
77/// --max-active-cids NUM       Maximum number of active Connection IDs.
78/// --enable-active-migration   Enable active connection migration.
79/// --max-field-section-size BYTES  Max size of uncompressed field section.
80/// --qpack-max-table-capacity BYTES  Max capacity of dynamic QPACK decoding.
81/// --qpack-blocked-streams STREAMS  Limit of blocked streams while decoding.
82/// --initial-cwnd-packets      Size of initial congestion window, in packets.
83///
84/// [`Docopt`]: https://docs.rs/docopt/1.1.0/docopt/
85impl Args for CommonArgs {
86    fn with_docopt(docopt: &docopt::Docopt) -> Self {
87        let args = docopt.parse().unwrap_or_else(|e| e.exit());
88
89        let http_version = args.get_str("--http-version");
90        let dgram_proto = args.get_str("--dgram-proto");
91        let (alpns, dgrams_enabled) = match (http_version, dgram_proto) {
92            ("HTTP/0.9", "none") => (alpns::HTTP_09.to_vec(), false),
93
94            ("HTTP/0.9", _) =>
95                panic!("Unsupported HTTP version and DATAGRAM protocol."),
96
97            ("HTTP/3", "none") => (alpns::HTTP_3.to_vec(), false),
98
99            ("HTTP/3", "oneway") => (alpns::HTTP_3.to_vec(), true),
100
101            ("all", "none") => (
102                [alpns::HTTP_3.as_slice(), &alpns::HTTP_09]
103                    .concat()
104                    .to_vec(),
105                false,
106            ),
107
108            (..) => panic!("Unsupported HTTP version and DATAGRAM protocol."),
109        };
110
111        let dgram_count = args.get_str("--dgram-count");
112        let dgram_count = dgram_count.parse::<u64>().unwrap();
113
114        let dgram_data = args.get_str("--dgram-data").to_string();
115
116        let max_data = args.get_str("--max-data");
117        let max_data = max_data.parse::<u64>().unwrap();
118
119        let max_window = args.get_str("--max-window");
120        let max_window = max_window.parse::<u64>().unwrap();
121
122        let max_stream_data = args.get_str("--max-stream-data");
123        let max_stream_data = max_stream_data.parse::<u64>().unwrap();
124
125        let max_stream_window = args.get_str("--max-stream-window");
126        let max_stream_window = max_stream_window.parse::<u64>().unwrap();
127
128        let max_streams_bidi = args.get_str("--max-streams-bidi");
129        let max_streams_bidi = max_streams_bidi.parse::<u64>().unwrap();
130
131        let max_streams_uni = args.get_str("--max-streams-uni");
132        let max_streams_uni = max_streams_uni.parse::<u64>().unwrap();
133
134        let idle_timeout = args.get_str("--idle-timeout");
135        let idle_timeout = idle_timeout.parse::<u64>().unwrap();
136
137        let early_data = args.get_bool("--early-data");
138
139        let dump_packet_path = if !args.get_str("--dump-packets").is_empty() {
140            Some(args.get_str("--dump-packets").to_string())
141        } else {
142            None
143        };
144
145        let no_grease = args.get_bool("--no-grease");
146
147        let cc_algorithm = args.get_str("--cc-algorithm");
148
149        let disable_hystart = args.get_bool("--disable-hystart");
150
151        let max_active_cids = args.get_str("--max-active-cids");
152        let max_active_cids = max_active_cids.parse::<u64>().unwrap();
153
154        let enable_active_migration = args.get_bool("--enable-active-migration");
155
156        let max_field_section_size =
157            if !args.get_str("--max-field-section-size").is_empty() {
158                Some(
159                    args.get_str("--max-field-section-size")
160                        .parse::<u64>()
161                        .unwrap(),
162                )
163            } else {
164                None
165            };
166
167        let qpack_max_table_capacity =
168            if !args.get_str("--qpack-max-table-capacity").is_empty() {
169                Some(
170                    args.get_str("--qpack-max-table-capacity")
171                        .parse::<u64>()
172                        .unwrap(),
173                )
174            } else {
175                None
176            };
177
178        let qpack_blocked_streams =
179            if !args.get_str("--qpack-blocked-streams").is_empty() {
180                Some(
181                    args.get_str("--qpack-blocked-streams")
182                        .parse::<u64>()
183                        .unwrap(),
184                )
185            } else {
186                None
187            };
188
189        let initial_cwnd_packets = args
190            .get_str("--initial-cwnd-packets")
191            .parse::<u64>()
192            .unwrap();
193
194        CommonArgs {
195            alpns,
196            max_data,
197            max_window,
198            max_stream_data,
199            max_stream_window,
200            max_streams_bidi,
201            max_streams_uni,
202            idle_timeout,
203            early_data,
204            dump_packet_path,
205            no_grease,
206            cc_algorithm: cc_algorithm.to_string(),
207            disable_hystart,
208            dgrams_enabled,
209            dgram_count,
210            dgram_data,
211            max_active_cids,
212            enable_active_migration,
213            max_field_section_size,
214            qpack_max_table_capacity,
215            qpack_blocked_streams,
216            initial_cwnd_packets,
217        }
218    }
219}
220
221impl Default for CommonArgs {
222    fn default() -> Self {
223        CommonArgs {
224            alpns: alpns::HTTP_3.to_vec(),
225            max_data: 10000000,
226            max_window: 25165824,
227            max_stream_data: 1000000,
228            max_stream_window: 16777216,
229            max_streams_bidi: 100,
230            max_streams_uni: 100,
231            idle_timeout: 30000,
232            early_data: false,
233            dump_packet_path: None,
234            no_grease: false,
235            cc_algorithm: "cubic".to_string(),
236            disable_hystart: false,
237            dgrams_enabled: false,
238            dgram_count: 0,
239            dgram_data: "quack".to_string(),
240            max_active_cids: 2,
241            enable_active_migration: false,
242            max_field_section_size: None,
243            qpack_max_table_capacity: None,
244            qpack_blocked_streams: None,
245            initial_cwnd_packets: 10,
246        }
247    }
248}
249
250pub const CLIENT_USAGE: &str = "Usage:
251  quiche-client [options] URL...
252  quiche-client -h | --help
253
254Options:
255  --method METHOD          Use the given HTTP request method [default: GET].
256  --body FILE              Send the given file as request body.
257  --max-data BYTES         Connection-wide flow control limit [default: 10000000].
258  --max-window BYTES       Connection-wide max receiver window [default: 25165824].
259  --max-stream-data BYTES  Per-stream flow control limit [default: 1000000].
260  --max-stream-window BYTES   Per-stream max receiver window [default: 16777216].
261  --max-streams-bidi STREAMS  Number of allowed concurrent streams [default: 100].
262  --max-streams-uni STREAMS   Number of allowed concurrent streams [default: 100].
263  --idle-timeout TIMEOUT   Idle timeout in milliseconds [default: 30000].
264  --wire-version VERSION   The version number to send to the server [default: babababa].
265  --http-version VERSION   HTTP version to use [default: all].
266  --early-data             Enable sending early data.
267  --dgram-proto PROTO      DATAGRAM application protocol to use [default: none].
268  --dgram-count COUNT      Number of DATAGRAMs to send [default: 0].
269  --dgram-data DATA        Data to send for certain types of DATAGRAM application protocol [default: quack].
270  --dump-packets PATH      Dump the incoming packets as files in the given directory.
271  --dump-responses PATH    Dump response payload as files in the given directory.
272  --dump-json              Dump response headers and payload to stdout in JSON format.
273  --max-json-payload BYTES  Per-response payload limit when dumping JSON [default: 10000].
274  --connect-to ADDRESS     Override the server's address.
275  --no-verify              Don't verify server's certificate.
276  --trust-origin-ca-pem <file>  Path to the pem file of the origin's CA, if not publicly trusted.
277  --no-grease              Don't send GREASE.
278  --cc-algorithm NAME      Specify which congestion control algorithm to use [default: cubic].
279  --disable-hystart        Disable HyStart++.
280  --max-active-cids NUM    The maximum number of active Connection IDs we can support [default: 2].
281  --enable-active-migration   Enable active connection migration.
282  --perform-migration      Perform connection migration on another source port.
283  -H --header HEADER ...   Add a request header.
284  -n --requests REQUESTS   Send the given number of identical requests [default: 1].
285  --send-priority-update   Send HTTP/3 priority updates if the query string params 'u' or 'i' are present in URLs
286  --max-field-section-size BYTES    Max size of uncompressed field section. Default is unlimited.
287  --qpack-max-table-capacity BYTES  Max capacity of dynamic QPACK decoding.. Any value other that 0 is currently unsupported.
288  --qpack-blocked-streams STREAMS   Limit of blocked streams while decoding. Any value other that 0 is currently unsupported.
289  --session-file PATH      File used to cache a TLS session for resumption.
290  --source-port PORT       Source port to use when connecting to the server [default: 0].
291  --initial-cwnd-packets PACKETS   The initial congestion window size in terms of packet count [default: 10].
292  -h --help                Show this screen.
293";
294
295/// Application-specific arguments that compliment the `CommonArgs`.
296pub struct ClientArgs {
297    pub version: u32,
298    pub dump_response_path: Option<String>,
299    pub dump_json: Option<usize>,
300    pub urls: Vec<url::Url>,
301    pub reqs_cardinal: u64,
302    pub req_headers: Vec<String>,
303    pub no_verify: bool,
304    pub trust_origin_ca_pem: Option<String>,
305    pub body: Option<Vec<u8>>,
306    pub method: String,
307    pub connect_to: Option<String>,
308    pub session_file: Option<String>,
309    pub source_port: u16,
310    pub perform_migration: bool,
311    pub send_priority_update: bool,
312}
313
314impl Args for ClientArgs {
315    fn with_docopt(docopt: &docopt::Docopt) -> Self {
316        let args = docopt.parse().unwrap_or_else(|e| e.exit());
317
318        let version = args.get_str("--wire-version");
319        let version = u32::from_str_radix(version, 16).unwrap();
320
321        let dump_response_path = if !args.get_str("--dump-responses").is_empty() {
322            Some(args.get_str("--dump-responses").to_string())
323        } else {
324            None
325        };
326
327        let dump_json = args.get_bool("--dump-json");
328        let dump_json = if dump_json {
329            let max_payload = args.get_str("--max-json-payload");
330            let max_payload = max_payload.parse::<usize>().unwrap();
331            Some(max_payload)
332        } else {
333            None
334        };
335
336        // URLs (can be multiple).
337        let urls: Vec<url::Url> = args
338            .get_vec("URL")
339            .into_iter()
340            .map(|x| url::Url::parse(x).unwrap())
341            .collect();
342
343        // Request headers (can be multiple).
344        let req_headers = args
345            .get_vec("--header")
346            .into_iter()
347            .map(|x| x.to_string())
348            .collect();
349
350        let reqs_cardinal = args.get_str("--requests");
351        let reqs_cardinal = reqs_cardinal.parse::<u64>().unwrap();
352
353        let no_verify = args.get_bool("--no-verify");
354
355        let trust_origin_ca_pem = args.get_str("--trust-origin-ca-pem");
356        let trust_origin_ca_pem = if !trust_origin_ca_pem.is_empty() {
357            Some(trust_origin_ca_pem.to_string())
358        } else {
359            None
360        };
361
362        let body = if args.get_bool("--body") {
363            std::fs::read(args.get_str("--body")).ok()
364        } else {
365            None
366        };
367
368        let method = args.get_str("--method").to_string();
369
370        let connect_to = if args.get_bool("--connect-to") {
371            Some(args.get_str("--connect-to").to_string())
372        } else {
373            None
374        };
375
376        let session_file = if args.get_bool("--session-file") {
377            Some(args.get_str("--session-file").to_string())
378        } else {
379            None
380        };
381
382        let source_port = args.get_str("--source-port");
383        let source_port = source_port.parse::<u16>().unwrap();
384
385        let perform_migration = args.get_bool("--perform-migration");
386
387        let send_priority_update = args.get_bool("--send-priority-update");
388
389        ClientArgs {
390            version,
391            dump_response_path,
392            dump_json,
393            urls,
394            reqs_cardinal,
395            req_headers,
396            no_verify,
397            trust_origin_ca_pem,
398            body,
399            method,
400            connect_to,
401            session_file,
402            source_port,
403            perform_migration,
404            send_priority_update,
405        }
406    }
407}
408
409impl Default for ClientArgs {
410    fn default() -> Self {
411        ClientArgs {
412            version: 0xbabababa,
413            dump_response_path: None,
414            dump_json: None,
415            urls: vec![],
416            req_headers: vec![],
417            reqs_cardinal: 1,
418            no_verify: false,
419            trust_origin_ca_pem: None,
420            body: None,
421            method: "GET".to_string(),
422            connect_to: None,
423            session_file: None,
424            source_port: 0,
425            perform_migration: false,
426            send_priority_update: false,
427        }
428    }
429}
430
431pub const SERVER_USAGE: &str = "Usage:
432  quiche-server [options]
433  quiche-server -h | --help
434
435Options:
436  --listen <addr>             Listen on the given IP:port [default: 127.0.0.1:4433]
437  --cert <file>               TLS certificate path [default: src/bin/cert.crt]
438  --key <file>                TLS certificate key path [default: src/bin/cert.key]
439  --root <dir>                Root directory [default: src/bin/root/]
440  --index <name>              The file that will be used as index [default: index.html].
441  --name <str>                Name of the server [default: quic.tech]
442  --max-data BYTES            Connection-wide flow control limit [default: 10000000].
443  --max-window BYTES          Connection-wide max receiver window [default: 25165824].
444  --max-stream-data BYTES     Per-stream flow control limit [default: 1000000].
445  --max-stream-window BYTES   Per-stream max receiver window [default: 16777216].
446  --max-streams-bidi STREAMS  Number of allowed concurrent streams [default: 100].
447  --max-streams-uni STREAMS   Number of allowed concurrent streams [default: 100].
448  --idle-timeout TIMEOUT      Idle timeout in milliseconds [default: 30000].
449  --dump-packets PATH         Dump the incoming packets as files in the given directory.
450  --early-data                Enable receiving early data.
451  --no-retry                  Disable stateless retry.
452  --no-grease                 Don't send GREASE.
453  --http-version VERSION      HTTP version to use [default: all].
454  --dgram-proto PROTO         DATAGRAM application protocol to use [default: none].
455  --dgram-count COUNT         Number of DATAGRAMs to send [default: 0].
456  --dgram-data DATA           Data to send for certain types of DATAGRAM application protocol [default: brrr].
457  --cc-algorithm NAME         Specify which congestion control algorithm to use [default: cubic].
458  --disable-hystart           Disable HyStart++.
459  --max-active-cids NUM       The maximum number of active Connection IDs we can support [default: 2].
460  --enable-active-migration   Enable active connection migration.
461  --max-field-section-size BYTES    Max size of uncompressed HTTP/3 field section. Default is unlimited.
462  --qpack-max-table-capacity BYTES  Max capacity of QPACK dynamic table decoding. Any value other that 0 is currently unsupported.
463  --qpack-blocked-streams STREAMS   Limit of streams that can be blocked while decoding. Any value other that 0 is currently unsupported.
464  --disable-gso               Disable GSO (linux only).
465  --disable-pacing            Disable pacing (linux only).
466  --initial-cwnd-packets PACKETS      The initial congestion window size in terms of packet count [default: 10].
467  -h --help                   Show this screen.
468";
469
470// Application-specific arguments that compliment the `CommonArgs`.
471pub struct ServerArgs {
472    pub listen: String,
473    pub no_retry: bool,
474    pub root: String,
475    pub index: String,
476    pub cert: String,
477    pub key: String,
478    pub disable_gso: bool,
479    pub disable_pacing: bool,
480    pub enable_pmtud: bool,
481}
482
483impl Args for ServerArgs {
484    fn with_docopt(docopt: &docopt::Docopt) -> Self {
485        let args = docopt.parse().unwrap_or_else(|e| e.exit());
486
487        let listen = args.get_str("--listen").to_string();
488        let no_retry = args.get_bool("--no-retry");
489        let root = args.get_str("--root").to_string();
490        let index = args.get_str("--index").to_string();
491        let cert = args.get_str("--cert").to_string();
492        let key = args.get_str("--key").to_string();
493        let disable_gso = args.get_bool("--disable-gso");
494        let disable_pacing = args.get_bool("--disable-pacing");
495        let enable_pmtud = args.get_bool("--enable-pmtud");
496
497        ServerArgs {
498            listen,
499            no_retry,
500            root,
501            index,
502            cert,
503            key,
504            disable_gso,
505            disable_pacing,
506            enable_pmtud,
507        }
508    }
509}
quiche_apps/args.rs

quiche_apps/
args.rs
