Skip to content

Commit cb82ecc

Browse files
EdwardAngertEdwardAngert
committed
Merge branch 'main' into update-feature-stages
2 parents 21635c8 + d9d2263 commit cb82ecc

File tree

75 files changed

+2915
-574
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

75 files changed

+2915
-574
lines changed

‎.cursorrules

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,25 @@ This project is called "Coder" - an application for managing remote development
44

55
Coder provides a platform for creating, managing, and using remote development environments (also known as Cloud Development Environments or CDEs). It leverages Terraform to define and provision these environments, which are referred to as "workspaces" within the project. The system is designed to be extensible, secure, and provide developers with a seamless remote development experience.
66

7-
# Core Architecture
7+
## Core Architecture
88

99
The heart of Coder is a control plane that orchestrates the creation and management of workspaces. This control plane interacts with separate Provisioner processes over gRPC to handle workspace builds. The Provisioners consume workspace definitions and use Terraform to create the actual infrastructure.
1010

1111
The CLI package serves dual purposes - it can be used to launch the control plane itself and also provides client functionality for users to interact with an existing control plane instance. All user-facing frontend code is developed in TypeScript using React and lives in the `site/` directory.
1212

1313
The database layer uses PostgreSQL with SQLC for generating type-safe database code. Database migrations are carefully managed to ensure both forward and backward compatibility through paired `.up.sql` and `.down.sql` files.
1414

15-
# API Design
15+
## API Design
1616

1717
Coder's API architecture combines REST and gRPC approaches. The REST API is defined in `coderd/coderd.go` and uses Chi for HTTP routing. This provides the primary interface for the frontend and external integrations.
1818

1919
Internal communication with Provisioners occurs over gRPC, with service definitions maintained in `.proto` files. This separation allows for efficient binary communication with the components responsible for infrastructure management while providing a standard REST interface for human-facing applications.
2020

21-
# Network Architecture
21+
## Network Architecture
2222

2323
Coder implements a secure networking layer based on Tailscale's Wireguard implementation. The `tailnet` package provides connectivity between workspace agents and clients through DERP (Designated Encrypted Relay for Packets) servers when direct connections aren't possible. This creates a secure overlay network allowing access to workspaces regardless of network topology, firewalls, or NAT configurations.
2424

25-
## Tailnet and DERP System
25+
### Tailnet and DERP System
2626

2727
The networking system has three key components:
2828

@@ -35,7 +35,7 @@ The networking system has three key components:
3535

3636
3. **Direct Connections**: When possible, the system establishes peer-to-peer connections between clients and workspaces using STUN for NAT traversal. This requires both endpoints to send UDP traffic on ephemeral ports.
3737

38-
## Workspace Proxies
38+
### Workspace Proxies
3939

4040
Workspace proxies (in the Enterprise edition) provide regional relay points for browser-based connections, reducing latency for geo-distributed teams. Key characteristics:
4141

@@ -45,9 +45,10 @@ Workspace proxies (in the Enterprise edition) provide regional relay points for
4545
- Managed through the `coder wsproxy` commands
4646
- Implemented primarily in the `enterprise/wsproxy/` package
4747

48-
# Agent System
48+
## Agent System
4949

5050
The workspace agent runs within each provisioned workspace and provides core functionality including:
51+
5152
- SSH access to workspaces via the `agentssh` package
5253
- Port forwarding
5354
- Terminal connectivity via the `pty` package for pseudo-terminal support
@@ -57,7 +58,7 @@ The workspace agent runs within each provisioned workspace and provides core fun
5758

5859
Agents communicate with the control plane using the tailnet system and authenticate using secure tokens.
5960

60-
# Workspace Applications
61+
## Workspace Applications
6162

6263
Workspace applications (or "apps") provide browser-based access to services running within workspaces. The system supports:
6364

@@ -69,17 +70,17 @@ Workspace applications (or "apps") provide browser-based access to services runn
6970

7071
The implementation is primarily in the `coderd/workspaceapps/` directory with components for URL generation, proxying connections, and managing application state.
7172

72-
# Implementation Details
73+
## Implementation Details
7374

7475
The project structure separates frontend and backend concerns. React components and pages are organized in the `site/src/` directory, with Jest used for testing. The backend is primarily written in Go, with a strong emphasis on error handling patterns and test coverage.
7576

7677
Database interactions are carefully managed through migrations in `coderd/database/migrations/` and queries in `coderd/database/queries/`. All new queries require proper database authorization (dbauthz) implementation to ensure that only users with appropriate permissions can access specific resources.
7778

78-
# Authorization System
79+
## Authorization System
7980

8081
The database authorization (dbauthz) system enforces fine-grained access control across all database operations. It uses role-based access control (RBAC) to validate user permissions before executing database operations. The `dbauthz` package wraps the database store and performs authorization checks before returning data. All database operations must pass through this layer to ensure security.
8182

82-
# Testing Framework
83+
## Testing Framework
8384

8485
The codebase has a comprehensive testing approach with several key components:
8586

@@ -91,7 +92,7 @@ The codebase has a comprehensive testing approach with several key components:
9192

9293
4. **Enterprise Testing**: Enterprise features have dedicated test utilities in the `coderdenttest` package.
9394

94-
# Open Source and Enterprise Components
95+
## Open Source and Enterprise Components
9596

9697
The repository contains both open source and enterprise components:
9798

@@ -100,9 +101,10 @@ The repository contains both open source and enterprise components:
100101
- The boundary between open source and enterprise is managed through a licensing system
101102
- The same core codebase supports both editions, with enterprise features conditionally enabled
102103

103-
# Development Philosophy
104+
## Development Philosophy
104105

105106
Coder emphasizes clear error handling, with specific patterns required:
107+
106108
- Concise error messages that avoid phrases like "failed to"
107109
- Wrapping errors with `%w` to maintain error chains
108110
- Using sentinel errors with the "err" prefix (e.g., `errNotFound`)
@@ -111,7 +113,7 @@ All tests should run in parallel using `t.Parallel()` to ensure efficient testin
111113

112114
Git contributions follow a standard format with commit messages structured as `type: <message>`, where type is one of `feat`, `fix`, or `chore`.
113115

114-
# Development Workflow
116+
## Development Workflow
115117

116118
Development can be initiated using `scripts/develop.sh` to start the application after making changes. Database schema updates should be performed through the migration system using `create_migration.sh <name>` to generate migration files, with each `.up.sql` migration paired with a corresponding `.down.sql` that properly reverts all changes.
117119

‎CLAUDE.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Coder Development Guidelines
2+
3+
Read [cursor rules](.cursorrules).
4+
5+
## Build/Test/Lint Commands
6+
7+
### Main Commands
8+
9+
- `make build` or `make build-fat` - Build all "fat" binaries (includes "server" functionality)
10+
- `make build-slim` - Build "slim" binaries
11+
- `make test` - Run Go tests
12+
- `make test RUN=TestFunctionName` or `go test -v ./path/to/package -run TestFunctionName` - Test single
13+
- `make test-postgres` - Run tests with Postgres database
14+
- `make test-race` - Run tests with Go race detector
15+
- `make test-e2e` - Run end-to-end tests
16+
- `make lint` - Run all linters
17+
- `make fmt` - Format all code
18+
- `make gen` - Generates mocks, database queries and other auto-generated files
19+
20+
### Frontend Commands (site directory)
21+
22+
- `pnpm build` - Build frontend
23+
- `pnpm dev` - Run development server
24+
- `pnpm check` - Run code checks
25+
- `pnpm format` - Format frontend code
26+
- `pnpm lint` - Lint frontend code
27+
- `pnpm test` - Run frontend tests
28+
29+
## Code Style Guidelines
30+
31+
### Go
32+
33+
- Follow [Effective Go](https://go.dev/doc/effective_go) and [Go's Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
34+
- Use `gofumpt` for formatting
35+
- Create packages when used during implementation
36+
- Validate abstractions against implementations
37+
38+
### Error Handling
39+
40+
- Use descriptive error messages
41+
- Wrap errors with context
42+
- Propagate errors appropriately
43+
- Use proper error types
44+
- (`xerrors.Errorf("failed to X: %w", err)`)
45+
46+
### Naming
47+
48+
- Use clear, descriptive names
49+
- Abbreviate only when obvious
50+
- Follow Go and TypeScript naming conventions
51+
52+
### Comments
53+
54+
- Document exported functions, types, and non-obvious logic
55+
- Follow JSDoc format for TypeScript
56+
- Use godoc format for Go code
57+
58+
## Commit Style
59+
60+
- Follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
61+
- Format: `type(scope): message`
62+
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
63+
- Keep message titles concise (~70 characters)
64+
- Use imperative, present tense in commit titles
65+
66+
## Database queries
67+
68+
- MUST DO! Any changes to database - adding queries, modifying queries should be done in the `coderd\database\queries\*.sql` files. Use `make gen` to generate necessary changes after.
69+
- MUST DO! Queries are grouped in files relating to context - e.g. `prebuilds.sql`, `users.sql`, `provisionerjobs.sql`.
70+
- After making changes to any `coderd\database\queries\*.sql` files you must run `make gen` to generate respective ORM changes.
71+
72+
## Architecture
73+
74+
### Core Components
75+
76+
- **coderd**: Main API service connecting workspaces, provisioners, and users
77+
- **provisionerd**: Execution context for infrastructure-modifying providers
78+
- **Agents**: Services in remote workspaces providing features like SSH and port forwarding
79+
- **Workspaces**: Cloud resources defined by Terraform
80+
81+
## Sub-modules
82+
83+
### Template System
84+
85+
- Templates define infrastructure for workspaces using Terraform
86+
- Environment variables pass context between Coder and templates
87+
- Official modules extend development environments
88+
89+
### RBAC System
90+
91+
- Permissions defined at site, organization, and user levels
92+
- Object-Action model protects resources
93+
- Built-in roles: owner, member, auditor, templateAdmin
94+
- Permission format: `<sign>?<level>.<object>.<id>.<action>`
95+
96+
### Database
97+
98+
- PostgreSQL 13+ recommended for production
99+
- Migrations managed with `migrate`
100+
- Database authorization through `dbauthz` package
101+
102+
## Frontend
103+
104+
For building Frontend refer to [this document](docs/contributing/frontend.md)

‎cli/testdata/server-config.yaml.golden

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -704,3 +704,7 @@ workspace_prebuilds:
704704
# backoff.
705705
# (default: 1h0m0s, type: duration)
706706
reconciliation_backoff_lookback_period: 1h0m0s
707+
# Maximum number of consecutive failed prebuilds before a preset hits the hard
708+
# limit; disabled when set to zero.
709+
# (default: 3, type: int)
710+
failure_hard_limit: 3

‎coderd/apidoc/docs.go

Lines changed: 8 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎coderd/apidoc/swagger.json

Lines changed: 8 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎coderd/database/dbauthz/dbauthz.go

Lines changed: 49 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ var (
177177
// Unsure why provisionerd needs update and read personal
178178
rbac.ResourceUser.Type: {policy.ActionRead, policy.ActionReadPersonal, policy.ActionUpdatePersonal},
179179
rbac.ResourceWorkspaceDormant.Type: {policy.ActionDelete, policy.ActionRead, policy.ActionUpdate, policy.ActionWorkspaceStop},
180-
rbac.ResourceWorkspace.Type: {policy.ActionDelete, policy.ActionRead, policy.ActionUpdate, policy.ActionWorkspaceStart, policy.ActionWorkspaceStop},
180+
rbac.ResourceWorkspace.Type: {policy.ActionDelete, policy.ActionRead, policy.ActionUpdate, policy.ActionWorkspaceStart, policy.ActionWorkspaceStop, policy.ActionCreateAgent},
181181
rbac.ResourceApiKey.Type: {policy.WildcardSymbol},
182182
// When org scoped provisioner credentials are implemented,
183183
// this can be reduced to read a specific org.
@@ -339,7 +339,7 @@ var (
339339
rbac.ResourceProvisionerDaemon.Type: {policy.ActionCreate, policy.ActionRead, policy.ActionUpdate},
340340
rbac.ResourceUser.Type: rbac.ResourceUser.AvailableActions(),
341341
rbac.ResourceWorkspaceDormant.Type: {policy.ActionUpdate, policy.ActionDelete, policy.ActionWorkspaceStop},
342-
rbac.ResourceWorkspace.Type: {policy.ActionUpdate, policy.ActionDelete, policy.ActionWorkspaceStart, policy.ActionWorkspaceStop, policy.ActionSSH},
342+
rbac.ResourceWorkspace.Type: {policy.ActionUpdate, policy.ActionDelete, policy.ActionWorkspaceStart, policy.ActionWorkspaceStop, policy.ActionSSH, policy.ActionCreateAgent, policy.ActionDeleteAgent},
343343
rbac.ResourceWorkspaceProxy.Type: {policy.ActionCreate, policy.ActionUpdate, policy.ActionDelete},
344344
rbac.ResourceDeploymentConfig.Type: {policy.ActionCreate, policy.ActionUpdate, policy.ActionDelete},
345345
rbac.ResourceNotificationMessage.Type: {policy.ActionCreate, policy.ActionRead, policy.ActionUpdate, policy.ActionDelete},
@@ -2226,6 +2226,15 @@ func (q *querier) GetPresetParametersByTemplateVersionID(ctx context.Context, ar
22262226
return q.db.GetPresetParametersByTemplateVersionID(ctx, args)
22272227
}
22282228

2229+
func (q *querier) GetPresetsAtFailureLimit(ctx context.Context, hardLimit int64) ([]database.GetPresetsAtFailureLimitRow, error) {
2230+
// GetPresetsAtFailureLimit returns a list of template version presets that have reached the hard failure limit.
2231+
// Request the same authorization permissions as GetPresetsBackoff, since the methods are similar.
2232+
if err := q.authorizeContext(ctx, policy.ActionViewInsights, rbac.ResourceTemplate.All()); err != nil {
2233+
return nil, err
2234+
}
2235+
return q.db.GetPresetsAtFailureLimit(ctx, hardLimit)
2236+
}
2237+
22292238
func (q *querier) GetPresetsBackoff(ctx context.Context, lookback time.Time) ([]database.GetPresetsBackoffRow, error) {
22302239
// GetPresetsBackoff returns a list of template version presets along with metadata such as the number of failed prebuilds.
22312240
if err := q.authorizeContext(ctx, policy.ActionViewInsights, rbac.ResourceTemplate.All()); err != nil {
@@ -3180,6 +3189,10 @@ func (q *querier) GetWorkspaceByOwnerIDAndName(ctx context.Context, arg database
31803189
return fetch(q.log, q.auth, q.db.GetWorkspaceByOwnerIDAndName)(ctx, arg)
31813190
}
31823191

3192+
func (q *querier) GetWorkspaceByResourceID(ctx context.Context, resourceID uuid.UUID) (database.Workspace, error) {
3193+
return fetch(q.log, q.auth, q.db.GetWorkspaceByResourceID)(ctx, resourceID)
3194+
}
3195+
31833196
func (q *querier) GetWorkspaceByWorkspaceAppID(ctx context.Context, workspaceAppID uuid.UUID) (database.Workspace, error) {
31843197
return fetch(q.log, q.auth, q.db.GetWorkspaceByWorkspaceAppID)(ctx, workspaceAppID)
31853198
}
@@ -3713,9 +3726,24 @@ func (q *querier) InsertWorkspace(ctx context.Context, arg database.InsertWorksp
37133726
}
37143727

37153728
func (q *querier) InsertWorkspaceAgent(ctx context.Context, arg database.InsertWorkspaceAgentParams) (database.WorkspaceAgent, error) {
3716-
if err := q.authorizeContext(ctx, policy.ActionCreate, rbac.ResourceSystem); err != nil {
3729+
// NOTE(DanielleMaywood):
3730+
// Currently, the only way to link a Resource back to a Workspace is by following this chain:
3731+
//
3732+
// WorkspaceResource -> WorkspaceBuild -> Workspace
3733+
//
3734+
// It is possible for this function to be called without there existing
3735+
// a `WorkspaceBuild` to link back to. This means that we want to allow
3736+
// execution to continue if there isn't a workspace found to allow this
3737+
// behavior to continue.
3738+
workspace, err := q.db.GetWorkspaceByResourceID(ctx, arg.ResourceID)
3739+
if err != nil && !errors.Is(err, sql.ErrNoRows) {
3740+
return database.WorkspaceAgent{}, err
3741+
}
3742+
3743+
if err := q.authorizeContext(ctx, policy.ActionCreateAgent, workspace); err != nil {
37173744
return database.WorkspaceAgent{}, err
37183745
}
3746+
37193747
return q.db.InsertWorkspaceAgent(ctx, arg)
37203748
}
37213749

@@ -4182,6 +4210,24 @@ func (q *querier) UpdateOrganizationDeletedByID(ctx context.Context, arg databas
41824210
return deleteQ(q.log, q.auth, q.db.GetOrganizationByID, deleteF)(ctx, arg.ID)
41834211
}
41844212

4213+
func (q *querier) UpdatePresetPrebuildStatus(ctx context.Context, arg database.UpdatePresetPrebuildStatusParams) error {
4214+
preset, err := q.db.GetPresetByID(ctx, arg.PresetID)
4215+
if err != nil {
4216+
return err
4217+
}
4218+
4219+
object := rbac.ResourceTemplate.
4220+
WithID(preset.TemplateID.UUID).
4221+
InOrg(preset.OrganizationID)
4222+
4223+
err = q.authorizeContext(ctx, policy.ActionUpdate, object)
4224+
if err != nil {
4225+
return err
4226+
}
4227+
4228+
return q.db.UpdatePresetPrebuildStatus(ctx, arg)
4229+
}
4230+
41854231
func (q *querier) UpdateProvisionerDaemonLastSeenAt(ctx context.Context, arg database.UpdateProvisionerDaemonLastSeenAtParams) error {
41864232
if err := q.authorizeContext(ctx, policy.ActionUpdate, rbac.ResourceProvisionerDaemon); err != nil {
41874233
return err

0 commit comments

Comments
 (0)