Document the repodata fingerprint invariant #178

Merged

benvin merged 2 commits from benvin/repodata-fingerprint-invariant into master 2026-10-25 22:53:04 +11:00

Conversation 2 Commits 2 Files Changed 3

+10 -1

unkin-agent commented 2026-10-25 20:27:47 +11:00

Member

Copy Link

Copy Source

The cache_repodata fingerprint (count, max id) only detects every change while one writer at a time touches a remote's rows; with interleaved writers a late-committing lower id plus a delete can leave it unchanged. In the deployed server, github_rpm scans run under the per-remote sync lease, which holds only while the lease outlives the scan timeout.

• note the invariant on RPMMetadataFingerprint, scoped to github_rpm remotes
• state it in the Repodata cache section of the github_rpm docs
• add a test asserting syncLeaseDuration > defaultScanTimeout

The cache_repodata fingerprint (count, max id) only detects every change while one writer at a time touches a remote's rows; with interleaved writers a late-committing lower id plus a delete can leave it unchanged. In the deployed server, github_rpm scans run under the per-remote sync lease, which holds only while the lease outlives the scan timeout. - note the invariant on RPMMetadataFingerprint, scoped to github_rpm remotes - state it in the Repodata cache section of the github_rpm docs - add a test asserting syncLeaseDuration > defaultScanTimeout

unkin-agent added 1 commit 2026-10-25 20:27:47 +11:00

Document the serialised-writer invariant behind the repodata fingerprint 9fb44c22d6

unkin-agent commented 2026-10-25 20:30:50 +11:00

Author

Member

Copy Link

Copy Source

• docs/rpm/remote-github.md:97 — "which the sync lease guarantees across replicas" is unconditional, but GitHubProvider.onRequest falls back to refresh()/runScan (internal/provider/rpm/github.go:243,417) with no lease when p.syncer == nil (production wires it at internal/server/server.go:91) → say "in the deployed server" or drop "guarantees".
• nit: internal/database/rpm_metadata.go:45 — the lease only outlives the scan because syncLeaseDuration (15m, syncer.go:22) > defaultScanTimeout (10m, github.go:48); nothing pins that → mention the dependency in the comment or add a one-line test asserting syncLeaseDuration > defaultScanTimeout.
• nit: internal/database/rpm_metadata.go:45 — comment line is overlong and says "a remote's writers" while the function takes any repoName (local rpm repos write via AfterUpload/AfterDelete unserialised) → scope it to "github_rpm remotes" and wrap.

- docs/rpm/remote-github.md:97 — "which the sync lease guarantees across replicas" is unconditional, but `GitHubProvider.onRequest` falls back to `refresh()`/`runScan` (internal/provider/rpm/github.go:243,417) with no lease when `p.syncer == nil` (production wires it at internal/server/server.go:91) → say "in the deployed server" or drop "guarantees". - nit: internal/database/rpm_metadata.go:45 — the lease only outlives the scan because `syncLeaseDuration` (15m, syncer.go:22) > `defaultScanTimeout` (10m, github.go:48); nothing pins that → mention the dependency in the comment or add a one-line test asserting `syncLeaseDuration > defaultScanTimeout`. - nit: internal/database/rpm_metadata.go:45 — comment line is overlong and says "a remote's writers" while the function takes any `repoName` (local rpm repos write via AfterUpload/AfterDelete unserialised) → scope it to "github_rpm remotes" and wrap.

unkin-agent added 1 commit 2026-10-25 20:32:05 +11:00

Scope the fingerprint invariant to the wired syncer and pin lease > scan timeout df4c397db9

unkin-agent commented 2026-10-25 20:35:06 +11:00

Author

Member

Copy Link

Copy Source

• internal/provider/rpm/syncer_test.go:514 — nit: test asserts the default constants only; p.scanTimeout is the value the syncer actually uses (syncer.go:228) and is overridable → fine as a guard, but the comment/doc should say "default scan timeout" if kept exact.
• internal/provider/rpm/github.go:411 — nit: the invariant holds only when the syncer is wired; without it refresh runs runScan with no lease (comment at github.go:236 acknowledges this). The new docs say "the sync lease serialises scans" unqualified → word it as "when the background syncer is enabled (always, in the deployed server)".

- internal/provider/rpm/syncer_test.go:514 — nit: test asserts the default constants only; `p.scanTimeout` is the value the syncer actually uses (syncer.go:228) and is overridable → fine as a guard, but the comment/doc should say "default scan timeout" if kept exact. - internal/provider/rpm/github.go:411 — nit: the invariant holds only when the syncer is wired; without it `refresh` runs `runScan` with no lease (comment at github.go:236 acknowledges this). The new docs say "the sync lease serialises scans" unqualified → word it as "when the background syncer is enabled (always, in the deployed server)".

benvin merged commit e59d9728b2 into master 2026-10-25 22:53:04 +11:00

benvin deleted branch benvin/repodata-fingerprint-invariant 2026-10-25 22:53:04 +11:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

benvin (BenVincent) unkin-agent (Unkin Agent) unkinben (Ben Vincent)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: unkin/artifactapi#178