@forge/events 2.0.0 → 2.0.1-next.1

package/src/__test__/queue.test.ts

@@ -1,306 +0,0 @@
-import {
-  InternalServerError,
-  InvalidQueueNameError,
-  InvalidPayloadError,
-  NoEventsToPushError,
-  PartialSuccessError,
-  PayloadTooBigError,
-  RateLimitError,
-  TooManyEventsError,
-  InvalidPushSettingsError,
-  InvocationLimitReachedError
-} from '../errors';
-import { getMockFetchMethod, getApiClientMockWithoutResponseBody, verifyApiClientCalledPushPathWith } from './utils';
-import { Queue } from '../queue';
-import { JobProgress } from '../jobProgress';
-import { __requestAtlassianAsApp } from '@forge/api';
-
-jest.mock('@forge/api', () => ({
-  __requestAtlassianAsApp: getMockFetchMethod('done', 201)
-}));
-
-const getQueue = (queueName: string, apiClientMock?: any) => new Queue({ key: queueName }, apiClientMock);
-
-describe('Queue methods', () => {
-  describe('constructor', () => {
-    it('should throw InvalidQueueNameError', async () => {
-      const apiClientMock = getMockFetchMethod();
-      expect(() => getQueue('invalid name', apiClientMock)).toThrowError(
-        new InvalidQueueNameError('Queue names can only contain alphanumeric characters, dashes and underscores.')
-      );
-    });
-  });
-
-  const PAYLOAD = { body: { page: 1 } } as const;
-
-  describe('push', () => {
-    it.each([
-      ['single payload', PAYLOAD, [PAYLOAD]],
-      ['payload array', [PAYLOAD, PAYLOAD], [PAYLOAD, PAYLOAD]]
-    ])('should call the queue/publish endpoint when given %s', async (_, payload, expectedPayload) => {
-      const apiClientMock = getMockFetchMethod();
-      const queue = getQueue('name', apiClientMock);
-      await queue.push(payload);
-      verifyApiClientCalledPushPathWith(apiClientMock, expectedPayload, 'name');
-    });
-
-    it.each([
-      ['number', 1],
-      ['string', 'test'],
-      ['boolean', true],
-      ['array', [1, 2, 3]],
-      ['null', null],
-      ['undefined', undefined],
-      ['array with non-object', [1]],
-      ['array with an array', [[2, 3]]]
-    ])('rejects non-object (%s) event', async (_, payload) => {
-      const apiClientMock = getMockFetchMethod();
-      const queue = getQueue('name', apiClientMock);
-      // @ts-expect-error Testing invalid payload type on purpose
-      await expect(queue.push(payload)).rejects.toThrow(new InvalidPayloadError(`Event must be an object.`));
-      expect(apiClientMock).toHaveBeenCalledTimes(0);
-    });
-
-    it.each([
-      ['number', 1],
-      ['string', 'test'],
-      ['boolean', true],
-      ['array', [1, 2, 3]],
-      ['null', null],
-      ['undefined', undefined],
-      ['array with non-object', [1]],
-      ['array with an array', [[2, 3]]]
-    ])('rejects non-object (%s) event body', async (_, body) => {
-      const apiClientMock = getMockFetchMethod();
-      const queue = getQueue('name', apiClientMock);
-      // @ts-expect-error Testing invalid payload type on purpose
-      await expect(queue.push({ body })).rejects.toThrow(new InvalidPayloadError(`Event body must be an object.`));
-      expect(apiClientMock).toHaveBeenCalledTimes(0);
-    });
-
-    it('should throw InvalidPushSettingsError for delay', async () => {
-      const apiClientMock = getMockFetchMethod();
-      const queue = getQueue('name', apiClientMock);
-      await expect(queue.push({ ...PAYLOAD, 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 = getMockFetchMethod();
-      const queue = getQueue('name', apiClientMock);
-      await expect(queue.push([])).rejects.toThrow(new NoEventsToPushError(`No events pushed.`));
-      expect(apiClientMock).toHaveBeenCalledTimes(0);
-    });
-
-    it('should throw TooManyEventsError', async () => {
-      const apiClientMock = getMockFetchMethod();
-      const queue = getQueue('name', apiClientMock);
-      await expect(queue.push(Array(51).fill(PAYLOAD))).rejects.toThrow(
-        new TooManyEventsError(`This push contains more than the 50 events allowed.`)
-      );
-      expect(apiClientMock).toHaveBeenCalledTimes(0);
-    });
-
-    it('should throw PayloadTooBigError', async () => {
-      const apiClientMock = getMockFetchMethod();
-      const queue = getQueue('name', apiClientMock);
-      await expect(queue.push({ body: { content: '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 = getMockFetchMethod({}, 429);
-      const queue = getQueue('name', apiClientMock);
-      await expect(queue.push(PAYLOAD)).rejects.toThrow(new RateLimitError(`Too many requests.`));
-      verifyApiClientCalledPushPathWith(apiClientMock, [PAYLOAD], 'name');
-    });
-
-    it('should throw InvocationLimitReachedError', async () => {
-      const apiClientMock = getMockFetchMethod({}, 405);
-      const queue = getQueue('name', apiClientMock);
-      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 = getMockFetchMethod(
-        {
-          failedEvents: [
-            {
-              index: '0',
-              errorMessage: 'failed-1'
-            },
-            {
-              index: 2,
-              errorMessage: 'failed-3'
-            }
-          ]
-        },
-        202
-      );
-      const queue = getQueue('name', apiClientMock);
-      const payload = [
-        {
-          body: {
-            content: 'payload-1'
-          }
-        },
-        {
-          body: {
-            content: 'payload-2'
-          }
-        },
-        {
-          body: {
-            content: 'payload-3'
-          }
-        }
-      ];
-      await expect(queue.push(payload)).rejects.toThrow(
-        new PartialSuccessError(`Failed to process 2 event(s).`, { jobId: 'some-job-id' }, [
-          {
-            errorMessage: 'failed-1',
-            event: {
-              body: {
-                content: 'payload-1'
-              }
-            }
-          },
-          {
-            errorMessage: 'failed-3',
-            event: {
-              body: {
-                content: 'payload-3'
-              }
-            }
-          }
-        ])
-      );
-      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
-    });
-
-    it('should throw PartialSuccessError when backend failed to create job stats', async () => {
-      const apiClientMock = getMockFetchMethod(
-        {
-          errorMessage: 'Failed to create stats for job name#12345'
-        },
-        202
-      );
-      const queue = getQueue('name', apiClientMock);
-      const payload = [
-        {
-          body: {
-            content: 'payload-1'
-          }
-        },
-        {
-          body: {
-            content: 'payload-2'
-          }
-        },
-        {
-          body: {
-            content: 'payload-3'
-          }
-        }
-      ];
-      await expect(queue.push(payload)).rejects.toThrow(
-        new PartialSuccessError(`Failed to create stats for job name#12345`, { jobId: 'some-job-id' }, [])
-      );
-      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
-    });
-
-    it('should throw PartialSuccessError when there are failed events and backend failed to create job stats', async () => {
-      const apiClientMock = getMockFetchMethod(
-        {
-          errorMessage: 'Failed to create stats for job name#12345',
-          failedEvents: [
-            {
-              index: '0',
-              errorMessage: 'failed-1'
-            }
-          ]
-        },
-        202
-      );
-      const queue = getQueue('name', apiClientMock);
-      const payload = [
-        {
-          body: {
-            content: 'payload-1'
-          }
-        },
-        {
-          body: {
-            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`,
-          { jobId: 'some-job-id' },
-          [
-            {
-              errorMessage: 'failed-1',
-              event: {
-                body: {
-                  content: 'payload-1'
-                }
-              }
-            }
-          ]
-        )
-      );
-      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
-    });
-
-    it('should throw InternalServerError', async () => {
-      const apiClientMock = getMockFetchMethod(
-        {
-          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('name', apiClientMock);
-      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('name', apiClientMock);
-      await expect(queue.push(PAYLOAD)).rejects.toThrow(new InternalServerError(`504 Gateway Timeout`, 504));
-      verifyApiClientCalledPushPathWith(apiClientMock, [PAYLOAD], 'name');
-    });
-
-    it('requests stargate if no api client is provided', async () => {
-      const queue = getQueue('queue');
-      await queue.push({ body: { test: 'stargate' } });
-      expect(__requestAtlassianAsApp).toHaveBeenCalledTimes(1);
-    });
-  });
-
-  describe('getJob', () => {
-    it('should create a JobProgress by jobId', async () => {
-      const apiClientMock = getMockFetchMethod();
-      const queue = getQueue('name', apiClientMock);
-      const jobProgress = queue.getJob('test-job-id');
-      expect(jobProgress).toEqual(new JobProgress({ key: 'name' }, 'test-job-id', apiClientMock));
-    });
-  });
-});

package/src/__test__/queueResponse.test.ts

@@ -1,14 +0,0 @@
-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

@@ -1,47 +0,0 @@
-import { Payload } from '../types';
-
-export const getMockFetchMethod = (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/{contextAri}/{environmentId}/{appId}/{appVersion}', {
-    queueName: name,
-    schema: 'ari:cloud:ecosystem::forge/app-event-2',
-    type: 'avi:forge:app:event',
-    payload: payloads
-  });
-};

package/src/appEvents.ts

@@ -1,107 +0,0 @@
-import { post } from './queries';
-import { __requestAtlassianAsApp } from '@forge/api';
-
-export interface AppEvent {
-  key: string;
-}
-
-export type AppEventPublishResult = AppEventPublishSuccess | AppEventPublishError;
-
-/**
- * Represents the successful result of the publishing operation.
- *
- * It may happen that publishing some of the events fails even though the request was generally successful.
- * Inspect the `failedEvents` field to see which events failed to be published and why
- * (if the list is empty then the operation was fully successful).
- */
-export type AppEventPublishSuccess = {
-  type: 'success';
-  /** A list of events that failed to be published along with error messages. */
-  failedEvents: AppEventPublishFailure[];
-};
-
-/**
- * A publishing failure of a specific event.
- */
-export interface AppEventPublishFailure {
-  event: AppEvent;
-  errorMessage: string;
-}
-
-/**
- * A general error of the event publishing operation.
- * No events were published if this is returned.
- */
-export interface AppEventPublishError {
-  type: 'error';
-  errorType: AppEventErrorType;
-  errorMessage: string;
-}
-
-export type AppEventErrorType =
-  | 'VALIDATION_ERROR'
-  | 'AUTHENTICATION_ERROR'
-  | 'AUTHORIZATION_ERROR'
-  | 'RATE_LIMIT'
-  | 'SERVICE_ERROR'
-  | 'SERVICE_UNAVAILABLE'
-  | `OTHER`;
-
-interface AppEventErrorResponse {
-  errorMessages: string[];
-  errors: Map<string, string>;
-}
-
-interface AppEventSuccessResponse {
-  failedEvents: AppEventPublishFailure[];
-}
-
-const errorTypes: Record<number, AppEventErrorType> = {
-  400: 'VALIDATION_ERROR',
-  401: 'AUTHENTICATION_ERROR',
-  403: 'AUTHORIZATION_ERROR',
-  429: 'RATE_LIMIT',
-  500: 'SERVICE_ERROR',
-  503: 'SERVICE_UNAVAILABLE'
-};
-
-const endpoint = '/forge/events/v1/app-events';
-
-export const appEvents = {
-  async publish(events: AppEvent | AppEvent[]): Promise<AppEventPublishResult> {
-    const eventsArray = Array.isArray(events) ? events : [events];
-    const body = {
-      events: eventsArray.map((e) => ({
-        key: e.key
-      }))
-    };
-
-    const response = await post(endpoint, body, __requestAtlassianAsApp);
-    const responseBody = await response.json();
-
-    if (!response.ok) {
-      return {
-        type: 'error',
-        errorType: errorTypes[response.status] ?? 'OTHER',
-        errorMessage: getErrorMessage(responseBody)
-      };
-    }
-
-    return {
-      type: 'success',
-      failedEvents: (responseBody as AppEventSuccessResponse).failedEvents ?? []
-    };
-  }
-};
-
-function getErrorMessage(responseBody: AppEventErrorResponse) {
-  if (responseBody.errorMessages && responseBody.errorMessages.length > 0) {
-    return responseBody.errorMessages.join(', ');
-  } else if (responseBody.errors) {
-    return Object.entries(responseBody.errors)
-      .map(([key, value]) => `${key}: ${value}`)
-      .join(', ');
-  } else {
-    return JSON.stringify(responseBody);
-  }
-}

package/src/errors.ts

@@ -1,46 +0,0 @@
-import { FailedEvent, PushResult } from './types';
-
-export class EventsError extends Error {
-  constructor(message: string) {
-    super(message);
-  }
-}
-
-export class InvalidPushSettingsError extends EventsError {}
-
-export class InvalidQueueNameError extends EventsError {}
-
-export class InvalidPayloadError extends EventsError {}
-
-export class TooManyEventsError extends EventsError {}
-
-export class PayloadTooBigError extends EventsError {}
-
-export class NoEventsToPushError extends EventsError {}
-
-export class RateLimitError extends EventsError {}
-
-export class PartialSuccessError extends EventsError {
-  constructor(
-    message: string,
-    public result: PushResult,
-    public failedEvents: FailedEvent[]
-  ) {
-    super(message);
-  }
-}
-
-export class InternalServerError extends EventsError {
-  constructor(message: string, errorCode?: number, details?: string) {
-    super(message);
-    this.errorCode = errorCode;
-    this.details = details;
-  }
-
-  errorCode?: number;
-  details?: string;
-}
-
-export class JobDoesNotExistError extends EventsError {}
-
-export class InvocationLimitReachedError extends EventsError {}

package/src/index.ts

@@ -1,28 +0,0 @@
-export { Queue } from './queue';
-export {
-  InvalidQueueNameError,
-  TooManyEventsError,
-  PayloadTooBigError,
-  NoEventsToPushError,
-  RateLimitError,
-  PartialSuccessError,
-  InternalServerError,
-  JobDoesNotExistError,
-  InvalidPushSettingsError,
-  InvocationLimitReachedError
-} from './errors';
-export { JobProgress, JobStats } from './jobProgress';
-export { QueueResponse } from './queueResponse';
-export { InvocationError } from './invocationError';
-export { InvocationErrorCode } from './invocationErrorCode';
-export { RetryOptions } from './retryOptions';
-export { AsyncEvent, PushEvent, PushResult } from './types';
-export {
-  appEvents,
-  AppEvent,
-  AppEventPublishResult,
-  AppEventPublishSuccess,
-  AppEventPublishFailure,
-  AppEventPublishError,
-  AppEventErrorType
-} from './appEvents';

package/src/invocationError.ts

@@ -1,22 +0,0 @@
-import { DEFAULT_RETRY_OPTIONS, MIN_RETRY_AFTER, RetryOptions } from './retryOptions';
-import { Response } from './queueResponse';
-
-export class InvocationError extends Response {
-  constructor(public retryOptions: RetryOptions = DEFAULT_RETRY_OPTIONS) {
-    super(true);
-    if (this.retryOptions.retryAfter !== undefined && this.retryOptions.retryAfter <= 0) {
-      this.retryOptions.retryAfter = MIN_RETRY_AFTER;
-    }
-    return this.toJSON() as unknown as InvocationError;
-  }
-
-  /***
-   * Function to convert class object to JSON object so that app function return this as part of lambda invocation.
-   */
-  public toJSON(): { _retry: boolean; retryOptions: RetryOptions } {
-    return {
-      _retry: this._retry,
-      retryOptions: this.retryOptions
-    };
-  }
-}

package/src/invocationErrorCode.ts

@@ -1,8 +0,0 @@
-export enum InvocationErrorCode {
-  FUNCTION_OUT_OF_MEMORY = 'FUNCTION_OUT_OF_MEMORY',
-  FUNCTION_TIME_OUT = 'FUNCTION_TIME_OUT',
-  FUNCTION_PLATFORM_UNKNOWN_ERROR = 'FUNCTION_PLATFORM_UNKNOWN_ERROR',
-  FUNCTION_PLATFORM_RATE_LIMITED = 'FUNCTION_PLATFORM_RATE_LIMITED',
-  FUNCTION_UPSTREAM_RATE_LIMITED = 'FUNCTION_UPSTREAM_RATE_LIMITED',
-  FUNCTION_RETRY_REQUEST = 'FUNCTION_RETRY_REQUEST'
-}

package/src/jobProgress.ts

@@ -1,51 +0,0 @@
-import { __requestAtlassianAsApp, FetchMethod } from '@forge/api';
-import { CANCEL_JOB_PATH, GET_STATS_PATH, post } from './queries';
-import {
-  validateCancelJobAPIResponse,
-  validateCancelJobRequest,
-  validateGetStatsAPIResponse,
-  validateGetStatsPayload
-} from './validators';
-import { CancelJobRequest, GetStatsRequest, QueueParams } from './types';
-
-export type JobStats = {
-  success: number;
-  inProgress: number;
-  failed: number;
-};
-
-export class JobProgress {
-  constructor(
-    private readonly queueParams: QueueParams,
-    private readonly id: string,
-    private readonly apiClient: FetchMethod = __requestAtlassianAsApp
-  ) {}
-
-  async getStats(): Promise<JobStats> {
-    const getStatsRequest: GetStatsRequest = {
-      queueName: this.queueParams.key,
-      jobId: this.id,
-      time: new Date().toISOString()
-    };
-
-    validateGetStatsPayload(getStatsRequest);
-
-    const response = await post(GET_STATS_PATH, getStatsRequest, this.apiClient);
-    await validateGetStatsAPIResponse(response, getStatsRequest);
-    const { success, inProgress, failed } = await response.json();
-    return { success, inProgress, failed };
-  }
-
-  async cancel(): Promise<void> {
-    const cancelJobRequest: CancelJobRequest = {
-      queueName: this.queueParams.key,
-      jobId: this.id,
-      time: new Date().toISOString()
-    };
-
-    validateCancelJobRequest(cancelJobRequest);
-
-    const response = await post(CANCEL_JOB_PATH, cancelJobRequest, this.apiClient);
-    await validateCancelJobAPIResponse(response, cancelJobRequest);
-  }
-}

package/src/queries.ts

@@ -1,17 +0,0 @@
-import { APIResponse, FetchMethod } from '@forge/api';
-
-export const PUSH_PATH = '/webhook/queue/publish/{contextAri}/{environmentId}/{appId}/{appVersion}';
-export const GET_STATS_PATH = '/webhook/queue/stats/{contextAri}/{environmentId}/{appId}/{appVersion}';
-export const CANCEL_JOB_PATH = '/webhook/queue/cancel/{contextAri}/{environmentId}/{appId}/{appVersion}';
-
-export const post = async (endpoint: string, body: unknown, 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,39 +0,0 @@
-import { FetchMethod, __requestAtlassianAsApp } from '@forge/api';
-import { PUSH_PATH, post } from './queries';
-import { validatePushAPIResponse, validatePushEvents, validateQueueKey } from './validators';
-import { QueueParams, PushEvent, PushRequest, PushResult } from './types';
-import { v4 as uuid } from 'uuid';
-import { JobProgress } from './jobProgress';
-
-export class Queue {
-  constructor(
-    private readonly queueParams: QueueParams,
-    private readonly apiClient: FetchMethod = __requestAtlassianAsApp
-  ) {
-    validateQueueKey(this.queueParams.key);
-  }
-
-  async push(events: PushEvent | PushEvent[]): Promise<PushResult> {
-    const validEvents = validatePushEvents(events);
-    const queueName = this.queueParams.key;
-    const jobId = uuid();
-
-    const pushRequest: PushRequest = {
-      queueName: queueName,
-      jobId: jobId,
-      type: 'avi:forge:app:event',
-      schema: 'ari:cloud:ecosystem::forge/app-event-2',
-      payload: validEvents,
-      time: new Date().toISOString()
-    };
-
-    const response = await post(PUSH_PATH, pushRequest, this.apiClient);
-    const result = { jobId };
-    await validatePushAPIResponse(pushRequest, response, result);
-    return result;
-  }
-
-  getJob(jobId: string): JobProgress {
-    return new JobProgress(this.queueParams, jobId, this.apiClient);
-  }
-}