Egothor/ZeroEcho
2
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects 1 Releases 2 Wiki Activity

Introduce JPMS module-info.java declarations to enforce architectural layer boundaries #19

New Issue
Open
opened 2026-03-27 00:36:15 +01:00 by galambos · 0 comments
galambos commented 2026-03-27 00:36:15 +01:00
Owner
Copy Link

The project has a well-defined three-layer architecture (core → sdk → app),
but this layering is currently enforced only by convention. Nothing in the build
prevents app-layer code from importing zeroecho.core.alg.* or
zeroecho.core.spi.* directly, bypassing the sdk abstraction entirely. As the
codebase grows and external contributors appear, this silent coupling will
inevitably occur.

Why this matters

Architectural boundaries that are not machine-enforced tend to erode. JPMS
module-info.java declarations make violations a compile-time error rather than a
review-time catch. They also improve IDE tooling, enable strong encapsulation of
internal packages, and signal maturity to library consumers.

The project already targets Java 21 and uses Gradle 9.4, both of which support
JPMS without friction.

Proposed change

Introduce module-info.java in each subproject:

  • zeroecho.core — exports zeroecho.core and zeroecho.core.context publicly;
    exports zeroecho.core.alg, zeroecho.core.spi, zeroecho.core.marshal, and
    other internal packages only to zeroecho.sdk; declares
    uses zeroecho.core.CryptoAlgorithm for ServiceLoader.
  • zeroecho.sdk — exports zeroecho.sdk.builders, zeroecho.sdk.content.api,
    and zeroecho.sdk.hybrid; keeps zeroecho.sdk.content.builtin and
    zeroecho.sdk.integrations internal.
  • zeroecho.app — no exports (application module).

SPI providers must add provides zeroecho.core.CryptoAlgorithm with ... in their
own module-info.java.

Acceptance criteria

  • Each subproject (lib, app, pki) has a valid module-info.java.
  • javac rejects any direct import of zeroecho.core.alg.* from app-layer
    code.
  • ServiceLoader discovery of CryptoAlgorithm continues to work in both modular
    and classpath modes.
  • All existing tests pass with --module-path compilation.
The project has a well-defined three-layer architecture (`core` → `sdk` → `app`), but this layering is currently enforced only by convention. Nothing in the build prevents `app`-layer code from importing `zeroecho.core.alg.*` or `zeroecho.core.spi.*` directly, bypassing the `sdk` abstraction entirely. As the codebase grows and external contributors appear, this silent coupling will inevitably occur. ## Why this matters Architectural boundaries that are not machine-enforced tend to erode. JPMS `module-info.java` declarations make violations a compile-time error rather than a review-time catch. They also improve IDE tooling, enable strong encapsulation of internal packages, and signal maturity to library consumers. The project already targets Java 21 and uses Gradle 9.4, both of which support JPMS without friction. ## Proposed change Introduce `module-info.java` in each subproject: - `zeroecho.core` — exports `zeroecho.core` and `zeroecho.core.context` publicly; exports `zeroecho.core.alg`, `zeroecho.core.spi`, `zeroecho.core.marshal`, and other internal packages only `to zeroecho.sdk`; declares `uses zeroecho.core.CryptoAlgorithm` for `ServiceLoader`. - `zeroecho.sdk` — exports `zeroecho.sdk.builders`, `zeroecho.sdk.content.api`, and `zeroecho.sdk.hybrid`; keeps `zeroecho.sdk.content.builtin` and `zeroecho.sdk.integrations` internal. - `zeroecho.app` — no exports (application module). SPI providers must add `provides zeroecho.core.CryptoAlgorithm with ...` in their own `module-info.java`. ## Acceptance criteria - Each subproject (`lib`, `app`, `pki`) has a valid `module-info.java`. - `javac` rejects any direct import of `zeroecho.core.alg.*` from `app`-layer code. - `ServiceLoader` discovery of `CryptoAlgorithm` continues to work in both modular and classpath modes. - All existing tests pass with `--module-path` compilation.
galambos added this to the PKI Foundation Hardening and Regulated Operations Roadmap project 2026-03-27 00:36:47 +01:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project PKI Foundation Hardening and Regulated Operations Roadmap
Assignees
Clear assignees
galambos gitea-ci
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Egothor/ZeroEcho#19
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?