@veloxts/events 0.6.51

package/dist/plugin.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Events Plugin
+ *
+ * Fastify plugin for real-time event broadcasting.
+ * Extends BaseContext with events manager access.
+ */
+import type { FastifyInstance } from 'fastify';
+import '@veloxts/core';
+import type { EventsManager, EventsPluginOptions } from './types.js';
+/**
+ * Extend BaseContext with events manager.
+ *
+ * After registering the events plugin, `ctx.events` becomes available
+ * in all procedures:
+ *
+ * @example
+ * ```typescript
+ * const createOrder = procedure
+ *   .input(CreateOrderSchema)
+ *   .mutation(async ({ input, ctx }) => {
+ *     const order = await ctx.db.order.create({ data: input });
+ *
+ *     // Broadcast order creation
+ *     await ctx.events.broadcast(`orders.${order.userId}`, 'order.created', order);
+ *
+ *     return order;
+ *   });
+ * ```
+ */
+declare module '@veloxts/core' {
+    interface BaseContext {
+        /** Events manager for real-time broadcasting */
+        events: EventsManager;
+    }
+}
+/**
+ * Events plugin for Fastify.
+ *
+ * Registers an events manager and sets up WebSocket/SSE endpoints.
+ *
+ * @param options - Events plugin options (driver configuration)
+ *
+ * @example
+ * ```typescript
+ * import { eventsPlugin } from '@veloxts/events';
+ *
+ * // WebSocket driver (recommended)
+ * app.register(eventsPlugin, {
+ *   driver: 'ws',
+ *   path: '/ws',
+ *   redis: process.env.REDIS_URL, // For horizontal scaling
+ *   authorizer: async (channel, request) => {
+ *     if (channel.type === 'public') return { authorized: true };
+ *     const user = await getUserFromRequest(request);
+ *     if (!user) return { authorized: false, error: 'Not authenticated' };
+ *     return { authorized: true, member: { id: user.id, info: { name: user.name } } };
+ *   },
+ * });
+ *
+ * // SSE driver (fallback for environments without WebSocket)
+ * app.register(eventsPlugin, {
+ *   driver: 'sse',
+ *   path: '/events',
+ * });
+ * ```
+ */
+export declare function eventsPlugin(options?: EventsPluginOptions): (fastify: FastifyInstance) => Promise<void>;
+/**
+ * Get the events manager from a Fastify instance.
+ *
+ * @param fastify - Fastify instance
+ * @returns Events manager
+ * @throws If events plugin is not registered
+ *
+ * @example
+ * ```typescript
+ * const events = getEventsFromInstance(fastify);
+ * await events.broadcast('notifications', 'alert', { message: 'Hello!' });
+ * ```
+ */
+export declare function getEventsFromInstance(fastify: FastifyInstance): EventsManager;
+/**
+ * Get or create a standalone events manager.
+ *
+ * This is useful when you need events access outside of a Fastify request
+ * context, such as in background jobs or CLI commands.
+ *
+ * @param options - Events options (only used on first call)
+ * @returns Events manager instance
+ *
+ * @example
+ * ```typescript
+ * import { getEvents } from '@veloxts/events';
+ *
+ * // In a background job
+ * const events = await getEvents({ driver: 'ws' });
+ * await events.broadcast('jobs', 'completed', { jobId: '123' });
+ * ```
+ */
+export declare function getEvents(options?: EventsPluginOptions): Promise<EventsManager>;
+/**
+ * Reset the standalone events instance.
+ * Primarily used for testing.
+ */
+export declare function _resetStandaloneEvents(): Promise<void>;

package/dist/plugin.js

@@ -0,0 +1,242 @@
+/**
+ * Events Plugin
+ *
+ * Fastify plugin for real-time event broadcasting.
+ * Extends BaseContext with events manager access.
+ */
+import fp from 'fastify-plugin';
+// Side-effect import for declaration merging
+import '@veloxts/core';
+import { createChannelAuthSigner } from './auth.js';
+import { createSseDriver } from './drivers/sse.js';
+import { createWsDriver } from './drivers/ws.js';
+import { createManagerFromDriver } from './manager.js';
+import { formatValidationErrors, SseSubscribeBodySchema, SseUnsubscribeBodySchema, validateBody, WsAuthBodySchema, } from './schemas.js';
+/**
+ * Symbol for accessing events manager from Fastify instance.
+ */
+const EVENTS_KEY = Symbol.for('velox.events');
+/**
+ * Default channel authorizer that allows public channels and denies private/presence.
+ */
+const defaultAuthorizer = (channel) => {
+    // Public channels (no prefix) are allowed
+    if (!channel.name.startsWith('private-') && !channel.name.startsWith('presence-')) {
+        return { authorized: true };
+    }
+    // Private/presence channels require explicit authorization
+    return { authorized: false, error: 'Authentication required' };
+};
+/**
+ * Events plugin for Fastify.
+ *
+ * Registers an events manager and sets up WebSocket/SSE endpoints.
+ *
+ * @param options - Events plugin options (driver configuration)
+ *
+ * @example
+ * ```typescript
+ * import { eventsPlugin } from '@veloxts/events';
+ *
+ * // WebSocket driver (recommended)
+ * app.register(eventsPlugin, {
+ *   driver: 'ws',
+ *   path: '/ws',
+ *   redis: process.env.REDIS_URL, // For horizontal scaling
+ *   authorizer: async (channel, request) => {
+ *     if (channel.type === 'public') return { authorized: true };
+ *     const user = await getUserFromRequest(request);
+ *     if (!user) return { authorized: false, error: 'Not authenticated' };
+ *     return { authorized: true, member: { id: user.id, info: { name: user.name } } };
+ *   },
+ * });
+ *
+ * // SSE driver (fallback for environments without WebSocket)
+ * app.register(eventsPlugin, {
+ *   driver: 'sse',
+ *   path: '/events',
+ * });
+ * ```
+ */
+export function eventsPlugin(options = {}) {
+    return fp(async (fastify) => {
+        const authorizer = options.authorizer ?? defaultAuthorizer;
+        let driver;
+        if (options.driver === 'sse') {
+            const sseOptions = options;
+            const sse = createSseDriver(sseOptions);
+            driver = sse;
+            // Register SSE endpoint
+            const path = sseOptions.path ?? '/events';
+            fastify.get(path, async (request, reply) => {
+                await sse.handler(request, reply);
+            });
+            // Register subscription endpoint with Zod validation
+            fastify.post(`${path}/subscribe`, async (request, reply) => {
+                const validation = validateBody(request.body, SseSubscribeBodySchema);
+                if (!validation.success) {
+                    return reply.status(400).send(formatValidationErrors(validation.errors));
+                }
+                const { connectionId, channel, member } = validation.data;
+                // Authorize the channel
+                const channelInfo = parseChannel(channel);
+                const authResult = await authorizer(channelInfo, request);
+                if (!authResult.authorized) {
+                    return reply.status(403).send({ error: authResult.error ?? 'Unauthorized' });
+                }
+                sse.subscribe(connectionId, channel, authResult.member ?? member);
+                return { success: true };
+            });
+            // Register unsubscribe endpoint with Zod validation
+            fastify.post(`${path}/unsubscribe`, async (request, reply) => {
+                const validation = validateBody(request.body, SseUnsubscribeBodySchema);
+                if (!validation.success) {
+                    return reply.status(400).send(formatValidationErrors(validation.errors));
+                }
+                const { connectionId, channel } = validation.data;
+                sse.unsubscribe(connectionId, channel);
+                return { success: true };
+            });
+        }
+        else {
+            // WebSocket driver (default)
+            const wsOptions = (options.driver === 'ws' ? options : { ...options, driver: 'ws' });
+            const ws = await createWsDriver(wsOptions, { server: fastify.server });
+            driver = ws;
+            // Initialize auth signer if authSecret is provided
+            let authSigner = null;
+            if (options.authSecret) {
+                authSigner = createChannelAuthSigner(options.authSecret);
+            }
+            // Handle WebSocket upgrade
+            const path = wsOptions.path ?? '/ws';
+            fastify.server.on('upgrade', (request, socket, head) => {
+                const url = new URL(request.url ?? '', `http://${request.headers.host}`);
+                if (url.pathname === path) {
+                    ws.handleUpgrade(request, socket, head);
+                }
+            });
+            // Register auth endpoint for private/presence channels with Zod validation
+            fastify.post(`${path}/auth`, async (request, reply) => {
+                const validation = validateBody(request.body, WsAuthBodySchema);
+                if (!validation.success) {
+                    return reply.status(400).send(formatValidationErrors(validation.errors));
+                }
+                const { socketId, channel } = validation.data;
+                const channelInfo = parseChannel(channel);
+                const authResult = await authorizer(channelInfo, request);
+                if (!authResult.authorized) {
+                    return reply.status(403).send({ error: authResult.error ?? 'Unauthorized' });
+                }
+                // Require authSecret for private/presence channels
+                if (!authSigner && channelInfo.type !== 'public') {
+                    return reply.status(500).send({
+                        error: 'Server configuration error: authSecret required for private channels',
+                    });
+                }
+                // For public channels, no signature needed
+                if (channelInfo.type === 'public') {
+                    return { auth: null };
+                }
+                // Generate HMAC-SHA256 signature for secure auth
+                const channelData = authResult.member ? JSON.stringify(authResult.member) : undefined;
+                const signature = authSigner?.sign(socketId, channel, channelData) ?? '';
+                return {
+                    auth: `${socketId}:${signature}`,
+                    channel_data: channelData,
+                };
+            });
+        }
+        // Create events manager
+        const events = createManagerFromDriver(driver);
+        // Store on fastify instance
+        fastify[EVENTS_KEY] = events;
+        // Decorate request with events accessor
+        fastify.decorateRequest('events', {
+            getter() {
+                return events;
+            },
+        });
+        // Register cleanup hook
+        fastify.addHook('onClose', async () => {
+            await events.close();
+        });
+    }, {
+        name: '@veloxts/events',
+        fastify: '5.x',
+    });
+}
+/**
+ * Parse channel name to determine type.
+ */
+function parseChannel(name) {
+    if (name.startsWith('presence-')) {
+        return { name, type: 'presence' };
+    }
+    if (name.startsWith('private-')) {
+        return { name, type: 'private' };
+    }
+    return { name, type: 'public' };
+}
+/**
+ * Get the events manager from a Fastify instance.
+ *
+ * @param fastify - Fastify instance
+ * @returns Events manager
+ * @throws If events plugin is not registered
+ *
+ * @example
+ * ```typescript
+ * const events = getEventsFromInstance(fastify);
+ * await events.broadcast('notifications', 'alert', { message: 'Hello!' });
+ * ```
+ */
+export function getEventsFromInstance(fastify) {
+    const events = fastify[EVENTS_KEY];
+    if (!events) {
+        throw new Error('Events plugin not registered. Register it with: app.register(eventsPlugin, { ... })');
+    }
+    return events;
+}
+// =============================================================================
+// Standalone Usage (outside Fastify context)
+// =============================================================================
+/**
+ * Singleton events instance for standalone usage.
+ */
+let standaloneEvents = null;
+/**
+ * Get or create a standalone events manager.
+ *
+ * This is useful when you need events access outside of a Fastify request
+ * context, such as in background jobs or CLI commands.
+ *
+ * @param options - Events options (only used on first call)
+ * @returns Events manager instance
+ *
+ * @example
+ * ```typescript
+ * import { getEvents } from '@veloxts/events';
+ *
+ * // In a background job
+ * const events = await getEvents({ driver: 'ws' });
+ * await events.broadcast('jobs', 'completed', { jobId: '123' });
+ * ```
+ */
+export async function getEvents(options) {
+    if (!standaloneEvents) {
+        const { createEventsManager } = await import('./manager.js');
+        standaloneEvents = await createEventsManager(options ?? {});
+    }
+    return standaloneEvents;
+}
+/**
+ * Reset the standalone events instance.
+ * Primarily used for testing.
+ */
+export async function _resetStandaloneEvents() {
+    if (standaloneEvents) {
+        await standaloneEvents.close();
+        standaloneEvents = null;
+    }
+}

package/dist/schemas.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Validation Schemas
+ *
+ * Zod schemas for validating request bodies and WebSocket messages.
+ */
+import { z } from 'zod';
+/**
+ * Presence member schema for channel subscriptions.
+ */
+export declare const PresenceMemberSchema: z.ZodObject<{
+    id: z.ZodString;
+    info: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    info?: Record<string, unknown> | undefined;
+}, {
+    id: string;
+    info?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Schema for SSE subscribe endpoint.
+ * POST /events/subscribe
+ */
+export declare const SseSubscribeBodySchema: z.ZodObject<{
+    connectionId: z.ZodString;
+    channel: z.ZodString;
+    member: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        info: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        info?: Record<string, unknown> | undefined;
+    }, {
+        id: string;
+        info?: Record<string, unknown> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    connectionId: string;
+    channel: string;
+    member?: {
+        id: string;
+        info?: Record<string, unknown> | undefined;
+    } | undefined;
+}, {
+    connectionId: string;
+    channel: string;
+    member?: {
+        id: string;
+        info?: Record<string, unknown> | undefined;
+    } | undefined;
+}>;
+export type SseSubscribeBody = z.infer<typeof SseSubscribeBodySchema>;
+/**
+ * Schema for SSE unsubscribe endpoint.
+ * POST /events/unsubscribe
+ */
+export declare const SseUnsubscribeBodySchema: z.ZodObject<{
+    connectionId: z.ZodString;
+    channel: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    connectionId: string;
+    channel: string;
+}, {
+    connectionId: string;
+    channel: string;
+}>;
+export type SseUnsubscribeBody = z.infer<typeof SseUnsubscribeBodySchema>;
+/**
+ * Schema for WebSocket auth endpoint.
+ * POST /ws/auth
+ */
+export declare const WsAuthBodySchema: z.ZodObject<{
+    socketId: z.ZodString;
+    channel: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    channel: string;
+    socketId: string;
+}, {
+    channel: string;
+    socketId: string;
+}>;
+export type WsAuthBody = z.infer<typeof WsAuthBodySchema>;
+/**
+ * Schema for WebSocket client messages.
+ * Uses discriminated union for type-safe message handling.
+ */
+export declare const ClientMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"subscribe">;
+    channel: z.ZodString;
+    auth: z.ZodOptional<z.ZodString>;
+    channelData: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        info: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        info?: Record<string, unknown> | undefined;
+    }, {
+        id: string;
+        info?: Record<string, unknown> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    channel: string;
+    type: "subscribe";
+    auth?: string | undefined;
+    channelData?: string | undefined;
+    data?: {
+        id: string;
+        info?: Record<string, unknown> | undefined;
+    } | undefined;
+}, {
+    channel: string;
+    type: "subscribe";
+    auth?: string | undefined;
+    channelData?: string | undefined;
+    data?: {
+        id: string;
+        info?: Record<string, unknown> | undefined;
+    } | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"unsubscribe">;
+    channel: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    channel: string;
+    type: "unsubscribe";
+}, {
+    channel: string;
+    type: "unsubscribe";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+}, "strip", z.ZodTypeAny, {
+    type: "ping";
+}, {
+    type: "ping";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"message">;
+    channel: z.ZodString;
+    event: z.ZodString;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    channel: string;
+    type: "message";
+    event: string;
+    data?: unknown;
+}, {
+    channel: string;
+    type: "message";
+    event: string;
+    data?: unknown;
+}>]>;
+export type ValidatedClientMessage = z.infer<typeof ClientMessageSchema>;
+/**
+ * Validation result type - discriminated union for type-safe error handling.
+ */
+export type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: z.ZodIssue[];
+};
+/**
+ * Validate request body against a Zod schema.
+ * Returns a discriminated union for type-safe error handling.
+ *
+ * @template TSchema - The Zod schema type
+ */
+export declare function validateBody<TSchema extends z.ZodTypeAny>(body: unknown, schema: TSchema): ValidationResult<z.infer<TSchema>>;
+/**
+ * Format Zod validation errors for API response.
+ */
+export declare function formatValidationErrors(errors: z.ZodIssue[]): {
+    error: string;
+    details: Array<{
+        path: string;
+        message: string;
+    }>;
+};

package/dist/schemas.js

@@ -0,0 +1,101 @@
+/**
+ * Validation Schemas
+ *
+ * Zod schemas for validating request bodies and WebSocket messages.
+ */
+import { z } from 'zod';
+// =============================================================================
+// Presence Member Schema
+// =============================================================================
+/**
+ * Presence member schema for channel subscriptions.
+ */
+export const PresenceMemberSchema = z.object({
+    id: z.string().min(1, 'Member ID is required'),
+    info: z.record(z.unknown()).optional(),
+});
+// =============================================================================
+// SSE Endpoint Schemas
+// =============================================================================
+/**
+ * Schema for SSE subscribe endpoint.
+ * POST /events/subscribe
+ */
+export const SseSubscribeBodySchema = z.object({
+    connectionId: z.string().min(1, 'Connection ID is required'),
+    channel: z.string().min(1, 'Channel name is required'),
+    member: PresenceMemberSchema.optional(),
+});
+/**
+ * Schema for SSE unsubscribe endpoint.
+ * POST /events/unsubscribe
+ */
+export const SseUnsubscribeBodySchema = z.object({
+    connectionId: z.string().min(1, 'Connection ID is required'),
+    channel: z.string().min(1, 'Channel name is required'),
+});
+// =============================================================================
+// WebSocket Endpoint Schemas
+// =============================================================================
+/**
+ * Schema for WebSocket auth endpoint.
+ * POST /ws/auth
+ */
+export const WsAuthBodySchema = z.object({
+    socketId: z.string().min(1, 'Socket ID is required'),
+    channel: z.string().min(1, 'Channel name is required'),
+});
+// =============================================================================
+// WebSocket Client Message Schemas
+// =============================================================================
+/**
+ * Schema for WebSocket client messages.
+ * Uses discriminated union for type-safe message handling.
+ */
+export const ClientMessageSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('subscribe'),
+        channel: z.string().min(1),
+        auth: z.string().optional(),
+        channelData: z.string().optional(),
+        data: PresenceMemberSchema.optional(),
+    }),
+    z.object({
+        type: z.literal('unsubscribe'),
+        channel: z.string().min(1),
+    }),
+    z.object({
+        type: z.literal('ping'),
+    }),
+    z.object({
+        type: z.literal('message'),
+        channel: z.string().min(1),
+        event: z.string().min(1),
+        data: z.unknown().optional(),
+    }),
+]);
+/**
+ * Validate request body against a Zod schema.
+ * Returns a discriminated union for type-safe error handling.
+ *
+ * @template TSchema - The Zod schema type
+ */
+export function validateBody(body, schema) {
+    const result = schema.safeParse(body);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, errors: result.error.issues };
+}
+/**
+ * Format Zod validation errors for API response.
+ */
+export function formatValidationErrors(errors) {
+    return {
+        error: 'Validation failed',
+        details: errors.map((issue) => ({
+            path: issue.path.join('.'),
+            message: issue.message,
+        })),
+    };
+}