@huaqiu/dsh-tool-plugin-update 0.6.1 → 0.6.2

package/src/routes.ts

@@ -17,6 +17,21 @@
  *   POST /plugin-update/ignore   → POST /api/v1/plugin-updates/ignore {setVersion}
  *   POST /plugin-update/unignore → POST /api/v1/plugin-updates/unignore {setVersion}
  *   GET  /plugin-update/runtime  → GET  /api/v1/runtime-update
+ *   POST /plugin-update/runtime-request
+ *                                → POST /api/v1/runtime-update/request {targetVersion}
+ *   GET  /plugin-update/runtime-source
+ *                                → GET  /api/v1/runtime-update/source
+ *   POST /plugin-update/runtime-source
+ *                                → POST /api/v1/runtime-update/source {url}
+ *   GET  /plugin-update/plugin-source
+ *                                → GET  /api/v1/plugin-updates/source
+ *   POST /plugin-update/plugin-source
+ *                                → POST /api/v1/plugin-updates/source {url}
+ *
+ * The runtime-update request is user-confirmed in this plugin's review panel:
+ * hq-edge validates the version against a fresh manifest, downloads and
+ * verifies the bundle, stages it, then hands it to the EDA host and answers
+ * `202 Accepted` before shutting itself down to be swapped and relaunched.
  *
  * @module
  */
@@ -27,6 +42,23 @@ export const UPDATE_ROUTE_PREFIX = '/api/v1/huaqiu/plugin-update'
 /** End-to-end budget for one forwarded request, in milliseconds. */
 export const DEFAULT_FORWARD_TIMEOUT_MS = 30_000
 
+/**
+ * Budget for `POST /runtime-update/request` — deliberately far larger than
+ * {@link DEFAULT_FORWARD_TIMEOUT_MS}.
+ *
+ * This route is not a quick RPC. Before it answers, hq-edge re-reads the
+ * update manifest, downloads the entire runtime bundle (hundreds of MB),
+ * verifies its SHA-256, extracts it into the shared staging root and validates
+ * the layout + version stamp. Measured end-to-end against a local update
+ * server: 56 s (16:49:49 → 16:50:45).
+ *
+ * Under the generic 30 s budget the forwarder aborts mid-flight and answers
+ * `504 hq-edge request timed out after 30000ms`, so the panel reports a failure
+ * for an update that is still running perfectly well — and which then goes on
+ * to complete, swap the runtime and restart HQ Edge underneath the error toast.
+ */
+export const RUNTIME_REQUEST_TIMEOUT_MS = 600_000
+
 export type BaseUrlResolver = () => string | undefined
 
 function sendJson(res: ServerResponse, status: number, body: unknown): void {
@@ -66,21 +98,76 @@ function readBody(req: IncomingMessage): Promise<string> {
   })
 }
 
