cowboy_req:push(3)

NAME

cowboy_req:push - Push a resource to the client

DESCRIPTION
    push(Path, Headers, Req :: cowboy_req:req())
        -> push(Path, Headers, Req, #{})

    push(Path, Headers, Req :: cowboy_req:req(), Opts)
        -> ok

    Path    :: iodata()                %% case sensitive
    Headers :: cowboy:http_headers()
    Opts    :: cowboy_req:push_opts()

Push a resource to the client.

Cowboy handles push requests the same way as if they came from the client, including the creation of a request handling process, routing and middlewares and so on.

This function does nothing when the HTTP/1.1 protocol is used. You may call it safely without first checking whether the connection uses HTTP/2.

The header names must be given as lowercase binary strings. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

Note that the headers must be the headers the client is expected to send if it were to perform the request. They are therefore request headers, and not response headers.

By default, Cowboy will use the GET method, an empty query string, and take the scheme, host and port directly from the current request's URI. You can override them by passing options.

Note that clients may cancel the push or ignore it entirely. For example browsers may ignore the resource when the connection is not considered secure.

It is not possible to push resources after sending a response. Any attempt will result in an error.

ARGUMENTS

Path
    The status code for the response.

Headers
    The response headers.

    Header names must be given as lowercase binary strings.

Req
    The Req object.

Opts
    Customize the HTTP method or the URI scheme, host, port or query string.

RETURN VALUE

The atom ok is always returned. It can be safely ignored.

CHANGELOG
    • 2.0: Function introduced.

EXAMPLES

Push a resource
    cowboy_req:push("/static/style.css", #{
        <<"accept">> => <<"text/css">>
    }, Req),

Push a resource with a custom host
    cowboy_req:push("/static/style.css", #{
        <<"accept">> => <<"text/css">>
    }, #{host => <<"cdn.example.org">>}, Req),

SEE ALSO

cowboy_req(3), cowboy_req:inform(3), cowboy_req:reply(3), cowboy_req:stream_reply(3)