HTTP API & Controllers
Relevant source files
The following files were used as context for generating this wiki page:
The PRKS HTTP API provides a structured interface for managing a personal research library, including Works, Folders, People, and Research Entities. The system uses a standard library Python HTTP adapter that handles request lifecycle, security validation, and dispatching to specialized controllers.
Sources: backend/server.py:108-115, AGENTS.md:15-18
Architecture and Lifecycle
The HTTP server is built on socketserver.ThreadingMixIn and http.server.TCPServer. It processes requests concurrently using PRKSHandler, which inherits from SimpleHTTPRequestHandler. The backend is currently transitioning from a monolithic handler in server.py to decomposed controllers located in backend/api/.
Request Processing Flow
Every incoming request passes through a series of validation gates before reaching the domain logic.
The admission gate (_prks_admit) enforces host/origin checks for mutations and handles session-based authentication when configured. The LibraryAccessGate manages concurrent access by acquiring read or write scopes based on the requested route.
Sources: backend/server.py:539-550, backend/server.py:657-684, backend/server.py:686-728
Security Headers and Controls
The server enforces several security policies through HTTP headers:
| Header | Purpose | Value/Behavior |
|---|---|---|
X-Content-Type-Options | Prevents MIME sniffing | nosniff (on every response) |
X-Request-ID | Tracks request lifecycle | Generated UUID (12 hex chars) |
Cache-Control | Manages browser caching | no-store for shell; immutable for assets |
Server-Timing | Performance telemetry | Metrics for encode, compression, etc. |
Sources: backend/server.py:782-823, backend/server.py:1016-1033
Controller Responsibility
Controllers parse path and query parameters, validate request body shapes, invoke domain modules (e.g., db_manager, research_network), and map domain errors to HTTP status codes.
Body Parsing and Validation
The server limits JSON body sizes to 50 MiB. Requests for mutations (POST, PATCH, PUT) require an application/json Content-Type.
# Example of body validation in server.py
def _read_json_body(self):
types = self.headers.get_all("Content-Type") or []
if len(types) != 1 or not json_content_type_allowed(types[0]):
self._reject_request(415, "unsupported_media_type", "unsupported_media_type")
return _JSON_BODY_REJECTED
# ... size and length checks ...
return json.loads(payload)
Sources: backend/server.py:730-760, AGENTS.md:535-545
API Feature Families
The API is organized into several functional families, some of which are documented via OpenAPI specifications.
Research Network (Positions, Concepts, Arguments)
The Research Network API allows for structured research relationships. Positions and Arguments support complex metadata and targets.
Managed PDF and Media
The server handles PDF uploads, linearized serving, and thumbnail generation.
- Uploads: Handled via
POST /api/workswithfile_b64. The server mints unique filenames and validates containment within the managed directory. - Serving: Supports HTTP Range requests, enabling progressive loading for WASM-based PDF engines.
- Thumbnails: Generated on-demand using PyMuPDF and cached as WebP or JPEG.
Sources: backend/server.py:1145-1215, backend/server.py:910-975, tests/test_server_api.py:345-380
Sync and Operations
The /api/sync/operations endpoint processes durable operations from local-first clients. It manages relationship revisions and research index synchronization.
| Endpoint | Method | Description |
|---|---|---|
/api/sync/operations | POST | Processes durable ledger entries (tags, notes, deletes) |
/api/works/{id}/metadata-state | GET | Returns field-level revisions for metadata |
/api/persons/{id}/group-state | GET | Returns membership revisions and tombstones |
Sources: backend/server.py:1062-1090, backend/server.py:1515-1530
Client-Side Request Coordination
The frontend uses a createPrksRequestCoordinator to manage API traffic. It implements several sophisticated patterns:
- Deduplication: Identical GET requests in flight are joined to a single network call.
- Burst Caching: Responses are cached for 1500ms to handle rapid UI updates.
- Prioritization: Supports "foreground" and "background" request queues.
- Mutation Epochs: Any mutation increments an epoch that invalidates all read caches.
Sources: frontend/js/request-coordinator.js:235-260, frontend/js/request-coordinator.js:465-495
Conclusion
The HTTP API & Controllers in PRKS serve as the critical bridge between the local-first frontend and the Python-based backend. By enforcing strict host validation, atomic materialization locks for PDFs, and epoch-based caching, the system ensures data integrity and security across both SQLite and the emerging PostgreSQL architectures.
Sources: AGENTS.md:520-530, backend/server.py:1580-1600