#![doc(html_root_url = "https://docs.rs/rust_release_channel/0.1.0")]
#![warn(missing_docs)]
//! A data structure for Rust release channel metadata
//!
//! Introduction
//! ============
//!
//! New versions of the Rust toolchain are released
//! on a regular six-week cycle.
//! Each version is described in a release-channel metadata file
//! in a known location,
//! allowing automated tools to detect new releases
//! and find the tools and components for each supported platform.
//!
//! The data structures in this library
//! represent the information present in each metadata file,
//! organised to help you pull out the specific information you need.
//!
//! This library is designed to handle version 2 of the manifest file format.
//!
//! The most important class is [`Channel`],
//! so you'll want to start there.
//!
//! [`Channel`]: struct.Channel.html
//!
//! First Example
//! =============
//!
//!     extern crate rust_release_channel;
//!     use std::error::Error;
//!
//!     fn dump_manifest_info(input: &str) -> Result<(), Box<Error>> {
//!         // Parse the manifest into a data structure.
//!         let channel: rust_release_channel::Channel = input.parse()?;
//!
//!         // Check the manifest is sensible before we use it.
//!         let errors = channel.validate();
//!         if errors.is_empty() {
//!             // Dump a summary of the manifest data
//!             println!(
//!                 "Channel manifest created on {}",
//!                 channel.date,
//!             );
//!             println!("Included packages:");
//!             for (name, pkg) in channel.pkg.iter() {
//!                 println!("  - {} version {}", name, pkg.version);
//!             }
//!         } else {
//!             println!("Channel has problems:");
//!             for each in errors {
//!                 println!("  - {}", each);
//!             }
//!         }
//!
//!         Ok(())
//!     }
//!
//! Capabilities
//! ============
//!
//! Reading manifests
//! -----------------
//!
//! If you can read the content of an existing manifest file,
//! you can turn it into a queryable, explorable data structure
//!  with the `.parse()` method
//! (courtesy of the standard [`FromStr`] trait).
//!
//! [`FromStr`]: https://doc.rust-lang.org/std/str/trait.FromStr.html
//!
//!     # extern crate rust_release_channel;
//!     # use std::error::Error;
//!     # fn example1() -> Result<(), Box<Error>> {
//!     # let my_str = r#"metadata-version = "2"\ndate = "2018-02-26"\n"#;
//!     let channel: rust_release_channel::Channel = my_str.parse()?;
//!     # Ok(())
//!     # }
//!
//! After reading a manifest,
//! you should call [`.validate()`]
//! to see if the data makes sense before trusting it.
//!
//! [`.validate()`]: struct.Channel.html#method.validate
//!
//! Querying manifests
//! ------------------
//!
//! All the content of the manifest is available to inspect,
//! as native-feeling Rust data structures.
//! For example,
//! where the native manifest file-format models
//! different available file-formats as
//! differently-named keys with the same meaning
//! (`url` vs. `xz_url`, `hash` vs. `xz_hash`),
//! `rust_release_channel` gives you a mapping from
//! [`ArchiveFormat`] to [`ArchiveSource`].
//!
//! [`ArchiveFormat`]: enum.ArchiveFormat.html
//! [`ArchiveSource`]: struct.ArchiveSource.html
//!
//!     # extern crate rust_release_channel;
//!     # use std::error::Error;
//!     # fn example2() -> Result<(), Box<Error>> {
//!     # let my_str = r#"metadata-version = "2"\ndate = "2018-02-26"\n"#;
//!     # let channel: rust_release_channel::Channel = my_str.parse()?;
//!     let rust_for_aarch64_url = channel.pkg
//!         .get("rust")
//!         .and_then(|pkg| { pkg.target.get("aarch64-unknown-linux-gnu") })
//!         .and_then(|artefact| {
//!              artefact.standalone.get(
//!                 &rust_release_channel::ArchiveFormat::TarGzip,
//!              )
//!         })
//!         .map(|archive| { &archive.url });
//!     # Ok(())
//!     # }
//!
//! Creating fresh manifests
//! ------------------------
//!
//! You can also create manifest data completely from scratch,
//! in case you need to create test-data for another system.
//!
//!     # extern crate rust_release_channel;
//!     # extern crate chrono;
//!     # use std::error::Error;
//!     # fn example3() -> Result<(), Box<Error>> {
//!     let source = rust_release_channel::ArchiveSource::new(
//!         "https://example.com/rust/mypackage-linux-x86.tar.gz".parse()?,
//!         "aa0a89d80329fec6f9e84b79c1674c5427034408630c35da1be442c7da6d2364"
//!             .into(),
//!     );
//!
//!     let mut artefact = rust_release_channel::Artefact::new();
//!     artefact.standalone.insert(
//!         rust_release_channel::ArchiveFormat::TarGzip,
//!         source,
//!     );
//!
//!     let mut mypackage = rust_release_channel::Package::new(
//!         "1.2.3 (abc1234 2018-02-26)".into(),
//!     );
//!     mypackage.target.insert(
//!         "x86_64-unknown-linux-gnu".into(),
//!         artefact,
//!     );
//!
//!     let mut channel = rust_release_channel::Channel::new();
//!     channel.pkg.insert("mypackage".into(), mypackage);
//!     # Ok(())
//!     # }
//!
//! Writing manifests
//! -----------------
//!
//! You can turn manifest data back into a string with the [`.to_string()`] method.
//! If you serialize a [`Channel`] and deserialize it again,
//! the result should be identical to the original.
//!
//!     # extern crate rust_release_channel;
//!     # use std::error::Error;
//!     # fn example3() -> Result<(), Box<Error>> {
//!     # let channel = rust_release_channel::Channel::new();
//!     let manifest_string = channel.to_string()?;
//!     # Ok(())
//!     # }
//!
//! [`.to_string()`]: struct.Channel.html#method.to_string
//!
//! Before writing a manifest,
//! you should call [`.validate()`]
//! to check you haven't left the metadata in an inconsistent state.
//!
//! [`.validate()`]: struct.Channel.html#method.validate
extern crate chrono;
extern crate serde;
#[macro_use]
extern crate serde_derive;
extern crate toml;
extern crate url;
extern crate url_serde;

#[cfg(test)]
#[macro_use]
extern crate pretty_assertions;

use std::collections;
use std::error;
use std::fmt;
use std::str::FromStr;

/// The metadata for a Rust release channel.
///
/// This data structure represents
/// all the information available in a Rust release channel metadata file.
/// You can create one from scratch with `new()`,
/// or by parsing an official metadata file:
///
///     # extern crate rust_release_channel;
///     # use std::error::Error;
///     # fn foo() -> Result<(), Box<Error>> {
///     use std::fs;
///     use std::io::Read;
///
///     let mut handle = fs::File::open("examples/channel-rust-1.24.toml")?;
///     let mut buffer = String::new();
///     handle.read_to_string(&mut buffer);
///     let channel: rust_release_channel::Channel = buffer.parse()?;
///     # Ok(())
///     # }
///
/// Look at the `pkg` field to find out what packages
/// are available from this channel.
/// If you have something specific in mind,
/// consult the `.lookup_artefact()` method.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Channel {
    /// The creation date of the original metadata file, in `YYYY-MM-DD` format.
    pub date: chrono::NaiveDate,
    /// The packages included in this channel.
    ///
    /// The keys of this map are package names,
    /// the values are the metadata for that package.
    pub pkg: collections::BTreeMap<String, Package>,
    /// A mapping from old package names to new ones.
    ///
    /// Sometimes packages get renamed.
    /// For the benefit of systems that have the old name recorded,
    /// this mapping allows them to look up the new name.
    /// Packages that have not been renamed should not appear in this map.
    pub renames: collections::BTreeMap<String, String>,
}

impl Channel {
    /// Create a new, empty Channel whose creation date is today.
    ///
    /// "today" means the current date in the local timezone.
    ///
    ///     # extern crate rust_release_channel;
    ///     # use std::error::Error;
    ///     # fn foo() -> Result<(), Box<Error>> {
    ///     let channel = rust_release_channel::Channel::new();
    ///     # Ok(())
    ///     # }
    pub fn new() -> Channel {
        Channel {
            date: chrono::Local::today().naive_local(),
            pkg: collections::BTreeMap::new(),
            renames: collections::BTreeMap::new(),
        }
    }

    /// Create a new, empty Channel whose creation date is set to the given value.
    ///
    ///     # extern crate rust_release_channel;
    ///     # extern crate chrono;
    ///     # fn foo() {
    ///     let channel = rust_release_channel::Channel::with_date(
    ///         chrono::NaiveDate::from_ymd(2018, 2, 26),
    ///     );
    ///     # }
    pub fn with_date(date: chrono::NaiveDate) -> Channel {
        Channel {
            date: date,
            pkg: collections::BTreeMap::new(),
            renames: collections::BTreeMap::new(),
        }
    }

    /// Serialize this Channel to the standard metadata format.
    ///
    /// If you write the resulting `String` to a file,
    /// it will be a standard channel metadata file.
    ///
    ///     # extern crate rust_release_channel;
    ///     # use std::error::Error;
    ///     # fn foo() -> Result<(), Box<Error>> {
    ///     # let channel = rust_release_channel::Channel::new();
    ///     let metadata_string = channel.to_string()?;
    ///     # Ok(())
    ///     # }
    pub fn to_string(&self) -> Result<String, toml::ser::Error> {
        toml::to_string(self)
    }

    /// Find the [`Artefact`] represented by the given [`ArtefactToken`].
    ///
    /// `ArtefactToken`s can be found in
    /// the `components` and `extensions` fields of `Artefact`s,
    /// or can be created from scratch
    /// if you want to look up the artefact for a specific package and target.
    ///
    /// If no artefact exists in this channel for the given package and target,
    /// this method will consult the `renames` map
    /// to see if the requested package is available under a new name.
    /// If there's still no matching artefact,
    /// this method returns `None`.
    ///
    /// [`Artefact`]: struct.Artefact.html
    /// [`ArtefactToken`]: struct.ArtefactToken.html
    ///
    ///     # extern crate rust_release_channel;
    ///     # use std::error::Error;
    ///     # fn foo() -> Result<(), Box<Error>> {
    ///     # let channel = rust_release_channel::Channel::new();
    ///     let token = rust_release_channel::ArtefactToken {
    ///         pkg: "rustc".into(),
    ///         target: "x86_64-unknown-linux-gnu".into(),
    ///     };
    ///     let pkg = channel.lookup_artefact(&token);
    ///     # Ok(())
    ///     # }
    pub fn lookup_artefact<'s, 'q>(
        &'s self,
        query: &'q ArtefactToken,
    ) -> Option<&'s Artefact> {
        // Find the package containing this artefact
        self.pkg
            .get(&query.pkg)
            .or_else(|| {
                // No package by that name exists; perhaps it was renamed?
                self.renames.get(&query.pkg).and_then(|new_name| {
                    // Yes, it was reramed!
                    // Find the package under its new name.
                    self.pkg.get(new_name)
                })
            })
            .and_then(|pkg| {
                // Find the target containing this artefact.
                pkg.target.get(&query.target)
            })
    }

    /// Validate the internal consistency of this metadata.
    ///
    /// Specifically:
    ///
    ///   - If [`renames`] says a package named X was renamed to Y,
    ///     then Y should exist in the [`pkg`] map.
    ///   - Each component or extension in an [`Artefact`] should reference
    ///     the name of a package in the channel's [`pkg`] map,
    ///     and a target in that package's [`target`] map.
    ///
    /// Returns all detected problems.
    ///
    ///     # extern crate rust_release_channel;
    ///     # fn foo() {
    ///     # let channel = rust_release_channel::Channel::new();
    ///     let errors = channel.validate();
    ///     if !errors.is_empty() {
    ///         println!("Errors found:");
    ///         for each in errors {
    ///             println!("  - {}", each);
    ///         }
    ///     }
    ///     # }
    ///
    /// [`renames`]: #structfield.renames
    /// [`pkg`]: #structfield.pkg
    /// [`Artefact`]: struct.Artefact.html
    /// [`target`]: struct.Artefact.html#structfield.target
    pub fn validate<'a>(&'a self) -> Vec<ValidationError<'a>> {
        let pkg_problems = self.pkg
            .iter()
            .flat_map(|(name, pkg)| pkg.validate(self, name));

        let rename_problems = self.renames.iter().filter_map(|(old, new)| {
            if !self.pkg.contains_key(new) {
                Some(ValidationError::RenameToUnknownPackage { old, new })
            } else {
                None
            }
        });

        pkg_problems.chain(rename_problems).collect()
    }
}

