gvfs-helper: emit X-Session-Id headers for requests (#862)

A common problem when tracking GVFS Protocol queries is that we don't
have a way to connect client and server interactions. This is especially
true in the typical case where a cache server deployment is hidden
behind a load balancer. We can't even determine which cache server was
used for certain requests!

Add some client-identifying data to the HTTP queries using the
X-Session-Id header. This will by default identify the helper process
using its SID. If configured via the new gvfs.sessionKey config, it will
prefix this SID with another config value.

For example, Office monorepo users have an 'otel.trace2.id' config value
that is a pseudonymous identifier. This allows telemetry readers to
group requests by enlistment without knowing the user's identity at all.
Users could opt-in to provide this identifier for investigations around
their long-term performance or issues. This change makes it possible to
extend this to cache server interactions.

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

Author: mjcheetham

Documentation/config/gvfs.adoc

@@ -26,3 +26,11 @@ gvfs.fallback::
 	If set to `false`, then never fallback to the origin server when the cache
 	server fails to connect. This will alert users to failures with the cache
 	server, but avoid causing throttling on the origin server.
+
+gvfs.sessionKey::
+	If set to a string, then the value is a config key name that will be used
+	to set a prefix in the `X-Session-Id` header sent to the server for all
+	GVFS Protocol calls. This allows engineering systems to improve support
+	across client and server behavior, including any End User Pseodynomous
+	Identifiers (EUPI) that may be configured. The `X-Session-Id` will
+	include the SID of the current process in either case.

gvfs-helper.c

@@ -251,6 +251,7 @@
 #include "abspath.h"
 #include "progress.h"
 #include "trace2.h"
+#include "trace2/tr2_sid.h"
 #include "wrapper.h"
 #include "packfile.h"
 #include "date.h"
@@ -451,6 +452,54 @@ static void reset_cache_server(void)
 	}
 }
 
