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

Move packages/search-common -> plugins/search-common

Browse Source 
Signed-off-by: Eric Peterson <ericpeterson@spotify.com>
This commit is contained in:
Eric Peterson
2022-03-03 16:14:32 +01:00
parent cea6f10b97
commit 6921edc6a0
8 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/search-common/.eslintrc.js
+3
View File
@@ -0,0 +1,3 @@
module.exports = {
extends: [require.resolve('@backstage/cli/config/eslint.backend')],
};
plugins/search-common/CHANGELOG.md
+148
View File
@@ -0,0 +1,148 @@
# @backstage/search-common
## 0.3.0
### Minor Changes
- 022507c860: **BREAKING**
The Backstage Search Platform's indexing process has been rewritten as a stream
pipeline in order to improve efficiency and performance on large document sets.
The concepts of `Collator` and `Decorator` have been replaced with readable and
transform object streams (respectively), as well as factory classes to
instantiate them. Accordingly, the `SearchEngine.index()` method has also been
replaced with a `getIndexer()` factory method that resolves to a writable
object stream.
Check [this upgrade guide](https://backstage.io/docs/features/search/how-to-guides#how-to-migrate-from-search-alpha-to-beta)
for further details.
### Patch Changes
- Updated dependencies
- @backstage/plugin-permission-common@0.5.2
## 0.2.4
### Patch Changes
- Fix for the previous release with missing type declarations.
- Updated dependencies
- @backstage/types@0.1.3
- @backstage/plugin-permission-common@0.5.1
## 0.2.3
### Patch Changes
- c77c5c7eb6: Added `backstage.role` to `package.json`
- Updated dependencies
- @backstage/plugin-permission-common@0.5.0
- @backstage/types@0.1.2
## 0.2.2
### Patch Changes
- 9a511968b1: - Add optional visibilityPermission property to DocumentCollator type
- Add new DocumentTypeInfo type for housing information about the document types stored in a search engine.
- b2e918fa0b: Add optional resourceRef field to the IndexableDocument type for use when authorizing access to documents.
- 96cbebc629: Add optional query request options containing authorization token to SearchEngine#query.
## 0.2.1
### Patch Changes
- 10615525f3: Switch to use the json and observable types from `@backstage/types`
## 0.2.0
### Minor Changes
- a13f21cdc: Implement optional `pageCursor` based paging in search.
To use paging in your app, add a `<SearchResultPager />` to your
`SearchPage.tsx`.
## 0.1.3
### Patch Changes
- d9c13d535: Implements configuration and indexing functionality for ElasticSearch search engine. Adds indexing, searching and default translator for ElasticSearch and modifies default backend example-app to use ES if it is configured.
## Example configurations:
### AWS
Using AWS hosted ElasticSearch the only configuration options needed is the URL to the ElasticSearch service. The implementation assumes
that environment variables for AWS access key id and secret access key are defined in accordance to the [default AWS credential chain.](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html).
```yaml
search:
elasticsearch:
provider: aws
node: https://my-backstage-search-asdfqwerty.eu-west-1.es.amazonaws.com
```
### Elastic.co
Elastic Cloud hosted ElasticSearch uses a Cloud ID to determine the instance of hosted ElasticSearch to connect to. Additionally, username and password needs to be provided either directly or using environment variables like defined in [Backstage documentation.](https://backstage.io/docs/conf/writing#includes-and-dynamic-data)
```yaml
search:
elasticsearch:
provider: elastic
cloudId: backstage-elastic:asdfqwertyasdfqwertyasdfqwertyasdfqwerty==
auth:
username: elastic
password: changeme
```
### Others
Other ElasticSearch instances can be connected to by using standard ElasticSearch authentication methods and exposed URL, provided that the cluster supports that. The configuration options needed are the URL to the node and authentication information. Authentication can be handled by either providing username/password or and API key or a bearer token. In case both username/password combination and one of the tokens are provided, token takes precedence. For more information how to create an API key, see [Elastic documentation on API keys](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html) and how to create a bearer token, see [Elastic documentation on tokens.](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-service-token.html)
#### Configuration examples
##### With username and password
```yaml
search:
elasticsearch:
node: http://localhost:9200
auth:
username: elastic
password: changeme
```
##### With bearer token
```yaml
search:
elasticsearch:
node: http://localhost:9200
auth:
bearer: token
```
##### With API key
```yaml
search:
elasticsearch:
node: http://localhost:9200
auth:
apiKey: base64EncodedKey
```
- Updated dependencies
- @backstage/config@0.1.6
## 0.1.2
### Patch Changes
- db1c8f93b: The `<Search...Next /> set of components exported by the Search Plugin are now updated to use the Search Backend API. These will be made available as the default non-"next" versions in a follow-up release.
The interfaces for decorators and collators in the Search Backend have also seen minor, breaking revisions ahead of a general release. If you happen to be building on top of these interfaces, check and update your implementations accordingly. The APIs will be considered more stable in a follow-up release.
plugins/search-common/README.md
+3
View File
@@ -0,0 +1,3 @@
# @backstage/search-common
Common functionalities for Search, to be shared between various search-enabled plugins.
plugins/search-common/api-report.md
+89
View File
@@ -0,0 +1,89 @@
## API Report File for "@backstage/search-common"
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
```ts
/// <reference types="node" />
import { JsonObject } from '@backstage/types';
import { Permission } from '@backstage/plugin-permission-common';
import { Readable } from 'stream';
import { Transform } from 'stream';
import { Writable } from 'stream';
// @beta
export interface DocumentCollatorFactory {
getCollator(): Promise<Readable>;
readonly type: string;
readonly visibilityPermission?: Permission;
}
// @beta
export interface DocumentDecoratorFactory {
getDecorator(): Promise<Transform>;
readonly types?: string[];
}
// @beta
export type DocumentTypeInfo = {
visibilityPermission?: Permission;
};
// @beta
export interface IndexableDocument {
authorization?: {
resourceRef: string;
};
location: string;
text: string;
title: string;
}
// @beta
export type QueryRequestOptions = {
token?: string;
};
// @beta
export type QueryTranslator = (query: SearchQuery) => unknown;
// @beta
export interface SearchEngine {
getIndexer(type: string): Promise<Writable>;
query(
query: SearchQuery,
options?: QueryRequestOptions,
): Promise<SearchResultSet>;
setTranslator(translator: QueryTranslator): void;
}
// @beta (undocumented)
export interface SearchQuery {
// (undocumented)
filters?: JsonObject;
// (undocumented)
pageCursor?: string;
// (undocumented)
term: string;
// (undocumented)
types?: string[];
}
// @beta (undocumented)
export interface SearchResult {
// (undocumented)
document: IndexableDocument;
// (undocumented)
type: string;
}
// @beta (undocumented)
export interface SearchResultSet {
// (undocumented)
nextPageCursor?: string;
// (undocumented)
previousPageCursor?: string;
// (undocumented)
results: SearchResult[];
}
```
plugins/search-common/package.json
+53
View File
@@ -0,0 +1,53 @@
{
"name": "@backstage/search-common",
"description": "Common functionalities for Search, to be shared between various search-enabled plugins",
"version": "0.3.0",
"main": "src/index.ts",
"types": "src/index.ts",
"private": false,
"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": "packages/search-common"
},
"keywords": [
"backstage",
"search"
],
"license": "Apache-2.0",
"files": [
"dist"
],
"scripts": {
"build": "backstage-cli package build",
"lint": "backstage-cli package lint",
"test": "backstage-cli package test",
"prepack": "backstage-cli package prepack",
"postpack": "backstage-cli package postpack",
"clean": "backstage-cli package clean"
},
"bugs": {
"url": "https://github.com/backstage/backstage/issues"
},
"dependencies": {
"@backstage/types": "^0.1.3",
"@backstage/plugin-permission-common": "^0.5.2"
},
"devDependencies": {
"@backstage/cli": "^0.15.0"
},
"jest": {
"roots": [
".."
]
}
}
plugins/search-common/src/index.test.ts
+24
View File
@@ -0,0 +1,24 @@
/*
* Copyright 2021 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 * as anything from './';
describe('search-common', () => {
// TODO: Test real things once they exist.
it('should exist', () => {
expect(anything).toBeTruthy();
});
});
plugins/search-common/src/index.ts
+23
View File
@@ -0,0 +1,23 @@
/*
* Copyright 2021 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 Search, to be shared between various search-enabled plugins
*
* @packageDocumentation
*/
export * from './types';
plugins/search-common/src/types.ts
+182
View File
@@ -0,0 +1,182 @@
/*
* Copyright 2021 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 { Permission } from '@backstage/plugin-permission-common';
import { JsonObject } from '@backstage/types';
import { Readable, Transform, Writable } from 'stream';
/**
* @beta
*/
export interface SearchQuery {
term: string;
filters?: JsonObject;
types?: string[];
pageCursor?: string;
}
/**
* @beta
*/
export interface SearchResult {
type: string;
document: IndexableDocument;
}
/**
* @beta
*/
export interface SearchResultSet {
results: SearchResult[];
nextPageCursor?: string;
previousPageCursor?: string;
}
/**
* Base properties that all indexed documents must include, as well as some
* common properties that documents are encouraged to use where appropriate.
* @beta
*/
export interface IndexableDocument {
/**
* The primary name of the document (e.g. name, title, identifier, etc).
*/
title: string;
/**
* Free-form text of the document (e.g. description, content, etc).
*/
text: string;
/**
* The relative or absolute URL of the document (target when a search result
* is clicked).
*/
location: string;
/**
* Optional authorization information to be used when determining whether this
* search result should be visible to a given user.
*/
authorization?: {
/**
* Identifier for the resource.
*/
resourceRef: string;
};
}
/**
* Information about a specific document type. Intended to be used in the
* {@link @backstage/search-backend-node#IndexBuilder} to collect information
* about the types stored in the index.
* @beta
*/
export type DocumentTypeInfo = {
/**
* The {@link @backstage/plugin-permission-common#Permission} that controls
* visibility of resources associated with this collator's documents.
*/
visibilityPermission?: Permission;
};
/**
* Factory class for instantiating collators.
* @beta
*/
export interface DocumentCollatorFactory {
/**
* The type or name of the document set returned by this collator. Used as an
* index name by Search Engines.
*/
readonly type: string;
/**
* The {@link @backstage/plugin-permission-common#Permission} that controls
* visibility of resources associated with this collator's documents.
*/
readonly visibilityPermission?: Permission;
/**
* Instantiates and resolves a document collator.
*/
getCollator(): Promise<Readable>;
}
/**
* Factory class for instantiating decorators.
* @beta
*/
export interface DocumentDecoratorFactory {
/**
* An optional array of document/index types on which this decorator should
* be applied. If no types are provided, this decorator will be applied to
* all document/index types.
*/
readonly types?: string[];
/**
* Instantiates and resolves a document decorator.
*/
getDecorator(): Promise<Transform>;
}
/**
* A type of function responsible for translating an abstract search query into
* a concrete query relevant to a particular search engine.
* @beta
*/
export type QueryTranslator = (query: SearchQuery) => unknown;
/**
* Options when querying a search engine.
* @beta
*/
export type QueryRequestOptions = {
token?: string;
};
/**
* Interface that must be implemented by specific search engines, responsible
* for performing indexing and querying and translating abstract queries into
* concrete, search engine-specific queries.
* @beta
*/
export interface SearchEngine {
/**
* Override the default translator provided by the SearchEngine.
*/
setTranslator(translator: QueryTranslator): void;
/**
* Factory method for getting a search engine indexer for a given document
* type.
*
* @param type - The type or name of the document set for which an indexer
* should be retrieved. This corresponds to the `type` property on the
* document collator/decorator factories and will most often be used to
* identify an index or group to which documents should be written.
*/
getIndexer(type: string): Promise<Writable>;
/**
* Perform a search query against the SearchEngine.
*/
query(
query: SearchQuery,
options?: QueryRequestOptions,
): Promise<SearchResultSet>;
}