impl Default for Channel {
    fn default() -> Self {
        Channel::new()
    }
}

impl FromStr for Channel {
    type Err = toml::de::Error;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        toml::from_str(s)
    }
}

impl fmt::Display for Channel {
    fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
        write!(
            f,
            "Rust release channel for version {}, dated {}",
            self.pkg
                .get("rust")
                .map(|pkg| pkg.version.as_str())
                .unwrap_or("<unknown>"),
            self.date,
        )
    }
}

/// A single package installable from this release channel.
///
/// This package may be available for multiple targets,
/// but every artefact should be built from the same source.
#[derive(Deserialize, Serialize, Debug, Clone, PartialEq, Eq, PartialOrd, Ord,
         Hash)]
pub struct Package {
    /// A human-readable version-number for this package.
    ///
    /// This should be a [SemVer] version number of the form `X.Y.Z`,
    /// followed by a space,
    /// an open-parenthesis,
    /// a Git commit ID truncated to 9 digits,
    /// a space,
    /// the date of that commit in `YYYY-MM-DD` format,
    /// and a close-parenthesis: `1.2.3 (a1b2c3d4e 2018-02-26)`
    ///
    /// [SemVer]: https://semver.org/
    pub version: String,
    /// The complete Git commit ID of this version of this package.
    pub git_commit_hash: Option<String>,
    /// A mapping from target names to [`Artefact`]s of this package built
    /// for that target.
    ///
    /// A target name
    /// (sometimes "[target triplet][tt]",
    /// although there's not always three parts)
    /// is a name that identifies a particular hardware and software platform,
    /// such as `x86_64-unknown-linux-gnu` (for modern Linux PCs)
    /// or `i686-pc-windows-msvc` (for Win32 with the Visual C++ compiler).
    /// Software built for a particular target
    /// usually won't work on a different target,
    /// so if you're looking for a particular package
    /// you'll want to get the artefact for the platform you're using.
    ///
    /// The special target name `*` (an asterisk)
    /// is used for packages that are the same on every concievable platform,
    /// like `rust-src` which contains the Rust source code.
    ///
    /// [tt]: https://wiki.osdev.org/Target_Triplet
    /// [`Artefact`]: struct.Artefact.html
    #[serde(skip_serializing_if = "::std::collections::BTreeMap::is_empty")]
    pub target: collections::BTreeMap<String, Artefact>,
}

impl Package {
    /// Create a new, empty Package whose version is set to the given value.
    ///
    /// By convention, `version` is in the format `X.Y.Z (HHHHHHH YYYY-MM-DD)`
    /// where `X.Y.Z` is a SemVer version string,
    /// `HHHHHHH` is the abbreviated commit ID of the source repository
    /// at that version,
    /// and `YYYY-MM-DD` is the date when that version was released.
    ///
    ///     # extern crate rust_release_channel;
    ///     let pkg = rust_release_channel::Package::new(
    ///         "1.2.3 (abc1234 2018-02-26)".into()
    ///     );
    ///
    pub fn new(version: String) -> Package {
        Package {
            version: version,
            git_commit_hash: None,
            target: collections::BTreeMap::new(),
        }
    }

    fn validate<'a>(
        &'a self,
        channel: &'a Channel,
        pkg: &'a str,
    ) -> Vec<ValidationError<'a>> {
        self.target
            .iter()
            .flat_map(|(target, artefact)| {
                artefact.validate(channel, pkg, target)
            })
            .collect()
    }
}

impl fmt::Display for Package {
    fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
        write!(
            f,
            "Package version {} for {} target(s)",
            self.version,
            self.target.len(),
        )
    }
}

/// One or more packages built for a single target.
///
/// All the relevant files are grouped together into an archive.
/// The `standalone` field may reference
/// multiple archives in different formats,
/// but each archive should contain exactly the same files.
///
/// If this artefact is a combination of other, smaller artefacts,
/// they are mentioned in the `components` field.
/// The `extensions` field suggests other artefacts
/// that might be useful, but are not required.
///
/// All the fields in this structure may be empty,
/// which can occur when this package was not built for this target
/// for some reason.
#[derive(Default, Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Artefact {
    /// Points to archives containing the files of this artefact.
    ///
    /// Each archive contains exactly the same files,
    /// so you can use whichever format is most convenient.
    pub standalone: collections::BTreeMap<ArchiveFormat, ArchiveSource>,
    /// Points to the individual artefacts that make up this artefact, if any.
    ///
    /// If you don't need some particular artefact
    /// that's included by default,
    /// you can save bandwidth by just downloading
    /// the artefacts you need.
    pub components: Vec<ArtefactToken>,
    /// Points to other artefacts that may be useful with this one.
    ///
    /// In particular, this artefact may be able to use
    /// certain other artefacts built for different targets,
    /// and this field describes which ones.
    pub extensions: Vec<ArtefactToken>,
}

impl Artefact {
    /// Create a new, empty Artefact.
    ///
    ///     # extern crate rust_release_channel;
    ///     let pkg = rust_release_channel::Artefact::new();
    ///
    pub fn new() -> Artefact {
        Default::default()
    }

