coderd

Documentation

Index

• Constants
• func AuthorizeFilter[O rbac.Objecter](h *HTTPAuthorizer, r *http.Request, action rbac.Action, objects []O) ([]O, error)
• func LatencyCheck() http.HandlerFunc
• func ReadExperiments(log slog.Logger, raw []string) codersdk.Experiments
• type API
  • func New(options *Options) *API
  • func (api *API) Authorize(r *http.Request, action rbac.Action, object rbac.Objecter) bool
  • func (api *API) Close() error
  • func (api *API) CreateInMemoryProvisionerDaemon(ctx context.Context, debounce time.Duration) (client proto.DRPCProvisionerDaemonClient, err error)
  • func (api *API) CreateUser(ctx context.Context, store database.Store, req CreateUserRequest) (database.User, uuid.UUID, error)
  • func (api *API) PrimaryRegion(ctx context.Context) (codersdk.Region, error)
  • func (api *API) PrimaryWorkspaceProxy(ctx context.Context) (database.WorkspaceProxy, error)
  • func (api *API) ValidWorkspaceAppHostname(ctx context.Context, host string, opts ValidWorkspaceAppHostnameOpts) (string, error)
• type CreateUserRequest
• type GithubOAuth2Config
• type GithubOAuth2Team
• type HTTPAuthorizer
  • func (h *HTTPAuthorizer) Authorize(r *http.Request, action rbac.Action, object rbac.Objecter) bool
  • func (h *HTTPAuthorizer) AuthorizeSQLFilter(r *http.Request, action rbac.Action, objectType string) (rbac.PreparedAuthorized, error)
• type OAuthConvertStateClaims
• type OIDCConfig
• type Options
• type ServerTailnet
  • func NewServerTailnet(ctx context.Context, logger slog.Logger, derpServer *derp.Server, ...) (*ServerTailnet, error)
  • func (s *ServerTailnet) AgentConn(ctx context.Context, agentID uuid.UUID) (*codersdk.WorkspaceAgentConn, func(), error)
  • func (s *ServerTailnet) Close() error
  • func (s *ServerTailnet) DialAgentNetConn(ctx context.Context, agentID uuid.UUID, network, addr string) (net.Conn, error)
  • func (s *ServerTailnet) ReverseProxy(targetURL, dashboardURL *url.URL, agentID uuid.UUID) (_ *httputil.ReverseProxy, release func(), _ error)
• type ValidWorkspaceAppHostnameOpts

Constants

const (
	OAuthConvertCookieValue = "coder_oauth_convert_jwt"
)

Functions

func AuthorizeFilter

func AuthorizeFilter[O rbac.Objecter](h *HTTPAuthorizer, r *http.Request, action rbac.Action, objects []O) ([]O, error)

AuthorizeFilter takes a list of objects and returns the filtered list of objects that the user is authorized to perform the given action on. This is faster than calling Authorize() on each object.

func LatencyCheck

func LatencyCheck() http.HandlerFunc

LatencyCheck is an endpoint for the web ui to measure latency with. allowAll allows any Origin to get timing information. The allowAll should only be set in dev modes.

func ReadExperiments

func ReadExperiments(log slog.Logger, raw []string) codersdk.Experiments

nolint:revive

Types

type API

