@memberjunction/server 6.2.0-edge.5 → 6.2.0-edge.7

package/dist/broadcast/providers/AWSIoTCoreBroadcastProvider.js

@@ -0,0 +1,144 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { createHash, createHmac } from 'node:crypto';
+import { RegisterClass } from '@memberjunction/global';
+import { BaseCacheInvalidationBroadcastProvider, } from '../BaseCacheInvalidationBroadcastProvider.js';
+/**
+ * Topology 3 Cloud Multiplexer Provider for **AWS IoT Core MQTT over WebSockets** (`'AWSIoTCore'`).
+ *
+ * Offloads per-client WebSocket connection management and message fan-out from MJServer
+ * to AWS IoT Core's managed MQTT message broker:
+ * - Each authenticated browser client calls `NegotiateCacheBroadcastConnection` to obtain
+ *   a SigV4-presigned `wss://<endpoint>/mqtt` URL and its authorized MQTT topic list
+ *   (`<topicPrefix>/roles/<RoleID>`).
+ * - When an entity mutation occurs, MJServer shapes the invalidation payload once per
+ *   authorized role on the entity and publishes to `<topicPrefix>/roles/<RoleID>`.
+ */
+let AWSIoTCoreBroadcastProvider = class AWSIoTCoreBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    constructor() {
+        super(...arguments);
+        this._topicPublisher = null;
+    }
+    get Topology() {
+        return 'AWSIoTCore';
+    }
+    /**
+     * Installs a custom MQTT topic publisher (e.g., AWS SDK `IoTDataPlaneClient` adapter or test spy).
+     */
+    SetTopicPublisher(publisher) {
+        this._topicPublisher = publisher;
+    }
+    /**
+     * Computes the MQTT topic filters (`<topicPrefix>/roles/<roleId>`) for a user's roles.
+     */
+    GetAuthorizedTopicsForUser(user) {
+        const prefix = (this._config.awsIoTCore?.topicPrefix || 'mj/cache').replace(/\/+$/, '');
+        const roles = user.UserRoles ?? [];
+        const topics = [];
+        for (const r of roles) {
+            const roleId = (r.RoleID ?? '').trim().toLowerCase();
+            if (roleId.length > 0) {
+                topics.push(`${prefix}/roles/${roleId}`);
+            }
+        }
+        topics.sort();
+        return topics;
+    }
+    async OnInvalidationRecorded(payload) {
+        const prefix = (this._config.awsIoTCore?.topicPrefix || 'mj/cache').replace(/\/+$/, '');
+        const entity = this.ResolveEntityForPayload(payload);
+        if (!entity) {
+            return;
+        }
+        for (const perm of entity.Permissions) {
+            if (!perm.CanRead)
+                continue;
+            const roleId = (perm.RoleID ?? '').trim().toLowerCase();
+            if (!roleId)
+                continue;
+            const syntheticRoleHolder = { UserRoles: [{ RoleID: roleId }] };
+            const shaped = this.ShapeEventForSubscriber(payload, syntheticRoleHolder, entity);
+            const message = {
+                Topic: `${prefix}/roles/${roleId}`,
+                QoS: 1,
+                Event: shaped,
+            };
+            if (this._topicPublisher) {
+                await this._topicPublisher(message);
+            }
+        }
+    }
+    async NegotiateClientConnection(user, defaultGraphQLWsUrl = '/graphql') {
+        const endpoint = (this._config.awsIoTCore?.endpoint ?? '').replace(/^https?:\/\//i, '').replace(/\/+$/, '');
+        const region = this._config.awsIoTCore?.region || 'us-east-1';
+        const ttlSeconds = this._config.awsIoTCore?.tokenTtlSeconds ?? 3600;
+        const expiresAtMs = Date.now() + ttlSeconds * 1000;
+        const topics = this.GetAuthorizedTopicsForUser(user);
+        if (!endpoint) {
+            return {
+                Provider: this.Topology,
+                Url: defaultGraphQLWsUrl,
+                Groups: topics,
+                ExpiresAt: new Date(expiresAtMs).toISOString(),
+                ServerProcessID: this.ServerProcessID,
+                CurrentSequence: this.CurrentSequence,
+            };
+        }
+        const accessKeyId = this._config.awsIoTCore?.accessKeyId;
+        const secretAccessKey = this._config.awsIoTCore?.secretAccessKey;
+        const presignedUrl = accessKeyId && secretAccessKey
+            ? this.buildSigV4PresignedMqttUrl(endpoint, region, accessKeyId, secretAccessKey, ttlSeconds)
+            : `wss://${endpoint}/mqtt`;
+        return {
+            Provider: this.Topology,
+            Url: presignedUrl,
+            Groups: topics,
+            ExpiresAt: new Date(expiresAtMs).toISOString(),
+            ServerProcessID: this.ServerProcessID,
+            CurrentSequence: this.CurrentSequence,
+        };
+    }
+    buildSigV4PresignedMqttUrl(host, region, accessKeyId, secretAccessKey, expiresSeconds) {
+        const now = new Date();
+        const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, '');
+        const dateStamp = amzDate.slice(0, 8);
+        const service = 'iotdevicegateway';
+        const credentialScope = `${dateStamp}/${region}/${service}/aws4_request`;
+        const queryParams = [
+            `X-Amz-Algorithm=AWS4-HMAC-SHA256`,
+            `X-Amz-Credential=${encodeURIComponent(`${accessKeyId}/${credentialScope}`)}`,
+            `X-Amz-Date=${amzDate}`,
+            `X-Amz-Expires=${expiresSeconds}`,
+            `X-Amz-SignedHeaders=host`,
+        ].join('&');
+        const canonicalRequest = [
+            'GET',
+            '/mqtt',
+            queryParams,
+            `host:${host}\n`,
+            'host',
+            createHash('sha256').update('').digest('hex'),
+        ].join('\n');
+        const stringToSign = [
+            'AWS4-HMAC-SHA256',
+            amzDate,
+            credentialScope,
+            createHash('sha256').update(canonicalRequest).digest('hex'),
+        ].join('\n');
+        const kDate = createHmac('sha256', `AWS4${secretAccessKey}`).update(dateStamp).digest();
+        const kRegion = createHmac('sha256', kDate).update(region).digest();
+        const kService = createHmac('sha256', kRegion).update(service).digest();
+        const kSigning = createHmac('sha256', kService).update('aws4_request').digest();
+        const signature = createHmac('sha256', kSigning).update(stringToSign).digest('hex');
+        return `wss://${host}/mqtt?${queryParams}&X-Amz-Signature=${signature}`;
+    }
+};
+AWSIoTCoreBroadcastProvider = __decorate([
+    RegisterClass(BaseCacheInvalidationBroadcastProvider, 'AWSIoTCore')
+], AWSIoTCoreBroadcastProvider);
+export { AWSIoTCoreBroadcastProvider };
+//# sourceMappingURL=AWSIoTCoreBroadcastProvider.js.map

