@tokamakdev/plugin-notifications 0.1.0-beta.50 → 0.1.0-beta.51

package/README.md

@@ -119,36 +119,66 @@ Every field is optional.
 
 ### Data-only messages
 
-A message without a title or body runs the Worker's `push` handler in native
-builds, whether the app is in the foreground, in the background, or started by
-the message:
+In native builds, the plugin posts a message without a title or body to the
+Worker's `/tokamak/push` endpoint, whether the app is in the foreground, in the
+background, or started by the message. `handlePushRequest` serves the endpoint.
+Route `POST /tokamak/push` to it, in a plain Worker:
+
+```ts
+import { handlePushRequest } from "@tokamakdev/plugin-notifications/worker";
 
-```js
 export default {
   async fetch(request, env, ctx) {
+    if (new URL(request.url).pathname === "/tokamak/push") {
+      return handlePushRequest<{ itemId: string }>(request, async (message) => {
+        const item = await fetch(`https://api.example.com/items/${message.data.itemId}`);
+        // Return a notification to show it, or return nothing.
+        return { id: `item-${message.data.itemId}`, title: "New item", body: (await item.json()).summary };
+      });
+    }
     // ...
   },
-
-  async push(message, env, ctx) {
-    const item = await fetch(`https://api.example.com/items/${message.data.id}`);
-    // Return a notification to show it, or return nothing.
-    return { id: `item-${message.data.id}`, title: "New item", body: (await item.json()).summary };
-  },
 };
 ```
 
-`message` is the `Message`; `env` and `ctx` are the Worker's usual arguments.
-A returned notification is shown as `show` shows one. The page also receives
-the message through `onMessage` while it is loaded. Cloudflare never calls
-`push`, and `tok dev` does not run it.
+or in a framework's server route, such as `src/pages/tokamak/push.ts` in Astro:
+
+```ts
+import type { APIRoute } from "astro";
+import { handlePushRequest } from "@tokamakdev/plugin-notifications/worker";
+
+export const POST: APIRoute = ({ request }) =>
+  handlePushRequest<{ itemId: string }>(request, (message) => {
+    // ...
+  });
+```
+
+`message` is the `Message`, with `data` of the type argument's type, which is
+not checked; FCM delivers every `data` value as a string. A returned
+notification is shown as `show` shows one. The page also receives the message
+through `onMessage` while it is loaded.
+
+`handlePushRequest` accepts requests in a tokamak app, where
+`process.env.TOKAMAK_RUNTIME` is `"true"`, and in development, where
+`process.env.NODE_ENV` is `development`, as in the development server `tok dev`
+delivers messages to. It responds 404 otherwise, so the endpoint serves nothing
+on Cloudflare. A build made with `NODE_ENV=development`, or a Worker that
+declares `TOKAMAK_RUNTIME` itself, accepts every request.
+
+Each attempt waits up to 2 seconds for a 200 response. After a failure, the
+plugin tries again 1 second later, up to three attempts, while an attempt can
+finish within the plugin's time for the message. A handler can run more than
+once for one message, and an attempt that timed out keeps running. The plugin
+logs each failed attempt to the device log as
+`push notification failed: <reason>`.
 
 The platforms limit background delivery:
 
 | Platform | The server sends | Limits |
 |---|---|---|
-| iOS | `content-available: 1` with `apns-push-type: background` and `apns-priority: 5` | The system throttles delivery and may drop messages, and delivers nothing after the user force-quits the app until they open it. The plugin stops the handler after 25 seconds, within the system's 30. |
+| iOS | `content-available: 1` with `apns-push-type: background` and `apns-priority: 5` | The system throttles delivery and may drop messages, and delivers nothing after the user force-quits the app until they open it. The plugin's time for a message is 25 seconds, within the system's 30. |
 | macOS | As iOS | Delivered while the app is running. |
-| Android | A `data` message with `priority: high` | Nothing is delivered after the app is force-stopped. The plugin stops the handler after 8 seconds, within FCM's 10, which include starting the app. |
+| Android | A `data` message with `priority: high` | Nothing is delivered after the app is force-stopped. The plugin's time for a message is 8 seconds, within FCM's 10, which include starting the app. |
 
 The web does not support data-only messages: browsers require every push
 message to show a notification.

package/android/NotificationsPlugin.kt

@@ -5,6 +5,7 @@ import android.content.Context
 import android.content.Intent
 import android.content.pm.PackageManager
 import android.os.Build
+import android.os.SystemClock
 import android.util.Log
 import com.google.firebase.FirebaseApp
 import com.google.firebase.messaging.FirebaseMessaging
@@ -24,7 +25,10 @@ private const val SHOW_IN_FOREGROUND = "show-in-foreground"
 private const val PERMISSION_REQUEST = 0x4E07
 
 /** FCM allows about 10 seconds for a message, including starting the app. */
-private const val PUSH_TIMEOUT_MILLIS = 8_000L
+private const val PUSH_DEADLINE_MILLIS = 8_000L
+private const val PUSH_ATTEMPTS = 3
+private const val PUSH_ATTEMPT_TIMEOUT_MILLIS = 2_000L
+private const val PUSH_RETRY_DELAY_MILLIS = 1_000L
 private const val FCM_MESSAGE_ID_EXTRA = "google.message_id"
 private val LISTENERS = setOf("onMessage", "onNotificationOpened", "onSubscriptionChange")
 
@@ -112,8 +116,8 @@ class TokamakNotificationsPlugin(
     }
 
     /**
-     * Delivers an FCM message to the page. Runs the Worker's `push` handler for a data-only
-     * message and shows the notification it returns. FCM calls this off the main thread.
+     * Delivers an FCM message to the page. Posts a data-only message to the Worker's push
+     * endpoint and shows the notification it returns. FCM calls this off the main thread.
      */
     internal fun onMessageReceived(message: JSONObject, visible: Boolean) {
         context.mainExecutor.execute { emit("onMessage", message) }
@@ -121,15 +125,38 @@ class TokamakNotificationsPlugin(
             if (preferences.getBoolean(SHOW_IN_FOREGROUND, false)) notifier.post(content(message), "push")
             return
         }
-        runCatching { host.dispatch("push", message.toString(), PUSH_TIMEOUT_MILLIS) }
-            .onSuccess { result -> result?.let(::showReturned) }
-            .onFailure { Log.w("tokamak", "the Worker's push handler failed", it) }
+        val deadline = SystemClock.elapsedRealtime() + PUSH_DEADLINE_MILLIS
+        runCatching { deliverPush(message.toString(), attempt = 1, deadline = deadline) }
+            .onSuccess(::showReturned)
     }
 
-    private fun showReturned(result: String) {
-        val returned = JSONTokener(result).nextValue() as? JSONObject ?: return
-        runCatching { notifier.post(Content.parse(returned, scheduled = false), "local") }
-            .onFailure { Log.w("tokamak", "the Worker's push handler returned an invalid notification", it) }
+    /**
+     * Posts [body] to `/tokamak/push`, logging each failed attempt and retrying while another
+     * attempt can finish before [deadline].
+     */
+    private fun deliverPush(
+        body: String,
+        attempt: Int,
+        deadline: Long,
+    ): String =
+        try {
+            host.call("push", body, PUSH_ATTEMPT_TIMEOUT_MILLIS)
+        } catch (error: Exception) {
+            Log.w("tokamak", "push notification failed: ${error.message}")
+            val retryEnds = SystemClock.elapsedRealtime() + PUSH_RETRY_DELAY_MILLIS + PUSH_ATTEMPT_TIMEOUT_MILLIS
+            if (attempt == PUSH_ATTEMPTS || retryEnds > deadline) throw error
+            Thread.sleep(PUSH_RETRY_DELAY_MILLIS)
+            deliverPush(body, attempt + 1, deadline)
+        }
+
+    /** Shows the notification a push response returns, if any. */
+    private fun showReturned(response: String) {
+        if (response.isEmpty()) return
+        runCatching {
+            val returned = JSONTokener(response).nextValue()
+            if (returned == JSONObject.NULL) return
+            notifier.post(Content.parse(returned as JSONObject, scheduled = false), "local")
+        }.onFailure { Log.w("tokamak", "the push response is not a notification", it) }
     }
 
     private fun emit(method: String, value: JSONObject) {

package/apple/NotificationsPlugin.swift

@@ -12,7 +12,10 @@ private let showInForegroundKey = "tokamak.notifications.show-in-foreground"
 /// The system keeps only the soonest 64 pending requests.
 private let pendingLimit = 64
 /// The system allows about 30 seconds for a background remote notification.
-private let pushTimeout: TimeInterval = 25
+private let pushDeadline: TimeInterval = 25
+private let pushAttempts = 3
+private let pushAttemptTimeout: TimeInterval = 2
+private let pushRetryDelay: TimeInterval = 1
 private let shown: UNNotificationPresentationOptions = [.banner, .list, .sound]
 
 #if os(iOS)
@@ -138,7 +141,7 @@ final class TokamakNotificationsPlugin: NSObject, TokamakPlugin,
     }
   }
 
-  /// Runs the Worker's `push` handler for a data-only message, showing the
+  /// Posts a data-only message to the Worker's push endpoint, showing the
   /// notification it returns.
   func didReceiveRemoteNotification(
     _ userInfo: [AnyHashable: Any],
@@ -150,19 +153,39 @@ final class TokamakNotificationsPlugin: NSObject, TokamakPlugin,
       return
     }
     emit("onMessage", fields.message)
-    host.dispatch(event: "push", payload: fields.message, timeout: pushTimeout) { result in
+    deliverPush(fields.message, attempt: 1, deadline: Date() + pushDeadline) { result in
       switch result {
-      case .success(.handled(let returned)):
-        self.show(returned) { completion(.newData) }
-      case .success(.unhandled):
-        completion(.noData)
-      case .failure(let error):
-        print("tokamak push handler failed: \(error)")
+      case .success(let response):
+        self.show(response) { completion(.newData) }
+      case .failure:
         completion(.failed)
       }
     }
   }
 
+  /// Posts `message` to `/tokamak/push`, logging each failed attempt and
+  /// retrying while another attempt can finish before `deadline`.
+  private func deliverPush(
+    _ message: [String: Any],
+    attempt: Int,
+    deadline: Date,
+    completion: @escaping (Result<Data, Error>) -> Void
+  ) {
+    host.call("push", body: message, timeout: pushAttemptTimeout) { result in
+      if case .failure(let error) = result {
+        print("push notification failed: \(error)")
+      }
+      let retryEnds = Date() + pushRetryDelay + pushAttemptTimeout
+      guard case .failure = result, attempt < pushAttempts, retryEnds <= deadline else {
+        completion(result)
+        return
+      }
+      DispatchQueue.main.asyncAfter(deadline: .now() + pushRetryDelay) {
+        self.deliverPush(message, attempt: attempt + 1, deadline: deadline, completion: completion)
+      }
+    }
+  }
+
   func userNotificationCenter(
     _ center: UNUserNotificationCenter,
     willPresent notification: UNNotification,
@@ -256,14 +279,16 @@ final class TokamakNotificationsPlugin: NSObject, TokamakPlugin,
     }
   }
 
-  /// Shows a notification a Worker handler returned, then calls `completion`.
-  private func show(_ returned: Any, completion: @escaping () -> Void) {
-    guard !(returned is NSNull) else {
+  /// Shows the notification a push response returns, if any.
+  private func show(_ response: Data, completion: @escaping () -> Void) {
+    let returned = try? JSONSerialization.jsonObject(with: response, options: .fragmentsAllowed)
+    guard !response.isEmpty, !(returned is NSNull) else {
       completion()
       return
     }
-    guard let request = try? TokamakNotificationRequest(returned, scheduled: false) else {
-      print("tokamak push handler returned an invalid notification")
+    guard let returned, let request = try? TokamakNotificationRequest(returned, scheduled: false)
+    else {
+      print("tokamak push response is not a notification")
       completion()
       return
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin-notifications",
-  "version": "0.1.0-beta.50",
+  "version": "0.1.0-beta.51",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
@@ -9,10 +9,11 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./service-worker": "./service-worker/index.ts"
+    "./service-worker": "./service-worker/index.ts",
+    "./worker": "./worker/index.ts"
   },
   "dependencies": {
-    "@tokamakdev/plugin": "0.1.0-beta.50"
+    "@tokamakdev/plugin": "0.1.0-beta.51"
   },
   "files": [
     "android",
@@ -20,6 +21,7 @@
     "service-worker",
     "src",
     "web",
+    "worker",
     "tokamak-plugin.json",
     "README.md"
   ],

package/src/index.ts

@@ -18,11 +18,11 @@ export interface ScheduledNotification extends NotificationContent {
 }
 
 /** A received push message. A data-only message has no title or body. */
-export interface Message {
+export interface Message<Data extends object = Record<string, unknown>> {
   readonly id: string;
   readonly title: string | null;
   readonly body: string | null;
-  readonly data: Record<string, unknown>;
+  readonly data: Data;
 }
 
 export interface OpenedNotification extends Message {

package/worker/index.ts

@@ -0,0 +1,22 @@
+import { acceptsRuntimeCalls } from "@tokamakdev/plugin/worker";
+
+import type { Message, NotificationContent } from "../src/index.js";
+
+/** Runs for a data-only push message and returns a notification to show, or nothing. */
+export type PushHandler<Data extends object = Record<string, unknown>> =
+  | ((message: Message<Data>) => NotificationContent | undefined | Promise<NotificationContent | undefined>)
+  | ((message: Message<Data>) => void | Promise<void>);
+
+/**
+ * Serves `POST /tokamak/push`: runs `handler` with the data-only push message the tokamak
+ * runtime delivers and responds with the notification it returns. Responds 404 outside a
+ * tokamak app and development.
+ */
+export async function handlePushRequest<Data extends object = Record<string, unknown>>(
+  request: Request,
+  handler: PushHandler<Data>,
+): Promise<Response> {
+  if (!acceptsRuntimeCalls()) return new Response(null, { status: 404 });
+  const message = (await request.json()) as Message<Data>;
+  return Response.json((await handler(message)) ?? null);
+}