@dronedeploy/rocos-js-sdk 4.1.1 → 4.3.0-rc.1

package/esm/services/robot-status/connectivity.d.ts

@@ -0,0 +1,76 @@
+import { IConnectedCallsign, RobotConnectivity, RobotConnectivityStatus, ServiceConnection } from '../../models';
+import { Observable } from 'rxjs';
+/**
+ * Service id → public path prefix, for services that expose the standard
+ * `connections` endpoint. New services adopting the convention are added here.
+ * The `telemetry` (Teletubby) endpoint joins this once built — see EAI-718/719.
+ */
+export declare const CONNECTION_SERVICE_PREFIXES: Record<string, string>;
+/**
+ * The telemetry-liveness signal is derived from heartbeat freshness rather than
+ * an HTTP endpoint, so it is handled specially (its observable is supplied by
+ * the caller). See `getTelemetryLiveness`.
+ */
+export declare const TELEMETRY_LIVENESS_SERVICE = "telemetry-liveness";
+/**
+ * The services evaluated by default. The `telemetry` connections endpoint joins
+ * this list once Teletubby exposes it (follow-up).
+ */
+export declare const DEFAULT_EXPECTED_SERVICES: string[];
+/**
+ * Floor for the connections-endpoint poll interval. Guards against a caller
+ * passing `0` (or any tiny value), which would otherwise poll the API on every
+ * event-loop tick.
+ */
+export declare const MIN_CONNECTIVITY_POLL_MS = 250;
+/** Clamps a requested poll interval up to {@link MIN_CONNECTIVITY_POLL_MS}. */
+export declare const clampPollInterval: (pollMs: number) => number;
+/** Authenticated GET used to poll a service's `connections` endpoint. */
+export type ConnectionsHttpGet = (url: string) => Promise<IConnectedCallsign>;
+/**
+ * Builds the `connections` endpoint URL for a service — per-callsign when a
+ * callsign is given, otherwise the bulk per-project variant.
+ */
+export declare const buildConnectionsUrl: (serviceId: string, baseUrl: string, projectId: string, callsign?: string, insecure?: boolean) => string;
+/** Maps a `connections` endpoint response onto a {@link ServiceConnection}. */
+export declare const mapConnectionStatus: (connection?: IConnectedCallsign | null) => ServiceConnection;
+/**
+ * Aggregates per-service connection states into an overall verdict:
+ * - `ONLINE`   — at least one service connected and none disconnected.
+ * - `DEGRADED` — a genuine mix: some connected, some disconnected.
+ * - `OFFLINE`  — nothing connected.
+ *
+ * `UNKNOWN` services (e.g. not yet polled) never force `DEGRADED`, so startup
+ * settles on `OFFLINE` (gray) rather than a spurious flashing-red degraded state.
+ *
+ * Note: this optimism also means a service held `UNKNOWN` indefinitely (e.g. an
+ * endpoint whose polls keep failing) does not by itself pull the aggregate below
+ * `ONLINE` — a deliberate v1 tradeoff to keep transient errors from flapping the
+ * indicator. Surfacing a long-lived failure distinctly (likely via health rather
+ * than connectivity) is left as a future refinement.
+ */
+export declare const aggregateConnectivity: (services: Record<string, ServiceConnection>) => RobotConnectivity;
+/**
+ * Polls a single service's `connections` endpoint on an interval, emitting its
+ * {@link ServiceConnection} (change-only). A failed/timed-out poll yields
+ * `UNKNOWN` (held transitional) rather than `DISCONNECTED`, to avoid a spurious
+ * degraded flash on a transient error.
+ *
+ * `pollMs` is floored at {@link MIN_CONNECTIVITY_POLL_MS} so the endpoint can't
+ * be polled unreasonably fast.
+ */
+export declare const getServiceConnectionChanges: (httpGet: ConnectionsHttpGet, url: string, pollMs?: number) => Observable<ServiceConnection>;
+export interface ConnectivityDeps {
+    httpGet: ConnectionsHttpGet;
+    baseUrl: string;
+    insecure?: boolean;
+    /** The telemetry-liveness signal (from `getTelemetryLiveness`), folded in as one service. */
+    telemetryLiveness$: Observable<ServiceConnection>;
+}
+/**
+ * Emits the robot's {@link RobotConnectivityStatus} — the per-service breakdown
+ * plus the aggregate verdict — for the configured `expectedServices`. HTTP
+ * services are polled; `telemetry-liveness` uses the supplied observable; any
+ * unrecognised service id resolves to `UNKNOWN`.
+ */
+export declare const getConnectivityChanges: (deps: ConnectivityDeps, projectId: string, callsign: string, expectedServices?: string[], pollMs?: number) => Observable<RobotConnectivityStatus>;