type API struct {

	// DeploymentID is loaded from the database on startup.
	DeploymentID string

	*Options
	// ID is a uniquely generated ID on initialization.
	// This is used to associate objects with a specific
	// Coder API instance, like workspace agents to a
	// specific replica.
	ID                                uuid.UUID
	Auditor                           atomic.Pointer[audit.Auditor]
	WorkspaceClientCoordinateOverride atomic.Pointer[func(rw http.ResponseWriter) bool]
	TailnetCoordinator                atomic.Pointer[tailnet.Coordinator]
	QuotaCommitter                    atomic.Pointer[proto.QuotaCommitter]
	// WorkspaceProxyHostsFn returns the hosts of healthy workspace proxies
	// for header reasons.
	WorkspaceProxyHostsFn atomic.Pointer[func() []string]
	// TemplateScheduleStore is a pointer to an atomic pointer because this is
	// passed to another struct, and we want them all to be the same reference.
	TemplateScheduleStore *atomic.Pointer[schedule.TemplateScheduleStore]
	// UserQuietHoursScheduleStore is a pointer to an atomic pointer for the
	// same reason as TemplateScheduleStore.
	UserQuietHoursScheduleStore *atomic.Pointer[schedule.UserQuietHoursScheduleStore]

	HTTPAuth *HTTPAuthorizer

	// APIHandler serves "/api/v2"
	APIHandler chi.Router
	// RootHandler serves "/"
	RootHandler chi.Router

	// SiteHandler serves static files for the dashboard.
	SiteHandler *site.Handler

	WebsocketWaitMutex sync.Mutex
	WebsocketWaitGroup sync.WaitGroup

	WorkspaceAppsProvider workspaceapps.SignedTokenProvider

	// Experiments contains the list of experiments currently enabled.
	// This is used to gate features that are not yet ready for production.
	Experiments codersdk.Experiments
	// contains filtered or unexported fields
}

func New

func New(options *Options) *API

@securitydefinitions.apiKey CoderSessionToken @in header @name Coder-Session-Token New constructs a Coder API handler.

func (*API) Authorize

func (api *API) Authorize(r *http.Request, action rbac.Action, object rbac.Objecter) bool

Authorize will return false if the user is not authorized to do the action. This function will log appropriately, but the caller must return an error to the api client. Eg:

if !api.Authorize(...) {
	httpapi.Forbidden(rw)
	return
}

func (*API) Close

func (api *API) Close() error

Close waits for all WebSocket connections to drain before returning.

func (*API) CreateInMemoryProvisionerDaemon

func (api *API) CreateInMemoryProvisionerDaemon(ctx context.Context, debounce time.Duration) (client proto.DRPCProvisionerDaemonClient, err error)

CreateInMemoryProvisionerDaemon is an in-memory connection to a provisionerd. Useful when starting coderd and provisionerd in the same process.

func (*API) CreateUser

func (api *API) CreateUser(ctx context.Context, store database.Store, req CreateUserRequest) (database.User, uuid.UUID, error)

func (*API) PrimaryRegion

func (api *API) PrimaryRegion(ctx context.Context) (codersdk.Region, error)

PrimaryRegion exposes the user facing values of a workspace proxy to be used by a user.

func (*API) PrimaryWorkspaceProxy

func (api *API) PrimaryWorkspaceProxy(ctx context.Context) (database.WorkspaceProxy, error)

PrimaryWorkspaceProxy returns the primary workspace proxy for the site.

func (*API) ValidWorkspaceAppHostname

func (api *API) ValidWorkspaceAppHostname(ctx context.Context, host string, opts ValidWorkspaceAppHostnameOpts) (string, error)

ValidWorkspaceAppHostname checks if the given host is a valid workspace app hostname based on the provided options. It returns a scheme to force on success. If the hostname is not valid or doesn't match, an empty string is returned. Any error returned is a 500 error.

For hosts that match a wildcard app hostname, the scheme is forced to be the corresponding access URL scheme.

type CreateUserRequest

type CreateUserRequest struct {
	codersdk.CreateUserRequest
	CreateOrganization bool
	LoginType          database.LoginType
}

type GithubOAuth2Config

type GithubOAuth2Config struct {
	httpmw.OAuth2Config
	AuthenticatedUser           func(ctx context.Context, client *http.Client) (*github.User, error)
	ListEmails                  func(ctx context.Context, client *http.Client) ([]*github.UserEmail, error)
	ListOrganizationMemberships func(ctx context.Context, client *http.Client) ([]*github.Membership, error)
	TeamMembership              func(ctx context.Context, client *http.Client, org, team, username string) (*github.Membership, error)

	AllowSignups       bool
	AllowEveryone      bool
	AllowOrganizations []string
	AllowTeams         []GithubOAuth2Team
}

GithubOAuth2Provider exposes required functions for the Github authentication flow.

type GithubOAuth2Team

type GithubOAuth2Team struct {
	Organization string
	Slug         string
}

GithubOAuth2Team represents a team scoped to an organization.

