Merge origin/main into claude/spelunk-tunnel

Port forwarding took host schema version 8 first, so the Spelunk route moves to 9 and is written after the forwards. A host may carry both.

src/DodoSSH.Client.Domain/HostSecretCodec.cs

@@ -112,6 +112,13 @@ public static class HostSecretCodec
     /// </remarks>
     public const int PinnedPathsSchemaVersion = 7;
 
+    /// <summary>The version that introduced <see cref="HostSecret.PortForwards"/>.</summary>
+    /// <remarks>
+    /// Its own version for the reason <see cref="PinnedPathsSchemaVersion"/> gives: a host can carry
+    /// forwards without pinning anything, and should stay editable on a build that knows 7 until it does.
+    /// </remarks>
+    public const int PortForwardsSchemaVersion = 8;
+
     /// <summary>The version that introduced <see cref="HostSecret.Spelunk"/>.</summary>
     /// <remarks>
     /// <para>
@@ -122,10 +129,11 @@ public static class HostSecretCodec
     /// </para>
     /// <para>
     /// Additive, like every version but <see cref="PortInheritSchemaVersion"/>: the route is one more
-    /// property, and a build that does not know it skips it and still reads a valid host.
+    /// property, and a build that does not know it skips it and still reads a valid host. It follows
+    /// <see cref="PortForwardsSchemaVersion"/>, whose forwards reached main first.
     /// </para>
     /// </remarks>
-    public const int SpelunkSchemaVersion = 8;
+    public const int SpelunkSchemaVersion = 9;
 
     /// <summary>The highest schema version this build can write.</summary>
     /// <remarks>
@@ -179,6 +187,10 @@ public static class HostSecretCodec
             // as it did before this field existed.
             PinnedPaths = host.PinnedPaths.Count == 0 ? null : [.. host.PinnedPaths],
 
+            // Last, and null when empty, for the reason both fields above give.
+            PortForwards = host.PortForwards.Count == 0
+                ? null
+                : [.. host.PortForwards.Select(PortForwardDocument.From)],
             // Last of all, and absent for a host that is dialled, so every host without a route encodes
             // exactly as it did before routes existed.
             Spelunk = host.Spelunk is { } route
@@ -264,6 +276,11 @@ public static class HostSecretCodec
             version = Math.Max(version, PinnedPathsSchemaVersion);
         }
 
+        if (host.PortForwards.Count > 0)
+        {
+            version = Math.Max(version, PortForwardsSchemaVersion);
+        }
+
         if (host.Spelunk is not null)
         {
             version = Math.Max(version, SpelunkSchemaVersion);
@@ -326,6 +343,11 @@ public static class HostSecretCodec
             return false;
         }
 
+        if (!TryBuildForwards(parsed.PortForwards, out var forwards))
+        {
+            return false;
+        }
+
         var candidate = new HostSecret
         {
             Label = parsed.Label ?? string.Empty,
@@ -348,6 +370,7 @@ public static class HostSecretCodec
 
             PinnedPaths = PinnedPathList.Create(parsed.PinnedPaths ?? []),
 
+            PortForwards = forwards,
             Spelunk = RouteFrom(parsed.Spelunk),
         };
 
@@ -360,6 +383,45 @@ public static class HostSecretCodec
         return true;
     }
 
+    /// <remarks>
+    /// A missing id, kind or port is a refusal rather than a default. Each would be invented here — a fresh
+    /// id the other machines do not have, a <c>Local</c> nobody chose — and an invented forward is one the
+    /// next save writes back as though somebody had asked for it.
+    /// </remarks>
+    private static bool TryBuildForwards(
+        PortForwardDocument?[]? parsed,
+        [NotNullWhen(true)] out PortForwardList? forwards)
+    {
+        forwards = PortForwardList.Empty;
+
+        if (parsed is null)
+        {
+            return true;
+        }
+
+        var rules = new List<PortForwardRule>(parsed.Length);
+
+        foreach (var entry in parsed)
+        {
+            if (entry?.Id is not { } id || entry.Kind is not { } kind || entry.BindPort is not { } bindPort)
+            {
+                return false;
+            }
+
+            rules.Add(new PortForwardRule
+            {
+                Id = id,
+                Kind = (PortForwardKind)kind,
+                BindPort = bindPort,
+                TargetHost = entry.TargetHost,
+                TargetPort = entry.TargetPort,
+            });
+        }
+
+        forwards = PortForwardList.Create(rules);
+        return true;
+    }
+
     /// <summary>The route as stored, or null when there is none.</summary>
     /// <remarks>
     /// Missing parts come through as empty values rather than making the route vanish, so that
@@ -447,6 +509,9 @@ internal sealed class HostPayloadDocument
     /// </remarks>
     public string[]? PinnedPaths { get; set; }
 
+    /// <remarks>Last, and null rather than <c>[]</c>, for the reasons <see cref="TagIds"/> gives.</remarks>
+    public PortForwardDocument?[]? PortForwards { get; set; }
+
     /// <remarks>
     /// Last, and null for a host that is dialled, for the reason <see cref="TagIds"/> gives. One nested object
     /// rather than three loose properties, because the three are one decision — a server id without its
@@ -465,6 +530,33 @@ internal sealed class SpelunkPayloadDocument
     public Guid? ApiKeyCredentialId { get; set; }
 }
 
+/// <summary>One forward's serialised shape. Nullable throughout, because it models untrusted input.</summary>
+/// <remarks>
+/// The kind is written as its number rather than its name, so renaming a member of
+/// <see cref="PortForwardKind"/> can never change what is on the wire.
+/// </remarks>
+internal sealed class PortForwardDocument
+{
+    public Guid? Id { get; set; }
+
+    public int? Kind { get; set; }
+
+    public int? BindPort { get; set; }
+
+    public string? TargetHost { get; set; }
+
+    public int? TargetPort { get; set; }
+
+    public static PortForwardDocument From(PortForwardRule rule) => new()
+    {
+        Id = rule.Id,
+        Kind = (int)rule.Kind,
+        BindPort = rule.BindPort,
+        TargetHost = rule.TargetHost,
+        TargetPort = rule.TargetPort,
+    };
+}
+
 [JsonSourceGenerationOptions(
     PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
     DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,