Offline and air-gapped use
Status: draft · two parts, read in order: fetching, then supplying dependencies and tooling
The question. Nothing yet says how Comline works without internet access. What must hold, in every repository, so Comline can be used on a machine or in a network that can't reach the internet, and so a build there is exactly the build anywhere else?
The situations
All four are in scope:
| Situation | What it needs |
|---|---|
| An offline developer machine | Work from what was fetched earlier, or from a bundle, and be told clearly what's missing. |
| An isolated build or CI network | Build and generate from vendored copies or internal mirrors, never reaching outside. |
| An air-gapped deployment | Services built with Comline run in a sealed network: the runtime and generated code need nothing beyond the peer they talk to. |
| The tooling into the gap | The CLI, the language server, generators and docs brought into a sealed network, verifiably. |
What it looks like today
| Part | Network today | Already offline-friendly |
|---|---|---|
| core (dependencies) | A Git dependency is fetched by the system git into a per-package .comline/deps-cache/. Registry sources exist in the config (with hash and signature) but nothing resolves them. |
Pins are exact commits, and a checkout is reused. A mode that never fetches exists, which the language server uses. A declared hash (blake3 of the dependency's compiled content) is checked; without one, core warns and trusts the fetch. |
| cli | check, add and build fetch through core. It installs only with cargo install --path .: no release binaries, checksums or signatures. |
Generators are built in, or local executables and .wasm files: nothing is downloaded. |
| language server | None. | It never fetches, and says "isn't fetched yet — run comline check". |
| generated code | Rust depends on comline-runtime by a git rev; TypeScript on @comline/runtime from npm. |
Otherwise self-contained. |
| runtime | None beyond the peer it's given. | Fits air-gapped deployment as it is. |
| specification | The vendoring scripts clone from GitHub, only when a developer runs them. | Copies are committed, pinned and checked. |
| docs | The theme loads Google Fonts by default. | — |
Nothing reports usage or checks for updates.
Rules that hold whatever the details
- Choosing is separate from getting. Choosing a dependency (
add, a futureupdate) writes pins, and uses the network only when the user asks. Getting bytes that are already pinned follows the fetching rules. - Identity is the hash, location is replaceable. Where bytes come from (a registry, git, a mirror, a vendored copy, a cache, a bundle) never changes what is built. A copy is accepted only when it matches the pin.
- Offline is absolute. When the environment says offline, nothing touches the network, whatever any package says.
- Nothing calls home. The runtime and generated code never reach anything but the peer they're given. No tool sends telemetry or checks for updates. The language server never fetches.
Rollout
In stages, each useful on its own:
- Fetching rules in core and the CLI: the offline switch,
comline fetch, the package settings and their precedence, and the hash rules. - The shared cache and vendoring: one hash-keyed cache per machine, in
place of the per-package deps cache, and
comline vendor. - Several sources per dependency, and mirrors: ordered sources, machine and organisation mirrors, and the root package's additions.
- Bundles: export and import of a signed archive.
- Tooling into the gap: release artifacts with checksums, signatures and an SBOM, reproducible builds, and an offline docs bundle.
- Generated code's dependencies: the runtimes published to crates.io and npm, a hard requirement for 1.0. Until then, the docs say how to vendor them.
Where settings live
| Where | What | Frozen |
|---|---|---|
config.idp |
each dependency's identity (version or commit, and hash) and its sources |
identity only; sources is never frozen |
the project's comline.toml (committed, read only for the root package) |
the fetch policy, and sources the root adds for transitive dependencies | never |
machine and organisation config: a system file (/etc/comline/config.toml, %PROGRAMDATA%), a user file (~/.config/comline/config.toml and the platform's equivalents), or one named by COMLINE_CONFIG |
offline, mirrors, the cache's location, trusted keys |
— |
| the environment and flags | COMLINE_OFFLINE=1, --offline |
— |
They combine, and the strictest applies.
Remaining open questions
- Whether
comline fetchtakes--for <target>, to fetch only what one target's generation needs.