@tamyla/clodo-framework 4.3.5 → 4.4.1

package/dist/utilities/durable-objects/base.js

@@ -0,0 +1,200 @@
+/**
+ * Durable Object Base Class
+ * Provides a foundation for building stateful Durable Objects
+ * 
+ * @example
+ * import { DurableObjectBase } from '@tamyla/clodo-framework/utilities/durable-objects';
+ * 
+ * export class MyCounter extends DurableObjectBase {
+ *   async increment() {
+ *     const current = await this.getState('count', 0);
+ *     const newCount = current + 1;
+ *     await this.setState('count', newCount);
+ *     return newCount;
+ *   }
+ * }
+ */
+
+/**
+ * Base class for Durable Objects with common patterns
+ */
+export class DurableObjectBase {
+  /**
+   * @param {DurableObjectState} state - DO state
+   * @param {Object} env - Environment bindings
+   */
+  constructor(state, env) {
+    this.state = state;
+    this.env = env;
+    this.storage = state.storage;
+    this.id = state.id;
+    this.initialized = false;
+    this.initPromise = null;
+  }
+
+  /**
+   * Override this method for async initialization
+   * Called once when the DO is first accessed
+   */
+  async initialize() {
+    // Override in subclass
+  }
+
+  /**
+   * Ensure initialization is complete
+   */
+  async ensureInitialized() {
+    if (this.initialized) return;
+    if (!this.initPromise) {
+      this.initPromise = this.state.blockConcurrencyWhile(async () => {
+        if (!this.initialized) {
+          await this.initialize();
+          this.initialized = true;
+        }
+      });
+    }
+    await this.initPromise;
+  }
+
+  /**
+   * Get a value from storage with optional default
+   * @param {string} key - Storage key
+   * @param {*} defaultValue - Default if key doesn't exist
+   * @returns {Promise<*>}
+   */
+  async getState(key, defaultValue = undefined) {
+    const value = await this.storage.get(key);
+    return value !== undefined ? value : defaultValue;
+  }
+
+  /**
+   * Set a value in storage
+   * @param {string} key - Storage key
+   * @param {*} value - Value to store
+   * @returns {Promise<void>}
+   */
+  async setState(key, value) {
+    await this.storage.put(key, value);
+  }
+
+  /**
+   * Delete a key from storage
+   * @param {string} key - Storage key
+   * @returns {Promise<boolean>}
+   */
+  async deleteState(key) {
+    return this.storage.delete(key);
+  }
+
+  /**
+   * Get multiple values from storage
+   * @param {string[]} keys - Storage keys
+   * @returns {Promise<Map<string, *>>}
+   */
+  async getMany(keys) {
+    return this.storage.get(keys);
+  }
+
+  /**
+   * Set multiple values in storage
+   * @param {Object} entries - Key-value pairs
+   * @returns {Promise<void>}
+   */
+  async setMany(entries) {
+    return this.storage.put(entries);
+  }
+
+  /**
+   * List all keys with a prefix
+   * @param {Object} options - List options
+   * @returns {Promise<Map<string, *>>}
+   */
+  async listState(options = {}) {
+    return this.storage.list(options);
+  }
+
+  /**
+   * Execute a transaction
+   * @param {Function} callback - Transaction callback
+   * @returns {Promise<*>}
+   */
+  async transaction(callback) {
+    return this.state.blockConcurrencyWhile(callback);
+  }
+
+  /**
+   * Set an alarm for future execution
+   * @param {Date|number} time - When to trigger (Date or ms from now)
+   * @returns {Promise<void>}
+   */
+  async setAlarm(time) {
+    const alarmTime = typeof time === 'number' ? Date.now() + time : time.getTime();
+    await this.storage.setAlarm(alarmTime);
+  }
+
+  /**
+   * Get the current alarm time
+   * @returns {Promise<Date|null>}
+   */
+  async getAlarm() {
+    const alarm = await this.storage.getAlarm();
+    return alarm ? new Date(alarm) : null;
+  }
+
+  /**
+   * Delete the current alarm
+   * @returns {Promise<void>}
+   */
+  async deleteAlarm() {
+    await this.storage.deleteAlarm();
+  }
+
+  /**
+   * Default alarm handler - override in subclass
+   */
+  async alarm() {
+    // Override in subclass
+  }
+
+  /**
+   * Handle HTTP requests - override in subclass
+   * @param {Request} request
+   * @returns {Promise<Response>}
+   */
+  async fetch(request) {
+    await this.ensureInitialized();
+
+    // Default implementation - override for custom behavior
+    return new Response('Not implemented', {
+      status: 501
+    });
+  }
+
+  /**
+   * JSON response helper
+   * @param {*} data - Data to serialize
+   * @param {number} status - HTTP status
+   * @returns {Response}
+   */
+  json(data, status = 200) {
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    });
+  }
+
+  /**
+   * Error response helper
+   * @param {string} message - Error message
+   * @param {number} status - HTTP status
+   * @returns {Response}
+   */
+  error(message, status = 500) {
+    return this.json({
+      error: message
+    }, status);
+  }
+}
+export default DurableObjectBase;

