Document temp-staging-in-managed-dir invariant (#6) #18

Merged

erik merged 1 commit from chore/tmp-dirs-managed-staging into main

2026-06-27 00:05:40 +00:00

agent-dev commented

2026-06-26 23:48:00 +00:00

Member

Refs: #6

What

Issue #6 raised that if staged writes use mktemp / os.TempDir(), atomic renames into the synced tree could hit cross-device penalties, and suggested staging temp files inside the dropbear-managed directory instead.

Audit finding: the codebase already does this everywhere. No code change is needed; this PR captures the invariant as a decision record so the concern doesn't recur.

Audit

Every non-test atomic-rename temp writer stages on the same filesystem as its destination:

internal/blobio/tempdir.go — NewRunTempDir stages synced content under <root>/.dropbear/restore-tmp/run-*; downloads rename to <root>/<path>. Used by internal/upload/run.go (downloads/conflict copies) and internal/restore/run.go.
internal/blobio/download.go — os.CreateTemp(tempDir, "blob-*") → rename to finalPath, both under the same root.
internal/config/writer.go — temp sibling in the destination dir → rename to root.toml.
internal/statusapi/runtime.go — os.CreateTemp(filepath.Dir(path), …) → rename in place.
internal/daemoninstall/install.go — os.CreateTemp(filepath.Dir(path), …) → rename in place.

No path uses the system temp dir for staged writes.

Change

Added wiki/decisions/temp-staging-in-managed-dir.md documenting the same-filesystem staging invariant and its call sites.
Cross-linked it from wiki/decisions/dropbear-dir-per-root.md (the per-root .dropbear/ placement is what makes same-filesystem staging structural).

Docs-only — just validate skipped (no code changed).

Refs: #6 --- ## What Issue #6 raised that if staged writes use `mktemp` / `os.TempDir()`, atomic renames into the synced tree could hit cross-device penalties, and suggested staging temp files inside the dropbear-managed directory instead. Audit finding: **the codebase already does this everywhere.** No code change is needed; this PR captures the invariant as a decision record so the concern doesn't recur. ## Audit Every non-test atomic-rename temp writer stages on the same filesystem as its destination: - `internal/blobio/tempdir.go` — `NewRunTempDir` stages synced content under `<root>/.dropbear/restore-tmp/run-*`; downloads rename to `<root>/<path>`. Used by `internal/upload/run.go` (downloads/conflict copies) and `internal/restore/run.go`. - `internal/blobio/download.go` — `os.CreateTemp(tempDir, "blob-*")` → rename to `finalPath`, both under the same root. - `internal/config/writer.go` — temp sibling in the destination `dir` → rename to `root.toml`. - `internal/statusapi/runtime.go` — `os.CreateTemp(filepath.Dir(path), …)` → rename in place. - `internal/daemoninstall/install.go` — `os.CreateTemp(filepath.Dir(path), …)` → rename in place. No path uses the system temp dir for staged writes. ## Change - Added `wiki/decisions/temp-staging-in-managed-dir.md` documenting the same-filesystem staging invariant and its call sites. - Cross-linked it from `wiki/decisions/dropbear-dir-per-root.md` (the per-root `.dropbear/` placement is what makes same-filesystem staging structural). Docs-only — `just validate` skipped (no code changed).

agent-dev added 1 commit

2026-06-26 23:48:00 +00:00

Document temp-staging-in-managed-dir invariant

Validate / validate (pull_request) Successful in 43s

Details

e5ea8af1bd

Issue #6 asks whether staged writes use system temp (mktemp / os.TempDir), which would risk cross-device rename penalties, and suggests staging inside the dropbear-managed directory instead. Audit shows the codebase already does this everywhere: synced content stages under <root>/.dropbear/restore-tmp via blobio.NewRunTempDir, and metadata writers (root.toml, daemon runtime JSON, installed daemon assets) create their temp file as a sibling of the destination. No path uses the system temp dir, so there is no code change to make.

Record the invariant and its call sites as a decision doc so the concern does not recur, and cross-link it from the per-root .dropbear decision.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

agent-dev referenced this pull request

2026-06-26 23:48:11 +00:00

Tmp dirs & cross-device issues #6