package/dist/broadcast/providers/AWSIoTCoreBroadcastProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AWSIoTCoreBroadcastProvider.js","sourceRoot":"","sources":["../../../src/broadcast/providers/AWSIoTCoreBroadcastProvider.ts"],"names":[],"mappings":"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"}

package/dist/broadcast/providers/AzureWebPubSubBroadcastProvider.d.ts

@@ -0,0 +1,46 @@
+import { UserInfo } from '@memberjunction/core';
+import { BaseCacheInvalidationBroadcastProvider, CacheBroadcastNegotiationResult, CacheInvalidationBroadcastTopology } from '../BaseCacheInvalidationBroadcastProvider.js';
+import type { CacheInvalidationNotification, CacheInvalidationPayload } from '../../generic/CacheInvalidationResolver.js';
+/**
+ * Envelope published to an Azure Web PubSub role group.
+ */
+export interface AzureWebPubSubGroupMessage {
+    HubName: string;
+    GroupName: string;
+    Event: CacheInvalidationNotification;
+}
+/**
+ * Transport callback used by {@link AzureWebPubSubBroadcastProvider} to deliver a shaped
+ * invalidation notification to an Azure Web PubSub group.
+ */
+export type AzureWebPubSubGroupPublisher = (message: AzureWebPubSubGroupMessage) => Promise<void>;
+/**
+ * Topology 3 Cloud Multiplexer Provider for **Azure Web PubSub** (`'AzureWebPubSub'`).
+ *
+ * Offloads per-client WebSocket connection management and message fan-out from MJServer
+ * to Azure Web PubSub:
+ * - Each authenticated browser client calls `NegotiateCacheBroadcastConnection` to receive
+ *   a short-lived, HMAC-signed JWT access token scoped to its authorized role groups (`mj-role-<RoleID>`).
+ * - When an entity mutation occurs, MJServer shapes the invalidation payload once per
+ *   authorized role group on the entity and publishes a single group broadcast to Azure Web PubSub,
+ *   which fans the message out to thousands of connected browsers in C++ edge infrastructure.
+ */
+export declare class AzureWebPubSubBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    private _groupPublisher;
+    get Topology(): CacheInvalidationBroadcastTopology;
+    /**
+     * Installs a custom group publisher (e.g., Azure WebPubSubServiceClient adapter or test spy).
+     * When unset and an HTTP endpoint + accessKey are configured, defaults to the Azure Web PubSub
+     * REST Data Plane API (`POST /api/hubs/{hub}/groups/{group}/:send`).
+     */
+    SetGroupPublisher(publisher: AzureWebPubSubGroupPublisher | null): void;
+    /**
+     * Computes the Azure Web PubSub group names (`mj-role-<roleId>`) for a user's roles.
+     */
+    GetAuthorizedGroupsForUser(user: UserInfo): string[];
+    protected OnInvalidationRecorded(payload: CacheInvalidationPayload): Promise<void>;
+    NegotiateClientConnection(user: UserInfo, defaultGraphQLWsUrl?: string): Promise<CacheBroadcastNegotiationResult>;
+    private mintJwtToken;
+    private publishViaRestApi;
+}
+//# sourceMappingURL=AzureWebPubSubBroadcastProvider.d.ts.map

package/dist/broadcast/providers/AzureWebPubSubBroadcastProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AzureWebPubSubBroadcastProvider.d.ts","sourceRoot":"","sources":["../../../src/broadcast/providers/AzureWebPubSubBroadcastProvider.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EACH,sCAAsC,EACtC,+BAA+B,EAC/B,kCAAkC,EACrC,MAAM,8CAA8C,CAAC;AACtD,OAAO,KAAK,EACR,6BAA6B,EAC7B,wBAAwB,EAC3B,MAAM,4CAA4C,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,6BAA6B,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,OAAO,EAAE,0BAA0B,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAElG;;;;;;;;;;GAUG;AACH,qBACa,+BAAgC,SAAQ,sCAAsC;IACvF,OAAO,CAAC,eAAe,CAA6C;IAEpE,IAAoB,QAAQ,IAAI,kCAAkC,CAEjE;IAED;;;;OAIG;IACI,iBAAiB,CAAC,SAAS,EAAE,4BAA4B,GAAG,IAAI,GAAG,IAAI;IAI9E;;OAEG;IACI,0BAA0B,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE;cAalC,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IA6B3E,yBAAyB,CAC3C,IAAI,EAAE,QAAQ,EACd,mBAAmB,SAAa,GACjC,OAAO,CAAC,+BAA+B,CAAC;IAuC3C,OAAO,CAAC,YAAY;YAsBN,iBAAiB;CAgBlC"}

package/dist/broadcast/providers/AzureWebPubSubBroadcastProvider.js

