@alwaysai/device-agent-schemas 3.3.0 → 3.3.1

package/src/schemas/system-information-schema.json

@@ -0,0 +1,149 @@
+{
+  "$id": "https://alwaysai.co/system-information-schema.json",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "title": "system-information",
+  "type": "object",
+  "properties": {
+    "os": {
+      "type": "object",
+      "properties": {
+        "platform": {
+          "type": "string"
+        },
+        "distro": {
+          "type": "string"
+        },
+        "release": {
+          "type": "string"
+        },
+        "kernel": {
+          "type": "string"
+        },
+        "architecture": {
+          "type": "string"
+        },
+        "hostname": {
+          "type": "string"
+        }
+      }
+    },
+    "cpu": {
+      "type": "object",
+      "properties": {
+        "manufacturer": {
+          "type": "string"
+        },
+        "brand": {
+          "type": "string"
+        },
+        "vendor": {
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        },
+        "cores": {
+          "type": "string"
+        },
+        "physicalCores": {
+          "type": "string"
+        },
+        "efficiencyCores": {
+          "type": "string"
+        },
+        "processors": {
+          "type": "string"
+        }
+      }
+    },
+    "disk": {
+      "type": "object",
+      "properties": {
+        "drives": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "device": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "vendor": {
+                "type": "string"
+              },
+              "size": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
+      "required": []
+    },
+    "device": {
+      "type": "object",
+      "properties": {
+        "manufacturer": {
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        },
+        "serial": {
+          "type": "string"
+        },
+        "virtual": {
+          "type": "boolean"
+        }
+      }
+    },
+    "network": {
+      "type": "object",
+      "properties": {
+        "ipv4Address": {
+          "type": "string"
+        },
+        "ipv6Address": {
+          "type": "string"
+        },
+        "macAddress": {
+          "type": "string"
+        }
+      }
+    },
+    "versions": {
+      "type": "object",
+      "properties": {
+        "agent": {
+          "type": "string"
+        },
+        "deviceAgentSchemas": {
+          "type": "string"
+        },
+        "npm": {
+          "type": "string"
+        },
+        "node": {
+          "type": "string"
+        },
+        "docker": {
+          "type": "string"
+        },
+        "dockerCompose": {
+          "type": "string"
+        }
+      }
+    },
+    "lastBootTime": {
+      "type": "string"
+    }
+  }
+}

package/src/schemas/to-client-message-schema.json

@@ -0,0 +1,92 @@
+{
+  "$id": "https://alwaysai.co/to-client-message-schema.json",
+  "title": "to_client_message",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "description": "The messaging payload structure for messages sent from device agent to clients",
+  "type": "object",
+  "properties": {
+    "timestamp": {
+      "type": "string"
+    },
+    "deviceId": {
+      "description": "Device UUID of device sending the message",
+      "type": "string"
+    },
+    "topic": {
+      "oneOf": [{ "$ref": "#/$defs/toClient" }]
+    },
+    "messageType": {
+      "type": "string",
+      "enum": [
+        "device_stats",
+        "app_state",
+        "status_response",
+        "app_logs"
+      ]
+    },
+    "txId": {
+      "$ref": "https://alwaysai.co/common-schema.json#/$defs/txId"
+    },
+    "payload": {
+      "type": "object"
+    }
+  },
+  "required": ["timestamp", "deviceId", "messageType", "txId", "payload"],
+  "allOf":[
+  {
+    "if": {
+      "properties": {
+        "messageType": { "const": "device_stats" }
+      }
+    },
+    "then": {
+      "properties": {
+        "payload": {"$ref": "https://alwaysai.co/device-stats-schema.json"}
+      }
+    }
+  },
+  {
+    "if": {
+      "properties": {
+        "messageType": { "const": "app_state" }
+      }
+    },
+    "then": {
+      "properties": {
+        "payload": {"$ref": "https://alwaysai.co/app-state-schema.json"}
+      }
+    }
+  },
+  {
+    "if": {
+      "properties": {
+        "messageType": { "const": "status_response" }
+      }
+    },
+    "then": {
+      "properties": {
+        "payload": {"$ref": "https://alwaysai.co/status-response-schema.json"}
+      }
+    }
+  },
+  {
+    "if": {
+      "properties": {
+        "messageType": { "const": "app_logs" }
+      }
+    },
+    "then": {
+      "properties": {
+        "payload": {"$ref": "https://alwaysai.co/app-logs-schema.json"}
+      }
+    }
+  }
+  ],
+  "$defs": {
+    "toClient": {
+      "description": "Messages sent from the device agent to console client",
+      "type": "string",
+      "pattern": "to-client/aai-device/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+    }
+  }
+}

package/src/schemas/to-cloud-message-schema.json

@@ -0,0 +1,53 @@
+{
+  "$id": "https://alwaysai.co/cloud-message-schema.json",
+  "title": "cloud_message",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "description": "The messaging payload structure for messages sent from device agent to the cloud",
+  "type": "object",
+  "properties": {
+    "timestamp": {
+      "type": "string"
+    },
+    "deviceId": {
+      "description": "Device UUID of device sending the message",
+      "type": "string"
+    },
+    "topic": {
+      "oneOf": [{ "$ref": "#/$defs/toCloud" }]
+    },
+    "messageType": {
+      "type": "string",
+      "enum": [
+        "signed_urls_request"
+      ]
+    },
+    "txId": {
+      "$ref": "https://alwaysai.co/common-schema.json#/$defs/txId"
+    },
+    "payload": {
+      "type": "object"
+    }
+  },
+  "allOf":[
+  {
+    "if": {
+      "properties": {
+        "messageType": { "const": "signed_urls_request" }
+      }
+    },
+    "then": {
+      "properties": {
+        "payload": {"$ref": "https://alwaysai.co/signed-urls-request-schema.json"}
+      }
+    }
+  }
+  ],
+  "required": ["timestamp", "deviceId", "txId", "payload", "messageType"],
+  "$defs": {
+    "toCloud": {
+      "description": "Messages sent from the device agent to cloud backend client",
+      "type": "string",
+      "pattern": "to-cloud/aai-device/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+    }
+  }
+}

package/src/schemas/to-device-agent-message-schema.json

@@ -0,0 +1,127 @@
+{
+  "$id": "https://alwaysai.co/to-device-agent-message-schema.json",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "title": "to_device_agent_message",
+  "description":
+    "A schema that describes the message payload structure for messages sent from clients to device agent",
+  "type": "object",
+  "properties": {
+    "timestamp": {
+      "type": "string"
+    },
+    "topic": { "$ref": "#/$defs/toDevice" },
+    "messageType": {
+      "type": "string",
+      "enum": [
+        "app_state_control",
+        "app_version_control",
+        "fleet_app_version_control",
+        "app_install_response",
+        "models_install_response",
+        "live_state_updates",
+        "device_action",
+        "status_response"
+      ]
+    },
+    "txId": {
+      "$ref": "https://alwaysai.co/common-schema.json#/$defs/txId"
+    },
+    "payload": {
+      "type": "object"
+    }
+  },
+  "required": ["messageType", "timestamp", "txId", "payload"],
+  "allOf":[
+    {
+      "if": {
+        "properties": {
+          "messageType": { "const": "app_state_control" }
+        }
+      },
+      "then": {
+        "properties": {
+          "payload": {"$ref": "https://alwaysai.co/app-state-control-schema.json"}
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "messageType": { "const": "app_version_control" }
+        }
+      },
+      "then": {
+        "properties": {
+          "payload": {"$ref": "https://alwaysai.co/app-version-control-schema.json"}
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "messageType": { "const": "app_install_response" }
+        }
+      },
+      "then": {
+        "properties": {
+          "payload": {"$ref": "https://alwaysai.co/app-install-response-schema.json"}
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "messageType": { "const": "models_install_response" }
+        }
+      },
+      "then": {
+        "properties": {
+          "payload": {"$ref": "https://alwaysai.co/models-install-response-schema.json"}
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "messageType": { "const": "live_state_updates" }
+        }
+      },
+      "then": {
+        "properties": {
+          "payload": {"$ref": "https://alwaysai.co/live-updates-toggle-schema.json"}
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "messageType": { "const": "device_action" }
+        }
+      },
+      "then": {
+        "properties": {
+          "payload": {"$ref": "https://alwaysai.co/device-action-schema.json"}
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "messageType": { "const": "status_response" }
+        }
+      },
+      "then": {
+        "properties": {
+          "payload": {"$ref": "https://alwaysai.co/status-response-schema.json"}
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "toDevice": {
+      "description": "Topic on which messages are sent to device agent.",
+      "type": "string",
+      "pattern": "^to-device/aai-device/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+    }
+  }
+}

package/src/shadow-schema.ts

@@ -0,0 +1,258 @@
+import Ajv2019 from 'ajv/dist/2019';
+import * as commonSchema from './schemas/common-schema.json';
+import * as deviceAgentStatusSchema from './schemas/device-agent-status-schema.json';
+import * as envVarSchema from './schemas/env-var-schema.json';
+import * as secureTunnelSchema from './schemas/secure-tunnel-schema.json';
+import * as shadowProjectUpdateLegacySchema from './schemas/shadow-project-update-legacy-schema.json';
+import * as shadowProjectUpdateSchema from './schemas/shadow-project-update-schema.json';
+import * as shadowProjectsUpdateAllSchema from './schemas/shadow-projects-update-all-schema.json';
+import * as systemInformationSchema from './schemas/system-information-schema.json';
+
+import { keyMirror } from './utils';
+
+const ajv = new Ajv2019({
+  allErrors: true,
+  schemas: [commonSchema]
+});
+
+export function getDesiredFromMessage(message) {
+  if (message?.state?.desired) {
+    return message.state.desired;
+  } else return null;
+}
+
+export function getReportedFromMessage(message) {
+  if (message?.state?.reported) {
+    return message.state.reported;
+  } else return null;
+}
+
+export function getUpdateDeltaStateFromMessage(message) {
+  if (message?.state) {
+    return message.state;
+  } else return null;
+}
+
+/* ============================================================================
+                                  Shadow Topics
+============================================================================ */
+
+const SHADOW_PREFIX = `$aws/things/`;
+
+export const ShadowTopics = keyMirror({
+  get: null,
+  'get/accepted': null,
+  'get/rejected': null,
+  update: null,
+  'update/delta': null,
+  'update/accepted': null,
+  'update/rejected': null,
+  delete: null,
+  'delete/accepted': null,
+  'delete/rejected': null
+});
+export type ShadowTopics = keyof typeof ShadowTopics;
+export const SHADOW_TOPICS = Object.keys(ShadowTopics) as ShadowTopics[];
+
+const ShadowNames = keyMirror({
+  projects: null,
+  'system-info': null,
+  'secure-tunnel': null,
+  'device-agent-status': null
+});
+export type ShadowNames = keyof typeof ShadowNames;
+export const SHADOW_NAMES = Object.keys(ShadowNames) as ShadowNames[];
+
+export const getShadowTopic = (
+  clientId: string,
+  shadowName: ShadowNames,
+  shadowTopic: ShadowTopics
+) => `${SHADOW_PREFIX}${clientId}/shadow/name/${shadowName}/${shadowTopic}`;
+
+/* ============================================================================
+                                  Project Shadow
+============================================================================ */
+
+export type ShadowUpdateTypes =
+  | ShadowProjectsUpdateAll
+  | SystemInformationShadowUpdate
+  | SecureTunnelShadowUpdate
+  | DeviceAgentStatusShadowUpdate;
+
+export interface ProjectShadowUpdate {
+  appConfig?: string;
+  envVars?: string;
+}
+
+export interface ProjectShadowUpdateLegacy {
+  appConfig?: string;
+  envVars?: {
+    [service: string]: {
+      [key: string]: string | null;
+    };
+  };
+}
+
+export interface ShadowProjectsUpdateAll {
+  [projectId: string]: ProjectShadowUpdate | null;
+}
+
+// Shadow Message validator functions
+ajv.addSchema(shadowProjectUpdateSchema, 'shadow-project-update-schema.json');
+export const validateProjectShadowUpdate = ajv.compile<ProjectShadowUpdate>(
+  shadowProjectUpdateSchema
+);
+
+ajv.addSchema(
+  shadowProjectUpdateLegacySchema,
+  'shadow-project-update-legacy-schema.json'
+);
+export const validateLegacyProjectShadowUpdate =
+  ajv.compile<ProjectShadowUpdateLegacy>(shadowProjectUpdateSchema);
+
+ajv.addSchema(
+  shadowProjectsUpdateAllSchema,
+  'shadow-projects-update-all-schema.json'
+);
+export const validateShadowProjectsUpdateAll =
+  ajv.compile<ShadowProjectsUpdateAll>(shadowProjectsUpdateAllSchema);
+
+/* ============================================================================
+                                  System Information Shadow
+============================================================================ */
+
+export interface SystemInformationShadowUpdate {
+  os?: {
+    platform?: string;
+    distro?: string;
+    release?: string;
+    kernel?: string;
+    architecture?: string;
+    hostname?: string;
+  };
+  cpu?: {
+    manufacturer?: string;
+    brand?: string;
+    vendor?: string;
+    model?: string;
+    cores?: string;
+    physicalCores?: string;
+    efficiencyCores?: string;
+    processors?: string;
+  };
+  disk?: {
+    drives: {
+      device?: string;
+      type?: string;
+      name?: string;
+      vendor?: string;
+      size?: string;
+    }[];
+  };
+  device?: {
+    manufacturer?: string;
+    model?: string;
+    version?: string;
+    serial?: string;
+    virtual?: boolean; // boolean on purpose
+  };
+  network?: {
+    ipv4Address?: string;
+    ipv6Address?: string;
+    macAddress?: string;
+  };
+  versions?: {
+    agent?: string;
+    deviceAgentSchemas?: string;
+    npm?: string;
+    node?: string;
+    docker?: string;
+    dockerCompose?: string;
+  };
+  lastBootTime?: string;
+}
+
+ajv.addSchema(systemInformationSchema, 'system-information-schema.json');
+export const validateSystemInformationShadowUpdate =
+  ajv.compile<SystemInformationShadowUpdate>(systemInformationSchema);
+
+/* ============================================================================
+                                  Environment Variables Shadow
+============================================================================ */
+
+export interface EnvVars {
+  [service: string]: {
+    [name: string]: string | null;
+  };
+}
+
+ajv.addSchema(envVarSchema, 'env-var-schema.json');
+export const validateEnvVarSchemaShadowUpdate =
+  ajv.compile<EnvVars>(envVarSchema);
+
+/* ============================================================================
+                                  Secure Tunnel Shadow
+============================================================================ */
+
+export type SecureTunnelPortInfo = {
+  enabled: boolean;
+  type: string;
+  ip: string;
+  port: number;
+};
+
+export type SecureTunnelShadowUpdate = {
+  st_ports: SecureTunnelPortInfo[];
+};
+
+ajv.addSchema(secureTunnelSchema, 'secure-tunnel-schema.json');
+export const validateSecureTunnelShadowUpdate =
+  ajv.compile<SecureTunnelShadowUpdate>(secureTunnelSchema);
+
+/* ============================================================================
+                                  Device Agent Status
+============================================================================ */
+
+export const passthroughStatusEnum = keyMirror({
+  starting: null,
+  running: null,
+  error: null,
+  disabled: null
+});
+
+export type PassthroughStatusValue = keyof typeof passthroughStatusEnum;
+export interface DeviceAgentStatusShadowUpdate {
+  passthrough: {
+    status: PassthroughStatusValue;
+    message: string;
+  };
+}
+
+ajv.addSchema(deviceAgentStatusSchema, 'device-agent-status-schema.json');
+export const validateDeviceAgentStatusShadowUpdate =
+  ajv.compile<DeviceAgentStatusShadowUpdate>(deviceAgentStatusSchema);
+
+/* ============================================================================
+                                  Shadow Message Builders
+============================================================================ */
+
+export function buildUpdateShadowMessage<T extends ShadowUpdateTypes>(opts: {
+  clientId: string;
+  reported?: T;
+  desired?: T;
+}) {
+  const { clientId, reported, desired } = opts;
+  const state = { reported, desired };
+  const message = {
+    ...buildBaseShadowMessage(clientId),
+    state
+  };
+  return message;
+}
+
+export function buildBaseShadowMessage(clientId: string) {
+  const baseShadowMessage = {
+    clientToken: clientId
+  };
+  return baseShadowMessage;
+}

package/src/signed-urls-request-schema.ts

@@ -0,0 +1,22 @@
+import { SignedUrlsRequestMessageType } from './constants';
+import { BaseToClientMessage } from './common';
+
+type ModelsObject = {
+  [modelId: string]: number;
+};
+
+export interface SignedUrlsRequestPayload {
+  signedUrlsRequest?: {
+    projectId: string;
+    appReleaseHash: string;
+  };
+  modelsOnlyUrlsRequest?: {
+    projectId: string;
+    models: ModelsObject;
+  };
+}
+
+export interface SignedUrlsRequestMessage extends BaseToClientMessage {
+  messageType: SignedUrlsRequestMessageType;
+  payload: SignedUrlsRequestPayload;
+}