Skip to content

Commit 42eef7a

Browse files
committed
feat(service-push): serve the direct push transport and refuse the relay at init
PushServicePlugin parses the relay | direct union. transport: 'direct' (or a vendor block with no transport) drives the APNs and FCM transports unchanged. transport: 'relay', and the empty config that reads as it, is refused at init with PUSH_RELAY_NOT_SERVED_MESSAGE, naming follow-up card #29920 and the direct transport for a white-label build; nothing is registered. Pinned: direct boots named and inferred, relay is refused four ways. ADR-0012: the Amended status line, the section 4 push row and the section 6 note say service-push ships the direct transport and the hosted relay, the default per cloud#3519, is not yet served (#29920). README and changeset say the same. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 5f56298 commit 42eef7a

6 files changed

Lines changed: 60 additions & 17 deletions

File tree

‎.changeset/29041-push-notification-channel.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,6 @@ feat(notifications): the `push` channel — a `notify` node naming `push` reache
99
Clause-②: yes (widening)
1010
Metadata-protocol: none
1111

12-
- **New package `@objectstack/service-push`.** `PushServicePlugin` registers the kernel's `push` service: APNs over HTTP/2 with token-based auth (an ES256 provider token signed with the `.p8` key, reused for fifty minutes) and FCM over the HTTP v1 API (an OAuth access token from the service account). It reads `PushServiceConfigSchema` from its `config` option and refuses an inline secret at boot with the schema's guidance. Each secret is named by `credentialRef` and resolved when the transport first signs; in the open tier the reference is the name of an environment variable (ADR-0143 D3).
12+
- **New package `@objectstack/service-push`.** `PushServicePlugin` registers the kernel's `push` service: APNs over HTTP/2 with token-based auth (an ES256 provider token signed with the `.p8` key, reused for fifty minutes) and FCM over the HTTP v1 API (an OAuth access token from the service account). It reads `PushServiceConfigSchema` from its `config` option and refuses an inline secret at boot with the schema's guidance. It serves the direct transport (`transport: 'direct'`, the operator's own APNs key and Firebase project, for a white-label build); the hosted relay, the schema's default and so also an empty config, is refused at init until its sender ships (#29920). Each secret is named by `credentialRef` and resolved when the transport first signs; in the open tier the reference is the name of an environment variable (ADR-0143 D3).
1313
- **`@objectstack/service-messaging`: the `push` channel.** Mounted while a `push` service is registered, as the sms channel is while an `sms` service is. One delivery reaches every enabled device the recipient registered, on each vendor the push service has a transport for. The push carries the notification id and, when it is a same-server path (`PushRouteSchema`), the notification's `actionUrl` as `route`; any other `actionUrl` is left out and the delivery still goes. Each device's push also carries the origin stored on its row (`PushDeliveryDataSchema.origin`) when the row holds one; the registry does not store it yet, so today none does. A token the vendor reports dead (APNs `BadDeviceToken` / `Unregistered`, FCM `UNREGISTERED`) is retired through `invalidateDeviceToken`: the device row is kept, disabled, and the user's other devices still get the push. A recipient with no enabled device, or whose every device was reported dead, is graded `invalid_recipient`; no push service is refused `transport_not_configured`, as the sms and email channels refuse it.
14-
- **`@objectstack/spec`: description and comment text only.** The `[PLANNED]` markers come off `PushServiceConfigSchema`, `ApnsTransportConfigSchema`, `FcmTransportConfigSchema` and `PushDeliveryDataSchema`, which now have their reader and producer. `NotificationChannelSchema`'s JSDoc lists `push` among the registered channels, the docblocks name `@objectstack/service-push` where they named `plugin-notification-push`, and the `NOT_FOUND` synonym waiver's reason names service-messaging's own provenance row. No key, schema shape or export changes.
14+
- **`@objectstack/spec`: description and comment text only.** The `[PLANNED]` markers come off `PushServiceConfigSchema`, `PushDirectTransportConfigSchema`, `ApnsTransportConfigSchema`, `FcmTransportConfigSchema` and `PushDeliveryDataSchema`, which now have their reader and producer; `PushRelayTransportConfigSchema` keeps `[PLANNED — not yet served]`, now saying the push service refuses it at boot (#29920). `NotificationChannelSchema`'s JSDoc lists `push` among the registered channels, the docblocks name `@objectstack/service-push` where they named `plugin-notification-push`, and the `NOT_FOUND` synonym waiver's reason names service-messaging's own provenance row. No key, schema shape or export changes.

‎docs/adr/0012-notification-platform.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ADR-0012: Messaging Platform — Outbound Notifications on a Generalized Outbox
22

3-
**Status**: Draft (2026-05-25 · scope-revised 2026-05-26) · **Superseded by [ADR-0030](./0030-notification-platform-convergence.md)** (2026-06-01) — the M1 implementation drifted (two conflated inbox objects); ADR-0030 records the correction and realizes this layered model. · **Amended (2026-11-03, #29041)**: push ships as `@objectstack/service-push` (the APNs and FCM transports, the kernel's `push` service) with its channel shell `push-channel.ts` in `@objectstack/service-messaging`, which also owns `sys_user_device`; every `plugin-notification-push` below reads that way. ADR-0030 is unchanged.
3+
**Status**: Draft (2026-05-25 · scope-revised 2026-05-26) · **Superseded by [ADR-0030](./0030-notification-platform-convergence.md)** (2026-06-01) — the M1 implementation drifted (two conflated inbox objects); ADR-0030 records the correction and realizes this layered model. · **Amended (2026-11-03, #29041)**: push ships as `@objectstack/service-push` (the direct APNs and FCM transports, the kernel's `push` service; the hosted relay, the default transport per cloud#3519, is not yet served, #29920) with its channel shell `push-channel.ts` in `@objectstack/service-messaging`, which also owns `sys_user_device`; every `plugin-notification-push` below reads that way. ADR-0030 is unchanged.
44
**Authors**: Platform team — surfaced from GitHub Issue #1292 ("[P0] notification: no outbound notification channel")
55
**Consumers**: `@objectstack/spec` (new `messaging/` domain), `@objectstack/service-messaging` (new), `@objectstack/plugin-notification-inbox` (new), `@objectstack/plugin-notification-email` (replaces `plugin-email`), `@objectstack/plugin-notification-webhook` (extracted from `plugin-webhooks`), `@objectstack/plugin-notification-push` (new), every flow that has a `notify` node, every template that ships notification rules
66
**Sibling**: [ADR-0013 — Bidirectional Messaging & Conversational Channels](./0013-bidirectional-messaging.md)
@@ -306,7 +306,7 @@ These cost ~5 columns and one empty table in M1. They are non-negotiable: introd
306306
| `inbox` | `plugin-notification-inbox` | Writes to `sys_inbox_message`; fires `service-realtime` event for online users | **MUST ship M1** |
307307
| `email` | `plugin-notification-email` (replaces `plugin-email`) | SMTP + transport plugins (SendGrid baseline) | **MUST ship M1** |
308308
| `webhook` | `plugin-notification-webhook` (extracted from `plugin-webhooks`) | HTTP POST with HMAC | **MUST ship M1** (port existing) |
309-
| `push` | `service-push` (transports) + `push-channel.ts` in `service-messaging` (channel); amended 2026-11-03, #29041 | APNs (HTTP/2, token auth) + FCM (HTTP v1) | Shipped (#29041) |
309+
| `push` | `service-push` (transports) + `push-channel.ts` in `service-messaging` (channel); amended 2026-11-03, #29041 | Direct: APNs (HTTP/2, token auth) + FCM (HTTP v1) with the operator's own credentials, for a white-label build. The hosted relay is the default transport (cloud#3519) and is not yet served (#29920) | Direct shipped (#29041); relay not yet served (#29920) |
310310

311311
All four bind into `channel-registry` during `onEnable`.
312312

@@ -375,7 +375,7 @@ Lifecycle hooks:
375375

376376
* Client SDK calls `POST /api/v1/notifications/devices` on login → `device-registry.upsert(...)`.
377377
* APNs / FCM `BadDeviceToken` / `Unregistered` response → channel returns `classifyError = 'invalid_recipient'` → dispatcher calls `device-registry.invalidate(token)` (sets `invalidated_at`, `enabled=false`) without dead-lettering the notification (it just routes around the dead token).
378-
> Amended (2026-11-03, #29041): the push channel (`push-channel.ts` in service-messaging) retires the dead token itself, through `INotificationService.invalidateDeviceToken`, because one delivery fans out to all of the recipient's devices and only the channel knows which token died; the other devices still get the push. The delivery is graded `invalid_recipient` (suppressed, not dead-lettered) only when every device was reported dead. The shipped device shape is `UserDeviceSchema` in `packages/spec/src/system/push-device.zod.ts`, narrowed to `apns` | `fcm` and `ios` | `android` | `web`.
378+
> Amended (2026-11-03, #29041): the push channel (`push-channel.ts` in service-messaging) retires the dead token itself, through `INotificationService.invalidateDeviceToken`, because one delivery fans out to all of the recipient's devices and only the channel knows which token died; the other devices still get the push. The delivery is graded `invalid_recipient` (suppressed, not dead-lettered) only when every device was reported dead. The shipped device shape is `UserDeviceSchema` in `packages/spec/src/system/push-device.zod.ts`, narrowed to `apns` | `fcm` and `ios` | `android` | `web`. `service-push` ships the direct transport; the hosted relay, the default per cloud#3519, is not yet served (#29920), and `PushServicePlugin` refuses a relay configuration at init until it is.
379379
* Domestic vendors (HMS / Xiaomi / OPPO / VIVO) plug in as **alternate channel implementations** (one package each, named by kind like `service-push`), not as transports — their on-device SDKs and quotas are too different to share a code path.
380380

381381
### 7. Topic + Preference matrix

‎packages/services/service-push/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,14 @@
22

33
The push service: `IPushService` over the APNs (HTTP/2, token-based auth) and FCM (HTTP v1) transports, configured by `PushServiceConfigSchema` from `@objectstack/spec/system`. Each secret, the APNs `.p8` signing key and the FCM service-account JSON, is named by a `credentialRef` and resolved when the transport first signs (in the open tier, the name of an environment variable). `PushServicePlugin` registers the kernel's `push` service, and the `push` channel in `@objectstack/service-messaging` delivers through it to the devices users register under `/api/v1/notifications/devices`.
44

5+
The direct transport is the one served: `transport: 'direct'` with your own APNs key and Firebase project, for a white-label build. The hosted relay (`transport: 'relay'`, the schema's default, so also an empty config) is refused at init until its sender ships (#29920).
6+
57
```typescript
68
import { PushServicePlugin } from '@objectstack/service-push';
79

810
kernel.use(new PushServicePlugin({
911
config: {
12+
transport: 'direct',
1013
apns: { teamId: 'ABCDE12345', keyId: 'KEY1234567', topic: 'com.example.app', environment: 'production', credentialRef: 'APNS_SIGNING_KEY' },
1114
fcm: { projectId: 'example-app', credentialRef: 'FCM_SERVICE_ACCOUNT' },
1215
},

‎packages/services/service-push/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ export {
99
type PushSendResult,
1010
type PushServiceOptions,
1111
} from './push-service.js';
12-
export { PushServicePlugin, type PushServicePluginOptions } from './push-plugin.js';
12+
export { PushServicePlugin, PUSH_RELAY_NOT_SERVED_MESSAGE, type PushServicePluginOptions } from './push-plugin.js';
1313
export {
1414
envPushCredentialResolver,
1515
PushCredentialError,

‎packages/services/service-push/src/push-plugin.test.ts‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
*/
77

88
import { describe, it, expect } from 'vitest';
9-
import { PushServicePlugin } from './push-plugin.js';
9+
import { PushServicePlugin, PUSH_RELAY_NOT_SERVED_MESSAGE } from './push-plugin.js';
1010
import { PushService, type IPushTransport, type PushMessage } from './push-service.js';
1111
import { envPushCredentialResolver } from './credential.js';
1212

@@ -34,11 +34,30 @@ describe('PushServicePlugin', () => {
3434
expect(push.vendors().sort()).toEqual(['apns', 'fcm']);
3535
});
3636

37-
it('registers a push service with no vendor when nothing is configured, and says so', async () => {
38-
const { ctx, services, lines } = context();
39-
await new PushServicePlugin().init(ctx);
40-
expect((services.get('push') as PushService).vendors()).toEqual([]);
41-
expect(lines.some((l) => l.includes('no vendor configured'))).toBe(true);
37+
it('boots the direct transport, named or read from a vendor block', async () => {
38+
for (const config of [{ transport: 'direct' as const, apns: APNS }, { apns: APNS }]) {
39+
const { ctx, services } = context();
40+
await new PushServicePlugin({ config }).init(ctx);
41+
expect((services.get('push') as PushService).vendors()).toEqual(['apns']);
42+
}
43+
});
44+
45+
it.each([
46+
['no config', undefined],
47+
['the empty config', {}],
48+
["transport: 'relay'", { transport: 'relay' as const }],
49+
['a staging relay endpoint', { transport: 'relay' as const, endpoint: 'https://relay.staging.example.com' }],
50+
])('refuses the relay transport at init (%s), registering nothing', async (_name, config) => {
51+
const { ctx, services } = context();
52+
const init = new PushServicePlugin({ config }).init(ctx);
53+
await expect(init).rejects.toThrow(PUSH_RELAY_NOT_SERVED_MESSAGE);
54+
expect(services.has('push')).toBe(false);
55+
});
56+
57+
it('names the follow-up card and the direct transport in the relay refusal', () => {
58+
expect(PUSH_RELAY_NOT_SERVED_MESSAGE).toContain('#29920');
59+
expect(PUSH_RELAY_NOT_SERVED_MESSAGE).toContain("transport: 'direct'");
60+
expect(PUSH_RELAY_NOT_SERVED_MESSAGE).toContain('credentialRef');
4261
});
4362

4463
it('refuses an inline secret at init with the schema\'s guidance, registering nothing', async () => {

‎packages/services/service-push/src/push-plugin.ts‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,16 @@ import { FcmPushTransport } from './transports/fcm.js';
99

1010
export interface PushServicePluginOptions {
1111
/**
12-
* The push transports: one optional block per vendor, parsed by
13-
* `PushServiceConfigSchema` (`@objectstack/spec/system`) when the plugin
14-
* initialises, so an inline secret or a misspelt key fails the boot with
15-
* the schema's own guidance. A vendor with no block is not delivered to.
12+
* The push transport, parsed by `PushServiceConfigSchema`
13+
* (`@objectstack/spec/system`) when the plugin initialises, so an inline
14+
* secret or a misspelt key fails the boot with the schema's own guidance.
15+
*
16+
* Only the direct transport is served: `transport: 'direct'` (or a block
17+
* with an `apns` / `fcm` block and no `transport`), one vendor transport per
18+
* block; a vendor with no block is not delivered to. The hosted relay
19+
* (`transport: 'relay'`, and the default `{}` that reads as it) is refused
20+
* at init until its sender ships (#29920): see
21+
* {@link PUSH_RELAY_NOT_SERVED_MESSAGE}.
1622
*/
1723
config?: PushServiceConfig;
1824
/**
@@ -42,7 +48,8 @@ export interface PushServicePluginOptions {
4248
* user.
4349
*
4450
* Configuration is the constructor's `config`, the operator's
45-
* `PushServiceConfigSchema` value; secrets are named by `credentialRef` and
51+
* `PushServiceConfigSchema` value. The direct transport is served; the hosted
52+
* relay, the schema's default, is refused at init until #29920 ships it. Secrets are named by `credentialRef` and
4653
* resolved through {@link PushServicePluginOptions.resolveCredential}, never
4754
* written inline (ADR-0143 D3).
4855
*
@@ -51,13 +58,26 @@ export interface PushServicePluginOptions {
5158
* kernel.use(new MessagingServicePlugin());
5259
* kernel.use(new PushServicePlugin({
5360
* config: {
61+
* transport: 'direct',
5462
* apns: { teamId: 'ABCDE12345', keyId: 'KEY1234567', topic: 'com.example.app',
5563
* environment: 'production', credentialRef: 'APNS_SIGNING_KEY' },
5664
* fcm: { projectId: 'example-app', credentialRef: 'FCM_SERVICE_ACCOUNT' },
5765
* },
5866
* }));
5967
* ```
6068
*/
69+
/**
70+
* The refusal a relay configuration meets at init. The relay is the schema's
71+
* default (cloud#3519), but its sender is not served yet (#29920): booting a
72+
* `push` service that would deliver nothing is worse than refusing, because
73+
* the channel would mount and every push would look sent.
74+
*/
75+
export const PUSH_RELAY_NOT_SERVED_MESSAGE =
76+
"PushServicePlugin: the hosted push relay (transport: 'relay', which is also what an empty push config reads as) "
77+
+ 'is not served yet: its sender is follow-up card #29920, and nothing would deliver through it. For a white-label '
78+
+ "build signed with your own APNs key or Firebase project, write transport: 'direct' with an apns and/or fcm block, "
79+
+ 'each naming its secret by credentialRef.';
80+
6181
export class PushServicePlugin implements Plugin {
6282
name = 'com.objectstack.service.push';
6383
/** Services init() registers on every path (ADR-0116). */
@@ -71,6 +91,7 @@ export class PushServicePlugin implements Plugin {
7191

7292
async init(ctx: PluginContext): Promise<void> {
7393
const config = PushServiceConfigSchema.parse(this.options.config ?? {});
94+
if (config.transport !== 'direct') throw new Error(PUSH_RELAY_NOT_SERVED_MESSAGE);
7495
const resolveCredential = this.options.resolveCredential ?? envPushCredentialResolver;
7596
const transports: Partial<Record<PushVendor, IPushTransport>> = {};
7697
if (config.apns) transports.apns = new ApnsPushTransport({ config: config.apns, resolveCredential });

0 commit comments

Comments
 (0)