health.js

Go to the documentation of this file.

/**
 * @file health.js
 * @module HealthRoutes
 * @description Health check and service testing endpoints for infrastructure monitoring. Provides status checks for llama.cpp AI service, Redis cache, and PostgreSQL database. Used by load balancers, monitoring systems, and DevOps dashboards.
 * @see {@link ../services/llamaCppService} for llama.cpp integration
 * @see {@link ../services/db} for database connection
 * @see {@link ../config/redis} for Redis configuration
 * @apiDefine HealthGroup Health
 * @apiGroup Health
 * @apiError (Error 500) ServerError Service test failed (for test endpoints).
 */
 
// Health check route for AI and infrastructure
const express = require('express');
const router = express.Router();
const { healthCheck: llamaHealthCheck, getModelInfo } = require('../services/llamaCppService');
const Redis = require('ioredis');
 
/**
 * @api {get} /health Health check for all services
 * @apiName GetHealth
 * @apiGroup Health
 * @apiDescription Comprehensive health check for all backend services including llama.cpp AI service, Redis cache, and PostgreSQL database. Always returns 200 OK to keep load balancers happy even if individual services are degraded. Use service-level status fields to determine actual health.
 * @apiSuccess {string} status Overall status ("ok").
 * @apiSuccess {string} timestamp Health check timestamp.
 * @apiSuccess {object} services Service-specific health status.
 * @apiSuccess {object} services.llamaCpp Llama.cpp AI service status.
 * @apiSuccess {string} services.llamaCpp.status Service status (healthy, unhealthy, error).
 * @apiSuccess {string} services.llamaCpp.endpoint Llama.cpp endpoint URL.
 * @apiSuccess {object} [services.llamaCpp.model] Model information (if healthy).
 * @apiSuccess {object} services.redis Redis cache status.
 * @apiSuccess {string} services.redis.status Service status (healthy, error).
 * @apiSuccess {Object} services.database PostgreSQL database status.
 * @apiSuccess {string} services.database.status Service status (healthy, unhealthy, error).
 * @apiExample {curl} Example usage:
 *     curl https://api.example.com/health
 * @apiExample {json} Response example:
 *     {
 *       "status": "ok",
 *       "timestamp": "2026-03-12T10:30:00Z",
 *       "services": {
 *         "llamaCpp": {
 *           "status": "healthy",
 *           "endpoint": "http://localhost:8080",
 *           "model": "Qwen2.5-14B-Instruct"
 *         },
 *         "redis": {
 *           "status": "healthy",
 *           "host": "localhost",
 *           "port": 6379
 *         },
 *         "database": {
 *           "status": "healthy"
 *         }
 *       }
 *     }
 */
router.get('/health', async (req, res) => {
  const health = {
    status: 'ok',
    timestamp: new Date().toISOString(),
    services: {}
  };
 
  // Check llama.cpp
  try {
    const llamaHealthy = await llamaHealthCheck();
    health.services.llamaCpp = {
      status: llamaHealthy ? 'healthy' : 'unhealthy',
      endpoint: process.env.LLAMA_CPP_ENDPOINT || 'http://localhost:8080'
    };
    
    if (llamaHealthy) {
      const modelInfo = await getModelInfo();
      if (modelInfo) {
        health.services.llamaCpp.model = modelInfo;
      }
    }
  } catch (error) {
    health.services.llamaCpp = {
      status: 'error',
      error: error.message
    };
    // Don't mark as degraded - llama.cpp might be slow to respond
    console.warn('[Health] llama.cpp check failed:', error.message);
  }
 
  // Check Redis
  try {
    const redisConfig = require('../config/redis');
    const redis = new Redis({
      ...redisConfig,
      lazyConnect: true
    });
    
    await redis.connect();
    await redis.ping();
    
    health.services.redis = {
      status: 'healthy',
      host: process.env.REDIS_HOST || 'localhost',
      port: process.env.REDIS_PORT || 6379
    };
    
    redis.disconnect();
  } catch (error) {
    health.services.redis = {
      status: 'error',
      error: error.message
    };
    // Don't mark as degraded - Redis might be initializing
    console.warn('[Health] Redis check failed:', error.message);
  }
 
  // Check database (if DB module exists)
  try {
    const db = require('../services/db');
    const result = await db.query('SELECT 1 as health');
    health.services.database = {
      status: result ? 'healthy' : 'unhealthy'
    };
  } catch (error) {
    health.services.database = {
      status: 'error',
      error: error.message
    };
    // Don't mark as degraded - DB might be initializing
    console.warn('[Health] Database check failed:', error.message);
  }
 
  // Always return 200 for DO health checks - the API is running
  res.status(200).json(health);
});
 
/**
 * @api {post} /health/test-llama Test llama.cpp AI endpoint
 * @apiName TestLlama
 * @apiGroup Health
 * @apiDescription Test llama.cpp AI service by sending a sample text for rewriting. Returns the AI-generated output and endpoint information. Used for verifying AI service functionality and model responsiveness.
 * @apiParam {string} [text="Hello, this is a test."] Test input text to send to llama.cpp.
 * @apiSuccess {boolean} success Operation success status.
 * @apiSuccess {string} input Input text sent to llama.cpp.
 * @apiSuccess {string} output AI-generated output from llama.cpp.
 * @apiSuccess {string} endpoint Llama.cpp endpoint URL.
 * @apiError (Error 500) ServerError Llama.cpp service unreachable or error.
 * @apiExample {curl} Example usage:
 *     curl -X POST -d '{"text":"Test message"}' https://api.example.com/health/test-llama
 */
router.post('/test-llama', async (req, res) => {
  const { callLlama } = require('../services/llamaCppService');
  const { text = 'Hello, this is a test.' } = req.body;
  
  try {
    const result = await callLlama(text, 'rewrite');
    res.json({
      success: true,
      input: text,
      output: result,
      endpoint: process.env.LLAMA_CPP_ENDPOINT
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message,
      endpoint: process.env.LLAMA_CPP_ENDPOINT
    });
  }
});
 
/**
 * @api {get} /health/test-redis Test Redis connection
 * @apiName TestRedis
 * @apiGroup Health
 * @apiDescription Test Redis cache connection and functionality by performing set/get operations with a test key. Key expires after 10 seconds. Used for verifying Redis connectivity and read/write operations.
 * @apiSuccess {boolean} success Operation success status.
 * @apiSuccess {string} message Status message.
 * @apiSuccess {number} testValue Value that was set and retrieved.
 * @apiSuccess {string} host Redis host.
 * @apiSuccess {number} port Redis port.
 * @apiError (Error 500) ServerError Redis connection or operation failed.
 * @apiExample {curl} Example usage:
 *     curl https://api.example.com/health/test-redis
 */
router.get('/test-redis', async (req, res) => {
  try {
    const redisConfig = require('../config/redis');
    const redis = new Redis(redisConfig);
    
    const testKey = 'health:test';
    const testValue = Date.now().toString();
    
    await redis.set(testKey, testValue, 'EX', 10);
    const retrieved = await redis.get(testKey);
    
    redis.disconnect();
    
    res.json({
      success: true,
      written: testValue,
      retrieved,
      match: testValue === retrieved,
      config: {
        host: process.env.REDIS_HOST || 'localhost',
        port: process.env.REDIS_PORT || 6379,
        passwordSet: !!process.env.REDIS_PASSWORD
      }
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message
    });
  }
});
 
module.exports = router;