@@ -0,0 +1,149 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { createHmac } from 'node:crypto';
+import { RegisterClass } from '@memberjunction/global';
+import { BaseCacheInvalidationBroadcastProvider, } from '../BaseCacheInvalidationBroadcastProvider.js';
+/**
+ * Topology 3 Cloud Multiplexer Provider for **Azure Web PubSub** (`'AzureWebPubSub'`).
+ *
+ * Offloads per-client WebSocket connection management and message fan-out from MJServer
+ * to Azure Web PubSub:
+ * - Each authenticated browser client calls `NegotiateCacheBroadcastConnection` to receive
+ *   a short-lived, HMAC-signed JWT access token scoped to its authorized role groups (`mj-role-<RoleID>`).
+ * - When an entity mutation occurs, MJServer shapes the invalidation payload once per
+ *   authorized role group on the entity and publishes a single group broadcast to Azure Web PubSub,
+ *   which fans the message out to thousands of connected browsers in C++ edge infrastructure.
+ */
+let AzureWebPubSubBroadcastProvider = class AzureWebPubSubBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    constructor() {
+        super(...arguments);
+        this._groupPublisher = null;
+    }
+    get Topology() {
+        return 'AzureWebPubSub';
+    }
+    /**
+     * Installs a custom group publisher (e.g., Azure WebPubSubServiceClient adapter or test spy).
+     * When unset and an HTTP endpoint + accessKey are configured, defaults to the Azure Web PubSub
+     * REST Data Plane API (`POST /api/hubs/{hub}/groups/{group}/:send`).
+     */
+    SetGroupPublisher(publisher) {
+        this._groupPublisher = publisher;
+    }
+    /**
+     * Computes the Azure Web PubSub group names (`mj-role-<roleId>`) for a user's roles.
+     */
+    GetAuthorizedGroupsForUser(user) {
+        const roles = user.UserRoles ?? [];
+        const groups = [];
+        for (const r of roles) {
+            const roleId = (r.RoleID ?? '').trim().toLowerCase();
+            if (roleId.length > 0) {
+                groups.push(`mj-role-${roleId}`);
+            }
+        }
+        groups.sort();
+        return groups;
+    }
+    async OnInvalidationRecorded(payload) {
+        const hubName = this._config.azureWebPubSub?.hubName || 'mj_cache_hub';
+        const entity = this.ResolveEntityForPayload(payload);
+        if (!entity) {
+            return;
+        }
+        // Group entity permissions by RoleID and shape once per authorized role
+        for (const perm of entity.Permissions) {
+            if (!perm.CanRead)
+                continue;
+            const roleId = (perm.RoleID ?? '').trim().toLowerCase();
+            if (!roleId)
+                continue;
+            const syntheticRoleHolder = { UserRoles: [{ RoleID: roleId }] };
+            const shaped = this.ShapeEventForSubscriber(payload, syntheticRoleHolder, entity);
+            const message = {
+                HubName: hubName,
+                GroupName: `mj-role-${roleId}`,
+                Event: shaped,
+            };
+            if (this._groupPublisher) {
+                await this._groupPublisher(message);
+            }
+            else if (this._config.azureWebPubSub?.endpoint && this._config.azureWebPubSub?.accessKey) {
+                await this.publishViaRestApi(message);
+            }
+        }
+    }
+    async NegotiateClientConnection(user, defaultGraphQLWsUrl = '/graphql') {
+        const endpoint = (this._config.azureWebPubSub?.endpoint ?? '').replace(/\/+$/, '');
+        const hubName = this._config.azureWebPubSub?.hubName || 'mj_cache_hub';
+        const accessKey = this._config.azureWebPubSub?.accessKey || '';
+        const ttlMinutes = this._config.azureWebPubSub?.tokenTtlMinutes ?? 60;
+        const expiresAtMs = Date.now() + ttlMinutes * 60 * 1000;
+        const groups = this.GetAuthorizedGroupsForUser(user);
+        if (!endpoint) {
+            return {
+                Provider: this.Topology,
+                Url: defaultGraphQLWsUrl,
+                Groups: groups,
+                ExpiresAt: new Date(expiresAtMs).toISOString(),
+                ServerProcessID: this.ServerProcessID,
+                CurrentSequence: this.CurrentSequence,
+            };
+        }
+        const wsEndpoint = endpoint.replace(/^http:/i, 'ws:').replace(/^https:/i, 'wss:');
+        const audience = `${endpoint}/client/hubs/${hubName}`;
+        const token = accessKey
+            ? this.mintJwtToken(audience, user.ID, groups, Math.floor(expiresAtMs / 1000), accessKey)
+            : undefined;
+        const url = token
+            ? `${wsEndpoint}/client/hubs/${hubName}?access_token=${encodeURIComponent(token)}`
+            : `${wsEndpoint}/client/hubs/${hubName}`;
+        return {
+            Provider: this.Topology,
+            Url: url,
+            Token: token,
+            Groups: groups,
+            ExpiresAt: new Date(expiresAtMs).toISOString(),
+            ServerProcessID: this.ServerProcessID,
+            CurrentSequence: this.CurrentSequence,
+        };
+    }
+    mintJwtToken(audience, subject, groups, expSeconds, secret) {
+        const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+        const claims = Buffer.from(JSON.stringify({
+            aud: audience,
+            sub: subject,
+            iat: Math.floor(Date.now() / 1000),
+            exp: expSeconds,
+            role: groups.map((g) => `webpubsub.joinLeaveGroup.${g}`),
+        })).toString('base64url');
+        const signingInput = `${header}.${claims}`;
+        const signature = createHmac('sha256', secret).update(signingInput).digest('base64url');
+        return `${signingInput}.${signature}`;
+    }
+    async publishViaRestApi(message) {
+        const endpoint = (this._config.azureWebPubSub?.endpoint ?? '').replace(/\/+$/, '');
+        const accessKey = this._config.azureWebPubSub?.accessKey ?? '';
+        if (!endpoint || !accessKey)
+            return;
+        const targetUrl = `${endpoint}/api/hubs/${encodeURIComponent(message.HubName)}/groups/${encodeURIComponent(message.GroupName)}/:send?api-version=2024-01-01`;
+        const token = this.mintJwtToken(targetUrl, 'mj-server', [], Math.floor(Date.now() / 1000) + 300, accessKey);
+        await fetch(targetUrl, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(message.Event),
+        });
+    }
+};
+AzureWebPubSubBroadcastProvider = __decorate([
+    RegisterClass(BaseCacheInvalidationBroadcastProvider, 'AzureWebPubSub')
+], AzureWebPubSubBroadcastProvider);
+export { AzureWebPubSubBroadcastProvider };
+//# sourceMappingURL=AzureWebPubSubBroadcastProvider.js.map

