Skip to content

fix(downloader): install binaries atomically and once under concurrent jobs - #121

Open
Macbet wants to merge 2 commits into
masterfrom
fix/downloader-atomic-install
Open

Macbet wants to merge 2 commits into
masterfrom
fix/downloader-atomic-install

Conversation

@Macbet

@Macbet Macbet commented Nov 18, 2026

Copy link
Copy Markdown

Stacked on #120 (fix/tofu-release-pagination), which is stacked on #117. Review only the last two commits. Merge #117 and #120 first.

Problem

Concurrent jobs that need the same uncached version both streamed into the same download/<file>.zip and unzipped into the same terraform/<version>/terraform. That caused three failures:

  • The binary was written in place, so a concurrent isUsableBinary() could chmod it and return it while it was still being written. The result was exec of a partial binary, or "Text file busy".
  • A JVM killed mid-unzip left a truncated, executable binary that was then treated as installed forever.
  • Zip entry names were concatenated into paths unchecked (zip-slip). This is reachable through a custom terraformReleasesUrl or tofuReleasesUrl, or a tampered mirror.

Change

Atomic install

  • The archive downloads to <archive>.<uuid>.part, then moves into place with an atomic move.
  • Extraction goes to a sibling temp directory. Only the product binary is made executable, it is verified, and then it is moved into place atomically.
  • A partially written file never appears at the final path. Paths and directory layout are unchanged, including tofu/v1.x.y/.

Locking

  • There is a per-version interruptible lock in the JVM, plus FileChannel.lock() on a per-version lock file for pods sharing a volume.
  • Jobs already waiting behind a failed install fail fast with its cause instead of each re-downloading. A later job retries.
  • If the filesystem has no lock support, the install proceeds without the cross-process lock, which is still atomic.
  • The fast path, an already-installed binary, takes no lock and makes no network call.

Cleanup

  • Leftovers of killed installs (.part, .tmp) are swept under the lock. Only entries older than the download timeout plus 5 min are removed, so it is safe even where locks are not enforced across hosts. Matching uses prefix and suffix, not a glob.

Zip-slip and index validation

  • Entries escaping the extraction directory, via .. or absolute paths, are rejected.
  • The server-supplied archive file name must be a plain file name.

Robustness

  • @JsonIgnoreProperties(ignoreUnknown = true) on the Terraform index models, so a new field in index.json no longer breaks every download.
  • x86_64 maps to amd64 and i386/i686 to 386. Intel macOS no longer fails with "Invalid Terraform Version".
  • chmod runs on every non-Windows OS, and only the product binary is made executable.

Behaviour change

A found binary without the exec bit is no longer chmod'ed and reused. It is reinstalled instead, because it may be a truncated leftover. Pre-seeded caches (air-gapped installs, baked images) must have +x. Terrakube's executor already sets +x itself before calling the library.

Tests

New tests in TerraformDownloaderTest:

  • 8 concurrent threads trigger exactly 1 archive download and get an identical, executable binary. With the locks removed, the test fails with 8 downloads.
  • A truncated archive leaves nothing usable and no temp files, and a retry succeeds.
  • Killed-install leftovers are swept, and fresh ones are kept.
  • An interrupted waiter returns promptly with the interrupt flag set.
  • Waiters behind a failed holder fail fast.
  • Only the product binary is executable.
  • Zip-slip entries are rejected, and bad index file names are rejected.
  • Glob characters in an archive name are handled.
  • Unknown index fields are ignored.
  • The arch mapping is covered.

All behaviour tests fail on the previous code.

Docker verify (temurin 17, --init), together with #120: 68/68 in terraform-client. Downloader tests 3× with --cpus=1. Real installs of terraform 1.9.8 and tofu 1.13.9 succeeded, and the second call hits the fast path in 0 ms.

@Macbet
Macbet changed the base branch from fix/client-drop-webflux to fix/tofu-release-pagination November 18, 2026 04:20
@Macbet
Macbet added this pull request to stack #122 November 18, 2026 21:25
@alfespa17

Copy link
Copy Markdown
Member

@Macbet I dont think this is need it, the library is only used for the executor component, the executor component is only running 1 job each time so there are not concurrent request in reality

@alfespa17
alfespa17 force-pushed the fix/downloader-atomic-install branch from 46ca8b2 to b507dce Compare November 18, 2026 22:45
Base automatically changed from fix/tofu-release-pagination to master November 18, 2026 22:54
…t jobs

Concurrent jobs needing the same uncached version streamed into the same
archive and unzipped into the same binary, so another job could exec a
partially written file, and a JVM killed mid-unzip left a truncated binary
that was treated as installed forever.

- Download to a unique <archive>.<uuid>.part and rename it when complete.
- Extract into a unique temp directory next to the version directory and
  rename the directory (or just the binary, if the directory exists) into
  place once the binary is complete and executable.
- Serialize installs of a version with an interruptible per-version lock
  and a FileChannel lock in the download directory, so executors sharing a
  volume download it once. Jobs that waited behind a failed install fail
  with its cause instead of each retrying in turn.
- Under the lock, delete leftovers of killed installs, but only those older
  than the download timeout plus 5 minutes, since some shared file systems
  don't enforce the lock across hosts.
- Merge the two unzip methods, mark only the product binary executable,
  reject entries that escape the extraction directory (zip slip) and
  archive file names from the index that are not plain file names.
- Delete an archive that fails to extract for any reason, so it is not
  retried on every run.

Behaviour change: a found binary without the exec bit is no longer
chmod-ed and reused, it is reinstalled. Only interrupted older installs
leave one, and it may be truncated. Pre-seeded caches (air-gapped hosts,
baked images) must have +x on the binaries.
- Ignore unknown fields in the Terraform index models like the Tofu ones
  already do, so a new field in HashiCorp's index.json or a mirror no
  longer breaks every Terraform download.
- Map x86_64/amd64 to amd64 and x86/i386-i686 to 386. Intel macOS reports
  x86_64 and failed with "Invalid Terraform Version".
- Drop the terraformDirectory field: it was never read, and the tofu setup
  overwrote it with the tofu path.
@alfespa17
alfespa17 force-pushed the fix/downloader-atomic-install branch from b507dce to b094bba Compare November 18, 2026 22:54
@sonarqubecloud

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants