create-tigra 1.0.7 → 2.0.0

package/template/server/src/libs/logger.ts

@@ -1,60 +1,33 @@
-/**
- * Logger Configuration
- * 
- * Pino logger with structured logging and sensitive data redaction.
- * 
- * @see /mnt/project/08-observability.md
- */
-
-import pino from 'pino';
-
-/**
- * Create Pino logger instance
- * 
- * Features:
- * - Structured JSON logging in production
- * - Pretty-printed logs in development
- * - Automatic redaction of sensitive data
- * - Configurable log levels
- */
-const logger = pino({
-    // Log level from environment or default to 'info'
-    level: process.env.LOG_LEVEL || 'info',
-
-    // Pretty printing in development only
-    transport:
-        process.env.NODE_ENV === 'development'
-            ? {
-                target: 'pino-pretty',
-                options: {
-                    colorize: true,
-                    translateTime: 'HH:MM:ss Z',
-                    ignore: 'pid,hostname',
-                },
-            }
-            : undefined,
-
-    // Redact sensitive data
-    redact: {
-        paths: [
-            'req.headers.authorization',
-            '*.password',
-            '*.token',
-            'req.body.password',
-            'req.body.refreshToken',
-            'req.body.accessToken',
-            'res.headers.authorization',
-        ],
-        censor: '[REDACTED]',
-    },
-
-    // Base configuration
-    base: {
-        env: process.env.NODE_ENV || 'development',
-    },
-
-    // Timestamp format
-    timestamp: pino.stdTimeFunctions.isoTime,
-});
-
-export default logger;
+import pino from 'pino';
+import { env } from '@config/env.js';
+
+export const logger = pino({
+  level: env.LOG_LEVEL,
+  ...(env.NODE_ENV !== 'production' && {
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        colorize: true,
+        translateTime: 'HH:MM:ss.l',
+        ignore: 'pid,hostname',
+        messageFormat: '{msg}',
+      },
+    },
+  }),
+  serializers: {
+    req: (req) => ({
+      method: req.method,
+      url: req.url,
+      query: req.query,
+      params: req.params,
+      headers: {
+        host: req.headers.host,
+        'user-agent': req.headers['user-agent'],
+        'content-type': req.headers['content-type'],
+      },
+    }),
+    res: (res) => ({
+      statusCode: res.statusCode,
+    }),
+  },
+});

package/template/server/src/libs/monitoring.ts

@@ -0,0 +1,205 @@
+import { prisma } from '@libs/prisma.js';
+import { getRedis } from '@libs/redis.js';
+import { env } from '@config/env.js';
+import { logger } from '@libs/logger.js';
+
+export interface HealthCheckResult {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  checks: {
+    database: CheckStatus;
+    redis: CheckStatus;
+    memory: CheckStatus;
+    uptime: CheckStatus;
+  };
+  timestamp: string;
+  version: string;
+  environment: string;
+}
+
+export interface CheckStatus {
+  status: 'up' | 'down' | 'degraded';
+  message?: string;
+  responseTime?: number;
+  details?: Record<string, unknown>;
+}
+
+const startTime = Date.now();
+
+/**
+ * Check database connectivity and response time
+ */
+async function checkDatabase(): Promise<CheckStatus> {
+  const start = Date.now();
+  try {
+    await prisma.$queryRaw`SELECT 1`;
+    const responseTime = Date.now() - start;
+
+    return {
+      status: responseTime < 100 ? 'up' : 'degraded',
+      message: responseTime < 100 ? 'Database is healthy' : 'Database responding slowly',
+      responseTime,
+      details: {
+        poolMin: env.DATABASE_POOL_MIN,
+        poolMax: env.DATABASE_POOL_MAX,
+      },
+    };
+  } catch (error) {
+    const responseTime = Date.now() - start;
+    logger.error({ error }, 'Database health check failed');
+    return {
+      status: 'down',
+      message: 'Database connection failed',
+      responseTime,
+    };
+  }
+}
+
+/**
+ * Check Redis connectivity and response time
+ */
+async function checkRedis(): Promise<CheckStatus> {
+  const start = Date.now();
+  try {
+    const redis = getRedis();
+    await redis.ping();
+    const responseTime = Date.now() - start;
+
+    return {
+      status: responseTime < 50 ? 'up' : 'degraded',
+      message: responseTime < 50 ? 'Redis is healthy' : 'Redis responding slowly',
+      responseTime,
+      details: {
+        maxRetries: env.REDIS_MAX_RETRIES,
+        connectTimeout: env.REDIS_CONNECT_TIMEOUT,
+      },
+    };
+  } catch (error) {
+    const responseTime = Date.now() - start;
+    logger.warn({ error }, 'Redis health check failed');
+    return {
+      status: 'down',
+      message: 'Redis connection failed (non-fatal)',
+      responseTime,
+    };
+  }
+}
+
+/**
+ * Check memory usage
+ */
+function checkMemory(): CheckStatus {
+  const used = process.memoryUsage();
+  const heapUsedMB = Math.round(used.heapUsed / 1024 / 1024);
+  const heapTotalMB = Math.round(used.heapTotal / 1024 / 1024);
+  const rssMB = Math.round(used.rss / 1024 / 1024);
+  const heapUsagePercent = Math.round((used.heapUsed / used.heapTotal) * 100);
+
+  // Warn if heap usage > 80%
+  const status = heapUsagePercent > 80 ? 'degraded' : 'up';
+  const message =
+    status === 'degraded'
+      ? `High memory usage: ${heapUsagePercent}%`
+      : `Memory usage normal: ${heapUsagePercent}%`;
+
+  return {
+    status,
+    message,
+    details: {
+      heapUsedMB,
+      heapTotalMB,
+      rssMB,
+      heapUsagePercent,
+      external: Math.round(used.external / 1024 / 1024),
+    },
+  };
+}
+
+/**
+ * Check server uptime
+ */
+function checkUptime(): CheckStatus {
+  const uptimeSeconds = Math.floor((Date.now() - startTime) / 1000);
+  const uptimeMinutes = Math.floor(uptimeSeconds / 60);
+  const uptimeHours = Math.floor(uptimeMinutes / 60);
+  const uptimeDays = Math.floor(uptimeHours / 24);
+
+  let uptimeFormatted: string;
+  if (uptimeDays > 0) {
+    uptimeFormatted = `${uptimeDays}d ${uptimeHours % 24}h`;
+  } else if (uptimeHours > 0) {
+    uptimeFormatted = `${uptimeHours}h ${uptimeMinutes % 60}m`;
+  } else if (uptimeMinutes > 0) {
+    uptimeFormatted = `${uptimeMinutes}m ${uptimeSeconds % 60}s`;
+  } else {
+    uptimeFormatted = `${uptimeSeconds}s`;
+  }
+
+  return {
+    status: 'up',
+    message: `Server running for ${uptimeFormatted}`,
+    details: {
+      uptimeSeconds,
+      startTime: new Date(startTime).toISOString(),
+    },
+  };
+}
+
+/**
+ * Perform comprehensive health check
+ */
+export async function performHealthCheck(): Promise<HealthCheckResult> {
+  const [database, redis, memory, uptime] = await Promise.all([
+    checkDatabase(),
+    checkRedis(),
+    checkMemory(),
+    checkUptime(),
+  ]);
+
+  // Determine overall status
+  let status: 'healthy' | 'degraded' | 'unhealthy';
+  if (database.status === 'down') {
+    status = 'unhealthy'; // Critical: DB is required
+  } else if (
+    database.status === 'degraded' ||
+    redis.status === 'degraded' ||
+    memory.status === 'degraded'
+  ) {
+    status = 'degraded';
+  } else {
+    status = 'healthy';
+  }
+
+  return {
+    status,
+    checks: {
+      database,
+      redis,
+      memory,
+      uptime,
+    },
+    timestamp: new Date().toISOString(),
+    version: '1.0.0',
+    environment: env.NODE_ENV,
+  };
+}
+
+/**
+ * Simple readiness check (for load balancers)
+ */
+export async function checkReadiness(): Promise<boolean> {
+  try {
+    // Only check database - critical dependency
+    await prisma.$queryRaw`SELECT 1`;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Simple liveness check (for container orchestration)
+ */
+export function checkLiveness(): boolean {
+  // Server is alive if this function executes
+  return true;
+}

package/template/server/src/libs/password.ts

@@ -0,0 +1,38 @@
+import argon2 from 'argon2';
+
+// OWASP recommended argon2id configuration
+const ARGON2_OPTIONS: argon2.Options = {
+  type: argon2.argon2id,
+  memoryCost: 65536, // 64 MB
+  timeCost: 3,
+  parallelism: 4,
+};
+
+/**
+ * Hash a password using argon2id
+ */
+export async function hashPassword(password: string): Promise<string> {
+  return argon2.hash(password, ARGON2_OPTIONS);
+}
+
+/**
+ * Verify a password against a hash.
+ * Supports both argon2 and legacy bcrypt hashes.
+ * Returns { valid, needsRehash } so the caller can transparently upgrade bcrypt hashes.
+ */
+export async function verifyPassword(
+  password: string,
+  hash: string,
+): Promise<{ valid: boolean; needsRehash: boolean }> {
+  const isBcryptHash = hash.startsWith('$2a$') || hash.startsWith('$2b$') || hash.startsWith('$2y$');
+
+  if (isBcryptHash) {
+    // Lazy-import bcryptjs only for legacy hash verification
+    const bcrypt = await import('bcryptjs');
+    const valid = await bcrypt.default.compare(password, hash);
+    return { valid, needsRehash: valid }; // rehash only if password is correct
+  }
+
+  const valid = await argon2.verify(hash, password);
+  return { valid, needsRehash: false };
+}

package/template/server/src/libs/prisma.ts

@@ -0,0 +1,68 @@
+import { PrismaClient } from '@prisma/client';
+import { logger } from '@libs/logger.js';
+import { env } from '@config/env.js';
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    // Note: Connection pool size is configured via DATABASE_URL query params
+    // Example: DATABASE_URL="mysql://...?connection_limit=50&pool_timeout=10"
+    log:
+      env.NODE_ENV === 'development'
+        ? [
+            { emit: 'event', level: 'query' },
+            { emit: 'stdout', level: 'warn' },
+            { emit: 'stdout', level: 'error' },
+          ]
+        : [
+            { emit: 'stdout', level: 'error' },
+            // Log slow queries in production (queries taking > 2000ms)
+            { emit: 'event', level: 'query' },
+          ],
+    // Note: Connection pool size is configured via DATABASE_URL query params
+    // Example: DATABASE_URL="mysql://...?connection_limit=50&pool_timeout=10"
+  });
+
+// Log slow queries in production (queries taking > 2000ms)
+if (env.NODE_ENV === 'production') {
+  prisma.$on('query' as never, (e: { duration: number; query: string }) => {
+    if (e.duration > 2000) {
+      logger.warn(
+        { duration: e.duration, query: e.query },
+        `Slow query detected: ${e.duration}ms`,
+      );
+    }
+  });
+}
+
+// Log all queries in development for debugging
+if (env.NODE_ENV === 'development') {
+  prisma.$on('query' as never, (e: { duration: number; query: string }) => {
+    logger.debug({ duration: e.duration, query: e.query }, 'Database query');
+  });
+}
+
+if (env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma;
+}
+
+export async function testDatabaseConnection(): Promise<boolean> {
+  try {
+    await prisma.$queryRaw`SELECT 1`;
+    logger.info('[DATABASE] Connection established');
+    return true;
+  } catch (error) {
+    logger.warn('[DATABASE] Connection failed — server will start without DB');
+    logger.debug(error);
+    return false;
+  }
+}
+
+export async function disconnectPrisma(): Promise<void> {
+  await prisma.$disconnect();
+  logger.info('[DATABASE] Disconnected');
+}

package/template/server/src/libs/redis.ts

@@ -1,79 +1,60 @@
-/**
- * Redis Connection
- * 
- * Redis client for caching, sessions, and BullMQ queues.
- * 
- * @see /mnt/project/10-background-jobs-v2.md
- */
-
-import Redis from 'ioredis';
-import logger from './logger';
-
-/**
- * Create Redis client instance
- * 
- * Configuration:
- * - maxRetriesPerRequest: null (REQUIRED for BullMQ)
- * - Automatic reconnection
- * - Error handling
- */
-const redis = new Redis({
-    host: process.env['REDIS_HOST'] || 'localhost',
-    port: parseInt(process.env['REDIS_PORT'] || '6379'),
-    password: process.env['REDIS_PASSWORD'] || undefined,
-    db: parseInt(process.env['REDIS_DB'] || '0'),
-
-    // CRITICAL: Required for BullMQ compatibility
-    maxRetriesPerRequest: null,
-
-    // Retry strategy
-    retryStrategy: () => {
-        // Stop retrying immediately if connection fails
-        logger.error('Redis connection failed. Running without Redis.');
-        return null;
-    },
-
-    // Connection timeout
-    connectTimeout: 10000,
-
-    // Enable offline queue
-    enableOfflineQueue: true,
-});
-
-/**
- * Connection Event Handlers
- */
-redis.on('connect', () => {
-    logger.info('Redis connected');
-});
-
-redis.on('ready', () => {
-    logger.info('Redis ready to accept commands');
-});
-
-redis.on('error', (error: Error) => {
-    // Suppress ECONNREFUSED logs (connection refused) to prevent noise when Redis is offline
-    if (error.message.includes('ECONNREFUSED') || error.stack?.includes('ECONNREFUSED')) {
-        return;
-    }
-
-    logger.error(
-        {
-            error: error.message,
-            stack: error.stack,
-        },
-        'Redis connection error'
-    );
-});
-
-redis.on('close', () => {
-    logger.warn('Redis connection closed');
-});
-
-redis.on('reconnecting', () => {
-    logger.info('Redis reconnecting...');
-});
-
-
-
-export { redis };
+import { Redis } from 'ioredis';
+import { env } from '@config/env.js';
+import { logger } from '@libs/logger.js';
+
+let redis: Redis | null = null;
+
+export function getRedis(): Redis {
+  if (!redis) {
+    redis = new Redis(env.REDIS_URL, {
+      maxRetriesPerRequest: env.REDIS_MAX_RETRIES,
+      connectTimeout: env.REDIS_CONNECT_TIMEOUT,
+      lazyConnect: true,
+      retryStrategy: (times: number) => {
+        // Exponential backoff with max delay of 3 seconds
+        if (times > env.REDIS_MAX_RETRIES) {
+          // Stop retrying after max retries
+          logger.error('[REDIS] Max retries reached, giving up');
+          return null;
+        }
+        const delay = Math.min(times * 50, 3000);
+        logger.debug(`[REDIS] Retry attempt ${times}, waiting ${delay}ms`);
+        return delay;
+      },
+    });
+
+    redis.on('connect', () => {
+      logger.info('[REDIS] Connection established');
+    });
+
+    redis.on('error', (error: Error) => {
+      logger.warn({ err: error }, '[REDIS] Connection error');
+    });
+
+    redis.on('reconnecting', (delay: number) => {
+      logger.info({ delay }, '[REDIS] Reconnecting');
+    });
+  }
+
+  return redis;
+}
+
+export async function connectRedis(): Promise<boolean> {
+  try {
+    const client = getRedis();
+    await client.connect();
+    return true;
+  } catch (error) {
+    logger.warn('[REDIS] Connection failed — server will start without Redis');
+    logger.debug(error);
+    return false;
+  }
+}
+
+export async function disconnectRedis(): Promise<void> {
+  if (redis) {
+    await redis.quit();
+    redis = null;
+    logger.info('[REDIS] Disconnected');
+  }
+}

package/template/server/src/libs/requestLogger.ts

@@ -0,0 +1,66 @@
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import { logger } from '@libs/logger.js';
+
+const colors = {
+  // Methods: blue=read, green=create, yellow=update, red=destroy, gray=meta
+  GET: '\x1b[34m',
+  POST: '\x1b[32m',
+  PUT: '\x1b[33m',
+  PATCH: '\x1b[33m',
+  DELETE: '\x1b[31m',
+  OPTIONS: '\x1b[90m',
+  HEAD: '\x1b[90m',
+
+  // Status: green=ok, cyan=redirect, yellow=client error, red=server error
+  success: '\x1b[32m',
+  redirect: '\x1b[36m',
+  clientError: '\x1b[33m',
+  serverError: '\x1b[31m',
+
+  dim: '\x1b[90m',
+  reset: '\x1b[0m',
+};
+
+function getStatusColor(statusCode: number): string {
+  if (statusCode >= 500) return colors.serverError;
+  if (statusCode >= 400) return colors.clientError;
+  if (statusCode >= 300) return colors.redirect;
+  return colors.success;
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1) return `${(ms * 1000).toFixed(0)}μs`;
+  if (ms < 1000) return `${ms.toFixed(0)}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+/**
+ * Mark request start time (called in preHandler)
+ */
+export function markRequestStart(request: FastifyRequest): void {
+  request.startTime = Date.now();
+}
+
+/**
+ * Log a single-line request/response summary (called in onResponse)
+ *
+ * Format: GET /api/v1/auth/me 200 OK (12ms)
+ */
+export function logRequestLine(request: FastifyRequest, reply: FastifyReply): void {
+  const duration = request.startTime ? Date.now() - request.startTime : 0;
+  const statusCode = reply.statusCode;
+  const statusMessage = reply.raw.statusMessage || '';
+
+  const methodColor = colors[request.method as keyof typeof colors] || colors.reset;
+  const statusColor = getStatusColor(statusCode);
+
+  const line = `${methodColor}${request.method.padEnd(7)}${colors.reset}${request.url} ${statusColor}${statusCode} ${statusMessage}${colors.reset} ${colors.dim}(${formatDuration(duration)})${colors.reset}`;
+
+  if (statusCode >= 500) {
+    logger.error(line);
+  } else if (statusCode >= 400) {
+    logger.warn(line);
+  } else {
+    logger.info(line);
+  }
+}