fix(extension): robust port handling — fallback + URL push on restart #619
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,7 +8,10 @@ | |
| "vscode": { | ||
| "extensions": [ | ||
| "harmoniqs.amicode" | ||
| ], | ||
| "settings": { | ||
| "amicode.opencodePort": 43117 | ||
| } | ||
| } | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| # ADR 0008: Server URL Push on Restart | ||
|
|
||
| ## Status | ||
|
|
||
| Accepted | ||
|
|
||
| ## Context | ||
|
|
||
| The Amicode extension embeds the opencode web app in a WebviewPanel iframe. The | ||
| iframe's `location.origin` IS the server URL (e.g., `http://127.0.0.1:43117`). | ||
| When the server restarts, two scenarios exist: | ||
|
|
||
| 1. **Same port** (the default, `amicode.opencodePort = 43117`): the iframe's origin | ||
| is still valid. The SSE reconnect loop retries every 250 ms and reconnects once | ||
| the server is back. The server's `server.connected` event carries a `bootId` that | ||
| the web app uses to detect the restart and trigger a full state refresh. | ||
|
|
||
| 2. **Different port** (ephemeral mode, `amicode.opencodePort = 0`): the iframe's | ||
| origin points to a dead port. The SSE loop fails indefinitely. The webview's | ||
| localStorage may hold a stale URL from the previous port, compounding the issue. | ||
|
|
||
| Previously, there was no mechanism for the extension host to notify the webview of | ||
| a server restart or URL change. The webview relied entirely on the SSE reconnect | ||
| loop and localStorage, both of which fail when the port changes. | ||
|
|
||
| ## Decision | ||
|
|
||
| ### Extension host (this repo) | ||
|
|
||
| 1. **`ChatPanel.notifyServerUrlChanged(url)`**: a static method that checks whether | ||
| the new URL's origin differs from the panel's recorded origin. | ||
| - If same origin: posts a `server-url-changed` message (Lane 2) to all live | ||
| panels as a "restart happened" signal. | ||
| - If different origin: returns `true`, signaling the caller to dispose and | ||
| recreate the panel. | ||
|
|
||
| 2. **`ChatPanel.disposeCurrent()`**: disposes the underlying `vscode.WebviewPanel`, | ||
| which triggers cleanup and allows `openOrReveal` to create a fresh panel with the | ||
| new iframe `src`. | ||
|
|
||
| 3. **`serverManager.onReady` hook**: after every successful server start (including | ||
| restarts), calls `notifyServerUrlChanged`. If recreation is needed, disposes the | ||
| panel before `openOrReveal` creates a fresh one. | ||
|
|
||
| 4. **Lane 2 allowlist**: `"server-url-changed"` added to the relay script's Lane 2 | ||
| filter in both `chat_panel.ts` and `deck/shell.ts`. | ||
|
|
||
| ### Web app (opencode repo) | ||
|
|
||
| 5. **`AmicodeServerBridge` component**: listens for `server-url-changed` messages. | ||
| If the URL in the message differs from `location.origin` (unexpected — the panel | ||
| should have been recreated), redirects to the new URL as a safety net. If same | ||
| origin, does nothing (the SSE loop handles it). | ||
|
|
||
| ## Consequences | ||
|
|
||
| - Same-port restarts (the common case) are seamless: the SSE loop reconnects and | ||
| the boot-ID mismatch triggers a full refresh — no panel recreation needed. | ||
| - Port-change restarts (ephemeral mode) cause a brief panel flicker as the old | ||
| panel is disposed and a new one is created with the correct origin. | ||
| - The `onReady` approach covers ALL server-ready events, not just explicit restarts | ||
| — including the initial boot, solver-mode switches, and vault respawns. | ||
| - Future improvement: self-healing via `postMessage` (documented in | ||
| `plans/followup-self-healing-reconnect.md` in the workspace) to avoid panel | ||
| recreation entirely. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,193 @@ | ||
| # Devcontainer Configuration | ||
|
|
||
| This document covers how the Amicode extension's runtime invariants (server port, | ||
| storage paths, etc.) are configured in devcontainer environments, including the | ||
| Dockerfile-based build case. | ||
|
|
||
| --- | ||
|
|
||
| ## Why port stability matters | ||
|
|
||
| The Amicode webview panel embeds the opencode web app in an iframe served by a | ||
| local HTTP server. The webview's localStorage (which persists session tabs, project | ||
| paths, and connection state) lives on the **host machine** — it survives container | ||
| rebuilds. The server port, however, is ephemeral unless explicitly pinned. | ||
|
|
||
| If the server starts on a different port after a container rebuild, the persisted | ||
| connection state in localStorage is stale. The webview's SSE event stream connects | ||
| to the dead port, and the user sees no responses until localStorage is cleared. | ||
|
|
||
| **The fix:** pin the server port to a stable value (default: `43117`) so that the | ||
| persisted URL remains valid across container rebuilds. | ||
|
|
||
| --- | ||
|
|
||
| ## Use cases | ||
|
|
||
| ### A. Pre-built extension (marketplace install) | ||
|
|
||
| The devcontainer installs Amicode from the VS Code Marketplace. No build-time | ||
| dependencies are needed. | ||
|
|
||
| ```jsonc | ||
| // .devcontainer/devcontainer.json | ||
| { | ||
| "name": "Amicode", | ||
| "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04", | ||
| "customizations": { | ||
| "vscode": { | ||
| "extensions": ["harmoniqs.amicode"], | ||
| "settings": { | ||
| "amicode.opencodePort": 43117 | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The `amicode.opencodePort` setting is read by the extension at startup. It passes | ||
| `--port 43117` to the spawned `opencode serve` process. This is the simplest | ||
| configuration and covers most users. | ||
|
|
||
| ### B. Dockerfile-based build (extension under development) | ||
|
|
||
| The devcontainer uses a Dockerfile that installs build-time dependencies (Node, | ||
| pnpm, Bun, etc.). The extension is NOT installed from the marketplace — it runs | ||
| via F5 ("Run Extension") or is manually installed from a locally-built `.vsix`. | ||
|
|
||
| ```jsonc | ||
| // .devcontainer/devcontainer.json | ||
| { | ||
| "name": "Amicode Dev", | ||
| "build": { | ||
| "dockerfile": "Dockerfile" | ||
| }, | ||
| "customizations": { | ||
| "vscode": { | ||
| "settings": { | ||
| "amicode.opencodePort": 43117 | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| **Key point:** `customizations.vscode.settings` is applied to the VS Code instance | ||
| regardless of how extensions are installed. Even when the extension is launched via | ||
| F5 (Extension Development Host), VS Code resolves `amicode.opencodePort` from the | ||
| workspace/container settings. You do NOT need the extension to be listed in | ||
| `"extensions"` for the setting to be available. | ||
|
|
||
| If the Dockerfile needs to set a default port for cases where VS Code is not | ||
| involved (e.g., running `opencode serve` directly in a terminal during | ||
| development): | ||
|
|
||
| ```dockerfile | ||
| # Dockerfile | ||
| FROM mcr.microsoft.com/devcontainers/base:ubuntu-24.04 | ||
|
|
||
| # ... build-time dependencies ... | ||
|
|
||
| # Default server port for opencode (read via OPENCODE_CONFIG_CONTENT) | ||
| ENV OPENCODE_CONFIG_CONTENT='{"server":{"port":43117}}' | ||
| ``` | ||
|
|
||
| This env var is read by the opencode binary directly, bypassing VS Code settings. | ||
| It works in all contexts — terminal, scripts, CI — but note that when the Amicode | ||
| extension IS running, it builds its own `OPENCODE_CONFIG_CONTENT` (merging | ||
| instructions, permissions, telemetry, etc.) and passes it to the server process. | ||
| The Dockerfile's `ENV` value is therefore only effective when running the binary | ||
| manually outside the extension. | ||
|
|
||
| ### C. CI / headless (no VS Code) | ||
|
|
||
| For test harnesses, build pipelines, or headless environments where VS Code is not | ||
| present: | ||
|
|
||
| **Option 1 — `opencode.json` in the project root:** | ||
| ```json | ||
| { | ||
| "server": { | ||
| "port": 43117 | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| This is the most portable option. The opencode binary reads it from the working | ||
| directory (or any ancestor). It works in all contexts and requires no environment | ||
| variable management. | ||
|
|
||
| **Option 2 — `OPENCODE_CONFIG_CONTENT` env var:** | ||
| ```bash | ||
| export OPENCODE_CONFIG_CONTENT='{"server":{"port":43117}}' | ||
| opencode serve | ||
| ``` | ||
|
|
||
| Or in `docker-compose.yml`: | ||
| ```yaml | ||
| services: | ||
| opencode: | ||
| environment: | ||
| OPENCODE_CONFIG_CONTENT: '{"server":{"port":43117}}' | ||
| ``` | ||
|
|
||
| **Option 3 — CLI flag:** | ||
| ```bash | ||
| opencode serve --port 43117 | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Port resolution priority (highest wins) | ||
|
|
||
| | Priority | Mechanism | Who sets it | | ||
| |----------|-----------|-------------| | ||
| | 1 | `--port` CLI flag | The extension (internally) or manual invocation | | ||
| | 2 | `OPENCODE_CONFIG_CONTENT` env var | The extension (builds merged config) or Dockerfile `ENV` | | ||
| | 3 | `opencode.json` `server.port` field | Developer, committed to repo | | ||
| | 4 | Default: `0` → try 4096, then OS-assigned | Built-in fallback | | ||
|
|
||
| When the Amicode extension is running: | ||
| - It reads `amicode.opencodePort` from VS Code settings (default: `43117`) | ||
| - It passes this as `--port` to the spawned server (priority 1) | ||
| - All other mechanisms are fallbacks for when the extension is not present | ||
|
|
||
| --- | ||
|
|
||
| ## Other configurable paths | ||
|
|
||
| The extension also supports overriding storage locations via VS Code settings | ||
| (added in #378): | ||
|
|
||
| | Setting | Env var injected | Default (XDG) | | ||
| |---------|-----------------|---------------| | ||
| | `amicode.sessionDatabase` | `OPENCODE_DB` | `~/.local/share/opencode/opencode.db` | | ||
| | `amicode.configDir` | `OPENCODE_CONFIG_DIR` | `~/.config/opencode` | | ||
|
|
||
| These can also be set in `customizations.vscode.settings` in `devcontainer.json` | ||
| for container-specific overrides (e.g., placing the database on a mounted volume). | ||
|
|
||
| --- | ||
|
|
||
| ## Caveats for Dockerfile-based builds | ||
|
|
||
| 1. **The extension is not installed at image build time.** `customizations.vscode` | ||
| is processed by VS Code/Codespaces at container start, not during `docker build`. | ||
| Do not rely on extension presence in Dockerfile `RUN` steps. | ||
|
|
||
| 2. **`OPENCODE_CONFIG_CONTENT` conflicts.** If both the Dockerfile sets this env | ||
| var AND the extension is running, the extension's value wins (it spawns the | ||
| server with its own merged config in the process env, overriding the container | ||
| env). The Dockerfile value is only effective for manual `opencode serve` calls. | ||
|
|
||
| 3. **Port forwarding.** If VS Code auto-forwards port 43117 (which it does by | ||
| default for detected listening ports), the server is accessible from the host at | ||
| `localhost:43117`. This is expected behavior and does not interfere with the | ||
| webview (which connects to the container-internal `127.0.0.1:43117`). | ||
|
Comment on lines
+183
to
+186
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- applicable repository conventions ---'
find /tmp/coderabbit-repo-knowledge/harmoniqs-amicode-b00ba095 -type f -name '*.md' -print
printf '%s\n' '--- target document ---'
sed -n '160,200p' docs/devcontainers.md
printf '%s\n' '--- extension symbols and URL flow ---'
rg -n -C 5 'opencodeExternalUrl|ChatPanel\.openOrReveal|sseClient\.connect|asExternalUri|43117|externalUrl' packages/extension/src/extension.ts packages/extension/src docs/devcontainers.mdRepository: harmoniqs/amicode Length of output: 45290 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- extension conventions ---'
cat /tmp/coderabbit-repo-knowledge/harmoniqs-amicode-b00ba095/conventions/packages-extension.md
printf '%s\n' '--- repo-wide conventions ---'
cat /tmp/coderabbit-repo-knowledge/harmoniqs-amicode-b00ba095/conventions/repo-wide.md
printf '%s\n' '--- ChatPanel URL contract and webview creation ---'
rg -n -C 6 'class ChatPanel|openOrReveal|openNew|adopt|WebviewPanel|webview|baseUrl|serverUrl' packages/extension/src --glob '*.ts'
printf '%s\n' '--- complete fleet and startup handlers ---'
sed -n '500,625p' packages/extension/src/extension.ts
sed -n '820,895p' packages/extension/src/extension.ts
sed -n '1360,1400p' packages/extension/src/extension.tsRepository: harmoniqs/amicode Length of output: 50374 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- fleet/postDown flow ---'
sed -n '500,620p' packages/extension/src/extension.ts
printf '%s\n' '--- ChatPanel constructor and render URL use ---'
sed -n '66,128p' packages/extension/src/chat_panel.ts
sed -n '270,365p' packages/extension/src/chat_panel.ts
printf '%s\n' '--- all direct webview-opening call sites ---'
rg -n 'ChatPanel\.(openOrReveal|openNew|adopt)|DeckPanel\.(openOrReveal|openNew|adopt)|createWebviewPanel' packages/extension/src --glob '*.ts'
printf '%s\n' '--- server manager URL callback contract ---'
sed -n '1,125p' packages/extension/src/server_manager.tsRepository: harmoniqs/amicode Length of output: 21972 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- remaining fleet branch ---'
sed -n '585,620p' packages/extension/src/extension.ts
printf '%s\n' '--- every URL assignment and webview call in extension.ts ---'
rg -n -C 2 'opencodeExternalUrl\s*=|ChatPanel\.(openOrReveal|openNew|adopt)|DeckPanel\.openOrReveal' packages/extension/src/extension.ts
printf '%s\n' '--- iframe source and DeckPanel URL use ---'
sed -n '339,390p' packages/extension/src/chat_panel.ts
sed -n '55,100p' packages/extension/src/deck_panel.tsRepository: harmoniqs/amicode Length of output: 10785 Document and use the external webview URL.
🤖 Prompt for AI Agents |
||
|
|
||
| 4. **Multiple containers on the same host.** If two devcontainers both use port | ||
| 43117, VS Code handles port forwarding conflicts (it maps to different host | ||
| ports). The webview inside each container connects to its own `127.0.0.1:43117` | ||
| without conflict. The localStorage isolation concern (multiple webviews sharing | ||
| one localStorage scope) is separate and addressed by the boot-ID mechanism | ||
| (opencode ADR 0005). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document the occupied-port fallback.
ServerManager.start()uses43117only when the port is available. When it is occupied, the code selects an ephemeral port. These lines state that pinning keeps the persisted URL valid and that the extension always passes43117. State that pinning is best effort and describe the restart URL propagation and panel recreation path.Also applies to: 48-50, 150-153
🤖 Prompt for AI Agents