docs: design support IM reliability fix

2026-10-19 16:50:29 +08:00
parent e6c421ac3e
commit c39ec78e89
2 changed files with 121 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Customer Service IM Reliability Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Restore customer-service message and image delivery after WebSocket interruptions and route every browser IM request through its current frontend origin.
+
+**Architecture:** Browser-facing session endpoints are relative paths resolved against the current origin, while server-to-server calls use Docker-internal endpoints. Caddy routes the IM API, file service, and WebSocket before each site's frontend fallback. The mobile chat client reauthenticates and resubscribes after SDK reconnects.
+
+**Tech Stack:** Go, Vue 3, TypeScript, Tinode SDK, Vitest, Docker Compose, Caddy, Python/Bash deployment contract tests.
+
+---
+
+### Task 1: Relative browser endpoint contract
+
+**Files:**
+- Modify: `internal/support/service.go`
+- Modify: `internal/support/service_test.go`
+
+- [ ] Write a failing Go test asserting `OpenSession` returns `/v1/im`, `/v0/channels`, and `/v0/file` even when internal IM configuration contains an absolute host.
+- [ ] Run `go test ./internal/support -run TestOpenSessionReturnsSameOriginEndpoints -v` and confirm the absolute-host assertion failure.
+- [ ] Return the three relative public endpoints from `OpenSession` without changing `imclient.Config()` used for server calls.
+- [ ] Re-run the targeted test and `go test ./internal/support ./internal/imclient ./internal/httpapi`.
+
+### Task 2: Mobile reconnect and media authentication
+
+**Files:**
+- Modify: `web/package.json`
+- Modify: `web/pnpm-lock.yaml`
+- Modify: `web/src/mobile/im.ts`
+- Create: `web/src/mobile/im.test.ts`
+- Modify: `web/src/mobile/views/SupportView.vue`
+
+- [ ] Add Vitest and a test script.
+- [ ] Write failing tests for same-origin endpoint resolution, initial connect/login/subscribe, reconnect login/resubscribe with later data, and intentional disconnect.
+- [ ] Run `pnpm test --run` and confirm the failures are caused by missing reconnect behavior.
+- [ ] Add serialized reconnect recovery, connection-state callbacks, relative endpoint resolution, and Header-based upload authentication.
+- [ ] Add an offline/reconnecting banner, disable sending while disconnected, and add media error/retry UI.
+- [ ] Run `pnpm test --run`, `pnpm run build`, and the Go package tests.
+
+### Task 3: Remove fixed IM public origins from im_webapp
+
+**Files:**
+- Modify: `../im_webapp/tests/test_actions_workflow.py`
+- Modify: `../im_webapp/.gitea/workflows/deploy.yml`
+- Modify: `../im_webapp/Dockerfile`
+- Modify: `../im_webapp/web/src/lib/config.ts`
+- Modify or create: `../im_webapp/web/tests/same-origin-endpoints.test.mjs`
+
+- [ ] Change contract tests first so they reject fixed production API/file build arguments and the legacy default WebSocket host.
+- [ ] Run the Python and Node tests and confirm they fail on the current fixed values.
+- [ ] Remove fixed endpoint build arguments, make file base default empty, and derive the fallback WebSocket host from `window.location.host`.
+- [ ] Run Python contracts, Node tests, and `pnpm run build`.
+
+### Task 4: Caddy same-origin route contract
+
+**Files:**
+- Modify: `../deploy/olns-stack/test-deployment.sh`
+- Modify: `../deploy/olns-stack/Caddyfile`
+- Modify: `../deploy/olns-stack/compose.yaml`
+- Modify: `.gitea/workflows/deploy.yml`
+
+- [ ] Add failing deployment assertions requiring `/v1/im*`, `/v0/file*`, and `/v0/channels*` to be handled before frontend fallbacks for both site groups.
+- [ ] Run `bash ../deploy/olns-stack/test-deployment.sh` and confirm failure.
+- [ ] Add the Caddy route handlers with no-store responses.
+- [ ] Switch server-side IM HTTP/WS/base values to `im-server:6060` in Compose and the OLONS deployment overlay.
+- [ ] Re-run deployment contracts and workflow tests.
+
+### Task 5: Integration and production verification
+
+**Files:**
+- Update: `../DEPLOYMENT_RECORD.md` with non-secret route and acceptance notes.
+
+- [ ] Run full Go, web, workflow and deployment test suites and builds.
+- [ ] Commit each repository, merge the task branch into current `pro`, and push `pro` only after all local gates pass.
+- [ ] Back up `/opt/olns/Caddyfile` and Compose files, install the tested Caddy/Compose changes, validate Caddy, and reload atomically.
+- [ ] Wait for both Actions deployments and verify image digests, container health and restart counts.
+- [ ] Verify all five domains return IM responses instead of SPA HTML, WebSocket upgrades to 101, and file responses are not HTML.
+- [ ] Exercise a real support session, interrupt/recover its network connection, and verify a subsequent text and image arrive without refreshing.