thecore_backend_commons 3.2.11 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe73ef2835e94090bd037724805658c43bb87820a68d2fc86eadd35747ef8e94
-  data.tar.gz: 707da7e03c6f3bad7499c95fa8616e0f43ff75feed46ebe0159ec05a0594f06f
+  metadata.gz: 00717650bd9fe40c41bdf1c30e6372a2abbd095f461b3d1271048e9e408cb8ea
+  data.tar.gz: b613ac4217fb65df2b934dc289b6d4167eb19d0f0605ab44914bb9996385467c
 SHA512:
-  metadata.gz: 047fff2d4b57e67c7320df0e8d38874603084e91cab99d8e5802807bcf903f75c503360fa5e4845692876906db4118f720457f631c9a51cfbaf65099ed0a8a39
-  data.tar.gz: 10d926f3d871d4adb4ce2cc7a721b930d32a608ceb2505fc37e07f1408c0a96fe7f7e1d23c065a55e35d344d3433e2dc4fc1c7cb2778e5550079eeea56031ce4
+  metadata.gz: c6e95d2f7f3ad718c6a1722cc679be17761179f5dac5c0dbabe9590403f3c297a66f67223366871fe35a78d5786ad73699feb30a1028d76603310526fa20cccf
+  data.tar.gz: b7d31a43dbc06cb21846674ba6d3f74bed4d2061b7f70c21c823612a13bc5af14d350d0881bd21f9750b0417d53679008405ec9dac204c3c1134dc2e6b6ff041

data/README.md

