@backstage/backend-defaults/dist/urlReader.d.ts

Backend defaults used by Backstage backend apps

import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
import { RootConfigService, LoggerService, UrlReaderServiceReadTreeResponse, UrlReaderService, UrlReaderServiceReadUrlOptions, UrlReaderServiceReadUrlResponse, UrlReaderServiceReadTreeOptions, UrlReaderServiceSearchOptions, UrlReaderServiceSearchResponse } from '@backstage/backend-plugin-api';
import { AzureIntegration, AzureDevOpsCredentialsProvider, BitbucketCloudIntegration, BitbucketIntegration, BitbucketServerIntegration, GerritIntegration, GithubIntegration, GithubCredentialsProvider, GitLabIntegration, GiteaIntegration, HarnessIntegration, AwsS3Integration, AzureCredentialsManager, AzureBlobStorageIntergation } from '@backstage/integration';
import { Readable } from 'stream';
import { AwsCredentialsManager } from '@backstage/integration-aws-node';

/**
 * A predicate that decides whether a specific {@link @backstage/backend-plugin-api#UrlReaderService} can handle a
 * given URL.
 *
 * @public
 */
type UrlReaderPredicateTuple = {
    predicate: (url: URL) => boolean;
    reader: UrlReaderService;
};
/**
 * A factory function that can read config to construct zero or more
 * {@link @backstage/backend-plugin-api#UrlReaderService}s along with a predicate for when it should be used.
 *
 * @public
 */
type ReaderFactory = (options: {
    config: RootConfigService;
    logger: LoggerService;
    treeResponseFactory: ReadTreeResponseFactory;
}) => UrlReaderPredicateTuple[];
/**
 * An options object for {@link ReadUrlResponseFactory} factory methods.
 *
 * @public
 */
type ReadUrlResponseFactoryFromStreamOptions = {
    etag?: string;
    lastModifiedAt?: Date;
};
/**
 * Options that control execution of {@link ReadTreeResponseFactory} methods.
 *
 * @public
 */
type ReadTreeResponseFactoryOptions = {
    stream: Readable;
    subpath?: string;
    etag: string;
    filter?: (path: string, info?: {
        size: number;
    }) => boolean;
} | {
    /** A response from a fetch request */
    response: Response;
    /** If unset, the files at the root of the tree will be read. Subpath must not contain the name of the top level directory. */
    subpath?: string;
    /** etag of the blob, to optionally override what the response header may or may not say */
    etag?: string;
    /** Filter passed on from the ReadTreeOptions */
    filter?: (path: string, info?: {
        size: number;
    }) => boolean;
};
/**
 * Options that control {@link ReadTreeResponseFactory.fromReadableArray}
 * execution.
 *
 * @public
 */
type FromReadableArrayOptions = Array<{
    /**
     * The raw data itself.
     */
    data: Readable;
    /**
     * The filepath of the data.
     */
    path: string;
    /**
     * Last modified date of the file contents.
     */
    lastModifiedAt?: Date;
}>;
/**
 * A factory for response factories that handle the unpacking and inspection of
 * complex responses such as archive data.
 *
 * @public
 */
interface ReadTreeResponseFactory {
    fromTarArchive(options: ReadTreeResponseFactoryOptions & {
        /**
         * Strip the first parent directory of a tar archive.
         * Defaults to true.
         */
        stripFirstDirectory?: boolean;
    }): Promise<UrlReaderServiceReadTreeResponse>;
    fromZipArchive(options: ReadTreeResponseFactoryOptions): Promise<UrlReaderServiceReadTreeResponse>;
    fromReadableArray(options: FromReadableArrayOptions): Promise<UrlReaderServiceReadTreeResponse>;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for Azure repos.
 *
 * @public
 */
declare class AzureUrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly integration;
    private readonly deps;
    constructor(integration: AzureIntegration, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
        credentialsProvider: AzureDevOpsCredentialsProvider;
    });
    read(url: string): Promise<Buffer>;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for files from Bitbucket Cloud.
 *
 * @public
 */
declare class BitbucketCloudUrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly integration;
    private readonly deps;
    constructor(integration: BitbucketCloudIntegration, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
    });
    read(url: string): Promise<Buffer>;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
    private getLastCommitShortHash;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for files from Bitbucket v1 and v2 APIs, such
 * as the one exposed by Bitbucket Cloud itself.
 *
 * @public
 * @deprecated in favor of BitbucketCloudUrlReader and BitbucketServerUrlReader
 */
declare class BitbucketUrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly integration;
    private readonly deps;
    constructor(integration: BitbucketIntegration, logger: LoggerService, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
    });
    read(url: string): Promise<Buffer>;
    private getCredentials;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
    private getLastCommitShortHash;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for files from Bitbucket Server APIs.
 *
 * @public
 */
