DOCS-1069: Document API methods for Session and SessionManager
#1752
Conversation
sguequierre
commented
Sep 5, 2023
•
sguequierre
commented
- Add documentation for methods available and documented in RDK client docs
viambot
added
the
safe to build
docs/program/apis/session-manager.md
Outdated
| @@ -8,7 +8,8 @@ tags: ["client", "sdk", "viam-server", "networking", "apis", "robot api", "sessi | |||
| --- | |||
|
|
|||
| When controlling a robot or fleet with Viam, you want a way to understand the presence of the clients that are communicating with and authenticated to each robot's `viam-server`. | |||
| The period of time during which these clients are present is called a *session*. | |||
| The period of time during which these clients are present is called a *session.* | |||
| Sessions each have [their own API](/program/apis/session), which is a client of `viam-server`. | |||
There was a problem hiding this comment.
Needs technical review but I believe this is where the diagram can come in
sguequierre
changed the title
Session and SessionManager
|
|
||
| ## API | ||
|
|
||
| The `SessionManager` API built-in to the [Robot API](/program/apis/robot/) supports the following methods: |
There was a problem hiding this comment.
I think this needs documentation on NewSessionManager() in robot API to be functional-- sme review may help clear up some confusion on my end
There was a problem hiding this comment.
Added, then removed,NewSessionManager() instantiation of mySessionManager-- unsure whether that should be in there or not. How would a user most simply request to the default session manager API with what we have set up in the RDK? @dgottlieb
There was a problem hiding this comment.
As discussed, this SessionManager structure is used by the viam-server running on a robot to track and time out/call Stop robot parts when heartbeats stop coming in.
Client code using the Go SDK wouldn't see anything happen if they were to try using this object.
That said, the documentation for these methods is 100% correct!
|
You can view a rendered version of the docs from this PR at https://docs-test.viam.dev/dadae246166ac7c7f4dafac771d4d130de978c24/public |
|
|
||
| ## API | ||
|
|
||
| The `Session` API supports the following methods: |
There was a problem hiding this comment.
Question for @dgottlieb or any SME who has a better idea of what's going on in the RDK than I do: is this correct? Or should this all be replaced with https://pkg.go.dev/go.viam.com/[email protected]/session#Session as these are just the methods the session package offers and the interface for the type itself has different methods (Active, Heartbeat, etc.). Should both be on here? Apologies for the confusion
There was a problem hiding this comment.
Similarly, for posterity, these are internal data types that are not client facing.
|
Closing out and leaving these methods undocumented as they are not meant to be user-facing re discussion with @dgottlieb @npentrel |
There was a problem hiding this comment.
FWIW, the following is the (internal) client* session/heartbeat code that gets run when connecting with sessions enabled:
- Start/create a session
- Sending a heartbeat
- Adding session data to other RPC commands (e.g:
WheeledBase.MoveStraight)
|
|
||
| ## API | ||
|
|
||
| The `SessionManager` API built-in to the [Robot API](/program/apis/robot/) supports the following methods: |
There was a problem hiding this comment.
As discussed, this SessionManager structure is used by the viam-server running on a robot to track and time out/call Stop robot parts when heartbeats stop coming in.
Client code using the Go SDK wouldn't see anything happen if they were to try using this object.
That said, the documentation for these methods is 100% correct!
|
|
||
| ## API | ||
|
|
||
| The `Session` API supports the following methods: |
There was a problem hiding this comment.
Similarly, for posterity, these are internal data types that are not client facing.
