Enable NullAway static null-safety analysis for util module

[Apisapple]

PR description

This PR enables NullAway static null-safety analysis for the util module as a pilot and fixes all violations surfaced by the check.

Summary of changes

• Enable NullAway at ERROR severity for util production compilation via Error Prone.
• Disable NullAway for util test compilation for this pilot.
• Add dependency verification metadata entries required by NullAway and related transitive artifacts.
• Apply null-safety fixes and JSpecify nullable contracts across util classes, including PlatformDetector, BesuVersionUtils, ExceptionUtils, MemoryBoundCache, RollingFileWriter, and StackTraceMatchFilter.
• NullAway is compiler-only via Error Prone and does not add runtime artifacts to util.

Developer setup

• In IntelliJ, set Build and run using to Gradle so NullAway diagnostics appear during normal IDE builds.
• No additional Gradle wiring is required beyond the current Error Prone plus NullAway setup for this pilot.
• If we expand to other modules later, shared NullAway options can be centralized in a common convention plugin.

Validation

• spotless: ./gradlew spotlessApply
• module build with NullAway: ./gradlew :util:build
• optional broader compile check: ./gradlew build -x test

Fixed Issue(s)

fixes #10004

Thanks for sending a pull request! Have you done the following?

• Checked out our contribution guidelines?
• Considered documentation and added the doc-change-required label to this PR if updates are required.
• Considered the changelog and included an update if required.
• For database changes (e.g. KeyValueSegmentIdentifier) considered compatibility and performed forwards and backwards compatibility tests

Locally, you can run these tests to catch failures early:

• spotless: ./gradlew spotlessApply
• unit tests: ./gradlew build
• acceptance tests: ./gradlew acceptanceTest
• integration tests: ./gradlew integrationTest
• reference tests: ./gradlew ethereum:referenceTests:referenceTests
• hive tests: Engine or other RPCs modified?

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

[Copilot]

These tests hardcode the sentinel string UNKNOWN. Since BesuVersionUtils.UNKNOWN is now a public constant, consider referencing it (e.g., via string concatenation in the regex) to prevent tests drifting if the sentinel value changes.

[Copilot]

These tests hardcode the sentinel string UNKNOWN. Since BesuVersionUtils.UNKNOWN is now a public constant, consider referencing it (e.g., via string concatenation in the regex) to prevent tests drifting if the sentinel value changes.

[Copilot]

These tests hardcode the sentinel string UNKNOWN. Since BesuVersionUtils.UNKNOWN is now a public constant, consider referencing it (e.g., via string concatenation in the regex) to prevent tests drifting if the sentinel value changes.

[Copilot]

The Javadoc no longer matches the method contract: the parameter and return value are now nullable. Update the @param and @return docs to reflect that null is accepted and that the method may return null when passed null.

[Copilot]

This method compiles a regex Pattern on each call. Since the pattern is constant, make it a private static final Pattern to avoid repeated compilation overhead and simplify the method.

[Copilot]

The lazy initialization of mutable static fields is not thread-safe (no synchronization/volatile). With the new UNKNOWN fallback, a thread can observe _os as null during/after another thread’s detect() and return UNKNOWN even though detection will eventually set a real value. Consider making the cached fields volatile and/or synchronizing detect() + reads (or using an initialization-on-demand holder) to ensure safe publication and consistent results under concurrency.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

[Copilot]

org.jspecify.annotations.Nullable is now part of util’s public API surface (annotations appear in public method signatures/fields). Using compileOnly means downstream modules/consumers may not have the annotation type available on their compile classpath, which can break static analysis tooling and (depending on build tooling) compilation when reading annotated signatures. Prefer compileOnlyApi 'org.jspecify:jspecify' (with the java-library plugin) so consumers get the annotation on their compile classpath without adding a runtime dependency.

Suggested change

	compileOnly 'org.jspecify:jspecify'
	compileOnlyApi 'org.jspecify:jspecify'

[Copilot]

The builder setter setStackContains(@Nullable String) allows explicitly passing null, but build() then unconditionally fails via requireNonNull. This makes the API easier to misuse and shifts validation to a later point. Consider making the setter parameter non-null (and annotating it accordingly), or validate immediately in setStackContains (e.g., requireNonNull(text, ...)) so failures are earlier and closer to the source of the misuse.

Suggested change

	public StackTraceMatchFilter.Builder setStackContains(final @Nullable String text) {
	this.stackContains = text;
	public StackTraceMatchFilter.Builder setStackContains(final String text) {
	this.stackContains = Objects.requireNonNull(text, "stackContains must be provided");

[Copilot]

The builder setter setStackContains(@Nullable String) allows explicitly passing null, but build() then unconditionally fails via requireNonNull. This makes the API easier to misuse and shifts validation to a later point. Consider making the setter parameter non-null (and annotating it accordingly), or validate immediately in setStackContains (e.g., requireNonNull(text, ...)) so failures are earlier and closer to the source of the misuse.

[Copilot]

Wrapping a directory-creation IOException as a FileNotFoundException is a bit misleading (the directory may be unreadable, permission denied, invalid path, etc., not “file not found”). If the constructor/method signature allows, prefer throwing IOException directly (or UncheckedIOException if you can’t). If you must keep FileNotFoundException, consider using a message that clearly indicates this is a directory creation failure and ensure callers can still distinguish it (e.g., via a dedicated exception type or documented cause inspection).

[Copilot]

These tests interpolate BesuVersionUtils.UNKNOWN directly into a regex. Today it’s safe ("UNKNOWN"), but if the sentinel ever changes to contain regex metacharacters, these patterns will become brittle. Wrapping the interpolated token with regex quoting (e.g., Pattern.quote(...)) would make the tests resilient to future sentinel changes.

[Copilot]

These tests interpolate BesuVersionUtils.UNKNOWN directly into a regex. Today it’s safe ("UNKNOWN"), but if the sentinel ever changes to contain regex metacharacters, these patterns will become brittle. Wrapping the interpolated token with regex quoting (e.g., Pattern.quote(...)) would make the tests resilient to future sentinel changes.

[Copilot]

These tests interpolate BesuVersionUtils.UNKNOWN directly into a regex. Today it’s safe ("UNKNOWN"), but if the sentinel ever changes to contain regex metacharacters, these patterns will become brittle. Wrapping the interpolated token with regex quoting (e.g., Pattern.quote(...)) would make the tests resilient to future sentinel changes.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

util/src/main/java/org/hyperledger/besu/util/BesuVersionUtils.java:87

• The Javadoc for shortVersion() claims it returns strings like \"v23.1.0\", but (based on the ethstats format/tests using /v as a prefix) shortVersion() is likely intended to return the version without a leading v. Please update the examples/wording to match the actual format (e.g., \"23.1.0\" / \"23.1.1-dev-ac23d311\"), while keeping the UNKNOWN part.

  /**
   * Generate version-only Besu version
   *
   * @return Besu version in format such as "v23.1.0" or "v23.1.1-dev-ac23d311", or {@value
   *     #UNKNOWN} if not available
   */
  public static String shortVersion() {
    return VERSION;
  }

[Copilot]

The regex change from [0-9] to [\\d] is both redundant (a character class around \\d isn’t needed) and subtly changes matching semantics (Unicode digits vs ASCII digits). If the intent is to parse glibc versions, consider reverting to [0-9] (original behavior) or using \\d without square brackets if Unicode digits are explicitly desired.

Suggested change

	final Pattern pattern = Pattern.compile("[-+]?[\\d]*\\.?[\\d]+");
	final Pattern pattern = Pattern.compile("[-+]?[0-9]*\\.?[0-9]+");

[siladu]

Kind of agree with copilot on this but I'm not sure there's any noticeable difference, so it's a nitpick, won't request another review cycle for just this.

[Apisapple]

@siladu I've incorporated all the feedback you provided.
I'd be grateful if you could review the updates when you get a chance.

[siladu]

Tested happy path version string in:

• startup logs
• VERSION_METADATA.json
• RPCs
• evmtool
• docker tag
• docker startup logs
• docker with custom version ./gradlew testDocker -Prelease.releaseVersion=26.x.x -Pversion=26.x.x

Have not tested plugins or variations where parts of the version might be null/unknown.

Looking good 🎉 Just a couple of nitpicks left for me so feel free to ignore. Will merge PR tomorrow if no further changes/comments.

[siladu]

nit: think I still prefer compileOnly since I expect every module to eventually add this anyway. Is there a reason I've missed why compileOnlyApi is better?

[Apisapple]

Thank you for the review. I decided to keep compileOnlyApi for now, as it is currently used only in the util module. Adding compileOnly manually to every module could lead to omissions, so I felt this was the safer choice at this stage. Once all modules adopt it consistently, we can switch to a shared compileOnly configuration.

[Apisapple]

I’ve verified that updating the section you pointed out to compileOnly does not cause any issues during the build.

[siladu]

it is currently used only in the util module

that's not the case, we have it in a few places already after your first PR.
I'm trying to avoid relying on transitive but I do see some advantages to compileOnlyApi.
However, my main concern is a consistent approach and currently it is mixed.

[Apisapple]

Thanks for raising this. I agree that we currently have a mixed approach (api / compileOnly / compileOnlyApi) for org.jspecify:jspecify.

To keep the scope of this PR focused, I suggest addressing JSpecify dependency consistency in a dedicated follow-up PR. In that PR, we can update all modules in one pass based on an agreed rule (for example, avoiding transitive dependencies and requiring explicit declarations, with documented exceptions).

[Apisapple]

If the changes needed this time are small, I can update the current compileOnlyApi entries to compileOnly and submit the PR again.

[siladu]

nit: technically this can result null as well so it's either missing a method annotation or a fallback to "unknown".
Not a blocker as ending up with "null" in the version string isn't the end of the world.