From 6b7b4161159800482e67663734e5920a1f03432f Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 15 Nov 2026 16:59:45 -0600 Subject: [PATCH 1/3] build: omit optional annotation bytecode and redundant JAR metadata --- SimpleAPI/pom.xml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/SimpleAPI/pom.xml b/SimpleAPI/pom.xml index d261276..8442320 100644 --- a/SimpleAPI/pom.xml +++ b/SimpleAPI/pom.xml @@ -156,6 +156,15 @@ META-INF/versions/** + + org/checkerframework/** + org/jspecify/** + + module-info.class + META-INF/maven/**/pom.xml + META-INF/maven/**/pom.properties From 53927172de9be3db3ec558d2036bfcf47f813820 Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 15 Nov 2026 16:59:47 -0600 Subject: [PATCH 2/3] test: protect SimpleAPI shaded runtime size without removing services --- .../simpleapi/tests/packaging/FullArtifactTest.java | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/SimpleAPI/src/test/java/com/bencodez/simpleapi/tests/packaging/FullArtifactTest.java b/SimpleAPI/src/test/java/com/bencodez/simpleapi/tests/packaging/FullArtifactTest.java index b06d88c..0120eee 100644 --- a/SimpleAPI/src/test/java/com/bencodez/simpleapi/tests/packaging/FullArtifactTest.java +++ b/SimpleAPI/src/test/java/com/bencodez/simpleapi/tests/packaging/FullArtifactTest.java @@ -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)); } From e72339e7e8190d583ae162142722213b0afad092 Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 15 Nov 2026 16:59:49 -0600 Subject: [PATCH 3/3] docs: refresh current JDK TLS and package-size contract --- docs/jar-packaging.md | 72 ++++++++++++++++++++++++------------------- 1 file changed, 41 insertions(+), 31 deletions(-) diff --git a/docs/jar-packaging.md b/docs/jar-packaging.md index 6932524..ef52099 100644 --- a/docs/jar-packaging.md +++ b/docs/jar-packaging.md @@ -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: @@ -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.