Skip to content

Publish client echo-login example, API docs, and ExecPlan#477

Merged
leynos merged 3 commits intomainfrom
docs-wireframe-client-docs-examples-0tr5b7
Feb 24, 2026
Merged

Publish client echo-login example, API docs, and ExecPlan#477
leynos merged 3 commits intomainfrom
docs-wireframe-client-docs-examples-0tr5b7

Conversation

@leynos
Copy link
Copy Markdown
Owner

@leynos leynos commented Feb 23, 2026

Summary

  • Adds a runnable client example that connects to the echo server, sends a login, and decodes the echoed acknowledgement, plus expanded client docs.
  • Introduces an ExecPlan doc to guide implementation, testing, and gating for the client docs/examples work.
  • Updates roadmap and design docs to reflect completion of roadmap items 10.4.1 and 10.4.2.

Changes

  • New runnable example and docs plan
    • Add docs/execplans/10-4-1-client-documentation-and-examples.md describing the Publish client echo-login example and client API documentation plan.
  • Runnable client example
    • Introduce examples/client_echo_login.rs (runnable client example) that:
      • connects to 127.0.0.1:7878,
      • sends a typed login request,
      • decodes the echoed response as the login acknowledgement,
      • prints a clear success line.
    • Register the new example in Cargo.toml with required-features = ["examples"].
    • The example assumes examples/echo.rs is running and documents that requirement.
  • Tests and validation
    • Extend tests/client_runtime.rs with a focused rstest-based unit/integration test for the login round-trip.
    • Extend behavioural tests with rstest-bdd v0.5.0 support by updating:
      • tests/features/client_runtime.feature
      • tests/fixtures/client_runtime.rs
      • tests/steps/client_runtime_steps.rs
      • tests/scenarios/client_runtime_scenarios.rs
    • Reuse existing client-runtime test infrastructure where possible.
  • Documentation updates
    • Update docs/users-guide.md with configuration tables, lifecycle guidance, and runnable-example usage.
    • Update docs/wireframe-client-design.md with the design rationale for the login-acknowledgement contract and the end-to-end flow.
  • Roadmap and governance
    • Update docs/roadmap.md to mark 10.4.1 and 10.4.2 as done.
    • Ensure the new ExecPlan aligns with AGENTS.md style and gating requirements.

Plan of work (highlights)

The ExecPlan outlines six stages (A–F):

  • A. Contract confirmation and scaffolding mapping (no code changes)
  • B. Runnable example implementation
  • C. Unit/integration validation with rstest
  • D. Behavioural validation with rstest-bdd
  • E. Documentation and design-decision updates
  • F. Roadmap closure and full validation

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:

  • The client_echo_login example exists and runs with cargo run --example client_echo_login --features examples, assuming the echo server is running.
  • The client connects to the echo server, sends a login request, and decodes a typed acknowledgement.
  • New rstest-based unit/integration coverage validates the login round-trip.
  • New rstest-bdd scenario validates the same behaviour at the feature level.
  • docs/users-guide.md and docs/wireframe-client-design.md include configuration guidance, lifecycle diagrams, troubleshooting, and design rationale.
  • The roadmap marks 10.4.1 and 10.4.2 as completed.
  • All gated checks (fmt, lint, tests, doc checks) pass.

How to run locally

  • Build and run the runnable client example (requires echo server):
    • Start the echo server (existing example): cargo run --example echo --features examples
    • Run the client example: cargo run --example client_echo_login --features examples
  • Targeted tests:
    • cargo test --test client_runtime -- --nocapture
    • make test-bdd
  • Quality gates:
    • make check-fmt
    • make lint
    • make test
    • make test-doc
    • make doctest-benchmark
  • Documentation checks:
    • make fmt
    • make markdownlint
    • make nixie

Interfaces and dependencies

  • No changes to public API signatures in src/client/—only an additional runnable example and tests.
  • Dependencies remain within existing crates (tokio, rstest, rstest-bdd); no new external dependencies.
  • Artifacts include the new ExecPlan doc and updated docs and tests.