type HTTPAuthorizer

type HTTPAuthorizer struct {
	Authorizer rbac.Authorizer
	Logger     slog.Logger
}

func (*HTTPAuthorizer) Authorize

func (h *HTTPAuthorizer) Authorize(r *http.Request, action rbac.Action, object rbac.Objecter) bool

Authorize will return false if the user is not authorized to do the action. This function will log appropriately, but the caller must return an error to the api client. Eg:

if !h.Authorize(...) {
	httpapi.Forbidden(rw)
	return
}

func (*HTTPAuthorizer) AuthorizeSQLFilter

func (h *HTTPAuthorizer) AuthorizeSQLFilter(r *http.Request, action rbac.Action, objectType string) (rbac.PreparedAuthorized, error)

AuthorizeSQLFilter returns an authorization filter that can used in a SQL 'WHERE' clause. If the filter is used, the resulting rows returned from postgres are already authorized, and the caller does not need to call 'Authorize()' on the returned objects. Note the authorization is only for the given action and object type.

type OAuthConvertStateClaims

type OAuthConvertStateClaims struct {
	jwt.RegisteredClaims

	UserID        uuid.UUID          `json:"user_id"`
	State         string             `json:"state"`
	FromLoginType codersdk.LoginType `json:"from_login_type"`
	ToLoginType   codersdk.LoginType `json:"to_login_type"`
}

type OIDCConfig

type OIDCConfig struct {
	httpmw.OAuth2Config

	Provider *oidc.Provider
	Verifier *oidc.IDTokenVerifier
	// EmailDomains are the domains to enforce when a user authenticates.
	EmailDomain  []string
	AllowSignups bool
	// IgnoreEmailVerified allows ignoring the email_verified claim
	// from an upstream OIDC provider. See #5065 for context.
	IgnoreEmailVerified bool
	// UsernameField selects the claim field to be used as the created user's
	// username.
	UsernameField string
	// EmailField selects the claim field to be used as the created user's
	// email.
	EmailField string
	// AuthURLParams are additional parameters to be passed to the OIDC provider
	// when requesting an access token.
	AuthURLParams map[string]string
	// IgnoreUserInfo causes Coder to only use claims from the ID token to
	// process OIDC logins. This is useful if the OIDC provider does not
	// support the userinfo endpoint, or if the userinfo endpoint causes
	// undesirable behavior.
	IgnoreUserInfo bool
	// GroupField selects the claim field to be used as the created user's
	// groups. If the group field is the empty string, then no group updates
	// will ever come from the OIDC provider.
	GroupField string
	// GroupMapping controls how groups returned by the OIDC provider get mapped
	// to groups within Coder.
	// map[oidcGroupName]coderGroupName
	GroupMapping map[string]string
	// SignInText is the text to display on the OIDC login button
	SignInText string
	// IconURL points to the URL of an icon to display on the OIDC login button
	IconURL string
}

type Options

