stream.hpp

Go to the documentation of this file.

//
// Copyright (c) 2016-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//
// Official repository: https://github.com/boostorg/beast
//

#ifndef BOOST_BEAST_WEBSOCKET_STREAM_HPP
#define BOOST_BEAST_WEBSOCKET_STREAM_HPP

#include <boost/beast/config.hpp>
#include <boost/beast/websocket/error.hpp>
#include <boost/beast/websocket/option.hpp>
#include <boost/beast/websocket/role.hpp>
#include <boost/beast/websocket/rfc6455.hpp>
#include <boost/beast/websocket/detail/frame.hpp>
#include <boost/beast/websocket/detail/hybi13.hpp>
#include <boost/beast/websocket/detail/mask.hpp>
#include <boost/beast/websocket/detail/pausation.hpp>
#include <boost/beast/websocket/detail/pmd_extension.hpp>
#include <boost/beast/websocket/detail/utf8_checker.hpp>
#include <boost/beast/core/async_result.hpp>
#include <boost/beast/core/static_buffer.hpp>
#include <boost/beast/core/string.hpp>
#include <boost/beast/core/detail/type_traits.hpp>
#include <boost/beast/http/empty_body.hpp>
#include <boost/beast/http/message.hpp>
#include <boost/beast/http/string_body.hpp>
#include <boost/beast/http/detail/type_traits.hpp>
#include <boost/beast/zlib/deflate_stream.hpp>
#include <boost/beast/zlib/inflate_stream.hpp>
#include <boost/asio/error.hpp>
#include <algorithm>
#include <cstdint>
#include <functional>
#include <limits>
#include <type_traits>

namespace boost {
namespace beast {
namespace websocket {

namespace detail {
class frame_test;
}

using request_type = http::request<http::empty_body>;

using response_type = http::response<http::string_body>;

enum class frame_type
{
    close,

    ping,

    pong
};

//--------------------------------------------------------------------

template<class NextLayer>
class stream
{
    friend class close_test;
    friend class frame_test;
    friend class ping_test;
    friend class read_test;
    friend class stream_test;
    friend class write_test;

    /*  The read buffer has to be at least as large
        as the largest possible control frame including
        the frame header.
    */
    static std::size_t constexpr max_control_frame_size = 2 + 8 + 4 + 125;
    static std::size_t constexpr tcp_frame_size = 1536;

    struct op {};

    using control_cb_type =
        std::function<void(frame_type, string_view)>;

    // tokens are used to order reads and writes
    class token
    {
        unsigned char id_ = 0;
    public:
        token() = default;
        token(token const&) = default;
        explicit token(unsigned char id) : id_(id) {}
        operator bool() const { return id_ != 0; }
        bool operator==(token const& t) { return id_ == t.id_; }
        bool operator!=(token const& t) { return id_ != t.id_; }
        token unique() { token t{id_++}; if(id_ == 0) ++id_; return t; }
        void reset() { id_ = 0; }
    };

    // State information for the permessage-deflate extension
    struct pmd_t
    {
        // `true` if current read message is compressed
        bool rd_set = false;

        zlib::deflate_stream zo;
        zlib::inflate_stream zi;
    };

    enum class status
    {
        open,
        closing,
        closed,
        failed
    };

    NextLayer               stream_;        // the wrapped stream
    close_reason            cr_;            // set from received close frame
    control_cb_type         ctrl_cb_;       // control callback

    std::size_t             rd_msg_max_     // max message size
                                = 16 * 1024 * 1024;
    std::uint64_t           rd_size_        // total size of current message so far
                                = 0;
    std::uint64_t           rd_remain_      // message frame bytes left in current frame
                                = 0;
    detail::frame_header    rd_fh_;         // current frame header
    detail::prepared_key    rd_key_         // current stateful mask key
                                = 0;
    detail::frame_buffer    rd_fb_;         // to write control frames (during reads)
    detail::utf8_checker    rd_utf8_;       // to validate utf8
    static_buffer<
        +tcp_frame_size>    rd_buf_;        // buffer for reads
    detail::opcode          rd_op_          // current message binary or text
                                = detail::opcode::text;
    bool                    rd_cont_        // `true` if the next frame is a continuation
                                = false;
    bool                    rd_done_        // set when a message is done
                                = true;
    bool                    rd_close_       // did we read a close frame?
                                = false;
    token                   rd_block_;      // op currenly reading

