convex/src/server/storage.ts

Client for the Convex Cloud

/**
 * A reference to a file in storage.
 *
 * This is used in the {@link StorageReader} and {@link StorageWriter} which are accessible in
 * Convex queries and mutations via {@link QueryCtx} and {@link MutationCtx} respectively.
 *
 * @public
 */
export type StorageId = string;

/**
 * Metadata for a single file as returned by {@link StorageReader.getMetadata | storage.getMetadata}.
 *
 * @public
 */
export type FileMetadata = {
  /**
   * ID for referencing the file (eg. via {@link StorageReader.getUrl | storage.getUrl})
   */
  storageId: StorageId;
  /**
   * Hex encoded sha256 checksum of file contents
   */
  sha256: string;
  /**
   * Size of the file in bytes
   */
  size: number;
  /**
   * ContentType of the file if it was provided on upload
   */
  contentType: string | null;
};

/**
 * An interface to read from storage within Convex query functions.
 *
 * @public
 */
export interface StorageReader {
  /**
   * Get the URL for a file in storage by its {@link StorageId}.
   *
   * The GET response includes a standard HTTP Digest header with a sha256 checksum.
   *
   * @param storageId - The {@link StorageId} of the file to fetch from Convex storage.
   * @returns - A url which fetches the file via an HTTP GET, or `null` if it no longer exists.
   */
  getUrl(storageId: StorageId): Promise<string | null>;
  /**
   * Get metadata for a file.
   *
   * @param storageId - The {@link StorageId} of the file.
   * @returns - A {@link FileMetadata} object if found or `null` if not found.
   */
  getMetadata(storageId: StorageId): Promise<FileMetadata | null>;
}

/**
 * An interface to write to storage within Convex mutation functions.
 *
 * @public
 */
export interface StorageWriter extends StorageReader {
  /**
   * Fetch a short-lived URL for uploading a file into storage.
   *
   * Upon a POST request to this URL, the endpoint will return a JSON object containing a newly allocated {@link StorageId}.
   *
   * The POST URL accepts an optional standard HTTP Digest header with a sha256 checksum.
   *
   * @returns - A url that allows file upload via an HTTP POST.
   */
  generateUploadUrl(): Promise<string>;
  /**
   * Delete a file from Convex storage.
   *
   * Once a file is deleted, any URLs previously generated by {@link StorageReader.getUrl} will return 404s.
   *
   * @param storageId - The {@link StorageId} of the file to delete from Convex storage.
   */
  delete(storageId: StorageId): Promise<void>;
}