action_push_native 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c37771ec586061a95004904931f0ffc841177a104fa27b8f5c9404bdef33bcc8
+  data.tar.gz: d39db792468a2516ce99d9330f0612b1ba1ef1ba194ee0cfa3b4f493164c214e
+SHA512:
+  metadata.gz: 761d8d0a9eeb0f4914fa2129dda438958babf02354be17ed87b8264ebd052d10ff73a98723afbeb40c6dc0253de81f26ed37fc93588b3315b08264181cee1554
+  data.tar.gz: b0351f879b5fcf6a244c053bcd375ea4803071ec82d8d56329bd22e4eb7a346f8219f56b34497c27faf705a094490164399df7526dbf04daf89b8d73344d9330

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 37signals, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,329 @@
+# Action Push Native
+
+Action Push Native is a Rails push notification gem for mobile platforms, supporting APNs (Apple) and FCM (Google).
+
+## Installation
+
+```bash
+1. bundle add action_push_native
+2. bin/rails g action_push_native:install
+3. bin/rails action_push_native:install:migrations
+4. bin/rails db:migrate
+```
+
+This will install the gem and run the necessary migrations to set up the database.
+
+## Configuration
+
+The installation will create:
+
+- `app/models/application_push_notification.rb`
+- `app/jobs/application_push_notification_job.rb`
+- `app/models/application_push_device.rb`
+- `config/push.yml`
+
+`app/models/application_push_notification.rb`:
+
+```ruby
+class ApplicationPushNotification < ActionPushNative::Notification
+  # Set a custom job queue_name
+  queue_as :realtime
+
+  # Controls whether push notifications are enabled (default: !Rails.env.test?)
+  self.enabled = Rails.env.production?
+
+  # Define a custom callback to modify or abort the notification before it is sent
+  before_delivery do |notification|
+    throw :abort if Notification.find(notification.context[:notification_id]).expired?
+  end
+end
+```
+
+Used to create and send push notifications. You can customize it by subclassing or
+you can change the application defaults by editing it directly.
+
+`app/jobs/application_push_notification_job.rb`:
+
+```ruby
+class ApplicationPushNotificationJob < ActionPushNative::NotificationJob
+  # Enable logging job arguments (default: false)
+  self.log_arguments = true
+
+  # Report job retries via the `Rails.error` reporter (default: false)
+  self.report_job_retries = true
+end
+```
+
+Job class that processes the push notifications. You can customize it by editing it
+directly in your application.
+
+`app/models/application_push_device.rb`:
+
+```ruby
+class ApplicationPushDevice < ActionPushNative::Device
+  # Customize TokenError handling (default: destroy!)
+  # rescue_from (ActionPushNative::TokenError) { Rails.logger.error("Device #{id} token is invalid") }
+end
+```
+
+This represents a push notification device. You can customize it by editing it directly in your application.
+
+`config/push.yml`:
+
+```yaml
+shared:
+  apple:
+    # Token auth params
+    # See https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns
+    key_id: your_key_id
+    encryption_key: your_apple_encryption_key
+
+    team_id: your_apple_team_id
+    # Your identifier found on https://developer.apple.com/account/resources/identifiers/list
+    topic: your.bundle.identifier
+
+  google:
+    # Your Firebase project service account credentials
+    # See https://firebase.google.com/docs/cloud-messaging/auth-server
+    encryption_key: your_service_account_json_file
+
+    # Firebase project_id
+    project_id: your_project_id
+```
+
+This file contains the configuration for the push notification services you want to use.
+The push notification services supported are `apple` (APNs) and `google` (FCM).
+If you're configuring more than one app, see the section [Configuring multiple apps](#configuring-multiple-apps) below.
+
+### Configuring multiple apps
+
+You can send push notifications to multiple apps using different notification classes.
+Each notification class need to inherit from `ApplicationPushNotification` and set `self.application`, to a key set in `push.yml`
+for each supported platform. You can also (optionally) set a shared `application` option in `push.yml`.
+This acts as the base configuration for that platform, and its values will be merged (and overridden) with the matching app-specific configuration.
+
+In the example below we are configuring two apps: `calendar` and `email` using respectively the
+`CalendarPushNotification` and `EmailPushNotification` notification classes.
+
+```ruby
+class CalendarPushNotification < ApplicationPushNotification
+  self.application = "calendar"
+
+  # Custom notification logic for calendar app
+end
+
+class EmailPushNotification < ApplicationPushNotification
+  self.application = "email"
+
+  # Custom notification logic for email app
+end
+```
+
+```yaml
+shared:
+  apple:
+    # Base configuration for Apple platform
+    # This will be merged with the app-specific configuration
+    application:
+      team_id: your_apple_team_id
+
+    calendar:
+      # Token auth params
+      # See https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns
+      key_id: calendar_key_id
+      encryption_key: calendar_apple_encryption_key
+      # Your identifier found on https://developer.apple.com/account/resources/identifiers/list
+      topic: calendar.bundle.identifier
+
+    email:
+      # Token auth params
+      # See https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns
+      key_id: email_key_id
+      encryption_key: email_apple_encryption_key
+      # Your identifier found on https://developer.apple.com/account/resources/identifiers/list
+      topic: email.bundle.identifier
+
+  google:
+    calendar:
+      # Your Firebase project service account credentials
+      # See https://firebase.google.com/docs/cloud-messaging/auth-server
+      encryption_key: calendar_service_account_json_file
+
+      # Firebase project_id
+      project_id: calendar_project_id
+
+    email:
+      # Your Firebase project service account credentials
+      # See https://firebase.google.com/docs/cloud-messaging/auth-server
+      encryption_key: email_service_account_json_file
+
+      # Firebase project_id
+      project_id: email_project_id
+```
+
+## Usage
+
+### Create and send a notification asynchronously to a device
+
+```ruby
+device = ApplicationPushDevice.create! \
+  name: "iPhone 16",
+  token: "6c267f26b173cd9595ae2f6702b1ab560371a60e7c8a9e27419bd0fa4a42e58f",
+  platform: "apple"
+
+notification = ApplicationPushNotification.new \
+  title: "Hello world!",
+  body:  "Welcome to Action Push Native"
+
+notification.deliver_later_to(device)
+```
+
+`deliver_later_to` supports also an array of devices:
+
+```ruby
+notification.deliver_later_to([ device1, device2 ])
+```
+
+A notification can also be delivered synchronously using `deliver_to`:
+
+```ruby
+notification.deliver_to(device)
+```
+
+It is recommended to send notifications asynchronously using `deliver_later_to`.
+This ensures error handling and retry logic are in place, and avoids blocking your application's execution.
+
+### Application data attributes
+
+You can pass custom data to the application using the `with_data` method:
+
+```ruby
+notification = ApplicationPushNotification
+  .with_data({ badge: "1" })
+  .new(title: "Welcome to Action Push Native")
+```
+
+### Custom platform Payload
+
+You can configure custom platform payload to be sent with the notification. This is useful when you
+need to send additional data that is specific to the platform you are using.
+
+You can use `with_apple` for Apple and `with_google` for Google:
+
+```ruby
+notification = ApplicationPushNotification
+  .with_apple(category: "observable")
+  .with_google(data: { badge: 1 })
+  .new(title: "Hello world!")
+```
+
+The platform payload takes precedence over the other fields, and you can use it to override the
+default behaviour:
+
+```ruby
+notification = ApplicationPushNotification
+  .with_google(android: { notification: { notification_count: nil } })
+  .new(title: "Hello world!", body: "Welcome to Action Push Native", badge: 1)
+```
+
+This will unset the default `notification_count` (`badge`) field in the Google payload, while keeping `title`
+and `body`.
+
+### Silent Notifications
+
+You can create a silent notification via the `silent` method:
+
+```ruby
+notification = ApplicationPushNotification.silent.with_data(id: 1)
+```
+
+This will create a silent notification for both Apple and Google platforms and sets an application
+data field of `{ id: 1 }` for both platforms. Silent push notification must not contain any attribute which would trigger
+a visual notification on the device, such as `title`, `body`, `badge`, etc.
+
+### Linking a Device to a Record
+
+A Device can be associated with any record in your application via the `owner` polymorphic association:
+
+```ruby
+  user = User.find_by_email_address("jacopo@37signals.com")
+
+  ApplicationPushDevice.create! \
+    name: "iPhone 16",
+    token: "6c267f26b173cd9595ae2f6702b1ab560371a60e7c8a9e27419bd0fa4a42e58f",
+    platform: "apple",
+    owner: user
+```
+### `before_delivery` callback
+
+You can specify Active Record like callbacks for the `delivery` method. For example, you can modify
+or cancel the notification by specifying a custom `before_delivery` block. The callback has access
+to the `notification` object. You can also pass additional context data to the notification
+by adding extra arguments to the notification constructor:
+
+```ruby
+  class CalendarPushNotification < ApplicationPushNotification
+    before_delivery do |notification|
+      throw :abort if Calendar.find(notification.context[:calendar_id]).expired?
+    end
+  end
+
+  data = { calendar_id: @calendar.id, identity_id: @identity.id }
+
+  notification = CalendarPushNotification
+    .with_apple(custom_payload: data)
+    .with_google(data: data)
+    .new(calendar_id: 123)
+
+  notification.deliver_later_to(device)
+```
+
+### Using a custom Device model
+
+If using the default `ApplicationPushDevice` model does not fit your needs, you can create a custom
+device model, as long as:
+
+1. It can be serialized and deserialized by `ActiveJob`.
+2. It responds to the `token` and `platform` methods.
+3. It implements a `push` method like this:
+
+```ruby
+class CustomDevice
+  # Your custom device attributes and methods...
+
+  def push(notification)
+    notification.token = token
+    ActionPushNative.service_for(platform, notification).push(notification)
+  rescue ActionPushNative::TokenError => error
+    # Custom token error handling
+  end
+end
+```
+
+## `ActionPushNative::Notification` attributes
+
+| Name           | Description
+|------------------|------------
+| :title           | The title of the notification.
+| :body            | The body of the notification.
+| :badge           | The badge number to display on the app icon.
+| :thread_id       | The thread identifier for grouping notifications.
+| :sound           | The sound to play when the notification is received.
+| :high_priority   | Whether the notification should be sent with high priority (default: true).
+| :google_data     | The Google-specific payload for the notification.
+| :apple_data      | The Apple-specific payload for the notification.
+| :data            | The data payload for the notification, sent to all platforms.
+| **               | Any additional attributes passed to the constructor will be merged in the `context` hash.
+
+### Factory methods
+
+| Name           | Description
+|------------------|------------
+| :with_apple           | Set the Apple-specific payload for the notification.
+| :with_google          | Set the Google-specific payload for the notification.
+| :with_data            | Set the data payload for the notification, sent to all platforms.
+| :silent               | Create a silent notification that does not trigger a visual alert on the device.
+
+## License
+
+Action Push Native is licensed under MIT.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/jobs/action_push_native/notification_job.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ActionPushNative
+  class NotificationJob < ActiveJob::Base
+    self.log_arguments = false
+
+    class_attribute :report_job_retries, default: false
+
+    discard_on ActiveJob::DeserializationError
+    discard_on BadDeviceTopicError do |_job, error|
+      Rails.error.report(error)
+    end
+
+    class << self
+      def retry_options
+        Rails.version >= "8.1" ? { report: report_job_retries } : {}
+      end
+
+      # Exponential backoff starting from a minimum of 1 minute, capped at 60m as suggested by FCM:
+      # https://firebase.google.com/docs/cloud-messaging/scale-fcm#errors
+      #
+      # | Executions | Delay (rounded minutes) |
+      # |------------|-------------------------|
+      # | 1          | 1                       |
+      # | 2          | 2                       |
+      # | 3          | 4                       |
+      # | 4          | 8                       |
+      # | 5          | 16                      |
+      # | 6          | 32                      |
+      # | 7          | 60 (cap)                |
+      def exponential_backoff_delay(executions)
+        base_wait = 1.minute
+        delay = base_wait * (2**(executions - 1))
+        jitter = 0.15
+        jitter_delay = rand * delay * jitter
+
+        [ delay + jitter_delay, 60.minutes ].min
+      end
+    end
+
+    with_options retry_options do
+      retry_on TimeoutError, wait: 1.minute
+      retry_on ConnectionError, ConnectionPool::TimeoutError, attempts: 20
+
+      # Altough unexpected, these are short-lived errors that can be retried most of the times.
+      retry_on ForbiddenError, BadRequestError
+    end
+
+    with_options wait: ->(executions) { exponential_backoff_delay(executions) }, attempts: 6, **retry_options do
+      retry_on TooManyRequestsError, ServiceUnavailableError, InternalServerError
+      retry_on Signet::RemoteServerError
+    end
+
+    def perform(notification_class, notification_attributes, device)
+      notification_class.constantize.new(**notification_attributes).deliver_to(device)
+    end
+  end
+end

data/app/models/action_push_native/device.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActionPushNative
+  class Device < ApplicationRecord
+    include ActiveSupport::Rescuable
+
+    rescue_from(TokenError) { destroy! }
+
+    belongs_to :owner, polymorphic: true, optional: true
+
+    enum :platform, { apple: "apple", google: "google" }
+
+    def push(notification)
+       notification.token = token
+       ActionPushNative.service_for(platform, notification).push(notification)
+    rescue => error
+      rescue_with_handler(error) || raise
+    end
+  end
+end

data/db/migrate/20250610075650_create_action_push_native_device.rb

@@ -0,0 +1,12 @@
+class CreateActionPushNativeDevice < ActiveRecord::Migration[8.0]
+  def change
+    create_table :action_push_native_devices do |t|
+      t.string :name
+      t.string :platform, null: false
+      t.string :token, null: false
+      t.belongs_to :owner, polymorphic: true
+
+      t.timestamps
+    end
+  end
+end

data/lib/action_push_native/configured_notification.rb

@@ -0,0 +1,35 @@
+module ActionPushNative
+  class ConfiguredNotification
+    def initialize(notification_class)
+      @notification_class = notification_class
+      @options = {}
+    end
+
+    def new(**attributes)
+      notification_class.new(**attributes.merge(options))
+    end
+
+    def with_data(data)
+      @options[:data] = @options.fetch(:data, {}).merge(data)
+      self
+    end
+
+    def silent
+      @options = options.merge(high_priority: false)
+      with_apple(content_available: 1)
+    end
+
+    def with_apple(apple_data)
+      @options[:apple_data] = @options.fetch(:apple_data, {}).merge(apple_data)
+      self
+    end
+
+    def with_google(google_data)
+      @options[:google_data] = @options.fetch(:google_data, {}).merge(google_data)
+      self
+    end
+
+    private
+      attr_reader :notification_class, :options
+  end
+end

