backend-common: Remove read method from UrlReader

Signed-off-by: Johan Haals <johan.haals@gmail.com>
2023-01-02 16:34:54 +01:00
parent 7de9f5c868
commit 4ae89dbce6
32 changed files with 417 additions and 387 deletions
@@ -3,6 +3,8 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).

 ```ts
+/// <reference types="node" />
+
 import { Config } from '@backstage/config';
 import { Handler } from 'express';
 import { Logger } from 'winston';
@@ -12,9 +14,9 @@ import { PluginCacheManager } from '@backstage/backend-common';
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
+import { Readable } from 'stream';
 import { TokenManager } from '@backstage/backend-common';
 import { TransportStreamOptions } from 'winston-transport';
-import { UrlReader } from '@backstage/backend-common';

 // @public (undocumented)
 export interface BackendFeature {
@@ -245,6 +247,50 @@ export interface PluginMetadataService {
 // @public (undocumented)
 const pluginMetadataServiceRef: ServiceRef<PluginMetadataService, 'plugin'>;

+// @public
+export type ReadTreeOptions = {
+  filter?(
+    path: string,
+    info?: {
+      size: number;
+    },
+  ): boolean;
+  etag?: string;
+  signal?: AbortSignal;
+};
+
+// @public
+export type ReadTreeResponse = {
+  files(): Promise<ReadTreeResponseFile[]>;
+  archive(): Promise<NodeJS.ReadableStream>;
+  dir(options?: ReadTreeResponseDirOptions): Promise<string>;
+  etag: string;
+};
+
+// @public
+export type ReadTreeResponseDirOptions = {
+  targetDir?: string;
+};
+
+// @public
+export type ReadTreeResponseFile = {
+  path: string;
+  content(): Promise<Buffer>;
+};
+
+// @public
+export type ReadUrlOptions = {
+  etag?: string;
+  signal?: AbortSignal;
+};
+
+// @public
+export type ReadUrlResponse = {
+  buffer(): Promise<Buffer>;
+  stream?(): Readable;
+  etag?: string;
+};
+
 // @public (undocumented)
 export type RootLoggerService = LoggerService;

@@ -257,6 +303,24 @@ export type SchedulerService = PluginTaskScheduler;
 // @public (undocumented)
 const schedulerServiceRef: ServiceRef<PluginTaskScheduler, 'plugin'>;

+// @public
+export type SearchOptions = {
+  etag?: string;
+  signal?: AbortSignal;
+};
+
+// @public
+export type SearchResponse = {
+  files: SearchResponseFile[];
+  etag: string;
+};
+
+// @public
+export type SearchResponseFile = {
+  url: string;
+  content(): Promise<Buffer>;
+};
+
 // @public (undocumented)
 export type ServiceFactory<TService = unknown> =
  | {
@@ -307,9 +371,13 @@ export type TypesToServiceRef<T> = {
  [key in keyof T]: ServiceRef<T[key]>;
 };

-// @public (undocumented)
-export type UrlReaderService = UrlReader;
+// @public
+export type UrlReaderService = {
+  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
+  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
+  search(url: string, options?: SearchOptions): Promise<SearchResponse>;
+};

 // @public (undocumented)
-const urlReaderServiceRef: ServiceRef<UrlReader, 'plugin'>;
+const urlReaderServiceRef: ServiceRef<UrlReaderService, 'plugin'>;
 ```
@@ -32,4 +32,15 @@ export type { PluginMetadataService } from './pluginMetadataServiceRef';
 export type { RootLoggerService } from './rootLoggerServiceRef';
 export type { SchedulerService } from './schedulerServiceRef';
 export type { TokenManagerService } from './tokenManagerServiceRef';
