Object Store (EAP)

 

The Forge Object Store is a hosted storage solution designed to manage large items such as substantial data objects or media files. It provides you with a seamless way to store, retrieve, and manage objects directly from your Forge apps. Unlike our existing storage solutions, the Object Store is optimized for efficient handling of large files. Object Store integrates tightly with the Forge platform, enabling secure and reliable data management. This document will guide you through its key features, limitations, and usage for the Early Access Program (EAP).

Limitations

The Forge Object Store has the following limitations during the EAP:

• Storage limits: Objects can be up to 50 MB each, with a total storage cap of 1 GB across all objects.

• Time-to-Live (TTL): Objects have a default TTL of 90 days. Custom TTLs can be set but must be greater than 1 second and can't exceed 90 days. This limitation will only be in effect for the EAP.

  All objects will be deleted at the end of the EAP. Atlassian will provide notice before the end of the EAP to ensure you have time to download any stored data.

• Rate limits: Combined read and write operations are limited to 50 MB per minute.

• Payload limit: The payload size is limited to 300 KB when invoking a resolver from the front end.

• Forge resolver limits:

  • Payload size: Maximum of 5 MB per request.
  • Response size: Maximum of 5 MB, to ensure consistency and account for metadata.

• Accessing objects in UI: Direct object upload and download links for UI components are not supported and must be managed through Forge functions. File uploads or downloads in UI Kit must be handled through a Frame component, which acts as a container for a Custom UI application.

• Production deployments: The EAP is only for testing purposes and deployment to production will not be available.

API Availability

The Forge Object Store APIs are accessible exclusively through Forge methods:

• Upload/Update (Put): Save new objects or overwrite existing ones using their objectId.
• Get metadata (Get): Retrieve metadata (e.g., size, checksum, creation time) for the latest version of an object. Does not include the object's actual data.
• Download: Retrieve the actual object data.
• List versions: View all versions of an object, showing its change history. Metadata returned per version matches what is available via "Get metadata."
• Delete: Remove objects entirely from the store.

Setup

To get started with the Object store, follow these steps:

1. Install the Forge object store package: Add the required Forge package to your project by running:

   1
   2
   npm install @forge/os
   

2. Import the package: Include the package in your app by adding the following import statement:

   1
   2
   import os from '@forge/os'
   

Upload/Update object (put)

Store large files or media efficiently from your app using the Forge-hosted storage.

The put method allows you to upload an object with the following parameters:

• objectId (string): A unique identifier for the object being stored. If an object already exists with the same objectId, the new upload will add a new version of the object, effectively functioning as an update operation.
• object (any): The data to be stored, which is buffered internally for efficient handling.
• ttlSeconds (number): Allows you to set a custom TTL for and object. If no TTL is set, the object's TTL will default to 90 days. Custom TTLs must be greater than 1 second and can't exceed 90 days.

Method signature

1
2
os.put(objectId: string, object: any, ttlSeconds?: number): Promise<void>;

Example

1
2
export const uploadObject = async (objectId: string, object: any, ttlSeconds?: number): Promise<void> => {
  try {
    const bufferedObject = Buffer.from(object)
    await os.put(objectId, bufferedObject, ttlSeconds)
  } catch (error) {
    console.error('Error uploading object', JSON.stringify(error))
  }
}

Get metadata (get)

Retrieve the metadata for objects stored in the Forge-hosted object store using the get method.

The get method works as follows:

• objectId (string): The unique identifier for the object metadata to retrieve.
• Returns: The objectReference if found, or undefined if the object does not exist.

Method signature

1
2
os.get(objectId: string): Promise<ObjectReference | undefined>;

interface ObjectReference {
  key: string;
  checksum: string;
  size: number;
  createdAt?: string;
  currentVersion?: string;
} 

Example

1
2
export const getObjectRef = async (objectId: string): Promise<ObjectReference | undefined> => {
  try {
    const objectRef = os.get(objectId);
    if (objectRef === undefined) {
      console.info('Object was not found',  { objectId })
    }
    return objectRef
  } catch (error) {
    console.error('Error getting object reference', JSON.stringify(error))
  }
};

Download

Retrieve the data of the latest version of an object stored in the Forge Object Store using the download method.

The download method works as follows:

• objectId (string): The unique identifier for the object to download.
• Returns: A Buffer containing the latest object data if it exists, or undefined if the object is not found.

Method signature

1
2
os.download(objectId: string): Promise<Buffer | undefined>;

Example

1
2
export const downloadObject = async (objectId: string): Promise<Buffer | undefined> {
try {
    const object = os.download(objectId);
    if (object === undefined) {
      console.info('Object was not found',  { objectId })
    }
    return object
  } catch (error) {
    console.error('Error downloading object', JSON.stringify(error))
  }
}

List versions (listVersions)

View the version history for a stored object using the listVersions method.

The listVersions method works as follows:

• objectId (string): The unique identifier for the object whose versions you want to list.
• Returns: A VersionsList containing details of object versions from the last 30 days, or undefined if the object does not exist.

Method signature

1
2
os.listVersions(objectId: string): Promise<VersionsList | undefined>;

interface VersionsList {
 versions: ObjectReference[]
}

export interface ObjectReference {
  key: string;
  checksum: string;
  size: number;
  createdAt?: string;
  currentVersion?: string;
}

Example

1
2
export const listObjectVersions = async (objectId: string): Promise<VersionsList | undefined> {
  try {
    const versionsList = os.listVersions(objectId);
    if (versionsList === undefined) {
      console.info('Object was not found',  { objectId })
    }
    return versionsList
  } catch (error) {
    console.error('Error getting versionsList', JSON.stringify(error))
  }
}

Delete

Remove objects from the Forge-hosted object store using the delete method.

The delete method works as follows:

• objectId (string): The unique identifier for the object to delete.

Method signature

1
2
os.delete(objectId: string): Promise<void>;

Example

1
2
export const deleteObject = async (objectId: string): Promise<void> => {
  try {
    await os.delete(objectId)
  } catch (error) {
    console.error('Error deleting object', JSON.stringify(error))
  }
}

 

The Forge Object Store provides a robust and efficient solution for storing large files and media directly within your Forge apps. With seamless integration, straightforward setup, and a versatile API, it streamlines data storage and retrieval, making it an essential tool for developers.

As part of the EAP, your feedback is invaluable in shaping the future of this feature. We encourage you to explore the object store's capabilities and share your insights to help us refine and enhance this service.