detrix-py 1.0.0__tar.gz

detrix_py-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+**target**
+.cargo/
+.claude/
+logs/
+fixtures/go/detrix_example_app
+
+# Go client built binaries
+clients/go/basic_usage
+clients/go/test_wake
+clients/go/trade_bot
+fixtures/go/go

detrix_py-1.0.0/ARCHITECTURE.md

@@ -0,0 +1,282 @@
+# Python Client Architecture
+
+This document describes the architecture of the Detrix Python client.
+
+## Module Structure
+
+```
+src/detrix/
+├── __init__.py      # Public API: init, status, wake, sleep, shutdown
+├── _operations.py   # Core wake/sleep operations (shared by __init__ and control)
+├── _state.py        # Global state singleton with thread-safe access
+├── auth.py          # Token discovery (env var, file)
+├── config.py        # Configuration utilities (ports, names, env vars)
+├── control.py       # HTTP control plane server
+├── daemon.py        # Daemon client protocol and HTTP implementation
+├── debugger.py      # debugpy lifecycle management
+├── errors.py        # Error type hierarchy
+└── py.typed         # PEP 561 marker for type checking
+```
+
+## Module Dependencies
+
+```
+┌─────────────────┐
+│   __init__.py   │  ← Public API (delegates to _operations)
+│   control.py    │  ← HTTP server (delegates to _operations)
+├─────────────────┤
+│  _operations.py │  ← Core wake/sleep logic (shared)
+├─────────────────┤
+│   daemon.py     │  ← Daemon communication
+│   debugger.py   │  ← debugpy management
+├─────────────────┤
+│   _state.py     │  ← Global state singleton
+│   auth.py       │  ← Token handling
+│   config.py     │  ← Configuration
+│   errors.py     │  ← Error types
+└─────────────────┘
+```
+
+**Dependency Rules:**
+- `__init__.py` imports from `_operations`, `_state`, `config`, `control`, `daemon`, `debugger`, `errors`
+- `control.py` imports from `_operations`, `_state`, `auth`, `debugger`, `errors`
+- `_operations.py` imports from `_state`, `auth`, `daemon`, `debugger`, `errors`
+- `daemon.py` imports only from `errors`
+- `debugger.py` has no local imports (only stdlib + debugpy)
+- `_state.py`, `auth.py`, `config.py`, `errors.py` have no local imports
+
+## State Machine
+
+```
+┌──────────┐               ┌────────┐    success    ┌───────┐
+│ SLEEPING │ ──────────► │ WAKING │ ───────────► │ AWAKE │
+└──────────┘    wake()     └────────┘              └───────┘
+    ▲                          │                      │
+    │                          │ failure              │
+    │                          └──────────────────────┤
+    │                                                 │
+    │                               sleep()           │
+    └─────────────────────────────────────────────────┘
+```
+
+**Note:** WAKING is a transitional state used internally during `wake()` to allow
+`status()` calls while network I/O is in progress. It is not exposed in the public API.
+
+### States
+
+| State    | debugpy Loaded | debugpy Listening | Registered with Daemon |
+|----------|----------------|-------------------|------------------------|
+| SLEEPING | No             | No*               | No                     |
+| WAKING   | Yes            | In progress       | In progress            |
+| AWAKE    | Yes            | Yes               | Yes                    |
+
+*Note: After first wake, debugpy port remains open due to debugpy limitation.
+The `debug_port_active` field tracks the actual port state.
+
+**WAKING** is a transitional state that exists only during the `wake()` call while
+network I/O is in progress. This allows `status()` to return immediately without
+blocking on daemon communication.
+
+### Transitions
+
+| From     | To       | Trigger        | Actions                                    |
+|----------|----------|----------------|--------------------------------------------|
+| SLEEPING | WAKING   | wake()         | Load debugpy, mark transitional            |
+| WAKING   | AWAKE    | wake() success | Start listener, register with daemon       |
+| WAKING   | SLEEPING | wake() failure | Revert to sleeping state                   |
+| AWAKE    | SLEEPING | sleep()        | Unregister, mark state (port stays open)   |
+
+## Thread Safety
+
+### Global State Access
+
+All state access must use the `ClientState.lock` (RLock):
+
+```python
+state = get_state()
+with state.lock:
+    # Read or modify state fields
+    state.state = State.AWAKE
+    state.connection_id = "..."
+```
+
+The lock is reentrant to allow nested acquisitions in the same thread.
+
+### Lock-Free Pattern for Network I/O
+
+The `wake()` and `sleep()` functions use a three-phase lock-free pattern to
+prevent `status()` calls from blocking during network I/O:
+
+```python
+# Phase 1: Read state (short lock)
+with state.lock:
+    if state.state == State.AWAKE:
+        return already_awake_result
+    previous_state = state.state
+    state.state = State.WAKING  # Transitional state
+    # Capture config for use outside lock
+    daemon_url = state.daemon_url
+    ...
+
+# Phase 2: Network I/O (no lock held)
+# status() can return immediately while this runs
+check_daemon_health(daemon_url)
+register_connection(...)
+
+# Phase 3: Update state (short lock)
+with state.lock:
+    state.state = State.AWAKE
+    state.connection_id = connection_id
+```
+
+### Wake Lock
+
+A separate `wake_lock` (non-reentrant Lock) prevents concurrent `wake()` calls:
+
+```python
+if not state.wake_lock.acquire(blocking=False):
+    # Another thread is waking - wait for it
+    with state.wake_lock:
+        pass
+    # Check result and return
+```
+
+This ensures only one wake operation runs at a time, while allowing `status()`
+and other read operations to proceed without blocking.
+
+### Control Plane Thread
+
+The HTTP control plane runs in a daemon thread. Request handlers access the
+global state through the lock. The daemon thread flag ensures the thread
+terminates when the main process exits.
+
+### Lock Acquisition Order
+
+When multiple locks are needed:
+1. Try `wake_lock` first (non-blocking)
+2. Then acquire `ClientState.lock` briefly for state reads/writes
+3. Never hold any lock during network I/O
+
+## Error Hierarchy
+
+```
+DetrixError (base)
+├── ConfigError        # Configuration/initialization errors
+├── DaemonError        # Communication with daemon failed
+├── DebuggerError      # debugpy-related errors
+└── ControlPlaneError  # Control plane server errors
+```
+
+`DaemonConnectionError` is kept as an alias for `DaemonError` for backward
+compatibility.
+
+## Control Plane HTTP API
+
+| Endpoint        | Method | Auth Required | Description                |
+|-----------------|--------|---------------|----------------------------|
+| /detrix/health  | GET    | No            | Health check               |
+| /detrix/status  | GET    | Remote only   | Get current status         |
+| /detrix/info    | GET    | Remote only   | Get process info           |
+| /detrix/wake    | POST   | Remote only   | Start debugger + register  |
+| /detrix/sleep   | POST   | Remote only   | Unregister connection      |
+
+### Authentication
+
+- Localhost requests (127.0.0.1, ::1, localhost, 0.0.0.0) are always allowed
+- Remote requests require Bearer token matching DETRIX_TOKEN or ~/detrix/mcp-token
+- If no token is configured, remote requests are DENIED (security-first default)
+
+## Known Limitations
+
+### 1. debugpy Cannot Stop Listener
+
+**Symptom:** After `sleep()`, the debug port remains open.
+
+**Cause:** debugpy does not support stopping its listener once started. The
+`listen()` function can only be called once per process.
+
+**Impact:**
+- `debug_port_active` remains True after sleep
+- Same port is reused on subsequent wake calls
+- Port is freed only when process exits
+
+**Reference:** https://github.com/microsoft/debugpy/issues/895
+
+### 2. Port Allocation Race Condition (TOCTOU) - FIXED
+
+**Previous Issue:** `get_free_port()` found a free port, closed the socket, then
+passed the port to debugpy. Another process could grab the port in between.
+
+**Fix:** We now pass `debug_port=0` directly to `debugpy.listen()`, which handles
+port allocation atomically. The port is assigned by the OS at bind time, with no
+window for another process to claim it.
+
+**Note:** `get_free_port()` still exists in `config.py` for other use cases,
+but is no longer used in the wake path.
+
+### 3. Control Server Thread Termination
+
+**Symptom:** Control server thread may not terminate immediately on shutdown.
+
+**Cause:** HTTP server shutdown is cooperative. If a request is in progress,
+the thread waits for it to complete.
+
+**Impact:** Warning logged if thread doesn't terminate within timeout (default 2s).
+Thread is marked as daemon, so it won't prevent process exit.
+
+## Configuration Priority
+
+Configuration values are resolved in this order (first wins):
+1. Explicit parameters to `init()`
+2. Environment variables (DETRIX_*)
+3. Default values
+
+| Parameter             | Env Variable                  | Default                 |
+|-----------------------|-------------------------------|-------------------------|
+| name                  | DETRIX_NAME                   | "detrix-client-{pid}"   |
+| control_host          | DETRIX_CONTROL_HOST           | "127.0.0.1"             |
+| control_port          | DETRIX_CONTROL_PORT           | 0 (auto-assign)         |
+| debug_port            | DETRIX_DEBUG_PORT             | 0 (auto-assign)         |
+| daemon_url            | DETRIX_DAEMON_URL             | "http://127.0.0.1:8090" |
+| token                 | DETRIX_TOKEN                  | (from file)             |
+| detrix_home           | DETRIX_HOME                   | ~/detrix                |
+| health_check_timeout  | DETRIX_HEALTH_CHECK_TIMEOUT   | 2.0 seconds             |
+| register_timeout      | DETRIX_REGISTER_TIMEOUT       | 5.0 seconds             |
+| unregister_timeout    | DETRIX_UNREGISTER_TIMEOUT     | 2.0 seconds             |
+
+## DaemonClient Protocol
+
+The `DaemonClient` protocol enables dependency injection and testing:
+
+```python
+class DaemonClient(Protocol):
+    def health_check(self, timeout: float = 2.0) -> bool: ...
+    def register(self, host: str, port: int, connection_id: str,
+                 token: Optional[str] = None, timeout: float = 5.0) -> str: ...
+    def unregister(self, connection_id: str,
+                   token: Optional[str] = None, timeout: float = 2.0) -> None: ...
+```
+
+`HttpDaemonClient` is the default implementation using httpx with connection pooling.
+
+## Go/Rust Implementation Notes
+
+When implementing clients in Go or Rust:
+
+1. **Singleton Pattern:** Use package-level state with mutex protection
+   - Go: `sync.RWMutex` protecting a struct
+   - Rust: `OnceCell<RwLock<ClientState>>`
+
+2. **Error Handling:** Implement equivalent error types with the same hierarchy
+
+3. **HTTP Client:** Use native HTTP clients (net/http, reqwest) implementing
+   the same endpoints and error handling
+
+4. **Debug Adapter:** Use language-appropriate DAP libraries (delve for Go,
+   lldb-dap/CodeLLDB for Rust)
+
+5. **Thread Safety:** Use native synchronization primitives matching the Python
+   RLock semantics (reentrant mutex)
+
+6. **Known Limitations:** Document the same limitations - debug adapter port
+   persistence is a common issue across DAP implementations

detrix_py-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ilya Dyachenko https://github.com/flashus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

detrix_py-1.0.0/PKG-INFO

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: detrix-py
+Version: 1.0.0
+Summary: Python client for Detrix - debug-on-demand observability with zero overhead
+Project-URL: Homepage, https://github.com/flashus/detrix
+Project-URL: Documentation, https://github.com/flashus/detrix/tree/main/clients/python
+Project-URL: Repository, https://github.com/flashus/detrix
+Author: Ilya Dyachenko
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dap,debugging,debugpy,metrics,observability
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: debugpy>=1.8.0
+Requires-Dist: httpx>=0.28.1
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.25.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Detrix Python Client
+
+Debug-on-demand observability for Python applications with zero overhead when inactive.
+
+## Overview
+
+The Detrix Python client enables your application to be observed by the [Detrix](https://github.com/flashus/detrix) daemon without:
+
+- **Code modifications** - No print statements or logging changes needed
+- **Redeployment** - Add metrics to running processes
+- **Performance overhead** - Zero cost when not actively observing
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add detrix-py
+
+# Using pip
+pip install detrix-py
+```
+
+## Quick Start
+
+### 1. Start the Detrix daemon
+
+```bash
+detrix serve --daemon
+```
+
+### 2. Initialize the client in your application
+
+```python
+import detrix
+
+# Initialize client - starts control plane, stays SLEEPING (zero overhead)
+detrix.init(
+    name="my-service",
+    daemon_url="http://127.0.0.1:8090",
+)
+
+# Your application code runs normally...
+def process_request(request):
+    data = transform(request)
+    return data
+```
+
+### 3. Enable observability when needed
+
+```python
+# Wake up - starts debugger, registers with daemon
+detrix.wake()
+
+# Now the daemon can set observation points on any line
+# No code changes needed!
+
+# When done observing
+detrix.sleep()
+```
+
+## Try It
+
+Run the end-to-end example that simulates an AI agent: starts a sample app, wakes it, adds metrics, and captures events.
+
+```bash
+# 1. Start the Detrix server
+detrix serve --daemon
+
+# 2. Run the agent simulation (from clients/python/)
+uv run python examples/test_wake.py --daemon-port 8090
+```
+
+Other examples in `examples/`:
+
+| Example | Description | Run |
+|---------|-------------|-----|
+| `basic_usage.py` | Init / wake / sleep cycle | `uv run python examples/basic_usage.py` |
+| `trade_bot_detrix.py` | Long-running app with embedded client | `uv run python examples/trade_bot_detrix.py` |
+| `test_wake.py` | Agent simulation (starts app, wakes, observes) | `uv run python examples/test_wake.py` |
+
+## API Reference
+
+### `detrix.init(**kwargs)`
+
+Initialize the client. Starts the control plane HTTP server.
+
+**Parameters:**
+- `name` (str): Connection name (default: `"detrix-client-{pid}"`)
+- `control_host` (str): Control plane host (default: `"127.0.0.1"`)
+- `control_port` (int): Control plane port (default: `0` = auto-assign)
+- `debug_port` (int): debugpy port (default: `0` = auto-assign on wake)
+- `daemon_url` (str): Detrix daemon URL (default: `"http://127.0.0.1:8090"`)
+- `start_state` (str): Initial state `"sleeping"` or `"warm"` (default: `"sleeping"`)
+- `detrix_home` (str): Path to Detrix home directory (default: `~/detrix`)
+- `health_check_timeout` (float): Timeout for daemon health checks in seconds (default: `2.0`)
+- `register_timeout` (float): Timeout for connection registration in seconds (default: `5.0`)
+- `unregister_timeout` (float): Timeout for connection unregistration in seconds (default: `2.0`)
+
+### `detrix.status() -> dict`
+
+Get current client status.
+
+**Returns:**
+```python
+{
+    "state": "sleeping" | "warm" | "awake",
+    "name": "my-service-12345",
+    "control_host": "127.0.0.1",
+    "control_port": 9000,
+    "debug_port": 5678,  # 0 if never awake
+    "debug_port_active": True,  # True if debug port is actually open
+    "daemon_url": "http://127.0.0.1:8090",
+    "connection_id": "my-service-12345",  # None if not awake
+}
+```
+
+### `detrix.wake(daemon_url: str = None) -> dict`
+
+Start debugger and register with daemon.
+
+**Parameters:**
+- `daemon_url` (str): Override daemon URL (optional)
+
+**Raises:**
+- `DaemonError`: If daemon is not reachable or URL is invalid
+
+**Returns:**
+```python
+{"status": "awake", "debug_port": 5678, "connection_id": "my-service-12345"}
+```
+
+### `detrix.sleep() -> dict`
+
+Stop debugger and unregister from daemon.
+
+**Returns:**
+```python
+{"status": "sleeping"}
+```
+
+### `detrix.shutdown()`
+
+Stop control server and cleanup. Call `init()` again to reinitialize.
+
+## State Machine
+
+```
+┌──────────┐         wake()          ┌───────┐
+│ SLEEPING │ ──────────────────────►│ AWAKE │
+└──────────┘                         └───────┘
+    ▲                                   │
+    │              sleep()               │
+    └────────────────────────────────────┘
+```
+
+- **SLEEPING**: No debugger loaded, zero overhead
+- **AWAKE**: debugpy listening, registered with daemon
+
+## Control Plane HTTP Endpoints
+
+The client exposes a local HTTP server for management:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/detrix/health`  | GET | Health check |
+| `/detrix/status`  | GET | Get current status |
+| `/detrix/info`    | GET | Get process info |
+| `/detrix/wake`    | POST | Start debugger + register |
+| `/detrix/sleep`   | POST | Stop debugger + unregister |
+
+## Environment Variables
+
+| Variable                        | Description                              |
+|---------------------------------|------------------------------------------|
+| `DETRIX_NAME`                   | Default connection name                  |
+| `DETRIX_CONTROL_HOST`           | Control plane host                       |
+| `DETRIX_CONTROL_PORT`           | Control plane port                       |
+| `DETRIX_DEBUG_PORT`             | debugpy port                             |
+| `DETRIX_DAEMON_URL`             | Daemon URL                               |
+| `DETRIX_TOKEN`                  | Authentication token                     |
+| `DETRIX_HOME`                   | Detrix home directory                    |
+| `DETRIX_HEALTH_CHECK_TIMEOUT`   | Timeout for daemon health checks (secs)  |
+| `DETRIX_REGISTER_TIMEOUT`       | Timeout for connection registration (secs)|
+| `DETRIX_UNREGISTER_TIMEOUT`     | Timeout for connection unregistration (secs)|
+
+## Security
+
+### Authentication
+
+The control plane HTTP server has a security-first authentication model:
+
+- **Localhost requests** (127.0.0.1, ::1, localhost) are always allowed without authentication
+- **Remote requests** require a valid Bearer token
+
+To enable remote access:
+1. Set `DETRIX_TOKEN` environment variable, or
+2. Create `~/detrix/mcp-token` file with the token
+
+If no token is configured, remote requests are denied by default.
+
+### Remote Exposure Guidelines
+
+The control plane is designed for **localhost access only** by default. If you need to expose it remotely:
+
+1. **Always configure authentication** - Set `DETRIX_TOKEN` or create `~/detrix/mcp-token`
+2. **Use a reverse proxy** - Place nginx, HAProxy, or similar in front for:
+   - TLS termination (HTTPS)
+   - Rate limiting
+   - Access logging
+   - IP allowlisting
+3. **Restrict network access** - Use firewall rules to limit which hosts can connect
+4. **Protect the token file** - Ensure `~/detrix/mcp-token` has restrictive permissions (`chmod 600`)
+
+Example nginx configuration:
+```nginx
+location /detrix/ {
+    # Rate limiting
+    limit_req zone=detrix burst=10 nodelay;
+
+    # Proxy to control plane
+    proxy_pass http://127.0.0.1:9000;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+}
+```
+
+**Note:** The control plane exposes debugging capabilities. Unauthorized access could allow an attacker to inspect process state. Always treat it as a sensitive endpoint.
+
+## Error Handling
+
+The client provides a hierarchy of exception types:
+
+```python
+from detrix import DetrixError, ConfigError, DaemonError, DebuggerError
+
+try:
+    detrix.wake()
+except DaemonError as e:
+    print(f"Cannot reach daemon: {e}")
+except DebuggerError as e:
+    print(f"Debugger error: {e}")
+except DetrixError as e:
+    print(f"General error: {e}")
+```
+
+- `DetrixError`: Base class for all Detrix errors
+- `ConfigError`: Configuration/initialization errors
+- `DaemonError`: Communication with daemon failed
+- `DebuggerError`: debugpy-related errors
+- `ControlPlaneError`: Control plane server errors
+
+Note: `DaemonConnectionError` is kept as an alias for `DaemonError` for backward compatibility.
+
+## Known Limitations
+
+### 1. debugpy Port Remains Open After Sleep
+
+**Issue:** After calling `sleep()`, the debug port remains open until the process exits.
+
+**Cause:** This is a limitation of debugpy itself - it does not support stopping its listener once started. See [debugpy#895](https://github.com/microsoft/debugpy/issues/895).
+
+**Impact:**
+- The `debug_port_active` field in status remains `True` after sleep
+- Calling `wake()` after `sleep()` reuses the same port
+- The port is only freed when the process terminates
+
+**Workaround:** This is expected behavior. If you need to fully release the port, you must restart the process.
+
+### 2. Port Allocation Race Condition (Fixed)
+
+**Previous issue:** Another process could claim a port between detection and binding.
+
+**Resolution:** The client now passes `port=0` directly to `debugpy.listen()`, which
+handles port allocation atomically at bind time. There is no window for another
+process to claim the port.
+
+**Note:** If you explicitly specify a port via `debug_port` parameter or
+`DETRIX_DEBUG_PORT`, the standard TOCTOU limitation applies (another process
+could theoretically bind to that port first). Use `port=0` for guaranteed
+atomic allocation.
+
+## Architecture
+
+For detailed architecture documentation, see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Type check
+uv run mypy src/detrix
+
+# Lint
+uv run ruff check src/detrix
+```
+
+## License
+
+MIT