You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(git-store): add drafts, explicit save, conflicts and expiry - #48
Adds the write path of the git-store document store: per-user drafts, the explicit save with lease, conflict handling per path, concurrent change detection, draft expiry with garbage collection, and the author, committer and credential rules. The spec for this work is PLAN-08 of the epic libraries-initial-implementation (GDR-STORE-2/3/4/5/7/8, GDR-NFR-2).
Intent
The store could read and register repositories but not write documents. This change adds the write path: users keep per-user drafts on references that are never pushed, and an explicit save squashes a draft into one commit on the remote tip, pushed with a lease and re-applied up to a bounded number of attempts, so concurrent writers on one branch all succeed and two writers on one file produce exactly one save and one conflict.
Everything stays in git-store; git-core is used as it is (push with lease, compare-and-swap, in-core writing and merging) and gains no code. The in-process garbage collection after draft expiry sets the prune expiry to now in the clone's own configuration and runs under an exclusive lock, so no concurrent save can lose an object it still needs. By decision of the owner, author and committer e-mail addresses are off by default (GDR-NFR-3) and only appear when commit.email is switched on; the committer address is then the technical user's configured one, and the author address is supplied by the caller.
Non-goals: signing and trailers on the commits (GDR-STORE-12/13, a later plan), any change to git-core, and any new dependency.
Changes
StoreConfiguration: save.max-attempts now has an upper bound of 100, so a value such as Integer.MAX_VALUE is refused as malformed (the key is named, the value never). New section commit with commit.email (default false): author and committer carry an e-mail address only when it is set.
Reference layout and ids: Ulid, DocumentCollection, DocumentKey, StoreReferences (the push refspec never carries refs/drafts/*).
Drafts: StoreWriter with Draft, TechnicalUser, Author over the package-private DraftReferences, RepositoryGuard and CommitIdentities.
Explicit save: ExplicitSave and SaveResult (fetch, one commit on the remote tip, push with lease, re-apply up to save.max-attempts, then move the local branch and compare-and-delete the draft; conflicts name every path).
Draft expiry: DraftExpiry (compare-and-delete of stale drafts, then in-process garbage collection under an exclusive lock).
Log messages GIT_STORE-2/3/4/101/102 and their catalogue in git-store/doc/LogMessages.adoc.
Save.MAX_ATTEMPTS = 100 bounds save.max-attempts: a larger value is
refused as MALFORMED at start and by the Save constructor. The new
section commit carries commit.email (default false), so commits keep
author and committer e-mail empty unless configured (GDR-NFR-3).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
Ulid creates and checks the 26-character Crockford base32 ids of
per-document collections (cui-java-tools 2.7.0 has no ULID generator).
DocumentCollection, DocumentKey and StoreReferences give the target
branch of each collection kind, the never-pushed draft reference
refs/drafts/<pseudonym>/<collection>/<id> and the push refspecs, and
refuse invalid or reserved names, invalid ids and pseudonyms, and a
collection name declared twice (GDR-STORE-2).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
StoreWriter opens the bare clone of a repository with the push refspecs
that never carry refs/drafts/*, and writes intermediate saves as commits
of refs/drafts/<pseudonym>/<collection>/<id>: a new draft starts at the
tip of the target branch, else main, else as a root commit, and every
further save stacks on it by compare-and-swap. The drafts of a user are
listed sorted by reference name (GDR-STORE-2). CommitIdentities builds
author and committer from Author and TechnicalUser and writes an e-mail
address only with commit.email true (GDR-NFR-3). RepositoryGuard holds
the shared and exclusive maintenance lock and the transport lock.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
…ge detection
StoreWriter.save applies the changes of a draft (from the merge base of
draft tip and fetched base to the draft tip) onto the fetched tip of the
target branch as one commit, pushes it with the lease of that tip (the
zero id for a branch created from main) and re-applies after a refused
lease or a rejection up to save.max-attempts (GDR-STORE-3). Only after
the remote accepted the commit the local branch moves and the draft is
deleted by compare-and-delete, so a newer draft is kept. An expected
blob id that differs on the fetched tip is a conflict that pushes
nothing (GDR-STORE-4, GDR-STORE-5); SaveResult carries the conflicting
paths as data. Fetch and push use the technical user's credentials only
(GDR-STORE-8). GIT_STORE-2, GIT_STORE-3 and GIT_STORE-101 log the
outcome without a path, content or address.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
StoreWriter.expireDrafts deletes every draft unchanged for drafts.expiry by compare-and-delete, keeping a draft changed meanwhile, then collects the garbage under the exclusive side of the maintenance lock (GDR-STORE-7). DraftExpiryTest covers stale, fresh, changed-meanwhile and failed-collection cases.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
…tests
ConcurrentWritersTest saves from ten writers with own clones, from two writers on one file, and from ten threads sharing one writer. WritePathSecretsTest checks that no log record, result detail, rendering, exception or commit message carries a credential, address or person name, and that addresses appear only in commit e-mail fields when commit.email is true.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
The git-store specification now states GDR-STORE-2, 3, 4, 5, 7 and 8 as implemented with their design, the commit.email key and the bound of save.max-attempts; general.adoc states the commit.email exception of GDR-NFR-3 and the test coverage of GDR-NFR-2; the index, the module structure and AGENTS.md name the write path.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
…ts-save
Narrow constants used only inside their own class to private and drop an
unused test accessor.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
The git-store module adds draft creation and listing, explicit saves with leases and conflict detection, and draft expiry with garbage collection. It also adds write-path types, configuration, tests, log messages, and specifications. git-core fetch operations gain optional pruning of stale references within fetch destinations.
Changes: git-store write path
Layer / File(s)
Summary
Write contracts and configuration git-store/src/main/java/de/cuioss/git/document/store/*, git-store/src/test/java/de/cuioss/git/document/store/*Test.java, doc/specification/general.adoc, doc/specification/git-store.adoc
Adds collection, key, reference, identity, ULID, draft, and save-result types. Adds the commit.email setting, defaulting to false, and limits save.max-attempts to 1–100.
Draft operations and writer entry point git-store/src/main/java/de/cuioss/git/document/store/StoreWriter.java, git-store/src/main/java/de/cuioss/git/document/store/DraftReferences.java, git-store/src/test/java/de/cuioss/git/document/store/StoreWriterDraftTest.java, doc/README.adoc, doc/concepts/module-structure.adoc, AGENTS.md
Adds the StoreWriter entry point and draft write and listing operations. Draft writes use compare-and-swap. Listings return sorted draft metadata.
Explicit save and conflict handling git-store/src/main/java/de/cuioss/git/document/store/ExplicitSave.java, git-store/src/main/java/de/cuioss/git/document/store/RepositoryGuard.java, git-core/src/main/java/de/cuioss/git/document/core/*, git-store/src/test/java/de/cuioss/git/document/store/*Test.java, git-store/doc/LogMessages.adoc, doc/specification/git-store.adoc, doc/specification/git-core.adoc
Adds fetch-and-push saves with leases and retries, expected-blob conflict checks, and post-push reference updates. Fetch inputs can enable pruning of stale references within fetch destinations. Tests cover concurrent writers, outcomes, credentials, and pruning.
Draft expiry and garbage collection git-store/src/main/java/de/cuioss/git/document/store/DraftExpiry.java, git-store/src/test/java/de/cuioss/git/document/store/DraftExpiryTest.java, doc/specification/git-store.adoc
Adds expiry based on draft tip commit time. Stale references are compare-and-deleted before garbage collection. Collection failures return FAILED with the exception class in the detail.
cuioss/git-document-repository#25: Introduces RepositoryOperations and its JGit implementation, which this change extends with fetch pruning.
Merge Risk: Moderate · previous review 9f3e6
The new write path can lose unsaved drafts when it reuses a clone with a non-standard fetch configuration. Concurrent saves of one draft can re-apply an already saved change. A skipped garbage collection is reported as success. Fix the draft-pruning scope and the save serialization before merging; the remaining items are smaller follow-ups.
Pre-merge checks: 2
Check name
Status
Explanation
Description Check
Check skipped - CodeRabbit’s high-level summary is enabled.
Title check
The title "feat(git-store): add drafts, explicit save, conflicts and expiry" matches the main change. The PR adds a write path to git-store, including per-user drafts, explicit saves with leases, path…
Full details: Title check
Explanation
The title "feat(git-store): add drafts, explicit save, conflicts and expiry" matches the main change. The PR adds a write path to git-store, including per-user drafts, explicit saves with leases, path-level conflict handling, and draft expiry with garbage collection. The title names the module and the main features. It omits the identity, reference, and configuration types, which is expected for a title.
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 12
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Minor comments: 10
doc/specification/git-store.adoc: 2
267-268: Minor · Functional Correctness · Quick win
Distinguish fetch effects from conflict effects.
If the remote target moves from A to B, ExplicitSave.attempt mirror-fetches B before it checks expected blob ids. A subsequent conflict leaves the local target at B, not A. Document that the conflict does not push or modify the draft, but that the preceding fetch can update local branches. (raw.githubusercontent.com)
As per path instructions, “Check a guard's predicate against the scenario the guard exists for,” including earlier operations.
Source: Path instructions
325-326: Minor · Security & Privacy · Quick win
Exclude DEBUG throwable logging from the sanitized failure path.
DraftExpiry.collectGarbage also calls LOGGER.debug(e, ...). CuiLogger 2.7.0 forwards that throwable, so the DEBUG record retains the exception message and causes. The class-only result and WARN do not provide the stated protection. Remove the throwable argument and log only the exception class before making this guarantee. (raw.githubusercontent.com)
As per path instructions, “Prose, a code comment, or a summary table is not a mechanism.” The missing sanitization belongs in DraftExpiry.java.
244-246: Minor · Functional Correctness · Quick win
Assert the file contents, not just the paths.
Both checks pass if the draft has the right paths but contains the wrong bytes. In particular, the branch-tip check does not verify that its content survived the edit. Keep the expected bytes or blob IDs from setup and compare them with the draft tree. Use the same check in secondSaveStacks to verify that the second write preserves the first edit’s content.
170-176: Minor · Data Integrity & Integration · Heavy lift
Publish the draft ref only after the first draft commit is ready.
If the first write contains two edits to the same path, createIfMissing publishes the target tip before InCoreWriter rejects the edits. The caller receives NOT_FOUND, but drafts() now lists the target commit as an intermediate save. A corrected retry also inherits that tip even if the target has advanced. Build the first draft commit from the selected base, then publish it with an absent-ref check. If another writer publishes a draft first, retry from that draft’s tip. (raw.githubusercontent.com)
200-200: Minor · Security & Privacy · Quick win
Keep the raw exception out of the debug log.
If opening a clone fails with a path-bearing exception, the path can contain an e-mail address. CuiLogger attaches the original throwable to the JUL record, even though the returned detail contains only its type. Log the safe context and exception type without attaching e. GDR-NFR-3 applies to debug output as well as to result details. (raw.githubusercontent.com)
Document the JVM-wide prerequisite for blocking process starts.
Setting RefusingFS on the repository does not replace JGit’s default SystemReader. On first use, that reader can still start a process to locate system configuration. State that the embedding application must install RefusingFS.systemReader(...) before any JGit use for the JVM-wide guarantee. As per path instructions, “verify that the mechanism exists in the file that would have to implement it”; the repository setup in StoreWriter.java does not install the reader. (raw.githubusercontent.com)
644-645: Minor · Functional Correctness · Quick win
Guarantee distinct content in the change-detection fixtures.
The base, draft, and concurrent contents are generated independently. If a draft value equals its base value, that path is not a draft change and never reaches the conflict check. If the concurrent value equals the original, there is no concurrent change to detect. These collisions can fail a correct implementation or let the overwrite test pass without exercising an overwrite. (raw.githubusercontent.com)
Use distinct fixed values, or append a different fixed suffix for each role. Keep the generated paths if they are useful.
277-281: Minor · Data Integrity & Integration · Quick win
Do not return Saved for a branch that does not exist.
If the document branch is absent and the draft matches main, base() supplies the main commit. This branch deletes the draft and returns Saved with that ID, but it never creates the document branch. The caller receives an ID that the target branch does not point at. (raw.githubusercontent.com)
Distinguish an unchanged existing target from a missing target. If a no-op must not push, return an explicit no-target result and keep the draft. Keep the current no-op success for an existing target.
git-store/doc/LogMessages.adoc: 1
29-29: Minor · Maintainability & Code Quality · Heavy lift
Derive the catalogue entries from the log declarations.
This table manually mirrors the identifiers and templates in GitStoreLogMessages. A new declaration can be omitted from the catalogue. Generate these fields from the declarations while retaining the descriptions separately. (raw.githubusercontent.com)
As per path instructions: “Treat a hardcoded list that must mirror a set defined elsewhere … as a defect unless it is derived from that source at build or run time.”
159-160: Minor · Functional Correctness · Quick win
Do not treat a skipped collection as successful expiry.
If an interrupted collection leaves a recent gc.pid, JGit 7.8.0 skips collection for up to twelve hours. GarbageCollectCommand.call() still returns normally. This code then returns OK, although the deleted drafts' objects remain. (raw.githubusercontent.com)
Detect this deferred collection and return a non-success that permits retry. Add a recent-gc.pid case alongside the exception test.
Assert the exact author and committer names on written commits.
These checks can pass if the write path swaps the author and committer names or reuses the first author's pseudonym for the second draft. Retain the expected pseudonym for each commit and the technical-user name. Assert both fields with email disabled and enabled.
Based on learnings, identity-sensitive tests should assert “the actual field(s) that determine the resulting identity,” not only adjacent metadata.
Also applies to: 330-331
Source: Learnings
Review info
Run configuration
Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Central YAML; Path: .coderabbit.yaml
Review profile: CHILL
Plan: Advanced
Run ID: 54b2e1b5-ff52-47fa-907d-b9ae2f17c340
Commits
Reviewing files that changed from the base of the PR and between e0a8c5b and 3237a26.
Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.
…eview
- Run the draft expiry deletes and the garbage collection together under the
exclusive side of the maintenance lock; never write a root commit for a draft
deleted beneath a write; publish a first draft commit only after it is written;
treat a LOCK_FAILURE of the publication as a retry, not as proof of a draft.
- Capture the draft commit once per save, prune mirrored references the remote
deleted (new FetchInput.prune in git-core), keep an accepted save Saved when
the local branch cannot move, detect file/directory overlaps as conflicts,
replay a kept newer draft only with what it changed since (refs/applied/),
and do not report Saved for a draft without changes and without a target.
- Refuse a reused clone whose remote is not the registered one; share one
RepositoryGuard per clone path across all writers of the JVM.
- Report a garbage collection skipped for a held gc.pid as CONFLICT; log only
exception classes; new GIT_STORE-103 and GIT_STORE-104.
- Tests: regression tests for every scenario, a bounded teardown for the
concurrency test, the Sonar S1130/S5778/S135/S4449 findings, exact commit
identity names, distinct fixture contents, and a catalogue check of
LogMessages.adoc against GitStoreLogMessages.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
…ts-save
Narrow two constants of DraftExpiry that are used only inside the class to private.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
Files skipped from review as they are similar to previous changes: 1
git-store/doc/LogMessages.adoc
Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.
In reply to comment_id: PRR_kwDOVwLcIM8AAAABZeFfMw
Will be addressed by TASK-17: the minor and nitpick comments of this review are applied one by one (documentation, debug logging, draft publication order, skipped garbage collection, missing target branch, test assertions and fixtures); the log catalogue is covered by a test instead of being generated; see follow-up commit on this branch
Walkthrough summary, re-opened by an edit for the new head. Its merge-risk items (draft-pruning scope, same-draft save serialization, skipped garbage collection reported as success) are the three inline comments, handled in their own threads. Nothing further to act on here
In reply to comment_id: PRR_kwDOVwLcIM8AAAABZeXOYg
Review summary with 3 actionable comments; each is handled in its own thread (DraftExpiry gc skip, ExplicitSave same-draft serialization, ExplicitSave pruning scope). Nothing further to act on here
…began as CONFLICT
The expiry checked gc.pid before calling JGit, so a collection another
process started in between was skipped by JGit without an error and
reported as a successful expiry. The pre-check is dropped: the expiry
now gives GarbageCollectCommand a progress monitor, which JGit 7.8.0
GC.doGc starts only after it took gc.pid, and a monitor never started
ends the expiry in CONFLICT (PR 48 review).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
… fetch in the mirrored namespaces
A second save of one draft could read the draft and its applied-draft
reference while the first save was between push and settlement, and
then replay the first save's changes. RepositoryGuard now holds one
lock per draft reference, taken by ExplicitSave after the shared side
of the maintenance lock and before the transport lock, so a save reads
its snapshot only after every earlier save of the draft has settled.
The pruning fetch of a save passed an empty refspec list, so JGit used
the clone's stored fetch refspecs and a reused clone with a broader one
such as +refs/*:refs/* lost its drafts. The save now passes the mirror
refspecs explicitly; JGitRepositoryOperations.MIRROR_FETCH_REF_SPECS is
public in git-core as the one source of that set (PR 48 review).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the write path of the
git-storedocument store: per-user drafts, the explicit save with lease, conflict handling per path, concurrent change detection, draft expiry with garbage collection, and the author, committer and credential rules. The spec for this work is PLAN-08 of the epic libraries-initial-implementation (GDR-STORE-2/3/4/5/7/8, GDR-NFR-2).Intent
The store could read and register repositories but not write documents. This change adds the write path: users keep per-user drafts on references that are never pushed, and an explicit save squashes a draft into one commit on the remote tip, pushed with a lease and re-applied up to a bounded number of attempts, so concurrent writers on one branch all succeed and two writers on one file produce exactly one save and one conflict.
Everything stays in
git-store;git-coreis used as it is (push with lease, compare-and-swap, in-core writing and merging) and gains no code. The in-process garbage collection after draft expiry sets the prune expiry to now in the clone's own configuration and runs under an exclusive lock, so no concurrent save can lose an object it still needs. By decision of the owner, author and committer e-mail addresses are off by default (GDR-NFR-3) and only appear whencommit.emailis switched on; the committer address is then the technical user's configured one, and the author address is supplied by the caller.Non-goals: signing and trailers on the commits (GDR-STORE-12/13, a later plan), any change to
git-core, and any new dependency.Changes
StoreConfiguration:save.max-attemptsnow has an upper bound of 100, so a value such asInteger.MAX_VALUEis refused as malformed (the key is named, the value never). New sectioncommitwithcommit.email(defaultfalse): author and committer carry an e-mail address only when it is set.Ulid,DocumentCollection,DocumentKey,StoreReferences(the push refspec never carriesrefs/drafts/*).StoreWriterwithDraft,TechnicalUser,Authorover the package-privateDraftReferences,RepositoryGuardandCommitIdentities.ExplicitSaveandSaveResult(fetch, one commit on the remote tip, push with lease, re-apply up tosave.max-attempts, then move the local branch and compare-and-delete the draft; conflicts name every path).DraftExpiry(compare-and-delete of stale drafts, then in-process garbage collection under an exclusive lock).GIT_STORE-2/3/4/101/102and their catalogue ingit-store/doc/LogMessages.adoc.doc/specification/git-store.adoc,doc/specification/general.adoc,doc/README.adoc,doc/concepts/module-structure.adoc,AGENTS.md.Test Plan
verify -Ppre-commit, 1027 tests)Related Issues
None.
🤖 Generated with Claude Code
https://claude.ai/code/session_01AEE74wHu5wPeCps7mBQK9N
Summary by CodeRabbit