Pigeon v1.1.1 Pigeon.Http2.Client behaviour View Source

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

Link to this section Summary

Functions

Default http2 client to use

Link to this section Functions

Default http2 client to use.

When not configured, defaults to Pigeon.Http2.Client.Kadabra

Examples

iex> Pigeon.Http2.Client.default
Pigeon.Http2.Client.Kadabra

Link to this section Callbacks

Link to this callback connect(uri, scheme, options) View Source
connect(uri :: charlist, scheme :: :https, options :: Keyword.t) ::
  {:ok, pid} |
  {:error, any}
Link to this callback handle_end_stream(msg, state) View Source
handle_end_stream(msg :: term, state :: term) ::
  {:ok, %Pigeon.Http2.Stream{body: term, error: term, headers: term, id: term, status: term}} |
  any
Link to this callback send_ping(pid) View Source
send_ping(pid) :: :ok
Link to this callback send_request(pid, headers, data) View Source
send_request(pid, headers :: Keyword.t, data :: String.t) :: :ok
Link to this callback start() View Source
start() :: no_return