数据面
文件、进程、桌面与服务连接直接发往运行 Workspace 的 node，不经过 ctrl 转发。本页介绍怎样向 ctrl 申请会话凭证、让它保持有效，并带着它访问 node。
每次访问数据面都分两步：
- 向 ctrl 申请一张短期的会话凭证访问数据面用的短期凭证。向 ctrl 申请，同时得到运行这个 Workspace 的 node 的地址。，响应里同时给出 node 的地址。
- 带着凭证向这个地址发请求。
申请会话凭证
对 AVAILABLE 的 Workspace，在 ctrl 上调用 DataPlaneSessionService/CreateDataPlaneSession。请求与响应的全部字段见 DataPlaneSessionService。
- 在
metadata.command_id里给出幂等键。相同的 ID 重放返回相同的凭证。 requested_scopes只申请调用需要的范围。各方法需要的范围见数据面服务。- 申请
SERVICE_CONNECT时，在service_targets里列出精确的目标。 - 不希望凭证用到更新的执行上时，把
expected_generation设为你认为的当前执行代Workspace 的一轮运行。每次启动成功都开始新的一代，从 1 起编号；上一代的凭证、进程与连接全部失效。，不符返回FAILED_PRECONDITION。
请求被 FAILED_PRECONDITION 拒绝时，错误详情的 observed_workspace 带 Workspace 当时的状态。据此判断执行是否已结束：
| Workspace | 含义 |
|---|---|
generation 与 expected_generation 不同，或状态是 STOPPED、DELETED | 这次执行已结束，它的进程和连接都不在了 |
状态是 STOPPING、DELETING、FAILED、UNKNOWN，或仍是 AVAILABLE（比如已到期但还没停） | 执行可能还在运行，稍后再问 |
凭证有效期
lifetime 在两种策略中选一种：
lifetime | 凭证的有效期 | 约束 |
|---|---|---|
| 缺省 | 按 requested_ttl。默认 5 分钟，上限 15 分钟。0 表示使用默认值。其他值要是 1 秒到上限之间的整秒数，超过上限返回 invalid_argument | 无 |
EXECUTION | 绑定 Workspace 的本次执行：最长 1 小时，Workspace 的到期时间更早时到期即止 | 必须同时给出 expected_generation，不能带 requested_ttl。能力名 workspace.session.execution |
响应
响应的 credential 是凭证本身；session 里有 node 数据面的地址 endpoint、实际授予的范围与目标，以及到期时间 expires_at。session.generation 是签发时 Workspace 的执行代：值相同就是同一次执行，endpoint 变了也一样。所有数据面请求都以 session.endpoint 为 base URL。
警告
把 credential 当作机密保管：不要解析、不要写入日志、不要放进 URL。需要关联请求时，在日志里记 session.session_id。
缓存与续期凭证
缓存凭证、供多个请求复用时：
- 已用掉约 80% 有效期之后（再减去最多 10% 的随机抖动）就重新申请，不要等到只剩几秒。node 允许 30 秒时钟偏差，固定的小余量会在你以为凭证还有效时被拒绝。
- node 返回的
reason是SESSION_EXPIRED、SESSION_REVOKED或UNAUTHENTICATED时丢掉缓存的凭证，下一次请求重新申请，不要拿同一张凭证重试。 - 不要只看错误码。guest 拒绝访问文件、凭证缺少权限范围也返回
permission_denied，它们的reason是PERMISSION_DENIED，换凭证没有用。
交互式会话
交互式会话比一张凭证活得久。输出流只在建立时鉴权一次，但每次按键的 SendInput、每次 Resize 和 SendSignal 都是新的 RPC，都要重新鉴权。
这类调用方要在 expires_at 之前用新的 command_id 再申请一张凭证换上，不必重开输出流。kibo workspace terminal 就是这么做的。
访问 node
向 session.endpoint 发请求，加上一个 Authorization: Bearer <credential> 头。只能有一个这样的头。
node 数据面的 TLS 设置与 ctrl 不同：
- 信任系统根证书，再加上身份里的
server-ca.pem；主机名按标准规则校验。 - 不跟随 HTTP 重定向。
- 流式方法需要 HTTP/2。
两个入口的设置对照见 TLS 配置。
数据面服务
每个方法需要表中同一行的权限范围：
| 服务 | 方法 | 需要的范围 |
|---|---|---|
FilesystemService | Stat、ListDir、WatchDir（服务端流） | FILE_READ |
FilesystemService | MakeDir、Move、Remove | FILE_WRITE |
ProcessService | Start（服务端流）、Attach（服务端流）、SendInput、CloseStdin、SendSignal、Resize | PROCESS |
DesktopService | Screenshot、PerformActions | DESKTOP |
ServiceConnectionService | Connect（双向流） | SERVICE_CONNECT |
HTTP /v1/files | GET | FILE_READ |
HTTP /v1/files | PUT | FILE_WRITE |
WebSocket /v1/service | GET | SERVICE_CONNECT |
流的中断
凭证到期只影响新建的 RPC，已经建立的流照常运行。
以下情况会结束进行中的流：
- 凭证被撤销。
- Workspace 重新启动，进入新的执行代。
- 有人调用了
WorkspaceService/RevokeWorkspaceDataPlane。 - node 换用新的数据面进程，例如升级 node 之后。旧进程的 HTTP/2 连接先收到 GOAWAY 再关闭，进行中的流随之结束。
有的客户端库把 GOAWAY 之后的关闭报成协议错误，例如 Go 的 Connect 客户端报 invalid_argument: protocol error: incomplete envelope。同样按连接中断处理：进程流续传，重新开始目录监视。