@forge/events 0.0.0-experimental-e05f7a2 → 0.0.0-experimental-64caa5a

package/src/__test__/queue.test.ts

@@ -0,0 +1,236 @@
+import {
+  InternalServerError,
+  InvalidQueueNameError,
+  NoEventsToPushError,
+  PartialSuccessError,
+  PayloadTooBigError,
+  RateLimitError,
+  TooManyEventsError,
+  InvalidPushSettingsError,
+  InvocationLimitReachedError
+} from '../errors';
+import { getApiClientMock, getApiClientMockWithoutResponseBody, verifyApiClientCalledPushPathWith } from './utils';
+import { Queue } from '../queue';
+import { JobProgress } from '../jobProgress';
+
+const getQueue = (apiClientMock: any, queueName: string) => new Queue({ key: queueName }, apiClientMock);
+
+describe('Queue methods', () => {
+  describe('constructor', () => {
+    it('should throw InvalidQueueNameError', async () => {
+      const apiClientMock = getApiClientMock();
+      expect(() => getQueue(apiClientMock, 'invalid name')).toThrowError(
+        new InvalidQueueNameError('Queue names can only contain alphanumeric characters, dashes and underscores.')
+      );
+    });
+  });
+
+  describe('push', () => {
+    it('should call the queue/publish endpoint', async () => {
+      const apiClientMock = getApiClientMock();
+      const queue = getQueue(apiClientMock, 'name');
+      const payload = {
+        page: 1
+      };
+      await queue.push([payload]);
+      verifyApiClientCalledPushPathWith(apiClientMock, [payload], 'name');
+    });
+
+    it('should throw InvalidPushSettingsError for delay', async () => {
+      const apiClientMock = getApiClientMock();
+      const queue = getQueue(apiClientMock, 'name');
+      await expect(queue.push(1, { delayInSeconds: 901 })).rejects.toThrow(
+        new InvalidPushSettingsError(`The delayInSeconds setting must be between 0 and 900.`)
+      );
+      expect(apiClientMock).toHaveBeenCalledTimes(0);
+    });
+
+    it('should throw NoEventsToPushError', async () => {
+      const apiClientMock = getApiClientMock();
+      const queue = getQueue(apiClientMock, 'name');
+      await expect(queue.push([])).rejects.toThrow(new NoEventsToPushError(`No events pushed.`));
+      expect(apiClientMock).toHaveBeenCalledTimes(0);
+    });
+
+    it('should throw TooManyEventsError', async () => {
+      const apiClientMock = getApiClientMock();
+      const queue = getQueue(apiClientMock, 'name');
+      await expect(queue.push([...Array(51).keys()])).rejects.toThrow(
+        new TooManyEventsError(`This push contains more than the 50 events allowed.`)
+      );
+      expect(apiClientMock).toHaveBeenCalledTimes(0);
+    });
+
+    it('should throw PayloadTooBigError', async () => {
+      const apiClientMock = getApiClientMock();
+      const queue = getQueue(apiClientMock, 'name');
+      await expect(queue.push('x'.repeat(201 * 1024))).rejects.toThrow(
+        new PayloadTooBigError(`The maximum payload size is 200KB.`)
+      );
+      expect(apiClientMock).toHaveBeenCalledTimes(0);
+    });
+
+    it('should throw RateLimitError', async () => {
+      const apiClientMock = getApiClientMock({}, 429);
+      const queue = getQueue(apiClientMock, 'name');
+      const payload = [...Array(10).keys()];
+      await expect(queue.push(payload)).rejects.toThrow(new RateLimitError(`Too many requests.`));
+      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+    });
+
+    it('should throw InvocationLimitReachedError', async () => {
+      const apiClientMock = getApiClientMock({}, 405);
+      const queue = getQueue(apiClientMock, 'name');
+      const payload = [...Array(5).keys()];
+      await expect(queue.push(payload)).rejects.toThrow(
+        new InvocationLimitReachedError(`The limit on cyclic invocation has been reached.`)
+      );
+      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+    });
+
+    it('should throw PartialSuccessError when there are failed events', async () => {
+      const apiClientMock = getApiClientMock(
+        {
+          failedEvents: [
+            {
+              index: '0',
+              errorMessage: 'failed-1'
+            },
+            {
+              index: 2,
+              errorMessage: 'failed-3'
+            }
+          ]
+        },
+        202
+      );
+      const queue = getQueue(apiClientMock, 'name');
+      const payload = [
+        {
+          content: 'payload-1'
+        },
+        {
+          content: 'payload-2'
+        },
+        {
+          content: 'payload-3'
+        }
+      ];
+      await expect(queue.push(payload)).rejects.toThrow(
+        new PartialSuccessError(`Failed to process 2 event(s).`, [
+          {
+            errorMessage: 'failed-1',
+            payload: {
+              content: 'payload-1'
+            }
+          },
+          {
+            errorMessage: 'failed-3',
+            payload: {
+              content: 'payload-3'
+            }
+          }
+        ])
+      );
+      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+    });
+
+    it('should throw PartialSuccessError when backend failed to create job stats', async () => {
+      const apiClientMock = getApiClientMock(
+        {
+          errorMessage: 'Failed to create stats for job name#12345'
+        },
+        202
+      );
+      const queue = getQueue(apiClientMock, 'name');
+      const payload = [
+        {
+          content: 'payload-1'
+        },
+        {
+          content: 'payload-2'
+        },
+        {
+          content: 'payload-3'
+        }
+      ];
+      await expect(queue.push(payload)).rejects.toThrow(
+        new PartialSuccessError(`Failed to create stats for job name#12345`, [])
+      );
+      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+    });
+
+    it('should throw PartialSuccessError when there are failed events and backend failed to create job stats', async () => {
+      const apiClientMock = getApiClientMock(
+        {
+          errorMessage: 'Failed to create stats for job name#12345',
+          failedEvents: [
+            {
+              index: '0',
+              errorMessage: 'failed-1'
+            }
+          ]
+        },
+        202
+      );
+      const queue = getQueue(apiClientMock, 'name');
+      const payload = [
+        {
+          content: 'payload-1'
+        },
+        {
+          content: 'payload-2'
+        }
+      ];
+      await expect(queue.push(payload)).rejects.toThrow(
+        new PartialSuccessError(`Failed to process 1 event(s). Failed to create stats for job name#12345`, [
+          {
+            errorMessage: 'failed-1',
+            payload: {
+              content: 'payload-1'
+            }
+          }
+        ])
+      );
+      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+    });
+
+    it('should throw InternalServerError', async () => {
+      const apiClientMock = getApiClientMock(
+        {
+          message: 'AWS SQS timed out',
+          code: 500,
+          details: 'The request processing has failed because of an unknown error, exception or failure'
+        },
+        500
+      );
+      const queue = getQueue(apiClientMock, 'name');
+      const payload = [...Array(9).keys()];
+      await expect(queue.push(payload)).rejects.toThrow(
+        new InternalServerError(
+          `500 Status Text: AWS SQS timed out`,
+          500,
+          'The request processing has failed because of an unknown error, exception or failure'
+        )
+      );
+      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+    });
+
+    it('should throw InternalServerError for error response without response body', async () => {
+      const apiClientMock = getApiClientMockWithoutResponseBody(504, 'Gateway Timeout');
+      const queue = getQueue(apiClientMock, 'name');
+      const payload = [1];
+      await expect(queue.push(1)).rejects.toThrow(new InternalServerError(`504 Gateway Timeout`, 504));
+      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+    });
+  });
+
+  describe('getJob', () => {
+    it('should create a JobProgress by jobId', async () => {
+      const apiClientMock = getApiClientMock();
+      const queue = getQueue(apiClientMock, 'name');
+      const jobProgress = queue.getJob('test-job-id');
+      expect(jobProgress).toEqual(new JobProgress('test-job-id', apiClientMock));
+    });
+  });
+});

