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

frontend-plugin-api: more relative imports

Browse Source 
Signed-off-by: Vincenzo Scamporlino <vincenzos@spotify.com>
This commit is contained in:
Vincenzo Scamporlino
2023-11-07 17:40:46 +01:00
committed by Patrik Oldsberg
parent 2096c38db6
commit cb1ed7d081
8 changed files with 142 additions and 764 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/frontend-plugin-api/src/apis/definitions/DiscoveryApi.ts
+5 -39
View File
@@ -13,43 +13,9 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { ApiRef, createApiRef } from '../system';
/**
* The discovery API is used to provide a mechanism for plugins to
* discover the endpoint to use to talk to their backend counterpart.
*
* @remarks
*
* The purpose of the discovery API is to allow for many different deployment
* setups and routing methods through a central configuration, instead
* of letting each individual plugin manage that configuration.
*
* Implementations of the discovery API can be a simple as a URL pattern
* using the pluginId, but could also have overrides for individual plugins,
* or query a separate discovery service.
*
* @public
*/
export type DiscoveryApi = {
/**
* Returns the HTTP base backend URL for a given plugin, without a trailing slash.
*
* This method must always be called just before making a request, as opposed to
* fetching the URL when constructing an API client. That is to ensure that more
* flexible routing patterns can be supported.
*
* For example, asking for the URL for `auth` may return something
* like `https://backstage.example.com/api/auth`
*/
getBaseUrl(pluginId: string): Promise<string>;
};
/**
* The {@link ApiRef} of {@link DiscoveryApi}.
*
* @public
*/
export const discoveryApiRef: ApiRef<DiscoveryApi> = createApiRef({
id: 'core.discovery',
});
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
export {
type DiscoveryApi,
discoveryApiRef,
} from '../../../../core-plugin-api';
packages/frontend-plugin-api/src/apis/definitions/ErrorApi.ts
+7 -75
View File
@@ -14,78 +14,10 @@
* limitations under the License.
*/
import { ApiRef, createApiRef } from '../system';
import { Observable } from '@backstage/types';
/**
* Mirrors the JavaScript Error class, for the purpose of
* providing documentation and optional fields.
*
* @public
*/
export type ErrorApiError = {
name: string;
message: string;
stack?: string;
};
/**
* Provides additional information about an error that was posted to the application.
*
* @public
*/
export type ErrorApiErrorContext = {
/**
* If set to true, this error should not be displayed to the user.
*
* Hidden errors are typically not displayed in the UI, but the ErrorApi
* implementation may still report them to error tracking services
* or other utilities that care about all errors.
*
* @defaultValue false
*/
hidden?: boolean;
};
/**
* The error API is used to report errors to the app, and display them to the user.
*
* @remarks
*
* Plugins can use this API as a method of displaying errors to the user, but also
* to report errors for collection by error reporting services.
*
* If an error can be displayed inline, e.g. as feedback in a form, that should be
* preferred over relying on this API to display the error. The main use of this API
* for displaying errors should be for asynchronous errors, such as a failing background process.
*
* Even if an error is displayed inline, it should still be reported through this API
* if it would be useful to collect or log it for debugging purposes, but with
* the hidden flag set. For example, an error arising from form field validation
* should probably not be reported, while a failed REST call would be useful to report.
*
* @public
*/
export type ErrorApi = {
/**
* Post an error for handling by the application.
*/
post(error: ErrorApiError, context?: ErrorApiErrorContext): void;
/**
* Observe errors posted by other parts of the application.
*/
error$(): Observable<{
error: ErrorApiError;
context?: ErrorApiErrorContext;
}>;
};
/**
* The {@link ApiRef} of {@link ErrorApi}.
*
* @public
*/
export const errorApiRef: ApiRef<ErrorApi> = createApiRef({
id: 'core.error',
});
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
export {
type ErrorApiError,
type ErrorApiErrorContext,
type ErrorApi,
errorApiRef,
} from '../../../../core-plugin-api';
packages/frontend-plugin-api/src/apis/definitions/FeatureFlagsApi.ts
+8 -94
View File
@@ -14,97 +14,11 @@
* limitations under the License.
*/
import { ApiRef, createApiRef } from '../system';
/**
* Feature flag descriptor.
*
* @public
*/
export type FeatureFlag = {
name: string;
pluginId: string;
description?: string;
};
/**
* Enum representing the state of a feature flag (inactive/active).
*
* @public
*/
export enum FeatureFlagState {
/**
* Feature flag inactive (disabled).
*/
None = 0,
/**
* Feature flag active (enabled).
*/
Active = 1,
}
/**
* Options to use when saving feature flags.
*
* @public
*/
export type FeatureFlagsSaveOptions = {
/**
* The new feature flag states to save.
*/
states: Record<string, FeatureFlagState>;
/**
* Whether the saves states should be merged into the existing ones, or replace them.
*
* Defaults to false.
*/
merge?: boolean;
};
/**
* The feature flags API is used to toggle functionality to users across plugins and Backstage.
*
* @remarks
*
* Plugins can use this API to register feature flags that they have available
* for users to enable/disable, and this API will centralize the current user's
* state of which feature flags they would like to enable.
*
* This is ideal for Backstage plugins, as well as your own App, to trial incomplete
* or unstable upcoming features. Although there will be a common interface for users
* to enable and disable feature flags, this API acts as another way to enable/disable.
*
* @public
*/
export interface FeatureFlagsApi {
/**
* Registers a new feature flag. Once a feature flag has been registered it
* can be toggled by users, and read back to enable or disable features.
*/
registerFlag(flag: FeatureFlag): void;
/**
* Get a list of all registered flags.
*/
getRegisteredFlags(): FeatureFlag[];
/**
* Whether the feature flag with the given name is currently activated for the user.
*/
isActive(name: string): boolean;
/**
* Save the user's choice of feature flag states.
*/
save(options: FeatureFlagsSaveOptions): void;
}
/**
* The {@link ApiRef} of {@link FeatureFlagsApi}.
*
* @public
*/
export const featureFlagsApiRef: ApiRef<FeatureFlagsApi> = createApiRef({
id: 'core.featureflags',
});
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
export {
type FeatureFlag,
type FeatureFlagState,
type FeatureFlagsSaveOptions,
type FeatureFlagsApi,
featureFlagsApiRef,
} from '../../../../core-plugin-api';
packages/frontend-plugin-api/src/apis/definitions/FetchApi.ts
+2 -35
View File
@@ -14,38 +14,5 @@
* limitations under the License.
*/
import { ApiRef, createApiRef } from '../system';
/**
* A wrapper for the fetch API, that has additional behaviors such as the
* ability to automatically inject auth information where necessary.
*
* @public
*/
export type FetchApi = {
/**
* The `fetch` implementation.
*/
fetch: typeof fetch;
};
/**
* The {@link ApiRef} of {@link FetchApi}.
*
* @remarks
*
* This is a wrapper for the fetch API, that has additional behaviors such as
* the ability to automatically inject auth information where necessary.
*
* Note that the default behavior of this API (unless overridden by your org),
* is to require that the user is already signed in so that it has auth
* information to inject. Therefore, using the default implementation of this
* utility API e.g. on the `SignInPage` or similar, would cause issues. In
* special circumstances like those, you can use the regular system `fetch`
* instead.
*
* @public
*/
export const fetchApiRef: ApiRef<FetchApi> = createApiRef({
id: 'core.fetch',
});
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
export { type FetchApi, fetchApiRef } from '../../../../core-plugin-api';
packages/frontend-plugin-api/src/apis/definitions/IdentityApi.ts
+2 -40
View File
@@ -13,44 +13,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { ApiRef, createApiRef } from '../system';
import { BackstageUserIdentity, ProfileInfo } from './auth';
/**
* The Identity API used to identify and get information about the signed in user.
*
* @public
*/
export type IdentityApi = {
/**
* The profile of the signed in user.
*/
getProfileInfo(): Promise<ProfileInfo>;
/**
* User identity information within Backstage.
*/
getBackstageIdentity(): Promise<BackstageUserIdentity>;
/**
* Provides credentials in the form of a token which proves the identity of the signed in user.
*
* The token will be undefined if the signed in user does not have a verified
* identity, such as a demo user or mocked user for e2e tests.
*/
getCredentials(): Promise<{ token?: string }>;
/**
* Sign out the current user
*/
signOut(): Promise<void>;
};
/**
* The {@link ApiRef} of {@link IdentityApi}.
*
* @public
*/
export const identityApiRef: ApiRef<IdentityApi> = createApiRef({
id: 'core.identity',
});
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
export { type IdentityApi, identityApiRef } from '../../../../core-plugin-api';
packages/frontend-plugin-api/src/apis/definitions/OAuthRequestApi.ts
+8 -115
View File
@@ -14,118 +14,11 @@
* limitations under the License.
*/
import { Observable } from '@backstage/types';
import { ApiRef, createApiRef } from '../system';
import { AuthProviderInfo } from './auth';
/**
* Describes how to handle auth requests. Both how to show them to the user, and what to do when
* the user accesses the auth request.
*
* @public
*/
export type OAuthRequesterOptions<TOAuthResponse> = {
/**
* Information about the auth provider, which will be forwarded to auth requests.
*/
provider: AuthProviderInfo;
/**
* Implementation of the auth flow, which will be called synchronously when
* trigger() is called on an auth requests.
*/
onAuthRequest(scopes: Set<string>): Promise<TOAuthResponse>;
};
/**
* Function used to trigger new auth requests for a set of scopes.
*
* @remarks
*
* The returned promise will resolve to the same value returned by the onAuthRequest in the
* {@link OAuthRequesterOptions}. Or rejected, if the request is rejected.
*
* This function can be called multiple times before the promise resolves. All calls
* will be merged into one request, and the scopes forwarded to the onAuthRequest will be the
* union of all requested scopes.
*
* @public
*/
export type OAuthRequester<TAuthResponse> = (
scopes: Set<string>,
) => Promise<TAuthResponse>;
/**
* An pending auth request for a single auth provider. The request will remain in this pending
* state until either reject() or trigger() is called.
*
* @remarks
*
* Any new requests for the same provider are merged into the existing pending request, meaning
* there will only ever be a single pending request for a given provider.
*
* @public
*/
export type PendingOAuthRequest = {
/**
* Information about the auth provider, as given in the AuthRequesterOptions
*/
provider: AuthProviderInfo;
/**
* Rejects the request, causing all pending AuthRequester calls to fail with "RejectedError".
*/
reject(): void;
/**
* Trigger the auth request to continue the auth flow, by for example showing a popup.
*
* Synchronously calls onAuthRequest with all scope currently in the request.
*/
trigger(): Promise<void>;
};
/**
* Provides helpers for implemented OAuth login flows within Backstage.
*
* @public
*/
export type OAuthRequestApi = {
/**
* A utility for showing login popups or similar things, and merging together multiple requests for
* different scopes into one request that includes all scopes.
*
* The passed in options provide information about the login provider, and how to handle auth requests.
*
* The returned AuthRequester function is used to request login with new scopes. These requests
* are merged together and forwarded to the auth handler, as soon as a consumer of auth requests
* triggers an auth flow.
*
* See AuthRequesterOptions, AuthRequester, and handleAuthRequests for more info.
*/
createAuthRequester<OAuthResponse>(
options: OAuthRequesterOptions<OAuthResponse>,
): OAuthRequester<OAuthResponse>;
/**
* Observers pending auth requests. The returned observable will emit all
* current active auth request, at most one for each created auth requester.
*
* Each request has its own info about the login provider, forwarded from the auth requester options.
*
* Depending on user interaction, the request should either be rejected, or used to trigger the auth handler.
* If the request is rejected, all pending AuthRequester calls will fail with a "RejectedError".
* If a auth is triggered, and the auth handler resolves successfully, then all currently pending
* AuthRequester calls will resolve to the value returned by the onAuthRequest call.
*/
authRequest$(): Observable<PendingOAuthRequest[]>;
};
/**
* The {@link ApiRef} of {@link OAuthRequestApi}.
*
* @public
*/
export const oauthRequestApiRef: ApiRef<OAuthRequestApi> = createApiRef({
id: 'core.oauthrequest',
});
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
export {
type OAuthRequesterOptions,
type OAuthRequester,
type PendingOAuthRequest,
type OAuthRequestApi,
oauthRequestApiRef,
} from '../../../../core-plugin-api';
packages/frontend-plugin-api/src/apis/definitions/StorageApi.ts
+6 -94
View File
@@ -14,97 +14,9 @@
* limitations under the License.
*/
import { ApiRef, createApiRef } from '../system';
import { JsonValue, Observable } from '@backstage/types';
/**
* A snapshot in time of the current known value of a storage key.
*
* @public
*/
export type StorageValueSnapshot<TValue extends JsonValue> =
| {
key: string;
presence: 'unknown' | 'absent';
value?: undefined;
}
| {
key: string;
presence: 'present';
value: TValue;
};
/**
* Provides a key-value persistence API.
*
* @public
*/
export interface StorageApi {
/**
* Create a bucket to store data in.
*
* @param name - Namespace for the storage to be stored under,
* will inherit previous namespaces too
*/
forBucket(name: string): StorageApi;
/**
* Remove persistent data.
*
* @param key - Unique key associated with the data.
*/
remove(key: string): Promise<void>;
/**
* Save persistent data, and emit messages to anyone that is using
* {@link StorageApi.observe$} for this key.
*
* @param key - Unique key associated with the data.
* @param data - The data to be stored under the key.
*/
set<T extends JsonValue>(key: string, data: T): Promise<void>;
/**
* Observe the value over time for a particular key in the current bucket.
*
* @remarks
*
* The observable will only emit values when the value changes in the underlying
* storage, although multiple values with the same shape may be emitted in a row.
*
* If a {@link StorageApi.snapshot} of a key is retrieved and the presence is
* `'unknown'`, then you are guaranteed to receive a snapshot with a known
* presence, as long as you observe the key within the same tick.
*
* Since the emitted values are shared across all subscribers, it is important
* not to mutate the returned values. The values may be frozen as a precaution.
*
* @param key - Unique key associated with the data
*/
observe$<T extends JsonValue>(
key: string,
): Observable<StorageValueSnapshot<T>>;
/**
* Returns an immediate snapshot value for the given key, if possible.
*
* @remarks
*
* Combine with {@link StorageApi.observe$} to get notified of value changes.
*
* Note that this method is synchronous, and some underlying storages may be
* unable to retrieve a value using this method - the result may or may not
* consistently have a presence of 'unknown'. Use {@link StorageApi.observe$}
* to be sure to receive an actual value eventually.
*/
snapshot<T extends JsonValue>(key: string): StorageValueSnapshot<T>;
}
/**
* The {@link ApiRef} of {@link StorageApi}.
*
* @public
*/
export const storageApiRef: ApiRef<StorageApi> = createApiRef({
id: 'core.storage',
});
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
export {
type StorageValueSnapshot,
type StorageApi,
storageApiRef,
} from '../../../../core-plugin-api';