@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/cloudflare-deploy/references/stream/patterns.md

@@ -0,0 +1,184 @@
+# Stream Patterns
+
+Common workflows, full-stack flows, and best practices.
+
+## React Stream Player
+
+`npm install @cloudflare/stream-react`
+
+```tsx
+import { Stream } from '@cloudflare/stream-react';
+
+export function VideoPlayer({ videoId, token }: { videoId: string; token?: string }) {
+  return <Stream controls src={token ? `${videoId}?token=${token}` : videoId} responsive />;
+}
+```
+
+## Full-Stack Upload Flow
+
+**Backend API (Workers/Pages)**
+```typescript
+import Cloudflare from 'cloudflare';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const { videoName } = await request.json();
+    const client = new Cloudflare({ apiToken: env.CF_API_TOKEN });
+    const { uploadURL, uid } = await client.stream.directUpload.create({
+      account_id: env.CF_ACCOUNT_ID,
+      maxDurationSeconds: 3600,
+      requireSignedURLs: true,
+      meta: { name: videoName }
+    });
+    return Response.json({ uploadURL, uid });
+  }
+};
+```
+
+**Frontend component**
+```tsx
+import { useState } from 'react';
+
+export function VideoUploader() {
+  const [uploading, setUploading] = useState(false);
+  const [progress, setProgress] = useState(0);
+  
+  async function handleUpload(file: File) {
+    setUploading(true);
+    const { uploadURL, uid } = await fetch('/api/upload-url', {
+      method: 'POST',
+      body: JSON.stringify({ videoName: file.name })
+    }).then(r => r.json());
+    
+    const xhr = new XMLHttpRequest();
+    xhr.upload.onprogress = (e) => setProgress((e.loaded / e.total) * 100);
+    xhr.onload = () => { setUploading(false); window.location.href = `/videos/${uid}`; };
+    xhr.open('POST', uploadURL);
+    const formData = new FormData();
+    formData.append('file', file);
+    xhr.send(formData);
+  }
+  
+  return (
+    <div>
+      <input type="file" accept="video/*" onChange={(e) => e.target.files?.[0] && handleUpload(e.target.files[0])} disabled={uploading} />
+      {uploading && <progress value={progress} max={100} />}
+    </div>
+  );
+}
+```
+
+## TUS Resumable Upload
+
+For large files (>500MB). `npm install tus-js-client`
+
+```typescript
+import * as tus from 'tus-js-client';
+
+async function uploadWithTUS(file: File, uploadURL: string, onProgress?: (pct: number) => void) {
+  return new Promise<string>((resolve, reject) => {
+    const upload = new tus.Upload(file, {
+      endpoint: uploadURL,
+      retryDelays: [0, 3000, 5000, 10000, 20000],
+      chunkSize: 50 * 1024 * 1024,
+      metadata: { filename: file.name, filetype: file.type },
+      onError: reject,
+      onProgress: (up, total) => onProgress?.((up / total) * 100),
+      onSuccess: () => resolve(upload.url?.split('/').pop() || '')
+    });
+    upload.start();
+  });
+}
+```
+
+## Video State Polling
+
+```typescript
+async function waitForVideoReady(client: Cloudflare, accountId: string, videoId: string) {
+  for (let i = 0; i < 60; i++) {
+    const video = await client.stream.videos.get(videoId, { account_id: accountId });
+    if (video.readyToStream || video.status.state === 'error') return video;
+    await new Promise(resolve => setTimeout(resolve, 5000));
+  }
+  throw new Error('Video processing timeout');
+}
+```
+
+## Webhook Handler
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const signature = request.headers.get('Webhook-Signature');
+    const body = await request.text();
+    if (!signature || !await verifyWebhook(signature, body, env.WEBHOOK_SECRET)) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+    const payload = JSON.parse(body);
+    if (payload.readyToStream) console.log(`Video ${payload.uid} ready`);
+    return new Response('OK');
+  }
+};
+
+async function verifyWebhook(sig: string, body: string, secret: string): Promise<boolean> {
+  const parts = Object.fromEntries(sig.split(',').map(p => p.split('=')));
+  const timestamp = parseInt(parts.time || '0', 10);
+  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
+  
+  const key = await crypto.subtle.importKey(
+    'raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']
+  );
+  const computed = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${timestamp}.${body}`));
+  const hex = Array.from(new Uint8Array(computed), b => b.toString(16).padStart(2, '0')).join('');
+  return hex === parts.sig1;
+}
+```
+
+## Self-Sign JWT (High Volume Tokens)
+
+For >1k tokens/day. Prerequisites: Create signing key (see configuration.md).
+
+```typescript
+async function selfSignToken(keyId: string, jwkBase64: string, videoId: string, expiresIn = 3600) {
+  const key = await crypto.subtle.importKey(
+    'jwk', JSON.parse(atob(jwkBase64)), { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign']
+  );
+  const now = Math.floor(Date.now() / 1000);
+  const header = btoa(JSON.stringify({ alg: 'RS256', kid: keyId })).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+  const payload = btoa(JSON.stringify({ sub: videoId, kid: keyId, exp: now + expiresIn, nbf: now }))
+    .replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+  const message = `${header}.${payload}`;
+  const sig = await crypto.subtle.sign('RSASSA-PKCS1-v1_5', key, new TextEncoder().encode(message));
+  const b64Sig = btoa(String.fromCharCode(...new Uint8Array(sig))).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+  return `${message}.${b64Sig}`;
+}
+
+// With access rules (geo-restriction)
+const payloadWithRules = {
+  sub: videoId, kid: keyId, exp: now + 3600, nbf: now,
+  accessRules: [{ type: 'ip.geoip.country', action: 'allow', country: ['US'] }]
+};
+```
+
+## Best Practices
+
+- **Use Direct Creator Uploads** - Avoid proxying through servers
+- **Enable requireSignedURLs** - Control private content access
+- **Self-sign tokens at scale** - Use signing keys for >1k/day
+- **Set allowedOrigins** - Prevent hotlinking
+- **Use webhooks over polling** - Efficient status updates
+- **Set maxDurationSeconds** - Prevent abuse
+- **Enable live recordings** - Auto VOD after stream
+
+## In This Reference
+
+- [README.md](./README.md) - Overview and quick start
+- [configuration.md](./configuration.md) - Setup and config
+- [api.md](./api.md) - On-demand video APIs
+- [api-live.md](./api-live.md) - Live streaming APIs
+- [gotchas.md](./gotchas.md) - Error codes, troubleshooting
+
+## See Also
+
+- [workers](../workers/) - Deploy Stream APIs in Workers
+- [pages](../pages/) - Integrate Stream with Pages

package/skills/cloudflare-deploy/references/tail-workers/README.md

@@ -0,0 +1,89 @@
+# Cloudflare Tail Workers
+
+Specialized Workers that consume execution events from producer Workers for logging, debugging, analytics, and observability.
+
+## When to Use This Reference
+
+- Implementing observability/logging for Cloudflare Workers
+- Processing Worker execution events, logs, exceptions
+- Building custom analytics or error tracking
+- Configuring real-time event streaming
+- Working with tail handlers or tail consumers
+
+## Core Concepts
+
+### What Are Tail Workers?
+
+Tail Workers automatically process events from producer Workers (the Workers being monitored). They receive:
+- HTTP request/response info
+- Console logs (`console.log/error/warn/debug`)
+- Uncaught exceptions
+- Execution outcomes (`ok`, `exception`, `exceededCpu`, etc.)
+- Diagnostic channel events
+
+**Key characteristics:**
+- Invoked AFTER producer finishes executing
+- Capture entire request lifecycle including Service Bindings and Dynamic Dispatch sub-requests
+- Billed by CPU time, not request count
+- Available on Workers Paid and Enterprise tiers
+
+### Alternative: OpenTelemetry Export
+
+**Before using Tail Workers, consider OpenTelemetry:**
+
+For batch exports to observability tools (Sentry, Grafana, Honeycomb):
+- OTEL export sends logs/traces in batches (more efficient)
+- Built-in integrations with popular platforms
+- Lower overhead than Tail Workers
+- **Use Tail Workers only for custom real-time processing**
+
+## Decision Tree
+
+```
+Need observability for Workers?
+├─ Batch export to known tools (Sentry/Grafana/Honeycomb)?
+│  └─ Use OpenTelemetry export (not Tail Workers)
+├─ Custom real-time processing needed?
+│  ├─ Aggregated metrics?
+│  │  └─ Use Tail Worker + Analytics Engine
+│  ├─ Error tracking?
+│  │  └─ Use Tail Worker + external service
+│  ├─ Custom logging/debugging?
+│  │  └─ Use Tail Worker + KV/HTTP endpoint
+│  └─ Complex event processing?
+│     └─ Use Tail Worker + Durable Objects
+└─ Quick debugging?
+   └─ Use `wrangler tail` (different from Tail Workers)
+```
+
+## Reading Order
+
+1. **[configuration.md](configuration.md)** - Set up Tail Workers
+2. **[api.md](api.md)** - Handler signature, types, redaction
+3. **[patterns.md](patterns.md)** - Common use cases and integrations
+4. **[gotchas.md](gotchas.md)** - Pitfalls and debugging tips
+
+## Quick Example
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    // Process events from producer Worker
+    ctx.waitUntil(
+      fetch(env.LOG_ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(events),
+      })
+    );
+  }
+};
+```
+
+## Related Skills
+
+- **observability** - General Workers observability patterns, OTEL export
+- **analytics-engine** - Aggregated metrics storage for tail event data
+- **durable-objects** - Stateful event processing, batching tail events
+- **logpush** - Alternative for batch log export (non-real-time)
+- **workers-for-platforms** - Dynamic dispatch with tail consumers

package/skills/cloudflare-deploy/references/tail-workers/api.md

@@ -0,0 +1,200 @@
+# Tail Workers API Reference
+
+## Handler Signature
+
+```typescript
+export default {
+  async tail(
+    events: TraceItem[],
+    env: Env,
+    ctx: ExecutionContext
+  ): Promise<void> {
+    // Process events
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+**Parameters:**
+- `events`: Array of `TraceItem` objects (one per producer invocation)
+- `env`: Bindings (KV, D1, R2, env vars, etc.)
+- `ctx`: Context with `waitUntil()` for async work
+
+**CRITICAL:** Tail handlers don't return values. Use `ctx.waitUntil()` for async operations.
+
+## TraceItem Type
+
+```typescript
+interface TraceItem {
+  scriptName: string;           // Producer Worker name
+  eventTimestamp: number;        // Epoch milliseconds
+  outcome: 'ok' | 'exception' | 'exceededCpu' | 'exceededMemory' 
+         | 'canceled' | 'scriptNotFound' | 'responseStreamDisconnected' | 'unknown';
+  
+  event?: {
+    request?: {
+      url: string;               // Redacted by default
+      method: string;
+      headers: Record<string, string>;  // Sensitive headers redacted
+      cf?: IncomingRequestCfProperties;
+      getUnredacted(): TraceRequest;    // Bypass redaction (use carefully)
+    };
+    response?: {
+      status: number;
+    };
+  };
+  
+  logs: Array<{
+    timestamp: number;           // Epoch milliseconds
+    level: 'debug' | 'info' | 'log' | 'warn' | 'error';
+    message: unknown[];          // Args passed to console function
+  }>;
+  
+  exceptions: Array<{
+    timestamp: number;           // Epoch milliseconds
+    name: string;                // Error type (Error, TypeError, etc.)
+    message: string;             // Error description
+  }>;
+  
+  diagnosticsChannelEvents: Array<{
+    channel: string;
+    message: unknown;
+    timestamp: number;           // Epoch milliseconds
+  }>;
+}
+```
+
+**Note:** Official SDK uses `TraceItem`, not `TailItem`. Use `@cloudflare/workers-types` for accurate types.
+
+## Timestamp Handling
+
+All timestamps are **epoch milliseconds**, not seconds:
+
+```typescript
+// ✅ CORRECT - use directly with Date
+const date = new Date(event.eventTimestamp);
+
+// ❌ WRONG - don't multiply by 1000
+const date = new Date(event.eventTimestamp * 1000);
+```
+
+## Automatic Redaction
+
+By default, sensitive data is redacted from `TraceRequest`:
+
+### Header Redaction
+
+Headers containing these substrings (case-insensitive):
+- `auth`, `key`, `secret`, `token`, `jwt`
+- `cookie`, `set-cookie`
+
+Redacted values show as `"REDACTED"`.
+
+### URL Redaction
+
+- **Hex IDs:** 32+ hex digits → `"REDACTED"`
+- **Base-64 IDs:** 21+ chars with 2+ upper, 2+ lower, 2+ digits → `"REDACTED"`
+
+## Bypassing Redaction
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    for (const event of events) {
+      // ⚠️ Use with extreme caution
+      const unredacted = event.event?.request?.getUnredacted();
+      // unredacted.url and unredacted.headers contain raw values
+    }
+  }
+};
+```
+
+**Best practices:**
+- Only call `getUnredacted()` when absolutely necessary
+- Never log unredacted sensitive data
+- Implement additional filtering before external transmission
+- Use environment variables for API keys, never hardcode
+
+## Type-Safe Handler
+
+```typescript
+interface Env {
+  LOGS_KV: KVNamespace;
+  ANALYTICS: AnalyticsEngineDataset;
+  LOG_ENDPOINT: string;
+  API_TOKEN: string;
+}
+
+export default {
+  async tail(
+    events: TraceItem[],
+    env: Env,
+    ctx: ExecutionContext
+  ): Promise<void> {
+    const payload = events.map(event => ({
+      script: event.scriptName,
+      timestamp: event.eventTimestamp,
+      outcome: event.outcome,
+      url: event.event?.request?.url,
+      status: event.event?.response?.status,
+    }));
+    
+    ctx.waitUntil(
+      fetch(env.LOG_ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      })
+    );
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## Outcome vs HTTP Status
+
+**IMPORTANT:** `outcome` is script execution status, NOT HTTP status.
+
+- Worker returns 500 → `outcome='ok'` if script completed successfully
+- Uncaught exception → `outcome='exception'` regardless of HTTP status
+- CPU limit exceeded → `outcome='exceededCpu'`
+
+```typescript
+// ✅ Check outcome for script execution status
+if (event.outcome === 'exception') {
+  // Script threw uncaught exception
+}
+
+// ✅ Check HTTP status separately
+if (event.event?.response?.status === 500) {
+  // HTTP 500 returned (script may have handled error)
+}
+```
+
+## Serialization Considerations
+
+`log.message` is `unknown[]` and may contain non-serializable objects:
+
+```typescript
+// ❌ May fail with circular references or BigInt
+JSON.stringify(events);
+
+// ✅ Safe serialization
+const safePayload = events.map(event => ({
+  ...event,
+  logs: event.logs.map(log => ({
+    ...log,
+    message: log.message.map(m => {
+      try {
+        return JSON.parse(JSON.stringify(m));
+      } catch {
+        return String(m);
+      }
+    })
+  }))
+}));
+```
+
+**Common serialization issues:**
+- Circular references in logged objects
+- `BigInt` values (not JSON-serializable)
+- Functions or symbols in console.log arguments
+- Large objects exceeding body size limits

package/skills/cloudflare-deploy/references/tail-workers/configuration.md

@@ -0,0 +1,176 @@
+# Tail Workers Configuration
+
+## Setup Steps
+
+### 1. Create Tail Worker
+
+Create a Worker with a `tail()` handler:
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    // Process events from producer Worker
+    ctx.waitUntil(
+      fetch(env.LOG_ENDPOINT, {
+        method: "POST",
+        body: JSON.stringify(events),
+      })
+    );
+  }
+};
+```
+
+### 2. Configure Producer Worker
+
+In producer's `wrangler.jsonc`:
+
+```jsonc
+{
+  "name": "my-producer-worker",
+  "tail_consumers": [
+    {
+      "service": "my-tail-worker"
+    }
+  ]
+}
+```
+
+### 3. Deploy Both Workers
+
+```bash
+# Deploy Tail Worker first
+cd tail-worker
+wrangler deploy
+
+# Then deploy producer Worker
+cd ../producer-worker
+wrangler deploy
+```
+
+## Wrangler Configuration
+
+### Single Tail Consumer
+
+```jsonc
+{
+  "name": "producer-worker",
+  "tail_consumers": [
+    {
+      "service": "logging-tail-worker"
+    }
+  ]
+}
+```
+
+### Multiple Tail Consumers
+
+```jsonc
+{
+  "name": "producer-worker",
+  "tail_consumers": [
+    {
+      "service": "logging-tail-worker"
+    },
+    {
+      "service": "metrics-tail-worker"
+    }
+  ]
+}
+```
+
+**Note:** Each consumer receives ALL events independently.
+
+### Remove Tail Consumer
+
+```jsonc
+{
+  "tail_consumers": []
+}
+```
+
+Then redeploy producer Worker.
+
+## Environment Variables
+
+Tail Workers use same binding syntax as regular Workers:
+
+```jsonc
+{
+  "name": "my-tail-worker",
+  "vars": {
+    "LOG_ENDPOINT": "https://logs.example.com/ingest"
+  },
+  "kv_namespaces": [
+    {
+      "binding": "LOGS_KV",
+      "id": "abc123..."
+    }
+  ]
+}
+```
+
+## Testing & Development
+
+### Local Testing
+
+**Tail Workers cannot be fully tested with `wrangler dev`.** Deploy to staging environment for testing.
+
+### Testing Strategy
+
+1. Deploy producer Worker to staging
+2. Deploy Tail Worker to staging
+3. Configure `tail_consumers` in producer
+4. Trigger producer Worker requests
+5. Verify Tail Worker receives events (check destination logs/storage)
+
+### Wrangler Tail Command
+
+```bash
+# Stream logs to terminal (NOT Tail Workers)
+wrangler tail my-producer-worker
+```
+
+**This is different from Tail Workers:**
+- `wrangler tail` streams logs to your terminal
+- Tail Workers are Workers that process events programmatically
+
+## Deployment Checklist
+
+- [ ] Tail Worker has `tail()` handler
+- [ ] Tail Worker deployed before producer
+- [ ] Producer's `wrangler.jsonc` has correct `tail_consumers`
+- [ ] Environment variables configured
+- [ ] Tested with staging environment
+- [ ] Monitoring configured for Tail Worker itself
+
+## Limits
+
+| Limit | Value | Notes |
+|-------|-------|-------|
+| Max tail consumers per producer | 10 | Each receives all events independently |
+| Events batch size | Up to 100 events per invocation | Larger batches split across invocations |
+| Tail Worker CPU time | Same as regular Workers | 10ms (free), 30ms (paid), 50ms (paid bundle) |
+| Pricing tier | Workers Paid or Enterprise | Not available on free plan |
+| Request body size | 100 MB max | When sending to external endpoints |
+| Event retention | None | Events not retried if tail handler fails |
+
+## Workers for Platforms
+
+For dynamic dispatch Workers, both dispatch and user Worker events sent to tail consumer:
+
+```jsonc
+{
+  "name": "dispatch-worker",
+  "tail_consumers": [
+    {
+      "service": "platform-tail-worker"
+    }
+  ]
+}
+```
+
+Tail Worker receives TWO `TraceItem` elements per request:
+1. Dynamic dispatch Worker event
+2. User Worker event
+
+See [patterns.md](patterns.md) for handling.