Database and Storage Services

/**
 * Database manager providing plugin-specific database connections
 */
class DatabaseManager {
  /**
   * Creates a DatabaseManager from backend database config
   * @param config - Root configuration service
   * @param options - Database manager options
   * @returns DatabaseManager instance
   */
  static fromConfig(
    config: RootConfigService,
    options?: DatabaseManagerOptions
  ): DatabaseManager;
  
  /**
   * Get database service for a specific plugin
   * @param pluginId - Unique identifier for the plugin
   * @param deps - Dependencies including logger and lifecycle services
   * @returns DatabaseService with getClient method
   */
  forPlugin(
    pluginId: string,
    deps: {
      logger: LoggerService;
      lifecycle: LifecycleService;
    }
  ): DatabaseService;
}

interface DatabaseManagerOptions {
  migrations?: {
    skip?: boolean;
  };
}

interface DatabaseService {
  getClient(): Promise<Knex>;
  migrations: {
    skip: boolean;
  };
}

/**
 * URL reader for GitHub repositories
 */
class GithubUrlReader implements UrlReader {
  constructor(integration: GitHubIntegration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
  search(url: string, path: string): Promise<ReadUrlResponse>;
}

/**
 * URL reader for GitLab repositories
 */
class GitlabUrlReader implements UrlReader {
  constructor(integration: GitLabIntegration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
}

/**
 * URL reader for Bitbucket repositories
 */
class BitbucketUrlReader implements UrlReader {
  constructor(integration: BitbucketIntegration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
}

/**
 * URL reader for Bitbucket Cloud repositories
 */
class BitbucketCloudUrlReader implements UrlReader {
  constructor(integration: BitbucketCloudIntegration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
}

/**
 * URL reader for Bitbucket Server repositories
 */
class BitbucketServerUrlReader implements UrlReader {
  constructor(integration: BitbucketServerIntegration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
}

/**
 * URL reader for Azure DevOps repositories
 */
class AzureUrlReader implements UrlReader {
  constructor(integration: AzureIntegration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
}

/**
 * URL reader for Gerrit repositories
 */
class GerritUrlReader implements UrlReader {
  constructor(integration: GerritIntegration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
}

/**
 * URL reader for Gitea repositories
 */
class GiteaUrlReader implements UrlReader {
  constructor(integration: GiteaIntegration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadUrlResponse>;
}

/**
 * URL reader for Harness repositories
 */
class HarnessUrlReader implements UrlReader {
  constructor(integration: HarnessIntegration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
}

/**
 * URL reader for AWS S3 buckets
 */
class AwsS3UrlReader implements UrlReader {
  constructor(integration: AwsS3Integration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
}

/**
 * URL reader for Azure Blob Storage
 */
class AzureBlobStorageUrlReader implements UrlReader {
  constructor(integration: AzureBlobStorageIntegration, deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
}

/**
 * Generic fetch-based URL reader for HTTP/HTTPS resources
 */
class FetchUrlReader implements UrlReader {
  constructor(deps: UrlReaderDeps);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
}

/**
 * Container for managing multiple URL readers
 */
class UrlReaders implements UrlReader {
  constructor(options: UrlReadersOptions);
  
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
  
  /**
   * Register a URL reader with predicate
   * @param predicate - Function to test if this reader handles the URL
   * @param reader - URL reader implementation
   */
  register(predicate: (url: URL) => boolean, reader: UrlReader): void;
}

interface UrlReadersOptions {
  logger: Logger;
  config: Config;
}

/**
 * Service reference for URL reader factories
 */
const urlReaderFactoriesServiceRef: ServiceRef<ReaderFactory[]>;

type UrlReaderPredicateTuple = [predicate: (url: URL) => boolean, reader: UrlReader];

/**
 * Factory for creating URL read responses
 */
class ReadUrlResponseFactory {
  /**
   * Create response from readable stream
   * @param stream - Readable stream containing data
   * @param options - Response creation options
   * @returns URL read response
   */
  static fromReadableArray(
    stream: Readable,
    options: ReadUrlResponseFactoryFromStreamOptions
  ): ReadUrlResponse;
  
  /**
   * Create response from readable array
   * @param array - Array of readable objects
   * @param options - Response creation options
   * @returns URL read response
   */
  static fromReadableArray(
    array: ReadableArray,
    options: FromReadableArrayOptions
  ): ReadUrlResponse;
}

interface ReadUrlResponseFactoryFromStreamOptions {
  etag?: string;
  lastModifiedAt?: Date;
}

interface FromReadableArrayOptions {
  data: Buffer;
  etag?: string;
  lastModifiedAt?: Date;
}

type ReadTreeResponseFactory = (options: ReadTreeResponseFactoryOptions) => ReadTreeResponse;

interface ReadTreeResponseFactoryOptions {
  stream: Readable;
  filter?: (path: string) => boolean;
  etag: string;
}

type ReaderFactory = (options: { config: Config; logger: Logger }) => UrlReaderPredicateTuple[];

interface UrlReader {
  readUrl(url: string, options?: ReadUrlOptions): Promise<ReadUrlResponse>;
  readTree?(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
  search?(url: string, path: string): Promise<ReadUrlResponse>;
}

interface ReadUrlOptions {
  etag?: string;
  lastModifiedAfter?: Date;
  signal?: AbortSignal;
}

interface ReadTreeOptions {
  etag?: string;
  filter?: (path: string, info?: { type: 'file' | 'dir'; size: number }) => boolean;
  signal?: AbortSignal;
}

interface ReadUrlResponse {
  buffer(): Promise<Buffer>;
  stream(): Readable;
  text(): Promise<string>;
  json(): Promise<any>;
  etag?: string;
  lastModifiedAt?: Date;
}

interface ReadTreeResponse {
  files(): AsyncIterable<ReadTreeResponseFile>;
  archive(): Promise<Buffer>;
  dir(options?: { targetDir?: string }): Promise<string>;
  etag?: string;
}

interface ReadTreeResponseFile {
  path: string;
  content(): Promise<Buffer>;
  lastModifiedAt?: Date;
}

interface UrlReaderDeps {
  logger: Logger;
  config: Config;
}

import { DatabaseManager } from "@backstage/backend-defaults/database";

const databaseManager = DatabaseManager.fromConfig(rootConfig, {
  migrations: { skip: false }
});

// Get database service for a plugin
const databaseService = databaseManager.forPlugin('catalog', {
  logger: pluginLogger,
  lifecycle: pluginLifecycle
});

// Get Knex client for database operations
const knex = await databaseService.getClient();
const entities = await knex('catalog_entities').select('*');

import { 
  GithubUrlReader, 
  UrlReaders,
  urlReaderFactoriesServiceRef 
} from "@backstage/backend-defaults/urlReader";

// Create URL readers container
const urlReaders = new UrlReaders({
  logger: backstageLogger,
  config: backstageConfig
});

// Read a file from GitHub
const response = await urlReaders.readUrl(
  'https://github.com/owner/repo/blob/main/README.md'
);

const content = await response.text();
console.log(content);

// Read an entire directory tree
const treeResponse = await urlReaders.readTree(
  'https://github.com/owner/repo/tree/main/src'
);

// Extract to local directory
await treeResponse.dir({ targetDir: './extracted' });

import { AwsS3UrlReader } from "@backstage/backend-defaults/urlReader";

const s3Reader = new AwsS3UrlReader(awsS3Integration, {
  logger: backstageLogger,
  config: backstageConfig
});

// Read file from S3
const response = await s3Reader.readUrl(
  's3://my-bucket/path/to/file.json'
);

const data = await response.json();