Facet Changelog - Version History

Release notes and version history

All notable changes to this project are documented here.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.


[1.1.0] — 2026-10-30

Moves to RESTHeart 9.12.3 and closes the findings of a full code review: wrong defaults, an open
redirector in the login service, error pages that came back empty, and integration tests nobody
could run. The plugin API and the template conventions are unchanged.

Upgrade notes — four behaviors change:

  • html-error-response-interceptor is now opt-in. It was the only Facet plugin enabled by
    default, so deploying the JAR alone rewrote every browser-facing 4xx/5xx as an HTML page. Add
    enabled: true under /html-error-response-interceptor to keep the HTML error pages (the
    quickstart and example configurations do).
  • tenantId is the plain tenant id, or null, no longer a JSON-quoted string or the literal
    "null". {% if tenantId %} now works; use {{ tenantId | toJson }} to embed it in JavaScript.
  • JsonHtmlResponseHandler — Facet's own variables (isAuthenticated, username, roles,
    requestMethod, path, data) now win over same-named fields of a service response.
  • cache-active of pebble-template-processor really defaults to true when the key is
    missing, as documented. Set it to false explicitly in development.

Added

  • Configurable auth redirect — HtmlAuthRedirectInterceptor options redirect-param
    (default redirect) and cookie-name (default rh_auth); login-service option cookie-name,
    forwarded with redirect-param to the interceptor it registers.
  • mongoPrefix is now really set at startup from the mongo-mounts configuration, so
    mongoPath is prefix-stripped when MongoDB is mounted under e.g. /api. See the
    Template Context Reference.
  • HtmlResponseHelper.renderErrorHtml() — public helper returning the error page HTML, or the
    built-in fallback page, for custom services.

Changed

  • RESTHeart 9.12.3 — restheart-commons and the Docker base image updated from 9.7.x. The
    quickstart stack was verified end-to-end (HTML rendering, cookie login, HTMX fragments, JSON
    passthrough). The quickstart and example configurations disable the MCP service that RESTHeart
    enables by default since 9.9.
  • HTMX and authentication — an HTMX request that fails authentication receives HX-Redirect to
    the login page and keeps status 401, instead of a 302 that HTMX would swap into the target
    element. The redirect target is the page URL from HX-Current-URL.
  • Rendering failures are visible — a template that exists but fails to render now yields a 500
    (error page, or plain text for HTMX) instead of silently sending the JSON payload with status 200.
  • Strong ETags — rendered pages use a 128-bit SHA-256 prefix instead of String.hashCode(),
    which could answer 304 Not Modified for content that had actually changed.
  • Less work per request — template resolution runs once per request, template existence is
    checked without compiling, lookup logging moved to DEBUG/TRACE, and the MongoDB count cache is a
    bounded Caffeine cache (5 s TTL, 1000 entries).
  • response-caching of html-response-interceptor defaults to true also when the plugin has no
    configuration block.
  • Pebble's {% parallel %} thread pool uses named daemon threads.

Fixed

  • Error pages without a template returned HTTP 500 with an empty body: the built-in fallback
    page is now used when neither templates/error.html nor templates/errors/{code}.html exists.
  • Auth redirect — the Location lost the original query string and did not URL-encode the
    path; the cookie was cleared with a hardcoded name; the interceptor also fired for authenticated
    but unauthorized users (403), clearing their cookie. It now acts only on unauthenticated requests.
  • mongoPath prefix stripping respects segment boundaries (/api no longer strips /apidocs).
  • hostParams JSON was built by string concatenation without escaping.
  • Build scripts — update-dependencies.sh no longer applies major updates when run with
    true; setversion.sh stages only the POM files it changes.
  • Integration tests — mvn verify runs again: JsPluginsIT builds its own RESTHeart + Facet
    image from the module output, is skipped without Docker, and CI runs the integration tests on
    every push.

