@gravito/radiance 1.0.3 → 1.0.5

package/dist/radiance/src/BroadcastManager.d.ts

@@ -0,0 +1,124 @@
+import type { PlanetCore } from '@gravito/core';
+import type { BroadcastDriver } from './drivers/BroadcastDriver';
+/**
+ * Channel authorization callback.
+ *
+ * Used to verify if a user has permission to join a specific broadcast channel.
+ *
+ * @param channel - The name of the channel to authorize
+ * @param socketId - The unique identifier for the client connection
+ * @param userId - The identifier of the user requesting access
+ * @returns True if the user is authorized to join the channel
+ */
+export type ChannelAuthorizationCallback = (channel: string, socketId: string, userId?: string | number) => Promise<boolean>;
+/**
+ * Central manager for real-time event broadcasting.
+ *
+ * Orchestrates the delivery of events to various broadcast drivers and handles
+ * channel authorization logic. It acts as a bridge between Gravito's event system
+ * and external real-time services.
+ *
+ * @example
+ * ```typescript
+ * const manager = new BroadcastManager(core);
+ * manager.setDriver(new PusherDriver(config));
+ * await manager.broadcast(null, { name: 'orders', type: 'public' }, { id: 1 }, 'OrderCreated');
+ * ```
+ */
+export declare class BroadcastManager {
+    private core;
+    private driver;
+    private authCallback?;
+    private throwOnError;
+    constructor(core: PlanetCore);
+    /**
+     * Configure error handling behavior for broadcast operations.
+     *
+     * Determines whether failures in the underlying broadcast driver should
+     * propagate as exceptions or be silently logged.
+     *
+     * @param throwOnError - Enable or disable exception propagation on failure
+     *
+     * @example
+     * ```typescript
+     * manager.setThrowOnError(false); // Log errors instead of throwing
+     * ```
+     */
+    setThrowOnError(throwOnError: boolean): void;
+    /**
+     * Assign the active broadcast delivery driver.
+     *
+     * Sets the driver responsible for the actual transmission of event data
+     * to the real-time service (e.g., Pusher, Ably, Redis).
+     *
+     * @param driver - The broadcast driver implementation to use
+     *
+     * @example
+     * ```typescript
+     * manager.setDriver(new RedisDriver(config));
+     * ```
+     */
+    setDriver(driver: BroadcastDriver): void;
+    /**
+     * Register a custom authorization logic for private channels.
+     *
+     * Provides a hook to implement business-specific permission checks
+     * before allowing a client to subscribe to restricted channels.
+     *
+     * @param callback - The authorization logic implementation
+     *
+     * @example
+     * ```typescript
+     * manager.setAuthCallback(async (channel, socketId, userId) => {
+     *   return userId === 'admin';
+     * });
+     * ```
+     */
+    setAuthCallback(callback: ChannelAuthorizationCallback): void;
+    /**
+     * Transmit an event payload to a specific channel.
+     *
+     * Forwards the event data to the configured driver. If no driver is set,
+     * the broadcast is skipped with a warning.
+     *
+     * @param _event - The original event instance (reserved for future use)
+     * @param channel - Target channel metadata including name and visibility type
+     * @param data - The serializable payload to be transmitted
+     * @param eventName - The name of the event as it will appear on the client
+     * @throws {Error} If the driver fails and throwOnError is enabled
+     *
+     * @example
+     * ```typescript
+     * await manager.broadcast(
+     *   null,
+     *   { name: 'private-user.1', type: 'private' },
+     *   { message: 'Hello' },
+     *   'UserMessage'
+     * );
+     * ```
+     */
+    broadcast(_event: unknown, channel: {
+        name: string;
+        type: string;
+    }, data: Record<string, unknown>, eventName: string): Promise<void>;
+    /**
+     * Validate client access to a specific channel.
+     *
+     * Executes the registered authorization callback and, if available,
+     * delegates to the driver's native authorization mechanism.
+     *
+     * @param channel - The name of the channel to authorize
+     * @param socketId - The unique identifier for the client connection
+     * @param userId - The identifier of the user requesting access
+     * @returns The authorization payload or null if access is denied
+     *
+     * @example
+     * ```typescript
+     * const auth = await manager.authorizeChannel('private-user.1', '123.456', 'user_1');
+     * ```
+     */
+    authorizeChannel(channel: string, socketId: string, userId?: string | number): Promise<{
+        auth: string;
+        channel_data?: string;
+    } | null>;
+}

package/dist/radiance/src/OrbitRadiance.d.ts

@@ -0,0 +1,98 @@
+import type { GravitoOrbit, PlanetCore } from '@gravito/core';
+import { BroadcastManager } from './BroadcastManager';
+import type { AblyDriverConfig } from './drivers/AblyDriver';
+import type { PusherDriverConfig } from './drivers/PusherDriver';
+import type { RedisDriverConfig } from './drivers/RedisDriver';
+import type { WebSocketDriverConfig } from './drivers/WebSocketDriver';
+/**
+ * Configuration options for the Radiance broadcasting orbit.
+ *
+ * Defines the delivery provider, its specific credentials, and optional
+ * hooks for security and error handling.
+ *
+ * @public
+ */
+export interface OrbitRadianceOptions {
+    /**
+     * The underlying delivery service provider.
+     *
+     * - pusher: Industry standard WebSocket service
+     * - ably: High-reliability global edge network
+     * - redis: Pub/Sub for internal microservices
+     * - websocket: Direct server-to-client communication
+     */
+    driver: 'pusher' | 'ably' | 'redis' | 'websocket';
+    /**
+     * Provider-specific connection and authentication settings.
+     */
+    config: PusherDriverConfig | AblyDriverConfig | RedisDriverConfig | WebSocketDriverConfig;
+    /**
+     * Hook for implementing custom channel access control.
+     *
+     * @param channel - The name of the channel being accessed
+     * @param socketId - The unique client connection identifier
+     * @param userId - The authenticated user's identifier
+     * @returns True if the subscription request should be granted
+     */
+    authorizeChannel?: (channel: string, socketId: string, userId?: string | number) => Promise<boolean>;
+    /**
+     * Control whether broadcast failures should interrupt the execution flow.
+     * @defaultValue true
+     */
+    throwOnError?: boolean;
+}
+/**
+ * OrbitRadiance provides real-time event broadcasting capabilities.
+ *
+ * It abstracts various delivery providers (Pusher, Ably, etc.) and integrates
+ * seamlessly with Gravito's Event system. When installed, it enables automatic
+ * broadcasting of events that implement the `ShouldBroadcast` interface.
+ *
+ * @example
+ * ```typescript
+ * const radiance = OrbitRadiance.configure({
+ *   driver: 'pusher',
+ *   config: { appId: '...', key: '...', secret: '...' }
+ * });
+ * core.addOrbit(radiance);
+ * ```
+ * @public
+ */
+export declare class OrbitRadiance implements GravitoOrbit {
+    private options;
+    constructor(options: OrbitRadianceOptions);
+    /**
+     * Create a new OrbitRadiance instance with the specified configuration.
+     *
+     * This static factory method is the preferred way to initialize the orbit
+     * before adding it to the PlanetCore.
+     *
+     * @param options - The configuration settings for the broadcaster
+     * @returns A configured OrbitRadiance instance
+     *
+     * @example
+     * ```typescript
+     * const orbit = OrbitRadiance.configure({
+     *   driver: 'redis',
+     *   config: { url: 'redis://localhost:6379' }
+     * });
+     * ```
+     */
+    static configure(options: OrbitRadianceOptions): OrbitRadiance;
+    /**
+     * Initialize and register the broadcasting system into the core.
+     *
+     * Sets up the BroadcastManager, initializes the selected driver, and
+     * hooks into the EventManager to enable automatic event broadcasting.
+     *
+     * @param core - The PlanetCore instance where the orbit is being installed
+     * @throws {Error} If an unsupported driver is specified in options
+     */
+    install(core: PlanetCore): Promise<void>;
+}
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Broadcaster manager for real-time events */
+        broadcast?: BroadcastManager;
+    }
+}

package/dist/radiance/src/channels/Channel.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Base channel interface representing a broadcast destination.
+ *
+ * Channels segregate broadcast traffic. Different channel types imply different
+ * access control rules and behaviors.
+ */
+export interface Channel {
+    /**
+     * The unique identifier for the channel.
+     *
+     * @remarks
+     * For private/presence channels, this typically includes a prefix like 'private-' or 'presence-'.
+     */
+    name: string;
+    /**
+     * The security level and behavior type of the channel.
+     */
+    type: 'public' | 'private' | 'presence';
+}
+/**
+ * A public channel open to any subscriber.
+ *
+ * Public channels require no authorization. Any client can subscribe and listen
+ * to events broadcast on these channels.
+ *
+ * @example
+ * ```typescript
+ * const channel = new PublicChannel('orders');
+ * ```
+ */
+export declare class PublicChannel implements Channel {
+    name: string;
+    type: "public";
+    /**
+     * Creates a new PublicChannel instance.
+     *
+     * @param name - The name of the channel (without prefixes).
+     */
+    constructor(name: string);
+}
+/**
+ * A private channel requiring authorization.
+ *
+ * Private channels are secured and require the client to provide an authentication
+ * signature (usually via an auth endpoint) before subscription is allowed.
+ * Suitable for sensitive user data.
+ *
+ * @example
+ * ```typescript
+ * const channel = new PrivateChannel('user.123');
+ * // Driver may prefix this as 'private-user.123'
+ * ```
+ */
+export declare class PrivateChannel implements Channel {
+    name: string;
+    type: "private";
+    /**
+     * Creates a new PrivateChannel instance.
+     *
+     * @param name - The name of the channel.
+     */
+    constructor(name: string);
+}
+/**
+ * A presence channel that tracks online users.
+ *
+ * Presence channels extend private channels by adding the ability to know *who*
+ * is subscribed. They are commonly used for chat rooms, "user is typing" indicators,
+ * and online user lists.
+ *
+ * @example
+ * ```typescript
+ * const channel = new PresenceChannel('chat.room.1');
+ * // Driver may prefix this as 'presence-chat.room.1'
+ * ```
+ */
+export declare class PresenceChannel implements Channel {
+    name: string;
+    type: "presence";
+    /**
+     * Creates a new PresenceChannel instance.
+     *
+     * @param name - The name of the channel.
+     */
+    constructor(name: string);
+}

package/dist/radiance/src/drivers/AblyDriver.d.ts

@@ -0,0 +1,73 @@
+import type { BroadcastDriver } from './BroadcastDriver';
+/**
+ * Configuration options for the Ably broadcast driver.
+ */
+export interface AblyDriverConfig {
+    /**
+     * The Ably API key.
+     *
+     * Format: "appId.keyId:secret"
+     */
+    apiKey: string;
+}
+/**
+ * Ably broadcast driver implementation.
+ *
+ * Uses the Ably REST API to publish messages to channels.
+ * Suitable for high-reliability global messaging without managing infrastructure.
+ *
+ * @remarks
+ * This driver uses standard HTTP fetch for publishing and does not require the full Ably SDK.
+ * Presence authorization is implemented using a basic compatible format.
+ *
+ * @example
+ * ```typescript
+ * const driver = new AblyDriver({
+ *   apiKey: 'APP_ID.KEY_ID:SECRET'
+ * });
+ * ```
+ */
+export declare class AblyDriver implements BroadcastDriver {
+    private config;
+    private baseUrl;
+    /**
+     * Creates a new AblyDriver instance.
+     *
+     * @param config - The Ably connection configuration.
+     */
+    constructor(config: AblyDriverConfig);
+    /**
+     * Broadcast an event to an Ably channel.
+     *
+     * @param channel - The target channel metadata.
+     * @param event - The name of the event.
+     * @param data - The event payload.
+     * @throws {Error} If the Ably API request fails.
+     *
+     * @example
+     * ```typescript
+     * await driver.broadcast({ name: 'orders', type: 'public' }, 'OrderCreated', { id: 123 });
+     * ```
+     */
+    broadcast(channel: {
+        name: string;
+        type: string;
+    }, event: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Authorize a client for a private or presence channel.
+     *
+     * @param channel - The channel name.
+     * @param _socketId - The socket ID (unused by Ably REST auth in this simple mode).
+     * @param userId - The user ID (used for presence).
+     * @returns The authorization object.
+     *
+     * @example
+     * ```typescript
+     * const auth = await driver.authorizeChannel('presence-chat', 'socket-1', 'user-1');
+     * ```
+     */
+    authorizeChannel(channel: string, _socketId: string, userId?: string | number): Promise<{
+        auth: string;
+        channel_data?: string;
+    }>;
+}

package/dist/radiance/src/drivers/BroadcastDriver.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Interface defining the contract for all broadcast drivers.
+ *
+ * Implementations of this interface serve as adapters for specific real-time
+ * messaging services (e.g., Pusher, Ably, Redis).
+ */
+export interface BroadcastDriver {
+    /**
+     * Broadcast an event to a specific channel.
+     *
+     * @param channel - The target channel metadata (name and type).
+     * @param event - The name of the event being broadcast.
+     * @param data - The payload data associated with the event.
+     * @throws {Error} If the underlying provider fails to accept the message.
+     *
+     * @example
+     * ```typescript
+     * await driver.broadcast(
+     *   { name: 'orders', type: 'public' },
+     *   'OrderCreated',
+     *   { id: 1 }
+     * );
+     * ```
+     */
+    broadcast(channel: {
+        name: string;
+        type: string;
+    }, event: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Authorize a client to access a restricted channel.
+     *
+     * Used for private and presence channels to generate the necessary
+     * authentication signature required by the client SDK.
+     *
+     * @param channel - The name of the channel to authorize.
+     * @param socketId - The unique socket ID provided by the client.
+     * @param userId - The identifier of the user (optional).
+     * @returns A promise resolving to the auth payload expected by the client.
+     *
+     * @example
+     * ```typescript
+     * const auth = await driver.authorizeChannel('private-user.1', 'socket-123', 'user-1');
+     * // Returns { auth: "key:signature" }
+     * ```
+     */
+    authorizeChannel?(channel: string, socketId: string, userId?: string | number): Promise<{
+        auth: string;
+        channel_data?: string;
+    }>;
+}

package/dist/radiance/src/drivers/PusherDriver.d.ts

@@ -0,0 +1,95 @@
+import type { BroadcastDriver } from './BroadcastDriver';
+/**
+ * Configuration for the Pusher broadcast driver.
+ */
+export interface PusherDriverConfig {
+    /**
+     * The application ID provided by Pusher.
+     */
+    appId: string;
+    /**
+     * The public application key.
+     */
+    key: string;
+    /**
+     * The secret key for signing requests.
+     */
+    secret: string;
+    /**
+     * The Pusher cluster to connect to (e.g., 'mt1', 'eu').
+     * @defaultValue 'mt1'
+     */
+    cluster?: string;
+    /**
+     * Whether to force TLS (HTTPS) for API requests.
+     * @defaultValue true
+     */
+    useTLS?: boolean;
+}
+/**
+ * Pusher broadcast driver implementation.
+ *
+ * Interacts with the Pusher HTTP API to trigger events on channels.
+ * It handles request signing, authentication generation for private channels,
+ * and HTTP communication using the native Fetch API.
+ *
+ * @remarks
+ * This driver avoids heavy dependencies by implementing the necessary crypto
+ * signatures (HMAC-SHA256 and MD5) using standard Web Crypto or Bun APIs.
+ *
+ * @example
+ * ```typescript
+ * const driver = new PusherDriver({
+ *   appId: '123456',
+ *   key: 'my-app-key',
+ *   secret: 'my-app-secret',
+ *   cluster: 'us2'
+ * });
+ * ```
+ */
+export declare class PusherDriver implements BroadcastDriver {
+    private config;
+    private baseUrl;
+    /**
+     * Creates a new PusherDriver instance.
+     *
+     * @param config - The Pusher connection configuration.
+     */
+    constructor(config: PusherDriverConfig);
+    /**
+     * Broadcast an event to a channel via the Pusher API.
+     *
+     * @param channel - The target channel metadata.
+     * @param event - The name of the event.
+     * @param data - The event payload.
+     * @throws {Error} If the Pusher API returns a non-200 response.
+     *
+     * @example
+     * ```typescript
+     * await driver.broadcast({ name: 'news', type: 'public' }, 'BreakingNews', { title: 'Hello' });
+     * ```
+     */
+    broadcast(channel: {
+        name: string;
+        type: string;
+    }, event: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Generate an authorization signature for private or presence channels.
+     *
+     * @param channel - The name of the channel.
+     * @param socketId - The client's socket ID.
+     * @param userId - The user ID (required for presence channels).
+     * @returns The auth object expected by Pusher client libraries.
+     *
+     * @example
+     * ```typescript
+     * const auth = await driver.authorizeChannel('private-user.1', '123.456');
+     * ```
+     */
+    authorizeChannel(channel: string, socketId: string, userId?: string | number): Promise<{
+        auth: string;
+        channel_data?: string;
+    }>;
+    private hmacSHA256;
+    private md5;
+}

package/dist/radiance/src/drivers/RedisDriver.d.ts

@@ -0,0 +1,83 @@
+import type { BroadcastDriver } from './BroadcastDriver';
+/**
+ * Configuration options for the Redis broadcast driver.
+ */
+export interface RedisDriverConfig {
+    /**
+     * The Redis connection URL.
+     * @example 'redis://localhost:6379'
+     */
+    url?: string;
+    /**
+     * The Redis host address.
+     */
+    host?: string;
+    /**
+     * The Redis port number.
+     */
+    port?: number;
+    /**
+     * The Redis password for authentication.
+     */
+    password?: string;
+    /**
+     * The Redis database index.
+     */
+    db?: number;
+    /**
+     * The prefix to use for Pub/Sub channels.
+     * @defaultValue 'gravito:broadcast:'
+     */
+    keyPrefix?: string;
+}
+/**
+ * Redis broadcast driver implementation.
+ *
+ * Leverages Redis Pub/Sub to broadcast messages. This is ideal for internal
+ * microservices or when managing your own WebSocket server fleet that subscribes to Redis.
+ *
+ * @remarks
+ * This driver is an adapter and requires an external Redis client instance to be injected.
+ * It is compatible with any Redis client that exposes a `publish` method.
+ *
+ * @example
+ * ```typescript
+ * const driver = new RedisDriver({ keyPrefix: 'app:' });
+ * driver.setRedisClient(redis);
+ * ```
+ */
+export declare class RedisDriver implements BroadcastDriver {
+    private config;
+    private redis;
+    /**
+     * Creates a new RedisDriver instance.
+     *
+     * @param config - The Redis configuration options.
+     */
+    constructor(config: RedisDriverConfig);
+    /**
+     * Inject the Redis client instance.
+     *
+     * @param client - A compatible Redis client (must have a publish method).
+     */
+    setRedisClient(client: {
+        publish(channel: string, message: string): Promise<number>;
+    }): void;
+    /**
+     * Broadcast an event to a Redis channel.
+     *
+     * @param channel - The target channel metadata.
+     * @param event - The name of the event.
+     * @param data - The event payload.
+     * @throws {Error} If the Redis client has not been set.
+     *
+     * @example
+     * ```typescript
+     * await driver.broadcast({ name: 'system', type: 'public' }, 'Alert', { msg: 'Down' });
+     * ```
+     */
+    broadcast(channel: {
+        name: string;
+        type: string;
+    }, event: string, data: Record<string, unknown>): Promise<void>;
+}

package/dist/radiance/src/drivers/WebSocketDriver.d.ts

@@ -0,0 +1,89 @@
+import type { Logger } from '@gravito/core';
+import type { BroadcastDriver } from './BroadcastDriver';
+/**
+ * Interface representing a WebSocket connection.
+ *
+ * Abstracts the native WebSocket or similar connection object to allow
+ * different underlying implementations (e.g., standard WebSocket, uWebSockets.js).
+ */
+export interface WebSocketConnection {
+    /**
+     * Send a message to the client.
+     *
+     * @param data - The stringified message payload.
+     */
+    send(data: string): void;
+    /**
+     * Close the connection.
+     */
+    close(): void;
+    /**
+     * The current state of the connection (1 = OPEN).
+     */
+    readyState: number;
+}
+/**
+ * Configuration for the WebSocket broadcast driver.
+ */
+export interface WebSocketDriverConfig {
+    /**
+     * Retrieve all active WebSocket connections.
+     *
+     * This function is called on every broadcast to get the list of recipients.
+     */
+    getConnections(): WebSocketConnection[];
+    /**
+     * Optional strategy to filter connections based on channel subscriptions.
+     *
+     * @param channel - The name of the channel to filter by.
+     */
+    filterConnectionsByChannel?(channel: string): WebSocketConnection[];
+    /**
+     * Logger instance for reporting broadcast failures.
+     */
+    logger?: Logger;
+}
+/**
+ * Native WebSocket broadcast driver.
+ *
+ * Broadcasts events directly to connected WebSocket clients.
+ * Ideal for single-node deployments or simple setups where you want to
+ * avoid external dependencies like Pusher or Redis.
+ *
+ * @remarks
+ * This driver iterates over all (or filtered) connections and sends the message.
+ * It is not scalable across multiple nodes without an additional sync mechanism (like Redis).
+ *
+ * @example
+ * ```typescript
+ * const driver = new WebSocketDriver({
+ *   getConnections: () => Array.from(wss.clients),
+ *   logger: console
+ * });
+ * ```
+ */
+export declare class WebSocketDriver implements BroadcastDriver {
+    private config;
+    /**
+     * Creates a new WebSocketDriver instance.
+     *
+     * @param config - Driver configuration.
+     */
+    constructor(config: WebSocketDriverConfig);
+    /**
+     * Broadcast an event to WebSocket clients.
+     *
+     * @param channel - The target channel metadata.
+     * @param event - The name of the event.
+     * @param data - The event payload.
+     *
+     * @example
+     * ```typescript
+     * await driver.broadcast({ name: 'chat', type: 'public' }, 'NewMessage', { text: 'Hi' });
+     * ```
+     */
+    broadcast(channel: {
+        name: string;
+        type: string;
+    }, event: string, data: Record<string, unknown>): Promise<void>;
+}