Bring over HPACK implementation from Mint (#1)

Author: mtrudel

.formatter.exs

@@ -1,4 +1,5 @@
 # Used by "mix format"
 [
-  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"],
+  import_deps: [:stream_data]
 ]

.github/workflows/main.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-18.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - erlang: "23.3.1"
+            elixir: "1.11.4"
+          - erlang: "23.0"
+            elixir: "1.11.2"
+            lint: true
+          - erlang: "23.0"
+            elixir: "1.10.3"
+          - erlang: "22.3"
+            elixir: "1.9.4"
+          - erlang: "21.3"
+            elixir: "1.8.2"
+          - erlang: "20.3.1"
+            elixir: "1.7.4"
+          - erlang: "19.3"
+            elixir: "1.6.6"
+          - erlang: "18.3"
+            elixir: "1.5.3"
+    steps:
+      - uses: actions/checkout@v1
+
+      - name: Install OTP and Elixir
+        uses: erlef/setup-elixir@v1
+        with:
+          otp-version: ${{matrix.erlang}}
+          elixir-version: ${{matrix.elixir}}
+
+      - name: Install dependencies
+        run: mix deps.get
+
+      - name: Check for unused dependencies
+        run: mix deps.unlock --check-unused
+        if: ${{matrix.lint}}
+
+      - name: Compile with --warnings-as-errors
+        run: mix compile --warnings-as-errors
+        if: ${{matrix.lint}}
+
+      - name: Check mix format
+        run: mix format --check-formatted
+        if: ${{matrix.lint}}
+
+      - name: Run tests
+        run: mix test --trace

README.md

@@ -1,21 +1,72 @@
-# Hpax
+# HPax
 
-**TODO: Add description**
+[![Build Status](https://travis-ci.org/elixir-mint/hpax.svg?branch=master)](https://travis-ci.org/elixir-mint/hpax)
+[![Docs](https://img.shields.io/badge/api-docs-green.svg?style=flat)](https://hexdocs.pm/hpax)
+[![Hex.pm Version](http://img.shields.io/hexpm/v/hpax.svg?style=flat)](https://hex.pm/packages/hpax)
+
+HPax is an Elixir implementation of the HPACK header compression algorithm as used in HTTP/2 and
+defined in RFC 7541. HPax is (or will soon be) used by several Elixir projects, including the
+[Mint](https://github.com/elixir-mint/mint) HTTP client and
+[bandit](https://github.com/mtrudel/bandit) HTTP server projects.
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `hpax` to your list of dependencies in `mix.exs`:
+To install HPax, add it to your `mix.exs` file.
 
 ```elixir
-def deps do
+defp deps do
   [
     {:hpax, "~> 0.1.0"}
   ]
 end
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at [https://hexdocs.pm/hpax](https://hexdocs.pm/hpax).
+Then, run `$ mix deps.get`.
+
+## Usage
+
+HPax is designed to be used in both encoding and decoding scenarios. In both cases, a context is
+used to maintain state internal to the HPACK algorithm. In the common use case of using HPax
+within HTTP/2, this context must be shared between any subsequent encoding/decoding calls within
+an endpoint. Note that the contexts used for encoding and decoding within HTTP/2 are completely
+distinct from one another, even though they are structurally identical.
+
+To encode a set of headers into a binary with HPax:
+
+```elixir
+ctx = HPax.new(4096)
+headers = [{:store, ":status", "201"}, {:store, "location", "http://example.com"}]
+{encoded_headers, ctx} = HPax.encode(headers, ctx)
+#=> {iodata, updated_context}
+```
+
+To decode a binary into a set of headers with HPax:
+
+```elixir
+ctx = HPax.new(4096)
+encoded_headers = <<...>>
+{:ok, headers, ctx} = HPax.decode(encoded_headers, ctx)
+#=> {:ok, [{:store, ":status", "201"}, {:store, "location", "http://example.com"}], updated_context}
+```
+
+For complete usage information, please see the HPax [documentation](https://hex.pm/packages/hpax).
+
+## Contributing
+
+If you wish to contribute check out the [issue list](https://github.com/elixir-mint/hpax/issues) and let us know what you want to work on so we can discuss it and reduce duplicate work.
+
+## License
+
+Copyright 2021 Eric Meadows-Jönsson and Andrea Leopardi
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
 
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.

lib/hpax.ex

@@ -1,18 +1,246 @@
-defmodule Hpax do
+defmodule HPax do
   @moduledoc """
-  Documentation for `Hpax`.
+  Support for the HPACK header compression algorithm.
+
+  This module provides support for the HPACK header compression algorithm used mainly in HTTP/2.
+  The HPACK algorithm requires an encoding context on the encoder side and a decoding context on
+  the decoder side. These contexts are semantically different but structurally the same and they
+  can both be created through `new/1`.
+  """
+
+  alias HPax.{Table, Types}
+
+  @type header_name() :: binary()
+  @type header_value() :: binary()
+
+  @valid_header_actions [:store, :store_name, :no_store, :never_store]
+
+  @doc """
+  Create a new context.
+
+  `max_table_size` is the maximum table size (in bytes) for the newly created context.
   """
+  @spec new(non_neg_integer()) :: Table.t()
+  def new(max_table_size) when is_integer(max_table_size) and max_table_size >= 0 do
+    Table.new(max_table_size)
+  end
 
   @doc """
-  Hello world.
+  Resizes the given table to the given size.
+  """
+  @spec resize(Table.t(), non_neg_integer()) :: Table.t()
+  defdelegate resize(table, new_size), to: Table
+
+  ## Decoding
+
+  @doc """
+  Decodes a header block fragment (HBF) through a given context.
+
+  If decoding is successful, this function returns a `{:ok, headers, updated_context}` tuple where
+  `headers` is a list of decoded headers, and `updated_context` is the updated context. If there's
+  an error in decoding, this function returns `{:error, reason}`.
 
   ## Examples
 
-      iex> Hpax.hello()
-      :world
+      context = HPax.new(1000)
+      hbf = get_hbf_from_somewhere()
+      HPax.decode(hbf, context)
+      #=> {:ok, [{":method", "GET"}], updated_context}
 
   """
-  def hello do
-    :world
+  @spec decode(binary(), Table.t()) :: {:ok, [{binary(), binary()}], Table.t()} | {:error, term()}
+  def decode(block, %Table{} = table) when is_binary(block) do
+    decode_headers(block, table, _acc = [])
+  catch
+    :throw, {:mint, error} -> {:error, error}
+  end
+
+  defp decode_headers(<<>>, table, acc) do
+    {:ok, Enum.reverse(acc), table}
+  end
+
+  # Indexed header field
+  # http://httpwg.org/specs/rfc7541.html#rfc.section.6.1
+  defp decode_headers(<<0b1::1, rest::bitstring>>, table, acc) do
+    {index, rest} = decode_integer(rest, 7)
+    decode_headers(rest, table, [lookup_by_index!(table, index) | acc])
+  end
+
+  # Literal header field with incremental indexing
+  # http://httpwg.org/specs/rfc7541.html#rfc.section.6.2.1
+  defp decode_headers(<<0b01::2, rest::bitstring>>, table, acc) do
+    {name, value, rest} =
+      case rest do
+        # The header name is a string.
+        <<0::6, rest::binary>> ->
+          {name, rest} = decode_binary(rest)
+          {value, rest} = decode_binary(rest)
+          {name, value, rest}
+
+        # The header name is an index to be looked up in the table.
+        _other ->
+          {index, rest} = decode_integer(rest, 6)
+          {value, rest} = decode_binary(rest)
+          {name, _value} = lookup_by_index!(table, index)
+          {name, value, rest}
+      end
+
+    decode_headers(rest, Table.add(table, name, value), [{name, value} | acc])
+  end
+
+  # Literal header field without indexing
+  # http://httpwg.org/specs/rfc7541.html#rfc.section.6.2.2
+  defp decode_headers(<<0b0000::4, rest::bitstring>>, table, acc) do
+    {name, value, rest} =
+      case rest do
+        <<0::4, rest::binary>> ->
+          {name, rest} = decode_binary(rest)
+          {value, rest} = decode_binary(rest)
+          {name, value, rest}
+
+        _other ->
+          {index, rest} = decode_integer(rest, 4)
+          {value, rest} = decode_binary(rest)
+          {name, _value} = lookup_by_index!(table, index)
+          {name, value, rest}
+      end
+
+    decode_headers(rest, table, [{name, value} | acc])
+  end
+
+  # Literal header field never indexed
+  # http://httpwg.org/specs/rfc7541.html#rfc.section.6.2.3
+  defp decode_headers(<<0b0001::4, rest::bitstring>>, table, acc) do
+    {name, value, rest} =
+      case rest do
+        <<0::4, rest::binary>> ->
+          {name, rest} = decode_binary(rest)
+          {value, rest} = decode_binary(rest)
+          {name, value, rest}
+
+        _other ->
+          {index, rest} = decode_integer(rest, 4)
+          {value, rest} = decode_binary(rest)
+          {name, _value} = lookup_by_index!(table, index)
+          {name, value, rest}
+      end
+
+    # TODO: enforce the "never indexed" part somehow.
+    decode_headers(rest, table, [{name, value} | acc])
+  end
+
+  # Dynamic table size update
+  defp decode_headers(<<0b001::3, rest::bitstring>>, table, acc) do
+    {new_size, rest} = decode_integer(rest, 5)
+    decode_headers(rest, Table.resize(table, new_size), acc)
+  end
+
+  defp decode_headers(_other, _table, _acc) do
+    throw({:mint, :protocol_error})
+  end
+
+  defp lookup_by_index!(table, index) do
+    case Table.lookup_by_index(table, index) do
+      {:ok, header} -> header
+      :error -> throw({:mint, {:index_not_found, index}})
+    end
+  end
+
+  defp decode_integer(bitstring, prefix) do
+    case Types.decode_integer(bitstring, prefix) do
+      {:ok, int, rest} -> {int, rest}
+      :error -> throw({:mint, :bad_integer_encoding})
+    end
+  end
+
+  defp decode_binary(binary) do
+    case Types.decode_binary(binary) do
+      {:ok, binary, rest} -> {binary, rest}
+      :error -> throw({:mint, :bad_binary_encoding})
+    end
+  end
+
+  ## Encoding
+
+  @doc """
+  Encodes a list of headers through the given context.
+
+  Returns a two-element tuple where the first element is a binary representing the encoded headers
+  and the second element is an updated context.
+
+  ## Examples
+
+      headers = [{:store, ":authority", "https://example.com"}]
+      context = HPax.new(1000)
+      HPax.encode(headers, context)
+      #=> {<<...>>, updated_context}
+
+  """
+  @spec encode([header], Table.t()) :: {iodata(), Table.t()}
+        when header: {action, header_name(), header_value()},
+             action: :store | :store_name | :no_store | :never_store
+  def encode(headers, %Table{} = table) when is_list(headers) do
+    encode_headers(headers, table, _acc = [])
+  end
+
+  defp encode_headers([], table, acc) do
+    {acc, table}
+  end
+
+  defp encode_headers([{action, name, value} | rest], table, acc)
+       when action in @valid_header_actions and is_binary(name) and is_binary(value) do
+    {encoded, table} =
+      case Table.lookup_by_header(table, name, value) do
+        {:full, index} ->
+          {encode_indexed_header(index), table}
+
+        {:name, index} when action == :store ->
+          {encode_literal_header_with_indexing(index, value), Table.add(table, name, value)}
+
+        {:name, index} when action in [:store_name, :no_store] ->
+          {encode_literal_header_without_indexing(index, value), table}
+
+        {:name, index} when action == :never_store ->
+          {encode_literal_header_never_indexed(index, value), table}
+
+        :not_found when action in [:store, :store_name] ->
+          {encode_literal_header_with_indexing(name, value), Table.add(table, name, value)}
+
+        :not_found when action == :no_store ->
+          {encode_literal_header_without_indexing(name, value), table}
+
+        :not_found when action == :never_store ->
+          {encode_literal_header_never_indexed(name, value), table}
+      end
+
+    encode_headers(rest, table, [acc, encoded])
+  end
+
+  defp encode_indexed_header(index) do
+    <<1::1, Types.encode_integer(index, 7)::bitstring>>
+  end
+
+  defp encode_literal_header_with_indexing(index, value) when is_integer(index) do
+    [<<1::2, Types.encode_integer(index, 6)::bitstring>>, Types.encode_binary(value, false)]
+  end
+
+  defp encode_literal_header_with_indexing(name, value) when is_binary(name) do
+    [<<1::2, 0::6>>, Types.encode_binary(name, false), Types.encode_binary(value, false)]
+  end
+
+  defp encode_literal_header_without_indexing(index, value) when is_integer(index) do
+    [<<0::4, Types.encode_integer(index, 4)::bitstring>>, Types.encode_binary(value, false)]
+  end
+
+  defp encode_literal_header_without_indexing(name, value) when is_binary(name) do
+    [<<0::4, 0::4>>, Types.encode_binary(name, false), Types.encode_binary(value, false)]
+  end
+
+  defp encode_literal_header_never_indexed(index, value) when is_integer(index) do
+    [<<1::4, Types.encode_integer(index, 4)::bitstring>>, Types.encode_binary(value, false)]
+  end
+
+  defp encode_literal_header_never_indexed(name, value) when is_binary(name) do
+    [<<1::4, 0::4>>, Types.encode_binary(name, false), Types.encode_binary(value, false)]
   end
 end