nullgate 1.2.5__tar.gz → 1.2.7__tar.gz

{nullgate-1.2.5/src/nullgate.egg-info → nullgate-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nullgate
-Version: 1.2.5
+Version: 1.2.7
 Summary: Disposable SSH gateway into confined directory workspaces
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -110,6 +110,8 @@ Options:
 - `--no-restrict-file-transfer`: Allow host-visible file transfers.
 - `--foreground`: Stay in the foreground and supervise gateway and transport instead of exiting after readiness. The parent handles SIGINT and SIGTERM and stops both children, exiting nonzero with recent log tails if either child dies.
 - `--json`: Emit machine-readable JSON on stdout (the only stdout in JSON mode). `start --foreground --json` prints one readiness object, flushes it, then supervises.
+- `--replace-stale`: Replace tracked gateway and transport processes when they are not healthy. Healthy srv.us sessions are reused.
+- `--rendezvous-url URL`: After srv.us passes its public SSH-over-TLS check, POST a minimal readiness document. Defaults to `NULLGATE_RENDEZVOUS_URL` and is saved for `restart`; the URL is never printed.
 
 A fresh `start` uses documented defaults and the current directory when no
 workspace is given; only `restart` reuses saved workspace, provider, port,
@@ -210,6 +212,7 @@ Unknown flags fail normally; only the hidden external-launcher flags
 | `NULLGATE_TUNNEL_PORT` | Port for srv.us ingress (default: `22`) |
 | `NULLGATE_CLOUDFLARED_TOKEN` | Credential token for `cloudflared` tunnels |
 | `NULLGATE_CONFINE_SFTP` | Set to `1` to confine SFTP and SCP transfers to the workspace root |
+| `NULLGATE_RENDEZVOUS_URL` | HTTP endpoint for publishing successful srv.us readiness; may contain a secret token and is never printed |
 | `NULLGATE_VERSION` | Install a specific published version instead of the stable release; accepts `1.0.1` or `v1.0.1` |
 | `NULLGATE_DIST_URL` | Override the public release channel used by `install.sh` |
 | `NULLGATE_INSTALL_URL` | Override the installer URL used by `nullgate upgrade` |
@@ -222,7 +225,7 @@ Unknown flags fail normally; only the hidden external-launcher flags
   secure mode without authorized keys fails immediately instead of hanging.
 - Readiness is decisive: `start` returns success only after the gateway
   listens, the transport stays alive, and (for srv.us) a hostname is
-  announced. On timeout or failure both processes are stopped, recent
+  announced and serves an SSH banner over certificate-validated TLS. On timeout or failure both processes are stopped, recent
   transport logs go to stderr, and the exit code is nonzero.
 - `start --foreground` keeps the parent alive supervising both children,
   handles SIGINT/SIGTERM by stopping them, and exits nonzero with recent log tails if
@@ -230,7 +233,7 @@ Unknown flags fail normally; only the hidden external-launcher flags
 - `start`, `status`, and `connect` accept `--json` for machine-readable
   output. JSON is the only stdout in JSON mode and carries the operational
   fields agents need: version, provider, running state and PIDs, port,
-  workspace, URL, host, user, proxy command, auth mode, TCP forwarding, and
+  workspace, URL, host, user, proxy command, public health, auth mode, TCP forwarding, and
   file-transfer mode. `--json` is the stable agent contract; human output may
   change. `start --foreground --json` prints one readiness object,
   flushes it, then supervises.

{nullgate-1.2.5 → nullgate-1.2.7}/README.md

@@ -98,6 +98,8 @@ Options:
 - `--no-restrict-file-transfer`: Allow host-visible file transfers.
 - `--foreground`: Stay in the foreground and supervise gateway and transport instead of exiting after readiness. The parent handles SIGINT and SIGTERM and stops both children, exiting nonzero with recent log tails if either child dies.
 - `--json`: Emit machine-readable JSON on stdout (the only stdout in JSON mode). `start --foreground --json` prints one readiness object, flushes it, then supervises.
+- `--replace-stale`: Replace tracked gateway and transport processes when they are not healthy. Healthy srv.us sessions are reused.
+- `--rendezvous-url URL`: After srv.us passes its public SSH-over-TLS check, POST a minimal readiness document. Defaults to `NULLGATE_RENDEZVOUS_URL` and is saved for `restart`; the URL is never printed.
 
 A fresh `start` uses documented defaults and the current directory when no
 workspace is given; only `restart` reuses saved workspace, provider, port,
@@ -198,6 +200,7 @@ Unknown flags fail normally; only the hidden external-launcher flags
 | `NULLGATE_TUNNEL_PORT` | Port for srv.us ingress (default: `22`) |
 | `NULLGATE_CLOUDFLARED_TOKEN` | Credential token for `cloudflared` tunnels |
 | `NULLGATE_CONFINE_SFTP` | Set to `1` to confine SFTP and SCP transfers to the workspace root |
+| `NULLGATE_RENDEZVOUS_URL` | HTTP endpoint for publishing successful srv.us readiness; may contain a secret token and is never printed |
 | `NULLGATE_VERSION` | Install a specific published version instead of the stable release; accepts `1.0.1` or `v1.0.1` |
 | `NULLGATE_DIST_URL` | Override the public release channel used by `install.sh` |
 | `NULLGATE_INSTALL_URL` | Override the installer URL used by `nullgate upgrade` |
@@ -210,7 +213,7 @@ Unknown flags fail normally; only the hidden external-launcher flags
   secure mode without authorized keys fails immediately instead of hanging.
 - Readiness is decisive: `start` returns success only after the gateway
   listens, the transport stays alive, and (for srv.us) a hostname is
-  announced. On timeout or failure both processes are stopped, recent
+  announced and serves an SSH banner over certificate-validated TLS. On timeout or failure both processes are stopped, recent
   transport logs go to stderr, and the exit code is nonzero.
 - `start --foreground` keeps the parent alive supervising both children,
   handles SIGINT/SIGTERM by stopping them, and exits nonzero with recent log tails if
@@ -218,7 +221,7 @@ Unknown flags fail normally; only the hidden external-launcher flags
 - `start`, `status`, and `connect` accept `--json` for machine-readable
   output. JSON is the only stdout in JSON mode and carries the operational
   fields agents need: version, provider, running state and PIDs, port,
-  workspace, URL, host, user, proxy command, auth mode, TCP forwarding, and
+  workspace, URL, host, user, proxy command, public health, auth mode, TCP forwarding, and
   file-transfer mode. `--json` is the stable agent contract; human output may
   change. `start --foreground --json` prints one readiness object,
   flushes it, then supervises.

nullgate-1.2.7/src/nullgate/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.2.7"

{nullgate-1.2.5 → nullgate-1.2.7}/src/nullgate/commands.py

@@ -188,6 +188,17 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Emit machine-readable JSON on stdout.",
     )
