fastapi-offline-sync 0.1.1__tar.gz

fastapi_offline_sync-0.1.1/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: fastapi-offline-sync
+Version: 0.1.1
+Summary: Offline-first sync primitives for FastAPI and MongoDB applications.
+Author: Fisco Team
+License: MIT
+Keywords: fastapi,indexeddb,mongodb,offline-first,react-native,sync
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: fastapi>=0.136.1
+Requires-Dist: motor>=3.7.1
+Requires-Dist: prometheus-client>=0.25.0
+Requires-Dist: prometheus-fastapi-instrumentator>=7.1.0
+Requires-Dist: pydantic-settings>=2.14.0
+Requires-Dist: pydantic>=2.13.3
+Requires-Dist: pymongo>=4.17.0
+Provides-Extra: dev
+Requires-Dist: build>=1.3.0; extra == 'dev'
+Requires-Dist: httpx>=0.28.1; extra == 'dev'
+Requires-Dist: mypy>=1.20.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.15.12; extra == 'dev'
+Requires-Dist: twine>=6.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fastapi-offline-sync
+
+`fastapi-offline-sync` is a robust, production-ready offline-first sync layer for FastAPI applications backed by MongoDB. It provides high-performance synchronization endpoints and live WebSocket updates with built-in conflict resolution, multi-worker safety, and atomic transactions.
+
+## Features
+
+- **Incremental Pull**: Efficient retrieval of incremental data changes using Hybrid Logical Clocks (HLC).
+- **Atomic Push Batches**: Safely apply client mutations in atomic MongoDB transactions, preventing partial state corruption.
+- **WebSocket Streaming**: Live Change Stream propagation for real-time document updates.
+- **Distributed Multi-Worker Safety**: Custom HLC node namespaces derived automatically or configured via container metadata to eliminate collision risks.
+- **Soft-Delete Propagation**: Seamless tombstones on full resyncs to clear obsolete client-side records.
+
+## Installation
+
+```bash
+pip install fastapi-offline-sync
+```
+
+## Quick Start
+
+Initialize and mount the router with production configurations:
+
+```python
+import os
+from fastapi import FastAPI
+from fastapi_offline_sync import SyncConfig, SyncRouter
+
+app = FastAPI(title="Production Sync Service")
+
+config = SyncConfig(
+    mongodb_uri=os.environ["MONGODB_URI"],
+    database_name=os.environ["MONGODB_DATABASE"],
+    collections=("tasks", "inventory_items"),
+    # Set unique HLC node ID (e.g., container hostname / Pod IP) for multi-worker safety
+    hlc_node_id=os.environ.get("HOSTNAME"),
+)
+
+app.include_router(SyncRouter(config))
+```
+
+## Authentication & Identity Resolution
+
+Configure a JWT dependency to verify credentials and return authenticated user properties.
+
+```python
+from fastapi import Header, HTTPException, status
+
+async def verify_jwt(
+    authorization: str | None = Header(default=None),
+) -> dict[str, str]:
+    if not authorization or not authorization.startswith("Bearer "):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing or invalid authentication header",
+        )
+    
+    token = authorization.removeprefix("Bearer ")
+    # Decode and verify the JWT with your auth provider
+    # Extract identity fields:
+    return {
+        "user_id": "user-unique-identifier",
+        "business_id": "business-tenant-identifier"
+    }
+```
+
+Then register the dependency with `SyncConfig`:
+
+```python
+config = SyncConfig(
+    mongodb_uri=os.environ["MONGODB_URI"],
+    database_name=os.environ["MONGODB_DATABASE"],
+    collections=("tasks",),
+    jwt_dependency=verify_jwt,
+)
+```
+
+## Fisco Integration
+
+For Fisco-style backends where data is scoped by business/tenant rather than individual user, configure the sync engine to scope operations by `business_id` while keeping the acting identity as `user_id`.
+
+```python
+from fastapi_offline_sync import SyncConfig, SyncRouter, SyncService
+
+config = SyncConfig(
+    mongodb_uri=os.environ["MONGODB_URI"],
+    database_name="Fisco",
+    collections=(
+        "inventory_items",
+        "categories",
+        "orders",
+        "customers",
+        "sales",
+    ),
+    actor_id_field="user_id",
+    scope_id_field="business_id",
+    jwt_dependency=verify_jwt,
+)
+
+router = SyncRouter(config)
+sync_service = SyncService(config)
+```
+
+### Server-Layer Writes
+
+For existing service-layer database writes, ensure that you append HLC metadata and oplog entries in the same session:
+
+1. Retrieve sync metadata with `sync_service.build_sync_metadata(actor=user, scope_id=business_id)`.
+2. Persist the metadata fields `_sync_version`, `_sync_actor_id`, `_sync_scope_id`, and `_sync_deleted` with the document.
+3. Record the change using `sync_service.record_server_change(...)`.
+
+## Deploying to Production
+
+Run the application using a production-grade ASGI server:
+
+```bash
+uvicorn examples.app:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+## API Reference
+
+### 1. Push Client Changes (`POST /sync/push`)
+Pushes client-side mutations to the server.
+
+```bash
+curl -X POST https://api.yourservice.com/sync/push \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <JWT_TOKEN>' \
+  -d '{
+    "client_id": "device-client-uuid",
+    "changes": [
+      {
+        "collection": "tasks",
+        "operation": "upsert",
+        "doc_id": "task-abc-123",
+        "data": {"title": "Acquire inventory", "done": false},
+        "parent_version": "20260502T120000.000Z-0001-a1b2"
+      }
+    ]
+  }'
+```
+
+### 2. Incremental Pull (`GET /sync/pull`)
+Fetches operations since a specific HLC token.
+
+```bash
+curl -H 'Authorization: Bearer <JWT_TOKEN>' \
+  'https://api.yourservice.com/sync/pull?since=20260502T120000.000Z-0001-a1b2&collections=tasks&limit=100'
+```
+
+### 3. Full Resync (`GET /sync/full`)
+Triggers a complete sync with Gzip compression and tombstones for soft-deleted documents.
+
+```bash
+curl -H 'Authorization: Bearer <JWT_TOKEN>' \
+  --compressed \
+  'https://api.yourservice.com/sync/full?collections=tasks&limit=1000'
+```
+
+### 4. Live Updates WebSocket (`WS /sync/stream`)
+Subscribes to live database modifications via a persistent WebSocket connection.
+
+```json
+{
+  "type": "subscribe",
+  "since": "20260502T120000.000Z-0001-a1b2",
+  "collections": ["tasks"],
+  "token": "<JWT_TOKEN>"
+}
+```

fastapi_offline_sync-0.1.1/PRD.MD

@@ -0,0 +1,408 @@
+Here’s the **Server‑Side PRD** for the `fastapi-offline-sync` package, extracted and detailed from the full offline sync engine. This focuses exclusively on the Python/FastAPI backend component.
+
+---
+
+# Product Requirements Document  
+## `fastapi-offline-sync` (Server‑Side Package)
+
+| Version | Date       | Author        | Status     |
+|---------|------------|---------------|------------|
+| 1.0     | 2026-05-02 | Fisco Team    | Draft      |
+
+---
+
+## 1. Introduction
+
+### 1.1 Purpose  
+`fastapi-offline-sync` is a Python library that adds offline‑first synchronization capabilities to any FastAPI application backed by MongoDB. It provides ready‑to‑use REST and WebSocket endpoints to accept, resolve, and redistribute data changes from intermittently connected clients. The package handles conflict resolution, change tracking, and fallback strategies, enabling developers to build offline‑resilient apps without reinventing the sync wheel.
+
+### 1.2 Problem Statement  
+Offline‑first mobile and web applications require a backend that can:
+- Accept batched changes from clients that have been offline for days or weeks.
+- Resolve conflicts deterministically without user intervention (or with customizable logic).
+- Serve a reliable, incremental stream of changes to bring stale clients up to date.
+- Operate efficiently even under intermittent, low‑bandwidth connections typical in regions like Nigeria.
+
+Existing sync solutions mostly target Node.js backends or require specific database adapters. This package gives the Python/FastAPI ecosystem a native, production‑ready answer.
+
+### 1.3 Target Audience  
+- Python developers building FastAPI + MongoDB applications that need offline support for web and React Native clients.
+- Open‑source contributors wanting to extend the FastAPI ecosystem with an offline sync layer.
+
+---
+
+## 2. Project Goals
+
+1. **Drop‑in integration**: add sync endpoints with minimal configuration (5 lines or less).
+2. **Reliable offline sync**: handle large backlogs, long offline gaps, and conflict storms.
+3. **Deterministic, configurable conflict resolution**: sensible defaults that can be overridden per collection.
+4. **Efficient delta sync**: serve only changes since the client’s last known version.
+5. **Graceful fallback**: when a client is too stale, provide a full data resync without data loss.
+6. **Real‑time live sync**: WebSocket support for instantly pushing changes to connected clients.
+7. **Observable, secure, and scalable**: metrics, authentication hooks, and horizontal scalability guidance.
+
+---
+
+## 3. Scope
+
+### In Scope
+- FastAPI router (`SyncRouter`) with:
+  - `POST /sync/push` – accept client changes.
+  - `GET /sync/pull` – deliver incremental changes.
+  - `GET /sync/full` – deliver complete dataset for stale clients.
+  - `WS /sync/stream` – real‑time change feed.
+- Hybrid Logical Clock (HLC) generation and ordering.
+- MongoDB oplog collection (`sync_oplog`) with TTL management.
+- Conflict resolution engine with default Last‑Writer‑Wins (LWW) and pluggable custom resolvers.
+- Per‑collection policies for delete‑update scenarios.
+- Authentication integration via FastAPI dependency injection (JWT scopes).
+- Full resync mechanism when client `since` is beyond oplog retention.
+- Prometheus metrics endpoint for sync operations.
+- Python type hints and auto‑generated OpenAPI documentation.
+
+### Out of Scope (Future)
+- Built‑in CRDT data types (Yjs/Automerge) – may be offered as optional extensions.
+- Peer‑to‑peer sync.
+- Client libraries.
+- Admin UI.
+- GraphQL subscription support.
+
+---
+
+## 4. Functional Requirements
+
+### FR1 – `POST /sync/push` – Client Change Ingestion
+
+**FR1.1** The endpoint accepts a JSON body with:
+- `client_id`: string (device identifier).
+- `changes`: array of change objects.
+
+Each change object:
+- `collection`: string (MongoDB collection name).
+- `operation`: `"upsert"` | `"delete"`.
+- `doc_id`: string or ObjectId.
+- `data`: object (null for delete).
+- `parent_version`: string (HLC version the change was based on).
+
+**FR1.2** The server processes each change sequentially, ensuring the following **atomic steps per change** (using MongoDB transactions):
+1. Fetch the current document from the business collection.
+2. Compare `parent_version` with the current document’s version (stored in a reserved `_sync_version` field or obtained from the oplog).
+3. If versions match → fast path: apply the change.
+4. If versions differ → invoke the conflict resolver for that collection.
+5. Generate a new HLC version.
+6. Store the resolved document in the business collection, setting `_sync_version` and `_sync_user_id`.
+7. Insert a new entry in `sync_oplog` with the new version, the final document snapshot, and metadata (`operation`, `collection`, `doc_id`, `user_id`, `parent_version`).
+8. Return a success or conflict status for the change.
+
+**FR1.3** The response contains an array of results, each with:
+- `doc_id`: string.
+- `status`: `"accepted"` | `"conflict_resolved"` | `"rejected"`.
+- `new_version`: (HLC string) if accepted or resolved.
+- `error`: optional message for rejection.
+
+**FR1.4** The endpoint requires a valid JWT (configurable via dependency). The authenticated user’s ID is used for `_sync_user_id` and may be compared against a user‑specific visibility scope (e.g., only own documents).
+
+**FR1.5** The server must handle partial batches: if one change fails validation, the whole batch may be rolled back (configurable) or individual failures returned, leaving successful changes applied.
+
+---
+
+### FR2 – `GET /sync/pull` – Incremental Change Feed
+
+**FR2.1** Query parameters:
+- `since` (required): HLC version to start pulling from (exclusive).
+- `collections` (optional): comma‑separated list of collection names to filter.
+- `limit` (optional, default 500, max 1000): max changes returned.
+- `user_id` (implicit from JWT, used to filter oplog entries).
+
+**FR2.2** The server queries `sync_oplog` for entries with `_id > since`, filtered by `user_id` (and optionally `collections`), sorted by `_id` ascending, limited by `limit`.
+
+**FR2.3** Response JSON:
+```json
+{
+  "changes": [
+    {
+      "version": "<hlc>",
+      "collection": "tasks",
+      "doc_id": "abc123",
+      "operation": "upsert",
+      "data": { ... }
+    }
+  ],
+  "last_seq": "<hlc>"   // the version of the last change in this batch, or the input `since` if empty
+}
+```
+
+**FR2.4** If `since` is older than the earliest oplog entry (i.e., older than the TTL), the server returns:
+```json
+{
+  "full_resync_required": true,
+  "collections": ["tasks", "projects"]  // affected collections from the request
+}
+```
+The client should then call the full resync endpoint.
+
+---
+
+### FR3 – `GET /sync/full` – Full Resync (Stale Client Fallback)
+
+**FR3.1** Query parameters:
+- `collections` (required): comma‑separated list of collections to export.
+- `cursor` (optional): pagination cursor (opaque string) for large datasets.
+- `limit` (optional, default 1000): batch size.
+
+**FR3.2** The server streams the current state of the requested collections as **Newline‑Delimited JSON (NDJSON)** with gzip compression (`Accept-Encoding: gzip`). Each line is a JSON object with `collection`, `doc_id`, and `data`.
+
+**FR3.3** Response headers include:
+- `X-Sync-Cursor`: cursor to request the next batch (if any remaining).
+- `X-Sync-LastSeq`: the latest HLC version of the included data (client will use as new `since` after full resync).
+- `Content-Type: application/x-ndjson`.
+
+**FR3.4** The endpoint must be efficient and not cause memory issues for large collections (use server‑side cursors).
+
+**FR3.5** Authentication and user scoping must still apply (only export documents the user is allowed to see).
+
+---
+
+### FR4 – `WS /sync/stream` – Real‑Time Sync
+
+**FR4.1** On connection, client sends a subscription message:
+```json
+{
+  "type": "subscribe",
+  "since": "<hlc>",
+  "collections": ["tasks", "projects"]
+}
+```
+
+**FR4.2** Server validates JWT from the WebSocket handshake (token passed as query parameter or in initial message).
+
+**FR4.3** Server begins monitoring the `sync_oplog` collection using MongoDB Change Streams, filtered to the user’s data and requested collections.
+
+**FR4.4** For each new oplog entry, the server pushes a JSON frame to the client:
+```json
+{
+  "version": "<hlc>",
+  "collection": "tasks",
+  "doc_id": "abc123",
+  "operation": "upsert",
+  "data": { ... }
+}
+```
+
+**FR4.5** Server must handle disconnections gracefully (no crash). A heartbeat/ping every 30 seconds keeps the connection alive.
+
+**FR4.6** If the oplog TTL has purged the requested `since`, the server sends:
+```json
+{
+  "type": "full_resync_required",
+  "collections": ["tasks", "projects"]
+}
+```
+and then closes the connection (client falls back to HTTP full resync).
+
+---
+
+### FR5 – Conflict Resolution Engine
+
+**FR5.1** The library includes a default conflict resolver `LastWriterWinsByHLC`. It compares the HLC of the incoming change’s parent version against the current document’s version; the change with the higher HLC wins. In case of identical HLC (rare), a tie‑breaking rule (e.g., lexicographic `doc_id`) is used.
+
+**FR5.2** Developers can provide a custom resolver function per collection via configuration:
+```python
+def custom_resolver(collection: str, doc_id: Any, current_doc: Optional[Dict], 
+                    incoming_change: Dict, current_version: str, incoming_parent_version: str) -> Dict:
+    # Return final document to store, or raise ConflictRejection
+    ...
+```
+
+**FR5.3** For delete‑update conflicts, a per‑collection policy can be set:
+- `resurrect_on_update` (default): if a client updates a deleted document, the document is recreated with the new data.
+- `reject_update`: the server rejects the update and returns a permanent conflict (the client must discard its change).
+- `delete_wins`: the update is ignored, and the document remains deleted (soft‑delete marker stays).
+
+**FR5.4** The conflict resolver is invoked inside the transaction that applies the change. It must be deterministic and fast (<10 ms typical).
+
+---
+
+### FR6 – Authentication & Authorization
+
+**FR6.1** All sync endpoints accept a FastAPI dependency injection for authentication (e.g., `Depends(get_current_user)`). The dependency returns a user object with at least `user_id`.
+
+**FR6.2** Optional: a collection‑scoped authorization callback can be registered. The server calls it before allowing push/pull/full for a specific collection, passing `user` and `collection` name. If it returns `False`, the operation is denied (403).
+
+**FR6.3** The `sync_oplog` entry includes `user_id` so that the pull endpoint can filter changes to only those visible to the requesting user (multi‑tenant safety).
+
+---
+
+### FR7 – Oplog & Database Management
+
+**FR7.1** The package creates a MongoDB collection named `sync_oplog` with the following schema:
+- `_id`: string (HLC version, e.g., `"20260502T143000.000Z-0001"`)
+- `timestamp`: datetime (used for TTL index)
+- `collection`: string
+- `doc_id`: any
+- `operation`: string (`upsert` / `delete`)
+- `data`: object (full document snapshot for upsert, null for delete)
+- `user_id`: string
+- `parent_version`: string (nullable)
+
+**FR7.2** A TTL index is created on `timestamp` with an expiry of `SYNC_OPLOG_TTL_DAYS` (configurable, default 30 days). This ensures the oplog doesn’t grow unbounded.
+
+**FR7.3** The business collections are augmented with a **reserved field** `_sync_version` (string, HLC) to track the latest sync version for each document. This field is managed solely by the sync engine and should not be modified by application code.
+
+**FR7.4** The engine supports MongoDB transactions (requires replica set) for atomic push operations. If transactions are not available (standalone), the library can fall back to non‑transactional writes with best‑effort consistency (explicitly documented as not recommended for production).
+
+**FR7.5** On startup, the library must verify/initialize the required indexes and collections. It should provide a CLI or helper function for setup (`fastapi-offline-sync init`).
+
+---
+
+### FR8 – Observability & Monitoring
+
+**FR8.1** Expose a Prometheus metrics endpoint (via `prometheus_fastapi_instrumentator` dependency) with these metrics:
+- `sync_push_total` (counter): number of push requests, labels: status (success/failure).
+- `sync_push_changes_total` (counter): total changes pushed.
+- `sync_conflict_total` (counter): number of conflicts detected, labels: collection.
+- `sync_pull_total` (counter): pull requests.
+- `sync_pull_changes_served` (counter): total changes returned to clients.
+- `sync_full_resync_total` (counter): full resync requests.
+- `sync_oplog_size` (gauge): estimated document count in oplog.
+- `sync_websocket_connections` (gauge): active WebSocket connections.
+
+**FR8.2** Logging: important events (conflicts, full resync triggers, connection errors) are logged at WARNING or INFO level using standard Python logging with structured fields for easy parsing.
+
+---
+
+## 5. Non‑Functional Requirements
+
+### NFR1 – Performance
+- Push endpoint processing time per change: < 10 ms (excluding network). Batch of 50 changes: < 500 ms total.
+- Pull endpoint response time: < 50 ms for batches up to 500 changes.
+- Full resync: streaming begins within 100 ms; supports collections with 100k+ documents without timeouts.
+- Oplog TTL index operates efficiently in aggregate.
+
+### NFR2 – Reliability
+- The sync engine must never lose a successfully pushed client change.
+- In the event of a server crash during a push transaction, MongoDB’s transaction guarantees ensure either full application or full rollback.
+- The oplog must be immutable (only appended to, never updated) to ensure pull consistency.
+- Full resync must always deliver the latest committed state of the database, not an intermediate dirty read.
+
+### NFR3 – Scalability
+- Operates as a stateless FastAPI service (except for the WebSocket state, which can be handled via sticky sessions or pub/sub backplane in future).
+- Can be horizontally scaled behind a load balancer; the use of MongoDB transactions and Change Streams ensures consistency across instances.
+- WebSocket connections scale linearly; recommended to use `redis` pub/sub for broadcasting changes across multiple server instances (out of scope for initial release but architecture should not preclude it).
+
+### NFR4 – Security
+- JWT validation on every endpoint; support for token refresh implied (client handles reconnection).
+- Input validation: `since` must be a valid HLC string; `limit` capped to 1000; collection names must pass a whitelist check if configured.
+- No sensitive data in logs.
+
+### NFR5 – Compatibility
+- Python 3.9+
+- FastAPI ≥ 0.100
+- MongoDB ≥ 4.4 (replica set for transactions and Change Streams)
+- `motor` (async MongoDB driver) or `pymongo` (synchronous fallback for certain operations if desired).
+
+### NFR6 – Developer Experience
+- Install via `pip install fastapi-offline-sync`.
+- Mount the sync router:
+```python
+from fastapi import FastAPI
+from fastapi_offline_sync import SyncRouter, SyncConfig
+
+app = FastAPI()
+sync_router = SyncRouter(config=SyncConfig(
+    mongodb_uri="mongodb://...",
+    database_name="mydb",
+    jwt_dependency=get_current_user  # FastAPI dependency
+))
+app.include_router(sync_router)
+```
+- Comprehensive API documentation generated from OpenAPI.
+- Configuration through environment variables or pydantic `Settings` class.
+
+---
+
+## 6. API Contract Details
+
+### 6.1 Push
+```
+POST /sync/push
+Authorization: Bearer <jwt>
+Content-Type: application/json
+
+{
+  "client_id": "device-xyz",
+  "changes": [
+    {
+      "collection": "tasks",
+      "operation": "upsert",
+      "doc_id": "task1",
+      "data": {"title": "Buy milk", "done": false},
+      "parent_version": "20260501T120000.000Z-0003"
+    }
+  ]
+}
+
+HTTP 200
+{
+  "results": [
+    {
+      "doc_id": "task1",
+      "status": "accepted",
+      "new_version": "20260502T150000.000Z-0005"
+    }
+  ]
+}
+```
+
+### 6.2 Pull
+```
+GET /sync/pull?since=20260502T150000.000Z-0005&collections=tasks&limit=100
+HTTP 200
+{
+  "changes": [...],
+  "last_seq": "20260502T151000.000Z-0008"
+}
+```
+
+### 6.3 Full Resync
+```
+GET /sync/full?collections=tasks,projects&cursor=optional
+Response: NDJSON stream with gzip
+...
+X-Sync-LastSeq: 20260502T151000.000Z-0008
+```
+
+### 6.4 WebSocket
+```
+ws://server/sync/stream?token=<jwt>
+→ {"type":"subscribe","since":"...","collections":["tasks"]}
+← {"version":"...","collection":"tasks","doc_id":"...","operation":"upsert","data":{...}}
+```
+
+---
+
+## 7. Implementation Milestones (Server Only)
+
+| Phase | Duration | Deliverables |
+|-------|----------|--------------|
+| **M1 – Setup & Core Libraries** | 1 week | Project scaffolding, HLC utility, MongoDB connection management, Pydantic models for API. |
+| **M2 – Oplog & Push Endpoint** | 2 weeks | `POST /sync/push` with transaction support, oplog collection and indexes, conflict resolution (LWW). |
+| **M3 – Pull & Full Resync** | 2 weeks | `GET /sync/pull`, `GET /sync/full`, full resync logic and stale detection. |
+| **M4 – WebSocket & Real‑Time** | 2 weeks | `WS /sync/stream`, Change Streams integration, heartbeat. |
+| **M5 – Hardening & Auth** | 1 week | Authentication dependency, authorization callbacks, per‑collection conflict policies, comprehensive error handling. |
+| **M6 – Observability & Docs** | 1 week | Prometheus metrics, structured logging, OpenAPI docs, README, contribution guide. |
+| **M7 – Testing & Release** | 1 week | Unit/integration tests (90%+ coverage), performance benchmarks, PyPI publication. |
+
+---
+
+## 8. Open Source & Community
+
+- **License**: MIT.
+- **Repository**: GitHub under `fisco/fastapi-offline-sync`.
+- **Contributing**: issue templates, pre‑commit hooks (black, ruff, mypy), CI with GitHub Actions against multiple MongoDB versions.
+- **Documentation site**: hosted on GitHub Pages with MkDocs.
+- **Community channel**: Discord server.
+
+---
+
+This server‑side PRD defines exactly what `fastapi-offline-sync` must deliver to become the backbone of Fisco’s offline capabilities and a valuable open‑source asset. Would you like me to now draft the **client‑side PRD** or dive deeper into any specific server feature like the hybrid logical clock implementation?