package/esm/services/robot-status/connectivity.js

@@ -0,0 +1,131 @@
+import { API_SERVICE_CONNECTIONS_URL, API_SERVICE_CONNECTION_URL } from '../../constants/api';
+import { ConnectionStatus, RobotConnectivity, ServiceConnection, } from '../../models';
+import { catchError, combineLatest, distinctUntilChanged, from, map, of, startWith, switchMap, timer, } from 'rxjs';
+import { formatServiceUrl } from '../../helpers/formatServiceUrl';
+/**
+ * Service id → public path prefix, for services that expose the standard
+ * `connections` endpoint. New services adopting the convention are added here.
+ * The `telemetry` (Teletubby) endpoint joins this once built — see EAI-718/719.
+ */
+export const CONNECTION_SERVICE_PREFIXES = {
+    'robot-configs': 'robot-configs',
+    'robot-services': 'robot-services',
+};
+/**
+ * The telemetry-liveness signal is derived from heartbeat freshness rather than
+ * an HTTP endpoint, so it is handled specially (its observable is supplied by
+ * the caller). See `getTelemetryLiveness`.
+ */
+export const TELEMETRY_LIVENESS_SERVICE = 'telemetry-liveness';
+/**
+ * The services evaluated by default. The `telemetry` connections endpoint joins
+ * this list once Teletubby exposes it (follow-up).
+ */
+export const DEFAULT_EXPECTED_SERVICES = [TELEMETRY_LIVENESS_SERVICE, 'robot-configs', 'robot-services'];
+const DEFAULT_CONNECTIVITY_POLL_MS = 5000;
+/**
+ * Floor for the connections-endpoint poll interval. Guards against a caller
+ * passing `0` (or any tiny value), which would otherwise poll the API on every
+ * event-loop tick.
+ */
+export const MIN_CONNECTIVITY_POLL_MS = 250;
+/** Clamps a requested poll interval up to {@link MIN_CONNECTIVITY_POLL_MS}. */
+export const clampPollInterval = (pollMs) => Math.max(pollMs, MIN_CONNECTIVITY_POLL_MS);
+/**
+ * Builds the `connections` endpoint URL for a service — per-callsign when a
+ * callsign is given, otherwise the bulk per-project variant.
+ */
+export const buildConnectionsUrl = (serviceId, baseUrl, projectId, callsign, insecure) => {
+    const template = callsign ? API_SERVICE_CONNECTION_URL : API_SERVICE_CONNECTIONS_URL;
+    const params = { url: baseUrl, service: CONNECTION_SERVICE_PREFIXES[serviceId], projectId };
+    if (callsign)
+        params.callsign = callsign;
+    return formatServiceUrl(template, params, insecure);
+};
+/** Maps a `connections` endpoint response onto a {@link ServiceConnection}. */
+export const mapConnectionStatus = (connection) => {
+    if (connection?.status === ConnectionStatus.CONNECTED)
+        return ServiceConnection.CONNECTED;
+    if (connection?.status === ConnectionStatus.DISCONNECTED)
+        return ServiceConnection.DISCONNECTED;
+    return ServiceConnection.UNKNOWN;
+};
+/**
+ * Aggregates per-service connection states into an overall verdict:
+ * - `ONLINE`   — at least one service connected and none disconnected.
+ * - `DEGRADED` — a genuine mix: some connected, some disconnected.
+ * - `OFFLINE`  — nothing connected.
+ *
+ * `UNKNOWN` services (e.g. not yet polled) never force `DEGRADED`, so startup
+ * settles on `OFFLINE` (gray) rather than a spurious flashing-red degraded state.
+ *
+ * Note: this optimism also means a service held `UNKNOWN` indefinitely (e.g. an
+ * endpoint whose polls keep failing) does not by itself pull the aggregate below
+ * `ONLINE` — a deliberate v1 tradeoff to keep transient errors from flapping the
+ * indicator. Surfacing a long-lived failure distinctly (likely via health rather
+ * than connectivity) is left as a future refinement.
+ */
+export const aggregateConnectivity = (services) => {
+    const values = Object.values(services);
+    const hasConnected = values.includes(ServiceConnection.CONNECTED);
+    const hasDisconnected = values.includes(ServiceConnection.DISCONNECTED);
+    if (hasConnected && hasDisconnected)
+        return RobotConnectivity.DEGRADED;
+    if (hasConnected)
+        return RobotConnectivity.ONLINE;
+    return RobotConnectivity.OFFLINE;
+};
+/**
+ * Polls a single service's `connections` endpoint on an interval, emitting its
+ * {@link ServiceConnection} (change-only). A failed/timed-out poll yields
+ * `UNKNOWN` (held transitional) rather than `DISCONNECTED`, to avoid a spurious
+ * degraded flash on a transient error.
+ *
+ * `pollMs` is floored at {@link MIN_CONNECTIVITY_POLL_MS} so the endpoint can't
+ * be polled unreasonably fast.
+ */
+export const getServiceConnectionChanges = (httpGet, url, pollMs = DEFAULT_CONNECTIVITY_POLL_MS) => {
+    return timer(0, clampPollInterval(pollMs)).pipe(switchMap(() => {
+        return from(httpGet(url)).pipe(map(mapConnectionStatus), catchError(() => of(ServiceConnection.UNKNOWN)));
+    }), startWith(ServiceConnection.UNKNOWN), distinctUntilChanged());
+};
+const connectivityEquals = (a, b) => {
+    if (a.overall !== b.overall)
+        return false;
+    const keys = Object.keys(a.services);
+    if (keys.length !== Object.keys(b.services).length)
+        return false;
+    return keys.every((key) => a.services[key] === b.services[key]);
+};
+/**
+ * Emits the robot's {@link RobotConnectivityStatus} — the per-service breakdown
+ * plus the aggregate verdict — for the configured `expectedServices`. HTTP
+ * services are polled; `telemetry-liveness` uses the supplied observable; any
+ * unrecognised service id resolves to `UNKNOWN`.
+ */
+export const getConnectivityChanges = (deps, projectId, callsign, expectedServices = DEFAULT_EXPECTED_SERVICES, pollMs = DEFAULT_CONNECTIVITY_POLL_MS) => {
+    // combineLatest([]) completes without emitting; emit an explicit empty/offline status instead.
+    if (expectedServices.length === 0) {
+        return of({ overall: RobotConnectivity.OFFLINE, services: {} });
+    }
+    const perService = expectedServices.map((serviceId) => {
+        let source$;
+        if (serviceId === TELEMETRY_LIVENESS_SERVICE) {
+            source$ = deps.telemetryLiveness$;
+        }
+        else if (serviceId in CONNECTION_SERVICE_PREFIXES) {
+            const url = buildConnectionsUrl(serviceId, deps.baseUrl, projectId, callsign, deps.insecure);
+            source$ = getServiceConnectionChanges(deps.httpGet, url, pollMs);
+        }
+        else {
+            source$ = of(ServiceConnection.UNKNOWN);
+        }
+        return source$.pipe(startWith(ServiceConnection.UNKNOWN), map((connection) => ({ serviceId, connection })));
+    });
+    return combineLatest(perService).pipe(map((entries) => {
+        const services = {};
+        for (const { serviceId, connection } of entries)
+            services[serviceId] = connection;
+        return { overall: aggregateConnectivity(services), services };
+    }), distinctUntilChanged(connectivityEquals));
+};

package/esm/services/robot-status/reportedStatus.d.ts

@@ -0,0 +1,38 @@
+import { Observable } from 'rxjs';
+import { RobotHealth, RobotReadiness, ServiceConnection } from '../../models';
+import { TelemetryService } from '../TelemetryService';
+/** The new agent topic carrying health + readiness (replaces the heartbeat). */
+export declare const ROBOT_STATUS_SOURCE = "/diagnostics/robot/status";
+/** The legacy heartbeat topic — liveness only, no status payload. */
+export declare const LEGACY_HEARTBEAT_SOURCE = "/rocos/agent/telemetry/heartbeat";
+export interface ReportedRobotStatus {
+    health: RobotHealth;
+    readiness: RobotReadiness;
+}
+/**
+ * Maps a `robot/status` wire value (integer, or its string equivalent) to a
+ * {@link RobotHealth}. Anything unrecognised — including `0` / `'unknown'` —
+ * resolves to {@link RobotHealth.UNKNOWN}.
+ */
+export declare const parseRobotHealth: (value: unknown) => RobotHealth;
+/** As {@link parseRobotHealth}, for {@link RobotReadiness}. */
+export declare const parseRobotReadiness: (value: unknown) => RobotReadiness;
+/**
+ * Emits the robot's reported health/readiness, subscribing to the new
+ * `robot/status` topic and the legacy heartbeat concurrently.
+ *
+ * The new topic takes precedence: once any `robot/status` message has been seen,
+ * legacy heartbeats no longer affect the reported value. While only the legacy
+ * heartbeat is present, a live heartbeat is reported as `NORMAL`/`IDLE` — which
+ * preserves today's "online ⇒ green" behaviour for agents not yet emitting the
+ * new topic.
+ */
+export declare const getReportedStatusChanges: (telemetry: TelemetryService, projectId: string, callsign: string) => Observable<ReportedRobotStatus>;
+/**
+ * Emits the `telemetry-liveness` connectivity signal: whether a heartbeat (from
+ * either the new `robot/status` topic or the legacy heartbeat) has been received
+ * within `heartbeatTimeoutMs`. Mirrors {@link TelemetryService.monitorTelemetryWithTimeout}
+ * but spans both topics and maps onto {@link ServiceConnection} so it can be
+ * folded into connectivity aggregation as just another service entry.
+ */
+export declare const getTelemetryLiveness: (telemetry: TelemetryService, projectId: string, callsign: string, heartbeatTimeoutMs?: number, intervalMs?: number) => Observable<ServiceConnection>;

package/esm/services/robot-status/reportedStatus.js

@@ -0,0 +1,102 @@
+import { catchError, combineLatest, distinctUntilChanged, filter, interval, map, merge, of, scan, startWith, } from 'rxjs';
+import { RobotHealth, RobotReadiness, ServiceConnection } from '../../models';
+/** The new agent topic carrying health + readiness (replaces the heartbeat). */
+export const ROBOT_STATUS_SOURCE = '/diagnostics/robot/status';
+/** The legacy heartbeat topic — liveness only, no status payload. */
+export const LEGACY_HEARTBEAT_SOURCE = '/rocos/agent/telemetry/heartbeat';
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 5000;
+const DEFAULT_INTERVAL_MS = 2000;
+/**
+ * Maps a `robot/status` wire value (integer, or its string equivalent) to a
+ * {@link RobotHealth}. Anything unrecognised — including `0` / `'unknown'` —
+ * resolves to {@link RobotHealth.UNKNOWN}.
+ */
+export const parseRobotHealth = (value) => {
+    switch (value) {
+        case 1:
+        case '1':
+        case 'normal':
+            return RobotHealth.NORMAL;
+        case 2:
+        case '2':
+        case 'abnormal':
+            return RobotHealth.ABNORMAL;
+        case 3:
+        case '3':
+        case 'critical':
+            return RobotHealth.CRITICAL;
+        default:
+            return RobotHealth.UNKNOWN;
+    }
+};
+/** As {@link parseRobotHealth}, for {@link RobotReadiness}. */
+export const parseRobotReadiness = (value) => {
+    switch (value) {
+        case 1:
+        case '1':
+        case 'idle':
+            return RobotReadiness.IDLE;
+        case 2:
+        case '2':
+        case 'busy':
+            return RobotReadiness.BUSY;
+        default:
+            return RobotReadiness.UNKNOWN;
+    }
+};
+/**
+ * Emits the robot's reported health/readiness, subscribing to the new
+ * `robot/status` topic and the legacy heartbeat concurrently.
+ *
+ * The new topic takes precedence: once any `robot/status` message has been seen,
+ * legacy heartbeats no longer affect the reported value. While only the legacy
+ * heartbeat is present, a live heartbeat is reported as `NORMAL`/`IDLE` — which
+ * preserves today's "online ⇒ green" behaviour for agents not yet emitting the
+ * new topic.
+ */
+export const getReportedStatusChanges = (telemetry, projectId, callsign) => {
+    const new$ = telemetry
+        .subscribe({ projectId, callsigns: [callsign], sources: [ROBOT_STATUS_SOURCE] })
+        .pipe(map((message) => ({
+        from: 'new',
+        status: {
+            health: parseRobotHealth(message.payload?.health),
+            readiness: parseRobotReadiness(message.payload?.readiness),
+        },
+    })));
+    const legacy$ = telemetry.subscribe({ projectId, callsigns: [callsign], sources: [LEGACY_HEARTBEAT_SOURCE] }).pipe(map(() => ({
+        from: 'legacy',
+        status: { health: RobotHealth.NORMAL, readiness: RobotReadiness.IDLE },
+    })));
+    return merge(new$, legacy$).pipe(scan((acc, event) => {
+        if (event.from === 'new')
+            return { seenNew: true, status: event.status };
+        // Legacy heartbeat: only honoured until the new topic has been seen.
+        return acc.seenNew ? acc : { seenNew: false, status: event.status };
+    }, { seenNew: false, status: undefined }), map((acc) => acc.status), filter((status) => status !== undefined), distinctUntilChanged((a, b) => a.health === b.health && a.readiness === b.readiness), 
+    // A telemetry error would otherwise terminate this stream permanently; fall back to
+    // UNKNOWN/UNKNOWN (matching getTelemetryLiveness) so subscribers get an honest value.
+    catchError(() => of({ health: RobotHealth.UNKNOWN, readiness: RobotReadiness.UNKNOWN })));
+};
+/**
+ * Emits the `telemetry-liveness` connectivity signal: whether a heartbeat (from
+ * either the new `robot/status` topic or the legacy heartbeat) has been received
+ * within `heartbeatTimeoutMs`. Mirrors {@link TelemetryService.monitorTelemetryWithTimeout}
+ * but spans both topics and maps onto {@link ServiceConnection} so it can be
+ * folded into connectivity aggregation as just another service entry.
+ */
+export const getTelemetryLiveness = (telemetry, projectId, callsign, heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS, intervalMs = DEFAULT_INTERVAL_MS) => {
+    const startedAt = Date.now();
+    const lastMessageAt$ = telemetry
+        .subscribe({ projectId, callsigns: [callsign], sources: [ROBOT_STATUS_SOURCE, LEGACY_HEARTBEAT_SOURCE] })
+        .pipe(map(() => Date.now()));
+    return combineLatest([lastMessageAt$.pipe(startWith(startedAt)), interval(intervalMs)]).pipe(map(([lastMessageAt]) => {
+        const now = Date.now();
+        // No message yet, but still within the initial grace period.
+        if (lastMessageAt === startedAt && now - startedAt <= heartbeatTimeoutMs)
+            return ServiceConnection.UNKNOWN;
+        if (now - lastMessageAt > heartbeatTimeoutMs)
+            return ServiceConnection.DISCONNECTED;
+        return ServiceConnection.CONNECTED;
+    }), startWith(ServiceConnection.UNKNOWN), distinctUntilChanged(), catchError(() => of(ServiceConnection.UNKNOWN)));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dronedeploy/rocos-js-sdk",
-  "version": "4.1.1",
+  "version": "4.3.0-rc.1",
   "description": "Javascript SDK for rocos",
   "main": "cjs/index.js",
   "module": "esm/index.js",