Pigeon v2 Planning

[hpopp]

General Updates

• [x] Migrate from Pigeon supervision to workers started under application's supervision tree
  • basically Ecto Repo style
• [x] Configurable JSON library (1.6.0 release)
  • default to Jason
• [x] Remove HTTP2.Client behaviour
  • non-Kadabra adapters haven't been officially supported for a while
• [x] Add a proper CONTRIBUTING.md
  • Simplify test configuration and document it (currently kind of a hot mess)
  • Credo and dialyzer checks for PRs, integration tests for master only
• [ ] v2 Migration Guide

APNS

• [x] Drop the :cert/:certfile and :key/:keyfile nonsense and only take :cert and :key strings. (#183)
  • This will require the user to File.read! their own secrets.
• [x] Revisit any significant APNS API updates and make sure they are supported (#196)
  • Maybe support web push, assuming no major API overhauls (Revisit in future versions with an adapter).

FCM

• [x] Use the v1 FCM API instead of legacy #169

ADM

• [x] Revisit HTTP2 support for ADM API and implement if available (Still not currently supported)

Nice to Haves

• [x] Some sort of test adapter override for Pigeon workers (#199)
• Maybe some sort of local development Plug route to look at dispatched pushes (Bamboo style)

[jayjun]

Thanks for making Pigeon! It’s one of the key libraries for our app, would love to help make v2 happen. Consider starting a #pigeon channel at Elixir Slack if you prefer informal discussions.

[hpopp]

Excellent idea. Looks like the channel name conflicts with someone's pigeon username, so I set one up at #pigeon_

[mayel]

How are things looking for v2? Are you considering including Web Push as well?

[hpopp]

Finally coming up for air to work on this release. Web push will likely be the last item on the list, as I need to complete the other restructuring tasks first. Any help in planning or implementation would be much appreciated!

[mayel]

Web push will likely be the last item on the list, as I need to complete the other restructuring tasks first. Any help in planning or implementation would be much appreciated!

Not sure if it's any help, but I have to a WIP implementation of web push here: https://github.com/bonfire-ecosystem/bonfire_notifications

It relies on this library, but I've so far hit a roadblock getting it to work: https://hex.pm/packages/web_push_encryption

[hpopp]

Thanks for the heads up, I'll take a look!

[aenonGit]

hei man, thanks for the great job here! Do you have any news on the v2?

[hpopp]

So some general updates. I'm polishing off the MR at #185 that will support the new Ecto-style workers.

I'm introducing new Pigeon.Dispatcher and Pigeon.Adapter modules that will make this process a lot more generic. You'll configure multiple dispatchers for your application similar to a Repo.

What this looks like in code:

defmodule YourApp.APNS do
  use Pigeon.Dispatcher, otp_app: :your_app
end

# config.exs

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

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

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

Unfortunately in the rework it made dynamically-spawned workers quite a bit harder. I'll need to tweak a bit to get them working again before merge.

Next Steps

Once this new style is in place, anyone could write custom adapters for any sort of push system and publish on hex. As a proof of concept, if I run into any compatibility issues with the new FCM API, I will likely introduce it as a new adapter within the project, and rename the old one to FCMLegacy. APNS Web push will also be a new adapter once I get to it.

Edit Never mind on the dynamic workers. They work great with the new changes!

[hpopp]

FCM v1 implementation has now been merged to master! The legacy FCM API has been renamed to LegacyFCM, as the payload and configuration are quite a bit different. That API has not changed, so doing a simple rename in your projects should not break functionality.

Configuring an FCM Dispatcher

config :your_app, YourApp.FCM,
  adapter: Pigeon.FCM,
  project_id: "your-project-1234",
  service_account_json: File.read!("service-account.json")

Design Choices

FCM v1 introduces a dozen or so object types and over 100 configurable attributes in a single message. Apart from the top level message keys, pigeon makes no effort to validate the fine-grained settings. Users of pigeon are likely reading the FCM docs anyway, so in theory, this it supports every possible use-case for FCM dispatch.

  @type t :: %__MODULE__{
          android: map | nil,
          apns: map | nil,
          data: map | nil,
          error: map | nil,
          fcm_options: map | nil,
          name: binary | nil,
          notification: map | nil,
          response: atom | nil,
          target: target,
          validate_only: boolean | nil,
          webpush: map | nil
        }

  @typedoc ~S"""
  FCM notification target. Must be one of the following:

  - `{:token, "string"}` - Registration token to send a message to.
  - `{:topic, "string"}` - Topic name to send a message to, e.g. "weather". Note: "/topics/" prefix should not be provided.
  - `{:condition, "string"}` - Condition to send a message to, e.g. "'foo' in topics && 'bar' in topics".
  """
  @type target :: {:token, binary} | {:topic, binary} | {:condition, binary}

v1 actually simplifies push responses. You can only send to one token, topic, or topic conditional at a time. No more batching of registration tokens.

      iex> Pigeon.FCM.Notification.new({:token, "reg ID"}, %{"body" => "test message"})
      %Pigeon.FCM.Notification{
        data: nil,
        notification: %{"body" => "test message"},
        target: {:token, "reg ID"}
      }

On successful response, :name will be set to the name returned from the FCM API. If there was an error, :error will contain a JSON map of the response. :response remains similar to the other notification structs. If successful, it will have an atom of :success. If error, it will return an atomized version of the error name. Other possible values include :not_started, :timeout, or :unknown_error (if no string match of the returned error).

Next Steps

The only thing left is polish, testing, and writing a v2 migration guide. Expect to have a release candidate out soon!

[victorolinasc]

Hi @hpopp ! Thank you very much for your work on Pigeon!

We haven't tested this branch yet but I just wanted to know if you are still working on this and intend to release this 2.0 version. If we can help in any way just tell me and I can give you some feedback!

Thanks once again!

[hpopp]

Yeah the RC's should be pretty close to final release. I just published 2.0.0-rc.1 that bundled a fix from earlier this year.

[macciomauro]

Hi! any update on the final release? Seems that Firebase is going to dismiss the legacy FCM next year (an email came in these days). It seems here that the V2 is pretty ready.

Thank you for all you work :heart:

[Xunjin]

@macciomauro Indeed, It appears that we just need a migration guide for v2. @hpopp Any help needed to revise the PR or even doing it, just ping me :D

~~PS: I wasn't able to find the version 2.0.0-rc.1 mentioned, maybe it's not released on GitHub?~~

Found on Hex: https://hex.pm/packages/pigeon/2.0.0-rc.1

TY @brosquinha for always saving my lazy **s

[tommyshadowboxer]

Any news on this? Is there a migration guide for v2?