[Notifications] notification storage and service (#3580209) · Issues · project / canvas

[Notifications] notification storage and service

>>> [!note] Migrated issue   Reported by: [justafish](https://www.drupal.org/user/161058) Related to !762 >>> Build the core notifications storage layer for Canvas. Create the <code>NotificationService</code> PHP class in the Canvas module that provides the core storage and retrieval layer for notifications. This service uses two custom database tables (<code>canvas_notifications</code> and <code>canvas_notification_reads</code>) with indexed columns for efficient queries. Run this on top of <a href="https://git.drupalcode.org/issue/canvas-3573776/-/tree/3573776-canvas-needs-a">https://git.drupalcode.org/issue/canvas-3573776/-/tree/3573776-canvas-needs-a</a> <h2>Notes</h2> A notification can have the following types: <code>processing</code>, <code>success</code>, <code>info</code>, <code>warning</code>, <code>error</code>. <h2>Acceptance criteria</h2> <ul> <li><code>NotificationService</code> is registered in <code>canvas.services.yml</code> with autowire.</li> <li><code>hook_schema()</code> defines the <code>canvas_notifications</code> and <code>canvas_notification_reads</code> tables.</li> <li><code>canvas_notifications</code> table stores notification payloads with indexed <code>type</code> and <code>timestamp</code> columns for efficient queries.</li> <li><code>canvas_notification_reads</code> table stores per-user read state keyed by <code>uid</code> and <code>notification_id</code>.</li> <li><code>create()</code> always auto-generates a UUID for the <code>id</code> field. Callers do not provide an id.</li> <li><code>create()</code> auto-generates a millisecond timestamp when not provided.</li> <li><code>create()</code> accepts an optional <code>key</code> field on all notification types.</li> <li>When <code>create()</code> is called with a <code>key</code>, all existing notifications with the same key are deleted before storing the new one (regardless of type). This handles state transitions (e.g. <code>processing</code> → <code>success</code>) and retry flows (e.g. <code>error</code>/<code>warning</code> → <code>processing</code>) in a single rule.</li> <li><code>getRecent($uid, $limit = 25)</code> returns the <code>$limit</code> most recent non-processing notifications plus all active processing notifications.</li> <li><code>getRecent()</code> includes a <code>hasRead</code> boolean on each notification resolved via a <code>LEFT JOIN</code> to the reads table for the given <code>$uid</code>.</li> <li><code>getRecent()</code> sorts results with processing notifications first, then by timestamp descending.</li> <li><code>markRead($uid, $notificationIds)</code> inserts entries in the reads table for each notification ID (using MERGE/upsert to be idempotent).</li> <li>All public methods have PHPDoc.</li> <li>Kernel tests cover all public methods and edge cases.</li> </ul> <h2>Implementation plan</h2> <h3>Database schema</h3> Add <code>hook_schema()</code> in <code>canvas.install</code> (or a dedicated Hook class): <pre><pre>function canvas_schema(): array {   $schema['canvas_notifications'] = [     'description' => 'Stores Canvas notification payloads.',     'fields' => [       'notification_id' => [         'type' => 'varchar_ascii',         'length' => 128,         'not null' => TRUE,         'description' => 'Notification UUID.',       ],       'type' => [         'type' => 'varchar_ascii',         'length' => 32,         'not null' => TRUE,         'description' => 'Notification type: processing, success, info, warning, error.',       ],       'key' => [         'type' => 'varchar_ascii',         'length' => 255,         'not null' => FALSE,         'default' => NULL,         'description' => 'Optional grouping key for related notifications.',       ],       'title' => [         'type' => 'varchar',         'length' => 255,         'not null' => TRUE,         'description' => 'Notification title.',       ],       'message' => [         'type' => 'text',         'size' => 'normal',         'not null' => TRUE,         'description' => 'Notification body text.',       ],       'timestamp' => [         'type' => 'int',         'size' => 'big',         'not null' => TRUE,         'description' => 'Unix timestamp in milliseconds.',       ],       'actions' => [         'type' => 'text',         'size' => 'normal',         'not null' => FALSE,         'default' => NULL,         'description' => 'JSON-encoded array of action objects.',       ],     ],     'primary key' => ['id'],     'indexes' => [       'idx_type_timestamp' => ['type', 'timestamp'],       'idx_timestamp' => ['timestamp'],     ],   ];   $schema['canvas_notification_reads'] = [     'description' => 'Tracks which notifications each user has read.',     'fields' => [       'uid' => [         'type' => 'int',         'unsigned' => TRUE,         'not null' => TRUE,         'description' => 'User ID.',       ],       'notification_id' => [         'type' => 'varchar_ascii',         'length' => 128,         'not null' => TRUE,         'description' => 'Notification UUID.',       ],       'timestamp' => [         'type' => 'int',         'size' => 'big',         'not null' => TRUE,         'description' => 'When the notification was marked as read (ms).',       ],     ],     'primary key' => ['uid', 'notification_id'],     'indexes' => [       'idx_timestamp' => ['timestamp'],     ],   ];   return $schema; }</pre></pre>A <code>hook_update_N()</code> will also be needed to create these tables on existing installations. <h3>Service class</h3> Create <code>src/Notification/NotificationService.php</code>: <pre><pre>&lt;?php declare(strict_types=1); namespace Drupal\canvas\Notification; use Drupal\Component\Serialization\Json; use Drupal\Component\Uuid\UuidInterface; use Drupal\Core\Database\Connection; final class NotificationService {   private const TABLE_NOTIFICATIONS = 'canvas_notifications';   private const TABLE_READS = 'canvas_notification_reads';   private const RETENTION_MS = 2592000000; // 30 days in milliseconds.   private const PROCESSING_TIMEOUT_MS = 1800000; // 30 minutes in milliseconds.   public function __construct(     private readonly Connection $database,     private readonly UuidInterface $uuid,   ) {}   public function create(array $notification): void { ... }   public function getRecent(int $uid, int $limit = 25): array { ... }   public function markRead(int $uid, array $notificationIds): void { ... } }</pre></pre><h3>Service registration</h3> Add to <code>canvas.services.yml</code>: <pre>Drupal\canvas\Notification\NotificationService: {}</pre>Autowire handles the <code>Connection</code> and <code>UuidInterface</code> constructor arguments. <h3>Key behaviours</h3> <h4><code>create()</code> logic</h4> <ul> <li>Always auto-generate <code>id</code> (UUID). Callers must not pass <code>id</code>.</li> <li>Auto-generate <code>timestamp</code> (<code>(int) (microtime(true) * 1000)</code>) if not set.</li> <li>Validate required fields: <code>type</code>, <code>title</code>, <code>message</code>.</li> <li>If <code>key</code> is set: delete all existing notifications of type <code>error</code>, <code>warning</code>, or <code>processing</code> with the same key.</li> <li>Insert into <code>canvas_notifications</code>. The <code>actions</code> field is JSON-encoded.</li> </ul> <h4><code>getRecent()</code> logic</h4> Uses a single efficient query with <code>LEFT JOIN</code> for read state: <pre><pre>(SELECT n.*, IF(r.uid IS NOT NULL, 1, 0) AS has_read FROM canvas_notifications n LEFT JOIN canvas_notification_reads r    ON r.notification_id = n.id AND r.uid = :uid WHERE n.type = 'processing' ORDER BY n.timestamp DESC) UNION ALL (SELECT n.*, IF(r.uid IS NOT NULL, 1, 0) AS has_read FROM canvas_notifications n LEFT JOIN canvas_notification_reads r    ON r.notification_id = n.id AND r.uid = :uid WHERE n.type != 'processing' ORDER BY n.timestamp DESC LIMIT :limit)</pre></pre>Processing notifications are always returned (no limit). Non-processing are limited to <code>$limit</code>. The <code>idx_type_timestamp</code> index covers both queries. The <code>actions</code> field is JSON-decoded before returning. <h4><code>markRead()</code> logic</h4> Uses a MERGE (upsert) to be idempotent: <pre><pre>INSERT INTO canvas_notification_reads (uid, notification_id, timestamp) VALUES (:uid, :id, :now) ON DUPLICATE KEY UPDATE timestamp = :now</pre></pre><h2>Tests required</h2> Kernel test: <code>tests/src/Kernel/Notification/NotificationServiceTest.php</code> Follow existing Canvas kernel test patterns (extends <code>KernelTestBase</code>, uses <code>#[CoversClass]</code>, <code>#[Group('canvas')]</code>). The test must install the schema via <code>$this->installSchema('canvas', ['canvas_notifications', 'canvas_notification_reads'])</code>. <table> <thead> <tr> <th>Test method</th> <th>Validates</th> </tr> </thead> <tbody> <tr> <td><code>testCreateStoresNotification</code></td> <td>Row exists in <code>canvas_notifications</code> after <code>create</code></td> </tr> <tr> <td><code>testCreateAlwaysGeneratesUuid</code></td> <td><code>id</code> is always a new UUID, never caller-provided. If a caller attempts to provide it, should throw an error.</td> </tr> <tr> <td><code>testCreateAutoGeneratesTimestamp</code></td> <td>Missing timestamp is auto-filled</td> </tr> <tr> <td><code>testCreateValidatesRequiredFields</code></td> <td>Exception on missing <code>type</code>/<code>title</code>/<code>message</code></td> </tr> <tr> <td><code>testCreateErrorWithKeyDeletesAcrossTypes</code></td> <td>Creating <code>error</code> with key deletes existing <code>processing</code>/<code>error</code>/<code>warning</code> with same key</td> </tr> <tr> <td><code>testCreateWarningWithKeyDeletesAcrossTypes</code></td> <td>Creating <code>warning</code> with key deletes existing <code>processing</code>/<code>error</code>/<code>warning</code> with same key</td> </tr> <tr> <td><code>testCreateProcessingWithKeyDeletesAcrossTypes</code></td> <td>Creating <code>processing</code> with key deletes existing <code>processing</code>/<code>error</code>/<code>warning</code> with same key</td> </tr> <tr> <td><code>testCreateSuccessWithKeyDoesNotDeleteAcrossTypes</code></td> <td>Creating <code>success</code> with key does not delete any existing notifications with same key</td> </tr> <tr> <td><code>testCreateInfoWithKeyDoesNotDeleteAcrossTypes</code></td> <td>Creating <code>info</code> with key does not delete any existing notifications with same key</td> </tr> <tr> <td><code>testCreateStoresActionsAsJson</code></td> <td>Actions array is JSON-encoded in DB, decoded on read</td> </tr> <tr> <td><code>testGetRecentReturnsLimitedResults</code></td> <td>Only returns <code>$limit</code> non-processing notifications</td> </tr> <tr> <td><code>testGetRecentAlwaysIncludesProcessing</code></td> <td>Processing notifications are included beyond limit</td> </tr> <tr> <td><code>testGetRecentSortsCorrectly</code></td> <td>Processing first, then newest first</td> </tr> <tr> <td><code>testGetRecentIncludesHasReadState</code></td> <td><code>hasRead</code> is true/false based on reads table</td> </tr> <tr> <td><code>testGetRecentHasReadIsPerUser</code></td> <td>Different users see different <code>hasRead</code> values</td> </tr> <tr> <td><code>testMarkReadCreatesReadEntries</code></td> <td>Rows exist in <code>canvas_notification_reads</code></td> </tr> <tr> <td><code>testMarkReadIdempotent</code></td> <td>Calling <code>markRead</code> twice does not error (upsert)</td> </tr> </tbody> </table> <h2>Manual testing steps</h2> <ol> <li>Enable <code>canvas_dev_mode</code> module.</li> <li> Verify the tables exist: <pre>ddev drush sqlq "SHOW TABLES LIKE 'canvas_notif%';"</pre>Expected output: <code>canvas_notifications</code> and <code>canvas_notification_reads</code>. </li> <li> Create a notification via Drush: <pre><pre>ddev drush php:eval "   \Drupal::service('Drupal\canvas\Notification\NotificationService')->create([     'type' => 'info',     'title' => 'Test notification',     'message' => 'Hello world',   ]); "</pre></pre></li> <li> Verify the row exists: <pre>ddev drush sqlq "SELECT * FROM canvas_notifications;"</pre></li> <li>Create a <code>processing</code> notification, then create a <code>success</code> notification with the same key. Verify the processing row was replaced by the success row. Expected: only the success notification with that key remains.</li> <li>Create an <code>error</code> notification with a key, then create a <code>processing</code> notification with the same key (simulating a retry). Verify the error row was replaced by the processing row. Expected: only the processing notification with that key remains.</li> <li>Repeat steps 1–7 starting from an old version of Canvas and running the database update procedure.</li> </ol> > Related issue: [Issue #3573776](https://www.drupal.org/node/3573776)

issue