Server compatibility¶

The client and server are versioned independently. A client release "targets" a server release when its pinned OpenAPI contract comes from that server tag and the complete Docker-backed library and consumer integration suites pass against an immutable image for the same release.

Dedicated typed helpers do not necessarily exist for every server operation. Authenticated relative routes remain available through raw() while typed coverage evolves.

Compatibility history¶

The client version 0.0.2 row predates and is unrelated to the independently versioned Hubuum server v0.0.2 release.

Forward compatibility¶

Client 0.11.1 introduced the fresh credential approval API for servers incorporating PR 423. That release kept its declared v0.0.15 target, pinned image, and OpenAPI snapshot. Existing calls do not require the approval endpoints. On an enforcing server, credential mutations return reauthentication_required until the caller uses the explicit approval workflow.

Focused live verification on 2026-09-19 used the PR's merged source revision 3a1c44c938cc9d06d665229612c0fb1b4f3c98c8 and immutable Linux amd64 image ghcr.io/hubuum/hubuum-server@sha256:62438f2473ee15f9699ccc904e79c4c20c27e06a1219986c04493d269127f3e0. With HUBUUM_INTEGRATION_EXPECT_CREDENTIAL_APPROVALS=1, async and blocking token creation/renewal preserved approved expirations, and downstream user/password and credential-import dry runs passed. Blocking and async full restore confirmation and recovery passed with and without history. These focused checks supplement the required complete pinned-server run; they do not declare compatibility with all other changes on server main.

The canonical complete pinned-server command also passed on 2026-09-19 against the v0.0.15 image declared in Cargo.toml, including library and downstream consumer tests and all four restore/recovery scenarios. The new credential scenarios passed through the original APIs without requiring approval support.

After the fixture repairs in client PR 95, the complete library and downstream consumer integration suite passed on 2026-09-22 against immutable server candidate 61f1bfd3455af26254e1dc73e697a80b0536813a, image ghcr.io/hubuum/hubuum-server@sha256:8944a31e47ff97eb14bf5072772149c06d87714a316db54aa4e010195c5811a0. Approval enforcement was required, and all four full restore/recovery variants passed. This extends the earlier focused evidence to the complete suite. This evidence preceded publication of v0.0.16. Client 0.11.2 targets the released artifact and reviewed contract as described below.

Required CI is deterministic and stays pinned to the declared target. Scheduled jobs separately compare the contract and run the integration suites against the server's main branch. Those scheduled checks are early-warning signals; they do not change a published client's declared target.

v0.0.17 target¶

Client 0.13.0 targets server v0.0.17. The reviewed contract grows from 220 to 227 operations and from 330 to 336 schemas. Most other snapshot changes reorder nullable schema alternatives after the server's Utoipa update; they do not alter wire behavior. Rust 1.88 and the client feature sets are unchanged.

Event sink CRUD and import models preserve delivery policy, subscription filters include task kinds, and delivery responses preserve purpose and deferral details. Delivery health accepts an absent or null collection ID for system subscriptions. The seven new system-subscription CRUD and notification preview/test operations use the existing authenticated raw() extension point. Their routes and limitations are recorded in known gaps.

This is a breaking Rust release: handle None in EventSubscriptionDeliveryHealth.collection_id, add delivery_policy: None to exhaustive sink request/import literals and task_kinds: None to exhaustive subscription filter literals. Default-based construction remains available for sink requests and filters; use .. in exhaustive destructuring patterns.

The server emits backup format 7 and still accepts format 6 with legacy notification defaults. The client recognizes both formats and rejects older or unknown formats through has_supported_version(). Existing format-6 schema sections and format-7 notification data remain intact in the generic backup section maps. See the backup guide.

Upgrading from v0.0.16 requires a maintenance window. Stop all writers, including API, worker, and restore-executor processes; take a PostgreSQL snapshot; then apply the webhook-notification migration and deploy matching v0.0.17 binaries. Binary-only rollback is unsupported. Recovery requires that snapshot with the matching v0.0.16 binaries and loses writes made after the snapshot. Older servers cannot restore format 7. Optional Treetop backends also require protocol 0.1 and updated policy bundles. See the server release notes.

