websock-wasm 0.5.0

WebAssembly transport implementation for browser-based WebSockets.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

//! Builders for browser WebSocket clients.

use websock_proto::{ConnectOptions, Error, Result, WebSocketLimits};

use crate::Connection;
use crate::connection::connect;

/// Builder for creating a WebSocket client.
///
/// The resulting client can be reused for multiple `connect()` calls.
#[derive(Debug, Clone)]
pub struct ClientBuilder {
    opts: ConnectOptions,
}

impl Default for ClientBuilder {
    fn default() -> Self {
        Self::new()
    }
}

impl ClientBuilder {
    /// Create a new client builder with default options.
    pub fn new() -> Self {
        Self {
            opts: ConnectOptions::default(),
        }
    }

    /// Replace the builder options wholesale.
    pub fn with_options(mut self, opts: ConnectOptions) -> Self {
        self.opts = opts;
        self
    }

    /// Return a reference to the current options.
    pub fn options(&self) -> &ConnectOptions {
        &self.opts
    }

    /// Add a single header to the connection request.
    pub fn with_header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.opts.headers.push((name.into(), value.into()));
        self
    }

    /// Add multiple headers to the connection request.
    pub fn with_headers<I, K, V>(mut self, headers: I) -> Self
    where
        I: IntoIterator<Item = (K, V)>,
        K: Into<String>,
        V: Into<String>,
    {
        for (k, v) in headers {
            self.opts.headers.push((k.into(), v.into()));
        }
        self
    }

    /// Configure WebSocket message resource limits.
    pub fn with_limits(mut self, limits: WebSocketLimits) -> Self {
        self.opts.limits = limits;
        self
    }

    /// Add a single subprotocol.
    pub fn with_protocol(mut self, protocol: impl Into<String>) -> Self {
        self.opts.protocols.push(protocol.into());
        self
    }

    /// Add multiple subprotocols.
    pub fn with_protocols<I, P>(mut self, protocols: I) -> Self
    where
        I: IntoIterator<Item = P>,
        P: Into<String>,
    {
        for p in protocols {
            self.opts.protocols.push(p.into());
        }
        self
    }

    /// Build a reusable client.
    pub fn build(self) -> Client {
        Client { opts: self.opts }
    }

    /// Build a client using system roots (no-op in the browser).
    pub fn with_system_roots(self) -> Result<Client> {
        Ok(self.build())
    }

    /// Attempt to configure custom certificates (not supported in the browser).
    pub fn with_server_certificates<I>(self, _chain: I) -> Result<Client>
    where
        I: IntoIterator<Item = Vec<u8>>,
    {
        Err(Error::Unsupported(
            "custom certificates are not supported in browser wasm".into(),
        ))
    }

    /// Enter the "dangerous" builder that can disable certificate verification.
    pub fn dangerous(self) -> DangerousClientBuilder {
        DangerousClientBuilder { opts: self.opts }
    }
}

/// Reusable WebSocket client created by [`ClientBuilder`].
#[derive(Debug, Clone)]
pub struct Client {
    opts: ConnectOptions,
}

impl Client {
    /// Return a reference to the configured connection options.
    pub fn options(&self) -> &ConnectOptions {
        &self.opts
    }

    /// Establish a browser WebSocket connection.
    pub async fn connect(&self, url: &str) -> Result<Connection> {
        connect(url, self.opts.clone()).await
    }
}

/// Builder that can attempt to disable certificate verification.
pub struct DangerousClientBuilder {
    #[allow(dead_code)]
    opts: ConnectOptions,
}

impl DangerousClientBuilder {
    /// Return an unsupported error, since browsers cannot disable verification.
    pub fn with_no_certificate_verification(self) -> Result<Client> {
        Err(Error::Unsupported(
            "certificate verification cannot be disabled in browser wasm".into(),
        ))
    }
}