paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 30 Packages Projects Releases Wiki Activity

Merge pull request #14389 from andrewthauer/explore-backend

Browse Source 
feat: add explore-backend plugin
This commit is contained in:
Patrik Oldsberg
2022-11-29 10:28:54 +01:00
committed by GitHub
parent 89c0b0e6e6 54ba2b70cf
commit 206e589533
51 changed files with 1912 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/explore-backend/.eslintrc.js
+1
View File
@@ -0,0 +1 @@
module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);
plugins/explore-backend/README.md
+144
View File
@@ -0,0 +1,144 @@
# explore-backend
The `explore-backend` plugin provides a backend service for the Explore plugin.
This allows your organizations tools to be surfaced in the Explore plugin
through an API. It also provides a search collator to make it possible to search
for these tools.
## Getting started
### Install the Package
```bash
# From your Backstage root directory
yarn add --cwd packages/backend @backstage/plugin-explore-backend
```
### Adding the plugin to your `packages/backend`
You'll need to add the plugin to the router in your `backend` package. You can
do this by creating a file called `packages/backend/src/plugins/explore.ts`
```ts
import {
createRouter,
StaticExploreToolProvider,
} from '@backstage/plugin-explore-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
// List of tools you want to surface in the Explore plugin "Tools" page.
const tools: ExploreTool[] = [
{
title: 'New Relic',
description:'new relic plugin',
url: '/newrelic',
image: 'https://i.imgur.com/L37ikrX.jpg',
tags: ['newrelic', 'proxy', 'nerdGraph'],
},
...
];
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return await createRouter({
logger: env.logger,
toolProvider: StaticExploreToolProvider.fromData(exploreTools),
});
}
```
With the `explore.ts` router setup in place, add the router to
`packages/backend/src/index.ts`:
```diff
+import explore from './plugins/explore';
async function main() {
...
const createEnv = makeCreateEnv(config);
const catalogEnv = useHotMemoize(module, () => createEnv('catalog'));
+ const exploreEnv = useHotMemoize(module, () => createEnv('explore'));
const apiRouter = Router();
+ apiRouter.use('/explore', await explore(exploreEnv));
...
apiRouter.use(notFoundHandler());
```
### Wire up Search Indexing
To index explore tools you will need to register the search collator in the
`packages/backend/src/plugins/search.ts` file.
```diff
+import { ToolDocumentCollatorFactory } from '@backstage/plugin-explore-backend';
async function createSearchEngine(
env: PluginEnvironment,
): Promise<SearchEngine> {
...
+ indexBuilder.addCollator({
+ schedule,
+ factory: ToolDocumentCollatorFactory.fromConfig(env.config, {
+ discovery: env.discovery,
+ logger: env.logger,
+ }),
+ });
...
}
```
### Wire up the Frontend
See [the explore plugin README](../explore/README.md) for more information.
## Explore Tool Customization
The `explore-backend` uses the `ExploreToolProvider` interface to provide a list
of tools used in your organization and/or within your Backstage instance. This
can be customized to provide tools from any source. For example you could create
a `CustomExploreToolProvider` that queries an internal for tools in your
`packages/backend/src/plugins/explore.ts` file.
```ts
import {
createRouter,
StaticExploreToolProvider,
} from '@backstage/plugin-explore-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
class CustomExploreToolProvider implements ExploreToolProvider {
async getTools(
request: GetExploreToolsRequest,
): Promise<GetExploreToolsResponse> {
const externalTools = await queryExternalTools(request);
const tools: ExploreTool[] = [
...externalTools,
// Backstage Tools
{
title: 'New Relic',
description: 'new relic plugin',
url: '/newrelic',
image: 'https://i.imgur.com/L37ikrX.jpg',
tags: ['newrelic', 'proxy', 'nerdGraph'],
},
];
return { tools };
}
}
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return await createRouter({
logger: env.logger,
toolProvider: new CustomExploreToolProvider(),
});
}
```
plugins/explore-backend/api-report.md
+66
View File
@@ -0,0 +1,66 @@
## API Report File for "@backstage/plugin-explore-backend"
> 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 { DocumentCollatorFactory } from '@backstage/plugin-search-common';
import { ExploreTool } from '@backstage/plugin-explore-common';
import express from 'express';
import { GetExploreToolsRequest } from '@backstage/plugin-explore-common';
import { GetExploreToolsResponse } from '@backstage/plugin-explore-common';
import { IndexableDocument } from '@backstage/plugin-search-common';
import { Logger } from 'winston';
import { PluginEndpointDiscovery } from '@backstage/backend-common';
import { Readable } from 'stream';
// @public (undocumented)
export function createRouter(options: RouterOptions): Promise<express.Router>;
// @public (undocumented)
export interface ExploreToolProvider {
getTools(request: GetExploreToolsRequest): Promise<GetExploreToolsResponse>;
}
// @public (undocumented)
export interface RouterOptions {
// (undocumented)
logger: Logger;
// (undocumented)
toolProvider: ExploreToolProvider;
}
// @public
export class StaticExploreToolProvider implements ExploreToolProvider {
// (undocumented)
static fromData(tools: ExploreTool[]): StaticExploreToolProvider;
// (undocumented)
getTools(request: GetExploreToolsRequest): Promise<GetExploreToolsResponse>;
}
// @public
export interface ToolDocument extends IndexableDocument, ExploreTool {}
// @public
export class ToolDocumentCollatorFactory implements DocumentCollatorFactory {
// (undocumented)
execute(): AsyncGenerator<ToolDocument>;
// (undocumented)
static fromConfig(
_config: Config,
options: ToolDocumentCollatorFactoryOptions,
): ToolDocumentCollatorFactory;
// (undocumented)
getCollator(): Promise<Readable>;
// (undocumented)
readonly type: string;
}
// @public
export type ToolDocumentCollatorFactoryOptions = {
discovery: PluginEndpointDiscovery;
logger: Logger;
};
```
plugins/explore-backend/package.json
+46
View File
@@ -0,0 +1,46 @@
{
"name": "@backstage/plugin-explore-backend",
"version": "0.0.0",
"main": "src/index.ts",
"types": "src/index.ts",
"license": "Apache-2.0",
"publishConfig": {
"access": "public",
"main": "dist/index.cjs.js",
"types": "dist/index.d.ts"
},
"backstage": {
"role": "backend-plugin"
},
"scripts": {
"start": "backstage-cli package start",
"build": "backstage-cli package build",
"lint": "backstage-cli package lint",
"test": "backstage-cli package test",
"clean": "backstage-cli package clean",
"prepack": "backstage-cli package prepack",
"postpack": "backstage-cli package postpack"
},
"dependencies": {
"@backstage/backend-common": "workspace:^",
"@backstage/config": "workspace:^",
"@backstage/plugin-explore-common": "workspace:^",
"@backstage/plugin-search-common": "workspace:^",
"@types/express": "*",
"express": "^4.18.1",
"express-promise-router": "^4.1.0",
"lodash": "^4.17.21",
"node-fetch": "^2.6.7",
"winston": "^3.2.1",
"yn": "^4.0.0"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
"@types/supertest": "^2.0.8",
"msw": "^0.47.0",
"supertest": "^6.2.4"
},
"files": [
"dist"
]
}
plugins/explore-backend/src/example/exampleTools.ts
+98
View File
@@ -0,0 +1,98 @@
/*
* Copyright 2020 The Backstage Authors
*
* 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 { ExploreTool } from '@backstage/plugin-explore-common';
/**
* @private Example only - do not use in production
*/
export const exampleTools: ExploreTool[] = [
{
title: 'New Relic',
description:
'Observability platform built to help engineers create and monitor their software',
url: '/newrelic',
image: 'https://i.imgur.com/L37ikrX.jpg',
tags: ['newrelic', 'performance', 'monitoring', 'errors', 'alerting'],
},
{
title: 'CircleCI',
description:
'Provides builds overview, detailed build info and retriggering functionality for CircleCI.',
url: '/circleci',
image: 'https://miro.medium.com/max/1200/1*hkTBp22vLAqlIHkrkZHPnw.png',
tags: ['circleci', 'ci', 'dev'],
},
{
title: 'Sentry',
description:
'Self-hosted and cloud-based error monitoring that helps software teams discover, triage, and prioritize errors in real-time.',
url: '/sentry',
image: 'https://sentry-brand.storage.googleapis.com/sentry-logo-black.png',
tags: ['sentry', 'monitoring', 'errors'],
},
{
title: 'Lighthouse',
description:
"Google's Lighthouse tool is a great resource for benchmarking and improving the accessibility, performance, SEO, and best practices of your website.",
url: '/lighthouse',
image:
'https://raw.githubusercontent.com/GoogleChrome/lighthouse/8b3d7f052b2e64dd857e741d7395647f487697e7/assets/lighthouse-logo.png',
tags: ['web', 'seo', 'accessibility', 'performance'],
},
{
title: 'Tech Radar',
description:
'Tech Radar is a list of technologies, complemented by an assessment result, called ring assignment.',
url: '/tech-radar',
image:
'https://storage.googleapis.com/wf-blogs-engineering-media/2018/09/fe13bb32-wf-tech-radar-hero-1024x597.png',
tags: ['standards', 'landscape'],
},
{
title: 'Cost Insights',
description: 'Insights into cloud costs for your organization.',
url: '/cost-insights',
image: 'https://cloud.google.com/images/press/logo-cloud.png',
tags: ['cloud', 'finops'],
},
{
title: 'GraphiQL',
description:
'Integrates GraphiQL as a tool to browse GraphiQL endpoints inside Backstage.',
url: '/graphiql',
image:
'https://camo.githubusercontent.com/517398c3fbe0687d3d4dcbe05da82970b882e75a/68747470733a2f2f64337676366c703535716a6171632e636c6f756466726f6e742e6e65742f6974656d732f33413061324e314c3346324f304c3377326e316a2f477261706869514c382e706e673f582d436c6f75644170702d56697369746f722d49643d3433363432',
tags: ['graphql', 'dev'],
},
{
title: 'GitOps Clusters',
description:
'Create GitOps-managed clusters with Backstage. Currently supports EKS flavors and profiles like Machine Learning Ops (MLOps)',
url: '/gitops-clusters',
image: 'https://miro.medium.com/max/801/1*R28u8gj-hVdDFISoYqPhrQ.png',
tags: ['gitops', 'dev'],
},
{
title: 'Rollbar',
description:
'Error monitoring and crash reporting for agile development and continuous delivery',
url: '/rollbar',
image:
'https://images.ctfassets.net/cj4mgtttlyx7/4DfiWj9CbuHBi10uWK7JHn/5e94a6c5dbd5d50bdcd8d9e78f88689b/rollbar-seo.png',
tags: ['rollbar', 'monitoring', 'errors'],
},
];
plugins/explore-backend/src/index.ts
+30
View File
@@ -0,0 +1,30 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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.
*/
/**
* A Backstage plugin for building an exploration page of your software ecosystem
*
* @packageDocumentation
*/
export * from './search';
export * from './service';
export * from './tools';
/**
* @internal Example only - do not use in production
*/
export { exampleTools } from './example/exampleTools';
plugins/explore-backend/src/run.ts
+33
View File
@@ -0,0 +1,33 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { getRootLogger } from '@backstage/backend-common';
import yn from 'yn';
import { startStandaloneServer } from './service/standaloneServer';
const port = process.env.PLUGIN_PORT ? Number(process.env.PLUGIN_PORT) : 7007;
const enableCors = yn(process.env.PLUGIN_CORS, { default: false });
const logger = getRootLogger();
startStandaloneServer({ port, enableCors, logger }).catch(err => {
logger.error(err);
process.exit(1);
});
process.on('SIGINT', () => {
logger.info('CTRL+C pressed; exiting.');
process.exit(0);
});
plugins/explore-backend/src/search/ToolDocumentCollatorFactory.ts
+101
View File
@@ -0,0 +1,101 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { PluginEndpointDiscovery } from '@backstage/backend-common';
import { Config } from '@backstage/config';
import { ExploreTool } from '@backstage/plugin-explore-common';
import {
DocumentCollatorFactory,
IndexableDocument,
} from '@backstage/plugin-search-common';
import fetch from 'node-fetch';
import { Readable } from 'stream';
import { Logger } from 'winston';
/**
* Extended IndexableDocument with explore tool specific properties
*
* @public
*/
export interface ToolDocument extends IndexableDocument, ExploreTool {}
/**
* The options for the {@link ToolDocumentCollatorFactory}.
*
* @public
*/
export type ToolDocumentCollatorFactoryOptions = {
discovery: PluginEndpointDiscovery;
logger: Logger;
};
/**
* Search collator responsible for collecting explore tools to index.
*
* @public
*/
export class ToolDocumentCollatorFactory implements DocumentCollatorFactory {
public readonly type: string = 'tools';
private readonly discovery: PluginEndpointDiscovery;
private readonly logger: Logger;
private constructor(options: ToolDocumentCollatorFactoryOptions) {
this.discovery = options.discovery;
this.logger = options.logger;
}
static fromConfig(
_config: Config,
options: ToolDocumentCollatorFactoryOptions,
) {
return new ToolDocumentCollatorFactory(options);
}
async getCollator() {
return Readable.from(this.execute());
}
async *execute(): AsyncGenerator<ToolDocument> {
this.logger.info('Starting collation of explore tools');
const tools = await this.fetchTools();
for (const tool of tools) {
yield {
...tool,
text: tool.description,
location: tool.url,
};
}
this.logger.info('Finished collation of explore tools');
}
private async fetchTools() {
const baseUrl = await this.discovery.getBaseUrl('explore');
const response = await fetch(`${baseUrl}/tools`);
if (!response.ok) {
throw new Error(
`Failed to explore fetch tools, ${response.status}: ${response.statusText}`,
);
}
const data = await response.json();
return data.tools;
}
}
plugins/explore-backend/src/search/index.ts
+21
View File
@@ -0,0 +1,21 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { ToolDocumentCollatorFactory } from './ToolDocumentCollatorFactory';
export type {
ToolDocument,
ToolDocumentCollatorFactoryOptions,
} from './ToolDocumentCollatorFactory';
plugins/explore-backend/src/service/index.ts
+18
View File
@@ -0,0 +1,18 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { createRouter } from './router';
export type { RouterOptions } from './router';
plugins/explore-backend/src/service/router.test.ts
+65
View File
@@ -0,0 +1,65 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { getVoidLogger } from '@backstage/backend-common';
import {
ExploreTool,
GetExploreToolsRequest,
} from '@backstage/plugin-explore-common';
import express from 'express';
import request from 'supertest';
import { ExploreToolProvider } from '../tools';
import { createRouter } from './router';
const mockTools: ExploreTool[] = [
{ title: 'Tool 1', url: 'https://example.com/tool1', image: '' },
{ title: 'Tool 2', url: 'https://example.com/tool2', image: '' },
{ title: 'Tool 3', url: 'https://example.com/tool2', image: '' },
];
describe('createRouter', () => {
let app: express.Express;
const toolProvider: ExploreToolProvider = {
getTools: async ({}: GetExploreToolsRequest) => {
return {
tools: mockTools,
};
},
};
beforeAll(async () => {
const router = await createRouter({
logger: getVoidLogger(),
toolProvider,
});
app = express().use(router);
});
beforeEach(() => {
jest.resetAllMocks();
});
describe('GET /tools', () => {
it('returns ok', async () => {
const response = await request(app).get('/tools');
expect(response.status).toEqual(200);
expect(response.body).toEqual(
expect.objectContaining({ tools: mockTools }),
);
});
});
});
plugins/explore-backend/src/service/router.ts
+65
View File
@@ -0,0 +1,65 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { errorHandler } from '@backstage/backend-common';
import { GetExploreToolsRequest } from '@backstage/plugin-explore-common';
import express from 'express';
import Router from 'express-promise-router';
import { Logger } from 'winston';
import { ExploreToolProvider } from '../tools';
/**
* @public
*/
export interface RouterOptions {
logger: Logger;
toolProvider: ExploreToolProvider;
}
/**
* @public
*/
export async function createRouter(
options: RouterOptions,
): Promise<express.Router> {
const { toolProvider } = options;
const router = Router();
router.use(express.json());
router.get('/tools', async (request, response) => {
const requestQuery = parseExploreToolRequestQuery(request.query);
const result = await toolProvider.getTools(requestQuery);
response.json(result);
});
router.use(errorHandler());
return router;
}
function parseExploreToolRequestQuery(
params: Record<string, unknown>,
): GetExploreToolsRequest {
// TODO: Implement proper query parsing for the filters
// Also consider using a `filter` query string like catalog client does
return {
filter: {
tags: [...[(params?.tag as any) ?? []]].flat(),
lifecycle: [...[(params?.lifecycle as any) ?? []]].flat(),
},
};
}
plugins/explore-backend/src/service/standaloneServer.ts
+67
View File
@@ -0,0 +1,67 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { createServiceBuilder } from '@backstage/backend-common';
import { GetExploreToolsRequest } from '@backstage/plugin-explore-common';
import { Server } from 'http';
import { Logger } from 'winston';
import { createRouter } from './router';
export interface ServerOptions {
port: number;
enableCors: boolean;
logger: Logger;
}
export async function startStandaloneServer(
options: ServerOptions,
): Promise<Server> {
const logger = options.logger.child({
service: 'explore-backend',
});
logger.debug('Starting application server...');
const router = await createRouter({
logger,
toolProvider: {
getTools: async ({}: GetExploreToolsRequest) => {
return {
filter: undefined,
tools: [
{ title: 'Tool 1', url: 'https://example.com/tool1', image: '' },
{ title: 'Tool 2', url: 'https://example.com/tool2', image: '' },
{ title: 'Tool 3', url: 'https://example.com/tool2', image: '' },
],
};
},
},
});
let service = createServiceBuilder(module)
.setPort(options.port)
.addRouter('/explore-backend', router);
if (options.enableCors) {
service = service.enableCors({ origin: 'http://localhost:3000' });
}
return await service.start().catch(err => {
logger.error(err);
process.exit(1);
});
}
module.hot?.accept();
plugins/explore-backend/src/setupTests.ts
+17
View File
@@ -0,0 +1,17 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 {};
plugins/explore-backend/src/tools/index.ts
+18
View File
@@ -0,0 +1,18 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { StaticExploreToolProvider } from './providers/StaticExploreToolProvider';
export * from './types';
plugins/explore-backend/src/tools/providers/StaticExploreToolProvider.test.ts
+85
View File
@@ -0,0 +1,85 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { ExploreTool } from '@backstage/plugin-explore-common';
import { StaticExploreToolProvider } from './StaticExploreToolProvider';
describe('StaticExploreToolProvider', () => {
const tool1: ExploreTool = {
title: 'Tool 1',
image: 'https://example/image.png',
url: 'https://example.com',
lifecycle: 'production',
tags: ['tag1', 'tag2'],
};
const tool2: ExploreTool = {
...tool1,
title: 'Tool 2',
lifecycle: 'production',
tags: ['tag1'],
};
const tool3: ExploreTool = {
...tool1,
title: 'Tool 3',
lifecycle: 'experimental',
tags: ['tag2'],
};
const allTools: ExploreTool[] = [tool1, tool2, tool3];
describe('getTools', () => {
it('returns a list of all tools', async () => {
const provider = StaticExploreToolProvider.fromData(allTools);
await expect(provider.getTools({})).resolves.toEqual({
tools: allTools,
});
});
it.each([
[['tag1'], [tool1, tool2]],
[['tag2'], [tool1, tool3]],
[[], allTools],
])(
'returns % when filtered by tags %',
async (tagFilter, expectedTools) => {
const provider = StaticExploreToolProvider.fromData(allTools);
await expect(
provider.getTools({ filter: { tags: tagFilter } }),
).resolves.toEqual({
tools: expectedTools,
});
},
);
it.each([
[['production'], [tool1, tool2]],
[['experimental'], [tool3]],
[[], allTools],
])(
'returns % when filtered by lifecycle %',
async (lifecycleFilter, expectedTools) => {
const provider = StaticExploreToolProvider.fromData(allTools);
await expect(
provider.getTools({ filter: { lifecycle: lifecycleFilter } }),
).resolves.toEqual({
tools: expectedTools,
});
},
);
});
});
plugins/explore-backend/src/tools/providers/StaticExploreToolProvider.ts
+59
View File
@@ -0,0 +1,59 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 {
ExploreTool,
GetExploreToolsRequest,
GetExploreToolsResponse,
} from '@backstage/plugin-explore-common';
import { intersection, isEmpty } from 'lodash';
import { ExploreToolProvider } from '../types';
const anyOf = <T>(prop: T | T[], matches: T[]) =>
isEmpty(matches)
? true
: intersection([...[prop]].flat(), matches)?.length > 0;
/**
* A basic ExploreToolProvider implementation using static data.
*
* @public
*/
export class StaticExploreToolProvider implements ExploreToolProvider {
private readonly tools: ExploreTool[];
static fromData(tools: ExploreTool[]) {
return new StaticExploreToolProvider(tools);
}
private constructor(tools: ExploreTool[]) {
this.tools = tools;
}
async getTools(
request: GetExploreToolsRequest,
): Promise<GetExploreToolsResponse> {
const { filter } = request ?? {};
const tags = filter?.tags ?? [];
const lifecycles = filter?.lifecycle ?? [];
const tools = this.tools.filter(
t => anyOf(t.tags ?? [], tags) && anyOf(t.lifecycle ?? [], lifecycles),
);
return { tools };
}
}
plugins/explore-backend/src/tools/types.ts
+33
View File
@@ -0,0 +1,33 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 {
GetExploreToolsRequest,
GetExploreToolsResponse,
} from '@backstage/plugin-explore-common';
/**
* @public
*/
export interface ExploreToolProvider {
/**
* Gets a list of explore tools filtered by the request options.
*
* @param request - The request options {@link @backstage/plugin-explore-common#GetExploreToolsRequest}.
* @returns The response {@link @backstage/plugin-explore-common#GetExploreToolsResponse}.
*/
getTools(request: GetExploreToolsRequest): Promise<GetExploreToolsResponse>;
}
plugins/explore-common/.eslintrc.js
+1
View File
@@ -0,0 +1 @@
module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);
plugins/explore-common/README.md
+3
View File
@@ -0,0 +1,3 @@
# explore-common
Shared types for the `explore` plugin.
plugins/explore-common/api-report.md
+31
View File
@@ -0,0 +1,31 @@
## API Report File for "@backstage/plugin-explore-common"
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
```ts
// @public (undocumented)
export type ExploreTool = {
title: string;
description?: string;
url: string;
image: string;
tags?: string[];
lifecycle?: string;
};
// @public (undocumented)
export type ExploreToolFilter = {
tags?: string[];
lifecycle?: string[];
};
// @public (undocumented)
export type GetExploreToolsRequest = {
filter?: ExploreToolFilter;
};
// @public (undocumented)
export type GetExploreToolsResponse = {
tools: ExploreTool[];
};
```
plugins/explore-common/package.json
+39
View File
@@ -0,0 +1,39 @@
{
"name": "@backstage/plugin-explore-common",
"description": "Common functionalities for the explore plugin",
"version": "0.0.0",
"main": "src/index.ts",
"types": "src/index.ts",
"license": "Apache-2.0",
"publishConfig": {
"access": "public",
"main": "dist/index.cjs.js",
"types": "dist/index.d.ts"
},
"backstage": {
"role": "common-library"
},
"homepage": "https://backstage.io",
"repository": {
"type": "git",
"url": "https://github.com/backstage/backstage",
"directory": "plugins/explore-common"
},
"keywords": [
"backstage"
],
"scripts": {
"build": "backstage-cli package build",
"lint": "backstage-cli package lint",
"test": "backstage-cli package test",
"clean": "backstage-cli package clean",
"prepack": "backstage-cli package prepack",
"postpack": "backstage-cli package postpack"
},
"devDependencies": {
"@backstage/cli": "workspace:^"
},
"files": [
"dist"
]
}
plugins/explore-common/src/index.ts
+23
View File
@@ -0,0 +1,23 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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.
*/
/**
* Common functionalities for the explore plugin.
*
* @packageDocumentation
*/
export * from './tools';
plugins/explore-common/src/tools/api.ts
+46
View File
@@ -0,0 +1,46 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { ExploreTool } from './types';
/**
* @public
*/
export type ExploreToolFilter = {
/**
* Filter by a list of tags
*/
tags?: string[];
/**
* Filter by a list of lifecycle strings
*/
lifecycle?: string[];
};
/**
* @public
*/
export type GetExploreToolsRequest = {
filter?: ExploreToolFilter;
};
/**
* @public
*/
export type GetExploreToolsResponse = {
tools: ExploreTool[];
};
plugins/explore-common/src/tools/index.ts
+24
View File
@@ -0,0 +1,24 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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.
*/
/**
* Common functionalities for the explore plugin.
*
* @packageDocumentation
*/
export * from './api';
export * from './types';
plugins/explore-common/src/tools/types.ts
+27
View File
@@ -0,0 +1,27 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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.
*/
/**
* @public
*/
export type ExploreTool = {
title: string;
description?: string;
url: string;
image: string;
tags?: string[];
lifecycle?: string;
};
plugins/explore-react/api-report.md
+5 -11
View File
@@ -4,23 +4,17 @@
```ts
import { ApiRef } from '@backstage/core-plugin-api';
import * as common from '@backstage/plugin-explore-common';
// @public (undocumented)
export type ExploreTool = {
title: string;
description?: string;
url: string;
image: string;
tags?: string[];
lifecycle?: string;
};
// @public @deprecated (undocumented)
export type ExploreTool = common.ExploreTool;
// @public (undocumented)
// @public @deprecated (undocumented)
export interface ExploreToolsConfig {
// (undocumented)
getTools: () => Promise<ExploreTool[]>;
}
// @public (undocumented)
// @public @deprecated (undocumented)
export const exploreToolsConfigRef: ApiRef<ExploreToolsConfig>;
```
plugins/explore-react/package.json
+2 -1
View File
@@ -32,7 +32,8 @@
"start": "backstage-cli package start"
},
"dependencies": {
"@backstage/core-plugin-api": "workspace:^"
"@backstage/core-plugin-api": "workspace:^",
"@backstage/plugin-explore-common": "workspace:^"
},
"devDependencies": {
"@backstage/cli": "workspace:^",
plugins/explore-react/src/tools/api.ts
+19 -12
View File
@@ -16,22 +16,29 @@
import { createApiRef } from '@backstage/core-plugin-api';
/** @public */
/**
* Deprecated types moved to `@backstage/plugin-explore-common`
*/
import * as common from '@backstage/plugin-explore-common';
/**
* @deprecated Use ExploreTool from `@backstage/plugin-explore-common`
* @public
*/
export type ExploreTool = common.ExploreTool;
/**
* @deprecated Use exploreApiRef from `@backstage/plugin-explore` & the `@backstage/plugin-explore-backend`
* @public
*/
export const exploreToolsConfigRef = createApiRef<ExploreToolsConfig>({
id: 'plugin.explore.toolsconfig',
});
/** @public */
export type ExploreTool = {
title: string;
description?: string;
url: string;
image: string;
tags?: string[];
lifecycle?: string;
};
/** @public */
/**
* @deprecated Use ExploreApi from `@backstage/plugin-explore` & the `@backstage/plugin-explore-backend`
* @public
*/
export interface ExploreToolsConfig {
getTools: () => Promise<ExploreTool[]>;
}
plugins/explore/README.md
+82 -55
View File
@@ -1,42 +1,105 @@
# explore
Welcome to the explore plugin!
This plugin helps to visualize the domains and tools in your ecosystem.
## Getting started
## Setup
To install the plugin, add and bind the route in `App.tsx`:
The following sections will help you get the Explore plugin setup and running.
```typescript
import { ExplorePage, explorePlugin } from '@backstage/plugin-explore';
### Backend
...
You need to setup the
[Explore backend plugin](https://github.com/backstage/backstage/tree/master/plugins/explore-backend)
before you move forward with any of these steps if you haven't already.
bindRoutes({ bind }) {
...
bind(explorePlugin.externalRoutes, {
catalogEntity: catalogPlugin.routes.catalogEntity,
});
},
### Installation
...
Install this plugin:
<Route path="/explore" element={<ExplorePage />} />
```bash
# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-explore
```
And add a link to the sidebar in `Root.tsx`:
### Add the plugin to your `packages/app`
```typescript
import LayersIcon from '@material-ui/icons/Layers';
Add the root page that the playlist plugin provides to your app. You can choose
any path for the route, but we recommend the following:
```diff
// packages/app/src/App.tsx
+ import { ExplorePage, explorePlugin } from '@backstage/plugin-explore';
...
<SidebarItem icon={LayersIcon} to="explore" text="Explore" />
<FlatRoutes>
<Route path="/catalog" element={<CatalogIndexPage />} />
<Route path="/catalog/:namespace/:kind/:name" element={<CatalogEntityPage />}>
{entityPage}
</Route>
+ <Route path="/explore" element={<ExplorePage />} />
...
</FlatRoutes>
```
You may also want to add a link to the playlist page to your application
sidebar:
```diff
// packages/app/src/components/Root/Root.tsx
+import LayersIcon from '@material-ui/icons/Layers';
export const Root = ({ children }: PropsWithChildren<{}>) => (
<SidebarPage>
<Sidebar>
+ <SidebarItem icon={LayersIcon} to="explore" text="Explore" />
...
</Sidebar>
```
### Use search result list item for Explore Tools
When you have your `packages/app/src/components/search/SearchPage.tsx` file
ready to make modifications, add the following code snippet to add the
`ToolSearchResultListItem` when the type of the search results are
`tool`.
```diff
+import { ToolSearchResultListItem } from '@backstage/plugin-explore';
const SearchPage = () => {
...
<SearchResult>
{({ results }) => (
<List>
{results.map(({ type, document, highlight, rank }) => {
switch (type) {
...
+ case 'tools':
+ return (
+ <ToolSearchResultListItem
+ icon={<BuildIcon />}
+ key={document.location}
+ result={document}
+ highlight={highlight}
+ rank={rank}
+ />
+ );
}
})}
</List>
)}
...
</SearchResult>
...
```
## Customization
Create a custom explore page in `packages/app/src/components/explore/ExplorePage.tsx`.
Create a custom explore page in
`packages/app/src/components/explore/ExplorePage.tsx`.
```tsx
import {
@@ -68,7 +131,7 @@ export const explorePage = <ExplorePage />;
Now register the new explore page in `packages/app/src/App.tsx`.
```diff
+ import { explorePage } from './components/explore/ExplorePage';
+import { explorePage } from './components/explore/ExplorePage';
const routes = (
<FlatRoutes>
@@ -79,39 +142,3 @@ const routes = (
</FlatRoutes>
);
```
## ToolExplorer Content Customization
Override the `exploreToolsConfigRef` API in `/packages/app/src/apis.ts`.
```tsx
import { exploreToolsConfigRef } from '@backstage/plugin-explore-react';
export const apis: AnyApiFactory[] = [
...
createApiFactory({
api: exploreToolsConfigRef,
deps: {},
factory: () => ({
async getTools() {
return tools;
},
/* e.g. tools = [
{
title: 'New Relic',
description:'new relic plugin,
url: '/newrelic',
image: 'https://i.imgur.com/L37ikrX.jpg',
tags: ['newrelic', 'proxy', 'nerdGraph'],
},
]
*/
}),
}),
....
];
```
plugins/explore/api-report.md
+49
View File
@@ -5,10 +5,19 @@
```ts
/// <reference types="react" />
import { ApiRef } from '@backstage/core-plugin-api';
import { BackstagePlugin } from '@backstage/core-plugin-api';
import { default as default_2 } from 'react';
import { DiscoveryApi } from '@backstage/core-plugin-api';
import { DomainEntity } from '@backstage/catalog-model';
import { ExploreToolsConfig } from '@backstage/plugin-explore-react';
import { ExternalRouteRef } from '@backstage/core-plugin-api';
import { FetchApi } from '@backstage/core-plugin-api';
import { GetExploreToolsRequest } from '@backstage/plugin-explore-common';
import { GetExploreToolsResponse } from '@backstage/plugin-explore-common';
import { IndexableDocument } from '@backstage/plugin-search-common';
import { ReactNode } from 'react';
import { ResultHighlight } from '@backstage/plugin-search-common';
import { RouteRef } from '@backstage/core-plugin-api';
import { TabProps } from '@material-ui/core';
@@ -30,6 +39,29 @@ export const DomainExplorerContent: (props: {
title?: string | undefined;
}) => JSX.Element;
// @public
export interface ExploreApi {
getTools(request?: GetExploreToolsRequest): Promise<GetExploreToolsResponse>;
}
// @public (undocumented)
export const exploreApiRef: ApiRef<ExploreApi>;
// @public
export class ExploreClient implements ExploreApi {
constructor({
discoveryApi,
fetchApi,
exploreToolsConfig,
}: {
discoveryApi: DiscoveryApi;
fetchApi: FetchApi;
exploreToolsConfig?: ExploreToolsConfig;
});
// (undocumented)
getTools(request?: GetExploreToolsRequest): Promise<GetExploreToolsResponse>;
}
// @public
export const ExploreLayout: {
(props: ExploreLayoutProps): JSX.Element;
@@ -91,4 +123,21 @@ export type SubRoute = {
export const ToolExplorerContent: (props: {
title?: string | undefined;
}) => JSX.Element;
// @public (undocumented)
export function ToolSearchResultListItem(
props: ToolSearchResultListItemProps,
): JSX.Element;
// @public
export interface ToolSearchResultListItemProps {
// (undocumented)
highlight?: ResultHighlight;
// (undocumented)
icon?: ReactNode;
// (undocumented)
rank?: number;
// (undocumented)
result: IndexableDocument;
}
```
plugins/explore/package.json
+4
View File
@@ -35,8 +35,12 @@
"@backstage/catalog-model": "workspace:^",
"@backstage/core-components": "workspace:^",
"@backstage/core-plugin-api": "workspace:^",
"@backstage/errors": "workspace:^",
"@backstage/plugin-catalog-react": "workspace:^",
"@backstage/plugin-explore-common": "workspace:^",
"@backstage/plugin-explore-react": "workspace:^",
"@backstage/plugin-search-common": "workspace:^",
"@backstage/plugin-search-react": "workspace:^",
"@backstage/theme": "workspace:^",
"@material-ui/core": "^4.12.2",
"@material-ui/icons": "^4.9.1",
plugins/explore/src/api/ExploreApi.ts
+42
View File
@@ -0,0 +1,42 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { createApiRef } from '@backstage/core-plugin-api';
import {
GetExploreToolsRequest,
GetExploreToolsResponse,
} from '@backstage/plugin-explore-common';
/**
* Interface for the explore plugin.
*
* @public
*/
export interface ExploreApi {
/**
* Returns a list of explore tools.
*
* @param request - The The request query options
*/
getTools(request?: GetExploreToolsRequest): Promise<GetExploreToolsResponse>;
}
/**
* @public
*/
export const exploreApiRef = createApiRef<ExploreApi>({
id: 'plugin.explore.service',
});
plugins/explore/src/api/ExploreClient.test.ts
+114
View File
@@ -0,0 +1,114 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 {
ExploreTool,
GetExploreToolsResponse,
} from '@backstage/plugin-explore-common';
import { MockFetchApi, setupRequestMockHandlers } from '@backstage/test-utils';
import { rest } from 'msw';
import { setupServer } from 'msw/node';
import { ExploreClient } from './ExploreClient';
const server = setupServer();
describe('ExploreClient', () => {
setupRequestMockHandlers(server);
const mockBaseUrl = 'http://backstage/api/explore';
const discoveryApi = { getBaseUrl: async () => mockBaseUrl };
const fetchApi = new MockFetchApi();
let client: ExploreClient;
beforeEach(() => {
client = new ExploreClient({ discoveryApi, fetchApi });
});
describe('getTools', () => {
const mockTools: ExploreTool[] = [
{
title: 'Tool 1',
image: 'https://example.com/image.png',
url: 'https://example.com',
},
{
title: 'Tool 2',
image: 'https://example.com/image.png',
url: 'https://example.com',
},
];
it('should fetch data from the explore-backend', async () => {
const expectedResponse: GetExploreToolsResponse = {
tools: mockTools,
};
server.use(
rest.get(`${mockBaseUrl}/tools`, (_, res, ctx) =>
res(ctx.json(expectedResponse)),
),
);
const response = await client.getTools();
expect(response).toEqual(expectedResponse);
});
it('should request explore tools with specific filters', async () => {
const expectedResponse: GetExploreToolsResponse = {
tools: mockTools,
};
server.use(
rest.get(`${mockBaseUrl}/tools`, (req, res, ctx) => {
expect(req.url.search).toBe('?tag=a&tag=b&lifecycle=alpha');
return res(ctx.json(expectedResponse));
}),
);
const response = await client.getTools({
filter: { tags: ['a', 'b'], lifecycle: ['alpha'] },
});
expect(response).toEqual(expectedResponse);
});
});
describe('when using exploreToolsConfig for backwards compatibility', () => {
const mockExploreToolsConfig = {
getTools: jest.fn(),
};
beforeEach(() => {
client = new ExploreClient({
discoveryApi,
fetchApi,
exploreToolsConfig: mockExploreToolsConfig,
});
});
it('should return data from the deprecated api', async () => {
mockExploreToolsConfig.getTools.mockResolvedValue([
{
title: 'Some Tool',
image: 'https://example.com/image.png',
url: 'https://example.com',
},
]);
await client.getTools();
expect(mockExploreToolsConfig.getTools).toHaveBeenCalled();
});
});
});
plugins/explore/src/api/ExploreClient.ts
+84
View File
@@ -0,0 +1,84 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { DiscoveryApi, FetchApi } from '@backstage/core-plugin-api';
import { ResponseError } from '@backstage/errors';
import {
GetExploreToolsRequest,
GetExploreToolsResponse,
} from '@backstage/plugin-explore-common';
import { ExploreToolsConfig } from '@backstage/plugin-explore-react';
import { ExploreApi } from './ExploreApi';
/**
* Default implementation of the ExploreApi.
*
* @public
*/
export class ExploreClient implements ExploreApi {
private readonly discoveryApi: DiscoveryApi;
private readonly fetchApi: FetchApi;
// NOTE: This will be removed in the future as it is replaced by the ExploreApi.getTools method
private readonly exploreToolsConfig: ExploreToolsConfig | undefined;
/**
* @remarks The exploreToolsConfig is for backwards compatibility with the exporeToolsConfigRef
* and will be removed in the future.
*/
constructor({
discoveryApi,
fetchApi,
exploreToolsConfig = undefined,
}: {
discoveryApi: DiscoveryApi;
fetchApi: FetchApi;
exploreToolsConfig?: ExploreToolsConfig;
}) {
this.discoveryApi = discoveryApi;
this.fetchApi = fetchApi;
this.exploreToolsConfig = exploreToolsConfig;
}
async getTools(
request: GetExploreToolsRequest = {},
): Promise<GetExploreToolsResponse> {
// NOTE: This will be removed in the future as it is replaced by the ExploreApi.getTools method
if (this.exploreToolsConfig) {
const tools = await this.exploreToolsConfig.getTools();
if (tools) {
return { tools };
}
}
const { fetch } = this.fetchApi;
const filter = request.filter ?? {};
const baseUrl = await this.discoveryApi.getBaseUrl('explore');
const tags = filter?.tags?.map(t => `tag=${encodeURIComponent(t)}`) ?? [];
const lifecycles =
filter?.lifecycle?.map(l => `lifecycle=${encodeURIComponent(l)}`) ?? [];
const query = [...tags, ...lifecycles].join('&');
const response = await fetch(`${baseUrl}/tools?${query}`);
if (!response.ok) {
throw await ResponseError.fromResponse(response);
}
return response.json() as Promise<GetExploreToolsResponse>;
}
}
plugins/explore/src/api/index.ts
+19
View File
@@ -0,0 +1,19 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 { ExploreClient } from './ExploreClient';
export { exploreApiRef } from './ExploreApi';
export type { ExploreApi } from './ExploreApi';
plugins/explore/src/components/ToolExplorerContent/ToolExplorerContent.test.tsx
+7 -9
View File
@@ -14,25 +14,23 @@
* limitations under the License.
*/
import {
ExploreTool,
exploreToolsConfigRef,
} from '@backstage/plugin-explore-react';
import { ExploreTool } from '@backstage/plugin-explore-common';
import { renderInTestApp, TestApiProvider } from '@backstage/test-utils';
import { lightTheme } from '@backstage/theme';
import { ThemeProvider } from '@material-ui/core';
import { waitFor } from '@testing-library/react';
import React from 'react';
import { exploreApiRef } from '../../api';
import { ToolExplorerContent } from './ToolExplorerContent';
describe('<ToolExplorerContent />', () => {
const exploreToolsConfigApi: jest.Mocked<typeof exploreToolsConfigRef.T> = {
const exploreApi: jest.Mocked<typeof exploreApiRef.T> = {
getTools: jest.fn(),
};
const Wrapper = ({ children }: { children?: React.ReactNode }) => (
<ThemeProvider theme={lightTheme}>
<TestApiProvider apis={[[exploreToolsConfigRef, exploreToolsConfigApi]]}>
<TestApiProvider apis={[[exploreApiRef, exploreApi]]}>
{children}
</TestApiProvider>
</ThemeProvider>
@@ -63,7 +61,7 @@ describe('<ToolExplorerContent />', () => {
tags: ['standards', 'landscape'],
},
];
exploreToolsConfigApi.getTools.mockResolvedValue(tools);
exploreApi.getTools.mockResolvedValue({ tools });
const { getByText } = await renderInTestApp(
<Wrapper>
@@ -78,7 +76,7 @@ describe('<ToolExplorerContent />', () => {
});
it('renders a custom title', async () => {
exploreToolsConfigApi.getTools.mockResolvedValue([]);
exploreApi.getTools.mockResolvedValue({ tools: [] });
const { getByText } = await renderInTestApp(
<Wrapper>
@@ -90,7 +88,7 @@ describe('<ToolExplorerContent />', () => {
});
it('renders empty state', async () => {
exploreToolsConfigApi.getTools.mockResolvedValue([]);
exploreApi.getTools.mockResolvedValue({ tools: [] });
const { getByText } = await renderInTestApp(
<Wrapper>
plugins/explore/src/components/ToolExplorerContent/ToolExplorerContent.tsx
+5 -4
View File
@@ -14,7 +14,6 @@
* limitations under the License.
*/
import { exploreToolsConfigRef } from '@backstage/plugin-explore-react';
import React from 'react';
import useAsync from 'react-use/lib/useAsync';
import { ToolCard } from '../ToolCard';
@@ -28,16 +27,18 @@ import {
WarningPanel,
} from '@backstage/core-components';
import { useApi } from '@backstage/core-plugin-api';
import { exploreApiRef } from '../../api';
const Body = () => {
const exploreToolsConfigApi = useApi(exploreToolsConfigRef);
const exploreApi = useApi(exploreApiRef);
const {
value: tools,
loading,
error,
} = useAsync(async () => {
return await exploreToolsConfigApi.getTools();
}, [exploreToolsConfigApi]);
return (await exploreApi.getTools())?.tools;
}, [exploreApi]);
if (loading) {
return <Progress />;
plugins/explore/src/components/ToolSearchResultListItem/ToolSearchResultListItem.tsx
+113
View File
@@ -0,0 +1,113 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 React, { ReactNode } from 'react';
import {
Box,
Chip,
Divider,
ListItem,
ListItemIcon,
ListItemText,
makeStyles,
} from '@material-ui/core';
import { Link } from '@backstage/core-components';
import { useAnalytics } from '@backstage/core-plugin-api';
import {
IndexableDocument,
ResultHighlight,
} from '@backstage/plugin-search-common';
import { HighlightedSearchResultText } from '@backstage/plugin-search-react';
const useStyles = makeStyles({
flexContainer: {
flexWrap: 'wrap',
},
itemText: {
width: '100%',
wordBreak: 'break-all',
marginBottom: '1rem',
},
});
/**
* Props for {@link ToolSearchResultListItem}.
*
* @public
*/
export interface ToolSearchResultListItemProps {
icon?: ReactNode;
result: IndexableDocument;
highlight?: ResultHighlight;
rank?: number;
}
/** @public */
export function ToolSearchResultListItem(props: ToolSearchResultListItemProps) {
const result = props.result as any;
const classes = useStyles();
const analytics = useAnalytics();
const handleClick = () => {
analytics.captureEvent('discover', result.title, {
attributes: { to: result.location },
value: props.rank,
});
};
return (
<Link noTrack to={result.location} onClick={handleClick}>
<ListItem alignItems="flex-start">
{props.icon && <ListItemIcon>{props.icon}</ListItemIcon>}
<div className={classes.flexContainer}>
<ListItemText
className={classes.itemText}
primaryTypographyProps={{ variant: 'h6' }}
primary={
props.highlight?.fields.title ? (
<HighlightedSearchResultText
text={props.highlight.fields.title}
preTag={props.highlight.preTag}
postTag={props.highlight.postTag}
/>
) : (
result.title
)
}
secondary={
props.highlight?.fields.text ? (
<HighlightedSearchResultText
text={props.highlight.fields.text}
preTag={props.highlight.preTag}
postTag={props.highlight.postTag}
/>
) : (
result.text
)
}
/>
<Box>
{result.tags &&
result.tags.map((tag: string) => (
<Chip label={tag} size="small" />
))}
</Box>
</div>
</ListItem>
<Divider component="li" />
</Link>
);
}
plugins/explore/src/components/ToolSearchResultListItem/index.ts
+17
View File
@@ -0,0 +1,17 @@
/*
* Copyright 2022 The Backstage Authors
*
* 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 * from './ToolSearchResultListItem';
plugins/explore/src/components/index.ts
+1
View File
@@ -16,3 +16,4 @@
export * from './DomainCard';
export * from './ExploreLayout';
export * from './ToolSearchResultListItem';
plugins/explore/src/index.ts
+1
View File
@@ -20,6 +20,7 @@
* @packageDocumentation
*/
export * from './api';
export * from './components';
export * from './extensions';
export { explorePlugin, explorePlugin as plugin } from './plugin';
plugins/explore/src/plugin.ts
+28 -5
View File
@@ -16,21 +16,44 @@
import { exploreToolsConfigRef } from '@backstage/plugin-explore-react';
import { catalogEntityRouteRef, exploreRouteRef } from './routes';
import { exampleTools } from './util/examples';
import { createApiFactory, createPlugin } from '@backstage/core-plugin-api';
import {
createApiFactory,
createPlugin,
discoveryApiRef,
fetchApiRef,
} from '@backstage/core-plugin-api';
import { ExploreClient, exploreApiRef } from './api';
// import { exampleTools } from './util/examples';
/** @public */
export const explorePlugin = createPlugin({
id: 'explore',
apis: [
// Register a default for exploreToolsConfigRef, you may want to override
// the API locally in your app.
createApiFactory({
api: exploreApiRef,
deps: {
discoveryApi: discoveryApiRef,
fetchApi: fetchApiRef,
exploreToolsConfig: exploreToolsConfigRef,
},
factory: ({ discoveryApi, fetchApi, exploreToolsConfig }) =>
// NOTE: The exploreToolsConfig is for backwards compatibility and will be removed in the future
new ExploreClient({ discoveryApi, fetchApi, exploreToolsConfig }),
}),
/**
* @deprecated Use ExploreApi from `@backstage/plugin-explore` instead
*
* Register a default for exploreToolsConfigRef, you may want to override
* the API locally in your app.
*/
createApiFactory({
api: exploreToolsConfigRef,
deps: {},
factory: () => ({
async getTools() {
return exampleTools;
// Returning `undefined` will enable the explore-backend to be used via the ExploreClient.
// If this API has been customized and returns data it will be respected first.
return undefined as any;
},
}),
}),