    fn validate<'a>(
        &'a self,
        channel: &'a Channel,
        pkg: &'a str,
        target: &'a str,
    ) -> Vec<ValidationError<'a>> {
        let mut res = Vec::new();

        for token in self.components.iter() {
            let component_pkg = channel.pkg.get(&token.pkg);
            let component_target = component_pkg
                .clone()
                .and_then(|pkg| pkg.target.get(&token.target));

            match (component_pkg, component_target) {
                (None, _) => {
                    res.push(ValidationError::ArtefactHasUnknownComponent {
                        pkg: pkg,
                        target: target,
                        component_pkg: &token.pkg,
                    })
                }
                (Some(_), None) => res.push(
                    ValidationError::ArtefactComponentHasUnknownTarget {
                        pkg: pkg,
                        target: target,
                        component_pkg: &token.pkg,
                        component_target: &token.target,
                    },
                ),
                _ => (),
            }
        }

        for token in self.extensions.iter() {
            let extension_pkg = channel.pkg.get(&token.pkg);
            let extension_target = extension_pkg
                .clone()
                .and_then(|pkg| pkg.target.get(&token.target));

            match (extension_pkg, extension_target) {
                (None, _) => {
                    res.push(ValidationError::ArtefactHasUnknownExtension {
                        pkg: pkg,
                        target: target,
                        extension_pkg: &token.pkg,
                    })
                }
                (Some(_), None) => res.push(
                    ValidationError::ArtefactExtensionHasUnknownTarget {
                        pkg: pkg,
                        target: target,
                        extension_pkg: &token.pkg,
                        extension_target: &token.target,
                    },
                ),
                _ => (),
            }
        }

        res
    }
}

impl fmt::Display for Artefact {
    fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
        write!(
            f,
            "Artefact in {} format(s), with {} component(s) and {} extension(s)",
            self.standalone.len(),
            self.components.len(),
            self.extensions.len(),
        )
    }
}

/// Describes where to obtain a particular archive.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ArchiveSource {
    /// A URL from where the archive may be obtained.
    pub url: url::Url,
    /// The expected SHA256 hash of the archive,
    /// encoded as ASCII lowercase hexadecimal digits.
    ///
    /// If you download this archive,
    /// hash it and compare the result to this value,
    /// so you can tell whether you got the right file.
    pub hash: String,
}

impl ArchiveSource {
    /// Create a new ArchiveSource for the given URL and hash.
    ///
    /// `url` is a URL from where the archive may be obtained.
    ///
    /// `hash` is the expected SHA256 hash of the archive,
    /// encoded as ASCII lowercase hexadecimal digits.
    ///
    ///     # extern crate rust_release_channel;
    ///     # use std::error::Error;
    ///     # fn example() -> Result<(), Box<Error>> {
    ///     let pkg = rust_release_channel::ArchiveSource::new(
    ///         "https://example.com/rust/archive.tar.gz".parse()?,
    ///         "867f3496607caeb969dabcd0083d35e010591bc2a9105af4f6c34289750c8b95"
    ///             .into(),
    ///     );
    ///     # Ok(())
    ///     # }
    ///
    pub fn new(url: url::Url, hash: String) -> ArchiveSource {
        ArchiveSource { url, hash }
    }
}

impl fmt::Display for ArchiveSource {
    fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
        write!(f, "<{}>", self.url)
    }
}

/// Represents the formats used by archives from this channel.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum ArchiveFormat {
    /// The archive is a tar archive compressed with [gzip].
    ///
    /// [gzip]: http://www.gzip.org/
    TarGzip,
    /// The archive is a tar archive compressed with [xz].
    ///
    /// [xz]: https://tukaani.org/xz/
    TarXz,
    // Discourage people from exhaustively matching this enum
    // so we can add more formats in future.
    #[doc(hidden)] ReservedForFutureExpansion,
}

impl fmt::Display for ArchiveFormat {
    fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
        match self {
            &ArchiveFormat::TarGzip => write!(f, ".tar.gz"),
            &ArchiveFormat::TarXz => write!(f, ".tar.xz"),
            _ => write!(f, "<unknown>"),
        }
    }
}

/// A reference to an artefact in a channel.
///
/// [`Channel::lookup_artefact()`]
/// will exchange an `ArtefactToken`
/// for a real [`Artefact`].
///
/// [`Channel::lookup_artefact()`]: struct.Channel.html#method.lookup_artefact
/// [`Artefact`]: struct.Artefact.html
#[derive(Deserialize, Serialize, Debug, Clone, PartialEq, Eq, PartialOrd, Ord,
         Hash)]
pub struct ArtefactToken {
    /// The name of the package that was built to produce the target artefact.
    ///
    /// See [`Channel::pkg`] for details.
    ///
    /// [`Channel::pkg`]: struct.Channel.html#structfield.pkg
    pub pkg: String,
    /// The name of the target the package was built for to produce the target
    /// artefact.
    ///
    /// See [`Package::target`] for details.
    ///
    /// [`Package::target`]: struct.Package.html#structfield.target
    pub target: String,
}

impl ArtefactToken {
    /// Create a new ArtefactToken for the given package and target.
    ///
    /// `pkg` is the name of the package that was built
    /// to produce the target artefact.
    ///
    /// `target` is the name of the target the package was built for
    /// to produce the target artefact.
    ///
    ///     # extern crate rust_release_channel;
    ///     let pkg = rust_release_channel::ArtefactToken::new(
    ///         "somepackage".into(),
    ///         "aarch64-unknown-linux-gnu".into(),
    ///     );
    ///
    /// [`pkg`]: struct.Channel.html#structfield.pkg
    pub fn new(pkg: String, target: String) -> ArtefactToken {
        ArtefactToken { pkg, target }
    }
}

impl fmt::Display for ArtefactToken {
    fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
        write!(f, "Package {} built for {}", self.pkg, self.target,)
    }
}