package/dist/utilities/durable-objects/counter.js

@@ -0,0 +1,117 @@
+/**
+ * Counter Durable Object
+ * Simple atomic counter with history
+ * 
+ * @example
+ * const id = env.COUNTER.idFromName('page-views');
+ * const counter = env.COUNTER.get(id);
+ * const response = await counter.fetch(new Request('https://counter/increment'));
+ */
+
+import { DurableObjectBase } from './base.js';
+export class Counter extends DurableObjectBase {
+  async fetch(request) {
+    await this.ensureInitialized();
+    const url = new URL(request.url);
+    const action = url.pathname.split('/').pop();
+    switch (action) {
+      case 'increment':
+        return this.increment(request);
+      case 'decrement':
+        return this.decrement(request);
+      case 'set':
+        return this.set(request);
+      case 'reset':
+        return this.reset();
+      case 'history':
+        return this.getHistory();
+      default:
+        return this.getValue();
+    }
+  }
+  async getValue() {
+    const value = await this.getState('value', 0);
+    return this.json({
+      value
+    });
+  }
+  async increment(request) {
+    const url = new URL(request.url);
+    const amount = parseInt(url.searchParams.get('amount')) || 1;
+    return this.transaction(async () => {
+      let value = await this.getState('value', 0);
+      value += amount;
+      await this.setState('value', value);
+      await this.recordHistory('increment', amount, value);
+      return this.json({
+        value,
+        change: amount
+      });
+    });
+  }
+  async decrement(request) {
+    const url = new URL(request.url);
+    const amount = parseInt(url.searchParams.get('amount')) || 1;
+    return this.transaction(async () => {
+      let value = await this.getState('value', 0);
+      value -= amount;
+      await this.setState('value', value);
+      await this.recordHistory('decrement', -amount, value);
+      return this.json({
+        value,
+        change: -amount
+      });
+    });
+  }
+  async set(request) {
+    const url = new URL(request.url);
+    const newValue = parseInt(url.searchParams.get('value'));
+    if (isNaN(newValue)) {
+      return this.error('Invalid value', 400);
+    }
+    return this.transaction(async () => {
+      const oldValue = await this.getState('value', 0);
+      await this.setState('value', newValue);
+      await this.recordHistory('set', newValue - oldValue, newValue);
+      return this.json({
+        value: newValue,
+        previousValue: oldValue
+      });
+    });
+  }
+  async reset() {
+    return this.transaction(async () => {
+      const oldValue = await this.getState('value', 0);
+      await this.setState('value', 0);
+      await this.recordHistory('reset', -oldValue, 0);
+      return this.json({
+        value: 0,
+        previousValue: oldValue
+      });
+    });
+  }
+  async recordHistory(action, change, newValue) {
+    const history = await this.getState('history', []);
+    history.push({
+      action,
+      change,
+      value: newValue,
+      timestamp: Date.now()
+    });
+
+    // Keep only last 100 entries
+    if (history.length > 100) {
+      history.shift();
+    }
+    await this.setState('history', history);
+  }
+  async getHistory() {
+    const history = await this.getState('history', []);
+    const value = await this.getState('value', 0);
+    return this.json({
+      currentValue: value,
+      history
+    });
+  }
+}
+export default Counter;

package/dist/utilities/durable-objects/index.js

@@ -0,0 +1,10 @@
+/**
+ * Durable Object Utilities
+ * @module @tamyla/clodo-framework/utilities/durable-objects
+ */
+
+export { DurableObjectBase } from './base.js';
+export { RateLimiter } from './rate-limiter.js';
+export { SessionStore } from './session-store.js';
+export { Counter } from './counter.js';
+export { WebSocketRoom } from './websocket-room.js';

package/dist/utilities/durable-objects/rate-limiter.js

@@ -0,0 +1,80 @@
+/**
+ * Rate Limiter Durable Object
+ * Implements sliding window rate limiting
+ * 
+ * @example
+ * // In wrangler.toml
+ * [[durable_objects.bindings]]
+ * name = "RATE_LIMITER"
+ * class_name = "RateLimiter"
+ * 
+ * // Usage
+ * const id = env.RATE_LIMITER.idFromName(clientIP);
+ * const limiter = env.RATE_LIMITER.get(id);
+ * const response = await limiter.fetch(request);
+ */
+
+import { DurableObjectBase } from './base.js';
+export class RateLimiter extends DurableObjectBase {
+  constructor(state, env) {
+    super(state, env);
+    this.defaultLimit = 100;
+    this.defaultWindow = 60000; // 1 minute in ms
+  }
+  async fetch(request) {
+    await this.ensureInitialized();
+    const url = new URL(request.url);
+    const action = url.pathname.split('/').pop();
+    switch (action) {
+      case 'check':
+        return this.checkLimit(request);
+      case 'reset':
+        return this.resetLimit();
+      case 'status':
+        return this.getStatus();
+      default:
+        return this.checkLimit(request);
+    }
+  }
+  async checkLimit(request) {
+    const url = new URL(request.url);
+    const limit = parseInt(url.searchParams.get('limit')) || this.defaultLimit;
+    const window = parseInt(url.searchParams.get('window')) || this.defaultWindow;
+    const now = Date.now();
+    const windowStart = now - window;
+
+    // Get current requests
+    let requests = await this.getState('requests', []);
+
+    // Filter to only requests within window
+    requests = requests.filter(timestamp => timestamp > windowStart);
+    const allowed = requests.length < limit;
+    if (allowed) {
+      requests.push(now);
+      await this.setState('requests', requests);
+    }
+    return this.json({
+      allowed,
+      remaining: Math.max(0, limit - requests.length),
+      reset: windowStart + window,
+      limit,
+      current: requests.length
+    });
+  }
+  async resetLimit() {
+    await this.setState('requests', []);
+    return this.json({
+      success: true,
+      message: 'Rate limit reset'
+    });
+  }
+  async getStatus() {
+    const requests = await this.getState('requests', []);
+    return this.json({
+      currentRequests: requests.length,
+      oldestRequest: requests[0] || null,
+      newestRequest: requests[requests.length - 1] || null
+    });
+  }
+}
+export default RateLimiter;

package/dist/utilities/durable-objects/session-store.js

@@ -0,0 +1,126 @@
+/**
+ * Session Store Durable Object
+ * Manages user sessions with automatic expiry
+ * 
+ * @example
+ * const id = env.SESSION_STORE.idFromName(sessionId);
+ * const store = env.SESSION_STORE.get(id);
+ * await store.fetch(new Request('https://session/set', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ userId: '123', data: { role: 'admin' } })
+ * }));
+ */
+
+import { DurableObjectBase } from './base.js';
+export class SessionStore extends DurableObjectBase {
+  constructor(state, env) {
+    super(state, env);
+    this.defaultTTL = 24 * 60 * 60 * 1000; // 24 hours
+  }
+  async fetch(request) {
+    await this.ensureInitialized();
+    const url = new URL(request.url);
+    const action = url.pathname.split('/').pop();
+    switch (request.method) {
+      case 'GET':
+        return this.getSession();
+      case 'POST':
+        return this.setSession(request);
+      case 'PATCH':
+        return this.updateSession(request);
+      case 'DELETE':
+        return this.deleteSession();
+      default:
+        return this.error('Method not allowed', 405);
+    }
+  }
+  async getSession() {
+    const session = await this.getState('session');
+    if (!session) {
+      return this.json({
+        exists: false,
+        session: null
+      });
+    }
+
+    // Check expiry
+    if (session.expiresAt && Date.now() > session.expiresAt) {
+      await this.deleteState('session');
+      return this.json({
+        exists: false,
+        expired: true,
+        session: null
+      });
+    }
+
+    // Update last accessed
+    session.lastAccessed = Date.now();
+    await this.setState('session', session);
+    return this.json({
+      exists: true,
+      session
+    });
+  }
+  async setSession(request) {
+    const body = await request.json();
+    const ttl = body.ttl || this.defaultTTL;
+    const session = {
+      data: body.data || {},
+      userId: body.userId,
+      createdAt: Date.now(),
+      lastAccessed: Date.now(),
+      expiresAt: Date.now() + ttl,
+      metadata: body.metadata || {}
+    };
+    await this.setState('session', session);
+
+    // Set alarm for cleanup
+    await this.setAlarm(ttl);
+    return this.json({
+      success: true,
+      session
+    });
+  }
+  async updateSession(request) {
+    const session = await this.getState('session');
+    if (!session) {
+      return this.error('Session not found', 404);
+    }
+    const body = await request.json();
+
+    // Merge data
+    session.data = {
+      ...session.data,
+      ...body.data
+    };
+    session.lastAccessed = Date.now();
+
+    // Optionally extend expiry
+    if (body.extend) {
+      const ttl = body.ttl || this.defaultTTL;
+      session.expiresAt = Date.now() + ttl;
+      await this.setAlarm(ttl);
+    }
+    await this.setState('session', session);
+    return this.json({
+      success: true,
+      session
+    });
+  }
+  async deleteSession() {
+    await this.deleteState('session');
+    await this.deleteAlarm();
+    return this.json({
+      success: true,
+      message: 'Session deleted'
+    });
+  }
+  async alarm() {
+    // Clean up expired session
+    const session = await this.getState('session');
+    if (session && session.expiresAt && Date.now() > session.expiresAt) {
+      await this.deleteState('session');
+    }
+  }
+}
+export default SessionStore;