@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

package/templates/standard/tests/integration/platform-sentinel.test.ts

@@ -0,0 +1,497 @@
+/**
+ * Integration Tests for Platform Sentinel Worker
+ *
+ * Tests the cron-triggered alerting workflow including:
+ * - Threshold evaluation logic
+ * - Rate limiting via KV
+ * - Alert generation and filtering
+ *
+ * @module tests/integration/platform-sentinel
+ * @created 2026-01-05
+ * @renamed 2026-01-23 (from cost-spike-alerter)
+ * @task task-17.28 - Integration test for alert cron trigger
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+// Import the worker module for testing internal functions
+// Note: We test via the exported default handlers
+
+/**
+ * Mock KV namespace for testing
+ */
+function createMockKV(initialData: Record<string, string> = {}) {
+  const store = { ...initialData };
+
+  return {
+    _store: store,
+    get: vi.fn().mockImplementation((key: string) => Promise.resolve(store[key] || null)),
+    put: vi.fn().mockImplementation((key: string, value: string) => {
+      store[key] = value;
+      return Promise.resolve();
+    }),
+    delete: vi.fn().mockImplementation((key: string) => {
+      delete store[key];
+      return Promise.resolve();
+    }),
+  };
+}
+
+describe('Platform Sentinel - Alert Evaluation', () => {
+  const DEFAULT_THRESHOLDS = {
+    workers: { warningPct: 50, highPct: 75, criticalPct: 90, absoluteMax: 5, enabled: true },
+    d1: { warningPct: 40, highPct: 60, criticalPct: 80, absoluteMax: 20, enabled: true },
+    kv: { warningPct: 50, highPct: 75, criticalPct: 90, absoluteMax: 5, enabled: true },
+    r2: { warningPct: 50, highPct: 75, criticalPct: 90, absoluteMax: 20, enabled: true },
+    vectorize: { warningPct: 50, highPct: 75, criticalPct: 90, absoluteMax: 5, enabled: false },
+  };
+
+  describe('Threshold Levels', () => {
+    it('marks cost as warning when >= 50% of max', () => {
+      // Workers: max $5, 50% = $2.50
+      const currentCost = 2.5;
+      const max = 5;
+      const pct = (currentCost / max) * 100;
+
+      expect(pct).toBeGreaterThanOrEqual(50);
+      expect(pct).toBeLessThan(75);
+    });
+
+    it('marks cost as high when >= 75% of max', () => {
+      // Workers: max $5, 75% = $3.75
+      const currentCost = 3.75;
+      const max = 5;
+      const pct = (currentCost / max) * 100;
+
+      expect(pct).toBeGreaterThanOrEqual(75);
+      expect(pct).toBeLessThan(90);
+    });
+
+    it('marks cost as critical when >= 90% of max', () => {
+      // Workers: max $5, 90% = $4.50
+      const currentCost = 4.5;
+      const max = 5;
+      const pct = (currentCost / max) * 100;
+
+      expect(pct).toBeGreaterThanOrEqual(90);
+    });
+
+    it('escalates to critical when cost exceeds absolute max', () => {
+      // Workers: max $5, current $6
+      const currentCost = 6;
+      const max = 5;
+
+      expect(currentCost).toBeGreaterThan(max);
+    });
+  });
+
+  describe('Cost Delta Detection', () => {
+    it('triggers alert when delta > 50%', () => {
+      const previousCost = 2.0;
+      const currentCost = 3.5;
+      const deltaPct = ((currentCost - previousCost) / previousCost) * 100;
+
+      expect(deltaPct).toBeGreaterThan(50); // 75% increase
+    });
+
+    it('does not trigger on small changes', () => {
+      const previousCost = 2.0;
+      const currentCost = 2.2;
+      const deltaPct = ((currentCost - previousCost) / previousCost) * 100;
+
+      expect(deltaPct).toBeLessThan(50); // 10% increase
+    });
+
+    it('handles zero previous cost', () => {
+      const previousCost = 0;
+      const currentCost = 1.0;
+      const deltaPct = previousCost > 0 ? ((currentCost - previousCost) / previousCost) * 100 : 0;
+
+      expect(deltaPct).toBe(0); // No delta calculation when previous is 0
+    });
+  });
+
+  describe('Service Enable/Disable', () => {
+    it('respects enabled flag on thresholds', () => {
+      const workers = DEFAULT_THRESHOLDS.workers;
+      const vectorize = DEFAULT_THRESHOLDS.vectorize;
+
+      expect(workers.enabled).toBe(true);
+      expect(vectorize.enabled).toBe(false);
+    });
+  });
+});
+
+describe('Platform Sentinel - Rate Limiting', () => {
+  describe('Slack Rate Limiting', () => {
+    it('allows first alert for a resource', async () => {
+      const kv = createMockKV();
+      const key = 'slack:cost-spike:workers';
+
+      // No existing entry
+      const existing = await kv.get(key);
+      expect(existing).toBeNull();
+    });
+
+    it('blocks second alert within 1 hour', async () => {
+      const kv = createMockKV({
+        'slack:cost-spike:workers': new Date().toISOString(),
+      });
+
+      // Entry exists
+      const existing = await kv.get('slack:cost-spike:workers');
+      expect(existing).not.toBeNull();
+    });
+
+    it('stores rate limit key with correct TTL pattern', async () => {
+      const kv = createMockKV();
+
+      await kv.put('slack:cost-spike:workers', new Date().toISOString());
+
+      expect(kv.put).toHaveBeenCalledWith('slack:cost-spike:workers', expect.any(String));
+    });
+  });
+
+  describe('Email Rate Limiting', () => {
+    it('only sends email for high/critical alerts', () => {
+      const thresholdLevels = ['normal', 'warning', 'high', 'critical'];
+      const emailEnabled = thresholdLevels.filter(
+        (level) => level === 'high' || level === 'critical'
+      );
+
+      expect(emailEnabled).toEqual(['high', 'critical']);
+    });
+
+    it('uses longer rate limit (4 hours) than Slack', () => {
+      const SLACK_RATE_LIMIT_TTL = 3600;
+      const EMAIL_RATE_LIMIT_TTL = 14400;
+
+      expect(EMAIL_RATE_LIMIT_TTL).toBe(SLACK_RATE_LIMIT_TTL * 4);
+    });
+  });
+});
+
+describe('Platform Sentinel - KV Data Flow', () => {
+  describe('Threshold Loading', () => {
+    it('merges stored thresholds with defaults', () => {
+      const defaults = {
+        workers: { warningPct: 50, highPct: 75, criticalPct: 90, absoluteMax: 5, enabled: true },
+        d1: { warningPct: 40, highPct: 60, criticalPct: 80, absoluteMax: 20, enabled: true },
+      };
+
+      const stored = {
+        workers: { warningPct: 60, highPct: 80, criticalPct: 95, absoluteMax: 10, enabled: true },
+      };
+
+      const merged = { ...defaults, ...stored };
+
+      // Workers should use stored values
+      expect(merged.workers.absoluteMax).toBe(10);
+      // D1 should use defaults (20, as defined above)
+      expect(merged.d1.absoluteMax).toBe(20);
+    });
+  });
+
+  describe('Cost Storage', () => {
+    it('stores costs with 7-day expiration', async () => {
+      const kv = createMockKV();
+      const costs = {
+        workers: 5.0,
+        d1: 2.0,
+        total: 7.0,
+      };
+
+      await kv.put('platform-sentinel:previous-costs', JSON.stringify(costs));
+
+      const stored = await kv.get('platform-sentinel:previous-costs');
+      expect(stored).toBe(JSON.stringify(costs));
+    });
+
+    it('retrieves previous costs for comparison', async () => {
+      const previousCosts = {
+        workers: 4.0,
+        d1: 1.5,
+        total: 5.5,
+      };
+
+      const kv = createMockKV({
+        'platform-sentinel:previous-costs': JSON.stringify(previousCosts),
+      });
+
+      const stored = await kv.get('platform-sentinel:previous-costs');
+      const parsed = JSON.parse(stored!);
+
+      expect(parsed.workers).toBe(4.0);
+    });
+  });
+
+  describe('Usage Data Loading', () => {
+    it('reads cached usage data from KV', async () => {
+      const usageData = {
+        costs: {
+          workers: 5.0,
+          d1: 2.0,
+          kv: 1.0,
+          r2: 3.0,
+          total: 11.0,
+        },
+      };
+
+      const kv = createMockKV({
+        'usage:30d:all': JSON.stringify(usageData),
+      });
+
+      const stored = await kv.get('usage:30d:all');
+      const parsed = JSON.parse(stored!);
+
+      expect(parsed.costs.total).toBe(11.0);
+    });
+
+    it('handles missing usage data gracefully', async () => {
+      const kv = createMockKV();
+      const stored = await kv.get('usage:30d:all');
+
+      expect(stored).toBeNull();
+    });
+  });
+});
+
+describe('Platform Sentinel - HTTP Endpoints', () => {
+  describe('Health Check', () => {
+    it('returns health status JSON', () => {
+      const response = {
+        status: 'ok',
+        service: 'platform-sentinel',
+        timestamp: expect.any(String),
+      };
+
+      expect(response.status).toBe('ok');
+      expect(response.service).toBe('platform-sentinel');
+    });
+  });
+
+  describe('Manual Trigger', () => {
+    it('accepts POST to /trigger endpoint', () => {
+      const validMethod = 'POST';
+      const validPath = '/trigger';
+
+      expect(validMethod).toBe('POST');
+      expect(validPath).toBe('/trigger');
+    });
+  });
+
+  describe('Root Endpoint', () => {
+    it('returns service info and available endpoints', () => {
+      const response = {
+        service: 'platform-sentinel',
+        endpoints: ['/health', '/trigger (POST)'],
+      };
+
+      expect(response.endpoints).toContain('/health');
+      expect(response.endpoints).toContain('/trigger (POST)');
+    });
+  });
+});
+
+describe('Platform Sentinel - Alert Message Formatting', () => {
+  describe('Service Name Formatting', () => {
+    const formatServiceName = (service: string): string => {
+      const names: Record<string, string> = {
+        workers: 'Workers',
+        d1: 'D1 Database',
+        kv: 'KV Storage',
+        r2: 'R2 Storage',
+        durableObjects: 'Durable Objects',
+        vectorize: 'Vectorize',
+        aiGateway: 'AI Gateway',
+        pages: 'Pages',
+        queues: 'Queues',
+        workflows: 'Workflows',
+      };
+      return names[service] || service;
+    };
+
+    it('formats workers correctly', () => {
+      expect(formatServiceName('workers')).toBe('Workers');
+    });
+
+    it('formats d1 correctly', () => {
+      expect(formatServiceName('d1')).toBe('D1 Database');
+    });
+
+    it('formats durableObjects correctly', () => {
+      expect(formatServiceName('durableObjects')).toBe('Durable Objects');
+    });
+
+    it('returns raw name for unknown services', () => {
+      expect(formatServiceName('unknown')).toBe('unknown');
+    });
+  });
+
+  describe('Currency Formatting', () => {
+    const formatCurrency = (amount: number): string => `$${amount.toFixed(2)}`;
+
+    it('formats whole numbers with cents', () => {
+      expect(formatCurrency(5)).toBe('$5.00');
+    });
+
+    it('formats decimals correctly', () => {
+      expect(formatCurrency(5.5)).toBe('$5.50');
+    });
+
+    it('rounds to 2 decimal places', () => {
+      // Note: JavaScript toFixed uses banker's rounding
+      expect(formatCurrency(5.556)).toBe('$5.56');
+    });
+  });
+
+  describe('Percentage Formatting', () => {
+    const formatPercentage = (pct: number): string => {
+      const sign = pct >= 0 ? '+' : '';
+      return `${sign}${pct.toFixed(1)}%`;
+    };
+
+    it('adds plus sign to positive values', () => {
+      expect(formatPercentage(50)).toBe('+50.0%');
+    });
+
+    it('preserves minus sign on negative values', () => {
+      expect(formatPercentage(-25)).toBe('-25.0%');
+    });
+
+    it('formats zero with plus sign', () => {
+      expect(formatPercentage(0)).toBe('+0.0%');
+    });
+  });
+
+  describe('Severity Colours', () => {
+    const getColour = (level: string): string => {
+      const colours: Record<string, string> = {
+        critical: '#dc3545',
+        high: '#fd7e14',
+        warning: '#ffc107',
+        normal: '#28a745',
+      };
+      return colours[level] || '#17a2b8';
+    };
+
+    it('returns red for critical', () => {
+      expect(getColour('critical')).toBe('#dc3545');
+    });
+
+    it('returns orange for high', () => {
+      expect(getColour('high')).toBe('#fd7e14');
+    });
+
+    it('returns yellow for warning', () => {
+      expect(getColour('warning')).toBe('#ffc107');
+    });
+
+    it('returns default blue for unknown', () => {
+      expect(getColour('unknown')).toBe('#17a2b8');
+    });
+  });
+
+  describe('Severity Emojis', () => {
+    const getEmoji = (level: string): string => {
+      const emojis: Record<string, string> = {
+        critical: ':rotating_light:',
+        high: ':warning:',
+        warning: ':yellow_circle:',
+        normal: ':white_check_mark:',
+      };
+      return emojis[level] || ':bell:';
+    };
+
+    it('returns siren for critical', () => {
+      expect(getEmoji('critical')).toBe(':rotating_light:');
+    });
+
+    it('returns warning for high', () => {
+      expect(getEmoji('high')).toBe(':warning:');
+    });
+
+    it('returns default bell for unknown', () => {
+      expect(getEmoji('unknown')).toBe(':bell:');
+    });
+  });
+
+  describe('Action Text', () => {
+    const getActionText = (level: string): string => {
+      switch (level) {
+        case 'critical':
+          return 'Investigate immediately - usage significantly exceeds budget';
+        case 'high':
+          return 'Review usage patterns and consider optimisation';
+        case 'warning':
+          return 'Monitor closely - approaching threshold';
+        default:
+          return 'No action required';
+      }
+    };
+
+    it('returns urgent text for critical', () => {
+      expect(getActionText('critical')).toContain('immediately');
+    });
+
+    it('returns review text for high', () => {
+      expect(getActionText('high')).toContain('Review');
+    });
+
+    it('returns monitor text for warning', () => {
+      expect(getActionText('warning')).toContain('Monitor');
+    });
+
+    it('returns no action for normal', () => {
+      expect(getActionText('normal')).toContain('No action');
+    });
+  });
+});
+
+describe('Platform Sentinel - Complete Workflow', () => {
+  it('follows correct execution order', () => {
+    const steps = [
+      '1. Load thresholds from KV',
+      '2. Fetch current costs from Usage API',
+      '3. Load previous costs from KV',
+      '4. Evaluate alerts',
+      '5. Send alerts (with rate limiting)',
+      '6. Store current costs for next comparison',
+    ];
+
+    expect(steps).toHaveLength(6);
+    expect(steps[0]).toContain('thresholds');
+    expect(steps[1]).toContain('current costs');
+    expect(steps[2]).toContain('previous costs');
+    expect(steps[3]).toContain('Evaluate');
+    expect(steps[4]).toContain('Send');
+    expect(steps[5]).toContain('Store');
+  });
+
+  it('handles missing current costs gracefully', async () => {
+    const kv = createMockKV(); // No usage data
+
+    const usageData = await kv.get('usage:30d:all');
+
+    // Should return early without errors
+    expect(usageData).toBeNull();
+  });
+
+  it('skips sending if no alerts generated', () => {
+    const costs = {
+      workers: 1.0, // Well under $5 max
+      d1: 2.0, // Well under $10 max
+      total: 3.0,
+    };
+
+    const previousCosts = {
+      workers: 0.9, // Small 11% increase
+      d1: 1.9, // Small 5% increase
+      total: 2.8,
+    };
+
+    // Check that delta is below threshold
+    const workersDelta = ((costs.workers - previousCosts.workers) / previousCosts.workers) * 100;
+    expect(workersDelta).toBeLessThan(50);
+  });
+});