portacode 0.3.4.dev0__py3-none-any.whl → 1.4.11.dev0__py3-none-any.whl

portacode/static/js/utils/ntp-clock.js

@@ -0,0 +1,232 @@
+/**
+ * NTP Clock - Synchronized time source for distributed tracing
+ *
+ * Provides synchronization by requesting the server clock across the WebSocket
+ * channel defined in `WEBSOCKET_PROTOCOL`. The client measures round-trip time
+ * and applies an offset that compensates for latency before exposing timestamps.
+ */
+class NTPClock {
+    constructor() {
+        this.ntpServer = 'portacode-gateway';
+        this.offset = null;
+        this.lastSync = null;
+        this.lastLatencyMs = null;
+        this.syncInterval = 60 * 1000;
+        this.clockSyncTimeout = 20 * 1000;
+        this.maxSyncFailures = 3;
+
+        this._clockSyncSender = null;
+        this._failureCallback = null;
+        this._clockSyncTimer = null;
+        this._clockSyncTimeoutHandle = null;
+        this._pendingRequest = null;
+        this._autoSyncStarted = false;
+        this._clockSyncFailures = 0;
+    }
+
+    /**
+     * Register the function responsible for piping `clock_sync_request`
+     * packets over the dashboard WebSocket.
+     */
+    setClockSyncSender(sender) {
+        this._clockSyncSender = sender;
+        if (this._autoSyncStarted && !this._pendingRequest) {
+            this._scheduleSync(0);
+        }
+    }
+
+    /**
+     * Callback invoked when multiple sync failures occur in a row.
+     * Useful for triggering a transport reconnect.
+     */
+    onClockSyncFailure(callback) {
+        this._failureCallback = callback;
+    }
+
+    /**
+     * Start the auto-sync loop (idempotent). Will skip sending until a sender
+     * has been registered.
+     */
+    startAutoSync() {
+        if (this._autoSyncStarted) {
+            return;
+        }
+        this._autoSyncStarted = true;
+        this._scheduleSync(0);
+    }
+
+    /**
+     * Stop the auto-sync loop (used primarily in tests).
+     */
+    stopAutoSync() {
+        this._autoSyncStarted = false;
+        if (this._clockSyncTimer) {
+            clearTimeout(this._clockSyncTimer);
+            this._clockSyncTimer = null;
+        }
+        this._clearPendingRequest();
+    }
+
+    sync() {
+        return this._performClockSync();
+    }
+
+    /**
+     * Get current NTP-synchronized timestamp in milliseconds since epoch
+     * Returns null if not synced
+     */
+    now() {
+        if (this.offset === null) {
+            return null;
+        }
+        return Date.now() + this.offset;
+    }
+
+    /**
+     * Get current NTP-synchronized timestamp in ISO format
+     * Returns null if not synced
+     */
+    nowISO() {
+        const ts = this.now();
+        if (ts === null) {
+            return null;
+        }
+        return new Date(ts).toISOString();
+    }
+
+    handleServerSync(payload) {
+        if (!payload) {
+            return;
+        }
+        const receiveTime = Date.now();
+        let roundTrip = 0;
+        if (
+            payload.request_id &&
+            this._pendingRequest &&
+            payload.request_id === this._pendingRequest.requestId
+        ) {
+            roundTrip = Math.max(receiveTime - this._pendingRequest.sentAt, 0);
+            this._clockSyncFailures = 0;
+            this._clearPendingRequest();
+        }
+        const serverSend = typeof payload.server_send_time === 'number' ? payload.server_send_time : payload.server_time;
+        const serverReceive = payload.server_receive_time;
+        const serverAvg = (typeof serverReceive === 'number' && typeof serverSend === 'number')
+            ? (serverReceive + serverSend) / 2
+            : typeof serverSend === 'number'
+                ? serverSend
+                : undefined;
+        if (typeof serverAvg === 'number') {
+            this.updateFromServer(serverAvg, roundTrip);
+        }
+        if (payload.server_time_iso) {
+            this.serverTimeIso = payload.server_time_iso;
+        }
+        this._scheduleSync(this.syncInterval);
+    }
+
+    applyServerSync(payload) {
+        this.handleServerSync(payload);
+    }
+
+    updateFromServer(serverTimeMs, roundTripMs = 0) {
+        const receiveTime = Date.now();
+        const halfLatency = (roundTripMs || 0) / 2;
+        const estimatedServerReceived = receiveTime - halfLatency;
+        this.offset = serverTimeMs - estimatedServerReceived;
+        this.lastLatencyMs = roundTripMs;
+        this.lastSync = receiveTime;
+    }
+
+    getStatus() {
+        return {
+            server: this.ntpServer,
+            offset: this.offset,
+            lastSync: this.lastSync ? new Date(this.lastSync).toISOString() : null,
+            lastLatencyMs: this.lastLatencyMs,
+            timeSinceSync: this.lastSync ? Date.now() - this.lastSync : null,
+            isSynced: this.offset !== null
+        };
+    }
+
+    _scheduleSync(delay) {
+        if (!this._autoSyncStarted) {
+            return;
+        }
+        if (this._clockSyncTimer) {
+            clearTimeout(this._clockSyncTimer);
+        }
+        this._clockSyncTimer = setTimeout(() => this._performClockSync(), delay);
+    }
+
+    _performClockSync() {
+        if (!this._autoSyncStarted) {
+            return false;
+        }
+        if (!this._clockSyncSender) {
+            this._scheduleSync(Math.min(this.syncInterval, 3000));
+            return false;
+        }
+        if (this._pendingRequest) {
+            return false;
+        }
+        const requestId = this._generateRequestId();
+        const payload = {
+            event: 'clock_sync_request',
+            request_id: requestId,
+        };
+        this._pendingRequest = {
+            requestId,
+            sentAt: Date.now(),
+        };
+        const sent = this._clockSyncSender(payload);
+        if (!sent) {
+            this._handleClockSyncFailure();
+            return false;
+        }
+        this._clockSyncTimeoutHandle = setTimeout(() => this._handleClockSyncTimeout(), this.clockSyncTimeout);
+        return true;
+    }
+
+    _handleClockSyncTimeout() {
+        this._clockSyncFailures += 1;
+        this._clearPendingRequest();
+        if (
+            this._clockSyncFailures >= this.maxSyncFailures &&
+            typeof this._failureCallback === 'function'
+        ) {
+            this._failureCallback();
+        }
+        this._scheduleSync(this.syncInterval);
+    }
+
+    _handleClockSyncFailure() {
+        this._clockSyncFailures += 1;
+        this._clearPendingRequest();
+        if (
+            this._clockSyncFailures >= this.maxSyncFailures &&
+            typeof this._failureCallback === 'function'
+        ) {
+            this._failureCallback();
+        }
+        this._scheduleSync(this.syncInterval);
+    }
+
+    _clearPendingRequest() {
+        if (this._clockSyncTimeoutHandle) {
+            clearTimeout(this._clockSyncTimeoutHandle);
+            this._clockSyncTimeoutHandle = null;
+        }
+        this._pendingRequest = null;
+    }
+
+    _generateRequestId() {
+        return `clock_sync:${Date.now()}:${Math.floor(Math.random() * 1000000)}`;
+    }
+}
+
+// Global instance - auto-starts sync
+const ntpClock = new NTPClock();
+ntpClock.startAutoSync();
+
+export default ntpClock;

