@tamyla/clodo-framework 4.4.1 → 4.5.0

package/templates/cron-worker/src/index.js

@@ -0,0 +1,211 @@
+/**
+ * Cron Worker Template — @tamyla/clodo-framework
+ * 
+ * A fully working scheduled/cron worker with:
+ * - Scheduled handler with cron trigger
+ * - KV state persistence between runs
+ * - Job registry for multiple cron schedules
+ * - Notification pattern
+ * - Health check endpoint
+ * 
+ * Deploy with: npx wrangler deploy
+ */
+
+import {
+  createCorsMiddleware,
+  createErrorHandler,
+  createLogger,
+  composeMiddleware,
+  createEnvironmentGuard
+} from '@tamyla/clodo-framework';
+
+// ── Environment validation ────────────────────────────────────────────
+const envGuard = createEnvironmentGuard({
+  required: ['KV_DATA'],
+  optional: ['NOTIFICATION_WEBHOOK']
+});
+
+// ── Middleware ────────────────────────────────────────────────────────
+const middleware = composeMiddleware(
+  createCorsMiddleware({ origins: ['*'] }),
+  createLogger({ prefix: 'cron-worker' }),
+  createErrorHandler()
+);
+
+// ── Job registry — define your scheduled jobs ─────────────────────────
+const jobs = {
+  /**
+   * Daily cleanup job — runs every day at midnight UTC
+   * Cron: 0 0 * * *
+   */
+  async 'daily-cleanup'(env, ctx) {
+    console.log('Running daily cleanup...');
+
+    const state = await getJobState(env, 'daily-cleanup');
+    
+    // Your cleanup logic here
+    const result = {
+      cleanedItems: 0,
+      freedSpace: '0 MB',
+      timestamp: new Date().toISOString()
+    };
+
+    // Persist state
+    await saveJobState(env, 'daily-cleanup', {
+      lastRun: new Date().toISOString(),
+      lastResult: result,
+      runCount: (state.runCount || 0) + 1
+    });
+
+    return result;
+  },
+
+  /**
+   * Periodic health probe — runs every 5 minutes
+   * Cron: *​/5 * * * *
+   */
+  async 'health-probe'(env, ctx) {
+    console.log('Running health probe...');
+
+    // Example: check external dependencies
+    const checks = {
+      timestamp: new Date().toISOString(),
+      status: 'healthy'
+    };
+
+    await saveJobState(env, 'health-probe', {
+      lastRun: new Date().toISOString(),
+      lastResult: checks
+    });
+
+    // Optionally notify on unhealthy status
+    if (checks.status !== 'healthy' && env.NOTIFICATION_WEBHOOK) {
+      ctx.waitUntil(
+        fetch(env.NOTIFICATION_WEBHOOK, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            text: `⚠️ Health probe failed: ${JSON.stringify(checks)}`
+          })
+        })
+      );
+    }
+
+    return checks;
+  }
+};
+
+// ── State helpers ────────────────────────────────────────────────────
+async function getJobState(env, jobName) {
+  try {
+    const data = await env.KV_DATA.get(`cron:${jobName}`, { type: 'json' });
+    return data || {};
+  } catch {
+    return {};
+  }
+}
+
+async function saveJobState(env, jobName, state) {
+  await env.KV_DATA.put(`cron:${jobName}`, JSON.stringify(state));
+}
+
+// ── HTTP Routes (for monitoring) ─────────────────────────────────────
+const routes = {
+  'GET /health': async (req, env) => {
+    return jsonResponse({ status: 'healthy', type: 'cron-worker' });
+  },
+
+  'GET /api/jobs': async (req, env) => {
+    const jobNames = Object.keys(jobs);
+    const statuses = await Promise.all(
+      jobNames.map(async (name) => ({
+        name,
+        state: await getJobState(env, name)
+      }))
+    );
+    return jsonResponse({ jobs: statuses });
+  },
+
+  'GET /api/jobs/:name': async (req, env) => {
+    const name = req.params?.name;
+    if (!jobs[name]) {
+      return jsonResponse({ error: `Job '${name}' not found` }, 404);
+    }
+    const state = await getJobState(env, name);
+    return jsonResponse({ name, state });
+  },
+
+  // Manual trigger endpoint (useful for testing)
+  'POST /api/jobs/:name/trigger': async (req, env, ctx) => {
+    const name = req.params?.name;
+    if (!jobs[name]) {
+      return jsonResponse({ error: `Job '${name}' not found` }, 404);
+    }
+
+    const result = await jobs[name](env, ctx);
+    return jsonResponse({ triggered: true, name, result });
+  }
+};
+
+function jsonResponse(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+
+// ── Worker entry point ────────────────────────────────────────────────
+export default {
+  // HTTP handler (for monitoring/manual triggers)
+  async fetch(request, env, ctx) {
+    envGuard.check(env);
+    const url = new URL(request.url);
+    const routeKey = `${request.method} ${url.pathname}`;
+    const handler = routes[routeKey];
+
+    if (!handler) {
+      return jsonResponse({ error: 'Not Found' }, 404);
+    }
+
+    return middleware.execute(request, () => handler(request, env, ctx));
+  },
+
+  // Scheduled handler (runs on cron triggers)
+  async scheduled(event, env, ctx) {
+    console.log(`Cron triggered at ${new Date(event.scheduledTime).toISOString()}, cron: ${event.cron}`);
+
+    // Map cron expressions to job names
+    const cronMap = {
+      '0 0 * * *': 'daily-cleanup',
+      '*/5 * * * *': 'health-probe'
+    };
+
+    const jobName = cronMap[event.cron];
+
+    if (jobName && jobs[jobName]) {
+      try {
+        const result = await jobs[jobName](env, ctx);
+        console.log(`Job ${jobName} completed:`, result);
+      } catch (error) {
+        console.error(`Job ${jobName} failed:`, error.message);
+
+        // Track failure
+        await saveJobState(env, jobName, {
+          lastRun: new Date().toISOString(),
+          lastError: error.message,
+          status: 'failed'
+        });
+      }
+    } else {
+      console.warn(`No job mapped to cron expression: ${event.cron}`);
+      // Run all jobs if no specific mapping
+      for (const [name, job] of Object.entries(jobs)) {
+        try {
+          await job(env, ctx);
+        } catch (error) {
+          console.error(`Job ${name} failed:`, error.message);
+        }
+      }
+    }
+  }
+};

package/templates/edge-proxy/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{SERVICE_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@tamyla/clodo-framework": "^4.4.1"
+  },
+  "devDependencies": {
+    "wrangler": "^3.0.0",
+    "vitest": "^2.0.0"
+  }
+}

