chore(rebrand): rename agent + relay URL paths to /api/v1/* (VS-24) #34

Merged

nrupard merged 3 commits from chore/rebrand-url-paths-VS-24 into main

2026-05-21 19:36:24 +02:00

nrupard commented

2026-05-21 19:27:09 +02:00

Owner

What

Server-side half of VS-24 (paired with VA-28 slice 6): rename the two agent-facing WebSocket endpoints off the legacy MeshCentral .ashx handler names to versioned, vervain-branded paths, and delete the old ones outright (no deprecation alias, per the no-active-deployments guidance).

Decisions (from the issue's open questions)

Versioning prefix: yes, /api/v1/. Lets a future protocol rev ship under /api/v2/ without breaking v1 agents.
Names: /api/v1/agent (control channel) and /api/v1/relay (per-tunnel relay). Composes the chosen /api/... namespace with the /v1/ version.
Relay query params renamed in lockstep: p becomes usage, nodeid becomes agent_id. id, rauth, auth, browser, slowrelay unchanged.

Changes

New meshcentral-web/src/wire_paths.rs: single source of truth for the path + param-name constants.
Router (build_router): old routes removed, new /api/v1/agent + /api/v1/relay registered (no-domain and /:domain/... forms). Dropped the /relay.ashx legacy alias.
RelayQuery: nodeid -> agent_id, p -> usage (wire keys); internal field names unchanged.
.msh MeshServer= URL builder (meshsettings) and the CSRF-safe-path allowlist (security) reference the constant.
SPA relay client (public/scripts/agent-redir-ws-0.1.1.js + its minified twin, public/samples/relay.js, views/messenger.handlebars): emit /api/v1/relay with usage/agent_id. The minified file was edited by targeted string replacement.
Comments, tracing messages, and Prometheus metric descriptions reworded so the AC grep is clean.
README gains an "Agent wire paths (VS-24)" paragraph.

Acceptance criteria

New control-channel and relay paths picked and documented (README + wire_paths.rs).
Old routes removed from the server.
grep -rE "agent\.ashx|meshrelay\.ashx" returns zero hits (verified).
Paired agent-side change merged (VA-28) - cross-link once opened. This server PR merges first; the agent only consumes server-supplied relay URLs, and its control-channel path comes from MeshServer= (regenerate .msh).
README paragraph calls out the rename.

Out of scope (unchanged)

/control.ashx (user UI channel) and /mcptunnel.ashx (VS-22 MCP rendezvous). Only the two paths named in VS-24 move.

Verification

cargo clippy --workspace --all-targets -- -D warnings clean; touched crates fmt --check clean; cargo test -p meshcentral-web --lib = 404 passed (incl. updated build_ws_url expectations).

Note: a pre-existing cargo fmt drift in meshcentral-agent-fetch (untouched by this PR) trips a full-workspace fmt --all --check. Flagging separately; not addressed here to keep the diff scoped.

🤖 Generated with Claude Code

## What Server-side half of VS-24 (paired with VA-28 slice 6): rename the two agent-facing WebSocket endpoints off the legacy MeshCentral `.ashx` handler names to versioned, vervain-branded paths, and delete the old ones outright (no deprecation alias, per the no-active-deployments guidance). ## Decisions (from the issue's open questions) - Versioning prefix: yes, `/api/v1/`. Lets a future protocol rev ship under `/api/v2/` without breaking v1 agents. - Names: `/api/v1/agent` (control channel) and `/api/v1/relay` (per-tunnel relay). Composes the chosen `/api/...` namespace with the `/v1/` version. - Relay query params renamed in lockstep: `p` becomes `usage`, `nodeid` becomes `agent_id`. `id`, `rauth`, `auth`, `browser`, `slowrelay` unchanged. ## Changes - New `meshcentral-web/src/wire_paths.rs`: single source of truth for the path + param-name constants. - Router (`build_router`): old routes removed, new `/api/v1/agent` + `/api/v1/relay` registered (no-domain and `/:domain/...` forms). Dropped the `/relay.ashx` legacy alias. - `RelayQuery`: `nodeid` -> `agent_id`, `p` -> `usage` (wire keys); internal field names unchanged. - `.msh` `MeshServer=` URL builder (`meshsettings`) and the CSRF-safe-path allowlist (`security`) reference the constant. - SPA relay client (`public/scripts/agent-redir-ws-0.1.1.js` + its minified twin, `public/samples/relay.js`, `views/messenger.handlebars`): emit `/api/v1/relay` with `usage`/`agent_id`. The minified file was edited by targeted string replacement. - Comments, tracing messages, and Prometheus metric descriptions reworded so the AC grep is clean. - README gains an "Agent wire paths (VS-24)" paragraph. ## Acceptance criteria - [x] New control-channel and relay paths picked and documented (README + `wire_paths.rs`). - [x] Old routes removed from the server. - [x] `grep -rE "agent\.ashx|meshrelay\.ashx"` returns zero hits (verified). - [ ] Paired agent-side change merged (VA-28) - cross-link once opened. This server PR merges first; the agent only consumes server-supplied relay URLs, and its control-channel path comes from `MeshServer=` (regenerate `.msh`). - [x] README paragraph calls out the rename. ## Out of scope (unchanged) `/control.ashx` (user UI channel) and `/mcptunnel.ashx` (VS-22 MCP rendezvous). Only the two paths named in VS-24 move. ## Verification `cargo clippy --workspace --all-targets -- -D warnings` clean; touched crates `fmt --check` clean; `cargo test -p meshcentral-web --lib` = 404 passed (incl. updated `build_ws_url` expectations). Note: a pre-existing `cargo fmt` drift in `meshcentral-agent-fetch` (untouched by this PR) trips a full-workspace `fmt --all --check`. Flagging separately; not addressed here to keep the diff scoped. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

nrupard added 1 commit

2026-05-21 19:27:09 +02:00

chore(rebrand): rename agent + relay URL paths to /api/v1/* (VS-24)

Check / fmt + clippy + build + tests (pull_request) Failing after 3s

Details

3616db7f13

Server-side half of the VA-28 URL-path rebrand. The two agent-facing WebSocket endpoints were named after the legacy MeshCentral ASP.NET SPA with a vestigial .ashx handler suffix; rename them to versioned, vervain-branded paths and delete the old ones outright (no compatibility alias, per the no-active-deployments guidance).

- Agent control channel: was the legacy .ashx-suffixed agent path, now /api/v1/agent (per-domain: /:domain/api/v1/agent).
- Per-tunnel relay: was the legacy .ashx-suffixed relay path, now /api/v1/relay (per-domain: /:domain/api/v1/relay).
- Relay query params renamed in lockstep: p -> usage, nodeid -> agent_id (id, rauth, auth, browser, slowrelay unchanged).
- Dropped the /relay.ashx legacy alias entirely.

The /api/v1/ prefix lets a future protocol rev ship under /api/v2/ without breaking v1 agents.

Canonical strings live in a new meshcentral-web/src/wire_paths.rs module, referenced by the router (build_router), the .msh MeshServer= URL builder (meshsettings), and the CSRF-safe-path allowlist (security). The browser-side SPA relay client (public/scripts/agent-redir-ws-*.js, public/samples/relay.js, views/messenger.handlebars) hard-codes the same paths and now emits /api/v1/relay with usage/agent_id params. Comments, tracing messages, and the monitoring metric descriptions that referenced the old names were reworded so `grep -rE "agent\.ashx|meshrelay\.ashx"` returns zero hits. README gains an "Agent wire paths" paragraph documenting the rename.

Out of scope (unchanged): /control.ashx (user UI channel) and /mcptunnel.ashx (VS-22 MCP rendezvous); only the two paths named in VS-24 move. The paired agent-side change ships under VA-28.

Tests: meshsettings build_ws_url expectations updated to /api/v1/agent; full meshcentral-web lib suite (404 tests) passes. cargo clippy --workspace --all-targets -- -D warnings clean; touched crates fmt --check clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

nrupard added 1 commit

2026-05-21 19:34:22 +02:00

docs(mcp): fix stale nodeid wording in relay scope-check comment

Check / fmt + clippy + build + tests (pull_request) Failing after 6s

Details

66a4ef4aad

The relay query field was renamed nodeid -> agent_id in this branch; the scope-check comment still referenced "the query's nodeid". Update it to agent_id (and "n (node)") to match the code. Comment-only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

nrupard added 1 commit

2026-05-21 19:35:25 +02:00

docs(mcp): finish stale wire-param wording in relay module doc

Check / fmt + clippy + build + tests (pull_request) Failing after 2s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

ce6367d7da

Follow-on to the scope-check comment fix: the meshrelay module doc and RelayQuery struct doc still referenced the pre-rename `p` and `nodeid` query params. Update to `usage`/`agent_id` so the whole file matches the renamed wire keys. Comment-only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>