feat(catalog-client): create a basic catalog client (#3166)

2020-11-04 13:18:03 +01:00
parent bb547d5bf6
commit 42b0dbddcb
22 changed files with 155 additions and 61 deletions
@@ -0,0 +1,3 @@
+module.exports = {
+  extends: [require.resolve('@backstage/cli/config/eslint')],
+};
@@ -0,0 +1,17 @@
+# Catalog Client
+
+Contains a frontend and backend compatible client for communicating with the
+Backstage Catalog.
+
+Backend code may import and use this package directly.
+
+However, frontend code will not want to import this package directly - use the
+`@backstage/plugin-catalog` package instead, which re-exports all of the types
+and classes from this package. Thereby, you will also gain access to its
+`catalogApiRef`.
+
+## Links
+
+- [Default frontend part of the catalog](https://github.com/spotify/backstage/tree/master/plugins/catalog)
+- [Default backend part of the catalog](https://github.com/spotify/backstage/tree/master/plugins/catalog-backend)
+- [The Backstage homepage](https://backstage.io)
@@ -0,0 +1,35 @@
+{
+  "name": "@backstage/catalog-client",
+  "version": "0.2.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "module": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "scripts": {
+    "build": "backstage-cli build",
+    "lint": "backstage-cli lint",
+    "test": "backstage-cli test",
+    "prepack": "backstage-cli prepack",
+    "postpack": "backstage-cli postpack",
+    "clean": "backstage-cli clean"
+  },
+  "dependencies": {
+    "@backstage/catalog-model": "^0.2.0",
+    "@backstage/config": "^0.1.1",
+    "cross-fetch": "^3.0.6"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.2.0",
+    "@types/jest": "^26.0.7",
+    "msw": "^0.21.2"
+  },
+  "files": [
+    "dist"
+  ]
+}
@@ -0,0 +1,93 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { rest } from 'msw';
+import { setupServer } from 'msw/node';
+import { CatalogClient } from './CatalogClient';
+import { Entity } from '@backstage/catalog-model';
+import { DiscoveryApi } from './types';
+
+const server = setupServer();
+const mockBaseUrl = 'http://backstage:9191/i-am-a-mock-base';
+const discoveryApi: DiscoveryApi = {
+  async getBaseUrl(_pluginId) {
+    return mockBaseUrl;
+  },
+};
+
+describe('CatalogClient', () => {
+  let client: CatalogClient;
+
+  beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+  afterAll(() => server.close());
+  afterEach(() => server.resetHandlers());
+
+  beforeEach(() => {
+    client = new CatalogClient({ discoveryApi });
+  });
+
+  describe('getEntities', () => {
+    const defaultResponse: Entity[] = [
+      {
+        apiVersion: '1',
+        kind: 'Component',
+        metadata: {
+          name: 'Test1',
+          namespace: 'test1',
+        },
+      },
+      {
+        apiVersion: '1',
+        kind: 'Component',
+        metadata: {
+          name: 'Test2',
+          namespace: 'test1',
+        },
+      },
+    ];
+
+    beforeEach(() => {
+      server.use(
+        rest.get(`${mockBaseUrl}/entities`, (_, res, ctx) => {
+          return res(ctx.json(defaultResponse));
+        }),
+      );
+    });
+
+    it('should entities from correct endpoint', async () => {
+      const entities = await client.getEntities();
+      expect(entities).toEqual(defaultResponse);
+    });
+
+    it('builds entity search filters properly', async () => {
+      expect.assertions(2);
+      server.use(
+        rest.get(`${mockBaseUrl}/entities`, (req, res, ctx) => {
+          expect(req.url.search).toBe('?filter=a=1,b=2,b=3,%C3%B6=%3D');
+          return res(ctx.json([]));
+        }),
+      );
+
+      const entities = await client.getEntities({
+        a: '1',
+        b: ['2', '3'],
+        ö: '=',
+      });
+
+      expect(entities).toEqual([]);
+    });
+  });
+});
@@ -0,0 +1,156 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  Entity,
+  EntityName,
+  Location,
+  LOCATION_ANNOTATION,
+} from '@backstage/catalog-model';
+import fetch from 'cross-fetch';
+import {
+  AddLocationRequest,
+  AddLocationResponse,
+  CatalogApi,
+  DiscoveryApi,
+} from './types';
+
+export class CatalogClient implements CatalogApi {
+  private readonly discoveryApi: DiscoveryApi;
+
+  constructor(options: { discoveryApi: DiscoveryApi }) {
+    this.discoveryApi = options.discoveryApi;
+  }
+
+  private async getRequired(path: string): Promise<any> {
+    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      const payload = await response.text();
+      const message = `Request failed with ${response.status} ${response.statusText}, ${payload}`;
+      throw new Error(message);
+    }
+
+    return await response.json();
+  }
+
+  private async getOptional(path: string): Promise<any | undefined> {
+    const url = `${await this.discoveryApi.getBaseUrl('catalog')}${path}`;
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      if (response.status === 404) {
+        return undefined;
+      }
+
+      const payload = await response.text();
+      const message = `Request failed with ${response.status} ${response.statusText}, ${payload}`;
+      throw new Error(message);
+    }
+
+    return await response.json();
+  }
+
+  async getLocationById(id: String): Promise<Location | undefined> {
+    return await this.getOptional(`/locations/${id}`);
+  }
+
+  async getEntities(
+    filter?: Record<string, string | string[]>,
+  ): Promise<Entity[]> {
+    let path = `/entities`;
+    if (filter) {
+      const parts: string[] = [];
+      for (const [key, value] of Object.entries(filter)) {
+        for (const v of [value].flat()) {
+          parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
+        }
+      }
+      path += `?filter=${parts.join(',')}`;
+    }
+
+    return await this.getRequired(path);
+  }
+
+  async getEntityByName(compoundName: EntityName): Promise<Entity | undefined> {
+    const { kind, namespace = 'default', name } = compoundName;
+    return this.getOptional(`/entities/by-name/${kind}/${namespace}/${name}`);
+  }
+
+  async addLocation({
+    type = 'url',
+    target,
+    dryRun,
+  }: AddLocationRequest): Promise<AddLocationResponse> {
+    const response = await fetch(
+      `${await this.discoveryApi.getBaseUrl('catalog')}/locations${
+        dryRun ? '?dryRun=true' : ''
+      }`,
+      {
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        method: 'POST',
+        body: JSON.stringify({ type, target }),
+      },
+    );
+
+    if (response.status !== 201) {
+      throw new Error(await response.text());
+    }
+
+    const { location, entities } = await response.json();
+
+    if (!location) {
+      throw new Error(`Location wasn't added: ${target}`);
+    }
+
+    if (entities.length === 0) {
+      throw new Error(
+        `Location was added but has no entities specified yet: ${target}`,
+      );
+    }
+    return {
+      location,
+      entities,
+    };
+  }
+
+  async getLocationByEntity(entity: Entity): Promise<Location | undefined> {
+    const locationCompound = entity.metadata.annotations?.[LOCATION_ANNOTATION];
+    const all: { data: Location }[] = await this.getRequired('/locations');
+    return all
+      .map(r => r.data)
+      .find(l => locationCompound === `${l.type}:${l.target}`);
+  }
+
+  async removeEntityByUid(uid: string): Promise<void> {
+    const response = await fetch(
+      `${await this.discoveryApi.getBaseUrl('catalog')}/entities/by-uid/${uid}`,
+      {
+        method: 'DELETE',
+      },
+    );
+    if (!response.ok) {
+      const payload = await response.text();
+      throw new Error(
+        `Request failed with ${response.status} ${response.statusText}, ${payload}`,
+      );
+    }
+    return undefined;
+  }
+}
@@ -0,0 +1,18 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { CatalogClient } from './CatalogClient';
+export type { CatalogApi } from './types';
@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {};
@@ -0,0 +1,44 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Entity, EntityName, Location } from '@backstage/catalog-model';
+
+export interface CatalogApi {
+  getLocationById(id: String): Promise<Location | undefined>;
+  getEntityByName(name: EntityName): Promise<Entity | undefined>;
+  getEntities(filter?: Record<string, string | string[]>): Promise<Entity[]>;
+  addLocation(location: AddLocationRequest): Promise<AddLocationResponse>;
+  getLocationByEntity(entity: Entity): Promise<Location | undefined>;
+  removeEntityByUid(uid: string): Promise<void>;
+}
+
+export type AddLocationRequest = {
+  type?: string;
+  target: string;
+  dryRun?: boolean;
+};
+
+export type AddLocationResponse = {
+  location: Location;
+  entities: Entity[];
+};
+
+/**
+ * This is a copy of the core DiscoveryApi, to avoid importing core.
+ */
+export type DiscoveryApi = {
+  getBaseUrl(pluginId: string): Promise<string>;
+};