    token                   tok_;           // used to order asynchronous ops
    role_type               role_           // server or client
                                = role_type::client;
    status                  status_
                                = status::closed;

    token                   wr_block_;      // op currenly writing
    bool                    wr_close_       // did we write a close frame?
                                = false;
    bool                    wr_cont_        // next write is a continuation
                                = false;
    bool                    wr_frag_        // autofrag the current message
                                = false;
    bool                    wr_frag_opt_    // autofrag option setting
                                = true;
    bool                    wr_compress_    // compress current message
                                = false;
    detail::opcode          wr_opcode_      // message type
                                = detail::opcode::text;
    std::unique_ptr<
        std::uint8_t[]>     wr_buf_;        // write buffer
    std::size_t             wr_buf_size_    // write buffer size (current message)
                                = 0;
    std::size_t             wr_buf_opt_     // write buffer size option setting
                                = 4096;
    detail::fh_buffer       wr_fb_;         // header buffer used for writes
    detail::maskgen         wr_gen_;        // source of mask keys

    detail::pausation       paused_rd_;     // paused read op
    detail::pausation       paused_wr_;     // paused write op
    detail::pausation       paused_ping_;   // paused ping op
    detail::pausation       paused_close_;  // paused close op
    detail::pausation       paused_r_rd_;   // paused read op (read)
    detail::pausation       paused_r_close_;// paused close op (read)

    std::unique_ptr<pmd_t>  pmd_;           // pmd settings or nullptr
    permessage_deflate      pmd_opts_;      // local pmd options
    detail::pmd_offer       pmd_config_;    // offer (client) or negotiation (server)

public:
    using next_layer_type =
        typename std::remove_reference<NextLayer>::type;

    using lowest_layer_type =
        typename get_lowest_layer<next_layer_type>::type;

    ~stream() = default;

    stream(stream&&) = default;

    stream& operator=(stream&&) = default;

    template<class... Args>
    explicit
    stream(Args&&... args);

    //--------------------------------------------------------------------------

    boost::asio::io_service&
    get_io_service()
    {
        return stream_.get_io_service();
    }

    next_layer_type&
    next_layer()
    {
        return stream_;
    }

    next_layer_type const&
    next_layer() const
    {
        return stream_;
    }

    lowest_layer_type&
    lowest_layer()
    {
        return stream_.lowest_layer();
    }

    lowest_layer_type const&
    lowest_layer() const
    {
        return stream_.lowest_layer();
    }

    //--------------------------------------------------------------------------
    //
    // Observers
    //
    //--------------------------------------------------------------------------

    bool
    is_open() const
    {
        return status_ == status::open;
    }

    bool
    got_binary() const
    {
        return rd_op_ == detail::opcode::binary;
    }

    bool
    got_text() const
    {
        return ! got_binary();
    }

    bool
    is_message_done() const
    {
        return rd_done_;
    }

    close_reason const&
    reason() const
    {
        return cr_;
    }

    std::size_t
    read_size_hint(
        std::size_t initial_size = +tcp_frame_size) const;

    template<class DynamicBuffer
#if ! BOOST_BEAST_DOXYGEN
        , class = typename std::enable_if<
            ! std::is_integral<DynamicBuffer>::value>::type
#endif
    >
    std::size_t
    read_size_hint(
        DynamicBuffer& buffer) const;

    //--------------------------------------------------------------------------
    //
    // Settings
    //
    //--------------------------------------------------------------------------

    void
    set_option(permessage_deflate const& o);

    void
    get_option(permessage_deflate& o)
    {
        o = pmd_opts_;
    }

    void
    auto_fragment(bool value)
    {
        wr_frag_opt_ = value;
    }

    bool
    auto_fragment() const
    {
        return wr_frag_opt_;
    }

    void
    binary(bool value)
    {
        wr_opcode_ = value ?
            detail::opcode::binary :
            detail::opcode::text;
    }

    bool
    binary() const
    {
        return wr_opcode_ == detail::opcode::binary;
    }

    template<class Callback>
    void
    control_callback(Callback& cb)
    {
        // Callback may not be constant, caller is responsible for
        // managing the lifetime of the callback. Copies are not made.
        BOOST_STATIC_ASSERT(! std::is_const<Callback>::value);

        ctrl_cb_ = std::ref(cb);
    }

    void
    control_callback()
    {
        ctrl_cb_ = {};
    }

    void
    read_message_max(std::size_t amount)
    {
        rd_msg_max_ = amount;
    }

    std::size_t
    read_message_max() const
    {
        return rd_msg_max_;
    }

    void
    write_buffer_size(std::size_t amount)
    {
        if(amount < 8)
            BOOST_THROW_EXCEPTION(std::invalid_argument{
                "write buffer size underflow"});
        wr_buf_opt_ = amount;
    };

    std::size_t
    write_buffer_size() const
    {
        return wr_buf_opt_;
    }

    void
    text(bool value)
    {
        wr_opcode_ = value ?
            detail::opcode::text :
            detail::opcode::binary;
    }

    bool
    text() const
    {
        return wr_opcode_ == detail::opcode::text;
    }

    //--------------------------------------------------------------------------
    //
    // Handshaking (Client)
    //
    //--------------------------------------------------------------------------

    void
    handshake(
        string_view host,
        string_view target);

    void
    handshake(
        response_type& res,
        string_view host,
        string_view target);

    template<class RequestDecorator>
    void
    handshake_ex(
        string_view host,
        string_view target,
        RequestDecorator const& decorator);

    template<class RequestDecorator>
    void
    handshake_ex(
        response_type& res,
        string_view host,
        string_view target,
        RequestDecorator const& decorator);

    void
    handshake(
        string_view host,
        string_view target,
        error_code& ec);

    void
    handshake(
        response_type& res,
        string_view host,
        string_view target,
        error_code& ec);

    template<class RequestDecorator>
    void
    handshake_ex(
        string_view host,
        string_view target,
        RequestDecorator const& decorator,
        error_code& ec);

    template<class RequestDecorator>
    void
    handshake_ex(
        response_type& res,
        string_view host,
        string_view target,
        RequestDecorator const& decorator,
        error_code& ec);

    template<class HandshakeHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        HandshakeHandler, void(error_code)>
#endif
    async_handshake(
        string_view host,
        string_view target,
        HandshakeHandler&& handler);

    template<class HandshakeHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        HandshakeHandler, void(error_code)>
#endif
    async_handshake(
        response_type& res,
        string_view host,
        string_view target,
        HandshakeHandler&& handler);

    template<class RequestDecorator, class HandshakeHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        HandshakeHandler, void(error_code)>
#endif
    async_handshake_ex(
        string_view host,
        string_view target,
        RequestDecorator const& decorator,
        HandshakeHandler&& handler);

    template<class RequestDecorator, class HandshakeHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        HandshakeHandler, void(error_code)>
#endif
    async_handshake_ex(
        response_type& res,
        string_view host,
        string_view target,
        RequestDecorator const& decorator,
        HandshakeHandler&& handler);

    //--------------------------------------------------------------------------
    //
    // Handshaking (Server)
    //
    //--------------------------------------------------------------------------

    void
    accept();

    template<class ResponseDecorator>
    void
    accept_ex(ResponseDecorator const& decorator);

    void
    accept(error_code& ec);

    template<class ResponseDecorator>
    void
    accept_ex(
        ResponseDecorator const& decorator,
        error_code& ec);

    template<class ConstBufferSequence>
#if BOOST_BEAST_DOXYGEN
    void
#else
    typename std::enable_if<! http::detail::is_header<
        ConstBufferSequence>::value>::type
#endif
    accept(ConstBufferSequence const& buffers);

    template<class ConstBufferSequence,
        class ResponseDecorator>
#if BOOST_BEAST_DOXYGEN
    void
#else
    typename std::enable_if<! http::detail::is_header<
        ConstBufferSequence>::value>::type
#endif
    accept_ex(
        ConstBufferSequence const& buffers,
        ResponseDecorator const& decorator);

    template<class ConstBufferSequence>
#if BOOST_BEAST_DOXYGEN
    void
#else
    typename std::enable_if<! http::detail::is_header<
        ConstBufferSequence>::value>::type
#endif
    accept(
        ConstBufferSequence const& buffers,
        error_code& ec);

    template<class ConstBufferSequence, class ResponseDecorator>
#if BOOST_BEAST_DOXYGEN
    void
#else
    typename std::enable_if<! http::detail::is_header<
        ConstBufferSequence>::value>::type
#endif
    accept_ex(
        ConstBufferSequence const& buffers,
        ResponseDecorator const& decorator,
        error_code& ec);

