@portel/photon-core 2.1.2 → 2.2.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/decorators.ts

@@ -0,0 +1,87 @@
+/**
+ * Photon Lock Helpers
+ *
+ * Runtime support for distributed locking via daemon.
+ * The @locked docblock tag and this.withLock() helper both use this.
+ */
+
+// ============================================================================
+// Lock Manager Interface
+// ============================================================================
+
+/**
+ * Interface for lock management
+ * Implemented by daemon client or other providers
+ */
+export interface LockManager {
+  acquire(lockName: string, timeout?: number): Promise<boolean>;
+  release(lockName: string): Promise<boolean>;
+}
+
+let _lockManager: LockManager | null = null;
+
+/**
+ * Set the global lock manager (called by runtime)
+ * @internal
+ */
+export function setLockManager(manager: LockManager | null): void {
+  _lockManager = manager;
+}
+
+/**
+ * Get the current lock manager
+ * @internal
+ */
+export function getLockManager(): LockManager | null {
+  return _lockManager;
+}
+
+// ============================================================================
+// withLock Helper
+// ============================================================================
+
+/**
+ * Execute a function with a distributed lock
+ *
+ * Use this for fine-grained locking within a method, or when you
+ * need dynamic lock names.
+ *
+ * @param lockName Name of the lock to acquire
+ * @param fn Function to execute while holding the lock
+ * @param timeout Optional lock timeout in ms (default 30000)
+ *
+ * @example
+ * ```typescript
+ * async moveTask(params: { taskId: string; column: string }) {
+ *   return this.withLock(`task:${params.taskId}`, async () => {
+ *     const task = await this.loadTask(params.taskId);
+ *     task.column = params.column;
+ *     await this.saveTask(task);
+ *     return task;
+ *   });
+ * }
+ * ```
+ */
+export async function withLock<T>(
+  lockName: string,
+  fn: () => Promise<T>,
+  timeout?: number
+): Promise<T> {
+  const lockManager = getLockManager();
+
+  if (!lockManager) {
+    // No lock manager, run without lock
+    return fn();
+  }
+
+  const acquired = await lockManager.acquire(lockName, timeout);
+  if (!acquired) {
+    throw new Error(`Could not acquire lock: ${lockName}`);
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await lockManager.release(lockName);
+  }
+}

package/src/index.ts

@@ -321,3 +321,16 @@ export * from './rendering/index.js';
 // ===== UCP (Universal Commerce Protocol) =====
 // Agentic commerce with checkout, identity, orders, and AP2 payments
 export * from './ucp/index.js';
+
+// ===== CHANNEL-BASED PUB/SUB =====
+// Cross-process messaging with pluggable brokers (daemon, Redis, HTTP, etc.)
+export * from './channels/index.js';
+
+// ===== LOCK HELPERS =====
+// Runtime support for distributed locking via daemon
+export {
+  withLock,
+  setLockManager,
+  getLockManager,
+  type LockManager,
+} from './decorators.js';