xwt_web/
options.rs

1//! High-level API for configuring the transport.
2
3/// Options for configuring the transport.
4///
5/// See <https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/WebTransport#options>.
6#[derive(Debug, Clone, Default, PartialEq, Eq)]
7pub struct WebTransportOptions {
8    /// If `true`, the network connection for this WebTransport can be shared
9    /// with a pool of other HTTP/3 sessions.
10    ///
11    /// By default the value is false, and the connection cannot be shared.
12    pub allow_pooling: bool,
13    /// Indicates the application's preference that the congestion control
14    /// algorithm used when sending data over this connection be tuned for
15    /// either throughput or low-latency.
16    ///
17    /// This is a hint to the user agent.
18    pub congestion_control: CongestionControl,
19    /// If true, the connection cannot be established over HTTP/2 if an HTTP/3
20    /// connection is not possible.
21    ///
22    /// By default the value is false.
23    pub require_unreliable: bool,
24    /// An array of objects, each defining the hash value of a server
25    /// certificate along with the name of the algorithm that was used to
26    /// generate it.
27    ///
28    /// This option is only supported for transports using dedicated connections
29    /// (`allow_pooling` is false).
30    ///
31    /// If specified, the browser will attempt to authenticate the certificate
32    /// provided by the server against the provided certificate hash(es) in
33    /// order to connect, instead of using the Web public key infrastructure
34    /// (PKI). If any hashes match, the browser knows that the server has
35    /// possession of a trusted certificate and will connect as normal. If empty
36    /// the user agent uses the same PKI certificate verification procedures it
37    /// would use for a normal fetch operation.
38    ///
39    /// This feature allows developers to connect to WebTransport servers that
40    /// would normally find obtaining a publicly trusted certificate
41    /// challenging, such as hosts that are not publicly routable, or ephemeral
42    /// hosts like virtual machines.
43    pub server_certificate_hashes: Vec<CertificateHash>,
44}
45
46/// The application's preference that the congestion control algorithm used when
47/// sending data over this connection be tuned for either throughput or
48/// low-latency.
49#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
50pub enum CongestionControl {
51    /// Default value.
52    #[default]
53    Default,
54    /// Favour throughput.
55    Throughput,
56    /// Favour low latency.
57    LowLatency,
58}
59
60/// Hash of a server certificate which the transport can connect to.
61///
62/// The certificate must be an X.509v3 certificate that has a validity period of
63/// less that 2 weeks, and the current time must be within that validity period.
64/// The format of the public key in the certificate depends on the
65/// implementation, but must minimally include ECDSA with the secp256r1 (NIST
66/// P-256) named group, and must not include RSA keys. An ECSDA key is therefore
67/// an interoperable default public key format. A user agent may add further
68/// requirements; these will be listed in the [browser compatibility] section if
69/// known.
70///
71/// See <https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/WebTransport#servercertificatehashes>.
72///
73/// [browser compatibility]: https://developer.mozilla.org/en-US/docs/Web/API/WebTransport/WebTransport#browser_compatibility
74#[derive(Debug, Clone, PartialEq, Eq, Hash)]
75pub struct CertificateHash {
76    /// Algorithm used to verify the hash.
77    pub algorithm: HashAlgorithm,
78    /// Hash value.
79    pub value: Vec<u8>,
80}
81
82/// Algorithm used to verify the hash.
83#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
84pub enum HashAlgorithm {
85    /// SHA-256 algorithm.
86    Sha256,
87}
88
89impl WebTransportOptions {
90    /// Creates a JavaScript value from this value.
91    pub fn to_js(&self) -> web_wt_sys::WebTransportOptions {
92        let js = web_wt_sys::WebTransportOptions::new();
93        js.set_allow_pooling(self.allow_pooling);
94        js.set_congestion_control(match self.congestion_control {
95            CongestionControl::Default => web_wt_sys::WebTransportCongestionControl::Default,
96            CongestionControl::Throughput => web_wt_sys::WebTransportCongestionControl::Throughput,
97            CongestionControl::LowLatency => web_wt_sys::WebTransportCongestionControl::LowLatency,
98        });
99        js.set_require_unreliable(self.require_unreliable);
100
101        let cert_hashes = self
102            .server_certificate_hashes
103            .iter()
104            .map(|cert| {
105                let hash = web_wt_sys::WebTransportHash::new();
106                hash.set_algorithm(match cert.algorithm {
107                    HashAlgorithm::Sha256 => "sha-256",
108                });
109                hash.set_value(&cert.value);
110                hash
111            })
112            .collect::<Vec<_>>();
113        js.set_server_certificate_hashes(cert_hashes);
114
115        js
116    }
117}
xwt_web/options.rs

xwt_web/
options.rs
