Pigeon 2.0.0-rc.0 Released

It’s been a long time coming, but it’s here! A lot of significant updates and new features, including the FCM v1 API with web-push support and better runtime configuration of push workers.

This will serve as an unofficial migration guide until I’ve written one. Feedback is welcome!

Hexdocs available here.

Using the New Worker Setup

Pigeon 1.x uses default expected atom names for workers and supervised all of them independent from your application. This has been done away with for more of an Ecto-style setup in your supervision tree. The following example is for APNS, but it’s a similar strategy for all of your other push workers.

1. Create an APNS dispatcher.

# lib/apns.ex
defmodule YourApp.APNS do
  use Pigeon.Dispatcher, otp_app: :your_app
end

2. (Optional) Add configuration to your config.exs. Note the :adapter key, which tells Pigeon what kind of worker you are setting up.

# config.exs

config :your_app, YourApp.APNS,
  adapter: Pigeon.APNS,
  cert: File.read!("cert.pem"),
  key: File.read!("key_unencrypted.pem"),
  mode: :dev

3. Start your dispatcher on application boot.

defmodule YourApp.Application do
  @moduledoc false

  use Application

  @doc false
  def start(_type, _args) do
    children = [
      YourApp.APNS
    ]
    opts = [strategy: :one_for_one, name: YourApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

If you skipped step two, include your configuration.

defmodule YourApp.Application do
  @moduledoc false

  use Application

  @doc false
  def start(_type, _args) do
    children = [
      {YourApp.APNS, apns_opts()}
    ]
    opts = [strategy: :one_for_one, name: YourApp.Supervisor]
    Supervisor.start_link(children, opts)
  end

  defp apns_opts do
    [
      adapter: Pigeon.APNS,
      cert: File.read!("cert.pem"),
      key: File.read!("key_unencrypted.pem"),
      mode: :dev
    ]
  end
end

4. Create a notification.

n = Pigeon.APNS.Notification.new("your message", "your device token", "your push topic")

5. Send the notification. Note: you use the module name! Not Pigeon.APNS.

YourApp.APNS.push(n)

Using this strategy should make it far more flexible for worker setup, including things like loading dynamic push configurations from a database. See Pigeon.Dispatcher for more instructions.

FCM v1.0 API

All legacy Pigeon.FCM functionality has been renamed to Pigeon.LegacyFCM. You will need to do a project-wide rename, or else update to the new configuration and notification structure.

# Before
Pigeon.FCM.Notification.new("reg ID", %{"body" => "test message"})

# After
Pigeon.LegacyFCM.Notification.new("reg ID", %{"body" => "test message"})

The new Pigeon.FCM.Notification exposes all of the v1 notification attributes you might expect to use, but makes no guarantees about structure and typing, apart from the top-level keys. This gets you maximum flexibility to use the API how you need, including things like custom APNS options or web push.

Notification targets replace the typical RegID string. You now pass a tuple for what you want, such as {:token, "regid"}, {:topic, "yourtopic"}, or {:condition, "yourcondition"}.

Pigeon.FCM.Notification.new({:token, "reg ID"})
%Pigeon.FCM.Notification{
  data: nil,
  notification: nil,
  target: {:token, "reg ID"}
}

Pigeon.FCM.Notification.new({:topic, "example"})
%Pigeon.FCM.Notification{
  data: nil,
  notification: nil,
  target: {:topic, "example"}
}

Notification moduledocs here. You also might want to reference the Firebase v1 Message API as well.

Custom Adapters

Probably the coolest feature of this update is the new Pigeon.Adapter behaviour, which all Pigeon workers implement. What does this mean long term? Anybody can write a push adapter for Pigeon, whether that’s a third party push service, SMS, webhooks, or anything else. Expect better documentation on this soon, but in the meantime if you’re interested in writing an adapter, reach out to me and I can help!

Here is an example of the Pigeon.Sandbox adapter, which is useful for tests and local development. It will mark any push as :success and return it.

defmodule Pigeon.Sandbox do
  import Pigeon.Tasks, only: [process_on_response: 1]

  @behaviour Pigeon.Adapter

  @impl true
  def init(opts \ []) do
    {:ok, opts}
  end

  @impl true
  def handle_info(_msg, state) do
    {:noreply, state}
  end

  @impl true
  def handle_push(%{response: nil} = notification, on_response, _state) do
    process_on_response(on_response, %{notification | response: :success})
    {:noreply, state}
  end

  def handle_push(notification, on_response, state) do
    process_on_response(on_response, notification)
    {:noreply, state}
  end
end

Worker Pooling By Default

Now that APNS allows multiple persistent connections, worker pooling has been enabled by default. The default value is 5 for all services, but this can be overridden on a per-dispatcher basis or globally.

# Just the FCM worker
config :your_app, YourApp.FCM,
  pool_size: 10

# Globally
config :pigeon, :default_pool_size, 10

Next Steps

This release removes a lot of the cruft from design choices that were made in the early days of Pigeon. It is highly encouraged to adopt the new FCM v1 API. Many users of Pigeon jumped through hoops to get dynamic runtime workers started. Feedback is welcome on the new style-- hopefully it’s far more pleasant!

So what’s next feature-wise? Telemetry metrics. Expect it in a 2.1 release!

v1.2.0 Released

Now with support for APNS JWT configuration! Special thanks to @Lankester for the feature.

It’s very simple to configure! Pigeon can auto-detect whether you are using a certificate or token config.

config :pigeon, :apns,
  apns_default: %{
    key: "AuthKey.p8",
    key_identifier: "ABC1234567",
    team_id: "DEF8901234",
    mode: :dev
  }

:key is configured just like :cert, which can be a file path, file contents, string or tuple.

Kadabra Updates

Pigeon now uses Kadabra 0.4.2, which brings more http2 stability improvements. Various race condition errors during connection shutdown should now be fixed!

Roadmap Ahead

The only remaining major feature is FCM web push encryption support. Once implemented, focus will shift to improving the reliability of error handling for failed push notifications. There are certain Kadabra API changes in the works that will make this task much easier. It’s finally starting to mature into a more general purpose http2 client. Take a look at the repo if you haven’t already.

Does pigeon implement the full IPoAC Protocol?

Congratulations @hpopp! Just wanted to say you’re doing a great job as the maintainer of Pigeon, and collaborating with you on pull requests and issues has been a pleasure.

Also I’ve been running Pigeon in production for nearly a year, and it’s been pretty stable, not to mention a breeze to set up. Thanks for your contributions to the Elixir ecosystem!

Maybe in a future release. I hear supervision is a bit complicated when they die.