Writing a Source
A provider is configuration. Every provider comb ships is a file, defaults/<name>.toml, written the way a user writes one, and any line of it can be overridden in config.toml or conf.d/. There is no other kind: to add a provider, write a Source. What jinja cannot do comes from a plugin (§8).
1. The model
Three layers
- Provider — a namespace, named by the key used in
comb get <name>.<field>. It holds one or more Sources. Its table is[daemon.providers.<name>]. - Source — one schedule, one lifecycle, one set of fields: the unit of execution. Its table is
[daemon.providers.<name>.sources.<source>]. - Field — a value. Belongs to exactly one Source, unless the provider's
resultmerges them in an order of its own.
A Source is up to four lines of jinja:
| line | says | sees |
|---|---|---|
root | the directory an instance answers for (none: one instance, at ~) | env, _ |
data | the body, rendered with the root as its working directory, on a blocking thread, so it may run a command | env, comb, sources, daemon, _, each provider by plain name (its stored value, as comb.<p>) |
result | the fields, each one line over data (result.<field>), or one line whose object is the whole node | data, _ |
return | the schedule: poll, watch, failback, budget, timeout, nearest |
A failing data or result line is a failure: nothing is written and the scheduler counts it toward failback. A result that renders nothing is a result: the Source has nothing to report here, and it replaces what the instance stored before, so a Source never leaves stale values behind by reporting nothing. A line that renders none leaves its field absent: null means absent, never "".
root says which instance answers for a directory. A Source whose records depend on a project (git, mise, direnv, asdf, terraform, python) walks up to its marker and renders that directory, or nothing when it finds none; no root line is a Source with no root: one instance, at ~. A root equal to $HOME is the instance at ~, and is not the same as finding nothing (see below). A line that fails is a root that could not be worked out, and it fails the read: it is never answered from the instance at ~.
A Source's instances combine in one of two ways, set by | nearest on its return line:
- Cascade (the default). A read of
p.<key>from directoryDasks the nearest instance first (R1 = root(D)). If the key is missing there, it asks the parent of that root (root(parent(R1))), and so on, ending at the instance at~and never past it; finding no root continues to~. A namespace read takes every instance on the way and merges them, the nearer winning per leaf. That is howasdfis a single Source: inside a projectasdf.nodeis the project's.tool-versions, andasdf.go, which only~/.tool-versionssets, is found at~. - Nearest. The instance
root(D)finds answers alone. A key it lacks is absent: no outer instance fills in, and the walk does not move up. If no root is found there is no instance at all: nothing runs and nothing is read, and~is not a fallback. Finding$HOMEitself is an instance (the one at~). That is howgitworks: inside a nested repositorygit.branch_parentis the inner repository's or absent, never the superproject's, and in a directory outside any repository there are no git values.
Choose nearest when the instance is the one you are in (git, direnv, a Python venv, a terraform root); keep cascade when instances are layers of one setting (mise, asdf's .tool-versions). A Source with no root has its one instance at ~ either way. Records written by put, and the config: seeds, merge up the directory chain whatever a Source does.
An instance's lifecycle key is (provider, root, source), with no root for the instance at ~. Its schedule registers when the instance is first requested, never at load: relative watch paths are watched under the instance's root, and absolute ones whatever the root. A relative watch on a Source with no root is a load error: it has no directory to resolve it against.
2. Writing one
2.1 Decide on Sources
Answer these for each group of fields; a group that differs is another Source, so a cheap field need not run with a dear one:
- How do these fields change? (a file, a timer, or both)
- Does it have a root? (none: one instance, at
~; a root: one instance per project root. Then: do they cascade, or does the nearest answer alone?) - What can it read rather than run?
| Signal | Root | return |
|---|---|---|
| File changes only | with or without | watch(...) |
| Timer only | with or without | poll(...) |
| File changes + safety timer | with or without | watch(...) | poll(...) |
| A file outside any project | none | watch('/absolute/path') |
A Source with watch and no poll runs on first demand and again only when a watched path changes. Like every Source it decays once nothing reads it (its Active window is the default poll lifespan, 60 s × 12) and its watches are dropped; the next read runs it again. There is no spelling for "run once": the shipped hostname, user and uname poll every 10 minutes, 10 minutes and hour while read, so a renamed machine is seen.
2.2 Write the file
In ~/.config/beachcomber/conf.d/docker.toml, say. The current Docker context, read from Docker's own file with no process:
[daemon.providers.dockercontext.sources.config]
# No root: one instance, at ~, so only absolute paths can be watched.
data = "{{ '~/.docker/config.json' | read | fromjson }}"
result.name = "{{ (data.currentContext or 'default') if data is not none }}"
return = "{{ result | watch('~/.docker/config.json') | failback('60s', 3) }}"
A missing file reads as undefined and every line over it renders nothing, so with no Docker config the Source reports nothing, which is not a failure.
2.3 Use it
comb get dockercontext.name
comb check config # lints every line, and names the file that set it
An edit under providers reloads in place. Read a shipped file to see how one is written: defaults/python.toml is root and data with some logic, defaults/hostname.toml one plugin call, defaults/git.toml all of it.
2.4 Worked example: git
git is defaults/git.toml, five Sources with different strategies, sharing one root line in their _ prototype. All get their data from the compiled-in git plugin (§8):
git.head → watch .git/HEAD, `plugin('git', 'head', root)`, no subprocess
fields: branch, detached
git.refs → watch what the refs, the stash and an operation in progress live in, `plugin('git', 'refs', root)`
fields: commit, tag, state, state_step, state_total,
stash, last_commit_timestamp, commit_summary, push_ahead, push_behind
git.diff → poll 30s, `plugin('git', 'diff', root)`
fields: lines_added, lines_removed, lines_staged_added, lines_staged_removed
git.branches → watch the refs, `plugin('git', 'branches', root)`
git.lineage → watch the refs, `plugin('git', 'lineage', root)`
fields: branch_parent, lines_added_parent, lines_removed_parent,
branch_default, lines_added_default, lines_removed_default
git.status → watch the index and the refs + poll 60s, `plugin('git', 'status', root)`
fields: upstream, ahead, behind, staged, unstaged, untracked, conflicted, dirty
This decomposition lets a read wait for only what it asked for, and an event run only what it can have changed: git add runs status and diff, and a read of git.branch waits for neither. Each git status says the upstream and the counts together, so one Source holds both and an event runs it once.
Consumers use comb get git.branch .: the registry's field → source map routes the query to the head Source.
3. Data providers and template-backed namespaces
Some providers serve raw data sets that clients consume through templates. The pattern separates two concerns:
- Data provider — a daemon provider that caches all variants of an env-selected source. Its name is descriptive of the data it holds (e.g.
aws_profiles,gcloud_configs). Each field is a variant keyed by name, each value an object of per-variant fields. The daemon caches the whole set regardless of any shell selector. - Consumer namespace — a
[client.providers.<ns>] template.*table, shipped as a manageddefaults/<ns>.tomlfile, whose templates present the user-facing surface (e.g.aws,gcloud). These referencecomb.<data_provider>[<selector>].<field>to index the data provider by the active selector; the daemon serves the templates as data and the client renders them with the caller's environment.
# data provider: daemon-side, env-blind
aws_profiles.default → Object{ region: "us-east-1" }
aws_profiles.staging → Object{ region: "us-west-2" }
# consumer namespace: templates in defaults/aws.toml, rendered by the client
[client.providers.aws]
template.profile = "{{ env.AWS_PROFILE or env.AWS_VAULT or env.AWS_DEFAULT_PROFILE or 'default' }}"
template.region = "{{ env.AWS_REGION or env.AWS_DEFAULT_REGION
or comb.aws_profiles[ env.AWS_PROFILE or env.AWS_VAULT
or env.AWS_DEFAULT_PROFILE or 'default' ].region }}"
comb get aws_profiles returns the raw dump. comb get aws renders the consumer templates. The daemon never reads $AWS_PROFILE.
The comb.* reference convention
Inside value expressions, comb.<provider>.<field> addresses the raw cached value, bypassing any field expression. This is distinct from <provider>.<field>, which evaluates that field's value expression (recursive, cycle-detected).
This matters when a template needs to override a same-named cached value — a template at a cached field's path wins on read:
# defaults/terraform.toml: the template at terraform.workspace overrides the cached workspace without a cycle
[client.providers.terraform]
template.workspace = "{{ env.TF_WORKSPACE or comb.terraform.workspace }}"
comb.terraform.workspace is the stored value; terraform.workspace is the resolved field. No self-reference, no rename needed.
4. What a read checks
A read answers from a Source's stored record only while the record is valid: within its lifetime (its poll), and with its stat inputs as its run found them. A run stamps its inputs immediately before it reads them, and a read stats them again (one stat(2) per input, on the request task) before it answers. If one changed, the record's instance runs again, and the read waits up to the Source's budget for it. A change while the run executes fails the next read's check, so it costs one run more, never a stale answer.
A record's inputs are the paths its watch(...) declares (each relative one joined to the instance's root, each absolute one as written, and at the ~ instance each single-component one under $HOME) and the files its data and result lines read. A path the lines compute (a linked worktree's HEAD, a file named by env.AWS_CONFIG_FILE, a hash) is checked as a constant one is: nothing needs declaring. A Source that only polls and reads no file has none, has no validity, and is checked for its lifetime alone.
| item | what it reads |
|---|---|
p | read, p | stat, p | realpath | the path |
lup(name) | every path its walk probed, each for its presence: <dir>/<name> from the instance's directory up to the hit (to the boundary when there is none, or with all); with git=true, each <dir>/.git it read to find the repository's root. A miss is read too: a name made nearer is a change. A hit changes when it goes, or becomes another kind of thing: not when an entry comes and goes in a directory it found. lup('x') | read checks the file's contents as well, by the read |
pattern | glob | each directory it listed, as a node (an entry made, removed or renamed in it is a change), and each literal component it found missing or ended on. A directory passed through on the way is not: what the glob read below it is |
[daemon.providers.flag.sources.s]
root = "{{ lup('.flagroot') | dirname }}"
# checked: every state.json probe, and the one read
data = "{{ lup('state.json') | read }}"
result.v = "{{ data }}"
# no watch() needed for a read to see a rewrite
return = "{{ result | poll('10m') }}"
-
The first 64 files a run reads are checked; a run that reads more logs once per Source (
flag.s: 150 files read; the first 64 are checked on read), and a change to a later file waits for the watch or the poll. -
What an
execchild or a plugin library reads is not the lines' reading: a Source that shells out declares what its command reads withwatch(...), orstats it in its own line, or lives with its poll. A plugin compiled into comb notes what it reads itself (§8). -
The
rootline's walk is not a record's input. The root a directory finds is kept per directory (see "How config Sources work"). -
A
watch(...)path is still what the daemon watches in the background, to warm a record before anyone reads it; what the lines read is checked on a read only. -
A stamp is
dev,ino, size, mtime in nanoseconds and kind, following symlinks, plus the link's own inode and mtime for a symlink. An absent path has a stamp of its own, so creating an input is a change. A path that cannot be stat'd (EACCES) is unknown, and keeps the record. -
A directory is an input as a node, by its own mtime: an entry created, removed or renamed in it is a change (git writes
HEADandindexby renaming a lockfile in.git/); a change deeper in the tree is left to the watch. -
A network or FUSE mount (NFS, SMB, AFP, FUSE, or one not known) is never stat'd on a read: a stat there can hang and its attribute cache can lie. A record with an input there is checked for its lifetime only, and the daemon logs one warning per mount.
-
A racy stamp, taken within the mount's timestamp resolution of the file's mtime (and at least 10 ms), cannot see a same-size write in place in that window. The first read once the window has closed counts the record invalid and runs it again.
Name only files the run reads: an input that changes when the value does not costs a run for nothing. A directory is the blunt case: watch('.git') makes .git an input, whose mtime moves whenever a git command makes a lockfile there, so the next read runs the Source again. Name what the run reads instead: watch('.git/HEAD', '.git/refs') matches by whole path components, so .git/HEAD.lock wakes nothing and .git/refs/heads/main wakes it, and only .git/HEAD and the .git/refs directory itself are stat'd on a read.
A read that finds an input changed while a run is in flight that stamped it before the change does not wait for that run: one begins at once in its place, and those waiting on it wait on the new one. What the replaced run produces is not written.
The record's validity hash is shown as hash in its :cache answer
(comb get git:cache.branch), 16 lowercase hex digits, written by the daemon
alone.
5. The schedule
A Source's return line maps onto one of three strategies:
| Signals available | Line |
|---|---|
| Timer only, no watchable file | poll(interval, count) |
| Filesystem events only, no poll needed | watch(paths...) |
| Filesystem events + safety backstop timer | watch(paths...) | poll(interval, count) |
poll(interval, count) runs the Source on a timer; the entry stays Active for count polls (interval × count) after its last read. Use it when there is no file that reliably reflects state changes.
return = "{{ result | poll('30s', 4) }}" # battery level: no file to watch reliably
watch(paths...) runs the Source when a path changes. A relative path is under the instance's root (Sources with a root only). An absolute or ~ one is watched directly, whatever the root. Its arguments are constants: a path a line computes is checked on a read (§4), not watched. A . covers the tree below the instance's root (Sources with a root only), and each !name leaves out every path with that component, so watch('.', '!.git') is a repository's working tree. A change there runs nothing: it makes the record invalid for the next read, which runs the Source, so a build's output no read asks about costs nothing, and the Source does not have to read anything a stat could see. While the instance is not Active nothing watches its tree, and a read of it always runs the Source.
# those paths and anything below them, per repository
return = "{{ result | watch('.git/HEAD', '.git/refs') | nearest }}"
There is no automatic poll fallback for a watch. If a watch cannot register at runtime, the scheduler logs a warning and the Source serves its last cached value. If a backstop is needed, add a poll, as git.status does for what does not touch a watchable file:
return = '''{{ result
| watch('.git/index', '.git/refs')
| poll('60s', 2)
| failback('30s', 3)
| nearest }}'''
A return names what it wants, and the line is whole: nearest too, so a retune of a nearest Source says | nearest again or the Source cascades. A failback, budget or timeout it does not name is the engine's (failback('1s', 3), [daemon] budget, [daemon] timeout), and a Source with no return takes the nearest _'s (the abstract Source's poll('60s', 12) | failback('1s', 3) ships in defaults/00-comb.toml). | super extends the _ line instead of replacing it.
A shipped Source is retuned by setting that line in a later layer, and any other line of it the same way:
[daemon.providers.git.sources.status]
return = '''{{ result
| watch('.git/index')
| poll('120s', 6)
| failback('2s', 5)
| nearest }}'''
Three things a Source relies on beyond its own table:
- Prototypes. A table named
_([daemon.providers.<p>.sources._]for one provider's Sources,[daemon.providers._.sources._]for all) holds defaults. A Source's ownroot,data,resultorreturnline wins whole; an absent line takes the nearest_'s;| superon areturnextends the_line instead of replacing it. The abstract Source (poll('60s', 12) | failback('1s', 3)) ships indefaults/00-comb.toml. - The engine.
datacan callexec,url,plugin,read,stat,lup,fromjson,fromini,merge,mapover objects,pluck,dirnameandtojson(the table is in the configuration reference). Anexecstring is run bysh -c, so$BARin it is invisible to the engine, and to a futurecache()hash of the line: preferexec('cmd ' ~ env.bar). - Calling a Source.
sources.<s>()reads a sibling's stored record anddaemon.providers.<q>.sources.<s>()any provider's. A Source with nothing stored is run inline, once, by the read or refresh that needs it (a cold call); a ring of Sources calling each other is a load error; a called Source stays warm and decays with its callers.
A provider is switched off with [daemon.providers.<p>] enabled = false: no Source of it runs, a read is a miss with no template half, and puts under it stay readable. An edit under providers reloads in place; only the bare [daemon] and [client] keys restart the daemon. Decay depth is data ([daemon.providers._.cache._] decay = 4 ships), settable per provider or by put.
The root a directory finds is kept: a root line (it may run a command) is rendered once per directory rather than per request. The kept answer carries the stamps of the directories from the one asked about up to the root it found (up to $HOME, or / outside it, when it found none), taken before the line rendered, and a read checks them, one stat per directory: creating or removing a marker in one moves that directory's mtime, so the next read renders the root again. A marker created below a kept root, or the marker at it removed, is seen at once, and so is one that gives a | nearest Source that found nothing its instance. A change the stamps cannot see (what a command in the line reads, a file rewritten in place) is seen when the instance the root named is evicted (it has gone cold and decayed away), which drops the kept answer too. A root line that fails is answered with the same error for a few seconds rather than re-run on every request.
Cache lifecycle
The full decay model (state machine, step durations, reinstatement rules) is described in docs/architecture.md §5. A Source's watches exist only while its instance is Active: decay drops them and the read that reinstates the instance registers them again, so a decaying record is checked by stat (§4) rather than by an event.
Decay depth is data. After the Active window an entry steps through its decay steps (4 unless told otherwise; step n lasts lifespan × 2^n) and is then evicted. A depth is put like any value: comb put '<provider>:cache._.decay' 6 for one provider, comb put '*:cache._.decay' 3 for every provider, with --path to scope it to a directory and below; the nearest prototype wins, and a lifecycle fixes its depth when it registers. comb get <provider>:cache.<field> shows the poll, watch and decay an entry registered with. There is no per-source keep-alive duration: fsevent_lifespan was removed, and a watch-only Source's Active window is the default poll lifespan (60 s × 12).
6. Performance
A Source runs on tokio's blocking thread pool. A slow one delays cache freshness but does not block the scheduler loop. Still, keep them fast. The tier list from docs/performance.md:
| Tier | Time | Providers | Method |
|---|---|---|---|
| A file's lines | about 90-170 µs | hostname, user, load, uptime, gcloud_configs | The engine, the lines, a sys call or a file read; no process |
| One process | 3-12 ms | network, battery | One spawn, inside sys |
| Commands | 10-50 ms | mise, direnv (with binary), Sources that call exec() | Multiple spawns or an interpreted CLI |
| A repository's worth | 16-64 ms per Source | git's status, diff, lineage, refs | One git process per fact, through the plugin; head none |
Rule 1: Never run a process when you can read a file.
A process costs 2-6 ms at least; a file read costs microseconds. Before reaching for exec(), ask: does this tool write its state to a file I can parse?
# Bad: a process for a value that is on disk
data = "{{ exec('gcloud config get-value project') }}"
# Good: read the file the tool reads
data = "{{ '~/.config/gcloud/configurations/config_default' | read | fromini }}"
Real examples from docs/performance.md:
gcloud: reading~/.config/gcloud/propertiesinstead of spawning the Python CLI — 500ms to 1µs (~500,000x)gitstash: reading.git/logs/refs/stashinstead ofgit stash list— 5ms to 1µsgit'shead: reading<gitdir>/HEADin the plugin, sogit.branchcosts no process at all
Rule 2: If you must run a process, run as few as you can. git's status Source runs one (git status), which is why it is its own Source: a read of git.dirty does not pay for git.lines_added.
Rule 3: What polls often must be fast. A Source polling every 5 seconds and taking 50 ms per run consumes 1% of a blocking thread slot continuously. Match the interval to the cost:
- Microseconds: can poll every 5-10s safely
- Millisecond: 30s minimum
- Slow (>10 ms): 60s minimum, or
watchinstead
Rule 4: A plugin symbol must be reentrant, or the library is locked. A library on the search path is entered by one thread at a time. A compiled-in plugin takes no lock, so its symbols keep nothing between calls.
See docs/performance.md for the full performance profile, benchmark commands, and the regression checklist.
7. Testing
A shipped file is tested as a user reads it: tests/suite/shipped/<namespace>.rs, through tests/suite/shipped/mod.rs. scenario() is a daemon in the test's process over a temp HOME and XDG_CONFIG_HOME, which writes the managed defaults as comb daemon does; served(vars, conf) is the same shipped registry behind a server with no scheduler, so a read that answers a changed file found the change itself; and a Source can be run straight, with_shipped_defaults().source(p, s).execute(dir), which needs no daemon and costs no socket.
#[test]
fn terraform_answers_nothing_outside_a_project() {
let s = scenario();
assert_eq!(s.get("terraform.workspace", &s.project), None);
}
Set up what the Source reads in the scenario's directory (a repository with GitRepoFixture, a .tool-versions, a pyvenv.cfg), read it, and assert on the JSON. Where a value depends on the machine (the hostname, the load), assert the shape and the type. Where a tool may be absent, put a stand-in on the isolated PATH (TestDaemon::spawn_with_tools).
What a compiled-in plugin does is unit tested beside it (src/plugin/): its parsers over canned output, through a seam like GitExecutor, cost no process. A test of the daemon that needs a Source of its own (a gated mock, a counter) implements the Source trait and registers it with ProviderRegistry::register_sources, gated behind cfg(test) and the test-helpers feature.
Platform differences
Some facts come from the platform differently. The shipped battery and network providers show the pattern: one Source, with no platform branch in its file, whose data line calls a sys symbol that hides the difference. src/plugin/sys/mod.rs holds what is shared and dispatches to sys/macos.rs or sys/linux.rs through one #[cfg] alias; the platform modules expose pub(super) functions.
For testing, keep the platform's text handling pure and put it in sys/parse.rs, compiled #[cfg(any(target_os = "...", test))], so the Linux parsers are tested on macOS and the reverse; gate only what reads the live system with #[cfg(target_os = "...")].
8. Plugins
A plugin is a shared library (.so on Linux, .dylib on macOS). A Source's data line can call into one with the daemon's plugin(name, symbol, args...) function. This avoids the per-run process spawn of exec() while letting the logic be written in any language that can export C symbols. A plugin is a function, not a provider: the Source around it declares the fields, the schedule and the root, as for any other Source.
Calling a plugin
[daemon.providers.hello.sources.main]
data = "{{ plugin('hello', 'greet', 'world') }}"
result.greeting = "{{ data }}"
plugin(name, symbol, args...) calls symbol in the library name with args and returns the library's JSON result, parsed (a map, list, string, number, bool or null). The call blocks the Source's run for as long as the library takes.
- A
namewithout a/is looked up aslib<name>.dylib(macOS) orlib<name>.so(Linux) in each directory of[daemon.plugin] path, in order; the first directory holding the file wins.plugin('hello', ...)loadslibhello.soorlibhello.dylib. Not found, it is an error naming the file and the directories searched:plugin(): libhello.so not found on [daemon.plugin] path (/home/me/.config/beachcomber/plugins). - A
namecontaining a/is the library path as given: absolute, or~/...(expanded from the daemon'sHOME). A relative path is an error. - A library is loaded on the first call that names it and stays loaded for the daemon's life. The daemon does not look at the file again: a name keeps the library it first loaded, even if another appears earlier on
path; a name first used after a rebuild loads the rebuilt file; restart the daemon to move every name. Names that reach the same file (a symlink, a hard link) share one loaded library.
[daemon.plugin]
path = ["~/.local/lib/beachcomber", "/opt/beachcomber/plugins"]
path is a list of directories (absolute, or starting ~/), default ["<config dir>/plugins"] (~/.config/beachcomber/plugins). A list in a later file replaces the earlier one whole. A key other than path, or a path that is not a list of directory strings, is a config error. Changing [daemon.plugin] restarts the daemon.
The C ABI
Every symbol is the same function type:
const char* symbol(const char* input);
inputis the call's arguments as a NUL-terminated JSON array:plugin('hello', 'greet', 'world', 3)passes["world",3].- The return value is a NUL-terminated JSON value (UTF-8) owned by the library, valid until the next call into the same library. The daemon copies it before it makes another call, and serialises calls into one library, so a static or thread-local buffer is enough; there is no free function.
NULLmeans failure. The Source's run fails withplugin(): <symbol> in <name>: returned NULL; a symbol that is missing, output that is not UTF-8 and output that is not JSON each have their own message.- The function must not unwind. A panic or C++ exception escaping an
extern "C"function aborts the daemon. In Rust, catch panics inside the function (std::panic::catch_unwind) and returnNULL. - The function may be called from any of the daemon's blocking threads (one at a time per library); do not rely on thread-local state surviving between calls.
Example: a minimal C plugin
#include <stdio.h>
// plugin('hello', 'greet', 'world') -> "hello, world"
static char out[256];
const char* greet(const char* input) {
char name[128];
// input is ["world"]; a real plugin parses it with a JSON library
if (sscanf(input, "[\"%127[^\"]\"]", name) != 1) return NULL;
snprintf(out, sizeof out, "\"hello, %s\"", name);
return out;
}
Build: cc -shared -fPIC -o libhello.so hello.c (Linux) or cc -shared -o libhello.dylib hello.c (macOS), and put the file in ~/.config/beachcomber/plugins/. With the Source above, comb get hello.greeting prints hello, world.
Plugins are for work where an exec() spawn is too expensive or the logic does not belong in the daemon binary: compiled parsing, a vendor SDK, a local socket protocol. A plugin runs inside the daemon with its permissions; only put libraries you trust on [daemon.plugin] path.
sys: the plugin compiled in
What only the operating system can say comes from one plugin compiled into comb, sys, called as any plugin is:
[daemon.providers.box.sources.load]
data = "{{ plugin('sys', 'loadavg') }}"
result.one = "{{ data.one }}"
return = "{{ result | poll('10s') }}"
Its symbols are the C ABI's own (const char* symbol(const char* input), JSON in and out, NULL for failure), held in a table in the binary: plugin('sys', …) takes the same path from the engine function to the C call as a library's symbol does, and only the finding of the function differs (the table, not dlsym). Each takes no arguments, answers an object, and leaves out a fact it has no value for, never "".
| symbol | answers | from |
|---|---|---|
hostname | {name, short} | gethostname; short is the first label |
loadavg | {one, five, fifteen} | getloadavg |
uname | {sysname, release, version, machine} | uname |
uptime | {seconds} | macOS sysctl KERN_BOOTTIME; Linux /proc/uptime |
user | {name, uid} | getuid, getpwuid_r; name is absent for a uid with no entry |
network | {interface, ip, ipv6, vpn_active, vpn_name, ssid, online} | getifaddrs; the preferred interface is an en* one on macOS and the default route's (/proc/net/route) on Linux; the SSID from airport on macOS (gone from macOS 14.4, where it is absent) and nmcli, then iw, on Linux |
battery | macOS {percent, charging, status, time_remaining_secs}; Linux {percent, charging, status_raw, status, time_remaining_secs}; {} with no battery | macOS pmset -g batt; Linux sysfs (capacity, status, and the estimate from time_to_empty_now/time_to_full_now or the energy or charge over the rate) |
The name is reserved: plugin('sys', …) never searches [daemon.plugin] path, and comb check config warns of a libsys.dylib or libsys.so there, which nothing would load. An unknown symbol is plugin(): <symbol> in sys: symbol not found; a symbol given arguments returns NULL.
The shipped hostname, user, uname, load, uptime, battery and network providers are Sources like the one above, each in its own defaults/<name>.toml: read one there to see how it is written, and override any of its lines in config.toml or conf.d/.
git: the plugin compiled in for repositories
git is the second compiled-in plugin, by the same table and the same one call path as sys. What git says through its own commands needs an environment set, commands that fail in a healthy repository tolerated, and lineage's branching, so it is a plugin and no shell runs on a refresh. Each symbol takes one argument, the work tree's root, and answers an object: a missing fact is left out, never "", and a directory that is not a work tree's root answers {}.
| symbol | answers | runs |
|---|---|---|
head | {branch, detached} | none |
refs | {stash, state, state_step, state_total, commit, last_commit_timestamp, commit_summary, tag, push_ahead, push_behind} | git log -1, describe, config --list, started together; with a push remote rev-parse and rev-list |
diff | {lines_added, lines_removed, lines_staged_added, lines_staged_removed} | git diff --numstat, diff --cached --numstat, started together |
branches | {branch_parent, branch_default} | rev-parse for a branch with no loose ref |
lineage | {lines_added_parent, lines_removed_parent, lines_added_default, lines_removed_default} | git merge-base, diff --numstat once for any two commits; rev-parse for a branch with no loose ref |
status | {upstream, ahead, behind, staged, unstaged, untracked, conflicted, dirty} | git status |
Every command runs with GIT_OPTIONAL_LOCKS=0, so git status cannot rewrite the index its Source watches, GIT_TERMINAL_PROMPT=0 and the askpass guards, and with GIT_DIR, GIT_COMMON_DIR and GIT_WORK_TREE removed. That environment is in one place in Rust (src/boundaries/git.rs), so no Source can forget it. NULL is failure: git status failing where a symbol needs it, or arguments other than one string.
git is reserved as sys is: plugin('git', …) never searches [daemon.plugin] path, and comb check config warns of a libgit.dylib or libgit.so there.
The shipped provider is defaults/git.toml, five Sources over those symbols, one each. A data line names its directory the way its root line does, lup('.git', root=true) | dirname: a line renders in the instance's root, so that is lup's first probe. A symbol notes each file it reads, stamped before it reads it, in the account of the run it is called in, as a Source's own lines do: what HEAD resolves through (HEAD, packed-refs, the branch's loose ref), and for each symbol what else it says something about (the index, the upstream's ref, the default branch's, the tags, the stash's log, a stepped operation's files). So a read checks exactly those, in a linked worktree too. A plugin library has no such account: its Source stats what it must see in its own lines. A user can override any line of the file, but not copy or edit what a symbol does.