Skip to content

devlanes is in beta and not ready for production use.Report an issue

Ready checks

One Hono server run as eight services, each with another kind of ready check, including an app that answers only on its own hostname and one that answers only on 127.0.0.1:<port>. The MODE variable picks each service’s behaviour, so devlanes.yaml is the file to read.

  • devlanes, with devlanes setup run once
  • Node 22 or later
  • curl on PATH, for the ready.cmd check of own-host-cmd
Terminal window
cd basics-ready-checks
devlanes start

devlanes start --no-ui prints the start as text:

example-ready-checks@0 · main
✓ services 8 of 8 ready
✓ index https://example-ready-checks.localhost
✓ http-check https://http-check.example-ready-checks.localhost
✓ tcp-check https://tcp-check.example-ready-checks.localhost
✓ log-check https://log-check.example-ready-checks.localhost
✓ own-host https://own-host.example-ready-checks.localhost
✓ own-host-cmd https://own-host-cmd.example-ready-checks.localhost
✓ legacy-host https://legacy-host.example-ready-checks.localhost
✓ slow-start https://slow-start.example-ready-checks.localhost

Open https://example-ready-checks.localhost. The page shows lane 0 of example-ready-checks and links to every service with the check it uses. Each service’s page shows the Host header the app received: own-host.example-ready-checks.localhost on own-host, 127.0.0.1:<port> on legacy-host.

The first start of a lane runs the install task (npm install), because a new worktree has no node_modules. Then devlanes starts every service with npm run dev from package.json (the node template), sets MODE from the service’s env, and waits for each one’s check:

  • index at example-ready-checks.localhost: ready.http on /healthz. Its links come from services.<name>.public_url.
  • http-check: GET /healthz on its port must answer 2xx within 15 s.
  • tcp-check: ready as soon as its port accepts a connection, whatever the app would answer.
  • log-check: waits 3 s, then listens and prints log-check listening on http://127.0.0.1:<port>, which ready.log matches.
  • own-host: answers 400 to any Host but own-host.example-ready-checks.localhost (ALLOWED_HOST), the way Django’s ALLOWED_HOSTS does. The check sends Host: 127.0.0.1:<port> by default, so ready.http.host sends ${{ self.hosts[0] }} instead.
  • own-host-cmd: the same app, checked by ready.cmd with curl -fsS -H "Host: ..." http://127.0.0.1:<port>/healthz.
  • legacy-host: answers 400 to any Host but 127.0.0.1:<port>. host_header: upstream makes the proxy send that address instead of the hostname, and the check sends it by default.
  • slow-start: sleeps 8 s before it listens, so it shows starting in devlanes status until then.

On Windows, add --ssl-revoke-best-effort to the curl commands.

  • Start a second lane: git worktree add ../examples-checkout -b feat/checkout, then cd ../examples-checkout/basics-ready-checks && devlanes start. The new worktree is lane 1 at https://example-ready-checks1.localhost, with http-check.example-ready-checks1.localhost and the rest, and curl https://example-ready-checks1.localhost/lane answers "lane":1. devlanes lane new --name example-ready-checks-review --start in this folder gives the same lane 1 without a worktree.

  • Catch a service while it starts: devlanes restart slow-start --no-ui --timeout 2s stops waiting after 2 seconds and exits 124:

    example-ready-checks@0 · main
    ✗ services 0 of 1 ready
    starting slow-start
    ! timed out before every unit was ready
  • Right after that, devlanes debug why slow-start prints starting; waiting for its readiness check (devlanes wait example-ready-checks@0:slow-start).

  • devlanes wait slow-start returns ready example-ready-checks@0:slow-start once the server listens.

  • Break a check: change http-check’s path: /healthz to path: /missing in devlanes.yaml and run devlanes reload --no-ui. After the 15 s timeout it exits 1:

    example-ready-checks@0 · main
    ✗ services 0 of 1 ready
    ✗ http-check wasn't ready in time; GET /missing (Host: 127.0.0.1:20520) answered 404 http-check listening on http://127.0.0.1:20520
    hint: use a `ready.http.path` that answers 2xx, set `ready.http.host` if the app routes by hostname, or set `ready.http.status: 404`

    The process keeps running, but https://http-check.example-ready-checks.localhost now gets the proxy’s DL203 Service failed page (503), and devlanes debug why http-check prints the same reason. Put /healthz back and devlanes reload --no-ui brings it back to ready.

  • Drop the Host rewrite: delete host_header: upstream from legacy-host and save. The proxy applies the route change by itself (devlanes reload reports nothing to reload), and curl https://legacy-host.example-ready-checks.localhost/ answers 400 with invalid host legacy-host.example-ready-checks.localhost: this app answers only on 127.0.0.1:<port>. Put the line back.

  • devlanes lane clean 0 --yes stops lane 0 and deletes its data and logs. Run it with 1 for the second lane.

  • devlanes.yaml: the install task and the eight services with their MODE and ready check, with a comment wherever a key is the point.
  • src/modes/: one file per behaviour. log.ts and slow-start.ts delay the listen, own-host.ts and legacy-host.ts refuse other Host headers.
  • src/index.ts: picks the mode from MODE and starts the server.
  • src/host-guard.ts: the middleware that answers 400 to another Host.