package/dist/broadcast/providers/AzureWebPubSubBroadcastProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AzureWebPubSubBroadcastProvider.js","sourceRoot":"","sources":["../../../src/broadcast/providers/AzureWebPubSubBroadcastProvider.ts"],"names":[],"mappings":"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"}

package/dist/broadcast/providers/GCPPubSubBroadcastProvider.d.ts

@@ -0,0 +1,49 @@
+import { UserInfo } from '@memberjunction/core';
+import { BaseCacheInvalidationBroadcastProvider, CacheBroadcastNegotiationResult, CacheInvalidationBroadcastTopology } from '../BaseCacheInvalidationBroadcastProvider.js';
+import type { CacheInvalidationNotification, CacheInvalidationPayload } from '../../generic/CacheInvalidationResolver.js';
+/**
+ * Envelope published to a Google Cloud Pub/Sub role topic.
+ */
+export interface GCPPubSubTopicMessage {
+    ProjectId: string;
+    TopicName: string;
+    Attributes: {
+        roleId: string;
+        entityName: string;
+        action: string;
+        sequence: string;
+    };
+    Event: CacheInvalidationNotification;
+}
+/**
+ * Transport callback used by {@link GCPPubSubBroadcastProvider} to publish a shaped
+ * invalidation notification to Google Cloud Pub/Sub.
+ */
+export type GCPPubSubTopicPublisher = (message: GCPPubSubTopicMessage) => Promise<void>;
+/**
+ * Topology 3 Cloud Multiplexer Provider for **Google Cloud Pub/Sub + Cloud Run WebSockets** (`'GCPPubSub'`).
+ *
+ * Offloads per-client WebSocket connection management and message fan-out from MJServer
+ * to a Google Cloud Pub/Sub + Cloud Run WebSocket fan-out gateway:
+ * - Each authenticated browser client calls `NegotiateCacheBroadcastConnection` to obtain
+ *   a signed gateway token and its authorized Pub/Sub role subscription attributes
+ *   (`projects/<projectId>/topics/<topicPrefix>-role-<RoleID>`).
+ * - When an entity mutation occurs, MJServer shapes the invalidation payload once per
+ *   authorized role on the entity and publishes a message with Pub/Sub filtering attributes.
+ */
+export declare class GCPPubSubBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    private _topicPublisher;
+    get Topology(): CacheInvalidationBroadcastTopology;
+    /**
+     * Installs a custom Google Cloud Pub/Sub topic publisher (e.g., `@google-cloud/pubsub` adapter or test spy).
+     */
+    SetTopicPublisher(publisher: GCPPubSubTopicPublisher | null): void;
+    /**
+     * Computes the fully-qualified GCP Pub/Sub topic names for a user's roles.
+     */
+    GetAuthorizedTopicsForUser(user: UserInfo): string[];
+    protected OnInvalidationRecorded(payload: CacheInvalidationPayload): Promise<void>;
+    NegotiateClientConnection(user: UserInfo, defaultGraphQLWsUrl?: string): Promise<CacheBroadcastNegotiationResult>;
+    private mintGatewayToken;
+}
+//# sourceMappingURL=GCPPubSubBroadcastProvider.d.ts.map

