feat(cmd): default db-max-handles to half of the process fd limit

[infrmtcs-agent]

Summary

• Default db-max-handles to half the process's open file descriptor limit instead of a fixed value
• Add a utils helper to read the fd limit, with a test
• Add tests covering the new default in cmd/juno

[codecov]

Codecov Report

❌ Patch coverage is 69.23077% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.32%. Comparing base (afd490f) to head (20cd3ca).

Files with missing lines	Patch %	Lines
cmd/juno/juno.go	75.00%	1 Missing and 1 partial ⚠️
utils/fdlimit.go	60.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3919      +/-   ##
==========================================
- Coverage   75.50%   75.32%   -0.18%     
==========================================
  Files         450      451       +1     
  Lines       40464    40476      +12     
==========================================
- Hits        30552    30490      -62     
- Misses       7818     7886      +68     
- Partials     2094     2100       +6     

Flag	Coverage Δ
jsonv2	77.42% <ø> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[brbrr]

@claude can you review this PR?

[github-actions]

Claude finished @infrmtcs's task in 7m 2s —— View job

---

Review: default db-max-handles to half the fd limit

• Read the diff and gather context
• Check portability / platform constraints of the new syscall usage
• Check bounds & overflow behaviour of the new default
• Check tests and docs generation
• Post review

The direction is right and matches what geth does. Four inline comments posted; no blockers.

Important

• cmd/juno/juno.go:724 — dbMaxHandlesForFDLimit has no ceiling. With an unlimited RLIMIT_NOFILE (LimitNOFILE=infinity, docker --ulimit nofile=-1) lim.Cur is RLIM_INFINITY-1, so this returns math.MaxInt64 into pebble.Options.MaxOpenFiles and the file cache never evicts. Suggested clamp inline. The same expression also can't clamp down: below a 2048 fd limit the 1024 floor wins and the DB is allowed as many handles as the whole process, contradicting the "leaving the rest for HTTP, p2p" comment.
• cmd/juno/juno_test.go:73 — expecting juno.DefaultDBMaxHandles() compares the default against itself, so all 12 sub-tests pass no matter what that function returns, and the expected config becomes machine-dependent. TestDBMaxHandlesForFDLimit already covers the maths hermetically.

Nit

• utils/fdlimit.go:5 — the runtime raises the soft limit to Max - 1, not Max, and darwin caps it further via adjustFileLimit; also the file has no //go:build unix tag despite using syscall.RLIMIT_NOFILE.
• docs/generate-config.js:103 — the committed docs/docs/_config-options.md:88 still shows 1024 and the old description. The generator change itself parses correctly.

Also minor: utils/fdlimit_test.go only asserts the result is positive, so it would pass against a hard-coded return — fine as a smoke test, but it's not verifying much.

Verified: golangci-lint and Dependency Review are green on this head; go vet ./utils/ passes locally. I could not run go test (command not permitted in this environment) — the Juno Test workflow was still in progress when I reviewed. G115 is globally excluded in .golangci.yaml, so lint won't flag the uint64→int conversion.
· branch dat/fd-limit-default

[github-actions]

Claude finished @infrmtcs's task in 8m 40s —— View job

---

Re-review: default db-max-handles to half the fd limit

• Read the updated diff vs dat/claude-review-bot-denylist
• Check which of the 4 earlier findings were addressed
• Look for new issues on this head
• Build / vet / lint
• Post review

The force-push addressed most of my earlier round. No blockers. Three inline comments, all non-blocking.

Resolved since the last review