data/lib/action_push_native/engine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActionPushNative
+  class Engine < ::Rails::Engine
+    isolate_namespace ActionPushNative
+
+    initializer "action_push_native.config" do |app|
+      app.paths.add "config/push", with: "config/push.yml"
+    end
+  end
+end

data/lib/action_push_native/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActionPushNative
+  class TimeoutError < StandardError; end
+  class ConnectionError < StandardError; end
+
+  class BadRequestError < StandardError; end
+  class ForbiddenError < StandardError; end
+  class PayloadTooLargeError < StandardError; end
+  class TooManyRequestsError < StandardError; end
+  class ServiceUnavailableError < StandardError; end
+  class InternalServerError < StandardError; end
+  class BadDeviceTopicError < StandardError; end
+  class NotFoundError < StandardError; end
+
+  class TokenError < StandardError; end
+end

data/lib/action_push_native/notification.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ActionPushNative
+  # = Action Push Native Notification
+  #
+  # A notification that can be delivered to devices.
+  class Notification
+    extend ActiveModel::Callbacks
+
+    attr_accessor :title, :body, :badge, :thread_id, :sound, :high_priority, :apple_data, :google_data, :data
+    attr_accessor :context
+    attr_accessor :token
+
+    define_model_callbacks :delivery
+
+    class_attribute :queue_name, default: ActiveJob::Base.default_queue_name
+    class_attribute :enabled, default: !Rails.env.test?
+    class_attribute :application
+
+    class << self
+      def queue_as(name)
+        self.queue_name = name
+      end
+
+      delegate :with_data, :silent, :with_apple, :with_google, to: :configured_notification
+
+      private
+        def configured_notification
+          ConfiguredNotification.new(self)
+        end
+    end
+
+    # === Attributes
+    #
+    #   title - The title
+    #   body - The message body
+    #   badge - The badge number to display on the app icon
+    #   thread_id - The thread ID for grouping notifications
+    #   sound - The sound to play when the notification is received
+    #   high_priority - Whether to send the notification with high priority (default: true).
+    #                   For silent notifications is recommended to set this to false
+    #   apple_data - Apple Push Notification Service (APNS) specific data
+    #   google_data - Firebase Cloud Messaging (FCM) specific data
+    #   data - Custom data to be sent with the notification
+    #
+    #   Any extra attributes are set inside the `context` hash.
+    def initialize(title: nil, body: nil, badge: nil, thread_id: nil, sound: nil, high_priority: true, apple_data: {}, google_data: {}, data: {}, **context)
+      @title = title
+      @body = body
+      @badge = badge
+      @thread_id = thread_id
+      @sound = sound
+      @high_priority = high_priority
+      @apple_data = apple_data
+      @google_data = google_data
+      @data = data
+      @context = context
+    end
+
+    def deliver_to(device)
+      if enabled
+        run_callbacks(:delivery) { device.push(self) }
+      end
+    end
+
+    def deliver_later_to(devices)
+      Array(devices).each do |device|
+        ApplicationPushNotificationJob.set(queue: queue_name).perform_later(self.class.name, self.as_json, device)
+      end
+    end
+
+    def as_json
+      {
+        title: title,
+        body: body,
+        badge: badge,
+        thread_id: thread_id,
+        sound: sound,
+        high_priority: high_priority,
+        apple_data: apple_data,
+        google_data: google_data,
+        data: data,
+        **context
+      }.compact
+    end
+  end
+end

data/lib/action_push_native/service/apns.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module ActionPushNative
+  module Service
+    class Apns
+      DEFAULT_TIMEOUT   = 30.seconds
+      DEFAULT_POOL_SIZE = 5
+
+      def initialize(config)
+        @config = config
+      end
+
+      # Per-application connection pools
+      cattr_accessor :connection_pools
+
+      def push(notification)
+        reset_connection_error
+
+        connection_pool.with do |connection|
+          rescue_and_reraise_network_errors do
+            apnotic_notification = apnotic_notification_from(notification)
+            Rails.logger.info("Pushing APNs notification: #{apnotic_notification.apns_id}")
+
+            response = connection.push \
+              apnotic_notification,
+              timeout: config[:request_timeout] || DEFAULT_TIMEOUT
+            raise connection_error if connection_error
+            handle_response_error(response) unless response&.ok?
+          end
+        end
+      end
+
+      private
+        attr_reader :config, :connection_error
+
+        def reset_connection_error
+          @connection_error = nil
+        end
+
+        def connection_pool
+          self.class.connection_pools ||= {}
+          self.class.connection_pools[config] ||= build_connection_pool
+        end
+
+        def build_connection_pool
+          build_method = config[:connect_to_development_server] ? "development" : "new"
+          Apnotic::ConnectionPool.public_send(build_method, {
+            auth_method: :token,
+            cert_path: StringIO.new(config.fetch(:encryption_key)),
+            key_id: config.fetch(:key_id),
+            team_id: config.fetch(:team_id)
+          }, size: config[:connection_pool_size] || DEFAULT_POOL_SIZE) do |connection|
+            # Prevents the main thread from crashing collecting the connection error from the off-thread
+            # and raising it afterwards.
+            connection.on(:error) { |error| @connection_error = error }
+          end
+        end
+
+        def rescue_and_reraise_network_errors
+          begin
+            yield
+          rescue Errno::ETIMEDOUT => e
+            raise ActionPushNative::TimeoutError, e.message
+          rescue Errno::ECONNRESET, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
+            raise ActionPushNative::ConnectionError, e.message
+          rescue OpenSSL::SSL::SSLError => e
+            if e.message.include?("SSL_connect")
+              raise ActionPushNative::ConnectionError, e.message
+            else
+              raise
+            end
+          end
+        end
+
+        PRIORITIES = { high: 10, normal: 5 }.freeze
+
+        def apnotic_notification_from(notification)
+          Apnotic::Notification.new(notification.token).tap do |n|
+            n.topic = config.fetch(:topic)
+            n.alert = { title: notification.title, body: notification.body }.compact
+            n.badge = notification.badge
+            n.thread_id = notification.thread_id
+            n.sound = notification.sound
+            n.priority = notification.high_priority ? PRIORITIES[:high] : PRIORITIES[:normal]
+            n.custom_payload = notification.data
+            notification.apple_data&.each do |key, value|
+              n.public_send("#{key.to_s.underscore}=", value)
+            end
+          end
+        end
+
+        def handle_response_error(response)
+          code = response&.status
+          reason = response.body["reason"] if response
+
+          Rails.logger.error("APNs response error #{code}: #{reason}") if reason
+
+          case [ code, reason ]
+          in [ nil, _ ]
+            raise ActionPushNative::TimeoutError
+          in [ "400", "BadDeviceToken" ]
+            raise ActionPushNative::TokenError, reason
+          in [ "400", "DeviceTokenNotForTopic" ]
+            raise ActionPushNative::BadDeviceTopicError, reason
+          in [ "400", _ ]
+            raise ActionPushNative::BadRequestError, reason
+          in [ "403", _ ]
+            raise ActionPushNative::ForbiddenError, reason
+          in [ "404", _ ]
+            raise ActionPushNative::NotFoundError, reason
+          in [ "410", _ ]
+            raise ActionPushNative::TokenError, reason
+          in [ "413", _ ]
+            raise ActionPushNative::PayloadTooLargeError, reason
+          in [ "429", _ ]
+            raise ActionPushNative::TooManyRequestsError, reason
+          in [ "503", _ ]
+            raise ActionPushNative::ServiceUnavailableError, reason
+          else
+            raise ActionPushNative::InternalServerError, reason
+          end
+        end
+    end
+  end
+end

