Trait Registry 

pub trait Registry: Send + Sync {
    // Required methods
    fn get_versions<'a>(
        &'a self,
        name: &'a str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Box<dyn Version>>>> + Send + 'a>>;
    fn get_latest_matching<'a>(
        &'a self,
        name: &'a str,
        req: &'a str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Box<dyn Version>>>> + Send + 'a>>;
    fn search<'a>(
        &'a self,
        query: &'a str,
        limit: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Box<dyn Metadata>>>> + Send + 'a>>;
    fn package_url(&self, name: &str) -> String;
    fn as_any(&self) -> &dyn Any;
}

Generic package registry interface.

Implementors provide access to a package registry (crates.io, npm, PyPI, etc.) with version lookup, search, and metadata retrieval capabilities.

All methods return Result<T> to allow graceful error handling. LSP handlers must never panic on registry errors.

Type Erasure

This trait uses Box<dyn Trait> return types instead of associated types to allow runtime polymorphism and dynamic ecosystem registration.

Examples

use deps_core::{Registry, Version, Metadata};
use std::any::Any;
use std::pin::Pin;

struct MyRegistry;

#[derive(Clone)]
struct MyVersion { version: String }

impl Version for MyVersion {
    fn version_string(&self) -> &str { &self.version }
    fn is_yanked(&self) -> bool { false }
    fn as_any(&self) -> &dyn Any { self }
}

#[derive(Clone)]
struct MyMetadata { name: String }

impl Metadata for MyMetadata {
    fn name(&self) -> &str { &self.name }
    fn description(&self) -> Option<&str> { None }
    fn repository(&self) -> Option<&str> { None }
    fn documentation(&self) -> Option<&str> { None }
    fn latest_version(&self) -> &str { "1.0.0" }
    fn as_any(&self) -> &dyn Any { self }
}

impl Registry for MyRegistry {
    fn get_versions<'a>(&'a self, _name: &'a str)
        -> Pin<Box<dyn std::future::Future<Output = deps_core::error::Result<Vec<Box<dyn Version>>>> + Send + 'a>>
    {
        Box::pin(async move { Ok(vec![Box::new(MyVersion { version: "1.0.0".into() }) as Box<dyn Version>]) })
    }

    fn get_latest_matching<'a>(&'a self, _name: &'a str, _req: &'a str)
        -> Pin<Box<dyn std::future::Future<Output = deps_core::error::Result<Option<Box<dyn Version>>>> + Send + 'a>>
    {
        Box::pin(async move { Ok(None) })
    }

    fn search<'a>(&'a self, _query: &'a str, _limit: usize)
        -> Pin<Box<dyn std::future::Future<Output = deps_core::error::Result<Vec<Box<dyn Metadata>>>> + Send + 'a>>
    {
        Box::pin(async move { Ok(vec![]) })
    }

    fn package_url(&self, name: &str) -> String {
        format!("https://example.com/packages/{}", name)
    }

    fn as_any(&self) -> &dyn Any { self }
}

Required Methods

fn get_versions<'a>( &'a self, name: &'a str, ) -> Pin<Box<dyn Future<Output = Result<Vec<Box<dyn Version>>>> + Send + 'a>>

Fetches all available versions for a package.

Returns versions sorted newest-first. May include yanked/deprecated versions.

Errors

Returns error if:

• Package does not exist
• Network request fails
• Response parsing fails

fn get_latest_matching<'a>( &'a self, name: &'a str, req: &'a str, ) -> Pin<Box<dyn Future<Output = Result<Option<Box<dyn Version>>>> + Send + 'a>>

Finds the latest version matching a version requirement.

Only returns stable (non-yanked, non-deprecated) versions unless explicitly requested in the version requirement.

Arguments

• name - Package name
• req - Version requirement string (e.g., “^1.0”, “>=2.0”)

Returns

• Ok(Some(version)) - Latest matching version found
• Ok(None) - No matching version found
• Err(_) - Network or parsing error

fn search<'a>( &'a self, query: &'a str, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Vec<Box<dyn Metadata>>>> + Send + 'a>>

Searches for packages by name or keywords.

Returns up to limit results sorted by relevance/popularity.

Errors

Returns error if network request or parsing fails.

fn package_url(&self, name: &str) -> String

Package URL for ecosystem (e.g., https://crates.io/crates/serde)

Returns a URL that links to the package page on the registry website.

fn as_any(&self) -> &dyn Any

Downcast to concrete registry type for ecosystem-specific operations

Implementors