docs(ermitegit): document negative MaxObjectSize and which writes refresh at once

commit: b42de979c3a2b7b0db2f5456396030d50462b9da
author: brice · 11d ago · 2026-10-11 02:08 UTC
parent: 23f3a22
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +9 -7

M internal/adapters/ermitegit/ermitegit.go +6 -5


@@ -22,10 +22,10 @@
22	22		// The adapter still calls Refresh to release replaced packs, pick up a new
23	23		// commit-graph and notice a repository that stopped being supported: at once
24	24		// when ermite itself wrote (the push and the maintenance tell it through
25		-	// Refresh), and as a safety net at most once per Config.RefreshEvery for each
26		-	// repository while it is read, by one reader at a time. A Refresh
27		-	// stats the files of the repository, too much to pay on every read of a
28		-	// method that itself costs 2 µs.
	25	+	// Refresh; a merge request merge waits for its maintenance), and as a safety
	26	+	// net at most once per Config.RefreshEvery for each repository while it is
	27	+	// read, by one reader at a time. A Refresh stats the files of the repository,
	28	+	// too much to pay on every read of a method that itself costs 2 µs.
29	29		//
30	30		// Memory: the cache of open repositories is bounded (LRU) and drops the ones
31	31		// idle longer than Config.IdleTTL; each repository holds at most

@@ -127,7 +127,8 @@ type Config struct {
127	127		DeltaCacheSize int64
128	128		// MaxObjectSize is the size in bytes above which an object that must be
129	129		// held in memory is read by the wrapped reader instead. Zero means
130		-	// DefaultMaxObjectSize.
	130	+	// DefaultMaxObjectSize; a negative value means the library default
	131	+	// (128 MiB).
131	132		MaxObjectSize int64
132	133		// Routes overrides DefaultRoutes when not nil.
133	134		Routes *Routes

 // The adapter still calls Refresh to release replaced packs, pick up a new
 // commit-graph and notice a repository that stopped being supported: at once
 // when ermite itself wrote (the push and the maintenance tell it through
-// Refresh), and as a safety net at most once per Config.RefreshEvery for each
+// Refresh; a merge request merge waits for its maintenance), and as a safety
-// repository while it is read, by one reader at a time. A Refresh
+// net at most once per Config.RefreshEvery for each repository while it is
-// stats the files of the repository, too much to pay on every read of a
+// read, by one reader at a time. A Refresh stats the files of the repository,
-// method that itself costs 2 µs.
+// too much to pay on every read of a method that itself costs 2 µs.
 //
 // Memory: the cache of open repositories is bounded (LRU) and drops the ones
 // idle longer than Config.IdleTTL; each repository holds at most
 	DeltaCacheSize int64
 	// MaxObjectSize is the size in bytes above which an object that must be
 	// held in memory is read by the wrapped reader instead. Zero means
-	// DefaultMaxObjectSize.
+	// DefaultMaxObjectSize; a negative value means the library default
+	// (128 MiB).
 	MaxObjectSize int64
 	// Routes overrides DefaultRoutes when not nil.
 	Routes *Routes

M internal/app/pushes.go +3 -2


@@ -127,8 +127,9 @@ func (u *Pushes) Check(ctx context.Context, p domain.Principal, name domain.Repo
127	127
128	128		// Record is the post-receive step of an accepted push: it sets pushed_at,
129	129		// repairs HEAD when it points to a missing branch, tells the reader that the
130		-	// repository changed, publishes a PushEvent and schedules maintenance. Every step runs even when an earlier one fails; the
131		-	// failures are returned together and the push itself is not affected.
	130	+	// repository changed, publishes a PushEvent and schedules maintenance. Every
	131	+	// step runs even when an earlier one fails; the failures are returned together
	132	+	// and the push itself is not affected.
132	133		func (u *Pushes) Record(ctx context.Context, p domain.Principal, name domain.RepoName, updates []domain.RefUpdate) error {
133	134		log := zerowrap.FromCtx(ctx)
134	135		now := u.clock.Now().UTC()

 // Record is the post-receive step of an accepted push: it sets pushed_at,
 // repairs HEAD when it points to a missing branch, tells the reader that the
-// repository changed, publishes a PushEvent and schedules maintenance. Every step runs even when an earlier one fails; the
+// repository changed, publishes a PushEvent and schedules maintenance. Every
-// failures are returned together and the push itself is not affected.
+// step runs even when an earlier one fails; the failures are returned together
+// and the push itself is not affected.
 func (u *Pushes) Record(ctx context.Context, p domain.Principal, name domain.RepoName, updates []domain.RefUpdate) error {
 	log := zerowrap.FromCtx(ctx)
 	now := u.clock.Now().UTC()