data/lib/action_push_native/service/fcm.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module ActionPushNative
+  module Service
+    class Fcm
+      # FCM suggests at least a 10s timeout for requests, we set 15 to add some buffer.
+      # https://firebase.google.com/docs/cloud-messaging/scale-fcm#timeouts
+      DEFAULT_TIMEOUT = 15.seconds
+
+      def initialize(config)
+        @config = config
+      end
+
+      def push(notification)
+        response = post_request payload_from(notification)
+        handle_error(response) unless response.code == "200"
+      end
+
+      private
+        attr_reader :config
+
+        def payload_from(notification)
+          deep_compact({
+            message: {
+              token: notification.token,
+              data: notification.data ? stringify(notification.data) : {},
+              android: {
+                notification: {
+                  title: notification.title,
+                  body: notification.body,
+                  notification_count: notification.badge,
+                  sound: notification.sound
+                },
+                collapse_key: notification.thread_id,
+                priority: notification.high_priority == true ? "high" : "normal"
+              }
+            }.deep_merge(notification.google_data ? stringify_data(notification.google_data) : {})
+          })
+        end
+
+        def deep_compact(payload)
+          payload.dig(:message, :android, :notification).try(&:compact!)
+          payload.dig(:message, :android).try(&:compact!)
+          payload[:message].compact!
+          payload
+        end
+
+        # FCM requires data values to be strings.
+        def stringify_data(google_data)
+          google_data.tap do |payload|
+            payload[:data] = stringify(payload[:data]) if payload[:data]
+          end
+        end
+
+        def stringify(hash)
+          hash.compact.transform_values(&:to_s)
+        end
+
+        def post_request(payload)
+          uri = URI("https://fcm.googleapis.com/v1/projects/#{config.fetch(:project_id)}/messages:send")
+          request = Net::HTTP::Post.new(uri)
+          request["Authorization"] = "Bearer #{access_token}"
+          request["Content-Type"]  = "application/json"
+          request.body             = payload.to_json
+
+          rescue_and_reraise_network_errors do
+            Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: config[:request_timeout] || DEFAULT_TIMEOUT) do |http|
+              http.request(request)
+            end
+          end
+        end
+
+        def rescue_and_reraise_network_errors
+          yield
+        rescue Net::ReadTimeout, Net::OpenTimeout => e
+          raise ActionPushNative::TimeoutError, e.message
+        rescue Errno::ECONNRESET, SocketError => e
+          raise ActionPushNative::ConnectionError, e.message
+        rescue OpenSSL::SSL::SSLError => e
+          if e.message.include?("SSL_connect")
+            raise ActionPushNative::ConnectionError, e.message
+          else
+            raise
+          end
+        end
+
+        def access_token
+          authorizer = Google::Auth::ServiceAccountCredentials.make_creds \
+            json_key_io: StringIO.new(config.fetch(:encryption_key)),
+            scope: "https://www.googleapis.com/auth/firebase.messaging"
+          authorizer.fetch_access_token!["access_token"]
+        end
+
+        def handle_error(response)
+          code = response.code
+          reason = \
+            begin
+              JSON.parse(response.body).dig("error", "message")
+            rescue JSON::ParserError
+              response.body
+            end
+
+          Rails.logger.error("FCM response error #{code}: #{reason}")
+
+          case
+          when reason =~ /message is too big/i
+            raise ActionPushNative::PayloadTooLargeError, reason
+          when code == "400"
+            raise ActionPushNative::BadRequestError, reason
+          when code == "404"
+            raise ActionPushNative::TokenError, reason
+          when code.in?([ "401", "403" ])
+            raise ActionPushNative::ForbiddenError, reason
+          when code == "429"
+            raise ActionPushNative::TooManyRequestsError, reason
+          when code == "503"
+            raise ActionPushNative::ServiceUnavailableError, reason
+          else
+            raise ActionPushNative::InternalServerError, reason
+          end
+        end
+    end
+  end
+end

