62b2a71dda
Enable a single LightRAG server instance to serve multiple isolated workspaces via HTTP header-based routing. This allows multi-tenant SaaS deployments where each tenant's data is completely isolated. Key features: - Header-based workspace routing (LIGHTRAG-WORKSPACE, X-Workspace-ID fallback) - Process-local pool of LightRAG instances with LRU eviction - FastAPI dependency (get_rag) for workspace resolution per request - Full backward compatibility - existing deployments work unchanged - Strict multi-tenant mode option (LIGHTRAG_ALLOW_DEFAULT_WORKSPACE=false) - Configurable pool size (LIGHTRAG_MAX_WORKSPACES_IN_POOL) - Graceful shutdown with workspace finalization Configuration: - LIGHTRAG_DEFAULT_WORKSPACE: Default workspace (falls back to WORKSPACE) - LIGHTRAG_ALLOW_DEFAULT_WORKSPACE: Require explicit header when false - LIGHTRAG_MAX_WORKSPACES_IN_POOL: Max concurrent workspace instances (default: 50) Files: - New: lightrag/api/workspace_manager.py (core multi-workspace module) - New: tests/test_multi_workspace_server.py (17 unit tests) - New: render.yaml (Render deployment blueprint) - Modified: All route files to use get_rag dependency - Updated: README.md, env.example with documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
87 lines
4.4 KiB
Markdown
87 lines
4.4 KiB
Markdown
# Implementation Plan: Multi-Workspace Server Support
|
|
|
|
**Branch**: `001-multi-workspace-server` | **Date**: 2025-12-01 | **Spec**: [spec.md](spec.md)
|
|
**Input**: Feature specification from `/specs/001-multi-workspace-server/spec.md`
|
|
|
|
## Summary
|
|
|
|
Implement server-level multi-workspace support for LightRAG Server by introducing:
|
|
1. A process-local pool of LightRAG instances keyed by workspace identifier
|
|
2. HTTP header-based workspace routing (`LIGHTRAG-WORKSPACE`, fallback `X-Workspace-ID`)
|
|
3. A FastAPI dependency that resolves the appropriate LightRAG instance per request
|
|
4. Configuration options for default workspace behavior and pool size limits
|
|
|
|
This builds on the existing workspace isolation in the LightRAG core (storage namespacing, pipeline status isolation) without re-implementing isolation at the storage level.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Python 3.10+
|
|
**Primary Dependencies**: FastAPI, Pydantic, asyncio, uvicorn
|
|
**Storage**: Delegates to existing backends (JsonKV, NanoVectorDB, NetworkX, Postgres, Neo4j, etc.)
|
|
**Testing**: pytest 8.4+, pytest-asyncio 1.2+ with `asyncio_mode = "auto"`
|
|
**Target Platform**: Linux server (also Windows/macOS for development)
|
|
**Project Type**: Single project - Python package with API server
|
|
**Performance Goals**: <10ms workspace routing overhead, <5s first-request initialization per workspace
|
|
**Constraints**: Full backward compatibility with existing single-workspace deployments
|
|
**Scale/Scope**: Support 50+ concurrent workspace instances (configurable)
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
| Principle | Requirement | Design Compliance |
|
|
|-----------|-------------|-------------------|
|
|
| **I. API Backward Compatibility** | No breaking changes to public API | ✅ No route/payload changes; existing behavior preserved when no workspace header |
|
|
| **II. Workspace/Tenant Isolation** | Data must never cross workspace boundaries | ✅ Leverages existing core isolation; each workspace gets separate LightRAG instance |
|
|
| **III. Explicit Configuration** | Config must be documented and validated | ✅ New env vars documented; startup validation for invalid configs |
|
|
| **IV. Multi-Workspace Test Coverage** | Tests for all new isolation logic | ✅ Test plan includes isolation, backward compat, config validation tests |
|
|
|
|
**Constitution Status**: ✅ All gates pass
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/001-multi-workspace-server/
|
|
├── plan.md # This file
|
|
├── research.md # Phase 0 output
|
|
├── data-model.md # Phase 1 output
|
|
├── quickstart.md # Phase 1 output
|
|
├── contracts/ # Phase 1 output (no new API contracts needed)
|
|
└── tasks.md # Phase 2 output (/speckit.tasks command)
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
lightrag/
|
|
├── api/
|
|
│ ├── lightrag_server.py # MODIFY: Integrate workspace pool and dependency
|
|
│ ├── config.py # MODIFY: Add multi-workspace config options
|
|
│ ├── workspace_manager.py # NEW: Instance pool and workspace resolution
|
|
│ ├── routers/
|
|
│ │ ├── document_routes.py # MODIFY: Use workspace dependency
|
|
│ │ ├── query_routes.py # MODIFY: Use workspace dependency
|
|
│ │ ├── graph_routes.py # MODIFY: Use workspace dependency
|
|
│ │ └── ollama_api.py # MODIFY: Use workspace dependency
|
|
│ └── utils_api.py # MODIFY: Add workspace-aware auth dependency
|
|
└── ...
|
|
|
|
tests/
|
|
├── conftest.py # MODIFY: Add multi-workspace fixtures
|
|
├── test_workspace_isolation.py # EXISTS: Core workspace isolation tests
|
|
└── test_multi_workspace_server.py # NEW: Server-level multi-workspace tests
|
|
```
|
|
|
|
**Structure Decision**: Extends existing single-project structure. New `workspace_manager.py` module encapsulates all multi-workspace logic to minimize changes to existing files.
|
|
|
|
## Complexity Tracking
|
|
|
|
> No Constitution Check violations requiring justification.
|
|
|
|
| Decision | Rationale |
|
|
|----------|-----------|
|
|
| Single new module (`workspace_manager.py`) | Centralizes multi-workspace logic; minimizes changes to existing code |
|
|
| LRU eviction for pool | Simple, well-understood algorithm; matches access patterns |
|
|
| Closure-to-dependency migration | Required for per-request workspace resolution; additive change |
|