Offline and air-gapped use #227

Epic. How Comline works with no internet access, across every repository. The draft proposal is ComlineProject/docs#163 (proposals/offline/).

Situations (all in scope)

• an offline developer machine;
• an isolated build or CI network;
• an air-gapped deployment;
• bringing the tooling itself into a sealed network.

Decided

• Choosing is separate from getting. add and a future update write pins. Getting already-pinned bytes follows the rules below.

• Default: a build fetches missing pinned content on demand.

  • A hard offline switch (--offline, an environment variable, machine config) forbids all network access, and lists everything missing in one error.
  • comline fetch fetches ahead of time exactly what a build would.

• Package settings can only tighten: explicit fetching, required hashes. The strictest setting wins. Offline is absolute, and a dependency's settings apply only to its own builds.

• Hashes are mandatory:

  • for registry dependencies, always;
  • for git dependencies, when offline or when the package requires them;
  • for any dependency with more than one source.

  A mismatch is a hard error naming the source.

• Identity is the hash; location is replaceable. Bytes can come from:

  • several ordered sources per dependency (from the package, machine or organisation mirrors, and root additions for hashed transitive pins, which add and never replace);
  • a shared hash-keyed cache;
  • vendoring, mirrors, or signed bundles.

  The order is mirrors, then the root's additions, then the package's own sources.

• Generated code's dependencies: publishing the runtimes to crates.io and npm is a 1.0 requirement. Until then, document vendoring.

• Tooling: release artifacts with checksums and signatures, reproducible builds, an SBOM, and an offline docs bundle.

• Nothing calls home: the runtime and generated code reach only their peer, there is no telemetry and no update check, and the language server never fetches.

Tracking

Proposal: ComlineProject/docs#163 (draft).

Stage 1, fetching rules

• Deps: an offline switch, and fetching ahead of time #228 offline switch, and fetching ahead of time
• Deps: package fetch settings, and the strictest-wins rule #229 package fetch settings, strictest wins
• Deps: when a hash is mandatory, and mismatches as errors #230 when a hash is mandatory; mismatches as errors
• Offline commands: --offline, fetch, vendor, bundle cli#145 --offline, fetch, vendor, bundle
• Offline: never fetch, report missing dependencies like check, release artifacts language-server#103 never fetch; missing dependencies like check

Stage 2, cache and vendoring

• Deps: one hash-keyed cache per machine #232 one hash-keyed cache per machine
• Deps: vendored dependencies as a source #233 vendored dependencies as a source

Stage 3, sources and mirrors

• Deps: several sources per dependency #231 several sources per dependency
• Deps: machine and organisation mirrors #234 machine and organisation mirrors

Stage 4, bundles

• Deps: importing a signed bundle into the cache #235 importing a signed bundle

Stage 5, tooling into the gap

• Releases: prebuilt artifacts, checksums, signatures, SBOM, reproducible builds cli#146 release artifacts, checksums, signatures, SBOM, reproducible builds
• An offline docs bundle, and an air-gapped guide docs#164 offline docs bundle, air-gapped guide
• Generated docs load no outside assets generation#129 generated docs load no outside assets

Stage 6, generated code's dependencies (1.0)

• Publish comline-runtime to crates.io (1.0 requirement), and the no-network rule runtime#115 publish comline-runtime; the no-network rule
• Publish @comline/runtime to npm (1.0), and offline install docs comline-typescript#154 publish @comline/runtime
• Generated code names a published runtime version (1.0), and vendoring docs until then comline-rust#115 generated code names a published version

Related: ComlineProject/cli#1 (publish comline to crates.io), ComlineProject/docs#102 (reserve package names).