Merge pull request #15506 from backstage/jhaals/remove-read

backend-common: Remove read method from UrlReader

docs/features/software-catalog/external-integrations.md

@@ -111,10 +111,10 @@ export class FrobsProvider implements EntityProvider {
       throw new Error('Not initialized');
     }
 
-    const raw = await this.reader.read(
+    const response = await this.reader.readUrl(
       `https://frobs-${this.env}.example.com/data`,
     );
-    const data = JSON.parse(raw.toString());
+    const data = JSON.parse(await response.buffer()).toString();
 
     /** [5] **/
     const entities: Entity[] = frobsToEntities(data);
@@ -525,8 +525,8 @@ export class SystemXReaderProcessor implements CatalogProcessor {
       // API. If you prefer, you can just use plain fetch here
       // (from the node-fetch package), or any other method of
       // your choosing.
-      const data = await this.reader.read(location.target);
-      const json = JSON.parse(data.toString());
+      const response = await this.reader.readUrl(location.target);
+      const json = JSON.parse((await response.buffer()).toString());
       // Repeatedly call emit(processingResult.entity(location, <entity>))
     } catch (error) {
       const message = `Unable to read ${location.type}, ${error}`;
@@ -627,7 +627,7 @@ export class SystemXReaderProcessor implements CatalogProcessor {
       // We send the ETag from the previous run if it exists.
       // The previous ETag will be set in the headers for the outgoing request and system-x
       // is going to throw NOT_MODIFIED (HTTP 304) if the ETag matches.
-      const response = await this.reader.readUrl?.(location.target, {
+      const response = await this.reader.readUrl(location.target, {
         etag: cacheItem?.etag,
       });
       if (!response) {

docs/plugins/url-reader.md

@@ -60,15 +60,7 @@ The generic interface of a URL Reader instance looks like this.
 ```ts
 export type UrlReader = {
   /* Used to read a single file and return its content. */
-  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>;
-
+  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
   /* Used to read a file tree and download as a directory. */
   readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
   /* Used to search a file in a tree. */
@@ -102,8 +94,8 @@ backend plugins.
 Once the reader instance is available inside the plugin, one of its methods can
 directly be used with a URL. Some example usages -
 
-- [`read`](https://github.com/backstage/backstage/blob/d5c83bb889b8142e343ebc4e4c0b90a02d1c1a3d/plugins/catalog-backend/src/ingestion/processors/codeowners/read.ts#L24-L33) -
-  Catalog using the `read` method to read the CODEOWNERS file in a repository.
+- [`readUrl`](https://github.com/backstage/backstage/blob/a7607b5/plugins/catalog-backend/src/modules/codeowners/lib/read.ts#L24-L33) -
+  Catalog using the `readUrl` method to read the CODEOWNERS file in a repository.
 - [`readTree`](https://github.com/backstage/backstage/blob/84a8788/plugins/techdocs-node/src/helpers.ts#L146-L167) -
   TechDocs using the `readTree` method to download markdown files in order to
   generate the documentation site.
@@ -155,11 +147,9 @@ all the methods of the `UrlReader` interface should be implemented. However it
 is okay to start by implementing just one of them and create issues for the
 remaining.
 
-#### read
+#### `readUrl`
 
-NOTE: Use `readUrl` instead of `read`.
-
-`read` method expects a user-friendly URL, something which can be copied from
+`readUrl` method expects a user-friendly URL, something which can be copied from
 the browser naturally when a person is browsing the provider in their browser.
 
 - ✅ Valid URL :
@@ -168,18 +158,10 @@ the browser naturally when a person is browsing the provider in their browser.
   `https://raw.githubusercontent.com/backstage/backstage/master/ADOPTERS.md`
 - ❌ Not a valid URL : `https://github.com/backstage/backstage/ADOPTERS.md`
 
-Upon receiving the URL, `read` converts the user-friendly URL into an API URL
+Upon receiving the URL, `readUrl` converts the user-friendly URL into an API URL
 which can be used to request the provider's API.
 
-`read` then makes an authenticated request to the provider API and returns the
-file's content.
-
-#### `readUrl`
-
-`readUrl` is a new interface that allows complex response objects and is
-intended to replace the `read` method. This new method is currently optional to
-implement which allows for a soft migration to `readUrl` instead of `read` in
-the future.
+`readUrl` then makes an authenticated request to the provider API and returns the response containing the file's contents and ETag(if the provider supports it).
 
 #### `readTree`