Artifacts and notes

  • New ExecPlan doc: docs/execplans/10-4-1-client-documentation-and-examples.md
  • Runnable example: examples/client_echo_login.rs (registered under the examples feature)
  • Documentation and roadmap updates as described above

Idempotence and recovery

  • Edits are additive and repeatable.
  • Re-running tests and gates is safe.
  • If port contention occurs during manual runs, stop and retry.
  • If BDD step matching fails, rename new steps with a client-runtime prefix and retry.

Review guidance

  • Verify the runnable example compiles and runs against a running echo server.
  • Confirm no public API changes and that all tests/doc checks pass.
  • Ensure docs are consistent across users-guide and design docs, with mirrored tables and diagrams.
  • Validate that the ExecPlan doc reflects gating and progress accurately.

📎 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:

  • Introduce a client_echo_login example that connects to the echo server, sends a typed login request, and decodes the echoed acknowledgement.
  • Document a concrete client login flow using correlated envelopes in both the user guide and design docs.

Bug Fixes:

  • Correct AppDataStore doctest imports so examples compile against the actual module path.
  • Fix interleaved push queue test helpers to properly propagate errors and avoid unused_must_use warnings under strict linting.

Enhancements:

  • Add client configuration reference tables, lifecycle sequence diagrams, troubleshooting guidance, and a decision record for the echo-based login acknowledgement contract.
  • Refine client runtime test and BDD fixtures to capture login acknowledgement behaviour without altering public client APIs.
  • Document and track the client documentation and examples work through a new ExecPlan aligned with repository governance.

Build:

  • Register the new client_echo_login example in Cargo.toml under the existing examples feature gate.

Documentation:

  • Create an ExecPlan for the client echo-login example and documentation work, including constraints, stages, decisions, and validation evidence.
  • Update the user guide and client design documents with configuration references, lifecycle diagrams, runnable commands, and rationale for the login acknowledgement semantics.
  • Mark roadmap items 10.4.1 and 10.4.2 as complete to reflect the shipped client example and documentation.

Tests:

  • Add rstest-based integration coverage to verify that the client decodes echoed login acknowledgements from the sample echo server.
  • Extend rstest-bdd client runtime scenarios, steps, and fixtures to cover the login request/acknowledgement round trip.
  • Tighten interleaved push queue test utilities and scenarios to propagate TestResult from async setup functions and keep behavioural tests lint-clean.

@sourcery-ai
Copy link
Copy Markdown
Contributor

sourcery-ai Bot commented Feb 23, 2026

Reviewer's Guide

Implements 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 example

sequenceDiagram
    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
Loading

Class diagram for echo-login example message and client types

classDiagram
    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
Loading

File-Level Changes

Change Details Files
Add runnable client echo-login example wired to the existing echo server and correlation-aware API.
  • Create examples/client_echo_login.rs that connects to 127.0.0.1:7878, sends a typed LoginRequest in an Envelope, receives the echoed Envelope, decodes LoginAck, and logs success with correlation ID.
  • Initialize tracing subscriber in the example and enforce a username match, returning an error on mismatch.
  • Register the new example in Cargo.toml under the existing examples feature gate.
examples/client_echo_login.rs
Cargo.toml
Extend client runtime tests with rstest-based login acknowledgement coverage and align BDD fixtures/steps/scenarios with the new behaviour.
  • Introduce a LoginAck type and add an rstest-parametrized test that verifies client.call<Login, LoginAck> round-trips usernames through the sample echo server.
  • Extend the ClientRuntimeWorld fixture with LoginRequest/LoginAck types, world state for login acknowledgements, and helper methods to send a login and verify the decoded acknowledgement.
  • Add new BDD steps and a scenario for sending a login request and validating the echoed acknowledgement, reusing the existing client-runtime world and echo server setup.
