just some small service docs advancements

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

packages/backend-plugin-api/src/services/definitions/AuthService.ts

@@ -18,15 +18,29 @@ import { PermissionAttributes } from '@backstage/plugin-permission-common';
 import { JsonObject } from '@backstage/types';
 
 /**
+ * Represents a user principal (for example when a user Backstage token issued
+ * by the auth backend was given to a request).
+ *
+ * @remarks
+ *
+ * Additional information about the user can be fetched using the
+ * {@link UserInfoService}.
+ *
  * @public
  */
 export type BackstageUserPrincipal = {
   type: 'user';
 
+  /**
+   * The entity ref of the user entity that this principal represents.
+   */
   userEntityRef: string;
 };
 
 /**
+ * Represents a principal that is not authenticated (for example when no token
+ * at all was given to a request).
+ *
  * @public
  */
 export type BackstageNonePrincipal = {
@@ -34,13 +48,22 @@ export type BackstageNonePrincipal = {
 };
 
 /**
+ * Represents a service principal (for example when an external access method
+ * token was given to a request, or the caller was a Backstage backend plugin).
  * @public
  */
 export type BackstageServicePrincipal = {
   type: 'service';
 
-  // Exact format TBD, possibly 'plugin:<pluginId>' or 'external:<externalServiceId>'
-  subject: string;
+  /**
+   * A string that represents the service.
+   *
+   * @remarks
+   *
+   * This string is only informational, has no well defined semantics, and
+   * should never be used to drive actual logic in code.
+   */
+  subject: string; // Exact format TBD, possibly 'plugin:<pluginId>' or 'external:<externalServiceId>'
 
   /**
    * The access restrictions that apply to this principal.
@@ -92,17 +115,38 @@ export type BackstagePrincipalAccessRestrictions = {
 };
 
 /**
+ * An opaque representation of credentials, for example as passed in a
+ * request-response flow.
+ *
  * @public
  */
 export type BackstageCredentials<TPrincipal = unknown> = {
   $$type: '@backstage/BackstageCredentials';
 
+  /**
+   * If the credentials have a limited lifetime, this is the time at which they
+   * expire and may no longer be accepted by a receiver.
+   */
   expiresAt?: Date;
 
+  /**
+   * The principal (originator) of the request.
+   *
+   * @remarks
+   *
+   * This is semantically the originator of a request chain, and may or may not
+   * represent the immediate caller of your service. For example, in
+   * on-behalf-of scenarios, the immediate caller may be an intermediary backend
+   * service, but the principal may still be a user that was the original
+   * caller.
+   */
   principal: TPrincipal;
 };
 
 /**
+ * The types of principal that can be represented in a
+ * {@link BackstageCredentials} object.
+ *
  * @public
  */
 export type BackstagePrincipalTypes = {
@@ -113,36 +157,95 @@ export type BackstagePrincipalTypes = {
 };
 
 /**
+ * Provides token authentication and credentials management.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/auth | service documentation} for more details.
+ *
  * @public
  */
 export interface AuthService {
+  /**
+   * Verifies a token and returns the associated credentials.
+   */
   authenticate(
     token: string,
     options?: {
+      /**
+       * If set to true, allow limited access tokens (such as cookies).
+       *
+       * If this flag is not set, or is set to false, calls with limited access
+       * tokens will lead to a {@link @backstage/errors#NotAllowedError} being
+       * thrown.
+       */
       allowLimitedAccess?: boolean;
     },
   ): Promise<BackstageCredentials>;
 
+  /**
+   * Checks if the given credentials are of the given type, and narrows the
+   * TypeScript type accordingly if there's a match.
+   */
   isPrincipal<TType extends keyof BackstagePrincipalTypes>(
     credentials: BackstageCredentials,
     type: TType,
   ): credentials is BackstageCredentials<BackstagePrincipalTypes[TType]>;
 
+  /**
+   * Create a credentials object that represents an unauthenticated caller.
+   */
   getNoneCredentials(): Promise<BackstageCredentials<BackstageNonePrincipal>>;
 
+  /**
+   * Create a credentials object that represents the current service itself.
+   */
   getOwnServiceCredentials(): Promise<
     BackstageCredentials<BackstageServicePrincipal>
   >;
 
+  /**
+   * Issue a token that can be used for authenticating calls towards other
+   * backend plugins.
+   *
+   * @remarks
+   *
+   * This method should be called before each request. Do not cold on to the
+   * issued token and reuse it for future calls.
+   */
   getPluginRequestToken(options: {
+    /**
+     * The credentials of the originator of the request.
+     *
+     * @remarks
+     *
+     * This is most commonly the result of
+     * {@link AuthService.getOwnServiceCredentials} when the current service is
+     * the originator, or the output of {@link HttpAuthService.credentials} when
+     * performing requests on behalf of an incoming request identity.
+     */
     onBehalfOf: BackstageCredentials;
+    /**
+     * The ID of the plugin that the request is being made to.
+     */
     targetPluginId: string;
   }): Promise<{ token: string }>;
 
+  /**
+   * Issue a limited user token that can be used e.g. in cookie flows.
+   */
   getLimitedUserToken(
+    /**
+     * The credentials that this token should represent. Must be a user
+     * principal. Commonly the output of {@link HttpAuthService.credentials} is
+     * used as the input.
+     */
     credentials: BackstageCredentials<BackstageUserPrincipal>,
   ): Promise<{ token: string; expiresAt: Date }>;
 
+  /**
+   * Retrieve the public keys that have been used to sign tokens that were
+   * issued by this service. This list is periodically pruned from keys that are
+   * significantly past their expiry.
+   */
   listPublicServiceKeys(): Promise<{
     keys: JsonObject[];
   }>;

packages/backend-plugin-api/src/services/definitions/CacheService.ts

@@ -47,6 +47,8 @@ export type CacheServiceOptions = {
  * A pre-configured, storage agnostic cache service suitable for use by
  * Backstage plugins.
  *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/cache | service documentation} for more details.
+ *
  * @public
  */
 export interface CacheService {

packages/backend-plugin-api/src/services/definitions/DatabaseService.ts

@@ -17,7 +17,9 @@
 import { Knex } from 'knex';
 
 /**
- * The DatabaseService manages access to databases that Plugins get.
+ * Manages access to databases that plugins get.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/database | service documentation} for more details.
  *
  * @public
  */

packages/backend-plugin-api/src/services/definitions/DiscoveryService.ts

@@ -18,6 +18,10 @@
  * The DiscoveryService is used to provide a mechanism for backend
  * plugins to discover the endpoints for itself or other backend plugins.
  *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/discovery | service documentation} for more details.
+ *
+ * @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.
@@ -32,13 +36,15 @@ export interface DiscoveryService {
   /**
    * Returns the internal HTTP base URL for a given plugin, without a trailing slash.
    *
+   * @remarks
+   *
    * The returned URL should point to an internal endpoint for the plugin, with
    * the shortest route possible. The URL should be used for service-to-service
    * communication within a Backstage backend deployment.
    *
-   * 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.
+   * This method must always be called just before making each request, as opposed to
+   * fetching the URL once when constructing an API client. That is to ensure that more
+   * flexible routing patterns can be supported where a different result might be returned each time.
    *
    * For example, asking for the URL for `catalog` may return something
    * like `http://10.1.2.3/api/catalog`
@@ -48,6 +54,8 @@ export interface DiscoveryService {
   /**
    * Returns the external HTTP base backend URL for a given plugin, without a trailing slash.
    *
+   * @remarks
+   *
    * The returned URL should point to an external endpoint for the plugin, such that
    * it is reachable from the Backstage frontend and other external services. The returned
    * URL should be usable for example as a callback / webhook URL.

packages/backend-plugin-api/src/services/definitions/HttpAuthService.ts

@@ -17,19 +17,84 @@
 import { Request, Response } from 'express';
 import { BackstageCredentials, BackstagePrincipalTypes } from './AuthService';
 
-/** @public */
+/**
+ * Provides handling of credentials in an ongoing request.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/http-auth | service documentation} for more details.
+ *
+ * @public
+ */
 export interface HttpAuthService {
+  /**
+   * Extracts the caller's credentials from a request.
+   *
+   * @remarks
+   *
+   * The credentials have been validated before returning, and are guaranteed to
+   * adhere to whatever policies have been added to this route using
+   * {@link HttpRouterService.addAuthPolicy}, if any.
+   *
+   * Further restrictions can be imposed by passing in options that control the
+   * allowed types of credential.
+   *
+   * You can narrow the returned credentials object to specific principal types
+   * using {@link AuthService.isPrincipal}.
+   */
   credentials<TAllowed extends keyof BackstagePrincipalTypes = 'unknown'>(
+    /**
+     * An Express request object.
+     */
     req: Request<any, any, any, any, any>,
+    /**
+     * Optional further restrictions.
+     */
     options?: {
+      /**
+       * If specified, allow only principals of the given type(s).
+       *
+       * If the incoming credentials were not of a type that matched this
+       * restriction, a {@link @backstage/errors#NotAllowedError} is thrown.
+       *
+       * The default is to allow user and service principals.
+       */
       allow?: Array<TAllowed>;
+      /**
+       * If set to true, allow limited access tokens (such as cookies).
+       *
+       * If this flag is not set, or is set to false, calls with limited access
+       * tokens will lead to a {@link @backstage/errors#NotAllowedError} being
+       * thrown.
+       */
       allowLimitedAccess?: boolean;
     },
   ): Promise<BackstageCredentials<BackstagePrincipalTypes[TAllowed]>>;
 
+  /**
+   * Issues a limited access token as a cookie on the given response object.
+   * This is only possible for requests that were originally made with user
+   * credentials (such as a Backstage token).
+   *
+   * This must be called before sending any payload data.
+   */
   issueUserCookie(
+    /**
+     * An Express response object.
+     */
     res: Response,
+    /**
+     * Optional further settings.
+     */
     options?: {
+      /**
+       * Issue the cookie for this specific credential. Must be a "user" type
+       * principal, or a "none" type (which leads to deleting the cookie).
+       *
+       * @remarks
+       *
+       * Normally you do not have to specify this option, because the default
+       * behavior is to extract the credentials from the request that
+       * corresponded to the given respnse.
+       */
       credentials?: BackstageCredentials;
     },
   ): Promise<{ expiresAt: Date }>;

packages/backend-plugin-api/src/services/definitions/HttpRouterService.ts

@@ -16,17 +16,51 @@
 
 import { Handler } from 'express';
 
-/** @public */
+/**
+ * Options for {@link HttpRouterService.addAuthPolicy}.
+ *
+ * @public
+ */
 export interface HttpRouterServiceAuthPolicy {
   path: string;
   allow: 'unauthenticated' | 'user-cookie';
 }
 
 /**
+ * Allows plugins to register HTTP routes.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/http-router | service documentation} for more details.
+ *
  * @public
  */
 export interface HttpRouterService {
+  /**
+   * Registers an Express request handler under the plugin's base router. This
+   * typically makes its base path `/api/<plugin-id>`.
+   */
   use(handler: Handler): void;
 
+  /**
+   * Adds an auth policy to the router. This is used to allow unauthenticated or
+   * cookie based access to parts of a plugin's API.
+   *
+   * @remarks
+   *
+   * The paths given follow the same pattern as the routers given to the `use`
+   * method, that is, they are relative to the plugin's base URL, and can
+   * contain placeholders.
+   *
+   * @example
+   *
+   * ```ts
+   * http.addAuthPolicy({
+   *   path: '/static/:id',
+   *   allow: 'user-cookie',
+   * });
+   * ```
+   *
+   * This allows limited access tokens via cookies on the
+   * `/api/<plugin-id>/static/*` paths, but not unauthenticated access.
+   */
   addAuthPolicy(policy: HttpRouterServiceAuthPolicy): void;
 }

packages/backend-plugin-api/src/services/definitions/IdentityService.ts

@@ -16,5 +16,12 @@
 
 import { IdentityApi } from '@backstage/plugin-auth-node';
 
-/** @public */
+/**
+ * This is the legacy service for identity handling in Backstage. Please migrate to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/identity | service documentation} for more details.
+ *
+ * @public
+ * @deprecated Please migrate to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead.
+ */
 export interface IdentityService extends IdentityApi {}

packages/backend-plugin-api/src/services/definitions/LifecycleService.ts

@@ -47,6 +47,10 @@ export interface LifecycleServiceShutdownOptions {
 }
 
 /**
+ * Provides registration of plugin startup and shutdown lifecycle hooks.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/lifecycle | service documentation} for more details.
+ *
  * @public
  */
 export interface LifecycleService {

packages/backend-plugin-api/src/services/definitions/LoggerService.ts

@@ -19,6 +19,8 @@ import { JsonObject } from '@backstage/types';
 /**
  * A service that provides a logging facility.
  *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/logger | service documentation} for more details.
+ *
  * @public
  */
 export interface LoggerService {

packages/backend-plugin-api/src/services/definitions/PermissionsService.ts

@@ -37,13 +37,46 @@ export type PermissionsServiceRequestOptions =
       credentials: BackstageCredentials;
     };
 
-/** @public */
+/**
+ * Permission system integration for authorization of user/service actions.
+ *
+ * See the {@link https://backstage.io/docs/permissions/overview | permissions documentation}
+ * and the {@link https://backstage.io/docs/backend-system/core-services/permissions | service documentation}
+ * for more details.
+ *
+ * @public
+ */
 export interface PermissionsService extends PermissionEvaluator {
+  /**
+   * Evaluates
+   * {@link @backstage/plugin-permission-common#Permission | Permissions} and
+   * returns definitive decisions.
+   *
+   * @remarks
+   *
+   * The returned array has the same number of items, in the same order, as the
+   * given requests.
+   */
   authorize(
     requests: AuthorizePermissionRequest[],
     options?: PermissionsServiceRequestOptions,
   ): Promise<AuthorizePermissionResponse[]>;
 
+  /**
+   * Evaluates {@link @backstage/plugin-permission-common#ResourcePermission | ResourcePermissions} and returns both definitive and
+   * conditional decisions, depending on the configured
+   * {@link @backstage/plugin-permission-node#PermissionPolicy}.
+   *
+   * @remarks
+   *
+   * This method is useful when the
+   * caller needs more control over the processing of conditional decisions. For example, a plugin
+   * backend may want to use {@link @backstage/plugin-permission-common#PermissionCriteria | conditions} in a database query instead of
+   * evaluating each resource in memory.
+   *
+   * The returned array has the same number of items, in the same order, as the
+   * given requests.
+   */
   authorizeConditional(
     requests: QueryPermissionRequest[],
     options?: PermissionsServiceRequestOptions,

packages/backend-plugin-api/src/services/definitions/PluginMetadataService.ts

@@ -15,8 +15,15 @@
  */
 
 /**
+ * Access metadata about the current plugin.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/plugin-metadata | service documentation} for more details.
+ *
  * @public
  */
 export interface PluginMetadataService {
+  /**
+   * The ID of the current plugin.
+   */
   getId(): string;
 }

packages/backend-plugin-api/src/services/definitions/RootConfigService.ts

@@ -17,6 +17,12 @@
 import { Config } from '@backstage/config';
 
 /**
+ * Provides access to static configuration.
+ *
+ * See the {@link https://backstage.io/docs/conf/ | configuration documentation}
+ * and the {@link https://backstage.io/docs/backend-system/core-services/root-config | service documentation}
+ * for more details.
+ *
  * @public
  */
 export interface RootConfigService extends Config {}

packages/backend-plugin-api/src/services/definitions/RootHttpRouterService.ts

@@ -17,6 +17,10 @@
 import { Handler } from 'express';
 
 /**
+ * HTTP route registration for root services.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/root-http-router | service documentation} for more details.
+ *
  * @public
  */
 export interface RootHttpRouterService {

packages/backend-plugin-api/src/services/definitions/RootLifecycleService.ts

@@ -16,5 +16,11 @@
 
 import { LifecycleService } from './LifecycleService';
 
-/** @public */
+/**
+ * Registration of backend startup and shutdown lifecycle hooks.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/root-lifecycle | service documentation} for more details.
+ *
+ * @public
+ */
 export interface RootLifecycleService extends LifecycleService {}

packages/backend-plugin-api/src/services/definitions/RootLoggerService.ts

@@ -16,5 +16,11 @@
 
 import { LoggerService } from './LoggerService';
 
-/** @public */
+/**
+ * Root-level logging.
+ *
+ * Seethe {@link https://backstage.io/docs/backend-system/core-services/root-logger | service documentation} for more details.
+ *
+ * @public
+ */
 export interface RootLoggerService extends LoggerService {}

packages/backend-plugin-api/src/services/definitions/SchedulerService.ts

@@ -285,6 +285,8 @@ export interface SchedulerServiceTaskRunner {
 /**
  * Deals with the scheduling of distributed tasks, for a given plugin.
  *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/scheduler | service documentation} for more details.
+ *
  * @public
  */
 export interface SchedulerService {

packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts

@@ -15,9 +15,12 @@
  */
 
 /**
- * Interface for creating and validating tokens.
+ * This is the legacy service for creating and validating tokens. Please migrate to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/token-manager | service documentation} for more details.
  *
  * @public
+ * @deprecated Please migrate to the new `coreServices.auth`, `coreServices.httpAuth`, and `coreServices.userInfo` services as needed instead.
  */
 export interface TokenManagerService {
   /**

packages/backend-plugin-api/src/services/definitions/UrlReaderService.ts

@@ -19,6 +19,8 @@ import { Readable } from 'stream';
 /**
  * A generic interface for fetching plain data from URLs.
  *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/url-reader | service documentation} for more details.
+ *
  * @public
  */
 export interface UrlReaderService {

packages/backend-plugin-api/src/services/definitions/UserInfoService.ts

@@ -16,13 +16,27 @@
 
 import { BackstageCredentials } from './AuthService';
 
-/** @public */
+/**
+ * Represents user information that is available to the backend, based on some
+ * user credentials.
+ *
+ * @public
+ */
 export interface BackstageUserInfo {
   userEntityRef: string;
   ownershipEntityRefs: string[];
 }
 
-/** @public */
+/**
+ * Authenticated user information retrieval.
+ *
+ * See the {@link https://backstage.io/docs/backend-system/core-services/user-info | service documentation} for more details.
+ *
+ * @public
+ */
 export interface UserInfoService {
+  /**
+   * Retrieve user information based on the provided credentials.
+   */
   getUserInfo(credentials: BackstageCredentials): Promise<BackstageUserInfo>;
 }