Skip to main content

​
Overview

The /ready endpoint provides a comprehensive readiness check that validates both the Permission Mongo server and its external dependencies (MongoDB, Redis). This endpoint is essential for Kubernetes readiness probes and ensuring the service is fully operational before routing traffic.

​
Endpoint

GET /ready

​
Authentication

No authentication required. This endpoint is publicly accessible.

​
Request

No request parameters or body required.

​
Example Request

curl http://localhost:8080/ready

​
Response

​
Success Response (200 OK)

Returns when the server and all required dependencies are operational. 
{
  "data": {
    "status": "ready",
    "checks": {
      "mongodb": "ok",
      "redis": "ok"
    },
    "goroutines": 42
  },
  "meta": {
    "request_id": "req_abc123xyz"
  }
}

​
Failure Response (503 Service Unavailable)

Returns when one or more dependencies are unavailable. 
{
  "data": {
    "status": "not_ready",
    "checks": {
      "mongodb": "unavailable",
      "redis": "not_configured"
    },
    "goroutines": 38
  },
  "meta": {
    "request_id": "req_def456uvw"
  }
}

​
Response Fields

FieldTypeDescription
data.statusstringOverall readiness status: "ready" or "not_ready"
data.checksobjectIndividual health checks for each dependency
data.checks.mongodbstringMongoDB connection status: "ok", "unavailable", or "not_configured"
data.checks.redisstringRedis/cache connection status: "ok" or "not_configured"
data.goroutinesintegerNumber of active goroutines in the server process
meta.request_idstringUnique identifier for the request

​
Status Codes

Status CodeDescription
200 OKService is ready and all dependencies are operational
503 Service UnavailableService is not ready or dependencies are unavailable

​
Dependency Checks

​
MongoDB

The MongoDB check validates the connection to the primary datastore:
  • ok: MongoDB is connected and operational
  • unavailable: MongoDB connection failed or is disconnected
  • not_configured: MongoDB store handler is not configured

​
Redis (Cache)

The Redis check validates the optional cache layer:
  • ok: Redis cache is configured and assumed operational
  • not_configured: Redis cache is not configured (optional, does not fail readiness)

​
Implementation Details

The readiness endpoint:
  • Checks Store.IsConnected() for MongoDB status
  • Verifies cache handler existence for Redis status
  • Returns HTTP 503 if MongoDB is unavailable or not configured
  • Returns HTTP 200 only when all required dependencies are healthy
  • Bypassed by authentication middleware for fast health checks

​
Source Code Reference

Implementation: ~/workspace/source/pkg/api/server.go:419 
func (s *Server) readyHandler(ctx *fasthttp.RequestCtx) {
    // Check dependencies
    ready := true
    checks := make(map[string]string)

    // Check store connection
    if s.handlers != nil && s.handlers.Store != nil {
        if s.handlers.Store.IsConnected() {
            checks["mongodb"] = "ok"
        } else {
            checks["mongodb"] = "unavailable"
            ready = false
        }
    } else {
        checks["mongodb"] = "not_configured"
        ready = false
    }

    // Check cache connection if available
    if s.handlers != nil && s.handlers.Cache != nil {
        checks["redis"] = "ok" // Cache is optional, assume ok if configured
    } else {
        checks["redis"] = "not_configured"
    }

    status := fasthttp.StatusOK
    statusText := "ready"
    if !ready {
        status = fasthttp.StatusServiceUnavailable
        statusText = "not_ready"
    }

    WriteJSON(ctx, status, map[string]interface{}{
        "status":     statusText,
        "checks":     checks,
        "goroutines": runtime.NumGoroutine(),
    })
}

​
Use Cases

  • Kubernetes Readiness Probes: Prevent traffic routing to unhealthy pods
  • Zero-Downtime Deployments: Ensure new instances are fully ready before serving requests
  • Dependency Monitoring: Verify external service connectivity
  • Pre-flight Checks: Validate service state before critical operations

​
Best Practices

  1. Use in Readiness Probes: Configure Kubernetes readiness probes to use this endpoint, not /health
  2. Set Appropriate Timeouts: Allow sufficient time for dependency checks to complete
  3. Monitor 503 Responses: Alert when readiness checks consistently fail
  4. Combine with Liveness: Use /health for liveness and /ready for readiness probes
  • GET /health - Simple health check without dependency validation
  • GET /metrics - Prometheus metrics for detailed monitoring

Build docs developers (and LLMs) love

Get started for freeTalk to us