Skip to content

Add configurable connection targets - #10

Merged
TraderSamwise merged 3 commits into
masterfrom
feat/connection-targets
May 23, 2026
Merged

Add configurable connection targets#10
TraderSamwise merged 3 commits into
masterfrom
feat/connection-targets

Conversation

@TraderSamwise

@TraderSamwise TraderSamwise commented May 22, 2026

Copy link
Copy Markdown
Owner

Summary

  • add shared CLI/app connection target resolvers with prod relay and dev local defaults
  • route app API calls through relay when relay mode is configured, failing closed instead of falling back to direct HTTP
  • add aimux-dev/local GUI helpers and docs for local vs relay development
  • require Clerk for relay/release mode and avoid direct relative image URLs in relay mode

Verification

  • yarn test
  • yarn --cwd app test
  • yarn typecheck
  • yarn --cwd app typecheck
  • yarn build
  • yarn --cwd app export:web
  • yarn lint
  • yarn --cwd app lint (passes with existing warnings)
  • git diff --check

Summary by CodeRabbit

  • New Features

    • Selectable connection modes (local vs relay) with new environment options to pick mode and override endpoints.
    • In relay mode, non-absolute images display as an "[image]" placeholder; auth now enforces required publishable-key when using relay.
  • Chores

    • New dev scripts for local/relay workflows and new dev GUI relay script; updated CLI local defaults.
  • Documentation

    • Deployment and dev guides updated with connection-mode and endpoint guidance.
  • Tests

    • Added tests for connection-mode, routing, and image URL behavior.

Review Change Stack

@coderabbitai

coderabbitai Bot commented May 22, 2026

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 55b7b3c5-b957-44db-9a33-1dfbd86f8d5f

📥 Commits

Reviewing files that changed from the base of the PR and between 84e6ad0 and a268528.

📒 Files selected for processing (1)
  • docs/deployment.md
✅ Files skipped from review due to trivial changes (1)
  • docs/deployment.md

📝 Walkthrough

Walkthrough

This PR centralizes connection-target resolution (mode, relay, daemon), adds EXPO_PUBLIC_AIMUX_CONNECTION_MODE and NODE_ENV getters, routes API calls via relay when appropriate, enforces auth config for relay, adjusts MessageBlock image resolution for relay mode, and updates scripts/docs/tests for both modes.

Changes

Connection Mode Configuration and Relay Routing

Layer / File(s) Summary
Environment system and connection target resolution
app/environment.d.ts, app/lib/envRuntime.ts, app/lib/envContract.js, app/lib/env.ts, app/lib/connection-targets.ts, app/lib/connection-targets.test.ts, src/connection-targets.ts, src/connection-targets.test.ts
New EXPO_PUBLIC_AIMUX_CONNECTION_MODE and NODE_ENV getters; centralized connection-target resolvers (resolveAppConnectionMode, resolveAppDaemonUrl, resolveAppRelayUrl) that validate/derive mode and return URLs only for the active mode; trimming/normalization and tests for defaults/overrides.
API routing based on connection mode
app/lib/api.ts, app/lib/api.test.ts, app/lib/daemon-url.ts
Add shouldRouteViaRelay() (env + relay status) and route service/daemon requests via relay proxy when true; simplify getDaemonUrl to read resolved env value. Tests assert no fallback to direct fetch when relay routing applies.
Authentication configuration validation
app/lib/auth.tsx
Add assertAuthConfiguredForConnectionMode() that throws when relay mode is active without CLERK_PUBLISHABLE_KEY; update LOCAL_MODE and invoke guard from AuthProvider, useAuth, and useUser.
Component behavior in relay mode
app/components/MessageBlock.tsx, app/components/MessageBlock.test.ts
Export resolveImageUrl and gate image URL synthesis on connection mode: in relay mode non-absolute image URLs return null (rendered as [image]), in local mode relative URLs are resolved to direct service URLs. Tests cover local/relay/absolute cases.
Developer tooling and documentation
app/.env.example, app/package.json, package.json, bin/aimux-dev, app/stores/relay.ts, docs/deployment.md, docs/dev-runtime.md, src/login-flow.ts
Add dev scripts dev:local, dev:relay, dev:gui:relay; CLI default AIMUX_WEB_APP_URL; update examples and docs with connection-mode config and defaults; login flow now uses centralized resolvers.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

  • TraderSamwise/aimux#4: Earlier relay-transport integration that this PR’s shouldRouteViaRelay()/routing changes build upon.
  • TraderSamwise/aimux#3: Related GUI/MessageBlock changes that this PR’s MessageBlock image-resolution update builds on.

Poem

🐰 I hop through env vars, sniff the chosen way,
Local daemon paths or relay over the bay.
Tests lined up, scripts set to run,
Images hidden or fetched in the sun.
A rabbit's cheer for mode—now pick and play!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 10.34% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'Add configurable connection targets' accurately summarizes the main change: introducing environment-driven configuration for selecting between local daemon and relay connection modes, with new resolver functions and environment variables.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/connection-targets

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
docs/deployment.md (1)

