Updates

Author: aritchie

readme.md

@@ -24,7 +24,7 @@ JWT, OpenAPI, HPACK, QPACK — is built on what is in the box.
 | [Shiny.Net.HttpServer.WebDav](https://www.nuget.org/packages/Shiny.Net.HttpServer.WebDav) | A WebDAV (RFC 4918) class 1 & 2 server over a directory — mount an app's storage in Finder, Windows Explorer or any WebDAV client, and open the same URL in a browser for a file manager with upload, rename and delete |
 | [Shiny.Net.HttpServer.Grpc](https://www.nuget.org/packages/Shiny.Net.HttpServer.Grpc) | gRPC and gRPC-Web — unary, streaming and bidirectional methods over the same HTTP/2 stack, with serialization you supply |
 | [Shiny.Net.HttpServer.Discovery](https://www.nuget.org/packages/Shiny.Net.HttpServer.Discovery) | mDNS/DNS-SD (Bonjour) — advertises the server on the local link and finds the ones other devices advertise, so nobody has to type an IP address |
-| [Shiny.Net.HttpServer.Mobile](https://www.nuget.org/packages/Shiny.Net.HttpServer.Mobile) | Mobile lifecycle on Shiny.Core — stop on background and start on resume, an Android foreground service to keep serving, rebind when the device changes network, and a check for the manifest entries that silently break local networking. iOS and Android, with or without MAUI |
+| [Shiny.Net.HttpServer.Mobile](https://www.nuget.org/packages/Shiny.Net.HttpServer.Mobile) | Mobile lifecycle on Shiny.Core — stop on background and start on resume, an Android foreground service that follows the server's own running state to keep serving, an iOS resume that restarts the server the suspension took, rebind when the device changes network, and a check for the manifest entries that silently break local networking. iOS and Android, with or without MAUI |
 | [Shiny.Net.HttpServer.Testing](https://www.nuget.org/packages/Shiny.Net.HttpServer.Testing) | An `HttpClient` wired to the server through memory — endpoint tests with no port, no listener and no socket, but the real parser, router and middleware |
 | [Shiny.Net.HttpServer.Tunnels](https://www.nuget.org/packages/Shiny.Net.HttpServer.Tunnels) | Agent-backed tunnels — supervises `cloudflared`, `ngrok` or `tailscale` and reports the public URL. Desktop, server and CLI; on a phone use the SSH provider or the relay |
 | [Shiny.Net.HttpServer.CommandLine](https://www.nuget.org/packages/Shiny.Net.HttpServer.CommandLine) | A .NET tool — `shinyhttpserver` — that serves a directory over WebDAV, so one address is both a browser file manager (browse, upload, rename, delete) and a drive Finder or Explorer can mount, with basic auth, per-operation permissions, and a QR code in the banner so a phone can scan its way in — `--tunnel` swaps the LAN address for a public pinggy.io tunnel so the phone need not be on the same network |
@@ -104,7 +104,8 @@ builder.Services.AddShinyHttpServer(
     {
         http.Options.Address = IPAddress.Any;
 
-        // Stops on background, starts on resume, rebinds when the network changes.
+        // Keeps serving in the background on Android through a foreground service; on iOS, where
+        // nothing can, restores the server on resume if it was running. Both rebind on a network change.
         http.AddHttpServerLifecycle(o => o.BackgroundMode = BackgroundServerMode.KeepAlive);
 
         // Advertises on the local link, so the other device does not need an IP address.

skills/shiny-httpserver/SKILL.md

@@ -1192,7 +1192,7 @@ services.AddShinyHttpServer(
 
         http.AddHttpServerLifecycle(o =>
         {
-            o.BackgroundMode = BackgroundServerMode.Stop;      // or KeepAlive on Android
+            o.BackgroundMode = BackgroundServerMode.Stop;      // or KeepAlive
             o.RestartOnConnectivityChange = true;              // default
         });
     },
@@ -1204,9 +1204,24 @@ Needs a Shiny host (`UseShiny()` in `MauiProgram`) — that is what delivers the
 
 - **iOS suspends the app within seconds of backgrounding**, and no background mode legitimately keeps
   a listener answering. `Stop` makes that visible: `IsRunning` goes false, the UI can say so, and
-  clients get a refused connection instead of a hang. `KeepAlive` behaves the same once suspended.
+  clients get a refused connection instead of a hang.
 - **Android `KeepAlive` starts a foreground service** with a permanent notification, which is the
   only supported way to hold a socket open in the background. That notification is the deal.
+- **iOS `KeepAlive` restores the server on resume** instead. It cannot keep the listener open, so it
+  does the other useful thing: the server is left running as the app goes away (a few seconds is
+  often enough to finish the request in flight) and is *restarted* when the app comes back. This
+  matters because the suspension takes the socket while `IsRunning` goes on saying `true`, so an app
+  that only re-checked `IsRunning` would find nothing wrong and serve nothing — and calling
+  `StartAsync()` yourself would not help either, since it is idempotent and agrees with the stale
+  state. `RestartAsync()` is what fixes it, and this does it for you.
+- **This is not `AlwaysStartOnForeground`.** A server that was off when the user left stays off; only
+  one that was running is put back. Set `AlwaysStartOnForeground = true` if you want it on at every
+  resume regardless — that overrides a toggle the user switched off, so make it a deliberate choice.
+- **Both platforms follow the server, not just the app's transitions.** On Android, stopping the
+  server while the app is backgrounded takes the notification down with it and starting it brings
+  the service up, so Android does not reclaim the process and kill the listener; on iOS the same
+  transitions decide whether the resume restores it. Nothing to call — the package tracks
+  `HttpServer.StateChanged` — so an app whose server is a toggle does not need its own bookkeeping.
 - A phone's address changes when it moves. The lifecycle package rebinds on connectivity changes;
   the core has the same thing without Shiny.Core via `options.RebindOnNetworkChange`, and raises
   `server.NetworkAddressesChanged` either way so a QR code or advertisement can be refreshed.

src/Shiny.Net.HttpServer.Mobile/HttpServerLifecycleOptions.cs

@@ -20,10 +20,24 @@ public enum BackgroundServerMode
     /// <para>
     /// On Android this starts a foreground service, which is the only supported way to keep a
     /// socket answering with the app in the background — and it means a permanent notification,
-    /// which is the deal Android offers. On iOS nothing can be done: this behaves as
-    /// <see cref="Stop"/> once the process is actually suspended, which is why the server is left
-    /// running rather than stopped — a few seconds of background execution is sometimes exactly
-    /// enough to finish the request in flight.
+    /// which is the deal Android offers.
+    /// </para>
+    /// <para>
+    /// On iOS nothing keeps the listener open, so this means the other half of the promise: the
+    /// server is left running as the app goes away — a few seconds of background execution is
+    /// sometimes exactly enough to finish the request in flight — and it is <b>restarted when the
+    /// app comes back</b>, because the suspension took the socket while leaving
+    /// <see cref="HttpServer.IsRunning"/> saying otherwise. A server that was serving when the user
+    /// switched away is serving again by the time they are looking at the app. One that was
+    /// switched off before they left stays off; this is not
+    /// <see cref="HttpServerLifecycleOptions.AlwaysStartOnForeground"/>.
+    /// </para>
+    /// <para>
+    /// Both platforms follow the server, not only the app's transitions: on Android, stop the server
+    /// while the app is backgrounded and the notification goes with it rather than claiming to serve
+    /// nothing, and start it while backgrounded and the service comes up rather than leaving the
+    /// process to be reclaimed; on iOS the same transitions decide whether the resume restores it.
+    /// Nothing to call for either.
     /// </para>
     /// </summary>
     KeepAlive,

src/Shiny.Net.HttpServer.Mobile/HttpServerLifecycleTask.cs

@@ -21,6 +21,7 @@ ILogger<HttpServerLifecycleTask> logger
 ) : ShinyLifecycleTask, IDisposable
 {
     bool stoppedByLifecycle;
+    bool restoreOnForeground;
     bool subscribed;
 
     public override void Start()
@@ -32,6 +33,10 @@ public override void Start()
             connectivity.Changed += this.OnConnectivityChanged;
             this.subscribed = true;
         }
+
+        // The foreground service follows the server, not only the app's lifecycle transitions -
+        // see OnServerStateChanged for why that difference matters.
+        server.StateChanged += this.OnServerStateChanged;
     }
 
     protected override void OnStateChanged(bool backgrounding)
@@ -67,6 +72,7 @@ async Task OnBackgroundingAsync()
 
             case BackgroundServerMode.KeepAlive when server.IsRunning:
                 this.StartBackgroundExecution();
+                this.TrackForRestore(true);
                 break;
         }
     }
@@ -75,6 +81,21 @@ async Task OnForegroundingAsync()
     {
         this.StopBackgroundExecution();
 
+        if (this.restoreOnForeground)
+        {
+            this.restoreOnForeground = false;
+
+            // Restarted, not started. The server object was never told anything happened, so it
+            // still reports Running - and StartAsync, being idempotent, would agree with it and do
+            // nothing, leaving the dead listener dead. RestartAsync unbinds and binds again, which
+            // is also the right call if the suspension took the socket but the server survived, and
+            // is harmless if it was in fact stopped underneath us.
+            logger.LogInformation("Restarting the server after the background suspension");
+
+            await server.RestartAsync().ConfigureAwait(false);
+            return;
+        }
+
         if (!this.stoppedByLifecycle && !options.AlwaysStartOnForeground)
             return;
 
@@ -87,6 +108,99 @@ async Task OnForegroundingAsync()
         this.stoppedByLifecycle = false;
     }
 
+    /// <summary>
+    /// Remembers, on a platform that cannot keep a listener answering in the background, whether the
+    /// server was running when the app went away - so the resume can put back what the suspension
+    /// took.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This is the Apple half of <see cref="BackgroundServerMode.KeepAlive"/>. Android has a
+    /// foreground service and needs none of it; iOS has nothing that will hold a socket open, so the
+    /// process is suspended, the listener stops answering, and the <see cref="HttpServer"/> object
+    /// goes on reporting <see cref="HttpServer.IsRunning"/> because nothing on the platform tells it
+    /// otherwise. Left alone, the user comes back to an app that says it is serving and a client
+    /// that cannot connect - and no amount of pressing the toggle fixes it, because the toggle is
+    /// already in the position it should be in.
+    /// </para>
+    /// <para>
+    /// Recorded rather than inferred at resume: <see cref="HttpServer.IsRunning"/> is exactly the
+    /// thing that has gone stale, so it cannot answer "was it on?". Only an explicit stop while
+    /// backgrounded clears this - see <see cref="OnServerStateChanged"/> - so a server the app or
+    /// the user switched off stays off. That restraint is exactly what
+    /// <see cref="HttpServerLifecycleOptions.AlwaysStartOnForeground"/> exists to lift, and lifting
+    /// it is a separate and more opinionated choice than restoring what was already on.
+    /// </para>
+    /// </remarks>
+    void TrackForRestore(bool running)
+    {
+        if (SupportsBackgroundExecution)
+            return;
+
+        this.restoreOnForeground = running;
+    }
+
+    /// <summary>
+    /// Keeps the background execution in step with the server itself.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Without this the foreground service is decided once, at the moment the app is backgrounded,
+    /// and never revisited - so it answers "was the server running when the user left?" rather than
+    /// "is the server running now?". Those come apart in both directions, and both are wrong in a
+    /// way the user sees:
+    /// </para>
+    /// <list type="bullet">
+    /// <item>A server stopped while the app is in the background - by a toggle in a notification
+    /// action, by the app's own code, by a rebind that failed - leaves the ongoing notification up,
+    /// holding the process alive and telling the user something is being served when nothing is.</item>
+    /// <item>A server started while the app is in the background gets no service at all, so Android
+    /// reclaims the process within minutes and the listener dies with it. The app did everything
+    /// right and the server simply stops.</item>
+    /// </list>
+    /// <para>
+    /// Only the settled states act. <see cref="HttpServerState.Starting"/> and
+    /// <see cref="HttpServerState.Stopping"/> deliberately leave it as it is: a bind that fails goes
+    /// Starting then Stopped, and acting on the first would flash a notification for a server that
+    /// never came up, while a stop waits in Stopping for in-flight requests - which is precisely
+    /// when the process still needs holding up.
+    /// </para>
+    /// </remarks>
+    void OnServerStateChanged(object? sender, HttpServerState state)
+    {
+        if (options.BackgroundMode != BackgroundServerMode.KeepAlive)
+            return;
+
+        // Only while backgrounded. Null is "no transition yet", which is treated as the foreground:
+        // of the two ways to be wrong before the app has ever been left, a missing notification is
+        // recoverable at the next transition and an unasked-for one is just wrong.
+        if (this.IsInForeground != false)
+            return;
+
+        try
+        {
+            switch (state)
+            {
+                case HttpServerState.Running:
+                    this.StartBackgroundExecution();
+                    this.TrackForRestore(true);
+                    break;
+
+                case HttpServerState.Stopped:
+                    this.StopBackgroundExecution();
+                    this.TrackForRestore(false);
+                    break;
+            }
+        }
+        catch (Exception ex)
+        {
+            // This runs inside the server's own state machine, on the thread that called Start or
+            // Stop - so an exception here would surface out of StartAsync as though the server had
+            // failed. The service is a platform concern and its failure is not the server's.
+            logger.LogWarning(ex, "Failed to update background execution for the {State} server", state);
+        }
+    }
+
     void OnConnectivityChanged(object? sender, EventArgs e) => _ = Task.Run(async () =>
     {
         try
@@ -108,6 +222,13 @@ void OnConnectivityChanged(object? sender, EventArgs e) => _ = Task.Run(async ()
         }
     });
 
+    /// <summary>
+    /// Whether the platform can actually keep the listener answering with the app in the background.
+    /// Android can, through a foreground service; Apple cannot, at any price - so the Apple build
+    /// restores the server on resume instead. Everything that differs between the two hangs off this.
+    /// </summary>
+    static partial bool SupportsBackgroundExecution { get; }
+
     /// <summary>Android starts a foreground service here; the Apple build has nothing to start.</summary>
     partial void StartBackgroundExecutionPlatform();
 
@@ -125,6 +246,8 @@ public void Dispose()
             this.subscribed = false;
         }
 
+        server.StateChanged -= this.OnServerStateChanged;
+
         GC.SuppressFinalize(this);
     }
 }

src/Shiny.Net.HttpServer.Mobile/Platforms/Android/HttpServerLifecycleTask.android.cs

@@ -4,6 +4,9 @@ namespace Shiny.Net.HttpServer.Mobile;
 
 public partial class HttpServerLifecycleTask
 {
+    /// <summary>A foreground service keeps the process and its listener alive, so nothing needs restoring on resume.</summary>
+    static partial bool SupportsBackgroundExecution => true;
+
     partial void StartBackgroundExecutionPlatform()
     {
         if (HttpServerForegroundService.IsStarted)

src/Shiny.Net.HttpServer.Mobile/Platforms/Apple/HttpServerLifecycleTask.apple.cs

@@ -2,6 +2,17 @@ namespace Shiny.Net.HttpServer.Mobile;
 
 public partial class HttpServerLifecycleTask
 {
+    /// <summary>
+    /// No, and there is no version of iOS where the answer changes.
+    /// <para>
+    /// So <see cref="BackgroundServerMode.KeepAlive"/> means something different here than it does
+    /// on Android: not "keep it running", which is not on offer, but "put it back on resume". The
+    /// server that was serving when the user switched away is serving again by the time they are
+    /// looking at the app, without the app having to notice the suspension or hold the flag itself.
+    /// </para>
+    /// </summary>
+    static partial bool SupportsBackgroundExecution => false;
+
     /// <summary>
     /// Nothing to start.
     /// <para>

version.json

@@ -1,6 +1,6 @@
 {
     "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "assemblyVersion": {
         "precision": "revision"
     },