Configuration Loading

Advanced configuration loading system with extension management, data store integration, and configuration merging from multiple sources.

Core Interfaces

AutorestConfigurationResult

interface AutorestConfigurationResult {
  config: AutorestConfiguration;
  extensions: ResolvedExtension[];
}

Result of the configuration loading process containing the final merged configuration and resolved extensions.

Properties:

• config: AutorestConfiguration - Final processed AutoRest configuration
• extensions: ResolvedExtension[] - Array of resolved and loaded extensions

ConfigurationLoaderOptions

interface ConfigurationLoaderOptions {
  fileSystem?: IFileSystem;
  dataStore?: DataStore;
  extensionManager?: ExtensionManager;
}

Options for customizing the configuration loading process.

Properties:

• fileSystem?: IFileSystem - Override the default file system implementation
• dataStore?: DataStore - Pass a custom data store for configuration data
• extensionManager?: ExtensionManager - Extension manager for resolving extension configurations

Extension Management

ExtensionDefinition

interface ExtensionDefinition {
  name: string;
  source: string;
  fullyQualified: string;
}

Defines an AutoRest extension with its identification and source information.

Properties:

• name: string - Extension name (e.g., "csharp", "python")
• source: string - Extension source location or package name
• fullyQualified: string - Fully qualified extension identifier

ResolvedExtension

interface ResolvedExtension {
  definition: ExtensionDefinition;
  extension: Extension;
}

Represents a successfully resolved and loaded extension.

Properties:

• definition: ExtensionDefinition - Extension definition information
• extension: Extension - Loaded extension instance

Configuration Loading Process

The configuration loader follows a comprehensive process:

1. Configuration Discovery - Locate and identify configuration sources
2. File Loading - Read configuration files using appropriate parsers
3. Schema Validation - Validate configurations against AutoRest schema
4. Extension Resolution - Resolve and load required extensions
5. Configuration Merging - Merge configurations from multiple sources
6. URI Resolution - Resolve relative paths to absolute URIs
7. Final Processing - Create final AutorestConfiguration object

Configuration Sources

File-based Configuration

• Markdown files - Literate YAML configuration with embedded code blocks
• YAML files - Standard YAML configuration format
• JSON files - JSON configuration format

Programmatic Configuration

• CLI arguments - Command-line provided configuration
• API configuration - Programmatically provided configuration objects
• Environment variables - Environment-based configuration

Extension Configuration

• Extension defaults - Default configurations provided by extensions
• Extension requirements - Required configurations for extension operation

Usage Examples

Basic Configuration Loading

import { ConfigurationLoader } from "@autorest/configuration";
import { RealFileSystem } from "@azure-tools/datastore";
import { ExtensionManager } from "@azure-tools/extension";

const options: ConfigurationLoaderOptions = {
  fileSystem: new RealFileSystem(),
  extensionManager: new ExtensionManager()
};

const loader = new ConfigurationLoader(options);
const result = await loader.loadConfiguration(configPath, cliOptions);

console.log("Loaded configuration:", result.config);
console.log("Resolved extensions:", result.extensions);

Custom File System

import { CachingFileSystem } from "@azure-tools/datastore";

const options: ConfigurationLoaderOptions = {
  fileSystem: new CachingFileSystem(new RealFileSystem())
};

const loader = new ConfigurationLoader(options);

Extension Management Integration

import { ExtensionManager } from "@azure-tools/extension";

const extensionManager = new ExtensionManager({
  // Extension manager configuration
});

const options: ConfigurationLoaderOptions = {
  extensionManager: extensionManager
};

const result = await loader.loadConfiguration(configPath, baseConfig);

// Access resolved extensions
for (const resolvedExt of result.extensions) {
  console.log(`Loaded extension: ${resolvedExt.definition.name}`);
  console.log(`Source: ${resolvedExt.definition.source}`);
}

Advanced Features

Data Store Integration

The configuration loader can work with custom data stores for advanced scenarios:

import { DataStore } from "@azure-tools/datastore";

const customDataStore = new DataStore();
const options: ConfigurationLoaderOptions = {
  dataStore: customDataStore
};

Timeout Configuration

Configuration loading supports timeout settings to prevent hanging on network operations:

const CONFIGURATION_LOAD_TIMEOUT: number; // Timeout in milliseconds

Configuration Caching

The system supports caching of loaded configurations to improve performance:

• File system caching - Cache file reads
• Extension caching - Cache extension resolution
• Configuration caching - Cache processed configurations

Error Handling

The configuration loader provides comprehensive error handling:

Configuration Errors

• File not found - Clear error messages for missing configuration files
• Parse errors - Detailed parsing error information with line numbers
• Schema validation - Validation errors with property paths and descriptions

Extension Errors

• Extension not found - Clear messages for missing extensions
• Extension loading failures - Detailed error information for failed extensions
• Version conflicts - Information about extension version mismatches

Network Errors

• Timeout errors - Clear timeout messages with retry suggestions
• Connection errors - Network connectivity error information
• Authentication errors - Authentication failure details

Performance Considerations

Optimization Strategies

• Parallel loading - Load multiple configurations concurrently
• Caching - Cache frequently accessed configurations and extensions
• Lazy loading - Load extensions only when needed
• Incremental processing - Process configurations incrementally

Resource Management

• Memory usage - Efficient memory usage for large configurations
• File handles - Proper cleanup of file system resources
• Network connections - Efficient network resource management