data/lib/action_push_native/version.rb

@@ -0,0 +1,3 @@
+module ActionPushNative
+  VERSION = "0.1.0"
+end

data/lib/action_push_native.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "action_push_native/engine"
+require "action_push_native/errors"
+require "net/http"
+require "apnotic"
+require "googleauth"
+
+loader= Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.ignore("#{__dir__}/generators")
+loader.ignore("#{__dir__}/action_push_native/errors.rb")
+loader.setup
+
+module ActionPushNative
+  def self.service_for(platform, notification)
+    platform_config = config_for(platform, notification)
+
+    case platform.to_sym
+    when :apple
+      Service::Apns.new(platform_config)
+    when :google
+      Service::Fcm.new(platform_config)
+    else
+      raise "ActionPushNative: '#{platform}' platform is unsupported"
+    end
+  end
+
+  def self.config_for(platform, notification)
+    platform_config = Rails.application.config_for(:push)[platform.to_sym]
+    raise "ActionPushNative: '#{platform}' platform is not configured" unless platform_config.present?
+
+    if notification.application.present?
+      notification_config = platform_config.fetch(notification.application.to_sym, {})
+      platform_config.fetch(:application, {}).merge(notification_config)
+    else
+      platform_config
+    end
+  end
+end

data/lib/generators/action_push_native/install/install_generator.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class ActionPushNative::InstallGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  def copy_files
+    template "config/push.yml"
+    template "app/models/application_push_notification.rb"
+    template "app/models/application_push_device.rb"
+    template "app/jobs/application_push_notification_job.rb"
+  end
+end

data/lib/generators/action_push_native/install/templates/app/jobs/application_push_notification_job.rb.tt

@@ -0,0 +1,7 @@
+class ApplicationPushNotificationJob < ActionPushNative::NotificationJob
+  # Enable logging job arguments (default: false)
+  # self.log_arguments = true
+
+  # Report job retries via the `Rails.error` reporter (default: false)
+  # self.report_job_retries = true
+end

data/lib/generators/action_push_native/install/templates/app/models/application_push_device.rb.tt

@@ -0,0 +1,4 @@
+class ApplicationPushDevice < ActionPushNative::Device
+  # Customize TokenError handling (default: destroy!)
+  # rescue_from (ActionPushNative::TokenError) { Rails.logger.error("Device #{id} token is invalid") }
+end

data/lib/generators/action_push_native/install/templates/app/models/application_push_notification.rb.tt

@@ -0,0 +1,12 @@
+class ApplicationPushNotification < ActionPushNative::Notification
+  # Set a custom job queue_name
+  # queue_as :realtime
+
+  # Controls whether push notifications are enabled (default: !Rails.env.test?)
+  # self.enabled = Rails.env.production?
+
+  # Define a custom callback to modify or abort the notification before it is sent
+  # before_delivery do |notification|
+  #   throw :abort if Notification.find(notification.context[:notification_id]).expired?
+  # end
+end

data/lib/generators/action_push_native/install/templates/config/push.yml.tt

@@ -0,0 +1,34 @@
+shared:
+  apple:
+    # Token auth params
+    # See https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns
+    key_id: your_key_id
+    encryption_key: your_apple_encryption_key
+
+    team_id: your_apple_team_id
+    # Your identifier found on https://developer.apple.com/account/resources/identifiers/list
+    topic: your.bundle.identifier
+
+    # Set this to the number of threads used to process notifications (default: 5).
+    # When the pool size is too small a ConnectionPool::TimeoutError error will be raised.
+    # connection_pool_size: 5
+
+    # Change the request timeout (default: 30).
+    # request_timeout: 60
+
+    # Decide when to connect to APNs development server.
+    # Please note that anything built directly from Xcode and loaded on your phone will have
+    # the app generate DEVELOPMENT tokens, while everything else (TestFlight, Apple Store, ...)
+    # will be considered as PRODUCTION environment.
+    # connect_to_development_server: <%# Rails.env.development? %>
+
+  google:
+    # Your Firebase project service account credentials
+    # See https://firebase.google.com/docs/cloud-messaging/auth-server
+    encryption_key: your_service_account_json_file
+
+    # Firebase project_id
+    project_id: your_project_id
+
+    # Change the request timeout (default: 15).
+    # request_timeout: 30

metadata

@@ -0,0 +1,145 @@
+--- !ruby/object:Gem::Specification
+name: action_push_native
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jacopo Beschi
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: apnotic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: googleauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description: Send push notifications to mobile apps
+email:
+- jacopo@37signals.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/jobs/action_push_native/notification_job.rb
+- app/models/action_push_native/device.rb
+- db/migrate/20250610075650_create_action_push_native_device.rb
+- lib/action_push_native.rb
+- lib/action_push_native/configured_notification.rb
+- lib/action_push_native/engine.rb
+- lib/action_push_native/errors.rb
+- lib/action_push_native/notification.rb
+- lib/action_push_native/service/apns.rb
+- lib/action_push_native/service/fcm.rb
+- lib/action_push_native/version.rb
+- lib/generators/action_push_native/install/install_generator.rb
+- lib/generators/action_push_native/install/templates/app/jobs/application_push_notification_job.rb.tt
+- lib/generators/action_push_native/install/templates/app/models/application_push_device.rb.tt
+- lib/generators/action_push_native/install/templates/app/models/application_push_notification.rb.tt
+- lib/generators/action_push_native/install/templates/config/push.yml.tt
+homepage: https://github.com/basecamp/action_push_native
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/basecamp/action_push_native
+  source_code_uri: https://github.com/basecamp/action_push_native
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Send push notifications to mobile apps
+test_files: []