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-interceptoris 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: trueunder/html-error-response-interceptorto keep the HTML error pages (the
quickstart and example configurations do).tenantIdis the plain tenant id, ornull, 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-activeofpebble-template-processorreally defaults totruewhen the key is
missing, as documented. Set it tofalseexplicitly in development.
Added
- Configurable auth redirect —
HtmlAuthRedirectInterceptoroptionsredirect-param
(defaultredirect) andcookie-name(defaultrh_auth);login-serviceoptioncookie-name,
forwarded withredirect-paramto the interceptor it registers. mongoPrefixis now really set at startup from themongo-mountsconfiguration, so
mongoPathis 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-commonsand 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-Redirectto
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 fromHX-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-cachingofhtml-response-interceptordefaults totruealso 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 neithertemplates/error.htmlnortemplates/errors/{code}.htmlexists. - Auth redirect — the
Locationlost 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. mongoPathprefix stripping respects segment boundaries (/apino longer strips/apidocs).hostParamsJSON was built by string concatenation without escaping.- Build scripts —
update-dependencies.shno longer applies major updates when run with
true;setversion.shstages only the POM files it changes. - Integration tests —
mvn verifyruns again:JsPluginsITbuilds its own RESTHeart + Facet
image from the module output, is skipped without Docker, and CI runs the integration tests on
every push.
Security
login-serviceis no longer an open redirector — theredirectparameter 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 applyescape(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 —
JsPluginsITvalidates 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-plugin3.15.0,maven-surefire-plugin3.5.6,maven-failsafe-plugin3.5.6,
maven-dependency-plugin3.11.0,maven-assembly-plugin3.8.0,versions-maven-plugin2.21.0. - Dockerfile base image updated to RESTHeart 9.7.
Fixed
update-dependencies.shimproved with better version control logic.
[1.0.1] — 2026-03-19
Fixed
- Bypass HTML interception for SSE
event-streamrequests (#8). - Allow
setversion.shto run frommasterandrelease/*branches. - Update
restheart.versionto 9.2.0 in POM.
Added
- OpenWiki documentation — Architecture, HTMX integration, operations, quickstart, template
system, and testing guides now live in the repository underopenwiki/. 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
-
requestMethodtemplate 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}.htmlbefore falling back to the generictemplates/error.html.
Example 404 page added to the product-catalog example attemplates/errors/404.html. -
MongoDB count caching — Count results for
estimatedDocumentCount(),countDocuments(),
listDatabaseNames(), andlistCollectionNames()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 withrequestMethod.
Changed
- Version bumped from
0.2.0-SNAPSHOTto1.0.0inpom.xmlandcore/pom.xml. requestMethodvariable 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-Reselectgap documented as known limitation
Changed
- Template resolver refactored to
PathBasedTemplateResolverwith full hierarchical fallback MongoHtmlResponseHandlerenriches documents with_idmetadata 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-Targetheader - 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-Reselectresponse header not implemented (minor HTMX gap)JsonHtmlResponseHandlerloads 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