matrx-orm 3.0.21__tar.gz → 3.0.22__tar.gz

matrx_orm-3.0.22/DESKTOP-API-INTEGRATION.md

@@ -0,0 +1,494 @@
+# Desktop App API Integration Guide
+
+> Complete guide for integrating matrx-orm with desktop applications
+> (Electron, Tauri, or any local HTTP client).
+
+---
+
+## Overview
+
+The `matrx_orm.api` module provides a **localhost-only HTTP + WebSocket server**
+that exposes your ORM managers as JSON-RPC endpoints. Your desktop frontend
+communicates with this server using standard HTTP requests.
+
+```
+Desktop App (Electron/Tauri)
+    │
+    ├── POST /auth/token      → Get bearer token
+    ├── POST /rpc             → CRUD operations
+    ├── GET  /ws              → WebSocket (streaming)
+    ├── GET  /health          → Health check
+    └── GET  /methods         → List available methods
+    │
+    ▼
+Python Backend (matrx-orm API Server)
+    │
+    ▼
+PostgreSQL
+```
+
+---
+
+## 1. Installation
+
+```bash
+pip install matrx-orm[api]
+```
+
+This adds `aiohttp` as an optional dependency.
+
+---
+
+## 2. Python Backend Setup
+
+### Minimal Server
+
+```python
+import asyncio
+import os
+from matrx_orm import register_database, DatabaseProjectConfig, BaseManager, Model
+from matrx_orm.api import APIServer, APIConfig
+
+# 1. Register your database
+register_database(DatabaseProjectConfig(
+    name="myapp",
+    host=os.getenv("DB_HOST", "localhost"),
+    port=os.getenv("DB_PORT", "5432"),
+    database_name=os.getenv("DB_NAME", "myapp"),
+    user=os.getenv("DB_USER", "postgres"),
+    password=os.getenv("DB_PASSWORD", "postgres"),
+))
+
+# 2. Import or define your models and managers
+# (Typically these are auto-generated by schema introspection)
+from myapp.models import User, Note
+from myapp.managers import UserManager, NoteManager
+
+user_mgr = UserManager(model=User)
+note_mgr = NoteManager(model=Note)
+
+# 3. Create and configure the API server
+server = APIServer(config=APIConfig(
+    secret=os.getenv("API_SECRET", ""),   # Auto-generates if empty
+    port=8745,
+))
+
+server.register_manager("users", user_mgr)
+server.register_manager("notes", note_mgr)
+
+# 4. Start
+asyncio.run(server.start())
+```
+
+### Configuration Options
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `host` | `"127.0.0.1"` | Bind address. **Keep this as localhost.** |
+| `port` | `8745` | TCP port |
+| `secret` | Auto-generated | Shared secret for token auth |
+| `token_ttl` | `86400` (24h) | Token lifetime in seconds |
+| `max_payload_bytes` | `10MB` | Maximum request body size |
+| `cors_origins` | localhost:3000/5173 | Allowed CORS origins |
+| `enable_websocket` | `True` | Enable `/ws` endpoint |
+| `log_requests` | `True` | Log each incoming RPC call |
+
+### Custom Methods
+
+You can register arbitrary async functions as RPC methods:
+
+```python
+async def search_notes(query: str, limit: int = 10, **params):
+    # Custom logic using raw SQL, multiple managers, etc.
+    results = await Note.filter(title__icontains=query).limit(limit).all()
+    return [r.to_dict() for r in results]
+
+server.register_method("notes.search", search_notes)
+```
+
+### Background Mode
+
+For embedding in a larger application:
+
+```python
+await server.start_background()
+
+# ... your app runs ...
+
+await server.stop()
+```
+
+---
+
+## 3. Authentication Flow
+
+### Step 1: Obtain Token
+
+```
+POST /auth/token
+Content-Type: application/json
+
+{
+  "secret": "your-shared-secret",
+  "client_id": "electron"
+}
+```
+
+Response:
+```json
+{
+  "token": "eyJ...<base64>.<hex-signature>",
+  "expires_in": 86400
+}
+```
+
+### Step 2: Use Token on All Requests
+
+```
+POST /rpc
+Authorization: Bearer eyJ...<base64>.<hex-signature>
+Content-Type: application/json
+
+{
+  "method": "users.load_items",
+  "params": {},
+  "id": 1
+}
+```
+
+### Step 3: Revoke Token (Optional)
+
+```
+POST /auth/revoke
+Authorization: Bearer <current-token>
+Content-Type: application/json
+
+{
+  "token": "<token-to-revoke>"
+}
+```
+
+---
+
+## 4. RPC Protocol
+
+### Request Format
+
+```json
+{
+  "method": "namespace.operation",
+  "params": { "key": "value" },
+  "id": 1
+}
+```
+
+### Success Response
+
+```json
+{
+  "result": { "id": "...", "username": "alice" },
+  "error": null,
+  "id": 1
+}
+```
+
+### Error Response
+
+```json
+{
+  "result": null,
+  "error": {
+    "code": 1001,
+    "message": "No User found matching: id=abc-123",
+    "data": { "model": "User" }
+  },
+  "id": 1
+}
+```
+
+### Batch Requests
+
+Send an array of requests to execute them concurrently:
+
+```json
+[
+  { "method": "users.count", "params": {}, "id": 1 },
+  { "method": "notes.count", "params": {}, "id": 2 },
+  { "method": "notes.load_items", "params": { "user_id": "..." }, "id": 3 }
+]
+```
+
+Response is an array of responses in the same order.
+
+---
+
+## 5. Available Methods
+
+Every registered manager exposes these methods under its namespace:
+
+### CRUD — Single Item
+
+| Method | Params | Returns |
+|--------|--------|---------|
+| `load_item` | `id=...` (or any PK filter) | `dict` |
+| `load_item_or_none` | `id=...` | `dict \| null` |
+| `load_by_id` | `item_id=...` | `dict` |
+| `create_item` | field=value pairs | `dict` |
+| `update_item` | `item_id=..., field=value` | `dict` |
+| `delete_item` | `item_id=...` | `bool` |
+| `exists` | `item_id=...` | `bool` |
+
+### CRUD — Bulk
+
+| Method | Params | Returns |
+|--------|--------|---------|
+| `load_items` | filter kwargs | `list[dict]` |
+| `load_items_by_ids` | `ids=[...]` | `list[dict]` |
+| `count` | filter kwargs | `int` |
+| `create_items` | `items_data=[{...}, ...]` | `list[dict]` |
+| `update_where` | `filters={...}, field=value` | `UpdateResult` |
+| `delete_where` | filter kwargs | `int` |
+| `upsert_item` | `data={...}, conflict_fields=[...], update_fields=[...]` | `dict` |
+| `get_or_create` | `defaults={...}, lookup_field=value` | `dict` |
+
+### Relationships
+
+| Method | Params | Returns |
+|--------|--------|---------|
+| `get_item_with_fk` | `item_id=..., fk_field="..."` | `[item, related]` |
+| `get_item_with_ifk` | `item_id=..., ifk_name="..."` | `[item, [related...]]` |
+| `get_item_with_m2m` | `item_id=..., m2m_name="..."` | `[item, [related...]]` |
+| `get_item_with_all_related` | `item_id=...` | `[item, all_relations]` |
+| `add_m2m` | `item_id=..., m2m_name="...", *target_ids` | `int` |
+| `remove_m2m` | `item_id=..., m2m_name="...", *target_ids` | `int` |
+| `set_m2m` | `item_id=..., m2m_name="...", target_ids=[...]` | `null` |
+| `clear_m2m` | `item_id=..., m2m_name="..."` | `int` |
+
+### Dict Variants
+
+| Method | Returns |
+|--------|---------|
+| `get_item_dict` | `dict` |
+| `create_item_get_dict` | `dict` |
+| `update_item_get_dict` | `dict` |
+
+---
+
+## 6. Error Codes
+
+| Code | Name | When |
+|------|------|------|
+| `-32700` | `PARSE_ERROR` | Invalid JSON |
+| `-32600` | `INVALID_REQUEST` | Missing method or bad format |
+| `-32601` | `METHOD_NOT_FOUND` | Unknown namespace or method |
+| `-32602` | `INVALID_PARAMS` | Wrong parameter types |
+| `-32603` | `INTERNAL_ERROR` | Unhandled server error |
+| `1001` | `NOT_FOUND` | Record does not exist |
+| `1002` | `VALIDATION_ERROR` | Data validation failed |
+| `1003` | `INTEGRITY_ERROR` | DB constraint violation |
+| `1004` | `AUTH_REQUIRED` | No token provided |
+| `1005` | `AUTH_INVALID` | Token expired or invalid |
+| `1008` | `CONNECTION_ERROR` | Database connection failed |
+| `1009` | `QUERY_ERROR` | SQL query error |
+
+---
+
+## 7. WebSocket Usage
+
+The WebSocket endpoint provides the same RPC interface with lower overhead
+for high-frequency calls.
+
+### Connection Flow
+
+```javascript
+const ws = new WebSocket("ws://127.0.0.1:8745/ws");
+
+ws.onopen = () => {
+  // First message: authenticate
+  ws.send(JSON.stringify({ token: "your-bearer-token" }));
+};
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+
+  if (data.type === "auth_ok") {
+    // Authenticated — now send RPC calls
+    ws.send(JSON.stringify({
+      method: "users.load_items",
+      params: {},
+      id: 1,
+    }));
+  }
+
+  if (data.result !== undefined) {
+    // RPC response
+    console.log("Result:", data.result);
+  }
+};
+```
+
+---
+
+## 8. Client Libraries
+
+### TypeScript (Electron / Tauri)
+
+See `tests/sample_project_desktop/client_example.ts` for a complete,
+zero-dependency TypeScript client with both HTTP and WebSocket support.
+
+### Python
+
+See `tests/sample_project_desktop/client_example.py` for an `aiohttp`-based
+Python client.
+
+---
+
+## 9. Security Checklist
+
+- [x] Server binds to `127.0.0.1` only — not reachable from network
+- [x] HMAC-SHA256 signed tokens — tamper-proof
+- [x] Token expiry (configurable TTL, default 24h)
+- [x] Token revocation support
+- [x] CORS restricted to specific origins
+- [x] Only allow-listed manager methods are callable (no arbitrary code exec)
+- [x] ORM errors mapped to safe error codes (no stack traces leaked)
+- [x] Maximum payload size enforced
+
+### For Production Desktop Apps
+
+Additional steps to implement in your application layer:
+
+1. **Secret delivery**: Write the auto-generated secret to a file readable
+   only by the current user (`chmod 600`), then read it from the desktop app.
+2. **Process isolation**: Run the Python backend as a child process of the
+   desktop app. Kill it on app exit.
+3. **Port discovery**: If port 8745 is taken, use port 0 (OS-assigned) and
+   communicate the actual port back to the parent process.
+4. **Scoped tokens**: Issue tokens with limited scopes (e.g. `["users.read"]`)
+   to restrict what the frontend can do.
+
+---
+
+## 10. Integration with matrx-local
+
+If you're using the [matrx-local](https://github.com/armanisadeghi/matrx-local)
+desktop application, here's what needs to happen on that side:
+
+### Required Changes in matrx-local
+
+1. **Install the Python backend** — The Electron app should bundle or spawn
+   a Python process that runs the matrx-orm API server.
+
+2. **Process management** — Add a module to spawn the Python backend on app
+   start and kill it on app quit:
+
+   ```typescript
+   // main/python-backend.ts
+   import { spawn, ChildProcess } from "child_process";
+   import { app } from "electron";
+   import path from "path";
+
+   let pythonProcess: ChildProcess | null = null;
+
+   export function startPythonBackend(secret: string): void {
+     const scriptPath = path.join(__dirname, "../python/server.py");
+
+     pythonProcess = spawn("python", [scriptPath], {
+       env: {
+         ...process.env,
+         API_SECRET: secret,
+         API_PORT: "8745",
+       },
+     });
+
+     pythonProcess.stdout?.on("data", (data) => {
+       console.log(`[python] ${data}`);
+     });
+
+     pythonProcess.stderr?.on("data", (data) => {
+       console.error(`[python] ${data}`);
+     });
+   }
+
+   export function stopPythonBackend(): void {
+     pythonProcess?.kill();
+     pythonProcess = null;
+   }
+
+   app.on("will-quit", stopPythonBackend);
+   ```
+
+3. **Client initialization** — Use the `MatrxClient` class from
+   `client_example.ts`:
+
+   ```typescript
+   // renderer/api.ts
+   import { MatrxClient } from "./matrx-client";
+
+   export const api = new MatrxClient(
+     "http://127.0.0.1:8745",
+     window.__MATRX_SECRET__ // Passed from main process
+   );
+
+   // Call on app startup
+   await api.authenticate();
+   ```
+
+4. **React hooks** (if using React):
+
+   ```typescript
+   // hooks/useMatrx.ts
+   import { useEffect, useState } from "react";
+   import { api } from "../api";
+
+   export function useMatrxQuery<T>(
+     method: string,
+     params: Record<string, unknown> = {},
+     deps: unknown[] = []
+   ) {
+     const [data, setData] = useState<T | null>(null);
+     const [loading, setLoading] = useState(true);
+     const [error, setError] = useState<Error | null>(null);
+
+     useEffect(() => {
+       let cancelled = false;
+       setLoading(true);
+
+       api.call<T>(method, params)
+         .then((result) => {
+           if (!cancelled) {
+             setData(result);
+             setLoading(false);
+           }
+         })
+         .catch((err) => {
+           if (!cancelled) {
+             setError(err);
+             setLoading(false);
+           }
+         });
+
+       return () => { cancelled = true; };
+     }, deps);
+
+     return { data, loading, error };
+   }
+
+   // Usage in a component:
+   function UserList() {
+     const { data: users, loading } = useMatrxQuery<User[]>("users.load_items");
+     if (loading) return <div>Loading...</div>;
+     return <ul>{users?.map(u => <li key={u.id}>{u.username}</li>)}</ul>;
+   }
+   ```
+
+### Files to Create in matrx-local
+
+| File | Purpose |
+|------|---------|
+| `python/server.py` | Copy of your API server script |
+| `python/requirements.txt` | `matrx-orm[api]` |
+| `src/main/python-backend.ts` | Process spawner |
+| `src/renderer/matrx-client.ts` | Copy of `client_example.ts` |
+| `src/renderer/hooks/useMatrx.ts` | React hooks for data fetching |
+| `src/renderer/api.ts` | Client singleton |

