gvfs-helper: prevent and/or give advice on repeated downloads to shared object cache (git-for-windows#840)

There have been a number of customer-reported problems with errors of
the form

```
error: inflate: data stream error (unknown compression method)
error: unable to unpack a163b1302d4729ebdb0a12d3876ca5bca4e1a8c3 header
error: files 'D:/.scalarCache/id_49b0c9f4-555f-4624-8157-a57e6df513b3/pack/tempPacks/t-20260106-014520-049919-0001.temp' and 'D:/.scalarCache/id_49b0c9f4-555f-4624-8157-a57e6df513b3/a1/63b1302d4729ebdb0a12d3876ca5bca4e1a8c3' differ in contents
error: gvfs-helper error: 'could not install loose object 'D:/.scalarCache/id_49b0c9f4-555f-4624-8157-a57e6df513b3/a1/63b1302d4729ebdb0a12d3876ca5bca4e1a8c3': from GET a163b1302d4729ebdb0a12d3876ca5bca4e1a8c3'
```

or 

```
Receiving packfile 1/1 with 1 objects (bytes received): 17367934, done.
Receiving packfile 1/1 with 1 objects [retry 1/6] (bytes received): 17367934, done.
Waiting to retry after network error (sec): 100% (8/8), done.
Receiving packfile 1/1 with 1 objects [retry 2/6] (bytes received): 17367934, done.
Waiting to retry after network error (sec): 100% (16/16), done.
Receiving packfile 1/1 with 1 objects [retry 3/6] (bytes received): 17367934, done.
```

These are not actually due to network issues, but they look like it
based on the stack that is doing retries. Instead, these actually have
problems when installing the loose object or packfile into the shared
object cache.

The loose objects are hitting issues when installing and the target
loose object is corrupt in some way, such as all NUL bytes because the
disk wasn't flushed when the machine shut down. The error results
because we are doing a collision check without confirming that the
existing contents are valid.

The packfiles may be hitting similar comparison cases, but it is less
likely. We update these packfile installations to also skip the
collision check.

In both cases, if we have a transient network error, we add a new advice
message that helps users with the two most common workarounds:

1. Your disk may be full. Make room.
2. Your shared object cache may be corrupt. Push all branches, delete
it, and fetch to refill it.

I make special note of when the shared object cache doesn't exist and
point that it probably should so the whole repo is suspect at that
point.

* [X] This change only applies to interactions with Azure DevOps and the
      GVFS Protocol.

Resolves git-for-windows#837.

Author: dscho

advice.c

@@ -93,6 +93,9 @@ static struct {
 	[ADVICE_USE_CORE_FSMONITOR_CONFIG]		= { "useCoreFSMonitorConfig" },
 	[ADVICE_WAITING_FOR_EDITOR]			= { "waitingForEditor" },
 	[ADVICE_WORKTREE_ADD_ORPHAN]			= { "worktreeAddOrphan" },
+
+	/* microsoft/git custom advice below: */
+	[ADVICE_GVFS_HELPER_TRANSIENT_RETRY]		= { "gvfs.transientRetry"},
 };
 
 static const char turn_off_instructions[] =

advice.h

@@ -60,6 +60,9 @@ enum advice_type {
 	ADVICE_USE_CORE_FSMONITOR_CONFIG,
 	ADVICE_WAITING_FOR_EDITOR,
 	ADVICE_WORKTREE_ADD_ORPHAN,
+
+	/* microsoft/git custom advice below: */
+	ADVICE_GVFS_HELPER_TRANSIENT_RETRY,
 };
 
 int git_default_advice_config(const char *var, const char *value);

gvfs-helper.c

@@ -255,6 +255,7 @@
 #include "packfile.h"
 #include "date.h"
 #include "versioncmp.h"
+#include "advice.h"
 
 #define TR2_CAT "gvfs-helper"
 
@@ -1939,12 +1940,21 @@ static void my_finalize_packfile(struct gh__request_params *params,
 	 * files, do we create the matching .keep (when requested).
 	 *
 	 * If we get an error and the target files already exist, we
-	 * silently eat the error.  Note that finalize_object_file()
+	 * silently eat the error.  Note that finalize_object_file_flags()
 	 * has already munged errno (and it has various creation
 	 * strategies), so we don't bother looking at it.
+	 *
+	 * We use FOF_SKIP_COLLISION_CHECK in case the same packfile was
+	 * attempted for install earlier but got corrupted or failed to
+	 * flush due to a disk issue. This prevents a narrow failure case
+	 * but is better than failing for silly reasons.
 	 */
-	if (finalize_object_file(the_repository, temp_path_pack->buf, final_path_pack->buf) ||
-	    finalize_object_file(the_repository, temp_path_idx->buf, final_path_idx->buf)) {
+	if (finalize_object_file_flags(the_repository,
+				       temp_path_pack->buf, final_path_pack->buf,
+				       FOF_SKIP_COLLISION_CHECK) ||
+	    finalize_object_file_flags(the_repository,
+				       temp_path_idx->buf, final_path_idx->buf,
+				       FOF_SKIP_COLLISION_CHECK)) {
 		unlink(temp_path_pack->buf);
 		unlink(temp_path_idx->buf);
 
@@ -2459,7 +2469,16 @@ static void install_loose(struct gh__request_params *params,
 		goto cleanup;
 	}
 
-	if (finalize_object_file(the_repository, tmp_path.buf, loose_path.buf)) {
+	/*
+	 * We skip collision check because the loose object in the target
+	 * may be corrupt and we should override it with a better value
+	 * instead of failing at this point.
+	 *
+	 * See https://github.com/microsoft/git/issues/837
+	 */
+	if (finalize_object_file_flags(the_repository,
+				       tmp_path.buf, loose_path.buf,
+				       FOF_SKIP_COLLISION_CHECK)) {
 		unlink(tmp_path.buf);
 		strbuf_addf(&status->error_message,
 			    "could not install loose object '%s'",
@@ -3007,6 +3026,32 @@ static int compute_transient_delay(int attempt)
 	return v;
 }
 
+static void gvfs_advice_on_retry(void)
+{
+	static int advice_given = 0;
+
+	if (advice_given)
+		return;
+	advice_given = 1;
+
+	if (gvfs_shared_cache_pathname.len) {
+		advise_if_enabled(ADVICE_GVFS_HELPER_TRANSIENT_RETRY,
+				  "These retries may hint towards issues with your disk or\n"
+				  "shared object cache. Check to see if your disk is full.\n"
+				  "If your disk has space, then your shared object cache\n"
+				  "may have corrupt files. Push all local branches then\n"
+				  "delete '%s'\n"
+				  "and run 'git fetch' to reload the cache.",
+				  gvfs_shared_cache_pathname.buf);
+	} else {
+		advise_if_enabled(ADVICE_GVFS_HELPER_TRANSIENT_RETRY,
+				  "These retries may hint towards issues with your disk.\n"
+				  "Check to see if your disk is full. Note also that you\n"
+				  "do not have a gvfs.sharedCache config, which is not\n"
+				  "normal. You may need to delete and reclone this repo.");
+	}
+}
+
 /*
  * Robustly make an HTTP request.  Retry if necessary to hide common
  * transient network errors and/or 429 blockages.
@@ -3049,6 +3094,10 @@ static void do_req__with_robust_retry(const char *url_base,
 			/*fallthru*/
 
 		case GH__RETRY_MODE__TRANSIENT:
+			/*
+			 * Give advice for common reasons this could happen:
+			 */
+			gvfs_advice_on_retry();
 			params->k_transient_delay_sec =
 				compute_transient_delay(params->k_attempt);
 			continue;