Security

  • login-service is no longer an open redirector — the redirect parameter is honored only
    for local absolute paths (/..., not //... or absolute URLs); anything else falls back to
    default-redirect. Values that could break out of the JavaScript string in the login template
    are rejected, and the bundled login templates apply escape(strategy="js").

[1.0.2] — 2026-08-11

Added

  • JavaScript server-side plugins — Custom backend logic in JavaScript (or TypeScript) via GraalVM.
    Add computed endpoints, data aggregations, and request/response interceptors without Java.
    Hot-reload on next request. See the JavaScript Plugins guide.

  • JavaScript plugin integration tests — JsPluginsIT validates JS plugin loading and
    request-logger interceptor with HTMX-driven verification.

Changed

  • RESTHeart commons updated from 9.5.2 to 9.7.2 (compatible with RESTHeart 9.7).
  • Pebble updated from 4.1.1 to 4.1.2.
  • Maven plugin versions now managed as properties in the parent POM:
    maven-compiler-plugin 3.15.0, maven-surefire-plugin 3.5.6, maven-failsafe-plugin 3.5.6,
    maven-dependency-plugin 3.11.0, maven-assembly-plugin 3.8.0, versions-maven-plugin 2.21.0.
  • Dockerfile base image updated to RESTHeart 9.7.

Fixed

  • update-dependencies.sh improved with better version control logic.

[1.0.1] — 2026-03-19

Fixed

  • Bypass HTML interception for SSE event-stream requests (#8).
  • Allow setversion.sh to run from master and release/* branches.
  • Update restheart.version to 9.2.0 in POM.

Added

  • OpenWiki documentation — Architecture, HTMX integration, operations, quickstart, template
    system, and testing guides now live in the repository under openwiki/.
  • update-dependencies.sh — Script to update project dependencies using Maven Versions Plugin.
  • Polyglot extensibility documented in README (GraalVM support).

Changed

  • README rewritten for clarity on Facet as a RESTHeart plugin with server-rendered HTML.
  • CI workflows updated to latest GitHub Actions versions.
  • Documentation consolidated: detailed guides moved to OpenWiki and the project website.

[1.0.0] — 2026-03-13

First stable release. The core API and template conventions are now considered stable.

Added

  • requestMethod template variable — All templates now receive the HTTP method of the current
    request (GET, POST, PATCH, DELETE, PUT, HEAD, OPTIONS, OTHER). Enables
    conditional rendering for post-mutation feedback (e.g., showing "Created successfully!" after POST).

  • Per-status-code error templates — HtmlResponseHelper.renderErrorPage() now looks for
    templates/errors/{statusCode}.html before falling back to the generic templates/error.html.
    Example 404 page added to the product-catalog example at templates/errors/404.html.

  • MongoDB count caching — Count results for estimatedDocumentCount(), countDocuments(),
    listDatabaseNames(), and listCollectionNames() are cached with a 5-second TTL.
    Eliminates extra MongoDB round-trips per rendered page.

  • JUnit 5 test suite — 67 tests covering template resolution, HTMX header parsing,
    authentication context building, and HTMX response helpers.

  • "Handling Mutations" section in Developer's Guide — Documents three patterns for
    responding to form submissions and API mutations: HTMX Fragment Swap (recommended),
    Post-Redirect-Get, and inline response with requestMethod.

Changed

  • Version bumped from 0.2.0-SNAPSHOT to 1.0.0 in pom.xml and core/pom.xml.
  • requestMethod variable documented in Template Context Reference.

[0.2.0] — 2026-01

Added

  • Parametric mongo-mount support and multi-tenant context (tenantId, isMultiTenant, hostParams)
  • Custom Pebble filters: stripTrailingSlash, buildPath, parentPath, toJson
  • HTMX strict mode: missing fragment template returns 500 to surface errors early
  • CRUD example in product-catalog with HTMX-powered edit forms
  • HX-Reselect gap documented as known limitation

Changed

  • Template resolver refactored to PathBasedTemplateResolver with full hierarchical fallback
  • MongoHtmlResponseHandler enriches documents with _id metadata for URL generation

[0.1.0] — 2025

Initial release.

Added

  • Core interceptor architecture (HtmlResponseInterceptor, HtmlErrorResponseInterceptor, HtmlAuthRedirectInterceptor)
  • Path-based template resolution with hierarchical fallback
  • Pebble template engine integration
  • HTMX fragment resolution via HX-Target header
  • MongoDB response handler with pagination
  • ETag-based response caching
  • Product-catalog example with Pico CSS

Known Limitations (Future Work)

These issues exist but are not blocking:

  • HX-Reselect response header not implemented (minor HTMX gap)
  • JsonHtmlResponseHandler loads full response into memory (no streaming)
  • MongoDB operation timeout handling not configurable
  • Thread pool size not configurable in PebbleTemplateProcessor
  • Count cache TTL and size are hardcoded (5 seconds, 1000 entries), not configurable