thecore_backend_commons 3.2.10 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c3ab89916ec1ac0d08617605d32e5ad30b2bc8232df838a29a9b75966f0d653
-  data.tar.gz: 89ea95480895118d1641d964fae91339e3714cb126e3d0ae3343b83e9c18c289
+  metadata.gz: 00717650bd9fe40c41bdf1c30e6372a2abbd095f461b3d1271048e9e408cb8ea
+  data.tar.gz: b613ac4217fb65df2b934dc289b6d4167eb19d0f0605ab44914bb9996385467c
 SHA512:
-  metadata.gz: 5e11ad2f433fd264b679cd7f77ad77363f75d0c5f4245027ab4b39e85190f45bb78af8624a5621334833a73615846084c5478375f0d7dae4622319c6225ddf9e
-  data.tar.gz: 7fa46bd7592d9d85db5778db94d2130d7c70771aea9118f089dd05822646e9602515b1d1ede8080280be79cf168939fc594a1daf60cec04ff370c501c38829f0
+  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
 
@@ -55,12 +181,20 @@ ThecoreBackendCommons::SmtpConfig.setting(:from)
 
 ### Testare la configurazione SMTP
 
-Dall'applicazione Rails che include questo gem, eseguire:
+Il gem espone `ThecoreBackendCommons::SmtpTester` e un rake task, disponibili automaticamente in qualsiasi app che include questo gem.
+
+**Da rake task (shell):**
 
 ```bash
-bundle exec rails runner script/test_smtp.rb destinatario@example.com
+rails thecore_backend_commons:smtp:test[destinatario@example.com]
+```
+
+**Da Rails console:**
+
+```ruby
+ThecoreBackendCommons::SmtpTester.call("destinatario@example.com")
 ```
 
-Se non si passa un indirizzo, l'email viene inviata all'indirizzo configurato in `ThecoreSettings mytask.default_email`.
+Se non si passa un indirizzo, in entrambi i casi viene usato `ThecoreSettings mytask.default_email`.
 
-Lo script stampa i parametri SMTP effettivamente usati (inclusi `tls` e `enable_starttls_auto`) prima di tentare la consegna, e restituisce exit code `1` in caso di errore con il messaggio dell'eccezione.
+Lo tester stampa i parametri SMTP effettivamente usati (inclusi `tls` e `enable_starttls_auto`) prima di tentare la consegna. Restituisce `true`/`false` dal console e exit code `1` dal rake task in caso di errore.

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/tasks/thecore_backend_commons_tasks.rake

@@ -1,4 +1,11 @@
-# desc "Explaining what the task does"
-# task :thecore_backend_commons do
-#   # Task goes here
-# end
+namespace :thecore_backend_commons do
+  namespace :smtp do
+    desc "Send a test email using ThecoreSettings SMTP config. " \
+         "Usage: rails thecore_backend_commons:smtp:test[recipient@example.com] " \
+         "(omit argument to use mytask.default_email)"
+    task :test, [:recipient] => :environment do |_t, args|
+      success = ThecoreBackendCommons::SmtpTester.call(args[:recipient])
+      exit 1 unless success
+    end
+  end
+end

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/smtp_tester.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ThecoreBackendCommons
+  # Sends a test email using the SMTP settings from ThecoreSettings.
+  # Usable from the Rails console or via the rake task.
+  #
+  # From rails console:
+  #   ThecoreBackendCommons::SmtpTester.call("you@example.com")
+  #
+  # From the shell:
+  #   rails thecore_backend_commons:smtp:test[you@example.com]
+  class SmtpTester
+    def self.call(recipient = nil)
+      new(recipient).call
+    end
+
+    def initialize(recipient = nil)
+      @recipient = recipient.presence ||
+                   ThecoreSettings::Setting.find_by(ns: :mytask, key: :default_email)&.raw
+    end
+
+    def call
+      validate!
+      print_settings
+      send_mail
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "No recipient given and mytask.default_email is not configured." if @recipient.blank?
+      raise ArgumentError, "smtp.address is not configured in ThecoreSettings." if opts[:address].blank?
+    end
+
+    def print_settings
+      puts "SMTP settings:"
+      puts "  address:             #{opts[:address]}"
+      puts "  port:                #{opts[:port]}"
+      puts "  domain:              #{opts[:domain].inspect}"
+      puts "  user_name:           #{opts[:user_name].inspect}"
+      puts "  authentication:      #{opts[:authentication].inspect}"
+      puts "  tls:                 #{opts[:tls]}"
+      puts "  enable_starttls_auto:#{opts[:enable_starttls_auto]}"
+      puts "  from:                #{SmtpConfig.setting(:from).inspect}"
+      puts ""
+      puts "Sending test email to: #{@recipient}"
+    end
+
+    def send_mail
+      from_address = SmtpConfig.setting(:from).presence || "noreply@mytask.local"
+      delivery_opts = opts
+
+      mail = Mail.new do
+        from    from_address
+        to      delivery_opts[:address] # placeholder; overridden below
+        subject "[MyTask] SMTP test — #{Time.current.strftime('%Y-%m-%d %H:%M:%S %Z')}"
+        body    "This is an automated SMTP connectivity test sent from MyTask.\n\n" \
+                "If you received this message, the SMTP configuration is working correctly.\n\n" \
+                "Settings used:\n" \
+                "  address: #{delivery_opts[:address]}\n" \
+                "  port: #{delivery_opts[:port]}\n" \
+                "  tls: #{delivery_opts[:tls]}\n" \
+                "  auth: #{delivery_opts[:authentication].inspect}"
+      end
+      mail.to = @recipient
+      mail.delivery_method(:smtp, delivery_opts)
+      mail.deliver!
+      puts "OK: email delivered successfully."
+      true
+    rescue StandardError => e
+      puts "ERROR: #{e.class}: #{e.message}"
+      false
+    end
+
+    def opts
+      @opts ||= SmtpConfig.delivery_options
+    end
+  end
+end

data/lib/thecore_backend_commons/version.rb

@@ -1,3 +1,3 @@
 module ThecoreBackendCommons
-  VERSION = "3.2.10".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"
@@ -14,6 +15,8 @@ require "seed_dump"
 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.10
+  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,11 +220,15 @@ 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
 homepage: https://github.com/gabrieletassoni/thecore_backend_commons
 licenses: []