package/src/__test__/queueResponse.test.ts

@@ -0,0 +1,14 @@
+import { QueueResponse } from '../queueResponse';
+
+describe('QueueResponse', () => {
+  it('should contain property retry=false by default', async () => {
+    const res = new QueueResponse();
+    expect(JSON.stringify(res)).toEqual('{"_retry":false}');
+  });
+
+  it('doRetry() should change property retry=true', async () => {
+    const res = new QueueResponse();
+    res.retry();
+    expect(JSON.stringify(res)).toEqual('{"_retry":true}');
+  });
+});

package/src/__test__/utils.ts

@@ -0,0 +1,47 @@
+import { Payload } from '../types';
+
+export const getApiClientMock = (response?: any, statusCode = 201) => {
+  return jest.fn().mockReturnValue({
+    created: statusCode === 201,
+    status: statusCode,
+    statusText: 'Status Text',
+    json: jest.fn().mockResolvedValue(response)
+  });
+};
+
+export const getApiClientMockWithoutResponseBody = (statusCode: number, statusText: string) => {
+  return jest.fn().mockReturnValue({
+    ok: statusCode === 200,
+    status: statusCode,
+    statusText: statusText
+  });
+};
+
+export const verifyApiClientCalledWith = (apiClientMock: jest.Mock, path: string, expectedBody: any) => {
+  expect(apiClientMock).toHaveBeenCalledWith(
+    path,
+    expect.objectContaining({
+      method: 'POST',
+      body: expect.any(String),
+      headers: {
+        'content-type': 'application/json'
+      }
+    })
+  );
+
+  const [, { body }] = apiClientMock.mock.calls[0];
+  expect(JSON.parse(body)).toEqual(expect.objectContaining(expectedBody));
+};
+
+export const verifyApiClientCalledPushPathWith = (
+  apiClientMock: jest.Mock,
+  payloads: Payload | Payload[],
+  name: string
+) => {
+  verifyApiClientCalledWith(apiClientMock, '/webhook/queue/publish/{cloudId}/{environmentId}/{appId}/{appVersion}', {
+    queueName: name,
+    schema: 'ari:cloud:ecosystem::forge/app-event',
+    type: 'avi:forge:app:event',
+    payload: payloads
+  });
+};