/// Possible ways in which channel metadata could be inconsistent.
///
/// See [`Channel::validate`] for more information.
///
/// [`Channel::validate`]: struct.Channel.html#method.validate
#[derive(Deserialize, Serialize, Debug, Clone, PartialEq, Eq, PartialOrd, Ord,
         Hash)]
pub enum ValidationError<'a> {
    /// The channel's [`renames`] field
    /// says package `old` was renamed to `new`,
    /// but no package named `new` is listed in the channel's [`pkg`] map.
    ///
    /// [`renames`]: struct.Channel.html#structfield.renames
    /// [`pkg`]: struct.Channel.html#structfield.pkg
    RenameToUnknownPackage {
        /// The old name for a package.
        old: &'a str,
        /// The alleged new name for the package,
        /// which isn't listed in the channel metadata.
        new: &'a str,
    },
    /// Package `pkg` built for `target`
    /// claims one of its [`components`]
    /// is an artefact built from a package named `component_pkg`,
    /// but no such package is listed in the channel's [`pkg`] map.
    ///
    /// [`components`]: struct.Artefact.html#structfield.components
    /// [`pkg`]: struct.Channel.html#structfield.pkg
    ArtefactHasUnknownComponent {
        /// The package whose artefact claims an unknown component.
        pkg: &'a str,
        /// The target of the artefact that claims an unknown component.
        target: &'a str,
        /// The alleged package name of the artefact that is
        /// a component of this artefact.
        component_pkg: &'a str,
    },
    /// Package `pkg` built for `target`
    /// claims one of its [`components`]
    /// is package `component_pkg` built for `component_target`,
    /// but no such target is listed in `component_pkg`'s [`target`] map.
    ///
    /// [`components`]: struct.Artefact.html#structfield.components
    /// [`target`]: struct.Package.html#structfield.target
    ArtefactComponentHasUnknownTarget {
        /// The package whose artefact claims a component
        /// with an unknown target.
        pkg: &'a str,
        /// The target of the artefact that claims a component
        /// with an unknown target.
        target: &'a str,
        /// The package name of the artefact that is
        /// a component of this artefact.
        component_pkg: &'a str,
        /// The alleged target of the artefact that is
        /// a component of this artefact.
        component_target: &'a str,
    },
    /// Package `pkg` built for `target`
    /// claims one of its [`extensions`]
    /// is an artefact built from a package named `extension_pkg`,
    /// but no such package is listed in the channel's [`pkg`] map.
    ///
    /// [`extensions`]: struct.Artefact.html#structfield.extensions
    /// [`pkg`]: struct.Channel.html#structfield.pkg
    ArtefactHasUnknownExtension {
        /// The package whose artefact claims an unknown extension.
        pkg: &'a str,
        /// The target of the artefact that claims an unknown extension.
        target: &'a str,
        /// The alleged package name of the artefact that is
        /// a extension of this artefact.
        extension_pkg: &'a str,
    },
    /// Package `pkg` built for `target`
    /// claims one of its [`extensions`]
    /// is package `extension_pkg` built for `extension_target`,
    /// but no such target is listed in `extension_pkg`'s [`target`] map.
    ///
    /// [`extensions`]: struct.Artefact.html#structfield.extensions
    /// [`target`]: struct.Package.html#structfield.target
    ArtefactExtensionHasUnknownTarget {
        /// The package whose artefact claims an extension
        /// with an unknown target.
        pkg: &'a str,
        /// The target of the artefact that claims an extension
        /// with an unknown target.
        target: &'a str,
        /// The package name of the artefact that is
        /// a extension of this artefact.
        extension_pkg: &'a str,
        /// The alleged target of the artefact that is
        /// a extension of this artefact.
        extension_target: &'a str,
    },
}

impl<'a> fmt::Display for ValidationError<'a> {
    fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
        match self {
            &ValidationError::RenameToUnknownPackage { old, new } => write!(
                f,
                "Package {:?} renamed to unknown package {:?}",
                old, new,
            ),
            &ValidationError::ArtefactHasUnknownComponent {
                pkg,
                target,
                component_pkg,
            } => write!(
                f,
                "Package {:?} for {:?} has unknown component {:?}",
                pkg, target, component_pkg,
            ),
            &ValidationError::ArtefactComponentHasUnknownTarget {
                pkg,
                target,
                component_pkg,
                component_target,
            } => write!(
                f,
                "Package {:?} for {:?} has \
                 component {:?} for unknown target {:?}",
                pkg, target, component_pkg, component_target,
            ),
            &ValidationError::ArtefactHasUnknownExtension {
                pkg,
                target,
                extension_pkg,
            } => write!(
                f,
                "Package {:?} for {:?} has unknown extension {:?}",
                pkg, target, extension_pkg,
            ),
            &ValidationError::ArtefactExtensionHasUnknownTarget {
                pkg,
                target,
                extension_pkg,
                extension_target,
            } => write!(
                f,
                "Package {:?} for {:?} has \
                 extension {:?} for unknown target {:?}",
                pkg, target, extension_pkg, extension_target,
            ),
        }
    }
}

impl<'a> error::Error for ValidationError<'a> {
    fn description(&self) -> &str {
        match self {
            &ValidationError::RenameToUnknownPackage { .. } => {
                "A package was renamed to an unknown name"
            }
            &ValidationError::ArtefactHasUnknownComponent { .. } => {
                "An artefact has an unknown component"
            }
            &ValidationError::ArtefactComponentHasUnknownTarget { .. } => {
                "An artefact has a component with an unknown target"
            }
            &ValidationError::ArtefactHasUnknownExtension { .. } => {
                "An artefact has an unknown extension"
            }
            &ValidationError::ArtefactExtensionHasUnknownTarget { .. } => {
                "An artefact has an extension with an unknown target"
            }
        }
    }
}

mod serialization;

#[cfg(test)]
mod tests {
    extern crate toml;

    use chrono::NaiveDate;

    static TEST_FILE: &'static str =
        include_str!("../examples/channel-rust-1.24.toml");

