Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions SimpleAPI/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,15 @@
<!-- The final artifact deliberately is not multi-release,
so these implementations are unreachable. -->
<exclude>META-INF/versions/**</exclude>
<!-- These compile-time annotations are not runtime services.
Keep the library APIs and all service descriptors. -->
<exclude>org/checkerframework/**</exclude>
<exclude>org/jspecify/**</exclude>
<!-- The shaded distribution is not a JPMS module.
Keep non-POM runtime metadata and all licenses. -->
<exclude>module-info.class</exclude>
<exclude>META-INF/maven/**/pom.xml</exclude>
<exclude>META-INF/maven/**/pom.properties</exclude>
</excludes>
</filter>
</filters>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,16 @@ public static int link() throws Exception {
assertTrue(classPath == null || classPath.isBlank(), "Smoke test must not load external manifest dependencies");
assertFalse(output.stream().anyMatch(entry -> entry.getName().startsWith("org/bouncycastle/")),
"The JDK-only TLS implementation must not package Bouncy Castle");
assertFalse(output.stream().anyMatch(entry ->
entry.getName().startsWith("org/checkerframework/")
|| entry.getName().startsWith("org/jspecify/")),
"Compile-time annotation libraries must not be embedded");
assertFalse(output.stream().anyMatch(entry -> entry.getName().equals("module-info.class")
|| entry.getName().startsWith("META-INF/versions/")
|| (entry.getName().startsWith("META-INF/maven/")
&& (entry.getName().endsWith("/pom.xml")
|| entry.getName().endsWith("/pom.properties")))),
"A shaded non-modular JAR must not contain unreachable module or Maven POM metadata");
}
System.out.printf("Full artifact: %,d bytes; no external crypto provider packaged%n", Files.size(full));
}
Expand Down
72 changes: 41 additions & 31 deletions docs/jar-packaging.md
Original file line number Diff line number Diff line change
@@ -1,25 +1,37 @@
# Full JAR size and cryptography packaging

`SimpleAPI.jar` remains the full, HTTP-capable artifact. The `shared` and
`shared-sources` classifiers, dependency scopes, and public APIs are unchanged.
There are no additional modules or runtime downloads.
`SimpleAPI.jar` is the self-contained, HTTP-capable artifact. The `shared` and
`shared-sources` classifiers, public APIs, dependency scopes, relocations, and
normal publication behavior remain unchanged. No external libraries are fetched
at runtime.

The HTTP transport uses Bouncy Castle for its private CA and certificates.
Do not remove those dependencies, switch them to `provided`, strip provider
mappings, or enable broad `minimizeJar` without packaged-runtime validation.
Providers load some implementation classes reflectively.
The HTTP identity implementation uses the JDK's EC/PKCS#12/TLS APIs; it does
**not** require Bouncy Castle. Keep the packaged certificate issuance, mutual
TLS, identity persistence, and renewal tests before changing TLS packaging.

The full shaded artifact is not a multi-release JAR. Its shade filter omits
`META-INF/versions/**`, which that artifact cannot select, while retaining base
classes and resources. This is a conservative reduction of unreachable payload,
not removal of the crypto provider or the entire HTTP dependency cost.
## Compact non-modular shaded artifact

Java only selects versioned classes when the final manifest declares
`Multi-Release: true`. If that contract changes, revisit this filter and the
packaged-runtime checks rather than silently enabling the attribute. Downstream
consumers that re-shade this artifact receive the base BC implementation.
The full shaded JAR is not a Java multi-release JAR or a JPMS module. It filters
`META-INF/versions/**` and root `module-info.class`, which cannot supply valid
alternate implementations or a usable module descriptor in this distribution.

## Verification
The shading step also excludes `org/checkerframework/**` and
`org/jspecify/**` from the full JAR. These are annotation-only support
packages, not implemented features, providers, or runtime entry points. Keep
all API classes, Hikari/FoliaLib relocations, service descriptors, application
resources, license notices, and other runtime metadata.

Shaded dependency `META-INF/maven/**/pom.xml` and `pom.properties` entries
are excluded to avoid embedding duplicate build descriptions. This does *not*
remove non-POM version or service resources needed at runtime.

Do not turn on global `minimizeJar`; bytecode reachability analysis can omit
reflection- and service-loaded APIs, Redis compatibility types, and platform
adapters. Treat any further reduction that removes code as a separately tested
compatibility change. Consumers needing external annotation classes in their
own source should declare those annotations explicitly.

## Validation

Run from the repository root with JDK 21 and Maven:

Expand All @@ -28,18 +40,16 @@ mvn -B -f SimpleAPI/pom.xml clean package
git diff --check
```

The package phase runs `FullArtifactTest` after shading, followed by the existing
shared-classpath tests. It verifies the non-multi-release manifest, absence of
all unreachable versioned payload and preservation of every base
`org/bouncycastle/` entry from the three resolved BC libraries. It prints the final JAR size and the
compressed upstream payload omitted. That payload counter is not an exact
before/after distribution size: shading/recompression and ZIP overhead differ.
To measure the exact reduction, compare clean baseline and candidate builds with
the same resolved dependencies and JDK.

A fresh JVM runs a JDK-only fixture using just the packaged JAR and the fixture's
single class file. No Maven dependencies or `target/classes` are on its classpath.
It verifies CA/server/client certificate creation, PKCS12 use, authenticated TLS,
rejection of absent/foreign client credentials, persisted identity reload, and
server/CA renewal. The subprocess and socket operations have bounded timeouts.
Reports are written under `SimpleAPI/target/full-artifact-reports/`.
The package phase runs `FullArtifactTest` after shading, then the existing
`SharedArtifactTest`. They validate the actual full and shared JARs, retained
legacy Jedis constructor linkage, the exclusion boundaries, and neutral
shared-classpath linkage.

A separate JVM uses only the packaged full JAR and one test fixture class to
exercise JDK-only CA/server/client certificate issuance, PKCS#12, mutual TLS,
rejection of missing/foreign credentials, reload, and renewal. Required service
resources remain packaged. Reports go under `SimpleAPI/target/`.

Measure improvements by comparing clean builds with the same resolved
dependencies and JDK. A smaller JAR and a passing CI suite do not substitute
for testing external consumers that have not been included in CI.
Loading