    template<class Body, class Allocator>
    void
    accept(http::request<Body,
        http::basic_fields<Allocator>> const& req);

    template<class Body, class Allocator,
        class ResponseDecorator>
    void
    accept_ex(http::request<Body,
        http::basic_fields<Allocator>> const& req,
            ResponseDecorator const& decorator);

    template<class Body, class Allocator>
    void
    accept(http::request<Body,
        http::basic_fields<Allocator>> const& req,
            error_code& ec);

    template<class Body, class Allocator,
        class ResponseDecorator>
    void
    accept_ex(http::request<Body,
        http::basic_fields<Allocator>> const& req,
            ResponseDecorator const& decorator,
                error_code& ec);

    template<class AcceptHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        AcceptHandler, void(error_code)>
#endif
    async_accept(AcceptHandler&& handler);

    template<
        class ResponseDecorator,
        class AcceptHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        AcceptHandler, void(error_code)>
#endif
    async_accept_ex(
        ResponseDecorator const& decorator,
        AcceptHandler&& handler);

    template<
        class ConstBufferSequence,
        class AcceptHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    typename std::enable_if<
        ! http::detail::is_header<ConstBufferSequence>::value,
        async_return_type<AcceptHandler, void(error_code)>>::type
#endif
    async_accept(
        ConstBufferSequence const& buffers,
        AcceptHandler&& handler);

    template<
        class ConstBufferSequence,
        class ResponseDecorator,
        class AcceptHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    typename std::enable_if<
        ! http::detail::is_header<ConstBufferSequence>::value,
        async_return_type<AcceptHandler, void(error_code)>>::type
#endif
    async_accept_ex(
        ConstBufferSequence const& buffers,
        ResponseDecorator const& decorator,
        AcceptHandler&& handler);

    template<
        class Body, class Allocator,
        class AcceptHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        AcceptHandler, void(error_code)>
#endif
    async_accept(
        http::request<Body,
            http::basic_fields<Allocator>> const& req,
        AcceptHandler&& handler);

    template<
        class Body, class Allocator,
        class ResponseDecorator,
        class AcceptHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        AcceptHandler, void(error_code)>
#endif
    async_accept_ex(
        http::request<Body,
            http::basic_fields<Allocator>> const& req,
        ResponseDecorator const& decorator,
        AcceptHandler&& handler);

    //--------------------------------------------------------------------------
    //
    // Control Frames
    //
    //--------------------------------------------------------------------------

    void
    close(close_reason const& cr);

    void
    close(close_reason const& cr, error_code& ec);

    template<class CloseHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        CloseHandler, void(error_code)>
#endif
    async_close(close_reason const& cr, CloseHandler&& handler);

    void
    ping(ping_data const& payload);

    void
    ping(ping_data const& payload, error_code& ec);

    template<class WriteHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        WriteHandler, void(error_code)>
#endif
    async_ping(ping_data const& payload, WriteHandler&& handler);

    void
    pong(ping_data const& payload);

    void
    pong(ping_data const& payload, error_code& ec);

    template<class WriteHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        WriteHandler, void(error_code)>
#endif
    async_pong(ping_data const& payload, WriteHandler&& handler);

    //--------------------------------------------------------------------------
    //
    // Reading
    //
    //--------------------------------------------------------------------------

    template<class DynamicBuffer>
    std::size_t
    read(DynamicBuffer& buffer);

    template<class DynamicBuffer>
    std::size_t
    read(DynamicBuffer& buffer, error_code& ec);

    template<class DynamicBuffer, class ReadHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        ReadHandler,
        void(error_code, std::size_t)>
#endif
    async_read(
        DynamicBuffer& buffer,
        ReadHandler&& handler);

    //--------------------------------------------------------------------------

    template<class DynamicBuffer>
    std::size_t
    read_some(
        DynamicBuffer& buffer,
        std::size_t limit);

    template<class DynamicBuffer>
    std::size_t
    read_some(
        DynamicBuffer& buffer,
        std::size_t limit,
        error_code& ec);

    template<class DynamicBuffer, class ReadHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        ReadHandler, void(error_code, std::size_t)>
#endif
    async_read_some(
        DynamicBuffer& buffer,
        std::size_t limit,
        ReadHandler&& handler);

    //--------------------------------------------------------------------------

    template<class MutableBufferSequence>
    std::size_t
    read_some(
        MutableBufferSequence const& buffers);

