From de351acb23f5c09bafcf14a7cabde139f536b1d1 Mon Sep 17 00:00:00 2001 From: sirily11 <32106111+sirily11@users.noreply.github.com> Date: Tue, 8 Mar 2022 10:58:08 +0800 Subject: [PATCH] docs(common): add more docs (#42) --- .../db-interfaces/device_interfaces.ts | 28 ++++++++++++ .../db-interfaces/docker_interfaces.ts | 11 ++++- .../execution_plan_interfaces.ts | 18 ++++++++ .../installation_template_interfaces.ts | 27 +++++++++++ .../db-interfaces/job_result_interfaces.ts | 27 ++++++++++- .../db-interfaces/pending_job_interfaces.ts | 15 +++++++ .../db-interfaces/static_node_interfaces.ts | 6 +++ .../db-interfaces/storage_interfaces.ts | 15 +++++++ .../update_template_interfaces.ts | 25 +++++++++++ .../src/interfaces/etd_interfaces.ts | 45 +++++++++++++++++++ packages/etd-common/src/schemas/index.ts | 2 +- .../src/tests/mongodb/jobResult.test.ts | 4 +- 12 files changed, 217 insertions(+), 6 deletions(-) diff --git a/packages/etd-common/src/interfaces/db-interfaces/device_interfaces.ts b/packages/etd-common/src/interfaces/db-interfaces/device_interfaces.ts index ad00112c..e4dd5493 100644 --- a/packages/etd-common/src/interfaces/db-interfaces/device_interfaces.ts +++ b/packages/etd-common/src/interfaces/db-interfaces/device_interfaces.ts @@ -2,16 +2,44 @@ import { ContainerInfo, ImageInfo } from "dockerode"; import { Web3DataInfo } from "../etd_interfaces"; interface Docker { + /** + * Docker images' info + */ images: ImageInfo[]; + /** + * Docker container's info + */ containers: ContainerInfo[]; } export interface DeviceDBInterface { + /** + * Device's online status + */ isOnline?: boolean; + /** + * Last seen time. This will be set on server side. + * DO NOT provide this field in your request, otherwise, it will be overwritten. + */ lastSeen?: Date; + /** + * Name of the device + */ name: string; + /** + * ID of the device + */ user: string | null; + /** + * Admin node's version + */ adminVersion: string; + /** + * ETD Node's info + */ data?: Web3DataInfo; + /** + * Device's docker info + */ docker?: Docker; } diff --git a/packages/etd-common/src/interfaces/db-interfaces/docker_interfaces.ts b/packages/etd-common/src/interfaces/db-interfaces/docker_interfaces.ts index 75fd365a..fe07e69b 100644 --- a/packages/etd-common/src/interfaces/db-interfaces/docker_interfaces.ts +++ b/packages/etd-common/src/interfaces/db-interfaces/docker_interfaces.ts @@ -1,13 +1,22 @@ export interface DockerImageDBInterface { + /** + * Name of the docker image. For example hello-world + */ imageName: string; + /** + * List of tags of the given image. For example [latest, 1.0, 1.1] + */ tags: DockerImageVersionDBInterface[]; /** - * Will be set when query from installation template + * Read only! Will be set when query from installation template. */ tag?: DockerImageVersionDBInterface; } interface DockerImageVersionDBInterface { + /** + * Tag of the image. For example 1.0 + */ tag: string; } diff --git a/packages/etd-common/src/interfaces/db-interfaces/execution_plan_interfaces.ts b/packages/etd-common/src/interfaces/db-interfaces/execution_plan_interfaces.ts index 65e6187f..24ce5625 100644 --- a/packages/etd-common/src/interfaces/db-interfaces/execution_plan_interfaces.ts +++ b/packages/etd-common/src/interfaces/db-interfaces/execution_plan_interfaces.ts @@ -1,8 +1,26 @@ export interface ExecutionPlanDBInterface { + /** + * Creation timestamp of the execution plan + */ createdAt: any; + /** + * Update template's id related to this execution plan + */ updateTemplate: any; + /** + * Is the execution finished? + */ isDone: boolean; + /** + * Does the execution plan contain any error? + */ isError: boolean; + /** + * Name of the execution plan + */ name: string; + /** + * Description of the execution plan + */ description: string; } diff --git a/packages/etd-common/src/interfaces/db-interfaces/installation_template_interfaces.ts b/packages/etd-common/src/interfaces/db-interfaces/installation_template_interfaces.ts index 0713699b..23f2f464 100644 --- a/packages/etd-common/src/interfaces/db-interfaces/installation_template_interfaces.ts +++ b/packages/etd-common/src/interfaces/db-interfaces/installation_template_interfaces.ts @@ -4,23 +4,50 @@ import { DockerImageDBInterface } from "./docker_interfaces"; export interface InstallationTemplateDBInterface { + /** + * Docker compose version + */ version: string; + /** + * Docker compose services. This should be the same format as the docker compose file + */ services: { name: string; service: InstallationTemplateServiceDBInterface }[]; /** * Template tag used to identify the template */ // eslint-disable-next-line camelcase template_tag: string; + /** + * Author of this installation template. Will be set on server. + */ // eslint-disable-next-line camelcase created_by: string; } export interface InstallationTemplateServiceDBInterface { + /** + * Docker Image of this service + */ image: DockerImageDBInterface; + /** + * Restart policy + */ restart: string; + /** + * Environments used in the docker compose. For example a=hello + */ environment: string[]; + /** + * Network mode + */ // eslint-disable-next-line camelcase network_mode: string; + /** + * Mounting options. For example ./data:/var/usr + */ volumes: string[]; + /** + * Labels of the docker compose + */ labels: string[]; } diff --git a/packages/etd-common/src/interfaces/db-interfaces/job_result_interfaces.ts b/packages/etd-common/src/interfaces/db-interfaces/job_result_interfaces.ts index aa9cad40..ad7cd196 100644 --- a/packages/etd-common/src/interfaces/db-interfaces/job_result_interfaces.ts +++ b/packages/etd-common/src/interfaces/db-interfaces/job_result_interfaces.ts @@ -1,13 +1,36 @@ +import { JobTaskType } from "../../enums"; + export interface JobResultDBInterface { + /** + * Pending job's id + */ jobId: string; + /** + * Submission date + */ time: Date; + /** + * Submitted by which device + */ deviceID: string; /** - * From which client. This will be the unique id + * From which client who sent this job. This will be the unique id */ from: string; + /** + * actual command + */ command: any; + /** + * Job's result + */ result: any; + /** + * Is success? + */ success: boolean; - commandType: string; + /** + * Command type. Should be one of the job task type enum + */ + commandType: JobTaskType; } diff --git a/packages/etd-common/src/interfaces/db-interfaces/pending_job_interfaces.ts b/packages/etd-common/src/interfaces/db-interfaces/pending_job_interfaces.ts index 52e954ab..11dd248b 100644 --- a/packages/etd-common/src/interfaces/db-interfaces/pending_job_interfaces.ts +++ b/packages/etd-common/src/interfaces/db-interfaces/pending_job_interfaces.ts @@ -1,17 +1,32 @@ import { JobTaskType, PendingJobTaskType } from "../../enums"; interface Task { + /** + * Job type + */ type: JobTaskType; + /** + * Job value + */ value: T; } export interface PendingJobDBInterface { + /** + * Send this job to which device + */ targetDeviceId: string; /** * From client id. */ from: string; + /** + * Task object + */ task: Task; + /** + * Creation timestamp + */ createdAt: string; /** * Whether this job has been retrieved diff --git a/packages/etd-common/src/interfaces/db-interfaces/static_node_interfaces.ts b/packages/etd-common/src/interfaces/db-interfaces/static_node_interfaces.ts index 3e5f6a78..168495b1 100644 --- a/packages/etd-common/src/interfaces/db-interfaces/static_node_interfaces.ts +++ b/packages/etd-common/src/interfaces/db-interfaces/static_node_interfaces.ts @@ -1,4 +1,10 @@ export interface StaticNodeDBInterface { + /** + * Static node's name + */ nodeName: string; + /** + * Static node's enode url + */ nodeURL: string; } diff --git a/packages/etd-common/src/interfaces/db-interfaces/storage_interfaces.ts b/packages/etd-common/src/interfaces/db-interfaces/storage_interfaces.ts index 280b1486..f8ef08de 100644 --- a/packages/etd-common/src/interfaces/db-interfaces/storage_interfaces.ts +++ b/packages/etd-common/src/interfaces/db-interfaces/storage_interfaces.ts @@ -1,13 +1,25 @@ import { DeviceDBInterface } from "./device_interfaces"; export interface StorageUserDBInterface { + /** + * User name + */ // eslint-disable-next-line camelcase user_name: string; + /** + * User id + */ // eslint-disable-next-line camelcase user_id: string; + /** + * User's coinbase + */ coinbase?: string; } +/** + * @deprecated this interface will be removed in the future + */ export interface OwnerDBInterface { // eslint-disable-next-line camelcase user_id: string; @@ -44,5 +56,8 @@ export interface StorageItemDBInterface { export interface StorageItemWithStatusDBInterface extends StorageItemDBInterface { + /** + * Realtime status of the device + */ status?: DeviceDBInterface; } diff --git a/packages/etd-common/src/interfaces/db-interfaces/update_template_interfaces.ts b/packages/etd-common/src/interfaces/db-interfaces/update_template_interfaces.ts index ae71ce70..d770679f 100644 --- a/packages/etd-common/src/interfaces/db-interfaces/update_template_interfaces.ts +++ b/packages/etd-common/src/interfaces/db-interfaces/update_template_interfaces.ts @@ -4,16 +4,41 @@ import { DeviceRequest, MountConfig } from "dockerode"; * Stack to describe the structure of the container */ export interface ContainerStack { + /** + * Docker container's id. If this was sent by remote server used to create a new container, + * then this field will be undefined + */ containerId?: string; + /** + * Docker container's name + */ containerName: string; + /** + * Related image + */ image: ImageStack; + /** + * Map of container's configuration. Similar to the docker's config + */ config?: DockerContainerConfig; + /** + * Log of container + */ runningLog?: string; } export interface ImageStack { + /** + * Image id. This field will be set during pulling. It will be undefined when receiving from the server. + */ imageId?: string; + /** + * Image name + */ image: string; + /** + * Image tag + */ tag: string; } diff --git a/packages/etd-common/src/interfaces/etd_interfaces.ts b/packages/etd-common/src/interfaces/etd_interfaces.ts index aec3c6a0..f7475772 100644 --- a/packages/etd-common/src/interfaces/etd_interfaces.ts +++ b/packages/etd-common/src/interfaces/etd_interfaces.ts @@ -14,26 +14,71 @@ export interface TransactionSummary { interface PeerInfo { caps: string[]; + /** + * Peer's id + */ id: string; + /** + * Peer's name + */ name: string; network: { + /** + * Peer's local ip address + */ localAddress: string; + /** + * Peer's network ip address + */ remoteAddress: string; }; + /** + * Peer's protocol info + */ protocols: any; } export interface Web3DataInfo extends BlockTransactionString { systemInfo: { + /** + * @deprecated Use admin version in device data directly. This field will be deleted in the future. + */ adminVersion: string; + /** + * ETD Node version + */ nodeVersion: string; + /** + * Number of peers connected to the + */ peerCount: number; + /** + * Syncing status of the ETD node + */ isSyncing: boolean; + /** + * Mining status of the ETD node + */ isMining: boolean; + /** + * Coinbase of the ETD node. Might be undefined if the node doesn't have one. + */ coinbase: string | undefined; + /** + * Hashing rate of the ETD node + */ hashRate: number; }; + /** + * Block time between this block and the previous block + */ blockTime: number; + /** + * Avg block time between this block and the x blocks before + */ avgBlockTime: number; + /** + * Peers info + */ peers: PeerInfo[]; } diff --git a/packages/etd-common/src/schemas/index.ts b/packages/etd-common/src/schemas/index.ts index 599470e3..516999a8 100644 --- a/packages/etd-common/src/schemas/index.ts +++ b/packages/etd-common/src/schemas/index.ts @@ -2,7 +2,7 @@ import deviceSchema from "./device_interfaces.json"; import dockerSchema from "./docker_interfaces.json"; import etdSchema from "./etd_interfaces.json"; import executionPlanSchema from "./execution_plan_interfaces.json"; -import installationTemplateSchema from "./execution_plan_interfaces.json"; +import installationTemplateSchema from "./installation_template_interfaces.json"; import jobResultSchema from "./job_result_interfaces.json"; import pendingJobSchema from "./pending_job_interfaces.json"; import pluginInterfaceSchema from "./plugin_interfaces.json"; diff --git a/packages/etd-services/src/tests/mongodb/jobResult.test.ts b/packages/etd-services/src/tests/mongodb/jobResult.test.ts index f6ec77e4..14f989d9 100644 --- a/packages/etd-services/src/tests/mongodb/jobResult.test.ts +++ b/packages/etd-services/src/tests/mongodb/jobResult.test.ts @@ -56,7 +56,7 @@ describe("Job Result Test", () => { command: undefined, result: undefined, success: true, - commandType: "", + commandType: enums.JobTaskType.Web3, }; /** @@ -70,7 +70,7 @@ describe("Job Result Test", () => { command: undefined, result: undefined, success: false, - commandType: "", + commandType: enums.JobTaskType.Web3, }; beforeAll(async () => {