DOCS-1069: Document API methods for Session and SessionManager

docs/program/apis/sessions.md → 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`.
-If you want to manage sessions yourself, use Viam's sessions management API.
+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.
@@ -126,6 +127,113 @@ 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 `SessionManager` API supports the following methods:
+
+{{< readfile "/static/include/program/apis/session-management.md" >}}
+
+### Start
+
+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): 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:**
+
+- [(*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 `SessionManager`.
+
+**Parameters:**
+
+- None
+
+**Returns:**
+
+- [([]*Session)](https://pkg.go.dev/go.viam.com/[email protected]/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, 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)](https://pkg.go.dev/go.viam.com/[email protected]/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(), uuid, ownerID)
+```
+
+### AssociateResource
+
+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(uuid.Nil, "my_base")
+```
+
+### 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/[email protected]/robot#SessionManager.Start).
+
+``` go
+mySessionManager.Close()
+```

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)
+```

static/include/program/apis/session-management.md

@@ -0,0 +1,7 @@
+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.

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.