websocket_simple/
lib.rs

1//! Lightweight, event-driven WebSockets for Rust.
2
3
4extern crate httparse;
5extern crate sha1;
6extern crate rand;
7extern crate url;
8#[cfg(feature="ssl")] extern crate openssl;
9#[macro_use] extern crate log;
10extern crate time;
11
12mod handler;
13mod result;
14mod connection;
15mod frame;
16mod message;
17mod handshake;
18mod protocol;
19mod stream;
20
21#[cfg(feature="permessage-deflate")]
22pub mod deflate;
23
24pub use handler::Handler;
25
26pub use result::{Result, Error};
27pub use result::Kind as ErrorKind;
28pub use message::Message;
29pub use frame::Frame;
30pub use protocol::{CloseCode, OpCode};
31pub use handshake::{Handshake, Request, Response};
32pub use connection::Connection;
33
34use std::default::Default;
35
36/// WebSocket settings
37#[derive(Debug, Clone, Copy)]
38pub struct Settings {
39    /// The maximum number of connections that this WebSocket will support.
40    /// The default setting is low and should be increased when expecting more
41    /// connections because this is a hard limit and no new connections beyond
42    /// this limit can be made until an old connection is dropped.
43    /// Default: 100
44    pub max_connections: usize,
45    /// The number of events anticipated per connection. The event loop queue size will
46    /// be `queue_size` * `max_connections`. In order to avoid an overflow error,
47    /// `queue_size` * `max_connections` must be less than or equal to `usize::max_value()`.
48    /// The queue is shared between connections, which means that a connection may schedule
49    /// more events than `queue_size` provided that another connection is using less than
50    /// `queue_size`. However, if the queue is maxed out a Queue error will occur.
51    /// Default: 5
52    pub queue_size: usize,
53    /// Whether to panic when unable to establish a new TCP connection.
54    /// Default: false
55    pub panic_on_new_connection: bool,
56    /// Whether to panic when a shutdown of the WebSocket is requested.
57    /// Default: false
58    pub panic_on_shutdown: bool,
59    /// The maximum number of fragments the connection can handle without reallocating.
60    /// Default: 10
61    pub fragments_capacity: usize,
62    /// Whether to reallocate when `fragments_capacity` is reached. If this is false,
63    /// a Capacity error will be triggered instead.
64    /// Default: true
65    pub fragments_grow: bool,
66    /// The maximum length of outgoing frames. Messages longer than this will be fragmented.
67    /// Default: 65,535
68    pub fragment_size: usize,
69    /// The size of the incoming buffer. A larger buffer uses more memory but will allow for fewer
70    /// reallocations.
71    /// Default: 2048
72    pub in_buffer_capacity: usize,
73    /// Whether to reallocate the incoming buffer when `in_buffer_capacity` is reached. If this is
74    /// false, a Capacity error will be triggered instead.
75    /// Default: true
76    pub in_buffer_grow: bool,
77    /// The size of the outgoing buffer. A larger buffer uses more memory but will allow for fewer
78    /// reallocations.
79    /// Default: 2048
80    pub out_buffer_capacity: usize,
81    /// Whether to reallocate the incoming buffer when `out_buffer_capacity` is reached. If this is
82    /// false, a Capacity error will be triggered instead.
83    /// Default: true
84    pub out_buffer_grow: bool,
85    /// Whether to panic when an Internal error is encountered. Internal errors should generally
86    /// not occur, so this setting defaults to true as a debug measure, whereas production
87    /// applications should consider setting it to false.
88    /// Default: true
89    pub panic_on_internal: bool,
90    /// Whether to panic when a Capacity error is encountered.
91    /// Default: false
92    pub panic_on_capacity: bool,
93    /// Whether to panic when a Protocol error is encountered.
94    /// Default: false
95    pub panic_on_protocol: bool,
96    /// Whether to panic when an Encoding error is encountered.
97    /// Default: false
98    pub panic_on_encoding: bool,
99    /// Whether to panic when a Queue error is encountered.
100    /// Default: false
101    pub panic_on_queue: bool,
102    /// Whether to panic when an Io error is encountered.
103    /// Default: false
104    pub panic_on_io: bool,
105    /// Whether to panic when a Timer error is encountered.
106    /// Default: false
107    pub panic_on_timeout: bool,
108    /// The WebSocket protocol requires frames sent from client endpoints to be masked as a
109    /// security and sanity precaution. Enforcing this requirement, which may be removed at some
110    /// point may cause incompatibilities. If you need the extra security, set this to true.
111    /// Default: false
112    pub masking_strict: bool,
113    /// The WebSocket protocol requires clients to verify the key returned by a server to ensure
114    /// that the server and all intermediaries can perform the protocol. Verifying the key will
115    /// consume processing time and other resources with the benifit that we can fail the
116    /// connection early. The default in WS-RS is to accept any key from the server and instead
117    /// fail late if a protocol error occurs. Change this setting to enable key verification.
118    /// Default: false
119    pub key_strict: bool,
120    /// The WebSocket protocol requires clients to perform an opening handshake using the HTTP
121    /// GET method for the request. However, since only WebSockets are supported on the connection,
122    /// verifying the method of handshake requests is not always necessary. To enforce the
123    /// requirement that handshakes begin with a GET method, set this to true.
124    /// Default: false
125    pub method_strict: bool,
126    /// Indicate whether server connections should use ssl encryption when accepting connections.
127    /// Setting this to true means that clients should use the `wss` scheme to connect to this
128    /// server. Note that using this flag will in general necessitate overriding the
129    /// `Handler::build_ssl` method in order to provide the details of the ssl context. It may be
130    /// simpler for most users to use a reverse proxy such as nginx to provide server side
131    /// encryption.
132    ///
133    /// Default: false
134    pub encrypt_server: bool,
135}
136
137impl Default for Settings {
138
139    fn default() -> Settings {
140        Settings {
141            max_connections: 100,
142            queue_size: 5,
143            panic_on_new_connection: false,
144            panic_on_shutdown: false,
145            fragments_capacity: 10,
146            fragments_grow: true,
147            fragment_size: u16::max_value() as usize,
148            in_buffer_capacity: 2048,
149            in_buffer_grow: true,
150            out_buffer_capacity: 2048,
151            out_buffer_grow: true,
152            panic_on_internal: true,
153            panic_on_capacity: false,
154            panic_on_protocol: false,
155            panic_on_encoding: false,
156            panic_on_queue: false,
157            panic_on_io: false,
158            panic_on_timeout: false,
159            masking_strict: false,
160            key_strict: false,
161            method_strict: false,
162            encrypt_server: false,
163        }
164    }
165}
166
websocket_simple/lib.rs

websocket_simple/
lib.rs
