@opengroundplan/core 0.1.1

package/templates/layers/health-checks/blueprint.yaml

@@ -0,0 +1,170 @@
+id: health-checks
+kind: layer
+name: Health checks
+description: >-
+  Kubernetes-shaped health surface: separate liveness, readiness, and startup
+  endpoints backed by a probe registry, per-probe timeouts, a short readiness
+  cache so probe traffic cannot stampede a dependency, and ready-made HTTP and
+  TCP dependency probes. Paths, timeouts, and dependency targets are read from
+  the environment; nothing is inlined at a call site.
+
+tags:
+  - health
+  - liveness
+  - readiness
+  - probes
+  - observability
+  - operations
+  - kubernetes
+
+# Nothing. The layer ships its own settings module and its own probe registry, and the
+# built-in probes take their target as an argument — so it composes with a repo that has
+# no database, cache, or queue. A db/cache layer is probed by registering one line, not by
+# this blueprint reaching into it.
+requires: []
+
+# Deliberately empty. Conflicts must name a blueprint that already exists or the whole
+# catalog fails to load (loader.assertReferencesResolve), and no other health/observability
+# layer exists yet. A future `health-none` or a competing probe layer declares the conflict
+# from its own side — conflicts are symmetric at resolve time, so one side is enough.
+conflicts: []
+
+# Capability names other layers key off instead of naming this blueprint. A tracing or
+# alerting layer wants "there is a readiness surface", not "health-checks is installed".
+provides:
+  - health
+  - liveness-probe
+  - readiness-probe
+  - startup-probe
+  - dependency-probes
+  - health-endpoint
+  - health-config
+
+# Operational concern, orthogonal to folder layout: the probe registry is a flat module in
+# every overlay, so listing a subset here would only be misleading documentation.
+supportsArchitectures: []
+# Framework packages these templates import are installed by the base itself.
+peerProvidedBy: [nextjs-app]
+
+
+variables:
+  - name: healthEnvPrefix
+    prompt: Environment-variable prefix for health settings
+    type: string
+    default: HEALTH
+    required: true
+
+  - name: healthLivePath
+    prompt: Liveness endpoint path (process is up)
+    type: string
+    default: /health/live
+    required: true
+
+  - name: healthReadyPath
+    prompt: Readiness endpoint path (dependencies are reachable)
+    type: string
+    default: /health/ready
+    required: true
+
+  - name: healthStartupPath
+    prompt: Startup endpoint path (slow boot has finished)
+    type: string
+    default: /health/startup
+    required: true
+
+  - name: healthProbeTimeoutMs
+    prompt: Per-probe timeout in milliseconds (must stay under the orchestrator's probe timeout)
+    type: number
+    default: 2000
+    required: true
+
+  - name: healthReadyCacheMs
+    prompt: How long a readiness result is reused, in milliseconds (0 disables the cache)
+    type: number
+    default: 1000
+    required: true
+
+  # A browser SPA has no server process to probe, and a Next.js app exposes route handlers
+  # rather than a node:http listener. One question keeps the same layer id honest for all three.
+  - name: healthTarget
+    prompt: Which runtime serves the health endpoints?
+    type: select
+    default: node-http
+    when: "stack == 'typescript' || stack == 'node'"
+    choices:
+      - { value: node-http, label: 'Node HTTP server (Hono, Nest, Express, plain node:http)' }
+      - { value: nextjs, label: 'Next.js App Router route handlers' }
+      - { value: none, label: 'None — browser-only app, skip the endpoints' }
+
+  - name: dotnetTargetFramework
+    prompt: Target framework for the health project
+    type: string
+    default: net10.0
+    when: "stack == 'dotnet'"
+
+files:
+  # ── docs ────────────────────────────────────────────────────────────────────
+  # A polyglot monorepo has no single place to drop a probe registry; it composes
+  # this layer per app instead, so it gets neither code nor docs.
+  - from: files/docs/health-checks.md
+    when: "stack != 'polyglot'"
+
+  # .NET binds the `Health:` configuration section instead of a dotenv file.
+  - from: files/.env.health.example
+    when: "stack != 'polyglot' && stack != 'dotnet'"
+
+  # ── typescript / node ───────────────────────────────────────────────────────
+  # One dependency-free core for both stacks: `.js` relative specifiers and
+  # `import type` satisfy Hono's nodenext ESM and Nest's commonjs build alike.
+  - from: files/src/health/*.ts
+    when: "(stack == 'typescript' || stack == 'node') && healthTarget != 'none'"
+  - from: files/src/health/__tests__/health.test.ts
+    when: "(stack == 'typescript' || stack == 'node') && healthTarget != 'none'"
+
+  # node:http and node:net are split out so a Next.js edge-capable build never sees them.
+  - from: files/src/health/node/*.ts
+    when: "(stack == 'typescript' || stack == 'node') && healthTarget == 'node-http'"
+
+  # App Router path segments define the URL, so these land on the same paths the
+  # `*_PATH` settings default to.
+  - from: files/src/app/health/**/route.ts
+    when: "stack == 'typescript' && healthTarget == 'nextjs'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  - from: files/src/__solutionName.snake__/health/*.py
+    when: "stack == 'python'"
+  # Stdlib `unittest` only, so the suite runs without adding a test dependency.
+  # The package marker is what makes `unittest discover` able to import the directory.
+  - from: files/tests/*.py
+    when: "stack == 'python'"
+    onConflict: skip
+
+  # ── go ──────────────────────────────────────────────────────────────────────
+  # Standalone package: it imports only the standard library, so it never has to
+  # know the base's module path.
+  - from: files/internal/health/*.go
+    when: "stack == 'go'"
+
+  # ── dotnet ──────────────────────────────────────────────────────────────────
+  # Self-contained class library on the ASP.NET Core shared framework, so it needs
+  # no PackageReference and stays compatible with central package management.
+  - from: files/src/__solutionName.dot__.Health/*
+    when: "stack == 'dotnet'"
+
+# Every stack is served by its standard library or shared framework, so there is nothing
+# to install. The only step is joining the .NET solution.
+  # Code that imports a package the manifest never installs does not build (ADR 0005).
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply: []

package/templates/layers/health-checks/files/.env.health.example

@@ -0,0 +1,23 @@
+# Health surface. Copy the keys you need into .env; every one of them already has a
+# default in the health config module, so an unset key is not an error.
+
+# Probe paths. Change them to match your orchestrator's convention, not the other way round.
+{{ healthEnvPrefix }}_LIVE_PATH={{ healthLivePath }}
+{{ healthEnvPrefix }}_READY_PATH={{ healthReadyPath }}
+{{ healthEnvPrefix }}_STARTUP_PATH={{ healthStartupPath }}
+
+# Per-probe budget. Keep it below the orchestrator's own timeoutSeconds or the probe is
+# cut off before it can report why it failed.
+{{ healthEnvPrefix }}_PROBE_TIMEOUT_MS={{ healthProbeTimeoutMs }}
+
+# How long one readiness result is reused. Every replica probes every few seconds; without
+# this, the probes themselves become load on the dependency. 0 disables the cache.
+{{ healthEnvPrefix }}_READY_CACHE_MS={{ healthReadyCacheMs }}
+
+# Probe endpoints are usually unauthenticated. Leave this off in production: failure
+# messages carry hostnames, ports, and driver errors.
+{{ healthEnvPrefix }}_EXPOSE_DETAILS=false
+
+# Reported in the payload so a probe response identifies which build answered.
+{{ healthEnvPrefix }}_SERVICE_NAME={{ solutionName | kebab }}
+{{ healthEnvPrefix }}_SERVICE_VERSION=0.1.0

package/templates/layers/health-checks/files/__solutionName.dot__.slnx

@@ -0,0 +1,5 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/{{ solutionName | dot }}.Health/{{ solutionName | dot }}.Health.csproj" />
+  </Folder>
+</Solution>

package/templates/layers/health-checks/files/docs/health-checks.md

@@ -0,0 +1,200 @@
+# Health checks
+
+Three endpoints, three different questions. Collapsing them into one is what turns a slow
+dependency into a restart loop.
+
+| Endpoint | Question | Fails when | Orchestrator reaction |
+|---|---|---|---|
+| `{{ healthLivePath }}` | Is the process wedged? | never touches the network | restart the instance |
+| `{{ healthReadyPath }}` | Can it serve traffic? | a critical dependency is unreachable | pull it out of the load balancer |
+| `{{ healthStartupPath }}` | Has boot finished? | slow warm-up still running | hold off liveness until it passes |
+
+A liveness probe that calls the database will restart a perfectly healthy instance every
+time the database hiccups — every replica at once. That is why liveness here has no
+dependency probes at all.
+
+## Status mapping
+
+| Report status | HTTP | Meaning |
+|---|---|---|
+| `healthy` | 200 | every probe passed |
+| `degraded` | 200 | a non-critical probe failed; the instance still serves traffic |
+| `unhealthy` | 503 | a critical probe failed |
+
+Mark a probe non-critical when losing it costs a feature rather than the instance.
+
+## Configuration
+
+Every value is read from the environment (`.NET` binds the `Health:` section instead) and
+falls back to one typed default in the health config module. Nothing is inlined at a call
+site — see `.env.health.example` for the full key list.
+
+| Setting | Default | Why you would change it |
+|---|---|---|
+| `*_LIVE_PATH` / `*_READY_PATH` / `*_STARTUP_PATH` | `{{ healthLivePath }}` / `{{ healthReadyPath }}` / `{{ healthStartupPath }}` | match your platform's convention |
+| `*_PROBE_TIMEOUT_MS` | `{{ healthProbeTimeoutMs }}` | must stay under the orchestrator's `timeoutSeconds` |
+| `*_READY_CACHE_MS` | `{{ healthReadyCacheMs }}` | raise it when many replicas probe one dependency |
+| `*_EXPOSE_DETAILS` | `false` | debugging only — messages leak hostnames and driver errors |
+
+## Registering a probe
+
+Probes are registered once at wiring time. The target address always comes from your own
+config layer, never from a literal in the probe call.
+
+### TypeScript / Node
+
+`src/health/register.ts` is the single registration point. Import it for its side effect
+during boot, then mount the endpoints:
+
+```ts
+import { createServer } from 'node:http';
+import './health/register.js';
+import { serveHealth } from './health/node/http.js';
+
+const server = createServer(async (req, res) => {
+  if (await serveHealth(req, res)) return;
+  // ...your router
+});
+```
+
+Hono:
+
+```ts
+import { handleHealthPath } from './health/index.js';
+
+app.use('*', async (c, next) => {
+  const result = await handleHealthPath(new URL(c.req.url).pathname);
+  return result ? c.json(result.body, result.status, result.headers) : next();
+});
+```
+
+NestJS — a controller that delegates, so the probe logic stays framework-free:
+
+```ts
+import { Controller, Get, Res } from '@nestjs/common';
+import { checkHealth } from '../health';
+
+@Controller()
+export class ProbeController {
+  @Get('health/ready')
+  async ready(@Res() res: Response) {
+    const result = await checkHealth('readiness');
+    res.status(result.status).set(result.headers).json(result.body);
+  }
+}
+```
+
+Next.js: the route handlers under `src/app/health/*` are already wired.
+
+Adding a dependency:
+
+```ts
+import { config } from './config.js';
+import { registerProbe, httpProbe, callbackProbe } from './health/index.js';
+import { tcpProbe } from './health/node/tcp.js';
+
+registerProbe(httpProbe({ name: 'billing-api', url: config.BILLING_API_URL }));
+registerProbe(tcpProbe({ name: 'redis', host: config.REDIS_HOST, port: config.REDIS_PORT }));
+registerProbe(callbackProbe({ name: 'db', run: () => pool.query('select 1'), critical: true }));
+```
+
+Run the suite with `node --test`.
+
+### Python
+
+```python
+from {{ solutionName | snake }}.health import http_probe, register_probe, tcp_probe
+from {{ solutionName | snake }}.health.router import router as health_router
+from {{ solutionName | snake }}.health.register import register_default_probes
+
+register_default_probes()
+register_probe(http_probe("billing-api", settings.billing_api_url))
+register_probe(tcp_probe("redis", settings.redis_host, settings.redis_port))
+
+app.include_router(health_router)
+```
+
+Health routes sit outside the versioned API prefix so a probe never chases an API version.
+Run the suite with `python -m unittest discover -s tests -t .`.
+
+### Go
+
+```go
+cfg, err := health.LoadConfig()
+if err != nil {
+    return err
+}
+
+probes := health.NewRegistry(cfg)
+probes.Register(health.ProcessProbe())
+probes.Register(health.HTTPProbe("billing-api", appCfg.BillingAPIURL))
+probes.Register(health.TCPProbe("redis", appCfg.RedisAddr))
+
+r.Mount("/", probes.Handler())
+```
+
+Or mount the paths on an existing router with `probes.HandlerFor(health.Readiness)`.
+On shutdown, call `probes.InvalidateReadyCache()` before closing the listener so the
+instance stops advertising itself while it drains.
+
+### .NET
+
+```csharp
+builder.Services.AddAppHealthChecks(builder.Configuration);
+// ...
+app.MapAppHealthChecks();
+```
+
+Dependencies are configuration, not code — add them to `appsettings.json`:
+
+```json
+{
+  "Health": {
+    "ExposeDetails": false,
+    "Dependencies": [
+      { "Name": "billing-api", "Kind": "Http", "Url": "https://billing.internal/health", "Tag": "ready" },
+      { "Name": "redis", "Kind": "Tcp", "Host": "redis", "Port": 6379, "Tag": "ready", "Critical": false }
+    ]
+  }
+}
+```
+
+## Kubernetes
+
+`initialDelaySeconds` on liveness is what a startup probe replaces: with a startup probe,
+liveness only begins after boot succeeds, so a slow start no longer needs a guessed delay.
+
+```yaml
+startupProbe:
+  httpGet:
+    path: {{ healthStartupPath }}
+    port: http
+  periodSeconds: 5
+  failureThreshold: 30
+livenessProbe:
+  httpGet:
+    path: {{ healthLivePath }}
+    port: http
+  periodSeconds: 10
+  timeoutSeconds: 3
+  failureThreshold: 3
+readinessProbe:
+  httpGet:
+    path: {{ healthReadyPath }}
+    port: http
+  periodSeconds: 10
+  timeoutSeconds: 3
+  failureThreshold: 2
+```
+
+`timeoutSeconds` must exceed `*_PROBE_TIMEOUT_MS`, or Kubernetes gives up before the probe
+can report which dependency failed.
+
+## Operational rules
+
+- Never authenticate the probe endpoints, and never expose them publicly — bind them to the
+  cluster network or keep `*_EXPOSE_DETAILS` off.
+- Never probe a dependency you would not restart for. Readiness is for dependencies you
+  cannot serve without; everything else belongs on a non-critical probe.
+- Keep the probe path out of your request-logging and tracing sampling, or the traces will
+  be almost entirely health checks.

package/templates/layers/health-checks/files/internal/health/config.go

@@ -0,0 +1,96 @@
+package health
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Prefixed so several services can share one environment without colliding.
+const envPrefix = "{{ healthEnvPrefix }}_"
+
+// Config is the fully resolved health surface for one process.
+type Config struct {
+	LivePath       string
+	ReadyPath      string
+	StartupPath    string
+	ProbeTimeout   time.Duration
+	ReadyCache     time.Duration
+	ExposeDetails  bool
+	ServiceName    string
+	ServiceVersion string
+}
+
+// defaults is the single source of truth for every health tunable. Add a knob here first;
+// the environment only ever overrides a key that already exists in this table.
+var defaults = map[string]string{
+	"LIVE_PATH":    "{{ healthLivePath }}",
+	"READY_PATH":   "{{ healthReadyPath }}",
+	"STARTUP_PATH": "{{ healthStartupPath }}",
+	// Must stay below the orchestrator's own probe timeout or the probe is cut off first.
+	"PROBE_TIMEOUT_MS": "{{ healthProbeTimeoutMs }}",
+	// Probes fire every few seconds from every replica; without this they stampede a dependency.
+	"READY_CACHE_MS": "{{ healthReadyCacheMs }}",
+	// Probe endpoints are usually unauthenticated, so failure detail is opt-in.
+	"EXPOSE_DETAILS":  "false",
+	"SERVICE_NAME":    "{{ solutionName | kebab }}",
+	"SERVICE_VERSION": "0.1.0",
+}
+
+// LoadConfig reads the environment once at startup and reports every bad value at once.
+func LoadConfig() (Config, error) {
+	r := &reader{}
+	cfg := Config{
+		LivePath:       r.str("LIVE_PATH"),
+		ReadyPath:      r.str("READY_PATH"),
+		StartupPath:    r.str("STARTUP_PATH"),
+		ProbeTimeout:   r.durationMs("PROBE_TIMEOUT_MS"),
+		ReadyCache:     r.durationMs("READY_CACHE_MS"),
+		ExposeDetails:  r.boolVal("EXPOSE_DETAILS"),
+		ServiceName:    r.str("SERVICE_NAME"),
+		ServiceVersion: r.str("SERVICE_VERSION"),
+	}
+	if len(r.errs) > 0 {
+		return Config{}, errors.Join(r.errs...)
+	}
+	return cfg, nil
+}
+
+type reader struct {
+	errs []error
+}
+
+func (r *reader) str(key string) string {
+	def, declared := defaults[key]
+	if !declared {
+		r.errs = append(r.errs, fmt.Errorf("health: no default declared for %q", key))
+		return ""
+	}
+	if v, found := os.LookupEnv(envPrefix + key); found && strings.TrimSpace(v) != "" {
+		return strings.TrimSpace(v)
+	}
+	return def
+}
+
+// Milliseconds keep one env contract across every stack; Go converts to a Duration here.
+func (r *reader) durationMs(key string) time.Duration {
+	raw := r.str(key)
+	ms, err := strconv.Atoi(raw)
+	if err != nil || ms < 0 {
+		r.errs = append(r.errs, fmt.Errorf("health: %s%s must be a non-negative integer of milliseconds, got %q", envPrefix, key, raw))
+		return 0
+	}
+	return time.Duration(ms) * time.Millisecond
+}
+
+func (r *reader) boolVal(key string) bool {
+	raw := r.str(key)
+	v, err := strconv.ParseBool(raw)
+	if err != nil {
+		r.errs = append(r.errs, fmt.Errorf("health: %s%s must be true or false, got %q", envPrefix, key, raw))
+	}
+	return v
+}

package/templates/layers/health-checks/files/internal/health/health.go

@@ -0,0 +1,113 @@
+// Package health serves liveness, readiness, and startup probes over a registry of checks.
+// It imports only the standard library, so it drops into any service unchanged.
+package health
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// Status is the aggregate verdict of one probe run.
+type Status string
+
+const (
+	StatusHealthy   Status = "healthy"
+	StatusDegraded  Status = "degraded"
+	StatusUnhealthy Status = "unhealthy"
+)
+
+// Kind separates the three questions an orchestrator asks. Collapsing them into one
+// endpoint is what turns a slow dependency into a restart loop.
+type Kind string
+
+const (
+	Liveness  Kind = "liveness"
+	Readiness Kind = "readiness"
+	Startup   Kind = "startup"
+)
+
+// Result is what a single check reports.
+type Result struct {
+	Status Status         `json:"status"`
+	Detail string         `json:"detail,omitempty"`
+	Data   map[string]any `json:"data,omitempty"`
+}
+
+// Probe is one registered dependency check.
+type Probe struct {
+	Name  string
+	Kinds []Kind
+	// Critical false degrades the report but keeps the endpoint answering 200.
+	Critical bool
+	Check    func(ctx context.Context) Result
+}
+
+// Entry is one probe's outcome inside a report.
+type Entry struct {
+	Name       string         `json:"name"`
+	Status     Status         `json:"status"`
+	Critical   bool           `json:"critical"`
+	DurationMS int64          `json:"duration_ms"`
+	Detail     string         `json:"detail,omitempty"`
+	Data       map[string]any `json:"data,omitempty"`
+}
+
+// Report is the response body of a health endpoint.
+type Report struct {
+	Status        Status  `json:"status"`
+	Service       string  `json:"service"`
+	Version       string  `json:"version"`
+	UptimeSeconds int64   `json:"uptime_seconds"`
+	CheckedAt     string  `json:"checked_at"`
+	DurationMS    int64   `json:"duration_ms"`
+	Checks        []Entry `json:"checks"`
+}
+
+// Registry holds the probes for one process. The zero value is not usable; call NewRegistry.
+type Registry struct {
+	cfg       Config
+	startedAt time.Time
+
+	mu     sync.RWMutex
+	probes []Probe
+
+	cacheMu    sync.Mutex
+	cached     *Report
+	cacheUntil time.Time
+}
+
+// NewRegistry builds a registry from resolved config, so tests can pass their own.
+func NewRegistry(cfg Config) *Registry {
+	return &Registry{cfg: cfg, startedAt: time.Now()}
+}
+
+// Register adds a probe. Registration happens at wiring time, never per request.
+func (r *Registry) Register(p Probe) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.probes = append(r.probes, p)
+}
+
+// InvalidateReadyCache drops the cached answer so a draining instance stops advertising itself.
+func (r *Registry) InvalidateReadyCache() {
+	r.cacheMu.Lock()
+	defer r.cacheMu.Unlock()
+	r.cached = nil
+}
+
+func (r *Registry) probesFor(kind Kind) []Probe {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	selected := make([]Probe, 0, len(r.probes))
+	for _, p := range r.probes {
+		for _, k := range p.Kinds {
+			if k == kind {
+				selected = append(selected, p)
+				break
+			}
+		}
+	}
+	return selected
+}