{matrx_orm-3.0.21 → matrx_orm-3.0.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.0.21
+Version: 3.0.22
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching. Works with any PostgreSQL database.
 Project-URL: Homepage, https://github.com/armanisadeghi/matrx-orm
 Project-URL: Repository, https://github.com/armanisadeghi/matrx-orm
@@ -32,6 +32,8 @@ Requires-Dist: matrx-utils>=1.0.16
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: api
+Requires-Dist: aiohttp>=3.9.0; extra == 'api'
 Provides-Extra: dev
 Requires-Dist: asyncpg-stubs>=0.30.0; extra == 'dev'
 Requires-Dist: pyright>=1.1.408; extra == 'dev'
@@ -1836,6 +1838,7 @@ When you run the schema builder against a database that has `vector(n)` columns,
 
 | Version | Highlights |
 |---|---|
+| **v3.0.22** | Patch release |
 | **v3.0.21** | Patch release |
 | **v3.0.20** | Patch release |
 | **v3.0.19** | Patch release |

{matrx_orm-3.0.21 → matrx_orm-3.0.22}/README.md

@@ -1795,6 +1795,7 @@ When you run the schema builder against a database that has `vector(n)` columns,
 
 | Version | Highlights |
 |---|---|
+| **v3.0.22** | Patch release |
 | **v3.0.21** | Patch release |
 | **v3.0.20** | Patch release |
 | **v3.0.19** | Patch release |

{matrx_orm-3.0.21 → matrx_orm-3.0.22}/TRANSACTION_POOLER_PLAN.MD

@@ -287,4 +287,5 @@ For batch-heavy workloads on any tier: the transaction pooler (port 6543\) is fr
 | Database migration | `Direct :5432 (IPv4 OK)` | `Supabase MCP / IPv6 runner` | Never run via Supavisor |
 | Pool exhausted | Circuit break, 503, alert | Circuit break, 503, alert | ORM raises PoolExhaustedError |
 
-Document generated from live Supabase MCP data — March 2026\. Update ProjectConnectionConfig entries if plans, compute tier, or IPv4 add-ons change.
+Document generated from live Supabase MCP data — March 2026\. Update ProjectConnectionConfig entries if plans, compute tier, or IPv4 add-ons change.
+

{matrx_orm-3.0.21 → matrx_orm-3.0.22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.0.21"
+version = "3.0.22"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching. Works with any PostgreSQL database."
 readme = "README.md"
 license = { text = "MIT" }
@@ -49,6 +49,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+api = [
+    "aiohttp>=3.9.0",
+]
 dev = [
     "asyncpg-stubs>=0.30.0",
     "pyright>=1.1.408",

{matrx_orm-3.0.21 → matrx_orm-3.0.22}/src/matrx_orm/__init__.py

@@ -191,6 +191,12 @@ from .migrations import (
     migrate_and_rebuild,
 )
 
+# ── Desktop API (optional — requires `pip install matrx-orm[api]`) ─────────
+# Imports are deferred to avoid hard dependency on aiohttp.
+def _lazy_api():
+    from matrx_orm.api import APIServer, APIConfig, TokenAuth
+    return APIServer, APIConfig, TokenAuth
+
 __all__ = [
     # ── Configuration ──────────────────────────────────────────────────────────
     "DatabaseProjectConfig",
@@ -385,4 +391,15 @@ __all__ = [
     "create_empty",
     "rollback",
     "migrate_and_rebuild",
+    # ── Desktop API (optional) ────────────────────────────────────────────────
+    "APIServer",
+    "APIConfig",
+    "TokenAuth",
 ]
+
+# Lazy imports for optional API module
+def __getattr__(name: str):
+    if name in ("APIServer", "APIConfig", "TokenAuth"):
+        from matrx_orm import api as _api
+        return getattr(_api, name)
+    raise AttributeError(f"module 'matrx_orm' has no attribute {name!r}")

matrx_orm-3.0.22/src/matrx_orm/api/__init__.py

@@ -0,0 +1,37 @@
+"""Secure local API server for desktop application integration.
+
+Provides a localhost-only HTTP + WebSocket server that exposes ORM operations
+to desktop frontends (Electron, Tauri, etc.) with token-based authentication.
+
+Install the optional dependency group::
+
+    pip install matrx-orm[api]
+
+Quick start::
+
+    from matrx_orm.api import APIServer, APIConfig
+
+    server = APIServer(config=APIConfig(secret="my-secret"))
+    server.register_manager("users", user_manager)
+    await server.start()
+"""
+
+from matrx_orm.api.config import APIConfig
+from matrx_orm.api.protocol import (
+    RPCRequest,
+    RPCResponse,
+    RPCError,
+    ErrorCode,
+)
+from matrx_orm.api.auth import TokenAuth
+from matrx_orm.api.server import APIServer
+
+__all__ = [
+    "APIConfig",
+    "APIServer",
+    "TokenAuth",
+    "RPCRequest",
+    "RPCResponse",
+    "RPCError",
+    "ErrorCode",
+]