@venizia/ignis-docs 0.0.4-1 → 0.0.4-2

package/wiki/best-practices/performance-optimization.md

@@ -194,3 +194,183 @@ try {
 
 > [!WARNING]
 > Higher isolation levels reduce concurrency. Use `READ COMMITTED` unless you have specific consistency requirements.
+
+## 7. Database Connection Pooling
+
+Connection pooling significantly improves performance by reusing database connections instead of creating new ones for each request.
+
+**Configure in DataSource:**
+
+```typescript
+import { Pool } from 'pg';
+import { drizzle } from 'drizzle-orm/node-postgres';
+
+export class PostgresDataSource extends AbstractDataSource {
+  override connect(): void {
+    const pool = new Pool({
+      host: this.settings.host,
+      port: this.settings.port,
+      user: this.settings.username,
+      password: this.settings.password,
+      database: this.settings.database,
+
+      // Connection pool settings
+      max: 20,                      // Maximum connections in pool
+      min: 5,                       // Minimum connections to maintain
+      idleTimeoutMillis: 30000,     // Close idle connections after 30s
+      connectionTimeoutMillis: 5000, // Fail if can't connect in 5s
+      maxUses: 7500,                // Close connection after 7500 queries
+    });
+
+    this.connector = drizzle({ client: pool, schema: this.schema });
+  }
+}
+```
+
+**Recommended Pool Sizes:**
+
+| Server RAM | Concurrent Users | Max Pool Size | Min Pool Size |
+|------------|------------------|---------------|---------------|
+| < 2GB | < 100 | 10 | 2 |
+| 2-4GB | 100-500 | 20 | 5 |
+| 4-8GB | 500-1000 | 30 | 10 |
+| > 8GB | > 1000 | 50+ | 15 |
+
+**Formula:** `max_connections = (number_of_cores * 2) + effective_spindle_count`
+
+For most applications: `max_connections = CPU_cores * 2 + 1`
+
+**Monitoring Pool Health:**
+
+```typescript
+// Log pool statistics periodically
+const pool = new Pool({ /* ... */ });
+
+setInterval(() => {
+  this.logger.info('[pool] Stats | total: %d | idle: %d | waiting: %d',
+    pool.totalCount,
+    pool.idleCount,
+    pool.waitingCount
+  );
+}, 60000); // Every minute
+```
+
+**Warning Signs:**
+- `waitingCount > 0` consistently → Increase `max`
+- `idleCount === totalCount` always → Decrease `max`
+- Connection timeouts → Check network, increase `connectionTimeoutMillis`
+
+## 8. Query Optimization Tips
+
+### Use Indexes Strategically
+
+```typescript
+// Create indexes on frequently queried columns
+export const User = pgTable('User', {
+  id: text('id').primaryKey(),
+  email: text('email').notNull().unique(),  // Implicit unique index
+  status: text('status').notNull(),
+  createdAt: timestamp('created_at').notNull(),
+}, (table) => ({
+  // Composite index for common query patterns
+  statusCreatedIdx: index('idx_user_status_created').on(table.status, table.createdAt),
+  // Partial index for active users only
+  activeEmailIdx: index('idx_active_email').on(table.email).where(eq(table.status, 'ACTIVE')),
+}));
+```
+
+### Avoid N+1 Queries
+
+```typescript
+// ❌ BAD - N+1 queries
+const users = await userRepo.find({ filter: { limit: 100 } });
+for (const user of users.data) {
+  user.posts = await postRepo.find({ filter: { where: { authorId: user.id } } });
+}
+
+// ✅ GOOD - Single query with relations
+const users = await userRepo.find({
+  filter: {
+    limit: 100,
+    include: [{ relation: 'posts' }],
+  },
+});
+```
+
+### Batch Operations
+
+```typescript
+// ❌ BAD - Many individual inserts
+for (const item of items) {
+  await repo.create({ data: item });
+}
+
+// ✅ GOOD - Batch insert
+await repo.createMany({ data: items });
+```
+
+## 9. Memory Management
+
+### Stream Large Datasets
+
+```typescript
+// ❌ BAD - Load all records into memory
+const allUsers = await userRepo.find({ filter: { limit: 100000 } });
+
+// ✅ GOOD - Process in batches
+const batchSize = 1000;
+let offset = 0;
+let hasMore = true;
+
+while (hasMore) {
+  const batch = await userRepo.find({
+    filter: { limit: batchSize, offset },
+  });
+
+  for (const user of batch.data) {
+    await processUser(user);
+  }
+
+  hasMore = batch.data.length === batchSize;
+  offset += batchSize;
+}
+```
+
+### Avoid Memory Leaks in Long-Running Processes
+
+```typescript
+// ❌ BAD - Growing array in long-running process
+const processedIds: string[] = [];
+// This array grows forever!
+
+// ✅ GOOD - Use Set with cleanup or external storage
+const processedIds = new Set<string>();
+
+// Periodically clear or use Redis
+setInterval(() => {
+  if (processedIds.size > 10000) {
+    processedIds.clear();
+  }
+}, 3600000); // Every hour
+```
+
+## Performance Checklist
+
+| Category | Check | Impact |
+|----------|-------|--------|
+| **Database** | Connection pooling configured | High |
+| **Database** | Indexes on WHERE/JOIN columns | High |
+| **Database** | Limit on all queries | High |
+| **Queries** | Using `fields` to select specific columns | Medium |
+| **Queries** | Relations limited to 2 levels | Medium |
+| **Queries** | Batch operations for bulk data | High |
+| **Memory** | Large datasets processed in batches | High |
+| **Caching** | Expensive queries cached | High |
+| **Workers** | CPU-intensive tasks offloaded | High |
+| **Monitoring** | Performance logging enabled | Low |
+
+## See Also
+
+- [Data Modeling](./data-modeling) - Schema design for performance
+- [Deployment Strategies](./deployment-strategies) - Production scaling
+- [Common Pitfalls](./common-pitfalls) - Performance mistakes to avoid

package/wiki/best-practices/security-guidelines.md

@@ -216,3 +216,252 @@ bun update
 - `jose` - JWT handling
 - `drizzle-orm` - Database ORM
 - `@venizia/ignis` - Framework core
+
+## 7. CORS Configuration
+
+Configure Cross-Origin Resource Sharing to control which domains can access your API.
+
+**Default (Development):**
+```typescript
+import { cors } from 'hono/cors';
+
+// Allow all origins (ONLY for development)
+this.server.use('*', cors());
+```
+
+**Production (Restrictive):**
+```typescript
+import { cors } from 'hono/cors';
+
+this.server.use('/api/*', cors({
+  origin: ['https://yourdomain.com', 'https://app.yourdomain.com'],
+  allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+  allowHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
+  exposeHeaders: ['X-Request-ID'],
+  credentials: true,
+  maxAge: 86400, // Cache preflight for 24 hours
+}));
+```
+
+**Dynamic Origin Validation:**
+```typescript
+this.server.use('/api/*', cors({
+  origin: (origin) => {
+    const allowedDomains = ['yourdomain.com', 'yourdomain.io'];
+    try {
+      const url = new URL(origin);
+      return allowedDomains.some(domain => url.hostname.endsWith(domain))
+        ? origin
+        : null;
+    } catch {
+      return null;
+    }
+  },
+}));
+```
+
+> [!WARNING]
+> Never use `origin: '*'` with `credentials: true` in production. This is a security vulnerability.
+
+## 8. Rate Limiting
+
+Protect against brute force attacks and denial of service.
+
+**Basic Rate Limiter:**
+```typescript
+import { createMiddleware } from 'hono/factory';
+
+const rateLimiter = (opts: { windowMs: number; max: number }) => {
+  const requests = new Map<string, { count: number; resetAt: number }>();
+
+  return createMiddleware(async (c, next) => {
+    const ip = c.req.header('x-forwarded-for') ?? c.req.header('x-real-ip') ?? 'unknown';
+    const now = Date.now();
+    const record = requests.get(ip);
+
+    if (!record || now > record.resetAt) {
+      requests.set(ip, { count: 1, resetAt: now + opts.windowMs });
+    } else if (record.count >= opts.max) {
+      return c.json({
+        statusCode: 429,
+        message: 'Too many requests. Please try again later.',
+      }, 429);
+    } else {
+      record.count++;
+    }
+
+    await next();
+  });
+};
+
+// Apply to sensitive endpoints
+this.server.use('/api/auth/login', rateLimiter({ windowMs: 15 * 60 * 1000, max: 5 }));
+this.server.use('/api/auth/register', rateLimiter({ windowMs: 60 * 60 * 1000, max: 10 }));
+this.server.use('/api/*', rateLimiter({ windowMs: 60 * 1000, max: 100 }));
+```
+
+**Recommended Limits:**
+
+| Endpoint | Window | Max Requests | Reason |
+|----------|--------|--------------|--------|
+| `/auth/login` | 15 min | 5 | Prevent brute force |
+| `/auth/register` | 1 hour | 10 | Prevent spam accounts |
+| `/auth/forgot-password` | 1 hour | 3 | Prevent email flooding |
+| `/api/*` (general) | 1 min | 100 | General protection |
+
+**Production Recommendation:** Use Redis-backed rate limiting for distributed deployments:
+
+```typescript
+import { RedisHelper } from '@venizia/ignis-helpers';
+
+// Rate limiter with Redis for multi-instance deployments
+const distributedRateLimiter = async (key: string, max: number, windowSec: number) => {
+  const redis = RedisHelper.getClient();
+  const current = await redis.incr(key);
+  if (current === 1) {
+    await redis.expire(key, windowSec);
+  }
+  return current <= max;
+};
+```
+
+## 9. SQL Injection Prevention
+
+Drizzle ORM automatically parameterizes queries, protecting against SQL injection. However, **raw queries require care**.
+
+**Safe (Parameterized):**
+```typescript
+// ✅ Repository methods are safe - queries are parameterized
+await userRepository.find({
+  filter: { where: { email: userInput } },
+});
+
+// ✅ Drizzle query builder is safe
+await db.select().from(users).where(eq(users.email, userInput));
+
+// ✅ sql`` template with placeholders is safe
+await db.execute(sql`SELECT * FROM users WHERE email = ${userInput}`);
+```
+
+**Dangerous (String Interpolation):**
+```typescript
+// ❌ NEVER use string interpolation in raw SQL
+const query = `SELECT * FROM users WHERE email = '${userInput}'`;
+await db.execute(sql.raw(query)); // Vulnerable to SQL injection!
+
+// ❌ NEVER build WHERE clauses with string concatenation
+const condition = `status = '${status}' AND role = '${role}'`;
+```
+
+**If You Must Use Dynamic SQL:**
+```typescript
+// Use parameterized queries with sql.raw only for table/column names
+const tableName = allowedTables.includes(input) ? input : 'default_table';
+await db.execute(sql`SELECT * FROM ${sql.identifier(tableName)} WHERE id = ${id}`);
+```
+
+## 10. Security Headers
+
+Add security headers to protect against common attacks:
+
+```typescript
+import { secureHeaders } from 'hono/secure-headers';
+
+// Add security headers to all responses
+this.server.use('*', secureHeaders({
+  // Prevent clickjacking
+  xFrameOptions: 'DENY',
+  // Prevent MIME type sniffing
+  xContentTypeOptions: 'nosniff',
+  // Enable XSS filter
+  xXssProtection: '1; mode=block',
+  // Control referrer information
+  referrerPolicy: 'strict-origin-when-cross-origin',
+  // Content Security Policy
+  contentSecurityPolicy: {
+    defaultSrc: ["'self'"],
+    scriptSrc: ["'self'"],
+    styleSrc: ["'self'", "'unsafe-inline'"],
+    imgSrc: ["'self'", 'data:', 'https:'],
+  },
+}));
+```
+
+## 11. Request Size Limits
+
+Prevent denial of service through large payloads:
+
+```typescript
+import { bodyLimit } from 'hono/body-limit';
+
+// Limit request body size
+this.server.use('/api/*', bodyLimit({
+  maxSize: 1024 * 1024, // 1MB for general API
+  onError: (c) => c.json({ message: 'Request body too large' }, 413),
+}));
+
+// Allow larger uploads for file endpoints
+this.server.use('/api/upload/*', bodyLimit({
+  maxSize: 50 * 1024 * 1024, // 50MB for file uploads
+}));
+```
+
+## 12. Logging Security Events
+
+Log security-relevant events for monitoring and forensics:
+
+```typescript
+import { BaseService } from '@venizia/ignis';
+
+export class AuthService extends BaseService {
+  async login(email: string, password: string, context: Context) {
+    const ip = context.req.header('x-forwarded-for') ?? 'unknown';
+    const userAgent = context.req.header('user-agent') ?? 'unknown';
+
+    const user = await this.userRepo.findByEmail(email);
+
+    if (!user || !await this.verifyPassword(password, user.password)) {
+      // Log failed attempt
+      this.logger.warn('[login] Failed login attempt | email: %s | ip: %s | userAgent: %s',
+        email, ip, userAgent);
+      throw getError({ statusCode: 401, message: 'Invalid credentials' });
+    }
+
+    // Log successful login
+    this.logger.info('[login] Successful login | userId: %s | ip: %s', user.id, ip);
+
+    return this.generateToken(user);
+  }
+}
+```
+
+**Events to Log:**
+- Failed login attempts
+- Successful logins
+- Password changes
+- Permission changes
+- Suspicious activity (rate limit hits, invalid tokens)
+- Admin actions
+
+## Security Checklist
+
+Before deploying to production, verify:
+
+| Category | Check |
+|----------|-------|
+| **Secrets** | All secrets in environment variables, not in code |
+| **Auth** | JWT tokens have reasonable expiration (15min - 24h) |
+| **Input** | All user input validated with Zod schemas |
+| **CORS** | Specific origins configured, not `*` |
+| **Rate Limiting** | Applied to auth endpoints and general API |
+| **Headers** | Security headers configured |
+| **Logging** | Security events logged for monitoring |
+| **Dependencies** | No known vulnerabilities (`bun audit`) |
+| **HTTPS** | TLS configured for production |
+| **Hidden Data** | Sensitive fields use `hiddenProperties` |
+
+## See Also
+
+- [Authentication Component](../references/components/authentication) - JWT setup and configuration
+- [Common Pitfalls](./common-pitfalls) - Security-related mistakes to avoid
+- [Deployment Strategies](./deployment-strategies) - Secure deployment practices