Skip to content

plugin-metadata.md

Latest commit

 

History

History
289 lines (211 loc) · 7.54 KB

plugin-metadata.md

File metadata and controls

289 lines (211 loc) · 7.54 KB
Raw

Plugin Metadata

Utilities for loading and injecting plugin metadata from Package CRD files into dynamic plugins configuration.

Import

import {
  shouldInjectPluginMetadata,
  extractPluginName,
  getMetadataDirectory,
  parseAllMetadataFiles,
  injectMetadataConfig,
  generateDynamicPluginsConfigFromMetadata,
  loadAndInjectPluginMetadata,
} from "rhdh-e2e-test-utils/utils";

Functions

shouldInjectPluginMetadata()

Checks if plugin metadata handling should be enabled.

function shouldInjectPluginMetadata(): boolean

Returns: true if metadata handling is enabled, false otherwise.

Behavior:

  • Returns false if RHDH_SKIP_PLUGIN_METADATA_INJECTION environment variable is set
  • Returns false if JOB_NAME contains periodic- (nightly/periodic builds)
  • Returns true otherwise (default for local dev and PR builds)

Example:

if (shouldInjectPluginMetadata()) {
  // Load and inject metadata
}

extractPluginName()

Extracts the plugin name from a package path or OCI reference.

function extractPluginName(packageRef: string): string

Parameters:

Parameter Type Description
packageRef string The package reference string

Returns: The extracted plugin name.

Supported Formats:

Format Example Extracted Name
Wrapper path ./dynamic-plugins/dist/my-plugin my-plugin
OCI with tag oci://quay.io/rhdh/my-plugin:1.0.0 my-plugin
OCI with digest oci://quay.io/rhdh/my-plugin@sha256:abc... my-plugin
OCI with alias oci://quay.io/rhdh/my-plugin@sha256:abc!alias my-plugin
GHCR ghcr.io/org/repo/my-plugin:tag my-plugin

Example:

const name = extractPluginName("oci://quay.io/rhdh/backstage-community-plugin-tech-radar:1.0.0");
// Returns: "backstage-community-plugin-tech-radar"

getMetadataDirectory()

Gets the metadata directory path.

function getMetadataDirectory(metadataPath?: string): string | null

Parameters:

Parameter Type Default Description
metadataPath string "../metadata" Path to metadata directory

Returns: The resolved metadata directory path, or null if it doesn't exist.

Example:

const metadataDir = getMetadataDirectory();
if (metadataDir) {
  console.log(`Found metadata at: ${metadataDir}`);
}

parseAllMetadataFiles()

Parses all metadata files in a directory and builds a map of plugin name to config.

async function parseAllMetadataFiles(
  metadataDir: string
): Promise<Map<string, PluginMetadata>>

Parameters:

Parameter Type Description
metadataDir string Path to the metadata directory

Returns: Map of plugin name to PluginMetadata.

Example:

const metadataDir = getMetadataDirectory();
if (metadataDir) {
  const metadataMap = await parseAllMetadataFiles(metadataDir);
  console.log(`Found ${metadataMap.size} plugins`);
}

injectMetadataConfig()

Injects plugin configurations from metadata into a dynamic plugins config.

function injectMetadataConfig(
  dynamicPluginsConfig: DynamicPluginsConfig,
  metadataMap: Map<string, PluginMetadata>
): DynamicPluginsConfig

Parameters:

Parameter Type Description
dynamicPluginsConfig DynamicPluginsConfig The config to augment
metadataMap Map<string, PluginMetadata> Map of plugin metadata

Returns: Augmented configuration with injected pluginConfigs.

Merge Behavior: Metadata config serves as the base, user-provided pluginConfig overrides it.

generateDynamicPluginsConfigFromMetadata()

Generates a complete dynamic-plugins configuration from metadata files.

async function generateDynamicPluginsConfigFromMetadata(
  metadataPath?: string
): Promise<DynamicPluginsConfig>

Parameters:

Parameter Type Default Description
metadataPath string "../metadata" Path to metadata directory

Returns: Complete dynamic plugins configuration with all plugins enabled.

Behavior:

  • Returns { plugins: [] } if shouldInjectPluginMetadata() returns false
  • Throws error if metadata directory not found
  • Throws error if no valid metadata files found
  • All generated plugins have disabled: false

PR Build Behavior (when GIT_PR_NUMBER is set):

  • Replaces local plugin paths with OCI URLs
  • Fetches plugin versions from source repo's package.json
  • Throws error if source.json or plugins-list.yaml not found
  • Throws error if version fetching fails

Example:

const config = await generateDynamicPluginsConfigFromMetadata();
console.log(`Generated config with ${config.plugins?.length} plugins`);

Example Output (PR Build):

plugins:
  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/my-plugin:pr_1234__1.0.0
    disabled: false
    pluginConfig:
      # ... from metadata

loadAndInjectPluginMetadata()

Main function to load and inject plugin metadata for PR builds.

async function loadAndInjectPluginMetadata(
  dynamicPluginsConfig: DynamicPluginsConfig,
  metadataPath?: string
): Promise<DynamicPluginsConfig>

Parameters:

Parameter Type Default Description
dynamicPluginsConfig DynamicPluginsConfig - The config to augment
metadataPath string "../metadata" Path to metadata directory

Returns: Augmented configuration with metadata (for PR) or unchanged (for nightly).

Behavior:

  • Returns config unchanged if shouldInjectPluginMetadata() returns false
  • Throws error if metadata directory not found
  • Throws error if no valid metadata files found
  • Only injects metadata for plugins already in the config

Example:

const config = { plugins: [{ package: "./dynamic-plugins/dist/my-plugin", disabled: false }] };
const augmented = await loadAndInjectPluginMetadata(config);

Types

PluginMetadata

interface PluginMetadata {
  /** The dynamic artifact path (e.g., ./dynamic-plugins/dist/plugin-name) */
  packagePath: string;
  /** The plugin configuration from appConfigExamples[0].content */
  pluginConfig: Record<string, unknown>;
  /** The package name (e.g., @backstage-community/plugin-tech-radar) */
  packageName: string;
  /** Source metadata file path */
  sourceFile: string;
}

PluginEntry

interface PluginEntry {
  package: string;
  disabled?: boolean;
  pluginConfig?: Record<string, unknown>;
  [key: string]: unknown;
}

DynamicPluginsConfig

interface DynamicPluginsConfig {
  plugins?: PluginEntry[];
  includes?: string[];
  [key: string]: unknown;
}

Constants

DEFAULT_METADATA_PATH

const DEFAULT_METADATA_PATH = "../metadata";

Default metadata directory path relative to the e2e-tests directory.

See Also