package/src/errors.ts

@@ -1,5 +1,11 @@
 import { FailedEvent } from './types';
 
+export class InvalidPushSettingsError extends Error {
+  constructor(message: string) {
+    super(message);
+  }
+}
+
 export class InvalidQueueNameError extends Error {
   constructor(message: string) {
     super(message);
@@ -49,3 +55,15 @@ export class InternalServerError extends Error {
   errorCode?: number;
   details?: string;
 }
+
+export class JobDoesNotExistError extends Error {
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export class InvocationLimitReachedError extends Error {
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/index.ts

@@ -1 +1,15 @@
 export { Queue } from './queue';
+export {
+  InvalidQueueNameError,
+  TooManyEventsError,
+  PayloadTooBigError,
+  NoEventsToPushError,
+  RateLimitError,
+  PartialSuccessError,
+  InternalServerError,
+  JobDoesNotExistError,
+  InvalidPushSettingsError,
+  InvocationLimitReachedError
+} from './errors';
+export { JobProgress } from './jobProgress';
+export { QueueResponse } from './queueResponse';

package/src/jobProgress.ts

@@ -0,0 +1,48 @@
+import { CANCEL_JOB_PATH, GET_STATS_PATH, post } from './queries';
+import {
+  validateCancelJobAPIResponse,
+  validateCancelJobRequest,
+  validateGetStatsAPIResponse,
+  validateGetStatsPayload
+} from './validators';
+import { APIResponse, CancelJobRequest, FetchMethod, GetStatsRequest } from './types';
+
+export class JobProgress {
+  private readonly apiClient: FetchMethod;
+  private id: string;
+
+  constructor(id: string, apiClient?: FetchMethod) {
+    this.id = id;
+    this.apiClient = apiClient || (global as any).api.asApp().__requestAtlassian;
+  }
+
+  async getStats(): Promise<APIResponse> {
+    const [queueName, jobId] = this.id.split('#');
+    const getStatsRequest: GetStatsRequest = {
+      queueName: queueName,
+      jobId: jobId,
+      time: new Date().toISOString()
+    };
+
+    validateGetStatsPayload(getStatsRequest);
+
+    const response = await post(GET_STATS_PATH, getStatsRequest, this.apiClient);
+    await validateGetStatsAPIResponse(response, getStatsRequest);
+    return response;
+  }
+
+  async cancel(): Promise<APIResponse> {
+    const [queueName, jobId] = this.id.split('#');
+    const cancelJobRequest: CancelJobRequest = {
+      queueName: queueName,
+      jobId: jobId,
+      time: new Date().toISOString()
+    };
+
+    validateCancelJobRequest(cancelJobRequest);
+
+    const response = await post(CANCEL_JOB_PATH, cancelJobRequest, this.apiClient);
+    await validateCancelJobAPIResponse(response, cancelJobRequest);
+    return response;
+  }
+}

package/src/queries.ts

@@ -1,11 +1,17 @@
-import { PushBodyParams, APIRequest } from './types';
-
-export const getPushBody = (params: PushBodyParams): APIRequest => ({
-  queueName: params.queueName,
-  type: params.type,
-  schema: params.schema,
-  payload: params.payload,
-  time: new Date().toISOString()
-});
+import { APIRequest, APIResponse, FetchMethod } from './types';
 
 export const PUSH_PATH = '/webhook/queue/publish/{cloudId}/{environmentId}/{appId}/{appVersion}';
+export const GET_STATS_PATH = '/webhook/queue/stats/{cloudId}/{environmentId}/{appId}/{appVersion}';
+export const CANCEL_JOB_PATH = '/webhook/queue/cancel/{cloudId}/{environmentId}/{appId}/{appVersion}';
+
+export const post = async (endpoint: string, body: APIRequest, apiClient: FetchMethod): Promise<APIResponse> => {
+  const request = {
+    method: 'POST',
+    body: JSON.stringify(body),
+    headers: {
+      'content-type': 'application/json'
+    }
+  };
+
+  return await apiClient(endpoint, request);
+};

package/src/queue.ts

@@ -1,47 +1,46 @@
-import { getPushBody, PUSH_PATH } from './queries';
-import { validateAPIResponse, validatePayloads, validateQueueName } from './validators';
-import { APIResponse, FetchMethod, Payload, PushBodyParams, QueueParams, APIRequest } from './types';
-
-async function getResponseBody(response: APIResponse, body: any): Promise<APIResponse> {
-  await validateAPIResponse(response, body);
-  return response;
-}
+import { PUSH_PATH, post } from './queries';
+import { validatePushAPIResponse, validatePushPayloads, validateQueueKey, validatePushSettings } from './validators';
+import { FetchMethod, Payload, QueueParams, PushSettings, PushRequest } from './types';
+import uuid from 'uuid/v4';
+import { JobProgress } from './jobProgress';
 
 export class Queue {
   private readonly apiClient: FetchMethod;
   private queueParams: QueueParams;
 
   constructor(queueParams: QueueParams, apiClient?: FetchMethod) {
-    validateQueueName(queueParams.queueName);
+    validateQueueKey(queueParams.key);
     this.queueParams = queueParams;
     this.apiClient = apiClient || (global as any).api.asApp().__requestAtlassian;
   }
 
-  async push(payloads: Payload | Payload[]): Promise<APIResponse> {
-    validatePayloads(payloads);
+  async push(payloads: Payload | Payload[], pushSettings?: PushSettings): Promise<string> {
+    validatePushPayloads(payloads);
+    const queueName = this.queueParams.key;
+    const jobId = uuid();
 
-    const queryParams: PushBodyParams = {
-      payload: Array.isArray(payloads) ? payloads : [payloads],
-      queueName: this.queueParams.queueName,
+    const pushRequest: PushRequest = {
+      queueName: queueName,
+      jobId: jobId,
+      type: 'avi:forge:app:event',
       schema: 'ari:cloud:ecosystem::forge/app-event',
-      type: 'avi:forge:app:event'
+      payload: Array.isArray(payloads) ? payloads : [payloads],
+      time: new Date().toISOString()
     };
-    const requestBody = getPushBody(queryParams);
-    return this.query(PUSH_PATH, requestBody);
-  }
 
-  private async query(endpoint: string, body: APIRequest): Promise<APIResponse> {
-    const response = await this.apiClient(endpoint, this.buildRequest(body));
-    return await getResponseBody(response, body);
+    if (pushSettings) {
+      validatePushSettings(pushSettings);
+      if (pushSettings.delayInSeconds) {
+        pushRequest.delayInSeconds = pushSettings.delayInSeconds;
+      }
+    }
+
+    const response = await post(PUSH_PATH, pushRequest, this.apiClient);
+    await validatePushAPIResponse(response, pushRequest);
+    return `${queueName}#${jobId}`;
   }
 
-  private buildRequest(requestBody: APIRequest) {
-    return {
-      method: 'POST',
-      body: JSON.stringify(requestBody),
-      headers: {
-        'content-type': 'application/json'
-      }
-    };
+  getJob(jobId: string): JobProgress {
+    return new JobProgress(jobId, this.apiClient);
   }
 }

package/src/queueResponse.ts

@@ -0,0 +1,7 @@
+export class QueueResponse {
+  protected _retry = false;
+
+  retry(): void {
+    this._retry = true;
+  }
+}

package/src/text.ts

@@ -0,0 +1,15 @@
+export const Text = {
+  error: {
+    invalidQueueName: `Queue names can only contain alphanumeric characters, dashes and underscores.`,
+    invalidDelayInSecondsSetting: `The delayInSeconds setting must be between 0 and 900.`,
+    maxEventsAllowed: (maxEventsCount: number): string =>
+      `This push contains more than the ${maxEventsCount} events allowed.`,
+    maxPayloadAllowed: (maxPayloadSize: number): string => `The maximum payload size is ${maxPayloadSize}KB.`,
+    noEventsPushed: `No events pushed.`,
+    rateLimitError: `Too many requests.`,
+    invocationLimitReachedError: `The limit on cyclic invocation has been reached.`,
+    jobIdEmpty: `jobId cannot be empty.`,
+    jobDoesNotExit: (jobId: string, queueName: string): string =>
+      `The job ${jobId} was not found for the queue ${queueName}.`
+  }
+};

package/src/types.ts

@@ -4,18 +4,23 @@ export type APIResponse = Pick<Response, 'json' | 'text' | 'arrayBuffer' | 'ok'
 export type FetchMethod = (url: string, init: RequestInit) => Promise<APIResponse>;
 export type Payload = string | number | boolean | { [key: string]: Payload };
 
+export interface PushSettings {
+  delayInSeconds: number;
+}
 export interface QueueParams {
-  queueName: string;
+  key: string;
 }
 
-export interface PushBodyParams {
+export interface PushRequest extends APIRequest {
   payload: Payload[];
-  queueName: string;
   schema: string;
   type: string;
+  delayInSeconds?: number;
 }
 
-export interface APIRequest extends PushBodyParams {
+export interface APIRequest {
+  queueName: string;
+  jobId: string;
   time: string;
 }
 
@@ -23,3 +28,6 @@ export interface FailedEvent {
   errorMessage: string;
   payload: Payload;
 }
+
+export type GetStatsRequest = APIRequest;
+export type CancelJobRequest = APIRequest;