The pinned multi-platform index is sha256:cc0518167816bfddb38853b8b7217c4a347511318d51e1abca93ca418f31b302. Its Linux amd64 manifest is sha256:a7082cb13a94d2c0f8934ade79f2117e39b66c1725b4ee9696e49c2895bcb672. The image's version and source labels identify v0.0.17 and tag commit 4a03d56b27f35af62175a80d09d36d0d41c4a663.

The canonical combined command passed on 2026-10-05 against that Linux amd64 image with HUBUUM_INTEGRATION_EXPECT_CREDENTIAL_APPROVALS=1: all 93 library integration tests, 33 ordinary consumer tests, and all four async/blocking restore/recovery variants with history included and omitted. The consumer tests covered all seven new notification routes in both modes, nullable system health, delivery-policy round trips and clearing, task-kind filter serialization, rendered previews, and real test-delivery decoding. Format-7 backups staged and restored successfully; recovery retained resource and schema revisions and validated subsequent backups.

All workspace tests, feature combinations, Rust 1.88, lint, documentation, generator, pinned contract, and dependency audit/policy checks passed. Dependency resolution is current under Rust 1.88 and upstream constraints; crypto-common 0.1.7 still pins generic-array to 0.14.7. The normal public API check accepts the 0.13.0 version; a stricter comparison confirms the documented added-field breaks requiring this pre-1.0 major bump. All GitHub Action pins and the PostgreSQL 18 fixture digest were verified current.

v0.0.16 target¶

Clients 0.11.2 and 0.12.0 target server v0.0.16. The pinned contract grows from 218 to 220 operations and from 315 to 330 schemas. Both added approval routes already have typed async and blocking APIs. Client 0.12.0 reconciles 79 wire-model mappings, including retained task details. Feature availability, Rust 1.88, and backup format 6 are unchanged.

Credential mutations require fresh, operation-bound password approval. Before upgrading the running server, update applications to use the approval workflow. Existing mutation methods retain their original behavior and return reauthentication_required when the server enforces approvals; they do not prompt or automatically retry.

Client 0.12.0 exposes every task-discovery filter and retained detail projection through the async and blocking typed APIs, including cursor pagination and local query validation. Client 0.11.2 required raw() for those additions. The new optional fields break exhaustive Rust struct literals and destructuring; see the task discovery migration guide.

Keep a verified v0.0.15 backup, quiesce protected mutations, drain workers, and apply 2026-09-18-000001_task_discovery and 2026-09-19-000001_credential_approvals with hubuum-admin --migrate. Deploy matching API, worker, administrator, and separately supervised restore-executor binaries before resuming operations. Older format-6 backups without discovery metadata remain accepted. See the server release notes.

The immutable multi-platform release image is ghcr.io/hubuum/hubuum-server@sha256:37b3299edd845a0c2aa7772d7d68565233ac8c1802bc44be3fb4bbc6dfa8778e. Its Linux amd64 manifest is sha256:2f1e59519c3e5fb0a849ee6db8f3f3981b76145cac2f9ffb6f463a8927d4f7d2, and its source label matches the v0.0.16 tag commit 8f4194ffe25d172d579b676f109efbdc71d9aab7.

The canonical combined command passed on 2026-09-22 with HUBUUM_INTEGRATION_EXPECT_CREDENTIAL_APPROVALS=1: all 93 library integration tests, every downstream consumer suite, and all four async/blocking full restore/recovery variants. The downstream discovery scenarios verified resource and output filters, comma-separated statuses, retained export metadata, and decoding of newer responses through the unchanged typed task models.

v0.0.13 target¶

The 0.10.0 release targets server v0.0.13, which fixes the restore drain-state race and JSON-null insertion failure found during v0.0.12 verification. Its 204-operation OpenAPI contract is unchanged from v0.0.12 apart from the server version. Backup format 5 is unchanged.

Install matching server, administrator, and template-worker binaries, including any separately deployed hubuum-admin --restore-executor. See the server release notes and the backup and restore guide for migration and recovery steps.

The canonical combined integration command passed on 2026-09-09 against the released immutable image above (Linux amd64). All 89 library and 24 ordinary consumer tests passed, followed by blocking and async full restore completion and recovery after each restore. Both modes reached Succeeded, rejected the pre-restore bearer token, and recovered the deleted object after administrator password reset and a fresh login.

The published image identifies source revision 8ecefbf3e3147714014221598d9873ba92e0fdce, matching the v0.0.13 release tag. The manifest pins the multi-platform image index; this live run verifies its Linux amd64 image.

v0.0.14 target¶

The 0.10.1 patch release targets server v0.0.14. Its 204-operation OpenAPI contract is unchanged from v0.0.13 apart from the server version. Public client APIs, features, the Rust 1.88 MSRV, and backup format 5 are unchanged.

The server fixes backup and restore consistency, including preserving revisions and establishing current temporal snapshots after history-free restores so later backups remain restorable. Install matching server, administrator, and template-worker binaries, including any separately deployed hubuum-admin --restore-executor. Existing history-free format 5 artifacts can be restored directly with the fixed executor. No database migration is added; the server's certified upgrade and application rollback path is v0.0.13 to v0.0.14. See the server release notes and the backup and restore guide.

The canonical combined integration command passed on 2026-09-10 against the released immutable image above (Linux amd64). All 89 library and 24 ordinary consumer tests passed, followed by all four combinations of blocking/async full restore and history included/omitted. Every restore reached Succeeded, rejected the pre-restore bearer token, and recovered the deleted object with its original revision after administrator password reset and a fresh login. Recovery also created and successfully staged default backups both before and after another mutation, covering the history-free restore fix.

The published image identifies source revision 0b0aa17f278496a32cc018cfcac56f34a408ccd6, matching the v0.0.14 release tag. The manifest pins the multi-platform image index; this live run verifies its Linux amd64 image.

v0.0.15 target¶

The 0.11.0 release targets server v0.0.15. The contract grows from 204 to 218 operations and from 280 to 315 schemas. All 14 new operations have typed async and blocking helpers, covering the class schema lifecycle, retained HTML repair reports, and task cancellation. Feature availability and Rust 1.88 remain unchanged.

ImportClassInput gains schema_activation; add schema_activation: None to existing struct literals or provide an explicit activation request. Changing schema policy on a nonempty class now requires staging, impact analysis, and activation instead of direct PATCH or legacy import overwrite. Imports must provide the exact staged policy. See the schema guide.

Backup format 6 replaces format 5, adding schema revisions, state, evidence, and history. Restore older artifacts using their matching older server before migrating and creating new format 6 backups; no artifact converter is provided. Drain old workers, apply the release's migrations, then deploy matching API, worker, administrator, and restore-executor binaries. Existing enforced objects start pending and need revalidation. See the backup guide and server release notes.

The server also tightens schema validation and resource budgets, changes string cursor ordering to byte ordering on locale-collated databases, and requires the CancelTask external authorization action. Restart in-progress string-sorted pagination, review stored schema admission, and deploy consistent schema, task, and backup limits across processes. Report assembly can return HTTP 413, and external-authorization traversal is bounded at 10,000 candidates.

All direct dependencies already use constraints that select the latest compatible releases. The lockfile refresh updates twelve packages, including Rustls 0.23.45 for RUSTSEC-2026-0285. generic-array remains at 0.14.7 because the current crypto-common 0.1.7 dependency requires that exact version.

The pinned multi-platform image identifies source revision 4bb889c66a5e2a1dfc86d1b6beac7495912fd02e, matching the annotated v0.0.15 tag.

The canonical combined integration command passed on 2026-09-16 against this image's Linux amd64 build. All 91 library and 26 ordinary consumer tests passed, including both modes of the schema lifecycle, diagnostic HTML, import activation, and task cancellation. All four combinations of blocking/async full restore and history included/omitted reached Succeeded and invalidated the old bearer token. Recovery after each restore preserved the object's resource revision, the active schema revision, and validation evidence. Subsequent backups before and after a mutation also passed restore staging validation.