chore: add cherry-picks for patch 2.18.2 (#16061)

Co-authored-by: Cian Johnston <cian@coder.com>
Co-authored-by: Joobi S B <joobisb@gmail.com>

.devcontainer/devcontainer.json

@@ -1,13 +1,13 @@
 {
-  "name": "Development environments on your infrastructure",
-  "image": "codercom/oss-dogfood:latest",
+	"name": "Development environments on your infrastructure",
+	"image": "codercom/oss-dogfood:latest",
 
-  "features": {
-    // See all possible options here https://github.com/devcontainers/features/tree/main/src/docker-in-docker
-    "ghcr.io/devcontainers/features/docker-in-docker:2": {
-      "moby": "false"
-    }
-  },
-  // SYS_PTRACE to enable go debugging
-  "runArgs": ["--cap-add=SYS_PTRACE"]
+	"features": {
+		// See all possible options here https://github.com/devcontainers/features/tree/main/src/docker-in-docker
+		"ghcr.io/devcontainers/features/docker-in-docker:2": {
+			"moby": "false"
+		}
+	},
+	// SYS_PTRACE to enable go debugging
+	"runArgs": ["--cap-add=SYS_PTRACE"]
 }

.dockerignore

@@ -0,0 +1,6 @@
+# Ignore all files and folders
+**
+
+# Include flake.nix and flake.lock
+!flake.nix
+!flake.lock

.editorconfig

@@ -7,7 +7,7 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 indent_style = tab
 
-[*.{md,json,yaml,yml,tf,tfvars,nix}]
+[*.{yaml,yml,tf,tfvars,nix}]
 indent_style = space
 indent_size = 2
 

.git-blame-ignore-revs

@@ -3,3 +3,5 @@
 
 # chore: format code with semicolons when using prettier (#9555)
 988c9af0153561397686c119da9d1336d2433fdd
+# chore: use tabs for prettier and biome (#14283)
+95a7c0c4f087744a22c2e88dd3c5d30024d5fb02

.gitattributes

@@ -1,14 +1,17 @@
 # Generated files
 coderd/apidoc/docs.go linguist-generated=true
-docs/api/*.md linguist-generated=true
-docs/cli/*.md linguist-generated=true
+docs/reference/api/*.md linguist-generated=true
+docs/reference/cli/*.md linguist-generated=true
 coderd/apidoc/swagger.json linguist-generated=true
 coderd/database/dump.sql linguist-generated=true
 peerbroker/proto/*.go linguist-generated=true
 provisionerd/proto/*.go linguist-generated=true
+provisionerd/proto/version.go linguist-generated=false
 provisionersdk/proto/*.go linguist-generated=true
 *.tfplan.json linguist-generated=true
 *.tfstate.json linguist-generated=true
 *.tfstate.dot linguist-generated=true
 *.tfplan.dot linguist-generated=true
+site/e2e/provisionerGenerated.ts linguist-generated=true
 site/src/api/typesGenerated.ts linguist-generated=true
+site/src/pages/SetupPage/countries.tsx linguist-generated=true

.github/.linkspector.yml

@@ -0,0 +1,22 @@
+dirs:
+  - docs
+excludedDirs:
+  # Downstream bug in linkspector means large markdown files fail to parse
+  # but these are autogenerated and shouldn't need checking
+  - docs/reference
+  # Older changelogs may contain broken links
+  - docs/changelogs
+ignorePatterns:
+  - pattern: "localhost"
+  - pattern: "example.com"
+  - pattern: "mailto:"
+  - pattern: "127.0.0.1"
+  - pattern: "0.0.0.0"
+  - pattern: "JFROG_URL"
+  - pattern: "coder.company.org"
+  # These real sites were blocking the linkspector action / GitHub runner IPs(?)
+  - pattern: "i.imgur.com"
+  - pattern: "code.visualstudio.com"
+  - pattern: "www.emacswiki.org"
+aliveStatusCodes:
+  - 200

.github/actions/setup-go/action.yaml

@@ -4,12 +4,12 @@ description: |
 inputs:
   version:
     description: "The Go version to use."
-    default: "1.21.5"
+    default: "1.22.8"
 runs:
   using: "composite"
   steps:
     - name: Setup Go
-      uses: buildjet/setup-go@v4
+      uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2
       with:
         go-version: ${{ inputs.version }}
 

.github/actions/setup-node/action.yaml

@@ -11,16 +11,16 @@ runs:
   using: "composite"
   steps:
     - name: Install pnpm
-      uses: pnpm/action-setup@v2
-      with:
-        version: 8
+      uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # v4.0.0
+
     - name: Setup Node
-      uses: buildjet/setup-node@v3
+      uses: actions/setup-node@0a44ba7841725637a19e28fa30b79a866c81b0a6 # v4.0.4
       with:
-        node-version: 18.17.0
+        node-version: 20.16.0
         # See https://github.com/actions/setup-node#caching-global-packages-data
         cache: "pnpm"
         cache-dependency-path: ${{ inputs.directory }}/pnpm-lock.yaml
+
     - name: Install root node_modules
       shell: bash
       run: ./scripts/pnpm_install.sh

.github/actions/setup-sqlc/action.yaml

@@ -5,6 +5,6 @@ runs:
   using: "composite"
   steps:
     - name: Setup sqlc
-      uses: sqlc-dev/setup-sqlc@v4
+      uses: sqlc-dev/setup-sqlc@c0209b9199cd1cce6a14fc27cabcec491b651761 # v4.0.0
       with:
-        sqlc-version: "1.24.0"
+        sqlc-version: "1.25.0"

.github/actions/setup-tf/action.yaml

@@ -5,7 +5,7 @@ runs:
   using: "composite"
   steps:
     - name: Install Terraform
-      uses: hashicorp/setup-terraform@v3
+      uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3.1.2
       with:
-        terraform_version: 1.5.7
+        terraform_version: 1.9.8
         terraform_wrapper: false

.github/actions/upload-datadog/action.yaml

@@ -1,5 +1,6 @@
 name: Upload tests to datadog
-if: always()
+description: |
+  Uploads the test results to datadog.
 inputs:
   api-key:
     description: "Datadog API key"

.github/codecov.yml

@@ -1,43 +0,0 @@
-codecov:
-  require_ci_to_pass: false
-  notify:
-    after_n_builds: 5
-
-comment: false
-
-github_checks:
-  annotations: false
-
-coverage:
-  range: 50..75
-  round: down
-  precision: 2
-  status:
-    patch:
-      default:
-        informational: yes
-    project:
-      default:
-        target: 65%
-        informational: true
-
-ignore:
-  # This is generated code.
-  - coderd/database/models.go
-  - coderd/database/queries.sql.go
-  - coderd/database/databasefake
-  # These are generated or don't require tests.
-  - cmd
-  - coderd/tunnel
-  - coderd/database/dump
-  - coderd/database/postgres
-  - peerbroker/proto
-  - provisionerd/proto
-  - provisionersdk/proto
-  - scripts
-  - site/.storybook
-  - rules.go
-  # Packages used for writing tests.
-  - cli/clitest
-  - coderd/coderdtest
-  - pty/ptytest

.github/dependabot.yaml

@@ -38,19 +38,26 @@ updates:
     commit-message:
       prefix: "chore"
     labels: []
+    open-pull-requests-limit: 15
+    groups:
+      x:
+        patterns:
+          - "golang.org/x/*"
     ignore:
       # Ignore patch updates for all dependencies
       - dependency-name: "*"
         update-types:
           - version-update:semver-patch
-    groups:
-      go:
-        patterns:
-          - "*"
 
   # Update our Dockerfile.
   - package-ecosystem: "docker"
-    directory: "/scripts/"
+    directories:
+      - "/dogfood/contents"
+      - "/scripts"
+      - "/examples/templates/docker/build"
+      - "/examples/parameters/build"
+      - "/scaletest/templates/scaletest-runner"
+      - "/scripts/ironbank"
     schedule:
       interval: "weekly"
       time: "06:00"
@@ -64,7 +71,12 @@ updates:
       - dependency-name: "terraform"
 
   - package-ecosystem: "npm"
-    directory: "/site/"
+    directories:
+      - "/site"
+      - "/offlinedocs"
+      - "/scripts"
+      - "/scripts/apidocgen"
+
     schedule:
       interval: "monthly"
       time: "06:00"
@@ -74,58 +86,35 @@ updates:
     commit-message:
       prefix: "chore"
     labels: []
+    groups:
+      xterm:
+        patterns:
+          - "@xterm*"
+      mui:
+        patterns:
+          - "@mui*"
+      react:
+        patterns:
+          - "react"
+          - "react-dom"
+          - "@types/react"
+          - "@types/react-dom"
+      emotion:
+        patterns:
+          - "@emotion*"
+        exclude-patterns:
+          - "jest-runner-eslint"
+      jest:
+        patterns:
+          - "jest"
+          - "@types/jest"
+      vite:
+        patterns:
+          - "vite*"
+          - "@vitejs/plugin-react"
     ignore:
-      # Ignore patch updates for all dependencies
+      # Ignore major version updates to avoid breaking changes
       - dependency-name: "*"
-        update-types:
-          - version-update:semver-patch
-      # Ignore major updates to Node.js types, because they need to
-      # correspond to the Node.js engine version
-      - dependency-name: "@types/node"
         update-types:
           - version-update:semver-major
     open-pull-requests-limit: 15
-    groups:
-      site:
-        patterns:
-          - "*"
-
-  - package-ecosystem: "npm"
-    directory: "/offlinedocs/"
-    schedule:
-      interval: "monthly"
-      time: "06:00"
-      timezone: "America/Chicago"
-    reviewers:
-      - "coder/ts"
-    commit-message:
-      prefix: "chore"
-    labels: []
-    ignore:
-      # Ignore patch updates for all dependencies
-      - dependency-name: "*"
-        update-types:
-          - version-update:semver-patch
-      # Ignore major updates to Node.js types, because they need to
-      # correspond to the Node.js engine version
-      - dependency-name: "@types/node"
-        update-types:
-          - version-update:semver-major
-    groups:
-      offlinedocs:
-        patterns:
-          - "*"
-
-  # Update dogfood.
-  - package-ecosystem: "terraform"
-    directory: "/dogfood/"
-    schedule:
-      interval: "weekly"
-      time: "06:00"
-      timezone: "America/Chicago"
-    commit-message:
-      prefix: "chore"
-    labels: []
-    ignore:
-      # We likely want to update this ourselves.
-      - dependency-name: "coder/coder"

.github/fly-wsproxies/jnb-coder.toml

@@ -0,0 +1,34 @@
+app = "jnb-coder"
+primary_region = "jnb"
+
+[experimental]
+  entrypoint = ["/bin/sh", "-c", "CODER_DERP_SERVER_RELAY_URL=\"http://[${FLY_PRIVATE_IP}]:3000\" /opt/coder wsproxy server"]
+  auto_rollback = true
+
+[build]
+  image = "ghcr.io/coder/coder-preview:main"
+
+[env]
+  CODER_ACCESS_URL = "https://jnb.fly.dev.coder.com"
+  CODER_HTTP_ADDRESS = "0.0.0.0:3000"
+  CODER_PRIMARY_ACCESS_URL = "https://dev.coder.com"
+  CODER_WILDCARD_ACCESS_URL = "*--apps.jnb.fly.dev.coder.com"
+  CODER_VERBOSE = "true"
+
+[http_service]
+  internal_port = 3000
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+  min_machines_running = 0
+
+# Ref: https://fly.io/docs/reference/configuration/#http_service-concurrency
+[http_service.concurrency]
+  type = "requests"
+  soft_limit = 50
+  hard_limit = 100
+
+[[vm]]
+  cpu_kind = "shared"
+  cpus = 2
+  memory_mb = 512

.github/fly-wsproxies/paris-coder.toml

@@ -13,6 +13,7 @@ primary_region = "cdg"
   CODER_HTTP_ADDRESS = "0.0.0.0:3000"
   CODER_PRIMARY_ACCESS_URL = "https://dev.coder.com"
   CODER_WILDCARD_ACCESS_URL = "*--apps.paris.fly.dev.coder.com"
+  CODER_VERBOSE = "true"
 
 [http_service]
   internal_port = 3000
@@ -21,6 +22,12 @@ primary_region = "cdg"
   auto_start_machines = true
   min_machines_running = 0
 
+# Ref: https://fly.io/docs/reference/configuration/#http_service-concurrency
+[http_service.concurrency]
+  type = "requests"
+  soft_limit = 50
+  hard_limit = 100
+
 [[vm]]
   cpu_kind = "shared"
   cpus = 2

.github/fly-wsproxies/sao-paulo-coder.toml

@@ -13,6 +13,7 @@ primary_region = "gru"
   CODER_HTTP_ADDRESS = "0.0.0.0:3000"
   CODER_PRIMARY_ACCESS_URL = "https://dev.coder.com"
   CODER_WILDCARD_ACCESS_URL = "*--apps.sao-paulo.fly.dev.coder.com"
+  CODER_VERBOSE = "true"
 
 [http_service]
   internal_port = 3000
@@ -21,6 +22,12 @@ primary_region = "gru"
   auto_start_machines = true
   min_machines_running = 0
 
+# Ref: https://fly.io/docs/reference/configuration/#http_service-concurrency
+[http_service.concurrency]
+  type = "requests"
+  soft_limit = 50
+  hard_limit = 100
+
 [[vm]]
   cpu_kind = "shared"
   cpus = 2

.github/fly-wsproxies/sydney-coder.toml

@@ -13,6 +13,7 @@ primary_region = "syd"
   CODER_HTTP_ADDRESS = "0.0.0.0:3000"
   CODER_PRIMARY_ACCESS_URL = "https://dev.coder.com"
   CODER_WILDCARD_ACCESS_URL = "*--apps.sydney.fly.dev.coder.com"
+  CODER_VERBOSE = "true"
 
 [http_service]
   internal_port = 3000
@@ -21,6 +22,12 @@ primary_region = "syd"
   auto_start_machines = true
   min_machines_running = 0
 
+# Ref: https://fly.io/docs/reference/configuration/#http_service-concurrency
+[http_service.concurrency]
+  type = "requests"
+  soft_limit = 50
+  hard_limit = 100
+
 [[vm]]
   cpu_kind = "shared"
   cpus = 2

.github/pr-deployments/template/main.tf

@@ -86,12 +86,12 @@ provider "kubernetes" {
 }
 
 data "coder_workspace" "me" {}
+data "coder_workspace_owner" "me" {}
 
 resource "coder_agent" "main" {
-  os                     = "linux"
-  arch                   = "amd64"
-  startup_script_timeout = 180
-  startup_script         = <<-EOT
+  os             = "linux"
+  arch           = "amd64"
+  startup_script = <<-EOT
     set -e
 
     # install and start code-server
@@ -176,21 +176,21 @@ resource "coder_app" "code-server" {
 
 resource "kubernetes_persistent_volume_claim" "home" {
   metadata {
-    name      = "coder-${lower(data.coder_workspace.me.owner)}-${lower(data.coder_workspace.me.name)}-home"
+    name      = "coder-${lower(data.coder_workspace_owner.me.name)}-${lower(data.coder_workspace.me.name)}-home"
     namespace = var.namespace
     labels = {
       "app.kubernetes.io/name"     = "coder-pvc"
-      "app.kubernetes.io/instance" = "coder-pvc-${lower(data.coder_workspace.me.owner)}-${lower(data.coder_workspace.me.name)}"
+      "app.kubernetes.io/instance" = "coder-pvc-${lower(data.coder_workspace_owner.me.name)}-${lower(data.coder_workspace.me.name)}"
       "app.kubernetes.io/part-of"  = "coder"
       //Coder-specific labels.
       "com.coder.resource"       = "true"
       "com.coder.workspace.id"   = data.coder_workspace.me.id
       "com.coder.workspace.name" = data.coder_workspace.me.name
-      "com.coder.user.id"        = data.coder_workspace.me.owner_id
-      "com.coder.user.username"  = data.coder_workspace.me.owner
+      "com.coder.user.id"        = data.coder_workspace_owner.me.id
+      "com.coder.user.username"  = data.coder_workspace_owner.me.name
     }
     annotations = {
-      "com.coder.user.email" = data.coder_workspace.me.owner_email
+      "com.coder.user.email" = data.coder_workspace_owner.me.email
     }
   }
   wait_until_bound = false
@@ -211,20 +211,20 @@ resource "kubernetes_deployment" "main" {
   ]
   wait_for_rollout = false
   metadata {
-    name      = "coder-${lower(data.coder_workspace.me.owner)}-${lower(data.coder_workspace.me.name)}"
+    name      = "coder-${lower(data.coder_workspace_owner.me.name)}-${lower(data.coder_workspace.me.name)}"
     namespace = var.namespace
     labels = {
       "app.kubernetes.io/name"     = "coder-workspace"
-      "app.kubernetes.io/instance" = "coder-workspace-${lower(data.coder_workspace.me.owner)}-${lower(data.coder_workspace.me.name)}"
+      "app.kubernetes.io/instance" = "coder-workspace-${lower(data.coder_workspace_owner.me.name)}-${lower(data.coder_workspace.me.name)}"
       "app.kubernetes.io/part-of"  = "coder"
       "com.coder.resource"         = "true"
       "com.coder.workspace.id"     = data.coder_workspace.me.id
       "com.coder.workspace.name"   = data.coder_workspace.me.name
-      "com.coder.user.id"          = data.coder_workspace.me.owner_id
-      "com.coder.user.username"    = data.coder_workspace.me.owner
+      "com.coder.user.id"          = data.coder_workspace_owner.me.id
+      "com.coder.user.username"    = data.coder_workspace_owner.me.name
     }
     annotations = {
-      "com.coder.user.email" = data.coder_workspace.me.owner_email
+      "com.coder.user.email" = data.coder_workspace_owner.me.email
     }
   }
 

.github/workflows/contrib.yaml

@@ -13,6 +13,11 @@ on:
       - opened
       - reopened
       - edited
+      # For jobs that don't run on draft PRs.
+      - ready_for_review
+
+permissions:
+  contents: read
 
 # Only run one instance per PR to ensure in-order execution.
 concurrency: pr-${{ github.ref }}
@@ -25,16 +30,26 @@ jobs:
     permissions:
       pull-requests: write
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: auto-approve dependabot
-        uses: hmarr/auto-approve-action@v3
+        uses: hmarr/auto-approve-action@f0939ea97e9205ef24d872e76833fa908a770363 # v4.0.0
         if: github.actor == 'dependabot[bot]'
 
   cla:
     runs-on: ubuntu-latest
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: cla
         if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
-        uses: contributor-assistant/github-action@v2.3.1
+        uses: contributor-assistant/github-action@ca4a40a7d1004f18d9960b404b97e5f30a505a08 # v2.6.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           # the below token should have repo scope and must be manually added by you in the repository's secret
@@ -52,10 +67,15 @@ jobs:
   release-labels:
     runs-on: ubuntu-latest
     # Skip tagging for draft PRs.
-    if: ${{ github.event_name == 'pull_request_target' && success() && !github.event.pull_request.draft }}
+    if: ${{ github.event_name == 'pull_request_target' && !github.event.pull_request.draft }}
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: release-labels
-        uses: actions/github-script@v7
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
         with:
           # This script ensures PR title and labels are in sync:
           #

.github/workflows/docker-base.yaml

@@ -8,6 +8,11 @@ on:
       - scripts/Dockerfile.base
       - scripts/Dockerfile
 
+  pull_request:
+    paths:
+      - scripts/Dockerfile.base
+      - .github/workflows/docker-base.yaml
+
   schedule:
     # Run every week at 09:43 on Monday, Wednesday and Friday. We build this
     # frequently to ensure that packages are up-to-date.
@@ -17,10 +22,6 @@ on:
 
 permissions:
   contents: read
-  # Necessary to push docker images to ghcr.io.
-  packages: write
-  # Necessary for depot.dev authentication.
-  id-token: write
 
 # Avoid running multiple jobs for the same commit.
 concurrency:
@@ -28,14 +29,24 @@ concurrency:
 
 jobs:
   build:
+    permissions:
+      # Necessary for depot.dev authentication.
+      id-token: write
+      # Necessary to push docker images to ghcr.io.
+      packages: write
     runs-on: ubuntu-latest
     if: github.repository_owner == 'coder'
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
 
       - name: Docker login
-        uses: docker/login-action@v3
+        uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -45,23 +56,25 @@ jobs:
         run: mkdir base-build-context
 
       - name: Install depot.dev CLI
-        uses: depot/setup-action@v1
+        uses: depot/setup-action@b0b1ea4f69e92ebf5dea3f8713a1b0c37b2126a5 # v1.6.0
 
       # This uses OIDC authentication, so no auth variables are required.
       - name: Build base Docker image via depot.dev
-        uses: depot/build-push-action@v1
+        uses: depot/build-push-action@636daae76684e38c301daa0c5eca1c095b24e780 # v1.14.0
         with:
           project: wl5hnrrkns
           context: base-build-context
           file: scripts/Dockerfile.base
           platforms: linux/amd64,linux/arm64,linux/arm/v7
+          provenance: true
           pull: true
           no-cache: true
-          push: true
+          push: ${{ github.event_name != 'pull_request' }}
           tags: |
             ghcr.io/coder/coder-base:latest
 
       - name: Verify that images are pushed properly
+        if: github.event_name != 'pull_request'
         run: |
           # retry 10 times with a 5 second delay as the images may not be
           # available immediately

.github/workflows/dogfood.yaml

@@ -7,23 +7,36 @@ on:
     paths:
       - "dogfood/**"
       - ".github/workflows/dogfood.yaml"
-  # Uncomment these lines when testing with CI.
-  # pull_request:
-  #   paths:
-  #     - "dogfood/**"
-  #     - ".github/workflows/dogfood.yaml"
+      - "flake.lock"
+      - "flake.nix"
+  pull_request:
+    paths:
+      - "dogfood/**"
+      - ".github/workflows/dogfood.yaml"
+      - "flake.lock"
+      - "flake.nix"
   workflow_dispatch:
 
+permissions:
+  # Necessary for GCP authentication (https://github.com/google-github-actions/setup-gcloud#usage)
+  id-token: write
+
 jobs:
-  deploy_image:
-    runs-on: buildjet-4vcpu-ubuntu-2204
+  build_image:
+    if: github.actor != 'dependabot[bot]' # Skip Dependabot PRs
+    runs-on: ubuntu-latest
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
 
       - name: Get branch name
         id: branch-name
-        uses: tj-actions/branch-names@v8
+        uses: tj-actions/branch-names@6871f53176ad61624f978536bbf089c574dc19a2 # v8.0.1
 
       - name: "Branch name to Docker tag name"
         id: docker-tag-name
@@ -33,54 +46,96 @@ jobs:
           tag=${tag//\//--}
           echo "tag=${tag}" >> $GITHUB_OUTPUT
 
+      - name: Set up Depot CLI
+        uses: depot/setup-action@b0b1ea4f69e92ebf5dea3f8713a1b0c37b2126a5 # v1.6.0
+
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@c47758b77c9736f4b2ef4073d4d51994fabfe349 # v3.7.1
 
       - name: Login to DockerHub
-        uses: docker/login-action@v3
+        if: github.ref == 'refs/heads/main'
+        uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_PASSWORD }}
 
-      - name: Build and push
-        uses: docker/build-push-action@v5
+      - name: Build and push Non-Nix image
+        uses: depot/build-push-action@636daae76684e38c301daa0c5eca1c095b24e780 # v1.14.0
         with:
-          context: "{{defaultContext}}:dogfood"
+          project: b4q6ltmpzh
+          token: ${{ secrets.DEPOT_TOKEN }}
+          buildx-fallback: true
+          context: "{{defaultContext}}:dogfood/contents"
           pull: true
-          push: true
+          save: true
+          push: ${{ github.ref == 'refs/heads/main' }}
           tags: "codercom/oss-dogfood:${{ steps.docker-tag-name.outputs.tag }},codercom/oss-dogfood:latest"
-          cache-from: type=registry,ref=codercom/oss-dogfood:latest
-          cache-to: type=inline
+
+      - name: Build and push Nix image
+        uses: depot/build-push-action@636daae76684e38c301daa0c5eca1c095b24e780 # v1.14.0
+        with:
+          project: b4q6ltmpzh
+          token: ${{ secrets.DEPOT_TOKEN }}
+          buildx-fallback: true
+          context: "."
+          file: "dogfood/contents/Dockerfile.nix"
+          pull: true
+          save: true
+          push: ${{ github.ref == 'refs/heads/main' }}
+          tags: "codercom/oss-dogfood-nix:${{ steps.docker-tag-name.outputs.tag }},codercom/oss-dogfood-nix:latest"
 
   deploy_template:
-    needs: deploy_image
+    needs: build_image
     runs-on: ubuntu-latest
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
+
+      - name: Setup Terraform
+        uses: ./.github/actions/setup-tf
+
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@6fc4af4b145ae7821d527454aa9bd537d1f2dc5f # v2.1.7
+        with:
+          workload_identity_provider: projects/573722524737/locations/global/workloadIdentityPools/github/providers/github
+          service_account: coder-ci@coder-dogfood.iam.gserviceaccount.com
+
+      - name: Terraform init and validate
+        run: |
+          cd dogfood
+          terraform init -upgrade
+          terraform validate
+          cd contents
+          terraform init -upgrade
+          terraform validate
 
       - name: Get short commit SHA
+        if: github.ref == 'refs/heads/main'
         id: vars
         run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
 
       - name: Get latest commit title
+        if: github.ref == 'refs/heads/main'
         id: message
         run: echo "pr_title=$(git log --format=%s -n 1 ${{ github.sha }})" >> $GITHUB_OUTPUT
 
-      - name: "Get latest Coder binary from the server"
-        run: |
-          curl -fsSL "https://dev.coder.com/bin/coder-linux-amd64" -o "./coder"
-          chmod +x "./coder"
-
       - name: "Push template"
+        if: github.ref == 'refs/heads/main'
         run: |
-          ./coder templates push $CODER_TEMPLATE_NAME --directory $CODER_TEMPLATE_DIR --yes --name=$CODER_TEMPLATE_VERSION --message="$CODER_TEMPLATE_MESSAGE"
+          cd dogfood
+          terraform apply -auto-approve
         env:
-          # Consumed by Coder CLI
+          # Consumed by coderd provider
           CODER_URL: https://dev.coder.com
           CODER_SESSION_TOKEN: ${{ secrets.CODER_SESSION_TOKEN }}
           # Template source & details
-          CODER_TEMPLATE_NAME: ${{ secrets.CODER_TEMPLATE_NAME }}
-          CODER_TEMPLATE_VERSION: ${{ steps.vars.outputs.sha_short }}
-          CODER_TEMPLATE_DIR: ./dogfood
-          CODER_TEMPLATE_MESSAGE: ${{ steps.message.outputs.pr_title }}
+          TF_VAR_CODER_TEMPLATE_NAME: ${{ secrets.CODER_TEMPLATE_NAME }}
+          TF_VAR_CODER_TEMPLATE_VERSION: ${{ steps.vars.outputs.sha_short }}
+          TF_VAR_CODER_TEMPLATE_DIR: ./contents
+          TF_VAR_CODER_TEMPLATE_MESSAGE: ${{ steps.message.outputs.pr_title }}
+          TF_LOG: info

.github/workflows/mlc_config.json

@@ -1,23 +0,0 @@
-{
-  "ignorePatterns": [
-    {
-      "pattern": "://localhost"
-    },
-    {
-      "pattern": "://.*.?example\\.com"
-    },
-    {
-      "pattern": "developer.github.com"
-    },
-    {
-      "pattern": "docs.github.com"
-    },
-    {
-      "pattern": "support.google.com"
-    },
-    {
-      "pattern": "tailscale.com"
-    }
-  ],
-  "aliveStatusCodes": [200, 0]
-}

.github/workflows/nightly-gauntlet.yaml

@@ -6,18 +6,27 @@ on:
     # Every day at midnight
     - cron: "0 0 * * *"
   workflow_dispatch:
+
+permissions:
+  contents: read
+
 jobs:
   go-race:
     # While GitHub's toaster runners are likelier to flake, we want consistency
     # between this environment and the regular test environment for DataDog
     # statistics and to only show real workflow threats.
-    runs-on: "buildjet-8vcpu-ubuntu-2204"
+    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     # This runner costs 0.016 USD per minute,
     # so 0.016 * 240 = 3.84 USD per run.
     timeout-minutes: 240
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
 
       - name: Setup Go
         uses: ./.github/actions/setup-go
@@ -40,11 +49,16 @@ jobs:
 
   go-timing:
     # We run these tests with p=1 so we don't need a lot of compute.
-    runs-on: "buildjet-2vcpu-ubuntu-2204"
+    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04' || 'ubuntu-latest' }}
     timeout-minutes: 10
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
 
       - name: Setup Go
         uses: ./.github/actions/setup-go

.github/workflows/pr-auto-assign.yaml

@@ -13,5 +13,10 @@ jobs:
   assign-author:
     runs-on: ubuntu-latest
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Assign author
-        uses: toshimaru/auto-author-assign@v2.0.1
+        uses: toshimaru/auto-author-assign@16f0022cf3d7970c106d8d1105f75a1165edb516 # v2.1.1

.github/workflows/pr-cleanup.yaml

@@ -9,12 +9,20 @@ on:
         required: true
 
 permissions:
-  packages: write
+  contents: read
 
 jobs:
   cleanup:
     runs-on: "ubuntu-latest"
+    permissions:
+      # Necessary to delete docker images from ghcr.io.
+      packages: write
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Get PR number
         id: pr_number
         run: |
@@ -26,7 +34,7 @@ jobs:
 
       - name: Delete image
         continue-on-error: true
-        uses: bots-house/ghcr-delete-image-action@v1.1.0
+        uses: bots-house/ghcr-delete-image-action@3827559c68cb4dcdf54d813ea9853be6d468d3a4 # v1.1.0
         with:
           owner: coder
           name: coder-preview

.github/workflows/pr-deploy.yaml

@@ -9,10 +9,6 @@ on:
       - main
   workflow_dispatch:
     inputs:
-      pr_number:
-        description: "PR number"
-        type: number
-        required: true
       experiments:
         description: "Experiments to enable"
         required: false
@@ -34,8 +30,6 @@ env:
 
 permissions:
   contents: read
-  packages: write
-  pull-requests: write # needed for commenting on PRs
 
 jobs:
   check_pr:
@@ -43,8 +37,13 @@ jobs:
     outputs:
       PR_OPEN: ${{ steps.check_pr.outputs.pr_open }}
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
 
       - name: Check if PR is open
         id: check_pr
@@ -73,8 +72,13 @@ jobs:
 
     runs-on: "ubuntu-latest"
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
         with:
           fetch-depth: 0
 
@@ -105,8 +109,8 @@ jobs:
         run: |
           set -euo pipefail
           mkdir -p ~/.kube
-          echo "${{ secrets.PR_DEPLOYMENTS_KUBECONFIG }}" > ~/.kube/config
-          chmod 644 ~/.kube/config
+          echo "${{ secrets.PR_DEPLOYMENTS_KUBECONFIG_BASE64 }}" | base64 --decode > ~/.kube/config
+          chmod 600 ~/.kube/config
           export KUBECONFIG=~/.kube/config
 
       - name: Check if the helm deployment already exists
@@ -123,7 +127,7 @@ jobs:
           echo "NEW=$NEW" >> $GITHUB_OUTPUT
 
       - name: Check changed files
-        uses: dorny/paths-filter@v2
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
         id: filter
         with:
           base: ${{ github.ref }}
@@ -158,16 +162,23 @@ jobs:
           set -euo pipefail
           # build if the workflow is manually triggered and the deployment doesn't exist (first build or force rebuild)
           echo "first_or_force_build=${{ (github.event_name == 'workflow_dispatch' && steps.check_deployment.outputs.NEW == 'true') || github.event.inputs.build == 'true' }}" >> $GITHUB_OUTPUT
-          # build if the deployment alreday exist and there are changes in the files that we care about (automatic updates)
+          # build if the deployment already exist and there are changes in the files that we care about (automatic updates)
           echo "automatic_rebuild=${{ steps.check_deployment.outputs.NEW == 'false' && steps.filter.outputs.all_count > steps.filter.outputs.ignored_count }}" >> $GITHUB_OUTPUT
 
   comment-pr:
     needs: get_info
     if: needs.get_info.outputs.BUILD == 'true' || github.event.inputs.deploy == 'true'
     runs-on: "ubuntu-latest"
+    permissions:
+      pull-requests: write # needed for commenting on PRs
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Find Comment
-        uses: peter-evans/find-comment@v2
+        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
         id: fc
         with:
           issue-number: ${{ needs.get_info.outputs.PR_NUMBER }}
@@ -177,7 +188,7 @@ jobs:
 
       - name: Comment on PR
         id: comment_id
-        uses: peter-evans/create-or-update-comment@v3
+        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
         with:
           comment-id: ${{ steps.fc.outputs.comment-id }}
           issue-number: ${{ needs.get_info.outputs.PR_NUMBER }}
@@ -193,8 +204,11 @@ jobs:
     needs: get_info
     # Run build job only if there are changes in the files that we care about or if the workflow is manually triggered with --build flag
     if: needs.get_info.outputs.BUILD == 'true'
-    runs-on: ${{ github.repository_owner == 'coder' && 'buildjet-8vcpu-ubuntu-2204' || 'ubuntu-latest' }}
-    # This concurrency only cancels build jobs if a new build is triggred. It will avoid cancelling the current deployemtn in case of docs chnages.
+    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
+    permissions:
+      # Necessary to push docker images to ghcr.io.
+      packages: write
+    # This concurrency only cancels build jobs if a new build is triggred. It will avoid cancelling the current deployemtn in case of docs changes.
     concurrency:
       group: build-${{ github.workflow }}-${{ github.ref }}-${{ needs.get_info.outputs.BUILD }}
       cancel-in-progress: true
@@ -202,8 +216,13 @@ jobs:
       DOCKER_CLI_EXPERIMENTAL: "enabled"
       CODER_IMAGE_TAG: ${{ needs.get_info.outputs.CODER_IMAGE_TAG }}
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
         with:
           fetch-depth: 0
 
@@ -217,7 +236,7 @@ jobs:
         uses: ./.github/actions/setup-sqlc
 
       - name: GHCR Login
-        uses: docker/login-action@v3
+        uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -246,6 +265,8 @@ jobs:
       always() && (needs.build.result == 'success' || needs.build.result == 'skipped') &&
       (needs.get_info.outputs.BUILD == 'true' || github.event.inputs.deploy == 'true')
     runs-on: "ubuntu-latest"
+    permissions:
+      pull-requests: write # needed for commenting on PRs
     env:
       CODER_IMAGE_TAG: ${{ needs.get_info.outputs.CODER_IMAGE_TAG }}
       PR_NUMBER: ${{ needs.get_info.outputs.PR_NUMBER }}
@@ -253,12 +274,17 @@ jobs:
       PR_URL: ${{ needs.get_info.outputs.PR_URL }}
       PR_HOSTNAME: "pr${{ needs.get_info.outputs.PR_NUMBER }}.${{ secrets.PR_DEPLOYMENTS_DOMAIN }}"
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Set up kubeconfig
         run: |
           set -euo pipefail
           mkdir -p ~/.kube
-          echo "${{ secrets.PR_DEPLOYMENTS_KUBECONFIG }}" > ~/.kube/config
-          chmod 644 ~/.kube/config
+          echo "${{ secrets.PR_DEPLOYMENTS_KUBECONFIG_BASE64 }}" | base64 --decode > ~/.kube/config
+          chmod 600 ~/.kube/config
           export KUBECONFIG=~/.kube/config
 
       - name: Check if image exists
@@ -298,7 +324,7 @@ jobs:
           kubectl create namespace "pr${{ env.PR_NUMBER }}"
 
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
 
       - name: Check and Create Certificate
         if: needs.get_info.outputs.NEW == 'true' || github.event.inputs.deploy == 'true'
@@ -355,6 +381,7 @@ jobs:
       - name: Install/Upgrade Helm chart
         run: |
           set -euo pipefail
+          helm dependency update --skip-refresh ./helm/coder
           helm upgrade --install "pr${{ env.PR_NUMBER }}" ./helm/coder \
           --namespace "pr${{ env.PR_NUMBER }}" \
           --values ./pr-deploy-values.yaml \
@@ -394,14 +421,14 @@ jobs:
           "${DEST}" version
           mv "${DEST}" /usr/local/bin/coder
 
-      - name: Create first user, template and workspace
+      - name: Create first user
         if: needs.get_info.outputs.NEW == 'true' || github.event.inputs.deploy == 'true'
         id: setup_deployment
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           set -euo pipefail
 
-          # Create first user
-
           # create a masked random password 12 characters long
           password=$(openssl rand -base64 16 | tr -d "=+/" | cut -c1-12)
 
@@ -410,20 +437,22 @@ jobs:
           echo "password=$password" >> $GITHUB_OUTPUT
 
           coder login \
-            --first-user-username coder \
+            --first-user-username pr${{ env.PR_NUMBER }}-admin \
             --first-user-email pr${{ env.PR_NUMBER }}@coder.com \
             --first-user-password $password \
-            --first-user-trial \
+            --first-user-trial=false \
             --use-token-as-session \
             https://${{ env.PR_HOSTNAME }}
 
-          # Create template
-          cd ./.github/pr-deployments/template
-          coder templates create -y --variable namespace=pr${{ env.PR_NUMBER }} kubernetes
+          # Create a user for the github.actor
+          # TODO: update once https://github.com/coder/coder/issues/15466 is resolved
+          # coder users create \
+          #   --username ${{ github.actor }} \
+          #   --login-type github
 
-          # Create workspace
-          coder create --template="kubernetes" kube --parameter cpu=2 --parameter memory=4 --parameter home_disk_size=2 -y
-          coder stop kube -y
+          # promote the user to admin role
+          # coder org members edit-role ${{ github.actor }} organization-admin
+          # TODO: update once https://github.com/coder/internal/issues/207 is resolved
 
       - name: Send Slack notification
         if: needs.get_info.outputs.NEW == 'true' || github.event.inputs.deploy == 'true'
@@ -435,7 +464,7 @@ jobs:
               "pr_url": "'"${{ env.PR_URL }}"'",
               "pr_title": "'"${{ env.PR_TITLE }}"'",
               "pr_access_url": "'"https://${{ env.PR_HOSTNAME }}"'",
-              "pr_username": "'"test"'",
+              "pr_username": "'"pr${{ env.PR_NUMBER }}-admin"'",
               "pr_email": "'"pr${{ env.PR_NUMBER }}@coder.com"'",
               "pr_password": "'"${{ steps.setup_deployment.outputs.password }}"'",
               "pr_actor": "'"${{ github.actor }}"'"
@@ -444,7 +473,7 @@ jobs:
           echo "Slack notification sent"
 
       - name: Find Comment
-        uses: peter-evans/find-comment@v2
+        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
         id: fc
         with:
           issue-number: ${{ env.PR_NUMBER }}
@@ -453,7 +482,7 @@ jobs:
           direction: last
 
       - name: Comment on PR
-        uses: peter-evans/create-or-update-comment@v3
+        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
         env:
           STATUS: ${{ needs.get_info.outputs.NEW == 'true' && 'Created' || 'Updated' }}
         with:
@@ -468,3 +497,14 @@ jobs:
             cc: @${{ github.actor }}
           reactions: rocket
           reactions-edit-mode: replace
+
+      - name: Create template and workspace
+        if: needs.get_info.outputs.NEW == 'true' || github.event.inputs.deploy == 'true'
+        run: |
+          set -euo pipefail
+          cd .github/pr-deployments/template
+          coder templates push -y --variable namespace=pr${{ env.PR_NUMBER }} kubernetes
+
+          # Create workspace
+          coder create --template="kubernetes" kube --parameter cpu=2 --parameter memory=4 --parameter home_disk_size=2 -y
+          coder stop kube -y

.github/workflows/release-validation.yaml

@@ -0,0 +1,28 @@
+name: release-validation
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  network-performance:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
+      - name: Run Schmoder CI
+        uses: benc-uk/workflow-dispatch@e2e5e9a103e331dad343f381a29e654aea3cf8fc # v1.2.4
+        with:
+          workflow: ci.yaml
+          repo: coder/schmoder
+          inputs: '{ "num_releases": "3", "commit": "${{ github.sha }}" }'
+          token: ${{ secrets.CDRCI_SCHMODER_ACTIONS_TOKEN }}
+          ref: main

.github/workflows/release.yaml

@@ -1,11 +1,16 @@
 # GitHub release workflow.
 name: Release
 on:
-  push:
-    tags:
-      - "v*"
   workflow_dispatch:
     inputs:
+      release_channel:
+        type: choice
+        description: Release channel
+        options:
+          - mainline
+          - stable
+      release_notes:
+        description: Release notes for the publishing the release. This is required to create a release.
       dry_run:
         description: Perform a dry-run release (devel). Note that ref must be an annotated tag when run without dry-run.
         type: boolean
@@ -13,12 +18,7 @@ on:
         default: false
 
 permissions:
-  # Required to publish a release
-  contents: write
-  # Necessary to push docker images to ghcr.io.
-  packages: write
-  # Necessary for GCP authentication (https://github.com/google-github-actions/setup-gcloud#usage)
-  id-token: write
+  contents: read
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
@@ -28,19 +28,33 @@ env:
   # https://github.blog/changelog/2022-06-10-github-actions-inputs-unified-across-manual-and-reusable-workflows/
   CODER_RELEASE: ${{ !inputs.dry_run }}
   CODER_DRY_RUN: ${{ inputs.dry_run }}
+  CODER_RELEASE_CHANNEL: ${{ inputs.release_channel }}
+  CODER_RELEASE_NOTES: ${{ inputs.release_notes }}
 
 jobs:
   release:
     name: Build and publish
-    runs-on: ${{ github.repository_owner == 'coder' && 'buildjet-8vcpu-ubuntu-2204' || 'ubuntu-latest' }}
+    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
+    permissions:
+      # Required to publish a release
+      contents: write
+      # Necessary to push docker images to ghcr.io.
+      packages: write
+      # Necessary for GCP authentication (https://github.com/google-github-actions/setup-gcloud#usage)
+      id-token: write
     env:
       # Necessary for Docker manifest
       DOCKER_CLI_EXPERIMENTAL: "enabled"
     outputs:
       version: ${{ steps.version.outputs.version }}
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
         with:
           fetch-depth: 0
 
@@ -62,21 +76,45 @@ jobs:
           echo "CODER_FORCE_VERSION=$version" >> $GITHUB_ENV
           echo "$version"
 
-      - name: Create release notes
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # We always have to set this since there might be commits on
-          # main that didn't have a PR.
-          CODER_IGNORE_MISSING_COMMIT_METADATA: "1"
+      # Verify that all expectations for a release are met.
+      - name: Verify release input
+        if: ${{ !inputs.dry_run }}
+        run: |
+          set -euo pipefail
+
+          if [[ "${GITHUB_REF}" != "refs/tags/v"* ]]; then
+            echo "Ref must be a semver tag when creating a release, did you use scripts/release.sh?"
+            exit 1
+          fi
+
+          # 2.10.2 -> release/2.10
+          version="$(./scripts/version.sh)"
+          release_branch=release/${version%.*}
+          branch_contains_tag=$(git branch --remotes --contains "${GITHUB_REF}" --list "*/${release_branch}" --format='%(refname)')
+          if [[ -z "${branch_contains_tag}" ]]; then
+            echo "Ref tag must exist in a branch named ${release_branch} when creating a release, did you use scripts/release.sh?"
+            exit 1
+          fi
+
+          if [[ -z "${CODER_RELEASE_NOTES}" ]]; then
+            echo "Release notes are required to create a release, did you use scripts/release.sh?"
+            exit 1
+          fi
+
+          echo "Release inputs verified:"
+          echo
+          echo "- Ref: ${GITHUB_REF}"
+          echo "- Version: ${version}"
+          echo "- Release channel: ${CODER_RELEASE_CHANNEL}"
+          echo "- Release branch: ${release_branch}"
+          echo "- Release notes: true"
+
+      - name: Create release notes file
         run: |
           set -euo pipefail
-          ref=HEAD
-          old_version="$(git describe --abbrev=0 "$ref^1")"
-          version="v$(./scripts/version.sh)"
 
-          # Generate notes.
           release_notes_file="$(mktemp -t release_notes.XXXXXX)"
-          ./scripts/release/generate_release_notes.sh --check-for-changelog --old-version "$old_version" --new-version "$version" --ref "$ref" >> "$release_notes_file"
+          echo "$CODER_RELEASE_NOTES" > "$release_notes_file"
           echo CODER_RELEASE_NOTES_FILE="$release_notes_file" >> $GITHUB_ENV
 
       - name: Show release notes
@@ -85,7 +123,7 @@ jobs:
           cat "$CODER_RELEASE_NOTES_FILE"
 
       - name: Docker Login
-        uses: docker/login-action@v3
+        uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -97,13 +135,20 @@ jobs:
       - name: Setup Node
         uses: ./.github/actions/setup-node
 
+      # Necessary for signing Windows binaries.
+      - name: Setup Java
+        uses: actions/setup-java@b36c23c0d998641eff861008f374ee103c25ac73 # v4.4.0
+        with:
+          distribution: "zulu"
+          java-version: "11.0"
+
       - name: Install nsis and zstd
         run: sudo apt-get install -y nsis zstd
 
       - name: Install nfpm
         run: |
           set -euo pipefail
-          wget -O /tmp/nfpm.deb https://github.com/goreleaser/nfpm/releases/download/v2.18.1/nfpm_amd64.deb
+          wget -O /tmp/nfpm.deb https://github.com/goreleaser/nfpm/releases/download/v2.35.1/nfpm_2.35.1_amd64.deb
           sudo dpkg -i /tmp/nfpm.deb
           rm /tmp/nfpm.deb
 
@@ -130,6 +175,32 @@ jobs:
           AC_CERTIFICATE_PASSWORD: ${{ secrets.AC_CERTIFICATE_PASSWORD }}
           AC_APIKEY_P8_BASE64: ${{ secrets.AC_APIKEY_P8_BASE64 }}
 
+      - name: Setup Windows EV Signing Certificate
+        run: |
+          set -euo pipefail
+          touch /tmp/ev_cert.pem
+          chmod 600 /tmp/ev_cert.pem
+          echo "$EV_SIGNING_CERT" > /tmp/ev_cert.pem
+          wget https://github.com/ebourg/jsign/releases/download/6.0/jsign-6.0.jar -O /tmp/jsign-6.0.jar
+        env:
+          EV_SIGNING_CERT: ${{ secrets.EV_SIGNING_CERT }}
+
+      - name: Test migrations from current ref to main
+        run: |
+          POSTGRES_VERSION=13 make test-migrations
+
+      # Setup GCloud for signing Windows binaries.
+      - name: Authenticate to Google Cloud
+        id: gcloud_auth
+        uses: google-github-actions/auth@6fc4af4b145ae7821d527454aa9bd537d1f2dc5f # v2.1.7
+        with:
+          workload_identity_provider: ${{ secrets.GCP_CODE_SIGNING_WORKLOAD_ID_PROVIDER }}
+          service_account: ${{ secrets.GCP_CODE_SIGNING_SERVICE_ACCOUNT }}
+          token_format: "access_token"
+
+      - name: Setup GCloud SDK
+        uses: google-github-actions/setup-gcloud@6189d56e4096ee891640bb02ac264be376592d6a # v2.1.2
+
       - name: Build binaries
         run: |
           set -euo pipefail
@@ -144,16 +215,26 @@ jobs:
             build/coder_helm_"$version".tgz \
             build/provisioner_helm_"$version".tgz
         env:
+          CODER_SIGN_WINDOWS: "1"
           CODER_SIGN_DARWIN: "1"
           AC_CERTIFICATE_FILE: /tmp/apple_cert.p12
           AC_CERTIFICATE_PASSWORD_FILE: /tmp/apple_cert_password.txt
           AC_APIKEY_ISSUER_ID: ${{ secrets.AC_APIKEY_ISSUER_ID }}
           AC_APIKEY_ID: ${{ secrets.AC_APIKEY_ID }}
           AC_APIKEY_FILE: /tmp/apple_apikey.p8
+          EV_KEY: ${{ secrets.EV_KEY }}
+          EV_KEYSTORE: ${{ secrets.EV_KEYSTORE }}
+          EV_TSA_URL: ${{ secrets.EV_TSA_URL }}
+          EV_CERTIFICATE_PATH: /tmp/ev_cert.pem
+          GCLOUD_ACCESS_TOKEN: ${{ steps.gcloud_auth.outputs.access_token }}
+          JSIGN_PATH: /tmp/jsign-6.0.jar
 
       - name: Delete Apple Developer certificate and API key
         run: rm -f /tmp/{apple_cert.p12,apple_cert_password.txt,apple_apikey.p8}
 
+      - name: Delete Windows EV Signing Cert
+        run: rm /tmp/ev_cert.pem
+
       - name: Determine base image tag
         id: image-base-tag
         run: |
@@ -171,17 +252,18 @@ jobs:
 
       - name: Install depot.dev CLI
         if: steps.image-base-tag.outputs.tag != ''
-        uses: depot/setup-action@v1
+        uses: depot/setup-action@b0b1ea4f69e92ebf5dea3f8713a1b0c37b2126a5 # v1.6.0
 
       # This uses OIDC authentication, so no auth variables are required.
       - name: Build base Docker image via depot.dev
         if: steps.image-base-tag.outputs.tag != ''
-        uses: depot/build-push-action@v1
+        uses: depot/build-push-action@636daae76684e38c301daa0c5eca1c095b24e780 # v1.14.0
         with:
           project: wl5hnrrkns
           context: base-build-context
           file: scripts/Dockerfile.base
           platforms: linux/amd64,linux/arm64,linux/arm/v7
+          provenance: true
           pull: true
           no-cache: true
           push: true
@@ -223,7 +305,7 @@ jobs:
 
           # build Docker images for each architecture
           version="$(./scripts/version.sh)"
-          make -j build/coder_"$version"_linux_{amd64,arm64,armv7}.tag
+          make build/coder_"$version"_linux_{amd64,arm64,armv7}.tag
 
           # we can't build multi-arch if the images aren't pushed, so quit now
           # if dry-running
@@ -234,7 +316,7 @@ jobs:
 
           # build and push multi-arch manifest, this depends on the other images
           # being pushed so will automatically push them.
-          make -j push/build/coder_"$version"_linux.tag
+          make push/build/coder_"$version"_linux.tag
 
           # if the current version is equal to the highest (according to semver)
           # version in the repo, also create a multi-arch image as ":latest" and
@@ -261,6 +343,9 @@ jobs:
           set -euo pipefail
 
           publish_args=()
+          if [[ $CODER_RELEASE_CHANNEL == "stable" ]]; then
+            publish_args+=(--stable)
+          fi
           if [[ $CODER_DRY_RUN == *t* ]]; then
             publish_args+=(--dry-run)
           fi
@@ -281,13 +366,13 @@ jobs:
           CODER_GPG_RELEASE_KEY_BASE64: ${{ secrets.GPG_RELEASE_KEY_BASE64 }}
 
       - name: Authenticate to Google Cloud
-        uses: google-github-actions/auth@v2
+        uses: google-github-actions/auth@6fc4af4b145ae7821d527454aa9bd537d1f2dc5f # v2.1.7
         with:
           workload_identity_provider: ${{ secrets.GCP_WORKLOAD_ID_PROVIDER }}
           service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
 
       - name: Setup GCloud SDK
-        uses: "google-github-actions/setup-gcloud@v2"
+        uses: google-github-actions/setup-gcloud@6189d56e4096ee891640bb02ac264be376592d6a # 2.1.2
 
       - name: Publish Helm Chart
         if: ${{ !inputs.dry_run }}
@@ -306,7 +391,7 @@ jobs:
 
       - name: Upload artifacts to actions (if dry-run)
         if: ${{ inputs.dry_run }}
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@604373da6381bf24206979c74d06a550515601b9 # v4.4.1
         with:
           name: release-artifacts
           path: |
@@ -319,14 +404,14 @@ jobs:
             ./build/*.rpm
           retention-days: 7
 
-      - name: Start Packer builds
+      - name: Send repository-dispatch event
         if: ${{ !inputs.dry_run }}
-        uses: peter-evans/repository-dispatch@v2
+        uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0 # v3.0.0
         with:
           token: ${{ secrets.CDRCI_GITHUB_TOKEN }}
           repository: coder/packages
           event-type: coder-release
-          client-payload: '{"coder_version": "${{ steps.version.outputs.version }}"}'
+          client-payload: '{"coder_version": "${{ steps.version.outputs.version }}", "release_channel": "${{ inputs.release_channel }}"}'
 
   publish-homebrew:
     name: Publish to Homebrew tap
@@ -337,6 +422,11 @@ jobs:
     steps:
       # TODO: skip this if it's not a new release (i.e. a backport). This is
       #       fine right now because it just makes a PR that we can close.
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Update homebrew
         env:
           # Variables used by the `gh` command
@@ -408,8 +498,18 @@ jobs:
     if: ${{ !inputs.dry_run }}
 
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
+      - name: Sync fork
+        run: gh repo sync cdrci/winget-pkgs -b master
+        env:
+          GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
         with:
           fetch-depth: 0
 
@@ -480,65 +580,33 @@ jobs:
           # different repo.
           GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
 
-  publish-chocolatey:
-    name: Publish to Chocolatey
-    runs-on: windows-latest
+  # publish-sqlc pushes the latest schema to sqlc cloud.
+  # At present these pushes cannot be tagged, so the last push is always the latest.
+  publish-sqlc:
+    name: "Publish to schema sqlc cloud"
+    runs-on: "ubuntu-latest"
     needs: release
     if: ${{ !inputs.dry_run }}
-
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
         with:
-          fetch-depth: 0
+          egress-policy: audit
 
-      # Same reason as for release.
-      - name: Fetch git tags
-        run: git fetch --tags --force
+      - name: Checkout
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
+        with:
+          fetch-depth: 1
 
-      # From https://chocolatey.org
-      - name: Install Chocolatey
+      # We need golang to run the migration main.go
+      - name: Setup Go
+        uses: ./.github/actions/setup-go
+
+      - name: Setup sqlc
+        uses: ./.github/actions/setup-sqlc
+
+      - name: Push schema to sqlc cloud
+        # Don't block a release on this
+        continue-on-error: true
         run: |
-          Set-ExecutionPolicy Bypass -Scope Process -Force
-          [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
-
-          iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
-
-      - name: Build chocolatey package
-        run: |
-          cd scripts/chocolatey
-
-          # The package version is the same as the tag minus the leading "v".
-          # The version in this output already has the leading "v" removed but
-          # we do it again to be safe.
-          $version = "${{ needs.release.outputs.version }}".Trim('v')
-
-          $release_assets = gh release view --repo coder/coder "v${version}" --json assets | `
-            ConvertFrom-Json
-
-          # Get the URL for the Windows ZIP from the release assets.
-          $zip_url = $release_assets.assets | `
-            Where-Object name -Match ".*_windows_amd64.zip$" | `
-            Select -ExpandProperty url
-
-          echo "ZIP URL: ${zip_url}"
-          echo "Package version: ${version}"
-
-          echo "Downloading ZIP..."
-          Invoke-WebRequest $zip_url -OutFile assets.zip
-
-          echo "Extracting ZIP..."
-          Expand-Archive assets.zip -DestinationPath assets/
-
-          # No need to specify nuspec if there's only one in the directory.
-          choco pack --version=$version binary_path=assets/coder.exe
-
-          choco apikey --api-key $env:CHOCO_API_KEY --source https://push.chocolatey.org/
-
-          # No need to specify nupkg if there's only one in the directory.
-          choco push --source https://push.chocolatey.org/
-
-        env:
-          CHOCO_API_KEY: ${{ secrets.CHOCO_API_KEY }}
-          # We need a GitHub token for the gh CLI to function under GitHub Actions
-          GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
+          make sqlc-push

.github/workflows/scorecard.yml

@@ -0,0 +1,52 @@
+name: OpenSSF Scorecard
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: "27 7 * * 3" # A random time to run weekly
+  push:
+    branches: ["main"]
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
+      - name: "Checkout code"
+        uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938 # v4.2.0
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@62b2cac7ed8198b15735ed49ab1e5cf35480ba46 # v2.4.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_results: true
+
+      # Upload the results as artifacts.
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@604373da6381bf24206979c74d06a550515601b9 # v4.4.1
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard.
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
+        with:
+          sarif_file: results.sarif

.github/workflows/security.yaml

@@ -3,7 +3,6 @@ name: "security"
 permissions:
   actions: read
   contents: read
-  security-events: write
 
 on:
   workflow_dispatch:
@@ -23,26 +22,33 @@ concurrency:
 
 jobs:
   codeql:
-    runs-on: ${{ github.repository_owner == 'coder' && 'buildjet-8vcpu-ubuntu-2204' || 'ubuntu-latest' }}
+    permissions:
+      security-events: write
+    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
         with:
-          languages: go, javascript
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
 
       - name: Setup Go
         uses: ./.github/actions/setup-go
 
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
+        with:
+          languages: go, javascript
+
       # Workaround to prevent CodeQL from building the dashboard.
       - name: Remove Makefile
         run: |
           rm Makefile
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
 
       - name: Send Slack notification on failure
         if: ${{ failure() }}
@@ -56,10 +62,17 @@ jobs:
             "${{ secrets.SLACK_SECURITY_FAILURE_WEBHOOK_URL }}"
 
   trivy:
-    runs-on: ${{ github.repository_owner == 'coder' && 'buildjet-8vcpu-ubuntu-2204' || 'ubuntu-latest' }}
+    permissions:
+      security-events: write
+    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
         with:
           fetch-depth: 0
 
@@ -75,7 +88,7 @@ jobs:
       - name: Install yq
         run: go run github.com/mikefarah/yq/v4@v4.30.6
       - name: Install mockgen
-        run: go install github.com/golang/mock/mockgen@v1.6.0
+        run: go install go.uber.org/mock/mockgen@v0.4.0
       - name: Install protoc-gen-go
         run: go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.30
       - name: Install protoc-gen-go-drpc
@@ -85,13 +98,20 @@ jobs:
           # protoc must be in lockstep with our dogfood Dockerfile or the
           # version in the comments will differ. This is also defined in
           # ci.yaml.
-          set -x
-          cd dogfood
+          set -euxo pipefail
+          cd dogfood/contents
+          mkdir -p /usr/local/bin
+          mkdir -p /usr/local/include
+
           DOCKER_BUILDKIT=1 docker build . --target proto -t protoc
           protoc_path=/usr/local/bin/protoc
           docker run --rm --entrypoint cat protoc /tmp/bin/protoc > $protoc_path
           chmod +x $protoc_path
           protoc --version
+          # Copy the generated files to the include directory.
+          docker run --rm -v /usr/local/include:/target protoc cp -r /tmp/include/google /target/
+          ls -la /usr/local/include/google/protobuf/
+          stat /usr/local/include/google/protobuf/timestamp.proto
 
       - name: Build Coder linux amd64 Docker image
         id: build
@@ -110,19 +130,13 @@ jobs:
           # the registry.
           export CODER_IMAGE_BUILD_BASE_TAG="$(CODER_IMAGE_BASE=coder-base ./scripts/image_tag.sh --version "$version")"
 
-          make -j "$image_job"
+          # We would like to use make -j here, but it doesn't work with the some recent additions
+          # to our code generation.
+          make "$image_job"
           echo "image=$(cat "$image_job")" >> $GITHUB_OUTPUT
 
-      - name: Run Prisma Cloud image scan
-        uses: PaloAltoNetworks/prisma-cloud-scan@v1
-        with:
-          pcc_console_url: ${{ secrets.PRISMA_CLOUD_URL }}
-          pcc_user: ${{ secrets.PRISMA_CLOUD_ACCESS_KEY }}
-          pcc_pass: ${{ secrets.PRISMA_CLOUD_SECRET_KEY }}
-          image_name: ${{ steps.build.outputs.image }}
-
       - name: Run Trivy vulnerability scanner
-        uses: aquasecurity/trivy-action@91713af97dc80187565512baba96e4364e983601
+        uses: aquasecurity/trivy-action@18f2510ee396bbf400402947b394f2dd8c87dbb0
         with:
           image-ref: ${{ steps.build.outputs.image }}
           format: sarif
@@ -130,13 +144,13 @@ jobs:
           severity: "CRITICAL,HIGH"
 
       - name: Upload Trivy scan results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@v2
+        uses: github/codeql-action/upload-sarif@f09c1c0a94de965c15400f5634aa42fac8fb8f88 # v3.27.5
         with:
           sarif_file: trivy-results.sarif
           category: "Trivy"
 
       - name: Upload Trivy scan results as an artifact
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@604373da6381bf24206979c74d06a550515601b9 # v4.4.1
         with:
           name: trivy
           path: trivy-results.sarif

.github/workflows/stale.yaml

@@ -1,23 +1,36 @@
-name: Stale Issue, Banch and Old Workflows Cleanup
+name: Stale Issue, Branch and Old Workflows Cleanup
 on:
   schedule:
     # Every day at midnight
     - cron: "0 0 * * *"
   workflow_dispatch:
+
+permissions:
+  contents: read
+
 jobs:
   issues:
     runs-on: ubuntu-latest
     permissions:
+      # Needed to close issues.
       issues: write
+      # Needed to close PRs.
       pull-requests: write
-      actions: write
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: stale
-        uses: actions/stale@v9.0.0
+        uses: actions/stale@28ca1036281a5e5922ead5184a1bbf96e5fc984e # v9.0.0
         with:
           stale-issue-label: "stale"
           stale-pr-label: "stale"
-          days-before-stale: 180
+          # days-before-stale: 180
+          # essentially disabled for now while we work through polish issues
+          days-before-stale: 3650
+
           # Pull Requests become stale more quickly due to merge conflicts.
           # Also, we promote minimizing WIP.
           days-before-pr-stale: 7
@@ -31,7 +44,7 @@ jobs:
           # Start with the oldest issues, always.
           ascending: true
       - name: "Close old issues labeled likely-no"
-        uses: actions/github-script@v7
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -57,7 +70,7 @@ jobs:
               });
 
               const labelEvent = timeline.data.find(event => event.event === 'labeled' && event.label.name === 'likely-no');
-              
+
               if (labelEvent) {
                 console.log(`Issue #${issue.number} was labeled with 'likely-no' at ${labelEvent.created_at}`);
 
@@ -68,7 +81,7 @@ jobs:
                     repo: context.repo.repo,
                     issue_number: issue.number,
                     state: 'closed',
-                    state_reason: 'not planned'
+                    state_reason: 'not_planned'
                   });
                 }
               } else {
@@ -78,11 +91,19 @@ jobs:
 
   branches:
     runs-on: ubuntu-latest
+    permissions:
+      # Needed to delete branches.
+      contents: write
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
       - name: Run delete-old-branches-action
-        uses: beatlabs/delete-old-branches-action@v0.0.10
+        uses: beatlabs/delete-old-branches-action@6e94df089372a619c01ae2c2f666bf474f890911 # v0.0.10
         with:
           repo_token: ${{ github.token }}
           date: "6 months ago"
@@ -92,9 +113,17 @@ jobs:
           exclude_open_pr_branches: true
   del_runs:
     runs-on: ubuntu-latest
+    permissions:
+      # Needed to delete workflow runs.
+      actions: write
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Delete PR Cleanup workflow runs
-        uses: Mattraks/delete-workflow-runs@v2
+        uses: Mattraks/delete-workflow-runs@39f0bbed25d76b34de5594dceab824811479e5de # v2.0.6
         with:
           token: ${{ github.token }}
           repository: ${{ github.repository }}
@@ -103,7 +132,7 @@ jobs:
           delete_workflow_pattern: pr-cleanup.yaml
 
       - name: Delete PR Deploy workflow skipped runs
-        uses: Mattraks/delete-workflow-runs@v2
+        uses: Mattraks/delete-workflow-runs@39f0bbed25d76b34de5594dceab824811479e5de # v2.0.6
         with:
           token: ${{ github.token }}
           repository: ${{ github.repository }}

.github/workflows/typos.toml

@@ -14,7 +14,16 @@ darcula = "darcula"
 Hashi = "Hashi"
 trialer = "trialer"
 encrypter = "encrypter"
-hel = "hel" # as in helsinki
+# as in helsinki
+hel = "hel"
+# this is used as proto node
+pn = "pn"
+# typos doesn't like the EDE in TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
+EDE = "EDE"
+# HELO is an SMTP command
+HELO = "HELO"
+LKE = "LKE"
+byt = "byt"
 
 [files]
 extend-exclude = [
@@ -30,4 +39,9 @@ extend-exclude = [
 	"**/*_test.go",
 	"**/*.test.tsx",
 	"**/pnpm-lock.yaml",
+	"tailnet/testdata/**",
+	"site/src/pages/SetupPage/countries.tsx",
+	"provisioner/terraform/testdata/**",
+	# notifications' golden files confuse the detector because of quoted-printable encoding
+	"coderd/notifications/testdata/**"
 ]

.github/workflows/weekly-docs.yaml

@@ -4,27 +4,41 @@ on:
   schedule:
     - cron: "0 9 * * 1"
   workflow_dispatch: # allows to run manually for testing
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+
+permissions:
+  contents: read
 
 jobs:
   check-docs:
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write # required to post PR review comments by the action
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
+        with:
+          egress-policy: audit
+
       - name: Checkout
-        uses: actions/checkout@master
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
 
       - name: Check Markdown links
-        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        uses: umbrelladocs/action-linkspector@fc382e19892aca958e189954912fe379a8df270c # v1.2.4
         id: markdown-link-check
         # checks all markdown files from /docs including all subfolders
         with:
-          use-quiet-mode: "yes"
-          use-verbose-mode: "yes"
-          config-file: ".github/workflows/mlc_config.json"
-          folder-path: "docs/"
-          file-path: "./README.md"
+          reporter: github-pr-review
+          config_file: ".github/.linkspector.yml"
+          fail_on_error: "true"
+          filter_mode: "nofilter"
 
       - name: Send Slack notification
-        if: failure()
+        if: failure() && github.event_name == 'schedule'
         run: |
           curl -X POST -H 'Content-type: application/json' -d '{"msg":"Broken links found in the documentation. Please check the logs at ${{ env.LOGS_URL }}"}' ${{ secrets.DOCS_LINK_SLACK_WEBHOOK }}
           echo "Sent Slack notification"

.gitignore

@@ -17,6 +17,8 @@ yarn-error.log
 # Allow VSCode recommendations and default settings in project root.
 !/.vscode/extensions.json
 !/.vscode/settings.json
+# Allow code snippets
+!/.vscode/*.code-snippets
 
 # Front-end ignore patterns.
 .next/
@@ -68,3 +70,9 @@ result
 
 # Filebrowser.db
 **/filebrowser.db
+
+# pnpm
+.pnpm-store/
+
+# Zed
+.zed_server

.golangci.yaml

@@ -195,6 +195,11 @@ linters-settings:
       - name: var-naming
       - name: waitgroup-by-value
 
+  # irrelevant as of Go v1.22: https://go.dev/blog/loopvar-preview
+  govet:
+    disable:
+      - loopclosure
+
 issues:
   # Rules listed here: https://github.com/securego/gosec#available-rules
   exclude-rules:

.prettierignore

@@ -20,6 +20,8 @@ yarn-error.log
 # Allow VSCode recommendations and default settings in project root.
 !/.vscode/extensions.json
 !/.vscode/settings.json
+# Allow code snippets
+!/.vscode/*.code-snippets
 
 # Front-end ignore patterns.
 .next/
@@ -71,24 +73,24 @@ result
 
 # Filebrowser.db
 **/filebrowser.db
+
+# pnpm
+.pnpm-store/
+
+# Zed
+.zed_server
 # .prettierignore.include:
 # Helm templates contain variables that are invalid YAML and can't be formatted
 # by Prettier.
 helm/**/templates/*.yaml
 
-# Terraform state files used in tests, these are automatically generated.
-# Example: provisioner/terraform/testdata/instance-id/instance-id.tfstate.json
-**/testdata/**/*.tf*.json
-
 # Testdata shouldn't be formatted.
-scripts/apitypings/testdata/**/*.ts
-enterprise/tailnet/testdata/*.golden.html
-tailnet/testdata/*.golden.html
-
-# Generated files shouldn't be formatted.
-site/e2e/provisionerGenerated.ts
+testdata/
 
+# Ignore generated files
 **/pnpm-lock.yaml
-
-# Ignore generated JSON (e.g. examples/examples.gen.json).
 **/*.gen.json
+
+# Everything in site/ is formatted by Biome. For the rest of the repo though, we
+# need broader language support.
+site/

.prettierignore.include

@@ -2,19 +2,13 @@
 # by Prettier.
 helm/**/templates/*.yaml
 
-# Terraform state files used in tests, these are automatically generated.
-# Example: provisioner/terraform/testdata/instance-id/instance-id.tfstate.json
-**/testdata/**/*.tf*.json
-
 # Testdata shouldn't be formatted.
-scripts/apitypings/testdata/**/*.ts
-enterprise/tailnet/testdata/*.golden.html
-tailnet/testdata/*.golden.html
-
-# Generated files shouldn't be formatted.
-site/e2e/provisionerGenerated.ts
+testdata/
 
+# Ignore generated files
 **/pnpm-lock.yaml
-
-# Ignore generated JSON (e.g. examples/examples.gen.json).
 **/*.gen.json
+
+# Everything in site/ is formatted by Biome. For the rest of the repo though, we
+# need broader language support.
+site/

.prettierrc.yaml

@@ -4,13 +4,13 @@
 printWidth: 80
 proseWrap: always
 trailingComma: all
-useTabs: false
+useTabs: true
 tabWidth: 2
 overrides:
   - files:
       - README.md
-      - docs/api/**/*.md
-      - docs/cli/**/*.md
+      - docs/reference/api/**/*.md
+      - docs/reference/cli/**/*.md
       - docs/changelogs/*.md
       - .github/**/*.{yaml,yml,toml}
       - scripts/**/*.{yaml,yml,toml}

.vscode/extensions.json

@@ -1,15 +1,16 @@
 {
-  "recommendations": [
-    "github.vscode-codeql",
-    "golang.go",
-    "hashicorp.terraform",
-    "esbenp.prettier-vscode",
-    "foxundermoon.shell-format",
-    "emeraldwalk.runonsave",
-    "zxh404.vscode-proto3",
-    "redhat.vscode-yaml",
-    "streetsidesoftware.code-spell-checker",
-    "dbaeumer.vscode-eslint",
-    "EditorConfig.EditorConfig"
-  ]
+	"recommendations": [
+		"github.vscode-codeql",
+		"golang.go",
+		"hashicorp.terraform",
+		"esbenp.prettier-vscode",
+		"foxundermoon.shell-format",
+		"emeraldwalk.runonsave",
+		"zxh404.vscode-proto3",
+		"redhat.vscode-yaml",
+		"tekumara.typos-vscode",
+		"EditorConfig.EditorConfig",
+		"biomejs.biome",
+		"bradlc.vscode-tailwindcss"
+	]
 }

.vscode/markdown.code-snippets

@@ -0,0 +1,38 @@
+{
+	// For info about snippets, visit https://code.visualstudio.com/docs/editor/userdefinedsnippets
+
+    "admonition": {
+        "prefix": "#callout",
+        "body": [
+            "<blockquote class=\"admonition ${1|caution,important,note,tip,warning|}\">\n",
+            "${TM_SELECTED_TEXT:${2:add info here}}\n",
+            "</blockquote>\n"
+        ],
+        "description": "callout admonition caution info note tip warning"
+    },
+	"fenced code block": {
+		"prefix": "#codeblock",
+		"body": ["```${1|apache,bash,console,diff,Dockerfile,env,go,hcl,ini,json,lisp,md,powershell,shell,sql,text,tf,tsx,yaml|}", "${TM_SELECTED_TEXT}$0", "```"],
+		"description": "fenced code block"
+	},
+	"image": {
+		"prefix": "#image",
+		"body": "![${TM_SELECTED_TEXT:${1:alt}}](${2:url})$0",
+		"description": "image"
+	},
+	"tabs": {
+		"prefix": "#tabs",
+		"body": [
+			"<div class=\"tabs\">\n",
+			"${1:optional description}\n",
+			"## ${2:tab title}\n",
+			"${TM_SELECTED_TEXT:${3:first tab content}}\n",
+			"## ${4:tab title}\n",
+			"${5:second tab content}\n",
+			"## ${6:tab title}\n",
+			"${7:third tab content}\n",
+			"</div>\n"
+		],
+		"description": "tabs"
+	}
+}

.vscode/settings.json

@@ -1,223 +1,61 @@
 {
-  "cSpell.words": [
-    "afero",
-    "agentsdk",
-    "apps",
-    "ASKPASS",
-    "authcheck",
-    "autostop",
-    "awsidentity",
-    "bodyclose",
-    "buildinfo",
-    "buildname",
-    "circbuf",
-    "cliflag",
-    "cliui",
-    "codecov",
-    "coderd",
-    "coderdenttest",
-    "coderdtest",
-    "codersdk",
-    "contravariance",
-    "cronstrue",
-    "databasefake",
-    "dbmem",
-    "dbgen",
-    "dbtype",
-    "DERP",
-    "derphttp",
-    "derpmap",
-    "devel",
-    "devtunnel",
-    "dflags",
-    "drpc",
-    "drpcconn",
-    "drpcmux",
-    "drpcserver",
-    "Dsts",
-    "embeddedpostgres",
-    "enablements",
-    "enterprisemeta",
-    "errgroup",
-    "eventsourcemock",
-    "externalauth",
-    "Failf",
-    "fatih",
-    "Formik",
-    "gitauth",
-    "gitsshkey",
-    "goarch",
-    "gographviz",
-    "goleak",
-    "gonet",
-    "gossh",
-    "gsyslog",
-    "GTTY",
-    "hashicorp",
-    "hclsyntax",
-    "httpapi",
-    "httpmw",
-    "idtoken",
-    "Iflag",
-    "incpatch",
-    "ipnstate",
-    "isatty",
-    "Jobf",
-    "Keygen",
-    "kirsle",
-    "Kubernetes",
-    "ldflags",
-    "magicsock",
-    "manifoldco",
-    "mapstructure",
-    "mattn",
-    "mitchellh",
-    "moby",
-    "namesgenerator",
-    "namespacing",
-    "netaddr",
-    "netip",
-    "netmap",
-    "netns",
-    "netstack",
-    "nettype",
-    "nfpms",
-    "nhooyr",
-    "nmcfg",
-    "nolint",
-    "nosec",
-    "ntqry",
-    "OIDC",
-    "oneof",
-    "opty",
-    "paralleltest",
-    "parameterscopeid",
-    "pqtype",
-    "prometheusmetrics",
-    "promhttp",
-    "protobuf",
-    "provisionerd",
-    "provisionerdserver",
-    "provisionersdk",
-    "ptty",
-    "ptys",
-    "ptytest",
-    "quickstart",
-    "reconfig",
-    "replicasync",
-    "retrier",
-    "rpty",
-    "SCIM",
-    "sdkproto",
-    "sdktrace",
-    "Signup",
-    "slogtest",
-    "sourcemapped",
-    "Srcs",
-    "stdbuf",
-    "stretchr",
-    "STTY",
-    "stuntest",
-    "tanstack",
-    "tailbroker",
-    "tailcfg",
-    "tailexchange",
-    "tailnet",
-    "tailnettest",
-    "Tailscale",
-    "tbody",
-    "TCGETS",
-    "tcpip",
-    "TCSETS",
-    "templateversions",
-    "testdata",
-    "testid",
-    "testutil",
-    "tfexec",
-    "tfjson",
-    "tfplan",
-    "tfstate",
-    "thead",
-    "tios",
-    "tmpdir",
-    "tokenconfig",
-    "tparallel",
-    "trialer",
-    "trimprefix",
-    "tsdial",
-    "tslogger",
-    "tstun",
-    "turnconn",
-    "typegen",
-    "typesafe",
-    "unconvert",
-    "Untar",
-    "Userspace",
-    "VMID",
-    "walkthrough",
-    "weblinks",
-    "webrtc",
-    "wgcfg",
-    "wgconfig",
-    "wgengine",
-    "wgmonitor",
-    "wgnet",
-    "workspaceagent",
-    "workspaceagents",
-    "workspaceapp",
-    "workspaceapps",
-    "workspacebuilds",
-    "workspacename",
-    "wsconncache",
-    "wsjson",
-    "xerrors",
-    "xlarge",
-    "yamux"
-  ],
-  "cSpell.ignorePaths": ["site/package.json", ".vscode/settings.json"],
-  "emeraldwalk.runonsave": {
-    "commands": [
-      {
-        "match": "database/queries/*.sql",
-        "cmd": "make gen"
-      },
-      {
-        "match": "provisionerd/proto/provisionerd.proto",
-        "cmd": "make provisionerd/proto/provisionerd.pb.go"
-      }
-    ]
-  },
-  "eslint.workingDirectories": ["./site"],
-  "search.exclude": {
-    "**.pb.go": true,
-    "**/*.gen.json": true,
-    "**/testdata/*": true,
-    "**Generated.ts": true,
-    "coderd/apidoc/**": true,
-    "docs/api/*.md": true,
-    "docs/templates/*.md": true,
-    "LICENSE": true,
-    "scripts/metricsdocgen/metrics": true,
-    "site/out/**": true,
-    "site/storybook-static/**": true,
-    "**.map": true,
-    "pnpm-lock.yaml": true
-  },
-  // Ensure files always have a newline.
-  "files.insertFinalNewline": true,
-  "go.lintTool": "golangci-lint",
-  "go.lintFlags": ["--fast"],
-  "go.coverageDecorator": {
-    "type": "gutter",
-    "coveredGutterStyle": "blockgreen",
-    "uncoveredGutterStyle": "blockred"
-  },
-  // The codersdk is used by coderd another other packages extensively.
-  // To reduce redundancy in tests, it's covered by other packages.
-  // Since package coverage pairing can't be defined, all packages cover
-  // all other packages.
-  "go.testFlags": ["-short", "-coverpkg=./..."],
-  // We often use a version of TypeScript that's ahead of the version shipped
-  // with VS Code.
-  "typescript.tsdk": "./site/node_modules/typescript/lib"
+	"emeraldwalk.runonsave": {
+		"commands": [
+			{
+				"match": "database/queries/*.sql",
+				"cmd": "make gen"
+			},
+			{
+				"match": "provisionerd/proto/provisionerd.proto",
+				"cmd": "make provisionerd/proto/provisionerd.pb.go"
+			}
+		]
+	},
+	"search.exclude": {
+		"**.pb.go": true,
+		"**/*.gen.json": true,
+		"**/testdata/*": true,
+		"coderd/apidoc/**": true,
+		"docs/reference/api/*.md": true,
+		"docs/reference/cli/*.md": true,
+		"docs/templates/*.md": true,
+		"LICENSE": true,
+		"scripts/metricsdocgen/metrics": true,
+		"site/out/**": true,
+		"site/storybook-static/**": true,
+		"**.map": true,
+		"pnpm-lock.yaml": true
+	},
+	// Ensure files always have a newline.
+	"files.insertFinalNewline": true,
+	"go.lintTool": "golangci-lint",
+	"go.lintFlags": ["--fast"],
+	"go.coverageDecorator": {
+		"type": "gutter",
+		"coveredGutterStyle": "blockgreen",
+		"uncoveredGutterStyle": "blockred"
+	},
+	// The codersdk is used by coderd another other packages extensively.
+	// To reduce redundancy in tests, it's covered by other packages.
+	// Since package coverage pairing can't be defined, all packages cover
+	// all other packages.
+	"go.testFlags": ["-short", "-coverpkg=./..."],
+	// We often use a version of TypeScript that's ahead of the version shipped
+	// with VS Code.
+	"typescript.tsdk": "./site/node_modules/typescript/lib",
+	// Playwright tests in VSCode will open a browser to live "view" the test.
+	"playwright.reuseBrowser": true,
+
+	"[javascript][javascriptreact][json][jsonc][typescript][typescriptreact]": {
+		"editor.defaultFormatter": "biomejs.biome",
+		"editor.codeActionsOnSave": {
+			"quickfix.biome": "explicit"
+			//   "source.organizeImports.biome": "explicit"
+		}
+	},
+
+	"[css][html][markdown][yaml]": {
+		"editor.defaultFormatter": "esbenp.prettier-vscode"
+	},
+	"typos.config": ".github/workflows/typos.toml"
 }

CODEOWNERS

@@ -0,0 +1,6 @@
+# These APIs are versioned, so any changes need to be carefully reviewed for whether
+# to bump API major or minor versions.
+agent/proto/ @spikecurtis @johnstcn
+tailnet/proto/ @spikecurtis @johnstcn
+vpn/vpn.proto @spikecurtis @johnstcn
+vpn/version.go @spikecurtis @johnstcn

CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+[https://coder.com/docs/coder-oss/latest/contributing/CODE_OF_CONDUCT](https://coder.com/docs/contributing/CODE_OF_CONDUCT)

Makefile

@@ -36,6 +36,7 @@ GOOS         := $(shell go env GOOS)
 GOARCH       := $(shell go env GOARCH)
 GOOS_BIN_EXT := $(if $(filter windows, $(GOOS)),.exe,)
 VERSION      := $(shell ./scripts/version.sh)
+POSTGRES_VERSION ?= 16
 
 # Use the highest ZSTD compression level in CI.
 ifdef CI
@@ -56,6 +57,9 @@ GO_SRC_FILES := $(shell find . $(FIND_EXCLUSIONS) -type f -name '*.go' -not -nam
 # All the shell files in the repo, excluding ignored files.
 SHELL_SRC_FILES := $(shell find . $(FIND_EXCLUSIONS) -type f -name '*.sh')
 
+# Ensure we don't use the user's git configs which might cause side-effects
+GIT_FLAGS = GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null
+
 # All ${OS}_${ARCH} combos we build for. Windows binaries have the .exe suffix.
 OS_ARCHES := \
 	linux_amd64 linux_arm64 linux_armv7 \
@@ -75,8 +79,12 @@ PACKAGE_OS_ARCHES := linux_amd64 linux_armv7 linux_arm64
 # All architectures we build Docker images for (Linux only).
 DOCKER_ARCHES := amd64 arm64 armv7
 
+# All ${OS}_${ARCH} combos we build the desktop dylib for.
+DYLIB_ARCHES := darwin_amd64 darwin_arm64
+
 # Computed variables based on the above.
 CODER_SLIM_BINARIES      := $(addprefix build/coder-slim_$(VERSION)_,$(OS_ARCHES))
+CODER_DYLIBS             := $(foreach os_arch, $(DYLIB_ARCHES), build/coder-vpn_$(VERSION)_$(os_arch).dylib)
 CODER_FAT_BINARIES       := $(addprefix build/coder_$(VERSION)_,$(OS_ARCHES))
 CODER_ALL_BINARIES       := $(CODER_SLIM_BINARIES) $(CODER_FAT_BINARIES)
 CODER_TAR_GZ_ARCHIVES    := $(foreach os_arch, $(ARCHIVE_TAR_GZ), build/coder_$(VERSION)_$(os_arch).tar.gz)
@@ -200,7 +208,8 @@ endef
 # calling this manually.
 $(CODER_ALL_BINARIES): go.mod go.sum \
 	$(GO_SRC_FILES) \
-	$(shell find ./examples/templates)
+	$(shell find ./examples/templates) \
+	site/static/error.html
 
 	$(get-mode-os-arch-ext)
 	if [[ "$$os" != "windows" ]] && [[ "$$ext" != "" ]]; then
@@ -233,6 +242,25 @@ $(CODER_ALL_BINARIES): go.mod go.sum \
 		cp "$@" "./site/out/bin/coder-$$os-$$arch$$dot_ext"
 	fi
 
+# This task builds Coder Desktop dylibs
+$(CODER_DYLIBS): go.mod go.sum $(GO_SRC_FILES)
+	@if [ "$(shell uname)" = "Darwin" ]; then
+		$(get-mode-os-arch-ext)
+		./scripts/build_go.sh \
+			--os "$$os" \
+			--arch "$$arch" \
+			--version "$(VERSION)" \
+			--output "$@" \
+			--dylib
+
+	else
+		echo "ERROR: Can't build dylib on non-Darwin OS" 1>&2
+		exit 1
+	fi
+
+# This task builds both dylibs
+build/coder-dylib: $(CODER_DYLIBS)
+
 # This task builds all archives. It parses the target name to get the metadata
 # for the build, so it must be specified in this format:
 #     build/coder_${version}_${os}_${arch}.${format}
@@ -361,6 +389,8 @@ $(foreach chart,$(charts),build/$(chart)_helm_$(VERSION).tgz): build/%_helm_$(VE
 
 site/out/index.html: site/package.json $(shell find ./site $(FIND_EXCLUSIONS) -type f \( -name '*.ts' -o -name '*.tsx' \))
 	cd site
+	# prevents this directory from getting to big, and causing "too much data" errors
+	rm -rf out/assets/
 	../scripts/pnpm_install.sh
 	pnpm build
 
@@ -380,32 +410,49 @@ install: build/coder_$(VERSION)_$(GOOS)_$(GOARCH)$(GOOS_BIN_EXT)
 	cp "$<" "$$output_file"
 .PHONY: install
 
-fmt: fmt/prettier fmt/terraform fmt/shfmt fmt/go
+BOLD := $(shell tput bold 2>/dev/null)
+GREEN := $(shell tput setaf 2 2>/dev/null)
+RESET := $(shell tput sgr0 2>/dev/null)
+
+fmt: fmt/ts fmt/go fmt/terraform fmt/shfmt fmt/prettier
 .PHONY: fmt
 
 fmt/go:
+	go mod tidy
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/go$(RESET)"
 	# VS Code users should check out
 	# https://github.com/mvdan/gofumpt#visual-studio-code
 	go run mvdan.cc/gofumpt@v0.4.0 -w -l .
 .PHONY: fmt/go
 
-fmt/prettier:
-	echo "--- prettier"
+fmt/ts:
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/ts$(RESET)"
 	cd site
 # Avoid writing files in CI to reduce file write activity
+ifdef CI
+	pnpm run check --linter-enabled=false
+else
+	pnpm run check:fix
+endif
+.PHONY: fmt/ts
+
+fmt/prettier: .prettierignore
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/prettier$(RESET)"
+# Avoid writing files in CI to reduce file write activity
 ifdef CI
 	pnpm run format:check
 else
-	pnpm run format:write
+	pnpm run format
 endif
 .PHONY: fmt/prettier
 
 fmt/terraform: $(wildcard *.tf)
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/terraform$(RESET)"
 	terraform fmt -recursive
 .PHONY: fmt/terraform
 
 fmt/shfmt: $(SHELL_SRC_FILES)
-	echo "--- shfmt"
+	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/shfmt$(RESET)"
 # Only do diff check in CI, errors on diff.
 ifdef CI
 	shfmt -d $(SHELL_SRC_FILES)
@@ -414,7 +461,7 @@ else
 endif
 .PHONY: fmt/shfmt
 
-lint: lint/shellcheck lint/go lint/ts lint/helm lint/site-icons
+lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons
 .PHONY: lint
 
 lint/site-icons:
@@ -423,16 +470,20 @@ lint/site-icons:
 
 lint/ts:
 	cd site
-	pnpm i && pnpm lint
+	pnpm lint
 .PHONY: lint/ts
 
 lint/go:
 	./scripts/check_enterprise_imports.sh
-	linter_ver=$(shell egrep -o 'GOLANGCI_LINT_VERSION=\S+' dogfood/Dockerfile | cut -d '=' -f 2)
-	go install github.com/golangci/golangci-lint/cmd/golangci-lint@v$$linter_ver
-	golangci-lint run
+	./scripts/check_codersdk_imports.sh
+	linter_ver=$(shell egrep -o 'GOLANGCI_LINT_VERSION=\S+' dogfood/contents/Dockerfile | cut -d '=' -f 2)
+	go run github.com/golangci/golangci-lint/cmd/golangci-lint@v$$linter_ver run
 .PHONY: lint/go
 
+lint/examples:
+	go run ./scripts/examplegen/main.go -lint
+.PHONY: lint/examples
+
 # Use shfmt to determine the shell files, takes editorconfig into consideration.
 lint/shellcheck: $(SHELL_SRC_FILES)
 	echo "--- shellcheck"
@@ -454,28 +505,39 @@ DB_GEN_FILES := \
 	coderd/database/dbauthz/dbauthz.go \
 	coderd/database/dbmock/dbmock.go
 
+TAILNETTEST_MOCKS := \
+	tailnet/tailnettest/coordinatormock.go \
+	tailnet/tailnettest/coordinateemock.go \
+	tailnet/tailnettest/workspaceupdatesprovidermock.go \
+	tailnet/tailnettest/subscriptionmock.go
+
+
 # all gen targets should be added here and to gen/mark-fresh
 gen: \
 	tailnet/proto/tailnet.pb.go \
 	agent/proto/agent.pb.go \
 	provisionersdk/proto/provisioner.pb.go \
 	provisionerd/proto/provisionerd.pb.go \
+	vpn/vpn.pb.go \
 	coderd/database/dump.sql \
 	$(DB_GEN_FILES) \
 	site/src/api/typesGenerated.ts \
 	coderd/rbac/object_gen.go \
-	docs/admin/prometheus.md \
-	docs/cli.md \
-	docs/admin/audit-logs.md \
+	codersdk/rbacresources_gen.go \
+	site/src/api/rbacresourcesGenerated.ts \
+	site/src/api/countriesGenerated.ts \
+	docs/admin/integrations/prometheus.md \
+	docs/reference/cli/index.md \
+	docs/admin/security/audit-logs.md \
 	coderd/apidoc/swagger.json \
 	.prettierignore.include \
 	.prettierignore \
-	site/.prettierrc.yaml \
-	site/.prettierignore \
-	site/.eslintignore \
+	provisioner/terraform/testdata/version \
 	site/e2e/provisionerGenerated.ts \
 	site/src/theme/icons.json \
-	examples/examples.gen.json
+	examples/examples.gen.json \
+	$(TAILNETTEST_MOCKS) \
+	coderd/database/pubsub/psmock/psmock.go
 .PHONY: gen
 
 # Mark all generated files as fresh so make thinks they're up-to-date. This is
@@ -486,23 +548,27 @@ gen/mark-fresh:
 		agent/proto/agent.pb.go \
 		provisionersdk/proto/provisioner.pb.go \
 		provisionerd/proto/provisionerd.pb.go \
+		vpn/vpn.pb.go \
 		coderd/database/dump.sql \
 		$(DB_GEN_FILES) \
 		site/src/api/typesGenerated.ts \
 		coderd/rbac/object_gen.go \
-		docs/admin/prometheus.md \
-		docs/cli.md \
-		docs/admin/audit-logs.md \
+		codersdk/rbacresources_gen.go \
+		site/src/api/rbacresourcesGenerated.ts \
+		site/src/api/countriesGenerated.ts \
+		docs/admin/integrations/prometheus.md \
+		docs/reference/cli/index.md \
+		docs/admin/security/audit-logs.md \
 		coderd/apidoc/swagger.json \
 		.prettierignore.include \
 		.prettierignore \
-		site/.prettierrc.yaml \
-		site/.prettierignore \
-		site/.eslintignore \
 		site/e2e/provisionerGenerated.ts \
 		site/src/theme/icons.json \
 		examples/examples.gen.json \
-	"
+		$(TAILNETTEST_MOCKS) \
+		coderd/database/pubsub/psmock/psmock.go \
+		"
+
 	for file in $$files; do
 		echo "$$file"
 		if [ ! -f "$$file" ]; then
@@ -529,6 +595,12 @@ coderd/database/querier.go: coderd/database/sqlc.yaml coderd/database/dump.sql $
 coderd/database/dbmock/dbmock.go: coderd/database/db.go coderd/database/querier.go
 	go generate ./coderd/database/dbmock/
 
+coderd/database/pubsub/psmock/psmock.go: coderd/database/pubsub/pubsub.go
+	go generate ./coderd/database/pubsub/psmock
+
+$(TAILNETTEST_MOCKS): tailnet/coordinator.go tailnet/service.go
+	go generate ./tailnet/tailnettest/
+
 tailnet/proto/tailnet.pb.go: tailnet/proto/tailnet.proto
 	protoc \
 		--go_out=. \
@@ -561,9 +633,15 @@ provisionerd/proto/provisionerd.pb.go: provisionerd/proto/provisionerd.proto
 		--go-drpc_opt=paths=source_relative \
 		./provisionerd/proto/provisionerd.proto
 
+vpn/vpn.pb.go: vpn/vpn.proto
+	protoc \
+		--go_out=. \
+		--go_opt=paths=source_relative \
+		./vpn/vpn.proto
+
 site/src/api/typesGenerated.ts: $(wildcard scripts/apitypings/*) $(shell find ./codersdk $(FIND_EXCLUSIONS) -type f -name '*.go')
 	go run ./scripts/apitypings/ > $@
-	pnpm run format:write:only "$@"
+	./scripts/pnpm_install.sh
 
 site/e2e/provisionerGenerated.ts: provisionerd/proto/provisionerd.pb.go provisionersdk/proto/provisioner.pb.go
 	cd site
@@ -572,29 +650,46 @@ site/e2e/provisionerGenerated.ts: provisionerd/proto/provisionerd.pb.go provisio
 
 site/src/theme/icons.json: $(wildcard scripts/gensite/*) $(wildcard site/static/icon/*)
 	go run ./scripts/gensite/ -icons "$@"
-	pnpm run format:write:only "$@"
+	./scripts/pnpm_install.sh
+	pnpm -C site/ exec biome format --write src/theme/icons.json
 
 examples/examples.gen.json: scripts/examplegen/main.go examples/examples.go $(shell find ./examples/templates)
 	go run ./scripts/examplegen/main.go > examples/examples.gen.json
 
-coderd/rbac/object_gen.go: scripts/rbacgen/main.go coderd/rbac/object.go
-	go run scripts/rbacgen/main.go ./coderd/rbac > coderd/rbac/object_gen.go
+coderd/rbac/object_gen.go: scripts/typegen/rbacobject.gotmpl scripts/typegen/main.go coderd/rbac/object.go coderd/rbac/policy/policy.go
+	go run scripts/typegen/main.go rbac object > coderd/rbac/object_gen.go
 
-docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics
+codersdk/rbacresources_gen.go: scripts/typegen/codersdk.gotmpl scripts/typegen/main.go coderd/rbac/object.go coderd/rbac/policy/policy.go
+	# Do no overwrite codersdk/rbacresources_gen.go directly, as it would make the file empty, breaking
+ 	# the `codersdk` package and any parallel build targets.
+	go run scripts/typegen/main.go rbac codersdk > /tmp/rbacresources_gen.go
+	mv /tmp/rbacresources_gen.go codersdk/rbacresources_gen.go
+
+site/src/api/rbacresourcesGenerated.ts: scripts/typegen/codersdk.gotmpl scripts/typegen/main.go coderd/rbac/object.go coderd/rbac/policy/policy.go
+	go run scripts/typegen/main.go rbac typescript > "$@"
+
+site/src/api/countriesGenerated.ts: scripts/typegen/countries.tstmpl scripts/typegen/main.go codersdk/countries.go
+	go run scripts/typegen/main.go countries > "$@"
+
+docs/admin/integrations/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/metrics
 	go run scripts/metricsdocgen/main.go
-	pnpm run format:write:only ./docs/admin/prometheus.md
+	./scripts/pnpm_install.sh
+	pnpm exec prettier --write ./docs/admin/integrations/prometheus.md
 
-docs/cli.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
+docs/reference/cli/index.md: scripts/clidocgen/main.go examples/examples.gen.json $(GO_SRC_FILES)
 	CI=true BASE_PATH="." go run ./scripts/clidocgen
-	pnpm run format:write:only ./docs/cli.md ./docs/cli/*.md ./docs/manifest.json
+	./scripts/pnpm_install.sh
+	pnpm exec prettier --write ./docs/reference/cli/index.md ./docs/reference/cli/*.md ./docs/manifest.json
 
-docs/admin/audit-logs.md: scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
+docs/admin/security/audit-logs.md: coderd/database/querier.go scripts/auditdocgen/main.go enterprise/audit/table.go coderd/rbac/object_gen.go
 	go run scripts/auditdocgen/main.go
-	pnpm run format:write:only ./docs/admin/audit-logs.md
+	./scripts/pnpm_install.sh
+	pnpm exec prettier --write ./docs/admin/security/audit-logs.md
 
 coderd/apidoc/swagger.json: $(shell find ./scripts/apidocgen $(FIND_EXCLUSIONS) -type f) $(wildcard coderd/*.go) $(wildcard enterprise/coderd/*.go) $(wildcard codersdk/*.go) $(wildcard enterprise/wsproxy/wsproxysdk/*.go) $(DB_GEN_FILES) .swaggo docs/manifest.json coderd/rbac/object_gen.go
 	./scripts/apidocgen/generate.sh
-	pnpm run format:write:only ./docs/api ./docs/manifest.json ./coderd/apidoc/swagger.json
+	./scripts/pnpm_install.sh
+	pnpm exec prettier --write ./docs/reference/api ./docs/manifest.json ./coderd/apidoc/swagger.json
 
 update-golden-files: \
 	cli/testdata/.gen-golden \
@@ -605,11 +700,12 @@ update-golden-files: \
 	enterprise/tailnet/testdata/.gen-golden \
 	tailnet/testdata/.gen-golden \
 	coderd/.gen-golden \
+	coderd/notifications/.gen-golden \
 	provisioner/terraform/testdata/.gen-golden
 .PHONY: update-golden-files
 
 cli/testdata/.gen-golden: $(wildcard cli/testdata/*.golden) $(wildcard cli/*.tpl) $(GO_SRC_FILES) $(wildcard cli/*_test.go)
-	go test ./cli -run="Test(CommandHelp|ServerYAML)" -update
+	go test ./cli -run="Test(CommandHelp|ServerYAML|ErrorExamples)" -update
 	touch "$@"
 
 enterprise/cli/testdata/.gen-golden: $(wildcard enterprise/cli/testdata/*.golden) $(wildcard cli/*.tpl) $(GO_SRC_FILES) $(wildcard enterprise/cli/*_test.go)
@@ -636,31 +732,24 @@ coderd/.gen-golden: $(wildcard coderd/testdata/*/*.golden) $(GO_SRC_FILES) $(wil
 	go test ./coderd -run="Test.*Golden$$" -update
 	touch "$@"
 
+coderd/notifications/.gen-golden: $(wildcard coderd/notifications/testdata/*/*.golden) $(GO_SRC_FILES) $(wildcard coderd/notifications/*_test.go)
+	go test ./coderd/notifications -run="Test.*Golden$$" -update
+	touch "$@"
+
 provisioner/terraform/testdata/.gen-golden: $(wildcard provisioner/terraform/testdata/*/*.golden) $(GO_SRC_FILES) $(wildcard provisioner/terraform/*_test.go)
 	go test ./provisioner/terraform -run="Test.*Golden$$" -update
 	touch "$@"
 
+provisioner/terraform/testdata/version:
+	if [[ "$(shell cat provisioner/terraform/testdata/version.txt)" != "$(shell terraform version -json | jq -r '.terraform_version')" ]]; then
+		./provisioner/terraform/testdata/generate.sh
+	fi
+.PHONY: provisioner/terraform/testdata/version
+
 scripts/ci-report/testdata/.gen-golden: $(wildcard scripts/ci-report/testdata/*) $(wildcard scripts/ci-report/*.go)
 	go test ./scripts/ci-report -run=TestOutputMatchesGoldenFile -update
 	touch "$@"
 
-# Generate a prettierrc for the site package that uses relative paths for
-# overrides. This allows us to share the same prettier config between the
-# site and the root of the repo.
-site/.prettierrc.yaml: .prettierrc.yaml
-	. ./scripts/lib.sh
-	dependencies yq
-
-	echo "# Code generated by Makefile (../$<). DO NOT EDIT." > "$@"
-	echo "" >> "$@"
-
-	# Replace all listed override files with relative paths inside site/.
-	# - ./ -> ../
-	# - ./site -> ./
-	yq \
-		'.overrides[].files |= map(. | sub("^./"; "") | sub("^"; "../") | sub("../site/"; "./") | sub("../!"; "!../"))' \
-		"$<" >> "$@"
-
 # Combine .gitignore with .prettierignore.include to generate .prettierignore.
 .prettierignore: .gitignore .prettierignore.include
 	echo "# Code generated by Makefile ($^). DO NOT EDIT." > "$@"
@@ -670,44 +759,31 @@ site/.prettierrc.yaml: .prettierrc.yaml
 		cat "$$f" >> "$@"
 	done
 
-# Generate ignore files based on gitignore into the site directory. We turn all
-# rules into relative paths for the `site/` directory (where applicable),
-# following the pattern format defined by git:
-# https://git-scm.com/docs/gitignore#_pattern_format
-#
-# This is done for compatibility reasons, see:
-# https://github.com/prettier/prettier/issues/8048
-# https://github.com/prettier/prettier/issues/8506
-# https://github.com/prettier/prettier/issues/8679
-site/.eslintignore site/.prettierignore: .prettierignore Makefile
-	rm -f "$@"
-	touch "$@"
-	# Skip generated by header, inherit `.prettierignore` header as-is.
-	while read -r rule; do
-		# Remove leading ! if present to simplify rule, added back at the end.
-		tmp="$${rule#!}"
-		ignore="$${rule%"$$tmp"}"
-		rule="$$tmp"
-		case "$$rule" in
-			# Comments or empty lines (include).
-			\#*|'') ;;
-			# Generic rules (include).
-			\*\**) ;;
-			# Site prefixed rules (include).
-			site/*) rule="$${rule#site/}";;
-			./site/*) rule="$${rule#./site/}";;
-			# Rules that are non-generic and don't start with site (rewrite).
-			/*) rule=.."$$rule";;
-			*/?*) rule=../"$$rule";;
-			*) ;;
-		esac
-		echo "$${ignore}$${rule}" >> "$@"
-	done < "$<"
-
 test:
-	gotestsum --format standard-quiet -- -v -short -count=1 ./...
+	$(GIT_FLAGS) gotestsum --format standard-quiet -- -v -short -count=1 ./...
 .PHONY: test
 
+# sqlc-cloud-is-setup will fail if no SQLc auth token is set. Use this as a
+# dependency for any sqlc-cloud related targets.
+sqlc-cloud-is-setup:
+	if [[ "$(SQLC_AUTH_TOKEN)" == "" ]]; then
+		echo "ERROR: 'SQLC_AUTH_TOKEN' must be set to auth with sqlc cloud before running verify." 1>&2
+		exit 1
+	fi
+.PHONY: sqlc-cloud-is-setup
+
+sqlc-push: sqlc-cloud-is-setup test-postgres-docker
+	echo "--- sqlc push"
+	SQLC_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/$(shell go run scripts/migrate-ci/main.go)" \
+	sqlc push -f coderd/database/sqlc.yaml && echo "Passed sqlc push"
+.PHONY: sqlc-push
+
+sqlc-verify: sqlc-cloud-is-setup test-postgres-docker
+	echo "--- sqlc verify"
+	SQLC_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/$(shell go run scripts/migrate-ci/main.go)" \
+	sqlc verify -f coderd/database/sqlc.yaml && echo "Passed sqlc verify"
+.PHONY: sqlc-verify
+
 sqlc-vet: test-postgres-docker
 	echo "--- sqlc vet"
 	SQLC_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/$(shell go run scripts/migrate-ci/main.go)" \
@@ -720,7 +796,7 @@ sqlc-vet: test-postgres-docker
 test-postgres: test-postgres-docker
 	# The postgres test is prone to failure, so we limit parallelism for
 	# more consistent execution.
-	DB=ci DB_FROM=$(shell go run scripts/migrate-ci/main.go) gotestsum \
+	$(GIT_FLAGS)  DB=ci gotestsum \
 		--junitfile="gotests.xml" \
 		--jsonfile="gotests.json" \
 		--packages="./..." -- \
@@ -729,8 +805,20 @@ test-postgres: test-postgres-docker
 		-count=1
 .PHONY: test-postgres
 
+test-migrations: test-postgres-docker
+	echo "--- test migrations"
+	set -euo pipefail
+	COMMIT_FROM=$(shell git log -1 --format='%h' HEAD)
+	echo "COMMIT_FROM=$${COMMIT_FROM}"
+	COMMIT_TO=$(shell git log -1 --format='%h' origin/main)
+	echo "COMMIT_TO=$${COMMIT_TO}"
+	if [[ "$${COMMIT_FROM}" == "$${COMMIT_TO}" ]]; then echo "Nothing to do!"; exit 0; fi
+	echo "DROP DATABASE IF EXISTS migrate_test_$${COMMIT_FROM}; CREATE DATABASE migrate_test_$${COMMIT_FROM};" | psql 'postgresql://postgres:postgres@localhost:5432/postgres?sslmode=disable'
+	go run ./scripts/migrate-test/main.go --from="$$COMMIT_FROM" --to="$$COMMIT_TO" --postgres-url="postgresql://postgres:postgres@localhost:5432/migrate_test_$${COMMIT_FROM}?sslmode=disable"
+
+# NOTE: we set --memory to the same size as a GitHub runner.
 test-postgres-docker:
-	docker rm -f test-postgres-docker || true
+	docker rm -f test-postgres-docker-${POSTGRES_VERSION} || true
 	docker run \
 		--env POSTGRES_PASSWORD=postgres \
 		--env POSTGRES_USER=postgres \
@@ -738,10 +826,11 @@ test-postgres-docker:
 		--env PGDATA=/tmp \
 		--tmpfs /tmp \
 		--publish 5432:5432 \
-		--name test-postgres-docker \
+		--name test-postgres-docker-${POSTGRES_VERSION} \
 		--restart no \
 		--detach \
-		gcr.io/coder-dev-1/postgres:13 \
+		--memory 16GB \
+		gcr.io/coder-dev-1/postgres:${POSTGRES_VERSION} \
 		-c shared_buffers=1GB \
 		-c work_mem=1GB \
 		-c effective_cache_size=1GB \
@@ -759,12 +848,28 @@ test-postgres-docker:
 
 # Make sure to keep this in sync with test-go-race from .github/workflows/ci.yaml.
 test-race:
-	gotestsum --junitfile="gotests.xml" -- -race -count=1 ./...
+	$(GIT_FLAGS) gotestsum --junitfile="gotests.xml" -- -race -count=1 -parallel 4 -p 4 ./...
 .PHONY: test-race
 
+test-tailnet-integration:
+	env \
+		CODER_TAILNET_TESTS=true \
+		CODER_MAGICSOCK_DEBUG_LOGGING=true \
+		TS_DEBUG_NETCHECK=true \
+		GOTRACEBACK=single \
+		go test \
+			-exec "sudo -E" \
+			-timeout=5m \
+			-count=1 \
+			./tailnet/test/integration
+
 # Note: we used to add this to the test target, but it's not necessary and we can
 # achieve the desired result by specifying -count=1 in the go test invocation
 # instead. Keeping it here for convenience.
 test-clean:
 	go clean -testcache
 .PHONY: test-clean
+
+.PHONY: test-e2e
+test-e2e:
+	cd ./site && DEBUG=pw:api pnpm playwright:test --forbid-only --workers 1

README.md

@@ -7,7 +7,7 @@
   </a>
 
   <h1>
-  Self-Hosted Remote Development Environments
+  Self-Hosted Cloud Development Environments
   </h1>
 
   <a href="https://coder.com#gh-light-mode-only">
@@ -20,20 +20,21 @@
   <br>
   <br>
 
-[Quickstart](#quickstart) | [Docs](https://coder.com/docs) | [Why Coder](https://coder.com/why) | [Enterprise](https://coder.com/docs/v2/latest/enterprise)
+[Quickstart](#quickstart) | [Docs](https://coder.com/docs) | [Why Coder](https://coder.com/why) | [Premium](https://coder.com/pricing#compare-plans)
 
 [![discord](https://img.shields.io/discord/747933592273027093?label=discord)](https://discord.gg/coder)
-[![codecov](https://codecov.io/gh/coder/coder/branch/main/graph/badge.svg?token=TNLW3OAP6G)](https://codecov.io/gh/coder/coder)
 [![release](https://img.shields.io/github/v/release/coder/coder)](https://github.com/coder/coder/releases/latest)
 [![godoc](https://pkg.go.dev/badge/github.com/coder/coder.svg)](https://pkg.go.dev/github.com/coder/coder)
-[![Go Report Card](https://goreportcard.com/badge/github.com/coder/coder)](https://goreportcard.com/report/github.com/coder/coder)
+[![Go Report Card](https://goreportcard.com/badge/github.com/coder/coder/v2)](https://goreportcard.com/report/github.com/coder/coder/v2)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9511/badge)](https://www.bestpractices.dev/projects/9511)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/coder/coder/badge)](https://scorecard.dev/viewer/?uri=github.com%2Fcoder%2Fcoder)
 [![license](https://img.shields.io/github/license/coder/coder)](./LICENSE)
 
 </div>
 
-[Coder](https://coder.com) enables organizations to set up development environments in the cloud. Environments are defined with Terraform, connected through a secure high-speed Wireguard® tunnel, and are automatically shut down when not in use to save on costs. Coder gives engineering teams the flexibility to use the cloud for workloads that are most beneficial to them.
+[Coder](https://coder.com) enables organizations to set up development environments in their public or private cloud infrastructure. Cloud development environments are defined with Terraform, connected through a secure high-speed Wireguard® tunnel, and automatically shut down when not used to save on costs. Coder gives engineering teams the flexibility to use the cloud for workloads most beneficial to them.
 
-- Define development environments in Terraform
+- Define cloud development environments in Terraform
   - EC2 VMs, Kubernetes Pods, Docker Containers, etc.
 - Automatically shutdown idle resources to save on costs
 - Onboard developers in seconds instead of days
@@ -44,7 +45,7 @@
 
 ## Quickstart
 
-The most convenient way to try Coder is to install it on your local machine and experiment with provisioning development environments using Docker (works on Linux, macOS, and Windows).
+The most convenient way to try Coder is to install it on your local machine and experiment with provisioning cloud development environments using Docker (works on Linux, macOS, and Windows).
 
 ```
 # First, install Coder
@@ -53,8 +54,8 @@ curl -L https://coder.com/install.sh | sh
 # Start the Coder server (caches data in ~/.cache/coder)
 coder server
 
-# Navigate to http://localhost:3000 to create your initial user
-# Create a Docker template, and provision a workspace
+# Navigate to http://localhost:3000 to create your initial user,
+# create a Docker template and provision a workspace
 ```
 
 ## Install
@@ -68,11 +69,11 @@ Releases.
 curl -L https://coder.com/install.sh | sh
 ```
 
-You can run the install script with `--dry-run` to see the commands that will be used to install without executing them. You can modify the installation process by including flags. Run the install script with `--help` for reference.
+You can run the install script with `--dry-run` to see the commands that will be used to install without executing them. Run the install script with `--help` for additional flags.
 
-> See [install](https://coder.com/docs/v2/latest/install) for additional methods.
+> See [install](https://coder.com/docs/install) for additional methods.
 
-Once installed, you can start a production deployment<sup>1</sup> with a single command:
+Once installed, you can start a production deployment with a single command:
 
 ```shell
 # Automatically sets up an external access URL on *.try.coder.app
@@ -82,44 +83,49 @@ coder server
 coder server --postgres-url <url> --access-url <url>
 ```
 
-> <sup>1</sup> For production deployments, set up an external PostgreSQL instance for reliability.
-
-Use `coder --help` to get a list of flags and environment variables. Use our [install guides](https://coder.com/docs/v2/latest/install) for a full walkthrough.
+Use `coder --help` to get a list of flags and environment variables. Use our [install guides](https://coder.com/docs/install) for a complete walkthrough.
 
 ## Documentation
 
-Browse our docs [here](https://coder.com/docs/v2) or visit a specific section below:
+Browse our docs [here](https://coder.com/docs) or visit a specific section below:
 
-- [**Templates**](https://coder.com/docs/v2/latest/templates): Templates are written in Terraform and describe the infrastructure for workspaces
-- [**Workspaces**](https://coder.com/docs/v2/latest/workspaces): Workspaces contain the IDEs, dependencies, and configuration information needed for software development
-- [**IDEs**](https://coder.com/docs/v2/latest/ides): Connect your existing editor to a workspace
-- [**Administration**](https://coder.com/docs/v2/latest/admin): Learn how to operate Coder
-- [**Enterprise**](https://coder.com/docs/v2/latest/enterprise): Learn about our paid features built for large teams
+- [**Templates**](https://coder.com/docs/templates): Templates are written in Terraform and describe the infrastructure for workspaces
+- [**Workspaces**](https://coder.com/docs/workspaces): Workspaces contain the IDEs, dependencies, and configuration information needed for software development
+- [**IDEs**](https://coder.com/docs/ides): Connect your existing editor to a workspace
+- [**Administration**](https://coder.com/docs/admin): Learn how to operate Coder
+- [**Premium**](https://coder.com/pricing#compare-plans): Learn about our paid features built for large teams
 
-## Community and Support
+## Support
 
 Feel free to [open an issue](https://github.com/coder/coder/issues/new) if you have questions, run into bugs, or have a feature request.
 
-[Join our Discord](https://discord.gg/coder) to provide feedback on in-progress features, and chat with the community using Coder!
+[Join our Discord](https://discord.gg/coder) to provide feedback on in-progress features and chat with the community using Coder!
 
-## Contributing
+## Integrations
 
-Contributions are welcome! Read the [contributing docs](https://coder.com/docs/v2/latest/CONTRIBUTING) to get started.
-
-Find our list of contributors [here](https://github.com/coder/coder/graphs/contributors).
-
-## Related
-
-We are always working on new integrations. Feel free to open an issue to request an integration. Contributions are welcome in any official or community repositories.
+We are always working on new integrations. Please feel free to open an issue and ask for an integration. Contributions are welcome in any official or community repositories.
 
 ### Official
 
 - [**VS Code Extension**](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote): Open any Coder workspace in VS Code with a single click
 - [**JetBrains Gateway Extension**](https://plugins.jetbrains.com/plugin/19620-coder): Open any Coder workspace in JetBrains Gateway with a single click
+- [**Dev Container Builder**](https://github.com/coder/envbuilder): Build development environments using `devcontainer.json` on Docker, Kubernetes, and OpenShift
+- [**Module Registry**](https://registry.coder.com): Extend development environments with common use-cases
+- [**Kubernetes Log Stream**](https://github.com/coder/coder-logstream-kube): Stream Kubernetes Pod events to the Coder startup logs
 - [**Self-Hosted VS Code Extension Marketplace**](https://github.com/coder/code-marketplace): A private extension marketplace that works in restricted or airgapped networks integrating with [code-server](https://github.com/coder/code-server).
+- [**Setup Coder**](https://github.com/marketplace/actions/setup-coder): An action to setup coder CLI in GitHub workflows.
 
 ### Community
 
 - [**Provision Coder with Terraform**](https://github.com/ElliotG/coder-oss-tf): Provision Coder on Google GKE, Azure AKS, AWS EKS, DigitalOcean DOKS, IBMCloud K8s, OVHCloud K8s, and Scaleway K8s Kapsule with Terraform
-- [**Coder GitHub Action**](https://github.com/marketplace/actions/update-coder-template): A GitHub Action that updates Coder templates
-- [**Various Templates**](./examples/templates/community-templates.md): Hetzner Cloud, Docker in Docker, and other templates the community has built.
+- [**Coder Template GitHub Action**](https://github.com/marketplace/actions/update-coder-template): A GitHub Action that updates Coder templates
+
+## Contributing
+
+We are always happy to see new contributors to Coder. If you are new to the Coder codebase, we have
+[a guide on how to get started](https://coder.com/docs/CONTRIBUTING). We'd love to see your
+contributions!
+
+## Hiring
+
+Apply [here](https://jobs.ashbyhq.com/coder?utm_source=github&utm_medium=readme&utm_campaign=unknown) if you're interested in joining our team.

agent/agentexec/cli_linux.go

@@ -0,0 +1,145 @@
+//go:build linux
+// +build linux
+
+package agentexec
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"os/exec"
+	"runtime"
+	"strconv"
+	"strings"
+	"syscall"
+
+	"golang.org/x/sys/unix"
+	"golang.org/x/xerrors"
+)
+
+// unset is set to an invalid value for nice and oom scores.
+const unset = -2000
+
+// CLI runs the agent-exec command. It should only be called by the cli package.
+func CLI() error {
+	// We lock the OS thread here to avoid a race condition where the nice priority
+	// we get is on a different thread from the one we set it on.
+	runtime.LockOSThread()
+	// Nop on success but we do it anyway in case of an error.
+	defer runtime.UnlockOSThread()
+
+	var (
+		fs   = flag.NewFlagSet("agent-exec", flag.ExitOnError)
+		nice = fs.Int("coder-nice", unset, "")
+		oom  = fs.Int("coder-oom", unset, "")
+	)
+
+	if len(os.Args) < 3 {
+		return xerrors.Errorf("malformed command %+v", os.Args)
+	}
+
+	// Parse everything after "coder agent-exec".
+	err := fs.Parse(os.Args[2:])
+	if err != nil {
+		return xerrors.Errorf("parse flags: %w", err)
+	}
+
+	// Get everything after "coder agent-exec --"
+	args := execArgs(os.Args)
+	if len(args) == 0 {
+		return xerrors.Errorf("no exec command provided %+v", os.Args)
+	}
+
+	if *nice == unset {
+		// If an explicit nice score isn't set, we use the default.
+		*nice, err = defaultNiceScore()
+		if err != nil {
+			return xerrors.Errorf("get default nice score: %w", err)
+		}
+	}
+
+	if *oom == unset {
+		// If an explicit oom score isn't set, we use the default.
+		*oom, err = defaultOOMScore()
+		if err != nil {
+			return xerrors.Errorf("get default oom score: %w", err)
+		}
+	}
+
+	err = unix.Setpriority(unix.PRIO_PROCESS, 0, *nice)
+	if err != nil {
+		return xerrors.Errorf("set nice score: %w", err)
+	}
+
+	err = writeOOMScoreAdj(*oom)
+	if err != nil {
+		return xerrors.Errorf("set oom score: %w", err)
+	}
+
+	path, err := exec.LookPath(args[0])
+	if err != nil {
+		return xerrors.Errorf("look path: %w", err)
+	}
+
+	return syscall.Exec(path, args, os.Environ())
+}
+
+func defaultNiceScore() (int, error) {
+	score, err := unix.Getpriority(unix.PRIO_PROCESS, 0)
+	if err != nil {
+		return 0, xerrors.Errorf("get nice score: %w", err)
+	}
+	// See https://linux.die.net/man/2/setpriority#Notes
+	score = 20 - score
+
+	score += 5
+	if score > 19 {
+		return 19, nil
+	}
+	return score, nil
+}
+
+func defaultOOMScore() (int, error) {
+	score, err := oomScoreAdj()
+	if err != nil {
+		return 0, xerrors.Errorf("get oom score: %w", err)
+	}
+
+	// If the agent has a negative oom_score_adj, we set the child to 0
+	// so it's treated like every other process.
+	if score < 0 {
+		return 0, nil
+	}
+
+	// If the agent is already almost at the maximum then set it to the max.
+	if score >= 998 {
+		return 1000, nil
+	}
+
+	// If the agent oom_score_adj is >=0, we set the child to slightly
+	// less than the maximum. If users want a different score they set it
+	// directly.
+	return 998, nil
+}
+
+func oomScoreAdj() (int, error) {
+	scoreStr, err := os.ReadFile("/proc/self/oom_score_adj")
+	if err != nil {
+		return 0, xerrors.Errorf("read oom_score_adj: %w", err)
+	}
+	return strconv.Atoi(strings.TrimSpace(string(scoreStr)))
+}
+
+func writeOOMScoreAdj(score int) error {
+	return os.WriteFile("/proc/self/oom_score_adj", []byte(fmt.Sprintf("%d", score)), 0o600)
+}
+
+// execArgs returns the arguments to pass to syscall.Exec after the "--" delimiter.
+func execArgs(args []string) []string {
+	for i, arg := range args {
+		if arg == "--" {
+			return args[i+1:]
+		}
+	}
+	return nil
+}

agent/agentexec/cli_linux_test.go

@@ -0,0 +1,178 @@
+//go:build linux
+// +build linux
+
+package agentexec_test
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/unix"
+
+	"github.com/coder/coder/v2/testutil"
+)
+
+func TestCLI(t *testing.T) {
+	t.Parallel()
+
+	t.Run("OK", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := testutil.Context(t, testutil.WaitMedium)
+		cmd, path := cmd(ctx, t, 123, 12)
+		err := cmd.Start()
+		require.NoError(t, err)
+		go cmd.Wait()
+
+		waitForSentinel(ctx, t, cmd, path)
+		requireOOMScore(t, cmd.Process.Pid, 123)
+		requireNiceScore(t, cmd.Process.Pid, 12)
+	})
+
+	t.Run("Defaults", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := testutil.Context(t, testutil.WaitMedium)
+		cmd, path := cmd(ctx, t, 0, 0)
+		err := cmd.Start()
+		require.NoError(t, err)
+		go cmd.Wait()
+
+		waitForSentinel(ctx, t, cmd, path)
+
+		expectedNice := expectedNiceScore(t)
+		expectedOOM := expectedOOMScore(t)
+		requireOOMScore(t, cmd.Process.Pid, expectedOOM)
+		requireNiceScore(t, cmd.Process.Pid, expectedNice)
+	})
+}
+
+func requireNiceScore(t *testing.T, pid int, score int) {
+	t.Helper()
+
+	nice, err := unix.Getpriority(unix.PRIO_PROCESS, pid)
+	require.NoError(t, err)
+	// See https://linux.die.net/man/2/setpriority#Notes
+	require.Equal(t, score, 20-nice)
+}
+
+func requireOOMScore(t *testing.T, pid int, expected int) {
+	t.Helper()
+
+	actual, err := os.ReadFile(fmt.Sprintf("/proc/%d/oom_score_adj", pid))
+	require.NoError(t, err)
+	score := strings.TrimSpace(string(actual))
+	require.Equal(t, strconv.Itoa(expected), score)
+}
+
+func waitForSentinel(ctx context.Context, t *testing.T, cmd *exec.Cmd, path string) {
+	t.Helper()
+
+	ticker := time.NewTicker(testutil.IntervalFast)
+	defer ticker.Stop()
+
+	// RequireEventually doesn't work well with require.NoError or similar require functions.
+	for {
+		err := cmd.Process.Signal(syscall.Signal(0))
+		require.NoError(t, err)
+
+		_, err = os.Stat(path)
+		if err == nil {
+			return
+		}
+
+		select {
+		case <-ticker.C:
+		case <-ctx.Done():
+			require.NoError(t, ctx.Err())
+		}
+	}
+}
+
+func cmd(ctx context.Context, t *testing.T, oom, nice int) (*exec.Cmd, string) {
+	var (
+		args = execArgs(oom, nice)
+		dir  = t.TempDir()
+		file = filepath.Join(dir, "sentinel")
+	)
+
+	args = append(args, "sh", "-c", fmt.Sprintf("touch %s && sleep 10m", file))
+	//nolint:gosec
+	cmd := exec.CommandContext(ctx, TestBin, args...)
+
+	// We set this so we can also easily kill the sleep process the shell spawns.
+	cmd.SysProcAttr = &syscall.SysProcAttr{
+		Setpgid: true,
+	}
+
+	cmd.Env = os.Environ()
+	var buf bytes.Buffer
+	cmd.Stdout = &buf
+	cmd.Stderr = &buf
+	t.Cleanup(func() {
+		// Print output of a command if the test fails.
+		if t.Failed() {
+			t.Logf("cmd %q output: %s", cmd.Args, buf.String())
+		}
+		if cmd.Process != nil {
+			// We use -cmd.Process.Pid to kill the whole process group.
+			_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGINT)
+		}
+	})
+	return cmd, file
+}
+
+func expectedOOMScore(t *testing.T) int {
+	t.Helper()
+
+	score, err := os.ReadFile(fmt.Sprintf("/proc/%d/oom_score_adj", os.Getpid()))
+	require.NoError(t, err)
+
+	scoreInt, err := strconv.Atoi(strings.TrimSpace(string(score)))
+	require.NoError(t, err)
+
+	if scoreInt < 0 {
+		return 0
+	}
+	if scoreInt >= 998 {
+		return 1000
+	}
+	return 998
+}
+
+func expectedNiceScore(t *testing.T) int {
+	t.Helper()
+
+	score, err := unix.Getpriority(unix.PRIO_PROCESS, os.Getpid())
+	require.NoError(t, err)
+
+	// Priority is niceness + 20.
+	score = 20 - score
+	score += 5
+	if score > 19 {
+		return 19
+	}
+	return score
+}
+
+func execArgs(oom int, nice int) []string {
+	execArgs := []string{"agent-exec"}
+	if oom != 0 {
+		execArgs = append(execArgs, fmt.Sprintf("--coder-oom=%d", oom))
+	}
+	if nice != 0 {
+		execArgs = append(execArgs, fmt.Sprintf("--coder-nice=%d", nice))
+	}
+	execArgs = append(execArgs, "--")
+	return execArgs
+}

agent/agentexec/cli_other.go

@@ -0,0 +1,10 @@
+//go:build !linux
+// +build !linux
+
+package agentexec
+
+import "golang.org/x/xerrors"
+
+func CLI() error {
+	return xerrors.New("agent-exec is only supported on Linux")
+}

agent/agentexec/cmdtest/main_linux.go

@@ -0,0 +1,19 @@
+//go:build linux
+// +build linux
+
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/coder/coder/v2/agent/agentexec"
+)
+
+func main() {
+	err := agentexec.CLI()
+	if err != nil {
+		_, _ = fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

agent/agentexec/exec.go

@@ -0,0 +1,86 @@
+package agentexec
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+
+	"golang.org/x/xerrors"
+)
+
+const (
+	// EnvProcPrioMgmt is the environment variable that determines whether
+	// we attempt to manage process CPU and OOM Killer priority.
+	EnvProcPrioMgmt  = "CODER_PROC_PRIO_MGMT"
+	EnvProcOOMScore  = "CODER_PROC_OOM_SCORE"
+	EnvProcNiceScore = "CODER_PROC_NICE_SCORE"
+)
+
+// CommandContext returns an exec.Cmd that calls "coder agent-exec" prior to exec'ing
+// the provided command if CODER_PROC_PRIO_MGMT is set, otherwise a normal exec.Cmd
+// is returned. All instances of exec.Cmd should flow through this function to ensure
+// proper resource constraints are applied to the child process.
+func CommandContext(ctx context.Context, cmd string, args ...string) (*exec.Cmd, error) {
+	_, enabled := os.LookupEnv(EnvProcPrioMgmt)
+	if runtime.GOOS != "linux" || !enabled {
+		return exec.CommandContext(ctx, cmd, args...), nil
+	}
+
+	executable, err := os.Executable()
+	if err != nil {
+		return nil, xerrors.Errorf("get executable: %w", err)
+	}
+
+	bin, err := filepath.EvalSymlinks(executable)
+	if err != nil {
+		return nil, xerrors.Errorf("eval symlinks: %w", err)
+	}
+
+	execArgs := []string{"agent-exec"}
+	if score, ok := envValInt(EnvProcOOMScore); ok {
+		execArgs = append(execArgs, oomScoreArg(score))
+	}
+
+	if score, ok := envValInt(EnvProcNiceScore); ok {
+		execArgs = append(execArgs, niceScoreArg(score))
+	}
+	execArgs = append(execArgs, "--", cmd)
+	execArgs = append(execArgs, args...)
+
+	return exec.CommandContext(ctx, bin, execArgs...), nil
+}
+
+// envValInt searches for a key in a list of environment variables and parses it to an int.
+// If the key is not found or cannot be parsed, returns 0 and false.
+func envValInt(key string) (int, bool) {
+	val, ok := os.LookupEnv(key)
+	if !ok {
+		return 0, false
+	}
+
+	i, err := strconv.Atoi(val)
+	if err != nil {
+		return 0, false
+	}
+	return i, true
+}
+
+// The following are flags used by the agent-exec command. We use flags instead of
+// environment variables to avoid having to deal with a caller overriding the
+// environment variables.
+const (
+	niceFlag = "coder-nice"
+	oomFlag  = "coder-oom"
+)
+
+func niceScoreArg(score int) string {
+	return fmt.Sprintf("--%s=%d", niceFlag, score)
+}
+
+func oomScoreArg(score int) string {
+	return fmt.Sprintf("--%s=%d", oomFlag, score)
+}

agent/agentexec/exec_test.go

@@ -0,0 +1,119 @@
+package agentexec_test
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/agent/agentexec"
+)
+
+//nolint:paralleltest // we need to test environment variables
+func TestExec(t *testing.T) {
+	//nolint:paralleltest // we need to test environment variables
+	t.Run("NonLinux", func(t *testing.T) {
+		t.Setenv(agentexec.EnvProcPrioMgmt, "true")
+
+		if runtime.GOOS == "linux" {
+			t.Skip("skipping on linux")
+		}
+
+		cmd, err := agentexec.CommandContext(context.Background(), "sh", "-c", "sleep")
+		require.NoError(t, err)
+
+		path, err := exec.LookPath("sh")
+		require.NoError(t, err)
+		require.Equal(t, path, cmd.Path)
+		require.Equal(t, []string{"sh", "-c", "sleep"}, cmd.Args)
+	})
+
+	//nolint:paralleltest // we need to test environment variables
+	t.Run("Linux", func(t *testing.T) {
+		//nolint:paralleltest // we need to test environment variables
+		t.Run("Disabled", func(t *testing.T) {
+			if runtime.GOOS != "linux" {
+				t.Skip("skipping on linux")
+			}
+
+			cmd, err := agentexec.CommandContext(context.Background(), "sh", "-c", "sleep")
+			require.NoError(t, err)
+			path, err := exec.LookPath("sh")
+			require.NoError(t, err)
+			require.Equal(t, path, cmd.Path)
+			require.Equal(t, []string{"sh", "-c", "sleep"}, cmd.Args)
+		})
+
+		//nolint:paralleltest // we need to test environment variables
+		t.Run("Enabled", func(t *testing.T) {
+			t.Setenv(agentexec.EnvProcPrioMgmt, "hello")
+
+			if runtime.GOOS != "linux" {
+				t.Skip("skipping on linux")
+			}
+
+			executable, err := os.Executable()
+			require.NoError(t, err)
+
+			cmd, err := agentexec.CommandContext(context.Background(), "sh", "-c", "sleep")
+			require.NoError(t, err)
+			require.Equal(t, executable, cmd.Path)
+			require.Equal(t, []string{executable, "agent-exec", "--", "sh", "-c", "sleep"}, cmd.Args)
+		})
+
+		t.Run("Nice", func(t *testing.T) {
+			t.Setenv(agentexec.EnvProcPrioMgmt, "hello")
+			t.Setenv(agentexec.EnvProcNiceScore, "10")
+
+			if runtime.GOOS != "linux" {
+				t.Skip("skipping on linux")
+			}
+
+			executable, err := os.Executable()
+			require.NoError(t, err)
+
+			cmd, err := agentexec.CommandContext(context.Background(), "sh", "-c", "sleep")
+			require.NoError(t, err)
+			require.Equal(t, executable, cmd.Path)
+			require.Equal(t, []string{executable, "agent-exec", "--coder-nice=10", "--", "sh", "-c", "sleep"}, cmd.Args)
+		})
+
+		t.Run("OOM", func(t *testing.T) {
+			t.Setenv(agentexec.EnvProcPrioMgmt, "hello")
+			t.Setenv(agentexec.EnvProcOOMScore, "123")
+
+			if runtime.GOOS != "linux" {
+				t.Skip("skipping on linux")
+			}
+
+			executable, err := os.Executable()
+			require.NoError(t, err)
+
+			cmd, err := agentexec.CommandContext(context.Background(), "sh", "-c", "sleep")
+			require.NoError(t, err)
+			require.Equal(t, executable, cmd.Path)
+			require.Equal(t, []string{executable, "agent-exec", "--coder-oom=123", "--", "sh", "-c", "sleep"}, cmd.Args)
+		})
+
+		t.Run("Both", func(t *testing.T) {
+			t.Setenv(agentexec.EnvProcPrioMgmt, "hello")
+			t.Setenv(agentexec.EnvProcOOMScore, "432")
+			t.Setenv(agentexec.EnvProcNiceScore, "14")
+
+			if runtime.GOOS != "linux" {
+				t.Skip("skipping on linux")
+			}
+
+			executable, err := os.Executable()
+			require.NoError(t, err)
+
+			cmd, err := agentexec.CommandContext(context.Background(), "sh", "-c", "sleep")
+			require.NoError(t, err)
+			require.Equal(t, executable, cmd.Path)
+			require.Equal(t, []string{executable, "agent-exec", "--coder-oom=432", "--coder-nice=14", "--", "sh", "-c", "sleep"}, cmd.Args)
+		})
+	})
+}

agent/agentexec/main_linux_test.go

@@ -0,0 +1,46 @@
+//go:build linux
+// +build linux
+
+package agentexec_test
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+)
+
+var TestBin string
+
+func TestMain(m *testing.M) {
+	code := func() int {
+		// We generate a unique directory per test invocation to avoid collisions between two
+		// processes attempting to create the same temp file.
+		dir := genDir()
+		defer os.RemoveAll(dir)
+		TestBin = buildBinary(dir)
+		return m.Run()
+	}()
+
+	os.Exit(code)
+}
+
+func buildBinary(dir string) string {
+	path := filepath.Join(dir, "agent-test")
+	out, err := exec.Command("go", "build", "-o", path, "./cmdtest").CombinedOutput()
+	mustf(err, "build binary: %s", out)
+	return path
+}
+
+func mustf(err error, msg string, args ...any) {
+	if err != nil {
+		panic(fmt.Sprintf(msg, args...))
+	}
+}
+
+func genDir() string {
+	dir, err := os.MkdirTemp(os.TempDir(), "agentexec")
+	mustf(err, "create temp dir: %v", err)
+	return dir
+}

agent/agentproc/agentproctest/proc.go

@@ -2,6 +2,7 @@ package agentproctest
 
 import (
 	"fmt"
+	"strconv"
 	"testing"
 
 	"github.com/spf13/afero"
@@ -29,8 +30,9 @@ func GenerateProcess(t *testing.T, fs afero.Fs, muts ...func(*agentproc.Process)
 	cmdline := fmt.Sprintf("%s\x00%s\x00%s", arg1, arg2, arg3)
 
 	process := agentproc.Process{
-		CmdLine: cmdline,
-		PID:     int32(pid),
+		CmdLine:     cmdline,
+		PID:         int32(pid),
+		OOMScoreAdj: 0,
 	}
 
 	for _, mut := range muts {
@@ -45,5 +47,9 @@ func GenerateProcess(t *testing.T, fs afero.Fs, muts ...func(*agentproc.Process)
 	err = afero.WriteFile(fs, fmt.Sprintf("%s/cmdline", process.Dir), []byte(process.CmdLine), 0o444)
 	require.NoError(t, err)
 
+	score := strconv.Itoa(process.OOMScoreAdj)
+	err = afero.WriteFile(fs, fmt.Sprintf("%s/oom_score_adj", process.Dir), []byte(score), 0o444)
+	require.NoError(t, err)
+
 	return process
 }

agent/agentproc/agentproctest/syscallermock.go

@@ -1,5 +1,10 @@
 // Code generated by MockGen. DO NOT EDIT.
 // Source: github.com/coder/coder/v2/agent/agentproc (interfaces: Syscaller)
+//
+// Generated by this command:
+//
+//	mockgen -destination ./syscallermock.go -package agentproctest github.com/coder/coder/v2/agent/agentproc Syscaller
+//
 
 // Package agentproctest is a generated GoMock package.
 package agentproctest
@@ -8,7 +13,7 @@ import (
 	reflect "reflect"
 	syscall "syscall"
 
-	gomock "github.com/golang/mock/gomock"
+	gomock "go.uber.org/mock/gomock"
 )
 
 // MockSyscaller is a mock of Syscaller interface.
@@ -44,7 +49,7 @@ func (m *MockSyscaller) GetPriority(arg0 int32) (int, error) {
 }
 
 // GetPriority indicates an expected call of GetPriority.
-func (mr *MockSyscallerMockRecorder) GetPriority(arg0 interface{}) *gomock.Call {
+func (mr *MockSyscallerMockRecorder) GetPriority(arg0 any) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetPriority", reflect.TypeOf((*MockSyscaller)(nil).GetPriority), arg0)
 }
@@ -58,7 +63,7 @@ func (m *MockSyscaller) Kill(arg0 int32, arg1 syscall.Signal) error {
 }
 
 // Kill indicates an expected call of Kill.
-func (mr *MockSyscallerMockRecorder) Kill(arg0, arg1 interface{}) *gomock.Call {
+func (mr *MockSyscallerMockRecorder) Kill(arg0, arg1 any) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Kill", reflect.TypeOf((*MockSyscaller)(nil).Kill), arg0, arg1)
 }
@@ -72,7 +77,7 @@ func (m *MockSyscaller) SetPriority(arg0 int32, arg1 int) error {
 }
 
 // SetPriority indicates an expected call of SetPriority.
-func (mr *MockSyscallerMockRecorder) SetPriority(arg0, arg1 interface{}) *gomock.Call {
+func (mr *MockSyscallerMockRecorder) SetPriority(arg0, arg1 any) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "SetPriority", reflect.TypeOf((*MockSyscaller)(nil).SetPriority), arg0, arg1)
 }

agent/agentproc/proc_test.go

@@ -5,9 +5,9 @@ import (
 	"syscall"
 	"testing"
 
-	"github.com/golang/mock/gomock"
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/require"
+	"go.uber.org/mock/gomock"
 	"golang.org/x/xerrors"
 
 	"github.com/coder/coder/v2/agent/agentproc"

agent/agentproc/proc_unix.go

@@ -5,6 +5,7 @@ package agentproc
 
 import (
 	"errors"
+	"os"
 	"path/filepath"
 	"strconv"
 	"strings"
@@ -44,16 +45,31 @@ func List(fs afero.Fs, syscaller Syscaller) ([]*Process, error) {
 
 		cmdline, err := afero.ReadFile(fs, filepath.Join(defaultProcDir, entry, "cmdline"))
 		if err != nil {
-			var errNo syscall.Errno
-			if xerrors.As(err, &errNo) && errNo == syscall.EPERM {
+			if isBenignError(err) {
 				continue
 			}
 			return nil, xerrors.Errorf("read cmdline: %w", err)
 		}
+
+		oomScore, err := afero.ReadFile(fs, filepath.Join(defaultProcDir, entry, "oom_score_adj"))
+		if err != nil {
+			if isBenignError(err) {
+				continue
+			}
+
+			return nil, xerrors.Errorf("read oom_score_adj: %w", err)
+		}
+
+		oom, err := strconv.Atoi(strings.TrimSpace(string(oomScore)))
+		if err != nil {
+			return nil, xerrors.Errorf("convert oom score: %w", err)
+		}
+
 		processes = append(processes, &Process{
-			PID:     int32(pid),
-			CmdLine: string(cmdline),
-			Dir:     filepath.Join(defaultProcDir, entry),
+			PID:         int32(pid),
+			CmdLine:     string(cmdline),
+			Dir:         filepath.Join(defaultProcDir, entry),
+			OOMScoreAdj: oom,
 		})
 	}
 
@@ -107,3 +123,12 @@ func (p *Process) Cmd() string {
 func (p *Process) cmdLine() []string {
 	return strings.Split(p.CmdLine, "\x00")
 }
+
+func isBenignError(err error) bool {
+	var errno syscall.Errno
+	if !xerrors.As(err, &errno) {
+		return false
+	}
+
+	return errno == syscall.ESRCH || errno == syscall.EPERM || xerrors.Is(err, os.ErrNotExist)
+}

agent/agentproc/syscaller.go

@@ -14,7 +14,8 @@ type Syscaller interface {
 const defaultProcDir = "/proc"
 
 type Process struct {
-	Dir     string
-	CmdLine string
-	PID     int32
+	Dir         string
+	CmdLine     string
+	PID         int32
+	OOMScoreAdj int
 }

agent/agentscripts/agentscripts.go

@@ -13,15 +13,19 @@ import (
 	"sync/atomic"
 	"time"
 
+	"github.com/google/uuid"
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/robfig/cron/v3"
 	"github.com/spf13/afero"
 	"golang.org/x/sync/errgroup"
 	"golang.org/x/xerrors"
+	"google.golang.org/protobuf/types/known/timestamppb"
 
 	"cdr.dev/slog"
 
 	"github.com/coder/coder/v2/agent/agentssh"
+	"github.com/coder/coder/v2/agent/proto"
+	"github.com/coder/coder/v2/coderd/database/dbtime"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
 )
@@ -41,13 +45,19 @@ var (
 	parser = cron.NewParser(cron.Second | cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.DowOptional)
 )
 
+type ScriptLogger interface {
+	Send(ctx context.Context, log ...agentsdk.Log) error
+	Flush(context.Context) error
+}
+
 // Options are a set of options for the runner.
 type Options struct {
-	LogDir     string
-	Logger     slog.Logger
-	SSHServer  *agentssh.Server
-	Filesystem afero.Fs
-	PatchLogs  func(ctx context.Context, req agentsdk.PatchLogs) error
+	DataDirBase     string
+	LogDir          string
+	Logger          slog.Logger
+	SSHServer       *agentssh.Server
+	Filesystem      afero.Fs
+	GetScriptLogger func(logSourceID uuid.UUID) ScriptLogger
 }
 
 // New creates a runner for the provided scripts.
@@ -59,6 +69,7 @@ func New(opts Options) *Runner {
 		cronCtxCancel: cronCtxCancel,
 		cron:          cron.New(cron.WithParser(parser)),
 		closed:        make(chan struct{}),
+		dataDir:       filepath.Join(opts.DataDirBase, "coder-script-data"),
 		scriptsExecuted: prometheus.NewCounterVec(prometheus.CounterOpts{
 			Namespace: "agent",
 			Subsystem: "scripts",
@@ -67,17 +78,21 @@ func New(opts Options) *Runner {
 	}
 }
 
+type ScriptCompletedFunc func(context.Context, *proto.WorkspaceAgentScriptCompletedRequest) (*proto.WorkspaceAgentScriptCompletedResponse, error)
+
 type Runner struct {
 	Options
 
-	cronCtx       context.Context
-	cronCtxCancel context.CancelFunc
-	cmdCloseWait  sync.WaitGroup
-	closed        chan struct{}
-	closeMutex    sync.Mutex
-	cron          *cron.Cron
-	initialized   atomic.Bool
-	scripts       []codersdk.WorkspaceAgentScript
+	cronCtx         context.Context
+	cronCtxCancel   context.CancelFunc
+	cmdCloseWait    sync.WaitGroup
+	closed          chan struct{}
+	closeMutex      sync.Mutex
+	cron            *cron.Cron
+	initialized     atomic.Bool
+	scripts         []codersdk.WorkspaceAgentScript
+	dataDir         string
+	scriptCompleted ScriptCompletedFunc
 
 	// scriptsExecuted includes all scripts executed by the workspace agent. Agents
 	// execute startup scripts, and scripts on a cron schedule. Both will increment
@@ -85,6 +100,17 @@ type Runner struct {
 	scriptsExecuted *prometheus.CounterVec
 }
 
+// DataDir returns the directory where scripts data is stored.
+func (r *Runner) DataDir() string {
+	return r.dataDir
+}
+
+// ScriptBinDir returns the directory where scripts can store executable
+// binaries.
+func (r *Runner) ScriptBinDir() string {
+	return filepath.Join(r.dataDir, "bin")
+}
+
 func (r *Runner) RegisterMetrics(reg prometheus.Registerer) {
 	if reg == nil {
 		// If no registry, do nothing.
@@ -96,21 +122,27 @@ func (r *Runner) RegisterMetrics(reg prometheus.Registerer) {
 // Init initializes the runner with the provided scripts.
 // It also schedules any scripts that have a schedule.
 // This function must be called before Execute.
-func (r *Runner) Init(scripts []codersdk.WorkspaceAgentScript) error {
+func (r *Runner) Init(scripts []codersdk.WorkspaceAgentScript, scriptCompleted ScriptCompletedFunc) error {
 	if r.initialized.Load() {
 		return xerrors.New("init: already initialized")
 	}
 	r.initialized.Store(true)
 	r.scripts = scripts
+	r.scriptCompleted = scriptCompleted
 	r.Logger.Info(r.cronCtx, "initializing agent scripts", slog.F("script_count", len(scripts)), slog.F("log_dir", r.LogDir))
 
+	err := r.Filesystem.MkdirAll(r.ScriptBinDir(), 0o700)
+	if err != nil {
+		return xerrors.Errorf("create script bin dir: %w", err)
+	}
+
 	for _, script := range scripts {
 		if script.Cron == "" {
 			continue
 		}
 		script := script
 		_, err := r.cron.AddFunc(script.Cron, func() {
-			err := r.trackRun(r.cronCtx, script)
+			err := r.trackRun(r.cronCtx, script, ExecuteCronScripts)
 			if err != nil {
 				r.Logger.Warn(context.Background(), "run agent script on schedule", slog.Error(err))
 			}
@@ -129,29 +161,51 @@ func (r *Runner) StartCron() {
 	// has exited by the time the `cron.Stop()` context returns, so we need to
 	// track it manually.
 	err := r.trackCommandGoroutine(func() {
-		r.cron.Run()
+		// Since this is run async, in quick unit tests, it is possible the
+		// Close() function gets called before we even start the cron.
+		// In these cases, the Run() will never end.
+		// So if we are closed, we just return, and skip the Run() entirely.
+		select {
+		case <-r.cronCtx.Done():
+			// The cronCtx is canceled before cron.Close() happens. So if the ctx is
+			// canceled, then Close() will be called, or it is about to be called.
+			// So do nothing!
+		default:
+			r.cron.Run()
+		}
 	})
 	if err != nil {
 		r.Logger.Warn(context.Background(), "start cron failed", slog.Error(err))
 	}
 }
 
+// ExecuteOption describes what scripts we want to execute.
+type ExecuteOption int
+
+// ExecuteOption enums.
+const (
+	ExecuteAllScripts ExecuteOption = iota
+	ExecuteStartScripts
+	ExecuteStopScripts
+	ExecuteCronScripts
+)
+
 // Execute runs a set of scripts according to a filter.
-func (r *Runner) Execute(ctx context.Context, filter func(script codersdk.WorkspaceAgentScript) bool) error {
-	if filter == nil {
-		// Execute em' all!
-		filter = func(script codersdk.WorkspaceAgentScript) bool {
-			return true
-		}
-	}
+func (r *Runner) Execute(ctx context.Context, option ExecuteOption) error {
 	var eg errgroup.Group
 	for _, script := range r.scripts {
-		if !filter(script) {
+		runScript := (option == ExecuteStartScripts && script.RunOnStart) ||
+			(option == ExecuteStopScripts && script.RunOnStop) ||
+			(option == ExecuteCronScripts && script.Cron != "") ||
+			option == ExecuteAllScripts
+
+		if !runScript {
 			continue
 		}
+
 		script := script
 		eg.Go(func() error {
-			err := r.trackRun(ctx, script)
+			err := r.trackRun(ctx, script, option)
 			if err != nil {
 				return xerrors.Errorf("run agent script %q: %w", script.LogSourceID, err)
 			}
@@ -162,8 +216,8 @@ func (r *Runner) Execute(ctx context.Context, filter func(script codersdk.Worksp
 }
 
 // trackRun wraps "run" with metrics.
-func (r *Runner) trackRun(ctx context.Context, script codersdk.WorkspaceAgentScript) error {
-	err := r.run(ctx, script)
+func (r *Runner) trackRun(ctx context.Context, script codersdk.WorkspaceAgentScript, option ExecuteOption) error {
+	err := r.run(ctx, script, option)
 	if err != nil {
 		r.scriptsExecuted.WithLabelValues("false").Add(1)
 	} else {
@@ -176,7 +230,7 @@ func (r *Runner) trackRun(ctx context.Context, script codersdk.WorkspaceAgentScr
 // If the timeout is exceeded, the process is sent an interrupt signal.
 // If the process does not exit after a few seconds, it is forcefully killed.
 // This function immediately returns after a timeout, and does not wait for the process to exit.
-func (r *Runner) run(ctx context.Context, script codersdk.WorkspaceAgentScript) error {
+func (r *Runner) run(ctx context.Context, script codersdk.WorkspaceAgentScript, option ExecuteOption) error {
 	logPath := script.LogPath
 	if logPath == "" {
 		logPath = fmt.Sprintf("coder-script-%s.log", script.LogSourceID)
@@ -197,7 +251,18 @@ func (r *Runner) run(ctx context.Context, script codersdk.WorkspaceAgentScript)
 	if !filepath.IsAbs(logPath) {
 		logPath = filepath.Join(r.LogDir, logPath)
 	}
-	logger := r.Logger.With(slog.F("log_path", logPath))
+
+	scriptDataDir := filepath.Join(r.DataDir(), script.LogSourceID.String())
+	err := r.Filesystem.MkdirAll(scriptDataDir, 0o700)
+	if err != nil {
+		return xerrors.Errorf("%s script: create script temp dir: %w", scriptDataDir, err)
+	}
+
+	logger := r.Logger.With(
+		slog.F("log_source_id", script.LogSourceID),
+		slog.F("log_path", logPath),
+		slog.F("script_data_dir", scriptDataDir),
+	)
 	logger.Info(ctx, "running agent script", slog.F("script", script.Script))
 
 	fileWriter, err := r.Filesystem.OpenFile(logPath, os.O_CREATE|os.O_RDWR, 0o600)
@@ -227,27 +292,34 @@ func (r *Runner) run(ctx context.Context, script codersdk.WorkspaceAgentScript)
 	cmd.WaitDelay = 10 * time.Second
 	cmd.Cancel = cmdCancel(cmd)
 
-	send, flushAndClose := agentsdk.LogsSender(script.LogSourceID, r.PatchLogs, logger)
+	// Expose env vars that can be used in the script for storing data
+	// and binaries. In the future, we may want to expose more env vars
+	// for the script to use, like CODER_SCRIPT_DATA_DIR for persistent
+	// storage.
+	cmd.Env = append(cmd.Env, "CODER_SCRIPT_DATA_DIR="+scriptDataDir)
+	cmd.Env = append(cmd.Env, "CODER_SCRIPT_BIN_DIR="+r.ScriptBinDir())
+
+	scriptLogger := r.GetScriptLogger(script.LogSourceID)
 	// If ctx is canceled here (or in a writer below), we may be
 	// discarding logs, but that's okay because we're shutting down
 	// anyway. We could consider creating a new context here if we
 	// want better control over flush during shutdown.
 	defer func() {
-		if err := flushAndClose(ctx); err != nil {
+		if err := scriptLogger.Flush(ctx); err != nil {
 			logger.Warn(ctx, "flush startup logs failed", slog.Error(err))
 		}
 	}()
 
-	infoW := agentsdk.LogsWriter(ctx, send, script.LogSourceID, codersdk.LogLevelInfo)
+	infoW := agentsdk.LogsWriter(ctx, scriptLogger.Send, script.LogSourceID, codersdk.LogLevelInfo)
 	defer infoW.Close()
-	errW := agentsdk.LogsWriter(ctx, send, script.LogSourceID, codersdk.LogLevelError)
+	errW := agentsdk.LogsWriter(ctx, scriptLogger.Send, script.LogSourceID, codersdk.LogLevelError)
 	defer errW.Close()
 	cmd.Stdout = io.MultiWriter(fileWriter, infoW)
 	cmd.Stderr = io.MultiWriter(fileWriter, errW)
 
-	start := time.Now()
+	start := dbtime.Now()
 	defer func() {
-		end := time.Now()
+		end := dbtime.Now()
 		execTime := end.Sub(start)
 		exitCode := 0
 		if err != nil {
@@ -260,6 +332,60 @@ func (r *Runner) run(ctx context.Context, script codersdk.WorkspaceAgentScript)
 		} else {
 			logger.Info(ctx, fmt.Sprintf("%s script completed", logPath), slog.F("execution_time", execTime), slog.F("exit_code", exitCode))
 		}
+
+		if r.scriptCompleted == nil {
+			logger.Debug(ctx, "r.scriptCompleted unexpectedly nil")
+			return
+		}
+
+		// We want to check this outside of the goroutine to avoid a race condition
+		timedOut := errors.Is(err, ErrTimeout)
+		pipesLeftOpen := errors.Is(err, ErrOutputPipesOpen)
+
+		err = r.trackCommandGoroutine(func() {
+			var stage proto.Timing_Stage
+			switch option {
+			case ExecuteStartScripts:
+				stage = proto.Timing_START
+			case ExecuteStopScripts:
+				stage = proto.Timing_STOP
+			case ExecuteCronScripts:
+				stage = proto.Timing_CRON
+			}
+
+			var status proto.Timing_Status
+			switch {
+			case timedOut:
+				status = proto.Timing_TIMED_OUT
+			case pipesLeftOpen:
+				status = proto.Timing_PIPES_LEFT_OPEN
+			case exitCode != 0:
+				status = proto.Timing_EXIT_FAILURE
+			default:
+				status = proto.Timing_OK
+			}
+
+			reportTimeout := 30 * time.Second
+			reportCtx, cancel := context.WithTimeout(context.Background(), reportTimeout)
+			defer cancel()
+
+			_, err := r.scriptCompleted(reportCtx, &proto.WorkspaceAgentScriptCompletedRequest{
+				Timing: &proto.Timing{
+					ScriptId: script.ID[:],
+					Start:    timestamppb.New(start),
+					End:      timestamppb.New(end),
+					ExitCode: int32(exitCode),
+					Stage:    stage,
+					Status:   status,
+				},
+			})
+			if err != nil {
+				logger.Error(ctx, fmt.Sprintf("reporting script completed: %s", err.Error()))
+			}
+		})
+		if err != nil {
+			logger.Error(ctx, fmt.Sprintf("reporting script completed: track command goroutine: %s", err.Error()))
+		}
 	}()
 
 	err = cmd.Start()
@@ -295,7 +421,7 @@ func (r *Runner) run(ctx context.Context, script codersdk.WorkspaceAgentScript)
 			"This usually means a child process was started with references to stdout or stderr. As a result, this " +
 				"process may now have been terminated. Consider redirecting the output or using a separate " +
 				"\"coder_script\" for the process, see " +
-				"https://coder.com/docs/v2/latest/templates/troubleshooting#startup-script-issues for more information.",
+				"https://coder.com/docs/templates/troubleshooting#startup-script-issues for more information.",
 		)
 		// Inform the user by propagating the message via log writers.
 		_, _ = fmt.Fprintf(cmd.Stderr, "WARNING: %s. %s\n", message, details)
@@ -315,6 +441,7 @@ func (r *Runner) Close() error {
 		return nil
 	}
 	close(r.closed)
+	// Must cancel the cron ctx BEFORE stopping the cron.
 	r.cronCtxCancel()
 	<-r.cron.Stop().Done()
 	r.cmdCloseWait.Wait()

agent/agentscripts/agentscripts_test.go

@@ -2,20 +2,24 @@ package agentscripts_test
 
 import (
 	"context"
+	"path/filepath"
+	"runtime"
 	"testing"
 	"time"
 
+	"github.com/google/uuid"
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"go.uber.org/atomic"
 	"go.uber.org/goleak"
 
-	"cdr.dev/slog/sloggers/slogtest"
 	"github.com/coder/coder/v2/agent/agentscripts"
 	"github.com/coder/coder/v2/agent/agentssh"
+	"github.com/coder/coder/v2/agent/agenttest"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
+	"github.com/coder/coder/v2/testutil"
 )
 
 func TestMain(m *testing.M) {
@@ -24,57 +28,183 @@ func TestMain(m *testing.M) {
 
 func TestExecuteBasic(t *testing.T) {
 	t.Parallel()
-	logs := make(chan agentsdk.PatchLogs, 1)
-	runner := setup(t, func(ctx context.Context, req agentsdk.PatchLogs) error {
-		logs <- req
-		return nil
+	ctx := testutil.Context(t, testutil.WaitShort)
+	fLogger := newFakeScriptLogger()
+	runner := setup(t, func(uuid2 uuid.UUID) agentscripts.ScriptLogger {
+		return fLogger
 	})
 	defer runner.Close()
+	aAPI := agenttest.NewFakeAgentAPI(t, testutil.Logger(t), nil, nil)
 	err := runner.Init([]codersdk.WorkspaceAgentScript{{
-		Script: "echo hello",
-	}})
+		LogSourceID: uuid.New(),
+		Script:      "echo hello",
+	}}, aAPI.ScriptCompleted)
 	require.NoError(t, err)
-	require.NoError(t, runner.Execute(context.Background(), func(script codersdk.WorkspaceAgentScript) bool {
-		return true
-	}))
-	log := <-logs
-	require.Equal(t, "hello", log.Logs[0].Output)
+	require.NoError(t, runner.Execute(context.Background(), agentscripts.ExecuteAllScripts))
+	log := testutil.RequireRecvCtx(ctx, t, fLogger.logs)
+	require.Equal(t, "hello", log.Output)
+}
+
+func TestEnv(t *testing.T) {
+	t.Parallel()
+	fLogger := newFakeScriptLogger()
+	runner := setup(t, func(uuid2 uuid.UUID) agentscripts.ScriptLogger {
+		return fLogger
+	})
+	defer runner.Close()
+	id := uuid.New()
+	script := "echo $CODER_SCRIPT_DATA_DIR\necho $CODER_SCRIPT_BIN_DIR\n"
+	if runtime.GOOS == "windows" {
+		script = `
+			cmd.exe /c echo %CODER_SCRIPT_DATA_DIR%
+			cmd.exe /c echo %CODER_SCRIPT_BIN_DIR%
+		`
+	}
+	aAPI := agenttest.NewFakeAgentAPI(t, testutil.Logger(t), nil, nil)
+	err := runner.Init([]codersdk.WorkspaceAgentScript{{
+		LogSourceID: id,
+		Script:      script,
+	}}, aAPI.ScriptCompleted)
+	require.NoError(t, err)
+
+	ctx := testutil.Context(t, testutil.WaitLong)
+
+	done := testutil.Go(t, func() {
+		err := runner.Execute(ctx, agentscripts.ExecuteAllScripts)
+		assert.NoError(t, err)
+	})
+	defer func() {
+		select {
+		case <-ctx.Done():
+		case <-done:
+		}
+	}()
+
+	var log []agentsdk.Log
+	for {
+		select {
+		case <-ctx.Done():
+			require.Fail(t, "timed out waiting for logs")
+		case l := <-fLogger.logs:
+			t.Logf("log: %s", l.Output)
+			log = append(log, l)
+		}
+		if len(log) >= 2 {
+			break
+		}
+	}
+	require.Contains(t, log[0].Output, filepath.Join(runner.DataDir(), id.String()))
+	require.Contains(t, log[1].Output, runner.ScriptBinDir())
 }
 
 func TestTimeout(t *testing.T) {
 	t.Parallel()
 	runner := setup(t, nil)
 	defer runner.Close()
+	aAPI := agenttest.NewFakeAgentAPI(t, testutil.Logger(t), nil, nil)
 	err := runner.Init([]codersdk.WorkspaceAgentScript{{
-		Script:  "sleep infinity",
-		Timeout: time.Millisecond,
-	}})
+		LogSourceID: uuid.New(),
+		Script:      "sleep infinity",
+		Timeout:     time.Millisecond,
+	}}, aAPI.ScriptCompleted)
 	require.NoError(t, err)
-	require.ErrorIs(t, runner.Execute(context.Background(), nil), agentscripts.ErrTimeout)
+	require.ErrorIs(t, runner.Execute(context.Background(), agentscripts.ExecuteAllScripts), agentscripts.ErrTimeout)
 }
 
-func setup(t *testing.T, patchLogs func(ctx context.Context, req agentsdk.PatchLogs) error) *agentscripts.Runner {
+func TestScriptReportsTiming(t *testing.T) {
+	t.Parallel()
+
+	ctx := testutil.Context(t, testutil.WaitShort)
+	fLogger := newFakeScriptLogger()
+	runner := setup(t, func(uuid2 uuid.UUID) agentscripts.ScriptLogger {
+		return fLogger
+	})
+
+	aAPI := agenttest.NewFakeAgentAPI(t, testutil.Logger(t), nil, nil)
+	err := runner.Init([]codersdk.WorkspaceAgentScript{{
+		DisplayName: "say-hello",
+		LogSourceID: uuid.New(),
+		Script:      "echo hello",
+	}}, aAPI.ScriptCompleted)
+	require.NoError(t, err)
+	require.NoError(t, runner.Execute(ctx, agentscripts.ExecuteAllScripts))
+	runner.Close()
+
+	log := testutil.RequireRecvCtx(ctx, t, fLogger.logs)
+	require.Equal(t, "hello", log.Output)
+
+	timings := aAPI.GetTimings()
+	require.Equal(t, 1, len(timings))
+
+	timing := timings[0]
+	require.Equal(t, int32(0), timing.ExitCode)
+	require.GreaterOrEqual(t, timing.End.AsTime(), timing.Start.AsTime())
+}
+
+// TestCronClose exists because cron.Run() can happen after cron.Close().
+// If this happens, there used to be a deadlock.
+func TestCronClose(t *testing.T) {
+	t.Parallel()
+	runner := agentscripts.New(agentscripts.Options{})
+	runner.StartCron()
+	require.NoError(t, runner.Close(), "close runner")
+}
+
+func setup(t *testing.T, getScriptLogger func(logSourceID uuid.UUID) agentscripts.ScriptLogger) *agentscripts.Runner {
 	t.Helper()
-	if patchLogs == nil {
+	if getScriptLogger == nil {
 		// noop
-		patchLogs = func(ctx context.Context, req agentsdk.PatchLogs) error {
-			return nil
+		getScriptLogger = func(uuid uuid.UUID) agentscripts.ScriptLogger {
+			return noopScriptLogger{}
 		}
 	}
 	fs := afero.NewMemMapFs()
-	logger := slogtest.Make(t, nil)
-	s, err := agentssh.NewServer(context.Background(), logger, prometheus.NewRegistry(), fs, 0, "")
+	logger := testutil.Logger(t)
+	s, err := agentssh.NewServer(context.Background(), logger, prometheus.NewRegistry(), fs, nil)
 	require.NoError(t, err)
-	s.AgentToken = func() string { return "" }
-	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
 	t.Cleanup(func() {
 		_ = s.Close()
 	})
 	return agentscripts.New(agentscripts.Options{
-		LogDir:     t.TempDir(),
-		Logger:     logger,
-		SSHServer:  s,
-		Filesystem: fs,
-		PatchLogs:  patchLogs,
+		LogDir:          t.TempDir(),
+		DataDirBase:     t.TempDir(),
+		Logger:          logger,
+		SSHServer:       s,
+		Filesystem:      fs,
+		GetScriptLogger: getScriptLogger,
 	})
 }
+
+type noopScriptLogger struct{}
+
+func (noopScriptLogger) Send(context.Context, ...agentsdk.Log) error {
+	return nil
+}
+
+func (noopScriptLogger) Flush(context.Context) error {
+	return nil
+}
+
+type fakeScriptLogger struct {
+	logs chan agentsdk.Log
+}
+
+func (f *fakeScriptLogger) Send(ctx context.Context, logs ...agentsdk.Log) error {
+	for _, log := range logs {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case f.logs <- log:
+			// OK!
+		}
+	}
+	return nil
+}
+
+func (*fakeScriptLogger) Flush(context.Context) error {
+	return nil
+}
+
+func newFakeScriptLogger() *fakeScriptLogger {
+	return &fakeScriptLogger{make(chan agentsdk.Log, 100)}
+}

agent/agentssh/agentssh.go

@@ -32,7 +32,6 @@ import (
 
 	"github.com/coder/coder/v2/agent/usershell"
 	"github.com/coder/coder/v2/codersdk"
-	"github.com/coder/coder/v2/codersdk/agentsdk"
 	"github.com/coder/coder/v2/pty"
 )
 
@@ -53,8 +52,40 @@ const (
 	// MagicProcessCmdlineJetBrains is a string in a process's command line that
 	// uniquely identifies it as JetBrains software.
 	MagicProcessCmdlineJetBrains = "idea.vendor.name=JetBrains"
+
+	// BlockedFileTransferErrorCode indicates that SSH server restricted the raw command from performing
+	// the file transfer.
+	BlockedFileTransferErrorCode    = 65 // Error code: host not allowed to connect
+	BlockedFileTransferErrorMessage = "File transfer has been disabled."
 )
 
+// BlockedFileTransferCommands contains a list of restricted file transfer commands.
+var BlockedFileTransferCommands = []string{"nc", "rsync", "scp", "sftp"}
+
+// Config sets configuration parameters for the agent SSH server.
+type Config struct {
+	// MaxTimeout sets the absolute connection timeout, none if empty. If set to
+	// 3 seconds or more, keep alive will be used instead.
+	MaxTimeout time.Duration
+	// MOTDFile returns the path to the message of the day file. If set, the
+	// file will be displayed to the user upon login.
+	MOTDFile func() string
+	// ServiceBanner returns the configuration for the Coder service banner.
+	AnnouncementBanners func() *[]codersdk.BannerConfig
+	// UpdateEnv updates the environment variables for the command to be
+	// executed. It can be used to add, modify or replace environment variables.
+	UpdateEnv func(current []string) (updated []string, err error)
+	// WorkingDirectory sets the working directory for commands and defines
+	// where users will land when they connect via SSH. Default is the home
+	// directory of the user.
+	WorkingDirectory func() string
+	// X11DisplayOffset is the offset to add to the X11 display number.
+	// Default is 10.
+	X11DisplayOffset *int
+	// BlockFileTransfer restricts use of file transfer applications.
+	BlockFileTransfer bool
+}
+
 type Server struct {
 	mu        sync.RWMutex // Protects following.
 	fs        afero.Fs
@@ -66,14 +97,10 @@ type Server struct {
 	// a lock on mu but protected by closing.
 	wg sync.WaitGroup
 
-	logger       slog.Logger
-	srv          *ssh.Server
-	x11SocketDir string
+	logger slog.Logger
+	srv    *ssh.Server
 
-	Env           map[string]string
-	AgentToken    func() string
-	Manifest      *atomic.Pointer[agentsdk.Manifest]
-	ServiceBanner *atomic.Pointer[codersdk.ServiceBannerConfig]
+	config *Config
 
 	connCountVSCode     atomic.Int64
 	connCountJetBrains  atomic.Int64
@@ -82,7 +109,7 @@ type Server struct {
 	metrics *sshServerMetrics
 }
 
-func NewServer(ctx context.Context, logger slog.Logger, prometheusRegistry *prometheus.Registry, fs afero.Fs, maxTimeout time.Duration, x11SocketDir string) (*Server, error) {
+func NewServer(ctx context.Context, logger slog.Logger, prometheusRegistry *prometheus.Registry, fs afero.Fs, config *Config) (*Server, error) {
 	// Clients' should ignore the host key when connecting.
 	// The agent needs to authenticate with coderd to SSH,
 	// so SSH authentication doesn't improve security.
@@ -94,21 +121,44 @@ func NewServer(ctx context.Context, logger slog.Logger, prometheusRegistry *prom
 	if err != nil {
 		return nil, err
 	}
-	if x11SocketDir == "" {
-		x11SocketDir = filepath.Join(os.TempDir(), ".X11-unix")
+	if config == nil {
+		config = &Config{}
+	}
+	if config.X11DisplayOffset == nil {
+		offset := X11DefaultDisplayOffset
+		config.X11DisplayOffset = &offset
+	}
+	if config.UpdateEnv == nil {
+		config.UpdateEnv = func(current []string) ([]string, error) { return current, nil }
+	}
+	if config.MOTDFile == nil {
+		config.MOTDFile = func() string { return "" }
+	}
+	if config.AnnouncementBanners == nil {
+		config.AnnouncementBanners = func() *[]codersdk.BannerConfig { return &[]codersdk.BannerConfig{} }
+	}
+	if config.WorkingDirectory == nil {
+		config.WorkingDirectory = func() string {
+			home, err := userHomeDir()
+			if err != nil {
+				return ""
+			}
+			return home
+		}
 	}
 
 	forwardHandler := &ssh.ForwardedTCPHandler{}
-	unixForwardHandler := &forwardedUnixHandler{log: logger}
+	unixForwardHandler := newForwardedUnixHandler(logger)
 
 	metrics := newSSHServerMetrics(prometheusRegistry)
 	s := &Server{
-		listeners:    make(map[net.Listener]struct{}),
-		fs:           fs,
-		conns:        make(map[net.Conn]struct{}),
-		sessions:     make(map[ssh.Session]struct{}),
-		logger:       logger,
-		x11SocketDir: x11SocketDir,
+		listeners: make(map[net.Listener]struct{}),
+		fs:        fs,
+		conns:     make(map[net.Conn]struct{}),
+		sessions:  make(map[ssh.Session]struct{}),
+		logger:    logger,
+
+		config: config,
 
 		metrics: metrics,
 	}
@@ -172,14 +222,16 @@ func NewServer(ctx context.Context, logger slog.Logger, prometheusRegistry *prom
 		},
 	}
 
-	// The MaxTimeout functionality has been substituted with the introduction of the KeepAlive feature.
-	// In cases where very short timeouts are set, the SSH server will automatically switch to the connection timeout for both read and write operations.
-	if maxTimeout >= 3*time.Second {
+	// The MaxTimeout functionality has been substituted with the introduction
+	// of the KeepAlive feature. In cases where very short timeouts are set, the
+	// SSH server will automatically switch to the connection timeout for both
+	// read and write operations.
+	if config.MaxTimeout >= 3*time.Second {
 		srv.ClientAliveCountMax = 3
-		srv.ClientAliveInterval = maxTimeout / time.Duration(srv.ClientAliveCountMax)
+		srv.ClientAliveInterval = config.MaxTimeout / time.Duration(srv.ClientAliveCountMax)
 		srv.MaxTimeout = 0
 	} else {
-		srv.MaxTimeout = maxTimeout
+		srv.MaxTimeout = config.MaxTimeout
 	}
 
 	s.srv = srv
@@ -222,13 +274,25 @@ func (s *Server) sessionHandler(session ssh.Session) {
 	extraEnv := make([]string, 0)
 	x11, hasX11 := session.X11()
 	if hasX11 {
-		handled := s.x11Handler(session.Context(), x11)
+		display, handled := s.x11Handler(session.Context(), x11)
 		if !handled {
 			_ = session.Exit(1)
 			logger.Error(ctx, "x11 handler failed")
 			return
 		}
-		extraEnv = append(extraEnv, fmt.Sprintf("DISPLAY=:%d.0", x11.ScreenNumber))
+		extraEnv = append(extraEnv, fmt.Sprintf("DISPLAY=localhost:%d.%d", display, x11.ScreenNumber))
+	}
+
+	if s.fileTransferBlocked(session) {
+		s.logger.Warn(ctx, "file transfer blocked", slog.F("session_subsystem", session.Subsystem()), slog.F("raw_command", session.RawCommand()))
+
+		if session.Subsystem() == "" { // sftp does not expect error, otherwise it fails with "package too long"
+			// Response format: <status_code><message body>\n
+			errorMessage := fmt.Sprintf("\x02%s\n", BlockedFileTransferErrorMessage)
+			_, _ = session.Write([]byte(errorMessage))
+		}
+		_ = session.Exit(BlockedFileTransferErrorCode)
+		return
 	}
 
 	switch ss := session.Subsystem(); ss {
@@ -281,6 +345,37 @@ func (s *Server) sessionHandler(session ssh.Session) {
 	_ = session.Exit(0)
 }
 
+// fileTransferBlocked method checks if the file transfer commands should be blocked.
+//
+// Warning: consider this mechanism as "Do not trespass" sign, as a violator can still ssh to the host,
+// smuggle the `scp` binary, or just manually send files outside with `curl` or `ftp`.
+// If a user needs a more sophisticated and battle-proof solution, consider full endpoint security.
+func (s *Server) fileTransferBlocked(session ssh.Session) bool {
+	if !s.config.BlockFileTransfer {
+		return false // file transfers are permitted
+	}
+	// File transfers are restricted.
+
+	if session.Subsystem() == "sftp" {
+		return true
+	}
+
+	cmd := session.Command()
+	if len(cmd) == 0 {
+		return false // no command?
+	}
+
+	c := cmd[0]
+	c = filepath.Base(c) // in case the binary is absolute path, /usr/sbin/scp
+
+	for _, cmd := range BlockedFileTransferCommands {
+		if cmd == c {
+			return true
+		}
+	}
+	return false
+}
+
 func (s *Server) sessionStart(logger slog.Logger, session ssh.Session, extraEnv []string) (retErr error) {
 	ctx := session.Context()
 	env := append(session.Environ(), extraEnv...)
@@ -400,26 +495,24 @@ func (s *Server) startPTYSession(logger slog.Logger, session ptySession, magicTy
 	session.DisablePTYEmulation()
 
 	if isLoginShell(session.RawCommand()) {
-		serviceBanner := s.ServiceBanner.Load()
-		if serviceBanner != nil {
-			err := showServiceBanner(session, serviceBanner)
-			if err != nil {
-				logger.Error(ctx, "agent failed to show service banner", slog.Error(err))
-				s.metrics.sessionErrors.WithLabelValues(magicTypeLabel, "yes", "service_banner").Add(1)
+		banners := s.config.AnnouncementBanners()
+		if banners != nil {
+			for _, banner := range *banners {
+				err := showAnnouncementBanner(session, banner)
+				if err != nil {
+					logger.Error(ctx, "agent failed to show announcement banner", slog.Error(err))
+					s.metrics.sessionErrors.WithLabelValues(magicTypeLabel, "yes", "announcement_banner").Add(1)
+					break
+				}
 			}
 		}
 	}
 
 	if !isQuietLogin(s.fs, session.RawCommand()) {
-		manifest := s.Manifest.Load()
-		if manifest != nil {
-			err := showMOTD(s.fs, session, manifest.MOTDFile)
-			if err != nil {
-				logger.Error(ctx, "agent failed to show MOTD", slog.Error(err))
-				s.metrics.sessionErrors.WithLabelValues(magicTypeLabel, "yes", "motd").Add(1)
-			}
-		} else {
-			logger.Warn(ctx, "metadata lookup failed, unable to show MOTD")
+		err := showMOTD(s.fs, session, s.config.MOTDFile())
+		if err != nil {
+			logger.Error(ctx, "agent failed to show MOTD", slog.Error(err))
+			s.metrics.sessionErrors.WithLabelValues(magicTypeLabel, "yes", "motd").Add(1)
 		}
 	}
 
@@ -557,7 +650,7 @@ func (s *Server) sftpHandler(logger slog.Logger, session ssh.Session) {
 	defer server.Close()
 
 	err = server.Serve()
-	if errors.Is(err, io.EOF) {
+	if err == nil || errors.Is(err, io.EOF) {
 		// Unless we call `session.Exit(0)` here, the client won't
 		// receive `exit-status` because `(*sftp.Server).Close()`
 		// calls `Close()` on the underlying connection (session),
@@ -589,11 +682,6 @@ func (s *Server) CreateCommand(ctx context.Context, script string, env []string)
 		return nil, xerrors.Errorf("get user shell: %w", err)
 	}
 
-	manifest := s.Manifest.Load()
-	if manifest == nil {
-		return nil, xerrors.Errorf("no metadata was provided")
-	}
-
 	// OpenSSH executes all commands with the users current shell.
 	// We replicate that behavior for IDE support.
 	caller := "-c"
@@ -638,7 +726,7 @@ func (s *Server) CreateCommand(ctx context.Context, script string, env []string)
 	}
 
 	cmd := pty.CommandContext(ctx, name, args...)
-	cmd.Dir = manifest.Directory
+	cmd.Dir = s.config.WorkingDirectory()
 
 	// If the metadata directory doesn't exist, we run the command
 	// in the users home directory.
@@ -652,21 +740,7 @@ func (s *Server) CreateCommand(ctx context.Context, script string, env []string)
 		cmd.Dir = homedir
 	}
 	cmd.Env = append(os.Environ(), env...)
-	executablePath, err := os.Executable()
-	if err != nil {
-		return nil, xerrors.Errorf("getting os executable: %w", err)
-	}
-	// Set environment variables reliable detection of being inside a
-	// Coder workspace.
-	cmd.Env = append(cmd.Env, "CODER=true")
 	cmd.Env = append(cmd.Env, fmt.Sprintf("USER=%s", username))
-	// Git on Windows resolves with UNIX-style paths.
-	// If using backslashes, it's unable to find the executable.
-	unixExecutablePath := strings.ReplaceAll(executablePath, "\\", "/")
-	cmd.Env = append(cmd.Env, fmt.Sprintf(`GIT_SSH_COMMAND=%s gitssh --`, unixExecutablePath))
-
-	// Specific Coder subcommands require the agent token exposed!
-	cmd.Env = append(cmd.Env, fmt.Sprintf("CODER_AGENT_TOKEN=%s", s.AgentToken()))
 
 	// Set SSH connection environment variables (these are also set by OpenSSH
 	// and thus expected to be present by SSH clients). Since the agent does
@@ -677,26 +751,9 @@ func (s *Server) CreateCommand(ctx context.Context, script string, env []string)
 	cmd.Env = append(cmd.Env, fmt.Sprintf("SSH_CLIENT=%s %s %s", srcAddr, srcPort, dstPort))
 	cmd.Env = append(cmd.Env, fmt.Sprintf("SSH_CONNECTION=%s %s %s %s", srcAddr, srcPort, dstAddr, dstPort))
 
-	// This adds the ports dialog to code-server that enables
-	// proxying a port dynamically.
-	cmd.Env = append(cmd.Env, fmt.Sprintf("VSCODE_PROXY_URI=%s", manifest.VSCodePortProxyURI))
-
-	// Hide Coder message on code-server's "Getting Started" page
-	cmd.Env = append(cmd.Env, "CS_DISABLE_GETTING_STARTED_OVERRIDE=true")
-
-	// Load environment variables passed via the agent.
-	// These should override all variables we manually specify.
-	for envKey, value := range manifest.EnvironmentVariables {
-		// Expanding environment variables allows for customization
-		// of the $PATH, among other variables. Customers can prepend
-		// or append to the $PATH, so allowing expand is required!
-		cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", envKey, os.ExpandEnv(value)))
-	}
-
-	// Agent-level environment variables should take over all!
-	// This is used for setting agent-specific variables like "CODER_AGENT_TOKEN".
-	for envKey, value := range s.Env {
-		cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", envKey, value))
+	cmd.Env, err = s.config.UpdateEnv(cmd.Env)
+	if err != nil {
+		return nil, xerrors.Errorf("apply env: %w", err)
 	}
 
 	return cmd, nil
@@ -891,9 +948,9 @@ func isQuietLogin(fs afero.Fs, rawCommand string) bool {
 	return err == nil
 }
 
-// showServiceBanner will write the service banner if enabled and not blank
+// showAnnouncementBanner will write the service banner if enabled and not blank
 // along with a blank line for spacing.
-func showServiceBanner(session io.Writer, banner *codersdk.ServiceBannerConfig) error {
+func showAnnouncementBanner(session io.Writer, banner codersdk.BannerConfig) error {
 	if banner.Enabled && banner.Message != "" {
 		// The banner supports Markdown so we might want to parse it but Markdown is
 		// still fairly readable in its raw form.

agent/agentssh/agentssh_internal_test.go

@@ -17,8 +17,6 @@ import (
 
 	"github.com/coder/coder/v2/pty"
 	"github.com/coder/coder/v2/testutil"
-
-	"cdr.dev/slog/sloggers/slogtest"
 )
 
 const longScript = `
@@ -36,8 +34,8 @@ func Test_sessionStart_orphan(t *testing.T) {
 
 	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitMedium)
 	defer cancel()
-	logger := slogtest.Make(t, nil)
-	s, err := NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+	logger := testutil.Logger(t)
+	s, err := NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 	require.NoError(t, err)
 	defer s.Close()
 

agent/agentssh/agentssh_test.go

@@ -17,14 +17,12 @@ import (
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"go.uber.org/atomic"
 	"go.uber.org/goleak"
 	"golang.org/x/crypto/ssh"
 
 	"cdr.dev/slog/sloggers/slogtest"
 
 	"github.com/coder/coder/v2/agent/agentssh"
-	"github.com/coder/coder/v2/codersdk/agentsdk"
 	"github.com/coder/coder/v2/pty/ptytest"
 	"github.com/coder/coder/v2/testutil"
 )
@@ -37,15 +35,11 @@ func TestNewServer_ServeClient(t *testing.T) {
 	t.Parallel()
 
 	ctx := context.Background()
-	logger := slogtest.Make(t, nil)
-	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+	logger := testutil.Logger(t)
+	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 	require.NoError(t, err)
 	defer s.Close()
 
-	// The assumption is that these are set before serving SSH connections.
-	s.AgentToken = func() string { return "" }
-	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
-
 	ln, err := net.Listen("tcp", "127.0.0.1:0")
 	require.NoError(t, err)
 
@@ -82,14 +76,12 @@ func TestNewServer_ExecuteShebang(t *testing.T) {
 	}
 
 	ctx := context.Background()
-	logger := slogtest.Make(t, nil)
-	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+	logger := testutil.Logger(t)
+	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 	require.NoError(t, err)
 	t.Cleanup(func() {
 		_ = s.Close()
 	})
-	s.AgentToken = func() string { return "" }
-	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
 
 	t.Run("Basic", func(t *testing.T) {
 		t.Parallel()
@@ -116,14 +108,10 @@ func TestNewServer_CloseActiveConnections(t *testing.T) {
 
 	ctx := context.Background()
 	logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true})
-	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 	require.NoError(t, err)
 	defer s.Close()
 
-	// The assumption is that these are set before serving SSH connections.
-	s.AgentToken = func() string { return "" }
-	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
-
 	ln, err := net.Listen("tcp", "127.0.0.1:0")
 	require.NoError(t, err)
 
@@ -170,15 +158,11 @@ func TestNewServer_Signal(t *testing.T) {
 		t.Parallel()
 
 		ctx := context.Background()
-		logger := slogtest.Make(t, nil)
-		s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+		logger := testutil.Logger(t)
+		s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 		require.NoError(t, err)
 		defer s.Close()
 
-		// The assumption is that these are set before serving SSH connections.
-		s.AgentToken = func() string { return "" }
-		s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
-
 		ln, err := net.Listen("tcp", "127.0.0.1:0")
 		require.NoError(t, err)
 
@@ -239,15 +223,11 @@ func TestNewServer_Signal(t *testing.T) {
 		t.Parallel()
 
 		ctx := context.Background()
-		logger := slogtest.Make(t, nil)
-		s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), 0, "")
+		logger := testutil.Logger(t)
+		s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), afero.NewMemMapFs(), nil)
 		require.NoError(t, err)
 		defer s.Close()
 
-		// The assumption is that these are set before serving SSH connections.
-		s.AgentToken = func() string { return "" }
-		s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
-
 		ln, err := net.Listen("tcp", "127.0.0.1:0")
 		require.NoError(t, err)
 

agent/agentssh/forward.go

@@ -2,11 +2,14 @@ package agentssh
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"io/fs"
 	"net"
 	"os"
 	"path/filepath"
 	"sync"
+	"syscall"
 
 	"github.com/gliderlabs/ssh"
 	gossh "golang.org/x/crypto/ssh"
@@ -33,22 +36,29 @@ type forwardedStreamLocalPayload struct {
 type forwardedUnixHandler struct {
 	sync.Mutex
 	log      slog.Logger
-	forwards map[string]net.Listener
+	forwards map[forwardKey]net.Listener
+}
+
+type forwardKey struct {
+	sessionID string
+	addr      string
+}
+
+func newForwardedUnixHandler(log slog.Logger) *forwardedUnixHandler {
+	return &forwardedUnixHandler{
+		log:      log,
+		forwards: make(map[forwardKey]net.Listener),
+	}
 }
 
 func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server, req *gossh.Request) (bool, []byte) {
 	h.log.Debug(ctx, "handling SSH unix forward")
-	h.Lock()
-	if h.forwards == nil {
-		h.forwards = make(map[string]net.Listener)
-	}
-	h.Unlock()
 	conn, ok := ctx.Value(ssh.ContextKeyConn).(*gossh.ServerConn)
 	if !ok {
 		h.log.Warn(ctx, "SSH unix forward request from client with no gossh connection")
 		return false, nil
 	}
-	log := h.log.With(slog.F("remote_addr", conn.RemoteAddr()))
+	log := h.log.With(slog.F("session_id", ctx.SessionID()), slog.F("remote_addr", conn.RemoteAddr()))
 
 	switch req.Type {
 	case "streamlocal-forward@openssh.com":
@@ -62,14 +72,22 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 		addr := reqPayload.SocketPath
 		log = log.With(slog.F("socket_path", addr))
 		log.Debug(ctx, "request begin SSH unix forward")
+
+		key := forwardKey{
+			sessionID: ctx.SessionID(),
+			addr:      addr,
+		}
+
 		h.Lock()
-		_, ok := h.forwards[addr]
+		_, ok := h.forwards[key]
 		h.Unlock()
 		if ok {
-			log.Warn(ctx, "SSH unix forward request for socket path that is already being forwarded (maybe to another client?)",
-				slog.F("socket_path", addr),
-			)
-			return false, nil
+			// In cases where `ExitOnForwardFailure=yes` is set, returning false
+			// here will cause the connection to be closed. To avoid this, and
+			// to match OpenSSH behavior, we silently ignore the second forward
+			// request.
+			log.Warn(ctx, "SSH unix forward request for socket path that is already being forwarded on this session, ignoring")
+			return true, nil
 		}
 
 		// Create socket parent dir if not exists.
@@ -83,12 +101,20 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 			return false, nil
 		}
 
-		ln, err := net.Listen("unix", addr)
+		// Remove existing socket if it exists. We do not use os.Remove() here
+		// so that directories are kept. Note that it's possible that we will
+		// overwrite a regular file here. Both of these behaviors match OpenSSH,
+		// however, which is why we unlink.
+		err = unlink(addr)
+		if err != nil && !errors.Is(err, fs.ErrNotExist) {
+			log.Warn(ctx, "remove existing socket for SSH unix forward request", slog.Error(err))
+			return false, nil
+		}
+
+		lc := &net.ListenConfig{}
+		ln, err := lc.Listen(ctx, "unix", addr)
 		if err != nil {
-			log.Warn(ctx, "listen on Unix socket for SSH unix forward request",
-				slog.F("socket_path", addr),
-				slog.Error(err),
-			)
+			log.Warn(ctx, "listen on Unix socket for SSH unix forward request", slog.Error(err))
 			return false, nil
 		}
 		log.Debug(ctx, "SSH unix forward listening on socket")
@@ -99,7 +125,7 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 		//
 		// This is also what the upstream TCP version of this code does.
 		h.Lock()
-		h.forwards[addr] = ln
+		h.forwards[key] = ln
 		h.Unlock()
 		log.Debug(ctx, "SSH unix forward added to cache")
 
@@ -115,9 +141,7 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 				c, err := ln.Accept()
 				if err != nil {
 					if !xerrors.Is(err, net.ErrClosed) {
-						log.Warn(ctx, "accept on local Unix socket for SSH unix forward request",
-							slog.Error(err),
-						)
+						log.Warn(ctx, "accept on local Unix socket for SSH unix forward request", slog.Error(err))
 					}
 					// closed below
 					log.Debug(ctx, "SSH unix forward listener closed")
@@ -131,10 +155,7 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 				go func() {
 					ch, reqs, err := conn.OpenChannel("forwarded-streamlocal@openssh.com", payload)
 					if err != nil {
-						h.log.Warn(ctx, "open SSH unix forward channel to client",
-							slog.F("socket_path", addr),
-							slog.Error(err),
-						)
+						h.log.Warn(ctx, "open SSH unix forward channel to client", slog.Error(err))
 						_ = c.Close()
 						return
 					}
@@ -144,12 +165,11 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 			}
 
 			h.Lock()
-			ln2, ok := h.forwards[addr]
-			if ok && ln2 == ln {
-				delete(h.forwards, addr)
+			if ln2, ok := h.forwards[key]; ok && ln2 == ln {
+				delete(h.forwards, key)
 			}
 			h.Unlock()
-			log.Debug(ctx, "SSH unix forward listener removed from cache", slog.F("path", addr))
+			log.Debug(ctx, "SSH unix forward listener removed from cache")
 			_ = ln.Close()
 		}()
 
@@ -162,13 +182,22 @@ func (h *forwardedUnixHandler) HandleSSHRequest(ctx ssh.Context, _ *ssh.Server,
 			h.log.Warn(ctx, "parse cancel-streamlocal-forward@openssh.com (SSH unix forward) request payload from client", slog.Error(err))
 			return false, nil
 		}
-		log.Debug(ctx, "request to cancel SSH unix forward", slog.F("path", reqPayload.SocketPath))
-		h.Lock()
-		ln, ok := h.forwards[reqPayload.SocketPath]
-		h.Unlock()
-		if ok {
-			_ = ln.Close()
+		log.Debug(ctx, "request to cancel SSH unix forward", slog.F("socket_path", reqPayload.SocketPath))
+
+		key := forwardKey{
+			sessionID: ctx.SessionID(),
+			addr:      reqPayload.SocketPath,
 		}
+
+		h.Lock()
+		ln, ok := h.forwards[key]
+		delete(h.forwards, key)
+		h.Unlock()
+		if !ok {
+			log.Warn(ctx, "SSH unix forward not found in cache")
+			return true, nil
+		}
+		_ = ln.Close()
 		return true, nil
 
 	default:
@@ -209,3 +238,15 @@ func directStreamLocalHandler(_ *ssh.Server, _ *gossh.ServerConn, newChan gossh.
 
 	Bicopy(ctx, ch, dconn)
 }
+
+// unlink removes files and unlike os.Remove, directories are kept.
+func unlink(path string) error {
+	// Ignore EINTR like os.Remove, see ignoringEINTR in os/file_posix.go
+	// for more details.
+	for {
+		err := syscall.Unlink(path)
+		if !errors.Is(err, syscall.EINTR) {
+			return err
+		}
+	}
+}

agent/agentssh/jetbrainstrack.go

@@ -1,6 +1,7 @@
 package agentssh
 
 import (
+	"context"
 	"strings"
 	"sync"
 
@@ -26,6 +27,7 @@ type localForwardChannelData struct {
 type JetbrainsChannelWatcher struct {
 	gossh.NewChannel
 	jetbrainsCounter *atomic.Int64
+	logger           slog.Logger
 }
 
 func NewJetbrainsChannelWatcher(ctx ssh.Context, logger slog.Logger, newChannel gossh.NewChannel, counter *atomic.Int64) gossh.NewChannel {
@@ -58,6 +60,7 @@ func NewJetbrainsChannelWatcher(ctx ssh.Context, logger slog.Logger, newChannel
 	return &JetbrainsChannelWatcher{
 		NewChannel:       newChannel,
 		jetbrainsCounter: counter,
+		logger:           logger.With(slog.F("destination_port", d.DestPort)),
 	}
 }
 
@@ -67,11 +70,15 @@ func (w *JetbrainsChannelWatcher) Accept() (gossh.Channel, <-chan *gossh.Request
 		return c, r, err
 	}
 	w.jetbrainsCounter.Add(1)
+	// nolint: gocritic // JetBrains is a proper noun and should be capitalized
+	w.logger.Debug(context.Background(), "JetBrains watcher accepted channel")
 
 	return &ChannelOnClose{
 		Channel: c,
 		done: func() {
 			w.jetbrainsCounter.Add(-1)
+			// nolint: gocritic // JetBrains is a proper noun and should be capitalized
+			w.logger.Debug(context.Background(), "JetBrains watcher channel closed")
 		},
 	}, r, err
 }

agent/agentssh/portinspection_supported.go

@@ -3,6 +3,7 @@
 package agentssh
 
 import (
+	"errors"
 	"fmt"
 	"os"
 
@@ -11,24 +12,37 @@ import (
 )
 
 func getListeningPortProcessCmdline(port uint32) (string, error) {
-	tabs, err := netstat.TCPSocks(func(s *netstat.SockTabEntry) bool {
+	acceptFn := func(s *netstat.SockTabEntry) bool {
 		return s.LocalAddr != nil && uint32(s.LocalAddr.Port) == port
-	})
-	if err != nil {
-		return "", xerrors.Errorf("inspect port %d: %w", port, err)
 	}
-	if len(tabs) == 0 {
-		return "", nil
+	tabs4, err4 := netstat.TCPSocks(acceptFn)
+	tabs6, err6 := netstat.TCP6Socks(acceptFn)
+
+	// In the common case, we want to check ipv4 listening addresses.  If this
+	// fails, we should return an error.  We also need to check ipv6.  The
+	// assumption is, if we have an err4, and 0 ipv6 addresses listed, then we are
+	// interested in the err4 (and vice versa).  So return both errors (at least 1
+	// is non-nil) if the other list is empty.
+	if (err4 != nil && len(tabs6) == 0) || (err6 != nil && len(tabs4) == 0) {
+		return "", xerrors.Errorf("inspect port %d: %w", port, errors.Join(err4, err6))
 	}
 
-	// Defensive check.
-	if tabs[0].Process == nil {
+	var proc *netstat.Process
+	if len(tabs4) > 0 {
+		proc = tabs4[0].Process
+	} else if len(tabs6) > 0 {
+		proc = tabs6[0].Process
+	}
+	if proc == nil {
+		// Either nothing is listening on this port or we were unable to read the
+		// process details (permission issues reading /proc/$pid/* potentially).
+		// Or, perhaps /proc/net/tcp{,6} is not listing the port for some reason.
 		return "", nil
 	}
 
 	// The process name provided by go-netstat does not include the full command
 	// line so grab that instead.
-	pid := tabs[0].Process.Pid
+	pid := proc.Pid
 	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/cmdline", pid))
 	if err != nil {
 		return "", xerrors.Errorf("read /proc/%d/cmdline: %w", pid, err)

agent/agentssh/x11.go

@@ -6,6 +6,8 @@ import (
 	"encoding/hex"
 	"errors"
 	"fmt"
+	"io"
+	"math"
 	"net"
 	"os"
 	"path/filepath"
@@ -21,61 +23,69 @@ import (
 	"cdr.dev/slog"
 )
 
+const (
+	// X11StartPort is the starting port for X11 forwarding, this is the
+	// port used for "DISPLAY=localhost:0".
+	X11StartPort = 6000
+	// X11DefaultDisplayOffset is the default offset for X11 forwarding.
+	X11DefaultDisplayOffset = 10
+)
+
 // x11Callback is called when the client requests X11 forwarding.
-// It adds an Xauthority entry to the Xauthority file.
-func (s *Server) x11Callback(ctx ssh.Context, x11 ssh.X11) bool {
-	hostname, err := os.Hostname()
-	if err != nil {
-		s.logger.Warn(ctx, "failed to get hostname", slog.Error(err))
-		s.metrics.x11HandlerErrors.WithLabelValues("hostname").Add(1)
-		return false
-	}
-
-	err = s.fs.MkdirAll(s.x11SocketDir, 0o700)
-	if err != nil {
-		s.logger.Warn(ctx, "failed to make the x11 socket dir", slog.F("dir", s.x11SocketDir), slog.Error(err))
-		s.metrics.x11HandlerErrors.WithLabelValues("socker_dir").Add(1)
-		return false
-	}
-
-	err = addXauthEntry(ctx, s.fs, hostname, strconv.Itoa(int(x11.ScreenNumber)), x11.AuthProtocol, x11.AuthCookie)
-	if err != nil {
-		s.logger.Warn(ctx, "failed to add Xauthority entry", slog.Error(err))
-		s.metrics.x11HandlerErrors.WithLabelValues("xauthority").Add(1)
-		return false
-	}
+func (*Server) x11Callback(_ ssh.Context, _ ssh.X11) bool {
+	// Always allow.
 	return true
 }
 
 // x11Handler is called when a session has requested X11 forwarding.
 // It listens for X11 connections and forwards them to the client.
-func (s *Server) x11Handler(ctx ssh.Context, x11 ssh.X11) bool {
+func (s *Server) x11Handler(ctx ssh.Context, x11 ssh.X11) (displayNumber int, handled bool) {
 	serverConn, valid := ctx.Value(ssh.ContextKeyConn).(*gossh.ServerConn)
 	if !valid {
 		s.logger.Warn(ctx, "failed to get server connection")
-		return false
+		return -1, false
 	}
-	// We want to overwrite the socket so that subsequent connections will succeed.
-	socketPath := filepath.Join(s.x11SocketDir, fmt.Sprintf("X%d", x11.ScreenNumber))
-	err := os.Remove(socketPath)
-	if err != nil && !errors.Is(err, os.ErrNotExist) {
-		s.logger.Warn(ctx, "failed to remove existing X11 socket", slog.Error(err))
-		return false
-	}
-	listener, err := net.Listen("unix", socketPath)
+
+	hostname, err := os.Hostname()
 	if err != nil {
-		s.logger.Warn(ctx, "failed to listen for X11", slog.Error(err))
-		return false
+		s.logger.Warn(ctx, "failed to get hostname", slog.Error(err))
+		s.metrics.x11HandlerErrors.WithLabelValues("hostname").Add(1)
+		return -1, false
+	}
+
+	ln, display, err := createX11Listener(ctx, *s.config.X11DisplayOffset)
+	if err != nil {
+		s.logger.Warn(ctx, "failed to create X11 listener", slog.Error(err))
+		s.metrics.x11HandlerErrors.WithLabelValues("listen").Add(1)
+		return -1, false
+	}
+	s.trackListener(ln, true)
+	defer func() {
+		if !handled {
+			s.trackListener(ln, false)
+			_ = ln.Close()
+		}
+	}()
+
+	err = addXauthEntry(ctx, s.fs, hostname, strconv.Itoa(display), x11.AuthProtocol, x11.AuthCookie)
+	if err != nil {
+		s.logger.Warn(ctx, "failed to add Xauthority entry", slog.Error(err))
+		s.metrics.x11HandlerErrors.WithLabelValues("xauthority").Add(1)
+		return -1, false
 	}
-	s.trackListener(listener, true)
 
 	go func() {
-		defer listener.Close()
-		defer s.trackListener(listener, false)
-		handledFirstConnection := false
+		// Don't leave the listener open after the session is gone.
+		<-ctx.Done()
+		_ = ln.Close()
+	}()
+
+	go func() {
+		defer ln.Close()
+		defer s.trackListener(ln, false)
 
 		for {
-			conn, err := listener.Accept()
+			conn, err := ln.Accept()
 			if err != nil {
 				if errors.Is(err, net.ErrClosed) {
 					return
@@ -83,40 +93,66 @@ func (s *Server) x11Handler(ctx ssh.Context, x11 ssh.X11) bool {
 				s.logger.Warn(ctx, "failed to accept X11 connection", slog.Error(err))
 				return
 			}
-			if x11.SingleConnection && handledFirstConnection {
-				s.logger.Warn(ctx, "X11 connection rejected because single connection is enabled")
+			if x11.SingleConnection {
+				s.logger.Debug(ctx, "single connection requested, closing X11 listener")
+				_ = ln.Close()
+			}
+
+			tcpConn, ok := conn.(*net.TCPConn)
+			if !ok {
+				s.logger.Warn(ctx, fmt.Sprintf("failed to cast connection to TCPConn. got: %T", conn))
 				_ = conn.Close()
 				continue
 			}
-			handledFirstConnection = true
-
-			unixConn, ok := conn.(*net.UnixConn)
+			tcpAddr, ok := tcpConn.LocalAddr().(*net.TCPAddr)
 			if !ok {
-				s.logger.Warn(ctx, fmt.Sprintf("failed to cast connection to UnixConn. got: %T", conn))
-				return
-			}
-			unixAddr, ok := unixConn.LocalAddr().(*net.UnixAddr)
-			if !ok {
-				s.logger.Warn(ctx, fmt.Sprintf("failed to cast local address to UnixAddr. got: %T", unixConn.LocalAddr()))
-				return
+				s.logger.Warn(ctx, fmt.Sprintf("failed to cast local address to TCPAddr. got: %T", tcpConn.LocalAddr()))
+				_ = conn.Close()
+				continue
 			}
 
 			channel, reqs, err := serverConn.OpenChannel("x11", gossh.Marshal(struct {
 				OriginatorAddress string
 				OriginatorPort    uint32
 			}{
-				OriginatorAddress: unixAddr.Name,
-				OriginatorPort:    0,
+				OriginatorAddress: tcpAddr.IP.String(),
+				OriginatorPort:    uint32(tcpAddr.Port),
 			}))
 			if err != nil {
 				s.logger.Warn(ctx, "failed to open X11 channel", slog.Error(err))
-				return
+				_ = conn.Close()
+				continue
 			}
 			go gossh.DiscardRequests(reqs)
-			go Bicopy(ctx, conn, channel)
+
+			if !s.trackConn(ln, conn, true) {
+				s.logger.Warn(ctx, "failed to track X11 connection")
+				_ = conn.Close()
+				continue
+			}
+			go func() {
+				defer s.trackConn(ln, conn, false)
+				Bicopy(ctx, conn, channel)
+			}()
 		}
 	}()
-	return true
+
+	return display, true
+}
+
+// createX11Listener creates a listener for X11 forwarding, it will use
+// the next available port starting from X11StartPort and displayOffset.
+func createX11Listener(ctx context.Context, displayOffset int) (ln net.Listener, display int, err error) {
+	var lc net.ListenConfig
+	// Look for an open port to listen on.
+	for port := X11StartPort + displayOffset; port < math.MaxUint16; port++ {
+		ln, err = lc.Listen(ctx, "tcp", fmt.Sprintf("localhost:%d", port))
+		if err == nil {
+			display = port - X11StartPort
+			return ln, display, nil
+		}
+	}
+	return nil, -1, xerrors.Errorf("failed to find open port for X11 listener: %w", err)
 }
 
 // addXauthEntry adds an Xauthority entry to the Xauthority file.
@@ -141,7 +177,7 @@ func addXauthEntry(ctx context.Context, fs afero.Fs, host string, display string
 	}
 
 	// Open or create the Xauthority file
-	file, err := fs.OpenFile(xauthPath, os.O_RDWR|os.O_CREATE|os.O_APPEND, 0o600)
+	file, err := fs.OpenFile(xauthPath, os.O_RDWR|os.O_CREATE, 0o600)
 	if err != nil {
 		return xerrors.Errorf("failed to open Xauthority file: %w", err)
 	}
@@ -153,7 +189,105 @@ func addXauthEntry(ctx context.Context, fs afero.Fs, host string, display string
 		return xerrors.Errorf("failed to decode auth cookie: %w", err)
 	}
 
-	// Write Xauthority entry
+	// Read the Xauthority file and look for an existing entry for the host,
+	// display, and auth protocol. If an entry is found, overwrite the auth
+	// cookie (if it fits). Otherwise, mark the entry for deletion.
+	type deleteEntry struct {
+		start, end int
+	}
+	var deleteEntries []deleteEntry
+	pos := 0
+	updated := false
+	for {
+		entry, err := readXauthEntry(file)
+		if err != nil {
+			if errors.Is(err, io.EOF) {
+				break
+			}
+			return xerrors.Errorf("failed to read Xauthority entry: %w", err)
+		}
+
+		nextPos := pos + entry.Len()
+		cookieStartPos := nextPos - len(entry.authCookie)
+
+		if entry.family == 0x0100 && entry.address == host && entry.display == display && entry.authProtocol == authProtocol {
+			if !updated && len(entry.authCookie) == len(authCookieBytes) {
+				// Overwrite the auth cookie
+				_, err := file.WriteAt(authCookieBytes, int64(cookieStartPos))
+				if err != nil {
+					return xerrors.Errorf("failed to write auth cookie: %w", err)
+				}
+				updated = true
+			} else {
+				// Mark entry for deletion.
+				if len(deleteEntries) > 0 && deleteEntries[len(deleteEntries)-1].end == pos {
+					deleteEntries[len(deleteEntries)-1].end = nextPos
+				} else {
+					deleteEntries = append(deleteEntries, deleteEntry{
+						start: pos,
+						end:   nextPos,
+					})
+				}
+			}
+		}
+
+		pos = nextPos
+	}
+
+	// In case the magic cookie changed, or we've previously bloated the
+	// Xauthority file, we may have to delete entries.
+	if len(deleteEntries) > 0 {
+		// Read the entire file into memory. This is not ideal, but it's the
+		// simplest way to delete entries from the middle of the file. The
+		// Xauthority file is small, so this should be fine.
+		_, err = file.Seek(0, io.SeekStart)
+		if err != nil {
+			return xerrors.Errorf("failed to seek Xauthority file: %w", err)
+		}
+		data, err := io.ReadAll(file)
+		if err != nil {
+			return xerrors.Errorf("failed to read Xauthority file: %w", err)
+		}
+
+		// Delete the entries in reverse order.
+		for i := len(deleteEntries) - 1; i >= 0; i-- {
+			entry := deleteEntries[i]
+			// Safety check: ensure the entry is still there.
+			if entry.start > len(data) || entry.end > len(data) {
+				continue
+			}
+			data = append(data[:entry.start], data[entry.end:]...)
+		}
+
+		// Write the data back to the file.
+		_, err = file.Seek(0, io.SeekStart)
+		if err != nil {
+			return xerrors.Errorf("failed to seek Xauthority file: %w", err)
+		}
+		_, err = file.Write(data)
+		if err != nil {
+			return xerrors.Errorf("failed to write Xauthority file: %w", err)
+		}
+
+		// Truncate the file.
+		err = file.Truncate(int64(len(data)))
+		if err != nil {
+			return xerrors.Errorf("failed to truncate Xauthority file: %w", err)
+		}
+	}
+
+	// Return if we've already updated the entry.
+	if updated {
+		return nil
+	}
+
+	// Ensure we're at the end (append).
+	_, err = file.Seek(0, io.SeekEnd)
+	if err != nil {
+		return xerrors.Errorf("failed to seek Xauthority file: %w", err)
+	}
+
+	// Append Xauthority entry.
 	family := uint16(0x0100) // FamilyLocal
 	err = binary.Write(file, binary.BigEndian, family)
 	if err != nil {
@@ -198,3 +332,96 @@ func addXauthEntry(ctx context.Context, fs afero.Fs, host string, display string
 
 	return nil
 }
+
+// xauthEntry is an representation of an Xauthority entry.
+//
+// The Xauthority file format is as follows:
+//
+// - 16-bit family
+// - 16-bit address length
+// - address
+// - 16-bit display length
+// - display
+// - 16-bit auth protocol length
+// - auth protocol
+// - 16-bit auth cookie length
+// - auth cookie
+type xauthEntry struct {
+	family       uint16
+	address      string
+	display      string
+	authProtocol string
+	authCookie   []byte
+}
+
+func (e xauthEntry) Len() int {
+	// 5 * uint16 = 10 bytes for the family/length fields.
+	return 2*5 + len(e.address) + len(e.display) + len(e.authProtocol) + len(e.authCookie)
+}
+
+func readXauthEntry(r io.Reader) (xauthEntry, error) {
+	var entry xauthEntry
+
+	// Read family
+	err := binary.Read(r, binary.BigEndian, &entry.family)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read family: %w", err)
+	}
+
+	// Read address
+	var addressLength uint16
+	err = binary.Read(r, binary.BigEndian, &addressLength)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read address length: %w", err)
+	}
+
+	addressBytes := make([]byte, addressLength)
+	_, err = r.Read(addressBytes)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read address: %w", err)
+	}
+	entry.address = string(addressBytes)
+
+	// Read display
+	var displayLength uint16
+	err = binary.Read(r, binary.BigEndian, &displayLength)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read display length: %w", err)
+	}
+
+	displayBytes := make([]byte, displayLength)
+	_, err = r.Read(displayBytes)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read display: %w", err)
+	}
+	entry.display = string(displayBytes)
+
+	// Read auth protocol
+	var authProtocolLength uint16
+	err = binary.Read(r, binary.BigEndian, &authProtocolLength)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read auth protocol length: %w", err)
+	}
+
+	authProtocolBytes := make([]byte, authProtocolLength)
+	_, err = r.Read(authProtocolBytes)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read auth protocol: %w", err)
+	}
+	entry.authProtocol = string(authProtocolBytes)
+
+	// Read auth cookie
+	var authCookieLength uint16
+	err = binary.Read(r, binary.BigEndian, &authCookieLength)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read auth cookie length: %w", err)
+	}
+
+	entry.authCookie = make([]byte, authCookieLength)
+	_, err = r.Read(entry.authCookie)
+	if err != nil {
+		return xauthEntry{}, xerrors.Errorf("failed to read auth cookie: %w", err)
+	}
+
+	return entry, nil
+}

agent/agentssh/x11_internal_test.go

@@ -0,0 +1,254 @@
+package agentssh
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_addXauthEntry(t *testing.T) {
+	t.Parallel()
+
+	type testEntry struct {
+		address      string
+		display      string
+		authProtocol string
+		authCookie   string
+	}
+	tests := []struct {
+		name         string
+		authFile     []byte
+		wantAuthFile []byte
+		entries      []testEntry
+	}{
+		{
+			name:     "add entry",
+			authFile: nil,
+			wantAuthFile: []byte{
+				// w/unix:0  MIT-MAGIC-COOKIE-1  00
+				//
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0001 00    GIC-COOKIE-1...
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x00,
+			},
+			entries: []testEntry{
+				{
+					address:      "w",
+					display:      "0",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "00",
+				},
+			},
+		},
+		{
+			name:     "add two entries",
+			authFile: []byte{},
+			wantAuthFile: []byte{
+				// w/unix:0  MIT-MAGIC-COOKIE-1  00
+				// w/unix:1  MIT-MAGIC-COOKIE-1  11
+				//
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0001 0001  GIC-COOKIE-1....
+				// 00000020: 0000 0177 0001 3100 124d 4954 2d4d 4147  ...w..1..MIT-MAG
+				// 00000030: 4943 2d43 4f4f 4b49 452d 3100 0111       IC-COOKIE-1...
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x00,
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x31,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x11,
+			},
+			entries: []testEntry{
+				{
+					address:      "w",
+					display:      "0",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "00",
+				},
+				{
+					address:      "w",
+					display:      "1",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "11",
+				},
+			},
+		},
+		{
+			name: "update entry with new auth cookie length",
+			authFile: []byte{
+				// w/unix:0  MIT-MAGIC-COOKIE-1  00
+				// w/unix:1  MIT-MAGIC-COOKIE-1  11
+				//
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0001 0001  GIC-COOKIE-1....
+				// 00000020: 0000 0177 0001 3100 124d 4954 2d4d 4147  ...w..1..MIT-MAG
+				// 00000030: 4943 2d43 4f4f 4b49 452d 3100 0111       IC-COOKIE-1...
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x00,
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x31,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x11,
+			},
+			wantAuthFile: []byte{
+				// The order changed, due to new length of auth cookie resulting
+				// in remove + append, we verify that the implementation is
+				// behaving as expected (changing the order is not a requirement,
+				// simply an implementation detail).
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x31,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x11,
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x02, 0xff, 0xff,
+			},
+			entries: []testEntry{
+				{
+					address:      "w",
+					display:      "0",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "ffff",
+				},
+			},
+		},
+		{
+			name: "update entry",
+			authFile: []byte{
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0001 0001  GIC-COOKIE-1....
+				// 00000020: 0000 0177 0001 3100 124d 4954 2d4d 4147  ...w..1..MIT-MAG
+				// 00000030: 4943 2d43 4f4f 4b49 452d 3100 0111       IC-COOKIE-1...
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x00,
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x31,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x11,
+			},
+			wantAuthFile: []byte{
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0001 0001  GIC-COOKIE-1....
+				// 00000020: 0000 0177 0001 3100 124d 4954 2d4d 4147  ...w..1..MIT-MAG
+				// 00000030: 4943 2d43 4f4f 4b49 452d 3100 0111       IC-COOKIE-1...
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0xff,
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x31,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x01, 0x11,
+			},
+			entries: []testEntry{
+				{
+					address:      "w",
+					display:      "0",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "ff",
+				},
+			},
+		},
+		{
+			name: "clean up old entries",
+			authFile: []byte{
+				// w/unix:0  MIT-MAGIC-COOKIE-1  80507df050756cdefa504b65adb3bcfb
+				// w/unix:0  MIT-MAGIC-COOKIE-1  267b37f6cbc11b97beb826bb1aab8570
+				// w/unix:0  MIT-MAGIC-COOKIE-1  516e22e2b11d1bd0115dff09c028ca5c
+				//
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0010 8050  GIC-COOKIE-1...P
+				// 00000020: 7df0 5075 6cde fa50 4b65 adb3 bcfb 0100  }.Pul..PKe......
+				// 00000030: 0001 7700 0130 0012 4d49 542d 4d41 4749  ..w..0..MIT-MAGI
+				// 00000040: 432d 434f 4f4b 4945 2d31 0010 267b 37f6  C-COOKIE-1..&{7.
+				// 00000050: cbc1 1b97 beb8 26bb 1aab 8570 0100 0001  ......&....p....
+				// 00000060: 7700 0130 0012 4d49 542d 4d41 4749 432d  w..0..MIT-MAGIC-
+				// 00000070: 434f 4f4b 4945 2d31 0010 516e 22e2 b11d  COOKIE-1..Qn"...
+				// 00000080: 1bd0 115d ff09 c028 ca5c                 ...]...(.\
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x10, 0x80, 0x50,
+				0x7d, 0xf0, 0x50, 0x75, 0x6c, 0xde, 0xfa, 0x50,
+				0x4b, 0x65, 0xad, 0xb3, 0xbc, 0xfb, 0x01, 0x00,
+				0x00, 0x01, 0x77, 0x00, 0x01, 0x30, 0x00, 0x12,
+				0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41, 0x47, 0x49,
+				0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b, 0x49, 0x45,
+				0x2d, 0x31, 0x00, 0x10, 0x26, 0x7b, 0x37, 0xf6,
+				0xcb, 0xc1, 0x1b, 0x97, 0xbe, 0xb8, 0x26, 0xbb,
+				0x1a, 0xab, 0x85, 0x70, 0x01, 0x00, 0x00, 0x01,
+				0x77, 0x00, 0x01, 0x30, 0x00, 0x12, 0x4d, 0x49,
+				0x54, 0x2d, 0x4d, 0x41, 0x47, 0x49, 0x43, 0x2d,
+				0x43, 0x4f, 0x4f, 0x4b, 0x49, 0x45, 0x2d, 0x31,
+				0x00, 0x10, 0x51, 0x6e, 0x22, 0xe2, 0xb1, 0x1d,
+				0x1b, 0xd0, 0x11, 0x5d, 0xff, 0x09, 0xc0, 0x28,
+				0xca, 0x5c,
+			},
+			wantAuthFile: []byte{
+				// w/unix:0  MIT-MAGIC-COOKIE-1  516e5bc892b7162b844abd1fc1a7c16e
+				//
+				// 00000000: 0100 0001 7700 0130 0012 4d49 542d 4d41  ....w..0..MIT-MA
+				// 00000010: 4749 432d 434f 4f4b 4945 2d31 0010 516e  GIC-COOKIE-1..Qn
+				// 00000020: 5bc8 92b7 162b 844a bd1f c1a7 c16e       [....+.J.....n
+				0x01, 0x00, 0x00, 0x01, 0x77, 0x00, 0x01, 0x30,
+				0x00, 0x12, 0x4d, 0x49, 0x54, 0x2d, 0x4d, 0x41,
+				0x47, 0x49, 0x43, 0x2d, 0x43, 0x4f, 0x4f, 0x4b,
+				0x49, 0x45, 0x2d, 0x31, 0x00, 0x10, 0x51, 0x6e,
+				0x5b, 0xc8, 0x92, 0xb7, 0x16, 0x2b, 0x84, 0x4a,
+				0xbd, 0x1f, 0xc1, 0xa7, 0xc1, 0x6e,
+			},
+			entries: []testEntry{
+				{
+					address:      "w",
+					display:      "0",
+					authProtocol: "MIT-MAGIC-COOKIE-1",
+					authCookie:   "516e5bc892b7162b844abd1fc1a7c16e",
+				},
+			},
+		},
+	}
+
+	homedir, err := os.UserHomeDir()
+	require.NoError(t, err)
+
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			fs := afero.NewMemMapFs()
+			if tt.authFile != nil {
+				err := afero.WriteFile(fs, filepath.Join(homedir, ".Xauthority"), tt.authFile, 0o600)
+				require.NoError(t, err)
+			}
+
+			for _, entry := range tt.entries {
+				err := addXauthEntry(context.Background(), fs, entry.address, entry.display, entry.authProtocol, entry.authCookie)
+				require.NoError(t, err)
+			}
+
+			gotAuthFile, err := afero.ReadFile(fs, filepath.Join(homedir, ".Xauthority"))
+			require.NoError(t, err)
+
+			if diff := cmp.Diff(tt.wantAuthFile, gotAuthFile); diff != "" {
+				assert.Failf(t, "addXauthEntry() mismatch", "(-want +got):\n%s", diff)
+			}
+		})
+	}
+}

agent/agentssh/x11_test.go

@@ -1,12 +1,17 @@
 package agentssh_test
 
 import (
+	"bufio"
+	"bytes"
 	"context"
 	"encoding/hex"
+	"fmt"
 	"net"
 	"os"
 	"path/filepath"
 	"runtime"
+	"strconv"
+	"strings"
 	"testing"
 
 	"github.com/gliderlabs/ssh"
@@ -14,13 +19,9 @@ import (
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"go.uber.org/atomic"
 	gossh "golang.org/x/crypto/ssh"
 
-	"cdr.dev/slog"
-	"cdr.dev/slog/sloggers/slogtest"
 	"github.com/coder/coder/v2/agent/agentssh"
-	"github.com/coder/coder/v2/codersdk/agentsdk"
 	"github.com/coder/coder/v2/testutil"
 )
 
@@ -31,17 +32,12 @@ func TestServer_X11(t *testing.T) {
 	}
 
 	ctx := context.Background()
-	logger := slogtest.Make(t, nil).Leveled(slog.LevelDebug)
+	logger := testutil.Logger(t)
 	fs := afero.NewOsFs()
-	dir := t.TempDir()
-	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), fs, 0, dir)
+	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), fs, &agentssh.Config{})
 	require.NoError(t, err)
 	defer s.Close()
 
-	// The assumption is that these are set before serving SSH connections.
-	s.AgentToken = func() string { return "" }
-	s.Manifest = atomic.NewPointer(&agentsdk.Manifest{})
-
 	ln, err := net.Listen("tcp", "127.0.0.1:0")
 	require.NoError(t, err)
 
@@ -57,21 +53,45 @@ func TestServer_X11(t *testing.T) {
 	sess, err := c.NewSession()
 	require.NoError(t, err)
 
+	wantScreenNumber := 1
 	reply, err := sess.SendRequest("x11-req", true, gossh.Marshal(ssh.X11{
 		AuthProtocol: "MIT-MAGIC-COOKIE-1",
 		AuthCookie:   hex.EncodeToString([]byte("cookie")),
-		ScreenNumber: 0,
+		ScreenNumber: uint32(wantScreenNumber),
 	}))
 	require.NoError(t, err)
 	assert.True(t, reply)
 
-	err = sess.Shell()
+	// Want: ~DISPLAY=localhost:10.1
+	out, err := sess.Output("echo DISPLAY=$DISPLAY")
 	require.NoError(t, err)
 
+	sc := bufio.NewScanner(bytes.NewReader(out))
+	displayNumber := -1
+	for sc.Scan() {
+		line := strings.TrimSpace(sc.Text())
+		t.Log(line)
+		if strings.HasPrefix(line, "DISPLAY=") {
+			parts := strings.SplitN(line, "=", 2)
+			display := parts[1]
+			parts = strings.SplitN(display, ":", 2)
+			parts = strings.SplitN(parts[1], ".", 2)
+			displayNumber, err = strconv.Atoi(parts[0])
+			require.NoError(t, err)
+			assert.GreaterOrEqual(t, displayNumber, 10, "display number should be >= 10")
+			gotScreenNumber, err := strconv.Atoi(parts[1])
+			require.NoError(t, err)
+			assert.Equal(t, wantScreenNumber, gotScreenNumber, "screen number should match")
+			break
+		}
+	}
+	require.NoError(t, sc.Err())
+	require.NotEqual(t, -1, displayNumber)
+
 	x11Chans := c.HandleChannelOpen("x11")
 	payload := "hello world"
 	require.Eventually(t, func() bool {
-		conn, err := net.Dial("unix", filepath.Join(dir, "X0"))
+		conn, err := net.Dial("tcp", fmt.Sprintf("localhost:%d", agentssh.X11StartPort+displayNumber))
 		if err == nil {
 			_, err = conn.Write([]byte(payload))
 			assert.NoError(t, err)

agent/agenttest/agent.go

@@ -7,10 +7,9 @@ import (
 
 	"github.com/stretchr/testify/assert"
 
-	"cdr.dev/slog"
-	"cdr.dev/slog/sloggers/slogtest"
 	"github.com/coder/coder/v2/agent"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
+	"github.com/coder/coder/v2/testutil"
 )
 
 // New starts a new agent for use in tests.
@@ -24,7 +23,7 @@ func New(t testing.TB, coderURL *url.URL, agentToken string, opts ...func(*agent
 	t.Helper()
 
 	var o agent.Options
-	log := slogtest.Make(t, nil).Leveled(slog.LevelDebug).Named("agent")
+	log := testutil.Logger(t).Named("agent")
 	o.Logger = log
 
 	for _, opt := range opts {

agent/agenttest/client.go

@@ -3,164 +3,132 @@ package agenttest
 import (
 	"context"
 	"io"
-	"net"
 	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 
 	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 	"golang.org/x/exp/maps"
+	"golang.org/x/exp/slices"
 	"golang.org/x/xerrors"
+	"google.golang.org/protobuf/types/known/durationpb"
+	"storj.io/drpc/drpcmux"
+	"storj.io/drpc/drpcserver"
+	"tailscale.com/tailcfg"
 
 	"cdr.dev/slog"
+	agentproto "github.com/coder/coder/v2/agent/proto"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
+	drpcsdk "github.com/coder/coder/v2/codersdk/drpc"
 	"github.com/coder/coder/v2/tailnet"
+	"github.com/coder/coder/v2/tailnet/proto"
 	"github.com/coder/coder/v2/testutil"
 )
 
+const statsInterval = 500 * time.Millisecond
+
 func NewClient(t testing.TB,
 	logger slog.Logger,
 	agentID uuid.UUID,
 	manifest agentsdk.Manifest,
-	statsChan chan *agentsdk.Stats,
+	statsChan chan *agentproto.Stats,
 	coordinator tailnet.Coordinator,
 ) *Client {
 	if manifest.AgentID == uuid.Nil {
 		manifest.AgentID = agentID
 	}
+	coordPtr := atomic.Pointer[tailnet.Coordinator]{}
+	coordPtr.Store(&coordinator)
+	mux := drpcmux.New()
+	derpMapUpdates := make(chan *tailcfg.DERPMap)
+	drpcService := &tailnet.DRPCService{
+		CoordPtr:               &coordPtr,
+		Logger:                 logger.Named("tailnetsvc"),
+		DerpMapUpdateFrequency: time.Microsecond,
+		DerpMapFn:              func() *tailcfg.DERPMap { return <-derpMapUpdates },
+	}
+	err := proto.DRPCRegisterTailnet(mux, drpcService)
+	require.NoError(t, err)
+	mp, err := agentsdk.ProtoFromManifest(manifest)
+	require.NoError(t, err)
+	fakeAAPI := NewFakeAgentAPI(t, logger, mp, statsChan)
+	err = agentproto.DRPCRegisterAgent(mux, fakeAAPI)
+	require.NoError(t, err)
+	server := drpcserver.NewWithOptions(mux, drpcserver.Options{
+		Log: func(err error) {
+			if xerrors.Is(err, io.EOF) {
+				return
+			}
+			logger.Debug(context.Background(), "drpc server error", slog.Error(err))
+		},
+	})
 	return &Client{
 		t:              t,
 		logger:         logger.Named("client"),
 		agentID:        agentID,
-		manifest:       manifest,
-		statsChan:      statsChan,
-		coordinator:    coordinator,
-		derpMapUpdates: make(chan agentsdk.DERPMapUpdate),
+		server:         server,
+		fakeAgentAPI:   fakeAAPI,
+		derpMapUpdates: derpMapUpdates,
 	}
 }
 
 type Client struct {
-	t                    testing.TB
-	logger               slog.Logger
-	agentID              uuid.UUID
-	manifest             agentsdk.Manifest
-	metadata             map[string]agentsdk.Metadata
-	statsChan            chan *agentsdk.Stats
-	coordinator          tailnet.Coordinator
-	LastWorkspaceAgent   func()
-	PatchWorkspaceLogs   func() error
-	GetServiceBannerFunc func() (codersdk.ServiceBannerConfig, error)
+	t                  testing.TB
+	logger             slog.Logger
+	agentID            uuid.UUID
+	server             *drpcserver.Server
+	fakeAgentAPI       *FakeAgentAPI
+	LastWorkspaceAgent func()
 
-	mu              sync.Mutex // Protects following.
-	lifecycleStates []codersdk.WorkspaceAgentLifecycle
-	startup         agentsdk.PostStartupRequest
-	logs            []agentsdk.Log
-	derpMapUpdates  chan agentsdk.DERPMapUpdate
+	mu             sync.Mutex // Protects following.
+	logs           []agentsdk.Log
+	derpMapUpdates chan *tailcfg.DERPMap
+	derpMapOnce    sync.Once
 }
 
-func (c *Client) Manifest(_ context.Context) (agentsdk.Manifest, error) {
-	return c.manifest, nil
+func (*Client) RewriteDERPMap(*tailcfg.DERPMap) {}
+
+func (c *Client) Close() {
+	c.derpMapOnce.Do(func() { close(c.derpMapUpdates) })
 }
 
-func (c *Client) Listen(_ context.Context) (net.Conn, error) {
-	clientConn, serverConn := net.Pipe()
-	closed := make(chan struct{})
+func (c *Client) ConnectRPC23(ctx context.Context) (
+	agentproto.DRPCAgentClient23, proto.DRPCTailnetClient23, error,
+) {
+	conn, lis := drpcsdk.MemTransportPipe()
 	c.LastWorkspaceAgent = func() {
-		_ = serverConn.Close()
-		_ = clientConn.Close()
-		<-closed
+		_ = conn.Close()
+		_ = lis.Close()
 	}
 	c.t.Cleanup(c.LastWorkspaceAgent)
+	serveCtx, cancel := context.WithCancel(ctx)
+	c.t.Cleanup(cancel)
+	streamID := tailnet.StreamID{
+		Name: "agenttest",
+		ID:   c.agentID,
+		Auth: tailnet.AgentCoordinateeAuth{ID: c.agentID},
+	}
+	serveCtx = tailnet.WithStreamID(serveCtx, streamID)
 	go func() {
-		_ = c.coordinator.ServeAgent(serverConn, c.agentID, "")
-		close(closed)
+		_ = c.server.Serve(serveCtx, lis)
 	}()
-	return clientConn, nil
-}
-
-func (c *Client) ReportStats(ctx context.Context, _ slog.Logger, statsChan <-chan *agentsdk.Stats, setInterval func(time.Duration)) (io.Closer, error) {
-	doneCh := make(chan struct{})
-	ctx, cancel := context.WithCancel(ctx)
-
-	go func() {
-		defer close(doneCh)
-
-		setInterval(500 * time.Millisecond)
-		for {
-			select {
-			case <-ctx.Done():
-				return
-			case stat := <-statsChan:
-				select {
-				case c.statsChan <- stat:
-				case <-ctx.Done():
-					return
-				default:
-					// We don't want to send old stats.
-					continue
-				}
-			}
-		}
-	}()
-	return closeFunc(func() error {
-		cancel()
-		<-doneCh
-		close(c.statsChan)
-		return nil
-	}), nil
+	return agentproto.NewDRPCAgentClient(conn), proto.NewDRPCTailnetClient(conn), nil
 }
 
 func (c *Client) GetLifecycleStates() []codersdk.WorkspaceAgentLifecycle {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	return c.lifecycleStates
+	return c.fakeAgentAPI.GetLifecycleStates()
 }
 
-func (c *Client) PostLifecycle(ctx context.Context, req agentsdk.PostLifecycleRequest) error {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	c.lifecycleStates = append(c.lifecycleStates, req.State)
-	c.logger.Debug(ctx, "post lifecycle", slog.F("req", req))
-	return nil
-}
-
-func (c *Client) PostAppHealth(ctx context.Context, req agentsdk.PostAppHealthsRequest) error {
-	c.logger.Debug(ctx, "post app health", slog.F("req", req))
-	return nil
-}
-
-func (c *Client) GetStartup() agentsdk.PostStartupRequest {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	return c.startup
+func (c *Client) GetStartup() <-chan *agentproto.Startup {
+	return c.fakeAgentAPI.startupCh
 }
 
 func (c *Client) GetMetadata() map[string]agentsdk.Metadata {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	return maps.Clone(c.metadata)
-}
-
-func (c *Client) PostMetadata(ctx context.Context, req agentsdk.PostMetadataRequest) error {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	if c.metadata == nil {
-		c.metadata = make(map[string]agentsdk.Metadata)
-	}
-	for _, md := range req.Metadata {
-		c.metadata[md.Key] = md
-		c.logger.Debug(ctx, "post metadata", slog.F("key", md.Key), slog.F("md", md))
-	}
-	return nil
-}
-
-func (c *Client) PostStartup(ctx context.Context, startup agentsdk.PostStartupRequest) error {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	c.startup = startup
-	c.logger.Debug(ctx, "post startup", slog.F("req", startup))
-	return nil
+	return c.fakeAgentAPI.GetMetadata()
 }
 
 func (c *Client) GetStartupLogs() []agentsdk.Log {
@@ -169,35 +137,11 @@ func (c *Client) GetStartupLogs() []agentsdk.Log {
 	return c.logs
 }
 
-func (c *Client) PatchLogs(ctx context.Context, logs agentsdk.PatchLogs) error {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	if c.PatchWorkspaceLogs != nil {
-		return c.PatchWorkspaceLogs()
-	}
-	c.logs = append(c.logs, logs.Logs...)
-	c.logger.Debug(ctx, "patch startup logs", slog.F("req", logs))
-	return nil
+func (c *Client) SetAnnouncementBannersFunc(f func() ([]codersdk.BannerConfig, error)) {
+	c.fakeAgentAPI.SetAnnouncementBannersFunc(f)
 }
 
-func (c *Client) SetServiceBannerFunc(f func() (codersdk.ServiceBannerConfig, error)) {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-
-	c.GetServiceBannerFunc = f
-}
-
-func (c *Client) GetServiceBanner(ctx context.Context) (codersdk.ServiceBannerConfig, error) {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	c.logger.Debug(ctx, "get service banner")
-	if c.GetServiceBannerFunc != nil {
-		return c.GetServiceBannerFunc()
-	}
-	return codersdk.ServiceBannerConfig{}, nil
-}
-
-func (c *Client) PushDERPMapUpdate(update agentsdk.DERPMapUpdate) error {
+func (c *Client) PushDERPMapUpdate(update *tailcfg.DERPMap) error {
 	timer := time.NewTimer(testutil.WaitShort)
 	defer timer.Stop()
 	select {
@@ -209,16 +153,175 @@ func (c *Client) PushDERPMapUpdate(update agentsdk.DERPMapUpdate) error {
 	return nil
 }
 
-func (c *Client) DERPMapUpdates(_ context.Context) (<-chan agentsdk.DERPMapUpdate, io.Closer, error) {
-	closed := make(chan struct{})
-	return c.derpMapUpdates, closeFunc(func() error {
-		close(closed)
-		return nil
-	}), nil
+func (c *Client) SetLogsChannel(ch chan<- *agentproto.BatchCreateLogsRequest) {
+	c.fakeAgentAPI.SetLogsChannel(ch)
 }
 
-type closeFunc func() error
+type FakeAgentAPI struct {
+	sync.Mutex
+	t      testing.TB
+	logger slog.Logger
 
-func (c closeFunc) Close() error {
-	return c()
+	manifest        *agentproto.Manifest
+	startupCh       chan *agentproto.Startup
+	statsCh         chan *agentproto.Stats
+	appHealthCh     chan *agentproto.BatchUpdateAppHealthRequest
+	logsCh          chan<- *agentproto.BatchCreateLogsRequest
+	lifecycleStates []codersdk.WorkspaceAgentLifecycle
+	metadata        map[string]agentsdk.Metadata
+	timings         []*agentproto.Timing
+
+	getAnnouncementBannersFunc func() ([]codersdk.BannerConfig, error)
+}
+
+func (f *FakeAgentAPI) GetManifest(context.Context, *agentproto.GetManifestRequest) (*agentproto.Manifest, error) {
+	return f.manifest, nil
+}
+
+func (*FakeAgentAPI) GetServiceBanner(context.Context, *agentproto.GetServiceBannerRequest) (*agentproto.ServiceBanner, error) {
+	return &agentproto.ServiceBanner{}, nil
+}
+
+func (f *FakeAgentAPI) GetTimings() []*agentproto.Timing {
+	f.Lock()
+	defer f.Unlock()
+	return slices.Clone(f.timings)
+}
+
+func (f *FakeAgentAPI) SetAnnouncementBannersFunc(fn func() ([]codersdk.BannerConfig, error)) {
+	f.Lock()
+	defer f.Unlock()
+	f.getAnnouncementBannersFunc = fn
+	f.logger.Info(context.Background(), "updated notification banners")
+}
+
+func (f *FakeAgentAPI) GetAnnouncementBanners(context.Context, *agentproto.GetAnnouncementBannersRequest) (*agentproto.GetAnnouncementBannersResponse, error) {
+	f.Lock()
+	defer f.Unlock()
+	if f.getAnnouncementBannersFunc == nil {
+		return &agentproto.GetAnnouncementBannersResponse{AnnouncementBanners: []*agentproto.BannerConfig{}}, nil
+	}
+	banners, err := f.getAnnouncementBannersFunc()
+	if err != nil {
+		return nil, err
+	}
+	bannersProto := make([]*agentproto.BannerConfig, 0, len(banners))
+	for _, banner := range banners {
+		bannersProto = append(bannersProto, agentsdk.ProtoFromBannerConfig(banner))
+	}
+	return &agentproto.GetAnnouncementBannersResponse{AnnouncementBanners: bannersProto}, nil
+}
+
+func (f *FakeAgentAPI) UpdateStats(ctx context.Context, req *agentproto.UpdateStatsRequest) (*agentproto.UpdateStatsResponse, error) {
+	f.logger.Debug(ctx, "update stats called", slog.F("req", req))
+	// empty request is sent to get the interval; but our tests don't want empty stats requests
+	if req.Stats != nil {
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case f.statsCh <- req.Stats:
+			// OK!
+		}
+	}
+	return &agentproto.UpdateStatsResponse{ReportInterval: durationpb.New(statsInterval)}, nil
+}
+
+func (f *FakeAgentAPI) GetLifecycleStates() []codersdk.WorkspaceAgentLifecycle {
+	f.Lock()
+	defer f.Unlock()
+	return slices.Clone(f.lifecycleStates)
+}
+
+func (f *FakeAgentAPI) UpdateLifecycle(_ context.Context, req *agentproto.UpdateLifecycleRequest) (*agentproto.Lifecycle, error) {
+	f.Lock()
+	defer f.Unlock()
+	s, err := agentsdk.LifecycleStateFromProto(req.GetLifecycle().GetState())
+	if assert.NoError(f.t, err) {
+		f.lifecycleStates = append(f.lifecycleStates, s)
+	}
+	return req.GetLifecycle(), nil
+}
+
+func (f *FakeAgentAPI) BatchUpdateAppHealths(ctx context.Context, req *agentproto.BatchUpdateAppHealthRequest) (*agentproto.BatchUpdateAppHealthResponse, error) {
+	f.logger.Debug(ctx, "batch update app health", slog.F("req", req))
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	case f.appHealthCh <- req:
+		return &agentproto.BatchUpdateAppHealthResponse{}, nil
+	}
+}
+
+func (f *FakeAgentAPI) AppHealthCh() <-chan *agentproto.BatchUpdateAppHealthRequest {
+	return f.appHealthCh
+}
+
+func (f *FakeAgentAPI) UpdateStartup(ctx context.Context, req *agentproto.UpdateStartupRequest) (*agentproto.Startup, error) {
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	case f.startupCh <- req.GetStartup():
+		return req.GetStartup(), nil
+	}
+}
+
+func (f *FakeAgentAPI) GetMetadata() map[string]agentsdk.Metadata {
+	f.Lock()
+	defer f.Unlock()
+	return maps.Clone(f.metadata)
+}
+
+func (f *FakeAgentAPI) BatchUpdateMetadata(ctx context.Context, req *agentproto.BatchUpdateMetadataRequest) (*agentproto.BatchUpdateMetadataResponse, error) {
+	f.Lock()
+	defer f.Unlock()
+	if f.metadata == nil {
+		f.metadata = make(map[string]agentsdk.Metadata)
+	}
+	for _, md := range req.Metadata {
+		smd := agentsdk.MetadataFromProto(md)
+		f.metadata[md.Key] = smd
+		f.logger.Debug(ctx, "post metadata", slog.F("key", md.Key), slog.F("md", md))
+	}
+	return &agentproto.BatchUpdateMetadataResponse{}, nil
+}
+
+func (f *FakeAgentAPI) SetLogsChannel(ch chan<- *agentproto.BatchCreateLogsRequest) {
+	f.Lock()
+	defer f.Unlock()
+	f.logsCh = ch
+}
+
+func (f *FakeAgentAPI) BatchCreateLogs(ctx context.Context, req *agentproto.BatchCreateLogsRequest) (*agentproto.BatchCreateLogsResponse, error) {
+	f.logger.Info(ctx, "batch create logs called", slog.F("req", req))
+	f.Lock()
+	ch := f.logsCh
+	f.Unlock()
+	if ch != nil {
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case ch <- req:
+			// ok
+		}
+	}
+	return &agentproto.BatchCreateLogsResponse{}, nil
+}
+
+func (f *FakeAgentAPI) ScriptCompleted(_ context.Context, req *agentproto.WorkspaceAgentScriptCompletedRequest) (*agentproto.WorkspaceAgentScriptCompletedResponse, error) {
+	f.Lock()
+	f.timings = append(f.timings, req.Timing)
+	f.Unlock()
+
+	return &agentproto.WorkspaceAgentScriptCompletedResponse{}, nil
+}
+
+func NewFakeAgentAPI(t testing.TB, logger slog.Logger, manifest *agentproto.Manifest, statsCh chan *agentproto.Stats) *FakeAgentAPI {
+	return &FakeAgentAPI{
+		t:           t,
+		logger:      logger.Named("FakeAgentAPI"),
+		manifest:    manifest,
+		statsCh:     statsCh,
+		startupCh:   make(chan *agentproto.Startup, 100),
+		appHealthCh: make(chan *agentproto.BatchUpdateAppHealthRequest, 100),
+	}
 }

agent/api.go

@@ -35,7 +35,14 @@ func (a *agent) apiHandler() http.Handler {
 		ignorePorts:   cpy,
 		cacheDuration: cacheDuration,
 	}
+	promHandler := PrometheusMetricsHandler(a.prometheusRegistry, a.logger)
 	r.Get("/api/v0/listening-ports", lp.handler)
+	r.Get("/api/v0/netcheck", a.HandleNetcheck)
+	r.Get("/debug/logs", a.HandleHTTPDebugLogs)
+	r.Get("/debug/magicsock", a.HandleHTTPDebugMagicsock)
+	r.Get("/debug/magicsock/debug-logging/{state}", a.HandleHTTPMagicsockDebugLoggingState)
+	r.Get("/debug/manifest", a.HandleHTTPDebugManifest)
+	r.Get("/debug/prometheus", promHandler.ServeHTTP)
 
 	return r
 }

agent/apphealth.go

@@ -12,12 +12,9 @@ import (
 	"cdr.dev/slog"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
-	"github.com/coder/retry"
+	"github.com/coder/quartz"
 )
 
-// WorkspaceAgentApps fetches the workspace apps.
-type WorkspaceAgentApps func(context.Context) ([]codersdk.WorkspaceApp, error)
-
 // PostWorkspaceAgentAppHealth updates the workspace app health.
 type PostWorkspaceAgentAppHealth func(context.Context, agentsdk.PostAppHealthsRequest) error
 
@@ -26,10 +23,26 @@ type WorkspaceAppHealthReporter func(ctx context.Context)
 
 // NewWorkspaceAppHealthReporter creates a WorkspaceAppHealthReporter that reports app health to coderd.
 func NewWorkspaceAppHealthReporter(logger slog.Logger, apps []codersdk.WorkspaceApp, postWorkspaceAgentAppHealth PostWorkspaceAgentAppHealth) WorkspaceAppHealthReporter {
-	runHealthcheckLoop := func(ctx context.Context) error {
+	return NewAppHealthReporterWithClock(logger, apps, postWorkspaceAgentAppHealth, quartz.NewReal())
+}
+
+// NewAppHealthReporterWithClock is only called directly by test code.  Product code should call
+// NewAppHealthReporter.
+func NewAppHealthReporterWithClock(
+	logger slog.Logger,
+	apps []codersdk.WorkspaceApp,
+	postWorkspaceAgentAppHealth PostWorkspaceAgentAppHealth,
+	clk quartz.Clock,
+) WorkspaceAppHealthReporter {
+	logger = logger.Named("apphealth")
+
+	return func(ctx context.Context) {
+		ctx, cancel := context.WithCancel(ctx)
+		defer cancel()
+
 		// no need to run this loop if no apps for this workspace.
 		if len(apps) == 0 {
-			return nil
+			return
 		}
 
 		hasHealthchecksEnabled := false
@@ -44,7 +57,7 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, apps []codersdk.Workspace
 
 		// no need to run this loop if no health checks are configured.
 		if !hasHealthchecksEnabled {
-			return nil
+			return
 		}
 
 		// run a ticker for each app health check.
@@ -56,25 +69,29 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, apps []codersdk.Workspace
 			}
 			app := nextApp
 			go func() {
-				t := time.NewTicker(time.Duration(app.Healthcheck.Interval) * time.Second)
-				defer t.Stop()
+				_ = clk.TickerFunc(ctx, time.Duration(app.Healthcheck.Interval)*time.Second, func() error {
+					// We time out at the healthcheck interval to prevent getting too backed up, but
+					// set it 1ms early so that it's not simultaneous with the next tick in testing,
+					// which makes the test easier to understand.
+					//
+					// It would be idiomatic to use the http.Client.Timeout or a context.WithTimeout,
+					// but we are passing this off to the native http library, which is not aware
+					// of the clock library we are using. That means in testing, with a mock clock
+					// it will compare mocked times with real times, and we will get strange results.
+					// So, we just implement the timeout as a context we cancel with an AfterFunc
+					reqCtx, reqCancel := context.WithCancel(ctx)
+					timeout := clk.AfterFunc(
+						time.Duration(app.Healthcheck.Interval)*time.Second-time.Millisecond,
+						reqCancel,
+						"timeout", app.Slug)
+					defer timeout.Stop()
 
-				for {
-					select {
-					case <-ctx.Done():
-						return
-					case <-t.C:
-					}
-					// we set the http timeout to the healthcheck interval to prevent getting too backed up.
-					client := &http.Client{
-						Timeout: time.Duration(app.Healthcheck.Interval) * time.Second,
-					}
 					err := func() error {
-						req, err := http.NewRequestWithContext(ctx, http.MethodGet, app.Healthcheck.URL, nil)
+						req, err := http.NewRequestWithContext(reqCtx, http.MethodGet, app.Healthcheck.URL, nil)
 						if err != nil {
 							return err
 						}
-						res, err := client.Do(req)
+						res, err := http.DefaultClient.Do(req)
 						if err != nil {
 							return err
 						}
@@ -87,6 +104,7 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, apps []codersdk.Workspace
 						return nil
 					}()
 					if err != nil {
+						nowUnhealthy := false
 						mu.Lock()
 						if failures[app.ID] < int(app.Healthcheck.Threshold) {
 							// increment the failure count and keep status the same.
@@ -96,61 +114,52 @@ func NewWorkspaceAppHealthReporter(logger slog.Logger, apps []codersdk.Workspace
 							// set to unhealthy if we hit the failure threshold.
 							// we stop incrementing at the threshold to prevent the failure value from increasing forever.
 							health[app.ID] = codersdk.WorkspaceAppHealthUnhealthy
+							nowUnhealthy = true
 						}
 						mu.Unlock()
+						logger.Debug(ctx, "error checking app health",
+							slog.F("id", app.ID.String()),
+							slog.F("slug", app.Slug),
+							slog.F("now_unhealthy", nowUnhealthy), slog.Error(err),
+						)
 					} else {
 						mu.Lock()
 						// we only need one successful health check to be considered healthy.
 						health[app.ID] = codersdk.WorkspaceAppHealthHealthy
 						failures[app.ID] = 0
 						mu.Unlock()
+						logger.Debug(ctx, "workspace app healthy", slog.F("id", app.ID.String()), slog.F("slug", app.Slug))
 					}
-
-					t.Reset(time.Duration(app.Healthcheck.Interval) * time.Second)
-				}
+					return nil
+				}, "healthcheck", app.Slug)
 			}()
 		}
 
 		mu.Lock()
 		lastHealth := copyHealth(health)
 		mu.Unlock()
-		reportTicker := time.NewTicker(time.Second)
-		defer reportTicker.Stop()
-		// every second we check if the health values of the apps have changed
-		// and if there is a change we will report the new values.
-		for {
-			select {
-			case <-ctx.Done():
+		reportTicker := clk.TickerFunc(ctx, time.Second, func() error {
+			mu.RLock()
+			changed := healthChanged(lastHealth, health)
+			mu.RUnlock()
+			if !changed {
 				return nil
-			case <-reportTicker.C:
-				mu.RLock()
-				changed := healthChanged(lastHealth, health)
-				mu.RUnlock()
-				if !changed {
-					continue
-				}
-
-				mu.Lock()
-				lastHealth = copyHealth(health)
-				mu.Unlock()
-				err := postWorkspaceAgentAppHealth(ctx, agentsdk.PostAppHealthsRequest{
-					Healths: lastHealth,
-				})
-				if err != nil {
-					logger.Error(ctx, "failed to report workspace app stat", slog.Error(err))
-				}
 			}
-		}
-	}
 
-	return func(ctx context.Context) {
-		for r := retry.New(time.Second, 30*time.Second); r.Wait(ctx); {
-			err := runHealthcheckLoop(ctx)
-			if err == nil || xerrors.Is(err, context.Canceled) || xerrors.Is(err, context.DeadlineExceeded) {
-				return
+			mu.Lock()
+			lastHealth = copyHealth(health)
+			mu.Unlock()
+			err := postWorkspaceAgentAppHealth(ctx, agentsdk.PostAppHealthsRequest{
+				Healths: lastHealth,
+			})
+			if err != nil {
+				logger.Error(ctx, "failed to report workspace app health", slog.Error(err))
+			} else {
+				logger.Debug(ctx, "sent workspace app health", slog.F("health", lastHealth))
 			}
-			logger.Error(ctx, "failed running workspace app reporter", slog.Error(err))
-		}
+			return nil
+		}, "report")
+		_ = reportTicker.Wait() // only possible error is context done
 	}
 }
 

agent/apphealth_test.go

@@ -4,33 +4,37 @@ import (
 	"context"
 	"net/http"
 	"net/http/httptest"
-	"sync"
-	"sync/atomic"
+	"slices"
+	"strings"
 	"testing"
 	"time"
 
+	"github.com/google/uuid"
 	"github.com/stretchr/testify/require"
 
-	"cdr.dev/slog"
-	"cdr.dev/slog/sloggers/slogtest"
 	"github.com/coder/coder/v2/agent"
+	"github.com/coder/coder/v2/agent/agenttest"
+	"github.com/coder/coder/v2/agent/proto"
 	"github.com/coder/coder/v2/coderd/httpapi"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/agentsdk"
 	"github.com/coder/coder/v2/testutil"
+	"github.com/coder/quartz"
 )
 
 func TestAppHealth_Healthy(t *testing.T) {
 	t.Parallel()
-	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
 	defer cancel()
 	apps := []codersdk.WorkspaceApp{
 		{
+			ID:          uuid.UUID{1},
 			Slug:        "app1",
 			Healthcheck: codersdk.Healthcheck{},
 			Health:      codersdk.WorkspaceAppHealthDisabled,
 		},
 		{
+			ID:   uuid.UUID{2},
 			Slug: "app2",
 			Healthcheck: codersdk.Healthcheck{
 				// URL: We don't set the URL for this test because the setup will
@@ -40,34 +44,81 @@ func TestAppHealth_Healthy(t *testing.T) {
 			},
 			Health: codersdk.WorkspaceAppHealthInitializing,
 		},
+		{
+			ID:   uuid.UUID{3},
+			Slug: "app3",
+			Healthcheck: codersdk.Healthcheck{
+				Interval:  2,
+				Threshold: 1,
+			},
+			Health: codersdk.WorkspaceAppHealthInitializing,
+		},
 	}
+	checks2 := 0
+	checks3 := 0
 	handlers := []http.Handler{
 		nil,
 		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			checks2++
+			httpapi.Write(r.Context(), w, http.StatusOK, nil)
+		}),
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			checks3++
 			httpapi.Write(r.Context(), w, http.StatusOK, nil)
 		}),
 	}
-	getApps, closeFn := setupAppReporter(ctx, t, apps, handlers)
-	defer closeFn()
-	apps, err := getApps(ctx)
-	require.NoError(t, err)
-	require.EqualValues(t, codersdk.WorkspaceAppHealthDisabled, apps[0].Health)
-	require.Eventually(t, func() bool {
-		apps, err := getApps(ctx)
-		if err != nil {
-			return false
-		}
+	mClock := quartz.NewMock(t)
+	healthcheckTrap := mClock.Trap().TickerFunc("healthcheck")
+	defer healthcheckTrap.Close()
+	reportTrap := mClock.Trap().TickerFunc("report")
+	defer reportTrap.Close()
 
-		return apps[1].Health == codersdk.WorkspaceAppHealthHealthy
-	}, testutil.WaitLong, testutil.IntervalSlow)
+	fakeAPI, closeFn := setupAppReporter(ctx, t, slices.Clone(apps), handlers, mClock)
+	defer closeFn()
+	healthchecksStarted := make([]string, 2)
+	for i := 0; i < 2; i++ {
+		c := healthcheckTrap.MustWait(ctx)
+		c.Release()
+		healthchecksStarted[i] = c.Tags[1]
+	}
+	slices.Sort(healthchecksStarted)
+	require.Equal(t, []string{"app2", "app3"}, healthchecksStarted)
+
+	// advance the clock 1ms before the report ticker starts, so that it's not
+	// simultaneous with the checks.
+	mClock.Advance(time.Millisecond).MustWait(ctx)
+	reportTrap.MustWait(ctx).Release()
+
+	mClock.Advance(999 * time.Millisecond).MustWait(ctx) // app2 is now healthy
+
+	mClock.Advance(time.Millisecond).MustWait(ctx) // report gets triggered
+	update := testutil.RequireRecvCtx(ctx, t, fakeAPI.AppHealthCh())
+	require.Len(t, update.GetUpdates(), 2)
+	applyUpdate(t, apps, update)
+	require.Equal(t, codersdk.WorkspaceAppHealthHealthy, apps[1].Health)
+	require.Equal(t, codersdk.WorkspaceAppHealthInitializing, apps[2].Health)
+
+	mClock.Advance(999 * time.Millisecond).MustWait(ctx) // app3 is now healthy
+
+	mClock.Advance(time.Millisecond).MustWait(ctx) // report gets triggered
+	update = testutil.RequireRecvCtx(ctx, t, fakeAPI.AppHealthCh())
+	require.Len(t, update.GetUpdates(), 2)
+	applyUpdate(t, apps, update)
+	require.Equal(t, codersdk.WorkspaceAppHealthHealthy, apps[1].Health)
+	require.Equal(t, codersdk.WorkspaceAppHealthHealthy, apps[2].Health)
+
+	// ensure we aren't spamming
+	require.Equal(t, 2, checks2)
+	require.Equal(t, 1, checks3)
 }
 
 func TestAppHealth_500(t *testing.T) {
 	t.Parallel()
-	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
 	defer cancel()
 	apps := []codersdk.WorkspaceApp{
 		{
+			ID:   uuid.UUID{2},
 			Slug: "app2",
 			Healthcheck: codersdk.Healthcheck{
 				// URL: We don't set the URL for this test because the setup will
@@ -83,59 +134,40 @@ func TestAppHealth_500(t *testing.T) {
 			httpapi.Write(r.Context(), w, http.StatusInternalServerError, nil)
 		}),
 	}
-	getApps, closeFn := setupAppReporter(ctx, t, apps, handlers)
-	defer closeFn()
-	require.Eventually(t, func() bool {
-		apps, err := getApps(ctx)
-		if err != nil {
-			return false
-		}
 
-		return apps[0].Health == codersdk.WorkspaceAppHealthUnhealthy
-	}, testutil.WaitLong, testutil.IntervalSlow)
+	mClock := quartz.NewMock(t)
+	healthcheckTrap := mClock.Trap().TickerFunc("healthcheck")
+	defer healthcheckTrap.Close()
+	reportTrap := mClock.Trap().TickerFunc("report")
+	defer reportTrap.Close()
+
+	fakeAPI, closeFn := setupAppReporter(ctx, t, slices.Clone(apps), handlers, mClock)
+	defer closeFn()
+	healthcheckTrap.MustWait(ctx).Release()
+	// advance the clock 1ms before the report ticker starts, so that it's not
+	// simultaneous with the checks.
+	mClock.Advance(time.Millisecond).MustWait(ctx)
+	reportTrap.MustWait(ctx).Release()
+
+	mClock.Advance(999 * time.Millisecond).MustWait(ctx) // check gets triggered
+	mClock.Advance(time.Millisecond).MustWait(ctx)       // report gets triggered, but unsent since we are at the threshold
+
+	mClock.Advance(999 * time.Millisecond).MustWait(ctx) // 2nd check, crosses threshold
+	mClock.Advance(time.Millisecond).MustWait(ctx)       // 2nd report, sends update
+
+	update := testutil.RequireRecvCtx(ctx, t, fakeAPI.AppHealthCh())
+	require.Len(t, update.GetUpdates(), 1)
+	applyUpdate(t, apps, update)
+	require.Equal(t, codersdk.WorkspaceAppHealthUnhealthy, apps[0].Health)
 }
 
 func TestAppHealth_Timeout(t *testing.T) {
 	t.Parallel()
-	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
-	defer cancel()
-	apps := []codersdk.WorkspaceApp{
-		{
-			Slug: "app2",
-			Healthcheck: codersdk.Healthcheck{
-				// URL: We don't set the URL for this test because the setup will
-				// create a httptest server for us and set it for us.
-				Interval:  1,
-				Threshold: 1,
-			},
-			Health: codersdk.WorkspaceAppHealthInitializing,
-		},
-	}
-	handlers := []http.Handler{
-		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			// sleep longer than the interval to cause the health check to time out
-			time.Sleep(2 * time.Second)
-			httpapi.Write(r.Context(), w, http.StatusOK, nil)
-		}),
-	}
-	getApps, closeFn := setupAppReporter(ctx, t, apps, handlers)
-	defer closeFn()
-	require.Eventually(t, func() bool {
-		apps, err := getApps(ctx)
-		if err != nil {
-			return false
-		}
-
-		return apps[0].Health == codersdk.WorkspaceAppHealthUnhealthy
-	}, testutil.WaitLong, testutil.IntervalSlow)
-}
-
-func TestAppHealth_NotSpamming(t *testing.T) {
-	t.Parallel()
-	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
 	defer cancel()
 	apps := []codersdk.WorkspaceApp{
 		{
+			ID:   uuid.UUID{2},
 			Slug: "app2",
 			Healthcheck: codersdk.Healthcheck{
 				// URL: We don't set the URL for this test because the setup will
@@ -147,22 +179,66 @@ func TestAppHealth_NotSpamming(t *testing.T) {
 		},
 	}
 
-	counter := new(int32)
 	handlers := []http.Handler{
-		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			atomic.AddInt32(counter, 1)
+		http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+			// allow the request to time out
+			<-r.Context().Done()
 		}),
 	}
-	_, closeFn := setupAppReporter(ctx, t, apps, handlers)
+	mClock := quartz.NewMock(t)
+	start := mClock.Now()
+
+	// for this test, it's easier to think in the number of milliseconds elapsed
+	// since start.
+	ms := func(n int) time.Time {
+		return start.Add(time.Duration(n) * time.Millisecond)
+	}
+	healthcheckTrap := mClock.Trap().TickerFunc("healthcheck")
+	defer healthcheckTrap.Close()
+	reportTrap := mClock.Trap().TickerFunc("report")
+	defer reportTrap.Close()
+	timeoutTrap := mClock.Trap().AfterFunc("timeout")
+	defer timeoutTrap.Close()
+
+	fakeAPI, closeFn := setupAppReporter(ctx, t, apps, handlers, mClock)
 	defer closeFn()
-	// Ensure we haven't made more than 2 (expected 1 + 1 for buffer) requests in the last second.
-	// if there is a bug where we are spamming the healthcheck route this will catch it.
-	time.Sleep(time.Second)
-	require.LessOrEqual(t, atomic.LoadInt32(counter), int32(2))
+	healthcheckTrap.MustWait(ctx).Release()
+	// advance the clock 1ms before the report ticker starts, so that it's not
+	// simultaneous with the checks.
+	mClock.Set(ms(1)).MustWait(ctx)
+	reportTrap.MustWait(ctx).Release()
+
+	w := mClock.Set(ms(1000)) // 1st check starts
+	timeoutTrap.MustWait(ctx).Release()
+	mClock.Set(ms(1001)).MustWait(ctx) // report tick, no change
+	mClock.Set(ms(1999))               // timeout pops
+	w.MustWait(ctx)                    // 1st check finished
+	w = mClock.Set(ms(2000))           // 2nd check starts
+	timeoutTrap.MustWait(ctx).Release()
+	mClock.Set(ms(2001)).MustWait(ctx) // report tick, no change
+	mClock.Set(ms(2999))               // timeout pops
+	w.MustWait(ctx)                    // 2nd check finished
+	// app is now unhealthy after 2 timeouts
+	mClock.Set(ms(3000)) // 3rd check starts
+	timeoutTrap.MustWait(ctx).Release()
+	mClock.Set(ms(3001)).MustWait(ctx) // report tick, sends changes
+
+	update := testutil.RequireRecvCtx(ctx, t, fakeAPI.AppHealthCh())
+	require.Len(t, update.GetUpdates(), 1)
+	applyUpdate(t, apps, update)
+	require.Equal(t, codersdk.WorkspaceAppHealthUnhealthy, apps[0].Health)
 }
 
-func setupAppReporter(ctx context.Context, t *testing.T, apps []codersdk.WorkspaceApp, handlers []http.Handler) (agent.WorkspaceAgentApps, func()) {
+func setupAppReporter(
+	ctx context.Context, t *testing.T,
+	apps []codersdk.WorkspaceApp,
+	handlers []http.Handler,
+	clk quartz.Clock,
+) (*agenttest.FakeAgentAPI, func()) {
 	closers := []func(){}
+	for _, app := range apps {
+		require.NotEqual(t, uuid.Nil, app.ID, "all apps must have ID set")
+	}
 	for i, handler := range handlers {
 		if handler == nil {
 			continue
@@ -174,34 +250,39 @@ func setupAppReporter(ctx context.Context, t *testing.T, apps []codersdk.Workspa
 		closers = append(closers, ts.Close)
 	}
 
-	var mu sync.Mutex
-	workspaceAgentApps := func(context.Context) ([]codersdk.WorkspaceApp, error) {
-		mu.Lock()
-		defer mu.Unlock()
-		var newApps []codersdk.WorkspaceApp
-		return append(newApps, apps...), nil
-	}
-	postWorkspaceAgentAppHealth := func(_ context.Context, req agentsdk.PostAppHealthsRequest) error {
-		mu.Lock()
-		for id, health := range req.Healths {
-			for i, app := range apps {
-				if app.ID != id {
-					continue
-				}
-				app.Health = health
-				apps[i] = app
-			}
-		}
-		mu.Unlock()
+	// We don't care about manifest or stats in this test since it's not using
+	// a full agent and these RPCs won't get called.
+	//
+	// We use a proper fake agent API so we can test the conversion code and the
+	// request code as well. Before we were bypassing these by using a custom
+	// post function.
+	fakeAAPI := agenttest.NewFakeAgentAPI(t, testutil.Logger(t), nil, nil)
 
-		return nil
-	}
+	go agent.NewAppHealthReporterWithClock(
+		testutil.Logger(t),
+		apps, agentsdk.AppHealthPoster(fakeAAPI), clk,
+	)(ctx)
 
-	go agent.NewWorkspaceAppHealthReporter(slogtest.Make(t, nil).Leveled(slog.LevelDebug), apps, postWorkspaceAgentAppHealth)(ctx)
-
-	return workspaceAgentApps, func() {
+	return fakeAAPI, func() {
 		for _, closeFn := range closers {
 			closeFn()
 		}
 	}
 }
+
+func applyUpdate(t *testing.T, apps []codersdk.WorkspaceApp, req *proto.BatchUpdateAppHealthRequest) {
+	t.Helper()
+	for _, update := range req.Updates {
+		updateID, err := uuid.FromBytes(update.Id)
+		require.NoError(t, err)
+		updateHealth := codersdk.WorkspaceAppHealth(strings.ToLower(proto.AppHealth_name[int32(update.Health)]))
+
+		for i, app := range apps {
+			if app.ID != updateID {
+				continue
+			}
+			app.Health = updateHealth
+			apps[i] = app
+		}
+	}
+}

agent/checkpoint.go

@@ -0,0 +1,51 @@
+package agent
+
+import (
+	"context"
+	"runtime"
+	"sync"
+
+	"cdr.dev/slog"
+)
+
+// checkpoint allows a goroutine to communicate when it is OK to proceed beyond some async condition
+// to other dependent goroutines.
+type checkpoint struct {
+	logger slog.Logger
+	mu     sync.Mutex
+	called bool
+	done   chan struct{}
+	err    error
+}
+
+// complete the checkpoint.  Pass nil to indicate the checkpoint was ok.  It is an error to call this
+// more than once.
+func (c *checkpoint) complete(err error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.called {
+		b := make([]byte, 2048)
+		n := runtime.Stack(b, false)
+		c.logger.Critical(context.Background(), "checkpoint complete called more than once", slog.F("stacktrace", b[:n]))
+		return
+	}
+	c.called = true
+	c.err = err
+	close(c.done)
+}
+
+func (c *checkpoint) wait(ctx context.Context) error {
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-c.done:
+		return c.err
+	}
+}
+
+func newCheckpoint(logger slog.Logger) *checkpoint {
+	return &checkpoint{
+		logger: logger,
+		done:   make(chan struct{}),
+	}
+}

agent/checkpoint_internal_test.go

@@ -0,0 +1,49 @@
+package agent
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"golang.org/x/xerrors"
+
+	"cdr.dev/slog/sloggers/slogtest"
+	"github.com/coder/coder/v2/testutil"
+)
+
+func TestCheckpoint_CompleteWait(t *testing.T) {
+	t.Parallel()
+	logger := testutil.Logger(t)
+	ctx := testutil.Context(t, testutil.WaitShort)
+	uut := newCheckpoint(logger)
+	err := xerrors.New("test")
+	uut.complete(err)
+	got := uut.wait(ctx)
+	require.Equal(t, err, got)
+}
+
+func TestCheckpoint_CompleteTwice(t *testing.T) {
+	t.Parallel()
+	logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true})
+	ctx := testutil.Context(t, testutil.WaitShort)
+	uut := newCheckpoint(logger)
+	err := xerrors.New("test")
+	uut.complete(err)
+	uut.complete(nil) // drops CRITICAL log
+	got := uut.wait(ctx)
+	require.Equal(t, err, got)
+}
+
+func TestCheckpoint_WaitComplete(t *testing.T) {
+	t.Parallel()
+	logger := testutil.Logger(t)
+	ctx := testutil.Context(t, testutil.WaitShort)
+	uut := newCheckpoint(logger)
+	err := xerrors.New("test")
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- uut.wait(ctx)
+	}()
+	uut.complete(err)
+	got := testutil.RequireRecvCtx(ctx, t, errCh)
+	require.Equal(t, err, got)
+}

agent/health.go

@@ -0,0 +1,31 @@
+package agent
+
+import (
+	"net/http"
+
+	"github.com/coder/coder/v2/coderd/healthcheck/health"
+	"github.com/coder/coder/v2/coderd/httpapi"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/codersdk/healthsdk"
+)
+
+func (a *agent) HandleNetcheck(rw http.ResponseWriter, r *http.Request) {
+	ni := a.TailnetConn().GetNetInfo()
+
+	ifReport, err := healthsdk.RunInterfacesReport()
+	if err != nil {
+		httpapi.Write(r.Context(), rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Failed to run interfaces report",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	httpapi.Write(r.Context(), rw, http.StatusOK, healthsdk.AgentNetcheckReport{
+		BaseReport: healthsdk.BaseReport{
+			Severity: health.SeverityOK,
+		},
+		NetInfo:    ni,
+		Interfaces: ifReport,
+	})
+}

agent/metrics.go

@@ -10,8 +10,7 @@ import (
 	"tailscale.com/util/clientmetric"
 
 	"cdr.dev/slog"
-
-	"github.com/coder/coder/v2/codersdk/agentsdk"
+	"github.com/coder/coder/v2/agent/proto"
 )
 
 type agentMetrics struct {
@@ -20,6 +19,7 @@ type agentMetrics struct {
 	// startupScriptSeconds is the time in seconds that the start script(s)
 	// took to run. This is reported once per agent.
 	startupScriptSeconds *prometheus.GaugeVec
+	currentConnections   *prometheus.GaugeVec
 }
 
 func newAgentMetrics(registerer prometheus.Registerer) *agentMetrics {
@@ -46,15 +46,24 @@ func newAgentMetrics(registerer prometheus.Registerer) *agentMetrics {
 	}, []string{"success"})
 	registerer.MustRegister(startupScriptSeconds)
 
+	currentConnections := prometheus.NewGaugeVec(prometheus.GaugeOpts{
+		Namespace: "coderd",
+		Subsystem: "agentstats",
+		Name:      "currently_reachable_peers",
+		Help:      "The number of peers (e.g. clients) that are currently reachable over the encrypted network.",
+	}, []string{"connection_type"})
+	registerer.MustRegister(currentConnections)
+
 	return &agentMetrics{
 		connectionsTotal:      connectionsTotal,
 		reconnectingPTYErrors: reconnectingPTYErrors,
 		startupScriptSeconds:  startupScriptSeconds,
+		currentConnections:    currentConnections,
 	}
 }
 
-func (a *agent) collectMetrics(ctx context.Context) []agentsdk.AgentMetric {
-	var collected []agentsdk.AgentMetric
+func (a *agent) collectMetrics(ctx context.Context) []*proto.Stats_Metric {
+	var collected []*proto.Stats_Metric
 
 	// Tailscale internal metrics
 	metrics := clientmetric.Metrics()
@@ -63,7 +72,7 @@ func (a *agent) collectMetrics(ctx context.Context) []agentsdk.AgentMetric {
 			continue
 		}
 
-		collected = append(collected, agentsdk.AgentMetric{
+		collected = append(collected, &proto.Stats_Metric{
 			Name:  m.Name(),
 			Type:  asMetricType(m.Type()),
 			Value: float64(m.Value()),
@@ -81,16 +90,16 @@ func (a *agent) collectMetrics(ctx context.Context) []agentsdk.AgentMetric {
 			labels := toAgentMetricLabels(metric.Label)
 
 			if metric.Counter != nil {
-				collected = append(collected, agentsdk.AgentMetric{
+				collected = append(collected, &proto.Stats_Metric{
 					Name:   metricFamily.GetName(),
-					Type:   agentsdk.AgentMetricTypeCounter,
+					Type:   proto.Stats_Metric_COUNTER,
 					Value:  metric.Counter.GetValue(),
 					Labels: labels,
 				})
 			} else if metric.Gauge != nil {
-				collected = append(collected, agentsdk.AgentMetric{
+				collected = append(collected, &proto.Stats_Metric{
 					Name:   metricFamily.GetName(),
-					Type:   agentsdk.AgentMetricTypeGauge,
+					Type:   proto.Stats_Metric_GAUGE,
 					Value:  metric.Gauge.GetValue(),
 					Labels: labels,
 				})
@@ -102,14 +111,14 @@ func (a *agent) collectMetrics(ctx context.Context) []agentsdk.AgentMetric {
 	return collected
 }
 
-func toAgentMetricLabels(metricLabels []*prompb.LabelPair) []agentsdk.AgentMetricLabel {
+func toAgentMetricLabels(metricLabels []*prompb.LabelPair) []*proto.Stats_Metric_Label {
 	if len(metricLabels) == 0 {
 		return nil
 	}
 
-	labels := make([]agentsdk.AgentMetricLabel, 0, len(metricLabels))
+	labels := make([]*proto.Stats_Metric_Label, 0, len(metricLabels))
 	for _, metricLabel := range metricLabels {
-		labels = append(labels, agentsdk.AgentMetricLabel{
+		labels = append(labels, &proto.Stats_Metric_Label{
 			Name:  metricLabel.GetName(),
 			Value: metricLabel.GetValue(),
 		})
@@ -130,12 +139,12 @@ func isIgnoredMetric(metricName string) bool {
 	return false
 }
 
-func asMetricType(typ clientmetric.Type) agentsdk.AgentMetricType {
+func asMetricType(typ clientmetric.Type) proto.Stats_Metric_Type {
 	switch typ {
 	case clientmetric.TypeGauge:
-		return agentsdk.AgentMetricTypeGauge
+		return proto.Stats_Metric_GAUGE
 	case clientmetric.TypeCounter:
-		return agentsdk.AgentMetricTypeCounter
+		return proto.Stats_Metric_COUNTER
 	default:
 		panic(fmt.Sprintf("unknown metric type: %d", typ))
 	}

agent/ports_supported.go

@@ -9,6 +9,7 @@ import (
 	"golang.org/x/xerrors"
 
 	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
 )
 
 func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.WorkspaceAgentListeningPort, error) {
@@ -32,7 +33,7 @@ func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.WorkspaceAgentL
 	seen := make(map[uint16]struct{}, len(tabs))
 	ports := []codersdk.WorkspaceAgentListeningPort{}
 	for _, tab := range tabs {
-		if tab.LocalAddr == nil || tab.LocalAddr.Port < codersdk.WorkspaceAgentMinimumListeningPort {
+		if tab.LocalAddr == nil || tab.LocalAddr.Port < workspacesdk.AgentMinimumListeningPort {
 			continue
 		}
 

agent/proto/agent.proto

@@ -8,7 +8,7 @@ import "google/protobuf/timestamp.proto";
 import "google/protobuf/duration.proto";
 
 message WorkspaceApp {
-	bytes uuid = 1;
+	bytes id = 1;
 	string url = 2;
 	bool external = 3;
 	string slug = 4;
@@ -26,12 +26,12 @@ message WorkspaceApp {
 	}
 	SharingLevel sharing_level = 10;
 
-	message HealthCheck {
+	message Healthcheck {
 		string url = 1;
-		int32 interval = 2;
+		google.protobuf.Duration interval = 2;
 		int32 threshold = 3;
 	}
-	HealthCheck healthcheck = 11;
+	Healthcheck healthcheck = 11;
 
 	enum Health {
 		HEALTH_UNSPECIFIED = 0;
@@ -41,13 +41,59 @@ message WorkspaceApp {
 		UNHEALTHY = 4;
 	}
 	Health health = 12;
+	bool hidden = 13;
+}
+
+message WorkspaceAgentScript {
+	bytes log_source_id = 1;
+	string log_path = 2;
+	string script = 3;
+	string cron = 4;
+	bool run_on_start = 5;
+	bool run_on_stop = 6;
+	bool start_blocks_login = 7;
+	google.protobuf.Duration timeout = 8;
+	string display_name = 9;
+	bytes id = 10;
+}
+
+message WorkspaceAgentMetadata {
+	message Result {
+		google.protobuf.Timestamp collected_at = 1;
+		int64 age = 2;
+		string value = 3;
+		string error = 4;
+	}
+	Result result = 1;
+
+	message Description {
+		string display_name = 1;
+		string key = 2;
+		string script = 3;
+		google.protobuf.Duration interval = 4;
+		google.protobuf.Duration timeout = 5;
+	}
+	Description description = 2;
 }
 
 message Manifest {
-	uint32 git_auth_configs = 1;
-	string vs_code_port_proxy_uri = 2;
-	repeated WorkspaceApp apps = 3;
-	coder.tailnet.v2.DERPMap derp_map = 4;
+	bytes agent_id = 1;
+	string agent_name = 15;
+	string owner_username = 13;
+	bytes workspace_id = 14;
+	string workspace_name = 16;
+	uint32 git_auth_configs = 2;
+	map<string, string> environment_variables = 3;
+	string directory = 4;
+	string vs_code_port_proxy_uri = 5;
+	string motd_path = 6;
+	bool disable_direct_connections = 7;
+	bool derp_force_websockets = 8;
+
+	coder.tailnet.v2.DERPMap derp_map = 9;
+	repeated WorkspaceAgentScript scripts = 10;
+	repeated WorkspaceApp apps = 11;
+	repeated WorkspaceAgentMetadata.Description metadata = 12;
 }
 
 message GetManifestRequest {}
@@ -100,8 +146,14 @@ message Stats {
 		Type type = 2;
 
 		double value = 3;
-		map<string, string> labels = 4;
+
+		message Label {
+			string name = 1;
+			string value = 2;
+		}
+		repeated Label labels = 4;
 	}
+	repeated Metric metrics = 12;
 }
 
 message UpdateStatsRequest{
@@ -109,14 +161,14 @@ message UpdateStatsRequest{
 }
 
 message UpdateStatsResponse {
-	google.protobuf.Duration report_interval_nanoseconds = 1;
+	google.protobuf.Duration report_interval = 1;
 }
 
 message Lifecycle {
 	enum State {
 		STATE_UNSPECIFIED = 0;
 		CREATED = 1;
-		STARTED = 2;
+		STARTING = 2;
 		START_TIMEOUT = 3;
 		START_ERROR = 4;
 		READY = 5;
@@ -126,6 +178,7 @@ message Lifecycle {
 		OFF = 9;
 	}
 	State state = 1;
+	google.protobuf.Timestamp changed_at = 2;
 }
 
 message UpdateLifecycleRequest {
@@ -142,7 +195,7 @@ enum AppHealth {
 
 message BatchUpdateAppHealthRequest {
 	message HealthUpdate {
-		bytes uuid = 1;
+		bytes id = 1;
 		AppHealth health = 2;
 	}
 	repeated HealthUpdate updates = 1;
@@ -153,7 +206,13 @@ message BatchUpdateAppHealthResponse {}
 message Startup {
 	string version = 1;
 	string expanded_directory = 2;
-	repeated string subsystems = 3;
+	enum Subsystem {
+		SUBSYSTEM_UNSPECIFIED = 0;
+		ENVBOX = 1;
+		ENVBUILDER = 2;
+		EXECTRACE = 3;
+	}
+	repeated Subsystem subsystems = 3;
 }
 
 message UpdateStartupRequest{
@@ -162,10 +221,7 @@ message UpdateStartupRequest{
 
 message Metadata {
 	string key = 1;
-	google.protobuf.Timestamp collected_at = 2;
-	int64 age = 3;
-	string value = 4;
-	string error = 5;
+	WorkspaceAgentMetadata.Result result = 2;
 }
 
 message BatchUpdateMetadataRequest {
@@ -190,11 +246,54 @@ message Log {
 }
 
 message BatchCreateLogsRequest {
-	bytes source_id = 1;
+	bytes log_source_id = 1;
 	repeated Log logs = 2;
 }
 
-message BatchCreateLogsResponse {}
+message BatchCreateLogsResponse {
+	bool log_limit_exceeded = 1;
+}
+
+message GetAnnouncementBannersRequest {}
+
+message GetAnnouncementBannersResponse {
+	repeated BannerConfig announcement_banners = 1;
+}
+
+message BannerConfig {
+	bool enabled = 1;
+	string message = 2;
+	string background_color = 3;
+}
+
+message WorkspaceAgentScriptCompletedRequest {
+    Timing timing = 1;
+}
+
+message WorkspaceAgentScriptCompletedResponse {
+}
+
+message Timing {
+    bytes script_id = 1;
+    google.protobuf.Timestamp start = 2;
+    google.protobuf.Timestamp end = 3;
+    int32 exit_code = 4;
+
+    enum Stage {
+        START = 0;
+        STOP = 1;
+        CRON = 2;
+	}
+    Stage stage = 5;
+
+    enum Status {
+        OK = 0;
+        EXIT_FAILURE = 1;
+        TIMED_OUT = 2;
+        PIPES_LEFT_OPEN = 3;
+    }
+    Status status = 6;
+}
 
 service Agent {
 	rpc GetManifest(GetManifestRequest) returns (Manifest);
@@ -205,7 +304,6 @@ service Agent {
 	rpc UpdateStartup(UpdateStartupRequest) returns (Startup);
 	rpc BatchUpdateMetadata(BatchUpdateMetadataRequest) returns (BatchUpdateMetadataResponse);
 	rpc BatchCreateLogs(BatchCreateLogsRequest) returns (BatchCreateLogsResponse);
-
-	rpc StreamDERPMaps(tailnet.v2.StreamDERPMapsRequest) returns (stream tailnet.v2.DERPMap);
-	rpc CoordinateTailnet(stream tailnet.v2.CoordinateRequest) returns (stream tailnet.v2.CoordinateResponse);
+	rpc GetAnnouncementBanners(GetAnnouncementBannersRequest) returns (GetAnnouncementBannersResponse);
+	rpc ScriptCompleted(WorkspaceAgentScriptCompletedRequest) returns (WorkspaceAgentScriptCompletedResponse);
 }

agent/proto/agent_drpc.pb.go

@@ -7,7 +7,6 @@ package proto
 import (
 	context "context"
 	errors "errors"
-	proto1 "github.com/coder/coder/v2/tailnet/proto"
 	protojson "google.golang.org/protobuf/encoding/protojson"
 	proto "google.golang.org/protobuf/proto"
 	drpc "storj.io/drpc"
@@ -47,8 +46,8 @@ type DRPCAgentClient interface {
 	UpdateStartup(ctx context.Context, in *UpdateStartupRequest) (*Startup, error)
 	BatchUpdateMetadata(ctx context.Context, in *BatchUpdateMetadataRequest) (*BatchUpdateMetadataResponse, error)
 	BatchCreateLogs(ctx context.Context, in *BatchCreateLogsRequest) (*BatchCreateLogsResponse, error)
-	StreamDERPMaps(ctx context.Context, in *proto1.StreamDERPMapsRequest) (DRPCAgent_StreamDERPMapsClient, error)
-	CoordinateTailnet(ctx context.Context) (DRPCAgent_CoordinateTailnetClient, error)
+	GetAnnouncementBanners(ctx context.Context, in *GetAnnouncementBannersRequest) (*GetAnnouncementBannersResponse, error)
+	ScriptCompleted(ctx context.Context, in *WorkspaceAgentScriptCompletedRequest) (*WorkspaceAgentScriptCompletedResponse, error)
 }
 
 type drpcAgentClient struct {
@@ -133,83 +132,22 @@ func (c *drpcAgentClient) BatchCreateLogs(ctx context.Context, in *BatchCreateLo
 	return out, nil
 }
 
-func (c *drpcAgentClient) StreamDERPMaps(ctx context.Context, in *proto1.StreamDERPMapsRequest) (DRPCAgent_StreamDERPMapsClient, error) {
-	stream, err := c.cc.NewStream(ctx, "/coder.agent.v2.Agent/StreamDERPMaps", drpcEncoding_File_agent_proto_agent_proto{})
+func (c *drpcAgentClient) GetAnnouncementBanners(ctx context.Context, in *GetAnnouncementBannersRequest) (*GetAnnouncementBannersResponse, error) {
+	out := new(GetAnnouncementBannersResponse)
+	err := c.cc.Invoke(ctx, "/coder.agent.v2.Agent/GetAnnouncementBanners", drpcEncoding_File_agent_proto_agent_proto{}, in, out)
 	if err != nil {
 		return nil, err
 	}
-	x := &drpcAgent_StreamDERPMapsClient{stream}
-	if err := x.MsgSend(in, drpcEncoding_File_agent_proto_agent_proto{}); err != nil {
-		return nil, err
-	}
-	if err := x.CloseSend(); err != nil {
-		return nil, err
-	}
-	return x, nil
+	return out, nil
 }
 
-type DRPCAgent_StreamDERPMapsClient interface {
-	drpc.Stream
-	Recv() (*proto1.DERPMap, error)
-}
-
-type drpcAgent_StreamDERPMapsClient struct {
-	drpc.Stream
-}
-
-func (x *drpcAgent_StreamDERPMapsClient) GetStream() drpc.Stream {
-	return x.Stream
-}
-
-func (x *drpcAgent_StreamDERPMapsClient) Recv() (*proto1.DERPMap, error) {
-	m := new(proto1.DERPMap)
-	if err := x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{}); err != nil {
-		return nil, err
-	}
-	return m, nil
-}
-
-func (x *drpcAgent_StreamDERPMapsClient) RecvMsg(m *proto1.DERPMap) error {
-	return x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{})
-}
-
-func (c *drpcAgentClient) CoordinateTailnet(ctx context.Context) (DRPCAgent_CoordinateTailnetClient, error) {
-	stream, err := c.cc.NewStream(ctx, "/coder.agent.v2.Agent/CoordinateTailnet", drpcEncoding_File_agent_proto_agent_proto{})
+func (c *drpcAgentClient) ScriptCompleted(ctx context.Context, in *WorkspaceAgentScriptCompletedRequest) (*WorkspaceAgentScriptCompletedResponse, error) {
+	out := new(WorkspaceAgentScriptCompletedResponse)
+	err := c.cc.Invoke(ctx, "/coder.agent.v2.Agent/ScriptCompleted", drpcEncoding_File_agent_proto_agent_proto{}, in, out)
 	if err != nil {
 		return nil, err
 	}
-	x := &drpcAgent_CoordinateTailnetClient{stream}
-	return x, nil
-}
-
-type DRPCAgent_CoordinateTailnetClient interface {
-	drpc.Stream
-	Send(*proto1.CoordinateRequest) error
-	Recv() (*proto1.CoordinateResponse, error)
-}
-
-type drpcAgent_CoordinateTailnetClient struct {
-	drpc.Stream
-}
-
-func (x *drpcAgent_CoordinateTailnetClient) GetStream() drpc.Stream {
-	return x.Stream
-}
-
-func (x *drpcAgent_CoordinateTailnetClient) Send(m *proto1.CoordinateRequest) error {
-	return x.MsgSend(m, drpcEncoding_File_agent_proto_agent_proto{})
-}
-
-func (x *drpcAgent_CoordinateTailnetClient) Recv() (*proto1.CoordinateResponse, error) {
-	m := new(proto1.CoordinateResponse)
-	if err := x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{}); err != nil {
-		return nil, err
-	}
-	return m, nil
-}
-
-func (x *drpcAgent_CoordinateTailnetClient) RecvMsg(m *proto1.CoordinateResponse) error {
-	return x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{})
+	return out, nil
 }
 
 type DRPCAgentServer interface {
@@ -221,8 +159,8 @@ type DRPCAgentServer interface {
 	UpdateStartup(context.Context, *UpdateStartupRequest) (*Startup, error)
 	BatchUpdateMetadata(context.Context, *BatchUpdateMetadataRequest) (*BatchUpdateMetadataResponse, error)
 	BatchCreateLogs(context.Context, *BatchCreateLogsRequest) (*BatchCreateLogsResponse, error)
-	StreamDERPMaps(*proto1.StreamDERPMapsRequest, DRPCAgent_StreamDERPMapsStream) error
-	CoordinateTailnet(DRPCAgent_CoordinateTailnetStream) error
+	GetAnnouncementBanners(context.Context, *GetAnnouncementBannersRequest) (*GetAnnouncementBannersResponse, error)
+	ScriptCompleted(context.Context, *WorkspaceAgentScriptCompletedRequest) (*WorkspaceAgentScriptCompletedResponse, error)
 }
 
 type DRPCAgentUnimplementedServer struct{}
@@ -259,12 +197,12 @@ func (s *DRPCAgentUnimplementedServer) BatchCreateLogs(context.Context, *BatchCr
 	return nil, drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
 }
 
-func (s *DRPCAgentUnimplementedServer) StreamDERPMaps(*proto1.StreamDERPMapsRequest, DRPCAgent_StreamDERPMapsStream) error {
-	return drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
+func (s *DRPCAgentUnimplementedServer) GetAnnouncementBanners(context.Context, *GetAnnouncementBannersRequest) (*GetAnnouncementBannersResponse, error) {
+	return nil, drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
 }
 
-func (s *DRPCAgentUnimplementedServer) CoordinateTailnet(DRPCAgent_CoordinateTailnetStream) error {
-	return drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
+func (s *DRPCAgentUnimplementedServer) ScriptCompleted(context.Context, *WorkspaceAgentScriptCompletedRequest) (*WorkspaceAgentScriptCompletedResponse, error) {
+	return nil, drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
 }
 
 type DRPCAgentDescription struct{}
@@ -346,22 +284,23 @@ func (DRPCAgentDescription) Method(n int) (string, drpc.Encoding, drpc.Receiver,
 					)
 			}, DRPCAgentServer.BatchCreateLogs, true
 	case 8:
-		return "/coder.agent.v2.Agent/StreamDERPMaps", drpcEncoding_File_agent_proto_agent_proto{},
+		return "/coder.agent.v2.Agent/GetAnnouncementBanners", drpcEncoding_File_agent_proto_agent_proto{},
 			func(srv interface{}, ctx context.Context, in1, in2 interface{}) (drpc.Message, error) {
-				return nil, srv.(DRPCAgentServer).
-					StreamDERPMaps(
-						in1.(*proto1.StreamDERPMapsRequest),
-						&drpcAgent_StreamDERPMapsStream{in2.(drpc.Stream)},
+				return srv.(DRPCAgentServer).
+					GetAnnouncementBanners(
+						ctx,
+						in1.(*GetAnnouncementBannersRequest),
 					)
-			}, DRPCAgentServer.StreamDERPMaps, true
+			}, DRPCAgentServer.GetAnnouncementBanners, true
 	case 9:
-		return "/coder.agent.v2.Agent/CoordinateTailnet", drpcEncoding_File_agent_proto_agent_proto{},
+		return "/coder.agent.v2.Agent/ScriptCompleted", drpcEncoding_File_agent_proto_agent_proto{},
 			func(srv interface{}, ctx context.Context, in1, in2 interface{}) (drpc.Message, error) {
-				return nil, srv.(DRPCAgentServer).
-					CoordinateTailnet(
-						&drpcAgent_CoordinateTailnetStream{in1.(drpc.Stream)},
+				return srv.(DRPCAgentServer).
+					ScriptCompleted(
+						ctx,
+						in1.(*WorkspaceAgentScriptCompletedRequest),
 					)
-			}, DRPCAgentServer.CoordinateTailnet, true
+			}, DRPCAgentServer.ScriptCompleted, true
 	default:
 		return "", nil, nil, nil, false
 	}
@@ -499,41 +438,34 @@ func (x *drpcAgent_BatchCreateLogsStream) SendAndClose(m *BatchCreateLogsRespons
 	return x.CloseSend()
 }
 
-type DRPCAgent_StreamDERPMapsStream interface {
+type DRPCAgent_GetAnnouncementBannersStream interface {
 	drpc.Stream
-	Send(*proto1.DERPMap) error
+	SendAndClose(*GetAnnouncementBannersResponse) error
 }
 
-type drpcAgent_StreamDERPMapsStream struct {
+type drpcAgent_GetAnnouncementBannersStream struct {
 	drpc.Stream
 }
 
-func (x *drpcAgent_StreamDERPMapsStream) Send(m *proto1.DERPMap) error {
-	return x.MsgSend(m, drpcEncoding_File_agent_proto_agent_proto{})
-}
-
-type DRPCAgent_CoordinateTailnetStream interface {
-	drpc.Stream
-	Send(*proto1.CoordinateResponse) error
-	Recv() (*proto1.CoordinateRequest, error)
-}
-
-type drpcAgent_CoordinateTailnetStream struct {
-	drpc.Stream
-}
-
-func (x *drpcAgent_CoordinateTailnetStream) Send(m *proto1.CoordinateResponse) error {
-	return x.MsgSend(m, drpcEncoding_File_agent_proto_agent_proto{})
-}
-
-func (x *drpcAgent_CoordinateTailnetStream) Recv() (*proto1.CoordinateRequest, error) {
-	m := new(proto1.CoordinateRequest)
-	if err := x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{}); err != nil {
-		return nil, err
+func (x *drpcAgent_GetAnnouncementBannersStream) SendAndClose(m *GetAnnouncementBannersResponse) error {
+	if err := x.MsgSend(m, drpcEncoding_File_agent_proto_agent_proto{}); err != nil {
+		return err
 	}
-	return m, nil
+	return x.CloseSend()
 }
 
-func (x *drpcAgent_CoordinateTailnetStream) RecvMsg(m *proto1.CoordinateRequest) error {
-	return x.MsgRecv(m, drpcEncoding_File_agent_proto_agent_proto{})
+type DRPCAgent_ScriptCompletedStream interface {
+	drpc.Stream
+	SendAndClose(*WorkspaceAgentScriptCompletedResponse) error
+}
+
+type drpcAgent_ScriptCompletedStream struct {
+	drpc.Stream
+}
+
+func (x *drpcAgent_ScriptCompletedStream) SendAndClose(m *WorkspaceAgentScriptCompletedResponse) error {
+	if err := x.MsgSend(m, drpcEncoding_File_agent_proto_agent_proto{}); err != nil {
+		return err
+	}
+	return x.CloseSend()
 }

agent/proto/agent_drpc_old.go

@@ -0,0 +1,42 @@
+package proto
+
+import (
+	"context"
+
+	"storj.io/drpc"
+)
+
+// DRPCAgentClient20 is the Agent API at v2.0.  Notably, it is missing GetAnnouncementBanners, but
+// is useful when you want to be maximally compatible with Coderd Release Versions from 2.9+
+type DRPCAgentClient20 interface {
+	DRPCConn() drpc.Conn
+
+	GetManifest(ctx context.Context, in *GetManifestRequest) (*Manifest, error)
+	GetServiceBanner(ctx context.Context, in *GetServiceBannerRequest) (*ServiceBanner, error)
+	UpdateStats(ctx context.Context, in *UpdateStatsRequest) (*UpdateStatsResponse, error)
+	UpdateLifecycle(ctx context.Context, in *UpdateLifecycleRequest) (*Lifecycle, error)
+	BatchUpdateAppHealths(ctx context.Context, in *BatchUpdateAppHealthRequest) (*BatchUpdateAppHealthResponse, error)
+	UpdateStartup(ctx context.Context, in *UpdateStartupRequest) (*Startup, error)
+	BatchUpdateMetadata(ctx context.Context, in *BatchUpdateMetadataRequest) (*BatchUpdateMetadataResponse, error)
+	BatchCreateLogs(ctx context.Context, in *BatchCreateLogsRequest) (*BatchCreateLogsResponse, error)
+}
+
+// DRPCAgentClient21 is the Agent API at v2.1. It is useful if you want to be maximally compatible
+// with Coderd Release Versions from 2.12+
+type DRPCAgentClient21 interface {
+	DRPCAgentClient20
+	GetAnnouncementBanners(ctx context.Context, in *GetAnnouncementBannersRequest) (*GetAnnouncementBannersResponse, error)
+}
+
+// DRPCAgentClient22 is the Agent API at v2.2. It is identical to 2.1, since the change was made on
+// the Tailnet API, which uses the same version number. Compatible with Coder v2.13+
+type DRPCAgentClient22 interface {
+	DRPCAgentClient21
+}
+
+// DRPCAgentClient23 is the Agent API at v2.3. It adds the ScriptCompleted RPC. Compatible with
+// Coder v2.18+
+type DRPCAgentClient23 interface {
+	DRPCAgentClient22
+	ScriptCompleted(ctx context.Context, in *WorkspaceAgentScriptCompletedRequest) (*WorkspaceAgentScriptCompletedResponse, error)
+}

agent/proto/compare.go

@@ -0,0 +1,26 @@
+package proto
+
+func LabelsEqual(a, b []*Stats_Metric_Label) bool {
+	am := make(map[string]string, len(a))
+	for _, lbl := range a {
+		v := lbl.GetValue()
+		if v == "" {
+			// Prometheus considers empty labels as equivalent to being absent
+			continue
+		}
+		am[lbl.GetName()] = lbl.GetValue()
+	}
+	lenB := 0
+	for _, lbl := range b {
+		v := lbl.GetValue()
+		if v == "" {
+			// Prometheus considers empty labels as equivalent to being absent
+			continue
+		}
+		lenB++
+		if am[lbl.GetName()] != v {
+			return false
+		}
+	}
+	return len(am) == lenB
+}

agent/proto/compare_test.go

@@ -0,0 +1,77 @@
+package proto_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/agent/proto"
+)
+
+func TestLabelsEqual(t *testing.T) {
+	t.Parallel()
+	for _, tc := range []struct {
+		name string
+		a    []*proto.Stats_Metric_Label
+		b    []*proto.Stats_Metric_Label
+		eq   bool
+	}{
+		{
+			name: "mainlineEq",
+			a: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			b: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			eq: true,
+		},
+		{
+			name: "emptyValue",
+			a: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+				{Name: "singularity", Value: ""},
+			},
+			b: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			eq: true,
+		},
+		{
+			name: "extra",
+			a: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+				{Name: "opacity", Value: "seyshells"},
+			},
+			b: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			eq: false,
+		},
+		{
+			name: "different",
+			a: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "sus"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			b: []*proto.Stats_Metric_Label{
+				{Name: "credulity", Value: "legit"},
+				{Name: "color", Value: "aquamarine"},
+			},
+			eq: false,
+		},
+	} {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			require.Equal(t, tc.eq, proto.LabelsEqual(tc.a, tc.b))
+			require.Equal(t, tc.eq, proto.LabelsEqual(tc.b, tc.a))
+		})
+	}
+}

agent/proto/version.go

@@ -0,0 +1,10 @@
+package proto
+
+import (
+	"github.com/coder/coder/v2/tailnet/proto"
+)
+
+// CurrentVersion is the current version of the agent API.  It is tied to the
+// tailnet API version to avoid confusion, since agents connect to the tailnet
+// API over the same websocket.
+var CurrentVersion = proto.CurrentVersion

agent/reconnectingpty/reconnectingpty.go

@@ -14,8 +14,7 @@ import (
 	"golang.org/x/xerrors"
 
 	"cdr.dev/slog"
-
-	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
 	"github.com/coder/coder/v2/pty"
 )
 
@@ -197,7 +196,7 @@ func (s *ptyState) waitForStateOrContext(ctx context.Context, state State) (Stat
 func readConnLoop(ctx context.Context, conn net.Conn, ptty pty.PTYCmd, metrics *prometheus.CounterVec, logger slog.Logger) {
 	decoder := json.NewDecoder(conn)
 	for {
-		var req codersdk.ReconnectingPTYRequest
+		var req workspacesdk.ReconnectingPTYRequest
 		err := decoder.Decode(&req)
 		if xerrors.Is(err, io.EOF) {
 			return

agent/reconnectingpty/screen.go

@@ -67,8 +67,6 @@ func newScreen(ctx context.Context, cmd *pty.Cmd, options *Options, logger slog.
 		timeout: options.Timeout,
 	}
 
-	go rpty.lifecycle(ctx, logger)
-
 	// Socket paths are limited to around 100 characters on Linux and macOS which
 	// depending on the temporary directory can be a problem.  To give more leeway
 	// use a short ID.
@@ -81,6 +79,13 @@ func newScreen(ctx context.Context, cmd *pty.Cmd, options *Options, logger slog.
 	rpty.id = hex.EncodeToString(buf)
 
 	settings := []string{
+		// Disable the startup message that appears for five seconds.
+		"startup_message off",
+		// Some message are hard-coded, the best we can do is set msgwait to 0
+		// which seems to hide them. This can happen for example if screen shows
+		// the version message when starting up.
+		"msgminwait 0",
+		"msgwait 0",
 		// Tell screen not to handle motion for xterm* terminals which allows
 		// scrolling the terminal via the mouse wheel or scroll bar (by default
 		// screen uses it to cycle through the command history).  There does not
@@ -117,6 +122,8 @@ func newScreen(ctx context.Context, cmd *pty.Cmd, options *Options, logger slog.
 		return rpty
 	}
 
+	go rpty.lifecycle(ctx, logger)
+
 	return rpty
 }
 

agent/reconnectingpty/server.go

@@ -0,0 +1,191 @@
+package reconnectingpty
+
+import (
+	"context"
+	"encoding/binary"
+	"encoding/json"
+	"net"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/prometheus/client_golang/prometheus"
+	"golang.org/x/xerrors"
+
+	"cdr.dev/slog"
+	"github.com/coder/coder/v2/agent/agentssh"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+)
+
+type Server struct {
+	logger           slog.Logger
+	connectionsTotal prometheus.Counter
+	errorsTotal      *prometheus.CounterVec
+	commandCreator   *agentssh.Server
+	connCount        atomic.Int64
+	reconnectingPTYs sync.Map
+	timeout          time.Duration
+}
+
+// NewServer returns a new ReconnectingPTY server
+func NewServer(logger slog.Logger, commandCreator *agentssh.Server,
+	connectionsTotal prometheus.Counter, errorsTotal *prometheus.CounterVec,
+	timeout time.Duration,
+) *Server {
+	return &Server{
+		logger:           logger,
+		commandCreator:   commandCreator,
+		connectionsTotal: connectionsTotal,
+		errorsTotal:      errorsTotal,
+		timeout:          timeout,
+	}
+}
+
+func (s *Server) Serve(ctx, hardCtx context.Context, l net.Listener) (retErr error) {
+	var wg sync.WaitGroup
+	for {
+		if ctx.Err() != nil {
+			break
+		}
+		conn, err := l.Accept()
+		if err != nil {
+			s.logger.Debug(ctx, "accept pty failed", slog.Error(err))
+			retErr = err
+			break
+		}
+		clog := s.logger.With(
+			slog.F("remote", conn.RemoteAddr().String()),
+			slog.F("local", conn.LocalAddr().String()))
+		clog.Info(ctx, "accepted conn")
+		wg.Add(1)
+		closed := make(chan struct{})
+		go func() {
+			select {
+			case <-closed:
+			case <-hardCtx.Done():
+				_ = conn.Close()
+			}
+			wg.Done()
+		}()
+		wg.Add(1)
+		go func() {
+			defer close(closed)
+			defer wg.Done()
+			_ = s.handleConn(ctx, clog, conn)
+		}()
+	}
+	wg.Wait()
+	return retErr
+}
+
+func (s *Server) ConnCount() int64 {
+	return s.connCount.Load()
+}
+
+func (s *Server) handleConn(ctx context.Context, logger slog.Logger, conn net.Conn) (retErr error) {
+	defer conn.Close()
+	s.connectionsTotal.Add(1)
+	s.connCount.Add(1)
+	defer s.connCount.Add(-1)
+
+	// This cannot use a JSON decoder, since that can
+	// buffer additional data that is required for the PTY.
+	rawLen := make([]byte, 2)
+	_, err := conn.Read(rawLen)
+	if err != nil {
+		// logging at info since a single incident isn't too worrying (the client could just have
+		// hung up), but if we get a lot of these we'd want to investigate.
+		logger.Info(ctx, "failed to read AgentReconnectingPTYInit length", slog.Error(err))
+		return nil
+	}
+	length := binary.LittleEndian.Uint16(rawLen)
+	data := make([]byte, length)
+	_, err = conn.Read(data)
+	if err != nil {
+		// logging at info since a single incident isn't too worrying (the client could just have
+		// hung up), but if we get a lot of these we'd want to investigate.
+		logger.Info(ctx, "failed to read AgentReconnectingPTYInit", slog.Error(err))
+		return nil
+	}
+	var msg workspacesdk.AgentReconnectingPTYInit
+	err = json.Unmarshal(data, &msg)
+	if err != nil {
+		logger.Warn(ctx, "failed to unmarshal init", slog.F("raw", data))
+		return nil
+	}
+
+	connectionID := uuid.NewString()
+	connLogger := logger.With(slog.F("message_id", msg.ID), slog.F("connection_id", connectionID))
+	connLogger.Debug(ctx, "starting handler")
+
+	defer func() {
+		if err := retErr; err != nil {
+			// If the context is done, we don't want to log this as an error since it's expected.
+			if ctx.Err() != nil {
+				connLogger.Info(ctx, "reconnecting pty failed with attach error (agent closed)", slog.Error(err))
+			} else {
+				connLogger.Error(ctx, "reconnecting pty failed with attach error", slog.Error(err))
+			}
+		}
+		connLogger.Info(ctx, "reconnecting pty connection closed")
+	}()
+
+	var rpty ReconnectingPTY
+	sendConnected := make(chan ReconnectingPTY, 1)
+	// On store, reserve this ID to prevent multiple concurrent new connections.
+	waitReady, ok := s.reconnectingPTYs.LoadOrStore(msg.ID, sendConnected)
+	if ok {
+		close(sendConnected) // Unused.
+		connLogger.Debug(ctx, "connecting to existing reconnecting pty")
+		c, ok := waitReady.(chan ReconnectingPTY)
+		if !ok {
+			return xerrors.Errorf("found invalid type in reconnecting pty map: %T", waitReady)
+		}
+		rpty, ok = <-c
+		if !ok || rpty == nil {
+			return xerrors.Errorf("reconnecting pty closed before connection")
+		}
+		c <- rpty // Put it back for the next reconnect.
+	} else {
+		connLogger.Debug(ctx, "creating new reconnecting pty")
+
+		connected := false
+		defer func() {
+			if !connected && retErr != nil {
+				s.reconnectingPTYs.Delete(msg.ID)
+				close(sendConnected)
+			}
+		}()
+
+		// Empty command will default to the users shell!
+		cmd, err := s.commandCreator.CreateCommand(ctx, msg.Command, nil)
+		if err != nil {
+			s.errorsTotal.WithLabelValues("create_command").Add(1)
+			return xerrors.Errorf("create command: %w", err)
+		}
+
+		rpty = New(ctx, cmd, &Options{
+			Timeout: s.timeout,
+			Metrics: s.errorsTotal,
+		}, logger.With(slog.F("message_id", msg.ID)))
+
+		done := make(chan struct{})
+		go func() {
+			select {
+			case <-done:
+			case <-ctx.Done():
+				rpty.Close(ctx.Err())
+			}
+		}()
+
+		go func() {
+			rpty.Wait()
+			s.reconnectingPTYs.Delete(msg.ID)
+		}()
+
+		connected = true
+		sendConnected <- rpty
+	}
+	return rpty.Attach(ctx, connectionID, conn, msg.Height, msg.Width, connLogger)
+}

agent/stats.go

@@ -0,0 +1,126 @@
+package agent
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"golang.org/x/xerrors"
+	"tailscale.com/types/netlogtype"
+
+	"cdr.dev/slog"
+	"github.com/coder/coder/v2/agent/proto"
+)
+
+const maxConns = 2048
+
+type networkStatsSource interface {
+	SetConnStatsCallback(maxPeriod time.Duration, maxConns int, dump func(start, end time.Time, virtual, physical map[netlogtype.Connection]netlogtype.Counts))
+}
+
+type statsCollector interface {
+	Collect(ctx context.Context, networkStats map[netlogtype.Connection]netlogtype.Counts) *proto.Stats
+}
+
+type statsDest interface {
+	UpdateStats(ctx context.Context, req *proto.UpdateStatsRequest) (*proto.UpdateStatsResponse, error)
+}
+
+// statsReporter is a subcomponent of the agent that handles registering the stats callback on the
+// networkStatsSource (tailnet.Conn in prod), handling the callback, calling back to the
+// statsCollector (agent in prod) to collect additional stats, then sending the update to the
+// statsDest (agent API in prod)
+type statsReporter struct {
+	*sync.Cond
+	networkStats *map[netlogtype.Connection]netlogtype.Counts
+	unreported   bool
+	lastInterval time.Duration
+
+	source    networkStatsSource
+	collector statsCollector
+	logger    slog.Logger
+}
+
+func newStatsReporter(logger slog.Logger, source networkStatsSource, collector statsCollector) *statsReporter {
+	return &statsReporter{
+		Cond:      sync.NewCond(&sync.Mutex{}),
+		logger:    logger,
+		source:    source,
+		collector: collector,
+	}
+}
+
+func (s *statsReporter) callback(_, _ time.Time, virtual, _ map[netlogtype.Connection]netlogtype.Counts) {
+	s.L.Lock()
+	defer s.L.Unlock()
+	s.logger.Debug(context.Background(), "got stats callback")
+	s.networkStats = &virtual
+	s.unreported = true
+	s.Broadcast()
+}
+
+// reportLoop programs the source (tailnet.Conn) to send it stats via the
+// callback, then reports them to the dest.
+//
+// It's intended to be called within the larger retry loop that establishes a
+// connection to the agent API, then passes that connection to go routines like
+// this that use it.  There is no retry and we fail on the first error since
+// this will be inside a larger retry loop.
+func (s *statsReporter) reportLoop(ctx context.Context, dest statsDest) error {
+	// send an initial, blank report to get the interval
+	resp, err := dest.UpdateStats(ctx, &proto.UpdateStatsRequest{})
+	if err != nil {
+		return xerrors.Errorf("initial update: %w", err)
+	}
+	s.lastInterval = resp.ReportInterval.AsDuration()
+	s.source.SetConnStatsCallback(s.lastInterval, maxConns, s.callback)
+
+	// use a separate goroutine to monitor the context so that we notice immediately, rather than
+	// waiting for the next callback (which might never come if we are closing!)
+	ctxDone := false
+	go func() {
+		<-ctx.Done()
+		s.L.Lock()
+		defer s.L.Unlock()
+		ctxDone = true
+		s.Broadcast()
+	}()
+	defer s.logger.Debug(ctx, "reportLoop exiting")
+
+	s.L.Lock()
+	defer s.L.Unlock()
+	for {
+		for !s.unreported && !ctxDone {
+			s.Wait()
+		}
+		if ctxDone {
+			return nil
+		}
+		networkStats := *s.networkStats
+		s.unreported = false
+		if err = s.reportLocked(ctx, dest, networkStats); err != nil {
+			return xerrors.Errorf("report stats: %w", err)
+		}
+	}
+}
+
+func (s *statsReporter) reportLocked(
+	ctx context.Context, dest statsDest, networkStats map[netlogtype.Connection]netlogtype.Counts,
+) error {
+	// here we want to do our collecting/reporting while it is unlocked, but then relock
+	// when we return to reportLoop.
+	s.L.Unlock()
+	defer s.L.Lock()
+	stats := s.collector.Collect(ctx, networkStats)
+	resp, err := dest.UpdateStats(ctx, &proto.UpdateStatsRequest{Stats: stats})
+	if err != nil {
+		return err
+	}
+	interval := resp.GetReportInterval().AsDuration()
+	if interval != s.lastInterval {
+		s.logger.Info(ctx, "new stats report interval", slog.F("interval", interval))
+		s.lastInterval = interval
+		s.source.SetConnStatsCallback(s.lastInterval, maxConns, s.callback)
+	}
+	return nil
+}

agent/stats_internal_test.go

@@ -0,0 +1,270 @@
+package agent
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/netip"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"google.golang.org/protobuf/types/known/durationpb"
+	"tailscale.com/types/ipproto"
+
+	"tailscale.com/types/netlogtype"
+
+	"cdr.dev/slog"
+	"cdr.dev/slog/sloggers/slogjson"
+	"github.com/coder/coder/v2/agent/proto"
+	"github.com/coder/coder/v2/testutil"
+)
+
+func TestStatsReporter(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+	logger := testutil.Logger(t)
+	fSource := newFakeNetworkStatsSource(ctx, t)
+	fCollector := newFakeCollector(t)
+	fDest := newFakeStatsDest()
+	uut := newStatsReporter(logger, fSource, fCollector)
+
+	loopErr := make(chan error, 1)
+	loopCtx, loopCancel := context.WithCancel(ctx)
+	go func() {
+		err := uut.reportLoop(loopCtx, fDest)
+		loopErr <- err
+	}()
+
+	// initial request to get duration
+	req := testutil.RequireRecvCtx(ctx, t, fDest.reqs)
+	require.NotNil(t, req)
+	require.Nil(t, req.Stats)
+	interval := time.Second * 34
+	testutil.RequireSendCtx(ctx, t, fDest.resps, &proto.UpdateStatsResponse{ReportInterval: durationpb.New(interval)})
+
+	// call to source to set the callback and interval
+	gotInterval := testutil.RequireRecvCtx(ctx, t, fSource.period)
+	require.Equal(t, interval, gotInterval)
+
+	// callback returning netstats
+	netStats := map[netlogtype.Connection]netlogtype.Counts{
+		{
+			Proto: ipproto.TCP,
+			Src:   netip.MustParseAddrPort("192.168.1.33:4887"),
+			Dst:   netip.MustParseAddrPort("192.168.2.99:9999"),
+		}: {
+			TxPackets: 22,
+			TxBytes:   23,
+			RxPackets: 24,
+			RxBytes:   25,
+		},
+	}
+	fSource.callback(time.Now(), time.Now(), netStats, nil)
+
+	// collector called to complete the stats
+	gotNetStats := testutil.RequireRecvCtx(ctx, t, fCollector.calls)
+	require.Equal(t, netStats, gotNetStats)
+
+	// while we are collecting the stats, send in two new netStats to simulate
+	// what happens if we don't keep up.  Only the latest should be kept.
+	netStats0 := map[netlogtype.Connection]netlogtype.Counts{
+		{
+			Proto: ipproto.TCP,
+			Src:   netip.MustParseAddrPort("192.168.1.33:4887"),
+			Dst:   netip.MustParseAddrPort("192.168.2.99:9999"),
+		}: {
+			TxPackets: 10,
+			TxBytes:   10,
+			RxPackets: 10,
+			RxBytes:   10,
+		},
+	}
+	fSource.callback(time.Now(), time.Now(), netStats0, nil)
+	netStats1 := map[netlogtype.Connection]netlogtype.Counts{
+		{
+			Proto: ipproto.TCP,
+			Src:   netip.MustParseAddrPort("192.168.1.33:4887"),
+			Dst:   netip.MustParseAddrPort("192.168.2.99:9999"),
+		}: {
+			TxPackets: 11,
+			TxBytes:   11,
+			RxPackets: 11,
+			RxBytes:   11,
+		},
+	}
+	fSource.callback(time.Now(), time.Now(), netStats1, nil)
+
+	// complete first collection
+	stats := &proto.Stats{SessionCountJetbrains: 55}
+	testutil.RequireSendCtx(ctx, t, fCollector.stats, stats)
+
+	// destination called to report the first stats
+	update := testutil.RequireRecvCtx(ctx, t, fDest.reqs)
+	require.NotNil(t, update)
+	require.Equal(t, stats, update.Stats)
+	testutil.RequireSendCtx(ctx, t, fDest.resps, &proto.UpdateStatsResponse{ReportInterval: durationpb.New(interval)})
+
+	// second update -- only netStats1 is reported
+	gotNetStats = testutil.RequireRecvCtx(ctx, t, fCollector.calls)
+	require.Equal(t, netStats1, gotNetStats)
+	stats = &proto.Stats{SessionCountJetbrains: 66}
+	testutil.RequireSendCtx(ctx, t, fCollector.stats, stats)
+	update = testutil.RequireRecvCtx(ctx, t, fDest.reqs)
+	require.NotNil(t, update)
+	require.Equal(t, stats, update.Stats)
+	interval2 := 27 * time.Second
+	testutil.RequireSendCtx(ctx, t, fDest.resps, &proto.UpdateStatsResponse{ReportInterval: durationpb.New(interval2)})
+
+	// set the new interval
+	gotInterval = testutil.RequireRecvCtx(ctx, t, fSource.period)
+	require.Equal(t, interval2, gotInterval)
+
+	loopCancel()
+	err := testutil.RequireRecvCtx(ctx, t, loopErr)
+	require.NoError(t, err)
+}
+
+type fakeNetworkStatsSource struct {
+	sync.Mutex
+	ctx      context.Context
+	t        testing.TB
+	callback func(start, end time.Time, virtual, physical map[netlogtype.Connection]netlogtype.Counts)
+	period   chan time.Duration
+}
+
+func (f *fakeNetworkStatsSource) SetConnStatsCallback(maxPeriod time.Duration, _ int, dump func(start time.Time, end time.Time, virtual map[netlogtype.Connection]netlogtype.Counts, physical map[netlogtype.Connection]netlogtype.Counts)) {
+	f.Lock()
+	defer f.Unlock()
+	f.callback = dump
+	select {
+	case <-f.ctx.Done():
+		f.t.Error("timeout")
+	case f.period <- maxPeriod:
+		// OK
+	}
+}
+
+func newFakeNetworkStatsSource(ctx context.Context, t testing.TB) *fakeNetworkStatsSource {
+	f := &fakeNetworkStatsSource{
+		ctx:    ctx,
+		t:      t,
+		period: make(chan time.Duration),
+	}
+	return f
+}
+
+type fakeCollector struct {
+	t     testing.TB
+	calls chan map[netlogtype.Connection]netlogtype.Counts
+	stats chan *proto.Stats
+}
+
+func (f *fakeCollector) Collect(ctx context.Context, networkStats map[netlogtype.Connection]netlogtype.Counts) *proto.Stats {
+	select {
+	case <-ctx.Done():
+		f.t.Error("timeout on collect")
+		return nil
+	case f.calls <- networkStats:
+		// ok
+	}
+	select {
+	case <-ctx.Done():
+		f.t.Error("timeout on collect")
+		return nil
+	case s := <-f.stats:
+		return s
+	}
+}
+
+func newFakeCollector(t testing.TB) *fakeCollector {
+	return &fakeCollector{
+		t:     t,
+		calls: make(chan map[netlogtype.Connection]netlogtype.Counts),
+		stats: make(chan *proto.Stats),
+	}
+}
+
+type fakeStatsDest struct {
+	reqs  chan *proto.UpdateStatsRequest
+	resps chan *proto.UpdateStatsResponse
+}
+
+func (f *fakeStatsDest) UpdateStats(ctx context.Context, req *proto.UpdateStatsRequest) (*proto.UpdateStatsResponse, error) {
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	case f.reqs <- req:
+		// OK
+	}
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	case resp := <-f.resps:
+		return resp, nil
+	}
+}
+
+func newFakeStatsDest() *fakeStatsDest {
+	return &fakeStatsDest{
+		reqs:  make(chan *proto.UpdateStatsRequest),
+		resps: make(chan *proto.UpdateStatsResponse),
+	}
+}
+
+func Test_logDebouncer(t *testing.T) {
+	t.Parallel()
+
+	var (
+		buf    bytes.Buffer
+		logger = slog.Make(slogjson.Sink(&buf))
+		ctx    = context.Background()
+	)
+
+	debouncer := &logDebouncer{
+		logger:   logger,
+		messages: map[string]time.Time{},
+		interval: time.Minute,
+	}
+
+	fields := map[string]interface{}{
+		"field_1": float64(1),
+		"field_2": "2",
+	}
+
+	debouncer.Error(ctx, "my message", "field_1", 1, "field_2", "2")
+	debouncer.Warn(ctx, "another message", "field_1", 1, "field_2", "2")
+	// Shouldn't log this.
+	debouncer.Warn(ctx, "another message", "field_1", 1, "field_2", "2")
+
+	require.Len(t, debouncer.messages, 2)
+
+	type entry struct {
+		Msg    string                 `json:"msg"`
+		Level  string                 `json:"level"`
+		Fields map[string]interface{} `json:"fields"`
+	}
+
+	assertLog := func(msg string, level string, fields map[string]interface{}) {
+		line, err := buf.ReadString('\n')
+		require.NoError(t, err)
+
+		var e entry
+		err = json.Unmarshal([]byte(line), &e)
+		require.NoError(t, err)
+		require.Equal(t, msg, e.Msg)
+		require.Equal(t, level, e.Level)
+		require.Equal(t, fields, e.Fields)
+	}
+	assertLog("my message", "ERROR", fields)
+	assertLog("another message", "WARN", fields)
+
+	debouncer.messages["another message"] = time.Now().Add(-2 * time.Minute)
+	debouncer.Warn(ctx, "another message", "field_1", 1, "field_2", "2")
+	assertLog("another message", "WARN", fields)
+	// Assert nothing else was written.
+	_, err := buf.ReadString('\n')
+	require.ErrorIs(t, err, io.EOF)
+}

apiversion/apiversion.go

@@ -0,0 +1,89 @@
+package apiversion
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	"golang.org/x/xerrors"
+)
+
+// New returns an *APIVersion with the given major.minor and
+// additional supported major versions.
+func New(maj, min int) *APIVersion {
+	v := &APIVersion{
+		supportedMajor:   maj,
+		supportedMinor:   min,
+		additionalMajors: make([]int, 0),
+	}
+	return v
+}
+
+type APIVersion struct {
+	supportedMajor   int
+	supportedMinor   int
+	additionalMajors []int
+}
+
+func (v *APIVersion) WithBackwardCompat(majs ...int) *APIVersion {
+	v.additionalMajors = append(v.additionalMajors, majs...)
+	return v
+}
+
+func (v *APIVersion) String() string {
+	return fmt.Sprintf("%d.%d", v.supportedMajor, v.supportedMinor)
+}
+
+// Validate validates the given version against the given constraints:
+// A given major.minor version is valid iff:
+//  1. The requested major version is contained within v.supportedMajors
+//  2. If the requested major version is the 'current major', then
+//     the requested minor version must be less than or equal to the supported
+//     minor version.
+//
+// For example, given majors {1, 2} and minor 2, then:
+// - 0.x is not supported,
+// - 1.x is supported,
+// - 2.0, 2.1, and 2.2 are supported,
+// - 2.3+ is not supported.
+func (v *APIVersion) Validate(version string) error {
+	major, minor, err := Parse(version)
+	if err != nil {
+		return err
+	}
+	if major > v.supportedMajor {
+		return xerrors.Errorf("server is at version %d.%d, behind requested major version %s",
+			v.supportedMajor, v.supportedMinor, version)
+	}
+	if major == v.supportedMajor {
+		if minor > v.supportedMinor {
+			return xerrors.Errorf("server is at version %d.%d, behind requested minor version %s",
+				v.supportedMajor, v.supportedMinor, version)
+		}
+		return nil
+	}
+	for _, mjr := range v.additionalMajors {
+		if major == mjr {
+			return nil
+		}
+	}
+	return xerrors.Errorf("version %s is no longer supported", version)
+}
+
+// Parse parses a valid major.minor version string into (major, minor).
+// Both major and minor must be valid integers separated by a period '.'.
+func Parse(version string) (major int, minor int, err error) {
+	parts := strings.Split(version, ".")
+	if len(parts) != 2 {
+		return 0, 0, xerrors.Errorf("invalid version string: %s", version)
+	}
+	major, err = strconv.Atoi(parts[0])
+	if err != nil {
+		return 0, 0, xerrors.Errorf("invalid major version: %s", version)
+	}
+	minor, err = strconv.Atoi(parts[1])
+	if err != nil {
+		return 0, 0, xerrors.Errorf("invalid minor version: %s", version)
+	}
+	return major, minor, nil
+}

apiversion/apiversion_test.go

@@ -0,0 +1,90 @@
+package apiversion_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/apiversion"
+)
+
+func TestAPIVersionValidate(t *testing.T) {
+	t.Parallel()
+
+	// Given
+	v := apiversion.New(2, 1).WithBackwardCompat(1)
+
+	for _, tc := range []struct {
+		name          string
+		version       string
+		expectedError string
+	}{
+		{
+			name:    "OK",
+			version: "2.1",
+		},
+		{
+			name:    "MinorOK",
+			version: "2.0",
+		},
+		{
+			name:    "MajorOK",
+			version: "1.0",
+		},
+		{
+			name:          "TooNewMinor",
+			version:       "2.2",
+			expectedError: "behind requested minor version",
+		},
+		{
+			name:          "TooNewMajor",
+			version:       "3.1",
+			expectedError: "behind requested major version",
+		},
+		{
+			name:          "Malformed0",
+			version:       "cats",
+			expectedError: "invalid version string",
+		},
+		{
+			name:          "Malformed1",
+			version:       "cats.dogs",
+			expectedError: "invalid major version",
+		},
+		{
+			name:          "Malformed2",
+			version:       "1.dogs",
+			expectedError: "invalid minor version",
+		},
+		{
+			name:          "Malformed3",
+			version:       "1.0.1",
+			expectedError: "invalid version string",
+		},
+		{
+			name:          "Malformed4",
+			version:       "11",
+			expectedError: "invalid version string",
+		},
+		{
+			name:          "TooOld",
+			version:       "0.8",
+			expectedError: "no longer supported",
+		},
+	} {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			// When
+			err := v.Validate(tc.version)
+
+			// Then
+			if tc.expectedError == "" {
+				require.NoError(t, err)
+			} else {
+				require.ErrorContains(t, err, tc.expectedError)
+			}
+		})
+	}
+}

archive/archive.go

@@ -0,0 +1,115 @@
+package archive
+
+import (
+	"archive/tar"
+	"archive/zip"
+	"bytes"
+	"errors"
+	"io"
+	"log"
+	"strings"
+)
+
+// CreateTarFromZip converts the given zipReader to a tar archive.
+func CreateTarFromZip(zipReader *zip.Reader, maxSize int64) ([]byte, error) {
+	var tarBuffer bytes.Buffer
+	err := writeTarArchive(&tarBuffer, zipReader, maxSize)
+	if err != nil {
+		return nil, err
+	}
+	return tarBuffer.Bytes(), nil
+}
+
+func writeTarArchive(w io.Writer, zipReader *zip.Reader, maxSize int64) error {
+	tarWriter := tar.NewWriter(w)
+	defer tarWriter.Close()
+
+	for _, file := range zipReader.File {
+		err := processFileInZipArchive(file, tarWriter, maxSize)
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func processFileInZipArchive(file *zip.File, tarWriter *tar.Writer, maxSize int64) error {
+	fileReader, err := file.Open()
+	if err != nil {
+		return err
+	}
+	defer fileReader.Close()
+
+	err = tarWriter.WriteHeader(&tar.Header{
+		Name:    file.Name,
+		Size:    file.FileInfo().Size(),
+		Mode:    int64(file.Mode()),
+		ModTime: file.Modified,
+		// Note: Zip archives do not store ownership information.
+		Uid: 1000,
+		Gid: 1000,
+	})
+	if err != nil {
+		return err
+	}
+
+	n, err := io.CopyN(tarWriter, fileReader, maxSize)
+	log.Println(file.Name, n, err)
+	if errors.Is(err, io.EOF) {
+		err = nil
+	}
+	return err
+}
+
+// CreateZipFromTar converts the given tarReader to a zip archive.
+func CreateZipFromTar(tarReader *tar.Reader, maxSize int64) ([]byte, error) {
+	var zipBuffer bytes.Buffer
+	err := WriteZip(&zipBuffer, tarReader, maxSize)
+	if err != nil {
+		return nil, err
+	}
+	return zipBuffer.Bytes(), nil
+}
+
+// WriteZip writes the given tarReader to w.
+func WriteZip(w io.Writer, tarReader *tar.Reader, maxSize int64) error {
+	zipWriter := zip.NewWriter(w)
+	defer zipWriter.Close()
+
+	for {
+		tarHeader, err := tarReader.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+
+		if err != nil {
+			return err
+		}
+
+		zipHeader, err := zip.FileInfoHeader(tarHeader.FileInfo())
+		if err != nil {
+			return err
+		}
+		zipHeader.Name = tarHeader.Name
+		// Some versions of unzip do not check the mode on a file entry and
+		// simply assume that entries with a trailing path separator (/) are
+		// directories, and that everything else is a file. Give them a hint.
+		if tarHeader.FileInfo().IsDir() && !strings.HasSuffix(tarHeader.Name, "/") {
+			zipHeader.Name += "/"
+		}
+
+		zipEntry, err := zipWriter.CreateHeader(zipHeader)
+		if err != nil {
+			return err
+		}
+
+		_, err = io.CopyN(zipEntry, tarReader, maxSize)
+		if errors.Is(err, io.EOF) {
+			err = nil
+		}
+		if err != nil {
+			return err
+		}
+	}
+	return nil // don't need to flush as we call `writer.Close()`
+}

archive/archive_test.go

@@ -0,0 +1,166 @@
+package archive_test
+
+import (
+	"archive/tar"
+	"archive/zip"
+	"bytes"
+	"io/fs"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/archive"
+	"github.com/coder/coder/v2/archive/archivetest"
+	"github.com/coder/coder/v2/testutil"
+)
+
+func TestCreateTarFromZip(t *testing.T) {
+	t.Parallel()
+	if runtime.GOOS != "linux" {
+		t.Skip("skipping this test on non-Linux platform")
+	}
+
+	// Read a zip file we prepared earlier
+	ctx := testutil.Context(t, testutil.WaitShort)
+	zipBytes := archivetest.TestZipFileBytes()
+	// Assert invariant
+	archivetest.AssertSampleZipFile(t, zipBytes)
+
+	zr, err := zip.NewReader(bytes.NewReader(zipBytes), int64(len(zipBytes)))
+	require.NoError(t, err, "failed to parse sample zip file")
+
+	tarBytes, err := archive.CreateTarFromZip(zr, int64(len(zipBytes)))
+	require.NoError(t, err, "failed to convert zip to tar")
+
+	archivetest.AssertSampleTarFile(t, tarBytes)
+
+	tempDir := t.TempDir()
+	tempFilePath := filepath.Join(tempDir, "test.tar")
+	err = os.WriteFile(tempFilePath, tarBytes, 0o600)
+	require.NoError(t, err, "failed to write converted tar file")
+
+	cmd := exec.CommandContext(ctx, "tar", "--extract", "--verbose", "--file", tempFilePath, "--directory", tempDir)
+	require.NoError(t, cmd.Run(), "failed to extract converted tar file")
+	assertExtractedFiles(t, tempDir, true)
+}
+
+func TestCreateZipFromTar(t *testing.T) {
+	t.Parallel()
+	if runtime.GOOS != "linux" {
+		t.Skip("skipping this test on non-Linux platform")
+	}
+	t.Run("OK", func(t *testing.T) {
+		t.Parallel()
+		tarBytes := archivetest.TestTarFileBytes()
+
+		tr := tar.NewReader(bytes.NewReader(tarBytes))
+		zipBytes, err := archive.CreateZipFromTar(tr, int64(len(tarBytes)))
+		require.NoError(t, err)
+
+		archivetest.AssertSampleZipFile(t, zipBytes)
+
+		tempDir := t.TempDir()
+		tempFilePath := filepath.Join(tempDir, "test.zip")
+		err = os.WriteFile(tempFilePath, zipBytes, 0o600)
+		require.NoError(t, err, "failed to write converted zip file")
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+		cmd := exec.CommandContext(ctx, "unzip", tempFilePath, "-d", tempDir)
+		require.NoError(t, cmd.Run(), "failed to extract converted zip file")
+
+		assertExtractedFiles(t, tempDir, false)
+	})
+
+	t.Run("MissingSlashInDirectoryHeader", func(t *testing.T) {
+		t.Parallel()
+
+		// Given: a tar archive containing a directory entry that has the directory
+		// mode bit set but the name is missing a trailing slash
+
+		var tarBytes bytes.Buffer
+		tw := tar.NewWriter(&tarBytes)
+		tw.WriteHeader(&tar.Header{
+			Name:     "dir",
+			Typeflag: tar.TypeDir,
+			Size:     0,
+		})
+		require.NoError(t, tw.Flush())
+		require.NoError(t, tw.Close())
+
+		// When: we convert this to a zip
+		tr := tar.NewReader(&tarBytes)
+		zipBytes, err := archive.CreateZipFromTar(tr, int64(tarBytes.Len()))
+		require.NoError(t, err)
+
+		// Then: the resulting zip should contain a corresponding directory
+		zr, err := zip.NewReader(bytes.NewReader(zipBytes), int64(len(zipBytes)))
+		require.NoError(t, err)
+		for _, zf := range zr.File {
+			switch zf.Name {
+			case "dir":
+				require.Fail(t, "missing trailing slash in directory name")
+			case "dir/":
+				require.True(t, zf.Mode().IsDir(), "should be a directory")
+			default:
+				require.Fail(t, "unexpected file in archive")
+			}
+		}
+	})
+}
+
+// nolint:revive // this is a control flag but it's in a unit test
+func assertExtractedFiles(t *testing.T, dir string, checkModePerm bool) {
+	t.Helper()
+
+	_ = filepath.Walk(dir, func(path string, info fs.FileInfo, err error) error {
+		relPath := strings.TrimPrefix(path, dir)
+		switch relPath {
+		case "", "/test.zip", "/test.tar": // ignore
+		case "/test":
+			stat, err := os.Stat(path)
+			assert.NoError(t, err, "failed to stat path %q", path)
+			assert.True(t, stat.IsDir(), "expected path %q to be a directory")
+			if checkModePerm {
+				assert.Equal(t, fs.ModePerm&0o755, stat.Mode().Perm(), "expected mode 0755 on directory")
+			}
+			assert.Equal(t, archivetest.ArchiveRefTime(t).UTC(), stat.ModTime().UTC(), "unexpected modtime of %q", path)
+		case "/test/hello.txt":
+			stat, err := os.Stat(path)
+			assert.NoError(t, err, "failed to stat path %q", path)
+			assert.False(t, stat.IsDir(), "expected path %q to be a file")
+			if checkModePerm {
+				assert.Equal(t, fs.ModePerm&0o644, stat.Mode().Perm(), "expected mode 0644 on file")
+			}
+			bs, err := os.ReadFile(path)
+			assert.NoError(t, err, "failed to read file %q", path)
+			assert.Equal(t, "hello", string(bs), "unexpected content in file %q", path)
+		case "/test/dir":
+			stat, err := os.Stat(path)
+			assert.NoError(t, err, "failed to stat path %q", path)
+			assert.True(t, stat.IsDir(), "expected path %q to be a directory")
+			if checkModePerm {
+				assert.Equal(t, fs.ModePerm&0o755, stat.Mode().Perm(), "expected mode 0755 on directory")
+			}
+		case "/test/dir/world.txt":
+			stat, err := os.Stat(path)
+			assert.NoError(t, err, "failed to stat path %q", path)
+			assert.False(t, stat.IsDir(), "expected path %q to be a file")
+			if checkModePerm {
+				assert.Equal(t, fs.ModePerm&0o644, stat.Mode().Perm(), "expected mode 0644 on file")
+			}
+			bs, err := os.ReadFile(path)
+			assert.NoError(t, err, "failed to read file %q", path)
+			assert.Equal(t, "world", string(bs), "unexpected content in file %q", path)
+		default:
+			assert.Fail(t, "unexpected path", relPath)
+		}
+
+		return nil
+	})
+}

archive/archivetest/archivetest.go

@@ -0,0 +1,113 @@
+package archivetest
+
+import (
+	"archive/tar"
+	"archive/zip"
+	"bytes"
+	_ "embed"
+	"io"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"golang.org/x/xerrors"
+)
+
+//go:embed testdata/test.tar
+var testTarFileBytes []byte
+
+//go:embed testdata/test.zip
+var testZipFileBytes []byte
+
+// TestTarFileBytes returns the content of testdata/test.tar
+func TestTarFileBytes() []byte {
+	return append([]byte{}, testTarFileBytes...)
+}
+
+// TestZipFileBytes returns the content of testdata/test.zip
+func TestZipFileBytes() []byte {
+	return append([]byte{}, testZipFileBytes...)
+}
+
+// AssertSampleTarfile compares the content of tarBytes against testdata/test.tar.
+func AssertSampleTarFile(t *testing.T, tarBytes []byte) {
+	t.Helper()
+
+	tr := tar.NewReader(bytes.NewReader(tarBytes))
+	for {
+		hdr, err := tr.Next()
+		if err != nil {
+			if err == io.EOF {
+				return
+			}
+			require.NoError(t, err)
+		}
+
+		// Note: ignoring timezones here.
+		require.Equal(t, ArchiveRefTime(t).UTC(), hdr.ModTime.UTC())
+
+		switch hdr.Name {
+		case "test/":
+			require.Equal(t, hdr.Typeflag, byte(tar.TypeDir))
+		case "test/hello.txt":
+			require.Equal(t, hdr.Typeflag, byte(tar.TypeReg))
+			bs, err := io.ReadAll(tr)
+			if err != nil && !xerrors.Is(err, io.EOF) {
+				require.NoError(t, err)
+			}
+			require.Equal(t, "hello", string(bs))
+		case "test/dir/":
+			require.Equal(t, hdr.Typeflag, byte(tar.TypeDir))
+		case "test/dir/world.txt":
+			require.Equal(t, hdr.Typeflag, byte(tar.TypeReg))
+			bs, err := io.ReadAll(tr)
+			if err != nil && !xerrors.Is(err, io.EOF) {
+				require.NoError(t, err)
+			}
+			require.Equal(t, "world", string(bs))
+		default:
+			require.Failf(t, "unexpected file in tar", hdr.Name)
+		}
+	}
+}
+
+// AssertSampleZipFile compares the content of zipBytes against testdata/test.zip.
+func AssertSampleZipFile(t *testing.T, zipBytes []byte) {
+	t.Helper()
+
+	zr, err := zip.NewReader(bytes.NewReader(zipBytes), int64(len(zipBytes)))
+	require.NoError(t, err)
+
+	for _, f := range zr.File {
+		// Note: ignoring timezones here.
+		require.Equal(t, ArchiveRefTime(t).UTC(), f.Modified.UTC())
+		switch f.Name {
+		case "test/", "test/dir/":
+			// directory
+		case "test/hello.txt":
+			rc, err := f.Open()
+			require.NoError(t, err)
+			bs, err := io.ReadAll(rc)
+			_ = rc.Close()
+			require.NoError(t, err)
+			require.Equal(t, "hello", string(bs))
+		case "test/dir/world.txt":
+			rc, err := f.Open()
+			require.NoError(t, err)
+			bs, err := io.ReadAll(rc)
+			_ = rc.Close()
+			require.NoError(t, err)
+			require.Equal(t, "world", string(bs))
+		default:
+			require.Failf(t, "unexpected file in zip", f.Name)
+		}
+	}
+}
+
+// archiveRefTime is the Go reference time. The contents of the sample tar and zip files
+// in testdata/ all have their modtimes set to the below in some timezone.
+func ArchiveRefTime(t *testing.T) time.Time {
+	locMST, err := time.LoadLocation("MST")
+	require.NoError(t, err, "failed to load MST timezone")
+	return time.Date(2006, 1, 2, 3, 4, 5, 0, locMST)
+}