Repository navigation
fix(jni): select the native library by OS and architecture - #460
Merged
Merged
Conversation
NativeLibrary.getInstance() returned the first ServiceLoader provider, so with several platform JARs on the classpath the classpath order decided which binary was loaded, and the wrong one failed with UnsatisfiedLinkError. The library could also only be extracted under java.io.tmpdir, which fails on hosts where /tmp is mounted noexec. - Platform providers declare their OS and architecture. The first matching provider is preferred, then the first one declaring nothing (custom or older providers). A clear IllegalStateException lists the providers when none can be used. - com.marcnuri.jkube-helm.nativeLibrary forces a registered provider and com.marcnuri.jkube-helm.tempDir sets the extraction directory. - Add a linux-aarch64 profile, since Linux JVMs report aarch64. - Document how the platform artifact is chosen, cross-building and the new properties in the README, and bump its version to 0.0.22. Fixes #459 Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Marc Nuri <marc@marcnuri.com>
manusa
commented
Nov 15, 2026
manusa
left a comment
Owner
Author
There was a problem hiding this comment.
Review of #460: native library selection by OS/arch (fixes #459)
The change was reviewed in two rounds before the PR was opened. All round-1 findings were addressed in the branch. Line numbers refer to the pre-commit worktree and may differ slightly from the final commit.
Verdict (round 2): approve. No Critical or Important findings remain, and all 7 items of the issue's Proposed fix are delivered.
Round 1: NEEDS_CHANGES (1 Important, 8 Minor)
Important
- An undeclared provider beat a matching one that came later on the classpath. The first version returned the first compatible provider, and a provider that declares no OS/arch (every platform jar up to 0.0.22) counted as compatible everywhere.
- Reproduced on Java 8, Linux x86_64: new
lib-api, thenlinux-arm64-0.0.22.jar, then the newlinux-amd64jar. That selectedhelm-linux-arm64.so, the exact #459 failure. - Realistic trigger: a version-pinned
linux-${arch}dependency plus an upgradedhelm-java. - Resolved: two-pass selection. A declared match is preferred, and the first undeclared provider is only the fallback. Covered by
NativeLibrarySelectorTestand by theMixedVersionscases inNativeLibraryServiceProviderTest.
- Reproduced on Java 8, Linux x86_64: new
Minor. All resolved unless noted.
- Versions. The README presented next-release behaviour under 0.0.22. It is now marked "(since 0.0.23)".
- No remote-jar fallback when local providers exist but none match. Kept by design, and now documented in the README.
- Blank override. A blank
com.marcnuri.jkube-helm.nativeLibrarywas treated as a class name. It is now trimmed and treated as unset, with tests. - Extraction directory.
- The error didn't name the path or property. It now names both, and
InvalidPathExceptionis also caught. - The README now says the directory is created if missing and holds a
helm-java*subdirectory.
- The error didn't name the path or property. It now names both, and
- Override docs. The README now says the forced class must be registered in
META-INF/services. - Test isolation. Tests cleared the system properties instead of restoring them. Values are now saved and restored, and the temp directory is cleaned up.
Platformcoverage. The newPlatformTestcovers Windows 10, Mac OS X, Linux, SunOS and nullos.name, and amd64, x86_64, aarch64, arm64, sparcv9 and nullos.arch.- Release notes.
serviceProviderLibrarycan now throw. This is covered in the PR description.
Round 2: APPROVE
- The
Files.isDirectoryguard inNativeLibrary.createTempDirectory()is justified.- On JDK 1.8.0_512,
Files.createDirectories(link)throwsFileAlreadyExistsExceptionfor an existing symlink to a directory, for example/tmpon macOS. On JDK 21 it succeeds. - With the guard removed,
usesSymbolicLinkToDirectorySetWithSystemPropertyfails on Java 8. The Java 11 macOS and Windows jobs wouldn't catch that, so the comment now says why the guard stays.
- On JDK 1.8.0_512,
- Three optional nits, all applied before the commit:
- README wording for partially declared providers ("declared OS and/or architecture match");
- the symlink test now skips only on
UnsupportedOperationException, or on aFileSystemExceptionon Windows; - the guard's comment.
- Checked and fine:
- partially declared providers never match an unknown OS/arch;
- the override never silently falls back;
- undeclared providers are still listed in the no-match error;
- Java 8 compilation and Javadoc;
- the
linux-aarch64profile is the only active one withos.arch=aarch64, and<name>linux</name>keeps Apple Silicon out; - README and AGENTS.md match the code;
- license headers are present.
- For awareness, not a finding. An old and a new copy of the same platform artifact share one class name, so the old one can shadow the new one. Maven never resolves two versions of one artifact, so only a hand-built or fat-jar classpath can hit this, and no selector change could fix it.
Verified by running (Java 8, Linux x86_64)
lib/api: 34 tests, 0 failures, 0 skipped.- Selected
helm-javatests:NativeLibraryTest,HelmVersionTest(loads the.sothrough the new selection),HelmCreateTest,HelmTemplateTest,HelmLintTest. - The #459 reproduction and the mixed-version case now select
linux-amd64andHelm.version()succeeds. help:active-profileswithos.arch=aarch64.
Not run locally: the KinD tests and the macOS/Windows jobs, which are left to CI.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Fixes #459
Summary
NativeLibrary.getInstance()used the firstServiceLoaderprovider, so with more than one platform JAR on the classpath the classpath order decided which native binary was loaded. Extraction was also tied tojava.io.tmpdir, which fails onnoexecmounts.Selection by OS and architecture.
NativeLibrarygetsgetOs()/getArch()default methods (returningnull), and the five platform providers declare their platform. Selection now works in this order:IllegalStateExceptionnamingos.name/os.archand the providers found.OS/arch detection moves from
RemoteJarLoaderinto a sharedPlatformhelper.System properties. Both follow the existing
com.marcnuri.jkube-helm.*convention:com.marcnuri.jkube-helm.nativeLibrary: fully qualified class name of a registeredNativeLibraryto use regardless of platform. A blank value is ignored.com.marcnuri.jkube-helm.tempDir: base directory for extracting the native library, created if missing (defaults tojava.io.tmpdir).Build. New
linux-aarch64profile, since Linux JVMs reportos.arch=aarch64. It is restricted toos.name=linuxso Apple Silicon Macs (also familyunix) don't pick it up.Docs.
Release notes
NativeLibrary.serviceProviderLibrary(ClassLoader)can now throw anIllegalStateExceptionwhen native library implementations are registered but none can be used on the current platform, or when the class forced withcom.marcnuri.jkube-helm.nativeLibraryisn't registered; before, it always returned the first registered implementation.Testing
lib/apion Java 8: 34 new tests, no mocking library (NativeLibrarySelectorTest,PlatformTest,NativeLibraryServiceProviderTest). They cover:URLClassLoaderwith a wrong-platform provider registered first, and the mixed-version case;helm-javaon Java 8, with the native library built for linux/amd64:NativeLibraryTest(including the remote-JAR tests),HelmVersionTest,HelmCreateTest,HelmTemplateTestandHelmLintTestpass.linux-arm64JAR beforelinux-amd64on the classpath:linux-amd64is now selected andHelm.version()succeeds. The same holds with a 0.0.22linux-arm64JAR first.linux-aarch64is the active profile whenos.arch=aarch64.