Merge pull request #300 from iExecBlockchainComputing/feature/expose-task-debug

Feature/expose task debug

Author: PierreJeanjacquot

CHANGELOG.md

@@ -7,11 +7,14 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - added key `isUserRejection` in `Web3ProviderError` set to `true` when the error is detected as a user rejection
+- `task.fetchOffchainInfo(taskid)` to get off-chain status information about the task from the workerpool
+- `task.fetchLogs(taskid)` to fetch app logs from the workers
 
 ### Changed
 
 - `iexec_result_storage_proxy` default value is no more set in request params
 - removed deprecated request param `iexec_developer_logger`
+- change information exposed by `iexec task debug` for better readability
 
 ### Removed
 
@@ -313,7 +316,7 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - workerpool API url configuration
-- `iexec task debug <taskid> [--logs]` to show offchain information
+- `iexec task debug <taskid> [--logs]` to show off-chain information
 - `ens.getDefaultDomain(address)` to get the default free to use ENS domain given an address
 - support for requester secrets
 - check dataset secret exists on requestorder check

docs/classes/IExecTaskModule.md

@@ -23,6 +23,8 @@ module exposing task methods
 ### Methods
 
 - [claim](IExecTaskModule.md#claim)
+- [fetchLogs](IExecTaskModule.md#fetchlogs)
+- [fetchOffchainInfo](IExecTaskModule.md#fetchoffchaininfo)
 - [fetchResults](IExecTaskModule.md#fetchresults)
 - [obsTask](IExecTaskModule.md#obstask)
 - [show](IExecTaskModule.md#show)
@@ -91,6 +93,68 @@ console.log('task claimed:', claimTxHash);
 
 ___
 
+### fetchLogs
+
+▸ **fetchLogs**(`taskid`): `Promise`<{ `stderr`: `string` ; `stdout`: `string` ; `worker`: `string`  }[]\>
+
+**SIGNER REQUIRED, ONLY REQUESTER**
+
+get the workers logs for specified task.
+
+_NB_: the workerpool must declare it's API url to enable this feature, check declared API url with `IExecWorkerpoolModule.getWorkerpoolApiUrl(workerpool)`
+
+example:
+```js
+const logArray = await fetchLogs('0x668cb3e53ebbcc9999997709586c5af07f502f6120906fa3506ce1f531cedc81');
+logsArray.forEach(({ worker, stdout, stderr }) => {
+  console.log(`----- worker ${worker} -----`);
+  console.log(`stdout:\n${stdout}`);
+  console.log(`stderr:\n${stderr}`);
+});
+```
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `taskid` | `string` |
+
+#### Returns
+
+`Promise`<{ `stderr`: `string` ; `stdout`: `string` ; `worker`: `string`  }[]\>
+
+___
+
+### fetchOffchainInfo
+
+▸ **fetchOffchainInfo**(`taskid`): `Promise`<{ `replicates`: { `exitCode?`: `number` ; `status`: `string` ; `statusHistory`: { `cause?`: `string` ; `date`: `string` ; `status`: `string`  }[] ; `worker`: `string`  }[] ; `task`: { `status`: `string` ; `statusHistory`: { `cause?`: `string` ; `date`: `string` ; `status`: `string`  }[]  }  }\>
+
+get off-chain status information for specified task.
+
+_NB_: the workerpool must declare it's API url to enable this feature, check declared API url with `IExecWorkerpoolModule.getWorkerpoolApiUrl(workerpool)`
+
+example:
+```js
+const { task, replicates } = await fetchOffchainInfo('0x668cb3e53ebbcc9999997709586c5af07f502f6120906fa3506ce1f531cedc81');
+
+console.log(`task status: ${task.status}`);
+replicates.forEach(({ worker, status }) =>
+  console.log(`worker ${worker} replicate status: ${status}`)
+);
+```
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `taskid` | `string` |
+
+#### Returns
+
+`Promise`<{ `replicates`: { `exitCode?`: `number` ; `status`: `string` ; `statusHistory`: { `cause?`: `string` ; `date`: `string` ; `status`: `string`  }[] ; `worker`: `string`  }[] ; `task`: { `status`: `string` ; `statusHistory`: { `cause?`: `string` ; `date`: `string` ; `status`: `string`  }[]  }  }\>
+
+___
+
 ### fetchResults
 
 ▸ **fetchResults**(`taskid`): `Promise`<`Response`\>

docs/classes/IExecWorkerpoolModule.md

@@ -149,15 +149,15 @@ ___
 
 ### getWorkerpoolApiUrl
 
-▸ **getWorkerpoolApiUrl**(`workerpoolAddress`, `url`): `Promise`<`undefined` \| `string`\>
+▸ **getWorkerpoolApiUrl**(`workerpoolAddress`): `Promise`<`undefined` \| `string`\>
 
 read the workerpool API url on the blockchain
 
 _NB_: resolve to `undefined` if the workerpool API url was not declared.
 
 example:
 ```js
-const url = await getWorkerpoolApiUrl('my-workerpool.eth', 'my-workerpool.com');
+const url = await getWorkerpoolApiUrl('my-workerpool.eth');
 console.log('workerpool API url:', url);
 ```
 
@@ -166,7 +166,6 @@ console.log('workerpool API url:', url);
 | Name | Type |
 | :------ | :------ |
 | `workerpoolAddress` | `string` |
-| `url` | `string` |
 
 #### Returns
 

docs/classes/internal_.TaskObservable.md

@@ -40,7 +40,7 @@
 
 ▸ **subscribe**(`callbacks`): () => `void`
 
-subscribe to task updates via an Observer until either `complete()` or `error(error: Error)` is called on the Observer or the subscribtion is canceled by calling the returned unsubscribe method.
+subscribe to task updates via an Observer until either `complete()` or `error(error: Error)` is called on the Observer or the subscription is canceled by calling the returned unsubscribe method.
 
 return the `unsubscribe: () => void` method.
 
@@ -67,7 +67,7 @@ data:
 
 ▸ (): `void`
 
-subscribe to task updates via an Observer until either `complete()` or `error(error: Error)` is called on the Observer or the subscribtion is canceled by calling the returned unsubscribe method.
+subscribe to task updates via an Observer until either `complete()` or `error(error: Error)` is called on the Observer or the subscription is canceled by calling the returned unsubscribe method.
 
 return the `unsubscribe: () => void` method.
 

src/common/execution/debug.js

@@ -80,11 +80,23 @@ export const fetchTaskOffchainInfo = async (
   try {
     const vTaskid = await bytes32Schema().validate(taskid);
     const workerpoolApiUrl = await getTaskOffchainApiUrl(contracts, vTaskid);
-    return await jsonApi.get({
+    const data = await jsonApi.get({
       api: workerpoolApiUrl,
       endpoint: `/tasks/${vTaskid}`,
       ApiCallErrorClass: WorkerpoolCallError,
     });
+    return {
+      task: {
+        status: data.currentStatus,
+        statusHistory: data.dateStatusList,
+      },
+      replicates: (data.replicates || []).map((replicate) => ({
+        worker: replicate.walletAddress,
+        exitCode: replicate.appExitCode,
+        status: replicate.currentStatus,
+        statusHistory: replicate.statusUpdateList,
+      })),
+    };
   } catch (error) {
     debug('fetchTaskOffchainInfo()', error);
     throw error;

src/common/utils/validator.js

@@ -70,7 +70,7 @@ export const uint256Schema = () =>
 export const booleanSchema = () => boolean();
 
 export const basicUrlSchema = () =>
-  string().matches(/^http[s]?:\/\//, '${path} "${value}" is not a valid URL');
+  string().matches(/^https?:\/\//, '${path} "${value}" is not a valid URL');
 
 const amountErrorMessage = ({ originalValue }) =>
   `${
@@ -816,7 +816,10 @@ export const textRecordKeySchema = () => string().required().strict(true);
 
 export const textRecordValueSchema = () => string().default('').strict(true);
 
-export const workerpoolApiUrlSchema = () => string().url().default('');
+export const workerpoolApiUrlSchema = () =>
+  string()
+    .matches(/^(https?:\/\/.*)?$/, '${path} "${value}" is not a valid URL') // accept empty string to reset workerpool URL
+    .default('');
 
 export const smsUrlOrMapSchema = () =>
   lazy((stringOrMap) => {

src/lib/IExecTaskModule.d.ts

@@ -36,7 +36,7 @@ interface Task {
 
 declare class TaskObservable extends Observable {
   /**
-   * subscribe to task updates via an Observer until either `complete()` or `error(error: Error)` is called on the Observer or the subscribtion is canceled by calling the returned unsubscribe method.
+   * subscribe to task updates via an Observer until either `complete()` or `error(error: Error)` is called on the Observer or the subscription is canceled by calling the returned unsubscribe method.
    *
    * return the `unsubscribe: () => void` method.
    *
@@ -165,6 +165,84 @@ export default class IExecTaskModule extends IExecModule {
    * ```
    */
   fetchResults(taskid: Taskid): Promise<Response>;
+  /**
+   * **SIGNER REQUIRED, ONLY REQUESTER**
+   *
+   * get the workers logs for specified task.
+   *
+   * _NB_: the workerpool must declare it's API url to enable this feature, check declared API url with `IExecWorkerpoolModule.getWorkerpoolApiUrl(workerpool)`
+   *
+   * example:
+   * ```js
+   * const logArray = await fetchLogs('0x668cb3e53ebbcc9999997709586c5af07f502f6120906fa3506ce1f531cedc81');
+   * logsArray.forEach(({ worker, stdout, stderr }) => {
+   *   console.log(`----- worker ${worker} -----`);
+   *   console.log(`stdout:\n${stdout}`);
+   *   console.log(`stderr:\n${stderr}`);
+   * });
+   * ```
+   */
+  fetchLogs(
+    taskid: Taskid,
+  ): Promise<Array<{ worker: Address; stdout: string; stderr: string }>>;
+  /**
+   * get off-chain status information for specified task.
+   *
+   * _NB_: the workerpool must declare it's API url to enable this feature, check declared API url with `IExecWorkerpoolModule.getWorkerpoolApiUrl(workerpool)`
+   *
+   * example:
+   * ```js
+   * const { task, replicates } = await fetchOffchainInfo('0x668cb3e53ebbcc9999997709586c5af07f502f6120906fa3506ce1f531cedc81');
+   *
+   * console.log(`task status: ${task.status}`);
+   * replicates.forEach(({ worker, status }) =>
+   *   console.log(`worker ${worker} replicate status: ${status}`)
+   * );
+   * ```
+   */
+  fetchOffchainInfo(taskid: Taskid): Promise<{
+    task: {
+      /**
+       * task status
+       *
+       * see https://protocol.docs.iex.ec/for-developers/task-feedback#task-statuses
+       */
+      status: string;
+      statusHistory: Array<{
+        /**
+         * task status
+         *
+         * see https://protocol.docs.iex.ec/for-developers/task-feedback#task-statuses
+         */
+        status: string;
+        date: string;
+        cause?: string;
+      }>;
+    };
+    replicates: Array<{
+      worker: Address;
+      /**
+       * app exit code (omitted when exit code is 0)
+       */
+      exitCode?: number;
+      /**
+       * replicate status
+       *
+       * see https://protocol.docs.iex.ec/for-developers/task-feedback#replicate-statuses
+       */
+      status: string;
+      statusHistory: Array<{
+        /**
+         * replicate status
+         *
+         * see https://protocol.docs.iex.ec/for-developers/task-feedback#replicate-statuses
+         */
+        status: string;
+        date: string;
+        cause?: string;
+      }>;
+    }>;
+  }>;
   /**
    * Create an IExecTaskModule instance using an IExecConfig instance
    */

src/lib/IExecTaskModule.js

@@ -1,6 +1,10 @@
 import IExecModule from './IExecModule.js';
 import { show, obsTask, claim } from '../common/execution/task.js';
 import { fetchTaskResults } from '../common/execution/result.js';
+import {
+  fetchAllReplicatesLogs,
+  fetchTaskOffchainInfo,
+} from '../common/execution/debug.js';
 
 export default class IExecTaskModule extends IExecModule {
   constructor(...args) {
@@ -18,5 +22,12 @@ export default class IExecTaskModule extends IExecModule {
       fetchTaskResults(await this.config.resolveContractsClient(), taskid, {
         ipfsGatewayURL: await this.config.resolveIpfsGatewayURL(),
       });
+    this.fetchLogs = async (taskid) =>
+      fetchAllReplicatesLogs(
+        await this.config.resolveContractsClient(),
+        taskid,
+      );
+    this.fetchOffchainInfo = async (taskid) =>
+      fetchTaskOffchainInfo(await this.config.resolveContractsClient(), taskid);
   }
 }

src/lib/IExecWorkerpoolModule.d.ts

@@ -141,13 +141,12 @@ export default class IExecWorkerpoolModule extends IExecModule {
    *
    * example:
    * ```js
-   * const url = await getWorkerpoolApiUrl('my-workerpool.eth', 'my-workerpool.com');
+   * const url = await getWorkerpoolApiUrl('my-workerpool.eth');
    * console.log('workerpool API url:', url);
    * ```
    */
   getWorkerpoolApiUrl(
     workerpoolAddress: Addressish,
-    url: string,
   ): Promise<string | undefined>;
   /**
    * **ONLY WORKERPOOL OWNER**