olons_server/docs/superpowers/plans/2026-10-19-customer-service-im-reliability.md

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.