@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/web-workers.md

@@ -0,0 +1,327 @@
+---
+name: web-workers
+description: Web Worker patterns for shared workers, service workers, Comlink RPC, transferable objects, and WebAssembly integration.
+---
+
+# Web Worker Patterns
+
+## When to Use
+Use Web Workers when you need to run CPU-intensive tasks without blocking the main thread. This includes image processing, data parsing, cryptographic operations, sorting large datasets, and running WebAssembly modules. Workers keep the UI responsive by moving computation off the main thread. Use Comlink to simplify the messaging API, and transferable objects to avoid expensive data copies.
+
+## How It Works
+
+### Basic Dedicated Worker
+
+```typescript
+// src/workers/data-processor.worker.ts
+interface ProcessRequest {
+  type: 'sort' | 'filter' | 'aggregate';
+  data: number[];
+  options?: { ascending?: boolean; threshold?: number };
+}
+
+self.addEventListener('message', (event: MessageEvent<ProcessRequest>) => {
+  const { type, data, options } = event.data;
+
+  let result: unknown;
+
+  switch (type) {
+    case 'sort':
+      result = [...data].sort((a, b) => options?.ascending ? a - b : b - a);
+      break;
+    case 'filter':
+      result = data.filter((n) => n >= (options?.threshold ?? 0));
+      break;
+    case 'aggregate':
+      result = {
+        sum: data.reduce((a, b) => a + b, 0),
+        avg: data.reduce((a, b) => a + b, 0) / data.length,
+        min: Math.min(...data),
+        max: Math.max(...data),
+      };
+      break;
+  }
+
+  self.postMessage({ type, result });
+});
+```
+
+```typescript
+// src/use-worker.ts
+export function createDataProcessor() {
+  const worker = new Worker(
+    new URL('./workers/data-processor.worker.ts', import.meta.url),
+    { type: 'module' }
+  );
+
+  return {
+    process(request: ProcessRequest): Promise<unknown> {
+      return new Promise((resolve) => {
+        const handler = (event: MessageEvent) => {
+          if (event.data.type === request.type) {
+            worker.removeEventListener('message', handler);
+            resolve(event.data.result);
+          }
+        };
+        worker.addEventListener('message', handler);
+        worker.postMessage(request);
+      });
+    },
+    terminate: () => worker.terminate(),
+  };
+}
+```
+
+### Comlink RPC (Simplified Messaging)
+
+```typescript
+// src/workers/image-processor.worker.ts
+import * as Comlink from 'comlink';
+
+class ImageProcessor {
+  async resize(imageData: ImageData, width: number, height: number): Promise<ImageData> {
+    const canvas = new OffscreenCanvas(width, height);
+    const ctx = canvas.getContext('2d')!;
+    const bitmap = await createImageBitmap(imageData);
+    ctx.drawImage(bitmap, 0, 0, width, height);
+    return ctx.getImageData(0, 0, width, height);
+  }
+
+  async grayscale(imageData: ImageData): Promise<ImageData> {
+    const data = new Uint8ClampedArray(imageData.data);
+    for (let i = 0; i < data.length; i += 4) {
+      const avg = (data[i] + data[i + 1] + data[i + 2]) / 3;
+      data[i] = data[i + 1] = data[i + 2] = avg;
+    }
+    return new ImageData(data, imageData.width, imageData.height);
+  }
+
+  async blur(imageData: ImageData, radius: number): Promise<ImageData> {
+    const { width, height, data } = imageData;
+    const output = new Uint8ClampedArray(data);
+    // Simple box blur
+    for (let y = radius; y < height - radius; y++) {
+      for (let x = radius; x < width - radius; x++) {
+        for (let c = 0; c < 3; c++) {
+          let sum = 0, count = 0;
+          for (let dy = -radius; dy <= radius; dy++) {
+            for (let dx = -radius; dx <= radius; dx++) {
+              sum += data[((y + dy) * width + (x + dx)) * 4 + c];
+              count++;
+            }
+          }
+          output[(y * width + x) * 4 + c] = sum / count;
+        }
+      }
+    }
+    return new ImageData(output, width, height);
+  }
+}
+
+Comlink.expose(new ImageProcessor());
+```
+
+```typescript
+// src/image-client.ts
+import * as Comlink from 'comlink';
+
+type ImageProcessor = {
+  resize(data: ImageData, w: number, h: number): Promise<ImageData>;
+  grayscale(data: ImageData): Promise<ImageData>;
+  blur(data: ImageData, radius: number): Promise<ImageData>;
+};
+
+const worker = new Worker(
+  new URL('./workers/image-processor.worker.ts', import.meta.url),
+  { type: 'module' }
+);
+const processor = Comlink.wrap<ImageProcessor>(worker);
+
+// Usage — call worker methods like local async functions
+const resized = await processor.resize(imageData, 800, 600);
+const gray = await processor.grayscale(imageData);
+```
+
+### Transferable Objects (Zero-Copy)
+
+```typescript
+// src/workers/transfer-worker.ts
+self.addEventListener('message', (event: MessageEvent) => {
+  const buffer: ArrayBuffer = event.data;
+  const view = new Float64Array(buffer);
+
+  // Process in-place
+  for (let i = 0; i < view.length; i++) {
+    view[i] = Math.sqrt(view[i]);
+  }
+
+  // Transfer back — zero copy
+  self.postMessage(buffer, [buffer]);
+});
+```
+
+```typescript
+// Main thread — transfer ownership to worker
+const data = new Float64Array(1_000_000);
+for (let i = 0; i < data.length; i++) data[i] = Math.random() * 1000;
+
+// Transfer ownership — main thread loses access, no copy made
+worker.postMessage(data.buffer, [data.buffer]);
+// data.buffer.byteLength === 0 after transfer
+
+worker.addEventListener('message', (event) => {
+  const result = new Float64Array(event.data);
+  console.log('Processed:', result.length, 'items');
+});
+```
+
+### Shared Worker (Multiple Tabs)
+
+```typescript
+// src/workers/shared-state.worker.ts
+const connections: MessagePort[] = [];
+let sharedState: Record<string, unknown> = {};
+
+self.addEventListener('connect', (event: MessageEvent) => {
+  const port = (event as any).ports[0] as MessagePort;
+  connections.push(port);
+
+  port.addEventListener('message', (msg: MessageEvent) => {
+    const { action, key, value } = msg.data;
+
+    if (action === 'set') {
+      sharedState[key] = value;
+      // Broadcast to all connected tabs
+      connections.forEach((p) => p.postMessage({ type: 'update', state: sharedState }));
+    }
+
+    if (action === 'get') {
+      port.postMessage({ type: 'state', state: sharedState });
+    }
+  });
+
+  port.start();
+  port.postMessage({ type: 'state', state: sharedState });
+});
+```
+
+```typescript
+// Main thread — connect to shared worker
+const shared = new SharedWorker(
+  new URL('./workers/shared-state.worker.ts', import.meta.url),
+  { type: 'module' }
+);
+
+shared.port.addEventListener('message', (event) => {
+  if (event.data.type === 'update') {
+    console.log('State updated across tabs:', event.data.state);
+  }
+});
+shared.port.start();
+
+// Set value (broadcasts to all tabs)
+shared.port.postMessage({ action: 'set', key: 'user', value: { name: 'Alice' } });
+```
+
+### WASM Integration in Worker
+
+```typescript
+// src/workers/wasm-worker.ts
+import * as Comlink from 'comlink';
+
+let wasmInstance: WebAssembly.Instance | null = null;
+
+async function initWasm(): Promise<void> {
+  if (wasmInstance) return;
+  const response = await fetch('/compute.wasm');
+  const { instance } = await WebAssembly.instantiateStreaming(response);
+  wasmInstance = instance;
+}
+
+const wasmApi = {
+  async fibonacci(n: number): Promise<number> {
+    await initWasm();
+    return (wasmInstance!.exports.fibonacci as (n: number) => number)(n);
+  },
+
+  async processBuffer(data: ArrayBuffer): Promise<ArrayBuffer> {
+    await initWasm();
+    const memory = wasmInstance!.exports.memory as WebAssembly.Memory;
+    const alloc = wasmInstance!.exports.alloc as (size: number) => number;
+    const process = wasmInstance!.exports.process as (ptr: number, len: number) => number;
+
+    const inputPtr = alloc(data.byteLength);
+    new Uint8Array(memory.buffer, inputPtr, data.byteLength).set(new Uint8Array(data));
+
+    const outputPtr = process(inputPtr, data.byteLength);
+    const output = new Uint8Array(memory.buffer, outputPtr, data.byteLength).slice();
+
+    return output.buffer;
+  },
+};
+
+Comlink.expose(wasmApi);
+```
+
+### Worker Pool
+
+```typescript
+// src/worker-pool.ts
+export class WorkerPool<T> {
+  private workers: Worker[] = [];
+  private queue: Array<{ resolve: (v: T) => void; args: unknown }> = [];
+  private busy = new Set<Worker>();
+
+  constructor(private workerUrl: URL, private size: number = navigator.hardwareConcurrency) {
+    for (let i = 0; i < this.size; i++) {
+      this.workers.push(new Worker(workerUrl, { type: 'module' }));
+    }
+  }
+
+  async execute(args: unknown): Promise<T> {
+    const available = this.workers.find((w) => !this.busy.has(w));
+    if (available) return this.dispatch(available, args);
+
+    return new Promise((resolve) => {
+      this.queue.push({ resolve, args });
+    });
+  }
+
+  private dispatch(worker: Worker, args: unknown): Promise<T> {
+    this.busy.add(worker);
+    return new Promise((resolve) => {
+      worker.onmessage = (event: MessageEvent<T>) => {
+        this.busy.delete(worker);
+        resolve(event.data);
+        const next = this.queue.shift();
+        if (next) this.dispatch(worker, next.args).then(next.resolve);
+      };
+      worker.postMessage(args);
+    });
+  }
+
+  terminate() {
+    this.workers.forEach((w) => w.terminate());
+  }
+}
+```
+
+## Examples
+
+| Pattern | Overhead | Use Case |
+|---------|----------|----------|
+| Dedicated Worker | ~1ms message | Image processing, sorting |
+| Shared Worker | ~1ms message | Cross-tab state sync |
+| Comlink | ~2ms message | Complex API, many methods |
+| Transferable | Zero-copy | Large ArrayBuffer operations |
+| Worker Pool | Pool management | Parallel batch processing |
+| WASM in Worker | Init once | Heavy compute (crypto, codec) |
+
+## Checklist
+- [ ] Workers created with `new URL()` for bundler compatibility
+- [ ] Comlink used for complex worker APIs to avoid manual message handling
+- [ ] Large buffers transferred, not copied, using `[buffer]` transfer list
+- [ ] Worker pool size matches `navigator.hardwareConcurrency`
+- [ ] Workers terminated when no longer needed to free resources
+- [ ] Error handler (`onerror`) set on every worker instance
+- [ ] Feature detection before using SharedWorker or WebAssembly

package/assets/skills/webhooks-patterns.md

@@ -0,0 +1,283 @@
+---
+name: webhooks-patterns
+description: Webhook patterns with signature verification, retry logic, idempotency keys, event ordering, and testing.
+---
+
+# Webhook Patterns
+
+## When to Use
+Apply when building webhook consumers (receiving events from Stripe, GitHub, etc.) or webhook producers (sending events to your users' endpoints). Webhooks are HTTP callbacks -- the sender POSTs to your URL when an event occurs. The key challenges are verification, reliability, idempotency, and ordering.
+
+## How It Works
+
+### Receiving Webhooks -- Signature Verification
+
+Always verify the webhook signature. Never trust the payload without it:
+
+```typescript
+import crypto from "crypto";
+import express from "express";
+
+// Stripe signature verification
+app.post(
+  "/webhooks/stripe",
+  express.raw({ type: "application/json" }),
+  (req, res) => {
+    const sig = req.headers["stripe-signature"] as string;
+    try {
+      const event = stripe.webhooks.constructEvent(
+        req.body,
+        sig,
+        process.env.STRIPE_WEBHOOK_SECRET!
+      );
+      processEvent(event);
+      res.json({ received: true });
+    } catch (err) {
+      res.status(400).send("Invalid signature");
+    }
+  }
+);
+
+// Generic HMAC-SHA256 verification (GitHub, custom webhooks)
+function verifyWebhookSignature(
+  payload: Buffer,
+  signature: string,
+  secret: string
+): boolean {
+  const expected = crypto
+    .createHmac("sha256", secret)
+    .update(payload)
+    .digest("hex");
+  const received = signature.replace("sha256=", "");
+  return crypto.timingSafeEqual(
+    Buffer.from(expected, "hex"),
+    Buffer.from(received, "hex")
+  );
+}
+
+app.post(
+  "/webhooks/github",
+  express.raw({ type: "application/json" }),
+  (req, res) => {
+    const sig = req.headers["x-hub-signature-256"] as string;
+    if (!verifyWebhookSignature(req.body, sig, process.env.GITHUB_WEBHOOK_SECRET!)) {
+      return res.status(401).send("Invalid signature");
+    }
+    const event = JSON.parse(req.body.toString());
+    processGitHubEvent(event);
+    res.status(200).send("OK");
+  }
+);
+```
+
+### Idempotent Processing
+
+Webhooks may be delivered more than once. Make handlers safe to re-run:
+
+```typescript
+async function processWebhookIdempotent(
+  eventId: string,
+  handler: () => Promise<void>
+): Promise<void> {
+  // Atomic check-and-set in Redis
+  const acquired = await redis.set(
+    `webhook:processed:${eventId}`, "1", "NX", "EX", 86400
+  );
+  if (!acquired) {
+    logger.info({ eventId }, "Duplicate webhook, skipping");
+    return;
+  }
+
+  try {
+    await handler();
+  } catch (err) {
+    // Remove the key so the webhook can be retried
+    await redis.del(`webhook:processed:${eventId}`);
+    throw err;
+  }
+}
+
+// Or use database constraints
+await db.query(
+  `INSERT INTO webhook_events (event_id, type, processed_at)
+   VALUES ($1, $2, NOW())
+   ON CONFLICT (event_id) DO NOTHING`,
+  [event.id, event.type]
+);
+```
+
+### Sending Webhooks -- Producer Side
+
+```typescript
+interface WebhookDelivery {
+  id: string;
+  endpoint: string;
+  event: string;
+  payload: object;
+  attempt: number;
+  nextRetryAt: Date | null;
+  deliveredAt: Date | null;
+  statusCode: number | null;
+}
+
+async function sendWebhook(
+  endpoint: string,
+  secret: string,
+  event: string,
+  payload: object
+): Promise<void> {
+  const body = JSON.stringify(payload);
+  const timestamp = Math.floor(Date.now() / 1000);
+  const signature = crypto
+    .createHmac("sha256", secret)
+    .update(`${timestamp}.${body}`)
+    .digest("hex");
+
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Webhook-Signature": `t=${timestamp},v1=${signature}`,
+      "X-Webhook-Event": event,
+      "X-Webhook-ID": crypto.randomUUID(),
+    },
+    body,
+    signal: AbortSignal.timeout(10000), // 10s timeout
+  });
+
+  if (!response.ok) {
+    throw new Error(`Webhook delivery failed: ${response.status}`);
+  }
+}
+```
+
+### Retry Logic with Exponential Backoff
+
+```typescript
+const RETRY_SCHEDULE = [
+  60,        // 1 minute
+  300,       // 5 minutes
+  1800,      // 30 minutes
+  7200,      // 2 hours
+  28800,     // 8 hours
+  86400,     // 24 hours
+];
+
+async function deliverWithRetry(delivery: WebhookDelivery): Promise<void> {
+  try {
+    await sendWebhook(
+      delivery.endpoint,
+      delivery.secret,
+      delivery.event,
+      delivery.payload
+    );
+    await db.webhookDeliveries.update(delivery.id, {
+      deliveredAt: new Date(),
+      statusCode: 200,
+    });
+  } catch (err) {
+    const nextAttempt = delivery.attempt + 1;
+    if (nextAttempt >= RETRY_SCHEDULE.length) {
+      await db.webhookDeliveries.update(delivery.id, {
+        statusCode: 0,
+        failedPermanently: true,
+      });
+      logger.error({ deliveryId: delivery.id }, "Webhook permanently failed");
+      return;
+    }
+
+    const delaySeconds = RETRY_SCHEDULE[nextAttempt];
+    await db.webhookDeliveries.update(delivery.id, {
+      attempt: nextAttempt,
+      nextRetryAt: new Date(Date.now() + delaySeconds * 1000),
+      lastError: (err as Error).message,
+    });
+  }
+}
+```
+
+### Event Ordering
+
+Webhooks may arrive out of order. Handle this gracefully:
+
+```typescript
+// Include a timestamp or sequence number in the event
+interface WebhookEvent {
+  id: string;
+  type: string;
+  createdAt: string; // ISO timestamp
+  data: Record<string, unknown>;
+}
+
+// For order-sensitive events, check the timestamp
+async function handleOrderStatusChange(event: WebhookEvent): Promise<void> {
+  const order = await db.orders.findById(event.data.orderId as string);
+
+  // Ignore events older than the last processed event
+  if (order.lastWebhookAt && new Date(event.createdAt) < order.lastWebhookAt) {
+    logger.warn({ eventId: event.id }, "Out-of-order webhook, skipping");
+    return;
+  }
+
+  await db.orders.update(order.id, {
+    status: event.data.status as string,
+    lastWebhookAt: new Date(event.createdAt),
+  });
+}
+```
+
+### Testing Webhooks Locally
+
+```bash
+# Stripe CLI -- forward webhooks to localhost
+stripe listen --forward-to localhost:3000/webhooks/stripe
+
+# ngrok -- expose local server to the internet
+ngrok http 3000
+
+# Use the ngrok URL as your webhook endpoint in development
+```
+
+```typescript
+// Integration test for webhook handler
+describe("POST /webhooks/stripe", () => {
+  it("processes checkout.session.completed", async () => {
+    const payload = { id: "evt_123", type: "checkout.session.completed", data: { /* ... */ } };
+    const body = JSON.stringify(payload);
+    const sig = stripe.webhooks.generateTestHeaderString({
+      payload: body,
+      secret: process.env.STRIPE_WEBHOOK_SECRET!,
+    });
+
+    const res = await request(app)
+      .post("/webhooks/stripe")
+      .set("Content-Type", "application/json")
+      .set("stripe-signature", sig)
+      .send(body);
+
+    expect(res.status).toBe(200);
+    const order = await db.orders.findById(payload.data.object.metadata.orderId);
+    expect(order.status).toBe("fulfilled");
+  });
+});
+```
+
+## Examples
+
+| Pattern | When | Result |
+|---------|------|--------|
+| HMAC signature | Every webhook | Prevents spoofed payloads |
+| Idempotency key | Duplicate deliveries | Process each event exactly once |
+| Retry with backoff | Network failures | Reliable delivery over 24 hours |
+| Timestamp ordering | Status updates | Ignore stale events |
+| Local forwarding | Development | Test webhooks without deploying |
+
+## Checklist
+- [ ] Webhook signatures verified on every incoming request
+- [ ] Raw request body used for signature verification (not parsed JSON)
+- [ ] Handlers are idempotent -- safe to process duplicate events
+- [ ] Respond 200 quickly, process asynchronously if slow
+- [ ] Retry schedule uses exponential backoff (1min to 24hrs)
+- [ ] Failed deliveries logged with attempt count and error
+- [ ] Out-of-order events handled via timestamp comparison
+- [ ] Webhook endpoint tested with local forwarding (Stripe CLI, ngrok)