package/dist/broadcast/providers/GCPPubSubBroadcastProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GCPPubSubBroadcastProvider.d.ts","sourceRoot":"","sources":["../../../src/broadcast/providers/GCPPubSubBroadcastProvider.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EACH,sCAAsC,EACtC,+BAA+B,EAC/B,kCAAkC,EACrC,MAAM,8CAA8C,CAAC;AACtD,OAAO,KAAK,EACR,6BAA6B,EAC7B,wBAAwB,EAC3B,MAAM,4CAA4C,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,KAAK,EAAE,6BAA6B,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAExF;;;;;;;;;;GAUG;AACH,qBACa,0BAA2B,SAAQ,sCAAsC;IAClF,OAAO,CAAC,eAAe,CAAwC;IAE/D,IAAoB,QAAQ,IAAI,kCAAkC,CAEjE;IAED;;OAEG;IACI,iBAAiB,CAAC,SAAS,EAAE,uBAAuB,GAAG,IAAI,GAAG,IAAI;IAIzE;;OAEG;IACI,0BAA0B,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE;cAelC,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC3E,yBAAyB,CAC3C,IAAI,EAAE,QAAQ,EACd,mBAAmB,SAAa,GACjC,OAAO,CAAC,+BAA+B,CAAC;IAmC3C,OAAO,CAAC,gBAAgB;CAmB3B"}

package/dist/broadcast/providers/GCPPubSubBroadcastProvider.js

@@ -0,0 +1,131 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { createHmac } from 'node:crypto';
+import { RegisterClass } from '@memberjunction/global';
+import { BaseCacheInvalidationBroadcastProvider, } from '../BaseCacheInvalidationBroadcastProvider.js';
+/**
+ * Topology 3 Cloud Multiplexer Provider for **Google Cloud Pub/Sub + Cloud Run WebSockets** (`'GCPPubSub'`).
+ *
+ * Offloads per-client WebSocket connection management and message fan-out from MJServer
+ * to a Google Cloud Pub/Sub + Cloud Run WebSocket fan-out gateway:
+ * - Each authenticated browser client calls `NegotiateCacheBroadcastConnection` to obtain
+ *   a signed gateway token and its authorized Pub/Sub role subscription attributes
+ *   (`projects/<projectId>/topics/<topicPrefix>-role-<RoleID>`).
+ * - When an entity mutation occurs, MJServer shapes the invalidation payload once per
+ *   authorized role on the entity and publishes a message with Pub/Sub filtering attributes.
+ */
+let GCPPubSubBroadcastProvider = class GCPPubSubBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    constructor() {
+        super(...arguments);
+        this._topicPublisher = null;
+    }
+    get Topology() {
+        return 'GCPPubSub';
+    }
+    /**
+     * Installs a custom Google Cloud Pub/Sub topic publisher (e.g., `@google-cloud/pubsub` adapter or test spy).
+     */
+    SetTopicPublisher(publisher) {
+        this._topicPublisher = publisher;
+    }
+    /**
+     * Computes the fully-qualified GCP Pub/Sub topic names for a user's roles.
+     */
+    GetAuthorizedTopicsForUser(user) {
+        const projectId = this._config.gcpPubSub?.projectId || 'mj-default-project';
+        const prefix = this._config.gcpPubSub?.topicPrefix || 'mj-cache';
+        const roles = user.UserRoles ?? [];
+        const topics = [];
+        for (const r of roles) {
+            const roleId = (r.RoleID ?? '').trim().toLowerCase();
+            if (roleId.length > 0) {
+                topics.push(`projects/${projectId}/topics/${prefix}-role-${roleId}`);
+            }
+        }
+        topics.sort();
+        return topics;
+    }
+    async OnInvalidationRecorded(payload) {
+        const projectId = this._config.gcpPubSub?.projectId || 'mj-default-project';
+        const prefix = this._config.gcpPubSub?.topicPrefix || 'mj-cache';
+        const entity = this.ResolveEntityForPayload(payload);
+        if (!entity) {
+            return;
+        }
+        for (const perm of entity.Permissions) {
+            if (!perm.CanRead)
+                continue;
+            const roleId = (perm.RoleID ?? '').trim().toLowerCase();
+            if (!roleId)
+                continue;
+            const syntheticRoleHolder = { UserRoles: [{ RoleID: roleId }] };
+            const shaped = this.ShapeEventForSubscriber(payload, syntheticRoleHolder, entity);
+            const message = {
+                ProjectId: projectId,
+                TopicName: `projects/${projectId}/topics/${prefix}-role-${roleId}`,
+                Attributes: {
+                    roleId,
+                    entityName: payload.entityName,
+                    action: payload.action,
+                    sequence: String(payload.sequence ?? 0),
+                },
+                Event: shaped,
+            };
+            if (this._topicPublisher) {
+                await this._topicPublisher(message);
+            }
+        }
+    }
+    async NegotiateClientConnection(user, defaultGraphQLWsUrl = '/graphql') {
+        const gatewayUrl = (this._config.gcpPubSub?.gatewayUrl ?? '').replace(/\/+$/, '');
+        const signingSecret = this._config.gcpPubSub?.signingSecret || '';
+        const ttlSeconds = this._config.gcpPubSub?.tokenTtlSeconds ?? 3600;
+        const expiresAtMs = Date.now() + ttlSeconds * 1000;
+        const topics = this.GetAuthorizedTopicsForUser(user);
+        if (!gatewayUrl) {
+            return {
+                Provider: this.Topology,
+                Url: defaultGraphQLWsUrl,
+                Groups: topics,
+                ExpiresAt: new Date(expiresAtMs).toISOString(),
+                ServerProcessID: this.ServerProcessID,
+                CurrentSequence: this.CurrentSequence,
+            };
+        }
+        const wsGatewayUrl = gatewayUrl.replace(/^http:/i, 'ws:').replace(/^https:/i, 'wss:');
+        const token = signingSecret
+            ? this.mintGatewayToken(user.ID, topics, Math.floor(expiresAtMs / 1000), signingSecret)
+            : undefined;
+        const url = token ? `${wsGatewayUrl}?token=${encodeURIComponent(token)}` : wsGatewayUrl;
+        return {
+            Provider: this.Topology,
+            Url: url,
+            Token: token,
+            Groups: topics,
+            ExpiresAt: new Date(expiresAtMs).toISOString(),
+            ServerProcessID: this.ServerProcessID,
+            CurrentSequence: this.CurrentSequence,
+        };
+    }
+    mintGatewayToken(subject, topics, expSeconds, secret) {
+        const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+        const claims = Buffer.from(JSON.stringify({
+            sub: subject,
+            iat: Math.floor(Date.now() / 1000),
+            exp: expSeconds,
+            topics,
+        })).toString('base64url');
+        const signingInput = `${header}.${claims}`;
+        const signature = createHmac('sha256', secret).update(signingInput).digest('base64url');
+        return `${signingInput}.${signature}`;
+    }
+};
+GCPPubSubBroadcastProvider = __decorate([
+    RegisterClass(BaseCacheInvalidationBroadcastProvider, 'GCPPubSub')
+], GCPPubSubBroadcastProvider);
+export { GCPPubSubBroadcastProvider };
+//# sourceMappingURL=GCPPubSubBroadcastProvider.js.map

