uapi-json 1.18.0 → 1.19.0

package/docs/Terminal.md

@@ -49,11 +49,12 @@ see [close_session](#close_session) method.
 # API
 
 **TerminalService**
-* [`.executeCommand(command, stopMD)`](#execute_command)
+* [`.executeCommand(command, options)`](#execute_command)
+* [`.executeStatelessCommandWhenIdle(command, options)`](#execute_stateless_command_when_idle)
 * [`.closeSession()`](#close_session)
 * [`.getToken()`](#get_token)
 
-## .executeCommand(command, stopMD)
+## .executeCommand(command, options)
 <a name="execute_command"></a>
 Executes a command in terminal and returns its terminal response
 
@@ -62,7 +63,61 @@ Executes a command in terminal and returns its terminal response
 | Param | Type | Description |
 | --- | --- | --- |
 | command | `String` | String representation of the command you want to execute |
+| options | `Object` | Optional command execution options. |
+
+**Options**
+
+| Param | Type | Description |
+| --- | --- | --- |
 | stopMD | `(screens) => boolean` | Function which gets all previous screens concatenated and detects if more `MD` command needed. |
+| sleepInterval | `Number` | Minimum delay in milliseconds from the last successful full terminal response to the next command send. |
+
+`stopMD` must be passed inside `options`; passing it directly as the second argument
+is not supported.
+
+## .executeStatelessCommandWhenIdle(command, options)
+<a name="execute_stateless_command_when_idle"></a>
+Executes a stateless command when terminal is idle and returns its terminal response.
+
+If terminal is busy, command is added to the stateless commands queue and executed
+after the current command and previously queued stateless commands are finished.
+Queued commands are executed one by one in FIFO order.
+If terminal is idle, regular `executeCommand` calls execute before queued stateless
+commands.
+
+This method is promise based. Every caller receives the result or error from its own
+command execution. If one queued command fails, later queued commands are still executed.
+If the active command fails before the queue is drained, queued stateless commands are
+skipped and rejected with the same terminal error.
+
+Stateless means command is independent of terminal context, such as an open booking,
+fare search, or other GDS working state. This method does not detect or enforce
+statelessness; caller is responsible for using it only for commands safe in any
+terminal context.
+
+**Returns**: `Promise` that returns terminal command response in `String` format
+
+| Param | Type | Description |
+| --- | --- | --- |
+| command | `String` | String representation of the stateless command you want to execute |
+| options | `Object` | Optional command execution options. |
+
+**Options**
+
+| Param | Type | Description |
+| --- | --- | --- |
+| stopMD | `(screens) => boolean` | Function which gets all previous screens concatenated and detects if more `MD` command needed. |
+| sleepInterval | `Number` | Minimum delay in milliseconds from the last successful full terminal response to the next command send. |
+
+```javascript
+await TerminalService.executeCommand('TE', {
+  stopMD: (screens) => screens.includes('END OF DISPLAY'),
+});
+
+await TerminalService.executeStatelessCommandWhenIdle('.CDIEV', {
+  sleepInterval: 1000,
+});
+```
 
 ## .closeSession()
 <a name="close_session"></a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uapi-json",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Travelport Universal API",
   "main": "src/",
   "engines": {

package/src/Services/Terminal/Terminal.js

@@ -101,6 +101,17 @@ const isErrorRetriable = (e) => {
   return (errorCode && RETRY_CODES_LIST.includes(errorCode));
 };
 
+const defaultStopMD = (screens) => !screenFunctions.hasMore(screens);
+
+const getCommandOptions = (options = {}) => ({
+  stopMD: options.stopMD || defaultStopMD,
+  sleepInterval: options.sleepInterval || 0,
+});
+
+const wait = (ms) => new Promise((resolve) => {
+  setTimeout(resolve, ms);
+});
+
 module.exports = function (settings) {
   const {
     timeout = false, debug = 0, autoClose = true,
@@ -109,25 +120,37 @@ module.exports = function (settings) {
   } = settings;
 
   const service = terminalService(validateServiceSettings(settings));
-  const defaultStopMD = (screens) => !screenFunctions.hasMore(screens);
 
   const state = {
     terminalState: TERMINAL_STATE_NONE,
     sessionToken: token,
+    terminalError: null,
+    lastCommandFinishedAt: null,
+    statelessCommandsQueue: [],
   };
 
   // Getting session token
-  const getSessionToken = async () => {
-    // Return error if not in correct state
+  const throwIfTerminalUnavailable = () => {
     if (state.terminalState === TERMINAL_STATE_BUSY) {
       throw new TerminalRuntimeError.TerminalIsBusy();
     }
     if (state.terminalState === TERMINAL_STATE_CLOSED) {
       throw new TerminalRuntimeError.TerminalIsClosed();
     }
+    if (state.terminalState === TERMINAL_STATE_ERROR) {
+      throw state.terminalError;
+    }
+  };
 
-    state.terminalState = TERMINAL_STATE_BUSY;
+  const setTerminalBusy = () => {
+    throwIfTerminalUnavailable();
+    Object.assign(state, {
+      terminalState: TERMINAL_STATE_BUSY,
+      terminalError: null,
+    });
+  };
 
+  const getSessionToken = async () => {
     // Return token if already obtained
     if (state.sessionToken !== null) {
       return state.sessionToken;
@@ -137,7 +160,6 @@ module.exports = function (settings) {
     state.sessionToken = sessionToken;
 
     if (!emulatePcc) {
-      state.terminalState = TERMINAL_STATE_READY;
       return state.sessionToken;
     }
 
@@ -158,6 +180,8 @@ module.exports = function (settings) {
       throw new TerminalRuntimeError.TerminalEmulationFailed(response);
     }
 
+    state.lastCommandFinishedAt = Date.now();
+
     return sessionToken;
   };
 
@@ -209,50 +233,151 @@ module.exports = function (settings) {
   const getTerminalId = (sessionToken) => getHashSubstr(sessionToken);
   const isClosed = () => state.terminalState === TERMINAL_STATE_CLOSED;
   const isInitialized = () => state.terminalState !== TERMINAL_STATE_NONE;
+  const hasStatelessCommands = () => (
+    state.statelessCommandsQueue.length > 0
+  );
+  const setTerminalReady = () => {
+    Object.assign(state, {
+      terminalState: TERMINAL_STATE_READY,
+      terminalError: null,
+    });
+  };
+  const setTerminalError = (err) => {
+    Object.assign(state, {
+      terminalState: TERMINAL_STATE_ERROR,
+      terminalError: err,
+    });
+  };
+  const rejectStatelessCommandsQueue = (err) => {
+    while (state.statelessCommandsQueue.length > 0) {
+      const { reject } = state.statelessCommandsQueue.shift();
+      reject(err);
+    }
+  };
+  const sleepBeforeCommand = async (sleepInterval) => {
+    if (state.lastCommandFinishedAt === null || sleepInterval <= 0) {
+      return;
+    }
 
-  const terminal = {
-    getToken: async () => {
-      await getSessionToken();
-      // Needed here as getSessionToken marks terminal as busy
-      state.terminalState = TERMINAL_STATE_READY;
-      return state.sessionToken;
-    },
-    executeCommand: async (command, stopMD = defaultStopMD) => {
-      try {
-        const sessionToken = await getSessionToken();
-        const terminalId = getTerminalId(sessionToken);
+    const timeToWait = sleepInterval - (Date.now() - state.lastCommandFinishedAt);
 
-        if (debug) {
-          log(`[${terminalId}] Terminal request:\n${command}`);
-        }
+    if (timeToWait > 0) {
+      await wait(timeToWait);
+    }
+  };
+  const executeCommandInternal = async (command, options) => {
+    const { stopMD, sleepInterval } = options;
+    const sessionToken = await getSessionToken();
+    const terminalId = getTerminalId(sessionToken);
 
-        const screen = await executeCommandWithRetry(command);
-        const response = await processResponse(screen, stopMD);
+    await sleepBeforeCommand(sleepInterval);
 
-        if (debug) {
-          log(`[${terminalId}] Terminal response:\n${response}`);
-        }
+    if (debug) {
+      log(`[${terminalId}] Terminal request:\n${command}`);
+    }
 
-        Object.assign(state, {
-          terminalState: TERMINAL_STATE_READY,
-        });
+    const screen = await executeCommandWithRetry(command);
+    const response = await processResponse(screen, stopMD);
 
-        if (UNEXPECTED_TERMINAL_ERRORS.some((e) => response.includes(e))) {
-          const errorObject = isFinancialCommand(command)
-            ? new TerminalRuntimeError.TerminalUnexpectedFinancialError({ screen: response })
-            : new TerminalRuntimeError.TerminalUnexpectedError({ screen: response });
+    if (debug) {
+      log(`[${terminalId}] Terminal response:\n${response}`);
+    }
 
-          throw errorObject;
-        }
+    if (UNEXPECTED_TERMINAL_ERRORS.some((e) => response.includes(e))) {
+      const errorObject = isFinancialCommand(command)
+        ? new TerminalRuntimeError.TerminalUnexpectedFinancialError({ screen: response })
+        : new TerminalRuntimeError.TerminalUnexpectedError({ screen: response });
+
+      throw errorObject;
+    }
+
+    state.lastCommandFinishedAt = Date.now();
+
+    return response;
+  };
+  const drainStatelessCommandsQueue = async () => {
+    if (state.statelessCommandsQueue.length === 0) {
+      setTerminalReady();
+      return;
+    }
+
+    const {
+      command, options, resolve, reject,
+    } = state.statelessCommandsQueue.shift();
+
+    try {
+      const response = await executeCommandInternal(command, options);
+
+      if (!hasStatelessCommands()) {
+        setTerminalReady();
+      }
+      resolve(response);
+    } catch (err) {
+      if (!hasStatelessCommands()) {
+        setTerminalReady();
+      }
+      reject(err);
+    }
+
+    await drainStatelessCommandsQueue();
+  };
+  const executeAndDrainCommands = async (command, options) => {
+    try {
+      const response = await executeCommandInternal(command, options);
+
+      if (hasStatelessCommands()) {
+        drainStatelessCommandsQueue()
+          .then(setTerminalReady)
+          .catch(setTerminalError);
+      } else {
+        setTerminalReady();
+      }
+
+      return response;
+    } catch (err) {
+      setTerminalError(err);
+      rejectStatelessCommandsQueue(err);
+      throw err;
+    }
+  };
+
+  const terminal = {
+    getToken: async () => {
+      setTerminalBusy();
 
-        return response;
+      try {
+        await getSessionToken();
+        setTerminalReady();
+        return state.sessionToken;
       } catch (err) {
-        Object.assign(state, {
-          terminalState: TERMINAL_STATE_ERROR,
-        });
+        setTerminalError(err);
         throw err;
       }
     },
+    executeCommand: async (command, options) => {
+      setTerminalBusy();
+      return executeAndDrainCommands(command, getCommandOptions(options));
+    },
+    executeStatelessCommandWhenIdle: async (command, options) => {
+      const commandOptions = getCommandOptions(options);
+
+      if (state.terminalState === TERMINAL_STATE_CLOSED) {
+        throw new TerminalRuntimeError.TerminalIsClosed();
+      }
+      if (state.terminalState === TERMINAL_STATE_ERROR) {
+        throw state.terminalError;
+      }
+      if (state.terminalState === TERMINAL_STATE_BUSY || hasStatelessCommands()) {
+        return new Promise((resolve, reject) => {
+          state.statelessCommandsQueue.push({
+            command, options: commandOptions, resolve, reject,
+          });
+        });
+      }
+
+      setTerminalBusy();
+      return executeAndDrainCommands(command, commandOptions);
+    },
     isClosed,
     isInitialized,
     closeSessionSafe: async () => {
@@ -267,19 +392,36 @@ module.exports = function (settings) {
 
       await terminal.closeSession().catch(console.error);
     },
-    closeSession: () => getSessionToken()
-      .then(
-        (sessionToken) => service.closeSession({
-          sessionToken,
-        })
-      ).then(
-        (response) => {
-          Object.assign(state, {
-            terminalState: TERMINAL_STATE_CLOSED,
-          });
-          return response;
-        }
-      ),
+    closeSession: () => {
+      if (state.terminalState === TERMINAL_STATE_BUSY) {
+        return Promise.reject(new TerminalRuntimeError.TerminalIsBusy());
+      }
+      if (state.terminalState === TERMINAL_STATE_CLOSED) {
+        return Promise.reject(new TerminalRuntimeError.TerminalIsClosed());
+      }
+      if (state.terminalState === TERMINAL_STATE_ERROR && state.sessionToken === null) {
+        return Promise.reject(state.terminalError);
+      }
+
+      Object.assign(state, {
+        terminalState: TERMINAL_STATE_BUSY,
+      });
+
+      return getSessionToken()
+        .then(
+          (sessionToken) => service.closeSession({
+            sessionToken,
+          })
+        ).then(
+          (response) => {
+            Object.assign(state, {
+              terminalState: TERMINAL_STATE_CLOSED,
+              terminalError: null,
+            });
+            return response;
+          }
+        );
+    },
   };
 
   if (autoClose) {