feat(control): isolated Meshrooms application channels over 0x50 - #135
Conversation
Add APPSEND/APPRECV/APPINFO and MGAPP1 framing so room traffic lives on per-channel queues. Legacy SEND/RECV/MSGS stay on the unframed path. Honor MESHGUARD_CONTROL_PATH on bind and CLI connect, and allow --gossip-port / MESHGUARD_GOSSIP_PORT for isolated candidate daemons. Co-authored-by: Igor Lins e Silva <igorls@users.noreply.github.com>
The previous case used a space inside the frame, which parse() treats as the channel/payload separator rather than an illegal channel character. Co-authored-by: Igor Lins e Silva <igorls@users.noreply.github.com>
Explicit --gossip-port or MESHGUARD_GOSSIP_PORT values that are missing, empty, zero, non-numeric, or outside 1-65535 now refuse to start instead of silently falling back to 51821. Unset flag and env keep the default. Co-authored-by: Igor Lins e Silva <igorls@users.noreply.github.com>
Zig 0.16 rejects declarations between container fields. Co-authored-by: Igor Lins e Silva <igorls@users.noreply.github.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2bb4223615
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
A few behavioral/documentation inconsistencies in the newly added app-channel/control-path logic should be corrected to match the stated “fail closed / no fallback” guarantees before merging.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 2
Open (4)
What changed in this PR
This PR extends MeshGuard’s control-plane messaging by introducing MGAPP1-framed, per-application channels inside the existing encrypted 0x50 payload, preventing Meshrooms traffic from being consumed by the legacy destructive RECV queue. It also improves testability/safety for running candidate daemons alongside production by making control socket and gossip-port selection explicit and configurable.
Changes:
- Added
MGAPP1 <channel> <payload>framing + validation and demuxed per-channel ring buffers (APPSEND/APPRECV/APPINFO) alongside the legacySEND/RECVqueue. - Added CLI wrappers (
meshguard appsend|apprecv|appinfo) and updated control socket path handling viaMESHGUARD_CONTROL_PATHand--control-path. - Implemented fail-closed gossip port resolution via
--gossip-port/MESHGUARD_GOSSIP_PORTwith tests and documentation updates.
| File | Description |
|---|---|
src/services/control.zig |
Implements app-channel demux/queues, new APP* IPC commands, control path env/flag behavior, and Windows pipe path support. |
src/protocol/app_channel.zig |
New MGAPP1 framing/validation/parser/encoder and max-payload constants with unit tests. |
src/main.zig |
Adds CLI commands for app channels; adds --gossip-port / --control-path plumbing and validation messaging. |
src/lib.zig |
Exposes protocol.AppChannel in the library surface and test harness. |
src/config.zig |
Adds fail-closed gossip port parsing/resolution and corresponding unit tests; exports getEnvVarOwned. |
docs/reference/modules.md |
Documents the new app_channel.zig module and updated control responsibilities. |
docs/reference/cli.md |
Documents new CLI commands and new env/flag overrides for control path and gossip port. |
docs/reference/app-channels.md |
New reference doc for IPC commands, wire format, payload sizing, and isolation semantics. |
docs/guide/configuration.md |
Adds --gossip-port / --control-path to configuration guidance. |
docs/concepts/wire-protocol.md |
Updates 0x50 payload docs and adds a note about optional MGAPP1 application framing. |
CHANGELOG.md |
Records the new app-channel feature and new control/gossip override behavior. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bd1247fa59
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 45874f0e9e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9e281c23f4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 79ceb996e3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
MeshGuard's single destructive receive queue lets legacy workers consume application traffic. This adds isolated application channels inside the existing encrypted 0x50 payload, with bounded queues and explicit control endpoints so test daemons can run beside existing ones.
Room admission, durable retry and remote storage receipts remain application responsibilities. See the channel contract.
Validation: 174 Windows Zig tests passed (one Unix-only socket lifecycle test skipped), and the ReleaseFast build passed. Ten Windows CLI regressions passed (one Unix-only path test skipped), including exact recovery of a maximum-size escaped payload over whole and fragmented byte-mode pipe responses. CI runs the CLI fixtures on Windows, Linux and macOS and both Linux crypto backends. Tests also cover the 952-byte ceiling for every channel, invalid UTF-8 rejection before queueing, boundary whitespace through encryption, queue isolation, empty/malformed/oversize frames, channel-slot reuse, positional channels, startup validation and Unix socket lifecycle safety. Isolated no-TUN daemon tests verify fatal endpoint collisions, fragmented command assembly, subsequent requests and graceful shutdown. Windows reserves its pipe name synchronously and joins its listener thread during cleanup.
Earlier isolated Windows/Linux Meshrooms qualification exercised the a7c7186 transport candidate with real messages and replies. That evidence predates these review fixes; this revision is validated separately by the regression tests and CI. No running user daemon or WormDB submodule pin was changed.