@portel/photon-core 2.1.2 → 2.3.0

package/src/channels/redis-broker.ts

@@ -0,0 +1,252 @@
+/**
+ * Redis Channel Broker
+ *
+ * Uses Redis pub/sub for cross-process and cross-server messaging.
+ *
+ * Best for:
+ * - Multi-server deployments
+ * - Cloud environments (AWS, GCP, etc.)
+ * - High-throughput scenarios
+ *
+ * Requires: ioredis package (optional dependency)
+ */
+
+import type { ChannelBroker, ChannelMessage, ChannelHandler, Subscription } from './types.js';
+import { registerBroker } from './registry.js';
+
+export interface RedisBrokerOptions {
+  /** Redis connection URL (redis://host:port) */
+  url?: string;
+  /** Channel prefix for namespacing */
+  prefix?: string;
+  /** Redis client options (passed to ioredis) */
+  clientOptions?: Record<string, unknown>;
+}
+
+// Lazy-load Redis to make it optional
+let Redis: any = null;
+
+async function getRedis(): Promise<any> {
+  if (!Redis) {
+    try {
+      // Dynamic import to avoid bundling redis if not used
+      // @ts-ignore - ioredis is an optional peer dependency
+      const module = await import('ioredis');
+      Redis = module.default || module;
+    } catch {
+      throw new Error(
+        'Redis broker requires ioredis package. Install it with: npm install ioredis'
+      );
+    }
+  }
+  return Redis;
+}
+
+export class RedisBroker implements ChannelBroker {
+  readonly type = 'redis';
+
+  private url: string;
+  private prefix: string;
+  private clientOptions: Record<string, unknown>;
+  private pubClient: any = null;
+  private subClient: any = null;
+  private connected = false;
+  private subscriptions = new Map<string, Set<ChannelHandler>>();
+
+  constructor(options: RedisBrokerOptions = {}) {
+    this.url = options.url || process.env.PHOTON_REDIS_URL || process.env.REDIS_URL || 'redis://localhost:6379';
+    this.prefix = options.prefix || process.env.PHOTON_REDIS_PREFIX || 'photon:channel:';
+    this.clientOptions = options.clientOptions || {};
+  }
+
+  private getChannelKey(channel: string): string {
+    return `${this.prefix}${channel}`;
+  }
+
+  async connect(): Promise<void> {
+    if (this.connected) return;
+
+    const RedisClient = await getRedis();
+
+    // Create publish client
+    this.pubClient = new RedisClient(this.url, {
+      ...this.clientOptions,
+      lazyConnect: true,
+    });
+
+    // Create subscribe client (Redis requires separate connections for pub/sub)
+    this.subClient = new RedisClient(this.url, {
+      ...this.clientOptions,
+      lazyConnect: true,
+    });
+
+    // Connect both clients
+    await Promise.all([
+      this.pubClient.connect(),
+      this.subClient.connect(),
+    ]);
+
+    // Handle incoming messages
+    this.subClient.on('message', (redisChannel: string, messageStr: string) => {
+      // Strip prefix to get original channel
+      const channel = redisChannel.startsWith(this.prefix)
+        ? redisChannel.slice(this.prefix.length)
+        : redisChannel;
+
+      const handlers = this.subscriptions.get(channel);
+      if (!handlers || handlers.size === 0) return;
+
+      try {
+        const message: ChannelMessage = JSON.parse(messageStr);
+        handlers.forEach((handler) => {
+          try {
+            handler(message);
+          } catch (err) {
+            console.error('Error in channel handler:', err);
+          }
+        });
+      } catch (err) {
+        console.error('Error parsing channel message:', err);
+      }
+    });
+
+    // Handle pattern messages (for wildcard subscriptions)
+    this.subClient.on('pmessage', (pattern: string, redisChannel: string, messageStr: string) => {
+      const channel = redisChannel.startsWith(this.prefix)
+        ? redisChannel.slice(this.prefix.length)
+        : redisChannel;
+
+      // Find matching pattern handlers
+      for (const [subPattern, handlers] of this.subscriptions) {
+        if (this.matchPattern(subPattern, channel)) {
+          try {
+            const message: ChannelMessage = JSON.parse(messageStr);
+            handlers.forEach((handler) => {
+              try {
+                handler(message);
+              } catch (err) {
+                console.error('Error in channel handler:', err);
+              }
+            });
+          } catch (err) {
+            console.error('Error parsing channel message:', err);
+          }
+        }
+      }
+    });
+
+    this.connected = true;
+  }
+
+  /**
+   * Simple wildcard pattern matching
+   * Supports * for single-segment wildcard
+   */
+  private matchPattern(pattern: string, channel: string): boolean {
+    if (!pattern.includes('*')) {
+      return pattern === channel;
+    }
+
+    const patternParts = pattern.split(':');
+    const channelParts = channel.split(':');
+
+    if (patternParts.length !== channelParts.length) {
+      return false;
+    }
+
+    return patternParts.every((part, i) => part === '*' || part === channelParts[i]);
+  }
+
+  async disconnect(): Promise<void> {
+    if (!this.connected) return;
+
+    // Unsubscribe from all channels
+    for (const channel of this.subscriptions.keys()) {
+      const redisChannel = this.getChannelKey(channel);
+      if (channel.includes('*')) {
+        await this.subClient.punsubscribe(redisChannel);
+      } else {
+        await this.subClient.unsubscribe(redisChannel);
+      }
+    }
+    this.subscriptions.clear();
+
+    // Disconnect clients
+    await Promise.all([
+      this.pubClient?.quit(),
+      this.subClient?.quit(),
+    ]);
+
+    this.pubClient = null;
+    this.subClient = null;
+    this.connected = false;
+  }
+
+  async publish(message: ChannelMessage): Promise<void> {
+    if (!this.connected) {
+      await this.connect();
+    }
+
+    const redisChannel = this.getChannelKey(message.channel);
+    const payload: ChannelMessage = {
+      ...message,
+      timestamp: message.timestamp || Date.now(),
+    };
+
+    await this.pubClient.publish(redisChannel, JSON.stringify(payload));
+  }
+
+  async subscribe(channel: string, handler: ChannelHandler): Promise<Subscription> {
+    if (!this.connected) {
+      await this.connect();
+    }
+
+    const redisChannel = this.getChannelKey(channel);
+    const isPattern = channel.includes('*');
+
+    // Track handler
+    if (!this.subscriptions.has(channel)) {
+      this.subscriptions.set(channel, new Set());
+
+      // Subscribe to Redis channel
+      if (isPattern) {
+        await this.subClient.psubscribe(redisChannel);
+      } else {
+        await this.subClient.subscribe(redisChannel);
+      }
+    }
+    this.subscriptions.get(channel)!.add(handler);
+
+    const subscription: Subscription = {
+      channel,
+      active: true,
+      unsubscribe: async () => {
+        subscription.active = false;
+        const handlers = this.subscriptions.get(channel);
+        if (handlers) {
+          handlers.delete(handler);
+          if (handlers.size === 0) {
+            this.subscriptions.delete(channel);
+            // Unsubscribe from Redis
+            if (isPattern) {
+              await this.subClient.punsubscribe(redisChannel);
+            } else {
+              await this.subClient.unsubscribe(redisChannel);
+            }
+          }
+        }
+      },
+    };
+
+    return subscription;
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+}
+
+// Register the broker
+registerBroker('redis', (options) => new RedisBroker(options as RedisBrokerOptions));
+
+export default RedisBroker;

package/src/channels/registry.ts

@@ -0,0 +1,170 @@
+/**
+ * Channel Broker Registry
+ *
+ * Manages registration and selection of channel brokers.
+ * Auto-detects the appropriate broker based on environment configuration.
+ */
+
+import type { ChannelBroker, BrokerConfig, BrokerFactory } from './types.js';
+
+/**
+ * Registry of available broker factories
+ */
+const brokerFactories = new Map<string, BrokerFactory>();
+
+/**
+ * Current active broker instance
+ */
+let activeBroker: ChannelBroker | null = null;
+
+/**
+ * Register a broker factory
+ * @param type Broker type identifier (e.g., 'redis', 'daemon', 'http')
+ * @param factory Factory function that creates the broker
+ */
+export function registerBroker(type: string, factory: BrokerFactory): void {
+  brokerFactories.set(type, factory);
+}
+
+/**
+ * Get a list of registered broker types
+ */
+export function getRegisteredBrokers(): string[] {
+  return Array.from(brokerFactories.keys());
+}
+
+/**
+ * Create a broker instance by type
+ * @param type Broker type
+ * @param options Type-specific options
+ */
+export function createBroker(type: string, options?: Record<string, unknown>): ChannelBroker {
+  const factory = brokerFactories.get(type);
+  if (!factory) {
+    throw new Error(
+      `Unknown broker type: ${type}. Available types: ${getRegisteredBrokers().join(', ')}`
+    );
+  }
+  return factory(options);
+}
+
+/**
+ * Auto-detect and create the appropriate broker based on environment
+ *
+ * Detection order:
+ * 1. PHOTON_CHANNEL_BROKER env var (explicit override)
+ * 2. PHOTON_REDIS_URL → Redis broker
+ * 3. PHOTON_CHANNEL_HTTP_URL → HTTP broker
+ * 4. PHOTON_CLOUDFLARE_* → Cloudflare broker
+ * 5. Default → NoOp broker (silent, no-op)
+ */
+export function detectBroker(): ChannelBroker {
+  // Explicit broker type override
+  const explicitType = process.env.PHOTON_CHANNEL_BROKER;
+  if (explicitType) {
+    return createBrokerFromEnv(explicitType);
+  }
+
+  // Redis detection
+  if (process.env.PHOTON_REDIS_URL || process.env.REDIS_URL) {
+    try {
+      return createBrokerFromEnv('redis');
+    } catch {
+      // Redis broker not available, continue
+    }
+  }
+
+  // HTTP webhook detection
+  if (process.env.PHOTON_CHANNEL_HTTP_URL) {
+    try {
+      return createBrokerFromEnv('http');
+    } catch {
+      // HTTP broker not available, continue
+    }
+  }
+
+  // Cloudflare detection
+  if (process.env.PHOTON_CLOUDFLARE_ACCOUNT_ID || process.env.CF_ACCOUNT_ID) {
+    try {
+      return createBrokerFromEnv('cloudflare');
+    } catch {
+      // Cloudflare broker not available, continue
+    }
+  }
+
+  // Local daemon detection (for local development)
+  if (process.env.PHOTON_DAEMON_ENABLED !== 'false') {
+    try {
+      return createBrokerFromEnv('daemon');
+    } catch {
+      // Daemon broker not available, continue
+    }
+  }
+
+  // Fallback to NoOp
+  return createBrokerFromEnv('noop');
+}
+
+/**
+ * Create a broker with configuration from environment variables
+ */
+function createBrokerFromEnv(type: string): ChannelBroker {
+  const options: Record<string, unknown> = {};
+
+  switch (type) {
+    case 'redis':
+      options.url = process.env.PHOTON_REDIS_URL || process.env.REDIS_URL;
+      options.prefix = process.env.PHOTON_REDIS_PREFIX || 'photon:channel:';
+      break;
+
+    case 'http':
+      options.publishUrl = process.env.PHOTON_CHANNEL_HTTP_URL;
+      options.subscribeUrl = process.env.PHOTON_CHANNEL_SSE_URL;
+      options.authToken = process.env.PHOTON_CHANNEL_AUTH_TOKEN;
+      break;
+
+    case 'cloudflare':
+      options.accountId = process.env.PHOTON_CLOUDFLARE_ACCOUNT_ID || process.env.CF_ACCOUNT_ID;
+      options.namespaceId = process.env.PHOTON_CLOUDFLARE_DO_NAMESPACE;
+      options.apiToken = process.env.PHOTON_CLOUDFLARE_API_TOKEN || process.env.CF_API_TOKEN;
+      break;
+
+    case 'daemon':
+      options.photonName = process.env.PHOTON_NAME;
+      options.socketDir = process.env.PHOTON_SOCKET_DIR;
+      break;
+
+    case 'noop':
+    default:
+      // No configuration needed
+      break;
+  }
+
+  return createBroker(type, options);
+}
+
+/**
+ * Get or create the active broker
+ * Uses auto-detection on first call, then caches the instance
+ */
+export function getBroker(): ChannelBroker {
+  if (!activeBroker) {
+    activeBroker = detectBroker();
+  }
+  return activeBroker;
+}
+
+/**
+ * Set the active broker explicitly
+ * @param broker Broker instance to use
+ */
+export function setBroker(broker: ChannelBroker): void {
+  activeBroker = broker;
+}
+
+/**
+ * Clear the active broker (for testing)
+ */
+export function clearBroker(): void {
+  activeBroker = null;
+}

package/src/channels/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Channel Broker Types
+ *
+ * Defines the interface for channel-based pub/sub messaging.
+ * Implementations can use different backends (local daemon, Redis, HTTP, etc.)
+ */
+
+/**
+ * Message published to a channel
+ */
+export interface ChannelMessage {
+  /** Channel identifier (e.g., 'board:my-board', 'user:123') */
+  channel: string;
+  /** Event type (e.g., 'update', 'created', 'deleted') */
+  event: string;
+  /** Message payload */
+  data?: unknown;
+  /** Timestamp when message was created */
+  timestamp?: number;
+  /** Source identifier (photon name, instance id, etc.) */
+  source?: string;
+}
+
+/**
+ * Handler function for channel messages
+ */
+export type ChannelHandler = (message: ChannelMessage) => void;
+
+/**
+ * Subscription handle returned by subscribe()
+ */
+export interface Subscription {
+  /** Unsubscribe from the channel */
+  unsubscribe(): void;
+  /** Channel name */
+  channel: string;
+  /** Whether subscription is active */
+  active: boolean;
+}
+
+/**
+ * Channel broker interface
+ *
+ * Implementations provide the actual pub/sub transport mechanism.
+ * Examples: Unix socket daemon, Redis, HTTP webhooks, Cloudflare Durable Objects, etc.
+ */
+export interface ChannelBroker {
+  /** Broker type identifier */
+  readonly type: string;
+
+  /**
+   * Publish a message to a channel
+   * @param message The message to publish
+   * @returns Promise that resolves when message is sent (not necessarily delivered)
+   */
+  publish(message: ChannelMessage): Promise<void>;
+
+  /**
+   * Subscribe to messages on a channel
+   * @param channel Channel to subscribe to (supports wildcards in some implementations)
+   * @param handler Function called when messages arrive
+   * @returns Subscription handle for unsubscribing
+   */
+  subscribe(channel: string, handler: ChannelHandler): Promise<Subscription>;
+
+  /**
+   * Check if broker is connected/ready
+   */
+  isConnected(): boolean;
+
+  /**
+   * Connect to the broker (if applicable)
+   */
+  connect?(): Promise<void>;
+
+  /**
+   * Disconnect from the broker and cleanup resources
+   */
+  disconnect?(): Promise<void>;
+}
+
+/**
+ * Configuration for broker initialization
+ */
+export interface BrokerConfig {
+  /** Broker type (e.g., 'daemon', 'redis', 'http', 'cloudflare') */
+  type: string;
+  /** Type-specific options */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * Factory function type for creating brokers
+ */
+export type BrokerFactory = (config?: BrokerConfig['options']) => ChannelBroker;

package/src/config.ts

@@ -0,0 +1,134 @@
+/**
+ * Photon Configuration Utilities
+ *
+ * Provides standard config storage for photons that implement the configure() convention.
+ * Config is stored at ~/.photon/{photonName}/config.json
+ *
+ * Usage in a Photon:
+ * ```typescript
+ * import { loadPhotonConfig, savePhotonConfig, getPhotonConfigPath } from '@portel/photon-core';
+ *
+ * export default class MyPhoton extends PhotonMCP {
+ *   async configure(params: { apiKey: string }) {
+ *     savePhotonConfig('my-photon', params);
+ *     return { success: true, config: params };
+ *   }
+ *
+ *   async getConfig() {
+ *     return loadPhotonConfig('my-photon');
+ *   }
+ * }
+ * ```
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+/**
+ * Get the config directory for photons
+ * Default: ~/.photon/
+ */
+export function getPhotonConfigDir(): string {
+  return process.env.PHOTON_CONFIG_DIR || path.join(os.homedir(), '.photon');
+}
+
+/**
+ * Get the config file path for a specific photon
+ * @param photonName The photon name (kebab-case)
+ * @returns Path to config.json for this photon
+ */
+export function getPhotonConfigPath(photonName: string): string {
+  const safeName = photonName.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(getPhotonConfigDir(), safeName, 'config.json');
+}
+
+/**
+ * Load configuration for a photon
+ * @param photonName The photon name (kebab-case)
+ * @param defaults Default values if config doesn't exist
+ * @returns The config object or defaults
+ */
+export function loadPhotonConfig<T extends Record<string, any>>(
+  photonName: string,
+  defaults?: T
+): T {
+  const configPath = getPhotonConfigPath(photonName);
+
+  try {
+    if (fs.existsSync(configPath)) {
+      const content = fs.readFileSync(configPath, 'utf-8');
+      const config = JSON.parse(content);
+      // Merge with defaults
+      return defaults ? { ...defaults, ...config } : config;
+    }
+  } catch (error) {
+    // Log but don't throw - return defaults
+    if (process.env.PHOTON_DEBUG) {
+      console.error(`Failed to load config for ${photonName}:`, error);
+    }
+  }
+
+  return defaults || ({} as T);
+}
+
+/**
+ * Save configuration for a photon
+ * @param photonName The photon name (kebab-case)
+ * @param config The configuration object to save
+ */
+export function savePhotonConfig<T extends Record<string, any>>(
+  photonName: string,
+  config: T
+): void {
+  const configPath = getPhotonConfigPath(photonName);
+  const configDir = path.dirname(configPath);
+
+  // Ensure directory exists
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Check if a photon has been configured
+ * @param photonName The photon name (kebab-case)
+ * @returns true if config file exists
+ */
+export function hasPhotonConfig(photonName: string): boolean {
+  return fs.existsSync(getPhotonConfigPath(photonName));
+}
+
+/**
+ * Delete configuration for a photon
+ * @param photonName The photon name (kebab-case)
+ */
+export function deletePhotonConfig(photonName: string): void {
+  const configPath = getPhotonConfigPath(photonName);
+  if (fs.existsSync(configPath)) {
+    fs.unlinkSync(configPath);
+  }
+}
+
+/**
+ * List all configured photons
+ * @returns Array of photon names that have config
+ */
+export function listConfiguredPhotons(): string[] {
+  const configDir = getPhotonConfigDir();
+
+  if (!fs.existsSync(configDir)) {
+    return [];
+  }
+
+  try {
+    return fs.readdirSync(configDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .filter(entry => fs.existsSync(path.join(configDir, entry.name, 'config.json')))
+      .map(entry => entry.name);
+  } catch {
+    return [];
+  }
+}