package/templates/edge-proxy/src/index.js

@@ -0,0 +1,150 @@
+/**
+ * Edge Proxy Worker Template — @tamyla/clodo-framework
+ * 
+ * An edge proxy/gateway with:
+ * - Request rewriting & URL mapping
+ * - Response caching (Cache API)
+ * - Rate limiting
+ * - Header manipulation
+ * - A/B routing
+ * 
+ * Deploy with: npx wrangler deploy
+ */
+
+import {
+  createCorsMiddleware,
+  createErrorHandler,
+  createLogger,
+  createRateLimitGuard,
+  composeMiddleware,
+  createEnvironmentGuard
+} from '@tamyla/clodo-framework';
+
+// ── Environment ──────────────────────────────────────────────────────
+const envGuard = createEnvironmentGuard({
+  required: [],
+  optional: ['KV_CONFIG', 'UPSTREAM_URL']
+});
+
+const middleware = composeMiddleware(
+  createCorsMiddleware({ origins: ['*'] }),
+  createLogger({ prefix: 'edge-proxy' }),
+  createRateLimitGuard({ maxRequests: 200, windowMs: 60000 }),
+  createErrorHandler({ includeStack: false })
+);
+
+// ── Route mapping (path rewrites) ────────────────────────────────────
+const routeMap = {
+  // Rewrite /api/* to upstream service
+  '/api/': {
+    upstream: 'https://api.example.com',
+    stripPrefix: '/api',
+    headers: { 'X-Forwarded-By': 'clodo-proxy' }
+  },
+  // Serve static assets from R2/another origin
+  '/assets/': {
+    upstream: 'https://cdn.example.com',
+    stripPrefix: '',
+    cache: { ttl: 86400 } // Cache for 24h
+  }
+};
+
+// ── Proxy logic ──────────────────────────────────────────────────────
+async function proxyRequest(request, env, ctx) {
+  const url = new URL(request.url);
+
+  // Find matching route
+  let matchedRoute = null;
+  let matchedPrefix = '';
+
+  for (const [prefix, config] of Object.entries(routeMap)) {
+    if (url.pathname.startsWith(prefix)) {
+      matchedRoute = config;
+      matchedPrefix = prefix;
+      break;
+    }
+  }
+
+  if (!matchedRoute) {
+    // Health check
+    if (url.pathname === '/health') {
+      return Response.json({ status: 'healthy', type: 'edge-proxy' });
+    }
+
+    // No route matched
+    return Response.json({ error: 'No route matched', path: url.pathname }, { status: 404 });
+  }
+
+  // Build upstream URL
+  const upstreamBase = env.UPSTREAM_URL || matchedRoute.upstream;
+  const strippedPath = matchedRoute.stripPrefix
+    ? url.pathname.replace(matchedPrefix, matchedRoute.stripPrefix || '/')
+    : url.pathname;
+  const upstreamUrl = new URL(strippedPath + url.search, upstreamBase);
+
+  // Check cache first
+  if (matchedRoute.cache && request.method === 'GET') {
+    const cache = caches.default;
+    const cacheKey = new Request(upstreamUrl.toString(), request);
+    const cached = await cache.match(cacheKey);
+
+    if (cached) {
+      const response = new Response(cached.body, cached);
+      response.headers.set('X-Cache', 'HIT');
+      return response;
+    }
+  }
+
+  // Build upstream request
+  const headers = new Headers(request.headers);
+
+  // Add custom headers
+  if (matchedRoute.headers) {
+    for (const [key, value] of Object.entries(matchedRoute.headers)) {
+      headers.set(key, value);
+    }
+  }
+
+  // Forward the original host
+  headers.set('X-Forwarded-Host', url.hostname);
+  headers.set('X-Forwarded-Proto', url.protocol.replace(':', ''));
+
+  const upstreamRequest = new Request(upstreamUrl.toString(), {
+    method: request.method,
+    headers,
+    body: request.method !== 'GET' && request.method !== 'HEAD' ? request.body : null,
+    redirect: 'follow'
+  });
+
+  // Fetch from upstream
+  const response = await fetch(upstreamRequest);
+
+  // Create mutable response
+  const proxyResponse = new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: new Headers(response.headers)
+  });
+
+  proxyResponse.headers.set('X-Cache', 'MISS');
+  proxyResponse.headers.set('X-Proxy', 'clodo-edge-proxy');
+
+  // Cache response if configured
+  if (matchedRoute.cache && request.method === 'GET' && response.ok) {
+    const cache = caches.default;
+    const cacheKey = new Request(upstreamUrl.toString(), request);
+    const toCache = proxyResponse.clone();
+    toCache.headers.set('Cache-Control', `public, max-age=${matchedRoute.cache.ttl}`);
+    ctx.waitUntil(cache.put(cacheKey, toCache));
+  }
+
+  return proxyResponse;
+}
+
+// ── Worker entry point ────────────────────────────────────────────────
+export default {
+  async fetch(request, env, ctx) {
+    envGuard.check(env);
+    return middleware.execute(request, () => proxyRequest(request, env, ctx));
+  }
+};

