Async events API

This API enables Forge apps to push events and execute them asynchronously in the background.

Get started

To import the Forge events package and instantiate the queue in your app, run:

1
2
import { Queue } from '@forge/events';

const queue = new Queue({ key: 'queue-name' });

Push API

Pushes events to the queue to be processed later. The events processing can be delayed up to 15 minutes using the delayInSeconds setting. A maximum of 50 events can be pushed per request, up to a maximum combined payload of 200kb.

Method signature

1
2
type Payload = string | number | boolean | { [key: string]: Payload };
type PushSettings = { delayInSeconds: number }

/**
 * @returns Id of the job created
 * */
await queue.push(Payload | Payload[], PushSettings)

Example

To push event(s) to the queue:

1
2
// Push a single event with string payload
await queue.push('hello world');

// Push a single event with JSON payload
await queue.push({ "hello": "world" });

// Push multiple events to the queue
await queue.push(["hello", "world"]);

// Delay the processing of the event by 5 seconds
await queue.push("hello world", {
	delayInSeconds: 5
})

Event consumer

To create an event consumer module in the app manifest, use:

1
2
modules:
  consumer:
    - key: queue-consumer
      # Name of the queue for which this consumer will be invoked
      queue: queue-name
      resolver:
        function: consumer-function
        # resolver function to be called with payload
        method: event-listener
  function:
    - key: consumer-function
      handler: consumer.handler

To create the resolver for the consumer module, use:

1
2
import Resolver from "@forge/resolver";
const resolver = new Resolver();

resolver.define("event-listener", async ({ payload, context }) => {
	// process the event
});

export const handler = resolver.getDefinitions();

Tracking progress of events

When you push events to the queue, a new job is created. This job’s id is returned from the push API. To get the job’s stats using the id, use:

1
2
// Get the job ID
const jobId = await queue.push(['event1', 'event2']);

// Get the JobProgress object
const jobProgress = queue.getJob(jobId);

// Get stats of a particular job
const response = await jobProgress.getStats();
const {success, inProgress, failed} = await response.json();

Job ID is also accessible via the context parameter of your resolver function:

1
2
resolver.define("event-listener", async ({ payload, context }) => {
  // Get the JobProgress object
  const jobProgress = queue.getJob(context.jobId);
});

Cancel a job in progress

You can cancel a job that’s in progress using its JobProgress instance. When a job is canceled, events of that job are no longer processed.

1
2
resolver.define("event-listener", async ({ payload, context }) => {
  // Get the JobProgress object
  const jobProgress = queue.getJob(context.jobId);

  try {
    // process the event
  } catch (error) {
    // You can cancel the job when an error happens
    await jobProgress.cancel()
  }
});

Retry events

You can retry events to handle app errors. Doing so does not create a new job. To create the retry response through the QueueResponse API, use:

1
2
import { QueueResponse } from "@forge/events"

resolver.define("import-builds", async () => {
  const res = new QueueResponse();
  try {
      // App logic
    } catch(error) {
        // update response to event retry
        res.retry();
    }
  return res;
});