portacode/utils/NTP_ARCHITECTURE.md

@@ -0,0 +1,136 @@
+# NTP Clock Architecture
+
+## Overview
+
+All entities (client, server, device) synchronize to **time.cloudflare.com** for distributed tracing.
+
+## Architecture: Single Package for Everything
+
+All NTP clock implementations (Python and JavaScript) are in the **portacode package** to ensure DRY principles.
+
+## Python Implementation
+
+**Location:** `portacode/utils/ntp_clock.py` (in portacode package)
+
+### Import Path
+```python
+from portacode.utils.ntp_clock import ntp_clock
+```
+
+### Usage Locations
+1. **Django Server Consumers** (`server/portacode_django/dashboard/consumers.py`)
+2. **Device Base Handlers** (`portacode/connection/handlers/base.py`)
+3. **Device Client** (`server/portacode_django/data/services/device_client.py`)
+4. **Any Python code with portacode installed**
+
+### Dependencies
+- `setup.py`: Added `ntplib>=0.4.0` to `install_requires`
+- `server/portacode_django/requirements.txt`: Added `portacode>=1.3.26`
+
+### API
+```python
+# Get NTP-synchronized timestamp (None if not synced)
+ntp_clock.now_ms()      # milliseconds
+ntp_clock.now()         # seconds
+ntp_clock.now_iso()     # ISO format
+
+# Check sync status
+status = ntp_clock.get_status()
+# {
+#   'server': 'time.cloudflare.com',
+#   'offset_ms': 6.04,
+#   'last_sync': '2025-10-05T04:37:12.768445+00:00',
+#   'is_synced': True
+# }
+```
+
+## JavaScript Implementation
+
+**Location:** `portacode/static/js/utils/ntp-clock.js` (in portacode package)
+
+### Django Setup
+
+Django will serve static files from the portacode package automatically after `collectstatic`:
+
+```python
+# Django settings.py - no changes needed, just ensure:
+INSTALLED_APPS = [
+    # ... other apps
+    'portacode',  # Add portacode as an installed app (optional, for admin integration)
+]
+
+# Static files will be collected from portacode package
+STATIC_URL = '/static/'
+```
+
+After installing portacode (`pip install portacode` or `pip install -e .`), run:
+```bash
+python manage.py collectstatic
+```
+
+This will copy `portacode/static/js/utils/ntp-clock.js` to Django's static files directory.
+
+### Import Path (in Django templates/JS)
+```javascript
+import ntpClock from '/static/js/utils/ntp-clock.js';
+// or relative to your JS file:
+import ntpClock from './utils/ntp-clock.js';
+```
+
+### Usage Locations
+1. **Dashboard WebSocket** (`websocket-service.js`)
+2. **Project WebSocket** (`websocket-service-project.js`)
+
+### API
+```javascript
+// Get NTP-synchronized timestamp (null if not synced)
+ntpClock.now()          // milliseconds
+ntpClock.nowISO()       // ISO format
+
+// Check sync status
+const status = ntpClock.getStatus();
+// {
+//   server: 'time.cloudflare.com',
+//   offset: 6.04,
+//   lastSync: '2025-10-05T04:37:12.768445+00:00',
+//   isSynced: true
+// }
+```
+
+## Design Principles
+
+1. **DRY (Don't Repeat Yourself)**
+   - **Python:** Single implementation in portacode package (`portacode/utils/ntp_clock.py`)
+   - **JavaScript:** Single implementation in portacode package (`portacode/static/js/utils/ntp-clock.js`)
+   - Both served from the same package, no duplication across repos
+
+2. **No Fallback Servers**
+   - All entities MUST sync to time.cloudflare.com
+   - If sync fails, timestamps are None/null
+   - Ensures all timestamps are comparable
+
+3. **Auto-Sync**
+   - Re-syncs every 5 minutes automatically
+   - Initial sync on import/load
+   - Max 3 retry attempts before marking as failed
+
+4. **Thread-Safe (Python)**
+   - Uses threading.Lock for concurrent access
+   - Background daemon thread for periodic sync
+
+## Testing
+
+### Python
+```bash
+python tools/test_python_ntp_clock.py
+```
+
+### JavaScript
+The test file is included in the package at `portacode/static/js/test-ntp-clock.html`.
+
+After Django collectstatic, open: `/static/js/test-ntp-clock.html` in browser
+
+Or run directly from package:
+```bash
+python -c "import portacode, os; print(os.path.join(os.path.dirname(portacode.__file__), 'static/js/test-ntp-clock.html'))"
+```

portacode/utils/__init__.py

@@ -0,0 +1 @@
+"""Portacode utility modules."""