    template<class MutableBufferSequence>
    std::size_t
    read_some(
        MutableBufferSequence const& buffers,
        error_code& ec);

    template<class MutableBufferSequence, class ReadHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<ReadHandler, void(error_code, std::size_t)>
#endif
    async_read_some(
        MutableBufferSequence const& buffers,
        ReadHandler&& handler);

    //--------------------------------------------------------------------------
    //
    // Writing
    //
    //--------------------------------------------------------------------------

    template<class ConstBufferSequence>
    std::size_t
    write(ConstBufferSequence const& buffers);

    template<class ConstBufferSequence>
    std::size_t
    write(ConstBufferSequence const& buffers, error_code& ec);

    template<
        class ConstBufferSequence,
        class WriteHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<
        WriteHandler,
        void(error_code, std::size_t)>
#endif
    async_write(
        ConstBufferSequence const& buffers,
        WriteHandler&& handler);

    template<class ConstBufferSequence>
    std::size_t
    write_some(bool fin, ConstBufferSequence const& buffers);

    template<class ConstBufferSequence>
    std::size_t
    write_some(bool fin,
        ConstBufferSequence const& buffers, error_code& ec);

    template<class ConstBufferSequence, class WriteHandler>
#if BOOST_BEAST_DOXYGEN
    void_or_deduced
#else
    async_return_type<WriteHandler,
        void(error_code, std::size_t)>
#endif
    async_write_some(bool fin,
        ConstBufferSequence const& buffers, WriteHandler&& handler);

private:
    template<class, class>  class accept_op;
    template<class>         class close_op;
    template<class>         class fail_op;
    template<class>         class handshake_op;
    template<class>         class ping_op;
    template<class>         class read_fh_op;
    template<class, class>  class read_some_op;
    template<class, class>  class read_op;
    template<class>         class response_op;
    template<class, class>  class write_some_op;
    template<class, class>  class write_op;

    static void default_decorate_req(request_type&) {}
    static void default_decorate_res(response_type&) {}

    void open(role_type role);
    void close();
    void reset();
    void begin_msg();

    bool
    check_open(error_code& ec)
    {
        if(status_ != status::open)
        {
            ec = boost::asio::error::operation_aborted;
            return false;
        }
        ec.assign(0, ec.category());
        return true;
    }

    bool
    check_ok(error_code& ec)
    {
        if(ec)
        {
            if(status_ != status::closed)
                status_ = status::failed;
            return false;
        }
        return true;
    }

    template<class DynamicBuffer>
    bool
    parse_fh(detail::frame_header& fh,
        DynamicBuffer& b, close_code& code);

    template<class DynamicBuffer>
    void
    write_close(DynamicBuffer& b, close_reason const& rc);

    template<class DynamicBuffer>
    void
    write_ping(DynamicBuffer& b,
        detail::opcode op, ping_data const& data);

    template<class Decorator>
    request_type
    build_request(detail::sec_ws_key_type& key,
        string_view host,
            string_view target,
                Decorator const& decorator);

    template<class Body,
        class Allocator, class Decorator>
    response_type
    build_response(http::request<Body,
        http::basic_fields<Allocator>> const& req,
            Decorator const& decorator);

    void
    on_response(response_type const& resp,
        detail::sec_ws_key_type const& key, error_code& ec);

    template<class Decorator>
    void
    do_accept(Decorator const& decorator,
        error_code& ec);

    template<class Body, class Allocator,
        class Decorator>
    void
    do_accept(http::request<Body,
        http::basic_fields<Allocator>> const& req,
            Decorator const& decorator, error_code& ec);

    template<class RequestDecorator>
    void
    do_handshake(response_type* res_p,
        string_view host, string_view target,
            RequestDecorator const& decorator,
                error_code& ec);

    void
    do_fail(
        std::uint16_t code,
        error_code ev,
        error_code& ec);
};

} // websocket
} // beast
} // boost

#include <boost/beast/websocket/impl/accept.ipp>
#include <boost/beast/websocket/impl/close.ipp>
#include <boost/beast/websocket/impl/handshake.ipp>
#include <boost/beast/websocket/impl/ping.ipp>
#include <boost/beast/websocket/impl/read.ipp>
#include <boost/beast/websocket/impl/stream.ipp>
#include <boost/beast/websocket/impl/write.ipp>

#endif