    #[test]
    fn it_works() {
        let ch: super::Channel = toml::from_str(TEST_FILE).unwrap();

        assert_eq!(ch.date, NaiveDate::from_ymd(2018, 2, 15));

        let pkgs: Vec<_> = ch.pkg.keys().cloned().collect();
        assert_eq!(
            pkgs,
            vec![
                "cargo",
                "rls-preview",
                "rust",
                "rust-analysis",
                "rust-docs",
                "rust-mingw",
                "rust-src",
                "rust-std",
                "rustc",
                "rustfmt-preview",
            ]
        );

        let cargo = ch.pkg.get("cargo").unwrap();
        assert_eq!(cargo.version, "0.25.0 (8c93e0895 2018-02-01)");
        assert_eq!(cargo.git_commit_hash, None);

        let cargo_for_aarch64 =
            cargo.target.get("aarch64-unknown-linux-gnu").unwrap();
        let cargo_for_aarch64_gz = cargo_for_aarch64
            .standalone
            .get(&super::ArchiveFormat::TarGzip)
            .unwrap();

        assert_eq!(
            cargo_for_aarch64_gz.url,
            "https://static.rust-lang.org/dist/2018-02-15/\
             cargo-0.25.0-aarch64-unknown-linux-gnu.tar.gz"
                .parse()
                .unwrap(),
        );
        assert_eq!(
            cargo_for_aarch64_gz.hash,
            "085fee1d520ca851dc14d8750ee843ebea81eec75c58a789396884171975e599"
        );
        assert_eq!(cargo_for_aarch64.components, []);
        assert_eq!(cargo_for_aarch64.extensions, []);

        let rust = ch.pkg.get("rust").unwrap();
        assert_eq!(rust.version, "1.24.0 (4d90ac38c 2018-02-12)");
        assert_eq!(
            rust.git_commit_hash,
            Some("4d90ac38c0b61bb69470b61ea2cccea0df48d9e5".into())
        );

        let rust_for_aarch64 =
            rust.target.get("aarch64-unknown-linux-gnu").unwrap();
        let rust_for_aarch64_xz = rust_for_aarch64
            .standalone
            .get(&super::ArchiveFormat::TarXz)
            .unwrap();

        assert_eq!(
            rust_for_aarch64_xz.url,
            "https://static.rust-lang.org/dist/2018-02-15/\
             rust-1.24.0-aarch64-unknown-linux-gnu.tar.xz"
                .parse()
                .unwrap(),
        );
        assert_eq!(
            rust_for_aarch64_xz.hash,
            "dd09d93396825f0a9f7806e677a87eb77f7ce76836568004264631027eaccc50"
        );

        fn mktoken(pkg: &str) -> super::ArtefactToken {
            super::ArtefactToken {
                pkg: pkg.into(),
                target: "aarch64-unknown-linux-gnu".into(),
            }
        };

        assert_eq!(
            rust_for_aarch64.components,
            [
                mktoken("rustc"),
                mktoken("rust-std"),
                mktoken("cargo"),
                mktoken("rust-docs"),
            ]
        );

        // I don't have the patience to type out all of these as Rust literals.
        assert_eq!(rust_for_aarch64.extensions.len(), 62);

        assert_eq!(ch.renames.get("rls").unwrap(), "rls-preview");

        assert_eq!(
            format!("{}", ch),
            "Rust release channel for version 1.24.0 (4d90ac38c 2018-02-12), \
             dated 2018-02-15",
        );
    }

    #[test]
    fn new_channel() {
        let ch = super::Channel::with_date(NaiveDate::from_ymd(1970, 1, 1));
        assert_eq!(ch.date, NaiveDate::from_ymd(1970, 01, 01));
        assert_eq!(ch.pkg.len(), 0);
        assert_eq!(ch.renames.len(), 0);

        assert_eq!(
            format!("{}", ch),
            "Rust release channel for version <unknown>, dated 1970-01-01",
        );
    }

    #[test]
    fn deserialize_channel() {
        let channel_toml = "\
            manifest-version = \"2\"
            date = \"1970-01-02\"
            ";
        let ch: super::Channel =
            channel_toml.parse().expect("Could not parse TOML");

        assert_eq!(ch.date, NaiveDate::from_ymd(1970, 01, 02));
        assert_eq!(ch.pkg.len(), 0);
        assert_eq!(ch.renames.len(), 0);
    }

    #[test]
    fn deserialize_rejects_v1() {
        let channel_toml = "\
            manifest-version = \"1\"
            date = \"1970-01-02\"
            ";
        let err = channel_toml
            .parse::<super::Channel>()
            .expect_err("Allowed manifest v1!");

        assert_eq!(
            format!("{}", err),
            "unknown variant `1`, expected `2` for key `manifest-version`"
        );
    }

    #[test]
    fn deserialize_rejects_v3() {
        let channel_toml = "\
            manifest-version = \"3\"
            date = \"1970-01-02\"
            ";
        let err = channel_toml
            .parse::<super::Channel>()
            .expect_err("Allowed manifest v3!");

        assert_eq!(
            format!("{}", err),
            "unknown variant `3`, expected `2` for key `manifest-version`"
        );
    }

    #[test]
    fn deserialize_rejects_unknown_version() {
        let channel_toml = "\
            manifest-version = \"freddled gruntbuggly\"
            date = \"1970-01-02\"
            ";
        let err = channel_toml
            .parse::<super::Channel>()
            .expect_err("Allowed manifest weird version!");

        assert_eq!(
            format!("{}", err),
            "unknown variant `freddled gruntbuggly`, \
             expected `2` for key `manifest-version`"
        );
    }

    #[test]
    fn deserialize_rejects_invalid_date() {
        let channel_toml = "\
            manifest-version = \"2\"
            date = \"invalid date\"
            ";
        let err = channel_toml
            .parse::<super::Channel>()
            .expect_err("Allowed manifest weird date!");

        assert_eq!(format!("{}", err), "input contains invalid characters");
    }

