HTTP2 client adapter behaviour

Uses Kadabra by default, but any client can be used with the appropriate adapter.

Writing a Custom Client Adapter

Pigeon.Worker relies on all of the callbacks for important connection functionality.

• start/0
  • Starts the client application when Pigeon starts.
• connect/3
  • Opens a socket connection. Must return {:ok, pid} or {:error, reason}. If an error, Pigeon.Worker will retry the callback two more times.
• send_ping/1
  • Sends an HTTP2 ping. Pigeon.Worker periodically sends pings to keep the connection alive. Client adapters must support pings for APNS-configured workers, though it is not necessary if only using FCM.
• send_request/3
  • Makes an HTTP2 request. Pigeon.Worker does not handle synchronous requests and will ignore the result of this callback. If the client is synchronous, the adapter will need to explicitly send a message back to the Pigeon.Worker.
• handle_end_stream/2
  • All incoming messages on the worker are passed through this callback. Must return {:ok, %Pigeon.Http2.Stream{...}} if it is a valid END_STREAM response for the adapter. All other messages are ignored.

Example implementation for Kadabra

if Code.ensure_loaded?(Kadabra) do
defmodule Pigeon.Http2.Client.Kadabra do
  @moduledoc false

  @behaviour Pigeon.Http2.Client

  def start do
    Application.ensure_all_started(:kadabra)
  end

  def connect(uri, scheme, opts) do
    Kadabra.open(uri, scheme, opts)
  end

  def send_request(pid, headers, data) do
    Kadabra.request(pid, headers, data)
  end

  def send_ping(pid) do
    Kadabra.ping(pid)
  end

  def handle_end_stream({:end_stream, %{id: id,
                                        status: status,
                                        headers: headers,
                                        body: body}}, _state) do
    {:ok, %Pigeon.Http2.Stream{
        id: id,
        status: status,
        headers: headers,
        body: body
    }}
  end
  def handle_end_stream(msg, _state), do: msg
end
end

Using Your Client Adapter

Once implemented, specify it in your config. Pigeon will use it for all HTTP2 connections.

config :pigeon, http2_client: Pigeon.YourCustomAdapter