service-readiness-check

A small, configuration-driven readiness gate for HTTP, TCP, and DNS dependencies. It answers a deployment question that endpoint monitoring alone does not: is the complete service path ready to receive traffic?

The checker distinguishes critical from optional dependencies, requires consecutive successes to reduce transient false positives, applies latency and response assertions, and emits both machine-readable JSON and a GitHub-friendly Markdown summary.

Quick start

Requires Node.js 22.19 or later.

npm ci
cp config.example.yaml services.yaml
npm run check:services -- --config services.yaml

Exit codes are 0 for ready, 1 for a failed readiness policy, and 2 for invalid configuration or an execution error. Reports are written to reports/readiness.json and reports/readiness.md by default.

Configuration

version: 1
settings:
  attempts: 3
  consecutive_successes: 2
  interval_ms: 500
  timeout_ms: 5000
policy:
  require_all_critical: true
  minimum_optional_healthy_percent: 50
services:
  - name: API readiness
    type: http
    critical: true
    url: https://api.example.com/ready
    headers:
      Authorization: Bearer ${READINESS_TOKEN}
    expected_statuses: [200]
    maximum_latency_ms: 1000
    json_path: status
    json_equals: ready

HTTP checks are intentionally read-only and accept only GET and HEAD. HTTP assertions support allowed status codes, maximum latency, a response substring, or equality at a dotted JSON path. TCP checks verify connectivity; DNS checks require at least one A or AAAA record. Every service supports a latency ceiling.

Values such as ${READINESS_TOKEN} are expanded from the environment. Missing variables are configuration errors, and secrets are not included in reports.

Validate without contacting any service:

node src/cli.js --config services.yaml --validate

Docker

docker build -t service-readiness-check .
docker run --rm -v "$PWD:/work:ro" service-readiness-check --config /work/services.yaml --output /tmp/reports

Mount a writable output directory if reports need to persist outside the container.

GitHub Actions

- uses: CodeVeloHQ/service-readiness-check@main
  with:
    config: services.yaml
- if: always()
  uses: actions/upload-artifact@v4
  with:
    name: service-readiness-report
    path: reports/

The action also writes its Markdown report to the workflow job summary. Keep authentication values in GitHub Actions secrets and reference them through environment variables. A complete example workflow is available to copy into .github/workflows/ after adding a services.yaml configuration to your repository.

Scope

This tool is a deployment/readiness gate, not a daemon, uptime monitor, load tester, or protocol-specific database client. Use it alongside observability and the other CodeVelo audit tools for broader delivery assurance.

Development

npm ci
npm run check

See CONTRIBUTING.md for contribution guidance and SECURITY.md for private vulnerability reporting.

License

MIT