+/*
+ * Build the X-Session-Id header value based on gvfs.sessionkey config.
+ *
+ * If gvfs.sessionkey is set, it specifies which config key contains
+ * a prefix to prepend to the SID. The format is: <prefix>:<SID>
+ *
+ * If gvfs.sessionkey is not set or the referenced key doesn't exist,
+ * the header value is just the SID.
+ *
+ * Returns a newly allocated string that must be freed by the caller.
+ */
+static char *build_session_id_header(void)
+{
+	struct strbuf header = STRBUF_INIT;
+	const char *sid = tr2_sid_get();
+	char *session_key = NULL;
+	char *prefix = NULL;
+
+	/* Read gvfs.sessionkey to see if it points to a config key */
+	if (!repo_config_get_string(the_repository, "gvfs.sessionkey", &session_key) &&
+	    session_key) {
+		/* Try to read the config key that session_key points to */
+		if (!repo_config_get_string(the_repository, session_key, &prefix) &&
+		    prefix) {
+			/* We have a prefix, format as: X-Session-Id: <prefix>:<SID> */
+			strbuf_addf(&header, "X-Session-Id: %s:%s", prefix, sid);
+			free(prefix);
+		} else {
+			/* Config key doesn't exist, use just SID */
+			strbuf_addf(&header, "X-Session-Id: %s", sid);
+		}
+
+		free(session_key);
+	} else {
+		/* No gvfs.sessionkey configured, use just SID */
+		strbuf_addf(&header, "X-Session-Id: %s", sid);
+	}
+
+	return strbuf_detach(&header, NULL);
+}
+
+static void append_session_id_header(struct curl_slist **headers)
+{
+	char *session_id_header = build_session_id_header();
+	*headers = curl_slist_append(*headers, session_id_header);
+	free(session_id_header);
+}
+
 static const char *gh__server_type_label[GH__SERVER_TYPE__NR] = {
 	"(main)",
 	"(cs)"
@@ -3304,6 +3353,7 @@ static void do__http_get__simple_endpoint(struct gh__response_status *status,
 					   "X-TFS-FedAuthRedirect: Suppress");
 	params.headers = curl_slist_append(params.headers,
 					   "Pragma: no-cache");
+	append_session_id_header(&params.headers);
 
 	if (gh__cmd_opts.show_progress) {
 		/*
@@ -3373,6 +3423,7 @@ static void do__http_get__gvfs_object(struct gh__response_status *status,
 					   "X-TFS-FedAuthRedirect: Suppress");
 	params.headers = curl_slist_append(params.headers,
 					   "Pragma: no-cache");
+	append_session_id_header(&params.headers);
 
 	oidcpy(&params.loose_oid, oid);
 
@@ -3434,6 +3485,8 @@ static void do__http_post__gvfs_objects(struct gh__response_status *status,
 					   "Pragma: no-cache");
 	params.headers = curl_slist_append(params.headers,
 					   "Content-Type: application/json");
+	append_session_id_header(&params.headers);
+
 	/*
 	 * If our POST contains more than one object, we want the
 	 * server to send us a packfile.  We DO NOT want the non-standard
@@ -3570,6 +3623,7 @@ static void do__http_get__gvfs_prefetch(struct gh__response_status *status,
 					   "Pragma: no-cache");
 	params.headers = curl_slist_append(params.headers,
 					   "Accept: application/x-gvfs-timestamped-packfiles-indexes");
+	append_session_id_header(&params.headers);
 
 	if (gh__cmd_opts.show_progress)
 		strbuf_addf(&params.progress_base_phase3_msg,

t/helper/test-gvfs-protocol.c

@@ -1552,6 +1552,19 @@ static enum worker_result req__read(struct req *req, int fd)
 	 */
 done:
 
+	/*
+	 * Log the X-Session-Id header if present (for testing purposes).
+	 */
+	{
+		struct string_list_item *item;
+		for_each_string_list_item(item, &req->header_list) {
+			if (starts_with(item->string, "X-Session-Id:")) {
+				loginfo("Received header: %s", item->string);
+				break;
+			}
+		}
+	}
+
 #if 0
 	/*
 	 * This is useful for debugging the request, but very noisy.

t/t5793-gvfs-helper-integration.sh

@@ -163,4 +163,54 @@ test_expect_success 'integration: implicit-get: cache_http_503,with-fallback: di
 
 # T2 should be considered contaminated at this point.
 
+#################################################################
+# Test X-Session-Id header
+#
+# The X-Session-Id header should contain the SID (session ID).
+#################################################################
+
+test_expect_success 'integration: X-Session-Id header with and without prefix' '
+	test_when_finished "per_test_cleanup" &&
+	start_gvfs_protocol_server &&
+
+	# Case 1: No gvfs.sessionkey configured - should send just SID
+	git -C "$REPO_T1" gvfs-helper \
+		--cache-server=disable \
+		--remote=origin \
+		get \
+		<"$OID_ONE_BLOB_FILE" >OUT.output1 &&
+
+	# Verify X-Session-Id contains SID (with process ID marker "-P")
+	test_grep "X-Session-Id:.*-P" "$SERVER_LOG" >OUT.case1 &&
+	# Verify no slash (no prefix)
+	test_grep ! "X-Session-Id:.*:" OUT.case1 &&
+
+	# Case 2: gvfs.sessionkey points to non-existent config - should send just SID
+	rm -f OUT.output* OUT.case* &&
+	git -C "$REPO_T1" -c gvfs.sessionkey="test.id" gvfs-helper \
+		--cache-server=disable \
+		--remote=origin \
+		get \
+		<"$OID_ONE_BLOB_FILE" >OUT.output2 &&
+
+	# Verify X-Session-Id still contains just SID (no prefix)
+	test_grep "X-Session-Id:.*-P" "$SERVER_LOG" >OUT.case2 &&
+	test_grep ! "X-Session-Id:.*:" OUT.case2 &&
+
+	# Case 3: gvfs.sessionkey points to existing config - should send prefix/SID
+	rm -f OUT.output* OUT.case* &&
+	git -C "$REPO_T1" \
+		-c gvfs.sessionkey="test.id" \
+		-c test.id="my-trace-12345" \
+		gvfs-helper \
+		--cache-server=disable \
+		--remote=origin \
+		get \
+		<"$OID_ONE_BLOB_FILE" >OUT.output3 &&
+
+	# Verify X-Session-Id contains prefix, slash, and SID
+	test_grep "X-Session-Id:.*my-trace-12345:" "$SERVER_LOG" >OUT.case3 &&
+	test_grep "X-Session-Id:.*my-trace-12345:.*-P" OUT.case3
+'
+
 test_done