Files
coder/tailnet/proto/version.go
T
Andrew Aquino 3aeb7f85d9 feat: correlate coder CLI workspace sessions with client_session_id (#28313)
## Summary

Implements DEVEX-664: the coder CLI commands that open a workspace
connection now generate a client session ID and attach it to their
requests, logs, and existing network telemetry, per the connection-log
RFC.

Commands opt in explicitly with a `client_session_id` annotation. The
opted-in set is `coder ssh`, `coder start`, `coder stop`, and `coder
update`. Long-running daemon commands (`coder server`, `agent`,
`provisionerd`, and so on) deliberately stay out, so they never carry a
meaningless session ID in their logs, request baggage, or telemetry.

- **Generate / resolve**: a 16-byte lowercase-hex session ID is
generated per opted-in invocation. When `CODER_TRACE_SESSION_ID` is set
(so Toolbox and the VS Code plugin can correlate the CLI they spawn),
that value is used verbatim; a warning is logged if it is not the
canonical 32-char lowercase hex form, since coderd/agent middleware drop
non-canonical values.
- **Requests**: the ID is attached to every request as
`client_session_id` W3C baggage via a transport wrapper, independent of
whether tracing is enabled. The already-merged coderd tracing middleware
(#27671) reads it.
- **Coordinate websocket**: the ID is also set explicitly as baggage on
the tailnet coordinate handshake in `workspacesdk.DialAgent`, so
coderd's `/api/v2/workspaceagents/{id}/coordinate` endpoint logs it (it
does not rely on the CLI transport for that dial).
- **Logs**: the ID is added to the command's log context.
- **Existing telemetry**: the ID is added to tailnet `TelemetryEvent`
(`client_session_id`, new field 20; proto minor version bumped) and
plumbed from the CLI through `workspacesdk.DialAgent`.

Scope is the coder CLI client only (RFC glossary + requirement 5), and
within the CLI only the opted-in workspace-connecting commands above.
This PR is independent of #28039 (the agent middleware that consumes the
baggage); it depends only on `tracing.SessionIDBaggageKey`, which is
already on `main` via #27671.

## Out of scope

RFC requirements 7-16 (connection-state change logging,
`connection_logs` columns, log buffering, routing/disconnect-reason
logs, coordination-protocol plumbing, `agentssh`/`reconnectingpty`
command logging, support-bundle log capture) and requirements 4.2/4.3
(VS Code telemetry, Prometheus stats) are separate tickets. IDE plugins,
Toolbox, and the daemon commands are also out of scope.

## Testing

- `go test ./coderd/tracing/... ./cli/... ./tailnet/...
./codersdk/workspacesdk/...` (unit tests for the generator, the
env/generate resolver, per-command opt-in, the baggage transport
wrapper, the coordinate-dial baggage helper, and the telemetry field).
- `go build ./...`, `go vet`, and `golangci-lint` pass on the touched
packages.
- `make tailnet/proto/tailnet.pb.go` regenerated the proto; the proto
minor version was bumped and `postStartup` now connects at the current
agent API version so `TestWorkspaceAgent_Startup/OK` tracks it.

> Note: the pre-commit `enterprise/cli/.gen-golden` step could not run
in this environment (no Postgres: `open postgres connection: EOF`).
`cli/testdata/.gen-golden` passed; this change adds no serpent flags, so
there is no CLI help/golden drift.

<details>
<summary>Implementation plan</summary>

### Scope mapping (RFC -> DEVEX-664)

In scope (the CLI workspace-connecting subset of RFC phase 2):
- Req 1: generate a 16-byte session ID as 32-char lowercase hex.
- Req 2: add the session ID to every log the command makes for the
session.
- Req 3: attach the session ID to every API request via
`client_session_id` baggage, including the coordinate websocket
handshake. (The query-param fallback is browser-only; not applicable to
the CLI.)
- Req 4.1: attach the session ID to CLI network telemetry.
- Req 5 / 5.3: support `CODER_TRACE_SESSION_ID`; when set, use it
instead of generating.

### Resolved decisions

- Scope: opt-in per command via a `client_session_id` annotation;
opted-in set is `coder ssh`, `coder start`, `coder stop`, `coder
update`. Daemon commands are excluded.
- `CODER_TRACE_SESSION_ID`: when set, use the value verbatim; warn if it
is not canonical 32-char lowercase hex. When unset, generate a fresh ID.
- Existing telemetry = CLI network telemetry (tailnet `TelemetryEvent`);
requires a new proto field + plumbing and a proto minor version bump.
- Coordinate endpoint: set the session ID as baggage on the coordinate
handshake explicitly in `DialAgent` (header, not query param) so it is
logged server-side without relying on the CLI transport.
- Shared helper: add `tracing.NewSessionID()` and export the validator
as `tracing.ValidSessionID` for a single source of truth.

### Implementation

1. `coderd/tracing`: add `NewSessionID()` (16 random bytes,
hex-encoded); export `ValidSessionID`.
2. `cli`: resolve the ID from `CODER_TRACE_SESSION_ID` or generate;
attach `client_session_id` baggage to every request via
`wrapTransportWithSessionIDHeader`, gated on the
`annotationClientSessionID` opt-in; add it to the command log context.
3. `tailnet` + `codersdk/workspacesdk`: add `client_session_id` to
`TelemetryEvent`, an `Options.ClientSessionID`/`Conn.clientSessionID`
set in `newTelemetryEvent`, a `DialAgentOptions.ClientSessionID` plumbed
from the opted-in commands, and the coordinate-handshake baggage in
`DialAgent`.

</details>

---

_This PR was created by Coder Agents on behalf of @aqandrew._
2026-09-02 19:31:01 +00:00

97 lines
3.5 KiB
Go

package proto
import (
"github.com/coder/coder/v2/apiversion"
)
// Version history:
//
// API v1:
// - retroactively applied name for the HTTP Rest APIs for the Agent and the
// JSON over websocket coordination and DERP Map APIs for Tailnet
//
// API v2.0:
// - Shipped in Coder v2.8.0
// - first dRPC over yamux over websocket APIs for tailnet and agent
//
// API v2.1:
// - Shipped in Coder v2.12.0
// - Added support for multiple banners via the GetAnnouncementBanners RPC on
// the Agent API.
// - No changes to the Tailnet API.
//
// API v2.2:
// - Shipped in Coder v2.13.0
// - Added support for network telemetry via the PostTelemetry RPC on the
// Tailnet API.
// - No changes to the Agent API.
//
// API v2.3:
// - Shipped in Coder v2.18.0
// - Added support for client Resume Tokens on the Tailnet API via the
// RefreshResumeToken RPC. (This actually shipped in Coder v2.15.0, but we
// forgot to increment the API version. If you dial for API v2.2, you MAY
// be connected to a server that supports RefreshResumeToken, but be
// prepared to process "unsupported" errors.)
// - Added support for WorkspaceUpdates RPC on the Tailnet API.
// - Added support for ScriptCompleted RPC on the Agent API. (This actually
// shipped in Coder v2.16.0, but we forgot to increment the API version. If
// you dial for API v2.2, you MAY be connected to a server that supports
// ScriptCompleted, but be prepared to process "unsupported" errors.)
//
// API v2.4:
// - Shipped in Coder v2.20.0
// - Added support for GetResourcesMonitoringConfiguration and
// PushResourcesMonitoringUsage RPCs on the Agent API.
// - Added support for reporting connection events for auditing via the
// ReportConnection RPC on the Agent API.
//
// API v2.5:
// - Shipped in Coder v2.23.0
// - Added `ParentId` to the agent manifest.
//
// API v2.6:
// - Shipped in Coder v2.24.0
// - Added support for CreateSubAgent RPC on the Agent API.
// - Added support for DeleteSubAgent RPC on the Agent API.
// - Added support for ListSubAgents RPC on the Agent API.
// - Add ORGANIZATION SharingLevel
//
// API v2.7:
// - Added support for ReportBoundaryLogs RPC on the Agent API for forwarding
// boundary audit logs to coderd.
//
// API v2.8:
// - Added support for pre-created sub agents on the Agent API.
// - Added support for UpdateAppStatus on the Agent API.
//
// API v2.9:
// - Added session_id and confined_process fields to
// ReportBoundaryLogsRequest on the Agent API.
// - Added sequence_number field to BoundaryLog on the Agent API.
//
// API v2.10:
// - Added PushContextState RPC on the Agent API for pushing
// resolved workspace context snapshots (instruction files,
// skills, MCP configs, MCP server tool lists) from the
// agent to coderd. Adds ContextResource, PushContextStateRequest,
// and PushContextStateResponse messages. The coderd handler
// ships as a stub returning Unimplemented; the agent push
// loop shuts down cleanly on that response so older coderd
// deployments remain interoperable. Real persistence,
// KindMCPServer provider, and chatd hydration land in
// CODAGT-569.
//
// API v2.11:
// - Added the session_counts map to Stats on the Agent API, deprecating
// the fixed session_count_* fields.
//
// API v2.12:
// - Added the client_session_id to TelemetryEvent.
const (
CurrentMajor = 2
CurrentMinor = 12
)
var CurrentVersion = apiversion.New(CurrentMajor, CurrentMinor)