beast/websocket/rfc6455.hpp

0001 //
0002 // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007 // Official repository: https://github.com/boostorg/beast
0008 //
0009
0010 #ifndef BOOST_BEAST_WEBSOCKET_RFC6455_HPP
0011 #define BOOST_BEAST_WEBSOCKET_RFC6455_HPP
0012
0013 #include <boost/beast/core/detail/config.hpp>
0014 #include <boost/beast/core/static_string.hpp>
0015 #include <boost/beast/core/string.hpp>
0016 #include <boost/beast/http/empty_body.hpp>
0017 #include <boost/beast/http/message.hpp>
0018 #include <boost/beast/http/string_body.hpp>
0019 #include <array>
0020 #include <cstdint>
0021
0022 namespace boost {
0023 namespace beast {
0024 namespace websocket {
0025
0026 /// The type of object holding HTTP Upgrade requests
0027 using request_type = http::request<http::empty_body>;
0028
0029 /// The type of object holding HTTP Upgrade responses
0030 using response_type = http::response<http::string_body>;
0031
0032 /** Returns `true` if the specified HTTP request is a WebSocket Upgrade.
0033
0034     This function returns `true` when the passed HTTP Request
0035     indicates a WebSocket Upgrade. It does not validate the
0036     contents of the fields: it just trivially accepts requests
0037     which could only possibly be a valid or invalid WebSocket
0038     Upgrade message.
0039
0040     Callers who wish to manually read HTTP requests in their
0041     server implementation can use this function to determine if
0042     the request should be routed to an instance of
0043     @ref websocket::stream.
0044
0045     @par Example
0046     @code
0047     void handle_connection(net::ip::tcp::socket& sock)
0048     {
0049         boost::beast::flat_buffer buffer;
0050         boost::beast::http::request<boost::beast::http::string_body> req;
0051         boost::beast::http::read(sock, buffer, req);
0052         if(boost::beast::websocket::is_upgrade(req))
0053         {
0054             boost::beast::websocket::stream<decltype(sock)> ws{std::move(sock)};
0055             ws.accept(req);
0056         }
0057     }
0058     @endcode
0059
0060     @param req The HTTP Request object to check.
0061
0062     @return `true` if the request is a WebSocket Upgrade.
0063 */
0064 template<class Allocator>
0065 bool
0066 is_upgrade(beast::http::header<true,
0067     http::basic_fields<Allocator>> const& req);
0068
0069 /** Close status codes.
0070
0071     These codes accompany close frames.
0072
0073     @see <a href="https://tools.ietf.org/html/rfc6455#section-7.4.1">RFC 6455 7.4.1 Defined Status Codes</a>
0074 */
0075 enum close_code : std::uint16_t
0076 {
0077     /// Normal closure; the connection successfully completed whatever purpose for which it was created.
0078     normal          = 1000,
0079
0080     /// The endpoint is going away, either because of a server failure or because the browser is navigating away from the page that opened the connection.
0081     going_away      = 1001,
0082
0083     /// The endpoint is terminating the connection due to a protocol error.
0084     protocol_error  = 1002,
0085
0086     /// The connection is being terminated because the endpoint received data of a type it cannot accept (for example, a text-only endpoint received binary data).
0087     unknown_data    = 1003,
0088
0089     /// The endpoint is terminating the connection because a message was received that contained inconsistent data (e.g., non-UTF-8 data within a text message).
0090     bad_payload     = 1007,
0091
0092     /// The endpoint is terminating the connection because it received a message that violates its policy. This is a generic status code, used when codes 1003 and 1009 are not suitable.
0093     policy_error    = 1008,
0094
0095     /// The endpoint is terminating the connection because a data frame was received that is too large.
0096     too_big         = 1009,
0097
0098     /// The client is terminating the connection because it expected the server to negotiate one or more extension, but the server didn't.
0099     needs_extension = 1010,
0100
0101     /// The server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.
0102     internal_error  = 1011,
0103
0104     /// The server is terminating the connection because it is restarting.
0105     service_restart = 1012,
0106
0107     /// The server is terminating the connection due to a temporary condition, e.g. it is overloaded and is casting off some of its clients.
0108     try_again_later = 1013,
0109
0110     //----
0111     //
0112     // The following are illegal on the wire
0113     //
0114
0115     /** Used internally to mean "no error"
0116
0117         This code is reserved and may not be sent.
0118     */
0119     none            = 0,
0120
0121     /** Reserved for future use by the WebSocket standard.
0122
0123         This code is reserved and may not be sent.
0124     */
0125     reserved1       = 1004,
0126
0127     /** No status code was provided even though one was expected.
0128
0129         This code is reserved and may not be sent.
0130     */
0131     no_status       = 1005,
0132
0133     /** Connection was closed without receiving a close frame
0134
0135         This code is reserved and may not be sent.
0136     */
0137     abnormal        = 1006,
0138
0139     /** Reserved for future use by the WebSocket standard.
0140
0141         This code is reserved and may not be sent.
0142     */
0143     reserved2       = 1014,
0144
0145     /** Reserved for future use by the WebSocket standard.
0146
0147         This code is reserved and may not be sent.
0148     */
0149     reserved3       = 1015
0150
0151     //
0152     //----
0153
0154     //last = 5000 // satisfy warnings
0155 };
0156
0157 /// The type representing the reason string in a close frame.
0158 using reason_string = static_string<123, char>;
0159
0160 /// The type representing the payload of ping and pong messages.
0161 using ping_data = static_string<125, char>;
0162
0163 /** Description of the close reason.
0164
0165     This object stores the close code (if any) and the optional
0166     utf-8 encoded implementation defined reason string.
0167 */
0168 struct close_reason
0169 {
0170     /// The close code.
0171     std::uint16_t code = close_code::none;
0172
0173     /// The optional utf8-encoded reason string.
0174     reason_string reason;
0175
0176     /** Default constructor.
0177
0178         The code will be none. Default constructed objects
0179         will explicitly convert to bool as `false`.
0180     */
0181     close_reason() = default;
0182
0183     /// Construct from a code.
0184     close_reason(std::uint16_t code_)
0185         : code(code_)
0186     {
0187     }
0188
0189     /// Construct from a reason string. code is @ref close_code::normal.
0190     close_reason(string_view s)
0191         : code(close_code::normal)
0192         , reason(s.data(), s.size())
0193     {
0194     }
0195
0196     /// Construct from a reason string literal. code is @ref close_code::normal.
0197     close_reason(char const* s)
0198         : code(close_code::normal)
0199         , reason(s)
0200     {
0201     }
0202
0203     /// Construct from a close code and reason string.
0204     close_reason(close_code code_, string_view s)
0205         : code(code_)
0206         , reason(s.data(), s.size())
0207     {
0208     }
0209
0210     /// Returns `true` if a code was specified
0211     operator bool() const
0212     {
0213         return code != close_code::none;
0214     }
0215 };
0216
0217 } // websocket
0218 } // beast
0219 } // boost
0220
0221 #include <boost/beast/websocket/impl/rfc6455.hpp>
0222
0223 #endif