-/** Map a sub-path to { method, path } on the hq-edge API. */
-function routeFor(sub: string): { method: string; path: string } | null {
+/**
+ * Map a sub-path + method to { method, path } on the hq-edge API.
+ *
+ * `timeoutMs` overrides {@link DEFAULT_FORWARD_TIMEOUT_MS} for routes whose
+ * upstream work legitimately outlasts it (only `/runtime-request` today).
+ *
+ * The method is part of the lookup because one sub-path can carry both a read
+ * and a write: `/runtime-source` is GET for the current value and POST to
+ * change it. A method the route does not declare is `null`, which the
+ * forwarder answers 405 rather than forwarding a GET to a POST-only upstream
+ * and surfacing hq-edge's 404 as a plugin bug.
+ */
+function routeFor(
+  sub: string,
+  method: string,
+): { method: string; path: string; timeoutMs?: number } | null {
+  if (sub === '/runtime-source') {
+    if (method === 'GET') return { method: 'GET', path: '/api/v1/runtime-update/source' }
+    if (method === 'POST') return { method: 'POST', path: '/api/v1/runtime-update/source' }
+    return null
+  }
+  if (sub === '/plugin-source') {
+    if (method === 'GET') return { method: 'GET', path: '/api/v1/plugin-updates/source' }
+    if (method === 'POST') return { method: 'POST', path: '/api/v1/plugin-updates/source' }
+    return null
+  }
   if (sub === '/report' || sub === '') {
-    return { method: 'GET', path: '/api/v1/plugin-updates' }
+    return method === 'GET' ? { method: 'GET', path: '/api/v1/plugin-updates' } : null
   }
   if (sub === '/runtime') {
-    return { method: 'GET', path: '/api/v1/runtime-update' }
+    return method === 'GET' ? { method: 'GET', path: '/api/v1/runtime-update' } : null
+  }
+  if (sub === '/runtime-request') {
+    return method === 'POST'
+      ? {
+          method: 'POST',
+          path: '/api/v1/runtime-update/request',
+          timeoutMs: RUNTIME_REQUEST_TIMEOUT_MS,
+        }
+      : null
+  }
+  if (sub === '/check') {
+    return method === 'POST' ? { method: 'POST', path: '/api/v1/plugin-updates/check' } : null
+  }
+  if (sub === '/install') {
+    return method === 'POST' ? { method: 'POST', path: '/api/v1/plugin-updates/install' } : null
+  }
+  if (sub === '/ignore') {
+    return method === 'POST' ? { method: 'POST', path: '/api/v1/plugin-updates/ignore' } : null
+  }
+  if (sub === '/unignore') {
+    return method === 'POST' ? { method: 'POST', path: '/api/v1/plugin-updates/unignore' } : null
   }
-  if (sub === '/check') return { method: 'POST', path: '/api/v1/plugin-updates/check' }
-  if (sub === '/install') return { method: 'POST', path: '/api/v1/plugin-updates/install' }
-  if (sub === '/ignore') return { method: 'POST', path: '/api/v1/plugin-updates/ignore' }
-  if (sub === '/unignore') return { method: 'POST', path: '/api/v1/plugin-updates/unignore' }
   return null
 }
 
+/** Every sub-path this forwarder serves — used to tell a 404 from a 405. */
+const ROUTE_SUB_PATHS = new Set([
+  '',
+  '/report',
+  '/check',
+  '/install',
+  '/ignore',
+  '/unignore',
+  '/runtime',
+  '/runtime-request',
+  '/runtime-source',
+  '/plugin-source',
+])
+
 /** Create the prefix-route handler forwarding to hq-edge. */
 export function createUpdateForwarder(
   baseUrlResolver: BaseUrlResolver,
@@ -92,9 +179,19 @@ export function createUpdateForwarder(
       sendJson(res, 404, { error: 'not found' })
       return
     }
-    const target = routeFor(sub)
+    // HEAD reads like GET: it never carried its own route, and the upstream
+    // has no HEAD semantics to preserve.
+    const method = req.method === 'HEAD' ? 'GET' : (req.method ?? '')
+    const target = routeFor(sub, method)
     if (target === null) {
-      sendJson(res, 404, { error: 'not found' })
+      // Either an unknown sub-path (404) or a known one under a method it does
+      // not serve (405). Both are client errors caught here, not upstream.
+      sendJson(res, sub === '' || ROUTE_SUB_PATHS.has(sub) ? 405 : 404, {
+        error:
+          sub === '' || ROUTE_SUB_PATHS.has(sub)
+            ? `method ${req.method} not allowed on ${sub || '/'}`
+            : 'not found',
+      })
       return
     }
     if (req.method !== 'GET' && req.method !== 'POST' && req.method !== 'HEAD') {
@@ -115,8 +212,9 @@ export function createUpdateForwarder(
         return
       }
     }
+    const budget = target.timeoutMs ?? timeoutMs
     const controller = new AbortController()
-    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    const timer = setTimeout(() => controller.abort(), budget)
     try {
       const upstream = await fetch(`${base}${target.path}`, {
         method: target.method,
@@ -138,7 +236,7 @@ export function createUpdateForwarder(
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err)
       if (err instanceof Error && err.name === 'AbortError') {
-        sendJson(res, 504, { error: `hq-edge request timed out after ${timeoutMs}ms` })
+        sendJson(res, 504, { error: `hq-edge request timed out after ${budget}ms` })
         return
       }
       sendJson(res, 502, { error: `hq-edge request failed: ${message}` })