backend-common: add new optional readUrl method to UrlReader

Co-authored-by: Johan Haals <johan.haals@gmail.com>
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

packages/backend-common/src/reading/types.ts

@@ -23,7 +23,17 @@ import { Config } from '@backstage/config';
  */
 export type UrlReader = {
   read(url: string): Promise<Buffer>;
+
+  /**
+   * A replacement for the read method that supports options and complex responses.
+   *
+   * Use this whenever it is available, as the read method will be deprecated and
+   * eventually removed in the future.
+   */
+  readUrl?(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
+
   readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
+
   search(url: string, options?: SearchOptions): Promise<SearchResponse>;
 };
 
@@ -42,6 +52,40 @@ export type ReaderFactory = (options: {
   treeResponseFactory: ReadTreeResponseFactory;
 }) => UrlReaderPredicateTuple[];
 
+/**
+ * An options object for readUrl operations.
+ */
+export type ReadUrlOptions = {
+  /**
+   * An etag can be provided to check whether readUrl's response has changed from a previous execution.
+   *
+   * In the readUrl() response, an etag is returned along with the data. The etag is a unique identifer
+   * of the data, usually the commit SHA or etag from the target.
+   *
+   * When an etag is given in ReadUrlOptions, readUrl will first compare the etag against the etag
+   * on the target branch. If they match, readUrl will throw a NotModifiedError indicating that the readUrl
+   * response will not differ from the previous response which included this particular etag. If they
+   * do not match, readUrl will return the rest of ReadUrlResponse along with a new etag.
+   */
+  etag?: string;
+};
+
+/**
+ * A response object for readUrl operations.
+ */
+export type ReadUrlResponse = {
+  /**
+   * Returns the data that was read from the remote URL.
+   */
+  buffer(): Promise<Buffer>;
+
+  /**
+   * Etag returned by content provider.
+   * Can be used to compare and cache responses when doing subsequent calls.
+   */
+  etag?: string;
+};
+
 /**
  * An options object for readTree operations.
  */
@@ -66,14 +110,17 @@ export type ReadTreeOptions = {
    * In the readTree() response, an etag is returned along with the tree blob. The etag is a unique identifer
    * of the tree blob, usually the commit SHA or etag from the target.
    *
-   * When a etag is given in ReadTreeOptions, readTree will first compare the etag against the etag
+   * When an etag is given in ReadTreeOptions, readTree will first compare the etag against the etag
    * on the target branch. If they match, readTree will throw a NotModifiedError indicating that the readTree
-   * response will not differ from the previous response which included this particular etag. If they mismatch,
-   * readTree will return the rest of ReadTreeResponse along with a new etag.
+   * response will not differ from the previous response which included this particular etag. If they
+   * do not match, readTree will return the rest of ReadTreeResponse along with a new etag.
    */
   etag?: string;
 };
 
+/**
+ * A response object for readTree operations.
+ */
 export type ReadTreeResponse = {
   /**
    * files() returns an array of all the files inside the tree and corresponding functions to read their content.
@@ -87,7 +134,8 @@ export type ReadTreeResponse = {
   dir(options?: ReadTreeResponseDirOptions): Promise<string>;
 
   /**
-   * A unique identifer of the tree blob, usually the commit SHA or etag from the target.
+   * Etag returned by content provider.
+   * Can be used to compare and cache responses when doing subsequent calls.
    */
   etag: string;
 };