tests/client_runtime.rs
tests/fixtures/client_runtime.rs
tests/steps/client_runtime_steps.rs
tests/scenarios/client_runtime_scenarios.rs
tests/features/client_runtime.feature
Improve client documentation with configuration reference tables, lifecycle sequence diagrams, runnable example usage, troubleshooting, and a decision record for the login-acknowledgement contract.
  • Add client configuration reference tables to the design and user guide docs, covering serializer, codec framing, socket options, preamble, and lifecycle hooks.
  • Embed Mermaid sequence diagrams describing client connection lifecycle, including optional preamble, hooks, and shutdown, with screen-reader guidance.
  • Document the runnable echo-login example, including the commands to run both server and client, and add troubleshooting guidance for common client issues such as frame length mismatches, preamble failures, correlation mismatches, streaming contention, and disconnects.
  • Record a decision section in the client design doc stating that login acknowledgement is represented as the echoed login payload decoded as LoginAck.
docs/wireframe-client-design.md
docs/users-guide.md
Introduce an ExecPlan for roadmap item 10.4 and mark roadmap entries 10.4.1 and 10.4.2 complete.
  • Add a detailed ExecPlan document describing stages A–F for implementing the client documentation and examples, including constraints, risks, validation gates, and final outcomes.
  • Update roadmap checkboxes to mark publication of the runnable echo-login example and the extended client docs as done.
docs/execplans/10-4-1-client-documentation-and-examples.md
docs/roadmap.md
Fix and harden tests and doctests needed for clean runs under strict warning and doc gates.
  • Change interleaved push test helpers and fixtures so async setup closures return TestResult and propagate failures via the push_expect! macro, fixing unused_must_use and error-handling issues across interleaved push tests.
  • Adjust doctest examples in the app data store to import AppDataStore from its module path rather than assuming a crate root re-export.
  • Ensure BDD and actor tests compile and run cleanly with RUSTFLAGS=-D warnings by updating signatures and adding explicit Ok(()) returns where needed.
tests/interleaved_push_queues.rs
tests/fixtures/interleaved_push_queues.rs
tests/common/interleaved_push_helpers.rs
src/app_data_store.rs

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Feb 23, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5aa8e80 and c7cb7b0.

📒 Files selected for processing (16)
  • Cargo.toml
  • docs/execplans/10-4-1-client-documentation-and-examples.md
  • docs/roadmap.md
  • docs/users-guide.md
  • docs/wireframe-client-design.md
  • examples/client_echo_login.rs
  • examples/support/echo_login_contract.rs
  • src/app_data_store.rs
  • tests/client_runtime.rs
  • tests/common/interleaved_push_helpers.rs
  • tests/features/client_runtime.feature
  • tests/fixtures/client_runtime.rs
  • tests/fixtures/interleaved_push_queues.rs
  • tests/interleaved_push_queues.rs
  • tests/scenarios/client_runtime_scenarios.rs
  • tests/steps/client_runtime_steps.rs

Summary by CodeRabbit

  • New Features

    • Runnable client example added demonstrating login with the echo server.
  • Documentation

    • Expanded client configuration reference, lifecycle diagrams, runnable walkthrough and troubleshooting for framing, preamble, correlation and disconnect handling.
  • API

    • Login acknowledgement type changed: now carries username (String) instead of a simple ok flag.
  • Tests

    • Added scenarios and fixtures to cover login round-trips and acknowledgement decoding.

Walkthrough

Summarise 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

Cohort / File(s) Summary
Example & Manifest
Cargo.toml, examples/client_echo_login.rs
Add new example client_echo_login and register it in Cargo.toml. Implements a client that sends a LoginRequest in an Envelope and awaits a correlated LoginAck.
Shared Contract
examples/support/echo_login_contract.rs
Add LOGIN_ROUTE_ID, LoginRequest, and LoginAck contract types used by example and tests.
Documentation & Planning
docs/execplans/10-4-1-client-documentation-and-examples.md, docs/roadmap.md, docs/users-guide.md, docs/wireframe-client-design.md
Add execution plan, mark roadmap items complete, extend client docs with configuration reference, envelope/correlation example, sequence diagrams, and troubleshooting guidance. Update LoginAck shape in docs to username: String.
BDD Scenarios & Steps
tests/features/client_runtime.feature, tests/scenarios/client_runtime_scenarios.rs, tests/steps/client_runtime_steps.rs
Add scenario "Client decodes echoed login acknowledgement" and step defs for sending login request and verifying acknowledgement.
Test Fixtures & Tests
tests/fixtures/client_runtime.rs, tests/client_runtime.rs, tests/scenarios/client_runtime_scenarios.rs
Add login state to ClientRuntimeWorld, implement send_login_request and verify_login_acknowledgement, update tests to use shared contract types and validate correlated responses.
Test Helper Error Propagation
tests/common/interleaved_push_helpers.rs, tests/fixtures/interleaved_push_queues.rs, tests/interleaved_push_queues.rs
Change setup futures to return TestResult, propagate errors via ?, and add explicit Ok(()) where required to enable early-return error handling in test helpers.
Documentation Example Fixes
src/app_data_store.rs
Adjust doctest references to fully-qualified wireframe::app_data_store::AppDataStore paths; no functional change.

Sequence Diagram

sequenceDiagram
    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
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

✉️ Enclose the login in an envelope so neat,
The echo bounces back a friendly greet,
Correlation ties the call and the reply,
Username returned — the client winks, “Aye!” ✨

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarises the three main additions: a runnable client example for echo-login, expanded API documentation, and an ExecPlan document.
Description check ✅ Passed The description comprehensively covers all changes in the changeset, including the new example, tests, documentation updates, and roadmap changes, with clear validation and acceptance criteria.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches
  • 📝 Generate docstrings (stacked PR)
  • 📝 Generate docstrings (commit on current branch)
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch docs-wireframe-client-docs-examples-0tr5b7

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

@leynos leynos changed the title Publish client echo-login example and client API docs Publish client echo-login example, API docs, and ExecPlan Feb 23, 2026
@leynos leynos marked this pull request as ready for review February 23, 2026 21:58
Copy link
Copy Markdown
Contributor

@sourcery-ai sourcery-ai Bot left a comment

Choose a reason for hiding this comment

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

Hey - I've left some high level feedback:

  • 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.
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.

Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.

@coderabbitai coderabbitai Bot added the codex label Feb 23, 2026
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

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

📥 Commits

Reviewing files that changed from the base of the PR and between 909a297 and 5aa8e80.

📒 Files selected for processing (15)
  • Cargo.toml
  • docs/execplans/10-4-1-client-documentation-and-examples.md
  • docs/roadmap.md
  • docs/users-guide.md
  • docs/wireframe-client-design.md
  • examples/client_echo_login.rs
  • src/app_data_store.rs
  • tests/client_runtime.rs
  • tests/common/interleaved_push_helpers.rs
  • tests/features/client_runtime.feature
  • tests/fixtures/client_runtime.rs
  • tests/fixtures/interleaved_push_queues.rs
  • tests/interleaved_push_queues.rs
  • tests/scenarios/client_runtime_scenarios.rs
  • tests/steps/client_runtime_steps.rs

Comment thread docs/execplans/10-4-1-client-documentation-and-examples.md Outdated
Comment thread docs/execplans/10-4-1-client-documentation-and-examples.md
Comment thread docs/users-guide.md
Comment thread docs/wireframe-client-design.md
Comment thread examples/client_echo_login.rs Outdated
Comment thread tests/fixtures/client_runtime.rs
leynos and others added 3 commits February 24, 2026 13:43
- 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.
@devboxerhub devboxerhub Bot force-pushed the docs-wireframe-client-docs-examples-0tr5b7 branch from 5aa8e80 to c7cb7b0 Compare February 24, 2026 13:46
@leynos leynos merged commit 7b7f995 into main Feb 24, 2026
6 checks passed
@leynos leynos deleted the docs-wireframe-client-docs-examples-0tr5b7 branch February 24, 2026 19:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant