Skip to content

Dependency kinds

Every edge between two services is declared, in depends_on. An edge has one of two kinds, and the kind is the whole of what fghj does with it.

services:
api:
build: .
depends_on:
db: {condition: service_healthy} # required: true is the default
migrate: {condition: service_completed_successfully}
hooks: {required: false} # called at runtime, not at boot
required: true (default): needed to startrequired: false: needed at runtime
Graphsolid linedashed line
Which runs start itevery run that starts the dependent (the required closure)only a run whose flows list it
Orderthe dependency starts firstnone
Waitingthe dependent waits until it’s ready: healthy if it has a healthcheck, exited 0 if it’s a task, running otherwisenone
It fails to startthe dependent isn’t started: “blocked by db”, transitivelynothing
It’s recreatedthe dependent is restarted after itnothing
It’s stoppedthe dependent is stopped firstnothing
Starting the dependent alonealso starts it if it isn’t runningnothing
A cycleblocking: it can never startcan’t happen: never part of a cycle
Not in the runcan’t happenadvisory before start: “api needs hooks at runtime, but this run doesn’t start it”

“Required” answers one question: will the dependent crash, or start broken, if this isn’t there when it boots? A database the connection pool opens at startup, or an S3 bucket a service downloads its model from, is required. A webhook receiver nobody calls until a user clicks something isn’t.

${FGHJ_SERVICE_FQDN:billing/api} expands to a hostname. It isn’t an edge, and doesn’t make one: a service may as well hardcode https://api.billing.fghj.internal, and fghj can’t see that. Deriving edges from templates would make the graph depend on how an address happened to be spelled. The UI couldn’t draw a dependency the user never declared, either.

A template still has to name an existing service, so that it can expand. Any service in the workspace may be named, including another repo’s, as alias/name.

So “uses” edges are gone. The sidecar can still report a lookup of a service that isn’t running. That’s a runtime observation, not part of the graph.

A task is a service that is expected to exit. It is one when either:

  • something requires it with condition: service_completed_successfully, or
  • it declares run: on_start or run: once.

The second rule closes the old gap. Before, a seed listed only in a flow had nothing waiting on it, so its clean exit read as a crash.

condition: service_completed_successfully together with required: false is a blocking error. “Must have finished” is a start-time statement, so it can’t hold for a dependency the service doesn’t need in order to start. A seed only one journey needs has run: on_start, its own depends_on (on the database it seeds), and is listed in that journey’s flow.

Other conditions on a required: false edge are ignored, with an advisory. Nothing waits on a runtime dependency.

Each node used to wait on its own healthcheck, whoever needed it. Now a node is waited on only if something in the run requires it. A database that only runtime dependents call no longer delays the rest of the run. Tasks are always waited on, because their exit code is their result.

The health wait stays best-effort, as described in Concurrency model: a healthcheck that never passes within the budget is reported, and the dependents start anyway. A failed task, or a container that can’t be created, does fail, and its required dependents are blocked.

A whole-flow start used to stop at the first failed node. Now:

  • A failed node’s required dependents, and theirs in turn, are skipped. Each one gets the event “blocked: db failed”.
  • Everything else keeps starting. A broken worker doesn’t stop an unrelated frontend.
  • The run then reports an error naming what failed and what was blocked. Whatever came up stays up and visible.

Only failing to create the environment’s network or sidecar stops the start outright, because nothing can start without them.

  • Recreating a node restarts the running services that require it, after it is ready again. This applies to a top-up recreating it for config drift, and to the Drawer’s Start button. A service holding a pool against the old database would otherwise keep failing until someone noticed. It’s a docker restart, not a recreate: the same container, image and code, so resetting a database doesn’t ship whatever the checkout behind its dependents holds now. A restarted service restarts what requires it in turn, and the graph shows each one as restarting while it goes. A re-run task doesn’t restart anything: on_start tasks re-run on every top-up, and bouncing the whole environment each time would make top-ups useless.
  • Starting one node also starts the required dependencies it has that aren’t running.
  • Stopping a node stops the running services that require it, first. They’d fail anyway, and a stopped required dependency they don’t know about is harder to read than a stopped service.

Flows say what to start; edges say how starting goes. They meet in one place: the required closure. A flow lists services, the run adds everything those need to start, and required: false dependencies stay out unless a flow lists them too. A flow never adds an edge, and an edge never adds a flow.