ws_deflate (ws v0.4.0)

RFC 7692 — permessage-deflate extension helpers.

Provides negotiation (parse client offer / build server response), and the inflate / deflate primitives used on the hot path once the extension is enabled. The session does not yet wire this in automatically — embedders enabling permessage-deflate should drive it from their upgrade helper and pass the resulting zlib streams into encode_payload/3 / decode_payload/3.

The algorithm follows the one in hackney_ws_proto / cowlib: deflate with sync flush, strip the trailing 0x00 0x00 0xff 0xff block on the wire, and re-append it before calling inflate.

Summary

Types

negotiated/0

opts/0

params/0

Functions

client_offer(Opts)

deflate(Z, Takeover, Data)

inflate(Z, Takeover, Data)

inflate(Z, Takeover, Data, MaxSize)

init_deflate(_, Role)

init_inflate(_, Role)

negotiate(Extensions, Opts)

Negotiate against the peer's raw Sec-WebSocket-Extensions offers as the upgrade validators deliver them (one binary per comma-separated element, e.g. <<"permessage-deflate; client_max_window_bits">>). Tries each permessage-deflate offer in order and settles on the first that can be agreed on. Returns the response header value (iolist) plus the negotiated parameters, or ignore when the peer offered nothing acceptable.

negotiate_server(Params, Opts)

parse_offer(Ext)

Parse one Sec-WebSocket-Extensions element into params() when it is a permessage-deflate offer.

parse_server_response(Params)

Types

negotiated/0

-type negotiated() ::
          #{server_context_takeover := takeover | no_takeover,
            client_context_takeover := takeover | no_takeover,
            server_max_window_bits := 8..15,
            client_max_window_bits := 8..15}.

opts/0

-type opts() ::
          #{server_context_takeover => takeover | no_takeover,
            client_context_takeover => takeover | no_takeover,
            server_max_window_bits => 8..15,
            client_max_window_bits => 8..15,
            level => zlib:zlevel(),
            mem_level => zlib:zmemlevel(),
            strategy => zlib:zstrategy()}.

params/0

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

Functions

client_offer(Opts)

-spec client_offer(opts()) -> iodata().

deflate(Z, Takeover, Data)

-spec deflate(zlib:zstream(), takeover | no_takeover, iodata()) -> binary().

inflate(Z, Takeover, Data)

-spec inflate(zlib:zstream(), takeover | no_takeover, iodata()) ->
                 {ok, binary()} | {error, {inflate_too_big, pos_integer()}}.

inflate(Z, Takeover, Data, MaxSize)

-spec inflate(zlib:zstream(), takeover | no_takeover, iodata(), pos_integer() | infinity) ->
                 {ok, binary()} | {error, {inflate_too_big, pos_integer() | infinity}}.

init_deflate(_, Role)

-spec init_deflate(negotiated(), client | server) -> zlib:zstream().

init_inflate(_, Role)

-spec init_inflate(negotiated(), client | server) -> zlib:zstream().

negotiate(Extensions, Opts)

-spec negotiate([binary()], opts()) -> ignore | {ok, iolist(), negotiated()}.

Negotiate against the peer's raw Sec-WebSocket-Extensions offers as the upgrade validators deliver them (one binary per comma-separated element, e.g. <<"permessage-deflate; client_max_window_bits">>). Tries each permessage-deflate offer in order and settles on the first that can be agreed on. Returns the response header value (iolist) plus the negotiated parameters, or ignore when the peer offered nothing acceptable.

negotiate_server(Params, Opts)

-spec negotiate_server(params(), opts()) -> ignore | {ok, iolist(), negotiated()}.

parse_offer(Ext)

-spec parse_offer(binary()) -> {ok, params()} | not_deflate.

Parse one Sec-WebSocket-Extensions element into params() when it is a permessage-deflate offer.

parse_server_response(Params)

-spec parse_server_response(params()) -> {ok, negotiated()} | {error, term()}.