From abaf15790d5954aa29dad60363a02a50c92a27f9 Mon Sep 17 00:00:00 2001
From: Lann Martin <lann.martin@fermyon.com>
Date: Fri, 21 Jun 2024 11:00:11 -0400
Subject: [PATCH 1/2] Move ContentDigest to wasm-pkg-common

---
 Cargo.lock                                             |  4 ++++
 crates/wasm-pkg-common/Cargo.toml                      | 10 +++++++++-
 .../src/release.rs => wasm-pkg-common/src/digest.rs}   | 10 ++--------
 crates/wasm-pkg-common/src/lib.rs                      |  1 +
 crates/wasm-pkg-loader/Cargo.toml                      | 10 +++++-----
 crates/wasm-pkg-loader/src/lib.rs                      | 10 +++++++---
 .../wasm-pkg-loader/src/{source/mod.rs => source.rs}   |  0
 7 files changed, 28 insertions(+), 17 deletions(-)
 rename crates/{wasm-pkg-loader/src/release.rs => wasm-pkg-common/src/digest.rs} (95%)
 rename crates/wasm-pkg-loader/src/{source/mod.rs => source.rs} (100%)

diff --git a/Cargo.lock b/Cargo.lock
index c765070..40e5d8b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3768,13 +3768,17 @@ name = "wasm-pkg-common"
 version = "0.4.1"
 dependencies = [
  "anyhow",
+ "bytes",
  "dirs",
+ "futures-util",
  "http",
  "reqwest",
  "semver",
  "serde 1.0.201",
  "serde_json",
+ "sha2",
  "thiserror",
+ "tokio",
  "toml 0.8.13",
  "tracing",
 ]
diff --git a/crates/wasm-pkg-common/Cargo.toml b/crates/wasm-pkg-common/Cargo.toml
index b395344..dd9df03 100644
--- a/crates/wasm-pkg-common/Cargo.toml
+++ b/crates/wasm-pkg-common/Cargo.toml
@@ -9,15 +9,23 @@ license.workspace = true
 
 [features]
 metadata-client = ["dep:reqwest"]
+tokio = ["dep:tokio"]
 
 [dependencies]
 anyhow = "1.0"
+bytes = "1.6.0"
 dirs = "5.0.1"
+futures-util = "0.3.30"
 http = "1.1.0"
 reqwest = { version = "0.12.0", features = ["json"], optional = true }
 semver = "1.0.23"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
+sha2 = "0.10.8"
+tokio = { workspace = true, features = ["io-util"], optional = true }
 toml = "0.8.13"
 thiserror = "1.0"
-tracing = "0.1"
\ No newline at end of file
+tracing = "0.1"
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["macros", "rt"] }
\ No newline at end of file
diff --git a/crates/wasm-pkg-loader/src/release.rs b/crates/wasm-pkg-common/src/digest.rs
similarity index 95%
rename from crates/wasm-pkg-loader/src/release.rs
rename to crates/wasm-pkg-common/src/digest.rs
index 0fa349b..1df4431 100644
--- a/crates/wasm-pkg-loader/src/release.rs
+++ b/crates/wasm-pkg-common/src/digest.rs
@@ -3,24 +3,18 @@ use std::path::Path;
 use bytes::Bytes;
 use futures_util::{future::ready, stream::once, Stream, StreamExt, TryStream, TryStreamExt};
 use sha2::{Digest, Sha256};
-use tokio::io::AsyncReadExt;
-use wasm_pkg_common::package::Version;
 
 use crate::Error;
 
-#[derive(Clone, Debug)]
-pub struct Release {
-    pub version: Version,
-    pub content_digest: ContentDigest,
-}
-
 #[derive(Clone, Debug, PartialEq)]
 pub enum ContentDigest {
     Sha256 { hex: String },
 }
 
 impl ContentDigest {
+    #[cfg(feature = "tokio")]
     pub async fn sha256_from_file(path: impl AsRef<Path>) -> Result<Self, std::io::Error> {
+        use tokio::io::AsyncReadExt;
         let mut file = tokio::fs::File::open(path).await?;
         let mut hasher = Sha256::new();
         let mut buf = [0; 4096];
diff --git a/crates/wasm-pkg-common/src/lib.rs b/crates/wasm-pkg-common/src/lib.rs
index d347a77..43941d1 100644
--- a/crates/wasm-pkg-common/src/lib.rs
+++ b/crates/wasm-pkg-common/src/lib.rs
@@ -6,6 +6,7 @@ pub mod label;
 pub mod metadata;
 pub mod package;
 pub mod registry;
+pub mod digest;
 
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
diff --git a/crates/wasm-pkg-loader/Cargo.toml b/crates/wasm-pkg-loader/Cargo.toml
index 7647058..9f7cb63 100644
--- a/crates/wasm-pkg-loader/Cargo.toml
+++ b/crates/wasm-pkg-loader/Cargo.toml
@@ -1,11 +1,11 @@
 [package]
 name = "wasm-pkg-loader"
 description = "Wasm package loader"
-authors.workspace = true
+repository = "https://github.com/bytecodealliance/wasm-pkg-tools/tree/main/crates/wasm-pkg-loader"
+edition.workspace = true
 version.workspace = true
+authors.workspace = true
 license.workspace = true
-edition.workspace = true
-repository = "https://github.com/bytecodealliance/wasm-pkg-tools/tree/main/crates/wasm-pkg-loader"
 
 [dependencies]
 anyhow = "1.0.79"
@@ -22,7 +22,7 @@ serde = { version = "1.0.194", features = ["derive"] }
 serde_json = "1.0.110"
 sha2 = "0.10.8"
 thiserror = "1.0.51"
-tokio = { version = "1.35.1", features = ["rt", "macros"] }
+tokio = { workspace = true, features = ["rt", "macros"] }
 tokio-util = { version = "0.7.10", features = ["io"] }
 toml = "0.8.8"
 tracing = "0.1.40"
@@ -30,4 +30,4 @@ tracing-subscriber = { workspace = true }
 url = "2.5.0"
 warg-client = "0.7.0"
 warg-protocol = "0.7.0"
-wasm-pkg-common = { workspace = true, features = ["metadata-client"] }
+wasm-pkg-common = { workspace = true, features = ["metadata-client", "tokio"] }
diff --git a/crates/wasm-pkg-loader/src/lib.rs b/crates/wasm-pkg-loader/src/lib.rs
index 0d3bc9d..58e6ab4 100644
--- a/crates/wasm-pkg-loader/src/lib.rs
+++ b/crates/wasm-pkg-loader/src/lib.rs
@@ -1,4 +1,3 @@
-mod release;
 pub mod source;
 
 use std::collections::HashMap;
@@ -18,13 +17,12 @@ pub use oci_distribution::client as oci_client;
 
 pub use wasm_pkg_common::{
     config::Config,
+    digest::ContentDigest,
     package::{PackageRef, Version},
     registry::Registry,
     Error,
 };
 
-pub use crate::release::{ContentDigest, Release};
-
 /// A read-only registry client.
 pub struct Client {
     config: Config,
@@ -137,3 +135,9 @@ impl Client {
         Ok(self.sources.get_mut(&registry).unwrap().as_mut())
     }
 }
+
+#[derive(Clone, Debug)]
+pub struct Release {
+    pub version: Version,
+    pub content_digest: ContentDigest,
+}
diff --git a/crates/wasm-pkg-loader/src/source/mod.rs b/crates/wasm-pkg-loader/src/source.rs
similarity index 100%
rename from crates/wasm-pkg-loader/src/source/mod.rs
rename to crates/wasm-pkg-loader/src/source.rs

From e54b27e4a8a6ee1fe18487202eff359b0da5607d Mon Sep 17 00:00:00 2001
From: Lann Martin <lann.martin@fermyon.com>
Date: Fri, 21 Jun 2024 12:01:55 -0400
Subject: [PATCH 2/2] Reorganize modules and improve documentation

- "Sources" are currently just an internal implementation detail, so
  remove the public `source` module and move individual backend modules
  to the crate root.

- Rename Oci/WargConfig to Oci/WargRegistryConfig to make the
  relationship with RegistryConfig more clear.

- Add various documentation, including a wasm-pkg-loader example.
---
 crates/wasm-pkg-common/src/config.rs          |  6 ++-
 crates/wasm-pkg-common/src/digest.rs          |  1 +
 crates/wasm-pkg-common/src/lib.rs             |  2 +-
 crates/wasm-pkg-common/src/package.rs         |  4 +-
 crates/wasm-pkg-common/src/registry.rs        |  4 +-
 crates/wasm-pkg-loader/src/lib.rs             | 46 ++++++++++++++++---
 .../wasm-pkg-loader/src/{source => }/local.rs |  0
 crates/wasm-pkg-loader/src/oci.rs             | 13 ++++++
 .../src/{source => }/oci/config.rs            | 15 +++---
 .../src/{source/oci.rs => oci/source.rs}      | 43 ++++++++---------
 crates/wasm-pkg-loader/src/source.rs          |  4 --
 crates/wasm-pkg-loader/src/warg.rs            | 11 +++++
 .../src/{source => }/warg/config.rs           |  7 ++-
 .../src/{source/warg.rs => warg/source.rs}    | 22 +++++----
 crates/wkg/src/main.rs                        |  4 +-
 15 files changed, 125 insertions(+), 57 deletions(-)
 rename crates/wasm-pkg-loader/src/{source => }/local.rs (100%)
 create mode 100644 crates/wasm-pkg-loader/src/oci.rs
 rename crates/wasm-pkg-loader/src/{source => }/oci/config.rs (93%)
 rename crates/wasm-pkg-loader/src/{source/oci.rs => oci/source.rs} (88%)
 create mode 100644 crates/wasm-pkg-loader/src/warg.rs
 rename crates/wasm-pkg-loader/src/{source => }/warg/config.rs (85%)
 rename crates/wasm-pkg-loader/src/{source/warg.rs => warg/source.rs} (89%)

diff --git a/crates/wasm-pkg-common/src/config.rs b/crates/wasm-pkg-common/src/config.rs
index c638cdf..faa2bb9 100644
--- a/crates/wasm-pkg-common/src/config.rs
+++ b/crates/wasm-pkg-common/src/config.rs
@@ -169,7 +169,8 @@ impl Config {
 
     /// Returns a registry for the given namespace.
     ///
-    /// Does not fall back to the default registry; see [`Self::resolve`].
+    /// Does not fall back to the default registry; see
+    /// [`Self::resolve_registry`].
     pub fn namespace_registry(&self, namespace: &Label) -> Option<&Registry> {
         self.namespace_registries.get(namespace)
     }
@@ -181,7 +182,8 @@ impl Config {
 
     /// Returns a registry override configured for the given package.
     ///
-    /// Does not fall back to namespace or default registries; see [`Self::resolve`].
+    /// Does not fall back to namespace or default registries; see
+    /// [`Self::resolve_registry`].
     pub fn package_registry_override(&self, package: &PackageRef) -> Option<&Registry> {
         self.package_registry_overrides.get(package)
     }
diff --git a/crates/wasm-pkg-common/src/digest.rs b/crates/wasm-pkg-common/src/digest.rs
index 1df4431..c703b40 100644
--- a/crates/wasm-pkg-common/src/digest.rs
+++ b/crates/wasm-pkg-common/src/digest.rs
@@ -6,6 +6,7 @@ use sha2::{Digest, Sha256};
 
 use crate::Error;
 
+/// A cryptographic digest (hash) of some content.
 #[derive(Clone, Debug, PartialEq)]
 pub enum ContentDigest {
     Sha256 { hex: String },
diff --git a/crates/wasm-pkg-common/src/lib.rs b/crates/wasm-pkg-common/src/lib.rs
index 43941d1..fa45333 100644
--- a/crates/wasm-pkg-common/src/lib.rs
+++ b/crates/wasm-pkg-common/src/lib.rs
@@ -2,11 +2,11 @@ use http::uri::InvalidUri;
 use label::Label;
 
 pub mod config;
+pub mod digest;
 pub mod label;
 pub mod metadata;
 pub mod package;
 pub mod registry;
-pub mod digest;
 
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
diff --git a/crates/wasm-pkg-common/src/package.rs b/crates/wasm-pkg-common/src/package.rs
index aa38bc4..385d42e 100644
--- a/crates/wasm-pkg-common/src/package.rs
+++ b/crates/wasm-pkg-common/src/package.rs
@@ -6,7 +6,9 @@ use crate::{label::Label, Error};
 
 pub use semver::Version;
 
-/// A package reference, consisting of kebab-case namespace and name, e.g. `wasm-pkg:loader`.
+/// A package reference, consisting of kebab-case namespace and name.
+///
+/// Ex: `wasm-pkg:loader`
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(into = "String", try_from = "String")]
 pub struct PackageRef {
diff --git a/crates/wasm-pkg-common/src/registry.rs b/crates/wasm-pkg-common/src/registry.rs
index c74df0f..2fd42dc 100644
--- a/crates/wasm-pkg-common/src/registry.rs
+++ b/crates/wasm-pkg-common/src/registry.rs
@@ -3,7 +3,9 @@ use serde::{Deserialize, Serialize};
 
 use crate::Error;
 
-/// A registry identifier, which should be a valid HTTP Host.
+/// A registry identifier.
+///
+/// This must be a valid HTTP Host.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(into = "String", try_from = "String")]
 pub struct Registry(Authority);
diff --git a/crates/wasm-pkg-loader/src/lib.rs b/crates/wasm-pkg-loader/src/lib.rs
index 58e6ab4..7ec9116 100644
--- a/crates/wasm-pkg-loader/src/lib.rs
+++ b/crates/wasm-pkg-loader/src/lib.rs
@@ -1,4 +1,35 @@
-pub mod source;
+//! Wasm Package Loader
+//!
+//! [`Client`] implements a unified interface for loading package content from
+//! multiple kinds of package registries.
+//!
+//! # Example
+//!
+//! ```no_run
+//! # async fn example() -> anyhow::Result<()> {
+//! // Initialize client from global configuration.
+//! let mut client = wasm_pkg_loader::Client::with_global_defaults()?;
+//!
+//! // Get a specific package release version.
+//! let pkg = "example:pkg".parse()?;
+//! let version = "1.0.0".parse()?;
+//! let release = client.get_release(&pkg, &version).await?;
+//!
+//! // Stream release content to a file.
+//! let mut stream = client.stream_content(&pkg, &release).await?;
+//! let mut file = tokio::fs::File::create("output.wasm").await?;
+//! use futures_util::TryStreamExt;
+//! use tokio::io::AsyncWriteExt;
+//! while let Some(chunk) = stream.try_next().await? {
+//!     file.write_all(&chunk).await?;
+//! }
+//! # Ok(()) }
+//! ```
+
+mod local;
+pub mod oci;
+mod source;
+pub mod warg;
 
 use std::collections::HashMap;
 
@@ -8,13 +39,11 @@ use futures_util::stream::BoxStream;
 
 use wasm_pkg_common::metadata::RegistryMetadata;
 
-use crate::source::{
-    local::LocalSource, oci::OciSource, warg::WargSource, PackageSource, VersionInfo,
+use crate::{
+    local::LocalSource, oci::source::OciSource, source::PackageSource, source::VersionInfo,
+    warg::source::WargSource,
 };
 
-/// Re-exported to ease configuration.
-pub use oci_distribution::client as oci_client;
-
 pub use wasm_pkg_common::{
     config::Config,
     digest::ContentDigest,
@@ -30,7 +59,7 @@ pub struct Client {
 }
 
 impl Client {
-    /// Returns a new client with the given [`ClientConfig`].
+    /// Returns a new client with the given [`Config`].
     pub fn new(config: Config) -> Self {
         Self {
             config,
@@ -136,6 +165,9 @@ impl Client {
     }
 }
 
+/// Package release details.
+///
+/// Returned by [`Client::get_release`] and passed to [`Client::stream_content`].
 #[derive(Clone, Debug)]
 pub struct Release {
     pub version: Version,
diff --git a/crates/wasm-pkg-loader/src/source/local.rs b/crates/wasm-pkg-loader/src/local.rs
similarity index 100%
rename from crates/wasm-pkg-loader/src/source/local.rs
rename to crates/wasm-pkg-loader/src/local.rs
diff --git a/crates/wasm-pkg-loader/src/oci.rs b/crates/wasm-pkg-loader/src/oci.rs
new file mode 100644
index 0000000..773dde4
--- /dev/null
+++ b/crates/wasm-pkg-loader/src/oci.rs
@@ -0,0 +1,13 @@
+//! OCI package loader.
+//!
+//! This follows the CNCF TAG Runtime guidance for [Wasm OCI Artifacts][1].
+//!
+//! [1]: https://tag-runtime.cncf.io/wgs/wasm/deliverables/wasm-oci-artifact/
+
+mod config;
+pub(crate) mod source;
+
+/// Re-exported for convenience.
+pub use oci_distribution::client;
+
+pub use config::{BasicCredentials, OciRegistryConfig};
diff --git a/crates/wasm-pkg-loader/src/source/oci/config.rs b/crates/wasm-pkg-loader/src/oci/config.rs
similarity index 93%
rename from crates/wasm-pkg-loader/src/source/oci/config.rs
rename to crates/wasm-pkg-loader/src/oci/config.rs
index db10e29..55fa981 100644
--- a/crates/wasm-pkg-loader/src/source/oci/config.rs
+++ b/crates/wasm-pkg-loader/src/oci/config.rs
@@ -8,13 +8,16 @@ use secrecy::{ExposeSecret, SecretString};
 use serde::Deserialize;
 use wasm_pkg_common::{config::RegistryConfig, Error};
 
+/// Registry configuration for OCI backends.
+///
+/// See: [`RegistryConfig::backend_config`]
 #[derive(Default)]
-pub struct OciConfig {
+pub struct OciRegistryConfig {
     pub client_config: ClientConfig,
     pub credentials: Option<BasicCredentials>,
 }
 
-impl Clone for OciConfig {
+impl Clone for OciRegistryConfig {
     fn clone(&self) -> Self {
         let client_config = ClientConfig {
             protocol: self.client_config.protocol.clone(),
@@ -29,7 +32,7 @@ impl Clone for OciConfig {
     }
 }
 
-impl std::fmt::Debug for OciConfig {
+impl std::fmt::Debug for OciRegistryConfig {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("OciConfig")
             .field("client_config", &"...")
@@ -38,7 +41,7 @@ impl std::fmt::Debug for OciConfig {
     }
 }
 
-impl TryFrom<&RegistryConfig> for OciConfig {
+impl TryFrom<&RegistryConfig> for OciRegistryConfig {
     type Error = Error;
 
     fn try_from(registry_config: &RegistryConfig) -> Result<Self, Self::Error> {
@@ -143,7 +146,7 @@ mod tests {
         "#;
         let cfg = wasm_pkg_common::config::Config::from_toml(toml_config).unwrap();
 
-        let oci_config: OciConfig = cfg
+        let oci_config: OciRegistryConfig = cfg
             .registry_config(&"example.com".parse().unwrap())
             .unwrap()
             .try_into()
@@ -156,7 +159,7 @@ mod tests {
             oci_config.client_config.protocol
         );
 
-        let oci_config: OciConfig = cfg
+        let oci_config: OciRegistryConfig = cfg
             .registry_config(&"wasi.dev".parse().unwrap())
             .unwrap()
             .try_into()
diff --git a/crates/wasm-pkg-loader/src/source/oci.rs b/crates/wasm-pkg-loader/src/oci/source.rs
similarity index 88%
rename from crates/wasm-pkg-loader/src/source/oci.rs
rename to crates/wasm-pkg-loader/src/oci/source.rs
index c8531b1..bcb96a1 100644
--- a/crates/wasm-pkg-loader/src/source/oci.rs
+++ b/crates/wasm-pkg-loader/src/oci/source.rs
@@ -1,8 +1,5 @@
-mod config;
-
 use async_trait::async_trait;
 use bytes::Bytes;
-use config::{BasicCredentials, OciConfig};
 use docker_credential::{CredentialRetrievalError, DockerCredential};
 use futures_util::{stream::BoxStream, StreamExt, TryStreamExt};
 use oci_distribution::{
@@ -10,11 +7,9 @@ use oci_distribution::{
 };
 use secrecy::ExposeSecret;
 use serde::Deserialize;
+use warg_protocol::Version;
 use wasm_pkg_common::{
-    config::RegistryConfig,
-    metadata::RegistryMetadata,
-    package::{PackageRef, Version},
-    registry::Registry,
+    config::RegistryConfig, metadata::RegistryMetadata, package::PackageRef, registry::Registry,
     Error,
 };
 
@@ -23,19 +18,21 @@ use crate::{
     Release,
 };
 
+use super::config::{BasicCredentials, OciRegistryConfig};
+
 #[derive(Default, Deserialize)]
 #[serde(rename_all = "camelCase")]
-struct OciRegistryMetadata {
-    registry: Option<String>,
-    namespace_prefix: Option<String>,
+pub(crate) struct OciRegistryMetadata {
+    pub(crate) registry: Option<String>,
+    pub(crate) namespace_prefix: Option<String>,
 }
 
-pub struct OciSource {
-    client: oci_wasm::WasmClient,
-    oci_registry: String,
-    namespace_prefix: Option<String>,
-    credentials: Option<BasicCredentials>,
-    registry_auth: Option<RegistryAuth>,
+pub(crate) struct OciSource {
+    pub(crate) client: oci_wasm::WasmClient,
+    pub(crate) oci_registry: String,
+    pub(crate) namespace_prefix: Option<String>,
+    pub(crate) credentials: Option<BasicCredentials>,
+    pub(crate) registry_auth: Option<RegistryAuth>,
 }
 
 impl OciSource {
@@ -44,7 +41,7 @@ impl OciSource {
         registry_config: &RegistryConfig,
         registry_meta: &RegistryMetadata,
     ) -> Result<Self, Error> {
-        let OciConfig {
+        let OciRegistryConfig {
             client_config,
             credentials,
         } = registry_config.try_into()?;
@@ -65,7 +62,7 @@ impl OciSource {
         })
     }
 
-    async fn auth(&mut self, reference: &Reference) -> Result<RegistryAuth, Error> {
+    pub(crate) async fn auth(&mut self, reference: &Reference) -> Result<RegistryAuth, Error> {
         if self.registry_auth.is_none() {
             let mut auth = self.get_credentials()?;
             // Preflight auth to check for validity; this isn't wasted
@@ -94,7 +91,7 @@ impl OciSource {
         Ok(self.registry_auth.clone().unwrap())
     }
 
-    fn get_credentials(&self) -> Result<RegistryAuth, Error> {
+    pub(crate) fn get_credentials(&self) -> Result<RegistryAuth, Error> {
         if let Some(BasicCredentials { username, password }) = &self.credentials {
             return Ok(RegistryAuth::Basic(
                 username.clone(),
@@ -129,7 +126,11 @@ impl OciSource {
         Ok(RegistryAuth::Anonymous)
     }
 
-    fn make_reference(&self, package: &PackageRef, version: Option<&Version>) -> Reference {
+    pub(crate) fn make_reference(
+        &self,
+        package: &PackageRef,
+        version: Option<&Version>,
+    ) -> Reference {
         let repository = format!(
             "{}{}/{}",
             self.namespace_prefix.as_deref().unwrap_or_default(),
@@ -227,7 +228,7 @@ impl PackageSource for OciSource {
     }
 }
 
-fn oci_registry_error(err: OciDistributionError) -> Error {
+pub(crate) fn oci_registry_error(err: OciDistributionError) -> Error {
     match err {
         // Technically this could be a missing version too, but there really isn't a way to find out
         OciDistributionError::ImageManifestNotFoundError(_) => Error::PackageNotFound,
diff --git a/crates/wasm-pkg-loader/src/source.rs b/crates/wasm-pkg-loader/src/source.rs
index dea090e..3b89262 100644
--- a/crates/wasm-pkg-loader/src/source.rs
+++ b/crates/wasm-pkg-loader/src/source.rs
@@ -10,10 +10,6 @@ use wasm_pkg_common::{
 
 use crate::Release;
 
-pub mod local;
-pub mod oci;
-pub mod warg;
-
 #[derive(Clone, Debug, Eq)]
 pub struct VersionInfo {
     pub version: Version,
diff --git a/crates/wasm-pkg-loader/src/warg.rs b/crates/wasm-pkg-loader/src/warg.rs
new file mode 100644
index 0000000..fe87ceb
--- /dev/null
+++ b/crates/wasm-pkg-loader/src/warg.rs
@@ -0,0 +1,11 @@
+//! Warg package loader.
+//!
+//!
+
+mod config;
+pub(crate) mod source;
+
+/// Re-exported for convenience.
+pub use warg_client as client;
+
+pub use config::WargRegistryConfig;
diff --git a/crates/wasm-pkg-loader/src/source/warg/config.rs b/crates/wasm-pkg-loader/src/warg/config.rs
similarity index 85%
rename from crates/wasm-pkg-loader/src/source/warg/config.rs
rename to crates/wasm-pkg-loader/src/warg/config.rs
index ff9c921..70b041d 100644
--- a/crates/wasm-pkg-loader/src/source/warg/config.rs
+++ b/crates/wasm-pkg-loader/src/warg/config.rs
@@ -4,13 +4,16 @@ use secrecy::SecretString;
 use serde::Deserialize;
 use wasm_pkg_common::{config::RegistryConfig, Error};
 
+/// Registry configuration for Warg backends.
+///
+/// See: [`RegistryConfig::backend_config`]
 #[derive(Clone, Debug, Default)]
-pub struct WargConfig {
+pub struct WargRegistryConfig {
     pub client_config: Option<warg_client::Config>,
     pub auth_token: Option<SecretString>,
 }
 
-impl TryFrom<&RegistryConfig> for WargConfig {
+impl TryFrom<&RegistryConfig> for WargRegistryConfig {
     type Error = Error;
 
     fn try_from(registry_config: &RegistryConfig) -> Result<Self, Self::Error> {
diff --git a/crates/wasm-pkg-loader/src/source/warg.rs b/crates/wasm-pkg-loader/src/warg/source.rs
similarity index 89%
rename from crates/wasm-pkg-loader/src/source/warg.rs
rename to crates/wasm-pkg-loader/src/warg/source.rs
index 890cf39..8854ab8 100644
--- a/crates/wasm-pkg-loader/src/source/warg.rs
+++ b/crates/wasm-pkg-loader/src/warg/source.rs
@@ -1,9 +1,6 @@
-mod config;
-
 use anyhow::anyhow;
 use async_trait::async_trait;
 use bytes::Bytes;
-use config::WargConfig;
 use futures_util::{stream::BoxStream, StreamExt, TryStreamExt};
 use serde::Deserialize;
 use warg_client::{storage::PackageInfo, ClientError, FileSystemClient};
@@ -21,14 +18,16 @@ use crate::{
     Release,
 };
 
+use super::config::WargRegistryConfig;
+
 #[derive(Debug, Default, Deserialize)]
 #[serde(rename_all = "camelCase")]
-struct WargRegistryMetadata {
-    url: Option<String>,
+pub(crate) struct WargRegistryMetadata {
+    pub(crate) url: Option<String>,
 }
 
 pub struct WargSource {
-    client: FileSystemClient,
+    pub(crate) client: FileSystemClient,
 }
 
 impl WargSource {
@@ -41,7 +40,7 @@ impl WargSource {
             .protocol_config::<WargRegistryMetadata>("warg")?
             .unwrap_or_default();
         let url = warg_meta.url.unwrap_or_else(|| registry.to_string());
-        let WargConfig {
+        let WargRegistryConfig {
             client_config,
             auth_token,
         } = registry_config.try_into()?;
@@ -60,7 +59,10 @@ impl WargSource {
         Ok(Self { client })
     }
 
-    async fn fetch_package_info(&mut self, package: &PackageRef) -> Result<PackageInfo, Error> {
+    pub(crate) async fn fetch_package_info(
+        &mut self,
+        package: &PackageRef,
+    ) -> Result<PackageInfo, Error> {
         let package_name = package_ref_to_name(package)?;
         self.client
             .package(&package_name)
@@ -128,12 +130,12 @@ impl PackageSource for WargSource {
     }
 }
 
-fn package_ref_to_name(package_ref: &PackageRef) -> Result<PackageName, Error> {
+pub(crate) fn package_ref_to_name(package_ref: &PackageRef) -> Result<PackageName, Error> {
     PackageName::new(package_ref.to_string())
         .map_err(|err| Error::InvalidPackageRef(err.to_string()))
 }
 
-fn warg_registry_error(err: ClientError) -> Error {
+pub(crate) fn warg_registry_error(err: ClientError) -> Error {
     match err {
         ClientError::PackageDoesNotExist { .. }
         | ClientError::PackageDoesNotExistWithHintHeader { .. } => Error::PackageNotFound,
diff --git a/crates/wkg/src/main.rs b/crates/wkg/src/main.rs
index ec235dd..771666b 100644
--- a/crates/wkg/src/main.rs
+++ b/crates/wkg/src/main.rs
@@ -46,8 +46,8 @@ struct GetCommand {
     #[arg(long)]
     overwrite: bool,
 
-    /// The package to get, specified as <namespace>:<name> plus optional
-    /// @<version>, e.g. "wasi:cli" or "wasi:http@0.2.0".
+    /// The package to get, specified as `<namespace>:<name>` plus optional
+    /// `@<version>`, e.g. `wasi:cli" or `wasi:http@0.2.0`.
     package_spec: PackageSpec,
 
     #[command(flatten)]