type Options struct {
	AccessURL *url.URL
	// AppHostname should be the wildcard hostname to use for workspace
	// applications INCLUDING the asterisk, (optional) suffix and leading dot.
	// It will use the same scheme and port number as the access URL.
	// E.g. "*.apps.coder.com" or "*-apps.coder.com".
	AppHostname string
	// AppHostnameRegex contains the regex version of options.AppHostname as
	// generated by httpapi.CompileHostnamePattern(). It MUST be set if
	// options.AppHostname is set.
	AppHostnameRegex *regexp.Regexp
	Logger           slog.Logger
	Database         database.Store
	Pubsub           pubsub.Pubsub

	// CacheDir is used for caching files served by the API.
	CacheDir string

	Auditor                        audit.Auditor
	AgentConnectionUpdateFrequency time.Duration
	AgentInactiveDisconnectTimeout time.Duration
	AWSCertificates                awsidentity.Certificates
	Authorizer                     rbac.Authorizer
	AzureCertificates              x509.VerifyOptions
	GoogleTokenValidator           *idtoken.Validator
	GithubOAuth2Config             *GithubOAuth2Config
	OIDCConfig                     *OIDCConfig
	PrometheusRegistry             *prometheus.Registry
	SecureAuthCookie               bool
	StrictTransportSecurityCfg     httpmw.HSTSConfig
	SSHKeygenAlgorithm             gitsshkey.Algorithm
	Telemetry                      telemetry.Reporter
	TracerProvider                 trace.TracerProvider
	GitAuthConfigs                 []*gitauth.Config
	RealIPConfig                   *httpmw.RealIPConfig
	TrialGenerator                 func(ctx context.Context, email string) error
	// TLSCertificates is used to mesh DERP servers securely.
	TLSCertificates             []tls.Certificate
	TailnetCoordinator          tailnet.Coordinator
	DERPServer                  *derp.Server
	DERPMap                     *tailcfg.DERPMap
	SwaggerEndpoint             bool
	SetUserGroups               func(ctx context.Context, tx database.Store, userID uuid.UUID, groupNames []string) error
	TemplateScheduleStore       *atomic.Pointer[schedule.TemplateScheduleStore]
	UserQuietHoursScheduleStore *atomic.Pointer[schedule.UserQuietHoursScheduleStore]
	// AppSecurityKey is the crypto key used to sign and encrypt tokens related to
	// workspace applications. It consists of both a signing and encryption key.
	AppSecurityKey     workspaceapps.SecurityKey
	HealthcheckFunc    func(ctx context.Context, apiKey string) *healthcheck.Report
	HealthcheckTimeout time.Duration
	HealthcheckRefresh time.Duration

	// OAuthSigningKey is the crypto key used to sign and encrypt state strings
	// related to OAuth. This is a symmetric secret key using hmac to sign payloads.
	// So this secret should **never** be exposed to the client.
	OAuthSigningKey [32]byte

	// APIRateLimit is the minutely throughput rate limit per user or ip.
	// Setting a rate limit <0 will disable the rate limiter across the entire
	// app. Some specific routes have their own configurable rate limits.
	APIRateLimit   int
	LoginRateLimit int
	FilesRateLimit int

	MetricsCacheRefreshInterval time.Duration
	AgentStatsRefreshInterval   time.Duration
	DeploymentValues            *codersdk.DeploymentValues
	UpdateCheckOptions          *updatecheck.Options // Set non-nil to enable update checking.

	// SSHConfig is the response clients use to configure config-ssh locally.
	SSHConfig codersdk.SSHConfigResponse

	HTTPClient *http.Client

	UpdateAgentMetrics func(ctx context.Context, username, workspaceName, agentName string, metrics []agentsdk.AgentMetric)
}

Options are requires parameters for Coder to start.

type ServerTailnet

type ServerTailnet struct {
	// contains filtered or unexported fields
}

func NewServerTailnet

func NewServerTailnet(
	ctx context.Context,
	logger slog.Logger,
	derpServer *derp.Server,
	derpMap *tailcfg.DERPMap,
	getMultiAgent func(context.Context) (tailnet.MultiAgentConn, error),
	cache *wsconncache.Cache,
) (*ServerTailnet, error)

NewServerTailnet creates a new tailnet intended for use by coderd. It automatically falls back to wsconncache if a legacy agent is encountered.

func (*ServerTailnet) AgentConn

func (s *ServerTailnet) AgentConn(ctx context.Context, agentID uuid.UUID) (*codersdk.WorkspaceAgentConn, func(), error)

func (*ServerTailnet) Close

func (s *ServerTailnet) Close() error

func (*ServerTailnet) DialAgentNetConn

func (s *ServerTailnet) DialAgentNetConn(ctx context.Context, agentID uuid.UUID, network, addr string) (net.Conn, error)

func (*ServerTailnet) ReverseProxy

func (s *ServerTailnet) ReverseProxy(targetURL, dashboardURL *url.URL, agentID uuid.UUID) (_ *httputil.ReverseProxy, release func(), _ error)

type ValidWorkspaceAppHostnameOpts

type ValidWorkspaceAppHostnameOpts struct {
	AllowPrimaryAccessURL bool
	AllowPrimaryWildcard  bool
	AllowProxyAccessURL   bool
	AllowProxyWildcard    bool
}