Document async-stream as canonical Response::Stream helper#154
Conversation
Reviewer's GuideThis PR streamlines streaming documentation by removing the FrameSink proposal in favor of the async-stream crate as the canonical Response::Stream helper, applies formatting and numbering fixes in key design tables, and updates the roadmap to mark async-stream docs complete while adding a follow-up example task. Class diagram for Response and async-stream usageclassDiagram
class Response {
<<enum>>
+Vec(Vec<Frame>)
+Stream(Pin<Box<dyn Stream<Item = Result<Frame, E>> + Send>>)
+Error(E)
}
class Frame
class E
class Stream
class async_stream {
+stream!
+try_stream!
}
Response --> Frame : uses
Response --> Stream : uses
Stream <.. async_stream : generated by
async_stream ..> Response : recommended for Stream variant
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Warning Rate limit exceeded@leynos has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 0 minutes and 19 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (2)
Summary by CodeRabbit
Summary by CodeRabbit
WalkthroughThis update refines documentation by improving markdown formatting, correcting list numbering, and clarifying explanations in several design documents. No technical logic, control flow, or public interfaces are changed; all modifications focus on presentation, readability, and concise communication within the documentation. Changes
Sequence Diagram(s)No sequence diagram generated, as changes are limited to documentation formatting and clarifications. Possibly related PRs
Poem
✨ Finishing Touches🧪 Generate Unit Tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🔭 Outside diff range comments (1)
docs/asynchronous-outbound-messaging-design.md (1)
687-695: Success-criteria table breaches 80-column ruleSeveral cells run far beyond 80 columns. Consider wrapping lines inside the
cells or disabling MD013 per line to avoid future lint noise.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (4)
docs/asynchronous-outbound-messaging-design.md(4 hunks)docs/asynchronous-outbound-messaging-roadmap.md(1 hunks)docs/multi-packet-and-streaming-responses-design.md(3 hunks)docs/the-road-to-wireframe-1-0-feature-set-philosophy-and-capability-maturity.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**/*.md`: * Avoid 2nd person or 1st person pronouns ("I", "you", "we") * Use en...
**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")
- Use en-oxendic spelling and grammar.
- Paragraphs and bullets must be wrapped to 80 columns, except where a long URL would prevent this (in which case, silence MD013 for that line)
- Code blocks should be wrapped to 120 columns.
- Headings must not be wrapped.
⚙️ Source: CodeRabbit Configuration File
List of files the instruction was applied to:
docs/asynchronous-outbound-messaging-roadmap.mddocs/multi-packet-and-streaming-responses-design.mddocs/the-road-to-wireframe-1-0-feature-set-philosophy-and-capability-maturity.mddocs/asynchronous-outbound-messaging-design.md
🧠 Learnings (2)
docs/multi-packet-and-streaming-responses-design.md (1)
Learnt from: CR
PR: leynos/wireframe#0
File: docs/multi-packet-and-streaming-responses-design.md:0-0
Timestamp: 2025-06-27T13:20:55.648Z
Learning: The async-stream crate's macros (stream! and try_stream!) allow developers to write imperative-style code with yield statements that are transformed into proper Stream objects, making dynamic or large streaming responses ergonomic and idiomatic in Rust.
docs/the-road-to-wireframe-1-0-feature-set-philosophy-and-capability-maturity.md (1)
Learnt from: CR
PR: leynos/wireframe#0
File: docs/multi-packet-and-streaming-responses-design.md:0-0
Timestamp: 2025-06-27T13:20:55.648Z
Learning: The async-stream crate's macros (stream! and try_stream!) allow developers to write imperative-style code with yield statements that are transformed into proper Stream objects, making dynamic or large streaming responses ergonomic and idiomatic in Rust.
🪛 LanguageTool
docs/asynchronous-outbound-messaging-design.md
[uncategorized] ~73-~73: Loose punctuation mark.
Context: ...low_priority_push_rx: mpsc::Receiver`: For standard, non-urgent background ...
(UNLIKELY_OPENING_PUNCTUATION)
🔇 Additional comments (1)
docs/asynchronous-outbound-messaging-design.md (1)
73-75: Double-space and line-length violation in list itemThere is an unintended double space before “background” and the line breaks the
80-column rule. Tighten the spacing and wrap the description.-2. `low_priority_push_rx: mpsc::Receiver<F>`: For standard, non-urgent - background messages like log forwarding or secondary status updates. +2. `low_priority_push_rx: mpsc::Receiver<F>`: For standard, non-urgent + background messages such as log forwarding or secondary status updates.Likely an incorrect or invalid review comment.
| - [x] **Document `async-stream`** for creating `Response::Stream` values | ||
| ([Roadmap #2.4][roadmap-2-4]). | ||
| - [ ] **Example handler using `async-stream`** demonstrating `Response::Stream` | ||
| generation in the examples directory. |
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Bullet exceeds 80-column guideline and should be wrapped
The added bullet for the example handler is > 100 characters, violating the
project’s 80-column wrap rule for paragraphs / bullets.
- - [ ] **Example handler using `async-stream`** demonstrating `Response::Stream` generation in the examples directory.
+ - [ ] **Example handler using `async-stream`** demonstrating `Response::Stream`
+ generation in the *examples* directory.Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In docs/asynchronous-outbound-messaging-roadmap.md around lines 32 to 35, the
bullet point describing the example handler using async-stream exceeds the
80-column limit. Break this long bullet into multiple lines so that no line
exceeds 80 characters, ensuring proper indentation for wrapped lines to maintain
markdown formatting and readability.
| imperative-style logic (e.g., inside a `for` loop), `wireframe` adopts and | ||
| recommends the `async-stream` crate. This crate provides macros (`stream!` and | ||
| `try_stream!`) that transform imperative `yield` statements into a fully | ||
| compliant `Stream` object. This gives developers the best of both worlds: the | ||
| intuitive feel of imperative code generation without the API complexity of a | ||
| separate `FrameSink` type. | ||
| compliant `Stream` object. This gives developers the intuitive feel of | ||
| imperative code generation with minimal API complexity. The library recommends | ||
| this pattern as the canonical way to build `Response::Stream` values. |
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Minor line-length breach – wrap for consistency
Lines 63-66 run a little past 80 columns. While tables are exempt, regular
paragraphs are not. Consider a soft wrap to stay consistent with the coding
guidelines.
🤖 Prompt for AI Agents
In docs/multi-packet-and-streaming-responses-design.md around lines 63 to 68,
the paragraph lines exceed the 80-column limit. To fix this, reformat the text
by inserting line breaks at appropriate points to ensure no line goes beyond 80
characters, maintaining readability and consistency with the coding guidelines.
| | ID | Requirement | | ||
| | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | G1 | Any async task must be able to push frames to a live connection. | | ||
| | G2 | Ordering-safety: Pushed frames must interleave correctly with normal request/response traffic and respect any per-message sequencing rules. | | ||
| | G3 | Back-pressure: Writers must block (or fail fast) when the peer cannot drain the socket, preventing unbounded memory consumption. | | ||
| | G4 | Generic—independent of any particular protocol; usable by both servers and clients built on wireframe. | | ||
| | G5 | Preserve the simple “return a reply” path for code that does not need pushes, ensuring backward compatibility and low friction for existing users. | | ||
| | G1 | Any async task must be able to push frames to a live connection. | | ||
| | G2 | Ordering-safety: Pushed frames must interleave correctly with normal request/response traffic and respect any per-message sequencing rules. | | ||
| | G3 | Back-pressure: Writers must block (or fail fast) when the peer cannot drain the socket, preventing unbounded memory consumption. | | ||
| | G4 | Generic—independent of any particular protocol; usable by both servers and clients built on wireframe. | | ||
| | G5 | Preserve the simple “return a reply” path for code that does not need pushes, ensuring backward compatibility and low friction for existing users. | | ||
|
|
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Table rows exceed 80 columns
The requirement rows G2–G5 are ~130 chars each. To satisfy MD013 you can either
soft-wrap the cell contents or silence the rule for those lines with
<!-- markdownlint-disable-line MD013 -->.
🤖 Prompt for AI Agents
In docs/asynchronous-outbound-messaging-design.md around lines 42 to 49, the
table rows for requirements G2 to G5 exceed 80 characters, violating the MD013
markdownlint rule. To fix this, either soft-wrap the long cell contents by
breaking the text into multiple lines within the same cell or add a markdownlint
disable comment like <!-- markdownlint-disable-line MD013 --> at the end of
those lines to silence the rule for them.
There was a problem hiding this comment.
Table rows are allowed to exceed 80 columns
There was a problem hiding this comment.
@leynos, understood! I've noted that table rows are exempt from the 80-column wrapping requirement for markdown files.
✏️ Learnings added
Learnt from: leynos
PR: leynos/wireframe#154
File: docs/asynchronous-outbound-messaging-design.md:42-49
Timestamp: 2025-06-29T16:50:55.852Z
Learning: In markdown files, table rows are allowed to exceed 80 columns and are exempt from the MD013 wrapping rule, even though paragraphs and bullets must be wrapped to 80 columns.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
There was a problem hiding this comment.
Actionable comments posted: 4
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
docs/wireframe-1-0-detailed-development-roadmap.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (7)
`docs/**/*.md`: Use the markdown files within the `docs/` directory as a knowled...
docs/**/*.md: Use the markdown files within thedocs/directory as a knowledge base and source of truth for project requirements, dependency choices, and architectural decisions.
Proactively update the relevant file(s) in thedocs/directory to reflect the latest state when new decisions are made, requirements change, libraries are added/removed, or architectural patterns evolve.
Documentation in thedocs/directory must use en-GB-oxendict spelling and grammar, except for the word 'license'.
📄 Source: CodeRabbit Inference Engine (AGENTS.md)
List of files the instruction was applied to:
docs/wireframe-1-0-detailed-development-roadmap.md
`**/*.md`: Validate Markdown files using `markdownlint *.md **/*.md`. Run `mdfor...
**/*.md: Validate Markdown files usingmarkdownlint *.md **/*.md.
Runmdformat-allafter any documentation changes to format all Markdown files and fix table markup.
Validate Markdown Mermaid diagrams using thenixieCLI by runningnixie *.md **/*.md.
Markdown paragraphs and bullet points must be wrapped at 80 columns.
Code blocks in Markdown files must be wrapped at 120 columns.
Tables and headings in Markdown files must not be wrapped.
📄 Source: CodeRabbit Inference Engine (AGENTS.md)
List of files the instruction was applied to:
docs/wireframe-1-0-detailed-development-roadmap.md
`docs/**/wireframe-1-0-detailed-development-roadmap.md`: Document `async-stream` for creating `Response::Stream` values.
docs/**/wireframe-1-0-detailed-development-roadmap.md: Documentasync-streamfor creatingResponse::Streamvalues.
📄 Source: CodeRabbit Inference Engine (docs/asynchronous-outbound-messaging-roadmap.md)
List of files the instruction was applied to:
docs/wireframe-1-0-detailed-development-roadmap.md
`docs/*`: Each file in the docs/ directory provides design, roadmap, testing, op...
docs/*: Each file in the docs/ directory provides design, roadmap, testing, operations, or reference documentation for the project. Use these files as a reference for understanding the project's architecture, development plans, testing strategies, operational guidelines, and documentation conventions.
📄 Source: CodeRabbit Inference Engine (docs/contents.md)
List of files the instruction was applied to:
docs/wireframe-1-0-detailed-development-roadmap.md
`docs/**/*.md`: Use British English spelling based on the Oxford English Diction...
docs/**/*.md: Use British English spelling based on the Oxford English Dictionary, except retain US spelling in API names (e.g., 'color').
Use the Oxford comma in lists.
Write headings in sentence case and use Markdown heading levels in order without skipping.
Follow markdownlint recommendations for Markdown formatting.
Always use fenced code blocks with a language identifier; use 'plaintext' for non-code text.
Use '-' as the first level bullet and renumber lists when items change.
Prefer inline links using 'text' or angle brackets around the URL.
Expand any uncommon acronym on first use, e.g., Continuous Integration (CI).
Wrap paragraphs at 80 columns, code at 120 columns, and do not wrap tables.
Use footnotes referenced with '[^label]'.
When embedding figures, use '' and provide concise alt text describing the content.
Add a short description before each Mermaid diagram for screen readers.
📄 Source: CodeRabbit Inference Engine (docs/documentation-style-guide.md)
List of files the instruction was applied to:
docs/wireframe-1-0-detailed-development-roadmap.md
`docs/**/*`: Write official documentation for new features, including separate g...
docs/**/*: Write official documentation for new features, including separate guides for 'Duplex Messaging & Pushes', 'Streaming Responses', and 'Message Fragmentation', each with runnable examples and explanations of relevant concepts and APIs.
📄 Source: CodeRabbit Inference Engine (docs/wireframe-1-0-detailed-development-roadmap.md)
List of files the instruction was applied to:
docs/wireframe-1-0-detailed-development-roadmap.md
`**/*.md`: * Avoid 2nd person or 1st person pronouns ("I", "you", "we") * Use en...
**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")
- Use en-oxendic spelling and grammar.
- Paragraphs and bullets must be wrapped to 80 columns, except where a long URL would prevent this (in which case, silence MD013 for that line)
- Code blocks should be wrapped to 120 columns.
- Headings must not be wrapped.
⚙️ Source: CodeRabbit Configuration File
List of files the instruction was applied to:
docs/wireframe-1-0-detailed-development-roadmap.md
🪛 LanguageTool
docs/wireframe-1-0-detailed-development-roadmap.md
[grammar] ~23-~23: The verb ‘depend’ requires the preposition ‘on’ (or ‘upon’).
Context: ... | Size | Depends | | ---- | ----------------------------...
(DEPEND_ON)
[typographical] ~25-~25: To join two clauses or introduce examples, consider using an em dash.
Context: .... | Small | - | | 1.2 | Priority Push Channels ...
(DASH_RULE)
[typographical] ~26-~26: To join two clauses or introduce examples, consider using an em dash.
Context: ... | Medium | - | | 1.3 | Connection Actor Write ...
(DASH_RULE)
[style] ~27-~27: Consider using the typographical ellipsis character here instead.
Context: ...stateful connection actors. Implement a select!(biased; ...) loop that polls for shutdown signals,...
(ELLIPSIS)
[uncategorized] ~27-~27: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...p that polls for shutdown signals, high/low priority pushes and the handler response stream ...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[typographical] ~28-~28: To join two clauses or introduce examples, consider using an em dash.
Context: ... | Medium | - | | 1.5 | Basic FragmentAdapter ...
(DASH_RULE)
[uncategorized] ~29-~29: Possible missing comma found.
Context: ...for a single, non-multiplexed stream of fragments and the outbound logic for splitting a ...
(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~38-~38: The verb ‘depend’ requires the preposition ‘on’ (or ‘upon’).
Context: ... | Size | Depends | | ---- | -------------------...
(DEPEND_ON)
[grammar] ~53-~53: The verb ‘depend’ requires the preposition ‘on’ (or ‘upon’).
Context: ... | Size | Depends | | ---- | ----------------------------...
(DEPEND_ON)
[grammar] ~66-~66: The verb ‘depend’ requires the preposition ‘on’ (or ‘upon’).
Context: ... | Size | Depends | | ---- | -------------------------...
(DEPEND_ON)
[uncategorized] ~73-~73: Do not mix variants of the same word (‘finalise’ and ‘finalize’) within a single text.
Context: ...Changelog & 1.0 Release | Finalise the CHANGELOG.md with a comprehensive...
(EN_WORD_COHERENCY)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: build-test
🔇 Additional comments (1)
docs/wireframe-1-0-detailed-development-roadmap.md (1)
72-74: Verify spelling consistency of “finalise”/“finalize”Line 74 uses the British spelling “finalise”, which is correct per guidelines.
Please double-check earlier occurrences (outside this diff) for any stray “finalize” forms to avoid mixing variants.
…ables Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 participant
Summary
Response::StreamTesting
make fmtmake lintmake testmarkdownlint *.md **/*.mdnixie *.md **/*.mdhttps://chatgpt.com/codex/tasks/task_e_68614ec06f388322920c839d605c5ae4
Summary by Sourcery
Update documentation to drop the FrameSink design, recommend async-stream for Response::Stream, and reflect completion of the async-stream docs with a new example task
Documentation: