72 lines
4.6 KiB
Markdown
72 lines
4.6 KiB
Markdown
# Step 05: Artifact Store
|
|
|
|
Prerequisites: steps 01, 04.
|
|
Read `README.md` and `00-legacy-analysis.md` first.
|
|
|
|
## Goal
|
|
|
|
Persist build artifacts (logs plus configured report directories) with stable naming and retention pruning.
|
|
|
|
## Design
|
|
|
|
Create package `de.hoennig.werkator.artifacts`:
|
|
|
|
- `ArtifactStore` service implementing the interface stubbed in step 04.
|
|
- Artifact root: a configurable directory (new key `artifacts.rootDir`), defaulting to `${XDG_STATE_HOME:-~/.local/state}/werkator/artifacts/<repo-key>`.
|
|
Do NOT default to `/tmp` like legacy — artifacts vanished on reboot.
|
|
- Repo key: sanitized absolute repo path (legacy `repository_key`): non `[A-Za-z0-9._-]` → `_`.
|
|
- Artifact key per build: sanitized branch name + 12-char SHA-256 prefix, plus sanitized start timestamp + hash (legacy `build_artifact_key`); keep this scheme so URLs stay predictable.
|
|
- `persist(build, stagingDir)`: copy configured `artifactDirs` and the log files into staging, then atomically move staging → `<root>/branches/<artifactKey>/`.
|
|
- `prune(keptResults)`: delete artifact directories whose keys are no longer in the result repository (call after repository retention pruning from step 01).
|
|
- Provide `artifactDir(artifactKey)` lookups for the server (step 07).
|
|
|
|
## Out of Scope
|
|
|
|
- HTTP serving (step 07).
|
|
- HTML index pages (step 08 renders from data instead of generated files).
|
|
|
|
## Config
|
|
|
|
New key `artifacts.rootDir` (empty = platform default above).
|
|
Update `WerkatorConfig`, `InitCommand` templates, and `docs/configuration.md` together.
|
|
|
|
## Tests
|
|
|
|
- Key naming: sanitization, hash stability, collision of similar branch names.
|
|
- Persist: copies configured dirs, missing artifact dirs are skipped with a log line, atomic move (no partial dirs on failure).
|
|
- Prune: deletes exactly the unreferenced dirs, never anything outside the artifact root.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `./gradlew ktlintFormat` then `./gradlew build` is green.
|
|
- Step 04's executor persists artifacts through the real store (integration test).
|
|
|
|
## Execution Notes (done 2026-07-07)
|
|
|
|
Implemented as `FileArtifactStore` in `de.hoennig.werkator.artifacts`; build green, 12 new tests
|
|
(`FileArtifactStoreTest`, `BuildExecutorArtifactIntegrationTest`, plus a `repoKey` case in `ArtifactKeysTest`).
|
|
Deviations and decisions:
|
|
|
|
- The `ArtifactStore` interface stays in `de.hoennig.werkator.build` (moving it would make `build` depend on `artifacts`).
|
|
It gained `prune(keptResults)` and `artifactDir(artifactKey)`; the `NoOpArtifactStore` placeholder was removed.
|
|
- Interface gap from step 04 resolved by an additional parameter: `persist(build, stagingDir, workspace)`.
|
|
The store copies the configured `artifactDirs` out of the branch worktree itself, so the archived layout stays store knowledge.
|
|
`workspace` is null when a build crashed before its worktree was prepared; only the logs are stored then.
|
|
- Key naming was reused from step 04's `ArtifactKeys` (UTC `Instant`, not local time like legacy); only `repoKey` was added.
|
|
The repo key sanitizes the absolute normalized working directory, not `git rev-parse --show-toplevel` — consistent
|
|
with step 04's decision to resolve everything relative to the working directory.
|
|
- The atomic move does not move the staging directory directly: staging is a temp dir (usually under `/tmp`) and may
|
|
be on a different filesystem than the artifact root, where a move is not atomic.
|
|
Like legacy `persist_build_artifacts` (`$artifact_dir.tmp.$$`), everything is assembled in `.incoming-<key>` next to
|
|
the target and then moved with `ATOMIC_MOVE`; on failure the incoming dir is deleted, so no partial dirs appear.
|
|
The staging directory is deleted after a successful move.
|
|
- The legacy archive layout was ported: `build/reports` archives as `reports/`, every other artifact dir below `reports/<dir>`.
|
|
- Concurrency (builds run concurrently since the step 04 amendment): persists share a read lock — their target dirs are
|
|
disjoint because artifact keys are unique per build — while `prune` takes the write lock, so it never deletes mid-persist.
|
|
`prune` also removes `.incoming-*` leftovers of crashed persists, deletes symlinks without following them,
|
|
and returns the removed keys.
|
|
- `artifactDir` rejects keys outside `[A-Za-z0-9._-]+` and anything resolving outside `<root>/branches/` (path traversal).
|
|
- `artifacts.rootDir` supports a leading `~/` and resolves relative paths against the repository;
|
|
when empty, the default is `$XDG_STATE_HOME` (or `~/.local/state`) + `/werkator/artifacts/<repo-key>` as designed.
|
|
- The bean is wired in `ArtifactsConfiguration` with the working directory defaulting to `.`, mirroring `BuildConfiguration`.
|