Add Readiness Checks

Use readiness checks when process start is not enough to guarantee service usability.

FlowLayer supports three readiness modes: none, tcp, and http.

Choose the right mode

• none: use when successful start or exit is already enough.
• tcp: use when "port is accepting connections" is a good readiness signal.
• http: use when your app exposes a health endpoint that reflects app-level readiness.

See full field semantics in Readiness.

Example: postgres TCP + api HTTP

{
	"services": {
		"postgres": {
			"cmd": ["docker", "compose", "up", "postgres"],
			"port": 5432,
			"ready": {
				"type": "tcp"
			}
		},
		"api": {
			"cmd": ["pnpm", "--dir", "services/api", "dev"],
			"dependsOn": ["postgres"],
			"port": 3000,
			"ready": {
				"type": "http",
				"url": "http://127.0.0.1:3000/health"
			}
		},
		"worker": {
			"cmd": ["pnpm", "--dir", "services/worker", "dev"],
			"dependsOn": ["postgres"],
			"ready": {
				"type": "none"
			}
		}
	}
}

Notes from confirmed behavior:

• for tcp, ready.port defaults to service.port when omitted
• for http, ready.url is required
• probes run every 200 ms
• HTTP and TCP probe attempts use a 200 ms client timeout

Ready vs running

In operations, treat these states differently:

• running: process start succeeded
• ready: readiness gate succeeded

Why it matters:

• without readiness, a dependent can start as soon as the dependency process is running
• with readiness, a dependent waits until the readiness condition is satisfied

Common pitfalls

• http probe path checks only HTTP status (200 to 399), not full business health.
• tcp proves listener availability, not schema/migration readiness.
• there is no user-configurable global startup timeout; probes continue until success, process exit, or shutdown.

Practical workflow

1. Start with none for fast iteration.
2. Add tcp on infrastructure services (postgres, redis, brokers).
3. Add http on application services that expose /health.
4. Keep probes cheap and local.

For dependency sequencing, continue with Use Startup Waves.