Add GraphQL News Broadcasting use case example#227
Add GraphQL News Broadcasting use case example#227Sachindu-Nethmin wants to merge 9 commits intowso2:mainfrom
Conversation
Sachindu-Nethmin
requested review from
KavinduZoysa,
NipunaRanasinghe,
anupama-pathirage and
rosensilva
as code owners
Sachindu-Nethmin
changed the title
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdds a new tutorial documenting a real-time GraphQL News Broadcasting Service: GraphQL schema with queries/mutations/subscriptions, an in-memory news store, a Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Client as Client (GraphiQL / Subscriber)
participant Server as GraphQL Server (/news)
participant Generator as NewsGenerator Service
participant Store as In-memory News Store
Client->>Server: subscribe generateNews()
Server->>Generator: create/attach stream iterator
Generator->>Store: read next news item (shift)
Generator-->>Server: emit news item (stream)
Server-->>Client: deliver subscription event
Note over Generator,Store: Generator loops with sleep intervals, continuing to shift and emit items
Client->>Server: mutation publishNews(headline, content)
Server->>Store: persist new News item (push)
Store-->>Generator: next iteration sees new item
Generator-->>Server: emits new item to subscribers
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In
`@en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md`:
- Around line 318-323: The snippet's field declaration should be changed to
match the guidance: in class NewsGenerator replace the mutable field declaration
`private News[] newsItems;` with `private final News[] newsItems;` so the field
is immutable after construction; ensure the existing isolated init(News[]
newsItems) still assigns the cloned array to this.newsItems (using
newsItems.clone()) and leave the init method and class name (NewsGenerator,
init, newsItems) unchanged aside from the modifier update.
- Around line 321-323: The subscription init function currently clones the
newsItems snapshot, causing subscribers to miss future publishes; update init
(and any subscription setup) to retain a reference to the shared newsStorage (or
store a cursor/index into newsStorage) instead of calling newsItems.clone(), and
remove the behavior that immediately closes the stream when the referenced array
is empty—instead open the stream and deliver new items as they are appended by
publishNews (or iterate from the stored cursor through newsStorage so new
entries become visible to the subscriber). Ensure references to init,
publishNews, newsStorage, and newsItems are updated consistently so
subscriptions observe subsequent publishes.
🧹 Nitpick comments (1)
en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md (1)
219-226: Reduce repeated “In the …” sentence starts for readability.These sections have three consecutive sentences starting with “In the …”. Consider rephrasing one or two sentences to improve flow.
Also applies to: 345-350
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Show resolved
Hide resolved
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Show resolved
Hide resolved
…iable access modifier for data integrity
…he GraphQL News Broadcasting Service guide.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In
`@en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md`:
- Line 331: Update the documentation instruction to require the newsItems field
inside the service class be declared as private final (not just private) to
enforce immutability; specifically, change the guidance referencing the
newsItems variable so readers are told to mark it as private final within the
service class.
🧹 Nitpick comments (3)
en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md (3)
3-3: Remove the contraction from the heading.The heading uses a contraction. Microsoft Style Guide recommends avoiding contractions in formal documentation.
✏️ Suggested fix
-## What you'll build +## What you will buildAs per coding guidelines, follow the Microsoft Style Guide for all documentation changes.
28-28: Use a more formal tone for the heading.The heading "Let's get started!" uses a contraction and an exclamation mark, which creates an informal tone. Microsoft Style Guide recommends formal, straightforward language in technical documentation.
✏️ Suggested fix
-## Let's get started! +## Get startedAs per coding guidelines, follow the Microsoft Style Guide for all documentation changes.
221-221: Consider varying sentence starters for better readability.Multiple consecutive sentences begin with "In the" at Lines 221, 347, and 349. While grammatically correct, varying sentence structure improves readability and flow.
Example alternatives:
- Line 221: "Within the Declare Variable pane:" or "Configure the following in the Declare Variable pane:"
- Line 347: "Within the Resource Design view, click..." or "Click the + icon..."
- Line 349: "Click the Condition field within the If pane..." or "Configure the condition..."
As per coding guidelines, follow the Microsoft Style Guide for all documentation changes.
Also applies to: 347-347, 349-349
| } | ||
| ``` | ||
|
|
||
| 4. Ensure the `newsItems` variable is marked as `private` to maintain data integrity within the service class. |
There was a problem hiding this comment.
Update the instruction to mention the final modifier.
The instruction states "Ensure the newsItems variable is marked as private" but does not mention marking it as final. Based on the previous review comment and best practices for immutability, the instruction should explicitly direct readers to use private final.
✏️ Proposed fix
-4. Ensure the `newsItems` variable is marked as `private` to maintain data integrity within the service class.
+4. Ensure the `newsItems` variable is marked as `private final` to maintain data integrity and immutability within the service class.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 4. Ensure the `newsItems` variable is marked as `private` to maintain data integrity within the service class. | |
| 4. Ensure the `newsItems` variable is marked as `private final` to maintain data integrity and immutability within the service class. |
🤖 Prompt for AI Agents
In
`@en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md`
at line 331, Update the documentation instruction to require the newsItems field
inside the service class be declared as private final (not just private) to
enforce immutability; specifically, change the guidance referencing the
newsItems variable so readers are told to mark it as private final within the
service class.
|
@Sachindu-Nethmin Can you please resolve the conflicts |
|
@daneshk / @ThisaruGuruge Please review this |
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Show resolved
Hide resolved
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Outdated
Show resolved
Hide resolved
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Outdated
Show resolved
Hide resolved
- Reorganize steps into logical sections (Setup, Configure Service, Implement Operations, Implement Subscriptions, Run and Test) - Remove step numbers from headings for cleaner navigation - Fix list rendering and image alignment - Remove bold formatting from non-UI elements (tool names, field labels, operation types) - Center all GIF images for better visual consistency
There was a problem hiding this comment.
Actionable comments posted: 8
♻️ Duplicate comments (1)
en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md (1)
344-358:⚠️ Potential issue | 🟡 MinorUpdate the code snippet and instruction to include the
finalmodifier.The code snippet at lines 344-356 shows
private News[] newsItems;but based on best practices for immutability (especially since the array is cloned ininitand not reassigned), the field should be declared asprivate final. Additionally, the instruction on line 358 mentions onlyprivatebut should also requirefinal.This issue was previously flagged in past review comments. Please update both the snippet and the instruction text:
✏️ Proposed fix
service class NewsGenerator { - private News[] newsItems; + private final News[] newsItems; isolated function init(News[] newsItems) { self.newsItems = newsItems.clone(); }And for the instruction:
-4. Ensure the `newsItems` variable is marked as `private` to maintain data integrity within the service class. +4. Ensure the `newsItems` variable is marked as `private final` to maintain data integrity and immutability within the service class.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md` around lines 344 - 358, The NewsGenerator service class field newsItems should be made immutable: change the declaration of the field referenced in NewsGenerator (currently "private News[] newsItems") to include the final modifier ("private final") and ensure any related comments or documentation in the surrounding instruction text also require both private and final; verify init still clones into the field and that next remains unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md`:
- Line 437: Update the heading "Define the GraphQL Subscription operation" to
sentence case by changing it to "Define the GraphQL subscription operation"
(only capitalize the first word and proper nouns); locate the exact heading text
in the document and replace it accordingly so it follows the project's
sentence-case heading guideline.
- Line 298: Change the heading text "Implement Subscriptions" to sentence case
"Implement subscriptions" in the documentation so it follows the guideline;
locate the heading string "Implement Subscriptions" in the markdown (e.g., the
heading under the Implement Subscriptions section) and update it accordingly.
- Line 164: The heading "Implement Operations" should be changed to sentence
case; update the heading text in the document (the header currently reading
"Implement Operations") to "Implement operations" so only the first word is
capitalized, following the sentence case guideline for headings.
- Line 300: Update the heading text "Implement real-time broadcasting logic with
a Service Class" to sentence case by changing "Service Class" to "service class"
so the heading reads "Implement real-time broadcasting logic with a service
class"; locate and edit the heading string in the markdown file where that exact
heading appears.
- Line 492: Update the heading text currently written as "Run and Test" to
sentence case "Run and test" in the markdown document (locate the heading string
"Run and Test" and replace it), ensuring only the first word is capitalized per
the documentation guideline.
- Line 335: The heading "Finalize the Service Class in code" uses title case;
update it to sentence case by changing the text to "Finalize the service class
in code" (edit the heading string shown as "Finalize the Service Class in code"
to "Finalize the service class in code") so it follows the documentation
guideline of sentence case for headings.
- Line 97: Change the heading text "Configure Service" to sentence case
"Configure service" in the markdown file so it follows the documentation
guideline; locate the heading line containing the exact string "Configure
Service" and replace it with "Configure service".
- Around line 530-540: The HTML image block after the "Observe that when a
mutation is executed..." line is indented by extra spaces which makes it render
as an indented code block (MD046); remove the leading indentation on the <p> and
its nested <a> and <img> tags so the block is left-aligned with the surrounding
text and matches other image blocks in the document (locate the HTML image block
containing <p align="center">, <a
href="{{base_path}}/assets/usecases/graphql-news-broadcasting/run_and_test.gif">
and the nested <img> and unindent those lines).
---
Duplicate comments:
In
`@en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md`:
- Around line 344-358: The NewsGenerator service class field newsItems should be
made immutable: change the declaration of the field referenced in NewsGenerator
(currently "private News[] newsItems") to include the final modifier ("private
final") and ensure any related comments or documentation in the surrounding
instruction text also require both private and final; verify init still clones
into the field and that next remains unchanged.
ℹ️ Review info
Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: ab07f1f7-0e69-40b1-a539-a4470b92c737
📒 Files selected for processing (2)
en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.mden/mkdocs.yml
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Outdated
Show resolved
Hide resolved
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Outdated
Show resolved
Hide resolved
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Outdated
Show resolved
Hide resolved
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Outdated
Show resolved
Hide resolved
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Outdated
Show resolved
Hide resolved
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Show resolved
Hide resolved
...ation-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md
Outdated
Show resolved
Hide resolved
| 5. Observe that when a mutation is executed, the subscription tab automatically receives the updated news broadcast. | ||
|
|
||
| <p align="center"> | ||
| <a href="{{base_path}}/assets/usecases/graphql-news-broadcasting/run_and_test.gif"> | ||
| <img | ||
| src="{{base_path}}/assets/usecases/graphql-news-broadcasting/run_and_test.gif" | ||
| alt="run and test the service" | ||
| width="80%" | ||
| /> | ||
| </a> | ||
| </p> |
There was a problem hiding this comment.
Fix inconsistent indentation for the image block.
The image HTML block is indented with 8 spaces, which causes markdownlint to flag it as an indented code block (MD046). Other image blocks in the document are not indented this way. Remove the extra indentation to maintain consistency.
✏️ Proposed fix
5. Observe that when a mutation is executed, the subscription tab automatically receives the updated news broadcast.
- <p align="center">
- <a href="{{base_path}}/assets/usecases/graphql-news-broadcasting/run_and_test.gif">
- <img
- src="{{base_path}}/assets/usecases/graphql-news-broadcasting/run_and_test.gif"
- alt="run and test the service"
- width="80%"
- />
- </a>
- </p>
+ <p align="center">
+ <a href="{{base_path}}/assets/usecases/graphql-news-broadcasting/run_and_test.gif">
+ <img
+ src="{{base_path}}/assets/usecases/graphql-news-broadcasting/run_and_test.gif"
+ alt="run and test the service"
+ width="80%"
+ />
+ </a>
+ </p>🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 532-532: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md`
around lines 530 - 540, The HTML image block after the "Observe that when a
mutation is executed..." line is indented by extra spaces which makes it render
as an indented code block (MD046); remove the leading indentation on the <p> and
its nested <a> and <img> tags so the block is left-aligned with the surrounding
text and matches other image blocks in the document (locate the HTML image block
containing <p align="center">, <a
href="{{base_path}}/assets/usecases/graphql-news-broadcasting/run_and_test.gif">
and the nested <img> and unindent those lines).
…broadcasting service documentation
…m/Sachindu-Nethmin/docs-bi into graphql-news-broadcasting-service
|
|
||
| 1. In the **Resource Design** view for the `next` method, click the **+** icon on the flow. | ||
|
|
||
| 2. Select **Call Function** from the **Statement** section and search for the `sleep` function under the `lang.runtime` library. |
There was a problem hiding this comment.
Why do we need sleep function here?
| NewsGenerator newsStream = new (newsStorage); | ||
| return new stream<News, error?>(newsStream); |
There was a problem hiding this comment.
Do this update the new news items to the users?
An array is a bounded stream and will not send the new updates to the existing users. Need to have a better way to handle this than having a global array.
One way I can think of is to have an internal array inside the stream generator and then keep an internal count to keep track the news and return the next value. To publish, we can expose another method from the stream generator so the new news is always fetched and sent to the subscribers.
| News[] newsStorage = []; | ||
| ``` | ||
|
|
||
| 3. Add the `@graphql:ServiceConfig` annotation above the service declaration to enable the **GraphiQL** explorer for testing: |
There was a problem hiding this comment.
Without adding it in code is there a better way to achieve this in UI level? @DimuthuMadushan
There was a problem hiding this comment.
No need to enable GraphiQL from code. BI provides a built-in TryIt feature that opens GraphiQL for testing. Once the service runs, the TryIt button pops up.
|
|
||
| Next, the **Create GraphQL Service** dialog will open. | ||
|
|
||
| 4. Ensure **Design From Scratch** is selected. |
There was a problem hiding this comment.
@anupama-pathirage Just a suggestion, we support generating a service from the SDL schema, that can be run immediately. In this case, Developers only need to implement the logic. Maybe we can mention it here or add a separate sample for it if possible.
4 participants
Purpose
The purpose of this PR is to add a new comprehensive use case to the documentation titled "GraphQL News Broadcasting Service".
Goals
This PR introduces a step-by-step guide to achieve the following:
NewsGeneratorclass to manage the stream iteration protocol required for subscriptions.Screencast.from.2026-02-12.08-35-10.webm
Summary by CodeRabbit