feat(transport): send X-SDK-VERSION header (dotnet-sdk/{version}) (#139)

Send the NArk SDK's own version as X-SDK-VERSION: dotnet-sdk/{version} on every gRPC and REST request, alongside the existing X-Build-Version. Value derived from Nerdbank.GitVersioning with +commit metadata stripped.

Author: Kukks

NArk.Core/Transport/ArkdVersion.cs

@@ -10,30 +10,64 @@ namespace NArk.Transport;
 public static class ArkdVersion
 {
     public const string TargetBuild = "0.9.9";
+
+    /// <summary>
+    /// This SDK's own package version (computed by Nerdbank.GitVersioning from git history),
+    /// sent as the <c>X-SDK-VERSION</c> header on every outgoing request. The SemVer build-metadata
+    /// suffix (the <c>+commit</c> part of the assembly informational version) is stripped, leaving
+    /// the clean version, e.g. <c>1.0.327-beta</c>. Unlike <see cref="TargetBuild"/> (the Arkade
+    /// server build this SDK targets), this is the version of the NArk SDK itself.
+    /// </summary>
+    public static readonly string SdkVersion = StripBuildMetadata(ThisAssembly.AssemblyInformationalVersion);
+
+    /// <summary>
+    /// Product token sent as the <c>X-SDK-VERSION</c> header, identifying this SDK and its version
+    /// in <c>name/version</c> form, e.g. <c>dotnet-sdk/1.0.327-beta</c>. The name lets arkd
+    /// distinguish the .NET SDK from other SDKs (e.g. the TypeScript SDK) on the same wire.
+    /// </summary>
+    public static readonly string SdkVersionHeaderValue = $"{SdkName}/{SdkVersion}";
+
+    internal const string SdkName = "dotnet-sdk";
     internal const string HeaderName = "X-Build-Version";
+    internal const string SdkVersionHeaderName = "X-SDK-VERSION";
     internal const string DigestHeaderName = "X-Digest";
 
     /// <summary>
-    /// Adds the <c>X-Build-Version</c> default header to <paramref name="http"/>.
+    /// Adds the <c>X-Build-Version</c> and <c>X-SDK-VERSION</c> default headers to <paramref name="http"/>.
     /// </summary>
     public static HttpClient InjectHeader(this HttpClient http)
     {
         if (!http.DefaultRequestHeaders.Contains(HeaderName))
         {
             http.DefaultRequestHeaders.TryAddWithoutValidation(HeaderName, TargetBuild);
         }
+        if (!http.DefaultRequestHeaders.Contains(SdkVersionHeaderName))
+        {
+            http.DefaultRequestHeaders.TryAddWithoutValidation(SdkVersionHeaderName, SdkVersionHeaderValue);
+        }
         return http;
     }
 
     /// <summary>
-    /// Appends the <c>X-Build-Version</c> entry to <paramref name="metadata"/>.
+    /// Appends the <c>X-Build-Version</c> and <c>X-SDK-VERSION</c> entries to <paramref name="metadata"/>.
     /// </summary>
     internal static Metadata InjectHeader(this Metadata metadata)
     {
         metadata.Add(HeaderName, TargetBuild);
+        metadata.Add(SdkVersionHeaderName, SdkVersionHeaderValue);
         return metadata;
     }
 
+    /// <summary>
+    /// Strips the SemVer build-metadata suffix (everything from the first <c>+</c>) from an
+    /// assembly informational version, e.g. <c>1.0.327-beta+d238a7c85b</c> → <c>1.0.327-beta</c>.
+    /// </summary>
+    private static string StripBuildMetadata(string informationalVersion)
+    {
+        var plus = informationalVersion.IndexOf('+');
+        return plus < 0 ? informationalVersion : informationalVersion[..plus];
+    }
+
     /// <summary>
     /// Throws <see cref="IncompatibleSdkVersionException"/> when <paramref name="errorDetail"/> contains
     /// <c>BUILD_VERSION_TOO_OLD</c>. The exception propagates to the caller; the SDK does not catch it.

NArk.Tests/BuildVersionHeaderTests.cs

@@ -24,6 +24,46 @@ public void InjectHeader_HttpClient_AddsXBuildVersionHeader()
             Contains.Item(ArkdVersion.TargetBuild));
     }
 
+    [Test]
+    public void SdkVersion_IsCleanSemVerWithoutBuildMetadata()
+    {
+        // nbgv computes this from git; the value changes per commit, so assert shape, not a literal.
+        Assert.That(ArkdVersion.SdkVersion, Is.Not.Empty);
+        Assert.That(ArkdVersion.SdkVersion, Does.Not.Contain("+"),
+            "SdkVersion must be the clean version without the +commit build-metadata suffix.");
+    }
+
+    [Test]
+    public void SdkVersionHeaderValue_IsDotnetSdkProductToken()
+    {
+        // Product-token form "name/version", e.g. dotnet-sdk/1.0.327-beta.
+        Assert.That(ArkdVersion.SdkVersionHeaderValue, Is.EqualTo($"dotnet-sdk/{ArkdVersion.SdkVersion}"));
+        Assert.That(ArkdVersion.SdkVersionHeaderValue, Does.StartWith("dotnet-sdk/"));
+    }
+
+    [Test]
+    public void InjectHeader_HttpClient_AddsXSdkVersionHeader()
+    {
+        var http = new HttpClient();
+
+        http.InjectHeader();
+
+        Assert.That(
+            http.DefaultRequestHeaders.GetValues("X-SDK-VERSION"),
+            Contains.Item(ArkdVersion.SdkVersionHeaderValue));
+    }
+
+    [Test]
+    public void InjectHeader_HttpClient_XSdkVersionIsIdempotent()
+    {
+        var http = new HttpClient();
+
+        http.InjectHeader();
+        http.InjectHeader();
+
+        Assert.That(http.DefaultRequestHeaders.GetValues("X-SDK-VERSION").ToList(), Has.Count.EqualTo(1));
+    }
+
     [Test]
     public void InjectHeader_HttpClient_IsIdempotent()
     {

docs/articles/signer-rotation.md

@@ -43,11 +43,12 @@ Reconciliation calls `ISingleKeyDefaultEnsurer.EnsureDefaultAsync` to upsert the
 
 ## Version and Digest Headers
 
-Every outgoing gRPC and REST request carries two headers:
+Every outgoing gRPC and REST request carries these headers:
 
 | Header | Value | Purpose |
 |--------|-------|---------|
 | `X-Build-Version` | `ArkdVersion.TargetBuild` (e.g. `0.9.9`) | Lets arkd reject SDKs that are too old (`BUILD_VERSION_TOO_OLD`) |
+| `X-SDK-VERSION` | `ArkdVersion.SdkVersionHeaderValue` (e.g. `dotnet-sdk/1.0.327-beta`) | Identifies the SDK and its own package version (from Nerdbank.GitVersioning) in `name/version` form, so arkd can distinguish the .NET SDK from other SDKs |
 | `X-Digest` | Current server-info digest | Lets arkd detect stale cached configuration (`DIGEST_MISMATCH`) |
 
 The headers are injected by `BuildVersionInterceptor` (gRPC) and `BuildVersionHandler` (REST). Both throw typed exceptions on rejection: