Health Check API (/health)

The Health Check API provides endpoints to monitor the status and availability of the Kodus Runtime API. It is a public-facing feature, requiring no authentication, making it suitable for use by automated monitoring systems, container orchestrators, and load balancers. The primary purpose is to confirm that the API service is running and, in some cases, ready to accept traffic by checking its dependencies.

The main project documentation highlights GET /api/health as a public route for checking the API's status. Different implementations exist within the codebase, including a primary one using the Elysia framework and a fallback using a basic Node.js HTTP server.

Sources: README.md:36-42, README.md:104-105

API Endpoints

The health check functionality is exposed through a set of GET endpoints prefixed with /health.

Sources: apps/api/src/routes/health.ts:3-19

Endpoint Summary

Sources: apps/api/src/routes/health.ts:5-19

Request Flow

The following diagram illustrates the sequence of a monitoring service checking the API's health.

This diagram shows a standard request-response cycle for the health and readiness endpoints.
Sources: apps/api/src/routes/health.ts:3-19, tools/docker/docker-compose.yml:20-25

Implementations

The Health Check API has multiple implementations within the project, tailored for different environments and frameworks.

Elysia.js Implementation (Primary)

The main API, built with Elysia.js, registers the health routes from a dedicated module. This is the primary implementation used by the application.

The request handling flow within the Elysia app is straightforward:

This diagram shows how an incoming request is routed to the healthRoutes module, which executes the corresponding handler to return a JSON object.
Sources: apps/api/src/index.ts:12, apps/api/src/routes/health.ts:3

/health Endpoint

This endpoint returns a simple status to indicate the API is alive.

// Source: apps/api/src/routes/health.ts:5-10
.get('/health', () => ({
  status: 'healthy',
  timestamp: new Date().toISOString(),
  service: 'Kodus Runtime API',
  version: '0.1.0'
}))

Sample Response:

{
  "status": "healthy",
  "timestamp": "2023-10-27T10:00:00.000Z",
  "service": "Kodus Runtime API",
  "version": "0.1.0"
}

Sources: apps/api/src/routes/health.ts:5-10

/health/ready Endpoint

This endpoint performs a deeper check, verifying the status of dependencies like the database and the core runtime.

// Source: apps/api/src/routes/health.ts:12-19
.get('/health/ready', () => ({
  status: 'ready',
  timestamp: new Date().toISOString(),
  checks: {
    database: 'healthy',
    runtime: 'healthy'
  }
}))

Sample Response:

{
  "status": "ready",
  "timestamp": "2023-10-27T10:01:00.000Z",
  "checks": {
    "database": "healthy",
    "runtime": "healthy"
  }
}

Note: The dependency checks (database, runtime) are currently hardcoded to 'healthy' and do not reflect a real-time check.
Sources: apps/api/src/routes/health.ts:12-19

Basic Node.js HTTP Server Implementation

A fallback implementation using Node.js's native http module exists in server.ts. This version provides a basic /health endpoint and is used when the full Elysia application isn't running, ensuring a minimal health check is always available.

// Source: apps/api/src/server.ts:6-14
if (req.url === '/health') {
  res.statusCode = 200
  res.setHeader('Content-Type', 'application/json')
  res.end(JSON.stringify({
    success: true,
    message: 'API is healthy',
    timestamp: new Date().toISOString()
  }))
  return
}

This implementation is simpler and only handles the /health path, returning a 404 Not Found for any other URL.
Sources: apps/api/src/server.ts:6-22

Express.js Example Implementation

An example Express application also demonstrates a /health endpoint, showing how the Kodus Runtime could be integrated into a standard Express server.

// Source: apps/api/examples/express-app.js:122-128
app.get('/health', (req, res) => {
    res.json({
        status: 'healthy',
        timestamp: new Date().toISOString(),
        service: 'Kodus Runtime API'
    });
});

This example reinforces the standard pattern for the health check endpoint across different Node.js frameworks.
Sources: apps/api/examples/express-app.js:122-128

Docker Integration

The health check is critical for containerized deployments. The docker-compose.yml file for the api service defines a healthcheck that uses curl to periodically hit the /health endpoint.

# Source: tools/docker/docker-compose.yml:20-25
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3201/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

This configuration instructs Docker to:

1. Wait for a start_period of 40 seconds before the first check.
2. Run the curl command every 30 seconds (interval).
3. If a check takes longer than 10 seconds, it fails (timeout).
4. If a check fails, retry it up to 3 times (retries) before marking the container as unhealthy.

Sources: tools/docker/docker-compose.yml:20-25

Summary

The Health Check API is a fundamental feature for ensuring the reliability and observability of the Kodus Runtime API. It provides simple, unauthenticated endpoints (/health and /health/ready) that are leveraged by both developers for manual checks and by automated systems like Docker for container health monitoring. The consistent implementation pattern across Elysia.js, basic Node.js, and Express.js examples underscores its importance in the system's architecture.

Sources: README.md:36, apps/api/src/routes/health.ts, tools/docker/docker-compose.yml:20-25