From 3457d327c0851dd2671b07d2f5c46622780606f0 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Tue, 5 Sep 2023 12:29:40 -0400 Subject: [PATCH 01/21] add main three functions to sessions page --- docs/program/apis/sessions.md | 94 ++++++++++++++++++- .../program/apis/session-management.md | 5 + 2 files changed, 98 insertions(+), 1 deletion(-) create mode 100644 static/include/program/apis/session-management.md diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index a652200508..5b709fb0ea 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -126,6 +126,98 @@ disableSessions: true {{% /tab %}} {{% /tabs %}} -This option allows you to have full control over sessions management. +This option allows you to have full control over session management. After disabling the client, you must now manage each of your sessions manually with the session management API. You can do this with Viam's [client SDKs](https://pkg.go.dev/go.viam.com/rdk/session). + +## API + +The session management API supports the following methods: + +{{< readfile "/static/include/program/apis/session-management.md" >}} + +{{% alert title="Tip" color="tip" %}} + +The following code examples assume that you have a robot configured with a `Navigation` service, and that you add the required code to connect to your robot and import any required packages at the top of your code file. +Go to your robot's **Code Sample** tab on the [Viam app](https://app.viam.com) for boilerplate code to connect to your robot. + +{{% /alert %}} + +### SafetyMonitor + +`SafetyMonitor()` signals to the session that the given target {{< glossary_tooltip term_id="resource" text="resource" >}}, if present, should be safety monitored so that if this session ends and this session was the last to monitor the target, it will attempt to be stopped. + +This not be called by a resource being monitored itself, but instead by another client, like another resource, that is controlling a resource on behalf of some request or routine. +For example, it would be appropriate for a remote [input controller](/components/input-controller/) resource to call a `SafetyMonitor()` on a base that it is remotely controlling the motion of. + +In the context of a gRPC handled request, this function can only be called before the first response is sent back. +In the case of unary, it can only be called before the handler returns. + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `target` [(resource.Resource)](https://pkg.go.dev/go.viam.com/rdk@v0.7.3/resource#Resource): The target resource. + +**Returns:** + +- None + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#SafetyMonitor). + +```go +myBase, err := base.FromRobot(robot, "my_base") + +// Signal to the session that the given target resource should be safety monitered. +session = session.SafetyMonitor(ctx, myBase) +``` + +### SafetyMonitorResourceName + +`SafetyMonitorResourceName()` works just like `SafetyMonitor()` but uses Viam {{< glossary_tooltip term_id="resource" text="resource" >}} names directly. +You assign the name of a resource when [configuring your robot](/manage/configuration/). + +This method, when called, signals to the session that the given target {{< glossary_tooltip term_id="resource" text="resource" >}}, if present, should be safety monitored so that if this session ends and this session was the last to monitor the target, it will attempt to be stopped. + +This not be called by a resource being monitored itself, but instead by another client, like another resource, that is controlling a resource on behalf of some request or routine. +For example, it would be appropriate for a remote [input controller](/components/input-controller/) resource to call a `SafetyMonitor()` on a base that it is remotely controlling the motion of. + +In the context of a gRPC handled request, this function can only be called before the first response is sent back. +In the case of unary, it can only be called before the handler returns. + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `targetName` [(resource.Name)](https://pkg.go.dev/go.viam.com/rdk@v0.7.3/resource#Name): The `name` you have set for the resource in configuration. + +**Returns:** + +- None + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#SafetyMonitorResourceName). + +```go +myBase, err := base.FromRobot(robot, "my_base") + +// Signal to the session that the given target resource should be safety monitered. +session = session.SafetyMonitor(ctx, "my_base") +``` + +### ToContext + +Attach a session to the given contxt. + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `sess` [(*Session)](https://pkg.go.dev/go.viam.com/rdk/session#Session): The session object that you wish to attach to this context. + +**Returns:** + +- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#ToContext). + +```go +// Attach session "my session" to the given Context +session = session.ToContext(context.Background(), my_session) +``` diff --git a/static/include/program/apis/session-management.md b/static/include/program/apis/session-management.md new file mode 100644 index 0000000000..617b517672 --- /dev/null +++ b/static/include/program/apis/session-management.md @@ -0,0 +1,5 @@ +Method Name | Description +----------- | ----------- +[`SafetyMonitor`](/program/apis/sessions/#safetymonitor) | Signal to the session that the given target resource should be safety monitored so that if the session ends and this session was the last to monitor the target, it will attempt to be stopped. +[`SafetyMonitorResourceName`](/program/apis/sessions/#safetymonitorresourcename) | Signal to the session that the given target resource attached to this resource name should be safety monitored so that if the session ends and this session was the last to monitor the target, it will attempt to be stopped. +[`ToContext`](/program/apis/sessions/#tocontext) | Attach a session to the given context. \ No newline at end of file From ef609d777ae0d4193c41a5c57fe1bd5566554926 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Tue, 5 Sep 2023 12:54:11 -0400 Subject: [PATCH 02/21] make more accurate --- docs/program/apis/sessions.md | 28 ++++++++++++++++++- .../include/program/apis/session-manager.md | 0 2 files changed, 27 insertions(+), 1 deletion(-) create mode 100644 static/include/program/apis/session-manager.md diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index 5b709fb0ea..93e1f7d27b 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -138,7 +138,7 @@ The session management API supports the following methods: {{% alert title="Tip" color="tip" %}} -The following code examples assume that you have a robot configured with a `Navigation` service, and that you add the required code to connect to your robot and import any required packages at the top of your code file. +The following code examples assume that you have a robot configured with a [base component](/components/base) resource, and that you add the required code to connect to your robot and import any required packages, including the `sessions` package, at the top of your client file. Go to your robot's **Code Sample** tab on the [Viam app](https://app.viam.com) for boilerplate code to connect to your robot. {{% /alert %}} @@ -221,3 +221,29 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/s // Attach session "my session" to the given Context session = session.ToContext(context.Background(), my_session) ``` + +## Manager API + +The sessions package provides the `SessionManager` as an interface for holding sessions for a particular robot and managing the lifetime of each of these sessions. + +Instantiate a `SessionManager` with `NewSessionManager()`: + +Then, the following functions are available for use with a `SessionManager`: + +{{< readfile "/static/include/program/apis/session-manager.md" >}} + +### Start + +Creates a new session that expects at least one heartbeat within the configured window. + +### FindByID + +FindByID finds a session by the given ID. If found, a heartbeat is triggered, extending the lifetime of the session. If ownerID is in use but the session in question has a different owner, this is a security violation and we report back no session found. + +### AssociateResource + +AssociateResource associates a session ID to a monitored resource such that when a session expires, if a resource is currently associated with that ID based on the order of AssociateResource calls, then it will have its resource stopped. If id is uuid.Nil, this has no effect other than disassociation with a session. Be sure to include any remote information in the name. + +### Close + +Close stops the session manager but will not explicitly expire any sessions. diff --git a/static/include/program/apis/session-manager.md b/static/include/program/apis/session-manager.md new file mode 100644 index 0000000000..e69de29bb2 From 0b8fa0d9cac35bad935f236ac5d74f67669c6703 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Tue, 5 Sep 2023 12:55:39 -0400 Subject: [PATCH 03/21] add session manager methods --- static/include/program/apis/session-manager.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/static/include/program/apis/session-manager.md b/static/include/program/apis/session-manager.md index e69de29bb2..daa72d9547 100644 --- a/static/include/program/apis/session-manager.md +++ b/static/include/program/apis/session-manager.md @@ -0,0 +1,8 @@ +Method Name | Description +----------- | ----------- +[`Start`](/program/apis/sessions/#start) | +[`All`](/program/apis/sessions/#all) | +[`FindByID`](/program/apis/sessions/#findbyid) | +[`AssociateResource`](/program/apis/sessions/#associateresource) | +[`Close`](/program/apis/sessions/#close) | +[`ServerInterceptors`](/program/apis/sessions/#serverinterceptors) | Provide gRPC interceptors to work with sessions. \ No newline at end of file From 836243f1cbbea2a0a41cf22aba5f4fa3d70874cd Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Tue, 5 Sep 2023 13:44:59 -0400 Subject: [PATCH 04/21] Remove trailing space --- docs/program/apis/sessions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index 93e1f7d27b..9f41a63724 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -222,7 +222,7 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/s session = session.ToContext(context.Background(), my_session) ``` -## Manager API +## Manager API The sessions package provides the `SessionManager` as an interface for holding sessions for a particular robot and managing the lifetime of each of these sessions. From 5526005ac93632bdfe7b49425edb780af91a1f2c Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Wed, 6 Sep 2023 12:51:44 -0400 Subject: [PATCH 05/21] update sessionsManager api section --- docs/program/apis/sessions.md | 72 ++++++++++++++++++++++++++++++----- 1 file changed, 63 insertions(+), 9 deletions(-) diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index 9f41a63724..bbb6d42160 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -138,7 +138,7 @@ The session management API supports the following methods: {{% alert title="Tip" color="tip" %}} -The following code examples assume that you have a robot configured with a [base component](/components/base) resource, and that you add the required code to connect to your robot and import any required packages, including the `sessions` package, at the top of your client file. +The following code examples assume that you have a robot configured with a [base component](/components/base/), and that you add the required code to connect to your robot and import any required packages, including the `sessions` package, at the top of your client file. Go to your robot's **Code Sample** tab on the [Viam app](https://app.viam.com) for boilerplate code to connect to your robot. {{% /alert %}} @@ -156,7 +156,7 @@ In the case of unary, it can only be called before the handler returns. **Parameters:** - `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `target` [(resource.Resource)](https://pkg.go.dev/go.viam.com/rdk@v0.7.3/resource#Resource): The target resource. +- `target` [(resource.Resource)](https://pkg.go.dev/go.viam.com/rdk/resource#Resource): The target resource. **Returns:** @@ -187,7 +187,7 @@ In the case of unary, it can only be called before the handler returns. **Parameters:** - `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `targetName` [(resource.Name)](https://pkg.go.dev/go.viam.com/rdk@v0.7.3/resource#Name): The `name` you have set for the resource in configuration. +- `targetName` [(resource.Name)](https://pkg.go.dev/go.viam.com/rdk/resource#Name): The `name` you have set for the resource in configuration. **Returns:** @@ -226,24 +226,78 @@ session = session.ToContext(context.Background(), my_session) The sessions package provides the `SessionManager` as an interface for holding sessions for a particular robot and managing the lifetime of each of these sessions. -Instantiate a `SessionManager` with `NewSessionManager()`: +`viam-server`'s Robot API provides a built-in `SessionManager`, which you can instantiate with `NewSessionManager()`: -Then, the following functions are available for use with a `SessionManager`: +### NewSessionManager + +Create a new manager for holding sessions. + +**Parameters:** + +- `robot` [(Robot)](): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `heartbeatWindow` [(time.Duration)](): The heartbeat window you want this `SessionManager` to follow. + +**Returns:** + +- [(SessionManager)]: A new manager for holding sessions. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#SafetyMonitorResourceName). + +``` go +robot, err := client.New( + context.Background(), + "3minutes-main.0b2qnylnp0.viam.cloud", + logger, + client.WithDialOptions(rpc.WithCredentials(rpc.Credentials{ + Type: utils.CredentialsTypeRobotLocationSecret, + // Replace "" (including brackets) with your robot's secret + Payload: "", + })), +) + +mySessionManager := robot.NewSessionManager(robot, 1000) +``` + +Then, the following functions are available for use with `viam-server`'s Robot API's built-in `SessionManager`: {{< readfile "/static/include/program/apis/session-manager.md" >}} +Method Name | Description +----------- | ----------- +[`Start`](/program/apis/sessions/#start) | Create a new session that expects at least one heartbeat within the configured window. +[`All`](/program/apis/sessions/#all) | Get all active sessions. +[`FindByID`](/program/apis/sessions/#findbyid) | Find a session by the given ID. If found, trigger a heartbeat and extend the lifetime of the session. +[`AssociateResource`](/program/apis/sessions/#associateresource) | Associate a session ID to a monitored resource. All associated resources will be stopped with this session is expired. +[`Close`](/program/apis/sessions/#close) | Stop the session manager without directing any sessions to expire. +[`expireLoop`](/program/apis/sessions/#expireLoop) | Set an expiration loop to be associated with a specific context. + ### Start -Creates a new session that expects at least one heartbeat within the configured window. +[Relevant github](https://github.com/viamrobotics/rdk/blob/473673baf8c395fe12b959f5579adbf614db53ab/robot/session_manager.go#L35). + +Create a new session that expects at least one heartbeat within the configured window. + +### All + +Get all sessions that are actively being held by this `SessionsManager`. ### FindByID -FindByID finds a session by the given ID. If found, a heartbeat is triggered, extending the lifetime of the session. If ownerID is in use but the session in question has a different owner, this is a security violation and we report back no session found. +Find a session by the given ID. +If found, a heartbeat is triggered, extending the lifetime of the session. +If ownerID is in use but the session in question has a different owner, this is a security violation and we report back no session found. ### AssociateResource -AssociateResource associates a session ID to a monitored resource such that when a session expires, if a resource is currently associated with that ID based on the order of AssociateResource calls, then it will have its resource stopped. If id is uuid.Nil, this has no effect other than disassociation with a session. Be sure to include any remote information in the name. +Associate a session ID to a monitored resource so that when a session expires: + +- If a resource is currently associated with that ID based on the order of AssociateResource calls, then it will have its resource stopped. +- If id is uuid.Nil, this has no effect other than disassociation with a session. Be sure to include any remote information in the name. ### Close -Close stops the session manager but will not explicitly expire any sessions. +Stop the session manager without directing any sessions to expire. + +### expireLoop + +Set an expiration loop to be associated with a specific context. From 54290b3455082eaf27631720a4d812bb5ac5a049 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Fri, 8 Sep 2023 15:05:00 -0400 Subject: [PATCH 06/21] Update methods and parameters --- docs/program/apis/sessions.md | 124 +++++++++++++++--- .../include/program/apis/session-manager.md | 12 +- 2 files changed, 109 insertions(+), 27 deletions(-) diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index bbb6d42160..30d2843fa1 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -21,7 +21,7 @@ For example, imagine a wheeled rover gets a [`SetPower()`](/components/base/#set Without session management, the API request from the client sets the flow of electricity to the motors of the robot and then does not time out, causing the robot to continue driving forever, colliding with objects and people. With default configuration, sessions are automatically managed for you with Viam's `SessionsClient`. -If you want to manage sessions yourself, use Viam's sessions management API. +If you want to manage sessions yourself, use Viam's session management API. ### The `SessionsClient` @@ -204,7 +204,7 @@ session = session.SafetyMonitor(ctx, "my_base") ### ToContext -Attach a session to the given contxt. +Attach a session to the given context. **Parameters:** @@ -226,7 +226,8 @@ session = session.ToContext(context.Background(), my_session) The sessions package provides the `SessionManager` as an interface for holding sessions for a particular robot and managing the lifetime of each of these sessions. -`viam-server`'s Robot API provides a built-in `SessionManager`, which you can instantiate with `NewSessionManager()`: +`viam-server` provides an implementation of a `SessionManager` that is built into the Robot API. +Instantiate a new built-in `SessionManager` manually with `NewSessionManager()`: ### NewSessionManager @@ -234,14 +235,14 @@ Create a new manager for holding sessions. **Parameters:** -- `robot` [(Robot)](): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `heartbeatWindow` [(time.Duration)](): The heartbeat window you want this `SessionManager` to follow. +- `robot` [(Robot)](https://pkg.go.dev/go.viam.com/rdk/robot#Robot): The robot that you want this `SessionManager` to manage the client sessions of. +- `heartbeatWindow` [(time.Duration)](https://pkg.go.dev/time#Duration): The heartbeat window you want this `SessionManager` to follow. The window is the elapsed time between two instants as an int64 nanosecond count. The representation limits the largest representable duration to approximately 290 years. **Returns:** -- [(SessionManager)]: A new manager for holding sessions. +- [(*SessionManager)](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager): A new manager for holding sessions. -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#SafetyMonitorResourceName). +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#NewSessionManager). ``` go robot, err := client.New( @@ -262,30 +263,66 @@ Then, the following functions are available for use with `viam-server`'s Robot A {{< readfile "/static/include/program/apis/session-manager.md" >}} -Method Name | Description ------------ | ----------- -[`Start`](/program/apis/sessions/#start) | Create a new session that expects at least one heartbeat within the configured window. -[`All`](/program/apis/sessions/#all) | Get all active sessions. -[`FindByID`](/program/apis/sessions/#findbyid) | Find a session by the given ID. If found, trigger a heartbeat and extend the lifetime of the session. -[`AssociateResource`](/program/apis/sessions/#associateresource) | Associate a session ID to a monitored resource. All associated resources will be stopped with this session is expired. -[`Close`](/program/apis/sessions/#close) | Stop the session manager without directing any sessions to expire. -[`expireLoop`](/program/apis/sessions/#expireLoop) | Set an expiration loop to be associated with a specific context. - ### Start -[Relevant github](https://github.com/viamrobotics/rdk/blob/473673baf8c395fe12b959f5579adbf614db53ab/robot/session_manager.go#L35). - Create a new session that expects at least one heartbeat within the configured window. +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `heartbeatWindow` [(string)](https://pkg.go.dev/time#Duration): . + +**Returns:** + +- [(*session.Session)](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager): A new session. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.Start). + +``` go +newSession, err := mySessionManager.Start(context.Background(), nil) +``` + ### All -Get all sessions that are actively being held by this `SessionsManager`. +Get all sessions that are actively being held by this `SessionManager`. + +**Parameters:** + +- None + +**Returns:** + +- [([]*session.Session)](https://pkg.go.dev/go.viam.com/rdk@v0.8.0/session#Session): All active sessions associated with this `SessionManager`. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.All). + +``` go +sessions := mySessionManager.All(context.Background(), nil) +``` ### FindByID Find a session by the given ID. -If found, a heartbeat is triggered, extending the lifetime of the session. -If ownerID is in use but the session in question has a different owner, this is a security violation and we report back no session found. +If found, trigger a heartbeat, extending the lifetime of the session. + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `id` [(uuid.UUID)](https://pkg.go.dev/github.com/google/uuid#UUID): The client's UUID associated with this session. +- `ownerID` [(string)](https://pkg.go.dev/builtin#string): The client's ownerID associated with this session. +If ownerID is in use but the session in question has a different owner, this is a security violation and Viam reports back that no session is found. + +**Returns:** + +- [(*session.Session)](https://pkg.go.dev/go.viam.com/rdk@v0.8.0/session#Session): A new manager for holding sessions. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.Start). + +``` go +newSession, err := mySessionManager.Start(context.Background(), nil) +``` ### AssociateResource @@ -294,10 +331,55 @@ Associate a session ID to a monitored resource so that when a session expires: - If a resource is currently associated with that ID based on the order of AssociateResource calls, then it will have its resource stopped. - If id is uuid.Nil, this has no effect other than disassociation with a session. Be sure to include any remote information in the name. +**Parameters:** + +- `id` [(uuid.UUID)](https://pkg.go.dev/github.com/google/uuid#UUID): The client's UUID associated with this session. +- `resourceName` [(resource.Name)](https://pkg.go.dev/go.viam.com/rdk/resource#Name): The `name` you have configured for this resource on your robot. + +**Returns:** + +- None + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.AssociateResource). + +``` go +newSession, err := mySessionManager.AssociateResource(TODO) +``` + ### Close Stop the session manager without directing any sessions to expire. +**Parameters:** + +- None + +**Returns:** + +- None + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk@v0.8.0/robot#SessionManager.Start). + +``` go +mySessionManager.Close() +``` + ### expireLoop Set an expiration loop to be associated with a specific context. + +**Parameters:** + +- TODO + +**Returns:** + +- TODO + + + +``` go +err := mySessionManager.expireLoop(context.Background(), nil) +``` diff --git a/static/include/program/apis/session-manager.md b/static/include/program/apis/session-manager.md index daa72d9547..6872b8d9e8 100644 --- a/static/include/program/apis/session-manager.md +++ b/static/include/program/apis/session-manager.md @@ -1,8 +1,8 @@ Method Name | Description ----------- | ----------- -[`Start`](/program/apis/sessions/#start) | -[`All`](/program/apis/sessions/#all) | -[`FindByID`](/program/apis/sessions/#findbyid) | -[`AssociateResource`](/program/apis/sessions/#associateresource) | -[`Close`](/program/apis/sessions/#close) | -[`ServerInterceptors`](/program/apis/sessions/#serverinterceptors) | Provide gRPC interceptors to work with sessions. \ No newline at end of file +[`Start`](/program/apis/sessions/#start) | Create a new session that expects at least one heartbeat within the configured window. +[`All`](/program/apis/sessions/#all) | Get all active sessions. +[`FindByID`](/program/apis/sessions/#findbyid) | Find a session by the given ID. If found, trigger a heartbeat and extend the lifetime of the session. +[`AssociateResource`](/program/apis/sessions/#associateresource) | Associate a session ID to a monitored resource. All associated resources will be stopped with this session is expired. +[`Close`](/program/apis/sessions/#close) | Stop the session manager without directing any sessions to expire. +[`expireLoop`](/program/apis/sessions/#expireLoop) | Set an expiration loop to be associated with a specific context. From 8a3387e91fa0eb88f57c47e9e67b94499c65f53a Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Fri, 8 Sep 2023 15:11:44 -0400 Subject: [PATCH 07/21] fixup methods table --- static/include/program/apis/session-manager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/include/program/apis/session-manager.md b/static/include/program/apis/session-manager.md index 6872b8d9e8..476c728cdc 100644 --- a/static/include/program/apis/session-manager.md +++ b/static/include/program/apis/session-manager.md @@ -5,4 +5,4 @@ Method Name | Description [`FindByID`](/program/apis/sessions/#findbyid) | Find a session by the given ID. If found, trigger a heartbeat and extend the lifetime of the session. [`AssociateResource`](/program/apis/sessions/#associateresource) | Associate a session ID to a monitored resource. All associated resources will be stopped with this session is expired. [`Close`](/program/apis/sessions/#close) | Stop the session manager without directing any sessions to expire. -[`expireLoop`](/program/apis/sessions/#expireLoop) | Set an expiration loop to be associated with a specific context. +[`expireLoop`](/program/apis/sessions/#expireloop) | Set an expiration loop to be associated with a specific context. From c80d2a028722aa3f63c1c0ba6e760c92d1d19cf6 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 10:34:30 -0400 Subject: [PATCH 08/21] Clean up methods --- docs/program/apis/sessions.md | 30 ++++--------------- .../include/program/apis/session-manager.md | 1 - 2 files changed, 5 insertions(+), 26 deletions(-) diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index 30d2843fa1..a0f2a48faa 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -236,7 +236,7 @@ Create a new manager for holding sessions. **Parameters:** - `robot` [(Robot)](https://pkg.go.dev/go.viam.com/rdk/robot#Robot): The robot that you want this `SessionManager` to manage the client sessions of. -- `heartbeatWindow` [(time.Duration)](https://pkg.go.dev/time#Duration): The heartbeat window you want this `SessionManager` to follow. The window is the elapsed time between two instants as an int64 nanosecond count. The representation limits the largest representable duration to approximately 290 years. +- `heartbeatWindow` [(time.Duration)](https://pkg.go.dev/time#Duration): The heartbeat window you want this `SessionManager` to follow by default for managed sessions. The window is the elapsed time between two instants as an [int64](https://pkg.go.dev/builtin#int64) nanosecond count. The representation limits the largest representable duration to approximately 290 years. **Returns:** @@ -270,7 +270,7 @@ Create a new session that expects at least one heartbeat within the configured w **Parameters:** - `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `heartbeatWindow` [(string)](https://pkg.go.dev/time#Duration): . +- `heartbeatWindow` [(string)](https://pkg.go.dev/time#Duration): The heartbeat window you want this `SessionManager` to follow for this session. The window is the elapsed time between two instants as an [int64](https://pkg.go.dev/builtin#int64) nanosecond count. The representation limits the largest representable duration to approximately 290 years **Returns:** @@ -321,7 +321,7 @@ If ownerID is in use but the session in question has a different owner, this is For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.Start). ``` go -newSession, err := mySessionManager.Start(context.Background(), nil) +newSession, err := mySessionManager.Start(context.Background(), uuid, ownerID) ``` ### AssociateResource @@ -329,7 +329,7 @@ newSession, err := mySessionManager.Start(context.Background(), nil) Associate a session ID to a monitored resource so that when a session expires: - If a resource is currently associated with that ID based on the order of AssociateResource calls, then it will have its resource stopped. -- If id is uuid.Nil, this has no effect other than disassociation with a session. Be sure to include any remote information in the name. +- If id is `uuid.Nil`, this has no effect other than disassociation with a session. Be sure to include any remote information in the name. **Parameters:** @@ -343,7 +343,7 @@ Associate a session ID to a monitored resource so that when a session expires: For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.AssociateResource). ``` go -newSession, err := mySessionManager.AssociateResource(TODO) +newSession, err := mySessionManager.AssociateResource(uuid.Nil, "my_base") ``` ### Close @@ -363,23 +363,3 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk@v ``` go mySessionManager.Close() ``` - -### expireLoop - -Set an expiration loop to be associated with a specific context. - -**Parameters:** - -- TODO - -**Returns:** - -- TODO - - - -``` go -err := mySessionManager.expireLoop(context.Background(), nil) -``` diff --git a/static/include/program/apis/session-manager.md b/static/include/program/apis/session-manager.md index 476c728cdc..75d0637397 100644 --- a/static/include/program/apis/session-manager.md +++ b/static/include/program/apis/session-manager.md @@ -5,4 +5,3 @@ Method Name | Description [`FindByID`](/program/apis/sessions/#findbyid) | Find a session by the given ID. If found, trigger a heartbeat and extend the lifetime of the session. [`AssociateResource`](/program/apis/sessions/#associateresource) | Associate a session ID to a monitored resource. All associated resources will be stopped with this session is expired. [`Close`](/program/apis/sessions/#close) | Stop the session manager without directing any sessions to expire. -[`expireLoop`](/program/apis/sessions/#expireloop) | Set an expiration loop to be associated with a specific context. From 1fb10fffbc0d6f788229d3560bb1cec95625d8fc Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 10:53:37 -0400 Subject: [PATCH 09/21] clean up safety monitor phrasing a bit --- docs/program/apis/sessions.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index a0f2a48faa..8c07ef18e0 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -145,9 +145,9 @@ Go to your robot's **Code Sample** tab on the [Viam app](https://app.viam.com) f ### SafetyMonitor -`SafetyMonitor()` signals to the session that the given target {{< glossary_tooltip term_id="resource" text="resource" >}}, if present, should be safety monitored so that if this session ends and this session was the last to monitor the target, it will attempt to be stopped. +Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that, if it exists, if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. -This not be called by a resource being monitored itself, but instead by another client, like another resource, that is controlling a resource on behalf of some request or routine. +Do not call this method from the resource being monitored itself, but instead from another client, like another resource, that controls the monitored resource on behalf of some request or routine. For example, it would be appropriate for a remote [input controller](/components/input-controller/) resource to call a `SafetyMonitor()` on a base that it is remotely controlling the motion of. In the context of a gRPC handled request, this function can only be called before the first response is sent back. @@ -173,12 +173,9 @@ session = session.SafetyMonitor(ctx, myBase) ### SafetyMonitorResourceName -`SafetyMonitorResourceName()` works just like `SafetyMonitor()` but uses Viam {{< glossary_tooltip term_id="resource" text="resource" >}} names directly. -You assign the name of a resource when [configuring your robot](/manage/configuration/). +Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that, if it exists, if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. -This method, when called, signals to the session that the given target {{< glossary_tooltip term_id="resource" text="resource" >}}, if present, should be safety monitored so that if this session ends and this session was the last to monitor the target, it will attempt to be stopped. - -This not be called by a resource being monitored itself, but instead by another client, like another resource, that is controlling a resource on behalf of some request or routine. +Do not call this method from the resource being monitored itself, but instead from another client, like another resource, that controls the monitored resource on behalf of some request or routine. For example, it would be appropriate for a remote [input controller](/components/input-controller/) resource to call a `SafetyMonitor()` on a base that it is remotely controlling the motion of. In the context of a gRPC handled request, this function can only be called before the first response is sent back. From 1300794c764ab2f4e76bc4decbf1f760ca33229e Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 11:08:17 -0400 Subject: [PATCH 10/21] edit methods descriptions --- static/include/program/apis/session-management.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/static/include/program/apis/session-management.md b/static/include/program/apis/session-management.md index 617b517672..abae177dde 100644 --- a/static/include/program/apis/session-management.md +++ b/static/include/program/apis/session-management.md @@ -1,5 +1,5 @@ Method Name | Description ----------- | ----------- -[`SafetyMonitor`](/program/apis/sessions/#safetymonitor) | Signal to the session that the given target resource should be safety monitored so that if the session ends and this session was the last to monitor the target, it will attempt to be stopped. -[`SafetyMonitorResourceName`](/program/apis/sessions/#safetymonitorresourcename) | Signal to the session that the given target resource attached to this resource name should be safety monitored so that if the session ends and this session was the last to monitor the target, it will attempt to be stopped. +[`SafetyMonitor`](/program/apis/sessions/#safetymonitor) | Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. +[`SafetyMonitorResourceName`](/program/apis/sessions/#safetymonitorresourcename) | Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. [`ToContext`](/program/apis/sessions/#tocontext) | Attach a session to the given context. \ No newline at end of file From 2b2681843986cfda24c2d581775750647fe56c9f Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 11:09:48 -0400 Subject: [PATCH 11/21] Fixup --- docs/program/apis/sessions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index 8c07ef18e0..22f68e282b 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -271,7 +271,7 @@ Create a new session that expects at least one heartbeat within the configured w **Returns:** -- [(*session.Session)](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager): A new session. +- [(*Session)](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager): A new session. - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.Start). @@ -290,7 +290,7 @@ Get all sessions that are actively being held by this `SessionManager`. **Returns:** -- [([]*session.Session)](https://pkg.go.dev/go.viam.com/rdk@v0.8.0/session#Session): All active sessions associated with this `SessionManager`. +- [([]*Session)](https://pkg.go.dev/go.viam.com/rdk@v0.8.0/session#Session): All active sessions associated with this `SessionManager`. For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.All). @@ -312,7 +312,7 @@ If ownerID is in use but the session in question has a different owner, this is **Returns:** -- [(*session.Session)](https://pkg.go.dev/go.viam.com/rdk@v0.8.0/session#Session): A new manager for holding sessions. +- [(*Session)](https://pkg.go.dev/go.viam.com/rdk@v0.8.0/session#Session): A new manager for holding sessions. - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.Start). From ed2837a4767b94e468cc92ec5b04dbae4bccfb31 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 11:18:29 -0400 Subject: [PATCH 12/21] fixup accuracy --- docs/program/apis/sessions.md | 45 +++---------------- .../program/apis/session-management.md | 8 ++-- .../include/program/apis/session-manager.md | 7 --- static/include/program/apis/session.md | 5 +++ 4 files changed, 15 insertions(+), 50 deletions(-) delete mode 100644 static/include/program/apis/session-manager.md create mode 100644 static/include/program/apis/session.md diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index 22f68e282b..32cfb2a220 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -130,11 +130,11 @@ This option allows you to have full control over session management. After disabling the client, you must now manage each of your sessions manually with the session management API. You can do this with Viam's [client SDKs](https://pkg.go.dev/go.viam.com/rdk/session). -## API +## Session API -The session management API supports the following methods: +The `Session` API supports the following methods: -{{< readfile "/static/include/program/apis/session-management.md" >}} +{{< readfile "/static/include/program/apis/session.md" >}} {{% alert title="Tip" color="tip" %}} @@ -219,44 +219,9 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/s session = session.ToContext(context.Background(), my_session) ``` -## Manager API +## SessionManager API -The sessions package provides the `SessionManager` as an interface for holding sessions for a particular robot and managing the lifetime of each of these sessions. - -`viam-server` provides an implementation of a `SessionManager` that is built into the Robot API. -Instantiate a new built-in `SessionManager` manually with `NewSessionManager()`: - -### NewSessionManager - -Create a new manager for holding sessions. - -**Parameters:** - -- `robot` [(Robot)](https://pkg.go.dev/go.viam.com/rdk/robot#Robot): The robot that you want this `SessionManager` to manage the client sessions of. -- `heartbeatWindow` [(time.Duration)](https://pkg.go.dev/time#Duration): The heartbeat window you want this `SessionManager` to follow by default for managed sessions. The window is the elapsed time between two instants as an [int64](https://pkg.go.dev/builtin#int64) nanosecond count. The representation limits the largest representable duration to approximately 290 years. - -**Returns:** - -- [(*SessionManager)](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager): A new manager for holding sessions. - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#NewSessionManager). - -``` go -robot, err := client.New( - context.Background(), - "3minutes-main.0b2qnylnp0.viam.cloud", - logger, - client.WithDialOptions(rpc.WithCredentials(rpc.Credentials{ - Type: utils.CredentialsTypeRobotLocationSecret, - // Replace "" (including brackets) with your robot's secret - Payload: "", - })), -) - -mySessionManager := robot.NewSessionManager(robot, 1000) -``` - -Then, the following functions are available for use with `viam-server`'s Robot API's built-in `SessionManager`: +The `SessionManager` API supports the following methods: {{< readfile "/static/include/program/apis/session-manager.md" >}} diff --git a/static/include/program/apis/session-management.md b/static/include/program/apis/session-management.md index abae177dde..75d0637397 100644 --- a/static/include/program/apis/session-management.md +++ b/static/include/program/apis/session-management.md @@ -1,5 +1,7 @@ Method Name | Description ----------- | ----------- -[`SafetyMonitor`](/program/apis/sessions/#safetymonitor) | Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. -[`SafetyMonitorResourceName`](/program/apis/sessions/#safetymonitorresourcename) | Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. -[`ToContext`](/program/apis/sessions/#tocontext) | Attach a session to the given context. \ No newline at end of file +[`Start`](/program/apis/sessions/#start) | Create a new session that expects at least one heartbeat within the configured window. +[`All`](/program/apis/sessions/#all) | Get all active sessions. +[`FindByID`](/program/apis/sessions/#findbyid) | Find a session by the given ID. If found, trigger a heartbeat and extend the lifetime of the session. +[`AssociateResource`](/program/apis/sessions/#associateresource) | Associate a session ID to a monitored resource. All associated resources will be stopped with this session is expired. +[`Close`](/program/apis/sessions/#close) | Stop the session manager without directing any sessions to expire. diff --git a/static/include/program/apis/session-manager.md b/static/include/program/apis/session-manager.md deleted file mode 100644 index 75d0637397..0000000000 --- a/static/include/program/apis/session-manager.md +++ /dev/null @@ -1,7 +0,0 @@ -Method Name | Description ------------ | ----------- -[`Start`](/program/apis/sessions/#start) | Create a new session that expects at least one heartbeat within the configured window. -[`All`](/program/apis/sessions/#all) | Get all active sessions. -[`FindByID`](/program/apis/sessions/#findbyid) | Find a session by the given ID. If found, trigger a heartbeat and extend the lifetime of the session. -[`AssociateResource`](/program/apis/sessions/#associateresource) | Associate a session ID to a monitored resource. All associated resources will be stopped with this session is expired. -[`Close`](/program/apis/sessions/#close) | Stop the session manager without directing any sessions to expire. diff --git a/static/include/program/apis/session.md b/static/include/program/apis/session.md new file mode 100644 index 0000000000..abae177dde --- /dev/null +++ b/static/include/program/apis/session.md @@ -0,0 +1,5 @@ +Method Name | Description +----------- | ----------- +[`SafetyMonitor`](/program/apis/sessions/#safetymonitor) | Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. +[`SafetyMonitorResourceName`](/program/apis/sessions/#safetymonitorresourcename) | Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. +[`ToContext`](/program/apis/sessions/#tocontext) | Attach a session to the given context. \ No newline at end of file From 729654c613b9b9de7f814145aa495874484dc60f Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 11:20:08 -0400 Subject: [PATCH 13/21] Fixup typo --- docs/program/apis/sessions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index 32cfb2a220..96da2581e4 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -167,7 +167,7 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/s ```go myBase, err := base.FromRobot(robot, "my_base") -// Signal to the session that the given target resource should be safety monitered. +// Signal to the session that the given target resource should be safety monitored. session = session.SafetyMonitor(ctx, myBase) ``` @@ -195,7 +195,7 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/s ```go myBase, err := base.FromRobot(robot, "my_base") -// Signal to the session that the given target resource should be safety monitered. +// Signal to the session that the given target resource should be safety monitored. session = session.SafetyMonitor(ctx, "my_base") ``` From efc91adef1c76045e3e03455eb2bd62fde7920b6 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 11:31:00 -0400 Subject: [PATCH 14/21] Edit page descriptions --- .../apis/{sessions.md => session-manager.md} | 100 ++---------------- docs/program/apis/session.md | 100 ++++++++++++++++++ 2 files changed, 106 insertions(+), 94 deletions(-) rename docs/program/apis/{sessions.md => session-manager.md} (69%) create mode 100644 docs/program/apis/session.md diff --git a/docs/program/apis/sessions.md b/docs/program/apis/session-manager.md similarity index 69% rename from docs/program/apis/sessions.md rename to docs/program/apis/session-manager.md index 96da2581e4..802b15d133 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/session-manager.md @@ -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`. Session management: @@ -20,10 +21,10 @@ Session management allows for safer operation of robots that physically move. For example, imagine a wheeled rover gets a [`SetPower()`](/components/base/#setpower) command as the last input from a client before the connection to the robot is interrupted. Without session management, the API request from the client sets the flow of electricity to the motors of the robot and then does not time out, causing the robot to continue driving forever, colliding with objects and people. -With default configuration, sessions are automatically managed for you with Viam's `SessionsClient`. +With default configuration, sessions are automatically managed for you with Viam's session management API's default `SessionsClient`. If you want to manage sessions yourself, use Viam's session management API. -### The `SessionsClient` +### What is a `SessionsClient` A Viam robot has many clients because a client is anything that is receiving the information served by `viam-server` running on the robot, which includes the primary part, sub-parts, client SDKs, and more. A *client* of a Viam robot could be an SDK script controlling the robot, an input controller, or just the different resources on the robot talking amongst themselves. @@ -130,100 +131,11 @@ This option allows you to have full control over session management. After disabling the client, you must now manage each of your sessions manually with the session management API. You can do this with Viam's [client SDKs](https://pkg.go.dev/go.viam.com/rdk/session). -## Session API - -The `Session` API supports the following methods: - -{{< readfile "/static/include/program/apis/session.md" >}} - -{{% alert title="Tip" color="tip" %}} - -The following code examples assume that you have a robot configured with a [base component](/components/base/), and that you add the required code to connect to your robot and import any required packages, including the `sessions` package, at the top of your client file. -Go to your robot's **Code Sample** tab on the [Viam app](https://app.viam.com) for boilerplate code to connect to your robot. - -{{% /alert %}} - -### SafetyMonitor - -Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that, if it exists, if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. - -Do not call this method from the resource being monitored itself, but instead from another client, like another resource, that controls the monitored resource on behalf of some request or routine. -For example, it would be appropriate for a remote [input controller](/components/input-controller/) resource to call a `SafetyMonitor()` on a base that it is remotely controlling the motion of. - -In the context of a gRPC handled request, this function can only be called before the first response is sent back. -In the case of unary, it can only be called before the handler returns. - -**Parameters:** - -- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `target` [(resource.Resource)](https://pkg.go.dev/go.viam.com/rdk/resource#Resource): The target resource. - -**Returns:** - -- None - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#SafetyMonitor). - -```go -myBase, err := base.FromRobot(robot, "my_base") - -// Signal to the session that the given target resource should be safety monitored. -session = session.SafetyMonitor(ctx, myBase) -``` - -### SafetyMonitorResourceName - -Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that, if it exists, if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. - -Do not call this method from the resource being monitored itself, but instead from another client, like another resource, that controls the monitored resource on behalf of some request or routine. -For example, it would be appropriate for a remote [input controller](/components/input-controller/) resource to call a `SafetyMonitor()` on a base that it is remotely controlling the motion of. - -In the context of a gRPC handled request, this function can only be called before the first response is sent back. -In the case of unary, it can only be called before the handler returns. - -**Parameters:** - -- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `targetName` [(resource.Name)](https://pkg.go.dev/go.viam.com/rdk/resource#Name): The `name` you have set for the resource in configuration. - -**Returns:** - -- None - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#SafetyMonitorResourceName). - -```go -myBase, err := base.FromRobot(robot, "my_base") - -// Signal to the session that the given target resource should be safety monitored. -session = session.SafetyMonitor(ctx, "my_base") -``` - -### ToContext - -Attach a session to the given context. - -**Parameters:** - -- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `sess` [(*Session)](https://pkg.go.dev/go.viam.com/rdk/session#Session): The session object that you wish to attach to this context. - -**Returns:** - -- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#ToContext). - -```go -// Attach session "my session" to the given Context -session = session.ToContext(context.Background(), my_session) -``` - -## SessionManager API +## API The `SessionManager` API supports the following methods: -{{< readfile "/static/include/program/apis/session-manager.md" >}} +{{< readfile "/static/include/program/apis/session-management.md" >}} ### Start diff --git a/docs/program/apis/session.md b/docs/program/apis/session.md new file mode 100644 index 0000000000..1c17386d58 --- /dev/null +++ b/docs/program/apis/session.md @@ -0,0 +1,100 @@ +--- +title: "The Session API" +linkTitle: "Session API" +weight: 20 +type: "docs" +description: "The session API offers resource safety monitoring and context attachment." +tags: ["client", "sdk", "viam-server", "networking", "apis", "robot api", "session", "sessions", "session management"] +--- + +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*. + +## API + +The `Session` API supports the following methods: + +{{< readfile "/static/include/program/apis/session.md" >}} + +{{% alert title="Tip" color="tip" %}} + +The following code examples assume that you have a robot configured with a [base component](/components/base/), and that you add the required code to connect to your robot and import any required packages, including the `sessions` package, at the top of your client file. +Go to your robot's **Code Sample** tab on the [Viam app](https://app.viam.com) for boilerplate code to connect to your robot. + +{{% /alert %}} + +### SafetyMonitor + +Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that, if it exists, if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. + +Do not call this method from the resource being monitored itself, but instead from another client, like another resource, that controls the monitored resource on behalf of some request or routine. +For example, it would be appropriate for a remote [input controller](/components/input-controller/) resource to call a `SafetyMonitor()` on a base that it is remotely controlling the motion of. + +In the context of a gRPC handled request, this function can only be called before the first response is sent back. +In the case of unary, it can only be called before the handler returns. + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `target` [(resource.Resource)](https://pkg.go.dev/go.viam.com/rdk/resource#Resource): The target resource. + +**Returns:** + +- None + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#SafetyMonitor). + +```go +myBase, err := base.FromRobot(robot, "my_base") + +// Signal to the session that the given target resource should be safety monitered. +session = session.SafetyMonitor(ctx, myBase) +``` + +### SafetyMonitorResourceName + +Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that, if it exists, if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. + +Do not call this method from the resource being monitored itself, but instead from another client, like another resource, that controls the monitored resource on behalf of some request or routine. +For example, it would be appropriate for a remote [input controller](/components/input-controller/) resource to call a `SafetyMonitor()` on a base that it is remotely controlling the motion of. + +In the context of a gRPC handled request, this function can only be called before the first response is sent back. +In the case of unary, it can only be called before the handler returns. + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `targetName` [(resource.Name)](https://pkg.go.dev/go.viam.com/rdk/resource#Name): The `name` you have set for the resource in configuration. + +**Returns:** + +- None + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#SafetyMonitorResourceName). + +```go +myBase, err := base.FromRobot(robot, "my_base") + +// Signal to the session that the given target resource should be safety monitered. +session = session.SafetyMonitor(ctx, "my_base") +``` + +### ToContext + +Attach a session to the given context. + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `sess` [(*Session)](https://pkg.go.dev/go.viam.com/rdk/session#Session): The session object that you wish to attach to this context. + +**Returns:** + +- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/session#ToContext). + +```go +// Attach session "my session" to the given Context +session = session.ToContext(context.Background(), my_session) +``` From 15a64a88f01d2ffccf84d07858f14d2a2c8e9e1e Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 12:21:41 -0400 Subject: [PATCH 15/21] Update session-manager.md --- docs/program/apis/session-manager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/program/apis/session-manager.md b/docs/program/apis/session-manager.md index 802b15d133..802d68285b 100644 --- a/docs/program/apis/session-manager.md +++ b/docs/program/apis/session-manager.md @@ -9,7 +9,7 @@ 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.* -Sessions each have [their own API](/program/apis/session), which is a client of `viam-server`. +Sessions each have [their own API](/program/apis/session/), which is a client of `viam-server`. Session management: From 6ec24e2db74e7f2bb06de699499d461791c91984 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 12:23:00 -0400 Subject: [PATCH 16/21] Apply suggestions from code review --- docs/program/apis/session-manager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/program/apis/session-manager.md b/docs/program/apis/session-manager.md index 802d68285b..db147a24e6 100644 --- a/docs/program/apis/session-manager.md +++ b/docs/program/apis/session-manager.md @@ -9,7 +9,7 @@ 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.* -Sessions each have [their own API](/program/apis/session/), which is a client of `viam-server`. +Sessions each have [their own API](/program/apis/session/), which is a client of both `viam-server` and the [session management API](/program/apis/sessions). Session management: From 42345e9e7293c7b687d118c5fa96417b1eaf2444 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 12:25:50 -0400 Subject: [PATCH 17/21] Add alias and clean up link --- docs/program/apis/session-manager.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/program/apis/session-manager.md b/docs/program/apis/session-manager.md index db147a24e6..bd2d65751e 100644 --- a/docs/program/apis/session-manager.md +++ b/docs/program/apis/session-manager.md @@ -5,11 +5,13 @@ weight: 20 type: "docs" description: "How to use the session management API with Viam's Client SDKs." tags: ["client", "sdk", "viam-server", "networking", "apis", "robot api", "session", "sessions", "session management"] +aliases: + /program/apis/sessions/ --- 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.* -Sessions each have [their own API](/program/apis/session/), which is a client of both `viam-server` and the [session management API](/program/apis/sessions). +Sessions each have [their own API](/program/apis/session/), which is a client of both `viam-server` and the session management API. Session management: From d0d917b018fd0e9094cd3931b8ed61f0c654b96d Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 14:30:50 -0400 Subject: [PATCH 18/21] make title better --- docs/program/apis/session-manager.md | 2 +- docs/program/apis/session.md | 4 ++-- .../apis/{session-management.md => session-manager.md} | 0 static/include/program/apis/session.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) rename static/include/program/apis/{session-management.md => session-manager.md} (100%) diff --git a/docs/program/apis/session-manager.md b/docs/program/apis/session-manager.md index bd2d65751e..4c3e1fca25 100644 --- a/docs/program/apis/session-manager.md +++ b/docs/program/apis/session-manager.md @@ -137,7 +137,7 @@ You can do this with Viam's [client SDKs](https://pkg.go.dev/go.viam.com/rdk/ses The `SessionManager` API supports the following methods: -{{< readfile "/static/include/program/apis/session-management.md" >}} +{{< readfile "/static/include/program/apis/session-manager.md" >}} ### Start diff --git a/docs/program/apis/session.md b/docs/program/apis/session.md index 1c17386d58..2eae0aa248 100644 --- a/docs/program/apis/session.md +++ b/docs/program/apis/session.md @@ -1,9 +1,9 @@ --- -title: "The Session API" +title: "Monitor resource sessions with the Session API" linkTitle: "Session API" weight: 20 type: "docs" -description: "The session API offers resource safety monitoring and context attachment." +description: "Safety monitor resources and attach contexts to sessions with the Session API." tags: ["client", "sdk", "viam-server", "networking", "apis", "robot api", "session", "sessions", "session management"] --- diff --git a/static/include/program/apis/session-management.md b/static/include/program/apis/session-manager.md similarity index 100% rename from static/include/program/apis/session-management.md rename to static/include/program/apis/session-manager.md diff --git a/static/include/program/apis/session.md b/static/include/program/apis/session.md index abae177dde..10f082fdf0 100644 --- a/static/include/program/apis/session.md +++ b/static/include/program/apis/session.md @@ -2,4 +2,4 @@ Method Name | Description ----------- | ----------- [`SafetyMonitor`](/program/apis/sessions/#safetymonitor) | Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. [`SafetyMonitorResourceName`](/program/apis/sessions/#safetymonitorresourcename) | Safety monitor this target {{< glossary_tooltip term_id="resource" text="resource" >}} so that if this session ends as the last session to monitor it, the `SessionManager` attempts to stop the resource by calling the `Stop()` method of the resource API. -[`ToContext`](/program/apis/sessions/#tocontext) | Attach a session to the given context. \ No newline at end of file +[`ToContext`](/program/apis/sessions/#tocontext) | Attach a session to the given context. From e95127055b00447982c0c3a109c8279ff8d620e2 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 14:31:19 -0400 Subject: [PATCH 19/21] Update docs/program/apis/session-manager.md --- docs/program/apis/session-manager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/program/apis/session-manager.md b/docs/program/apis/session-manager.md index 4c3e1fca25..71cf0a1c08 100644 --- a/docs/program/apis/session-manager.md +++ b/docs/program/apis/session-manager.md @@ -26,7 +26,7 @@ Without session management, the API request from the client sets the flow of ele With default configuration, sessions are automatically managed for you with Viam's session management API's default `SessionsClient`. If you want to manage sessions yourself, use Viam's session management API. -### What is a `SessionsClient` +### What is a `SessionsClient`? A Viam robot has many clients because a client is anything that is receiving the information served by `viam-server` running on the robot, which includes the primary part, sub-parts, client SDKs, and more. A *client* of a Viam robot could be an SDK script controlling the robot, an input controller, or just the different resources on the robot talking amongst themselves. From 1c1d9f1713b772f71b8d10c9632d45cbc0dc6ab9 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 14:34:42 -0400 Subject: [PATCH 20/21] Apply suggestions from code review --- docs/program/apis/session-manager.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/program/apis/session-manager.md b/docs/program/apis/session-manager.md index 71cf0a1c08..028d25b3c3 100644 --- a/docs/program/apis/session-manager.md +++ b/docs/program/apis/session-manager.md @@ -146,7 +146,7 @@ Create a new session that expects at least one heartbeat within the configured w **Parameters:** - `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `heartbeatWindow` [(string)](https://pkg.go.dev/time#Duration): The heartbeat window you want this `SessionManager` to follow for this session. The window is the elapsed time between two instants as an [int64](https://pkg.go.dev/builtin#int64) nanosecond count. The representation limits the largest representable duration to approximately 290 years +- `heartbeatWindow` [(time.Duration)](https://pkg.go.dev/time#Duration): The heartbeat window you want this `SessionManager` to follow for this session. The window is the elapsed time between two instants as an [int64](https://pkg.go.dev/builtin#int64) nanosecond count. The representation limits the largest representable duration to approximately 290 years **Returns:** @@ -169,7 +169,7 @@ Get all sessions that are actively being held by this `SessionManager`. **Returns:** -- [([]*Session)](https://pkg.go.dev/go.viam.com/rdk@v0.8.0/session#Session): All active sessions associated with this `SessionManager`. +- [([]*Session)](https://pkg.go.dev/go.viam.com/rdk/session#Session): All active sessions associated with this `SessionManager`. For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.All). @@ -191,7 +191,7 @@ If ownerID is in use but the session in question has a different owner, this is **Returns:** -- [(*Session)](https://pkg.go.dev/go.viam.com/rdk@v0.8.0/session#Session): A new manager for holding sessions. +- [(*SessionManager)](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager): A new manager for holding sessions. - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.Start). @@ -234,7 +234,7 @@ Stop the session manager without directing any sessions to expire. - None -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk@v0.8.0/robot#SessionManager.Start). +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/robot#SessionManager.Start). ``` go mySessionManager.Close() From dadae246166ac7c7f4dafac771d4d130de978c24 Mon Sep 17 00:00:00 2001 From: Sierra Guequierre Date: Mon, 11 Sep 2023 14:35:56 -0400 Subject: [PATCH 21/21] Add clarification for built-in session manager --- docs/program/apis/session-manager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/program/apis/session-manager.md b/docs/program/apis/session-manager.md index 028d25b3c3..6ce690f960 100644 --- a/docs/program/apis/session-manager.md +++ b/docs/program/apis/session-manager.md @@ -135,7 +135,7 @@ You can do this with Viam's [client SDKs](https://pkg.go.dev/go.viam.com/rdk/ses ## API -The `SessionManager` API supports the following methods: +The `SessionManager` API built-in to the [Robot API](/program/apis/robot/) supports the following methods: {{< readfile "/static/include/program/apis/session-manager.md" >}}