Pigeon v2 Planning

[hpopp]

General Updates

• Migrate from Pigeon supervision to workers started under application's supervision tree
  • basically Ecto Repo style
• Configurable JSON library (1.6.0 release)
  • default to Jason
• Remove HTTP2.Client behaviour
  • non-Kadabra adapters haven't been officially supported for a while
• 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

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

FCM

• Use the v1 FCM API instead of legacy Support the FCM HTTP V1  #169

ADM

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

Nice to Haves

• Some sort of test adapter override for Pigeon workers (feat: sandbox test adapter #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 ❤️

[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?

[Sinc63]

One of my coworkers received the information below (my emphasis added) regarding FCM messaging to Google. We have 2 days before the legacy API is not supported and a month or two before it stops working at all. The updated APIs that we need are available only in the Release 2 version of Pigeon, so it is important to all your users that you release this version (with the important migration notes if possible) as soon as possible. I'm already working on an upgrade of our push notification software, so getting Pigeon V2 at the same time would be great!

I hope you are close to ready and can complete things shortly. Thanks for your efforts.

We’re writing to remind you that starting **June 20, 2024** the legacy Firebase Cloud Messaging (FCM) APIs will be discontinued. This change will cause the legacy APIs to return an increased number of error responses.

The discontinued APIs will be **completely shut down by July-August 2024**.

What you need to do
If you’re still using legacy APIs to send messages with FCM, and do not expect the migration to the HTTP v1 API to be completed by June 20, 2024, please submit an extension request with Firebase Support before then to avoid disruptions in your service.

We’re here to help
We understand this change may take some planning, and we're here to support you during this transition. If you have any questions or need more information about the specific error codes and error messages, please review the Firebase FAQs.

[neel-desh]

I recently migrated pigeon 1.6.3 to 2.0.0-rc.2. Let me know if I can help write migration guide. 🥹 Would love to do this.
Plus if yes, do share guidelines to follow since a newbie here ✅

[hpopp]

Pigeon v2 officially out! Closing this.