Add some help with updating the registry in offline mode.

This makes two changes:

- If an index has never been downloaded, and `-Z offline` is used, provide a
  suggestion to run without `-Z offline`.

- If an index needs to be updated, and the network appears to be down, suggest
  running with `-Z offline`.

Author: ehuss

src/cargo/sources/registry/index.rs

@@ -300,6 +300,12 @@ impl<'cfg> RegistryIndex<'cfg> {
         let summaries = summaries
             .iter()
             .filter(|&(summary, yanked)| {
+                // Note: This particular logic can cause problems with
+                // optional dependencies when offline. If at least 1 version
+                // of an optional dependency is downloaded, but that version
+                // does not satisfy the requirements, then resolution will
+                // fail. Unfortunately, whether or not something is optional
+                // is not known here.
                 (online || load.is_crate_downloaded(summary.package_id()))
                     && (!yanked || {
                         log::debug!("{:?}", yanked_whitelist);

src/cargo/sources/registry/remote.rs

@@ -9,13 +9,14 @@ use std::str;
 use lazycell::LazyCell;
 use log::{debug, trace};
 
-use crate::core::{PackageId, SourceId};
+use crate::core::{nightly_features_allowed, PackageId, SourceId};
 use crate::sources::git;
 use crate::sources::registry::MaybeLock;
 use crate::sources::registry::{
     RegistryConfig, RegistryData, CRATE_TEMPLATE, INDEX_LOCK, VERSION_TEMPLATE,
 };
 use crate::util::errors::{CargoResult, CargoResultExt};
+use crate::util::network::maybe_spurious;
 use crate::util::{Config, Sha256};
 use crate::util::{FileLock, Filesystem};
 
@@ -176,6 +177,14 @@ impl<'cfg> RegistryData for RemoteRegistry<'cfg> {
 
     fn update_index(&mut self) -> CargoResult<()> {
         if self.config.cli_unstable().offline {
+            if self.repo()?.is_empty()? {
+                failure::bail!(
+                    "unable to fetch {} in offline mode\n\
+                     Run `cargo fetch` to download the registry index and all \
+                     of a project's dependencies before going offline.",
+                    self.source_id
+                );
+            }
             return Ok(());
         }
         if self.config.cli_unstable().no_index_update {
@@ -212,8 +221,18 @@ impl<'cfg> RegistryData for RemoteRegistry<'cfg> {
         let url = self.source_id.url();
         let refspec = "refs/heads/master:refs/remotes/origin/master";
         let repo = self.repo.borrow_mut().unwrap();
-        git::fetch(repo, url, refspec, self.config)
-            .chain_err(|| format!("failed to fetch `{}`", url))?;
+        let result = git::fetch(repo, url, refspec, self.config);
+        if let Err(e) = result {
+            let extra = if maybe_spurious(&e) && nightly_features_allowed() && !repo.is_empty()? {
+                "\nIf the network is unavailable, consider running with the -Zoffline \
+                 flag to run in offline mode."
+            } else {
+                ""
+            };
+            return Err(e
+                .context(format!("failed to fetch `{}`{}", url, extra))
+                .into());
+        }
         self.config.updated_sources().insert(self.source_id);
         Ok(())
     }

src/cargo/util/network.rs

@@ -36,7 +36,7 @@ impl<'a> Retry<'a> {
     }
 }
 
-fn maybe_spurious(err: &Error) -> bool {
+pub fn maybe_spurious(err: &Error) -> bool {
     for e in err.iter_chain() {
         if let Some(git_err) = e.downcast_ref::<git2::Error>() {
             match git_err.class() {

tests/testsuite/offline.rs

@@ -171,13 +171,15 @@ fn cargo_compile_offline_not_try_update() {
         .with_status(101)
         .with_stderr(
             "\
-error: no matching package named `not_cached_dep` found
-location searched: registry `[..]`
-required by package `bar v0.1.0 ([..])`
-As a reminder, you're using offline mode (-Z offline) \
-which can sometimes cause surprising resolution failures, \
-if this error is too confusing you may wish to retry \
-without the offline flag.",
+[ERROR] failed to load source for a dependency on `not_cached_dep`
+
+Caused by:
+  Unable to update registry `https://github.com/rust-lang/crates.io-index`
+
+Caused by:
+  unable to fetch registry `https://github.com/rust-lang/crates.io-index` in offline mode
+Run `cargo fetch` to download the registry index and all of a project's dependencies before going offline.
+",
         )
         .run();
 }
@@ -486,3 +488,60 @@ fn cargo_compile_offline_with_cached_git_dep() {
         .with_stdout("hello from cached git repo rev1\n")
         .run();
 }
+
+#[test]
+fn offline_resolve_optional_fail() {
+    // Example where resolve fails offline.
+    //
+    // This happens if at least 1 version of an optional dependency is
+    // available, but none of them satisfy the requirements. The current logic
+    // that handles this is `RegistryIndex::query_inner`, and it doesn't know
+    // if the package being queried is an optional one. This is not ideal, it
+    // would be best if it just ignored optional (unselected) dependencies.
+    Package::new("dep", "1.0.0").publish();
+
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "0.1.0"
+
+            [dependencies]
+            dep = { version = "1.0", optional = true }
+            "#,
+        )
+        .file("src/lib.rs", "")
+        .build();
+
+    p.cargo("fetch").run();
+
+    // Change dep to 2.0.
+    p.change_file(
+        "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "0.1.0"
+
+            [dependencies]
+            dep = { version = "2.0", optional = true }
+            "#,
+    );
+
+    p.cargo("build -Z offline")
+        .masquerade_as_nightly_cargo()
+        .with_status(101)
+        .with_stderr("\
+[ERROR] failed to select a version for the requirement `dep = \"^2.0\"`
+  candidate versions found which didn't match: 1.0.0
+  location searched: `[..]` index (which is replacing registry `https://github.com/rust-lang/crates.io-index`)
+required by package `foo v0.1.0 ([..]/foo)`
+perhaps a crate was updated and forgotten to be re-vendored?
+As a reminder, you're using offline mode (-Z offline) which can sometimes cause \
+surprising resolution failures, if this error is too confusing you may wish to \
+retry without the offline flag.
+")
+        .run();
+}