[build] Shaded fat-JARs (fluss-client, fluss-flink, etc.) leak shaded module-info.class, breaking JPMS modular consumption
- Dominant language
- Java
- Stars
- 2.1k
- Forks
- 625
- Avg merge
- 3d 14h
- Merged PRs (30d)
- 97
Description
### Search before asking
- [x] I searched in the [issues](https://github.com/apache/fluss/issues) and found nothing similar.
### Fluss version
main (development)
### Please describe the bug 🐞
## Problem Summary
All shaded uber-JARs produced by Fluss (e.g. `fluss-client`, `fluss-flink-1.20`, `fluss-flink-1.19`, `fluss-server`) currently embed `META-INF/versions/9/module-info.class` originating from shaded dependencies (such as `commons-lang3:3.18.0` and `fluss-shaded-jackson`).
As a result, on Java 9+, the Java Platform Module System (JPMS) treats these shaded JARs as the named module `org.apache.commons.lang3` rather than deriving an automatic module (e.g. `fluss.client`, `fluss.flink`).
## How to Reproduce
Run `jar --describe-module` on any built shaded JAR (e.g., `fluss-client` or `fluss-flink-1.20`):
```bash
jar --describe-module --file=fluss-client-1.0-SNAPSHOT.jar --release 21
```
**Actual Output:**
```text
releases: 9
org.apache.commons.lang3@3.18.0 jar:file:///.../fluss-client-1.0-SNAPSHOT.jar!/META-INF/versions/9/module-info.class
exports org.apache.commons.lang3
exports org.apache.commons.lang3.arch
...
requires java.base mandated
requires java.desktop
```
Notice that:
1. The entire Fluss JAR is identified as module `org.apache.commons.lang3`.
2. None of the `org.apache.fluss.*` packages are exported.
## Impact on Downstream Projects
Downstream projects using the Java Module System (`module-info.java`) cannot access any Fluss APIs (`org.apache.fluss.client.*`, `org.apache.fluss.flink.*`, `org.apache.fluss.config.*`) without manually configuring awkward compiler flags such as:
`--add-exports org.apache.commons.lang3/org.apache.fluss.client=`
### Solution
## Solution Details
In the root `pom.xml`, configure the global `maven-shade-plugin` filter (`*`) to exclude all `module-info.class` and multi-release `module-info.class` files:
```xml
*
...
module-info.class
META-INF/versions/**/module-info.class
...
```
This is the standard pattern used across Apache projects (Flink, Spark) when bundling shaded dependencies into uber-JARs.
## Local Validation
I have tested this fix across multiple modules:
- `fluss-client` now correctly derives `fluss.client@1.0-SNAPSHOT automatic` with all packages exported.
- `fluss-flink-1.20` correctly derives `fluss.flink@1.20-1.0-SNAPSHOT automatic`.
- `fluss-server` correctly derives `fluss.server@1.0-SNAPSHOT automatic`.
- Spotless formatting (`mvn spotless:check`) and Checkstyle pass cleanly.
I have this fix ready and tested locally, and would be very happy to submit a Pull Request if the maintainers approve this approach.
### Are you willing to submit a PR?
- [x] I'm willing to submit a PR!
Contributor guide
No contributing guide indexed for this repository
Research direction
Open the root pom.xml and inspect the global maven-shade-plugin filter used for shaded JARs. Build a representative artifact such as fluss-client, then run jar --describe-module --file=... --release 21 to verify that dependency module-info.class files are no longer embedded and the Fluss packages are available through an automatic module.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- build-system
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100