Structured Komodo port diagnostics + probe button

komodoResolveGamePort silently returned null for six distinct failure
modes (unconfigured, no-name, unreachable, http-error, unparseable,
no-udp-in-response), which made "no game_port — Komodo did not return
one" indistinguishable from an auth failure or an unrecognized response
shape. Adds komodoResolvePortDetailed returning a discriminated union
with the failure reason, HTTP status, and a truncated response snippet.

extractUdpPort broadens to cover four more shapes seen in the wild:
extra host-port field names (HostPort/hostPort/host_port/PublicPort),
`type` as a protocol alias, host-network strings ("28962/udp"), and the
docker-inspect container-keyed form ({ "28960/udp": [{ HostPort }] }).
Arrays reached via a ports-flavored key now win over accidental matches
elsewhere in the tree.

New POST /api/servers/[name]/probe-komodo triggers a fresh lookup,
caches the port on success, and returns the structured result. The RCON
diagnostic panel gains a Probe Komodo button (shown when endpoint is
unresolved and Komodo is configured) that renders the snippet inline —
so unrecognized shapes surface directly instead of vanishing.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

src/lib/server/integrations/komodo.ts

@@ -80,19 +80,63 @@ export async function komodoRestart(serverName: string): Promise<KomodoRestartRe
     return { ok: true };
 }
 
+// ---------- Port resolution ----------
+
+export type KomodoPortFailure =
+    | 'unconfigured'
+    | 'no-name'
+    | 'unreachable'          // network / DNS / timeout
+    | 'http-error'           // non-2xx
+    | 'unparseable'          // 2xx but body wasn't JSON
+    | 'no-udp-in-response';  // parsed but no UDP port found
+
+export interface KomodoPortSuccess {
+    ok: true;
+    port: number;
+    snippet: string;
+}
+export interface KomodoPortFailureResult {
+    ok: false;
+    reason: KomodoPortFailure;
+    detail: string;
+    httpStatus?: number;
+    snippet?: string;
+}
+export type KomodoPortResult = KomodoPortSuccess | KomodoPortFailureResult;
+
+const SNIPPET_LIMIT = 4000;
+
+function truncate(s: string): string {
+    if (s.length <= SNIPPET_LIMIT) return s;
+    return s.slice(0, SNIPPET_LIMIT) + `\n… (${s.length - SNIPPET_LIMIT} more bytes)`;
+}
+
+function safeJsonStringify(value: unknown): string {
+    try {
+        return JSON.stringify(value, null, 2);
+    } catch {
+        return String(value);
+    }
+}
+
 /**
- * Query Komodo's read API for a server's UDP game port. Called lazily by
+ * Detailed variant of `komodoResolveGamePort` — returns a discriminated
- * the RCON client and cached into `servers.game_port` on success.
+ * union so callers can distinguish "network died" from "auth failed" from
+ * "we parsed the JSON but couldn't find a UDP port in a shape we recognize".
  *
- * Komodo returns full deployment/container state; port mappings live under
+ * On success, the response snippet is included so the caller can render it
- * `state.container.ports` on deployments and `state.ports` on stacks/raw
+ * as "here's where we found the port". On no-udp-in-response, the snippet
- * containers. Shape varies by Komodo version, so we walk a few known
+ * is the only way we'll know what shape Komodo actually emitted — surface
- * candidate paths and pick the first UDP entry we can parse.
+ * it prominently in the UI so we can extend `extractUdpPort` for that shape.
  */
-export async function komodoResolveGamePort(serverName: string): Promise<number | null> {
+export async function komodoResolvePortDetailed(serverName: string): Promise<KomodoPortResult> {
-    if (!komodoConfigured()) return null;
+    if (!komodoConfigured()) {
+        return { ok: false, reason: 'unconfigured', detail: 'KOMODO_ADDRESS/KEY/SECRET are not all set' };
+    }
     const row = getServer(serverName);
-    if (!row?.komodo_name) return null;
+    if (!row?.komodo_name) {
+        return { ok: false, reason: 'no-name', detail: `server has no komodo_name: ${serverName}` };
+    }
 
     const type = row.komodo_type ?? 'deployment';
     let path: string;
@@ -104,7 +148,9 @@ export async function komodoResolveGamePort(serverName: string): Promise<number
             body = { stack: row.komodo_name };
             break;
         case 'container':
-            if (!row.komodo_server) return null;
+            if (!row.komodo_server) {
+                return { ok: false, reason: 'no-name', detail: 'container type needs komodo_server' };
+            }
             path = 'read/InspectContainer';
             body = { server: row.komodo_server, container: row.komodo_name };
             break;
@@ -118,64 +164,164 @@ export async function komodoResolveGamePort(serverName: string): Promise<number
     let res: Response;
     try {
         res = await komodoCall(path, body);
-    } catch {
+    } catch (err) {
-        return null;
+        return { ok: false, reason: 'unreachable', detail: (err as Error).message };
+    }
+
+    // Read the body up front — we want the snippet even on non-2xx so the
+    // UI can show what the error page actually said.
+    const rawText = await res.text().catch(() => '');
+
+    if (!res.ok) {
+        return {
+            ok: false,
+            reason: 'http-error',
+            detail: `HTTP ${res.status} ${res.statusText || ''}`.trim(),
+            httpStatus: res.status,
+            snippet: truncate(rawText)
+        };
     }
-    if (!res.ok) return null;
 
     let json: unknown;
     try {
-        json = await res.json();
+        json = JSON.parse(rawText);
-    } catch {
+    } catch (err) {
-        return null;
+        return {
+            ok: false,
+            reason: 'unparseable',
+            detail: `response body is not JSON: ${(err as Error).message}`,
+            httpStatus: res.status,
+            snippet: truncate(rawText)
+        };
     }
-    return extractUdpPort(json);
+
+    const port = extractUdpPort(json);
+    const snippet = truncate(safeJsonStringify(json));
+    if (port === null) {
+        return {
+            ok: false,
+            reason: 'no-udp-in-response',
+            detail: 'parsed the response but no UDP port matched any known shape',
+            httpStatus: res.status,
+            snippet
+        };
+    }
+    return { ok: true, port, snippet };
 }
 
 /**
- * Walks a Komodo response looking for a UDP port. Handles the two shapes
+ * Query Komodo's read API for a server's UDP game port. Called lazily by
- * we've seen in the wild:
+ * the RCON client and cached into `servers.game_port` on success. Thin shim
+ * over `komodoResolvePortDetailed` that swallows diagnostics — use the
+ * detailed variant when you care why it failed.
+ */
+export async function komodoResolveGamePort(serverName: string): Promise<number | null> {
+    const result = await komodoResolvePortDetailed(serverName);
+    return result.ok ? result.port : null;
+}
+
+// ---------- Extractor ----------
+
+// Property names Komodo/Docker use for the collection of port mappings.
+const PORT_ARRAY_KEYS = new Set(['ports', 'Ports', 'port_bindings', 'PortBindings']);
+// Value field names for the host-facing port on an object entry.
+const HOST_PORT_KEYS = ['published', 'PublishedPort', 'public_port', 'PublicPort', 'HostPort', 'hostPort', 'host_port'];
+
+interface PortsCandidate {
+    arr: unknown[];
+    /** True when the array was reached via a `ports`-flavored key — preferred. */
+    preferred: boolean;
+}
+
+/**
+ * Walks a Komodo response looking for a UDP port. Handles the shapes we've
+ * seen in the wild:
  *
- *   docker-compose-style: [{ protocol: "udp", published: 4976, target: 28960 }, ...]
+ *   docker-compose object:  [{ protocol: "udp", published: 4976, target: 28960 }]
- *   docker-run-style:     ["4976:28960/udp", "3074:3074/tcp"]
+ *   docker-compose caps:    [{ Protocol: "udp", PublishedPort: 4976 }]
+ *   docker-run string:      ["4976:28960/udp", "3074:3074/tcp"]
+ *   host-network string:    ["28962/udp"]
+ *   docker-inspect object:  { "28960/udp": [{ "HostIp": "0.0.0.0", "HostPort": "28962" }] }
  *
- * Returns the first published port whose protocol is UDP.
+ * Arrays reached via a `ports`/`Ports`/`port_bindings`/`PortBindings` key
+ * are preferred over arrays discovered elsewhere in the tree, so an
+ * unrelated array (e.g. tags, labels) can't shadow a real port list.
  */
 export function extractUdpPort(payload: unknown): number | null {
-    const candidates: unknown[] = [];
+    const candidates: PortsCandidate[] = [];
+    // Objects whose keys encode `<container-port>/<proto>` — a la docker inspect.
+    const containerKeyed: Record<string, unknown>[] = [];
     const seen = new Set<unknown>();
-    const walk = (v: unknown): void => {
+
+    const walk = (v: unknown, viaPortsKey: boolean): void => {
         if (v === null || typeof v !== 'object' || seen.has(v)) return;
         seen.add(v);
         if (Array.isArray(v)) {
-            for (const item of v) walk(item);
+            for (const item of v) walk(item, false);
-            candidates.push(v);
+            candidates.push({ arr: v, preferred: viaPortsKey });
-        } else {
+            return;
-            for (const val of Object.values(v as Record<string, unknown>)) walk(val);
+        }
+        const obj = v as Record<string, unknown>;
+        // Detect docker-inspect container-keyed objects: any key like `28960/udp`.
+        for (const k of Object.keys(obj)) {
+            if (/^\d+\/(udp|tcp)$/i.test(k)) {
+                containerKeyed.push(obj);
+                break;
+            }
+        }
+        for (const [key, val] of Object.entries(obj)) {
+            walk(val, PORT_ARRAY_KEYS.has(key));
         }
     };
-    walk(payload);
+    walk(payload, false);
 
-    // Object-form entries: { protocol, published, target }
+    // Sort so preferred `ports`-keyed arrays win over accidental hits.
-    for (const arr of candidates) {
+    candidates.sort((a, b) => (a.preferred === b.preferred ? 0 : a.preferred ? -1 : 1));
-        for (const entry of arr as unknown[]) {
+
+    // Try object-entry shape first — most Komodo/Docker responses use this.
+    for (const { arr } of candidates) {
+        for (const entry of arr) {
             if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
                 const e = entry as Record<string, unknown>;
-                const proto = String(e.protocol ?? e.Protocol ?? '').toLowerCase();
+                const proto = String(e.protocol ?? e.Protocol ?? e.type ?? e.Type ?? '').toLowerCase();
                 if (proto !== 'udp') continue;
-                const raw = e.published ?? e.PublishedPort ?? e.public_port ?? e.HostPort ?? e.host_port;
+                for (const field of HOST_PORT_KEYS) {
+                    const raw = e[field];
+                    if (raw === undefined || raw === null) continue;
                     const num = typeof raw === 'string' ? Number.parseInt(raw, 10) : Number(raw);
                     if (Number.isFinite(num) && num > 0) return num;
                 }
             }
         }
+    }
 
-    // String-form entries: "4976:28960/udp"
+    // Then string shapes: "host:container/udp" or "container/udp" (host-net).
-    for (const arr of candidates) {
+    for (const { arr } of candidates) {
-        for (const entry of arr as unknown[]) {
+        for (const entry of arr) {
             if (typeof entry !== 'string') continue;
-            const m = /^(\d+):\d+\/udp$/i.exec(entry);
+            const hostMapped = /^(\d+):\d+\/udp$/i.exec(entry);
-            if (m) return Number.parseInt(m[1], 10);
+            if (hostMapped) return Number.parseInt(hostMapped[1], 10);
+            const hostNet = /^(\d+)\/udp$/i.exec(entry);
+            if (hostNet) return Number.parseInt(hostNet[1], 10);
+        }
+    }
+
+    // Finally, docker-inspect container-keyed shape:
+    //   { "28960/udp": [{ HostIp, HostPort }] }
+    for (const obj of containerKeyed) {
+        for (const [key, val] of Object.entries(obj)) {
+            if (!/^\d+\/udp$/i.test(key)) continue;
+            if (!Array.isArray(val)) continue;
+            for (const binding of val) {
+                if (!binding || typeof binding !== 'object') continue;
+                const b = binding as Record<string, unknown>;
+                for (const field of HOST_PORT_KEYS) {
+                    const raw = b[field];
+                    if (raw === undefined || raw === null) continue;
+                    const num = typeof raw === 'string' ? Number.parseInt(raw, 10) : Number(raw);
+                    if (Number.isFinite(num) && num > 0) return num;
+                }
+            }
         }
     }
 

src/lib/ui/komodoError.ts

@@ -0,0 +1,27 @@
+export type KomodoPortFailure =
+    | 'unconfigured'
+    | 'no-name'
+    | 'unreachable'
+    | 'http-error'
+    | 'unparseable'
+    | 'no-udp-in-response';
+
+/** Short fix hint per failure reason, shown under the Komodo probe result. */
+export function komodoFixHint(reason: KomodoPortFailure, httpStatus?: number): string {
+    switch (reason) {
+        case 'unconfigured':
+            return 'Set KOMODO_ADDRESS, KOMODO_API_KEY, and KOMODO_API_SECRET in the container env.';
+        case 'no-name':
+            return 'This server row has no komodo_name — set it via SQL or via the fleet config.';
+        case 'unreachable':
+            return 'Network, DNS, or timeout. Check that KOMODO_ADDRESS is reachable from this container.';
+        case 'http-error':
+            if (httpStatus === 401 || httpStatus === 403) return 'Auth rejected — verify KOMODO_API_KEY and KOMODO_API_SECRET.';
+            if (httpStatus === 404) return 'Endpoint or deployment not found — check komodo_name matches the Komodo UI exactly.';
+            return `Komodo returned ${httpStatus ?? 'an error'}. Check the endpoint path and credentials.`;
+        case 'unparseable':
+            return 'Response was not JSON — is KOMODO_ADDRESS pointing at the Core API (not the Periphery)?';
+        case 'no-udp-in-response':
+            return 'Parsed the response but no UDP port matched our known shapes. See the snippet below and extend extractUdpPort.';
+    }
+}

src/routes/api/servers/[name]/probe-komodo/+server.ts

@@ -0,0 +1,27 @@
+import { json } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { komodoResolvePortDetailed } from '$lib/server/integrations/komodo.js';
+import { getServer, setServerField } from '$lib/server/fleet/servers.js';
+
+/**
+ * Trigger a fresh Komodo GetDeployment lookup for a specific server and
+ * return the structured result — including a snippet of the response so
+ * the UI can render "here's where we found the port" (or "here's what
+ * Komodo returned; extend extractUdpPort for this shape").
+ *
+ * On success, the resolved port is written to servers.game_port so the
+ * next RCON attempt uses it without waiting for another sweep tick.
+ */
+export const POST: RequestHandler = async ({ params }) => {
+    const name = params.name;
+    if (!name) return json({ ok: false, reason: 'no-name', detail: 'missing server name' }, { status: 400 });
+
+    const row = getServer(name);
+    if (!row) return json({ ok: false, reason: 'no-name', detail: `unknown server: ${name}` }, { status: 404 });
+
+    const result = await komodoResolvePortDetailed(name);
+    if (result.ok) {
+        setServerField(name, 'game_port', result.port);
+    }
+    return json(result);
+};

src/routes/servers/[name]/+page.svelte

@@ -7,6 +7,16 @@
     import PlayerRoster from '$ui/components/PlayerRoster.svelte';
     import { gametypeLabel } from '$ui/gametype.js';
     import { decodeRconError, rconFixHint } from '$ui/rconError.js';
+    import { komodoFixHint, type KomodoPortFailure } from '$ui/komodoError.js';
+
+    interface KomodoProbeResult {
+        ok: boolean;
+        port?: number;
+        reason?: KomodoPortFailure;
+        detail?: string;
+        httpStatus?: number;
+        snippet?: string;
+    }
 
     interface Server {
         name: string;
@@ -81,6 +91,37 @@
         if (!ep) return 'unresolved';
         return `${ep.host}:${ep.port}`;
     }
+
+    let komodoProbe = $state<KomodoProbeResult | null>(null);
+    let probing = $state(false);
+
+    async function probeKomodo(): Promise<void> {
+        if (probing || !name) return;
+        probing = true;
+        komodoProbe = null;
+        try {
+            const res = await fetch(`/api/servers/${encodeURIComponent(name)}/probe-komodo`, {
+                method: 'POST'
+            });
+            komodoProbe = (await res.json()) as KomodoProbeResult;
+            // On success, refresh the server row so the endpoint field
+            // updates from `unresolved` to `host:port` without a full reload.
+            if (komodoProbe.ok && server) {
+                const srvRes = await fetch('/api/servers');
+                const srvBody = (await srvRes.json()) as { servers: Server[]; integrations: Integrations };
+                server = srvBody.servers.find((s) => s.name === name) ?? server;
+                integrations = srvBody.integrations;
+            }
+        } catch (err) {
+            komodoProbe = {
+                ok: false,
+                reason: 'unreachable',
+                detail: (err as Error).message
+            };
+        } finally {
+            probing = false;
+        }
+    }
 </script>
 
 {#if server}
@@ -139,6 +180,46 @@
                     <span class="reason-detail">{effectiveErr}</span>
                 </div>
             {/if}
+
+            {#if !effectiveEndpoint && integrations.komodo}
+                <div class="probe-row">
+                    <button class="probe-btn" onclick={probeKomodo} disabled={probing}>
+                        {probing ? 'probing komodo…' : 'probe komodo'}
+                    </button>
+                    <span class="probe-hint">Ask Komodo for this server's UDP port now.</span>
+                </div>
+            {/if}
+
+            {#if komodoProbe}
+                {#if komodoProbe.ok}
+                    <div class="probe-result probe-ok">
+                        <span class="probe-tag ok">resolved</span>
+                        <span class="probe-detail">
+                            Port <strong>{komodoProbe.port}</strong> cached to server row — RCON will retry on the next tick.
+                        </span>
+                    </div>
+                    {#if komodoProbe.snippet}
+                        <details class="snippet-details">
+                            <summary>show response snippet</summary>
+                            <pre class="snippet">{komodoProbe.snippet}</pre>
+                        </details>
+                    {/if}
+                {:else}
+                    <div class="probe-result probe-bad">
+                        <span class="probe-tag bad">{komodoProbe.reason}</span>
+                        <span class="probe-detail">
+                            {komodoProbe.detail}
+                            {#if komodoProbe.httpStatus} · HTTP {komodoProbe.httpStatus}{/if}
+                        </span>
+                    </div>
+                    {#if komodoProbe.reason}
+                        <div class="hint">{komodoFixHint(komodoProbe.reason, komodoProbe.httpStatus)}</div>
+                    {/if}
+                    {#if komodoProbe.snippet}
+                        <pre class="snippet">{komodoProbe.snippet}</pre>
+                    {/if}
+                {/if}
+            {/if}
         </section>
     {/if}
 
@@ -350,6 +431,107 @@
         border-radius: var(--r-sm);
     }
 
+    .probe-row {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        margin-top: 14px;
+    }
+    .probe-btn {
+        background: var(--cherry-875);
+        color: var(--cream);
+        border: 1px solid var(--spark-500);
+        border-radius: var(--r-sm);
+        padding: 7px 14px;
+        font-family: var(--font-body);
+        font-size: 12px;
+        font-weight: 600;
+        letter-spacing: 0.3px;
+        cursor: pointer;
+        transition: box-shadow 0.15s, background 0.15s;
+    }
+    .probe-btn:hover:not(:disabled) {
+        box-shadow: var(--spark-glow);
+        background: var(--cherry-825);
+    }
+    .probe-btn:disabled { opacity: 0.5; cursor: default; }
+    .probe-hint {
+        color: var(--ink-500);
+        font-family: var(--font-mono);
+        font-size: 11px;
+    }
+
+    .probe-result {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+        margin-top: 12px;
+        padding: 10px 14px;
+        border-radius: var(--r-sm);
+        border: 1px solid transparent;
+    }
+    .probe-ok {
+        background: rgba(34, 224, 255, 0.08);
+        border-color: rgba(34, 224, 255, 0.3);
+    }
+    .probe-bad {
+        background: rgba(255, 48, 80, 0.08);
+        border-color: rgba(255, 48, 80, 0.25);
+    }
+    .probe-tag {
+        padding: 2px 8px;
+        border-radius: var(--r-sm);
+        font-family: var(--font-mono);
+        font-size: 10px;
+        text-transform: uppercase;
+        letter-spacing: 1px;
+        border: 1px solid transparent;
+        flex-shrink: 0;
+    }
+    .probe-tag.ok {
+        background: rgba(34, 224, 255, 0.15);
+        border-color: rgba(34, 224, 255, 0.4);
+        color: var(--spark-500);
+    }
+    .probe-tag.bad {
+        background: rgba(255, 48, 80, 0.15);
+        border-color: rgba(255, 48, 80, 0.4);
+        color: var(--danger-500);
+    }
+    .probe-detail {
+        color: var(--ink-100);
+        font-family: var(--font-mono);
+        font-size: 12px;
+    }
+    .probe-detail strong { color: var(--spark-500); }
+
+    .snippet-details {
+        margin-top: 10px;
+        font-family: var(--font-mono);
+        font-size: 11px;
+    }
+    .snippet-details summary {
+        color: var(--ink-500);
+        cursor: pointer;
+        padding: 4px 0;
+    }
+    .snippet-details summary:hover { color: var(--ink-100); }
+    .snippet {
+        margin: 10px 0 0;
+        padding: 12px 14px;
+        background: var(--cherry-975);
+        border: 1px solid var(--cherry-700);
+        border-radius: var(--r-sm);
+        color: var(--ink-300);
+        font-family: var(--font-mono);
+        font-size: 11px;
+        line-height: 1.5;
+        max-height: 400px;
+        overflow: auto;
+        white-space: pre-wrap;
+        word-break: break-all;
+    }
+
     .row {
         display: grid;
         grid-template-columns: 200px 160px 100px 120px 1fr;

tests/unit/komodo.test.ts

@@ -45,4 +45,51 @@ describe('extractUdpPort', () => {
         cyc.self = cyc;
         expect(extractUdpPort(cyc)).toBeNull();
     });
+
+    it('recognizes HostPort / hostPort / host_port on object entries', () => {
+        expect(extractUdpPort({ ports: [{ protocol: 'udp', HostPort: 28962 }] })).toBe(28962);
+        expect(extractUdpPort({ ports: [{ protocol: 'udp', hostPort: 28963 }] })).toBe(28963);
+        expect(extractUdpPort({ ports: [{ protocol: 'udp', host_port: 28964 }] })).toBe(28964);
+    });
+
+    it('recognizes `type` alongside `protocol` as the protocol field', () => {
+        expect(extractUdpPort({ ports: [{ type: 'UDP', published: 28965 }] })).toBe(28965);
+    });
+
+    it('parses host-network "container/udp" strings', () => {
+        expect(extractUdpPort({ ports: ['28966/udp'] })).toBe(28966);
+    });
+
+    it('handles docker-inspect container-keyed PortBindings shape', () => {
+        const payload = {
+            NetworkSettings: {
+                Ports: {
+                    '28960/udp': [{ HostIp: '0.0.0.0', HostPort: '28967' }],
+                    '3074/tcp': [{ HostIp: '0.0.0.0', HostPort: '3074' }]
+                }
+            }
+        };
+        expect(extractUdpPort(payload)).toBe(28967);
+    });
+
+    it('prefers `ports`-keyed arrays over unrelated arrays discovered deeper', () => {
+        // The unrelated array happens to contain a matching entry — the walker
+        // must still prefer the real `ports` list.
+        const payload = {
+            labels: [{ protocol: 'udp', published: 9999 }],
+            state: { container: { ports: [{ protocol: 'udp', published: 28968 }] } }
+        };
+        expect(extractUdpPort(payload)).toBe(28968);
+    });
+});
+
+describe('komodoResolvePortDetailed', () => {
+    it('is importable and has the discriminated-union shape at the type level', async () => {
+        // Runtime import shim just to prove it's exported. Behavior is
+        // covered by the fixture-based extractUdpPort tests above plus manual
+        // end-to-end verification against a live Komodo.
+        const mod = await import('../../src/lib/server/integrations/komodo.js');
+        expect(typeof mod.komodoResolvePortDetailed).toBe('function');
+        expect(typeof mod.komodoResolveGamePort).toBe('function');
+    });
 });