model_driven_api 3.6.4 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4757c81ca4ae3c4e59c12a96f5ddf23801121fc8ac3a7cde16ca3a8f2d47208
-  data.tar.gz: 2c342468dd9879aec91f2dd6bc49c5dba639dab0a8841583d6032377ef937e78
+  metadata.gz: ad2abbdb4e4fd783d5e4fadde50593be43e265aa857a0077655513b4e73f522e
+  data.tar.gz: 323ffab731877ae6c4f8adb6b75bb358e12319a7b2d55ccc77aadd5e6e52d41d
 SHA512:
-  metadata.gz: 0b36be5d13960e0166eaa31fc698745a1ba9d3d69ed4b49ca91540af7d112e7ce0bf39ff0cc87cb2e1c973b21add87a1e9ef9e18eaa3fc7adf81b82c268f745f
-  data.tar.gz: fe831b9b04fe80dfbd3db57e41d1b999035ab676f5d602904fa8e759af95504b9ff6d4d6ea91d947eef4dbe85a54afa62a1f9c30c17aa092191cbec960dc3ff0
+  metadata.gz: 17322346aef3972a55db2fce8703abfe9b2148076509c3a14aa465c0d34e4d5ec41294366496a77fc7dc44c5dd324fe9513f77961338591ae035ac5d03e8575d
+  data.tar.gz: f11a3a215784201aa30fb20b45b29a1df75ef8d1e8f045d2d15c6b8f45425487d40a9ba6315db679a827dabd2e54846ef78ee9950f5533861befb6342d59b150

data/README.md

@@ -528,6 +528,317 @@ fetch(`/api/v2/products/${id}`, { method: 'PATCH', body: formData });
 
 ---
 