declare class BitbucketServerUrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly integration;
    private readonly deps;
    constructor(integration: BitbucketServerIntegration, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
    });
    read(url: string): Promise<Buffer>;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
    private getLastCommitShortHash;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for files in Gerrit.
 *
 * @remarks
 * To be able to link to Git contents for Gerrit providers in a user friendly
 * way we are depending on that there is a Gitiles installation somewhere
 * that we can link to. It is perfectly possible to integrate Gerrit with
 * Backstage without Gitiles since all API calls goes directly to Gerrit.
 * However if Gitiles is configured, readTree will use it to fetch
 * an archive instead of cloning the repository.
 *
 * The "host" variable in the config is the Gerrit host. The address where
 * Gitiles is installed may be on the same host but it could be on a
 * separate host. For example a Gerrit instance could be hosted on
 * "gerrit-review.company.com" but the repos could be browsable on a separate
 * host, e.g. "gerrit.company.com" and the human readable URL would then
 * not point to the API host.
 *
 * @public
 */
declare class GerritUrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly integration;
    private readonly deps;
    constructor(integration: GerritIntegration, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
    });
    read(url: string): Promise<Buffer>;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
    private readTreeFromGitiles;
    private getRevisionForUrl;
    private searchFilesFromGitiles;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for files through the GitHub v3 APIs, such as
 * the one exposed by GitHub itself.
 *
 * @public
 */
declare class GithubUrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly integration;
    private readonly deps;
    constructor(integration: GithubIntegration, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
        credentialsProvider: GithubCredentialsProvider;
    });
    read(url: string): Promise<Buffer>;
    private getCredentials;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
    private doReadTree;
    private doSearch;
    private getRepoDetails;
    private getDefaultBranch;
    private fetchResponse;
    private fetchJson;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for files on GitLab.
 *
 * @public
 */
declare class GitlabUrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly integration;
    private readonly deps;
    constructor(integration: GitLabIntegration, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
    });
    read(url: string): Promise<Buffer>;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    /**
     * This function splits the input globPattern string into segments using the  path separator /. It then iterates over
     * the segments from the end of the array towards the beginning, checking if the concatenated string up to that
     * segment matches the original globPattern using the minimatch function. If a match is found, it continues iterating.
     * If no match is found, it returns the concatenated string up to the current segment, which is the static part of the
     * glob pattern.
     *
     * E.g. `catalog/foo/*.yaml` will return `catalog/foo`.
     *
     * @param globPattern - the glob pattern
     */
    private getStaticPart;
    toString(): string;
    private getGitlabFetchUrl;
    private getGitlabArtifactFetchUrl;
    private resolveProjectToId;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for the Gitea v1 api.
 *
 * @public
 */
declare class GiteaUrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly integration;
    private readonly deps;
    constructor(integration: GiteaIntegration, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
    });
    read(url: string): Promise<Buffer>;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
    private getLastCommitHash;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for the Harness code v1 api.
 *
 *
 * @public
 */
declare class HarnessUrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly integration;
    private readonly deps;
    constructor(integration: HarnessIntegration, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
    });
    read(url: string): Promise<Buffer>;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
    private getLastCommitHash;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for AWS S3 buckets.
 *
 * @public
 */
declare class AwsS3UrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly credsManager;
    private readonly integration;
    private readonly deps;
    constructor(credsManager: AwsCredentialsManager, integration: AwsS3Integration, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
    });
    /**
     * If accessKeyId and secretAccessKey are missing, the standard credentials provider chain will be used:
     * https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/DefaultAWSCredentialsProviderChain.html
     */
    private static buildStaticCredentials;
    private static buildCredentials;
    private buildS3Client;
    private retrieveS3ObjectData;
    read(url: string): Promise<Buffer>;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
}

/**
 * Implements a {@link @backstage/backend-plugin-api#UrlReaderService} for Azure storage accounts urls.
 *
 * @public
 */
declare class AzureBlobStorageUrlReader implements UrlReaderService {
    static factory: ReaderFactory;
    private readonly credsManager;
    private readonly integration;
    private readonly deps;
    constructor(credsManager: AzureCredentialsManager, integration: AzureBlobStorageIntergation, deps: {
        treeResponseFactory: ReadTreeResponseFactory;
    });
    private createContainerClient;
    read(url: string): Promise<Buffer>;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(url: string, options?: UrlReaderServiceReadTreeOptions): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
}

/**
 * A {@link @backstage/backend-plugin-api#UrlReaderService} that does a plain fetch of the URL.
 *
 * @public
 */