    #[test]
    fn deserialize_rejects_invalid_url() {
        let channel_toml = "\
            manifest-version = \"2\"
            date = \"1970-01-01\"
            [pkg.mypackage]
            version = \"1.2.3\"
            [pkg.mypackage.target.aarch64-unknown-linux-gnu]
            available = true
            url = \"some invalid url\"
            hash = \"aa0a89d80329fec6f9e84b79c1674c5427034408630c35da1be442c7da6d2364\"
            ";
        let err = channel_toml
            .parse::<super::Channel>()
            .expect_err("Allowed manifest weird date!");

        assert_eq!(format!("{}", err), "relative URL without a base");
    }

    #[test]
    fn serialize_channel() {
        let mut ch = super::Channel::with_date(NaiveDate::from_ymd(1970, 1, 1));

        ch.pkg.insert(
            "mytool".into(),
            super::Package {
                version: "0.1.0".into(),
                git_commit_hash: None,
                target: Default::default(),
            },
        );
        ch.renames.insert("myoldtool".into(), "mytool".into());

        assert_eq!(
            ch.to_string().expect("could not serialize"),
            "manifest-version = \"2\"\n\
             date = \"1970-01-01\"\n\
             [pkg.mytool]\n\
             version = \"0.1.0\"\n\
             [renames.myoldtool]\n\
             to = \"mytool\"\n\
             "
        );
    }

    #[test]
    fn lookup_unknown_token() {
        let ch: super::Channel =
            TEST_FILE.parse().expect("Could not parse TOML");

        let query = super::ArtefactToken {
            pkg: "mystery-package".into(),
            target: "mystery-unknown-linux-gnu".into(),
        };

        assert_eq!(ch.lookup_artefact(&query), None);
    }

    #[test]
    fn lookup_known_token() {
        let ch: super::Channel =
            TEST_FILE.parse().expect("Could not parse TOML");

        let query = super::ArtefactToken {
            pkg: "rls-preview".into(),
            target: "aarch64-unknown-linux-gnu".into(),
        };

        let art = ch.lookup_artefact(&query)
            .expect("Could not find rls-preview");
        let archive = art.standalone
            .get(&super::ArchiveFormat::TarXz)
            .expect("no .tar.xz?");

        assert_eq!(
            archive.url,
            "https://static.rust-lang.org/dist/2018-02-15/\
             rls-0.124.0-aarch64-unknown-linux-gnu.tar.xz"
                .parse()
                .unwrap(),
        );
        assert_eq!(
            archive.hash,
            "0970bd12581e5389b3c0af393d4ad58f2710ef62c68ff0eaf7523e5362db6c16"
        );
    }

    #[test]
    fn lookup_known_token_with_rename() {
        let ch: super::Channel =
            TEST_FILE.parse().expect("Could not parse TOML");

        let query = super::ArtefactToken {
            pkg: "rls".into(),
            target: "aarch64-unknown-linux-gnu".into(),
        };

        let art = ch.lookup_artefact(&query).expect("Could not find rls");
        let archive = art.standalone
            .get(&super::ArchiveFormat::TarXz)
            .expect("no .tar.xz?");

        assert_eq!(
            archive.url,
            "https://static.rust-lang.org/dist/2018-02-15/\
             rls-0.124.0-aarch64-unknown-linux-gnu.tar.xz"
                .parse()
                .unwrap(),
        );
        assert_eq!(
            archive.hash,
            "0970bd12581e5389b3c0af393d4ad58f2710ef62c68ff0eaf7523e5362db6c16"
        );
    }

    #[test]
    fn validate_accepts_valid_manifest() {
        let ch: super::Channel =
            TEST_FILE.parse().expect("Could not parse TOML");

        assert_eq!(ch.validate(), vec![]);
    }

    #[test]
    fn validate_rejects_bogus_rename_destination() {
        let mut ch: super::Channel =
            TEST_FILE.parse().expect("Could not parse TOML");

        ch.renames.insert("foo".into(), "bar".into());

        assert_eq!(
            ch.validate(),
            vec![
                super::ValidationError::RenameToUnknownPackage {
                    old: "foo",
                    new: "bar",
                },
            ],
        )
    }

    #[test]
    fn validate_rejects_package_component_with_bogus_package() {
        let mut ch: super::Channel =
            TEST_FILE.parse().expect("Could not parse TOML");

        {
            let cargo_pkg = ch.pkg.get_mut("cargo").expect("no cargo?");
            let cargo_for_aarch64 = cargo_pkg
                .target
                .get_mut("aarch64-unknown-linux-gnu")
                .expect("no aarch64?");
            cargo_for_aarch64.components.push(super::ArtefactToken {
                pkg: "foo".into(),
                target: "bar".into(),
            });
        }

        assert_eq!(
            ch.validate(),
            vec![
                super::ValidationError::ArtefactHasUnknownComponent {
                    pkg: "cargo",
                    target: "aarch64-unknown-linux-gnu",
                    component_pkg: "foo",
                },
            ],
        )
    }

    #[test]
    fn validate_rejects_package_component_with_bogus_target() {
        let mut ch: super::Channel =
            TEST_FILE.parse().expect("Could not parse TOML");

        {
            let cargo_pkg = ch.pkg.get_mut("cargo").expect("no cargo?");
            let cargo_for_aarch64 = cargo_pkg
                .target
                .get_mut("aarch64-unknown-linux-gnu")
                .expect("no aarch64?");
            cargo_for_aarch64.components.push(super::ArtefactToken {
                pkg: "rustc".into(),
                target: "bar".into(),
            });
        }

        assert_eq!(
            ch.validate(),
            vec![
                super::ValidationError::ArtefactComponentHasUnknownTarget {
                    pkg: "cargo",
                    target: "aarch64-unknown-linux-gnu",
                    component_pkg: "rustc",
                    component_target: "bar",
                },
            ],
        )
    }

    #[test]
    fn validate_rejects_package_extension_with_bogus_package() {
        let mut ch: super::Channel =
            TEST_FILE.parse().expect("Could not parse TOML");

        {
            let cargo_pkg = ch.pkg.get_mut("cargo").expect("no cargo?");
            let cargo_for_aarch64 = cargo_pkg
                .target
                .get_mut("aarch64-unknown-linux-gnu")
                .expect("no aarch64?");
            cargo_for_aarch64.extensions.push(super::ArtefactToken {
                pkg: "foo".into(),
                target: "bar".into(),
            });
        }

        assert_eq!(
            ch.validate(),
            vec![
                super::ValidationError::ArtefactHasUnknownExtension {
                    pkg: "cargo",
                    target: "aarch64-unknown-linux-gnu",
                    extension_pkg: "foo",
                },
            ],
        )
    }

    #[test]
    fn validate_rejects_package_extension_with_bogus_target() {
        let mut ch: super::Channel =
            TEST_FILE.parse().expect("Could not parse TOML");

        {
            let cargo_pkg = ch.pkg.get_mut("cargo").expect("no cargo?");
            let cargo_for_aarch64 = cargo_pkg
                .target
                .get_mut("aarch64-unknown-linux-gnu")
                .expect("no aarch64?");
            cargo_for_aarch64.extensions.push(super::ArtefactToken {
                pkg: "rustc".into(),
                target: "bar".into(),
            });
        }

        assert_eq!(
            ch.validate(),
            vec![
                super::ValidationError::ArtefactExtensionHasUnknownTarget {
                    pkg: "cargo",
                    target: "aarch64-unknown-linux-gnu",
                    extension_pkg: "rustc",
                    extension_target: "bar",
                },
            ],
        )
    }

    #[test]
    fn validate_detects_multiple_problems() {
        let mut ch: super::Channel =
            TEST_FILE.parse().expect("Could not parse TOML");
        ch.renames.insert("foo".into(), "bar".into());

        {
            let cargo_pkg = ch.pkg.get_mut("cargo").expect("no cargo?");
            let cargo_for_aarch64 = cargo_pkg
                .target
                .get_mut("aarch64-unknown-linux-gnu")
                .expect("no aarch64?");
            cargo_for_aarch64.components.push(super::ArtefactToken {
                pkg: "rustc".into(),
                target: "bar".into(),
            });
            cargo_for_aarch64.extensions.push(super::ArtefactToken {
                pkg: "foo".into(),
                target: "bar".into(),
            });
        }

        let mut errors = ch.validate();
        errors.sort();;

        assert_eq!(
            errors,
            vec![
                super::ValidationError::RenameToUnknownPackage {
                    old: "foo",
                    new: "bar",
                },
                super::ValidationError::ArtefactComponentHasUnknownTarget {
                    pkg: "cargo",
                    target: "aarch64-unknown-linux-gnu",
                    component_pkg: "rustc",
                    component_target: "bar",
                },
                super::ValidationError::ArtefactHasUnknownExtension {
                    pkg: "cargo",
                    target: "aarch64-unknown-linux-gnu",
                    extension_pkg: "foo",
                },
            ],
        )
    }

    #[test]
    fn test_errors_are_send_and_sync() {
        fn assert_send<T: Send>() {}
        fn assert_sync<T: Sync>() {}

        assert_send::<super::ValidationError>();
        assert_sync::<super::ValidationError>();
    }

    #[test]
    fn test_display_package() {
        let mut pkg = super::Package::new("1.2.3".into());
        assert_eq!(format!("{}", pkg), "Package version 1.2.3 for 0 target(s)",);

        pkg.target
            .insert("aarch64-unknown-linux-gnu".into(), Default::default());
        assert_eq!(format!("{}", pkg), "Package version 1.2.3 for 1 target(s)",)
    }

    #[test]
    fn test_display_artefact() {
        let mut artefact = super::Artefact::new();
        assert_eq!(
            format!("{}", artefact),
            "Artefact in 0 format(s), with 0 component(s) and 0 extension(s)",
        );

        artefact.components.push(super::ArtefactToken {
            pkg: "foo".into(),
            target: "bar".into(),
        });
        assert_eq!(
            format!("{}", artefact),
            "Artefact in 0 format(s), with 1 component(s) and 0 extension(s)",
        );

        artefact.extensions.push(super::ArtefactToken {
            pkg: "foo".into(),
            target: "bar".into(),
        });
        assert_eq!(
            format!("{}", artefact),
            "Artefact in 0 format(s), with 1 component(s) and 1 extension(s)",
        );

        artefact.standalone.insert(
            super::ArchiveFormat::TarGzip,
            super::ArchiveSource {
                url: "https://example.com/rust/archive.tar.gz".parse().unwrap(),
                hash: "abcd1234".into(),
            },
        );
        assert_eq!(
            format!("{}", artefact),
            "Artefact in 1 format(s), with 1 component(s) and 1 extension(s)",
        );
    }

    #[test]
    fn test_display_artefactsource() {
        let source = super::ArchiveSource::new(
            "https://example.com/rust/archive.tar.gz".parse().unwrap(),
            "abcd1234".into(),
        );
        assert_eq!(
            format!("{}", source),
            "<https://example.com/rust/archive.tar.gz>",
        );
    }

    #[test]
    fn test_display_archiveformat() {
        assert_eq!(format!("{}", super::ArchiveFormat::TarGzip), ".tar.gz",);
        assert_eq!(format!("{}", super::ArchiveFormat::TarXz), ".tar.xz",);
        assert_eq!(
            format!("{}", super::ArchiveFormat::ReservedForFutureExpansion),
            "<unknown>",
        );
    }

    #[test]
    fn test_display_artefacttoken() {
        let token = super::ArtefactToken::new(
            "somepackage".into(),
            "aarch64-unknown-linux-gnu".into(),
        );
        assert_eq!(
            format!("{}", token),
            "Package somepackage built for aarch64-unknown-linux-gnu",
        )
    }
}