-
Notifications
You must be signed in to change notification settings - Fork 8
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
chore(docs): developer docs on plugin system communication #728
base: main
Are you sure you want to change the base?
Conversation
b0997a3
to
e157e48
Compare
site/content/docs/contributing/developer-docs/plugin-query-system.md
Outdated
Show resolved
Hide resolved
site/content/docs/contributing/developer-docs/plugin-query-system.md
Outdated
Show resolved
Hide resolved
aaf2cd8
to
c062616
Compare
c062616
to
4bc732a
Compare
In Rust, the gRPC channel is accessed with using a `mpsc::{Sender, Receiver}` | ||
pair. The `Sender` can be cloned many times, meaning that many threads can | ||
`send` messages on the channel without needing exclusive access to any resource. | ||
However, a `Receiver` cannot be shared. The Rust SDK addresses this restriction | ||
and the above multiple-session, single-channel requirement by having a | ||
`HcSessionSocket` object that has the exclusive `Receiver` to the plugin's gRPC | ||
channel with Hipcheck core. The `HcSessionSocket` is responsible for tracking | ||
the set of live sessions, and detecting whether a new message from the gRPC | ||
channel should be forwarded to a live session, or constitues an entirely new | ||
session. Each session is represented by a `PluginEngine` instance. The |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a little confusing. There's explanation for why and functionality for there being multiple Sender
instances (if I'm understanding correctly), but I'm a little confused on how the HcSessionSocket
is handling the situation. Is it that the HcSessionSocket
forwards the session to the Receiver
when it's free? And I might be misunderstanding the wording, but is the session within the send
messages as a PluginEngine
instance?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We don't send "sessions," we send "messages". A session is made up of a series of messages with the same ID. The HcSessionSocket
forwards a message it receives on the Receiver
tied to the gRPC channel, and then forwards it on one of the many Senders
it has to different PluginEngine
instances. I will add a graphic and update the explanation.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added a graphic and expanded the description. @aamohd let me know if this is more clear.
site/content/docs/contributing/developer-docs/plugin-query-system.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I left comments on plugin-query-system.md
Regarding where to put images, here's the guide from the Zola docs on "asset colocation": https://www.getzola.org/documentation/content/overview/#asset-colocation The basic idea is that you turn the relevant page into a folder with an |
site/content/docs/contributing/developer-docs/plugin-query-system.md
Outdated
Show resolved
Hide resolved
@@ -0,0 +1,83 @@ | |||
--- | |||
title: Repo Structure |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This page is one that we'll want to make sure we keep up-to-date. In general, I think we probably ought to add a review checklist for approvals on PRs, which would include a documentation review to make sure documentation is updated to reflect PR changes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added a PR Review Checklist
page under the Contributing section. Let me know if you have any suggested changes.
@alilleybrinker this doesn't actually show how to display co-located images in a markdown file. The way I found to work with a custom shortcut only works if the images are in |
4bc732a
to
be4ba99
Compare
be4ba99
to
38c071b
Compare
Initial documentation oriented towards developers, describing the repo structure, Hipcheck distributed architecture, and plugin query control flow. Signed-off-by: jlanson <[email protected]>
38c071b
to
359ab14
Compare
To start the hipcheck developer docs, I added a document and accompanying graphic explaining how Hipcheck core queries are conducted over gRPC.
@alilleybrinker I could use advice on where the
.png
/.drawio
files should be stored in thesite
. I also need to set up to do local site dev to wire up this Markdown file to read the.png
and be part of theContributing
page links.@devin-b-lake @aamohd @ninaagrawal as the newer members on the team, I would appreciate if you read through the document and the graphic, and pointed out anything that was particularly confusing. The expectation is that someone would read it while looking through the functions it references.