declare class FetchUrlReader implements UrlReaderService {
    /**
     * The factory creates a single reader that will be used for reading any URL that's listed
     * in configuration at `backend.reading.allow`. The allow list contains a list of objects describing
     * targets to allow, containing the following fields:
     *
     * `host`:
     *   Either full hostnames to match, or subdomain wildcard matchers with a leading '*'.
     *   For example 'example.com' and '*.example.com' are valid values, 'prod.*.example.com' is not.
     *
     * `paths`:
     *   An optional list of paths which are allowed. If the list is omitted all paths are allowed.
     */
    static factory: ReaderFactory;
    read(url: string): Promise<Buffer>;
    readUrl(url: string, options?: UrlReaderServiceReadUrlOptions): Promise<UrlReaderServiceReadUrlResponse>;
    readTree(): Promise<UrlReaderServiceReadTreeResponse>;
    search(url: string, options?: UrlReaderServiceSearchOptions): Promise<UrlReaderServiceSearchResponse>;
    toString(): string;
}

/**
 * Utility class for UrlReader implementations to create valid ReadUrlResponse
 * instances from common response primitives.
 *
 * @public
 */
declare class ReadUrlResponseFactory {
    /**
     * Resolves a UrlReaderServiceReadUrlResponse from a Readable stream.
     */
    static fromReadable(stream: Readable, options?: ReadUrlResponseFactoryFromStreamOptions): Promise<UrlReaderServiceReadUrlResponse>;
    /**
     * Resolves a UrlReaderServiceReadUrlResponse from an old-style NodeJS.ReadableStream.
     */
    static fromNodeJSReadable(oldStyleStream: NodeJS.ReadableStream, options?: ReadUrlResponseFactoryFromStreamOptions): Promise<UrlReaderServiceReadUrlResponse>;
    /**
     * Resolves a UrlReaderServiceReadUrlResponse from a native fetch response body.
     */
    static fromResponse(response: Response): Promise<UrlReaderServiceReadUrlResponse>;
}

/**
 * Creation options for {@link @backstage/backend-plugin-api#UrlReaderService}.
 *
 * @public
 */
type UrlReadersOptions = {
    /** Root config object */
    config: RootConfigService;
    /** Logger used by all the readers */
    logger: LoggerService;
    /** A list of factories used to construct individual readers that match on URLs */
    factories?: ReaderFactory[];
};
/**
 * Helps construct {@link @backstage/backend-plugin-api#UrlReaderService}s.
 *
 * @public
 */
declare class UrlReaders {
    /**
     * Creates a custom {@link @backstage/backend-plugin-api#UrlReaderService} wrapper for your own set of factories.
     */
    static create(options: UrlReadersOptions): UrlReaderService;
    /**
     * Creates a {@link @backstage/backend-plugin-api#UrlReaderService} wrapper that includes all the default factories
     * from this package.
     *
     * Any additional factories passed will be loaded before the default ones.
     */
    static default(options: UrlReadersOptions): UrlReaderService;
}

/**
 * @public
 * A non-singleton reference to URL Reader factory services.
 *
 * @example
 * Creating a service factory implementation for a Custom URL Reader.
 * ```ts
 * createServiceFactory({
 *   service: urlReaderFactoriesServiceRef,
 *   deps: {},
 *   async factory() {
 *     return CustomUrlReader.factory;
 *   },
 * });
 * ```
 */
declare const urlReaderFactoriesServiceRef: _backstage_backend_plugin_api.ServiceRef<ReaderFactory, "plugin", "multiton">;
/**
 * Reading content from external systems.
 *
 * See {@link @backstage/code-plugin-api#UrlReaderService}
 * and {@link https://backstage.io/docs/backend-system/core-services/url-reader | the service docs}
 * for more information.
 *
 * @public
 */
declare const urlReaderServiceFactory: _backstage_backend_plugin_api.ServiceFactory<_backstage_backend_plugin_api.UrlReaderService, "plugin", "singleton">;

export { AwsS3UrlReader, AzureBlobStorageUrlReader, AzureUrlReader, BitbucketCloudUrlReader, BitbucketServerUrlReader, BitbucketUrlReader, FetchUrlReader, GerritUrlReader, GiteaUrlReader, GithubUrlReader, GitlabUrlReader, HarnessUrlReader, ReadUrlResponseFactory, UrlReaders, urlReaderFactoriesServiceRef, urlReaderServiceFactory };
export type { FromReadableArrayOptions, ReadTreeResponseFactory, ReadTreeResponseFactoryOptions, ReadUrlResponseFactoryFromStreamOptions, ReaderFactory, UrlReaderPredicateTuple, UrlReadersOptions };