package/dist/broadcast/providers/GCPPubSubBroadcastProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GCPPubSubBroadcastProvider.js","sourceRoot":"","sources":["../../../src/broadcast/providers/GCPPubSubBroadcastProvider.ts"],"names":[],"mappings":"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"}

package/dist/broadcast/providers/SequencedRoleBucketBroadcastProvider.d.ts

@@ -0,0 +1,24 @@
+import { UserInfo } from '@memberjunction/core';
+import { BaseCacheInvalidationBroadcastProvider, CacheBroadcastNegotiationResult, CacheInvalidationBroadcastTopology } from '../BaseCacheInvalidationBroadcastProvider.js';
+import type { CacheInvalidationPayload } from '../../generic/CacheInvalidationResolver.js';
+/**
+ * Default MemberJunction cache invalidation broadcast provider (`'SequencedRoleBucket'`).
+ *
+ * Combines:
+ * - **Topology 1 (Monotonic Sequence Ring Buffer + HTTP Header Piggybacking)**:
+ *   Every mutation assigns a monotonic `Sequence` integer, stores the event in a bounded ring buffer,
+ *   and piggybacks `X-MJ-Cache-Seq` and `X-MJ-Server-ID` onto GraphQL HTTP responses so clients can
+ *   detect and recover missed invalidations via `GetCacheInvalidationsSince` in a single delta query.
+ * - **Topology 2 (Role-Fingerprint $O(\text{Roles})$ Evaluation & Shaping Memoizer)**:
+ *   Memoizes entity-level read permission (`CanRead`) and row-level security key-withholding
+ *   (`ReadIsRowFiltered`) once per unique role fingerprint (`RoleID` set) per event instead of
+ *   re-evaluating permissions $N$ times across all connected WebSocket clients.
+ *
+ * Zero external cloud infrastructure is required.
+ */
+export declare class SequencedRoleBucketBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    get Topology(): CacheInvalidationBroadcastTopology;
+    protected OnInvalidationRecorded(_payload: CacheInvalidationPayload): Promise<void>;
+    NegotiateClientConnection(user: UserInfo, defaultGraphQLWsUrl?: string): Promise<CacheBroadcastNegotiationResult>;
+}
+//# sourceMappingURL=SequencedRoleBucketBroadcastProvider.d.ts.map

