feat: fallback to http gateway (#231)

Signed-off-by: David Wosk <dwosk@us.ibm.com>

Author: dwosk

src/app/core.ts

@@ -17,8 +17,7 @@ import * as ConnectTypes from '@ibm-aspera/connect-sdk-js/dist/esm/core/types';
  * @returns a promise that resolves if server can connect or rejects if not
  */
 export const testConnection = (): Promise<any> => {
-  // FIXME: If force HTTP gateway is false this ends up preventing SDK from verifying IBM Aspera for desktop is running.
-  if (asperaSdk.useHttpGateway || asperaSdk.useConnect) {
+  if (asperaSdk.isReady || asperaSdk.useConnect) {
     return Promise.resolve(asperaSdk.globals.sdkResponseData);
   }
 
@@ -215,9 +214,10 @@ export const init = (options?: InitOptions): Promise<any> => {
  * Use {@link registerStatusCallback} to receive status updates. Use {@link getStatus} to
  * read the current status synchronously at any time.
  *
- * **Desktop path**: `INITIALIZING` → `RUNNING` (app detected) or `FAILED` (timeout).
- * Detection continues in the background after `FAILED`. If the user launches the app
- * later, the status transitions to `RUNNING`.
+ * **Desktop path**: `INITIALIZING` → `RUNNING` (app detected), `DEGRADED` (timeout but
+ * HTTP Gateway is available as a supplementary transport), or `FAILED` (timeout, no
+ * fallback). Detection continues in the background after `DEGRADED` or `FAILED` — if the
+ * user launches the app later, the status transitions to `RUNNING`.
  *
  * **Connect path**: `INITIALIZING` → `RUNNING`, `FAILED`, `OUTDATED`, or
  * `EXTENSION_INSTALL` depending on the state of the Connect browser extension
@@ -467,15 +467,43 @@ export const deregisterActivityCallback = (id: string): void => {
 };
 
 /**
- * Register a callback for getting updates about the connection status of IBM Aspera SDK.
- *
- * For example, to be notified of when the SDK loses connection with the application or connection
- * is re-established. This can be useful if you want to handle the case where the user quits IBM Aspera
- * after `init` has already been called, and want to prompt the user to relaunch the application.
+ * Register a callback for SDK lifecycle status changes. The callback fires immediately
+ * with the current status (if one exists) and again whenever the status changes.
+ *
+ * Status values:
+ *
+ * - `INITIALIZING` — The SDK is detecting a transfer client.
+ * - `RUNNING` — A transfer client is ready. Full functionality is available.
+ * - `DEGRADED` — The primary transfer client (IBM Aspera for desktop) was not detected, but HTTP
+ *   Gateway is available as a fallback. This is only available if XXX...
+ * - `FAILED` — No transfer client could be reached. This could be because the user does
+ *    not have a transfer client installed, it is not running, or in the case of HTTP Gateway,
+ *    it was not reachable.
+ * - `DISCONNECTED` — The transfer client was previously running but lost connection. This is specific
+ *    to IBM Aspera for desktop. For example, if the user quits the app this status will trigger.
+ * - `OUTDATED` — (Connect only) The Connect installation needs updating.
+ * - `EXTENSION_INSTALL` — (Connect only) The browser extension needs to be installed.
+ *
+ * For IBM Aspera for desktop, detection continues in the background after `FAILED` or `DEGRADED`.
+ * If the user launches the application later, the status transitions to `RUNNING`.
  *
  * @param callback callback function to receive status events
  *
  * @returns ID representing the callback for deregistration purposes
+ *
+ * @example
+ * const id = registerStatusCallback(status => {
+ *   if (status === 'RUNNING') {
+ *     // Full functionality — enable all UI
+ *   } else if (status === 'DEGRADED') {
+ *     // Transfers work via HTTP Gateway
+ *   } else if (status === 'FAILED') {
+ *     // Nothing available — prompt user to install
+ *   }
+ * });
+ *
+ * // Later, to stop listening:
+ * deregisterStatusCallback(id);
  */
 export const registerStatusCallback = (callback: (status: SdkStatus) => void): string => {
   return statusService.registerCallback(callback);

src/app/status.ts

@@ -1,5 +1,6 @@
 import {SdkStatus} from '../models/models';
 import {randomUUID} from '../helpers/helpers';
+import {asperaSdk} from '../index';
 
 type StatusCallback = (status: SdkStatus) => void;
 
@@ -14,10 +15,22 @@ class StatusService {
   }
 
   setStatus(status: SdkStatus): void {
+    // When Desktop disconnects, remap to DEGRADED if HTTP Gateway is available
+    if (status === 'DISCONNECTED' && asperaSdk.httpGatewayIsReady) {
+      status = 'DEGRADED';
+    }
+
     if (this.currentStatus === status) {
       return;
     }
 
+    // Manage Desktop verification state based on status transitions
+    if (status === 'DISCONNECTED' || status === 'DEGRADED') {
+      asperaSdk.globals.asperaAppVerified = false;
+    } else if (status === 'RUNNING' && (this.currentStatus === 'DISCONNECTED' || this.currentStatus === 'DEGRADED')) {
+      asperaSdk.globals.asperaAppVerified = true;
+    }
+
     this.currentStatus = status;
     this.callbacks.forEach(cb => cb(status));
   }
@@ -40,15 +53,19 @@ class StatusService {
    *
    * @param detectFn async function that resolves if Desktop is found, rejects if not
    * @param interval ms between attempts
-   * @param failTimeout ms before transitioning to FAILED
+   * @param failTimeout ms before transitioning to FAILED or DEGRADED
    */
   startPolling(detectFn: () => Promise<void>, interval: number, failTimeout: number): void {
     this.stopPolling();
     this.setStatus('INITIALIZING');
 
     this.failTimeoutId = setTimeout(() => {
       if (this.currentStatus !== 'RUNNING') {
-        this.setStatus('FAILED');
+        if (asperaSdk.httpGatewayIsReady) {
+          this.setStatus('DEGRADED');
+        } else {
+          this.setStatus('FAILED');
+        }
       }
     }, failTimeout);
 

src/models/models.ts

@@ -739,6 +739,7 @@ export type SdkStatus =
   | 'INITIALIZING'
   | 'RETRYING'
   | 'RUNNING'
+  | 'DEGRADED'
   | 'FAILED'
   | 'OUTDATED'
   | 'EXTENSION_INSTALL'

tests/status.spec.ts

@@ -1,9 +1,12 @@
 import {statusService} from '../src/app/status';
 import {SdkStatus} from '../src/models/models';
+import {asperaSdk} from '../src/index';
 
 describe('StatusService', () => {
   afterEach(() => {
     statusService.reset();
+    asperaSdk.globals.httpGatewayVerified = false;
+    asperaSdk.globals.asperaAppVerified = false;
     jest.useRealTimers();
   });
 
@@ -47,6 +50,69 @@ describe('StatusService', () => {
 
       expect(cb).toHaveBeenCalledWith('DISCONNECTED');
     });
+
+    test('remaps DISCONNECTED to DEGRADED when HTTP Gateway is ready', () => {
+      asperaSdk.globals.httpGatewayVerified = true;
+      statusService.setStatus('RUNNING');
+
+      statusService.setStatus('DISCONNECTED');
+
+      expect(statusService.getStatus()).toBe('DEGRADED');
+    });
+
+    test('keeps DISCONNECTED when HTTP Gateway is not ready', () => {
+      statusService.setStatus('RUNNING');
+
+      statusService.setStatus('DISCONNECTED');
+
+      expect(statusService.getStatus()).toBe('DISCONNECTED');
+    });
+
+    test('resets asperaAppVerified on DISCONNECTED', () => {
+      asperaSdk.globals.asperaAppVerified = true;
+      statusService.setStatus('RUNNING');
+
+      statusService.setStatus('DISCONNECTED');
+
+      expect(asperaSdk.globals.asperaAppVerified).toBe(false);
+    });
+
+    test('resets asperaAppVerified on DEGRADED', () => {
+      asperaSdk.globals.asperaAppVerified = true;
+      asperaSdk.globals.httpGatewayVerified = true;
+      statusService.setStatus('RUNNING');
+
+      statusService.setStatus('DISCONNECTED'); // remapped to DEGRADED
+
+      expect(asperaSdk.globals.asperaAppVerified).toBe(false);
+    });
+
+    test('restores asperaAppVerified when transitioning from DEGRADED to RUNNING', () => {
+      asperaSdk.globals.httpGatewayVerified = true;
+      statusService.setStatus('DEGRADED');
+      expect(asperaSdk.globals.asperaAppVerified).toBe(false);
+
+      statusService.setStatus('RUNNING');
+
+      expect(asperaSdk.globals.asperaAppVerified).toBe(true);
+    });
+
+    test('restores asperaAppVerified when transitioning from DISCONNECTED to RUNNING', () => {
+      statusService.setStatus('DISCONNECTED');
+      expect(asperaSdk.globals.asperaAppVerified).toBe(false);
+
+      statusService.setStatus('RUNNING');
+
+      expect(asperaSdk.globals.asperaAppVerified).toBe(true);
+    });
+
+    test('does not set asperaAppVerified when transitioning to RUNNING from other states', () => {
+      statusService.setStatus('INITIALIZING');
+
+      statusService.setStatus('RUNNING');
+
+      expect(asperaSdk.globals.asperaAppVerified).toBe(false);
+    });
   });
 
   describe('registerCallback', () => {
@@ -162,6 +228,65 @@ describe('StatusService', () => {
       expect(detectFn).toHaveBeenCalledTimes(1);
     });
 
+    test('transitions to DEGRADED when HTTP Gateway is ready', async () => {
+      jest.useFakeTimers();
+      asperaSdk.globals.httpGatewayVerified = true;
+
+      const detectFn = jest.fn().mockRejectedValue(new Error('not found'));
+      statusService.startPolling(detectFn, 2000, 5000);
+
+      jest.advanceTimersByTime(5000);
+      expect(statusService.getStatus()).toBe('DEGRADED');
+    });
+
+    test('transitions to FAILED when HTTP Gateway is not ready', async () => {
+      jest.useFakeTimers();
+
+      const detectFn = jest.fn().mockRejectedValue(new Error('not found'));
+      statusService.startPolling(detectFn, 2000, 5000);
+
+      jest.advanceTimersByTime(5000);
+      expect(statusService.getStatus()).toBe('FAILED');
+    });
+
+    test('transitions from DEGRADED to RUNNING when detectFn eventually resolves', async () => {
+      jest.useFakeTimers();
+      asperaSdk.globals.httpGatewayVerified = true;
+
+      let callCount = 0;
+      const detectFn = jest.fn().mockImplementation(() => {
+        callCount++;
+        if (callCount <= 3) {
+          return Promise.reject(new Error('not found'));
+        }
+        return Promise.resolve();
+      });
+
+      const statuses: SdkStatus[] = [];
+      statusService.registerCallback((s) => statuses.push(s));
+
+      statusService.startPolling(detectFn, 2000, 5000);
+
+      // First attempt fails
+      await Promise.resolve();
+      expect(statusService.getStatus()).toBe('INITIALIZING');
+
+      // Advance past timeout
+      jest.advanceTimersByTime(5000);
+      await Promise.resolve();
+      expect(statusService.getStatus()).toBe('DEGRADED');
+
+      // Next poll interval triggers attempt that succeeds
+      jest.advanceTimersByTime(2000);
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(statusService.getStatus()).toBe('RUNNING');
+      expect(statuses).toContain('INITIALIZING');
+      expect(statuses).toContain('DEGRADED');
+      expect(statuses).toContain('RUNNING');
+    });
+
     test('transitions from FAILED to RUNNING when detectFn eventually resolves', async () => {
       jest.useFakeTimers();