• Ceiling added. dbMaxHandlesCeiling = 1_048_576 with max(int(min(fdLimit/2, ceiling)), floor). I traced the typing: the untyped const converts up, so min evaluates in uint64 and the result is always in [1024, 1_048_576] — the int() conversion is now provably safe even on 32-bit, so the G115 truncation caveat is moot. Table cases for math.MaxUint64 and MaxUint64-1 are there, and all 9 cases check out by hand.
• Tautological test fixed. juno_test.go:77 now re-derives the formula from its own literals instead of calling the production function, so a change to the production formula does fail the test. (Trade-off noted inline.)
• DefaultDBMaxHandles un-exported — the only reason it was exported is gone.
• Docstring corrected to "raises it close to the hard limit at startup".
• Generated docs updated. I traced preprocessCodebase over the new multi-line const: the " + continuation merges and the "" seam collapses to exactly the committed description, and variables["defaultDBMaxHandles()"] is undefined so the line-106 override supplies the default. The committed table matches what the generator produces. Worth noting the generator fetches juno.go from main, not the working tree — so hand-editing the generated file was the right call here, and it'll be self-consistent once this merges.

Important

• cmd/juno/juno.go:714 — a tuning judgment, not a bug. At 1,048,576 the ceiling only clamps when the fd limit is ≥ 2M, i.e. effectively never; a host with the common systemd LimitNOFILE=524288 goes 1024 → 262144 (256×). That feeds pebble's file-cache capacity (FileCacheSize = MaxOpenFiles - 10, against a pebble default of 1000), which is an eviction limit rather than a preallocation — so no upfront cost, but the steady state becomes "every sstable touched stays open", making RSS a function of the host's ulimit -n. Worth confirming 1M is deliberate. Also folded in: the 1024 floor still hands a nofile=1024 container the whole process budget (now disclosed as "min 1024", so a documented choice), and the MaxFDLimit error is swallowed silently.

Nits

• utils/fdlimit.go:1 — still no build constraint, and this repo already has the pattern for it: starknet/compiler/rlimit_linux.go / rlimit_other.go, using golang.org/x/sys/unix (already a direct dep) rather than the frozen syscall. Pins the widely imported utils package to unix.
• cmd/juno/juno.go:234 — 1024/1048576 are now hard-coded in four places (two consts, the usage string, generate-config.js:106, juno_test.go:77) with nothing tying them together.

Verified

golangci-lint and Dependency Review are green on this head (57f31ce) — that confirms the drive-by move of //nolint: gosec from a trailing comment to a doc comment above gwAPIKeyUsage still suppresses G101 and satisfies nolintlint, which was the one thing in this revision that could have silently regressed. go vet ./utils/ ./cmd/juno/ is clean locally. I could not run go test (command not permitted in this environment) — Juno Test was still in progress when I reviewed, so the new TestDBMaxHandlesForFDLimit and the reworked TestConfigPrecedence are unverified by execution on my side; I checked all 9 table cases by hand instead.

Note the diff also carries core/felt, rpc/v8–v10 and jsonrpc changes — those are commit e22b565 (#3881, already merged) showing up because the base branch dat/claude-review-bot-denylist predates it. Not part of this PR; not reviewed.
· branch dat/fd-limit-default

[github-actions]

Claude finished @infrmtcs's task in 5m 5s —— View job

---

Re-review: default db-max-handles to half the fd limit

• Read the new head's diff vs dat/claude-review-bot-denylist
• Check which prior findings changed on this push
• Look for new issues
• Build / vet / lint
• Post review

This push contains no code changes — it's a rebase. All seven changed files are byte-identical to the head I reviewed at 06:57 (blob hashes 6e7db84 / 810afdb / f44df2b / 5babd3c / dda7c0b / 593110d / cbd3fd8 all match), and HEAD~1 is now exactly 50857d76, the base branch tip. One useful side effect: the diff no longer carries the unrelated core/felt / rpc/v8–v10 / jsonrpc changes from #3881 that the stale base was dragging in, so what's on screen is now just this feature. No new findings, no blockers.

Status of the earlier rounds

Everything from round 1 is resolved (ceiling clamp, tautological test, un-exporting defaultDBMaxHandles, docstring, regenerated docs). The three round-2 nits have replies, and all three are recorded as deliberate:

Item	Author's position
Ceiling magnitude (1_048_576)	Deliberate — never-evicting is desirable
No //go:build unix on utils/fdlimit.go	Deliberate — only linux/darwin are supported targets
1024/1048576 duplicated across four sites	Known trade-off; generator regex + package boundary make the alternatives worse

Those are all judgment calls in your area, and you've now reaffirmed each — treating them as settled and not re-raising them. One factual footnote on the first, for the record rather than as a request: pebble's MaxOpenFiles is a file-cache eviction limit, not RocksDB's max_open_files (which additionally gates index/filter preloading), so the two knobs aren't quite the same lever — but the shape of the decision (unbounded-by-default, derived from the ulimit) is well-precedented, and the "min 1024, max 1048576" disclosure in the usage string and docs means an operator can see what they're getting. Your call, and it's documented.

Fresh checks on this head

Since the content is unchanged I re-verified the parts most likely to break silently rather than re-reading what I'd already confirmed:

• Only one consumer. cfg.DBMaxHandles reaches exactly one pebblev2.New call (node/node.go:221) — no second store that would double-count the fd budget, and nothing anywhere compares DBMaxHandles against the old 1024 to infer "unset", so making the registered default machine-dependent can't perturb precedence logic.
• No later RLIMIT_NOFILE mutation. The only Setrlimit calls in the tree are RLIMIT_CPU/RLIMIT_AS in starknet/compiler/rlimit_linux.go, so nothing raises the nofile limit after NewCmd computes the default — the value read at flag-registration time is the one that stays true.
• Package layout is right. juno_internal_test.go as package main sits correctly alongside the existing package main_test files (compile_test.go, dbcmd_test.go, usage_test.go follow the same split), so the unexported dbMaxHandlesForFDLimit and defaultMaxHandles are reachable without exporting anything.
• All 9 table cases re-checked by hand, and the typing argument holds: min(fdLimit/2, dbMaxHandlesCeiling) evaluates in uint64 (untyped const converts up), result is always in [1024, 1_048_576], so int(...) cannot truncate even on a 32-bit target.

Verified

golangci-lint ✅ and Dependency Review ✅ are green on this head. go vet ./utils/ ./cmd/juno/ is clean locally — that type-checks the new test files too, so TestDBMaxHandlesForFDLimit and the reworked TestConfigPrecedence at least compile. I still could not run go test (command not permitted in this environment), and Juno Test was in progress when I reviewed, so execution of the new tests remains unverified on my side — worth a glance at that run before merging. Given the rebase, though, this content already passed a full CI cycle on the previous head.
· branch dat/fd-limit-default

[github-actions]

Claude finished @infrmtcs's task in 7m 3s —— View job

---

Re-review: default db-max-handles to half the fd limit

• Read the new head's diff and compare against the previously reviewed head
• Check which prior findings changed on this push
• Look for new issues
• Build / vet / lint
• Post review

This push is another rebase — no code changes. HEAD~1 moved from 50857d76 to 324a00669 (#3926 landed, so the old base branch dat/claude-review-bot-denylist is now just main), and all seven blobs are byte-identical to the head I reviewed at 06:57 and 07:36 (6e7db84 / 810afdb / f44df2b / 5babd3c / dda7c0b / 593110d / cbd3fd8). Everything from rounds 1–3 stands as previously recorded: the ceiling clamp, hermetic table test, un-exported defaultDBMaxHandles, corrected docstring and regenerated docs are all in; the three round-2 nits (ceiling magnitude, no build tag, duplicated literals) you marked deliberate, and I'm treating those as settled.

Important

• utils/fdlimit.go:12 — one new question, and it decides whether the feature does anything. The default rests entirely on syscall.Getrlimit(RLIMIT_NOFILE) reporting the soft limit after the runtime's startup raise. syscall's unix init saves the pre-raise soft limit in origRlimitNofile for os/exec to restore in children; whether the exported Getrlimit also masks rlim.Cur with that saved value on go 1.26.0 is the part I could not verify here (no toolchain source or network, and go doc/go run/go test aren't permitted in this environment) — so it's a question, not a finding. If it is masked, then on the very common soft=1024, hard=1048576 shape MaxFDLimit() returns 1024, max(512, 1024) gives 1024, and the new default is byte-for-byte the old constant — a silent no-op on exactly the hosts this targets. Critically, no test would catch that: TestDBMaxHandlesForFDLimit never calls MaxFDLimit, TestMaxFDLimit only asserts Positive, and juno_test.go:77 re-derives from whatever MaxFDLimit returns, so it agrees either way. Inline comment has a 6-line program to settle it, plus a lim.Max variant that's correct under both semantics (the runtime never modifies Max, and RLIM_INFINITY is already absorbed by dbMaxHandlesCeiling).

No other new findings, and no blockers.

Fresh checks on this head

Since the content is unchanged, I re-verified things a rebase or a machine-dependent default could plausibly disturb, rather than re-reading what I'd already confirmed:

• No golden help-text assertion. cmd/juno/usage_test.go only checks flag categorisation and the presence of category headers — it never asserts on cobra's (default N) text, so a default that varies by host can't break it. Nothing else in the tree compares DBMaxHandles against 1024.
• The green Test Documentation Build does not validate this branch's generator. docs/package.json:8 runs node generate-config.js && docusaurus build, and the generator fetches cmd/juno/juno.go from raw.githubusercontent.com/.../juno/**main**/... (generate-config.js:309) — so the CI build regenerated the table from main's juno.go, not the working tree, and the build doesn't diff the result. The keyed db-max-handles override at line 105 fires regardless of source, but the description column came from main's old one-liner. So that check being green says nothing either way about the committed table; the hand-edit was still the right call, and it becomes self-consistent on merge, when the deploy build regenerates from the merged main.
• Versioned docs correctly untouched. docs/versioned_docs/version-0.9.3 … version-0.16.0 still show 1024; those are historical snapshots, so leaving them is right.
• No repo-level fd configuration. Grepping for nofile/LimitNOFILE/ulimit finds only the RLIMIT_CPU/RLIMIT_AS test helpers in starknet/compiler — no k8s manifest, systemd unit, or Dockerfile in-tree sets nofile. The new default is therefore driven entirely by the operator's environment, which is what makes the Cur-vs-Max question above load-bearing.

Verified

golangci-lint ✅, CodeQL ✅, Dependency Review ✅, Test Documentation Build ✅ and Code Quality ✅ are green on this head; Juno Test, Container Security and Deploy and Test on Dev were still in progress when I reviewed. go vet ./utils/ ./cmd/juno/ is clean locally, which type-checks the new test files. I still could not run go test (command not permitted here), so execution of TestDBMaxHandlesForFDLimit, TestMaxFDLimit and the reworked TestConfigPrecedence remains unverified on my side — worth a glance at the Juno Test run before merging, though this exact content already passed a full cycle on the pre-rebase head. I checked all 9 table cases by hand again and the typing argument holds: min(fdLimit/2, dbMaxHandlesCeiling) evaluates in uint64, result always in [1024, 1_048_576], so int(...) cannot truncate even on 32-bit.
· branch dat/fd-limit-default

[github-actions]

Claude finished @infrmtcs's task in 10m 8s —— View job

---

Re-review: default db-max-handles to half the fd limit

• Diff the new head against the previously reviewed head
• Check which prior findings this push addresses
• Verify the regenerated docs row against the generator
• Look for new issues
• Build / vet / lint / CI
• Post review

One blocker, and it's a CI failure rather than a logic problem. This push is a cleanup round; the feature itself is unchanged from the head I reviewed on Aug 11.

What changed on this push

Four of the seven files moved (generate-config.js, utils/fdlimit.go, utils/fdlimit_test.go are byte-identical to the previously reviewed head):

• defaultMaxHandles → defaultDBMaxHandlesFloor, and dbMaxHandlesCeiling → defaultDBMaxHandlesCeiling, both now in the main const block — addressing @EgeCaner's rename request. All references updated; grep finds no stale defaultMaxHandles outside juno_test.go's own local variable.
• Docs "Default" column now shows the formula rather than being blank: half of process fd limit (min 1024, max 1048576). I traced this end to end — variables["defaultDBMaxHandles()"] is undefined → "", the keyed override at generate-config.js:105 supplies the string, and formatDefault wraps it in backticks. The committed row in docs/docs/_config-options.md:88 matches character-for-character, and the style matches the existing max-vms → 3 * CPU Cores precedent. The preprocessCodebase merge of the new two-line dbMaxHandlesUsage also still produces exactly the committed description (the " "/"" seam collapses to a single space).
• //nolint: gosec on gwAPIKeyUsage gained an explanation, satisfying nolintlint's require-explanation: true.

Blocker

• cmd/juno/juno.go:234 — golangci-lint fails on this head. The golangci-lint-diffs step reports lll on the 116-char dbCacheSizeUsage line, which this PR doesn't touch; it's attributed to the PR because the const specs below it changed. Note the reported line (237) doesn't match this head (234), which points at the diff-lint's head-vs-merge-checkout coordinate drift rather than a genuine new violation — so a rebase onto current main may clear it by itself. Wrapping the line is the deterministic fix; suggestion inline, and it's docs-neutral.

Nit (no inline comment — @EgeCaner's call)

The rename delivers the Floor/Ceiling pairing that was asked for, but keeps the default prefix that the request specifically wanted dropped ("defaultMaxHandles is no longer a default, it's the clamp floor"). Net effect is that defaultDBMaxHandlesFloor now shares a longer prefix with the function defaultDBMaxHandles() than before, which was the other half of that comment. Cosmetic either way.

Footnote: the Getrlimit question is settled, in your favour

I raised a question on Aug 11 about whether syscall.Getrlimit reports the runtime-raised soft limit or masks it back to the pre-raise value, which you marked "Won't fix". I can now answer it — the runner has the Go 1.26.0 toolchain source on disk, and src/syscall/rlimit.go shows origRlimitNofile is written only by init (before any raise) and by the exported Setrlimit, with the raise itself applied through the unexported setrlimit; the in-source comment states the saved value is consumed in exec_linux.go. So nothing masks lim.Cur, MaxFDLimit() sees the raised limit, and the feature is not a no-op on soft=1024, hard=1048576 hosts. Recording it here so the assumption the default rests on is documented somewhere. (Sandbox rules blocked me from grepping the rest of the package, so this rests on rlimit.go plus that comment rather than an exhaustive check.)

Everything else from rounds 1–4 stands as previously recorded: ceiling clamp, hermetic table test, un-exported defaultDBMaxHandles, corrected docstring, regenerated docs — all in; the build-tag scope and the duplicated 1024/1048576 literals are settled as deliberate and I'm not re-raising them.

Verified

go vet ./utils/ ./cmd/juno/ is clean locally, which type-checks the new test files. All 9 table cases in TestDBMaxHandlesForFDLimit re-checked by hand against the renamed constants, including 2 */4 * defaultDBMaxHandlesCeiling (untyped consts, no overflow) — and the typing argument still holds, so int(...) cannot truncate. CodeQL ✅, Dependency Review ✅, Test Documentation Build ✅, Code Quality ✅; golangci-lint ❌ (above); Juno Test, Container Security and Deploy and Test on Dev were still in progress. I could not run go test (not permitted in this environment), so execution of the tests remains unverified on my side — worth a glance at Juno Test alongside the lint fix.
· branch dat/fd-limit-default

[github-actions]

Claude finished @infrmtcs's task in 6m 59s —— View job

---

Re-review: default db-max-handles to half the fd limit

• Diff the new head against the previously reviewed head
• Check whether the lll blocker from the last round is resolved
• Look for new issues
• Build / vet / lint / CI
• Post review

The blocker is resolved and this head is clean — no new findings, no inline comments. This push is a rebase; the feature content is unchanged from the head I reviewed at 04:02.

The lll blocker is cleared, and the cause is now confirmed

golangci-lint is ✅ green on this head (run 31671395628), including the golangci-lint-diffs step that failed last round. I can now show exactly why it fired, because the base moved by one commit and that commit is the culprit:

git diff e89a546d5 afd490f8d -- cmd/juno/juno.go — i.e. what #3909 did to this file — adds three lines above the usage-const block, all for the new disable-sync flag: disableSyncF (~line 60), defaultDisableSync (~134), disableSyncUsage (~216). So:

	dbCacheSizeUsage at
previously reviewed head (based on e89a546d5)	234
the merge commit actions/checkout actually linted	237

--new-from-patch was fed pull.patch in head coordinates, where this PR's added region was 235–239 — so merge-line 237 landed inside it and a 116-char line the PR never touched got classified as new. That's the coordinate drift I guessed at last round, confirmed with the real numbers (and it also means my "the reported line doesn't match this head" phrasing was backwards — 237 was correct for the checkout being linted, just not for the branch). Now that the branch sits on afd490f8d, head and merge coordinates agree, the added range is 238–242, line 237 is a context line, and the step passes. No change needed; wrapping dbCacheSizeUsage remains optional insurance if it ever recurs.

Closing out the Getrlimit question — fully settled, and Cur is the better choice

I raised this on Aug 11 and partially answered it last round from rlimit.go alone. I can now close it properly: grepping the whole syscall package on the Go 1.26 toolchain source (go.mod says go 1.26.0) shows origRlimitNofile is read in exactly four places — exec_unix.go:286, exec_linux.go:261, the other exec_* variants, and tests — and written only by init, by exported Setrlimit, and by Prlimit-on-self (syscall_linux.go:1314). Getrlimit never consults it. So MaxFDLimit() sees the raised soft limit and the feature is not a no-op on soft=1024, hard=1048576 hosts.

Better still, reading Cur turns out to be more correct than the lim.Max I suggested: rlimit.go:45 ignores the error from setrlimit, and on darwin adjustFileLimit clamps the raise to kern.maxfilesperproc. If the raise fails or gets capped, Getrlimit reports what the kernel actually enforces, whereas Max would over-promise. Your original choice is the right one — withdrawn on both counts.

Fresh checks on this head

• Rebase carried cleanly. git diff origin/main...HEAD is exactly the seven feature files; main's new disable-sync flag didn't leave juno_test.go's expected-config tables stale on this branch.
• Still a single consumer. cfg.DBMaxHandles → pebblev2.WithMaxOpenFiles at node/node.go:243 only. The other pebblev2.New call sites (cmd/juno/dbcmd.go:364, and the tests) pass no MaxOpenFiles, so DB subcommands keep pebble's own default and can't double-count the fd budget.
• go vet ./utils/ ./cmd/juno/ is clean locally (this type-checks both new test files).

Everything from rounds 1–5 stands as recorded: ceiling clamp, hermetic table test, un-exported defaultDBMaxHandles, Floor/Ceiling rename, corrected docstring, regenerated docs row. The build-tag scope and the duplicated 1024/1048576 literals are settled as deliberate, and the remaining defaultDBMaxHandlesFloor naming nit is @EgeCaner's call.

Verified

golangci-lint ✅, CodeQL ✅, Dependency Review ✅, Test Documentation Build ✅, Code Quality ✅ on this head. Juno Test, Container Security and Deploy and Test on Dev were still in progress when I finished — and go test is not permitted in this environment, so execution of TestDBMaxHandlesForFDLimit, TestMaxFDLimit and the reworked TestConfigPrecedence is still unverified on my side; worth a glance at Juno Test before merging, especially since it's the first run of these tests on a base whose juno.go changed. I re-checked all 9 table cases by hand and the typing argument holds — min(fdLimit/2, defaultDBMaxHandlesCeiling) evaluates in uint64, result always in [1024, 1_048_576], so int(...) cannot truncate.
· branch dat/fd-limit-default