-export type { UrlReaderService } from './urlReaderServiceRef';
+export type {
+  ReadTreeOptions,
+  ReadTreeResponse,
+  ReadTreeResponseDirOptions,
+  ReadTreeResponseFile,
+  ReadUrlResponse,
+  ReadUrlOptions,
+  SearchOptions,
+  SearchResponse,
+  SearchResponseFile,
+  UrlReaderService,
+} from './urlReaderServiceRef';
@@ -15,10 +15,278 @@
 */

 import { createServiceRef } from '../system/types';
-import { UrlReader } from '@backstage/backend-common';
+import { Readable } from 'stream';

-/** @public */
-export type UrlReaderService = UrlReader;
+/**
+ * A generic interface for fetching plain data from URLs.
+ *
+ * @public
+ */
+export type UrlReaderService = {
+  /**
+   * Reads a single file and return its content.
+   *
+   * @remarks
+   *
+   * This is a replacement for the read method that supports options and
+   * complex responses.
+   *
+   * Use this as the read method will be removed in a future release.
+   */
+  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
+
+  /**
+   * Reads a full or partial file tree.
+   */
+  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
+
+  /**
+   * Searches for a file in a tree using a glob pattern.
+   */
+  search(url: string, options?: SearchOptions): Promise<SearchResponse>;
+};
+
+/**
+ * An options object for readUrl operations.
+ *
+ * @public
+ */
+export type ReadUrlOptions = {
+  /**
+   * An ETag which can be provided to check whether a
+   * {@link UrlReaderService.readUrl} response has changed from a previous execution.
+   *
+   * @remarks
+   *
+   * In the {@link UrlReaderService.readUrl} response, an ETag is returned along with
+   * the data. The ETag is a unique identifier of the data, usually the commit
+   * SHA or ETag from the target.
+   *
+   * When an ETag is given in ReadUrlOptions, {@link UrlReaderService.readUrl} will
+   * first compare the ETag against the ETag of the target. If they match,
+   * {@link UrlReaderService.readUrl} will throw a
+   * {@link @backstage/errors#NotModifiedError} indicating that the response
+   * will not differ from the previous response which included this particular
+   * ETag. If they do not match, {@link UrlReaderService.readUrl} will return the rest
+   * of the response along with a new ETag.
+   */
+  etag?: string;
+
+  /**
+   * An abort signal to pass down to the underlying request.
+   *
+   * @remarks
+   *
+   * Not all reader implementations may take this field into account.
+   */
+  signal?: AbortSignal;
+};
+
+/**
+ * A response object for {@link UrlReaderService.readUrl} operations.
+ *
+ * @public
+ */
+export type ReadUrlResponse = {
+  /**
+   * Returns the data that was read from the remote URL.
+   */
+  buffer(): Promise<Buffer>;
+
+  /**
+   * Returns the data that was read from the remote URL as a Readable stream.
+   *
+   * @remarks
+   *
+   * This method will be required in a future release.
+   */
+  stream?(): Readable;
+
+  /**
+   * Etag returned by content provider.
+   *
+   * @remarks
+   *
+   * Can be used to compare and cache responses when doing subsequent calls.
+   */
+  etag?: string;
+};
+
+/**
+ * An options object for {@link UrlReaderService.readTree} operations.
+ *
+ * @public
+ */
+export type ReadTreeOptions = {
+  /**
+   * A filter that can be used to select which files should be included.
+   *
+   * @remarks
+   *
+   * The path passed to the filter function is the relative path from the URL
+   * that the file tree is fetched from, without any leading '/'.
+   *
+   * For example, given the URL https://github.com/my/repo/tree/master/my-dir, a file
+   * at https://github.com/my/repo/blob/master/my-dir/my-subdir/my-file.txt will
+   * be represented as my-subdir/my-file.txt
+   *
+   * If no filter is provided, all files are extracted.
+   */
+  filter?(path: string, info?: { size: number }): boolean;
+
+  /**
+   * An ETag which can be provided to check whether a
+   * {@link UrlReaderService.readTree} response has changed from a previous execution.
+   *
+   * @remarks
+   *
+   * In the {@link UrlReaderService.readTree} response, an ETag is returned along with
+   * the tree blob. The ETag is a unique identifier of the tree blob, usually
+   * the commit SHA or ETag from the target.
+   *
+   * When an ETag is given as a request option, {@link UrlReaderService.readTree} will
+   * first compare the ETag against the ETag on the target branch. If they
+   * match, {@link UrlReaderService.readTree} will throw a
+   * {@link @backstage/errors#NotModifiedError} indicating that the response
+   * will not differ from the previous response which included this particular
+   * ETag. If they do not match, {@link UrlReaderService.readTree} will return the
+   * rest of the response along with a new ETag.
+   */
+  etag?: string;
+
+  /**
+   * An abort signal to pass down to the underlying request.
+   *
+   * @remarks
+   *
+   * Not all reader implementations may take this field into account.
+   */
+  signal?: AbortSignal;
+};
+
+/**
+ * Options that control {@link ReadTreeResponse.dir} execution.
+ *
+ * @public
+ */
+export type ReadTreeResponseDirOptions = {
+  /**
+   * The directory to write files to.
+   *
+   * @remarks
+   *
+   * Defaults to the OS tmpdir, or `backend.workingDirectory` if set in config.
+   */
+  targetDir?: string;
+};
+
+/**
+ * A response object for {@link UrlReaderService.readTree} operations.
+ *
+ * @public
+ */
+export type ReadTreeResponse = {
+  /**
+   * Returns an array of all the files inside the tree, and corresponding
+   * functions to read their content.
+   */
+  files(): Promise<ReadTreeResponseFile[]>;
+
+  /**
+   * Returns the tree contents as a binary archive, using a stream.
+   */
+  archive(): Promise<NodeJS.ReadableStream>;
+
+  /**
+   * Extracts the tree response into a directory and returns the path of the
+   * directory.
+   *
+   * **NOTE**: It is the responsibility of the caller to remove the directory after use.
+   */
+  dir(options?: ReadTreeResponseDirOptions): Promise<string>;
+
+  /**
+   * Etag returned by content provider.
+   *
+   * @remarks
+   *
+   * Can be used to compare and cache responses when doing subsequent calls.
+   */
+  etag: string;
+};
+
+/**
+ * Represents a single file in a {@link UrlReaderService.readTree} response.
+ *
+ * @public
+ */
+export type ReadTreeResponseFile = {
+  path: string;
+  content(): Promise<Buffer>;
+};
+
+/**
+ * An options object for search operations.
+ *
+ * @public
+ */
+export type SearchOptions = {
+  /**
+   * An etag can be provided to check whether the search response has changed from a previous execution.
+   *
+   * In the search() response, an etag is returned along with the files. The etag is a unique identifier
+   * of the current tree, usually the commit SHA or etag from the target.
+   *
+   * When an etag is given in SearchOptions, search will first compare the etag against the etag
+   * on the target branch. If they match, search will throw a NotModifiedError indicating that the search
+   * response will not differ from the previous response which included this particular etag. If they mismatch,
+   * search will return the rest of SearchResponse along with a new etag.
+   */
+  etag?: string;
+
+  /**
+   * An abort signal to pass down to the underlying request.
+   *
+   * @remarks
+   *
+   * Not all reader implementations may take this field into account.
+   */
+  signal?: AbortSignal;
+};
+
+/**
+ * The output of a search operation.
+ *
+ * @public
+ */
+export type SearchResponse = {
+  /**
+   * The files that matched the search query.
+   */
+  files: SearchResponseFile[];
+
+  /**
+   * A unique identifier of the current remote tree, usually the commit SHA or etag from the target.
+   */
+  etag: string;
+};
+
+/**
+ * Represents a single file in a search response.
+ *
+ * @public
+ */
+export type SearchResponseFile = {
+  /**
+   * The full URL to the file.
+   */
+  url: string;
+
+  /**
+   * The binary contents of the file.
+   */
+  content(): Promise<Buffer>;
+};

 /**
 * @public