@push.rocks/smartregistry 2.2.3 → 2.3.0

package/dist_ts/upstream/interfaces.upstream.d.ts

@@ -0,0 +1,169 @@
+import type { TRegistryProtocol } from '../core/interfaces.core.js';
+/**
+ * Scope rule for routing requests to specific upstreams.
+ * Uses glob patterns for flexible matching.
+ */
+export interface IUpstreamScopeRule {
+    /** Glob pattern (e.g., "@company/*", "com.example.*", "library/*") */
+    pattern: string;
+    /** Whether matching resources should be included or excluded */
+    action: 'include' | 'exclude';
+}
+/**
+ * Authentication configuration for an upstream registry.
+ * Supports multiple auth strategies.
+ */
+export interface IUpstreamAuthConfig {
+    /** Authentication type */
+    type: 'none' | 'basic' | 'bearer' | 'api-key';
+    /** Username for basic auth */
+    username?: string;
+    /** Password for basic auth */
+    password?: string;
+    /** Token for bearer or api-key auth */
+    token?: string;
+    /** Custom header name for api-key auth (default: 'Authorization') */
+    headerName?: string;
+}
+/**
+ * Cache configuration for upstream content.
+ */
+export interface IUpstreamCacheConfig {
+    /** Whether caching is enabled */
+    enabled: boolean;
+    /** Default TTL in seconds for mutable content (default: 300 = 5 min) */
+    defaultTtlSeconds: number;
+    /** TTL in seconds for immutable/content-addressable content (default: 2592000 = 30 days) */
+    immutableTtlSeconds: number;
+    /** Whether to serve stale content while revalidating in background */
+    staleWhileRevalidate: boolean;
+    /** Maximum age in seconds for stale content (default: 3600 = 1 hour) */
+    staleMaxAgeSeconds: number;
+    /** TTL in seconds for negative cache entries (404s) (default: 60 = 1 min) */
+    negativeCacheTtlSeconds: number;
+}
+/**
+ * Resilience configuration for upstream requests.
+ */
+export interface IUpstreamResilienceConfig {
+    /** Request timeout in milliseconds (default: 30000) */
+    timeoutMs: number;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Initial retry delay in milliseconds (default: 1000) */
+    retryDelayMs: number;
+    /** Maximum retry delay in milliseconds (default: 30000) */
+    retryMaxDelayMs: number;
+    /** Number of failures before circuit breaker opens (default: 5) */
+    circuitBreakerThreshold: number;
+    /** Time in milliseconds before circuit breaker attempts reset (default: 30000) */
+    circuitBreakerResetMs: number;
+}
+/**
+ * Configuration for a single upstream registry.
+ */
+export interface IUpstreamRegistryConfig {
+    /** Unique identifier for this upstream */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Base URL of the upstream registry (e.g., "https://registry.npmjs.org") */
+    url: string;
+    /** Priority for routing (lower = higher priority, 1 = first) */
+    priority: number;
+    /** Whether this upstream is enabled */
+    enabled: boolean;
+    /** Scope rules for routing (empty = match all) */
+    scopeRules?: IUpstreamScopeRule[];
+    /** Authentication configuration */
+    auth: IUpstreamAuthConfig;
+    /** Cache configuration overrides */
+    cache?: Partial<IUpstreamCacheConfig>;
+    /** Resilience configuration overrides */
+    resilience?: Partial<IUpstreamResilienceConfig>;
+}
+/**
+ * Protocol-level upstream configuration.
+ * Configures upstream behavior for a specific protocol (npm, oci, etc.)
+ */
+export interface IProtocolUpstreamConfig {
+    /** Whether upstream is enabled for this protocol */
+    enabled: boolean;
+    /** List of upstream registries, ordered by priority */
+    upstreams: IUpstreamRegistryConfig[];
+    /** Protocol-level cache configuration defaults */
+    cache?: Partial<IUpstreamCacheConfig>;
+    /** Protocol-level resilience configuration defaults */
+    resilience?: Partial<IUpstreamResilienceConfig>;
+}
+/**
+ * Result of an upstream fetch operation.
+ */
+export interface IUpstreamResult {
+    /** Whether the fetch was successful (2xx status) */
+    success: boolean;
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Response body (Buffer for binary, object for JSON) */
+    body?: Buffer | any;
+    /** ID of the upstream that served the request */
+    upstreamId: string;
+    /** Whether the response was served from cache */
+    fromCache: boolean;
+    /** Request latency in milliseconds */
+    latencyMs: number;
+}
+/**
+ * Circuit breaker state.
+ */
+export type TCircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/**
+ * Context for an upstream fetch request.
+ */
+export interface IUpstreamFetchContext {
+    /** Protocol type */
+    protocol: TRegistryProtocol;
+    /** Resource identifier (package name, artifact name, etc.) */
+    resource: string;
+    /** Type of resource being fetched (packument, tarball, manifest, blob, etc.) */
+    resourceType: string;
+    /** Original request path */
+    path: string;
+    /** HTTP method */
+    method: string;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Query parameters */
+    query: Record<string, string>;
+}
+/**
+ * Cache entry stored in the upstream cache.
+ */
+export interface ICacheEntry {
+    /** Cached data */
+    data: Buffer;
+    /** Content type of the cached data */
+    contentType: string;
+    /** Original response headers */
+    headers: Record<string, string>;
+    /** When the entry was cached */
+    cachedAt: Date;
+    /** When the entry expires */
+    expiresAt?: Date;
+    /** ETag for conditional requests */
+    etag?: string;
+    /** ID of the upstream that provided the data */
+    upstreamId: string;
+    /** Whether the entry is stale but still usable */
+    stale?: boolean;
+}
+/**
+ * Default cache configuration values.
+ */
+export declare const DEFAULT_CACHE_CONFIG: IUpstreamCacheConfig;
+/**
+ * Default resilience configuration values.
+ */
+export declare const DEFAULT_RESILIENCE_CONFIG: IUpstreamResilienceConfig;

package/dist_ts/upstream/interfaces.upstream.js

@@ -0,0 +1,23 @@
+/**
+ * Default cache configuration values.
+ */
+export const DEFAULT_CACHE_CONFIG = {
+    enabled: true,
+    defaultTtlSeconds: 300, // 5 minutes
+    immutableTtlSeconds: 2592000, // 30 days
+    staleWhileRevalidate: true,
+    staleMaxAgeSeconds: 3600, // 1 hour
+    negativeCacheTtlSeconds: 60, // 1 minute
+};
+/**
+ * Default resilience configuration values.
+ */
+export const DEFAULT_RESILIENCE_CONFIG = {
+    timeoutMs: 30000,
+    maxRetries: 3,
+    retryDelayMs: 1000,
+    retryMaxDelayMs: 30000,
+    circuitBreakerThreshold: 5,
+    circuitBreakerResetMs: 30000,
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy51cHN0cmVhbS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3Vwc3RyZWFtL2ludGVyZmFjZXMudXBzdHJlYW0udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBNEtBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sb0JBQW9CLEdBQXlCO0lBQ3hELE9BQU8sRUFBRSxJQUFJO0lBQ2IsaUJBQWlCLEVBQUUsR0FBRyxFQUFZLFlBQVk7SUFDOUMsbUJBQW1CLEVBQUUsT0FBTyxFQUFNLFVBQVU7SUFDNUMsb0JBQW9CLEVBQUUsSUFBSTtJQUMxQixrQkFBa0IsRUFBRSxJQUFJLEVBQVUsU0FBUztJQUMzQyx1QkFBdUIsRUFBRSxFQUFFLEVBQU8sV0FBVztDQUM5QyxDQUFDO0FBRUY7O0dBRUc7QUFDSCxNQUFNLENBQUMsTUFBTSx5QkFBeUIsR0FBOEI7SUFDbEUsU0FBUyxFQUFFLEtBQUs7SUFDaEIsVUFBVSxFQUFFLENBQUM7SUFDYixZQUFZLEVBQUUsSUFBSTtJQUNsQixlQUFlLEVBQUUsS0FBSztJQUN0Qix1QkFBdUIsRUFBRSxDQUFDO0lBQzFCLHFCQUFxQixFQUFFLEtBQUs7Q0FDN0IsQ0FBQyJ9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartregistry",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "private": false,
   "description": "A composable TypeScript library implementing OCI, NPM, Maven, Cargo, Composer, PyPI, and RubyGems registries for building unified container and package registries",
   "main": "dist_ts/index.js",
@@ -42,8 +42,10 @@
     "@push.rocks/smartbucket": "^4.3.0",
     "@push.rocks/smartlog": "^3.1.10",
     "@push.rocks/smartpath": "^6.0.0",
+    "@push.rocks/smartrequest": "^5.0.1",
     "@tsclass/tsclass": "^9.3.0",
-    "adm-zip": "^0.5.10"
+    "adm-zip": "^0.5.10",
+    "minimatch": "^10.1.1"
   },
   "scripts": {
     "test": "(tstest test/ --verbose --logfile --timeout 240)",

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartregistry',
-  version: '2.2.3',
+  version: '2.3.0',
   description: 'A composable TypeScript library implementing OCI, NPM, Maven, Cargo, Composer, PyPI, and RubyGems registries for building unified container and package registries'
 }

package/ts/cargo/classes.cargoregistry.ts

@@ -3,6 +3,7 @@ import { BaseRegistry } from '../core/classes.baseregistry.js';
 import { RegistryStorage } from '../core/classes.registrystorage.js';
 import { AuthManager } from '../core/classes.authmanager.js';
 import type { IRequestContext, IResponse, IAuthToken } from '../core/interfaces.core.js';
+import type { IProtocolUpstreamConfig } from '../upstream/interfaces.upstream.js';
 import type {
   ICargoIndexEntry,
   ICargoPublishMetadata,
@@ -13,6 +14,7 @@ import type {
   ICargoSearchResponse,
   ICargoSearchResult,
 } from './interfaces.cargo.js';
+import { CargoUpstream } from './classes.cargoupstream.js';
 
 /**
  * Cargo/crates.io registry implementation
@@ -25,12 +27,14 @@ export class CargoRegistry extends BaseRegistry {
   private basePath: string = '/cargo';
   private registryUrl: string;
   private logger: Smartlog;
+  private upstream: CargoUpstream | null = null;
 
   constructor(
     storage: RegistryStorage,
     authManager: AuthManager,
     basePath: string = '/cargo',
-    registryUrl: string = 'http://localhost:5000/cargo'
+    registryUrl: string = 'http://localhost:5000/cargo',
+    upstreamConfig?: IProtocolUpstreamConfig
   ) {
     super();
     this.storage = storage;
@@ -50,6 +54,20 @@ export class CargoRegistry extends BaseRegistry {
       }
     });
     this.logger.enableConsole();
+
+    // Initialize upstream if configured
+    if (upstreamConfig?.enabled) {
+      this.upstream = new CargoUpstream(upstreamConfig, undefined, this.logger);
+    }
+  }
+
+  /**
+   * Clean up resources (timers, connections, etc.)
+   */
+  public destroy(): void {
+    if (this.upstream) {
+      this.upstream.stop();
+    }
   }
 
   public async init(): Promise<void> {
@@ -207,7 +225,25 @@ export class CargoRegistry extends BaseRegistry {
    * Serve index file for a crate
    */
   private async handleIndexFile(crateName: string): Promise<IResponse> {
-    const index = await this.storage.getCargoIndex(crateName);
+    let index = await this.storage.getCargoIndex(crateName);
+
+    // Try upstream if not found locally
+    if ((!index || index.length === 0) && this.upstream) {
+      const upstreamIndex = await this.upstream.fetchCrateIndex(crateName);
+      if (upstreamIndex) {
+        // Parse the newline-delimited JSON
+        const parsedIndex: ICargoIndexEntry[] = upstreamIndex
+          .split('\n')
+          .filter(line => line.trim())
+          .map(line => JSON.parse(line));
+
+        if (parsedIndex.length > 0) {
+          // Cache locally
+          await this.storage.putCargoIndex(crateName, parsedIndex);
+          index = parsedIndex;
+        }
+      }
+    }
 
     if (!index || index.length === 0) {
       return {
@@ -399,7 +435,16 @@ export class CargoRegistry extends BaseRegistry {
   ): Promise<IResponse> {
     this.logger.log('debug', 'handleDownload', { crate: crateName, version });
 
-    const crateFile = await this.storage.getCargoCrate(crateName, version);
+    let crateFile = await this.storage.getCargoCrate(crateName, version);
+
+    // Try upstream if not found locally
+    if (!crateFile && this.upstream) {
+      crateFile = await this.upstream.fetchCrate(crateName, version);
+      if (crateFile) {
+        // Cache locally
+        await this.storage.putCargoCrate(crateName, version, crateFile);
+      }
+    }
 
     if (!crateFile) {
       return {

package/ts/cargo/classes.cargoupstream.ts

@@ -0,0 +1,159 @@
+import * as plugins from '../plugins.js';
+import { BaseUpstream } from '../upstream/classes.baseupstream.js';
+import type {
+  IProtocolUpstreamConfig,
+  IUpstreamFetchContext,
+  IUpstreamRegistryConfig,
+} from '../upstream/interfaces.upstream.js';
+
+/**
+ * Cargo-specific upstream implementation.
+ *
+ * Handles:
+ * - Crate metadata (index) fetching
+ * - Crate file (.crate) downloading
+ * - Sparse index protocol support
+ * - Content-addressable caching for .crate files
+ */
+export class CargoUpstream extends BaseUpstream {
+  protected readonly protocolName = 'cargo';
+
+  /** Base URL for crate downloads (may differ from index URL) */
+  private readonly downloadUrl: string;
+
+  constructor(
+    config: IProtocolUpstreamConfig,
+    downloadUrl?: string,
+    logger?: plugins.smartlog.Smartlog,
+  ) {
+    super(config, logger);
+    // Default to crates.io download URL if not specified
+    this.downloadUrl = downloadUrl || 'https://static.crates.io/crates';
+  }
+
+  /**
+   * Fetch crate metadata from the sparse index.
+   */
+  public async fetchCrateIndex(crateName: string): Promise<string | null> {
+    const path = this.buildIndexPath(crateName);
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'cargo',
+      resource: crateName,
+      resourceType: 'index',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'text/plain',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    if (Buffer.isBuffer(result.body)) {
+      return result.body.toString('utf8');
+    }
+
+    return typeof result.body === 'string' ? result.body : null;
+  }
+
+  /**
+   * Fetch a crate file from upstream.
+   */
+  public async fetchCrate(crateName: string, version: string): Promise<Buffer | null> {
+    // Crate downloads typically go to a different URL than the index
+    const path = `/${crateName}/${crateName}-${version}.crate`;
+
+    const context: IUpstreamFetchContext = {
+      protocol: 'cargo',
+      resource: crateName,
+      resourceType: 'crate',
+      path,
+      method: 'GET',
+      headers: {
+        'accept': 'application/octet-stream',
+      },
+      query: {},
+    };
+
+    // Use special handling for crate downloads
+    const result = await this.fetchCrateFile(crateName, version);
+    return result;
+  }
+
+  /**
+   * Fetch crate file directly from the download URL.
+   */
+  private async fetchCrateFile(crateName: string, version: string): Promise<Buffer | null> {
+    const context: IUpstreamFetchContext = {
+      protocol: 'cargo',
+      resource: crateName,
+      resourceType: 'crate',
+      path: `/${crateName}/${crateName}-${version}.crate`,
+      method: 'GET',
+      headers: {
+        'accept': 'application/octet-stream',
+      },
+      query: {},
+    };
+
+    const result = await this.fetch(context);
+
+    if (!result || !result.success) {
+      return null;
+    }
+
+    return Buffer.isBuffer(result.body) ? result.body : Buffer.from(result.body);
+  }
+
+  /**
+   * Build the sparse index path for a crate.
+   *
+   * Path structure:
+   * - 1 char: /1/{name}
+   * - 2 chars: /2/{name}
+   * - 3 chars: /3/{first char}/{name}
+   * - 4+ chars: /{first 2}/{next 2}/{name}
+   */
+  private buildIndexPath(crateName: string): string {
+    const lowerName = crateName.toLowerCase();
+    const len = lowerName.length;
+
+    if (len === 1) {
+      return `/1/${lowerName}`;
+    } else if (len === 2) {
+      return `/2/${lowerName}`;
+    } else if (len === 3) {
+      return `/3/${lowerName[0]}/${lowerName}`;
+    } else {
+      return `/${lowerName.slice(0, 2)}/${lowerName.slice(2, 4)}/${lowerName}`;
+    }
+  }
+
+  /**
+   * Override URL building for Cargo-specific handling.
+   */
+  protected buildUpstreamUrl(
+    upstream: IUpstreamRegistryConfig,
+    context: IUpstreamFetchContext,
+  ): string {
+    let baseUrl = upstream.url;
+
+    // For crate downloads, use the download URL
+    if (context.resourceType === 'crate') {
+      baseUrl = this.downloadUrl;
+    }
+
+    // Remove trailing slash
+    if (baseUrl.endsWith('/')) {
+      baseUrl = baseUrl.slice(0, -1);
+    }
+
+    return `${baseUrl}${context.path}`;
+  }
+}

package/ts/cargo/index.ts

@@ -3,4 +3,5 @@
  */
 
 export { CargoRegistry } from './classes.cargoregistry.js';
+export { CargoUpstream } from './classes.cargoupstream.js';
 export * from './interfaces.cargo.js';

package/ts/classes.smartregistry.ts

@@ -46,7 +46,13 @@ export class SmartRegistry {
         realm: this.config.auth.ociTokens.realm,
         service: this.config.auth.ociTokens.service,
       } : undefined;
-      const ociRegistry = new OciRegistry(this.storage, this.authManager, ociBasePath, ociTokens);
+      const ociRegistry = new OciRegistry(
+        this.storage,
+        this.authManager,
+        ociBasePath,
+        ociTokens,
+        this.config.oci.upstream
+      );
       await ociRegistry.init();
       this.registries.set('oci', ociRegistry);
     }
@@ -55,7 +61,13 @@ export class SmartRegistry {
     if (this.config.npm?.enabled) {
       const npmBasePath = this.config.npm.basePath ?? '/npm';
       const registryUrl = `http://localhost:5000${npmBasePath}`; // TODO: Make configurable
-      const npmRegistry = new NpmRegistry(this.storage, this.authManager, npmBasePath, registryUrl);
+      const npmRegistry = new NpmRegistry(
+        this.storage,
+        this.authManager,
+        npmBasePath,
+        registryUrl,
+        this.config.npm.upstream
+      );
       await npmRegistry.init();
       this.registries.set('npm', npmRegistry);
     }
@@ -64,7 +76,13 @@ export class SmartRegistry {
     if (this.config.maven?.enabled) {
       const mavenBasePath = this.config.maven.basePath ?? '/maven';
       const registryUrl = `http://localhost:5000${mavenBasePath}`; // TODO: Make configurable
-      const mavenRegistry = new MavenRegistry(this.storage, this.authManager, mavenBasePath, registryUrl);
+      const mavenRegistry = new MavenRegistry(
+        this.storage,
+        this.authManager,
+        mavenBasePath,
+        registryUrl,
+        this.config.maven.upstream
+      );
       await mavenRegistry.init();
       this.registries.set('maven', mavenRegistry);
     }
@@ -73,7 +91,13 @@ export class SmartRegistry {
     if (this.config.cargo?.enabled) {
       const cargoBasePath = this.config.cargo.basePath ?? '/cargo';
       const registryUrl = `http://localhost:5000${cargoBasePath}`; // TODO: Make configurable
-      const cargoRegistry = new CargoRegistry(this.storage, this.authManager, cargoBasePath, registryUrl);
+      const cargoRegistry = new CargoRegistry(
+        this.storage,
+        this.authManager,
+        cargoBasePath,
+        registryUrl,
+        this.config.cargo.upstream
+      );
       await cargoRegistry.init();
       this.registries.set('cargo', cargoRegistry);
     }
@@ -82,7 +106,13 @@ export class SmartRegistry {
     if (this.config.composer?.enabled) {
       const composerBasePath = this.config.composer.basePath ?? '/composer';
       const registryUrl = `http://localhost:5000${composerBasePath}`; // TODO: Make configurable
-      const composerRegistry = new ComposerRegistry(this.storage, this.authManager, composerBasePath, registryUrl);
+      const composerRegistry = new ComposerRegistry(
+        this.storage,
+        this.authManager,
+        composerBasePath,
+        registryUrl,
+        this.config.composer.upstream
+      );
       await composerRegistry.init();
       this.registries.set('composer', composerRegistry);
     }
@@ -91,7 +121,13 @@ export class SmartRegistry {
     if (this.config.pypi?.enabled) {
       const pypiBasePath = this.config.pypi.basePath ?? '/pypi';
       const registryUrl = `http://localhost:5000`; // TODO: Make configurable
-      const pypiRegistry = new PypiRegistry(this.storage, this.authManager, pypiBasePath, registryUrl);
+      const pypiRegistry = new PypiRegistry(
+        this.storage,
+        this.authManager,
+        pypiBasePath,
+        registryUrl,
+        this.config.pypi.upstream
+      );
       await pypiRegistry.init();
       this.registries.set('pypi', pypiRegistry);
     }
@@ -100,7 +136,13 @@ export class SmartRegistry {
     if (this.config.rubygems?.enabled) {
       const rubygemsBasePath = this.config.rubygems.basePath ?? '/rubygems';
       const registryUrl = `http://localhost:5000${rubygemsBasePath}`; // TODO: Make configurable
-      const rubygemsRegistry = new RubyGemsRegistry(this.storage, this.authManager, rubygemsBasePath, registryUrl);
+      const rubygemsRegistry = new RubyGemsRegistry(
+        this.storage,
+        this.authManager,
+        rubygemsBasePath,
+        registryUrl,
+        this.config.rubygems.upstream
+      );
       await rubygemsRegistry.init();
       this.registries.set('rubygems', rubygemsRegistry);
     }

package/ts/composer/classes.composerregistry.ts

@@ -7,6 +7,7 @@ import { BaseRegistry } from '../core/classes.baseregistry.js';
 import type { RegistryStorage } from '../core/classes.registrystorage.js';
 import type { AuthManager } from '../core/classes.authmanager.js';
 import type { IRequestContext, IResponse, IAuthToken } from '../core/interfaces.core.js';
+import type { IProtocolUpstreamConfig } from '../upstream/interfaces.upstream.js';
 import { isBinaryData, toBuffer } from '../core/helpers.buffer.js';
 import type {
   IComposerPackage,
@@ -22,24 +23,41 @@ import {
   generatePackagesJson,
   sortVersions,
 } from './helpers.composer.js';
+import { ComposerUpstream } from './classes.composerupstream.js';
 
 export class ComposerRegistry extends BaseRegistry {
   private storage: RegistryStorage;
   private authManager: AuthManager;
   private basePath: string = '/composer';
   private registryUrl: string;
+  private upstream: ComposerUpstream | null = null;
 
   constructor(
     storage: RegistryStorage,
     authManager: AuthManager,
     basePath: string = '/composer',
-    registryUrl: string = 'http://localhost:5000/composer'
+    registryUrl: string = 'http://localhost:5000/composer',
+    upstreamConfig?: IProtocolUpstreamConfig
   ) {
     super();
     this.storage = storage;
     this.authManager = authManager;
     this.basePath = basePath;
     this.registryUrl = registryUrl;
+
+    // Initialize upstream if configured
+    if (upstreamConfig?.enabled) {
+      this.upstream = new ComposerUpstream(upstreamConfig);
+    }
+  }
+
+  /**
+   * Clean up resources (timers, connections, etc.)
+   */
+  public destroy(): void {
+    if (this.upstream) {
+      this.upstream.stop();
+    }
   }
 
   public async init(): Promise<void> {
@@ -161,7 +179,26 @@ export class ComposerRegistry extends BaseRegistry {
     token: IAuthToken | null
   ): Promise<IResponse> {
     // Read operations are public, no authentication required
-    const metadata = await this.storage.getComposerPackageMetadata(vendorPackage);
+    let metadata = await this.storage.getComposerPackageMetadata(vendorPackage);
+
+    // Try upstream if not found locally
+    if (!metadata && this.upstream) {
+      const [vendor, packageName] = vendorPackage.split('/');
+      if (vendor && packageName) {
+        const upstreamMetadata = includeDev
+          ? await this.upstream.fetchPackageDevMetadata(vendor, packageName)
+          : await this.upstream.fetchPackageMetadata(vendor, packageName);
+
+        if (upstreamMetadata && upstreamMetadata.packages) {
+          // Store upstream metadata locally
+          metadata = {
+            packages: upstreamMetadata.packages,
+            lastModified: new Date().toUTCString(),
+          };
+          await this.storage.putComposerPackageMetadata(vendorPackage, metadata);
+        }
+      }
+    }
 
     if (!metadata) {
       return {