message: backend-common: add new optional readUrl method to UrlReader
diff: @@ -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;
  };
  