122-122: 💤 Low value

Optional: Consider rephrasing for clarity.

The sentence begins with the variable name, which reads as a fragment. Consider rephrasing to:

-`AIMUX_RELAY_URL` may also be set in the environment as an override; it defaults to `wss://relay.aimux.app`.
+The relay URL may also be overridden by setting `AIMUX_RELAY_URL` in the environment; it defaults to `wss://relay.aimux.app`.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/deployment.md` at line 122, The sentence fragment starting with the
environment variable name (AIMUX_RELAY_URL) is unclear; rephrase the line so it
reads as a full sentence—for example, "You can optionally set the
AIMUX_RELAY_URL environment variable to override the default
wss://relay.aimux.app."—so that AIMUX_RELAY_URL and the default value are
clearly described in one coherent sentence.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/deployment.md`:
- Line 122: The sentence fragment starting with the environment variable name
(AIMUX_RELAY_URL) is unclear; rephrase the line so it reads as a full
sentence—for example, "You can optionally set the AIMUX_RELAY_URL environment
variable to override the default wss://relay.aimux.app."—so that AIMUX_RELAY_URL
and the default value are clearly described in one coherent sentence.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 498042ac-1418-4a47-83c6-50a2ff25c613

📥 Commits

Reviewing files that changed from the base of the PR and between 694fc17 and 3d8a810.

📒 Files selected for processing (22)
  • app/.env.example
  • app/components/MessageBlock.test.ts
  • app/components/MessageBlock.tsx
  • app/environment.d.ts
  • app/lib/api.test.ts
  • app/lib/api.ts
  • app/lib/auth.tsx
  • app/lib/connection-targets.test.ts
  • app/lib/connection-targets.ts
  • app/lib/daemon-url.ts
  • app/lib/env.ts
  • app/lib/envContract.js
  • app/lib/envRuntime.ts
  • app/package.json
  • app/stores/relay.ts
  • bin/aimux-dev
  • docs/deployment.md
  • docs/dev-runtime.md
  • package.json
  • src/connection-targets.test.ts
  • src/connection-targets.ts
  • src/login-flow.ts

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
docs/deployment.md (1)

75-77: 💤 Low value

Consider clarifying when to set these optional environment variables.

The documentation marks these variables as optional with defaults, but shows them set to their default values without explaining when or why a user would override them. This pattern might confuse readers about whether they need to set these variables.

Consider one of these approaches:

  • Comment out the example values to show they're optional
  • Add a note explaining scenarios where you'd override the defaults (e.g., "Set EXPO_PUBLIC_AIMUX_RELAY_URL to point to a staging relay or self-hosted instance")
  • Move these to a separate "Advanced Configuration" subsection
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/deployment.md` around lines 75 - 77, The docs currently show
EXPO_PUBLIC_AIMUX_CONNECTION_MODE and EXPO_PUBLIC_AIMUX_RELAY_URL set to their
defaults which can confuse readers; update the docs to clearly mark these as
optional by either commenting out the example assignments or moving them into an
"Advanced Configuration" subsection and add a short note explaining when to
override EXPO_PUBLIC_AIMUX_RELAY_URL (e.g., to point to a staging relay or a
self-hosted relay) and when to change EXPO_PUBLIC_AIMUX_CONNECTION_MODE from the
default "relay"; keep the environment variable names
(EXPO_PUBLIC_AIMUX_CONNECTION_MODE, EXPO_PUBLIC_AIMUX_RELAY_URL) in the text so
users can find and modify them easily.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/deployment.md`:
- Around line 75-77: The docs currently show EXPO_PUBLIC_AIMUX_CONNECTION_MODE
and EXPO_PUBLIC_AIMUX_RELAY_URL set to their defaults which can confuse readers;
update the docs to clearly mark these as optional by either commenting out the
example assignments or moving them into an "Advanced Configuration" subsection
and add a short note explaining when to override EXPO_PUBLIC_AIMUX_RELAY_URL
(e.g., to point to a staging relay or a self-hosted relay) and when to change
EXPO_PUBLIC_AIMUX_CONNECTION_MODE from the default "relay"; keep the environment
variable names (EXPO_PUBLIC_AIMUX_CONNECTION_MODE, EXPO_PUBLIC_AIMUX_RELAY_URL)
in the text so users can find and modify them easily.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b3bc310d-9b56-4691-97f0-bb30f24963b2

📥 Commits

Reviewing files that changed from the base of the PR and between 3d8a810 and 84e6ad0.

📒 Files selected for processing (1)
  • docs/deployment.md

@TraderSamwise
TraderSamwise merged commit ed00266 into master May 23, 2026
1 check passed
@TraderSamwise
TraderSamwise deleted the feat/connection-targets branch May 23, 2026 00:08
@coderabbitai coderabbitai Bot mentioned this pull request Jul 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant