Section and profile operations over a context:
{:engine IComposeEngine :runner IProgramRunner ; optional: host programs :settings Settings :state (atom {:active {id Active} :current id-or-nil}) :now (fn [] epoch-ms) :save! (fn [persisted-state] Result)} ; optional
A subject is a Profile: a configured preset (lookup) or a section resolved
from a target against the configured compose projects (resolve-target).
Every operation answers a Result (reap! and adopt! answer reports). The
active map changes only after the engine confirmed the action.
A section also holds the host programs paired with its services: they start once its containers are up and stop when the last section holding them is released. A program that fails to start is reported, never fatal.
Section and profile operations over a context:
{:engine IComposeEngine
:runner IProgramRunner ; optional: host programs
:settings Settings
:state (atom {:active {id Active} :current id-or-nil})
:now (fn [] epoch-ms)
:save! (fn [persisted-state] Result)} ; optional
A subject is a Profile: a configured preset (`lookup`) or a section resolved
from a target against the configured compose projects (`resolve-target`).
Every operation answers a Result (reap! and adopt! answer reports). The
active map changes only after the engine confirmed the action.
A section also holds the host programs paired with its services: they start
once its containers are up and stop when the last section holding them is
released. A program that fails to start is reported, never fatal.(adopt! ctx)Take charge, with a fresh idle clock, of what runs without an owner:
configured presets that are running, and the running services of configured
compose projects that no active profile accounts for (as section
<project>/adopted, needing their depends_on closure). Configured projects
that share one compose project adopt each stray once, in id order. Answers
the adopted ids.
Take charge, with a fresh idle clock, of what runs without an owner: configured presets that are running, and the running services of configured compose projects that no active profile accounts for (as section `<project>/adopted`, needing their depends_on closure). Configured projects that share one compose project adopt each stray once, in id order. Answers the adopted ids.
(config-health ctx){project-id {:compose-project name :ok? bool :error ..}}: whether docker compose config accepts each configured project as configured now (its
files and env; references rendered, never read). A missing required
variable, a bad file or an absent overlay shows here.
{project-id {:compose-project name :ok? bool :error ..}}: whether `docker
compose config` accepts each configured project as configured now (its
files and env; references rendered, never read). A missing required
variable, a bad file or an absent overlay shows here.(down-profile! ctx p action)Take p down with action (:down removes containers, :stop keeps them;
volumes are never touched). Services and programs another active profile
needs stay up.
Take `p` down with `action` (:down removes containers, :stop keeps them; volumes are never touched). Services and programs another active profile needs stay up.
(logs-profile ctx p tail)Result<{:out}>: the last tail log lines of p; touches it when active.
Result<{:out}>: the last `tail` log lines of `p`; touches it when active.
(lookup ctx id)Result<Profile> for id: the configured preset, else the snapshot an active
entry (a preset or a section) ran with.
Result<Profile> for `id`: the configured preset, else the snapshot an active entry (a preset or a section) ran with.
(merge-adopted old e)Active entry old with the newly adopted strays of entry e folded in;
e itself when there is no old. Pure.
The :profile snapshot's :profile/services follows the merged
:services: logs and ps address a section through that snapshot, so a
stale one would keep naming the subset adopted first. An entry without
:needs needs exactly its :services, so a merged :needs starts from
whichever of the two old carries.
Active entry `old` with the newly adopted strays of entry `e` folded in; `e` itself when there is no `old`. Pure. The `:profile` snapshot's `:profile/services` follows the merged `:services`: logs and ps address a section through that snapshot, so a stale one would keep naming the subset adopted first. An entry without `:needs` needs exactly its `:services`, so a merged `:needs` starts from whichever of the two `old` carries.
(program-row ctx run)What is known of started program run right now: alive, and whether its
nREPL answers. A port the program chose itself is read from its .nrepl-port.
One whose process is gone is :status :exited, with its exit code when the
runner kept it and the last lines of its log.
What is known of started program `run` right now: alive, and whether its nREPL answers. A port the program chose itself is read from its .nrepl-port. One whose process is gone is :status :exited, with its exit code when the runner kept it and the last lines of its log.
(programs ctx)Result<[row]>: every program the configured projects declare, as it would start (kind, command, nREPL port, the services it is paired with) and, when it runs, its pid and whether its nREPL answers.
Result<[row]>: every program the configured projects declare, as it would start (kind, command, nREPL port, the services it is paired with) and, when it runs, its pid and whether its nREPL answers.
(projects ctx)Result<[project]>: every compose project on the host, managed ones marked. :label-files are the files docker recorded when its containers were created. For a project a configured one runs as, :configured lists those with their :files as configured now, and :stale-files the label files no configured project of that name uses (a different checkout, an overlay since dropped); :files-match? false says the running containers were not created from the files configured now.
Result<[project]>: every compose project on the host, managed ones marked. :label-files are the files docker recorded when its containers were created. For a project a configured one runs as, :configured lists those with their :files as configured now, and :stale-files the label files no configured project of that name uses (a different checkout, an overlay since dropped); :files-match? false says the running containers were not created from the files configured now.
(ps-profile ctx p)Result<{:profile :needs :running}> for p; touches it when active.
Result<{:profile :needs :running}> for `p`; touches it when active.
(reap! ctx)One reaper pass: reconcile, then release every idle profile.
One reaper pass: reconcile, then release every idle profile.
(rebase-sections! ctx old-projects)After the configured projects changed from old-projects to the ones in
ctx's settings, re-base the snapshot of every active section of a changed
project on its project as configured now, so a release, ps or logs by id
runs with the new files and env. Answers {:rebased [id] :kept [{:id :reason}]};
a section whose project left the config keeps the snapshot it ran with.
After the configured projects changed from `old-projects` to the ones in
`ctx`'s settings, re-base the snapshot of every active section of a changed
project on its project as configured now, so a release, ps or logs by id
runs with the new files and env. Answers {:rebased [id] :kept [{:id :reason}]};
a section whose project left the config keeps the snapshot it ran with.(reconcile! ctx)Forget active profiles none of whose services still run (taken down outside the addon), stopping the programs they alone hold. Answers the forgotten ids.
Forget active profiles none of whose services still run (taken down outside the addon), stopping the programs they alone hold. Answers the forgotten ids.
(required-closure graph roots running)What roots need under the depends_on edges of graph
({service {dep {:required? bool}}}): {:start [service]} follows only the
required edges (an edge without :required? is required); {:needs [service]}
adds the required: false dependencies met on the way that are already in
running, together with everything those require in turn (and the running
optional ones they meet), so release never strands a kept service. What
:needs adds is waited on and kept, never started. Pure.
What `roots` need under the depends_on edges of `graph`
({service {dep {:required? bool}}}): {:start [service]} follows only the
required edges (an edge without :required? is required); {:needs [service]}
adds the `required: false` dependencies met on the way that are already in
`running`, together with everything those require in turn (and the running
optional ones they meet), so release never strands a kept service. What
:needs adds is waited on and kept, never started. Pure.(resolve-target ctx target-str)(resolve-target ctx target-str env)Result<Profile>: the section running exactly what target-str names
(services or native compose profiles, see promote.target/parse), in the
first configured project that defines all of them. Its services close over
the compose file's depends_on when brought up. env, the call's own, is
given to the compose queries that resolve the target, so a variable the
YAML requires can come from the call.
Result<Profile>: the section running exactly what `target-str` names (services or native compose profiles, see `promote.target/parse`), in the first configured project that defines all of them. Its services close over the compose file's depends_on when brought up. `env`, the call's own, is given to the compose queries that resolve the target, so a variable the YAML requires can come from the call.
(runner ctx)The program runner, nil when the context has none or programs are off.
The program runner, nil when the context has none or programs are off.
(status ctx)Every configured preset and every active section, with activity, reaper countdown and the host programs it holds. Up front, :ok? and :config say whether compose accepts each configured project now; a row of a project it rejects carries :config-ok? false, and an active one :reap-blocked? true, since no compose call on that project, the reaper's included, can run.
Every configured preset and every active section, with activity, reaper countdown and the host programs it holds. Up front, :ok? and :config say whether compose accepts each configured project now; a row of a project it rejects carries :config-ok? false, and an active one :reap-blocked? true, since no compose call on that project, the reaper's included, can run.
(subject ctx {:keys [target id env]})Result<Profile> for a tool call: target resolves a section, else id
looks up a preset or an active section. A target is resolved against the
config as it is now, so an active section picks up what its project gained
since (a program, a TTL); the snapshot it ran with answers only when the
target no longer resolves. env is the call's env, used by the compose
queries that resolve the target.
Result<Profile> for a tool call: `target` resolves a section, else `id` looks up a preset or an active section. A target is resolved against the config as it is now, so an active section picks up what its project gained since (a program, a TTL); the snapshot it ran with answers only when the target no longer resolves. `env` is the call's env, used by the compose queries that resolve the target.
(switch-profile! ctx p)Make p current: release what only the previous current profile needs, then
bring p up. Shared services and the programs p wants stay up throughout.
Optional (required: false) dependencies are treated as in up-profile!.
Make `p` current: release what only the previous current profile needs, then bring `p` up. Shared services and the programs `p` wants stay up throughout. Optional (`required: false`) dependencies are treated as in `up-profile!`.
(targets ctx)Result<[{:project :services :profiles}]>: what can be named as a target in each configured compose project.
Result<[{:project :services :profiles}]>: what can be named as a target in each
configured compose project.(touch! ctx id)Reset the idle clock of active profile id.
Reset the idle clock of active profile `id`.
(touch-all! ctx project)Reset the idle clock of every active profile, or only those of compose
project project (the configured project id is accepted too).
Reset the idle clock of every active profile, or only those of compose project `project` (the configured project id is accepted too).
(unknown-service-name res)The service compose named in a no such service: <name> refusal, nil for
any other result.
The service compose named in a `no such service: <name>` refusal, nil for any other result.
(up-profile! ctx p)Bring p up alongside whatever is active. Becomes current when nothing is.
A depends_on entry marked required: false is neither built nor started;
it is only needed when already running.
Bring `p` up alongside whatever is active. Becomes current when nothing is. A depends_on entry marked `required: false` is neither built nor started; it is only needed when already running.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |