[/
    Copyright (c) 2016-2019 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
]

[/-----------------------------------------------------------------------------]

[section:decorator Decorator]

For programs which need to modify either the outgoing WebSocket HTTP Upgrade
request, the outgoing WebSocket HTTP Upgrade response, or both, the stream
supports an optional property called a ['decorator]. This is a function 
pointer or callable object which is invoked before the implementation
sends an HTTP message. The decorator receives a modifiable reference to
the message, allowing for modifications. The interface to this system
uses:

[table WebSocket Decorator Interface
[[Name][Description]]
[[
    [link beast.ref.boost__beast__websocket__request_type `request_type`]
][
    This is the type of the object passed to the decorator to
    represent HTTP Upgrade requests.
]]
[[
    [link beast.ref.boost__beast__websocket__response_type `response_type`]
][
    This is the type of the object passed to the decorator to
    represent HTTP Upgrade response.
]]
[[
    [link beast.ref.boost__beast__websocket__stream_base__decorator `stream_base::decorator`]
][
    Objects of this type are used to hold a decorator to be
    set on the stream using `set_option`.
]]
[[
    [link beast.ref.boost__beast__websocket__stream.set_option `stream::set_option`]
][
    This function is used to set a `stream_base::decorator` on the stream.
]]
]

This declares a normal function which decorates outgoing HTTP requests:

[code_websocket_3_1]

When using a decorator, it must be set on the stream before any handshaking
takes place. This sets the decorator on the stream, to be used for all
subsequent calls to accept or handshake:

[code_websocket_3_2]

Alternatively, a function object may be used. Small function objects will
not incur a memory allocation. The follow code declares and sets a function
object as a decorator:

[code_websocket_3_3]

A lambda may be used in place of a named function object:

[code_websocket_3_4]

It also possible for a single decorator to handle both requests and
responses, if it is overloaded for both types either as a generic
lambda (C++14 and later) or as a class as shown here:

[code_websocket_3_5]

The implementation takes ownership by decay-copy of the invocable object
used as the decorator. Move-only types are possible:

[code_websocket_3_6]

[important
    Undefined behavior results if the decorator modifies the fields
    specific to perform the WebSocket Upgrade, such as the Upgrade
    or Connection fields.
]

[endsect]