+---
+
+## Web Push (VAPID) from a React client
+
+This section is the complete integration guide for React apps that want to receive browser push notifications from a Thecore backend. The server-side setup (models, service, ActionCable channel) is documented in the [`thecore_backend_commons` README](../thecore_backend_commons/README.md#web-push-notifications-vapid).
+
+### Prerequisites
+
+1. Run `rails db:seed` on the backend — this generates the VAPID key pair automatically.
+2. Set `vapid.contact_email` in RailsAdmin → Settings (e.g. `admin@yourapp.com`).
+3. Your site must be served over **HTTPS** (required by the Push API in all browsers). `localhost` is exempt for development.
+
+### Endpoint reference
+
+All endpoints live under `/api/v2/push_subscribers/custom_action/`.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET` | `vapid_public_key` | **No** | Returns the VAPID public key for `PushManager.subscribe` |
+| `POST` | `subscribe` | Yes (JWT) | Registers or updates a push subscription for the current user |
+| `POST` | `send_push` | Yes (JWT) | Creates a `PushMessage` and dispatches it to an active subscriber |
+| `POST` | `acknowledge` | Yes (JWT) | Marks a message as `received` and/or `read` |
+
+### Step 1 — Register a service worker
+
+Create `public/sw.js` in your React app:
+
+```javascript
+// public/sw.js
+
+self.addEventListener('push', event => {
+  const data = event.data?.json() ?? {};
+  event.waitUntil(
+    self.registration.showNotification(data.title ?? 'Notification', {
+      body: data.body,
+      icon: data.icon ?? '/favicon.ico',
+      data: { url: data.url },
+    })
+  );
+});
+
+self.addEventListener('notificationclick', event => {
+  event.notification.close();
+  const url = event.notification.data?.url;
+  if (url) {
+    event.waitUntil(clients.openWindow(url));
+  }
+});
+```
+
+### Step 2 — Subscribe to push notifications
+
+```javascript
+// src/usePushSubscription.js
+const API_BASE = process.env.REACT_APP_API_URL ?? '/api/v2';
+
+// Convert a base64url string to a Uint8Array (required by PushManager)
+function urlBase64ToUint8Array(base64String) {
+  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
+  const raw = atob(base64);
+  return Uint8Array.from([...raw].map(c => c.charCodeAt(0)));
+}
+
+// Convert a PushSubscription key to a base64url string (required by the backend)
+function keyToBase64(subscription, key) {
+  return btoa(String.fromCharCode(...new Uint8Array(subscription.getKey(key))));
+}
+
+export async function subscribeToPush(jwtToken) {
+  // 1. Register service worker
+  const registration = await navigator.serviceWorker.register('/sw.js');
+
+  // 2. Fetch the VAPID public key (no auth needed)
+  const res = await fetch(`${API_BASE}/push_subscribers/custom_action/vapid_public_key`);
+  const { vapid_public_key } = await res.json();
+
+  // 3. Subscribe via the Push API
+  const subscription = await registration.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: urlBase64ToUint8Array(vapid_public_key),
+  });
+
+  // 4. Register the subscription with the backend
+  const registerRes = await fetch(
+    `${API_BASE}/push_subscribers/custom_action/subscribe`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${jwtToken}`,
+      },
+      body: JSON.stringify({
+        endpoint: subscription.endpoint,
+        p256dh: keyToBase64(subscription, 'p256dh'),
+        auth:   keyToBase64(subscription, 'auth'),
+        user_agent: navigator.userAgent,
+      }),
+    }
+  );
+
+  const subscriber = await registerRes.json();
+  // subscriber.id is the push_subscriber_id to use with ActionCable and send_push
+  return subscriber;
+}
+```
+
+Call this after the user logs in (a JWT is required for `subscribe`):
+
+```javascript
+import { subscribeToPush } from './usePushSubscription';
+
+const subscriber = await subscribeToPush(jwtToken);
+localStorage.setItem('push_subscriber_id', subscriber.id);
+```
+
+### Step 3 — Listen via ActionCable
+
+Install the ActionCable client if you haven't already:
+
+```bash
+npm install @rails/actioncable
+# or
+yarn add @rails/actioncable
+```
+
+```javascript
+// src/usePushChannel.js
+import { createConsumer } from '@rails/actioncable';
+
+const WS_URL = process.env.REACT_APP_WS_URL ?? 'ws://localhost:3000/cable';
+
+export function connectPushChannel(jwtToken, subscriberId, onMessage) {
+  // The JWT token is passed as a query parameter so the ActionCable
+  // connection.rb can authenticate the WebSocket handshake.
+  const consumer = createConsumer(`${WS_URL}?token=${jwtToken}`);
+
+  const subscription = consumer.subscriptions.create(
+    { channel: 'PushNotificationChannel', subscriber_id: subscriberId },
+    {
+      received(data) {
+        // data is a PushMessage serialised as JSON:
+        // { id, title, body, url, icon, sent_at, received_at, read_at }
+        onMessage(data);
+      },
+      connected() {
+        console.log('[PushNotificationChannel] connected');
+      },
+      disconnected() {
+        console.log('[PushNotificationChannel] disconnected');
+      },
+    }
+  );
+
+  // Return a cleanup function
+  return () => {
+    subscription.unsubscribe();
+    consumer.disconnect();
+  };
+}
+```
+
+Use it in a React component or hook:
+
+```javascript
+import { useEffect } from 'react';
+import { connectPushChannel } from './usePushChannel';
+
+function App() {
+  const jwtToken = localStorage.getItem('token');
+  const subscriberId = localStorage.getItem('push_subscriber_id');
+
+  useEffect(() => {
+    if (!jwtToken || !subscriberId) return;
+
+    const disconnect = connectPushChannel(jwtToken, subscriberId, message => {
+      console.log('New push message via ActionCable:', message);
+      // Optionally acknowledge receipt immediately
+      acknowledgeMessage(jwtToken, message.id, { received: true });
+    });
+
+    return disconnect; // cleanup on unmount
+  }, [jwtToken, subscriberId]);
+}
+```
+
+> **Tip:** use `user_id` instead of `subscriber_id` if you want to receive messages across all active subscriptions for the current user (e.g. multiple tabs):
+> ```javascript
+> { channel: 'PushNotificationChannel', user_id: currentUserId }
+> ```
+
+### Step 4 — Acknowledge receipt and read
+
+```javascript
+// src/pushApi.js
+const API_BASE = process.env.REACT_APP_API_URL ?? '/api/v2';
+
+export async function acknowledgeMessage(jwtToken, messageId, { received = false, read = false } = {}) {
+  const res = await fetch(
+    `${API_BASE}/push_subscribers/custom_action/acknowledge`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${jwtToken}`,
+      },
+      body: JSON.stringify({
+        push_message_id: messageId,
+        received,
+        read,
+      }),
+    }
+  );
+  return res.json();
+  // Response: { id, title, body, url, icon, sent_at, received_at, read_at, ... }
+}
+```
+
+Call `received: true` as soon as the message arrives via ActionCable. Call `read: true` when the user opens or dismisses it. Fields are set only once — a second call with the same flag is a no-op (idempotent).
+
+### Step 5 — Send a push from the backend (optional)
+
+Normally the backend triggers pushes from jobs or model callbacks. If you need to trigger a push from a privileged frontend (e.g. an admin panel), use `send_push`:
+
+```javascript
+export async function sendPush(jwtToken, { subscriberId, title, body, url, icon }) {
+  const res = await fetch(
+    `${API_BASE}/push_subscribers/custom_action/send_push`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${jwtToken}`,
+      },
+      body: JSON.stringify({
+        push_subscriber_id: subscriberId,
+        title,
+        body,
+        url,   // optional
+        icon,  // optional
+      }),
+    }
+  );
+  if (!res.ok) {
+    const err = await res.json();
+    throw new Error(err.error ?? `HTTP ${res.status}`);
+  }
+  return res.json(); // PushMessage record
+}
+```
+
+### Full flow summary
+
+```
+React app                         Thecore backend
+    │                                   │
+    │── GET vapid_public_key ──────────►│  (no auth)
+    │◄── { vapid_public_key: "..." } ───│
+    │                                   │
+    │  navigator.serviceWorker.register('/sw.js')
+    │  registration.pushManager.subscribe({ applicationServerKey })
+    │                                   │
+    │── POST subscribe ────────────────►│  creates/updates PushSubscriber
+    │◄── { id: 42, endpoint, ... } ─────│
+    │                                   │
+    │  createConsumer(wsUrl?token=jwt)  │
+    │── WS upgrade ────────────────────►│  PushNotificationChannel#subscribed
+    │◄── stream: push_notifications_subscriber_42
+    │                                   │
+    │  [backend dispatches push]        │
+    │◄── Web Push payload (sw.js) ──────│  Webpush.payload_send via VAPID
+    │  showNotification(title, body)    │
+    │                                   │
+    │◄── ActionCable data ──────────────│  PushNotificationChannel.broadcast_to
+    │  onMessage(data)                  │
+    │                                   │
+    │── POST acknowledge (received) ───►│  message.received_at = now
+    │── POST acknowledge (read) ────────►│  message.read_at = now
+```
+
+### Handling subscription expiry
+
+Push service endpoints expire (the push provider returns HTTP 410). The backend automatically calls `subscriber.expire!` when this happens, but the client needs to re-subscribe on the next boot:
+
+```javascript
+export async function ensureSubscription(jwtToken) {
+  // Re-subscribe unconditionally — subscribe_for upserts on endpoint,
+  // so re-registering the same browser is always safe and clears expired_at.
+  const sub = await subscribeToPush(jwtToken);
+  localStorage.setItem('push_subscriber_id', sub.id);
+  return sub;
+}
+```
+
+### Permissions check
+
+Before calling `subscribeToPush`, check that the browser supports push and the user has granted permission:
+
+```javascript
+export async function requestPushPermission() {
+  if (!('serviceWorker' in navigator) || !('PushManager' in window)) {
+    console.warn('Web Push not supported in this browser');
+    return false;
+  }
+  const permission = await Notification.requestPermission();
+  return permission === 'granted';
+}
+```
+
+---
+
 ## License
 
 MIT

data/app/controllers/api/v2/application_controller.rb

@@ -13,7 +13,7 @@ class Api::V2::ApplicationController < ActionController::API
 
   # GET :controller/
   def index
-    authorize! :index, @model
+    authorize! :index, @model unless public_custom_action?
 
     # Custom Action
     status, result, status_number = check_for_custom_action
@@ -67,7 +67,7 @@ class Api::V2::ApplicationController < ActionController::API
   def create
     # Normal Create Action
     Rails.logger.debug("Creating a new record #{@record}")
-    authorize! :create, @record.presence || @model
+    authorize! :create, @record.presence || @model unless public_custom_action?
     # Custom Action
     status, result, status_number = check_for_custom_action
     return render json: result, status: (status_number.presence || 200) if status == true
@@ -127,6 +127,19 @@ class Api::V2::ApplicationController < ActionController::API
 
   private
 
+  # Returns true if the current request is for a NonCrudEndpoints custom action
+  # that has been declared as public (no authentication required).
+  # Forces autoloading of the Endpoints::<Model> class so the public_action_registry
+  # is populated before authenticate_request checks it.
+  def public_custom_action?
+    return false unless request.url.include?("/custom_action/")
+    model_name = params[:ctrl].to_s.classify
+    action_name = params[:action_name].to_s
+    # Ensure the endpoint class is loaded so its public_action declarations are registered.
+    ("Endpoints::#{model_name}".constantize rescue nil)
+    NonCrudEndpoints.public_action?(model_name, action_name)
+  end
+
   ## CUSTOM ACTION
   # [GET|PUT|POST|DELETE] :controller?do=:custom_action
   # or
@@ -159,6 +172,9 @@ class Api::V2::ApplicationController < ActionController::API
   end
 
   def authenticate_request
+    # Skip auth for public NonCrudEndpoints actions (e.g. vapid_public_key).
+    return if public_custom_action?
+
     @current_user = nil
     Settings.ns(:security).allowed_authorization_headers.split(",").each do |header|
       # puts "Found header #{header}: #{request.headers[header]}"

data/app/controllers/api/v3/application_controller.rb

@@ -2,7 +2,7 @@ class Api::V3::ApplicationController < Api::V2::ApplicationController
   include Pagy::Backend
 
   def index
-    authorize! :index, @model
+    authorize! :index, @model unless public_custom_action?
 
     status, result, status_number = check_for_custom_action
     return render json: result, status: (status_number.presence || 200) if status == true

data/app/models/endpoints/push_subscriber.rb

@@ -0,0 +1,110 @@
+class Endpoints::PushSubscriber < NonCrudEndpoints
+  # vapid_public_key is public — no authentication required.
+  public_action :vapid_public_key
+
+  self.desc 'PushSubscriber', :vapid_public_key, {
+    get: {
+      summary: 'Returns the VAPID public key for browser push subscription',
+      parameters: [],
+      responses: {
+        '200' => {
+          description: 'VAPID public key',
+          content: {
+            'application/json' => {
+              schema: {
+                type: 'object',
+                properties: {
+                  vapid_public_key: { type: 'string' }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  def vapid_public_key(params)
+    key = ThecoreSettings::Setting.where(ns: :vapid, key: :public_key).pluck(:raw).first
+    [{ vapid_public_key: key }, 200]
+  end
+
+  self.desc 'PushSubscriber', :subscribe, {
+    post: {
+      summary: 'Register or update a push subscription for the current user',
+      parameters: [],
+      responses: {
+        '200' => { description: 'Updated subscriber' },
+        '201' => { description: 'Created subscriber' }
+      }
+    }
+  }
+
+  def subscribe(params)
+    user = User.find(params[:current_user_id])
+    subscriber = PushSubscriber.subscribe_for(
+      user,
+      endpoint: params[:endpoint],
+      p256dh: params[:p256dh],
+      auth: params[:auth],
+      user_agent: params[:user_agent]
+    )
+    status = subscriber.previously_new_record? ? 201 : 200
+    [subscriber, status]
+  rescue ActiveRecord::RecordInvalid => e
+    [{ error: e.message }, 422]
+  end
+
+  self.desc 'PushSubscriber', :send_push, {
+    post: {
+      summary: 'Send a Web Push notification to a specific subscriber',
+      parameters: [],
+      responses: {
+        '201' => { description: 'Message created and dispatched' },
+        '422' => { description: 'Validation error' },
+        '404' => { description: 'Subscriber not found' }
+      }
+    }
+  }
+
+  def send_push(params)
+    subscriber = PushSubscriber.active.find_by(id: params[:push_subscriber_id])
+    return [{ error: 'Subscriber not found' }, 404] unless subscriber
+    message = subscriber.push_messages.build(
+      title: params[:title],
+      body: params[:body],
+      url: params[:url],
+      icon: params[:icon]
+    )
+    unless message.save
+      return [{ error: message.errors.full_messages.join(', ') }, 422]
+    end
+    ThecoreBackendCommons::PushNotificationService.dispatch(subscriber, message)
+    [message, 201]
+  rescue => e
+    [{ error: e.message }, 500]
+  end
+
+  self.desc 'PushSubscriber', :acknowledge, {
+    post: {
+      summary: 'Mark a push message as received or read',
+      parameters: [],
+      responses: {
+        '200' => { description: 'Message updated' },
+        '404' => { description: 'Message not found' }
+      }
+    }
+  }
+
+  def acknowledge(params)
+    message = PushMessage.find_by(id: params[:push_message_id])
+    return [{ error: 'Message not found' }, 404] unless message
+
+    now = Time.current
+    message.update!(received_at: now) if params[:received] && message.received_at.nil?
+    message.update!(read_at: now) if params[:read] && message.read_at.nil?
+    [message, 200]
+  rescue ActiveRecord::RecordInvalid => e
+    [{ error: e.message }, 422]
+  end
+end

data/lib/concerns/api_exception_management.rb

@@ -44,7 +44,10 @@ module ApiExceptionManagement
         
         def api_error(status: 501, errors: [])
             # puts errors.full_messages if !Rails.env.production? && errors.respond_to?(:full_messages)
-            head status && return if errors.blank?
+            if errors.blank?
+              head status
+              return
+            end
             
             # For retrocompatibility, I try to send back only strings, as errors
             errors_response = if errors.respond_to?(:full_messages) 

data/lib/model_driven_api/version.rb

@@ -1,3 +1,3 @@
 module ModelDrivenApi
-  VERSION = "3.6.4".freeze
+  VERSION = "3.7.1".freeze
 end

data/lib/non_crud_endpoints.rb

@@ -2,6 +2,24 @@ class NonCrudEndpoints
     attr_accessor :result
     cattr_accessor :definitions
     self.definitions = {}
+
+    # Registry of actions that do not require authentication.
+    # Populated by subclasses via `self.public_action :action_name`.
+    # Used by CustomActionDispatcher and ApplicationController to skip
+    # authenticate_request for these endpoints.
+    cattr_accessor :public_action_registry
+    self.public_action_registry = {}
+
+    def self.public_action(action_name)
+        self.public_action_registry[name] ||= []
+        self.public_action_registry[name] << action_name.to_sym
+    end
+
+    def self.public_action?(model_name, action_name)
+        registry = public_action_registry["Endpoints::#{model_name}"] || []
+        registry.include?(action_name.to_sym)
+    end
+
     # Add a validation method which will be inherited by all the instances, and automatically run before any method call
     def initialize(m, params)
         # Rails.logger.debug "Initializing NonCrudEndpoints"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: model_driven_api
 version: !ruby/object:Gem::Version
-  version: 3.6.4
+  version: 3.7.1
 platform: ruby
 authors:
 - Gabriele Tassoni
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: simple_command
   requirement: !ruby/object:Gem::Requirement
@@ -188,6 +188,7 @@ files:
 - app/controllers/api/v3/info_controller.rb
 - app/controllers/api/v3/raw_controller.rb
 - app/controllers/api/v3/users_controller.rb
+- app/models/endpoints/push_subscriber.rb
 - app/models/endpoints/test_api.rb
 - app/models/test_api.rb
 - app/models/used_token.rb