package/dist/broadcast/providers/SequencedRoleBucketBroadcastProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SequencedRoleBucketBroadcastProvider.d.ts","sourceRoot":"","sources":["../../../src/broadcast/providers/SequencedRoleBucketBroadcastProvider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EACH,sCAAsC,EACtC,+BAA+B,EAE/B,kCAAkC,EACrC,MAAM,8CAA8C,CAAC;AACtD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4CAA4C,CAAC;AAE3F;;;;;;;;;;;;;;GAcG;AACH,qBACa,oCAAqC,SAAQ,sCAAsC;IAC5F,IAAoB,QAAQ,IAAI,kCAAkC,CAEjE;cAEwB,sBAAsB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5E,yBAAyB,CAC3C,IAAI,EAAE,QAAQ,EACd,mBAAmB,SAAa,GACjC,OAAO,CAAC,+BAA+B,CAAC;CAY9C"}

package/dist/broadcast/providers/SequencedRoleBucketBroadcastProvider.js

@@ -0,0 +1,51 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { BaseCacheInvalidationBroadcastProvider, CacheInvalidationBroadcastManager, } from '../BaseCacheInvalidationBroadcastProvider.js';
+/**
+ * Default MemberJunction cache invalidation broadcast provider (`'SequencedRoleBucket'`).
+ *
+ * Combines:
+ * - **Topology 1 (Monotonic Sequence Ring Buffer + HTTP Header Piggybacking)**:
+ *   Every mutation assigns a monotonic `Sequence` integer, stores the event in a bounded ring buffer,
+ *   and piggybacks `X-MJ-Cache-Seq` and `X-MJ-Server-ID` onto GraphQL HTTP responses so clients can
+ *   detect and recover missed invalidations via `GetCacheInvalidationsSince` in a single delta query.
+ * - **Topology 2 (Role-Fingerprint $O(\text{Roles})$ Evaluation & Shaping Memoizer)**:
+ *   Memoizes entity-level read permission (`CanRead`) and row-level security key-withholding
+ *   (`ReadIsRowFiltered`) once per unique role fingerprint (`RoleID` set) per event instead of
+ *   re-evaluating permissions $N$ times across all connected WebSocket clients.
+ *
+ * Zero external cloud infrastructure is required.
+ */
+let SequencedRoleBucketBroadcastProvider = class SequencedRoleBucketBroadcastProvider extends BaseCacheInvalidationBroadcastProvider {
+    get Topology() {
+        return 'SequencedRoleBucket';
+    }
+    async OnInvalidationRecorded(_payload) {
+        // In-process GraphQL WebSocket subscriptions read directly from PubSub + role-bucket memoizer;
+        // no external cloud multiplexer dispatch is needed in SequencedRoleBucket mode.
+    }
+    async NegotiateClientConnection(user, defaultGraphQLWsUrl = '/graphql') {
+        const fingerprint = this.GetRoleFingerprint(user);
+        const expiresAt = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+        return {
+            Provider: this.Topology,
+            Url: defaultGraphQLWsUrl,
+            Groups: [fingerprint],
+            ExpiresAt: expiresAt,
+            ServerProcessID: this.ServerProcessID,
+            CurrentSequence: this.CurrentSequence,
+        };
+    }
+};
+SequencedRoleBucketBroadcastProvider = __decorate([
+    RegisterClass(BaseCacheInvalidationBroadcastProvider, 'SequencedRoleBucket')
+], SequencedRoleBucketBroadcastProvider);
+export { SequencedRoleBucketBroadcastProvider };
+// Ensure the default provider factory is always registered even if ClassFactory lookup happens early.
+CacheInvalidationBroadcastManager.Instance.RegisterDefaultProviderFactory(() => new SequencedRoleBucketBroadcastProvider());
+//# sourceMappingURL=SequencedRoleBucketBroadcastProvider.js.map