No description
f170a3034b
Implemented the complete HTTP proxy layer with full Meilisearch API compatibility.
## Core Components
**HTTP Server (main.rs)**
- axum server on port 7700 with metrics endpoint on port 9090
- Graceful shutdown handling for SIGINT/SIGTERM
- Structured JSON logging middleware
- Prometheus metrics collection
**Write Path (documents.rs, write.rs, scatter.rs)**
- Hash-based sharding using XxHash64 (seed 0) for primary key → shard mapping
- Automatic injection of _miroir_shard field into all documents
- Fan-out to RG × RF nodes per replica group
- Per-group quorum enforcement (floor(RF/2)+1)
- X-Miroir-Degraded header when any group misses quorum
- 503 miroir_no_quorum only when no group met quorum
- Orchestrator-side retry cache for idempotency
**Read Path (search.rs, merger.rs)**
- Replica group selection via query_seq % RG (round-robin)
- Intra-group covering set construction for all shards
- Parallel scatter to covering set nodes
- Global result merge by _rankingScore descending
- Offset/limit applied AFTER merge (global ordering preserved)
- Automatic stripping of _miroir_* reserved fields
- Conditional stripping of _rankingScore (only if not requested)
- Facet aggregation across shards (sum counts)
- Group fallback when covering set has holes
**Index Lifecycle (indexes.rs, settings.rs)**
- Create: broadcasts to all nodes + injects _miroir_shard into filterableAttributes
- Settings: sequential apply-with-rollback on failure
- Delete: broadcasts to all nodes
- Stats: aggregates numberOfDocuments (max) + fieldDistribution (merge)
**Tasks (tasks.rs, task_manager.rs)**
- Per-task ID reconciliation across nodes
- Aggregated status: failed if any failed, processing if any processing, etc.
- Node completion tracking in task metadata
**Error Handling (error_response.rs)**
- Meilisearch-compatible shape: {message, code, type, link}
- Custom miroir_* error codes
- Proper HTTP status codes (503 for no_quorum, 404 for not_found, etc.)
**Auth (auth.rs)**
- Bearer token dispatch per plan §5 rules 2-5
- master-key: full access to all endpoints
- admin-key: admin-only endpoints (/admin/*, /_miroir/*)
- No token: public endpoints only (/health, /version)
- Invalid token: 403 Forbidden
**Admin Endpoints (admin.rs, health.rs)**
- GET /health - public health check
- GET /version - version info
- GET /_miroir/ready - readiness check (requires healthy nodes)
- GET /_miroir/topology - cluster topology with node health
- GET /_miroir/shards - shard assignment information
- GET /_miroir/metrics - Prometheus metrics (admin-key gated)
- GET /admin/stats - aggregated stats across all nodes
## Bug Fixes
This commit includes several bug fixes:
- Fixed query value extraction before moving req in search.rs
- Fixed JSON deserialization in settings.rs (body bytes → Value)
- Fixed NodeId reference passing in rollback_setting
- Fixed type signatures in scatter.rs (headers slice, error types)
- Fixed response body handling in scatter (use bytes directly)
## Testing
Integration tests written in tests/phase2_integration_test.rs:
- test_1000_documents_indexed_retrievable_by_id
- test_unique_keyword_search_finds_all_docs_once
- test_facet_aggregation_sums_correctly
- test_offset_limit_paging_preserves_global_ordering
- test_write_with_degraded_group_succeeds_with_header
- test_topology_endpoint_shape
- test_error_format_parity
- test_index_stats_aggregation
Tests marked #[ignore] as they require running Meilisearch nodes.
## Definition of Done
- [x] axum server on port 7700, metrics on 9090
- [x] Write path with hash, _miroir_shard injection, fan-out, quorum
- [x] Read path with group selection, covering set, merge, fallback
- [x] Index lifecycle with broadcast, settings rollback, delete, stats
- [x] Tasks with ID reconciliation and aggregation
- [x] Meilisearch-compatible error format
- [x] Reserved fields contract (_miroir_shard always-reserved)
- [x] Bearer token auth (master-key, admin-key)
- [x] /health, /version, /_miroir/* endpoints
- [x] Structured JSON logging + Prometheus metrics
- [x] Scatter-gather with retry cache
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
||
|---|---|---|
| .beads | ||
| charts/miroir | ||
| coverage | ||
| crates | ||
| docs | ||
| notes | ||
| .editorconfig | ||
| .gitignore | ||
| .needle-predispatch-sha | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| clippy.toml | ||
| lcov.info | ||
| LICENSE | ||
| README.md | ||
| rust-toolchain.toml | ||
| rustfmt.toml | ||
Miroir
Multi-node Index Replication Orchestrator, Integrated Rebalancing
Miroir is a RAID-like orchestration layer for Meilisearch. It stripes a large index across a fleet of small-RAM Meilisearch nodes with a configurable replication factor, fans out search queries across all shards, and rebalances shard assignments when nodes are added or removed — all using the Meilisearch Community Edition.
The Problem
Meilisearch loads its entire index into memory-mapped LMDB files. A large index that exceeds a single server's available RAM cannot run on that server. The Enterprise Edition's native sharding is gated behind a commercial license. Miroir solves this without it.
How It Works
Client
│
▼
Miroir Orchestrator
├── Write path: hash(doc_id) → assign to shard → write to R replicas
├── Read path: scatter query to all shards → gather → merge ranked results
└── Rebalance: on node add/remove → recompute assignments → migrate minimum shards
Meilisearch Nodes (N instances, each holding a subset of shards)
node-0 node-1 node-2 ... node-N
Replication Factor
Analogous to software RAID — configurable per deployment:
| RF | Redundancy | Node failures tolerated | Capacity |
|---|---|---|---|
| 1 | None (stripe only) | 0 | 100% of fleet |
| 2 | One replica | 1 per shard group | 50% of fleet |
| 3 | Two replicas | 2 per shard group | 33% of fleet |
Key Components
- Orchestrator — proxy that handles shard routing, scatter-gather, result merging, and topology management
- Shard router — consistent hash function (Rendezvous/HRW) mapping document IDs to node assignments; minimal reshuffling on topology change
- Rebalancer — on node add/remove, recomputes assignments and migrates only the shards that changed owners; surviving replicas serve reads during rebuild
- Result merger — normalizes and merges ranked result sets from multiple shards into a single coherent response
Status
Design phase. See docs/ for architecture detail.