@@ -1,4 +1,130 @@
-This is part of Thecore framework: https://github.com/gabrieletassoni/thecore/tree/release/3
+This is part of [Thecore framework](https://github.com/gabrieletassoni/thecore/tree/release/3).
+
+---
+
+## Web Push notifications (VAPID)
+
+Self-contained browser push notifications — no Firebase, no APNs, no third-party account required. The gem provides the server-side half: models, dispatch service, and ActionCable channel. The client integration guide (React + service worker) lives in the [`model_driven_api` README](../model_driven_api/README.md#web-push-vapid-from-a-react-client).
+
+### How it works
+
+```
+Browser                   Rails backend
+  │                            │
+  │── POST subscribe ─────────►│  PushSubscriber.subscribe_for(user, endpoint:, p256dh:, auth:)
+  │                            │
+  │◄─ ActionCable stream ──────│  PushNotificationChannel streams push_notifications_subscriber_N
+  │                            │
+  │  [backend sends push]      │  PushNotificationService.dispatch(subscriber, message)
+  │◄─ Web Push payload ────────│    → Webpush.payload_send (VAPID)
+  │                            │    → message.sent_at = now
+  │── POST acknowledge ────────►│  message.update!(received_at: / read_at:)
+```
+
+### Server configuration
+
+VAPID keys are generated automatically the first time `rails db:seed` runs. You only need to set the contact email via RailsAdmin → Settings:
+
+| ThecoreSettings key (`ns: :vapid`) | Purpose | Default |
+|------------------------------------|---------|---------|
+| `public_key` | VAPID public key (base64url) — send to browsers | generated at seed |
+| `private_key` | VAPID private key — never expose to clients | generated at seed |
+| `contact_email` | `mailto:` URI in VAPID `sub` claim | `""` (set this) |
+| `max_messages_per_subscriber` | PushMessage retention cap per subscriber | `"500"` |
+
+> **Regenerating VAPID keys invalidates all existing `PushSubscriber` records.** Every registered browser must re-subscribe.
+
+### Models
+
+#### `PushSubscriber`
+
+Represents one browser/device subscription registered by a `User`.
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `user_id` | bigint | FK to users |
+| `endpoint` | text | Unique; push service URL provided by the browser |
+| `p256dh` | string | ECDH public key (base64url) |
+| `auth` | string | Auth secret (base64url) |
+| `user_agent` | string | Browser/OS identifier |
+| `expired_at` | datetime | `nil` = active; set when the push service returns 410 |
+
+```ruby
+# Upsert by endpoint (re-registering an existing browser updates the record)
+PushSubscriber.subscribe_for(user, endpoint:, p256dh:, auth:, user_agent:)
+
+# Scope: only active (not expired)
+PushSubscriber.active
+
+# Expire a subscriber (called automatically on 410 from push service)
+subscriber.expire!
+```
+
+#### `PushMessage`
+
+Records a notification payload and its lifecycle.
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `push_subscriber_id` | bigint | FK |
+| `title` | string | Required |
+| `body` | text | Required |
+| `url` | string | URL to open on notification click (optional) |
+| `icon` | string | Notification icon URL (optional) |
+| `sent_at` | datetime | Populated by `PushNotificationService` on successful dispatch |
+| `received_at` | datetime | Set by client via `acknowledge` endpoint |
+| `read_at` | datetime | Set by client via `acknowledge` endpoint |
+
+Old messages beyond `vapid.max_messages_per_subscriber` are pruned automatically after each dispatch (oldest first).
+
+### `PushNotificationService`
+
+```ruby
+ThecoreBackendCommons::PushNotificationService.dispatch(subscriber, message)
+```
+
+1. Calls `Webpush.payload_send` with the subscriber's keys and the VAPID credentials from `ThecoreSettings`.
+2. On success: sets `message.sent_at = Time.current`.
+3. On `Webpush::ExpiredSubscription` or `Webpush::InvalidSubscription` (HTTP 410/404 from push service): calls `subscriber.expire!`.
+4. Prunes oldest `PushMessage` records if the subscriber exceeds the retention cap.
+5. Always returns `message` — errors are rescued and logged, never propagated.
+
+### `PushNotificationChannel` (ActionCable)
+
+```ruby
+# In your connection.rb — current_user must be set
+class ApplicationCable::Connection < ActionCable::Connection::Base
+  identified_by :current_user
+  # ... authenticate and set current_user
+end
+```
+
+Subscribe from the frontend:
+
+```javascript
+// Stream for one subscriber (most common)
+consumer.subscriptions.create(
+  { channel: "PushNotificationChannel", subscriber_id: subscriberId },
+  { received(data) { /* handle message */ } }
+);
+
+// Stream for all active subscribers of the current user
+consumer.subscriptions.create(
+  { channel: "PushNotificationChannel", user_id: currentUserId },
+  { received(data) { /* handle message */ } }
+);
+```
+
+The channel only streams to `subscriber_id` values that belong to `current_user` — unauthorized subscriber IDs are silently ignored.
+
+Broadcast from anywhere in the backend:
+
+```ruby
+PushNotificationChannel.broadcast_to(subscriber, message)
+# Sends message.as_json to "push_notifications_subscriber_#{subscriber.id}"
+```
+
+---
 
 ## Invio email e configurazione SMTP
 

data/app/channels/push_notification_channel.rb

@@ -0,0 +1,18 @@
+class PushNotificationChannel < ApplicationCable::Channel
+  def subscribed
+    if params[:subscriber_id].present?
+      subscriber = PushSubscriber.active.find_by(id: params[:subscriber_id], user_id: current_user.id)
+      stream_from "push_notifications_subscriber_#{subscriber.id}" if subscriber
+    elsif params[:user_id].present? && params[:user_id].to_i == current_user.id
+      PushSubscriber.active.where(user_id: current_user.id).each do |sub|
+        stream_from "push_notifications_subscriber_#{sub.id}"
+      end
+    end
+  end
+
+  def unsubscribed; end
+
+  def self.broadcast_to(subscriber, message)
+    ActionCable.server.broadcast("push_notifications_subscriber_#{subscriber.id}", message.as_json)
+  end
+end

data/app/models/push_message.rb

@@ -0,0 +1,5 @@
+class PushMessage < ApplicationRecord
+  belongs_to :push_subscriber
+  validates :title, presence: true
+  validates :body, presence: true
+end

data/app/models/push_subscriber.rb

@@ -0,0 +1,21 @@
+class PushSubscriber < ApplicationRecord
+  belongs_to :user
+  has_many :push_messages, dependent: :destroy
+  validates :endpoint, presence: true, uniqueness: true
+  scope :active, -> { where(expired_at: nil) }
+
+  def expire!
+    update!(expired_at: Time.current)
+  end
+
+  def self.subscribe_for(user, endpoint:, p256dh: nil, auth: nil, user_agent: nil)
+    record = find_or_initialize_by(endpoint: endpoint)
+    record.user = user
+    record.p256dh = p256dh
+    record.auth = auth
+    record.user_agent = user_agent
+    record.expired_at = nil
+    record.save!
+    record
+  end
+end

data/db/migrate/20260616000001_create_push_subscribers.rb

@@ -0,0 +1,15 @@
+class CreatePushSubscribers < ActiveRecord::Migration[7.2]
+  def change
+    create_table :push_subscribers do |t|
+      t.bigint :user_id, null: false
+      t.text :endpoint, null: false
+      t.string :p256dh
+      t.string :auth
+      t.string :user_agent
+      t.datetime :expired_at
+      t.timestamps
+    end
+    add_index :push_subscribers, :endpoint, unique: true
+    add_index :push_subscribers, :user_id
+  end
+end

data/db/migrate/20260616000002_create_push_messages.rb

@@ -0,0 +1,16 @@
+class CreatePushMessages < ActiveRecord::Migration[7.2]
+  def change
+    create_table :push_messages do |t|
+      t.bigint :push_subscriber_id, null: false
+      t.string :title, null: false
+      t.text :body, null: false
+      t.string :url
+      t.string :icon
+      t.datetime :sent_at
+      t.datetime :received_at
+      t.datetime :read_at
+      t.timestamps
+    end
+    add_index :push_messages, :push_subscriber_id
+  end
+end

data/db/seeds.rb

@@ -10,4 +10,15 @@ Thecore::Seed.save_setting :smtp, :domain, ""
 Thecore::Seed.save_setting :smtp, :user_name, ""
 Thecore::Seed.save_setting :smtp, :password, ""
 Thecore::Seed.save_setting :smtp, :authentication, ""
-Thecore::Seed.save_setting :smtp, :enable_starttls_auto, ""
+Thecore::Seed.save_setting :smtp, :enable_starttls_auto, ""
+
+puts "Loading ThecoreBackendCommons VAPID config"
+require "web-push"
+unless ThecoreSettings::Setting.where(ns: :vapid, key: :public_key).where.not(raw: [nil, ""]).exists?
+  vapid_key = WebPush.generate_key
+  Thecore::Seed.save_setting :vapid, :public_key, vapid_key.public_key
+  Thecore::Seed.save_setting :vapid, :private_key, vapid_key.private_key
+  puts "  Generated new VAPID key pair"
+end
+Thecore::Seed.save_setting :vapid, :contact_email, "" unless ThecoreSettings::Setting.where(ns: :vapid, key: :contact_email).exists?
+Thecore::Seed.save_setting :vapid, :max_messages_per_subscriber, "500" unless ThecoreSettings::Setting.where(ns: :vapid, key: :max_messages_per_subscriber).exists?

data/lib/thecore_backend_commons/push_notification_service.rb

@@ -0,0 +1,58 @@
+module ThecoreBackendCommons
+  class PushNotificationService
+    MAX_MESSAGES_DEFAULT = 500
+
+    def self.dispatch(subscriber, message)
+      new(subscriber, message).dispatch
+    end
+
+    def initialize(subscriber, message)
+      @subscriber = subscriber
+      @message = message
+    end
+
+    def dispatch
+      send_push
+      prune_old_messages
+      @message
+    rescue => e
+      Rails.logger.error("[PushNotificationService] dispatch failed: #{e.message}")
+      @message
+    end
+
+    private
+
+    def send_push
+      WebPush.payload_send(
+        message: JSON.generate(payload),
+        endpoint: @subscriber.endpoint,
+        p256dh: @subscriber.p256dh,
+        auth: @subscriber.auth,
+        vapid: vapid_options
+      )
+      @message.update!(sent_at: Time.current)
+    rescue WebPush::ExpiredSubscription, WebPush::InvalidSubscription
+      @subscriber.expire!
+    end
+
+    def payload
+      { title: @message.title, body: @message.body, url: @message.url, icon: @message.icon }.compact
+    end
+
+    def vapid_options
+      {
+        public_key: ThecoreSettings::Setting.where(ns: :vapid, key: :public_key).pluck(:raw).first,
+        private_key: ThecoreSettings::Setting.where(ns: :vapid, key: :private_key).pluck(:raw).first,
+        subject: "mailto:#{ThecoreSettings::Setting.where(ns: :vapid, key: :contact_email).pluck(:raw).first.presence || 'admin@example.com'}"
+      }
+    end
+
+    def prune_old_messages
+      limit = ThecoreSettings::Setting.where(ns: :vapid, key: :max_messages_per_subscriber).pluck(:raw).first&.to_i || MAX_MESSAGES_DEFAULT
+      count = @subscriber.push_messages.count
+      return unless count > limit
+      oldest_ids = @subscriber.push_messages.order(created_at: :asc).limit(count - limit).pluck(:id)
+      PushMessage.where(id: oldest_ids).delete_all
+    end
+  end
+end

data/lib/thecore_backend_commons/version.rb

@@ -1,3 +1,3 @@
 module ThecoreBackendCommons
-  VERSION = "3.2.11".freeze
+  VERSION = "3.3.0".freeze
 end

data/lib/thecore_backend_commons.rb

@@ -1,4 +1,5 @@
 require "ostruct"
+require "web-push" # gem for VAPID web push (pushpad/web-push, actively maintained)
 require "thecore_auth_commons"
 require "thecore_background_jobs"
 require "rails-i18n"
@@ -15,6 +16,7 @@ require "thecore_backend_commons/version"
 require "thecore_backend_commons/engine"
 require "thecore_backend_commons/smtp_config"
 require "thecore_backend_commons/smtp_tester"
+require "thecore_backend_commons/push_notification_service"
 
 module ThecoreBackendCommons
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thecore_backend_commons
 version: !ruby/object:Gem::Version
-  version: 3.2.11
+  version: 3.3.0
 platform: ruby
 authors:
 - Gabriele Tassoni
@@ -177,6 +177,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: web-push
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: Wrapper to keep all the common libraries and setups needed by Thecore
   UI Backend(s).
 email:
@@ -188,7 +202,10 @@ files:
 - README.md
 - Rakefile
 - app/channels/activity_log_channel.rb
+- app/channels/push_notification_channel.rb
 - app/mailers/concerns/smtp_deliverable.rb
+- app/models/push_message.rb
+- app/models/push_subscriber.rb
 - config/initializers/abilities.rb
 - config/initializers/add_to_db_migrations.rb
 - config/initializers/after_initialize.rb
@@ -203,10 +220,13 @@ files:
 - config/locales/en.yml
 - config/locales/it.devise.custom.yml
 - config/locales/it.yml
+- db/migrate/20260616000001_create_push_subscribers.rb
+- db/migrate/20260616000002_create_push_messages.rb
 - db/seeds.rb
 - lib/tasks/thecore_backend_commons_tasks.rake
 - lib/thecore_backend_commons.rb
 - lib/thecore_backend_commons/engine.rb
+- lib/thecore_backend_commons/push_notification_service.rb
 - lib/thecore_backend_commons/smtp_config.rb
 - lib/thecore_backend_commons/smtp_tester.rb
 - lib/thecore_backend_commons/version.rb