@garethdaine/agentops 0.9.0

package/templates/architecture/caching-strategy.md

@@ -0,0 +1,359 @@
+# Architecture Pattern: Caching Strategy
+
+## When to Use
+
+- Read-heavy workloads where the same data is requested repeatedly
+- Expensive computations or queries that can tolerate slightly stale results
+- Reducing latency for frequently accessed resources
+- Protecting backend services from traffic spikes
+
+## Pattern Description
+
+Caching stores computed results closer to the consumer to avoid redundant work. Effective caching requires deliberate decisions about what to cache, where to cache it, how long entries remain valid, and how to invalidate them when the source data changes. The hardest part of caching is not adding it — it is invalidating it correctly.
+
+## Cache Layers
+
+```typescript
+/**
+ * Layer 1: Application memory (fastest, per-process, lost on restart)
+ * Layer 2: Redis / Memcached (shared across processes, survives restarts)
+ * Layer 3: CDN (edge cache for static and semi-static content)
+ *
+ * Check layers in order: memory -> Redis -> origin
+ */
+
+export interface CacheLayer {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, ttlSeconds: number): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+export class TieredCache implements CacheLayer {
+  constructor(
+    private memory: CacheLayer,
+    private redis: CacheLayer,
+  ) {}
+
+  async get<T>(key: string): Promise<T | null> {
+    // Check local memory first (sub-millisecond)
+    const memResult = await this.memory.get<T>(key);
+    if (memResult !== null) return memResult;
+
+    // Fall back to Redis (1-2ms network hop)
+    const redisResult = await this.redis.get<T>(key);
+    if (redisResult !== null) {
+      // Promote to memory cache with a shorter TTL
+      await this.memory.set(key, redisResult, 30);
+      return redisResult;
+    }
+
+    return null;
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {
+    await Promise.all([
+      this.memory.set(key, value, Math.min(ttlSeconds, 60)),
+      this.redis.set(key, value, ttlSeconds),
+    ]);
+  }
+
+  async delete(key: string): Promise<void> {
+    await Promise.all([
+      this.memory.delete(key),
+      this.redis.delete(key),
+    ]);
+  }
+}
+```
+
+### In-Memory Cache Implementation
+
+```typescript
+export class MemoryCache implements CacheLayer {
+  private store = new Map<string, { value: unknown; expiresAt: number }>();
+
+  async get<T>(key: string): Promise<T | null> {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry.value as T;
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {
+    this.store.set(key, {
+      value,
+      expiresAt: Date.now() + ttlSeconds * 1000,
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+}
+```
+
+## Cache Key Design
+
+```typescript
+/**
+ * Cache key rules:
+ * 1. Include all parameters that affect the result
+ * 2. Prefix with entity type for easy bulk invalidation
+ * 3. Include tenant ID to prevent cross-tenant data leaks
+ * 4. Keep keys human-readable for debugging
+ * 5. Use a consistent separator (colon is conventional for Redis)
+ */
+
+export function buildCacheKey(parts: {
+  entity: string;
+  tenantId: string;
+  id?: string;
+  params?: Record<string, string | number | boolean>;
+}): string {
+  const base = `${parts.entity}:${parts.tenantId}`;
+  if (parts.id) {
+    return `${base}:${parts.id}`;
+  }
+  if (parts.params) {
+    // Deterministic stringification — sort keys
+    const sorted = Object.keys(parts.params)
+      .sort()
+      .map((k) => `${k}=${parts.params![k]}`)
+      .join('&');
+    return `${base}:list:${sorted}`;
+  }
+  return base;
+}
+
+// Examples:
+// "project:tenant-abc:proj-123"
+// "project:tenant-abc:list:page=1&status=active"
+```
+
+## Invalidation Strategies
+
+### TTL-Based (Simplest)
+
+```typescript
+/**
+ * Set a time-to-live and accept that data may be stale
+ * for up to that duration. Appropriate when eventual
+ * consistency is acceptable.
+ */
+await cache.set('project:tenant-1:proj-123', project, 300); // 5 minutes
+```
+
+### Event-Based Invalidation (Strongest Consistency)
+
+```typescript
+/**
+ * Invalidate cache entries when the underlying data changes.
+ * Requires an event bus or change data capture pipeline.
+ */
+eventBus.subscribe('project.updated', async (event) => {
+  const key = buildCacheKey({
+    entity: 'project',
+    tenantId: event.data.tenantId,
+    id: event.data.projectId,
+  });
+  await cache.delete(key);
+
+  // Also invalidate list caches for this tenant
+  await redis.deletePattern(`project:${event.data.tenantId}:list:*`);
+});
+```
+
+### Write-Through
+
+```typescript
+/**
+ * Update the cache synchronously on every write.
+ * The cache is always consistent but writes are slower.
+ */
+export class WriteThroughRepository {
+  constructor(
+    private db: DatabaseClient,
+    private cache: CacheLayer,
+  ) {}
+
+  async update(tenantId: string, id: string, data: UpdateInput): Promise<Project> {
+    const updated = await this.db.update('projects', id, data);
+    const key = buildCacheKey({ entity: 'project', tenantId, id });
+    await this.cache.set(key, updated, 600);
+    return updated;
+  }
+}
+```
+
+### Write-Behind (Write-Back)
+
+```typescript
+/**
+ * Write to the cache immediately, persist to the database asynchronously.
+ * Higher write throughput but risk of data loss if the cache fails
+ * before the database write completes.
+ */
+export class WriteBehindRepository {
+  constructor(
+    private db: DatabaseClient,
+    private cache: CacheLayer,
+    private writeQueue: Queue,
+  ) {}
+
+  async update(tenantId: string, id: string, data: UpdateInput): Promise<void> {
+    const key = buildCacheKey({ entity: 'project', tenantId, id });
+
+    // Update cache immediately (fast path)
+    const updated = { ...data, id, updatedAt: new Date().toISOString() };
+    await this.cache.set(key, updated, 600);
+
+    // Queue database write for async processing
+    await this.writeQueue.add('db-write', {
+      table: 'projects',
+      id,
+      data,
+    });
+  }
+}
+```
+
+## Stampede Prevention
+
+When a popular cache entry expires, many concurrent requests can hit the database simultaneously.
+
+### Mutex Lock
+
+```typescript
+/**
+ * Only one request computes the value while others wait.
+ */
+export async function getWithMutex<T>(
+  cache: CacheLayer,
+  redis: RedisClient,
+  key: string,
+  computeFn: () => Promise<T>,
+  ttlSeconds: number,
+): Promise<T> {
+  const cached = await cache.get<T>(key);
+  if (cached !== null) return cached;
+
+  const lockKey = `lock:${key}`;
+  const acquired = await redis.set(lockKey, '1', { NX: true, EX: 10 });
+
+  if (acquired) {
+    try {
+      const value = await computeFn();
+      await cache.set(key, value, ttlSeconds);
+      return value;
+    } finally {
+      await redis.del(lockKey);
+    }
+  }
+
+  // Another process is computing — wait and retry
+  await sleep(50);
+  return getWithMutex(cache, redis, key, computeFn, ttlSeconds);
+}
+```
+
+### Probabilistic Early Expiration
+
+```typescript
+/**
+ * Each request has a small probability of recomputing the value
+ * before it actually expires, spreading the refresh load over time.
+ *
+ * XFetch algorithm: recompute with probability that increases
+ * as the entry approaches its expiry time.
+ */
+export async function getWithEarlyExpiry<T>(
+  cache: CacheLayer,
+  key: string,
+  computeFn: () => Promise<T>,
+  ttlSeconds: number,
+): Promise<T> {
+  const entry = await cache.getWithMetadata<T>(key);
+
+  if (entry !== null) {
+    const timeRemaining = entry.expiresAt - Date.now();
+    const totalTtl = ttlSeconds * 1000;
+    const beta = 1; // Tuning parameter
+
+    // Probability of early recompute increases as expiry approaches
+    const shouldRecompute =
+      timeRemaining > 0 &&
+      Math.random() < Math.exp((-timeRemaining / totalTtl) * beta);
+
+    if (!shouldRecompute) {
+      return entry.value;
+    }
+  }
+
+  const value = await computeFn();
+  await cache.set(key, value, ttlSeconds);
+  return value;
+}
+```
+
+## Cache Warming
+
+```typescript
+/**
+ * Pre-populate the cache on application startup or deployment
+ * to avoid cold-start latency for critical paths.
+ */
+export async function warmCache(
+  db: DatabaseClient,
+  cache: CacheLayer,
+): Promise<void> {
+  logger.info('Warming cache...');
+
+  // Warm the most frequently accessed entities
+  const activeTenants = await db.query<{ id: string }>(
+    'SELECT id FROM tenants WHERE status = $1 ORDER BY last_active_at DESC LIMIT 100',
+    ['active'],
+  );
+
+  for (const tenant of activeTenants) {
+    const projects = await db.query(
+      'SELECT * FROM projects WHERE tenant_id = $1 AND status = $2',
+      [tenant.id, 'active'],
+    );
+
+    for (const project of projects) {
+      const key = buildCacheKey({
+        entity: 'project',
+        tenantId: tenant.id,
+        id: project.id,
+      });
+      await cache.set(key, project, 600);
+    }
+  }
+
+  logger.info('Cache warming complete', {
+    tenants: activeTenants.length,
+  });
+}
+
+// Call on startup, after migrations
+await warmCache(db, cache);
+```
+
+## Trade-offs
+
+- **Consistency vs latency:** Longer TTLs mean faster reads but staler data. Event-based invalidation is more consistent but adds infrastructure complexity.
+- **Memory cost:** Caching everything is wasteful. Cache hot data and let cold data go to origin.
+- **Write-through vs write-behind:** Write-through is consistent but adds write latency. Write-behind is fast but risks data loss.
+- **Tiered caching complexity:** Each layer adds operational surface area. Start with one layer and add more only when measurements justify it.
+
+## Common Pitfalls
+
+1. **No invalidation strategy** — Setting a TTL and hoping for the best leads to stale data bugs that are hard to reproduce.
+2. **Cache keys missing a parameter** — If two different queries produce the same cache key, one overwrites the other with wrong data.
+3. **Caching errors** — A failed database query cached for 5 minutes means 5 minutes of errors. Never cache error responses.
+4. **Unbounded memory cache** — Without a max size and eviction policy (LRU), the process leaks memory. Set limits.
+5. **Cross-tenant cache pollution** — Always include tenant ID in the cache key. A missing tenant prefix leaks data across tenants.
+6. **Ignoring serialisation cost** — Serialising and deserialising large objects can negate the performance benefit of caching. Measure end-to-end latency.

package/templates/architecture/database-patterns.md

@@ -0,0 +1,347 @@
+# Architecture Pattern: Database Patterns
+
+## When to Use
+
+- Any application with persistent state beyond trivial key-value storage
+- Systems that require schema evolution over time without downtime
+- Read-heavy workloads that need query optimisation and replica routing
+- Multi-service architectures where connection management becomes critical
+
+## Pattern Description
+
+Database patterns cover the full lifecycle of data management: how schemas evolve through migrations, how connections are pooled and managed, how queries are optimised, and how read/write workloads are distributed. Getting these fundamentals right prevents the most common class of production incidents.
+
+## Migration Management
+
+Migrations must be versioned, reversible, and safe to run against a live database.
+
+```typescript
+/**
+ * Migration file naming convention:
+ *   YYYYMMDDHHMMSS_descriptive_name.ts
+ *   20250315120000_add_projects_table.ts
+ *
+ * Each migration has an up() and down() function.
+ * down() must perfectly reverse up().
+ */
+
+// 20250315120000_add_projects_table.ts
+export async function up(db: DatabaseClient): Promise<void> {
+  await db.schema.createTable('projects', (table) => {
+    table.uuid('id').primary().defaultTo(db.fn.uuid());
+    table.text('tenant_id').notNullable().index();
+    table.text('name').notNullable();
+    table.text('status').notNullable().defaultTo('active');
+    table.timestamp('created_at').notNullable().defaultTo(db.fn.now());
+    table.timestamp('updated_at').notNullable().defaultTo(db.fn.now());
+  });
+
+  // Composite index for the most common query pattern
+  await db.schema.raw(
+    'CREATE INDEX idx_projects_tenant_status ON projects(tenant_id, status)',
+  );
+}
+
+export async function down(db: DatabaseClient): Promise<void> {
+  await db.schema.dropTableIfExists('projects');
+}
+```
+
+### Safe Migration Practices
+
+```typescript
+/**
+ * Rules for zero-downtime migrations:
+ *
+ * 1. NEVER rename a column in one step. Instead:
+ *    Step 1: Add new column, backfill data
+ *    Step 2: Deploy code that writes to both columns
+ *    Step 3: Deploy code that reads from new column only
+ *    Step 4: Drop old column
+ *
+ * 2. NEVER add a NOT NULL column without a default value
+ *    to an existing table with data.
+ *
+ * 3. Adding an index on a large table — use CONCURRENTLY:
+ */
+export async function up(db: DatabaseClient): Promise<void> {
+  // CREATE INDEX CONCURRENTLY does not lock the table for writes
+  await db.schema.raw(
+    'CREATE INDEX CONCURRENTLY idx_orders_created ON orders(created_at)',
+  );
+}
+
+// CONCURRENTLY indexes cannot run inside a transaction,
+// so mark this migration as non-transactional if your tool supports it.
+export const config = { transaction: false };
+```
+
+## Connection Pooling
+
+```typescript
+/**
+ * Connection pool sizing formula (PostgreSQL):
+ *   pool_size = (core_count * 2) + effective_spindle_count
+ *
+ * For a typical 4-core cloud instance with SSDs: pool_size ~= 10
+ * Each Node.js process gets its own pool. With 4 processes: 10 / 4 = 2-3 per process.
+ */
+export function createPool(config: DatabaseConfig): Pool {
+  return new Pool({
+    host: config.host,
+    port: config.port,
+    database: config.database,
+    user: config.user,
+    password: config.password,
+
+    // Pool sizing
+    min: 2,                    // Minimum idle connections
+    max: 10,                   // Maximum connections per process
+    idleTimeoutMillis: 30_000, // Close idle connections after 30s
+    connectionTimeoutMillis: 5_000, // Fail fast if no connection available
+
+    // Statement timeout to prevent runaway queries
+    statement_timeout: 30_000,
+  });
+}
+
+// Health check: verify pool is functional
+export async function checkDatabaseHealth(pool: Pool): Promise<boolean> {
+  try {
+    const result = await pool.query('SELECT 1 AS ok');
+    return result.rows[0]?.ok === 1;
+  } catch {
+    return false;
+  }
+}
+```
+
+## Query Optimisation Checklist
+
+```typescript
+/**
+ * Before deploying a new query to production:
+ *
+ * 1. Run EXPLAIN ANALYZE on a representative dataset
+ * 2. Check for sequential scans on large tables (Seq Scan)
+ * 3. Verify index usage (Index Scan or Index Only Scan)
+ * 4. Check estimated vs actual row counts — large discrepancies
+ *    mean stale statistics (run ANALYZE)
+ * 5. Look for nested loops with high row counts
+ * 6. Check for implicit type casts that prevent index usage
+ */
+
+// Example: detecting slow queries at runtime
+export function queryWithTiming<T>(
+  pool: Pool,
+  sql: string,
+  params: unknown[],
+  label: string,
+): Promise<T[]> {
+  const start = performance.now();
+  return pool.query(sql, params).then((result) => {
+    const duration = performance.now() - start;
+    if (duration > 100) {
+      logger.warn('Slow query detected', { label, duration, sql });
+    }
+    return result.rows as T[];
+  });
+}
+```
+
+## Indexing Strategy
+
+```typescript
+/**
+ * Index type selection guide (PostgreSQL):
+ *
+ * B-tree (default):
+ *   - Equality and range queries (=, <, >, BETWEEN)
+ *   - ORDER BY, GROUP BY
+ *   - Most common choice
+ *
+ * GIN (Generalized Inverted Index):
+ *   - JSONB containment (@>, ?)
+ *   - Full-text search (tsvector)
+ *   - Array containment (@>, &&)
+ *
+ * GiST (Generalized Search Tree):
+ *   - Geometric/spatial data
+ *   - Range types (overlaps, contains)
+ *   - Nearest-neighbour searches
+ *
+ * BRIN (Block Range Index):
+ *   - Very large tables where values correlate with physical order
+ *   - Time-series data (created_at on append-only tables)
+ *   - Tiny index size compared to B-tree
+ */
+
+// Practical index examples
+export async function up(db: DatabaseClient): Promise<void> {
+  // B-tree: exact lookups and range scans
+  await db.schema.raw(
+    'CREATE INDEX idx_orders_status ON orders(status) WHERE status != \'completed\'',
+  );
+
+  // GIN: querying JSONB metadata
+  await db.schema.raw(
+    'CREATE INDEX idx_projects_metadata ON projects USING gin(metadata jsonb_path_ops)',
+  );
+
+  // Composite index: column order matters — put equality columns first
+  await db.schema.raw(
+    'CREATE INDEX idx_events_tenant_time ON events(tenant_id, created_at DESC)',
+  );
+}
+```
+
+## Read Replica Routing
+
+```typescript
+/**
+ * Route read-only queries to replicas, writes to the primary.
+ * Beware of replication lag — recently written data may not be
+ * available on replicas immediately.
+ */
+export class RoutingDatabase {
+  constructor(
+    private primary: Pool,
+    private replicas: Pool[],
+  ) {}
+
+  private nextReplicaIndex = 0;
+
+  /** Route to primary for writes */
+  async write<T>(sql: string, params: unknown[]): Promise<T[]> {
+    const result = await this.primary.query(sql, params);
+    return result.rows as T[];
+  }
+
+  /** Round-robin across read replicas */
+  async read<T>(sql: string, params: unknown[]): Promise<T[]> {
+    const replica = this.replicas[this.nextReplicaIndex % this.replicas.length];
+    this.nextReplicaIndex++;
+    const result = await replica.query(sql, params);
+    return result.rows as T[];
+  }
+
+  /**
+   * Read from primary when you need to read-your-own-writes.
+   * Use sparingly — this adds load to the primary.
+   */
+  async readFromPrimary<T>(sql: string, params: unknown[]): Promise<T[]> {
+    const result = await this.primary.query(sql, params);
+    return result.rows as T[];
+  }
+}
+```
+
+## Advisory Locks
+
+```typescript
+/**
+ * Advisory locks for application-level mutual exclusion.
+ * Use when you need to prevent concurrent execution of a
+ * critical section across multiple processes.
+ */
+export async function withAdvisoryLock<T>(
+  pool: Pool,
+  lockId: number,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const client = await pool.connect();
+  try {
+    // pg_try_advisory_lock returns immediately (non-blocking)
+    const lockResult = await client.query(
+      'SELECT pg_try_advisory_lock($1) AS acquired',
+      [lockId],
+    );
+
+    if (!lockResult.rows[0].acquired) {
+      throw new ConflictError('Could not acquire lock — another process holds it');
+    }
+
+    const result = await fn();
+    return result;
+  } finally {
+    await client.query('SELECT pg_advisory_unlock($1)', [lockId]);
+    client.release();
+  }
+}
+
+// Usage: prevent concurrent migration runs
+await withAdvisoryLock(pool, 1001, async () => {
+  await runPendingMigrations();
+});
+```
+
+## Transaction Isolation Levels
+
+```typescript
+/**
+ * Isolation levels (from least to most strict):
+ *
+ * READ COMMITTED (PostgreSQL default):
+ *   Each statement sees only committed data. Good for most workloads.
+ *
+ * REPEATABLE READ:
+ *   The transaction sees a snapshot from its start. Use for reports
+ *   or calculations that read the same data multiple times.
+ *
+ * SERIALIZABLE:
+ *   Full isolation — transactions behave as if run sequentially.
+ *   Highest safety, highest contention. Use for financial operations.
+ */
+export async function transferFunds(
+  pool: Pool,
+  fromAccountId: string,
+  toAccountId: string,
+  amount: number,
+): Promise<void> {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN ISOLATION LEVEL SERIALIZABLE');
+
+    const from = await client.query(
+      'SELECT balance FROM accounts WHERE id = $1 FOR UPDATE',
+      [fromAccountId],
+    );
+    if (from.rows[0].balance < amount) {
+      throw new ValidationError('Insufficient funds');
+    }
+
+    await client.query(
+      'UPDATE accounts SET balance = balance - $1 WHERE id = $2',
+      [amount, fromAccountId],
+    );
+    await client.query(
+      'UPDATE accounts SET balance = balance + $1 WHERE id = $2',
+      [amount, toAccountId],
+    );
+
+    await client.query('COMMIT');
+  } catch (error) {
+    await client.query('ROLLBACK');
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+```
+
+## Trade-offs
+
+- **Migration safety vs speed:** Zero-downtime migrations require more steps but avoid service interruption.
+- **Pool size:** Too small causes connection starvation under load. Too large wastes database memory and can degrade performance.
+- **Read replicas:** Reduce primary load but introduce replication lag. Not every read can tolerate stale data.
+- **Stronger isolation:** Prevents anomalies but increases transaction conflicts and retries.
+- **Index count:** More indexes speed reads but slow writes and consume storage.
+
+## Common Pitfalls
+
+1. **Irreversible migrations** — Every migration must have a working `down()`. Test it before deploying.
+2. **Missing indexes on foreign keys** — Unindexed foreign keys cause sequential scans on JOIN and DELETE operations.
+3. **N+1 queries** — Loading a list and then querying each item individually. Use JOINs or batch queries.
+4. **Long-running transactions** — Hold locks as briefly as possible. Move non-database work outside the transaction.
+5. **No connection timeout** — Without statement and connection timeouts, a single slow query can exhaust the pool.
+6. **Ignoring EXPLAIN output** — Query plans change as data grows. Review plans periodically, not just at development time.