Clément THOMAS 62b2a71dda feat(api): add multi-workspace server support for multi-tenant deployments

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>

2025-12-01 12:07:22 +01:00

4.4 KiB

Raw Blame History

Implementation Plan: Multi-Workspace Server Support

Branch: 001-multi-workspace-server | Date: 2025-12-01 | Spec: 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:

A process-local pool of LightRAG instances keyed by workspace identifier
HTTP header-based workspace routing (LIGHTRAG-WORKSPACE, fallback X-Workspace-ID)
A FastAPI dependency that resolves the appropriate LightRAG instance per request
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)

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)

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

4.4 KiB Raw Blame History