Skip to content

feat(api): implement canonical /readyz endpoint #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lffranca merged 1 commit into from
Apr 29, 2026
Merged

feat(api): implement canonical /readyz endpoint #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
# DEFAULT local
ENV_NAME=development

# DEPLOYMENT MODE
# Controls TLS enforcement for database connections:
# - saas: TLS MANDATORY for all DB connections (hard-fail at startup without TLS)
# - byoc: TLS recommended but not hard-enforced (customer-hosted)
# - local: TLS optional (developer workstation, default if unset)
DEPLOYMENT_MODE=local

# APP
SERVER_PORT=4021
VERSION=v1.0.0
Expand Down
91 changes: 32 additions & 59 deletions api/docs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,55 +16,12 @@ const docTemplate = `{
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/health": {
"/readyz": {
"get": {
"description": "Returns detailed health information including uptime and version",
"produces": [
"description": "Returns dependency health status following canonical contract",
"consumes": [
"application/json"
],
"tags": [
"Health"
],
"summary": "Combined health check",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/internal_adapters_http_in_health.HealthResponse"
}
},
"503": {
"description": "Service Unavailable",
"schema": {
"$ref": "#/definitions/internal_adapters_http_in_health.HealthResponse"
}
}
}
}
},
"/health/live": {
"get": {
"description": "Returns 200 OK if the application process is running",
"produces": [
"application/json"
],
"tags": [
"Health"
],
"summary": "Kubernetes liveness probe",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/internal_adapters_http_in_health.HealthResponse"
}
}
}
}
},
"/health/ready": {
"get": {
"description": "Returns 200 OK if the application is ready to serve traffic",
"produces": [
"application/json"
],
Expand All @@ -74,15 +31,15 @@ const docTemplate = `{
"summary": "Kubernetes readiness probe",
"responses": {
"200": {
"description": "OK",
"description": "Service is healthy - all dependencies up/skipped/n-a",
"schema": {
"$ref": "#/definitions/internal_adapters_http_in_health.HealthResponse"
"$ref": "#/definitions/internal_adapters_http_in_readyz.Response"
}
},
"503": {
"description": "Service Unavailable",
"description": "Service is unhealthy - one or more dependencies down/degraded",
"schema": {
"$ref": "#/definitions/internal_adapters_http_in_health.HealthResponse"
"$ref": "#/definitions/internal_adapters_http_in_readyz.Response"
}
}
}
Expand Down Expand Up @@ -3703,33 +3660,49 @@ const docTemplate = `{
}
}
},
"internal_adapters_http_in_health.CheckResult": {
"internal_adapters_http_in_readyz.DependencyCheck": {
"type": "object",
"properties": {
"message": {
"breaker_state": {
"description": "when dep is breaker-wrapped",
"type": "string"
},
"error": {
"description": "when status is down or degraded",
"type": "string"
},
"latency_ms": {
"description": "when status is up or degraded",
"type": "integer"
},
"reason": {
"description": "when status is skipped or n/a",
"type": "string"
},
"status": {
"description": "up/down/degraded/skipped/n/a (closed set)",
"type": "string"
},
"tls": {
"description": "when dependency supports TLS",
"type": "boolean"
}
}
},
"internal_adapters_http_in_health.HealthResponse": {
"internal_adapters_http_in_readyz.Response": {
"type": "object",
"properties": {
"checks": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/internal_adapters_http_in_health.CheckResult"
"$ref": "#/definitions/internal_adapters_http_in_readyz.DependencyCheck"
}
},
"status": {
"type": "string"
},
"timestamp": {
"deployment_mode": {
"type": "string"
},
"uptime": {
"status": {
"description": "\"healthy\" or \"unhealthy\"",
"type": "string"
},
"version": {
Expand Down
2 changes: 1 addition & 1 deletion api/docs_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ func TestDocTemplate(t *testing.T) {
"/v1/workflows/{id}",
"/v1/catalog/executors",
"/v1/catalog/triggers",
"/health",
// NOTE: /health and /readyz are infrastructure routes excluded from OpenAPI spec
},
},
{
Expand Down
88 changes: 38 additions & 50 deletions api/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,54 +8,22 @@ info:
servers:
- url: //localhost:4021/
paths:
/health:
/readyz:
get:
description: Returns detailed health information including uptime and version
description: Returns dependency health status following canonical contract
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/internal_adapters_http_in_health.HealthResponse'
description: OK
"503":
content:
application/json:
schema:
$ref: '#/components/schemas/internal_adapters_http_in_health.HealthResponse'
description: Service Unavailable
summary: Combined health check
tags:
- Health
/health/live:
get:
description: Returns 200 OK if the application process is running
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/internal_adapters_http_in_health.HealthResponse'
description: OK
summary: Kubernetes liveness probe
tags:
- Health
/health/ready:
get:
description: Returns 200 OK if the application is ready to serve traffic
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/internal_adapters_http_in_health.HealthResponse'
description: OK
$ref: '#/components/schemas/internal_adapters_http_in_readyz.Response'
description: Service is healthy - all dependencies up/skipped/n-a
"503":
content:
application/json:
schema:
$ref: '#/components/schemas/internal_adapters_http_in_health.HealthResponse'
description: Service Unavailable
$ref: '#/components/schemas/internal_adapters_http_in_readyz.Response'
description: Service is unhealthy - one or more dependencies down/degraded
summary: Kubernetes readiness probe
tags:
- Health
Expand Down Expand Up @@ -3386,36 +3354,56 @@ components:
valid:
type: boolean
type: object
internal_adapters_http_in_health.CheckResult:
internal_adapters_http_in_readyz.DependencyCheck:
example:
message: message
reason: reason
tls: true
error: error
breaker_state: breaker_state
latency_ms: 0
status: status
properties:
message:
breaker_state:
description: when dep is breaker-wrapped
type: string
error:
description: when status is down or degraded
type: string
latency_ms:
description: when status is up or degraded
type: integer
reason:
description: when status is skipped or n/a
type: string
status:
description: up/down/degraded/skipped/n/a (closed set)
type: string
tls:
description: when dependency supports TLS
type: boolean
type: object
internal_adapters_http_in_health.HealthResponse:
internal_adapters_http_in_readyz.Response:
example:
checks:
key:
message: message
reason: reason
tls: true
error: error
breaker_state: breaker_state
latency_ms: 0
status: status
version: version
deployment_mode: deployment_mode
status: status
timestamp: timestamp
uptime: uptime
properties:
checks:
additionalProperties:
$ref: '#/components/schemas/internal_adapters_http_in_health.CheckResult'
$ref: '#/components/schemas/internal_adapters_http_in_readyz.DependencyCheck'
type: object
status:
type: string
timestamp:
deployment_mode:
type: string
uptime:
status:
description: '"healthy" or "unhealthy"'
type: string
version:
type: string
Expand Down
Loading
Loading