package/templates/minimal/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{SERVICE_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@tamyla/clodo-framework": "^4.4.1"
+  },
+  "devDependencies": {
+    "wrangler": "^3.0.0"
+  }
+}

package/templates/minimal/src/index.js

@@ -0,0 +1,40 @@
+/**
+ * Minimal Worker Template — @tamyla/clodo-framework
+ * 
+ * The absolute minimal starting point. Just a fetch handler,
+ * CORS, and a health check. Add what you need.
+ * 
+ * Deploy with: npx wrangler deploy
+ */
+
+import {
+  createCorsMiddleware,
+  createErrorHandler,
+  composeMiddleware
+} from '@tamyla/clodo-framework';
+
+const middleware = composeMiddleware(
+  createCorsMiddleware({ origins: ['*'] }),
+  createErrorHandler()
+);
+
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+
+    return middleware.execute(request, async () => {
+      if (url.pathname === '/health') {
+        return Response.json({ status: 'healthy', timestamp: new Date().toISOString() });
+      }
+
+      if (url.pathname === '/') {
+        return Response.json({
+          name: '{{SERVICE_NAME}}',
+          message: 'Worker is running. Edit src/index.js to add your routes.'
+        });
+      }
+
+      return Response.json({ error: 'Not Found' }, { status: 404 });
+    });
+  }
+};

package/templates/queue-processor/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "{{SERVICE_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@tamyla/clodo-framework": "^4.4.1"
+  },
+  "devDependencies": {
+    "wrangler": "^3.0.0",
+    "vitest": "^2.0.0",
+    "@cloudflare/vitest-pool-workers": "^0.5.0"
+  }
+}

package/templates/queue-processor/src/index.js

@@ -0,0 +1,213 @@
+/**
+ * Queue Processor Worker Template — @tamyla/clodo-framework
+ * 
+ * A fully working queue consumer/producer with:
+ * - Queue message consumption with batch processing
+ * - Dead letter queue handling
+ * - Retry logic with exponential backoff
+ * - KV state tracking
+ * - HTTP API for sending messages
+ * 
+ * Deploy with: npx wrangler deploy
+ */
+
+import {
+  createCorsMiddleware,
+  createErrorHandler,
+  createLogger,
+  composeMiddleware,
+  createEnvironmentGuard
+} from '@tamyla/clodo-framework';
+
+import {
+  QueueProducer,
+  QueueConsumer,
+  MessageBuilder,
+  MessageTypes
+} from '@tamyla/clodo-framework/utilities';
+
+// ── Environment validation ────────────────────────────────────────────
+const envGuard = createEnvironmentGuard({
+  required: ['QUEUE'],
+  optional: ['KV_DATA', 'DEAD_LETTER_QUEUE']
+});
+
+// ── Middleware ────────────────────────────────────────────────────────
+const middleware = composeMiddleware(
+  createCorsMiddleware({ origins: ['*'] }),
+  createLogger({ prefix: 'queue-worker' }),
+  createErrorHandler()
+);
+
+// ── Message handlers (register per message type) ─────────────────────
+const handlers = {
+  /**
+   * Process a generic task message
+   */
+  async 'task.process'(message, env) {
+    const { taskId, payload } = message.body;
+    console.log(`Processing task ${taskId}:`, payload);
+
+    // Your business logic here
+    // Example: call an API, transform data, update a database
+
+    // Track completion in KV if available
+    if (env.KV_DATA) {
+      await env.KV_DATA.put(`task:${taskId}`, JSON.stringify({
+        status: 'completed',
+        completedAt: new Date().toISOString(),
+        result: { processed: true }
+      }));
+    }
+  },
+
+  /**
+   * Process a notification message
+   */
+  async 'notification.send'(message, env) {
+    const { recipient, subject, body } = message.body;
+    console.log(`Sending notification to ${recipient}: ${subject}`);
+    // Your notification logic here (email, webhook, push, etc.)
+  },
+
+  /**
+   * Default handler for unknown message types
+   */
+  async 'default'(message, env) {
+    console.warn(`Unknown message type: ${message.body?.type}`, message.body);
+  }
+};
+
+// ── Queue consumer logic ─────────────────────────────────────────────
+async function processMessage(message, env) {
+  const type = message.body?.type || 'default';
+  const handler = handlers[type] || handlers['default'];
+
+  const maxRetries = message.body?.maxRetries || 3;
+  const attempt = message.body?._attempt || 1;
+
+  try {
+    await handler(message, env);
+    message.ack(); // Acknowledge successful processing
+  } catch (error) {
+    console.error(`Failed to process message (attempt ${attempt}/${maxRetries}):`, error.message);
+
+    if (attempt >= maxRetries) {
+      // Max retries exceeded — send to dead letter queue if available
+      if (env.DEAD_LETTER_QUEUE) {
+        await env.DEAD_LETTER_QUEUE.send({
+          ...message.body,
+          _error: error.message,
+          _failedAt: new Date().toISOString(),
+          _attempts: attempt
+        });
+      }
+
+      // Track failure in KV
+      if (env.KV_DATA && message.body?.taskId) {
+        await env.KV_DATA.put(`task:${message.body.taskId}`, JSON.stringify({
+          status: 'failed',
+          error: error.message,
+          failedAt: new Date().toISOString(),
+          attempts: attempt
+        }));
+      }
+
+      message.ack(); // Remove from queue after max retries
+    } else {
+      message.retry({ delaySeconds: Math.pow(2, attempt) * 10 }); // Exponential backoff
+    }
+  }
+}
+
+// ── HTTP Routes (for sending messages) ───────────────────────────────
+const routes = {
+  'GET /health': async (req, env) => {
+    return jsonResponse({ status: 'healthy', type: 'queue-processor' });
+  },
+
+  'POST /api/enqueue': async (req, env) => {
+    const body = await req.json();
+    const message = {
+      type: body.type || 'task.process',
+      taskId: body.taskId || crypto.randomUUID(),
+      payload: body.payload || body,
+      _attempt: 1,
+      enqueuedAt: new Date().toISOString()
+    };
+
+    await env.QUEUE.send(message);
+
+    return jsonResponse({
+      queued: true,
+      taskId: message.taskId,
+      type: message.type
+    }, 202);
+  },
+
+  'POST /api/enqueue/batch': async (req, env) => {
+    const { messages } = await req.json();
+    const batch = messages.map(m => ({
+      body: {
+        type: m.type || 'task.process',
+        taskId: m.taskId || crypto.randomUUID(),
+        payload: m.payload || m,
+        _attempt: 1,
+        enqueuedAt: new Date().toISOString()
+      }
+    }));
+
+    await env.QUEUE.sendBatch(batch);
+
+    return jsonResponse({
+      queued: true,
+      count: batch.length,
+      taskIds: batch.map(b => b.body.taskId)
+    }, 202);
+  },
+
+  'GET /api/task/:taskId': async (req, env) => {
+    if (!env.KV_DATA) {
+      return jsonResponse({ error: 'KV storage not configured' }, 501);
+    }
+    const taskId = req.params?.taskId;
+    const data = await env.KV_DATA.get(`task:${taskId}`, { type: 'json' });
+    if (!data) {
+      return jsonResponse({ error: 'Task not found' }, 404);
+    }
+    return jsonResponse({ taskId, ...data });
+  }
+};
+
+function jsonResponse(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+
+// ── Worker entry point ────────────────────────────────────────────────
+export default {
+  // HTTP handler
+  async fetch(request, env, ctx) {
+    envGuard.check(env);
+    const url = new URL(request.url);
+    const routeKey = `${request.method} ${url.pathname}`;
+    const handler = routes[routeKey];
+
+    if (!handler) {
+      return jsonResponse({ error: 'Not Found' }, 404);
+    }
+
+    return middleware.execute(request, () => handler(request, env, ctx));
+  },
+
+  // Queue consumer handler
+  async queue(batch, env, ctx) {
+    console.log(`Processing batch of ${batch.messages.length} messages`);
+
+    for (const message of batch.messages) {
+      await processMessage(message, env);
+    }
+  }
+};

package/templates/rest-api/.dev.vars

@@ -0,0 +1,2 @@
+# Environment variables for local dev (wrangler dev)
+SECRET_KEY=

package/templates/rest-api/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "{{SERVICE_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@tamyla/clodo-framework": "^4.4.1"
+  },
+  "devDependencies": {
+    "wrangler": "^3.0.0",
+    "vitest": "^2.0.0",
+    "@cloudflare/vitest-pool-workers": "^0.5.0"
+  }
+}