Publish client echo-login example, API docs, and ExecPlan#477
Conversation
Reviewer's GuideImplements a runnable client echo-login example wired into Cargo, adds corresponding unit and BDD tests for the login round-trip, expands client configuration and lifecycle documentation (including troubleshooting and decision rationale), introduces an ExecPlan doc for roadmap item 10.4, and updates roadmap and minor test/doc issues needed to keep all quality gates passing. Sequence diagram for client echo-login round trip examplesequenceDiagram
actor User
participant ClientApp as client_echo_login
participant Builder as WireframeClientBuilder
participant Client as WireframeClient
participant EchoServer as echo_example
User->>EchoServer: start echo server (cargo run --example echo)
User->>ClientApp: run client_echo_login example
ClientApp->>Builder: WireframeClient::builder()
ClientApp->>Builder: connect(addr)
Builder->>Client: create WireframeClient
ClientApp->>Client: login.to_bytes()
ClientApp->>Client: Envelope::new(LOGIN_ROUTE_ID, None, payload)
ClientApp->>Client: call_correlated(envelope)
Client->>EchoServer: send Envelope (route_id=LOGIN_ROUTE_ID)
EchoServer-->>Client: echo Envelope (same payload, correlation_id)
Client-->>ClientApp: Envelope response
ClientApp->>ClientApp: LoginAck::from_bytes(response.payload_bytes())
ClientApp->>ClientApp: compare ack.username with login.username
alt usernames match
ClientApp->>ClientApp: log decoded login acknowledgement
ClientApp-->>User: exit successfully
else mismatch
ClientApp->>ClientApp: log error and return Err
ClientApp-->>User: example exits with error
end
Class diagram for echo-login example message and client typesclassDiagram
class LoginRequest {
+String username
+to_bytes() Result<Vec<u8>, Error>
}
class LoginAck {
+String username
+from_bytes(bytes: &[u8]) Result<(LoginAck, usize), Error>
}
class Envelope {
+u32 route_id
+Option<u64> correlation_id
+Vec<u8> payload
+new(route_id: u32, correlation_id: Option<u64>, payload: Vec<u8>) Envelope
+payload_bytes() &[u8]
+correlation_id() Option<u64>
}
class WireframeClientBuilder {
+builder() WireframeClientBuilder
+serializer(serializer: Serializer) WireframeClientBuilder
+codec_config(config: ClientCodecConfig) WireframeClientBuilder
+socket_options(options: SocketOptions) WireframeClientBuilder
+with_preamble(preamble: T) WireframeClientBuilder
+preamble_timeout(timeout: Duration) WireframeClientBuilder
+on_connection_setup(callback: Fn)
+on_connection_teardown(callback: Fn)
+on_error(callback: Fn)
+connect(addr: SocketAddr) WireframeClient
}
class WireframeClient {
+call_correlated(request: Envelope) Future<Envelope>
+close() Future<()>
}
class EchoLoginExample {
+main() Result<(), Error>
}
EchoLoginExample --> WireframeClientBuilder : uses
WireframeClientBuilder --> WireframeClient : constructs
EchoLoginExample --> LoginRequest : creates
EchoLoginExample --> LoginAck : decodes
EchoLoginExample --> Envelope : wraps payload
WireframeClient --> Envelope : sends and receives
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review infoConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro 📒 Files selected for processing (16)
Summary by CodeRabbit
WalkthroughSummarise the addition of a runnable client echo-login example, supporting documentation and execution plan, BDD scenarios and test fixture updates, a shared echo-login contract, and test-helper error-propagation changes; no behavioural changes to runtime library APIs. Changes
Sequence DiagramsequenceDiagram
participant Client as Client (Wireframe)
participant Echo as Echo Server
participant Envelope as Envelope/Correlation
rect rgba(100,150,250,0.5)
Client->>Envelope: Build Envelope(LoginRequest{username})
end
rect rgba(120,200,150,0.5)
Client->>Echo: Send Envelope (route = LOGIN_ROUTE_ID)
Echo->>Echo: Echo payload back (retain correlation_id)
end
rect rgba(250,200,100,0.5)
Echo->>Client: Return Envelope(LoginAck) (correlated)
Client->>Envelope: Await correlated response
Client->>Client: Decode Envelope payload -> LoginAck
Client->>Client: Verify username matches and log result
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The login request/acknowledgement types are now defined separately in the example,
tests/client_runtime.rs, andtests/fixtures/client_runtime.rs; consider centralising these into a shared module to keep the echo-login contract consistent and reduce the chance of drift. - The echo-login docs and the new
client_echo_loginexample useEnvelope+call_correlated, while the newclient_decodes_echoed_login_acknowledgementtest uses a plainclient.call<Login, LoginAck>; it may be clearer to align the test with the documented pattern or explicitly document when to prefer each style.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The login request/acknowledgement types are now defined separately in the example, `tests/client_runtime.rs`, and `tests/fixtures/client_runtime.rs`; consider centralising these into a shared module to keep the echo-login contract consistent and reduce the chance of drift.
- The echo-login docs and the new `client_echo_login` example use `Envelope` + `call_correlated`, while the new `client_decodes_echoed_login_acknowledgement` test uses a plain `client.call<Login, LoginAck>`; it may be clearer to align the test with the documented pattern or explicitly document when to prefer each style.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/execplans/10-4-1-client-documentation-and-examples.md`:
- Around line 315-361: Replace every 4-space indented command block in the
section (the baseline/targeted checks, full Rust quality gates, documentation
quality gates, and the Manual runtime proof example commands) with fenced code
blocks annotated with the sh language identifier; i.e., wrap each command
sequence (e.g., the sequences starting with "set -o pipefail" and the cargo/make
commands and the Terminal A/B examples) inside ```sh ... ``` fences so each
indented block becomes a fenced shell code block with the language identifier.
- Line 100: Update the three documented items to follow en-GB-oxendict and
punctuation rules: in the checklist entries that read "- - [x] (2026-02-23
00:42Z) Stage C complete: added parameterized `rstest`" and "- - [x]
(2026-02-23 01:55Z) Stage F complete: updated roadmap checkboxes" insert a comma
after the timestamp and change "parameterized" to British spelling
"parameterised" so they read "- - [x] (2026-02-23 00:42Z), Stage C complete:
added parameterised `rstest`" and "- - [x] (2026-02-23 01:55Z), Stage F
complete: updated roadmap checkboxes"; for the line containing "coverage
across:" remove or reword the colon to a standard phrase such as "coverage in
the following files:"; and in the sentence "If manual example run fails" insert
the article "a" so it reads "If a manual example run fails".
In `@docs/users-guide.md`:
- Around line 1638-1641: The sentence describing transport disconnects is
missing the article "a"; update the wording around
ClientError::Wireframe(WireframeError::Io(_)) so it reads "apply a
reconnect/retry policy at the call site" instead of "apply reconnect/retry
policy at the call site" to correct the grammar.
In `@docs/wireframe-client-design.md`:
- Around line 219-251: The doc example's main function return type
std::io::Result<()> is incorrect because the ? operator is used on
AddrParseError (from "127.0.0.1:7878".parse()), ClientError (from
WireframeClient::call_correlated) and bincode::error::DecodeError (from
LoginAck::from_bytes) which do not convert to io::Error; change the signature of
the async main (annotated with #[tokio::main]) to return a generic error like
Result<(), Box<dyn std::error::Error>> so all three error types can be
propagated with ? without additional conversions.
In `@examples/client_echo_login.rs`:
- Around line 51-56: The log currently emits duplicate "message" fields by
passing %message and a literal event message; remove the temporary message
variable and instead call error! with typed structured fields (e.g., sent =
%login.username, received = %ack.username, "login acknowledgement mismatch"),
then construct the std::io::Error string independently with format!(...) and
return that error (from the same if branch that checks ack.username !=
login.username).
In `@tests/fixtures/client_runtime.rs`:
- Around line 267-279: In send_login_request, clear the stored acknowledgement
at the start to avoid stale LoginAck persisting on failure: inside the
send_login_request method (before taking self.client and calling client.call),
set *self.login_ack.borrow_mut() = None (and keep the existing reset of
*self.last_error.borrow_mut() = None after the call if desired); this ensures
login_ack is cleared before client.call::<_, LoginAck>(&login).await so a failed
call cannot leave an old ack behind.
ℹ️ Review info
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (15)
Cargo.tomldocs/execplans/10-4-1-client-documentation-and-examples.mddocs/roadmap.mddocs/users-guide.mddocs/wireframe-client-design.mdexamples/client_echo_login.rssrc/app_data_store.rstests/client_runtime.rstests/common/interleaved_push_helpers.rstests/features/client_runtime.featuretests/fixtures/client_runtime.rstests/fixtures/interleaved_push_queues.rstests/interleaved_push_queues.rstests/scenarios/client_runtime_scenarios.rstests/steps/client_runtime_steps.rs
- Add a new runnable client example `client_echo_login` showcasing login request and decoded acknowledgement round-trip against echo server. - Extend integration (`rstest`) and behavioural (`rstest-bdd`) tests to validate the new login contract. - Update user guide and client design docs with configuration tables, lifecycle diagrams, troubleshooting guidance, and design decision notes. - Register the example under existing examples feature gate without introducing new dependencies or changing public APIs. - Mark roadmap items 10.4.1 and 10.4.2 complete. - Ensure all quality gates pass including formatting, linting, testing, and documentation checks. This adds comprehensive client-side documentation and usage examples to improve usability and onboarding. Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>
- Added `examples/client_echo_login.rs` demonstrating a client login against the echo server. - Registered new example in `Cargo.toml`. - Added integration tests in `tests/client_runtime.rs` with `rstest` coverage for login acknowledgement decoding. - Extended BDD feature, scenarios, and steps to cover the new login acknowledgement behavior. - Expanded client user guide and design documentation with configuration tables, lifecycle diagrams, troubleshooting, and runnable example instructions. - Marked roadmap items 10.4.1 and 10.4.2 complete. Also included repository health fixes: - Fixed `unused_must_use` warnings in interleaved push queue test fixtures for clean BDD test runs under strict warnings. - Corrected doctest imports in `src/app_data_store.rs` for accurate documentation. Validation evidence includes all tests passing, formatting, linting, documentation, and manual runtime proof of the new client example. Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>
Centralize the echo-login request/ack contract in a shared module and\nreuse it from the example and client runtime tests to reduce drift.\n\nAlign login acknowledgement coverage with the documented\nEnvelope+call_correlated flow, and harden the client runtime fixture by\nclearing stale acknowledgement state before each login call.\n\nApply review-driven documentation fixes in the execplan and client docs,\nincluding shell code fences, en-GB wording, grammar corrections, and a\ncorrect generic error type in the design example.
5aa8e80 to
c7cb7b0
Compare
Summary
Changes
Plan of work (highlights)
The ExecPlan outlines six stages (A–F):
Each stage includes explicit go/no-go criteria to ensure alignment with the echo contract and public API stability. The plan also specifies commands and gates to validate the implementation (see the ExecPlan document for details).
Validation and acceptance
Acceptance criteria:
How to run locally
Interfaces and dependencies
Artifacts and notes
Idempotence and recovery
Review guidance
📎 Task: https://www.devboxer.com/task/1cb36cd4-f23f-4bea-aba6-22565520ccb1
Summary by Sourcery
Add a runnable client echo-login example, strengthen client runtime validation, and expand documentation and roadmap to cover the new client behaviour and configuration guidance.
New Features:
Bug Fixes:
Enhancements:
Build:
Documentation:
Tests: