yakmesh 2.8.2 → 3.0.0

package/oracle/time-api.js

@@ -0,0 +1,239 @@
+/**
+ * ╔═══════════════════════════════════════════════════════════════════════════════╗
+ * ║                 ⏱️  YAKMESH TIME API — ATOMIC CLOCK SERVICE  ⏱️             ║
+ * ╠═══════════════════════════════════════════════════════════════════════════════╣
+ * ║                                                                               ║
+ * ║  HTTP endpoint that serves GPS-derived atomic time from the MA-902/S-C1      ║
+ * ║  GPS Gigabit Time Server via the existing SNMP monitor module.               ║
+ * ║                                                                               ║
+ * ║  Runs on port 3099 (configurable via YAKMESH_TIME_API_PORT).                 ║
+ * ║  Reverse-proxied by Caddy at time.yakmesh.dev.                               ║
+ * ║                                                                               ║
+ * ║  Endpoints:                                                                   ║
+ * ║    GET  /api/time         — Full time + satellite telemetry (JSON)            ║
+ * ║    GET  /api/time/simple  — Minimal { t, s, q } response                     ║
+ * ║    GET  /api/health       — Satellite health + alarm status                   ║
+ * ║    HEAD /api/time         — Headers only, zero body                           ║
+ * ║                                                                               ║
+ * ╚═══════════════════════════════════════════════════════════════════════════════╝
+ *
+ * @module oracle/time-api
+ */
+
+import http from 'node:http';
+import { getMA902Monitor } from './ma902-snmp.js';
+import { createLogger } from '../utils/logger.js';
+
+const log = createLogger('time-api');
+
+const PORT = parseInt(process.env.YAKMESH_TIME_API_PORT || '3099', 10);
+const HOST = process.env.YAKMESH_TIME_API_HOST || '0.0.0.0';
+
+// ============================================================
+// MA-902 MONITOR — cached telemetry from SNMP polling
+// ============================================================
+
+let lastTelemetry = null;
+let monitor = null;
+
+/**
+ * Initialize the MA-902 monitor and begin SNMP polling.
+ * Telemetry updates are cached in `lastTelemetry` for low-latency HTTP responses.
+ */
+function initMonitor() {
+  monitor = getMA902Monitor({
+    host: process.env.MA902_HOST || '192.168.1.30',
+    community: process.env.MA902_COMMUNITY || 'public',
+    pollInterval: parseInt(process.env.MA902_POLL_INTERVAL || '5000', 10),
+    verbose: process.env.MA902_VERBOSE === 'true',
+  });
+
+  monitor.on('telemetry', (data) => {
+    lastTelemetry = data;
+  });
+
+  monitor.on('error', (err) => {
+    log.warn('MA-902 monitor error', { error: err.message });
+  });
+
+  return monitor;
+}
+
+// ============================================================
+// QUALITY ASSESSMENT
+// ============================================================
+
+/**
+ * Derive a human-readable quality string from telemetry.
+ * Matches the thresholds in ma902-snmp.js: excellent(≥8), good(≥5), marginal(≥3), degraded(≥1).
+ */
+function getQuality() {
+  if (!lastTelemetry) return 'unknown';
+  if (!lastTelemetry.locked) return 'degraded';
+  const sats = lastTelemetry.satellites?.used || 0;
+  if (sats >= 8) return 'excellent';
+  if (sats >= 5) return 'good';
+  if (sats >= 3) return 'marginal';
+  return 'degraded';
+}
+
+// ============================================================
+// HTTP SERVER
+// ============================================================
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url, `http://${HOST}:${PORT}`);
+  const pathname = url.pathname;
+
+  // CORS — time is a public good
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, HEAD, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+  res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+
+  // CORS preflight
+  if (req.method === 'OPTIONS') {
+    res.setHeader('Access-Control-Max-Age', '86400');
+    res.writeHead(204);
+    return res.end();
+  }
+
+  // Timing headers on every response
+  const now = Date.now();
+  const unixS = now / 1000;
+  const locked = lastTelemetry?.locked ?? false;
+
+  res.setHeader('X-Yakmesh-Time', unixS.toFixed(3));
+  res.setHeader('X-Yakmesh-Stratum', locked ? '1' : '2');
+  res.setHeader('X-Yakmesh-Source', locked ? 'GPS' : 'system');
+
+  // ---- HEAD /api/time — zero body ----
+  if (pathname === '/api/time' && req.method === 'HEAD') {
+    res.writeHead(200);
+    return res.end();
+  }
+
+  // ---- GET /api/time/simple — minimal response ----
+  if (pathname === '/api/time/simple' && req.method === 'GET') {
+    const body = JSON.stringify({
+      t: now,
+      s: locked ? 1 : 2,
+      q: getQuality(),
+    });
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    return res.end(body);
+  }
+
+  // ---- GET /api/time — full atomic time with telemetry ----
+  if (pathname === '/api/time' && req.method === 'GET') {
+    const sats = lastTelemetry?.satellites || {};
+    const body = JSON.stringify({
+      iso: new Date(now).toISOString(),
+      unix: unixS,
+      unix_ms: now,
+      stratum: locked ? 1 : 2,
+      source: 'MA-902/S-C1 GPS',
+      accuracy_ms: locked ? 1 : 50,
+      leap_indicator: 0,
+      satellites: {
+        visible: sats.visible ?? 0,
+        used: sats.used ?? 0,
+        tracking: sats.tracking ?? 0,
+        constellations: sats.constellations ?? [],
+      },
+      lock: locked,
+      quality: getQuality(),
+      offset_ns: lastTelemetry?.offset ?? 0,
+      reference_id: locked ? 'GPS' : 'SYS',
+    });
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    return res.end(body);
+  }
+
+  // ---- GET /api/health — satellite health & SNMP telemetry ----
+  if (pathname === '/api/health' && req.method === 'GET') {
+    const body = JSON.stringify({
+      status: locked ? 'healthy' : 'degraded',
+      lock: locked,
+      satellites_visible: lastTelemetry?.satellites?.visible ?? 0,
+      satellites_used: lastTelemetry?.satellites?.used ?? 0,
+      constellations: lastTelemetry?.satellites?.constellations ?? [],
+      alarm: lastTelemetry?.alarm ?? false,
+      quality: lastTelemetry?.satellites?.quality ?? 'unknown',
+      last_poll: lastTelemetry?.timestamp
+        ? new Date(lastTelemetry.timestamp).toISOString()
+        : null,
+      drift_ns: lastTelemetry?.offset ?? 0,
+      trust_level: lastTelemetry?.maniTrust?.level ?? 'unknown',
+    });
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    return res.end(body);
+  }
+
+  // ---- GET / — redirect to info page on yakmesh.dev ----
+  if (pathname === '/' && req.method === 'GET') {
+    res.writeHead(302, { 'Location': 'https://yakmesh.dev/time/' });
+    return res.end();
+  }
+
+  // ---- 404 ----
+  res.writeHead(404, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ error: 'Not found', endpoints: ['/api/time', '/api/time/simple', '/api/health'] }));
+});
+
+// ============================================================
+// STARTUP
+// ============================================================
+
+/**
+ * Start the Time API server and MA-902 monitor.
+ * @returns {{ server: http.Server, monitor: MA902Monitor }}
+ */
+export async function startTimeApi() {
+  const mon = initMonitor();
+  const started = await mon.start();
+
+  if (!started) {
+    log.warn('MA-902 SNMP not available — Time API will return system time (Stratum 2)');
+  }
+
+  return new Promise((resolve, reject) => {
+    server.listen(PORT, HOST, () => {
+      log.info('Yakmesh Time API listening', { url: `http://${HOST}:${PORT}`, monitor: started ? 'MA-902 SNMP active' : 'system fallback' });
+      resolve({ server, monitor: mon });
+    });
+    server.on('error', (err) => {
+      log.error('Time API failed to start', { error: err.message });
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Stop the Time API server and monitor.
+ */
+export async function stopTimeApi() {
+  if (monitor) {
+    monitor.stop();
+    monitor = null;
+    lastTelemetry = null;
+  }
+  return new Promise((resolve) => {
+    server.close(() => {
+      log.info('Yakmesh Time API stopped');
+      resolve();
+    });
+  });
+}
+
+// ---- Direct execution support ----
+// node oracle/time-api.js
+const isMain = import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`;
+if (isMain) {
+  startTimeApi().catch((err) => {
+    console.error('Fatal:', err.message);
+    process.exit(1);
+  });
+}
+
+export default { startTimeApi, stopTimeApi };

package/oracle/time-source.js

@@ -43,6 +43,7 @@ import { existsSync, readFileSync } from 'fs';
 import { platform } from 'os';
 import { EventEmitter } from 'events';
 import { createLogger } from '../utils/logger.js';
+import { MA902Monitor, getMA902Monitor } from './ma902-snmp.js';
 
 const log = createLogger('mani:time-source');
 
@@ -174,6 +175,9 @@ export class ManiTimeDetector extends EventEmitter {
       refreshInterval: options.refreshInterval || 60000,
       // Verbose logging
       verbose: options.verbose || false,
+      // MA-902 SNMP monitoring configuration
+      ma902: options.ma902 || null,
+      // Example: { host: '192.168.1.30', pollInterval: 10000 }
     };
     
     this.platform = platform();
@@ -182,12 +186,54 @@ export class ManiTimeDetector extends EventEmitter {
     this.trustLevel = ManiTrustLevel.UNSYNC;
     this.lastCheck = null;
     this.refreshTimer = null;
+    
+    // MA-902 SNMP monitor instance
+    this.ma902Monitor = null;
   }
   
   /**
    * Start continuous monitoring of time sources
    */
-  start() {
+  async start() {
+    // Start MA-902 SNMP monitor if configured
+    if (this.options.ma902) {
+      try {
+        this.ma902Monitor = new MA902Monitor({
+          verbose: this.options.verbose,
+          ...this.options.ma902,
+        });
+        
+        // Forward MA-902 events
+        this.ma902Monitor.on('telemetry', (data) => {
+          this.emit('ma902:telemetry', data);
+        });
+        this.ma902Monitor.on('lockLost', (data) => {
+          log.warn('MA-902 satellite lock lost — GPS trust degraded');
+          this.emit('ma902:lockLost', data);
+          // Re-detect to update trust level
+          this.detect();
+        });
+        this.ma902Monitor.on('lockAcquired', (data) => {
+          log.info('MA-902 satellite lock acquired — GPS trust restored');
+          this.emit('ma902:lockAcquired', data);
+          this.detect();
+        });
+        this.ma902Monitor.on('alarm', (data) => {
+          this.emit('ma902:alarm', data);
+          this.detect();
+        });
+        this.ma902Monitor.on('trustChanged', (data) => {
+          this.emit('ma902:trustChanged', data);
+          this.detect();
+        });
+        
+        await this.ma902Monitor.start();
+      } catch (err) {
+        log.warn('MA-902 SNMP monitor failed to start', { error: err.message });
+        this.ma902Monitor = null;
+      }
+    }
+    
     this.detect();
     
     if (this.options.refreshInterval > 0) {
@@ -207,6 +253,10 @@ export class ManiTimeDetector extends EventEmitter {
       clearInterval(this.refreshTimer);
       this.refreshTimer = null;
     }
+    if (this.ma902Monitor) {
+      this.ma902Monitor.stop();
+      this.ma902Monitor = null;
+    }
   }
   
   /**
@@ -231,8 +281,31 @@ export class ManiTimeDetector extends EventEmitter {
         this.detectedSources.set('atomic', atomicResult);
       }
       
-      // Check for GPS/PPS
+      // Check for GPS/PPS (enriched with MA-902 SNMP telemetry)
       const gpsResult = this.detectGPS();
+      
+      // Enrich GPS result with MA-902 SNMP data if available
+      if (this.ma902Monitor && this.ma902Monitor.isAvailable()) {
+        const telemetry = this.ma902Monitor.getTelemetry();
+        if (telemetry) {
+          gpsResult.detected = true;
+          gpsResult.device = gpsResult.device || 'MA-902/S-C1';
+          gpsResult.synchronized = telemetry.synchronized;
+          gpsResult.satellites = telemetry.satellites.used;
+          gpsResult.ma902 = {
+            host: telemetry.host,
+            locked: telemetry.locked,
+            satellites: telemetry.satellites,
+            gpsTime: telemetry.gpsTimeISO,
+            clockDelta: telemetry.clockDeltaSeconds,
+            alarm: telemetry.alarm,
+            quality: telemetry.qualityIndicator,
+            trust: telemetry.maniTrust,
+            constellations: telemetry.satellites.constellations,
+          };
+        }
+      }
+      
       if (gpsResult.detected) {
         results.sources.gps = gpsResult;
         this.detectedSources.set('gps', gpsResult);
@@ -245,8 +318,14 @@ export class ManiTimeDetector extends EventEmitter {
         this.detectedSources.set('ptp', ptpResult);
       }
       
-      // Check NTP status
+      // Check NTP status — if MA-902 is the NTP source, note that
       const ntpResult = this.detectNTP();
+      if (ntpResult.server && this.ma902Monitor?.isAvailable()) {
+        const ma902Host = this.ma902Monitor.options.host;
+        if (ntpResult.server === ma902Host || ntpResult.server.includes(ma902Host)) {
+          ntpResult.ma902Backed = true;
+        }
+      }
       results.sources.ntp = ntpResult;
       this.detectedSources.set('ntp', ntpResult);
       
@@ -265,6 +344,11 @@ export class ManiTimeDetector extends EventEmitter {
         results.trustLevel = TimeTrustLevel.NTP;
       }
       
+      // MA-902 data enrichment for results
+      if (this.ma902Monitor) {
+        results.ma902 = this.ma902Monitor.getStatus();
+      }
+      
       results.phaseTolerance = PhaseTolerance[results.trustLevel];
       
     } catch (error) {
@@ -501,45 +585,7 @@ export class ManiTimeDetector extends EventEmitter {
     }
       // 4. Check for Meinberg PTP hardware (PTP270PEX, etc.)
       try {
-        const meinbergCheck = execSilent('lspci 2>/dev/null | grep -i meinberg', { encoding: 'utf8', timeout: 5000 });
-        if (meinbergCheck.trim()) {
-          result.detected = true;
-          result.device = 'Meinberg PTP';
-          result.type = meinbergCheck.includes('270') ? 'PTP270PEX' : 'Meinberg PTP Card';
-          try {
-            const mbgStatus = execSilent('mbgstatus 2>/dev/null | head -20', { encoding: 'utf8', timeout: 5000 });
-            if (mbgStatus.includes('SYNC') || mbgStatus.includes('synchronized')) {
-              result.synchronized = true;
-            }
-            const offsetMatch = mbgStatus.match(/offset[:\s]+(-?\d+)/i);
-            if (offsetMatch) {
-              result.offset = parseInt(offsetMatch[1]);
-            }
-          } catch (e) { /* mbgstatus not available */ }
-        }
-      } catch (e) { /* Meinberg not found */ }
-      // 4. Check for Meinberg PTP hardware (PTP270PEX, etc.)
-      try {
-        const meinbergCheck = execSilent('lspci 2>/dev/null | grep -i meinberg', { encoding: 'utf8', timeout: 5000 });
-        if (meinbergCheck.trim()) {
-          result.detected = true;
-          result.device = 'Meinberg PTP';
-          result.type = meinbergCheck.includes('270') ? 'PTP270PEX' : 'Meinberg PTP Card';
-          try {
-            const mbgStatus = execSilent('mbgstatus 2>/dev/null | head -20', { encoding: 'utf8', timeout: 5000 });
-            if (mbgStatus.includes('SYNC') || mbgStatus.includes('synchronized')) {
-              result.synchronized = true;
-            }
-            const offsetMatch = mbgStatus.match(/offset[:\s]+(-?\d+)/i);
-            if (offsetMatch) {
-              result.offset = parseInt(offsetMatch[1]);
-            }
-          } catch (e) { /* mbgstatus not available */ }
-        }
-      } catch (e) { /* Meinberg not found */ }
-      // 4. Check for Meinberg PTP hardware (PTP270PEX, etc.)
-      try {
-        // Check for Meinberg driver/software
+        // Check for Meinberg driver/software via lspci
         const meinbergCheck = execSilent('lspci 2>/dev/null | grep -i meinberg', { encoding: 'utf8', timeout: 5000 });
         if (meinbergCheck.trim()) {
           result.detected = true;
@@ -565,13 +611,27 @@ export class ManiTimeDetector extends EventEmitter {
         // Meinberg not found via lspci
       }
       
-      // 5. Windows: Check for Meinberg driver
+      // 5. Windows: Check for Meinberg driver + MbgAdjTm service
       if (this.platform === 'win32') {
         try {
           const driverCheck = execSilent('driverquery /v 2>nul | findstr /i meinberg', { encoding: 'utf8', timeout: 5000 });
           if (driverCheck.trim()) {
             result.detected = true;
-            result.type = 'Meinberg (Windows)';
+            result.type = 'Meinberg PTP270PEX (Windows)';
+            
+            // Check if MbgAdjTm service is running (disciplines system clock from PTP card)
+            const svcCheck = execSilent('sc query MbgAdjTm 2>nul', { encoding: 'utf8', timeout: 3000 });
+            if (svcCheck && /RUNNING/i.test(svcCheck)) {
+              result.serviceRunning = true;
+              
+              // Cross-reference with MA-902 SNMP: if MA-902 is GPS-locked and serving PTP,
+              // and MbgAdjTm is running, the PTP card is receiving disciplined time
+              if (this.ma902Monitor?.isAvailable() && this.ma902Monitor.isLocked()) {
+                result.synchronized = true;
+                result.source = 'ma902-ptp';
+                result.device = 'PTP270PEX ← MA-902/S-C1';
+              }
+            }
           }
         } catch (e) {
           // Meinberg driver not found
@@ -712,11 +772,21 @@ export class ManiTimeDetector extends EventEmitter {
     }
     
     if (results.sources.gps?.detected) {
-      log.info('GPS detected', {
+      const gpsLog = {
         device: results.sources.gps.device || 'detected',
         hasPPS: results.sources.gps.hasPPS,
         synchronized: results.sources.gps.synchronized,
-      });
+      };
+      // Enrich log with MA-902 SNMP data if available
+      if (results.sources.gps.ma902) {
+        const ma = results.sources.gps.ma902;
+        gpsLog.ma902 = true;
+        gpsLog.satellites = `${ma.satellites.used}/${ma.satellites.tracking}/${ma.satellites.visible}`;
+        gpsLog.constellations = ma.constellations.join('+');
+        gpsLog.locked = ma.locked;
+        gpsLog.trust = ma.trust.level;
+      }
+      log.info('GPS detected', gpsLog);
     }
     
     if (results.sources.ptp?.detected) {
@@ -776,7 +846,7 @@ export class ManiTimeDetector extends EventEmitter {
    * Get status object for API responses
    */
   getStatus() {
-    return {
+    const status = {
       trustLevel: this.trustLevel,
       phaseTolerance: this.getPhaseTolerance(),
       stratum: this.getStratum(),
@@ -789,6 +859,21 @@ export class ManiTimeDetector extends EventEmitter {
         tightPhaseWindow: this.trustLevel !== TimeTrustLevel.UNSYNC,
       },
     };
+    
+    // Include MA-902 SNMP status if monitor is active
+    if (this.ma902Monitor) {
+      status.ma902 = this.ma902Monitor.getStatus();
+    }
+    
+    return status;
+  }
+  
+  /**
+   * Get the MA-902 monitor instance (if configured)
+   * @returns {MA902Monitor|null}
+   */
+  getMA902Monitor() {
+    return this.ma902Monitor;
   }
 }
 
@@ -883,6 +968,9 @@ export {
 // Backward compatibility exports (original naming)
 export { ManiTimeDetector as TimeSourceDetector };
 
+// Re-export MA-902 monitor for direct access
+export { MA902Monitor, getMA902Monitor } from './ma902-snmp.js';
+
 export default {
   ManiTimeDetector,
   ManiTrustLevel,
@@ -891,6 +979,8 @@ export default {
   createPhaseConfig,
   getManiTimeDetector,
   detectTimeSources,
+  MA902Monitor,
+  getMA902Monitor,
   // Backward compatibility
   TimeSourceDetector: ManiTimeDetector,
   TimeTrustLevel: ManiTrustLevel,