Dated fixes and setup changes, newest first. These updates retain version 0.6.0; the KPZ filename and checksum identify the exact build. A newer plugin upload alone does not update the server integration.
Latest package
0.6.0 — general update guidance and compatible updater correction
· Build afb945d8efb5
The plugin’s Update RustSearch section now gives reusable instructions for updating the engine and plugin. Release-specific fixes and incident details belong in these dated release notes.
Distinguishes --update, which replaces the engine and matching components, from --existing-engine, which retains the executable.
Applies the supported SearchEngine preference guard before extending its trusted integration baseline. Both preference files are included in the update backup and rollback.
Shows captured subprocess errors when an update step fails, so the underlying cause is visible.
Retains the staff barcode repair, optional OpenSearch API and Swagger. The native engine source and schema are unchanged from the preceding validated build.
Validated with 254 Python tests and 1,671 Perl assertions. The unchanged engine matches the previously validated ARM64 and x86-64 source provenance. The separately reported Z39.50 save HTTP 500 remains unresolved.
Repairs a missing barcode result in general staff keyword search when explicit Barcode search already finds the item. The simple keyword path now searches the barcode projection already present in schema 7.
Retains leading zeroes, explicit field scope, result visibility and pagination. Item-masked requests retain their existing visibility path.
Requires an engine executable refresh using the new package’s bundled --update command. A KPZ upload alone or --existing-engine does not apply this engine change.
No record reimport, schema migration or full reindex is needed for this repair.
Retains the optional OpenSearch API and Swagger. The API stays disabled by default; an already-enabled listener is preserved during update.
Portable ARM64 and x86-64 builds passed the 77 native HTTP checks, including barcode regressions, and the 31 optional API checks on each architecture. The Configuration page now distinguishes engine updates from plugin-only refreshes.
The separately reported HTTP 500 while saving a Z39.50 record is still under investigation and is not claimed fixed by this package.
An additional, experimental interface for trusted local applications. OpenSearch clients can run the supported read-only searches and counts against the existing RustSearch bibliographic index. Native Koha integration and the index schema stay unchanged.
Optional at build time and disabled at runtime by default; uses a separate loopback listener and /opensearch/v1 namespace.
Includes a versioned OpenAPI specification and locally bundled Swagger UI with interactive requests.
Supports a defined query subset, exact totals, pagination and stored fields. Requires _source: false; original JSON documents are not retained.
No OpenSearch or Elasticsearch server dependency. Unsupported operations return explicit errors; this is not full Elasticsearch compatibility or a drop-in replacement for Koha’s Elasticsearch adapter.
The compatible updater preserves index paths, tenant ports and enabled API settings. The prior pagination repair and schema-7 activation guard remain included.
API checks passed on ARM64 and x86-64 using the official OpenSearch Python client 3.2.0. Enablement requires an engine refresh and a separate administrator opt-in; uploading the KPZ alone does not enable it.
Fixed staff and OPAC searches failing with “Invalid pagination parameters” when Koha requests more than 100 records per page. The adapter collects the requested page in native requests of at most 100 records, within the supported 10,000-result window.
Preserves result order, offsets, visibility rules, totals and facets.
Detects incomplete, duplicate or changing result pages instead of returning a successful partial response.
Logs the underlying native search error for future diagnosis.
Update the existing plugin; do not uninstall. Upload the new KPZ and run its bundled setup with --existing-engine on a compatible schema-7 server. No engine rebuild or reindex is needed. If search is currently restored by a 20-result page-size workaround, keep that setting until the update completes.
Verified with 1,668 Perl assertions and real Koha searches at 20, 200 and 500 records per page, including later pages and ID/order comparisons. The earlier performance optimizations and activation guard remain included.
Checks the running engine schema, profiles and native capabilities before saving SEARCHENGINE. An incompatible engine leaves that preference unchanged.
Reports server setup or coordinated migration requirements instead of hiding an engine mismatch behind a generic search error.
Requires schema 7 for production updates and prohibits schema-6 production rollback.
Update in place; do not uninstall. Upload the new KPZ. If the check reports a compatible local engine, run the same bundled command with --existing-engine instead of --check-only. The read-only check does not apply changes. Schema-6 servers need coordinated migration.
Verified with 1,631 Perl assertions, targeted activation/update/integrity tests and checks of the bundled source manifest. Existing native engine optimizations are retained.
Earlier package · retained in this release
0.6.0 — bounded item lookup and text normalization
· Build ebed7eb6b4f2
Item-ID queries narrow candidates through a compact reverse lookup while retaining item visibility, availability and other predicates. A fixed entry budget falls back to the existing native scanner for oversized segments.
ASCII text uses a fast Rust normalization path. Non-ASCII text retains the existing Unicode routine. No assembly or index schema change is introduced.
Stress checks cover concurrent commits, merges, old snapshots, updates, deletes, shared identifiers and budget fallback. Multilingual canonical text and token positions matched the reference on 80,173 strings.
In local synthetic measurements, warm item-ID latency fell about 97% at 150,000 items; at one million items the bounded fallback limited the gain to about 20%. These are native-handler measurements, not a whole-import or browser speed claim. Published historical benchmark charts are unchanged.
Install the engine change
Fresh setup builds the bundled engine when missing. Existing libraries must rebuild and refresh the native executable with a coordinated backup/probe/restart procedure. A KPZ upload or --existing-engine refresh alone preserves the older executable. Compatible schema-7 indexes do not need a full reindex for this update. Batch sizes, schedules and engine selections are unchanged.
Removed catalog-completeness gates from staff/OPAC, browse and authority searches. Pending updates, retrying records and catalog-count differences no longer disable searches.
OPAC activation no longer waits for indexing to finish. Backend compatibility and OPAC visibility restrictions remain enforced.
Malformed MARC failures remain visible and retryable. Missing records stay absent from search until indexed; catalog readiness is a diagnostic report, not an activation prerequisite.
Initial setup continues when the worker reports individual record failures, while fatal worker errors remain explicit.
Apply to an installed library
Upload this KPZ without uninstalling. To enable OPAC using the updated plugin and reload Plack, replace INSTANCE in the paths and final argument with the library’s instance name:
SELECT RUSTSEARCH IN SEARCHENGINE to use the current index. No full reindex or catalog changes are required. The normal --existing-engine refresh also installs this behavior in the protected worker copy.
Verified with pending work and ten retrying decoding errors. Historical behavior described below is superseded by this update.
0.6.0 — protected multi-tenant setup
· Build a393940d4f77
Protected plugin directories: fixed setup stopping with “Permission denied” while checking or backing up an existing tenant’s plugin. File and ownership checks now use sudo without loosening Koha directory permissions.
Launcher access: the plugin’s setup guide now copies bundled launcher files with sudo, then runs the copy as the normal SSH user.
Correct refresh instructions: compatible schema-7 installations use --existing-engine. The guide no longer directs them to the legacy schema-6 engine updater.
Updating an existing library
Upload the latest KPZ through that library’s Koha plugin manager; do not uninstall the existing plugin.
Open the plugin’s Configuration page and follow its updated SSH instructions. For a compatible schema-7 engine, use the existing-engine refresh command. For an unfinished first installation, rerun normal setup for that instance.
Check indexing status and readiness, then test staff and OPAC searches. SELECT RUSTSEARCH UNDER ADMINISTRATION > SEARCHENGINE TO USE THE CURRENT INDEX. Indexing completeness is diagnostic; the separate OPAC flag validates visibility enforcement.
The compatible refresh reuses the engine binary and indexes and does not request a full reindex. Older or incompatible indexes require a separate migration. A failed setup can leave earlier steps installed; keep its log and backup paths.
Using an earlier extracted setup folder? It still contains the old installer. Use the newly uploaded KPZ’s setup guide to extract and run the corrected bundle.
Verified with 249 Python tests, 1,618 Perl assertions and a full setup run against a protected tenant plugin directory.
0.6.0 — OPAC activation and engine switching
· Earlier build d8d8ce412ce6; included in the latest package
Setup validates and enables OPAC automatically once indexing coverage is complete. If indexing is still running, the scheduled worker completes activation afterward.
Readiness cannot pass with OPAC activation disabled.
Saving a changed SEARCHENGINE through Koha Administration reloads that instance’s running Plack. The separate OPAC enable flag is preserved.
A failed automatic reload is reported explicitly. Direct SQL or command-line preference changes still require an explicit Plack reload.
0.6.0 — tenant setup and optional authorities
· Included in the latest package
One bundled setup can configure selected Koha instances. Each receives its own service, endpoint, indexes and worker; its dashboard uses its own Koha database for stats, errors and settings.
Interactive setup supports a normal sudo password and maintains authorization during long builds.
Recognized stock Koha source can receive the required plugin-engine integration with staged checks and backups.
Libraries without authority records can index author and subject text normally. Unresolved authority links remain unchanged in MARC and appear as separate warnings; real indexing failures remain retryable errors.
Installation, upgrades and validation details
Pagination repair — build 31c1a0e8b34a: update the existing plugin; do not uninstall. Larger Koha pages now use bounded native requests instead of failing above 100 results. Run the bundled server setup before SELECTING RUSTSEARCH IN SEARCHENGINE. Compatible schema-7 engines use --existing-engine; schema 6 requires coordinated migration. The corrected activation guard refuses incompatible engines. Repair instructions.
The latest build adds bounded item-ID lookup and faster ASCII normalization. Existing installations need an engine binary refresh; a KPZ upload alone does not update the executable. Performance update and upgrade details.
Release acceptance passed for the documented Koha MARC21 profile on ARM64 and x86-64. Validate your library’s catalog and settings in staging before production. Historical benchmark snapshots remain labeled as measurements, not live telemetry.
These notes describe packaged changes, not live server telemetry. Published benchmark statistics retain their saved measurements. See setup, migration and limits for the supported profile. When RustSearch is selected, searches execute in Rust without automatic fallback to another engine.