ws_h2_upgrade (ws v0.1.1)

View Source

RFC 8441 — Bootstrapping WebSockets with HTTP/2.

This module only deals with the pseudo-header / response-status validation. Actually driving the HTTP/2 stream (sending the request, receiving the response, swapping data frames for WebSocket frames) belongs to the embedder; erlang_h2 already enforces the semantics and the handshake details below mirror that.

Caller responsibilities (server-side): * Before receiving any Extended CONNECT, the HTTP/2 stack must have advertised SETTINGS_ENABLE_CONNECT_PROTOCOL = 1. If the peer sent :protocol without having seen that setting it is the erlang_h2 layer that rejects the stream. * After this module returns {ok, Info}, the embedder issues a 200 response with the headers from response_headers/1 and hands the stream bytes to ws:accept/5.

Caller responsibilities (client-side): * peer_enable_connect_protocol must be true (the peer advertised SETTINGS_ENABLE_CONNECT_PROTOCOL = 1). client_request/4 returns an error when that is not the case.

Summary

Types

client_opts/0
pseudo_headers/0
request_info/0
request_opts/0

Functions

client_request(Scheme, Authority, Path, Opts)
client_request(Scheme, Authority, Path, Opts, Extra)
response_headers(Info)
validate_request(Headers)
validate_request(Headers, Opts)
validate_response(Status, Hdrs)

Types

client_opts/0

-type client_opts() ::
          #{subprotocols => [binary()],
            extensions => [binary()],
            peer_enable_connect_protocol := boolean(),
            origin => binary(),
            extra_headers => [{binary(), binary()}]}.

pseudo_headers/0

-type pseudo_headers() :: [{binary(), binary()}] | map().

request_info/0

-type request_info() ::
          #{method := binary(),
            protocol := binary(),
            scheme := binary(),
            authority := binary(),
            path := binary(),
            subprotocols := [binary()],
            extensions := [binary()],
            selected_subprotocol => binary()}.

request_opts/0

-type request_opts() :: #{required_subprotocols => [binary()]}.

Functions

client_request(Scheme, Authority, Path, Opts)

-spec client_request(binary(), binary(), binary(), client_opts()) ->
                        {ok, [{binary(), binary()}]} | {error, term()}.

client_request(Scheme, Authority, Path, Opts, Extra)

-spec client_request(binary(), binary(), binary(), client_opts(), [{binary(), binary()}]) ->
                        {ok, [{binary(), binary()}]} | {error, term()}.

response_headers(Info)

-spec response_headers(request_info()) -> [{binary(), binary()}].

validate_request(Headers)

-spec validate_request(pseudo_headers()) -> {ok, request_info()} | {error, term()}.

validate_request(Headers, Opts)

-spec validate_request(pseudo_headers(), request_opts()) -> {ok, request_info()} | {error, term()}.

validate_response(Status, Hdrs)

-spec validate_response(integer(), [{binary(), binary()}]) ->
                           {ok, #{subprotocol => binary(), extensions => [binary()]}} | {error, term()}.