Pigeon v1.6.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 Types

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 :: uri(), 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 :: [{binary(), binary()}, ...], data :: String.t()) ::
  :ok