CoSyncAsset object

CosyncAsset object #

The CoSync AssetLink subsystem is implemented using the CosyncAsset class, which is a MongoDB Realm object. This object serve as the intermediary, facilitating communication between the client application and the Amazon S3 bucket storage. Positioned between them is the MongoDB App Service, which supports the client application and manages the API keys for the Amazon S3 bucket storage. This MongoDB App Service will build the CosyncAsset on behalf of the client application.

The CosyncAsset object fully represents a client asset within the MongoDB Realm framework. It encompasses all the essential information required to display an asset within the client’s user interface, along with pertinent metadata about the asset. The URLs contained in a CosyncAsset directly reference storage within the application’s Amazon S3 bucket storage.

This class assumes the MongoDB Flexible Sync sync type. The older Partition Sync is no longer supported by CoSync.

A CosyncAsset object represents an asset that has been successfully uploaded to Amazon S3 bucket storage using the CosyncCreateAsset() function. The CosyncAsset object is created by the MongoDB App Service. This function is called by the client after it has completed uploading the assets to a set of write URLs that are returned by the function CosyncInitAsset().

Assets serve as storage for various file data within the bucket storage. Initially, CoSync AssetLink employs Amazon S3 as its bucket storage solution. The path of an asset is derived from the filePath parameter to the CosyncInitAsset() function. This path incorporates the contentId assigned by the server and is sufficient to ascertain the complete paths of all associated cuts for image and video assets. For image assets, the paths for small, medium, and large image cuts will include the suffixes ‘small,’ ‘medium,’ and ’large,’ respectively. The contentId is returned by the CosyncInitAsset() function.

In the case of image assets, multiple size cuts are typically generated by the client and uploaded to the bucket storage via the CosyncAssetUpload object. These cuts consistently maintain the aspect ratio of the original image. The largest dimension of the image is adjusted to fit within the dimensions of the image cut (300, 600, or 900). Clients have the flexibility to determine the specific sizes for these image cuts as needed. The smaller dimension always remains smaller than the size of the image cut. If the largest dimension is smaller than the size of the cut, the cut will match the dimensions of the original image; cuts are never scaled up. In the case of video assets, a video preview image is also included, along with cuts for the video preview in small, medium, and large sizes.

Asset Status #

The status property serves to document the condition or state of the asset. It offers several options, including:

  • active
  • deleted

The default status is ‘active’, indicating that the asset is currently in use. Alternatively, it can be changed to ‘deleted’, implying that the asset is to be deleted from the bucket storage. If the client application wishes to delete an asset, the code simply needs to change the status to ‘deleted’.

An asset can be configured to expire or not. For assets with no expiration, the expirationHours property is assigned a positive value greater than zero, indicating the expiration duration in hours. In case expirationHours is set to zero, the asset is considered public and does not expire. URLs associated with non-expiring assets remain perpetually valid and do not require refreshing.

However, for assets set to expire, their URLs become invalid once the current date surpasses the date specified in the expiration property. To access URLs for expired assets, the client must request an asset refresh via the CosyncRefreshAsset server function call.

CosyncAsset class in Swift #

public class CosyncAsset: Object {
	@Persisted(primaryKey: true) public var _id: ObjectId

	/* userId of user that created the storage upload */
	@Persisted var userId: String = ""

	/* extra information put in by client (only used by client) */
	@Persisted var extra: String = ""

	/* path of file in bucket (storage path key) */
	@Persisted var path: String = ""

	/* expiration hours (zero for non-expiring public assets) */
	@Persisted var expirationHours: Double = 0

	/* when the asset expires */
	@Persisted public var expiration: Date?

	/* content type (set by client) */
	@Persisted var contentType: String?

	/* size in bytes of asset */
	@Persisted var size: Int?

	/* duration for audio or video file in seconds */
	@Persisted var duration: Double?

	/* average color (hex color of background for image) */
	@Persisted var color: String = ""

	/* x resolution of original image or video asset */
	@Persisted var xRes: Int = 0

	/* y resolution of original image or video asset */
	@Persisted var yRes: Int = 0

	/* caption */
	@Persisted var caption: String = ""

	/* url of asset in storage (for non-expiring public assets) */
	@Persisted var url: String?

	/* url of small cut in storage (for non-expiring public assets) */
	@Persisted var urlSmall: String?	

	/* url of medium cut in storage (for non-expiring public assets) */
	@Persisted var urlMedium: String?

	/* url of large cut in storage (for non-expiring public assets) */
	@Persisted var urlLarge: String?

	/* url of video preview in storage (for non-expiring public assets) */
	@Persisted var urlVideoPreview: String?

	/* status either 'active', 'deleted' */
	@Persisted var status: String = ""
	/* when created */
	@Persisted var createdAt: Date?

	/* when updated */
	@Persisted var updatedAt: Date?


Content Types #

There are all kinds of assets that may be stored and retrieved in S3. The following is a list of compatible assets for CoSync AssetLink and these strings are used in the contentType property.

    /* text asset type */

    /* image asset type */
    /* video asset type */

    /* audio asset type */

    /* file asset type */

Functions #

CosyncRefreshAsset #

The function CosyncRefreshAsset() is called by a client to refresh the URLs of an expiring asset. If called, the function will recompute the URLs of an expired asset and update the CosyncAsset object with the updated url(s). It will also modify the updatedAt property. The only parameter to this function is the assetId.

The assetId can contain multiple assetId(s) separated by commas ‘,’. This can enable a client to refresh multiple assets at the same time. If multiple assets were passed in, the function will return a JSON array of multiple asset objects. Otherwise, it returns a single JSON asset object.

async function CosyncRefreshAsset(
		assetId			/* asset Id of the CosyncAsset object */

CosyncClearAsset #

The function CosyncClearAsset() is called clean up an asset on the storage server, if an upload and/or the CosyncCreateAsset() failed. Normally, a client deletes an asset by setting the status field to ‘deleted’ on the CosyncAsset object. However, the client can be assured the uploaded asset is deleted by calling the CosyncClearAsset() function if the CosyncAsset object has not yet been created.

async function CosyncClearAsset(
		filePath,			/* Input file path */
		contentType,		/* content MIME type for asset */
		expirationHours,	/* Expiration in hours (0 means public) */
		contentId			/* contentId returned by CreateInitAsset() */