+    start_parser.add_argument(
+        "--replace-stale",
+        action="store_true",
+        help="Replace tracked processes when they are not publicly healthy.",
+    )
+    start_parser.add_argument(
+        "--rendezvous-url",
+        metavar="URL",
+        default=None,
+        help="Publish srv.us readiness to an HTTP endpoint.",
+    )
     start_parser.add_argument(
         "--notte-api", dest="notte_api", action="store_true", help=argparse.SUPPRESS
     )

{nullgate-1.2.5 → nullgate-1.2.7}/src/nullgate/ingress.py

@@ -2,9 +2,11 @@
 """srv.us reverse tunnel for the Nullgate srvus transport.
 
 Holds one AsyncSSH connection to srv.us with a remote port forward pointing back
-at the local SSH server. AsyncSSH is already required by the server, so speaking
-SSH in-process here removes the OpenSSH client and ssh-keygen from the host's
-requirements; the tunnel then works on stripped images that ship neither.
+at the local SSH server, reconnecting with backoff whenever the server drops it
+(srv.us documents wrapping the tunnel in a reconnect loop). AsyncSSH is already
+required by the server, so speaking SSH in-process here removes the OpenSSH
+client and ssh-keygen from the host's requirements; the tunnel then works on
+stripped images that ship neither.
 
 Launch with asyncssh available, e.g.:
   python -m nullgate.ingress --local-port 4822 --slot 1
@@ -30,6 +32,9 @@ from nullgate.account import current_username, ensure_username_environment
 
 IDENTITY_SEED_ENV = "NULLGATE_IDENTITY_SEED"
 
+RECONNECT_MIN = 1.0
+RECONNECT_MAX = 30.0
+
 
 class TunnelClient(asyncssh.SSHClient):
     """Surface srv.us protocol messages in the tunnel log.
@@ -96,37 +101,19 @@ async def pump(reader: asyncssh.SSHReader, writer) -> None:
         writer.flush()
 
 
-async def run(
-    host: str,
-    port: int,
+async def serve_connection(
+    connection: asyncssh.SSHClientConnection,
     local_host: str,
     local_port: int,
     slot: int,
-    key: Path,
-    username: str,
-) -> int:
-    ensure_username_environment(username)
-    ensure_key(key)
-
-    stopped = asyncio.Event()
-    loop = asyncio.get_running_loop()
-    for signum in (signal.SIGINT, signal.SIGTERM):
-        with contextlib.suppress(NotImplementedError):
-            loop.add_signal_handler(signum, stopped.set)
-
-    # known_hosts=None matches the connection commands this project prints: the
-    # ingress is disposable and only carries bytes, so it is not authenticated.
-    connection = await asyncssh.connect(
-        host,
-        port=port,
-        username=username,
-        client_keys=[str(key)],
-        known_hosts=None,
-        client_factory=TunnelClient,
-        keepalive_interval=30,
-        keepalive_count_max=3,
-    )
+    stopped: asyncio.Event,
+) -> bool:
+    """Hold one tunnel connection until it closes or a stop is requested.
 
+    Opens the session channel and the remote port forward, then waits. Returns
+    True when ``stopped`` was set (clean shutdown), False when the server
+    dropped the connection and the caller should reconnect.
+    """
     process = None
     listener = None
     tasks: list[asyncio.Task] = []
@@ -156,9 +143,9 @@ async def run(
         tasks.extend((closed, requested))
         await asyncio.wait((closed, requested), return_when=asyncio.FIRST_COMPLETED)
         if requested.done():
-            return 0
+            return True
         print("nullgate-ingress: connection closed by the server", flush=True)
-        return 1
+        return False
     finally:
         if listener is not None:
             listener.close()
@@ -172,6 +159,74 @@ async def run(
             await asyncio.gather(*tasks, return_exceptions=True)
 
 
+async def backoff(stopped: asyncio.Event, delay: float) -> None:
+    """Wait out a reconnect delay, returning early on a requested stop."""
+    with contextlib.suppress(asyncio.TimeoutError):
+        await asyncio.wait_for(stopped.wait(), timeout=delay)
+
+
+async def run(
+    host: str,
+    port: int,
+    local_host: str,
+    local_port: int,
+    slot: int,
+    key: Path,
+    username: str,
+) -> int:
+    ensure_username_environment(username)
+    ensure_key(key)
+
+    stopped = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for signum in (signal.SIGINT, signal.SIGTERM):
+        with contextlib.suppress(NotImplementedError):
+            loop.add_signal_handler(signum, stopped.set)
+
+    # Retry forever: srv.us documents wrapping the tunnel in a reconnect loop,
+    # and a disposable gateway must survive transient server-side flaps.
+    delay = RECONNECT_MIN
+    attempt = 0
+    while not stopped.is_set():
+        try:
+            # known_hosts=None matches the connection commands this project
+            # prints: the ingress is disposable and only carries bytes, so it
+            # is not authenticated.
+            connection = await asyncssh.connect(
+                host,
+                port=port,
+                username=username,
+                client_keys=[str(key)],
+                known_hosts=None,
+                client_factory=TunnelClient,
+                keepalive_interval=30,
+                keepalive_count_max=3,
+            )
+            if attempt:
+                print("nullgate-ingress: reconnected", flush=True)
+                attempt = 0
+                delay = RECONNECT_MIN
+            clean = await serve_connection(
+                connection, local_host, local_port, slot, stopped
+            )
+        except (OSError, asyncssh.Error) as error:
+            print(f"nullgate-ingress: {error}", flush=True)
+            clean = False
+        if clean:
+            return 0
+        attempt += 1
+        if stopped.is_set():
+            break
+        delay = min(delay, RECONNECT_MAX)
+        print(
+            f"nullgate-ingress: reconnecting in {delay:g}s (attempt {attempt})",
+            flush=True,
+        )
+        await backoff(stopped, delay)
+        delay *= 2
+    return 0
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--host", default="srv.us", help="tunnel host")