refactor: add upm application facade and module api

crates/upm-module-api/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "upm-module-api"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[lib]
+path = "src/lib.rs"
+
+[dependencies]
+serde.workspace = true

crates/upm-module-api/src/adapters/mod.rs

@@ -0,0 +1 @@
+pub mod traits;

crates/upm-module-api/src/adapters/traits.rs

@@ -0,0 +1,73 @@
+use crate::domain::source::{ResolvedRelease, SourceKind, SourceRef};
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct AdapterCapabilities {
+    pub supports_search: bool,
+    pub supports_exact_resolution: bool,
+}
+
+impl AdapterCapabilities {
+    pub fn exact_resolution_only() -> Self {
+        Self {
+            supports_search: false,
+            supports_exact_resolution: true,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct AdapterResolution {
+    pub source: SourceRef,
+    pub release: ResolvedRelease,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum AdapterResolveOutcome {
+    Resolved(AdapterResolution),
+    NoInstallableArtifact { source: SourceRef },
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum AdapterError {
+    UnsupportedQuery,
+    UnsupportedSource,
+    ResolutionFailed(String),
+}
+
+pub trait SourceAdapter {
+    fn id(&self) -> &'static str;
+
+    fn capabilities(&self) -> AdapterCapabilities;
+
+    fn repository_source_kind(&self) -> Option<SourceKind> {
+        None
+    }
+
+    fn exact_source_kind(&self) -> Option<SourceKind> {
+        None
+    }
+
+    fn normalize(&self, query: &str) -> Result<SourceRef, AdapterError>;
+
+    fn resolve(&self, source: &SourceRef) -> Result<AdapterResolution, AdapterError>;
+
+    fn resolve_supported_source(
+        &self,
+        source: &SourceRef,
+    ) -> Result<AdapterResolveOutcome, AdapterError> {
+        self.resolve(source).map(AdapterResolveOutcome::Resolved)
+    }
+
+    fn supports_source(&self, source: &SourceRef) -> bool {
+        self.repository_source_kind() == Some(source.kind)
+            || self.exact_source_kind() == Some(source.kind)
+    }
+
+    fn resolve_source(&self, source: &SourceRef) -> Result<AdapterResolveOutcome, AdapterError> {
+        if !self.supports_source(source) {
+            return Err(AdapterError::UnsupportedSource);
+        }
+
+        self.resolve_supported_source(source)
+    }
+}

crates/upm-module-api/src/app/mod.rs

@@ -0,0 +1,2 @@
+pub mod providers;
+pub mod search;

crates/upm-module-api/src/app/providers.rs

@@ -0,0 +1,42 @@
+use crate::adapters::traits::{AdapterError, AdapterResolution};
+use crate::app::search::SearchProvider;
+use crate::domain::source::SourceRef;
+use crate::domain::update::{ArtifactCandidate, UpdateStrategy};
+
+pub trait ExternalAddProvider {
+    fn id(&self) -> &'static str;
+
+    fn resolve(&self, source: &SourceRef) -> Result<Option<ExternalAddResolution>, AdapterError>;
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ExternalAddResolution {
+    pub resolution: AdapterResolution,
+    pub selected_artifact: ArtifactCandidate,
+    pub update_strategy: UpdateStrategy,
+    pub display_name_hint: Option<String>,
+}
+
+#[derive(Default)]
+pub struct ProviderRegistry<'a> {
+    pub search_providers: Vec<Box<dyn SearchProvider + 'a>>,
+    pub external_add_providers: Vec<Box<dyn ExternalAddProvider + 'a>>,
+}
+
+impl<'a> ProviderRegistry<'a> {
+    pub fn with_search_provider<P>(mut self, provider: P) -> Self
+    where
+        P: SearchProvider + 'a,
+    {
+        self.search_providers.push(Box::new(provider));
+        self
+    }
+
+    pub fn with_external_add_provider<P>(mut self, provider: P) -> Self
+    where
+        P: ExternalAddProvider + 'a,
+    {
+        self.external_add_providers.push(Box::new(provider));
+        self
+    }
+}

crates/upm-module-api/src/app/search.rs

@@ -0,0 +1,23 @@
+use crate::domain::search::SearchResult;
+
+pub trait SearchProvider {
+    fn search(
+        &self,
+        query: &crate::domain::search::SearchQuery,
+    ) -> Result<Vec<SearchResult>, SearchProviderError>;
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SearchProviderError {
+    pub provider_id: String,
+    pub message: String,
+}
+
+impl SearchProviderError {
+    pub fn new(provider_id: &str, message: &str) -> Self {
+        Self {
+            provider_id: provider_id.to_owned(),
+            message: message.to_owned(),
+        }
+    }
+}

crates/upm-module-api/src/domain/mod.rs

@@ -0,0 +1,3 @@
+pub mod search;
+pub mod source;
+pub mod update;

crates/upm-module-api/src/domain/search.rs

@@ -0,0 +1,68 @@
+pub const DEFAULT_REMOTE_LIMIT: usize = 10;
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum SearchInstallStatus {
+    Available,
+    Installed {
+        installed_version: Option<String>,
+    },
+    UpdateAvailable {
+        installed_version: Option<String>,
+        latest_version: Option<String>,
+    },
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SearchQuery {
+    pub text: String,
+    pub remote_limit: usize,
+}
+
+impl SearchQuery {
+    pub fn new(text: &str) -> Self {
+        Self {
+            text: text.to_owned(),
+            remote_limit: DEFAULT_REMOTE_LIMIT,
+        }
+    }
+
+    pub fn with_remote_limit(text: &str, remote_limit: usize) -> Self {
+        Self {
+            text: text.to_owned(),
+            remote_limit,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SearchResult {
+    pub provider_id: String,
+    pub display_name: String,
+    pub description: Option<String>,
+    pub source_locator: String,
+    pub install_query: String,
+    pub canonical_locator: String,
+    pub version: Option<String>,
+    pub install_status: SearchInstallStatus,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct InstalledSearchMatch {
+    pub stable_id: String,
+    pub display_name: String,
+    pub installed_version: Option<String>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SearchWarning {
+    pub provider_id: Option<String>,
+    pub message: String,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SearchResults {
+    pub query_text: String,
+    pub remote_hits: Vec<SearchResult>,
+    pub installed_matches: Vec<InstalledSearchMatch>,
+    pub warnings: Vec<SearchWarning>,
+}

crates/upm-module-api/src/domain/source.rs

@@ -0,0 +1,117 @@
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub enum SourceKind {
+    GitHub,
+    GitLab,
+    AppImageHub,
+    SourceForge,
+    DirectUrl,
+    File,
+}
+
+impl SourceKind {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::GitHub => "github",
+            Self::GitLab => "gitlab",
+            Self::AppImageHub => "appimagehub",
+            Self::SourceForge => "sourceforge",
+            Self::DirectUrl => "direct-url",
+            Self::File => "file",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub enum SourceInputKind {
+    RepoShorthand,
+    GitHubRepositoryUrl,
+    GitHubReleaseUrl,
+    GitHubReleaseAssetUrl,
+    GitLabUrl,
+    AppImageHubUrl,
+    AppImageHubShorthand,
+    SourceForgeUrl,
+    DirectUrl,
+    File,
+}
+
+impl SourceInputKind {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::RepoShorthand => "repo-shorthand",
+            Self::GitHubRepositoryUrl => "github-repository-url",
+            Self::GitHubReleaseUrl => "github-release-url",
+            Self::GitHubReleaseAssetUrl => "github-release-asset-url",
+            Self::GitLabUrl => "gitlab-url",
+            Self::AppImageHubUrl => "appimagehub-url",
+            Self::AppImageHubShorthand => "appimagehub-shorthand",
+            Self::SourceForgeUrl => "sourceforge-url",
+            Self::DirectUrl => "direct-url",
+            Self::File => "file",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub enum NormalizedSourceKind {
+    GitHubRepository,
+    GitHubRelease,
+    GitHubReleaseAsset,
+    GitLab,
+    GitLabCandidate,
+    AppImageHub,
+    SourceForge,
+    SourceForgeCandidate,
+    DirectUrl,
+    File,
+}
+
+impl NormalizedSourceKind {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::GitHubRepository => "github-repository",
+            Self::GitHubRelease => "github-release",
+            Self::GitHubReleaseAsset => "github-release-asset",
+            Self::GitLab => "gitlab",
+            Self::GitLabCandidate => "gitlab-candidate",
+            Self::AppImageHub => "appimagehub",
+            Self::SourceForge => "sourceforge",
+            Self::SourceForgeCandidate => "sourceforge-candidate",
+            Self::DirectUrl => "direct-url",
+            Self::File => "file",
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct SourceRef {
+    pub kind: SourceKind,
+    pub locator: String,
+    #[serde(default = "default_source_input_kind")]
+    pub input_kind: SourceInputKind,
+    #[serde(default = "default_normalized_source_kind")]
+    pub normalized_kind: NormalizedSourceKind,
+    #[serde(default)]
+    pub canonical_locator: Option<String>,
+    #[serde(default)]
+    pub requested_tag: Option<String>,
+    #[serde(default)]
+    pub requested_asset_name: Option<String>,
+    #[serde(default)]
+    pub tracks_latest: bool,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct ResolvedRelease {
+    pub version: String,
+    #[serde(default)]
+    pub prerelease: bool,
+}
+
+const fn default_source_input_kind() -> SourceInputKind {
+    SourceInputKind::DirectUrl
+}
+
+const fn default_normalized_source_kind() -> NormalizedSourceKind {
+    NormalizedSourceKind::DirectUrl
+}

crates/upm-module-api/src/domain/update.rs

@@ -0,0 +1,42 @@
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub enum UpdateChannelKind {
+    GitHubReleases,
+    ElectronBuilder,
+    Zsync,
+    DirectAsset,
+}
+
+impl UpdateChannelKind {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::GitHubReleases => "github-releases",
+            Self::ElectronBuilder => "electron-builder",
+            Self::Zsync => "zsync",
+            Self::DirectAsset => "direct-asset-lineage",
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct ChannelPreference {
+    pub kind: UpdateChannelKind,
+    pub locator: String,
+    pub reason: String,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct UpdateStrategy {
+    pub preferred: ChannelPreference,
+    #[serde(default)]
+    pub alternates: Vec<ChannelPreference>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ArtifactCandidate {
+    pub url: String,
+    pub version: String,
+    pub arch: Option<String>,
+    pub trusted_checksum: Option<String>,
+    pub weak_checksum_md5: Option<String>,
+    pub selection_reason: String,
+}

crates/upm-module-api/src/lib.rs

@@ -0,0 +1,3 @@
+pub mod adapters;
+pub mod app;
+pub mod domain;