+
+
+
\ No newline at end of file
diff --git a/coderd/notifications/dispatch/smtp/plaintext.gotmpl b/coderd/notifications/dispatch/smtp/plaintext.gotmpl
new file mode 100644
index 0000000000000..ecc60611d04bd
--- /dev/null
+++ b/coderd/notifications/dispatch/smtp/plaintext.gotmpl
@@ -0,0 +1,5 @@
+{{ .Labels._body }}
+
+{{ range $action := .Actions }}
+{{ $action.Label }}: {{ $action.URL }}
+{{ end }}
\ No newline at end of file
diff --git a/coderd/notifications/dispatch/smtp_test.go b/coderd/notifications/dispatch/smtp_test.go
new file mode 100644
index 0000000000000..2605157f2b210
--- /dev/null
+++ b/coderd/notifications/dispatch/smtp_test.go
@@ -0,0 +1,509 @@
+package dispatch_test
+
+import (
+ "bytes"
+ "crypto/tls"
+ _ "embed"
+ "fmt"
+ "log"
+ "net"
+ "sync"
+ "testing"
+
+ "github.com/emersion/go-sasl"
+ "github.com/emersion/go-smtp"
+ "github.com/google/uuid"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+ "go.uber.org/goleak"
+
+ "cdr.dev/slog"
+ "cdr.dev/slog/sloggers/slogtest"
+ "github.com/coder/serpent"
+
+ "github.com/coder/coder/v2/coderd/notifications/dispatch"
+ "github.com/coder/coder/v2/coderd/notifications/types"
+ "github.com/coder/coder/v2/codersdk"
+ "github.com/coder/coder/v2/testutil"
+)
+
+func TestMain(m *testing.M) {
+ goleak.VerifyTestMain(m)
+}
+
+func TestSMTP(t *testing.T) {
+ t.Parallel()
+
+ const (
+ username = "bob"
+ password = "🤫"
+
+ hello = "localhost"
+
+ identity = "robert"
+ from = "system@coder.com"
+ to = "bob@bob.com"
+
+ subject = "This is the subject"
+ body = "This is the body"
+
+ caFile = "fixtures/ca.crt"
+ certFile = "fixtures/server.crt"
+ keyFile = "fixtures/server.key"
+ )
+
+ logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true, IgnoredErrorIs: []error{}}).Leveled(slog.LevelDebug)
+ tests := []struct {
+ name string
+ cfg codersdk.NotificationsEmailConfig
+ toAddrs []string
+ authMechs []string
+ expectedAuthMeth string
+ expectedErr string
+ retryable bool
+ useTLS bool
+ }{
+ /**
+ * LOGIN auth mechanism
+ */
+ {
+ name: "LOGIN auth",
+ authMechs: []string{sasl.Login},
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+
+ Auth: codersdk.NotificationsEmailAuthConfig{
+ Username: username,
+ Password: password,
+ },
+ },
+ toAddrs: []string{to},
+ expectedAuthMeth: sasl.Login,
+ },
+ {
+ name: "invalid LOGIN auth user",
+ authMechs: []string{sasl.Login},
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+
+ Auth: codersdk.NotificationsEmailAuthConfig{
+ Username: username + "-wrong",
+ Password: password,
+ },
+ },
+ toAddrs: []string{to},
+ expectedAuthMeth: sasl.Login,
+ expectedErr: "unknown user",
+ retryable: true,
+ },
+ {
+ name: "invalid LOGIN auth credentials",
+ authMechs: []string{sasl.Login},
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+
+ Auth: codersdk.NotificationsEmailAuthConfig{
+ Username: username,
+ Password: password + "-wrong",
+ },
+ },
+ toAddrs: []string{to},
+ expectedAuthMeth: sasl.Login,
+ expectedErr: "incorrect password",
+ retryable: true,
+ },
+ {
+ name: "password from file",
+ authMechs: []string{sasl.Login},
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+
+ Auth: codersdk.NotificationsEmailAuthConfig{
+ Username: username,
+ PasswordFile: "fixtures/password.txt",
+ },
+ },
+ toAddrs: []string{to},
+ expectedAuthMeth: sasl.Login,
+ },
+ /**
+ * PLAIN auth mechanism
+ */
+ {
+ name: "PLAIN auth",
+ authMechs: []string{sasl.Plain},
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+
+ Auth: codersdk.NotificationsEmailAuthConfig{
+ Identity: identity,
+ Username: username,
+ Password: password,
+ },
+ },
+ toAddrs: []string{to},
+ expectedAuthMeth: sasl.Plain,
+ },
+ {
+ name: "PLAIN auth without identity",
+ authMechs: []string{sasl.Plain},
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+
+ Auth: codersdk.NotificationsEmailAuthConfig{
+ Identity: "",
+ Username: username,
+ Password: password,
+ },
+ },
+ toAddrs: []string{to},
+ expectedAuthMeth: sasl.Plain,
+ },
+ {
+ name: "PLAIN+LOGIN, choose PLAIN",
+ authMechs: []string{sasl.Login, sasl.Plain},
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+
+ Auth: codersdk.NotificationsEmailAuthConfig{
+ Identity: identity,
+ Username: username,
+ Password: password,
+ },
+ },
+ toAddrs: []string{to},
+ expectedAuthMeth: sasl.Plain,
+ },
+ /**
+ * No auth mechanism
+ */
+ {
+ name: "No auth mechanisms supported",
+ authMechs: []string{},
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+
+ Auth: codersdk.NotificationsEmailAuthConfig{
+ Username: username,
+ Password: password,
+ },
+ },
+ toAddrs: []string{to},
+ expectedAuthMeth: "",
+ expectedErr: "no authentication mechanisms supported by server",
+ retryable: false,
+ },
+ {
+ // No auth, no problem!
+ name: "No auth mechanisms supported, none configured",
+ authMechs: []string{},
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+ },
+ toAddrs: []string{to},
+ expectedAuthMeth: "",
+ },
+ /**
+ * TLS connections
+ */
+ {
+ // TLS is forced but certificate used by mock server is untrusted.
+ name: "TLS: x509 untrusted",
+ useTLS: true,
+ expectedErr: "tls: failed to verify certificate",
+ retryable: true,
+ },
+ {
+ // TLS is forced and self-signed certificate used by mock server is not verified.
+ name: "TLS: x509 untrusted ignored",
+ useTLS: true,
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+ ForceTLS: true,
+ TLS: codersdk.NotificationsEmailTLSConfig{
+ InsecureSkipVerify: true,
+ },
+ },
+ toAddrs: []string{to},
+ },
+ {
+ // TLS is forced and STARTTLS is configured, but STARTTLS cannot be used by TLS connections.
+ // STARTTLS should be disabled and connection should succeed.
+ name: "TLS: STARTTLS is ignored",
+ useTLS: true,
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+ TLS: codersdk.NotificationsEmailTLSConfig{
+ InsecureSkipVerify: true,
+ StartTLS: true,
+ },
+ },
+ toAddrs: []string{to},
+ },
+ {
+ // Plain connection is established and upgraded via STARTTLS, but certificate is untrusted.
+ name: "TLS: STARTTLS untrusted",
+ useTLS: false,
+ cfg: codersdk.NotificationsEmailConfig{
+ TLS: codersdk.NotificationsEmailTLSConfig{
+ InsecureSkipVerify: false,
+ StartTLS: true,
+ },
+ ForceTLS: false,
+ },
+ expectedErr: "tls: failed to verify certificate",
+ retryable: true,
+ },
+ {
+ // Plain connection is established and upgraded via STARTTLS, certificate is not verified.
+ name: "TLS: STARTTLS",
+ useTLS: false,
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+ TLS: codersdk.NotificationsEmailTLSConfig{
+ InsecureSkipVerify: true,
+ StartTLS: true,
+ },
+ ForceTLS: false,
+ },
+ toAddrs: []string{to},
+ },
+ {
+ // TLS connection using self-signed certificate.
+ name: "TLS: self-signed",
+ useTLS: true,
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+ TLS: codersdk.NotificationsEmailTLSConfig{
+ CAFile: caFile,
+ CertFile: certFile,
+ KeyFile: keyFile,
+ },
+ },
+ toAddrs: []string{to},
+ },
+ {
+ // TLS connection using self-signed certificate & specifying the DNS name configured in the certificate.
+ name: "TLS: self-signed + SNI",
+ useTLS: true,
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+ TLS: codersdk.NotificationsEmailTLSConfig{
+ ServerName: "myserver.local",
+ CAFile: caFile,
+ CertFile: certFile,
+ KeyFile: keyFile,
+ },
+ },
+ toAddrs: []string{to},
+ },
+ {
+ name: "TLS: load CA",
+ useTLS: true,
+ cfg: codersdk.NotificationsEmailConfig{
+ TLS: codersdk.NotificationsEmailTLSConfig{
+ CAFile: "nope.crt",
+ },
+ },
+ // not using full error message here since it differs on *nix and Windows:
+ // *nix: no such file or directory
+ // Windows: The system cannot find the file specified.
+ expectedErr: "open nope.crt:",
+ retryable: true,
+ },
+ {
+ name: "TLS: load cert",
+ useTLS: true,
+ cfg: codersdk.NotificationsEmailConfig{
+ TLS: codersdk.NotificationsEmailTLSConfig{
+ CAFile: caFile,
+ CertFile: "fixtures/nope.cert",
+ KeyFile: keyFile,
+ },
+ },
+ // not using full error message here since it differs on *nix and Windows:
+ // *nix: no such file or directory
+ // Windows: The system cannot find the file specified.
+ expectedErr: "open fixtures/nope.cert:",
+ retryable: true,
+ },
+ {
+ name: "TLS: load cert key",
+ useTLS: true,
+ cfg: codersdk.NotificationsEmailConfig{
+ TLS: codersdk.NotificationsEmailTLSConfig{
+ CAFile: caFile,
+ CertFile: certFile,
+ KeyFile: "fixtures/nope.key",
+ },
+ },
+ // not using full error message here since it differs on *nix and Windows:
+ // *nix: no such file or directory
+ // Windows: The system cannot find the file specified.
+ expectedErr: "open fixtures/nope.key:",
+ retryable: true,
+ },
+ /**
+ * Kitchen sink
+ */
+ {
+ name: "PLAIN auth and TLS",
+ useTLS: true,
+ authMechs: []string{sasl.Plain},
+ cfg: codersdk.NotificationsEmailConfig{
+ Hello: hello,
+ From: from,
+ Auth: codersdk.NotificationsEmailAuthConfig{
+ Identity: identity,
+ Username: username,
+ Password: password,
+ },
+ TLS: codersdk.NotificationsEmailTLSConfig{
+ CAFile: caFile,
+ CertFile: certFile,
+ KeyFile: keyFile,
+ },
+ },
+ toAddrs: []string{to},
+ expectedAuthMeth: sasl.Plain,
+ },
+ }
+
+ // nolint:paralleltest // Reinitialization is not required as of Go v1.22.
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ ctx := testutil.Context(t, testutil.WaitShort)
+
+ tc.cfg.ForceTLS = serpent.Bool(tc.useTLS)
+
+ backend := NewBackend(Config{
+ AuthMechanisms: tc.authMechs,
+
+ AcceptedIdentity: tc.cfg.Auth.Identity.String(),
+ AcceptedUsername: username,
+ AcceptedPassword: password,
+ })
+
+ // Create a mock SMTP server which conditionally listens for plain or TLS connections.
+ srv, listen, err := createMockSMTPServer(backend, tc.useTLS)
+ require.NoError(t, err)
+ t.Cleanup(func() {
+ // We expect that the server has already been closed in the test
+ assert.ErrorIs(t, srv.Shutdown(ctx), smtp.ErrServerClosed)
+ })
+
+ errs := bytes.NewBuffer(nil)
+ srv.ErrorLog = log.New(errs, "oops", 0)
+ // Enable this to debug mock SMTP server.
+ // srv.Debug = os.Stderr
+
+ var hp serpent.HostPort
+ require.NoError(t, hp.Set(listen.Addr().String()))
+ tc.cfg.Smarthost = hp
+
+ handler := dispatch.NewSMTPHandler(tc.cfg, logger.Named("smtp"))
+
+ // Start mock SMTP server in the background.
+ var wg sync.WaitGroup
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ assert.NoError(t, srv.Serve(listen))
+ }()
+
+ // Wait for the server to become pingable.
+ require.Eventually(t, func() bool {
+ cl, err := pingClient(listen, tc.useTLS, tc.cfg.TLS.StartTLS.Value())
+ if err != nil {
+ t.Logf("smtp not yet dialable: %s", err)
+ return false
+ }
+
+ if err = cl.Noop(); err != nil {
+ t.Logf("smtp not yet noopable: %s", err)
+ return false
+ }
+
+ if err = cl.Close(); err != nil {
+ t.Logf("smtp didn't close properly: %s", err)
+ return false
+ }
+
+ return true
+ }, testutil.WaitShort, testutil.IntervalFast)
+
+ // Build a fake payload.
+ payload := types.MessagePayload{
+ Version: "1.0",
+ UserEmail: to,
+ Labels: make(map[string]string),
+ }
+
+ dispatchFn, err := handler.Dispatcher(payload, subject, body)
+ require.NoError(t, err)
+
+ msgID := uuid.New()
+ retryable, err := dispatchFn(ctx, msgID)
+
+ if tc.expectedErr == "" {
+ require.Nil(t, err)
+ require.Empty(t, errs.Bytes())
+
+ msg := backend.LastMessage()
+ require.NotNil(t, msg)
+ backend.Reset()
+
+ require.Equal(t, tc.expectedAuthMeth, msg.AuthMech)
+ require.Equal(t, from, msg.From)
+ require.Equal(t, tc.toAddrs, msg.To)
+ if !tc.cfg.Auth.Empty() {
+ require.Equal(t, tc.cfg.Auth.Identity.String(), msg.Identity)
+ require.Equal(t, username, msg.Username)
+ require.Equal(t, password, msg.Password)
+ }
+ require.Contains(t, msg.Contents, subject)
+ require.Contains(t, msg.Contents, body)
+ require.Contains(t, msg.Contents, fmt.Sprintf("Message-Id: %s", msgID))
+ } else {
+ require.ErrorContains(t, err, tc.expectedErr)
+ }
+
+ require.Equal(t, tc.retryable, retryable)
+
+ require.NoError(t, srv.Shutdown(ctx))
+ wg.Wait()
+ })
+ }
+}
+
+func pingClient(listen net.Listener, useTLS bool, startTLS bool) (*smtp.Client, error) {
+ tlsCfg := &tls.Config{
+ // nolint:gosec // It's a test.
+ InsecureSkipVerify: true,
+ }
+
+ switch {
+ case useTLS:
+ return smtp.DialTLS(listen.Addr().String(), tlsCfg)
+ case startTLS:
+ return smtp.DialStartTLS(listen.Addr().String(), tlsCfg)
+ default:
+ return smtp.Dial(listen.Addr().String())
+ }
+}
diff --git a/coderd/notifications/dispatch/smtp_util_test.go b/coderd/notifications/dispatch/smtp_util_test.go
new file mode 100644
index 0000000000000..659a17bec4a08
--- /dev/null
+++ b/coderd/notifications/dispatch/smtp_util_test.go
@@ -0,0 +1,200 @@
+package dispatch_test
+
+import (
+ "crypto/tls"
+ _ "embed"
+ "io"
+ "net"
+ "sync"
+ "time"
+
+ "github.com/emersion/go-sasl"
+ "github.com/emersion/go-smtp"
+ "golang.org/x/xerrors"
+)
+
+// TLS cert files.
+var (
+ //go:embed fixtures/server.crt
+ certFile []byte
+ //go:embed fixtures/server.key
+ keyFile []byte
+)
+
+type Config struct {
+ AuthMechanisms []string
+ AcceptedIdentity, AcceptedUsername, AcceptedPassword string
+}
+
+type Message struct {
+ AuthMech string
+ Identity, Username, Password string // Auth
+ From string
+ To []string // Address
+ Subject, Contents string // Content
+}
+
+type Backend struct {
+ cfg Config
+
+ mu sync.Mutex
+ lastMsg *Message
+}
+
+func NewBackend(cfg Config) *Backend {
+ return &Backend{
+ cfg: cfg,
+ }
+}
+
+// NewSession is called after client greeting (EHLO, HELO).
+func (b *Backend) NewSession(c *smtp.Conn) (smtp.Session, error) {
+ return &Session{conn: c, backend: b}, nil
+}
+
+func (b *Backend) LastMessage() *Message {
+ return b.lastMsg
+}
+
+func (b *Backend) Reset() {
+ b.lastMsg = nil
+}
+
+type Session struct {
+ conn *smtp.Conn
+ backend *Backend
+}
+
+// AuthMechanisms returns a slice of available auth mechanisms; only PLAIN is
+// supported in this example.
+func (s *Session) AuthMechanisms() []string {
+ return s.backend.cfg.AuthMechanisms
+}
+
+// Auth is the handler for supported authenticators.
+func (s *Session) Auth(mech string) (sasl.Server, error) {
+ s.backend.mu.Lock()
+ defer s.backend.mu.Unlock()
+
+ if s.backend.lastMsg == nil {
+ s.backend.lastMsg = &Message{AuthMech: mech}
+ }
+
+ switch mech {
+ case sasl.Plain:
+ return sasl.NewPlainServer(func(identity, username, password string) error {
+ s.backend.lastMsg.Identity = identity
+ s.backend.lastMsg.Username = username
+ s.backend.lastMsg.Password = password
+
+ if s.backend.cfg.AcceptedIdentity != "" && identity != s.backend.cfg.AcceptedIdentity {
+ return xerrors.Errorf("unknown identity: %q", identity)
+ }
+ if username != s.backend.cfg.AcceptedUsername {
+ return xerrors.Errorf("unknown user: %q", username)
+ }
+ if password != s.backend.cfg.AcceptedPassword {
+ return xerrors.Errorf("incorrect password for username: %q", username)
+ }
+
+ return nil
+ }), nil
+ case sasl.Login:
+ return sasl.NewLoginServer(func(username, password string) error {
+ s.backend.lastMsg.Username = username
+ s.backend.lastMsg.Password = password
+
+ if username != s.backend.cfg.AcceptedUsername {
+ return xerrors.Errorf("unknown user: %q", username)
+ }
+ if password != s.backend.cfg.AcceptedPassword {
+ return xerrors.Errorf("incorrect password for username: %q", username)
+ }
+
+ return nil
+ }), nil
+ default:
+ return nil, xerrors.Errorf("unexpected auth mechanism: %q", mech)
+ }
+}
+
+func (s *Session) Mail(from string, _ *smtp.MailOptions) error {
+ s.backend.mu.Lock()
+ defer s.backend.mu.Unlock()
+
+ if s.backend.lastMsg == nil {
+ s.backend.lastMsg = &Message{}
+ }
+
+ s.backend.lastMsg.From = from
+ return nil
+}
+
+func (s *Session) Rcpt(to string, _ *smtp.RcptOptions) error {
+ s.backend.mu.Lock()
+ defer s.backend.mu.Unlock()
+
+ s.backend.lastMsg.To = append(s.backend.lastMsg.To, to)
+ return nil
+}
+
+func (s *Session) Data(r io.Reader) error {
+ s.backend.mu.Lock()
+ defer s.backend.mu.Unlock()
+
+ b, err := io.ReadAll(r)
+ if err != nil {
+ return err
+ }
+
+ s.backend.lastMsg.Contents = string(b)
+
+ return nil
+}
+
+func (*Session) Reset() {}
+
+func (*Session) Logout() error { return nil }
+
+// nolint:revive // Yes, useTLS is a control flag.
+func createMockSMTPServer(be *Backend, useTLS bool) (*smtp.Server, net.Listener, error) {
+ // nolint:gosec
+ tlsCfg := &tls.Config{
+ GetCertificate: readCert,
+ }
+
+ l, err := net.Listen("tcp", "localhost:0")
+ if err != nil {
+ return nil, nil, xerrors.Errorf("connect: tls? %v: %w", useTLS, err)
+ }
+
+ if useTLS {
+ l = tls.NewListener(l, tlsCfg)
+ }
+
+ addr, ok := l.Addr().(*net.TCPAddr)
+ if !ok {
+ return nil, nil, xerrors.Errorf("unexpected address type: %T", l.Addr())
+ }
+
+ s := smtp.NewServer(be)
+
+ s.Addr = addr.String()
+ s.WriteTimeout = 10 * time.Second
+ s.ReadTimeout = 10 * time.Second
+ s.MaxMessageBytes = 1024 * 1024
+ s.MaxRecipients = 50
+ s.AllowInsecureAuth = !useTLS
+ s.TLSConfig = tlsCfg
+
+ return s, l, nil
+}
+
+func readCert(_ *tls.ClientHelloInfo) (*tls.Certificate, error) {
+ crt, err := tls.X509KeyPair(certFile, keyFile)
+ if err != nil {
+ return nil, xerrors.Errorf("load x509 cert: %w", err)
+ }
+
+ return &crt, nil
+}
diff --git a/coderd/notifications/dispatch/spec.go b/coderd/notifications/dispatch/spec.go
new file mode 100644
index 0000000000000..037a0ebb4a1bf
--- /dev/null
+++ b/coderd/notifications/dispatch/spec.go
@@ -0,0 +1,13 @@
+package dispatch
+
+import (
+ "context"
+
+ "github.com/google/uuid"
+)
+
+// DeliveryFunc delivers the notification.
+// The first return param indicates whether a retry can be attempted (i.e. a temporary error), and the second returns
+// any error that may have arisen.
+// If (false, nil) is returned, that is considered a successful dispatch.
+type DeliveryFunc func(ctx context.Context, msgID uuid.UUID) (retryable bool, err error)
diff --git a/coderd/notifications/dispatch/webhook.go b/coderd/notifications/dispatch/webhook.go
new file mode 100644
index 0000000000000..4a548b40e4c2f
--- /dev/null
+++ b/coderd/notifications/dispatch/webhook.go
@@ -0,0 +1,110 @@
+package dispatch
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "errors"
+ "io"
+ "net/http"
+
+ "github.com/google/uuid"
+ "golang.org/x/xerrors"
+
+ "cdr.dev/slog"
+
+ "github.com/coder/coder/v2/coderd/notifications/types"
+ markdown "github.com/coder/coder/v2/coderd/render"
+ "github.com/coder/coder/v2/codersdk"
+)
+
+// WebhookHandler dispatches notification messages via an HTTP POST webhook.
+type WebhookHandler struct {
+ cfg codersdk.NotificationsWebhookConfig
+ log slog.Logger
+
+ cl *http.Client
+}
+
+// WebhookPayload describes the JSON payload to be delivered to the configured webhook endpoint.
+type WebhookPayload struct {
+ Version string `json:"_version"`
+ MsgID uuid.UUID `json:"msg_id"`
+ Payload types.MessagePayload `json:"payload"`
+ Title string `json:"title"`
+ Body string `json:"body"`
+}
+
+func NewWebhookHandler(cfg codersdk.NotificationsWebhookConfig, log slog.Logger) *WebhookHandler {
+ return &WebhookHandler{cfg: cfg, log: log, cl: &http.Client{}}
+}
+
+func (w *WebhookHandler) Dispatcher(payload types.MessagePayload, titleTmpl, bodyTmpl string) (DeliveryFunc, error) {
+ if w.cfg.Endpoint.String() == "" {
+ return nil, xerrors.New("webhook endpoint not defined")
+ }
+
+ title, err := markdown.PlaintextFromMarkdown(titleTmpl)
+ if err != nil {
+ return nil, xerrors.Errorf("render title: %w", err)
+ }
+ body, err := markdown.PlaintextFromMarkdown(bodyTmpl)
+ if err != nil {
+ return nil, xerrors.Errorf("render body: %w", err)
+ }
+
+ return w.dispatch(payload, title, body, w.cfg.Endpoint.String()), nil
+}
+
+func (w *WebhookHandler) dispatch(msgPayload types.MessagePayload, title, body, endpoint string) DeliveryFunc {
+ return func(ctx context.Context, msgID uuid.UUID) (retryable bool, err error) {
+ // Prepare payload.
+ payload := WebhookPayload{
+ Version: "1.0",
+ MsgID: msgID,
+ Title: title,
+ Body: body,
+ Payload: msgPayload,
+ }
+ m, err := json.Marshal(payload)
+ if err != nil {
+ return false, xerrors.Errorf("marshal payload: %v", err)
+ }
+
+ // Prepare request.
+ // Outer context has a deadline (see CODER_NOTIFICATIONS_DISPATCH_TIMEOUT).
+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewBuffer(m))
+ if err != nil {
+ return false, xerrors.Errorf("create HTTP request: %v", err)
+ }
+ req.Header.Set("Content-Type", "application/json")
+ req.Header.Set("X-Message-Id", msgID.String())
+
+ // Send request.
+ resp, err := w.cl.Do(req)
+ if err != nil {
+ if errors.Is(err, context.DeadlineExceeded) {
+ return true, xerrors.Errorf("request timeout: %w", err)
+ }
+
+ return true, xerrors.Errorf("request failed: %w", err)
+ }
+ defer resp.Body.Close()
+
+ // Handle response.
+ if resp.StatusCode/100 > 2 {
+ // Body could be quite long here, let's grab the first 512B and hope it contains useful debug info.
+ respBody := make([]byte, 512)
+ lr := io.LimitReader(resp.Body, int64(len(respBody)))
+ n, err := lr.Read(respBody)
+ if err != nil && !errors.Is(err, io.EOF) {
+ return true, xerrors.Errorf("non-2xx response (%d), read body: %w", resp.StatusCode, err)
+ }
+ w.log.Warn(ctx, "unsuccessful delivery", slog.F("status_code", resp.StatusCode),
+ slog.F("response", respBody[:n]), slog.F("msg_id", msgID))
+ return true, xerrors.Errorf("non-2xx response (%d)", resp.StatusCode)
+ }
+
+ return false, nil
+ }
+}
diff --git a/coderd/notifications/dispatch/webhook_test.go b/coderd/notifications/dispatch/webhook_test.go
new file mode 100644
index 0000000000000..546fbc2e88057
--- /dev/null
+++ b/coderd/notifications/dispatch/webhook_test.go
@@ -0,0 +1,145 @@
+package dispatch_test
+
+import (
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "net/http/httptest"
+ "net/url"
+ "testing"
+ "time"
+
+ "github.com/google/uuid"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "cdr.dev/slog"
+ "cdr.dev/slog/sloggers/slogtest"
+ "github.com/coder/serpent"
+
+ "github.com/coder/coder/v2/coderd/notifications/dispatch"
+ "github.com/coder/coder/v2/coderd/notifications/types"
+ "github.com/coder/coder/v2/codersdk"
+ "github.com/coder/coder/v2/testutil"
+)
+
+func TestWebhook(t *testing.T) {
+ t.Parallel()
+
+ const (
+ titleTemplate = "this is the title ({{.Labels.foo}})"
+ bodyTemplate = "this is the body ({{.Labels.baz}})"
+ )
+
+ msgPayload := types.MessagePayload{
+ Version: "1.0",
+ NotificationName: "test",
+ Labels: map[string]string{
+ "foo": "bar",
+ "baz": "quux",
+ },
+ }
+
+ tests := []struct {
+ name string
+ serverURL string
+ serverTimeout time.Duration
+ serverFn func(uuid.UUID, http.ResponseWriter, *http.Request)
+
+ expectSuccess bool
+ expectRetryable bool
+ expectErr string
+ }{
+ {
+ name: "successful",
+ serverFn: func(msgID uuid.UUID, w http.ResponseWriter, r *http.Request) {
+ var payload dispatch.WebhookPayload
+ err := json.NewDecoder(r.Body).Decode(&payload)
+ assert.NoError(t, err)
+ assert.Equal(t, "application/json", r.Header.Get("Content-Type"))
+ assert.Equal(t, msgID, payload.MsgID)
+ assert.Equal(t, msgID.String(), r.Header.Get("X-Message-Id"))
+
+ w.WriteHeader(http.StatusOK)
+ _, err = w.Write([]byte(fmt.Sprintf("received %s", payload.MsgID)))
+ assert.NoError(t, err)
+ },
+ expectSuccess: true,
+ },
+ {
+ name: "invalid endpoint",
+ // Build a deliberately invalid URL to fail validation.
+ serverURL: "invalid .com",
+ expectSuccess: false,
+ expectErr: "invalid URL escape",
+ expectRetryable: false,
+ },
+ {
+ name: "timeout",
+ serverTimeout: time.Nanosecond,
+ expectSuccess: false,
+ expectRetryable: true,
+ expectErr: "request timeout",
+ },
+ {
+ name: "non-200 response",
+ serverFn: func(_ uuid.UUID, w http.ResponseWriter, r *http.Request) {
+ w.WriteHeader(http.StatusInternalServerError)
+ },
+ expectSuccess: false,
+ expectRetryable: true,
+ expectErr: "non-2xx response (500)",
+ },
+ }
+
+ logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true}).Leveled(slog.LevelDebug)
+
+ // nolint:paralleltest // Irrelevant as of Go v1.22
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ timeout := testutil.WaitLong
+ if tc.serverTimeout > 0 {
+ timeout = tc.serverTimeout
+ }
+
+ var (
+ err error
+ ctx = testutil.Context(t, timeout)
+ msgID = uuid.New()
+ )
+
+ var endpoint *url.URL
+ if tc.serverURL != "" {
+ endpoint = &url.URL{Host: tc.serverURL}
+ } else {
+ // Mock server to simulate webhook endpoint.
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ tc.serverFn(msgID, w, r)
+ }))
+ defer server.Close()
+
+ endpoint, err = url.Parse(server.URL)
+ require.NoError(t, err)
+ }
+
+ cfg := codersdk.NotificationsWebhookConfig{
+ Endpoint: *serpent.URLOf(endpoint),
+ }
+ handler := dispatch.NewWebhookHandler(cfg, logger.With(slog.F("test", tc.name)))
+ deliveryFn, err := handler.Dispatcher(msgPayload, titleTemplate, bodyTemplate)
+ require.NoError(t, err)
+
+ retryable, err := deliveryFn(ctx, msgID)
+ if tc.expectSuccess {
+ require.NoError(t, err)
+ require.False(t, retryable)
+ return
+ }
+
+ require.ErrorContains(t, err, tc.expectErr)
+ require.Equal(t, tc.expectRetryable, retryable)
+ })
+ }
+}
diff --git a/coderd/notifications/enqueuer.go b/coderd/notifications/enqueuer.go
new file mode 100644
index 0000000000000..32822dd6ab9d7
--- /dev/null
+++ b/coderd/notifications/enqueuer.go
@@ -0,0 +1,132 @@
+package notifications
+
+import (
+ "context"
+ "encoding/json"
+ "text/template"
+
+ "github.com/google/uuid"
+ "golang.org/x/xerrors"
+
+ "cdr.dev/slog"
+
+ "github.com/coder/coder/v2/coderd/database"
+ "github.com/coder/coder/v2/coderd/notifications/render"
+ "github.com/coder/coder/v2/coderd/notifications/types"
+ "github.com/coder/coder/v2/codersdk"
+)
+
+type StoreEnqueuer struct {
+ store Store
+ log slog.Logger
+
+ // TODO: expand this to allow for each notification to have custom delivery methods, or multiple, or none.
+ // For example, Larry might want email notifications for "workspace deleted" notifications, but Harry wants
+ // Slack notifications, and Mary doesn't want any.
+ method database.NotificationMethod
+ // helpers holds a map of template funcs which are used when rendering templates. These need to be passed in because
+ // the template funcs will return values which are inappropriately encapsulated in this struct.
+ helpers template.FuncMap
+}
+
+// NewStoreEnqueuer creates an Enqueuer implementation which can persist notification messages in the store.
+func NewStoreEnqueuer(cfg codersdk.NotificationsConfig, store Store, helpers template.FuncMap, log slog.Logger) (*StoreEnqueuer, error) {
+ var method database.NotificationMethod
+ if err := method.Scan(cfg.Method.String()); err != nil {
+ return nil, xerrors.Errorf("given notification method %q is invalid", cfg.Method)
+ }
+
+ return &StoreEnqueuer{
+ store: store,
+ log: log,
+ method: method,
+ helpers: helpers,
+ }, nil
+}
+
+// Enqueue queues a notification message for later delivery.
+// Messages will be dequeued by a notifier later and dispatched.
+func (s *StoreEnqueuer) Enqueue(ctx context.Context, userID, templateID uuid.UUID, labels map[string]string, createdBy string, targets ...uuid.UUID) (*uuid.UUID, error) {
+ payload, err := s.buildPayload(ctx, userID, templateID, labels)
+ if err != nil {
+ s.log.Warn(ctx, "failed to build payload", slog.F("template_id", templateID), slog.F("user_id", userID), slog.Error(err))
+ return nil, xerrors.Errorf("enqueue notification (payload build): %w", err)
+ }
+
+ input, err := json.Marshal(payload)
+ if err != nil {
+ return nil, xerrors.Errorf("failed encoding input labels: %w", err)
+ }
+
+ id := uuid.New()
+ err = s.store.EnqueueNotificationMessage(ctx, database.EnqueueNotificationMessageParams{
+ ID: id,
+ UserID: userID,
+ NotificationTemplateID: templateID,
+ Method: s.method,
+ Payload: input,
+ Targets: targets,
+ CreatedBy: createdBy,
+ })
+ if err != nil {
+ s.log.Warn(ctx, "failed to enqueue notification", slog.F("template_id", templateID), slog.F("input", input), slog.Error(err))
+ return nil, xerrors.Errorf("enqueue notification: %w", err)
+ }
+
+ s.log.Debug(ctx, "enqueued notification", slog.F("msg_id", id))
+ return &id, nil
+}
+
+// buildPayload creates the payload that the notification will for variable substitution and/or routing.
+// The payload contains information about the recipient, the event that triggered the notification, and any subsequent
+// actions which can be taken by the recipient.
+func (s *StoreEnqueuer) buildPayload(ctx context.Context, userID, templateID uuid.UUID, labels map[string]string) (*types.MessagePayload, error) {
+ metadata, err := s.store.FetchNewMessageMetadata(ctx, database.FetchNewMessageMetadataParams{
+ UserID: userID,
+ NotificationTemplateID: templateID,
+ })
+ if err != nil {
+ return nil, xerrors.Errorf("new message metadata: %w", err)
+ }
+
+ payload := types.MessagePayload{
+ Version: "1.0",
+
+ NotificationName: metadata.NotificationName,
+
+ UserID: metadata.UserID.String(),
+ UserEmail: metadata.UserEmail,
+ UserName: metadata.UserName,
+ UserUsername: metadata.UserUsername,
+
+ Labels: labels,
+ // No actions yet
+ }
+
+ // Execute any templates in actions.
+ out, err := render.GoTemplate(string(metadata.Actions), payload, s.helpers)
+ if err != nil {
+ return nil, xerrors.Errorf("render actions: %w", err)
+ }
+ metadata.Actions = []byte(out)
+
+ var actions []types.TemplateAction
+ if err = json.Unmarshal(metadata.Actions, &actions); err != nil {
+ return nil, xerrors.Errorf("new message metadata: parse template actions: %w", err)
+ }
+ payload.Actions = actions
+ return &payload, nil
+}
+
+// NoopEnqueuer implements the Enqueuer interface but performs a noop.
+type NoopEnqueuer struct{}
+
+// NewNoopEnqueuer builds a NoopEnqueuer which is used to fulfill the contract for enqueuing notifications, if ExperimentNotifications is not set.
+func NewNoopEnqueuer() *NoopEnqueuer {
+ return &NoopEnqueuer{}
+}
+
+func (*NoopEnqueuer) Enqueue(context.Context, uuid.UUID, uuid.UUID, map[string]string, string, ...uuid.UUID) (*uuid.UUID, error) {
+ // nolint:nilnil // irrelevant.
+ return nil, nil
+}
diff --git a/coderd/notifications/events.go b/coderd/notifications/events.go
new file mode 100644
index 0000000000000..c00912d70734c
--- /dev/null
+++ b/coderd/notifications/events.go
@@ -0,0 +1,21 @@
+package notifications
+
+import "github.com/google/uuid"
+
+// These vars are mapped to UUIDs in the notification_templates table.
+// TODO: autogenerate these.
+
+// Workspace-related events.
+var (
+ TemplateWorkspaceDeleted = uuid.MustParse("f517da0b-cdc9-410f-ab89-a86107c420ed")
+ TemplateWorkspaceAutobuildFailed = uuid.MustParse("381df2a9-c0c0-4749-420f-80a9280c66f9")
+ TemplateWorkspaceDormant = uuid.MustParse("0ea69165-ec14-4314-91f1-69566ac3c5a0")
+ TemplateWorkspaceAutoUpdated = uuid.MustParse("c34a0c09-0704-4cac-bd1c-0c0146811c2b")
+ TemplateWorkspaceMarkedForDeletion = uuid.MustParse("51ce2fdf-c9ca-4be1-8d70-628674f9bc42")
+)
+
+// Account-related events.
+var (
+ TemplateUserAccountCreated = uuid.MustParse("4e19c0ac-94e1-4532-9515-d1801aa283b2")
+ TemplateUserAccountDeleted = uuid.MustParse("f44d9314-ad03-4bc8-95d0-5cad491da6b6")
+)
diff --git a/coderd/notifications/manager.go b/coderd/notifications/manager.go
new file mode 100644
index 0000000000000..5f5d30974a302
--- /dev/null
+++ b/coderd/notifications/manager.go
@@ -0,0 +1,370 @@
+package notifications
+
+import (
+ "context"
+ "sync"
+ "time"
+
+ "github.com/google/uuid"
+ "golang.org/x/sync/errgroup"
+ "golang.org/x/xerrors"
+
+ "cdr.dev/slog"
+
+ "github.com/coder/coder/v2/coderd/database"
+ "github.com/coder/coder/v2/coderd/notifications/dispatch"
+ "github.com/coder/coder/v2/codersdk"
+)
+
+var ErrInvalidDispatchTimeout = xerrors.New("dispatch timeout must be less than lease period")
+
+// Manager manages all notifications being enqueued and dispatched.
+//
+// Manager maintains a notifier: this consumes the queue of notification messages in the store.
+//
+// The notifier dequeues messages from the store _CODER_NOTIFICATIONS_LEASE_COUNT_ at a time and concurrently "dispatches"
+// these messages, meaning they are sent by their respective methods (email, webhook, etc).
+//
+// To reduce load on the store, successful and failed dispatches are accumulated in two separate buffers (success/failure)
+// of size CODER_NOTIFICATIONS_STORE_SYNC_INTERVAL in the Manager, and updates are sent to the store about which messages
+// succeeded or failed every CODER_NOTIFICATIONS_STORE_SYNC_INTERVAL seconds.
+// These buffers are limited in size, and naturally introduce some backpressure; if there are hundreds of messages to be
+// sent but they start failing too quickly, the buffers (receive channels) will fill up and block senders, which will
+// slow down the dispatch rate.
+//
+// NOTE: The above backpressure mechanism only works within the same process, which may not be true forever, such as if
+// we split notifiers out into separate targets for greater processing throughput; in this case we will need an
+// alternative mechanism for handling backpressure.
+type Manager struct {
+ cfg codersdk.NotificationsConfig
+
+ store Store
+ log slog.Logger
+
+ notifier *notifier
+ handlers map[database.NotificationMethod]Handler
+ method database.NotificationMethod
+
+ metrics *Metrics
+
+ success, failure chan dispatchResult
+
+ runOnce sync.Once
+ stopOnce sync.Once
+ stop chan any
+ done chan any
+}
+
+// NewManager instantiates a new Manager instance which coordinates notification enqueuing and delivery.
+//
+// helpers is a map of template helpers which are used to customize notification messages to use global settings like
+// access URL etc.
+func NewManager(cfg codersdk.NotificationsConfig, store Store, metrics *Metrics, log slog.Logger) (*Manager, error) {
+ // TODO(dannyk): add the ability to use multiple notification methods.
+ var method database.NotificationMethod
+ if err := method.Scan(cfg.Method.String()); err != nil {
+ return nil, xerrors.Errorf("notification method %q is invalid", cfg.Method)
+ }
+
+ // If dispatch timeout exceeds lease period, it is possible that messages can be delivered in duplicate because the
+ // lease can expire before the notifier gives up on the dispatch, which results in the message becoming eligible for
+ // being re-acquired.
+ if cfg.DispatchTimeout.Value() >= cfg.LeasePeriod.Value() {
+ return nil, ErrInvalidDispatchTimeout
+ }
+
+ return &Manager{
+ log: log,
+ cfg: cfg,
+ store: store,
+
+ // Buffer successful/failed notification dispatches in memory to reduce load on the store.
+ //
+ // We keep separate buffered for success/failure right now because the bulk updates are already a bit janky,
+ // see BulkMarkNotificationMessagesSent/BulkMarkNotificationMessagesFailed. If we had the ability to batch updates,
+ // like is offered in https://docs.sqlc.dev/en/stable/reference/query-annotations.html#batchmany, we'd have a cleaner
+ // approach to this - but for now this will work fine.
+ success: make(chan dispatchResult, cfg.StoreSyncBufferSize),
+ failure: make(chan dispatchResult, cfg.StoreSyncBufferSize),
+
+ metrics: metrics,
+ method: method,
+
+ stop: make(chan any),
+ done: make(chan any),
+
+ handlers: defaultHandlers(cfg, log),
+ }, nil
+}
+
+// defaultHandlers builds a set of known handlers; panics if any error occurs as these handlers should be valid at compile time.
+func defaultHandlers(cfg codersdk.NotificationsConfig, log slog.Logger) map[database.NotificationMethod]Handler {
+ return map[database.NotificationMethod]Handler{
+ database.NotificationMethodSmtp: dispatch.NewSMTPHandler(cfg.SMTP, log.Named("dispatcher.smtp")),
+ database.NotificationMethodWebhook: dispatch.NewWebhookHandler(cfg.Webhook, log.Named("dispatcher.webhook")),
+ }
+}
+
+// WithHandlers allows for tests to inject their own handlers to verify functionality.
+func (m *Manager) WithHandlers(reg map[database.NotificationMethod]Handler) {
+ m.handlers = reg
+}
+
+// Run initiates the control loop in the background, which spawns a given number of notifier goroutines.
+// Manager requires system-level permissions to interact with the store.
+// Run is only intended to be run once.
+func (m *Manager) Run(ctx context.Context) {
+ m.log.Info(ctx, "started")
+
+ m.runOnce.Do(func() {
+ // Closes when Stop() is called or context is canceled.
+ go func() {
+ err := m.loop(ctx)
+ if err != nil {
+ m.log.Error(ctx, "notification manager stopped with error", slog.Error(err))
+ }
+ }()
+ })
+}
+
+// loop contains the main business logic of the notification manager. It is responsible for subscribing to notification
+// events, creating a notifier, and publishing bulk dispatch result updates to the store.
+func (m *Manager) loop(ctx context.Context) error {
+ defer func() {
+ close(m.done)
+ m.log.Info(context.Background(), "notification manager stopped")
+ }()
+
+ // Caught a terminal signal before notifier was created, exit immediately.
+ select {
+ case <-m.stop:
+ m.log.Warn(ctx, "gracefully stopped")
+ return xerrors.Errorf("gracefully stopped")
+ case <-ctx.Done():
+ m.log.Error(ctx, "ungracefully stopped", slog.Error(ctx.Err()))
+ return xerrors.Errorf("notifications: %w", ctx.Err())
+ default:
+ }
+
+ var eg errgroup.Group
+
+ // Create a notifier to run concurrently, which will handle dequeueing and dispatching notifications.
+ m.notifier = newNotifier(m.cfg, uuid.New(), m.log, m.store, m.handlers, m.method, m.metrics)
+ eg.Go(func() error {
+ return m.notifier.run(ctx, m.success, m.failure)
+ })
+
+ // Periodically flush notification state changes to the store.
+ eg.Go(func() error {
+ // Every interval, collect the messages in the channels and bulk update them in the store.
+ tick := time.NewTicker(m.cfg.StoreSyncInterval.Value())
+ defer tick.Stop()
+ for {
+ select {
+ case <-ctx.Done():
+ // Nothing we can do in this scenario except bail out; after the message lease expires, the messages will
+ // be requeued and users will receive duplicates.
+ // This is an explicit trade-off between keeping the database load light (by bulk-updating records) and
+ // exactly-once delivery.
+ //
+ // The current assumption is that duplicate delivery of these messages is, at worst, slightly annoying.
+ // If these notifications are triggering external actions (e.g. via webhooks) this could be more
+ // consequential, and we may need a more sophisticated mechanism.
+ //
+ // TODO: mention the above tradeoff in documentation.
+ m.log.Warn(ctx, "exiting ungracefully", slog.Error(ctx.Err()))
+
+ if len(m.success)+len(m.failure) > 0 {
+ m.log.Warn(ctx, "content canceled with pending updates in buffer, these messages will be sent again after lease expires",
+ slog.F("success_count", len(m.success)), slog.F("failure_count", len(m.failure)))
+ }
+ return ctx.Err()
+ case <-m.stop:
+ if len(m.success)+len(m.failure) > 0 {
+ m.log.Warn(ctx, "flushing buffered updates before stop",
+ slog.F("success_count", len(m.success)), slog.F("failure_count", len(m.failure)))
+ m.syncUpdates(ctx)
+ m.log.Warn(ctx, "flushing updates done")
+ }
+ return nil
+ case <-tick.C:
+ m.syncUpdates(ctx)
+ }
+ }
+ })
+
+ err := eg.Wait()
+ if err != nil {
+ m.log.Error(ctx, "manager loop exited with error", slog.Error(err))
+ }
+ return err
+}
+
+// BufferedUpdatesCount returns the number of buffered updates which are currently waiting to be flushed to the store.
+// The returned values are for success & failure, respectively.
+func (m *Manager) BufferedUpdatesCount() (success int, failure int) {
+ return len(m.success), len(m.failure)
+}
+
+// syncUpdates updates messages in the store based on the given successful and failed message dispatch results.
+func (m *Manager) syncUpdates(ctx context.Context) {
+ // Ensure we update the metrics to reflect the current state after each invocation.
+ defer func() {
+ m.metrics.PendingUpdates.Set(float64(len(m.success) + len(m.failure)))
+ }()
+
+ select {
+ case <-ctx.Done():
+ return
+ default:
+ }
+
+ nSuccess := len(m.success)
+ nFailure := len(m.failure)
+
+ m.metrics.PendingUpdates.Set(float64(nSuccess + nFailure))
+
+ // Nothing to do.
+ if nSuccess+nFailure == 0 {
+ return
+ }
+
+ var (
+ successParams database.BulkMarkNotificationMessagesSentParams
+ failureParams database.BulkMarkNotificationMessagesFailedParams
+ )
+
+ // Read all the existing messages due for update from the channel, but don't range over the channels because they
+ // block until they are closed.
+ //
+ // This is vulnerable to TOCTOU, but it's fine.
+ // If more items are added to the success or failure channels between measuring their lengths and now, those items
+ // will be processed on the next bulk update.
+
+ for i := 0; i < nSuccess; i++ {
+ res := <-m.success
+ successParams.IDs = append(successParams.IDs, res.msg)
+ successParams.SentAts = append(successParams.SentAts, res.ts)
+ }
+ for i := 0; i < nFailure; i++ {
+ res := <-m.failure
+
+ status := database.NotificationMessageStatusPermanentFailure
+ if res.retryable {
+ status = database.NotificationMessageStatusTemporaryFailure
+ }
+
+ failureParams.IDs = append(failureParams.IDs, res.msg)
+ failureParams.FailedAts = append(failureParams.FailedAts, res.ts)
+ failureParams.Statuses = append(failureParams.Statuses, status)
+ var reason string
+ if res.err != nil {
+ reason = res.err.Error()
+ }
+ failureParams.StatusReasons = append(failureParams.StatusReasons, reason)
+ }
+
+ // Execute bulk updates for success/failure concurrently.
+ var wg sync.WaitGroup
+ wg.Add(2)
+
+ go func() {
+ defer wg.Done()
+ if len(successParams.IDs) == 0 {
+ return
+ }
+
+ logger := m.log.With(slog.F("type", "update_sent"))
+
+ // Give up after waiting for the store for 30s.
+ uctx, cancel := context.WithTimeout(ctx, time.Second*30)
+ defer cancel()
+
+ n, err := m.store.BulkMarkNotificationMessagesSent(uctx, successParams)
+ if err != nil {
+ logger.Error(ctx, "bulk update failed", slog.Error(err))
+ return
+ }
+ m.metrics.SyncedUpdates.Add(float64(n))
+
+ logger.Debug(ctx, "bulk update completed", slog.F("updated", n))
+ }()
+
+ go func() {
+ defer wg.Done()
+ if len(failureParams.IDs) == 0 {
+ return
+ }
+
+ logger := m.log.With(slog.F("type", "update_failed"))
+
+ // Give up after waiting for the store for 30s.
+ uctx, cancel := context.WithTimeout(ctx, time.Second*30)
+ defer cancel()
+
+ failureParams.MaxAttempts = int32(m.cfg.MaxSendAttempts)
+ failureParams.RetryInterval = int32(m.cfg.RetryInterval.Value().Seconds())
+ n, err := m.store.BulkMarkNotificationMessagesFailed(uctx, failureParams)
+ if err != nil {
+ logger.Error(ctx, "bulk update failed", slog.Error(err))
+ return
+ }
+ m.metrics.SyncedUpdates.Add(float64(n))
+
+ logger.Debug(ctx, "bulk update completed", slog.F("updated", n))
+ }()
+
+ wg.Wait()
+}
+
+// Stop stops the notifier and waits until it has stopped.
+func (m *Manager) Stop(ctx context.Context) error {
+ var err error
+ m.stopOnce.Do(func() {
+ select {
+ case <-ctx.Done():
+ err = ctx.Err()
+ return
+ default:
+ }
+
+ m.log.Info(context.Background(), "graceful stop requested")
+
+ // If the notifier hasn't been started, we don't need to wait for anything.
+ // This is only really during testing when we want to enqueue messages only but not deliver them.
+ if m.notifier == nil {
+ close(m.done)
+ } else {
+ m.notifier.stop()
+ }
+
+ // Signal the stop channel to cause loop to exit.
+ close(m.stop)
+
+ // Wait for the manager loop to exit or the context to be canceled, whichever comes first.
+ select {
+ case <-ctx.Done():
+ var errStr string
+ if ctx.Err() != nil {
+ errStr = ctx.Err().Error()
+ }
+ // For some reason, slog.Error returns {} for a context error.
+ m.log.Error(context.Background(), "graceful stop failed", slog.F("err", errStr))
+ err = ctx.Err()
+ return
+ case <-m.done:
+ m.log.Info(context.Background(), "gracefully stopped")
+ return
+ }
+ })
+
+ return err
+}
+
+type dispatchResult struct {
+ notifier uuid.UUID
+ msg uuid.UUID
+ ts time.Time
+ err error
+ retryable bool
+}
diff --git a/coderd/notifications/manager_test.go b/coderd/notifications/manager_test.go
new file mode 100644
index 0000000000000..2e264c534ccfa
--- /dev/null
+++ b/coderd/notifications/manager_test.go
@@ -0,0 +1,231 @@
+package notifications_test
+
+import (
+ "context"
+ "encoding/json"
+ "sync/atomic"
+ "testing"
+ "time"
+
+ "github.com/google/uuid"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+ "golang.org/x/xerrors"
+
+ "github.com/coder/coder/v2/coderd/database"
+ "github.com/coder/coder/v2/coderd/database/dbgen"
+ "github.com/coder/coder/v2/coderd/notifications"
+ "github.com/coder/coder/v2/coderd/notifications/dispatch"
+ "github.com/coder/coder/v2/coderd/notifications/types"
+ "github.com/coder/coder/v2/testutil"
+ "github.com/coder/serpent"
+)
+
+func TestBufferedUpdates(t *testing.T) {
+ t.Parallel()
+
+ // setup
+ ctx, logger, db := setupInMemory(t)
+
+ interceptor := &syncInterceptor{Store: db}
+ santa := &santaHandler{}
+
+ cfg := defaultNotificationsConfig(database.NotificationMethodSmtp)
+ cfg.StoreSyncInterval = serpent.Duration(time.Hour) // Ensure we don't sync the store automatically.
+
+ // GIVEN: a manager which will pass or fail notifications based on their "nice" labels
+ mgr, err := notifications.NewManager(cfg, interceptor, createMetrics(), logger.Named("notifications-manager"))
+ require.NoError(t, err)
+ mgr.WithHandlers(map[database.NotificationMethod]notifications.Handler{
+ database.NotificationMethodSmtp: santa,
+ })
+ enq, err := notifications.NewStoreEnqueuer(cfg, interceptor, defaultHelpers(), logger.Named("notifications-enqueuer"))
+ require.NoError(t, err)
+
+ user := dbgen.User(t, db, database.User{})
+
+ // WHEN: notifications are enqueued which should succeed and fail
+ _, err = enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{"nice": "true"}, "") // Will succeed.
+ require.NoError(t, err)
+ _, err = enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{"nice": "true"}, "") // Will succeed.
+ require.NoError(t, err)
+ _, err = enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{"nice": "false"}, "") // Will fail.
+ require.NoError(t, err)
+
+ mgr.Run(ctx)
+
+ // THEN:
+
+ const (
+ expectedSuccess = 2
+ expectedFailure = 1
+ )
+
+ // Wait for messages to be dispatched.
+ require.Eventually(t, func() bool {
+ return santa.naughty.Load() == expectedFailure &&
+ santa.nice.Load() == expectedSuccess
+ }, testutil.WaitMedium, testutil.IntervalFast)
+
+ // Wait for the expected number of buffered updates to be accumulated.
+ require.Eventually(t, func() bool {
+ success, failure := mgr.BufferedUpdatesCount()
+ return success == expectedSuccess && failure == expectedFailure
+ }, testutil.WaitShort, testutil.IntervalFast)
+
+ // Stop the manager which forces an update of buffered updates.
+ require.NoError(t, mgr.Stop(ctx))
+
+ // Wait until both success & failure updates have been sent to the store.
+ require.EventuallyWithT(t, func(ct *assert.CollectT) {
+ if err := interceptor.err.Load(); err != nil {
+ ct.Errorf("bulk update encountered error: %s", err)
+ // Panic when an unexpected error occurs.
+ ct.FailNow()
+ }
+
+ assert.EqualValues(ct, expectedFailure, interceptor.failed.Load())
+ assert.EqualValues(ct, expectedSuccess, interceptor.sent.Load())
+ }, testutil.WaitMedium, testutil.IntervalFast)
+}
+
+func TestBuildPayload(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ ctx, logger, db := setupInMemory(t)
+
+ // GIVEN: a set of helpers to be injected into the templates
+ const label = "Click here!"
+ const baseURL = "http://xyz.com"
+ const url = baseURL + "/@bobby/my-workspace"
+ helpers := map[string]any{
+ "my_label": func() string { return label },
+ "my_url": func() string { return baseURL },
+ }
+
+ // GIVEN: an enqueue interceptor which returns mock metadata
+ interceptor := newEnqueueInterceptor(db,
+ // Inject custom message metadata to influence the payload construction.
+ func() database.FetchNewMessageMetadataRow {
+ // Inject template actions which use injected help functions.
+ actions := []types.TemplateAction{
+ {
+ Label: "{{ my_label }}",
+ URL: "{{ my_url }}/@{{.UserName}}/{{.Labels.name}}",
+ },
+ }
+ out, err := json.Marshal(actions)
+ assert.NoError(t, err)
+
+ return database.FetchNewMessageMetadataRow{
+ NotificationName: "My Notification",
+ Actions: out,
+ UserID: uuid.New(),
+ UserEmail: "bob@bob.com",
+ UserName: "bobby",
+ }
+ })
+
+ enq, err := notifications.NewStoreEnqueuer(defaultNotificationsConfig(database.NotificationMethodSmtp), interceptor, helpers, logger.Named("notifications-enqueuer"))
+ require.NoError(t, err)
+
+ // WHEN: a notification is enqueued
+ _, err = enq.Enqueue(ctx, uuid.New(), notifications.TemplateWorkspaceDeleted, map[string]string{
+ "name": "my-workspace",
+ }, "test")
+ require.NoError(t, err)
+
+ // THEN: expect that a payload will be constructed and have the expected values
+ payload := testutil.RequireRecvCtx(ctx, t, interceptor.payload)
+ require.Len(t, payload.Actions, 1)
+ require.Equal(t, label, payload.Actions[0].Label)
+ require.Equal(t, url, payload.Actions[0].URL)
+}
+
+func TestStopBeforeRun(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ ctx, logger, db := setupInMemory(t)
+
+ // GIVEN: a standard manager
+ mgr, err := notifications.NewManager(defaultNotificationsConfig(database.NotificationMethodSmtp), db, createMetrics(), logger.Named("notifications-manager"))
+ require.NoError(t, err)
+
+ // THEN: validate that the manager can be stopped safely without Run() having been called yet
+ require.Eventually(t, func() bool {
+ assert.NoError(t, mgr.Stop(ctx))
+ return true
+ }, testutil.WaitShort, testutil.IntervalFast)
+}
+
+type syncInterceptor struct {
+ notifications.Store
+
+ sent atomic.Int32
+ failed atomic.Int32
+ err atomic.Value
+}
+
+func (b *syncInterceptor) BulkMarkNotificationMessagesSent(ctx context.Context, arg database.BulkMarkNotificationMessagesSentParams) (int64, error) {
+ updated, err := b.Store.BulkMarkNotificationMessagesSent(ctx, arg)
+ b.sent.Add(int32(updated))
+ if err != nil {
+ b.err.Store(err)
+ }
+ return updated, err
+}
+
+func (b *syncInterceptor) BulkMarkNotificationMessagesFailed(ctx context.Context, arg database.BulkMarkNotificationMessagesFailedParams) (int64, error) {
+ updated, err := b.Store.BulkMarkNotificationMessagesFailed(ctx, arg)
+ b.failed.Add(int32(updated))
+ if err != nil {
+ b.err.Store(err)
+ }
+ return updated, err
+}
+
+// santaHandler only dispatches nice messages.
+type santaHandler struct {
+ naughty atomic.Int32
+ nice atomic.Int32
+}
+
+func (s *santaHandler) Dispatcher(payload types.MessagePayload, _, _ string) (dispatch.DeliveryFunc, error) {
+ return func(ctx context.Context, msgID uuid.UUID) (retryable bool, err error) {
+ if payload.Labels["nice"] != "true" {
+ s.naughty.Add(1)
+ return false, xerrors.New("be nice")
+ }
+
+ s.nice.Add(1)
+ return false, nil
+ }, nil
+}
+
+type enqueueInterceptor struct {
+ notifications.Store
+
+ payload chan types.MessagePayload
+ metadataFn func() database.FetchNewMessageMetadataRow
+}
+
+func newEnqueueInterceptor(db notifications.Store, metadataFn func() database.FetchNewMessageMetadataRow) *enqueueInterceptor {
+ return &enqueueInterceptor{Store: db, payload: make(chan types.MessagePayload, 1), metadataFn: metadataFn}
+}
+
+func (e *enqueueInterceptor) EnqueueNotificationMessage(_ context.Context, arg database.EnqueueNotificationMessageParams) error {
+ var payload types.MessagePayload
+ err := json.Unmarshal(arg.Payload, &payload)
+ if err != nil {
+ return err
+ }
+
+ e.payload <- payload
+ return err
+}
+
+func (e *enqueueInterceptor) FetchNewMessageMetadata(_ context.Context, _ database.FetchNewMessageMetadataParams) (database.FetchNewMessageMetadataRow, error) {
+ return e.metadataFn(), nil
+}
diff --git a/coderd/notifications/metrics.go b/coderd/notifications/metrics.go
new file mode 100644
index 0000000000000..204bc260c7742
--- /dev/null
+++ b/coderd/notifications/metrics.go
@@ -0,0 +1,80 @@
+package notifications
+
+import (
+ "fmt"
+ "strings"
+
+ "github.com/prometheus/client_golang/prometheus"
+ "github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+type Metrics struct {
+ DispatchAttempts *prometheus.CounterVec
+ RetryCount *prometheus.CounterVec
+
+ QueuedSeconds *prometheus.HistogramVec
+
+ InflightDispatches *prometheus.GaugeVec
+ DispatcherSendSeconds *prometheus.HistogramVec
+
+ PendingUpdates prometheus.Gauge
+ SyncedUpdates prometheus.Counter
+}
+
+const (
+ ns = "coderd"
+ subsystem = "notifications"
+
+ LabelMethod = "method"
+ LabelTemplateID = "notification_template_id"
+ LabelResult = "result"
+
+ ResultSuccess = "success"
+ ResultTempFail = "temp_fail"
+ ResultPermFail = "perm_fail"
+)
+
+func NewMetrics(reg prometheus.Registerer) *Metrics {
+ return &Metrics{
+ DispatchAttempts: promauto.With(reg).NewCounterVec(prometheus.CounterOpts{
+ Name: "dispatch_attempts_total", Namespace: ns, Subsystem: subsystem,
+ Help: fmt.Sprintf("The number of dispatch attempts, aggregated by the result type (%s)",
+ strings.Join([]string{ResultSuccess, ResultTempFail, ResultPermFail}, ", ")),
+ }, []string{LabelMethod, LabelTemplateID, LabelResult}),
+ RetryCount: promauto.With(reg).NewCounterVec(prometheus.CounterOpts{
+ Name: "retry_count", Namespace: ns, Subsystem: subsystem,
+ Help: "The count of notification dispatch retry attempts.",
+ }, []string{LabelMethod, LabelTemplateID}),
+
+ // Aggregating on LabelTemplateID as well would cause a cardinality explosion.
+ QueuedSeconds: promauto.With(reg).NewHistogramVec(prometheus.HistogramOpts{
+ Name: "queued_seconds", Namespace: ns, Subsystem: subsystem,
+ Buckets: []float64{1, 2.5, 5, 7.5, 10, 15, 20, 30, 60, 120, 300, 600, 3600},
+ Help: "The time elapsed between a notification being enqueued in the store and retrieved for dispatching " +
+ "(measures the latency of the notifications system). This should generally be within CODER_NOTIFICATIONS_FETCH_INTERVAL " +
+ "seconds; higher values for a sustained period indicates delayed processing and CODER_NOTIFICATIONS_LEASE_COUNT " +
+ "can be increased to accommodate this.",
+ }, []string{LabelMethod}),
+
+ InflightDispatches: promauto.With(reg).NewGaugeVec(prometheus.GaugeOpts{
+ Name: "inflight_dispatches", Namespace: ns, Subsystem: subsystem,
+ Help: "The number of dispatch attempts which are currently in progress.",
+ }, []string{LabelMethod, LabelTemplateID}),
+ // Aggregating on LabelTemplateID as well would cause a cardinality explosion.
+ DispatcherSendSeconds: promauto.With(reg).NewHistogramVec(prometheus.HistogramOpts{
+ Name: "dispatcher_send_seconds", Namespace: ns, Subsystem: subsystem,
+ Buckets: []float64{0.001, 0.05, 0.1, 0.5, 1, 2, 5, 10, 15, 30, 60, 120},
+ Help: "The time taken to dispatch notifications.",
+ }, []string{LabelMethod}),
+
+ // Currently no requirement to discriminate between success and failure updates which are pending.
+ PendingUpdates: promauto.With(reg).NewGauge(prometheus.GaugeOpts{
+ Name: "pending_updates", Namespace: ns, Subsystem: subsystem,
+ Help: "The number of dispatch attempt results waiting to be flushed to the store.",
+ }),
+ SyncedUpdates: promauto.With(reg).NewCounter(prometheus.CounterOpts{
+ Name: "synced_updates_total", Namespace: ns, Subsystem: subsystem,
+ Help: "The number of dispatch attempt results flushed to the store.",
+ }),
+ }
+}
diff --git a/coderd/notifications/metrics_test.go b/coderd/notifications/metrics_test.go
new file mode 100644
index 0000000000000..6c360dd2919d0
--- /dev/null
+++ b/coderd/notifications/metrics_test.go
@@ -0,0 +1,442 @@
+package notifications_test
+
+import (
+ "context"
+ "testing"
+ "time"
+
+ "github.com/google/uuid"
+ "github.com/prometheus/client_golang/prometheus"
+ promtest "github.com/prometheus/client_golang/prometheus/testutil"
+ dto "github.com/prometheus/client_model/go"
+ "github.com/prometheus/common/model"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "github.com/coder/serpent"
+
+ "github.com/coder/coder/v2/coderd/database"
+ "github.com/coder/coder/v2/coderd/database/dbtestutil"
+ "github.com/coder/coder/v2/coderd/notifications"
+ "github.com/coder/coder/v2/coderd/notifications/dispatch"
+ "github.com/coder/coder/v2/coderd/notifications/types"
+ "github.com/coder/coder/v2/testutil"
+)
+
+func TestMetrics(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ if !dbtestutil.WillUsePostgres() {
+ t.Skip("This test requires postgres; it relies on business-logic only implemented in the database")
+ }
+
+ ctx, logger, store := setup(t)
+
+ reg := prometheus.NewRegistry()
+ metrics := notifications.NewMetrics(reg)
+ template := notifications.TemplateWorkspaceDeleted
+
+ const (
+ method = database.NotificationMethodSmtp
+ maxAttempts = 3
+ debug = false
+ )
+
+ // GIVEN: a notification manager whose intervals are tuned low (for test speed) and whose dispatches are intercepted
+ cfg := defaultNotificationsConfig(method)
+ cfg.MaxSendAttempts = maxAttempts
+ // Tune the intervals low to increase test speed.
+ cfg.FetchInterval = serpent.Duration(time.Millisecond * 50)
+ cfg.RetryInterval = serpent.Duration(time.Millisecond * 50)
+ cfg.StoreSyncInterval = serpent.Duration(time.Millisecond * 100) // Twice as long as fetch interval to ensure we catch pending updates.
+
+ mgr, err := notifications.NewManager(cfg, store, metrics, logger.Named("manager"))
+ require.NoError(t, err)
+ t.Cleanup(func() {
+ assert.NoError(t, mgr.Stop(ctx))
+ })
+ handler := &fakeHandler{}
+ mgr.WithHandlers(map[database.NotificationMethod]notifications.Handler{
+ method: handler,
+ })
+
+ enq, err := notifications.NewStoreEnqueuer(cfg, store, defaultHelpers(), logger.Named("enqueuer"))
+ require.NoError(t, err)
+
+ user := createSampleUser(t, store)
+
+ // Build fingerprints for the two different series we expect.
+ methodTemplateFP := fingerprintLabels(notifications.LabelMethod, string(method), notifications.LabelTemplateID, template.String())
+ methodFP := fingerprintLabels(notifications.LabelMethod, string(method))
+
+ expected := map[string]func(metric *dto.Metric, series string) bool{
+ "coderd_notifications_dispatch_attempts_total": func(metric *dto.Metric, series string) bool {
+ // This metric has 3 possible dispositions; find if any of them match first before we check the metric's value.
+ results := map[string]float64{
+ notifications.ResultSuccess: 1, // Only 1 successful delivery.
+ notifications.ResultTempFail: maxAttempts - 1, // 2 temp failures, on the 3rd it'll be marked permanent failure.
+ notifications.ResultPermFail: 1, // 1 permanent failure after retries exhausted.
+ }
+
+ var match string
+ for result, val := range results {
+ seriesFP := fingerprintLabels(notifications.LabelMethod, string(method), notifications.LabelTemplateID, template.String(), notifications.LabelResult, result)
+ if !hasMatchingFingerprint(metric, seriesFP) {
+ continue
+ }
+
+ match = result
+
+ if debug {
+ t.Logf("coderd_notifications_dispatch_attempts_total{result=%q} == %v: %v", result, val, metric.Counter.GetValue())
+ }
+
+ break
+ }
+
+ // Could not find a matching series.
+ if match == "" {
+ assert.Failf(t, "found unexpected series %q", series)
+ return false
+ }
+
+ // nolint:forcetypeassert // Already checked above.
+ target := results[match]
+ return metric.Counter.GetValue() == target
+ },
+ "coderd_notifications_retry_count": func(metric *dto.Metric, series string) bool {
+ assert.Truef(t, hasMatchingFingerprint(metric, methodTemplateFP), "found unexpected series %q", series)
+
+ if debug {
+ t.Logf("coderd_notifications_retry_count == %v: %v", maxAttempts-1, metric.Counter.GetValue())
+ }
+
+ // 1 original attempts + 2 retries = maxAttempts
+ return metric.Counter.GetValue() == maxAttempts-1
+ },
+ "coderd_notifications_queued_seconds": func(metric *dto.Metric, series string) bool {
+ assert.Truef(t, hasMatchingFingerprint(metric, methodFP), "found unexpected series %q", series)
+
+ if debug {
+ t.Logf("coderd_notifications_queued_seconds > 0: %v", metric.Histogram.GetSampleSum())
+ }
+
+ // Notifications will queue for a non-zero amount of time.
+ return metric.Histogram.GetSampleSum() > 0
+ },
+ "coderd_notifications_dispatcher_send_seconds": func(metric *dto.Metric, series string) bool {
+ assert.Truef(t, hasMatchingFingerprint(metric, methodFP), "found unexpected series %q", series)
+
+ if debug {
+ t.Logf("coderd_notifications_dispatcher_send_seconds > 0: %v", metric.Histogram.GetSampleSum())
+ }
+
+ // Dispatches should take a non-zero amount of time.
+ return metric.Histogram.GetSampleSum() > 0
+ },
+ "coderd_notifications_inflight_dispatches": func(metric *dto.Metric, series string) bool {
+ // This is a gauge, so it can be difficult to get the timing right to catch it.
+ // See TestInflightDispatchesMetric for a more precise test.
+ return true
+ },
+ "coderd_notifications_pending_updates": func(metric *dto.Metric, series string) bool {
+ // This is a gauge, so it can be difficult to get the timing right to catch it.
+ // See TestPendingUpdatesMetric for a more precise test.
+ return true
+ },
+ "coderd_notifications_synced_updates_total": func(metric *dto.Metric, series string) bool {
+ if debug {
+ t.Logf("coderd_notifications_synced_updates_total = %v: %v", maxAttempts+1, metric.Counter.GetValue())
+ }
+
+ // 1 message will exceed its maxAttempts, 1 will succeed on the first try.
+ return metric.Counter.GetValue() == maxAttempts+1
+ },
+ }
+
+ // WHEN: 2 notifications are enqueued, 1 of which will fail until its retries are exhausted, and another which will succeed
+ _, err = enq.Enqueue(ctx, user.ID, template, map[string]string{"type": "success"}, "test") // this will succeed
+ require.NoError(t, err)
+ _, err = enq.Enqueue(ctx, user.ID, template, map[string]string{"type": "failure"}, "test2") // this will fail and retry (maxAttempts - 1) times
+ require.NoError(t, err)
+
+ mgr.Run(ctx)
+
+ // THEN: expect all the defined metrics to be present and have their expected values
+ require.EventuallyWithT(t, func(ct *assert.CollectT) {
+ handler.mu.RLock()
+ defer handler.mu.RUnlock()
+
+ gathered, err := reg.Gather()
+ assert.NoError(t, err)
+
+ succeeded := len(handler.succeeded)
+ failed := len(handler.failed)
+ if debug {
+ t.Logf("SUCCEEDED == 1: %v, FAILED == %v: %v\n", succeeded, maxAttempts, failed)
+ }
+
+ // Ensure that all metrics have a) the expected label combinations (series) and b) the expected values.
+ for _, family := range gathered {
+ hasExpectedValue, ok := expected[family.GetName()]
+ if !assert.Truef(ct, ok, "found unexpected metric family %q", family.GetName()) {
+ t.Logf("found unexpected metric family %q", family.GetName())
+ // Bail out fast if precondition is not met.
+ ct.FailNow()
+ }
+
+ for _, metric := range family.Metric {
+ assert.True(ct, hasExpectedValue(metric, metric.String()))
+ }
+ }
+
+ // One message will succeed.
+ assert.Equal(ct, succeeded, 1)
+ // One message will fail, and exhaust its maxAttempts.
+ assert.Equal(ct, failed, maxAttempts)
+ }, testutil.WaitShort, testutil.IntervalFast)
+}
+
+func TestPendingUpdatesMetric(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ ctx, logger, store := setupInMemory(t)
+
+ reg := prometheus.NewRegistry()
+ metrics := notifications.NewMetrics(reg)
+ template := notifications.TemplateWorkspaceDeleted
+
+ const method = database.NotificationMethodSmtp
+
+ // GIVEN: a notification manager whose store updates are intercepted so we can read the number of pending updates set in the metric
+ cfg := defaultNotificationsConfig(method)
+ cfg.FetchInterval = serpent.Duration(time.Millisecond * 50)
+ cfg.RetryInterval = serpent.Duration(time.Hour) // Delay retries so they don't interfere.
+ cfg.StoreSyncInterval = serpent.Duration(time.Millisecond * 100)
+
+ syncer := &syncInterceptor{Store: store}
+ interceptor := newUpdateSignallingInterceptor(syncer)
+ mgr, err := notifications.NewManager(cfg, interceptor, metrics, logger.Named("manager"))
+ require.NoError(t, err)
+ t.Cleanup(func() {
+ assert.NoError(t, mgr.Stop(ctx))
+ })
+ handler := &fakeHandler{}
+ mgr.WithHandlers(map[database.NotificationMethod]notifications.Handler{
+ method: handler,
+ })
+
+ enq, err := notifications.NewStoreEnqueuer(cfg, store, defaultHelpers(), logger.Named("enqueuer"))
+ require.NoError(t, err)
+
+ user := createSampleUser(t, store)
+
+ // WHEN: 2 notifications are enqueued, one of which will fail and one which will succeed
+ _, err = enq.Enqueue(ctx, user.ID, template, map[string]string{"type": "success"}, "test") // this will succeed
+ require.NoError(t, err)
+ _, err = enq.Enqueue(ctx, user.ID, template, map[string]string{"type": "failure"}, "test2") // this will fail and retry (maxAttempts - 1) times
+ require.NoError(t, err)
+
+ mgr.Run(ctx)
+
+ // THEN:
+ // Wait until the handler has dispatched the given notifications.
+ require.Eventually(t, func() bool {
+ handler.mu.RLock()
+ defer handler.mu.RUnlock()
+
+ return len(handler.succeeded) == 1 && len(handler.failed) == 1
+ }, testutil.WaitShort, testutil.IntervalFast)
+
+ // Wait until we intercept the calls to sync the pending updates to the store.
+ success := testutil.RequireRecvCtx(testutil.Context(t, testutil.WaitShort), t, interceptor.updateSuccess)
+ failure := testutil.RequireRecvCtx(testutil.Context(t, testutil.WaitShort), t, interceptor.updateFailure)
+
+ // Wait for the metric to be updated with the expected count of metrics.
+ require.Eventually(t, func() bool {
+ return promtest.ToFloat64(metrics.PendingUpdates) == float64(success+failure)
+ }, testutil.WaitShort, testutil.IntervalFast)
+
+ // Unpause the interceptor so the updates can proceed.
+ interceptor.unpause()
+
+ // Validate that the store synced the expected number of updates.
+ require.Eventually(t, func() bool {
+ return syncer.sent.Load() == 1 && syncer.failed.Load() == 1
+ }, testutil.WaitShort, testutil.IntervalFast)
+
+ // Wait for the updates to be synced and the metric to reflect that.
+ require.Eventually(t, func() bool {
+ return promtest.ToFloat64(metrics.PendingUpdates) == 0
+ }, testutil.WaitShort, testutil.IntervalFast)
+}
+
+func TestInflightDispatchesMetric(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ ctx, logger, store := setupInMemory(t)
+
+ reg := prometheus.NewRegistry()
+ metrics := notifications.NewMetrics(reg)
+ template := notifications.TemplateWorkspaceDeleted
+
+ const method = database.NotificationMethodSmtp
+
+ // GIVEN: a notification manager whose dispatches are intercepted and delayed to measure the number of inflight requests
+ cfg := defaultNotificationsConfig(method)
+ cfg.LeaseCount = 10
+ cfg.FetchInterval = serpent.Duration(time.Millisecond * 50)
+ cfg.RetryInterval = serpent.Duration(time.Hour) // Delay retries so they don't interfere.
+ cfg.StoreSyncInterval = serpent.Duration(time.Millisecond * 100)
+
+ mgr, err := notifications.NewManager(cfg, store, metrics, logger.Named("manager"))
+ require.NoError(t, err)
+ t.Cleanup(func() {
+ assert.NoError(t, mgr.Stop(ctx))
+ })
+
+ handler := &fakeHandler{}
+ // Delayer will delay all dispatches by 2x fetch intervals to ensure we catch the requests inflight.
+ delayer := newDelayingHandler(cfg.FetchInterval.Value()*2, handler)
+ mgr.WithHandlers(map[database.NotificationMethod]notifications.Handler{
+ method: delayer,
+ })
+
+ enq, err := notifications.NewStoreEnqueuer(cfg, store, defaultHelpers(), logger.Named("enqueuer"))
+ require.NoError(t, err)
+
+ user := createSampleUser(t, store)
+
+ // WHEN: notifications are enqueued which will succeed (and be delayed during dispatch)
+ const msgCount = 2
+ for i := 0; i < msgCount; i++ {
+ _, err = enq.Enqueue(ctx, user.ID, template, map[string]string{"type": "success"}, "test")
+ require.NoError(t, err)
+ }
+
+ mgr.Run(ctx)
+
+ // THEN:
+ // Ensure we see the dispatches of the messages inflight.
+ require.Eventually(t, func() bool {
+ return promtest.ToFloat64(metrics.InflightDispatches.WithLabelValues(string(method), template.String())) == msgCount
+ }, testutil.WaitShort, testutil.IntervalFast)
+
+ // Wait until the handler has dispatched the given notifications.
+ require.Eventually(t, func() bool {
+ handler.mu.RLock()
+ defer handler.mu.RUnlock()
+
+ return len(handler.succeeded) == msgCount
+ }, testutil.WaitShort, testutil.IntervalFast)
+
+ // Wait for the updates to be synced and the metric to reflect that.
+ require.Eventually(t, func() bool {
+ return promtest.ToFloat64(metrics.InflightDispatches) == 0
+ }, testutil.WaitShort, testutil.IntervalFast)
+}
+
+// hasMatchingFingerprint checks if the given metric's series fingerprint matches the reference fingerprint.
+func hasMatchingFingerprint(metric *dto.Metric, fp model.Fingerprint) bool {
+ return fingerprintLabelPairs(metric.Label) == fp
+}
+
+// fingerprintLabelPairs produces a fingerprint unique to the given combination of label pairs.
+func fingerprintLabelPairs(lbs []*dto.LabelPair) model.Fingerprint {
+ pairs := make([]string, 0, len(lbs)*2)
+ for _, lp := range lbs {
+ pairs = append(pairs, lp.GetName(), lp.GetValue())
+ }
+
+ return fingerprintLabels(pairs...)
+}
+
+// fingerprintLabels produces a fingerprint unique to the given pairs of label values.
+// MUST contain an even number of arguments (key:value), otherwise it will panic.
+func fingerprintLabels(lbs ...string) model.Fingerprint {
+ if len(lbs)%2 != 0 {
+ panic("imbalanced set of label pairs given")
+ }
+
+ lbsSet := make(model.LabelSet, len(lbs)/2)
+ for i := 0; i < len(lbs); i += 2 {
+ k := lbs[i]
+ v := lbs[i+1]
+ lbsSet[model.LabelName(k)] = model.LabelValue(v)
+ }
+
+ return lbsSet.Fingerprint() // FastFingerprint does not sort the labels.
+}
+
+// updateSignallingInterceptor intercepts bulk update calls to the store, and waits on the "proceed" condition to be
+// signaled by the caller so it can continue.
+type updateSignallingInterceptor struct {
+ notifications.Store
+
+ pause chan any
+
+ updateSuccess chan int
+ updateFailure chan int
+}
+
+func newUpdateSignallingInterceptor(interceptor notifications.Store) *updateSignallingInterceptor {
+ return &updateSignallingInterceptor{
+ Store: interceptor,
+
+ pause: make(chan any, 1),
+
+ updateSuccess: make(chan int, 1),
+ updateFailure: make(chan int, 1),
+ }
+}
+
+func (u *updateSignallingInterceptor) unpause() {
+ close(u.pause)
+}
+
+func (u *updateSignallingInterceptor) BulkMarkNotificationMessagesSent(ctx context.Context, arg database.BulkMarkNotificationMessagesSentParams) (int64, error) {
+ u.updateSuccess <- len(arg.IDs)
+
+ // Wait until signaled so we have a chance to read the number of pending updates.
+ <-u.pause
+
+ return u.Store.BulkMarkNotificationMessagesSent(ctx, arg)
+}
+
+func (u *updateSignallingInterceptor) BulkMarkNotificationMessagesFailed(ctx context.Context, arg database.BulkMarkNotificationMessagesFailedParams) (int64, error) {
+ u.updateFailure <- len(arg.IDs)
+
+ // Wait until signaled so we have a chance to read the number of pending updates.
+ <-u.pause
+
+ return u.Store.BulkMarkNotificationMessagesFailed(ctx, arg)
+}
+
+type delayingHandler struct {
+ h notifications.Handler
+
+ delay time.Duration
+}
+
+func newDelayingHandler(delay time.Duration, handler notifications.Handler) *delayingHandler {
+ return &delayingHandler{
+ delay: delay,
+ h: handler,
+ }
+}
+
+func (d *delayingHandler) Dispatcher(payload types.MessagePayload, title, body string) (dispatch.DeliveryFunc, error) {
+ deliverFn, err := d.h.Dispatcher(payload, title, body)
+ if err != nil {
+ return nil, err
+ }
+
+ return func(ctx context.Context, msgID uuid.UUID) (retryable bool, err error) {
+ time.Sleep(d.delay)
+
+ return deliverFn(ctx, msgID)
+ }, nil
+}
diff --git a/coderd/notifications/notifications_test.go b/coderd/notifications/notifications_test.go
new file mode 100644
index 0000000000000..37fe4a2ce5ce3
--- /dev/null
+++ b/coderd/notifications/notifications_test.go
@@ -0,0 +1,761 @@
+package notifications_test
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "net/http/httptest"
+ "net/url"
+ "slices"
+ "sort"
+ "sync"
+ "sync/atomic"
+ "testing"
+ "time"
+
+ "golang.org/x/xerrors"
+
+ "github.com/google/uuid"
+ smtpmock "github.com/mocktools/go-smtp-mock/v2"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+ "go.uber.org/goleak"
+
+ "github.com/coder/serpent"
+
+ "github.com/coder/coder/v2/coderd/database"
+ "github.com/coder/coder/v2/coderd/database/dbgen"
+ "github.com/coder/coder/v2/coderd/database/dbtestutil"
+ "github.com/coder/coder/v2/coderd/notifications"
+ "github.com/coder/coder/v2/coderd/notifications/dispatch"
+ "github.com/coder/coder/v2/coderd/notifications/render"
+ "github.com/coder/coder/v2/coderd/notifications/types"
+ "github.com/coder/coder/v2/coderd/util/syncmap"
+ "github.com/coder/coder/v2/codersdk"
+ "github.com/coder/coder/v2/testutil"
+)
+
+func TestMain(m *testing.M) {
+ goleak.VerifyTestMain(m)
+}
+
+// TestBasicNotificationRoundtrip enqueues a message to the store, waits for it to be acquired by a notifier,
+// passes it off to a fake handler, and ensures the results are synchronized to the store.
+func TestBasicNotificationRoundtrip(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ if !dbtestutil.WillUsePostgres() {
+ t.Skip("This test requires postgres; it relies on business-logic only implemented in the database")
+ }
+
+ ctx, logger, db := setup(t)
+ method := database.NotificationMethodSmtp
+
+ // GIVEN: a manager with standard config but a faked dispatch handler
+ handler := &fakeHandler{}
+ interceptor := &syncInterceptor{Store: db}
+ cfg := defaultNotificationsConfig(method)
+ cfg.RetryInterval = serpent.Duration(time.Hour) // Ensure retries don't interfere with the test
+ mgr, err := notifications.NewManager(cfg, interceptor, createMetrics(), logger.Named("manager"))
+ require.NoError(t, err)
+ mgr.WithHandlers(map[database.NotificationMethod]notifications.Handler{method: handler})
+ t.Cleanup(func() {
+ assert.NoError(t, mgr.Stop(ctx))
+ })
+ enq, err := notifications.NewStoreEnqueuer(cfg, db, defaultHelpers(), logger.Named("enqueuer"))
+ require.NoError(t, err)
+
+ user := createSampleUser(t, db)
+
+ // WHEN: 2 messages are enqueued
+ sid, err := enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{"type": "success"}, "test")
+ require.NoError(t, err)
+ fid, err := enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{"type": "failure"}, "test")
+ require.NoError(t, err)
+
+ mgr.Run(ctx)
+
+ // THEN: we expect that the handler will have received the notifications for dispatch
+ require.Eventually(t, func() bool {
+ handler.mu.RLock()
+ defer handler.mu.RUnlock()
+ return slices.Contains(handler.succeeded, sid.String()) &&
+ slices.Contains(handler.failed, fid.String())
+ }, testutil.WaitLong, testutil.IntervalFast)
+
+ // THEN: we expect the store to be called with the updates of the earlier dispatches
+ require.Eventually(t, func() bool {
+ return interceptor.sent.Load() == 1 &&
+ interceptor.failed.Load() == 1
+ }, testutil.WaitLong, testutil.IntervalFast)
+
+ // THEN: we verify that the store contains notifications in their expected state
+ success, err := db.GetNotificationMessagesByStatus(ctx, database.GetNotificationMessagesByStatusParams{
+ Status: database.NotificationMessageStatusSent,
+ Limit: 10,
+ })
+ require.NoError(t, err)
+ require.Len(t, success, 1)
+ failed, err := db.GetNotificationMessagesByStatus(ctx, database.GetNotificationMessagesByStatusParams{
+ Status: database.NotificationMessageStatusTemporaryFailure,
+ Limit: 10,
+ })
+ require.NoError(t, err)
+ require.Len(t, failed, 1)
+}
+
+func TestSMTPDispatch(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ ctx, logger, db := setupInMemory(t)
+
+ // start mock SMTP server
+ mockSMTPSrv := smtpmock.New(smtpmock.ConfigurationAttr{
+ LogToStdout: false,
+ LogServerActivity: true,
+ })
+ require.NoError(t, mockSMTPSrv.Start())
+ t.Cleanup(func() {
+ assert.NoError(t, mockSMTPSrv.Stop())
+ })
+
+ // GIVEN: an SMTP setup referencing a mock SMTP server
+ const from = "danny@coder.com"
+ method := database.NotificationMethodSmtp
+ cfg := defaultNotificationsConfig(method)
+ cfg.SMTP = codersdk.NotificationsEmailConfig{
+ From: from,
+ Smarthost: serpent.HostPort{Host: "localhost", Port: fmt.Sprintf("%d", mockSMTPSrv.PortNumber())},
+ Hello: "localhost",
+ }
+ handler := newDispatchInterceptor(dispatch.NewSMTPHandler(cfg.SMTP, logger.Named("smtp")))
+ mgr, err := notifications.NewManager(cfg, db, createMetrics(), logger.Named("manager"))
+ require.NoError(t, err)
+ mgr.WithHandlers(map[database.NotificationMethod]notifications.Handler{method: handler})
+ t.Cleanup(func() {
+ assert.NoError(t, mgr.Stop(ctx))
+ })
+ enq, err := notifications.NewStoreEnqueuer(cfg, db, defaultHelpers(), logger.Named("enqueuer"))
+ require.NoError(t, err)
+
+ user := createSampleUser(t, db)
+
+ // WHEN: a message is enqueued
+ msgID, err := enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{}, "test")
+ require.NoError(t, err)
+
+ mgr.Run(ctx)
+
+ // THEN: wait until the dispatch interceptor validates that the messages were dispatched
+ require.Eventually(t, func() bool {
+ assert.Nil(t, handler.lastErr.Load())
+ assert.True(t, handler.retryable.Load() == 0)
+ return handler.sent.Load() == 1
+ }, testutil.WaitLong, testutil.IntervalMedium)
+
+ // THEN: we verify that the expected message was received by the mock SMTP server
+ msgs := mockSMTPSrv.MessagesAndPurge()
+ require.Len(t, msgs, 1)
+ require.Contains(t, msgs[0].MsgRequest(), fmt.Sprintf("From: %s", from))
+ require.Contains(t, msgs[0].MsgRequest(), fmt.Sprintf("To: %s", user.Email))
+ require.Contains(t, msgs[0].MsgRequest(), fmt.Sprintf("Message-Id: %s", msgID))
+}
+
+func TestWebhookDispatch(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ ctx, logger, db := setupInMemory(t)
+
+ sent := make(chan dispatch.WebhookPayload, 1)
+ // Mock server to simulate webhook endpoint.
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ var payload dispatch.WebhookPayload
+ err := json.NewDecoder(r.Body).Decode(&payload)
+ assert.NoError(t, err)
+ assert.Equal(t, "application/json", r.Header.Get("Content-Type"))
+
+ w.WriteHeader(http.StatusOK)
+ _, err = w.Write([]byte("noted."))
+ assert.NoError(t, err)
+ sent <- payload
+ }))
+ defer server.Close()
+
+ endpoint, err := url.Parse(server.URL)
+ require.NoError(t, err)
+
+ // GIVEN: a webhook setup referencing a mock HTTP server to receive the webhook
+ cfg := defaultNotificationsConfig(database.NotificationMethodWebhook)
+ cfg.Webhook = codersdk.NotificationsWebhookConfig{
+ Endpoint: *serpent.URLOf(endpoint),
+ }
+ mgr, err := notifications.NewManager(cfg, db, createMetrics(), logger.Named("manager"))
+ require.NoError(t, err)
+ t.Cleanup(func() {
+ assert.NoError(t, mgr.Stop(ctx))
+ })
+ enq, err := notifications.NewStoreEnqueuer(cfg, db, defaultHelpers(), logger.Named("enqueuer"))
+ require.NoError(t, err)
+
+ const (
+ email = "bob@coder.com"
+ name = "Robert McBobbington"
+ username = "bob"
+ )
+ user := dbgen.User(t, db, database.User{
+ Email: email,
+ Username: username,
+ Name: name,
+ })
+
+ // WHEN: a notification is enqueued (including arbitrary labels)
+ input := map[string]string{
+ "a": "b",
+ "c": "d",
+ }
+ msgID, err := enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, input, "test")
+ require.NoError(t, err)
+
+ mgr.Run(ctx)
+
+ // THEN: the webhook is received by the mock server and has the expected contents
+ payload := testutil.RequireRecvCtx(testutil.Context(t, testutil.WaitShort), t, sent)
+ require.EqualValues(t, "1.0", payload.Version)
+ require.Equal(t, *msgID, payload.MsgID)
+ require.Equal(t, payload.Payload.Labels, input)
+ require.Equal(t, payload.Payload.UserEmail, email)
+ // UserName is coalesced from `name` and `username`; in this case `name` wins.
+ // This is not strictly necessary for this test, but it's testing some side logic which is too small for its own test.
+ require.Equal(t, payload.Payload.UserName, name)
+ require.Equal(t, payload.Payload.UserUsername, username)
+ // Right now we don't have a way to query notification templates by ID in dbmem, and it's not necessary to add this
+ // just to satisfy this test. We can safely assume that as long as this value is not empty that the given value was delivered.
+ require.NotEmpty(t, payload.Payload.NotificationName)
+}
+
+// TestBackpressure validates that delays in processing the buffered updates will result in slowed dequeue rates.
+// As a side-effect, this also tests the graceful shutdown and flushing of the buffers.
+func TestBackpressure(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ if !dbtestutil.WillUsePostgres() {
+ t.Skip("This test requires postgres; it relies on business-logic only implemented in the database")
+ }
+
+ ctx, logger, db := setup(t)
+
+ // Mock server to simulate webhook endpoint.
+ var received atomic.Int32
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ var payload dispatch.WebhookPayload
+ err := json.NewDecoder(r.Body).Decode(&payload)
+ assert.NoError(t, err)
+
+ w.WriteHeader(http.StatusOK)
+ _, err = w.Write([]byte("noted."))
+ assert.NoError(t, err)
+
+ received.Add(1)
+ }))
+ defer server.Close()
+
+ endpoint, err := url.Parse(server.URL)
+ require.NoError(t, err)
+
+ method := database.NotificationMethodWebhook
+ cfg := defaultNotificationsConfig(method)
+ cfg.Webhook = codersdk.NotificationsWebhookConfig{
+ Endpoint: *serpent.URLOf(endpoint),
+ }
+
+ // Tune the queue to fetch often.
+ const fetchInterval = time.Millisecond * 200
+ const batchSize = 10
+ cfg.FetchInterval = serpent.Duration(fetchInterval)
+ cfg.LeaseCount = serpent.Int64(batchSize)
+
+ // Shrink buffers down and increase flush interval to provoke backpressure.
+ // Flush buffers every 5 fetch intervals.
+ const syncInterval = time.Second
+ cfg.StoreSyncInterval = serpent.Duration(syncInterval)
+ cfg.StoreSyncBufferSize = serpent.Int64(2)
+
+ handler := newDispatchInterceptor(dispatch.NewWebhookHandler(cfg.Webhook, logger.Named("webhook")))
+
+ // Intercept calls to submit the buffered updates to the store.
+ storeInterceptor := &syncInterceptor{Store: db}
+
+ // GIVEN: a notification manager whose updates will be intercepted
+ mgr, err := notifications.NewManager(cfg, storeInterceptor, createMetrics(), logger.Named("manager"))
+ require.NoError(t, err)
+ mgr.WithHandlers(map[database.NotificationMethod]notifications.Handler{method: handler})
+ enq, err := notifications.NewStoreEnqueuer(cfg, db, defaultHelpers(), logger.Named("enqueuer"))
+ require.NoError(t, err)
+
+ user := createSampleUser(t, db)
+
+ // WHEN: a set of notifications are enqueued, which causes backpressure due to the batchSize which can be processed per fetch
+ const totalMessages = 30
+ for i := 0; i < totalMessages; i++ {
+ _, err = enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{"i": fmt.Sprintf("%d", i)}, "test")
+ require.NoError(t, err)
+ }
+
+ // Start the notifier.
+ mgr.Run(ctx)
+
+ // THEN:
+
+ // Wait for 3 fetch intervals, then check progress.
+ time.Sleep(fetchInterval * 3)
+
+ // We expect the notifier will have dispatched ONLY the initial batch of messages.
+ // In other words, the notifier should have dispatched 3 batches by now, but because the buffered updates have not
+ // been processed: there is backpressure.
+ require.EqualValues(t, batchSize, handler.sent.Load()+handler.err.Load())
+ // We expect that the store will have received NO updates.
+ require.EqualValues(t, 0, storeInterceptor.sent.Load()+storeInterceptor.failed.Load())
+
+ // However, when we Stop() the manager the backpressure will be relieved and the buffered updates will ALL be flushed,
+ // since all the goroutines that were blocked (on writing updates to the buffer) will be unblocked and will complete.
+ require.NoError(t, mgr.Stop(ctx))
+ require.EqualValues(t, batchSize, storeInterceptor.sent.Load()+storeInterceptor.failed.Load())
+}
+
+func TestRetries(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ if !dbtestutil.WillUsePostgres() {
+ t.Skip("This test requires postgres; it relies on business-logic only implemented in the database")
+ }
+
+ const maxAttempts = 3
+ ctx, logger, db := setup(t)
+
+ // GIVEN: a mock HTTP server which will receive webhooksand a map to track the dispatch attempts
+
+ receivedMap := syncmap.New[uuid.UUID, int]()
+ // Mock server to simulate webhook endpoint.
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ var payload dispatch.WebhookPayload
+ err := json.NewDecoder(r.Body).Decode(&payload)
+ assert.NoError(t, err)
+
+ count, _ := receivedMap.LoadOrStore(payload.MsgID, 0)
+ count++
+ receivedMap.Store(payload.MsgID, count)
+
+ // Let the request succeed if this is its last attempt.
+ if count == maxAttempts {
+ w.WriteHeader(http.StatusOK)
+ _, err = w.Write([]byte("noted."))
+ assert.NoError(t, err)
+ return
+ }
+
+ w.WriteHeader(http.StatusInternalServerError)
+ _, err = w.Write([]byte("retry again later..."))
+ assert.NoError(t, err)
+ }))
+ defer server.Close()
+
+ endpoint, err := url.Parse(server.URL)
+ require.NoError(t, err)
+
+ method := database.NotificationMethodWebhook
+ cfg := defaultNotificationsConfig(method)
+ cfg.Webhook = codersdk.NotificationsWebhookConfig{
+ Endpoint: *serpent.URLOf(endpoint),
+ }
+
+ cfg.MaxSendAttempts = maxAttempts
+
+ // Tune intervals low to speed up test.
+ cfg.StoreSyncInterval = serpent.Duration(time.Millisecond * 100)
+ cfg.RetryInterval = serpent.Duration(time.Second) // query uses second-precision
+ cfg.FetchInterval = serpent.Duration(time.Millisecond * 100)
+
+ handler := newDispatchInterceptor(dispatch.NewWebhookHandler(cfg.Webhook, logger.Named("webhook")))
+
+ // Intercept calls to submit the buffered updates to the store.
+ storeInterceptor := &syncInterceptor{Store: db}
+
+ mgr, err := notifications.NewManager(cfg, storeInterceptor, createMetrics(), logger.Named("manager"))
+ require.NoError(t, err)
+ t.Cleanup(func() {
+ assert.NoError(t, mgr.Stop(ctx))
+ })
+ mgr.WithHandlers(map[database.NotificationMethod]notifications.Handler{method: handler})
+ enq, err := notifications.NewStoreEnqueuer(cfg, db, defaultHelpers(), logger.Named("enqueuer"))
+ require.NoError(t, err)
+
+ user := createSampleUser(t, db)
+
+ // WHEN: a few notifications are enqueued, which will all fail until their final retry (determined by the mock server)
+ const msgCount = 5
+ for i := 0; i < msgCount; i++ {
+ _, err = enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{"i": fmt.Sprintf("%d", i)}, "test")
+ require.NoError(t, err)
+ }
+
+ mgr.Run(ctx)
+
+ // THEN: we expect to see all but the final attempts failing
+ require.Eventually(t, func() bool {
+ // We expect all messages to fail all attempts but the final;
+ return storeInterceptor.failed.Load() == msgCount*(maxAttempts-1) &&
+ // ...and succeed on the final attempt.
+ storeInterceptor.sent.Load() == msgCount
+ }, testutil.WaitLong, testutil.IntervalFast)
+}
+
+// TestExpiredLeaseIsRequeued validates that notification messages which are left in "leased" status will be requeued once their lease expires.
+// "leased" is the status which messages are set to when they are acquired for processing, and this should not be a terminal
+// state unless the Manager shuts down ungracefully; the Manager is responsible for updating these messages' statuses once
+// they have been processed.
+func TestExpiredLeaseIsRequeued(t *testing.T) {
+ t.Parallel()
+
+ // SETUP
+ if !dbtestutil.WillUsePostgres() {
+ t.Skip("This test requires postgres; it relies on business-logic only implemented in the database")
+ }
+
+ ctx, logger, db := setup(t)
+
+ // GIVEN: a manager which has its updates intercepted and paused until measurements can be taken
+
+ const (
+ leasePeriod = time.Second
+ msgCount = 5
+ method = database.NotificationMethodSmtp
+ )
+
+ cfg := defaultNotificationsConfig(method)
+ // Set low lease period to speed up tests.
+ cfg.LeasePeriod = serpent.Duration(leasePeriod)
+ cfg.DispatchTimeout = serpent.Duration(leasePeriod - time.Millisecond)
+
+ noopInterceptor := newNoopStoreSyncer(db)
+
+ mgrCtx, cancelManagerCtx := context.WithCancel(context.Background())
+ t.Cleanup(cancelManagerCtx)
+
+ mgr, err := notifications.NewManager(cfg, noopInterceptor, createMetrics(), logger.Named("manager"))
+ require.NoError(t, err)
+ enq, err := notifications.NewStoreEnqueuer(cfg, db, defaultHelpers(), logger.Named("enqueuer"))
+ require.NoError(t, err)
+
+ user := createSampleUser(t, db)
+
+ // WHEN: a few notifications are enqueued which will all succeed
+ var msgs []string
+ for i := 0; i < msgCount; i++ {
+ id, err := enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{"type": "success"}, "test")
+ require.NoError(t, err)
+ msgs = append(msgs, id.String())
+ }
+
+ mgr.Run(mgrCtx)
+
+ // THEN:
+
+ // Wait for the messages to be acquired
+ <-noopInterceptor.acquiredChan
+ // Then cancel the context, forcing the notification manager to shutdown ungracefully (simulating a crash); leaving messages in "leased" status.
+ cancelManagerCtx()
+
+ // Fetch any messages currently in "leased" status, and verify that they're exactly the ones we enqueued.
+ leased, err := db.GetNotificationMessagesByStatus(ctx, database.GetNotificationMessagesByStatusParams{
+ Status: database.NotificationMessageStatusLeased,
+ Limit: msgCount,
+ })
+ require.NoError(t, err)
+
+ var leasedIDs []string
+ for _, msg := range leased {
+ leasedIDs = append(leasedIDs, msg.ID.String())
+ }
+
+ sort.Strings(msgs)
+ sort.Strings(leasedIDs)
+ require.EqualValues(t, msgs, leasedIDs)
+
+ // Wait out the lease period; all messages should be eligible to be re-acquired.
+ time.Sleep(leasePeriod + time.Millisecond)
+
+ // Start a new notification manager.
+ // Intercept calls to submit the buffered updates to the store.
+ storeInterceptor := &syncInterceptor{Store: db}
+ handler := newDispatchInterceptor(&fakeHandler{})
+ mgr, err = notifications.NewManager(cfg, storeInterceptor, createMetrics(), logger.Named("manager"))
+ require.NoError(t, err)
+ mgr.WithHandlers(map[database.NotificationMethod]notifications.Handler{method: handler})
+
+ // Use regular context now.
+ t.Cleanup(func() {
+ assert.NoError(t, mgr.Stop(ctx))
+ })
+ mgr.Run(ctx)
+
+ // Wait until all messages are sent & updates flushed to the database.
+ require.Eventually(t, func() bool {
+ return handler.sent.Load() == msgCount &&
+ storeInterceptor.sent.Load() == msgCount
+ }, testutil.WaitLong, testutil.IntervalFast)
+
+ // Validate that no more messages are in "leased" status.
+ leased, err = db.GetNotificationMessagesByStatus(ctx, database.GetNotificationMessagesByStatusParams{
+ Status: database.NotificationMessageStatusLeased,
+ Limit: msgCount,
+ })
+ require.NoError(t, err)
+ require.Len(t, leased, 0)
+}
+
+// TestInvalidConfig validates that misconfigurations lead to errors.
+func TestInvalidConfig(t *testing.T) {
+ t.Parallel()
+
+ _, logger, db := setupInMemory(t)
+
+ // GIVEN: invalid config with dispatch period <= lease period
+ const (
+ leasePeriod = time.Second
+ method = database.NotificationMethodSmtp
+ )
+ cfg := defaultNotificationsConfig(method)
+ cfg.LeasePeriod = serpent.Duration(leasePeriod)
+ cfg.DispatchTimeout = serpent.Duration(leasePeriod)
+
+ // WHEN: the manager is created with invalid config
+ _, err := notifications.NewManager(cfg, db, createMetrics(), logger.Named("manager"))
+
+ // THEN: the manager will fail to be created, citing invalid config as error
+ require.ErrorIs(t, err, notifications.ErrInvalidDispatchTimeout)
+}
+
+func TestNotifierPaused(t *testing.T) {
+ t.Parallel()
+
+ // setup
+ ctx, logger, db := setupInMemory(t)
+
+ // Prepare the test
+ handler := &fakeHandler{}
+ method := database.NotificationMethodSmtp
+ user := createSampleUser(t, db)
+
+ cfg := defaultNotificationsConfig(method)
+ mgr, err := notifications.NewManager(cfg, db, createMetrics(), logger.Named("manager"))
+ require.NoError(t, err)
+ mgr.WithHandlers(map[database.NotificationMethod]notifications.Handler{method: handler})
+ t.Cleanup(func() {
+ assert.NoError(t, mgr.Stop(ctx))
+ })
+ enq, err := notifications.NewStoreEnqueuer(cfg, db, defaultHelpers(), logger.Named("enqueuer"))
+ require.NoError(t, err)
+
+ mgr.Run(ctx)
+
+ // Notifier is on, enqueue the first message.
+ sid, err := enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{"type": "success"}, "test")
+ require.NoError(t, err)
+ require.Eventually(t, func() bool {
+ handler.mu.RLock()
+ defer handler.mu.RUnlock()
+ return slices.Contains(handler.succeeded, sid.String())
+ }, testutil.WaitShort, testutil.IntervalFast)
+
+ // Pause the notifier.
+ settingsJSON, err := json.Marshal(&codersdk.NotificationsSettings{NotifierPaused: true})
+ require.NoError(t, err)
+ err = db.UpsertNotificationsSettings(ctx, string(settingsJSON))
+ require.NoError(t, err)
+
+ // Notifier is paused, enqueue the next message.
+ sid, err = enq.Enqueue(ctx, user.ID, notifications.TemplateWorkspaceDeleted, map[string]string{"type": "success"}, "test")
+ require.NoError(t, err)
+ require.Eventually(t, func() bool {
+ pendingMessages, err := db.GetNotificationMessagesByStatus(ctx, database.GetNotificationMessagesByStatusParams{
+ Status: database.NotificationMessageStatusPending,
+ })
+ assert.NoError(t, err)
+ return len(pendingMessages) == 1
+ }, testutil.WaitShort, testutil.IntervalFast)
+
+ // Unpause the notifier.
+ settingsJSON, err = json.Marshal(&codersdk.NotificationsSettings{NotifierPaused: false})
+ require.NoError(t, err)
+ err = db.UpsertNotificationsSettings(ctx, string(settingsJSON))
+ require.NoError(t, err)
+
+ // Notifier is running again, message should be dequeued.
+ require.Eventually(t, func() bool {
+ handler.mu.RLock()
+ defer handler.mu.RUnlock()
+ return slices.Contains(handler.succeeded, sid.String())
+ }, testutil.WaitShort, testutil.IntervalFast)
+}
+
+func TestNotifcationTemplatesBody(t *testing.T) {
+ t.Parallel()
+
+ if !dbtestutil.WillUsePostgres() {
+ t.Skip("This test requires postgres; it relies on the notification templates added by migrations in the database")
+ }
+
+ tests := []struct {
+ name string
+ id uuid.UUID
+ payload types.MessagePayload
+ }{
+ {
+ name: "TemplateWorkspaceDeleted",
+ id: notifications.TemplateWorkspaceDeleted,
+ payload: types.MessagePayload{
+ UserName: "bobby",
+ Labels: map[string]string{
+ "name": "bobby-workspace",
+ "reason": "autodeleted due to dormancy",
+ "initiator": "autobuild",
+ },
+ },
+ },
+ {
+ name: "TemplateWorkspaceAutobuildFailed",
+ id: notifications.TemplateWorkspaceAutobuildFailed,
+ payload: types.MessagePayload{
+ UserName: "bobby",
+ Labels: map[string]string{
+ "name": "bobby-workspace",
+ "reason": "autostart",
+ },
+ },
+ },
+ {
+ name: "TemplateWorkspaceDormant",
+ id: notifications.TemplateWorkspaceDormant,
+ payload: types.MessagePayload{
+ UserName: "bobby",
+ Labels: map[string]string{
+ "name": "bobby-workspace",
+ "reason": "breached the template's threshold for inactivity",
+ "initiator": "autobuild",
+ "dormancyHours": "24",
+ },
+ },
+ },
+ {
+ name: "TemplateWorkspaceAutoUpdated",
+ id: notifications.TemplateWorkspaceAutoUpdated,
+ payload: types.MessagePayload{
+ UserName: "bobby",
+ Labels: map[string]string{
+ "name": "bobby-workspace",
+ "template_version_name": "1.0",
+ },
+ },
+ },
+ {
+ name: "TemplateWorkspaceMarkedForDeletion",
+ id: notifications.TemplateWorkspaceMarkedForDeletion,
+ payload: types.MessagePayload{
+ UserName: "bobby",
+ Labels: map[string]string{
+ "name": "bobby-workspace",
+ "reason": "template updated to new dormancy policy",
+ "dormancyHours": "24",
+ },
+ },
+ },
+ }
+
+ for _, tc := range tests {
+ tc := tc
+
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ _, _, sql := dbtestutil.NewDBWithSQLDB(t)
+
+ var (
+ titleTmpl string
+ bodyTmpl string
+ )
+ err := sql.
+ QueryRow("SELECT title_template, body_template FROM notification_templates WHERE id = $1 LIMIT 1", tc.id).
+ Scan(&titleTmpl, &bodyTmpl)
+ require.NoError(t, err, "failed to query body template for template:", tc.id)
+
+ title, err := render.GoTemplate(titleTmpl, tc.payload, nil)
+ require.NoError(t, err, "failed to render notification title template")
+ require.NotEmpty(t, title, "title should not be empty")
+
+ body, err := render.GoTemplate(bodyTmpl, tc.payload, nil)
+ require.NoError(t, err, "failed to render notification body template")
+ require.NotEmpty(t, body, "body should not be empty")
+ })
+ }
+}
+
+type fakeHandler struct {
+ mu sync.RWMutex
+ succeeded, failed []string
+}
+
+func (f *fakeHandler) Dispatcher(payload types.MessagePayload, _, _ string) (dispatch.DeliveryFunc, error) {
+ return func(_ context.Context, msgID uuid.UUID) (retryable bool, err error) {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+
+ if payload.Labels["type"] == "success" {
+ f.succeeded = append(f.succeeded, msgID.String())
+ return false, nil
+ }
+
+ f.failed = append(f.failed, msgID.String())
+ return true, xerrors.New("oops")
+ }, nil
+}
+
+// noopStoreSyncer pretends to perform store syncs, but does not; leading to messages being stuck in "leased" state.
+type noopStoreSyncer struct {
+ *acquireSignalingInterceptor
+}
+
+func newNoopStoreSyncer(db notifications.Store) *noopStoreSyncer {
+ return &noopStoreSyncer{newAcquireSignalingInterceptor(db)}
+}
+
+func (*noopStoreSyncer) BulkMarkNotificationMessagesSent(_ context.Context, arg database.BulkMarkNotificationMessagesSentParams) (int64, error) {
+ return int64(len(arg.IDs)), nil
+}
+
+func (*noopStoreSyncer) BulkMarkNotificationMessagesFailed(_ context.Context, arg database.BulkMarkNotificationMessagesFailedParams) (int64, error) {
+ return int64(len(arg.IDs)), nil
+}
+
+type acquireSignalingInterceptor struct {
+ notifications.Store
+ acquiredChan chan struct{}
+}
+
+func newAcquireSignalingInterceptor(db notifications.Store) *acquireSignalingInterceptor {
+ return &acquireSignalingInterceptor{
+ Store: db,
+ acquiredChan: make(chan struct{}, 1),
+ }
+}
+
+func (n *acquireSignalingInterceptor) AcquireNotificationMessages(ctx context.Context, params database.AcquireNotificationMessagesParams) ([]database.AcquireNotificationMessagesRow, error) {
+ messages, err := n.Store.AcquireNotificationMessages(ctx, params)
+ n.acquiredChan <- struct{}{}
+ return messages, err
+}
diff --git a/coderd/notifications/notifier.go b/coderd/notifications/notifier.go
new file mode 100644
index 0000000000000..c39de6168db81
--- /dev/null
+++ b/coderd/notifications/notifier.go
@@ -0,0 +1,326 @@
+package notifications
+
+import (
+ "context"
+ "encoding/json"
+ "sync"
+ "time"
+
+ "github.com/google/uuid"
+ "golang.org/x/sync/errgroup"
+ "golang.org/x/xerrors"
+
+ "github.com/coder/coder/v2/coderd/notifications/dispatch"
+ "github.com/coder/coder/v2/coderd/notifications/render"
+ "github.com/coder/coder/v2/coderd/notifications/types"
+ "github.com/coder/coder/v2/codersdk"
+
+ "cdr.dev/slog"
+
+ "github.com/coder/coder/v2/coderd/database"
+)
+
+// notifier is a consumer of the notifications_messages queue. It dequeues messages from that table and processes them
+// through a pipeline of fetch -> prepare -> render -> acquire handler -> deliver.
+type notifier struct {
+ id uuid.UUID
+ cfg codersdk.NotificationsConfig
+ log slog.Logger
+ store Store
+
+ tick *time.Ticker
+ stopOnce sync.Once
+ quit chan any
+ done chan any
+
+ method database.NotificationMethod
+ handlers map[database.NotificationMethod]Handler
+ metrics *Metrics
+}
+
+func newNotifier(cfg codersdk.NotificationsConfig, id uuid.UUID, log slog.Logger, db Store, hr map[database.NotificationMethod]Handler, method database.NotificationMethod, metrics *Metrics) *notifier {
+ return ¬ifier{
+ id: id,
+ cfg: cfg,
+ log: log.Named("notifier").With(slog.F("notifier_id", id)),
+ quit: make(chan any),
+ done: make(chan any),
+ tick: time.NewTicker(cfg.FetchInterval.Value()),
+ store: db,
+ handlers: hr,
+ method: method,
+ metrics: metrics,
+ }
+}
+
+// run is the main loop of the notifier.
+func (n *notifier) run(ctx context.Context, success chan<- dispatchResult, failure chan<- dispatchResult) error {
+ n.log.Info(ctx, "started")
+
+ defer func() {
+ close(n.done)
+ n.log.Info(context.Background(), "gracefully stopped")
+ }()
+
+ // TODO: idea from Cian: instead of querying the database on a short interval, we could wait for pubsub notifications.
+ // if 100 notifications are enqueued, we shouldn't activate this routine for each one; so how to debounce these?
+ // PLUS we should also have an interval (but a longer one, maybe 1m) to account for retries (those will not get
+ // triggered by a code path, but rather by a timeout expiring which makes the message retryable)
+ for {
+ select {
+ case <-ctx.Done():
+ return xerrors.Errorf("notifier %q context canceled: %w", n.id, ctx.Err())
+ case <-n.quit:
+ return nil
+ default:
+ }
+
+ // Check if notifier is not paused.
+ ok, err := n.ensureRunning(ctx)
+ if err != nil {
+ n.log.Warn(ctx, "failed to check notifier state", slog.Error(err))
+ }
+
+ if ok {
+ // Call process() immediately (i.e. don't wait an initial tick).
+ err = n.process(ctx, success, failure)
+ if err != nil {
+ n.log.Error(ctx, "failed to process messages", slog.Error(err))
+ }
+ }
+
+ // Shortcut to bail out quickly if stop() has been called or the context canceled.
+ select {
+ case <-ctx.Done():
+ return xerrors.Errorf("notifier %q context canceled: %w", n.id, ctx.Err())
+ case <-n.quit:
+ return nil
+ case <-n.tick.C:
+ // sleep until next invocation
+ }
+ }
+}
+
+// ensureRunning checks if notifier is not paused.
+func (n *notifier) ensureRunning(ctx context.Context) (bool, error) {
+ settingsJSON, err := n.store.GetNotificationsSettings(ctx)
+ if err != nil {
+ return false, xerrors.Errorf("get notifications settings: %w", err)
+ }
+
+ var settings codersdk.NotificationsSettings
+ if len(settingsJSON) == 0 {
+ return true, nil // settings.NotifierPaused is false by default
+ }
+
+ err = json.Unmarshal([]byte(settingsJSON), &settings)
+ if err != nil {
+ return false, xerrors.Errorf("unmarshal notifications settings")
+ }
+
+ if settings.NotifierPaused {
+ n.log.Debug(ctx, "notifier is paused, notifications will not be delivered")
+ }
+ return !settings.NotifierPaused, nil
+}
+
+// process is responsible for coordinating the retrieval, processing, and delivery of messages.
+// Messages are dispatched concurrently, but they may block when success/failure channels are full.
+//
+// NOTE: it is _possible_ that these goroutines could block for long enough to exceed CODER_NOTIFICATIONS_DISPATCH_TIMEOUT,
+// resulting in a failed attempt for each notification when their contexts are canceled; this is not possible with the
+// default configurations but could be brought about by an operator tuning things incorrectly.
+func (n *notifier) process(ctx context.Context, success chan<- dispatchResult, failure chan<- dispatchResult) error {
+ msgs, err := n.fetch(ctx)
+ if err != nil {
+ return xerrors.Errorf("fetch messages: %w", err)
+ }
+
+ n.log.Debug(ctx, "dequeued messages", slog.F("count", len(msgs)))
+
+ if len(msgs) == 0 {
+ return nil
+ }
+
+ var eg errgroup.Group
+ for _, msg := range msgs {
+ // A message failing to be prepared correctly should not affect other messages.
+ deliverFn, err := n.prepare(ctx, msg)
+ if err != nil {
+ n.log.Warn(ctx, "dispatcher construction failed", slog.F("msg_id", msg.ID), slog.Error(err))
+ failure <- n.newFailedDispatch(msg, err, false)
+
+ n.metrics.PendingUpdates.Set(float64(len(success) + len(failure)))
+ continue
+ }
+
+ eg.Go(func() error {
+ // Dispatch must only return an error for exceptional cases, NOT for failed messages.
+ return n.deliver(ctx, msg, deliverFn, success, failure)
+ })
+ }
+
+ if err = eg.Wait(); err != nil {
+ n.log.Debug(ctx, "dispatch failed", slog.Error(err))
+ return xerrors.Errorf("dispatch failed: %w", err)
+ }
+
+ n.log.Debug(ctx, "batch completed", slog.F("count", len(msgs)))
+ return nil
+}
+
+// fetch retrieves messages from the queue by "acquiring a lease" whereby this notifier is the exclusive handler of these
+// messages until they are dispatched - or until the lease expires (in exceptional cases).
+func (n *notifier) fetch(ctx context.Context) ([]database.AcquireNotificationMessagesRow, error) {
+ msgs, err := n.store.AcquireNotificationMessages(ctx, database.AcquireNotificationMessagesParams{
+ Count: int32(n.cfg.LeaseCount),
+ MaxAttemptCount: int32(n.cfg.MaxSendAttempts),
+ NotifierID: n.id,
+ LeaseSeconds: int32(n.cfg.LeasePeriod.Value().Seconds()),
+ })
+ if err != nil {
+ return nil, xerrors.Errorf("acquire messages: %w", err)
+ }
+
+ return msgs, nil
+}
+
+// prepare has two roles:
+// 1. render the title & body templates
+// 2. build a dispatcher from the given message, payload, and these templates - to be used for delivering the notification
+func (n *notifier) prepare(ctx context.Context, msg database.AcquireNotificationMessagesRow) (dispatch.DeliveryFunc, error) {
+ select {
+ case <-ctx.Done():
+ return nil, ctx.Err()
+ default:
+ }
+
+ // NOTE: when we change the format of the MessagePayload, we have to bump its version and handle unmarshalling
+ // differently here based on that version.
+ var payload types.MessagePayload
+ err := json.Unmarshal(msg.Payload, &payload)
+ if err != nil {
+ return nil, xerrors.Errorf("unmarshal payload: %w", err)
+ }
+
+ handler, ok := n.handlers[msg.Method]
+ if !ok {
+ return nil, xerrors.Errorf("failed to resolve handler %q", msg.Method)
+ }
+
+ var title, body string
+ if title, err = render.GoTemplate(msg.TitleTemplate, payload, nil); err != nil {
+ return nil, xerrors.Errorf("render title: %w", err)
+ }
+ if body, err = render.GoTemplate(msg.BodyTemplate, payload, nil); err != nil {
+ return nil, xerrors.Errorf("render body: %w", err)
+ }
+
+ return handler.Dispatcher(payload, title, body)
+}
+
+// deliver sends a given notification message via its defined method.
+// This method *only* returns an error when a context error occurs; any other error is interpreted as a failure to
+// deliver the notification and as such the message will be marked as failed (to later be optionally retried).
+func (n *notifier) deliver(ctx context.Context, msg database.AcquireNotificationMessagesRow, deliver dispatch.DeliveryFunc, success, failure chan<- dispatchResult) error {
+ select {
+ case <-ctx.Done():
+ return ctx.Err()
+ default:
+ }
+
+ ctx, cancel := context.WithTimeout(ctx, n.cfg.DispatchTimeout.Value())
+ defer cancel()
+ logger := n.log.With(slog.F("msg_id", msg.ID), slog.F("method", msg.Method), slog.F("attempt", msg.AttemptCount+1))
+
+ if msg.AttemptCount > 0 {
+ n.metrics.RetryCount.WithLabelValues(string(n.method), msg.TemplateID.String()).Inc()
+ }
+
+ n.metrics.InflightDispatches.WithLabelValues(string(n.method), msg.TemplateID.String()).Inc()
+ n.metrics.QueuedSeconds.WithLabelValues(string(n.method)).Observe(msg.QueuedSeconds)
+
+ start := time.Now()
+ retryable, err := deliver(ctx, msg.ID)
+
+ n.metrics.DispatcherSendSeconds.WithLabelValues(string(n.method)).Observe(time.Since(start).Seconds())
+ n.metrics.InflightDispatches.WithLabelValues(string(n.method), msg.TemplateID.String()).Dec()
+
+ if err != nil {
+ // Don't try to accumulate message responses if the context has been canceled.
+ //
+ // This message's lease will expire in the store and will be requeued.
+ // It's possible this will lead to a message being delivered more than once, and that is why Stop() is preferable
+ // instead of canceling the context.
+ //
+ // In the case of backpressure (i.e. the success/failure channels are full because the database is slow),
+ // we can't append any more updates to the channels otherwise this, too, will block.
+ if xerrors.Is(err, context.Canceled) {
+ return err
+ }
+
+ select {
+ case <-ctx.Done():
+ logger.Warn(context.Background(), "cannot record dispatch failure result", slog.Error(ctx.Err()))
+ return ctx.Err()
+ case failure <- n.newFailedDispatch(msg, err, retryable):
+ logger.Warn(ctx, "message dispatch failed", slog.Error(err))
+ }
+ } else {
+ select {
+ case <-ctx.Done():
+ logger.Warn(context.Background(), "cannot record dispatch success result", slog.Error(ctx.Err()))
+ return ctx.Err()
+ case success <- n.newSuccessfulDispatch(msg):
+ logger.Debug(ctx, "message dispatch succeeded")
+ }
+ }
+ n.metrics.PendingUpdates.Set(float64(len(success) + len(failure)))
+
+ return nil
+}
+
+func (n *notifier) newSuccessfulDispatch(msg database.AcquireNotificationMessagesRow) dispatchResult {
+ n.metrics.DispatchAttempts.WithLabelValues(string(n.method), msg.TemplateID.String(), ResultSuccess).Inc()
+
+ return dispatchResult{
+ notifier: n.id,
+ msg: msg.ID,
+ ts: time.Now(),
+ }
+}
+
+// revive:disable-next-line:flag-parameter // Not used for control flow, rather just choosing which metric to increment.
+func (n *notifier) newFailedDispatch(msg database.AcquireNotificationMessagesRow, err error, retryable bool) dispatchResult {
+ var result string
+
+ // If retryable and not the last attempt, it's a temporary failure.
+ if retryable && msg.AttemptCount < int32(n.cfg.MaxSendAttempts)-1 {
+ result = ResultTempFail
+ } else {
+ result = ResultPermFail
+ }
+
+ n.metrics.DispatchAttempts.WithLabelValues(string(n.method), msg.TemplateID.String(), result).Inc()
+
+ return dispatchResult{
+ notifier: n.id,
+ msg: msg.ID,
+ ts: time.Now(),
+ err: err,
+ retryable: retryable,
+ }
+}
+
+// stop stops the notifier from processing any new notifications.
+// This is a graceful stop, so any in-flight notifications will be completed before the notifier stops.
+// Once a notifier has stopped, it cannot be restarted.
+func (n *notifier) stop() {
+ n.stopOnce.Do(func() {
+ n.log.Info(context.Background(), "graceful stop requested")
+
+ n.tick.Stop()
+ close(n.quit)
+ <-n.done
+ })
+}
diff --git a/coderd/notifications/render/gotmpl.go b/coderd/notifications/render/gotmpl.go
new file mode 100644
index 0000000000000..e194c9837d2a9
--- /dev/null
+++ b/coderd/notifications/render/gotmpl.go
@@ -0,0 +1,26 @@
+package render
+
+import (
+ "strings"
+ "text/template"
+
+ "golang.org/x/xerrors"
+
+ "github.com/coder/coder/v2/coderd/notifications/types"
+)
+
+// GoTemplate attempts to substitute the given payload into the given template using Go's templating syntax.
+// TODO: memoize templates for memory efficiency?
+func GoTemplate(in string, payload types.MessagePayload, extraFuncs template.FuncMap) (string, error) {
+ tmpl, err := template.New("text").Funcs(extraFuncs).Parse(in)
+ if err != nil {
+ return "", xerrors.Errorf("template parse: %w", err)
+ }
+
+ var out strings.Builder
+ if err = tmpl.Execute(&out, payload); err != nil {
+ return "", xerrors.Errorf("template execute: %w", err)
+ }
+
+ return out.String(), nil
+}
diff --git a/coderd/notifications/render/gotmpl_test.go b/coderd/notifications/render/gotmpl_test.go
new file mode 100644
index 0000000000000..ec2ec7ffe6237
--- /dev/null
+++ b/coderd/notifications/render/gotmpl_test.go
@@ -0,0 +1,79 @@
+package render_test
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/coder/coder/v2/coderd/notifications/render"
+
+ "github.com/coder/coder/v2/coderd/notifications/types"
+)
+
+func TestGoTemplate(t *testing.T) {
+ t.Parallel()
+
+ const userEmail = "bob@xyz.com"
+
+ tests := []struct {
+ name string
+ in string
+ payload types.MessagePayload
+ expectedOutput string
+ expectedErr error
+ }{
+ {
+ name: "top-level variables are accessible and substituted",
+ in: "{{ .UserEmail }}",
+ payload: types.MessagePayload{UserEmail: userEmail},
+ expectedOutput: userEmail,
+ expectedErr: nil,
+ },
+ {
+ name: "input labels are accessible and substituted",
+ in: "{{ .Labels.user_email }}",
+ payload: types.MessagePayload{Labels: map[string]string{
+ "user_email": userEmail,
+ }},
+ expectedOutput: userEmail,
+ expectedErr: nil,
+ },
+ {
+ name: "render workspace URL",
+ in: `[{
+ "label": "View workspace",
+ "url": "{{ base_url }}/@{{.UserUsername}}/{{.Labels.name}}"
+ }]`,
+ payload: types.MessagePayload{
+ UserName: "John Doe",
+ UserUsername: "johndoe",
+ Labels: map[string]string{
+ "name": "my-workspace",
+ },
+ },
+ expectedOutput: `[{
+ "label": "View workspace",
+ "url": "https://mocked-server-address/@johndoe/my-workspace"
+ }]`,
+ },
+ }
+
+ for _, tc := range tests {
+ tc := tc // unnecessary as of go1.22 but the linter is outdated
+
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ out, err := render.GoTemplate(tc.in, tc.payload, map[string]any{
+ "base_url": func() string { return "https://mocked-server-address" },
+ })
+ if tc.expectedErr == nil {
+ require.NoError(t, err)
+ } else {
+ require.ErrorIs(t, err, tc.expectedErr)
+ }
+
+ require.Equal(t, tc.expectedOutput, out)
+ })
+ }
+}
diff --git a/coderd/notifications/spec.go b/coderd/notifications/spec.go
new file mode 100644
index 0000000000000..c41189ba3d582
--- /dev/null
+++ b/coderd/notifications/spec.go
@@ -0,0 +1,36 @@
+package notifications
+
+import (
+ "context"
+
+ "github.com/google/uuid"
+
+ "github.com/coder/coder/v2/coderd/database"
+ "github.com/coder/coder/v2/coderd/notifications/dispatch"
+ "github.com/coder/coder/v2/coderd/notifications/types"
+)
+
+// Store defines the API between the notifications system and the storage.
+// This abstraction is in place so that we can intercept the direct database interactions, or (later) swap out these calls
+// with dRPC calls should we want to split the notifiers out into their own component for high availability/throughput.
+// TODO: don't use database types here
+type Store interface {
+ AcquireNotificationMessages(ctx context.Context, params database.AcquireNotificationMessagesParams) ([]database.AcquireNotificationMessagesRow, error)
+ BulkMarkNotificationMessagesSent(ctx context.Context, arg database.BulkMarkNotificationMessagesSentParams) (int64, error)
+ BulkMarkNotificationMessagesFailed(ctx context.Context, arg database.BulkMarkNotificationMessagesFailedParams) (int64, error)
+ EnqueueNotificationMessage(ctx context.Context, arg database.EnqueueNotificationMessageParams) error
+ FetchNewMessageMetadata(ctx context.Context, arg database.FetchNewMessageMetadataParams) (database.FetchNewMessageMetadataRow, error)
+ GetNotificationMessagesByStatus(ctx context.Context, arg database.GetNotificationMessagesByStatusParams) ([]database.NotificationMessage, error)
+ GetNotificationsSettings(ctx context.Context) (string, error)
+}
+
+// Handler is responsible for preparing and delivering a notification by a given method.
+type Handler interface {
+ // Dispatcher constructs a DeliveryFunc to be used for delivering a notification via the chosen method.
+ Dispatcher(payload types.MessagePayload, title, body string) (dispatch.DeliveryFunc, error)
+}
+
+// Enqueuer enqueues a new notification message in the store and returns its ID, should it enqueue without failure.
+type Enqueuer interface {
+ Enqueue(ctx context.Context, userID, templateID uuid.UUID, labels map[string]string, createdBy string, targets ...uuid.UUID) (*uuid.UUID, error)
+}
diff --git a/coderd/notifications/types/cta.go b/coderd/notifications/types/cta.go
new file mode 100644
index 0000000000000..d47ead0259251
--- /dev/null
+++ b/coderd/notifications/types/cta.go
@@ -0,0 +1,6 @@
+package types
+
+type TemplateAction struct {
+ Label string `json:"label"`
+ URL string `json:"url"`
+}
diff --git a/coderd/notifications/types/payload.go b/coderd/notifications/types/payload.go
new file mode 100644
index 0000000000000..ba666219af654
--- /dev/null
+++ b/coderd/notifications/types/payload.go
@@ -0,0 +1,19 @@
+package types
+
+// MessagePayload describes the JSON payload to be stored alongside the notification message, which specifies all of its
+// metadata, labels, and routing information.
+//
+// Any BC-incompatible changes must bump the version, and special handling must be put in place to unmarshal multiple versions.
+type MessagePayload struct {
+ Version string `json:"_version"`
+
+ NotificationName string `json:"notification_name"`
+
+ UserID string `json:"user_id"`
+ UserEmail string `json:"user_email"`
+ UserName string `json:"user_name"`
+ UserUsername string `json:"user_username"`
+
+ Actions []TemplateAction `json:"actions"`
+ Labels map[string]string `json:"labels"`
+}
diff --git a/coderd/notifications/utils_test.go b/coderd/notifications/utils_test.go
new file mode 100644
index 0000000000000..24cd361ede276
--- /dev/null
+++ b/coderd/notifications/utils_test.go
@@ -0,0 +1,133 @@
+package notifications_test
+
+import (
+ "context"
+ "database/sql"
+ "sync/atomic"
+ "testing"
+ "time"
+
+ "github.com/google/uuid"
+ "github.com/prometheus/client_golang/prometheus"
+ "github.com/stretchr/testify/require"
+
+ "cdr.dev/slog"
+ "cdr.dev/slog/sloggers/slogtest"
+ "github.com/coder/serpent"
+
+ "github.com/coder/coder/v2/coderd/database"
+ "github.com/coder/coder/v2/coderd/database/dbauthz"
+ "github.com/coder/coder/v2/coderd/database/dbgen"
+ "github.com/coder/coder/v2/coderd/database/dbmem"
+ "github.com/coder/coder/v2/coderd/database/dbtestutil"
+ "github.com/coder/coder/v2/coderd/notifications"
+ "github.com/coder/coder/v2/coderd/notifications/dispatch"
+ "github.com/coder/coder/v2/coderd/notifications/types"
+ "github.com/coder/coder/v2/codersdk"
+ "github.com/coder/coder/v2/testutil"
+)
+
+func setup(t *testing.T) (context.Context, slog.Logger, database.Store) {
+ t.Helper()
+
+ connectionURL, closeFunc, err := dbtestutil.Open()
+ require.NoError(t, err)
+ t.Cleanup(closeFunc)
+
+ ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitSuperLong)
+ t.Cleanup(cancel)
+ logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true, IgnoredErrorIs: []error{}}).Leveled(slog.LevelDebug)
+
+ sqlDB, err := sql.Open("postgres", connectionURL)
+ require.NoError(t, err)
+ t.Cleanup(func() {
+ require.NoError(t, sqlDB.Close())
+ })
+
+ // nolint:gocritic // unit tests.
+ return dbauthz.AsSystemRestricted(ctx), logger, database.New(sqlDB)
+}
+
+func setupInMemory(t *testing.T) (context.Context, slog.Logger, database.Store) {
+ t.Helper()
+
+ ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+ t.Cleanup(cancel)
+ logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true, IgnoredErrorIs: []error{}}).Leveled(slog.LevelDebug)
+
+ // nolint:gocritic // unit tests.
+ return dbauthz.AsSystemRestricted(ctx), logger, dbmem.New()
+}
+
+func defaultNotificationsConfig(method database.NotificationMethod) codersdk.NotificationsConfig {
+ return codersdk.NotificationsConfig{
+ Method: serpent.String(method),
+ MaxSendAttempts: 5,
+ FetchInterval: serpent.Duration(time.Millisecond * 100),
+ StoreSyncInterval: serpent.Duration(time.Millisecond * 200),
+ LeasePeriod: serpent.Duration(time.Second * 10),
+ DispatchTimeout: serpent.Duration(time.Second * 5),
+ RetryInterval: serpent.Duration(time.Millisecond * 50),
+ LeaseCount: 10,
+ StoreSyncBufferSize: 50,
+ SMTP: codersdk.NotificationsEmailConfig{},
+ Webhook: codersdk.NotificationsWebhookConfig{},
+ }
+}
+
+func defaultHelpers() map[string]any {
+ return map[string]any{
+ "base_url": func() string { return "http://test.com" },
+ }
+}
+
+func createSampleUser(t *testing.T, db database.Store) database.User {
+ return dbgen.User(t, db, database.User{
+ Email: "bob@coder.com",
+ Username: "bob",
+ })
+}
+
+func createMetrics() *notifications.Metrics {
+ return notifications.NewMetrics(prometheus.NewRegistry())
+}
+
+type dispatchInterceptor struct {
+ handler notifications.Handler
+
+ sent atomic.Int32
+ retryable atomic.Int32
+ unretryable atomic.Int32
+ err atomic.Int32
+ lastErr atomic.Value
+}
+
+func newDispatchInterceptor(h notifications.Handler) *dispatchInterceptor {
+ return &dispatchInterceptor{handler: h}
+}
+
+func (i *dispatchInterceptor) Dispatcher(payload types.MessagePayload, title, body string) (dispatch.DeliveryFunc, error) {
+ return func(ctx context.Context, msgID uuid.UUID) (retryable bool, err error) {
+ deliveryFn, err := i.handler.Dispatcher(payload, title, body)
+ if err != nil {
+ return false, err
+ }
+
+ retryable, err = deliveryFn(ctx, msgID)
+
+ if err != nil {
+ i.err.Add(1)
+ i.lastErr.Store(err)
+ }
+
+ switch {
+ case !retryable && err == nil:
+ i.sent.Add(1)
+ case retryable:
+ i.retryable.Add(1)
+ case !retryable && err != nil:
+ i.unretryable.Add(1)
+ }
+ return retryable, err
+ }, nil
+}
diff --git a/coderd/notifications_test.go b/coderd/notifications_test.go
new file mode 100644
index 0000000000000..7690154a0db80
--- /dev/null
+++ b/coderd/notifications_test.go
@@ -0,0 +1,95 @@
+package coderd_test
+
+import (
+ "net/http"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/coder/coder/v2/coderd/coderdtest"
+ "github.com/coder/coder/v2/codersdk"
+ "github.com/coder/coder/v2/testutil"
+)
+
+func TestUpdateNotificationsSettings(t *testing.T) {
+ t.Parallel()
+
+ t.Run("Permissions denied", func(t *testing.T) {
+ t.Parallel()
+
+ api := coderdtest.New(t, nil)
+ firstUser := coderdtest.CreateFirstUser(t, api)
+ anotherClient, _ := coderdtest.CreateAnotherUser(t, api, firstUser.OrganizationID)
+
+ // given
+ expected := codersdk.NotificationsSettings{
+ NotifierPaused: true,
+ }
+
+ ctx := testutil.Context(t, testutil.WaitShort)
+
+ // when
+ err := anotherClient.PutNotificationsSettings(ctx, expected)
+
+ // then
+ var sdkError *codersdk.Error
+ require.Error(t, err)
+ require.ErrorAsf(t, err, &sdkError, "error should be of type *codersdk.Error")
+ require.Equal(t, http.StatusForbidden, sdkError.StatusCode())
+ })
+
+ t.Run("Settings modified", func(t *testing.T) {
+ t.Parallel()
+
+ client := coderdtest.New(t, nil)
+ _ = coderdtest.CreateFirstUser(t, client)
+
+ // given
+ expected := codersdk.NotificationsSettings{
+ NotifierPaused: true,
+ }
+
+ ctx := testutil.Context(t, testutil.WaitShort)
+
+ // when
+ err := client.PutNotificationsSettings(ctx, expected)
+ require.NoError(t, err)
+
+ // then
+ actual, err := client.GetNotificationsSettings(ctx)
+ require.NoError(t, err)
+ require.Equal(t, expected, actual)
+ })
+
+ t.Run("Settings not modified", func(t *testing.T) {
+ t.Parallel()
+
+ // Empty state: notifications Settings are undefined now (default).
+ client := coderdtest.New(t, nil)
+ _ = coderdtest.CreateFirstUser(t, client)
+ ctx := testutil.Context(t, testutil.WaitShort)
+
+ // Change the state: pause notifications
+ err := client.PutNotificationsSettings(ctx, codersdk.NotificationsSettings{
+ NotifierPaused: true,
+ })
+ require.NoError(t, err)
+
+ // Verify the state: notifications are paused.
+ actual, err := client.GetNotificationsSettings(ctx)
+ require.NoError(t, err)
+ require.True(t, actual.NotifierPaused)
+
+ // Change the stage again: notifications are paused.
+ expected := actual
+ err = client.PutNotificationsSettings(ctx, codersdk.NotificationsSettings{
+ NotifierPaused: true,
+ })
+ require.NoError(t, err)
+
+ // Verify the state: notifications are still paused, and there is no error returned.
+ actual, err = client.GetNotificationsSettings(ctx)
+ require.NoError(t, err)
+ require.Equal(t, expected.NotifierPaused, actual.NotifierPaused)
+ })
+}
diff --git a/coderd/oauth2.go b/coderd/oauth2.go
index ef68e93a1fc47..da102faf9138c 100644
--- a/coderd/oauth2.go
+++ b/coderd/oauth2.go
@@ -207,7 +207,7 @@ func (api *API) deleteOAuth2ProviderApp(rw http.ResponseWriter, r *http.Request)
})
return
}
- httpapi.Write(ctx, rw, http.StatusNoContent, nil)
+ rw.WriteHeader(http.StatusNoContent)
}
// @Summary Get OAuth2 application secrets.
@@ -324,7 +324,7 @@ func (api *API) deleteOAuth2ProviderAppSecret(rw http.ResponseWriter, r *http.Re
})
return
}
- httpapi.Write(ctx, rw, http.StatusNoContent, nil)
+ rw.WriteHeader(http.StatusNoContent)
}
// @Summary OAuth2 authorization request.
diff --git a/coderd/organizations.go b/coderd/organizations.go
index 2a43ed2a7011a..2acd3fe401a89 100644
--- a/coderd/organizations.go
+++ b/coderd/organizations.go
@@ -1,221 +1,50 @@
package coderd
import (
- "database/sql"
- "errors"
- "fmt"
"net/http"
- "github.com/google/uuid"
- "golang.org/x/xerrors"
-
- "github.com/coder/coder/v2/coderd/database"
- "github.com/coder/coder/v2/coderd/database/dbtime"
+ "github.com/coder/coder/v2/coderd/database/db2sdk"
"github.com/coder/coder/v2/coderd/httpapi"
"github.com/coder/coder/v2/coderd/httpmw"
- "github.com/coder/coder/v2/coderd/rbac"
"github.com/coder/coder/v2/codersdk"
)
-// @Summary Get organization by ID
-// @ID get-organization-by-id
+// @Summary Get organizations
+// @ID get-organizations
// @Security CoderSessionToken
// @Produce json
// @Tags Organizations
-// @Param organization path string true "Organization ID" format(uuid)
-// @Success 200 {object} codersdk.Organization
-// @Router /organizations/{organization} [get]
-func (*API) organization(rw http.ResponseWriter, r *http.Request) {
+// @Success 200 {object} []codersdk.Organization
+// @Router /organizations [get]
+func (api *API) organizations(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
- organization := httpmw.OrganizationParam(r)
-
- httpapi.Write(ctx, rw, http.StatusOK, convertOrganization(organization))
-}
-
-// @Summary Create organization
-// @ID create-organization
-// @Security CoderSessionToken
-// @Accept json
-// @Produce json
-// @Tags Organizations
-// @Param request body codersdk.CreateOrganizationRequest true "Create organization request"
-// @Success 201 {object} codersdk.Organization
-// @Router /organizations [post]
-func (api *API) postOrganizations(rw http.ResponseWriter, r *http.Request) {
- ctx := r.Context()
- apiKey := httpmw.APIKey(r)
-
- var req codersdk.CreateOrganizationRequest
- if !httpapi.Read(ctx, rw, r, &req) {
- return
- }
-
- if req.Name == codersdk.DefaultOrganization {
- httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
- Message: fmt.Sprintf("Organization name %q is reserved.", codersdk.DefaultOrganization),
- })
- return
- }
-
- _, err := api.Database.GetOrganizationByName(ctx, req.Name)
- if err == nil {
- httpapi.Write(ctx, rw, http.StatusConflict, codersdk.Response{
- Message: "Organization already exists with that name.",
- })
- return
- }
- if !errors.Is(err, sql.ErrNoRows) {
- httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
- Message: fmt.Sprintf("Internal error fetching organization %q.", req.Name),
- Detail: err.Error(),
- })
- return
- }
-
- var organization database.Organization
- err = api.Database.InTx(func(tx database.Store) error {
- organization, err = tx.InsertOrganization(ctx, database.InsertOrganizationParams{
- ID: uuid.New(),
- Name: req.Name,
- CreatedAt: dbtime.Now(),
- UpdatedAt: dbtime.Now(),
- Description: "",
- })
- if err != nil {
- return xerrors.Errorf("create organization: %w", err)
- }
- _, err = tx.InsertOrganizationMember(ctx, database.InsertOrganizationMemberParams{
- OrganizationID: organization.ID,
- UserID: apiKey.UserID,
- CreatedAt: dbtime.Now(),
- UpdatedAt: dbtime.Now(),
- Roles: []string{
- // TODO: When organizations are allowed to be created, we should
- // come back to determining the default role of the person who
- // creates the org. Until that happens, all users in an organization
- // should be just regular members.
- rbac.RoleOrgMember(organization.ID),
- },
- })
- if err != nil {
- return xerrors.Errorf("create organization admin: %w", err)
- }
-
- _, err = tx.InsertAllUsersGroup(ctx, organization.ID)
- if err != nil {
- return xerrors.Errorf("create %q group: %w", database.EveryoneGroup, err)
- }
- return nil
- }, nil)
- if err != nil {
- httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
- Message: "Internal error inserting organization member.",
- Detail: err.Error(),
- })
- return
- }
-
- httpapi.Write(ctx, rw, http.StatusCreated, convertOrganization(organization))
-}
-
-// @Summary Update organization
-// @ID update-organization
-// @Security CoderSessionToken
-// @Accept json
-// @Produce json
-// @Tags Organizations
-// @Param organization path string true "Organization ID or name"
-// @Param request body codersdk.UpdateOrganizationRequest true "Patch organization request"
-// @Success 200 {object} codersdk.Organization
-// @Router /organizations/{organization} [patch]
-func (api *API) patchOrganization(rw http.ResponseWriter, r *http.Request) {
- ctx := r.Context()
- organization := httpmw.OrganizationParam(r)
-
- var req codersdk.UpdateOrganizationRequest
- if !httpapi.Read(ctx, rw, r, &req) {
- return
- }
-
- // "default" is a reserved name that always refers to the default org (much like the way we
- // use "me" for users).
- if req.Name == codersdk.DefaultOrganization {
- httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
- Message: fmt.Sprintf("Organization name %q is reserved.", codersdk.DefaultOrganization),
- })
- return
- }
-
- organization, err := api.Database.UpdateOrganization(ctx, database.UpdateOrganizationParams{
- ID: organization.ID,
- UpdatedAt: dbtime.Now(),
- Name: req.Name,
- })
+ organizations, err := api.Database.GetOrganizations(ctx)
if httpapi.Is404Error(err) {
httpapi.ResourceNotFound(rw)
return
}
- if database.IsUniqueViolation(err) {
- httpapi.Write(ctx, rw, http.StatusConflict, codersdk.Response{
- Message: fmt.Sprintf("Organization already exists with the name %q.", req.Name),
- Validations: []codersdk.ValidationError{{
- Field: "name",
- Detail: "This value is already in use and should be unique.",
- }},
- })
- return
- }
if err != nil {
httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
- Message: "Internal error updating organization.",
- Detail: fmt.Sprintf("update organization: %s", err.Error()),
+ Message: "Internal error fetching organizations.",
+ Detail: err.Error(),
})
return
}
- httpapi.Write(ctx, rw, http.StatusOK, convertOrganization(organization))
+ httpapi.Write(ctx, rw, http.StatusOK, db2sdk.List(organizations, db2sdk.Organization))
}
-// @Summary Delete organization
-// @ID delete-organization
+// @Summary Get organization by ID
+// @ID get-organization-by-id
// @Security CoderSessionToken
// @Produce json
// @Tags Organizations
-// @Param organization path string true "Organization ID or name"
-// @Success 200 {object} codersdk.Response
-// @Router /organizations/{organization} [delete]
-func (api *API) deleteOrganization(rw http.ResponseWriter, r *http.Request) {
+// @Param organization path string true "Organization ID" format(uuid)
+// @Success 200 {object} codersdk.Organization
+// @Router /organizations/{organization} [get]
+func (*API) organization(rw http.ResponseWriter, r *http.Request) {
ctx := r.Context()
organization := httpmw.OrganizationParam(r)
- if organization.IsDefault {
- httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
- Message: "Default organization cannot be deleted.",
- })
- return
- }
-
- err := api.Database.DeleteOrganization(ctx, organization.ID)
- if err != nil {
- httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
- Message: "Internal error deleting organization.",
- Detail: fmt.Sprintf("delete organization: %s", err.Error()),
- })
- return
- }
-
- httpapi.Write(ctx, rw, http.StatusOK, codersdk.Response{
- Message: "Organization has been deleted.",
- })
-}
-
-// convertOrganization consumes the database representation and outputs an API friendly representation.
-func convertOrganization(organization database.Organization) codersdk.Organization {
- return codersdk.Organization{
- ID: organization.ID,
- Name: organization.Name,
- CreatedAt: organization.CreatedAt,
- UpdatedAt: organization.UpdatedAt,
- IsDefault: organization.IsDefault,
- }
+ httpapi.Write(ctx, rw, http.StatusOK, db2sdk.Organization(organization))
}
diff --git a/coderd/organizations_test.go b/coderd/organizations_test.go
index 8ce39c5593d90..c6a26c1f86582 100644
--- a/coderd/organizations_test.go
+++ b/coderd/organizations_test.go
@@ -11,46 +11,6 @@ import (
"github.com/coder/coder/v2/testutil"
)
-func TestMultiOrgFetch(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- _ = coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitLong)
-
- makeOrgs := []string{"foo", "bar", "baz"}
- for _, name := range makeOrgs {
- _, err := client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: name,
- })
- require.NoError(t, err)
- }
-
- orgs, err := client.OrganizationsByUser(ctx, codersdk.Me)
- require.NoError(t, err)
- require.NotNil(t, orgs)
- require.Len(t, orgs, len(makeOrgs)+1)
-}
-
-func TestOrganizationsByUser(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- _ = coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitLong)
-
- orgs, err := client.OrganizationsByUser(ctx, codersdk.Me)
- require.NoError(t, err)
- require.NotNil(t, orgs)
- require.Len(t, orgs, 1)
- require.True(t, orgs[0].IsDefault, "first org is always default")
-
- // Make an extra org, and it should not be defaulted.
- notDefault, err := client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: "another",
- })
- require.NoError(t, err)
- require.False(t, notDefault.IsDefault, "only 1 default org allowed")
-}
-
func TestOrganizationByUserAndName(t *testing.T) {
t.Parallel()
t.Run("NoExist", func(t *testing.T) {
@@ -65,23 +25,6 @@ func TestOrganizationByUserAndName(t *testing.T) {
require.Equal(t, http.StatusNotFound, apiErr.StatusCode())
})
- t.Run("NoMember", func(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- first := coderdtest.CreateFirstUser(t, client)
- other, _ := coderdtest.CreateAnotherUser(t, client, first.OrganizationID)
- ctx := testutil.Context(t, testutil.WaitLong)
-
- org, err := client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: "another",
- })
- require.NoError(t, err)
- _, err = other.OrganizationByUserAndName(ctx, codersdk.Me, org.Name)
- var apiErr *codersdk.Error
- require.ErrorAs(t, err, &apiErr)
- require.Equal(t, http.StatusNotFound, apiErr.StatusCode())
- })
-
t.Run("Valid", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
@@ -94,161 +37,3 @@ func TestOrganizationByUserAndName(t *testing.T) {
require.NoError(t, err)
})
}
-
-func TestPostOrganizationsByUser(t *testing.T) {
- t.Parallel()
- t.Run("Conflict", func(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- user := coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitLong)
-
- org, err := client.Organization(ctx, user.OrganizationID)
- require.NoError(t, err)
- _, err = client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: org.Name,
- })
- var apiErr *codersdk.Error
- require.ErrorAs(t, err, &apiErr)
- require.Equal(t, http.StatusConflict, apiErr.StatusCode())
- })
-
- t.Run("Create", func(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- _ = coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitLong)
-
- _, err := client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: "new",
- })
- require.NoError(t, err)
- })
-}
-
-func TestPatchOrganizationsByUser(t *testing.T) {
- t.Parallel()
- t.Run("Conflict", func(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- user := coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitMedium)
-
- originalOrg, err := client.Organization(ctx, user.OrganizationID)
- require.NoError(t, err)
- o, err := client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: "something-unique",
- })
- require.NoError(t, err)
-
- _, err = client.UpdateOrganization(ctx, o.ID.String(), codersdk.UpdateOrganizationRequest{
- Name: originalOrg.Name,
- })
- var apiErr *codersdk.Error
- require.ErrorAs(t, err, &apiErr)
- require.Equal(t, http.StatusConflict, apiErr.StatusCode())
- })
-
- t.Run("ReservedName", func(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- _ = coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitMedium)
-
- o, err := client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: "something-unique",
- })
- require.NoError(t, err)
-
- _, err = client.UpdateOrganization(ctx, o.ID.String(), codersdk.UpdateOrganizationRequest{
- Name: codersdk.DefaultOrganization,
- })
- var apiErr *codersdk.Error
- require.ErrorAs(t, err, &apiErr)
- require.Equal(t, http.StatusBadRequest, apiErr.StatusCode())
- })
-
- t.Run("UpdateById", func(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- _ = coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitMedium)
-
- o, err := client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: "new",
- })
- require.NoError(t, err)
-
- o, err = client.UpdateOrganization(ctx, o.ID.String(), codersdk.UpdateOrganizationRequest{
- Name: "new-new",
- })
- require.NoError(t, err)
- require.Equal(t, "new-new", o.Name)
- })
-
- t.Run("UpdateByName", func(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- _ = coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitMedium)
-
- o, err := client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: "new",
- })
- require.NoError(t, err)
-
- o, err = client.UpdateOrganization(ctx, o.Name, codersdk.UpdateOrganizationRequest{
- Name: "new-new",
- })
- require.NoError(t, err)
- require.Equal(t, "new-new", o.Name)
- })
-}
-
-func TestDeleteOrganizationsByUser(t *testing.T) {
- t.Parallel()
- t.Run("Default", func(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- user := coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitMedium)
-
- o, err := client.Organization(ctx, user.OrganizationID)
- require.NoError(t, err)
-
- err = client.DeleteOrganization(ctx, o.ID.String())
- var apiErr *codersdk.Error
- require.ErrorAs(t, err, &apiErr)
- require.Equal(t, http.StatusBadRequest, apiErr.StatusCode())
- })
-
- t.Run("DeleteById", func(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- _ = coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitMedium)
-
- o, err := client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: "doomed",
- })
- require.NoError(t, err)
-
- err = client.DeleteOrganization(ctx, o.ID.String())
- require.NoError(t, err)
- })
-
- t.Run("DeleteByName", func(t *testing.T) {
- t.Parallel()
- client := coderdtest.New(t, nil)
- _ = coderdtest.CreateFirstUser(t, client)
- ctx := testutil.Context(t, testutil.WaitMedium)
-
- o, err := client.CreateOrganization(ctx, codersdk.CreateOrganizationRequest{
- Name: "doomed",
- })
- require.NoError(t, err)
-
- err = client.DeleteOrganization(ctx, o.Name)
- require.NoError(t, err)
- })
-}
diff --git a/coderd/pagination.go b/coderd/pagination.go
index 02199a390ec60..0d01220d195e7 100644
--- a/coderd/pagination.go
+++ b/coderd/pagination.go
@@ -17,8 +17,10 @@ func parsePagination(w http.ResponseWriter, r *http.Request) (p codersdk.Paginat
parser := httpapi.NewQueryParamParser()
params := codersdk.Pagination{
AfterID: parser.UUID(queryParams, uuid.Nil, "after_id"),
- Limit: int(parser.PositiveInt32(queryParams, 0, "limit")),
- Offset: int(parser.PositiveInt32(queryParams, 0, "offset")),
+ // A limit of 0 should be interpreted by the SQL query as "null" or
+ // "no limit". Do not make this value anything besides 0.
+ Limit: int(parser.PositiveInt32(queryParams, 0, "limit")),
+ Offset: int(parser.PositiveInt32(queryParams, 0, "offset")),
}
if len(parser.Errors) > 0 {
httpapi.Write(ctx, w, http.StatusBadRequest, codersdk.Response{
diff --git a/coderd/prometheusmetrics/insights/metricscollector_test.go b/coderd/prometheusmetrics/insights/metricscollector_test.go
index 91ef3c7ee88fa..9179c9896235d 100644
--- a/coderd/prometheusmetrics/insights/metricscollector_test.go
+++ b/coderd/prometheusmetrics/insights/metricscollector_test.go
@@ -18,6 +18,7 @@ import (
"cdr.dev/slog"
"cdr.dev/slog/sloggers/slogtest"
+ agentproto "github.com/coder/coder/v2/agent/proto"
"github.com/coder/coder/v2/coderd/coderdtest"
"github.com/coder/coder/v2/coderd/database"
"github.com/coder/coder/v2/coderd/database/dbauthz"
@@ -87,25 +88,37 @@ func TestCollectInsights(t *testing.T) {
)
// Start an agent so that we can generate stats.
- var agentClients []*agentsdk.Client
+ var agentClients []agentproto.DRPCAgentClient
for i, agent := range []database.WorkspaceAgent{agent1, agent2} {
agentClient := agentsdk.New(client.URL)
agentClient.SetSessionToken(agent.AuthToken.String())
agentClient.SDK.SetLogger(logger.Leveled(slog.LevelDebug).Named(fmt.Sprintf("agent%d", i+1)))
- agentClients = append(agentClients, agentClient)
+ conn, err := agentClient.ConnectRPC(context.Background())
+ require.NoError(t, err)
+ agentAPI := agentproto.NewDRPCAgentClient(conn)
+ agentClients = append(agentClients, agentAPI)
}
+ defer func() {
+ for a := range agentClients {
+ err := agentClients[a].DRPCConn().Close()
+ require.NoError(t, err)
+ }
+ }()
+
// Fake app stats
- _, err = agentClients[0].PostStats(context.Background(), &agentsdk.Stats{
- // ConnectionCount must be positive as database query ignores stats with no active connections at the time frame
- ConnectionsByProto: map[string]int64{"TCP": 1},
- ConnectionCount: 1,
- ConnectionMedianLatencyMS: 15,
- // Session counts must be positive, but the exact value is ignored.
- // Database query approximates it to 60s of usage.
- SessionCountSSH: 99,
- SessionCountJetBrains: 47,
- SessionCountVSCode: 34,
+ _, err = agentClients[0].UpdateStats(context.Background(), &agentproto.UpdateStatsRequest{
+ Stats: &agentproto.Stats{
+ // ConnectionCount must be positive as database query ignores stats with no active connections at the time frame
+ ConnectionsByProto: map[string]int64{"TCP": 1},
+ ConnectionCount: 1,
+ ConnectionMedianLatencyMs: 15,
+ // Session counts must be positive, but the exact value is ignored.
+ // Database query approximates it to 60s of usage.
+ SessionCountSsh: 99,
+ SessionCountJetbrains: 47,
+ SessionCountVscode: 34,
+ },
})
require.NoError(t, err, "unable to post fake stats")
diff --git a/coderd/prometheusmetrics/prometheusmetrics.go b/coderd/prometheusmetrics/prometheusmetrics.go
index fcc6958f39e84..b9a54633a5b13 100644
--- a/coderd/prometheusmetrics/prometheusmetrics.go
+++ b/coderd/prometheusmetrics/prometheusmetrics.go
@@ -120,9 +120,9 @@ func Workspaces(ctx context.Context, logger slog.Logger, registerer prometheus.R
if errors.Is(err, sql.ErrNoRows) {
// clear all series if there are no database entries
workspaceLatestBuildTotals.Reset()
+ } else {
+ logger.Warn(ctx, "failed to load latest workspace builds", slog.Error(err))
}
-
- logger.Warn(ctx, "failed to load latest workspace builds", slog.Error(err))
return
}
jobIDs := make([]uuid.UUID, 0, len(builds))
diff --git a/coderd/prometheusmetrics/prometheusmetrics_test.go b/coderd/prometheusmetrics/prometheusmetrics_test.go
index 9c4c9fca0b66f..f5ed96f64dc41 100644
--- a/coderd/prometheusmetrics/prometheusmetrics_test.go
+++ b/coderd/prometheusmetrics/prometheusmetrics_test.go
@@ -20,8 +20,8 @@ import (
"cdr.dev/slog"
"cdr.dev/slog/sloggers/slogtest"
+ agentproto "github.com/coder/coder/v2/agent/proto"
"github.com/coder/coder/v2/coderd/agentmetrics"
- "github.com/coder/coder/v2/coderd/batchstats"
"github.com/coder/coder/v2/coderd/coderdtest"
"github.com/coder/coder/v2/coderd/database"
"github.com/coder/coder/v2/coderd/database/dbgen"
@@ -29,6 +29,7 @@ import (
"github.com/coder/coder/v2/coderd/database/dbtestutil"
"github.com/coder/coder/v2/coderd/database/dbtime"
"github.com/coder/coder/v2/coderd/prometheusmetrics"
+ "github.com/coder/coder/v2/coderd/workspacestats"
"github.com/coder/coder/v2/codersdk"
"github.com/coder/coder/v2/codersdk/agentsdk"
"github.com/coder/coder/v2/cryptorand"
@@ -309,7 +310,7 @@ func TestAgents(t *testing.T) {
})
template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
- workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
+ workspace := coderdtest.CreateWorkspace(t, client, template.ID)
coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, workspace.LatestBuild.ID)
// given
@@ -391,14 +392,14 @@ func TestAgentStats(t *testing.T) {
db, pubsub := dbtestutil.NewDB(t)
log := slogtest.Make(t, nil).Leveled(slog.LevelDebug)
- batcher, closeBatcher, err := batchstats.New(ctx,
+ batcher, closeBatcher, err := workspacestats.NewBatcher(ctx,
// We had previously set the batch size to 1 here, but that caused
// intermittent test flakes due to a race between the batcher completing
// its flush and the test asserting that the metrics were collected.
// Instead, we close the batcher after all stats have been posted, which
// forces a flush.
- batchstats.WithStore(db),
- batchstats.WithLogger(log),
+ workspacestats.BatcherWithStore(db),
+ workspacestats.BatcherWithLogger(log),
)
require.NoError(t, err, "create stats batcher failed")
t.Cleanup(closeBatcher)
@@ -415,36 +416,45 @@ func TestAgentStats(t *testing.T) {
user := coderdtest.CreateFirstUser(t, client)
- agent1 := prepareWorkspaceAndAgent(t, client, user, 1)
- agent2 := prepareWorkspaceAndAgent(t, client, user, 2)
- agent3 := prepareWorkspaceAndAgent(t, client, user, 3)
+ agent1 := prepareWorkspaceAndAgent(ctx, t, client, user, 1)
+ agent2 := prepareWorkspaceAndAgent(ctx, t, client, user, 2)
+ agent3 := prepareWorkspaceAndAgent(ctx, t, client, user, 3)
+ defer agent1.DRPCConn().Close()
+ defer agent2.DRPCConn().Close()
+ defer agent3.DRPCConn().Close()
registry := prometheus.NewRegistry()
// given
var i int64
for i = 0; i < 3; i++ {
- _, err = agent1.PostStats(ctx, &agentsdk.Stats{
- TxBytes: 1 + i, RxBytes: 2 + i,
- SessionCountVSCode: 3 + i, SessionCountJetBrains: 4 + i, SessionCountReconnectingPTY: 5 + i, SessionCountSSH: 6 + i,
- ConnectionCount: 7 + i, ConnectionMedianLatencyMS: 8000,
- ConnectionsByProto: map[string]int64{"TCP": 1},
+ _, err = agent1.UpdateStats(ctx, &agentproto.UpdateStatsRequest{
+ Stats: &agentproto.Stats{
+ TxBytes: 1 + i, RxBytes: 2 + i,
+ SessionCountVscode: 3 + i, SessionCountJetbrains: 4 + i, SessionCountReconnectingPty: 5 + i, SessionCountSsh: 6 + i,
+ ConnectionCount: 7 + i, ConnectionMedianLatencyMs: 8000,
+ ConnectionsByProto: map[string]int64{"TCP": 1},
+ },
})
require.NoError(t, err)
- _, err = agent2.PostStats(ctx, &agentsdk.Stats{
- TxBytes: 2 + i, RxBytes: 4 + i,
- SessionCountVSCode: 6 + i, SessionCountJetBrains: 8 + i, SessionCountReconnectingPTY: 10 + i, SessionCountSSH: 12 + i,
- ConnectionCount: 8 + i, ConnectionMedianLatencyMS: 10000,
- ConnectionsByProto: map[string]int64{"TCP": 1},
+ _, err = agent2.UpdateStats(ctx, &agentproto.UpdateStatsRequest{
+ Stats: &agentproto.Stats{
+ TxBytes: 2 + i, RxBytes: 4 + i,
+ SessionCountVscode: 6 + i, SessionCountJetbrains: 8 + i, SessionCountReconnectingPty: 10 + i, SessionCountSsh: 12 + i,
+ ConnectionCount: 8 + i, ConnectionMedianLatencyMs: 10000,
+ ConnectionsByProto: map[string]int64{"TCP": 1},
+ },
})
require.NoError(t, err)
- _, err = agent3.PostStats(ctx, &agentsdk.Stats{
- TxBytes: 3 + i, RxBytes: 6 + i,
- SessionCountVSCode: 12 + i, SessionCountJetBrains: 14 + i, SessionCountReconnectingPTY: 16 + i, SessionCountSSH: 18 + i,
- ConnectionCount: 9 + i, ConnectionMedianLatencyMS: 12000,
- ConnectionsByProto: map[string]int64{"TCP": 1},
+ _, err = agent3.UpdateStats(ctx, &agentproto.UpdateStatsRequest{
+ Stats: &agentproto.Stats{
+ TxBytes: 3 + i, RxBytes: 6 + i,
+ SessionCountVscode: 12 + i, SessionCountJetbrains: 14 + i, SessionCountReconnectingPty: 16 + i, SessionCountSsh: 18 + i,
+ ConnectionCount: 9 + i, ConnectionMedianLatencyMs: 12000,
+ ConnectionsByProto: map[string]int64{"TCP": 1},
+ },
})
require.NoError(t, err)
}
@@ -596,7 +606,7 @@ func TestExperimentsMetric(t *testing.T) {
}
}
-func prepareWorkspaceAndAgent(t *testing.T, client *codersdk.Client, user codersdk.CreateFirstUserResponse, workspaceNum int) *agentsdk.Client {
+func prepareWorkspaceAndAgent(ctx context.Context, t *testing.T, client *codersdk.Client, user codersdk.CreateFirstUserResponse, workspaceNum int) agentproto.DRPCAgentClient {
authToken := uuid.NewString()
version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
@@ -606,14 +616,17 @@ func prepareWorkspaceAndAgent(t *testing.T, client *codersdk.Client, user coders
})
template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
- workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID, func(cwr *codersdk.CreateWorkspaceRequest) {
+ workspace := coderdtest.CreateWorkspace(t, client, template.ID, func(cwr *codersdk.CreateWorkspaceRequest) {
cwr.Name = fmt.Sprintf("workspace-%d", workspaceNum)
})
coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, workspace.LatestBuild.ID)
- agentClient := agentsdk.New(client.URL)
- agentClient.SetSessionToken(authToken)
- return agentClient
+ ac := agentsdk.New(client.URL)
+ ac.SetSessionToken(authToken)
+ conn, err := ac.ConnectRPC(ctx)
+ require.NoError(t, err)
+ agentAPI := agentproto.NewDRPCAgentClient(conn)
+ return agentAPI
}
var (
diff --git a/coderd/provisionerdserver/acquirer.go b/coderd/provisionerdserver/acquirer.go
index 3bf99992c9d3d..36e0d51df44f8 100644
--- a/coderd/provisionerdserver/acquirer.go
+++ b/coderd/provisionerdserver/acquirer.go
@@ -163,13 +163,14 @@ func (a *Acquirer) want(organization uuid.UUID, pt []database.ProvisionerType, t
if !ok {
ctx, cancel := context.WithCancel(a.ctx)
d = domain{
- ctx: ctx,
- cancel: cancel,
- a: a,
- key: dk,
- pt: pt,
- tags: tags,
- acquirees: make(map[chan<- struct{}]*acquiree),
+ ctx: ctx,
+ cancel: cancel,
+ a: a,
+ key: dk,
+ pt: pt,
+ tags: tags,
+ organizationID: organization,
+ acquirees: make(map[chan<- struct{}]*acquiree),
}
a.q[dk] = d
go d.poll(a.backupPollDuration)
@@ -450,16 +451,22 @@ type acquiree struct {
// tags. Acquirees in the same domain are restricted such that only one queries
// the database at a time.
type domain struct {
- ctx context.Context
- cancel context.CancelFunc
- a *Acquirer
- key dKey
- pt []database.ProvisionerType
- tags Tags
- acquirees map[chan<- struct{}]*acquiree
+ ctx context.Context
+ cancel context.CancelFunc
+ a *Acquirer
+ key dKey
+ pt []database.ProvisionerType
+ tags Tags
+ organizationID uuid.UUID
+ acquirees map[chan<- struct{}]*acquiree
}
func (d domain) contains(p provisionerjobs.JobPosting) bool {
+ // If the organization ID is 'uuid.Nil', this is a legacy job posting.
+ // Ignore this check in the legacy case.
+ if p.OrganizationID != uuid.Nil && p.OrganizationID != d.organizationID {
+ return false
+ }
if !slices.Contains(d.pt, p.ProvisionerType) {
return false
}
diff --git a/coderd/provisionerdserver/provisionerdserver.go b/coderd/provisionerdserver/provisionerdserver.go
index 3f5876d644617..458f79ca348e6 100644
--- a/coderd/provisionerdserver/provisionerdserver.go
+++ b/coderd/provisionerdserver/provisionerdserver.go
@@ -25,6 +25,7 @@ import (
protobuf "google.golang.org/protobuf/proto"
"cdr.dev/slog"
+
"github.com/coder/coder/v2/coderd/apikey"
"github.com/coder/coder/v2/coderd/audit"
"github.com/coder/coder/v2/coderd/database"
@@ -32,6 +33,7 @@ import (
"github.com/coder/coder/v2/coderd/database/dbtime"
"github.com/coder/coder/v2/coderd/database/pubsub"
"github.com/coder/coder/v2/coderd/externalauth"
+ "github.com/coder/coder/v2/coderd/notifications"
"github.com/coder/coder/v2/coderd/promoauth"
"github.com/coder/coder/v2/coderd/schedule"
"github.com/coder/coder/v2/coderd/telemetry"
@@ -96,6 +98,7 @@ type server struct {
TemplateScheduleStore *atomic.Pointer[schedule.TemplateScheduleStore]
UserQuietHoursScheduleStore *atomic.Pointer[schedule.UserQuietHoursScheduleStore]
DeploymentValues *codersdk.DeploymentValues
+ NotificationsEnqueuer notifications.Enqueuer
OIDCConfig promoauth.OAuth2Config
@@ -150,6 +153,7 @@ func NewServer(
userQuietHoursScheduleStore *atomic.Pointer[schedule.UserQuietHoursScheduleStore],
deploymentValues *codersdk.DeploymentValues,
options Options,
+ enqueuer notifications.Enqueuer,
) (proto.DRPCProvisionerDaemonServer, error) {
// Fail-fast if pointers are nil
if lifecycleCtx == nil {
@@ -198,6 +202,7 @@ func NewServer(
Database: db,
Pubsub: ps,
Acquirer: acquirer,
+ NotificationsEnqueuer: enqueuer,
Telemetry: tel,
Tracer: tracer,
QuotaCommitter: quotaCommitter,
@@ -559,16 +564,17 @@ func (s *server) acquireProtoJob(ctx context.Context, job database.ProvisionerJo
continue
}
- link, valid, err := config.RefreshToken(ctx, s.Database, link)
- if err != nil {
+ refreshed, err := config.RefreshToken(ctx, s.Database, link)
+ if err != nil && !externalauth.IsInvalidTokenError(err) {
return nil, failJob(fmt.Sprintf("refresh external auth link %q: %s", p.ID, err))
}
- if !valid {
+ if err != nil {
+ // Invalid tokens are skipped
continue
}
externalAuthProviders = append(externalAuthProviders, &sdkproto.ExternalAuthProvider{
Id: p.ID,
- AccessToken: link.OAuthAccessToken,
+ AccessToken: refreshed.OAuthAccessToken,
})
}
@@ -597,6 +603,7 @@ func (s *server) acquireProtoJob(ctx context.Context, job database.ProvisionerJo
WorkspaceOwnerSessionToken: sessionToken,
WorkspaceOwnerSshPublicKey: ownerSSHPublicKey,
WorkspaceOwnerSshPrivateKey: ownerSSHPrivateKey,
+ WorkspaceBuildId: workspaceBuild.ID.String(),
},
LogLevel: input.LogLevel,
},
@@ -975,12 +982,18 @@ func (s *server) FailJob(ctx context.Context, failJob *proto.FailedJob) (*proto.
}
var build database.WorkspaceBuild
+ var workspace database.Workspace
err = s.Database.InTx(func(db database.Store) error {
build, err = db.GetWorkspaceBuildByID(ctx, input.WorkspaceBuildID)
if err != nil {
return xerrors.Errorf("get workspace build: %w", err)
}
+ workspace, err = db.GetWorkspaceByID(ctx, build.WorkspaceID)
+ if err != nil {
+ return xerrors.Errorf("get workspace: %w", err)
+ }
+
if jobType.WorkspaceBuild.State != nil {
err = db.UpdateWorkspaceBuildProvisionerStateByID(ctx, database.UpdateWorkspaceBuildProvisionerStateByIDParams{
ID: input.WorkspaceBuildID,
@@ -1007,6 +1020,8 @@ func (s *server) FailJob(ctx context.Context, failJob *proto.FailedJob) (*proto.
return nil, err
}
+ s.notifyWorkspaceBuildFailed(ctx, workspace, build)
+
err = s.Pubsub.Publish(codersdk.WorkspaceNotifyChannel(build.WorkspaceID), []byte{})
if err != nil {
return nil, xerrors.Errorf("update workspace: %w", err)
@@ -1080,6 +1095,25 @@ func (s *server) FailJob(ctx context.Context, failJob *proto.FailedJob) (*proto.
return &proto.Empty{}, nil
}
+func (s *server) notifyWorkspaceBuildFailed(ctx context.Context, workspace database.Workspace, build database.WorkspaceBuild) {
+ var reason string
+ if build.Reason.Valid() && build.Reason == database.BuildReasonInitiator {
+ return // failed workspace build initiated by a user should not notify
+ }
+ reason = string(build.Reason)
+
+ if _, err := s.NotificationsEnqueuer.Enqueue(ctx, workspace.OwnerID, notifications.TemplateWorkspaceAutobuildFailed,
+ map[string]string{
+ "name": workspace.Name,
+ "reason": reason,
+ }, "provisionerdserver",
+ // Associate this notification with all the related entities.
+ workspace.ID, workspace.OwnerID, workspace.TemplateID, workspace.OrganizationID,
+ ); err != nil {
+ s.Logger.Warn(ctx, "failed to notify of failed workspace autobuild", slog.Error(err))
+ }
+}
+
// CompleteJob is triggered by a provision daemon to mark a provisioner job as completed.
func (s *server) CompleteJob(ctx context.Context, completed *proto.CompletedJob) (*proto.Empty, error) {
ctx, span := s.startTrace(ctx, tracing.FuncName())
@@ -1409,6 +1443,11 @@ func (s *server) CompleteJob(ctx context.Context, completed *proto.CompletedJob)
// audit the outcome of the workspace build
if getWorkspaceError == nil {
+ // If the workspace has been deleted, notify the owner about it.
+ if workspaceBuild.Transition == database.WorkspaceTransitionDelete {
+ s.notifyWorkspaceDeleted(ctx, workspace, workspaceBuild)
+ }
+
auditor := s.Auditor.Load()
auditAction := auditActionFromTransition(workspaceBuild.Transition)
@@ -1509,6 +1548,43 @@ func (s *server) CompleteJob(ctx context.Context, completed *proto.CompletedJob)
return &proto.Empty{}, nil
}
+func (s *server) notifyWorkspaceDeleted(ctx context.Context, workspace database.Workspace, build database.WorkspaceBuild) {
+ var reason string
+ initiator := build.InitiatorByUsername
+ if build.Reason.Valid() {
+ switch build.Reason {
+ case database.BuildReasonInitiator:
+ if build.InitiatorID == workspace.OwnerID {
+ // Deletions initiated by self should not notify.
+ return
+ }
+
+ reason = "initiated by user"
+ case database.BuildReasonAutodelete:
+ reason = "autodeleted due to dormancy"
+ initiator = "autobuild"
+ default:
+ reason = string(build.Reason)
+ }
+ } else {
+ reason = string(build.Reason)
+ s.Logger.Warn(ctx, "invalid build reason when sending deletion notification",
+ slog.F("reason", reason), slog.F("workspace_id", workspace.ID), slog.F("build_id", build.ID))
+ }
+
+ if _, err := s.NotificationsEnqueuer.Enqueue(ctx, workspace.OwnerID, notifications.TemplateWorkspaceDeleted,
+ map[string]string{
+ "name": workspace.Name,
+ "reason": reason,
+ "initiator": initiator,
+ }, "provisionerdserver",
+ // Associate this notification with all the related entities.
+ workspace.ID, workspace.OwnerID, workspace.TemplateID, workspace.OrganizationID,
+ ); err != nil {
+ s.Logger.Warn(ctx, "failed to notify of workspace deletion", slog.Error(err))
+ }
+}
+
func (s *server) startTrace(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span) {
return s.Tracer.Start(ctx, name, append(opts, trace.WithAttributes(
semconv.ServiceNameKey.String("coderd.provisionerd"),
diff --git a/coderd/provisionerdserver/provisionerdserver_test.go b/coderd/provisionerdserver/provisionerdserver_test.go
index e0403b7c7db2d..79c1b00ac78ee 100644
--- a/coderd/provisionerdserver/provisionerdserver_test.go
+++ b/coderd/provisionerdserver/provisionerdserver_test.go
@@ -24,6 +24,8 @@ import (
"golang.org/x/oauth2"
"cdr.dev/slog/sloggers/slogtest"
+ "github.com/coder/serpent"
+
"github.com/coder/coder/v2/buildinfo"
"github.com/coder/coder/v2/coderd/audit"
"github.com/coder/coder/v2/coderd/database"
@@ -32,6 +34,7 @@ import (
"github.com/coder/coder/v2/coderd/database/dbtime"
"github.com/coder/coder/v2/coderd/database/pubsub"
"github.com/coder/coder/v2/coderd/externalauth"
+ "github.com/coder/coder/v2/coderd/notifications"
"github.com/coder/coder/v2/coderd/provisionerdserver"
"github.com/coder/coder/v2/coderd/schedule"
"github.com/coder/coder/v2/coderd/schedule/cron"
@@ -41,7 +44,6 @@ import (
"github.com/coder/coder/v2/provisionersdk"
sdkproto "github.com/coder/coder/v2/provisionersdk/proto"
"github.com/coder/coder/v2/testutil"
- "github.com/coder/serpent"
)
func testTemplateScheduleStore() *atomic.Pointer[schedule.TemplateScheduleStore] {
@@ -102,8 +104,7 @@ func TestHeartbeat(t *testing.T) {
select {
case <-hbCtx.Done():
return hbCtx.Err()
- default:
- heartbeatChan <- struct{}{}
+ case heartbeatChan <- struct{}{}:
return nil
}
}
@@ -365,6 +366,7 @@ func TestAcquireJob(t *testing.T) {
WorkspaceOwnerSessionToken: sessionToken,
WorkspaceOwnerSshPublicKey: sshKey.PublicKey,
WorkspaceOwnerSshPrivateKey: sshKey.PrivateKey,
+ WorkspaceBuildId: build.ID.String(),
},
},
})
@@ -1563,6 +1565,247 @@ func TestInsertWorkspaceResource(t *testing.T) {
})
}
+func TestNotifications(t *testing.T) {
+ t.Parallel()
+
+ t.Run("Workspace deletion", func(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ deletionReason database.BuildReason
+ shouldNotify bool
+ shouldSelfInitiate bool
+ }{
+ {
+ name: "initiated by autodelete",
+ deletionReason: database.BuildReasonAutodelete,
+ shouldNotify: true,
+ },
+ {
+ name: "initiated by self",
+ deletionReason: database.BuildReasonInitiator,
+ shouldNotify: false,
+ shouldSelfInitiate: true,
+ },
+ {
+ name: "initiated by someone else",
+ deletionReason: database.BuildReasonInitiator,
+ shouldNotify: true,
+ shouldSelfInitiate: false,
+ },
+ }
+
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ ctx := context.Background()
+ notifEnq := &testutil.FakeNotificationsEnqueuer{}
+
+ srv, db, ps, pd := setup(t, false, &overrides{
+ notificationEnqueuer: notifEnq,
+ })
+
+ user := dbgen.User(t, db, database.User{})
+ initiator := user
+ if !tc.shouldSelfInitiate {
+ initiator = dbgen.User(t, db, database.User{})
+ }
+
+ template := dbgen.Template(t, db, database.Template{
+ Name: "template",
+ Provisioner: database.ProvisionerTypeEcho,
+ OrganizationID: pd.OrganizationID,
+ })
+ template, err := db.GetTemplateByID(ctx, template.ID)
+ require.NoError(t, err)
+ file := dbgen.File(t, db, database.File{CreatedBy: user.ID})
+ workspace := dbgen.Workspace(t, db, database.Workspace{
+ TemplateID: template.ID,
+ OwnerID: user.ID,
+ OrganizationID: pd.OrganizationID,
+ })
+ version := dbgen.TemplateVersion(t, db, database.TemplateVersion{
+ OrganizationID: pd.OrganizationID,
+ TemplateID: uuid.NullUUID{
+ UUID: template.ID,
+ Valid: true,
+ },
+ JobID: uuid.New(),
+ })
+ build := dbgen.WorkspaceBuild(t, db, database.WorkspaceBuild{
+ WorkspaceID: workspace.ID,
+ TemplateVersionID: version.ID,
+ InitiatorID: initiator.ID,
+ Transition: database.WorkspaceTransitionDelete,
+ Reason: tc.deletionReason,
+ })
+ job := dbgen.ProvisionerJob(t, db, ps, database.ProvisionerJob{
+ FileID: file.ID,
+ Type: database.ProvisionerJobTypeWorkspaceBuild,
+ Input: must(json.Marshal(provisionerdserver.WorkspaceProvisionJob{
+ WorkspaceBuildID: build.ID,
+ })),
+ OrganizationID: pd.OrganizationID,
+ })
+ _, err = db.AcquireProvisionerJob(ctx, database.AcquireProvisionerJobParams{
+ OrganizationID: pd.OrganizationID,
+ WorkerID: uuid.NullUUID{
+ UUID: pd.ID,
+ Valid: true,
+ },
+ Types: []database.ProvisionerType{database.ProvisionerTypeEcho},
+ })
+ require.NoError(t, err)
+
+ _, err = srv.CompleteJob(ctx, &proto.CompletedJob{
+ JobId: job.ID.String(),
+ Type: &proto.CompletedJob_WorkspaceBuild_{
+ WorkspaceBuild: &proto.CompletedJob_WorkspaceBuild{
+ State: []byte{},
+ Resources: []*sdkproto.Resource{{
+ Name: "example",
+ Type: "aws_instance",
+ }},
+ },
+ },
+ })
+ require.NoError(t, err)
+
+ workspace, err = db.GetWorkspaceByID(ctx, workspace.ID)
+ require.NoError(t, err)
+ require.True(t, workspace.Deleted)
+
+ if tc.shouldNotify {
+ // Validate that the notification was sent and contained the expected values.
+ require.Len(t, notifEnq.Sent, 1)
+ require.Equal(t, notifEnq.Sent[0].UserID, user.ID)
+ require.Contains(t, notifEnq.Sent[0].Targets, template.ID)
+ require.Contains(t, notifEnq.Sent[0].Targets, workspace.ID)
+ require.Contains(t, notifEnq.Sent[0].Targets, workspace.OrganizationID)
+ require.Contains(t, notifEnq.Sent[0].Targets, user.ID)
+ if tc.deletionReason == database.BuildReasonInitiator {
+ require.Equal(t, initiator.Username, notifEnq.Sent[0].Labels["initiator"])
+ }
+ } else {
+ require.Len(t, notifEnq.Sent, 0)
+ }
+ })
+ }
+ })
+
+ t.Run("Workspace build failed", func(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+
+ buildReason database.BuildReason
+ shouldNotify bool
+ }{
+ {
+ name: "initiated by owner",
+ buildReason: database.BuildReasonInitiator,
+ shouldNotify: false,
+ },
+ {
+ name: "initiated by autostart",
+ buildReason: database.BuildReasonAutostart,
+ shouldNotify: true,
+ },
+ }
+
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ ctx := context.Background()
+ notifEnq := &testutil.FakeNotificationsEnqueuer{}
+
+ // Otherwise `(*Server).FailJob` fails with:
+ // audit log - get build {"error": "sql: no rows in result set"}
+ ignoreLogErrors := true
+ srv, db, ps, pd := setup(t, ignoreLogErrors, &overrides{
+ notificationEnqueuer: notifEnq,
+ })
+
+ user := dbgen.User(t, db, database.User{})
+ initiator := user
+
+ template := dbgen.Template(t, db, database.Template{
+ Name: "template",
+ Provisioner: database.ProvisionerTypeEcho,
+ OrganizationID: pd.OrganizationID,
+ })
+ template, err := db.GetTemplateByID(ctx, template.ID)
+ require.NoError(t, err)
+ file := dbgen.File(t, db, database.File{CreatedBy: user.ID})
+ workspace := dbgen.Workspace(t, db, database.Workspace{
+ TemplateID: template.ID,
+ OwnerID: user.ID,
+ OrganizationID: pd.OrganizationID,
+ })
+ version := dbgen.TemplateVersion(t, db, database.TemplateVersion{
+ OrganizationID: pd.OrganizationID,
+ TemplateID: uuid.NullUUID{
+ UUID: template.ID,
+ Valid: true,
+ },
+ JobID: uuid.New(),
+ })
+ build := dbgen.WorkspaceBuild(t, db, database.WorkspaceBuild{
+ WorkspaceID: workspace.ID,
+ TemplateVersionID: version.ID,
+ InitiatorID: initiator.ID,
+ Transition: database.WorkspaceTransitionDelete,
+ Reason: tc.buildReason,
+ })
+ job := dbgen.ProvisionerJob(t, db, ps, database.ProvisionerJob{
+ FileID: file.ID,
+ Type: database.ProvisionerJobTypeWorkspaceBuild,
+ Input: must(json.Marshal(provisionerdserver.WorkspaceProvisionJob{
+ WorkspaceBuildID: build.ID,
+ })),
+ OrganizationID: pd.OrganizationID,
+ })
+ _, err = db.AcquireProvisionerJob(ctx, database.AcquireProvisionerJobParams{
+ OrganizationID: pd.OrganizationID,
+ WorkerID: uuid.NullUUID{
+ UUID: pd.ID,
+ Valid: true,
+ },
+ Types: []database.ProvisionerType{database.ProvisionerTypeEcho},
+ })
+ require.NoError(t, err)
+
+ _, err = srv.FailJob(ctx, &proto.FailedJob{
+ JobId: job.ID.String(),
+ Type: &proto.FailedJob_WorkspaceBuild_{
+ WorkspaceBuild: &proto.FailedJob_WorkspaceBuild{
+ State: []byte{},
+ },
+ },
+ })
+ require.NoError(t, err)
+
+ if tc.shouldNotify {
+ // Validate that the notification was sent and contained the expected values.
+ require.Len(t, notifEnq.Sent, 1)
+ require.Equal(t, notifEnq.Sent[0].UserID, user.ID)
+ require.Contains(t, notifEnq.Sent[0].Targets, template.ID)
+ require.Contains(t, notifEnq.Sent[0].Targets, workspace.ID)
+ require.Contains(t, notifEnq.Sent[0].Targets, workspace.OrganizationID)
+ require.Contains(t, notifEnq.Sent[0].Targets, user.ID)
+ require.Equal(t, string(tc.buildReason), notifEnq.Sent[0].Labels["reason"])
+ } else {
+ require.Len(t, notifEnq.Sent, 0)
+ }
+ })
+ }
+ })
+}
+
type overrides struct {
ctx context.Context
deploymentValues *codersdk.DeploymentValues
@@ -1574,6 +1817,7 @@ type overrides struct {
heartbeatFn func(ctx context.Context) error
heartbeatInterval time.Duration
auditor audit.Auditor
+ notificationEnqueuer notifications.Enqueuer
}
func setup(t *testing.T, ignoreLogErrors bool, ov *overrides) (proto.DRPCProvisionerDaemonServer, database.Store, pubsub.Pubsub, database.ProvisionerDaemon) {
@@ -1635,6 +1879,12 @@ func setup(t *testing.T, ignoreLogErrors bool, ov *overrides) (proto.DRPCProvisi
}
auditPtr.Store(&auditor)
pollDur = ov.acquireJobLongPollDuration
+ var notifEnq notifications.Enqueuer
+ if ov.notificationEnqueuer != nil {
+ notifEnq = ov.notificationEnqueuer
+ } else {
+ notifEnq = notifications.NewNoopEnqueuer()
+ }
daemon, err := db.UpsertProvisionerDaemon(ov.ctx, database.UpsertProvisionerDaemonParams{
Name: "test",
@@ -1674,6 +1924,7 @@ func setup(t *testing.T, ignoreLogErrors bool, ov *overrides) (proto.DRPCProvisi
HeartbeatInterval: ov.heartbeatInterval,
HeartbeatFn: ov.heartbeatFn,
},
+ notifEnq,
)
require.NoError(t, err)
return srv, db, ps, daemon
diff --git a/coderd/provisionerjobs_test.go b/coderd/provisionerjobs_test.go
index 2dc5db3bf8efb..cf17d6495cfed 100644
--- a/coderd/provisionerjobs_test.go
+++ b/coderd/provisionerjobs_test.go
@@ -35,7 +35,7 @@ func TestProvisionerJobLogs(t *testing.T) {
})
template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
- workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
+ workspace := coderdtest.CreateWorkspace(t, client, template.ID)
coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, workspace.LatestBuild.ID)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
@@ -74,7 +74,7 @@ func TestProvisionerJobLogs(t *testing.T) {
})
template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
- workspace := coderdtest.CreateWorkspace(t, client, user.OrganizationID, template.ID)
+ workspace := coderdtest.CreateWorkspace(t, client, template.ID)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
diff --git a/coderd/provisionerkey/provisionerkey.go b/coderd/provisionerkey/provisionerkey.go
new file mode 100644
index 0000000000000..bfd70fb0295e0
--- /dev/null
+++ b/coderd/provisionerkey/provisionerkey.go
@@ -0,0 +1,54 @@
+package provisionerkey
+
+import (
+ "crypto/sha256"
+ "crypto/subtle"
+
+ "github.com/google/uuid"
+ "golang.org/x/xerrors"
+
+ "github.com/coder/coder/v2/coderd/database"
+ "github.com/coder/coder/v2/coderd/database/dbtime"
+ "github.com/coder/coder/v2/cryptorand"
+)
+
+const (
+ secretLength = 43
+)
+
+func New(organizationID uuid.UUID, name string, tags map[string]string) (database.InsertProvisionerKeyParams, string, error) {
+ secret, err := cryptorand.String(secretLength)
+ if err != nil {
+ return database.InsertProvisionerKeyParams{}, "", xerrors.Errorf("generate secret: %w", err)
+ }
+
+ if tags == nil {
+ tags = map[string]string{}
+ }
+
+ return database.InsertProvisionerKeyParams{
+ ID: uuid.New(),
+ CreatedAt: dbtime.Now(),
+ OrganizationID: organizationID,
+ Name: name,
+ HashedSecret: HashSecret(secret),
+ Tags: tags,
+ }, secret, nil
+}
+
+func Validate(token string) error {
+ if len(token) != secretLength {
+ return xerrors.Errorf("must be %d characters", secretLength)
+ }
+
+ return nil
+}
+
+func HashSecret(secret string) []byte {
+ h := sha256.Sum256([]byte(secret))
+ return h[:]
+}
+
+func Compare(a []byte, b []byte) bool {
+ return subtle.ConstantTimeCompare(a, b) != 1
+}
diff --git a/coderd/rbac/astvalue.go b/coderd/rbac/astvalue.go
index 9549eb1ed7be8..e2fcedbd439f3 100644
--- a/coderd/rbac/astvalue.go
+++ b/coderd/rbac/astvalue.go
@@ -124,6 +124,10 @@ func (z Object) regoValue() ast.Value {
ast.StringTerm("org_owner"),
ast.StringTerm(z.OrgID),
},
+ [2]*ast.Term{
+ ast.StringTerm("any_org"),
+ ast.BooleanTerm(z.AnyOrgOwner),
+ },
[2]*ast.Term{
ast.StringTerm("type"),
ast.StringTerm(z.Type),
diff --git a/coderd/rbac/authz.go b/coderd/rbac/authz.go
index 859782d0286b1..ff4f9ce2371d4 100644
--- a/coderd/rbac/authz.go
+++ b/coderd/rbac/authz.go
@@ -75,6 +75,17 @@ type Subject struct {
cachedASTValue ast.Value
}
+// RegoValueOk is only used for unit testing. There is no easy way
+// to get the error for the unexported method, and this is intentional.
+// Failed rego values can default to the backup json marshal method,
+// so errors are not fatal. Unit tests should be aware when the custom
+// rego marshaller fails.
+func (s Subject) RegoValueOk() error {
+ tmp := s
+ _, err := tmp.regoValue()
+ return err
+}
+
// WithCachedASTValue can be called if the subject is static. This will compute
// the ast value once and cache it for future calls.
func (s Subject) WithCachedASTValue() Subject {
@@ -110,13 +121,13 @@ func (s Subject) SafeScopeName() string {
if s.Scope == nil {
return "no-scope"
}
- return s.Scope.Name()
+ return s.Scope.Name().String()
}
// SafeRoleNames prevent nil pointer dereference.
-func (s Subject) SafeRoleNames() []string {
+func (s Subject) SafeRoleNames() []RoleIdentifier {
if s.Roles == nil {
- return []string{}
+ return []RoleIdentifier{}
}
return s.Roles.Names()
}
@@ -170,7 +181,7 @@ func Filter[O Objecter](ctx context.Context, auth Authorizer, subject Subject, a
for _, o := range objects {
rbacObj := o.RBACObject()
if rbacObj.Type != objectType {
- return nil, xerrors.Errorf("object types must be uniform across the set (%s), found %s", objectType, rbacObj)
+ return nil, xerrors.Errorf("object types must be uniform across the set (%s), found %s", objectType, rbacObj.Type)
}
err := auth.Authorize(ctx, subject, action, o.RBACObject())
if err == nil {
@@ -376,6 +387,13 @@ func (a RegoAuthorizer) authorize(ctx context.Context, subject Subject, action p
return xerrors.Errorf("subject must have a scope")
}
+ // The caller should use either 1 or the other (or none).
+ // Using "AnyOrgOwner" and an OrgID is a contradiction.
+ // An empty uuid or a nil uuid means "no org owner".
+ if object.AnyOrgOwner && !(object.OrgID == "" || object.OrgID == "00000000-0000-0000-0000-000000000000") {
+ return xerrors.Errorf("object cannot have 'any_org' and an 'org_id' specified, values are mutually exclusive")
+ }
+
astV, err := regoInputValue(subject, action, object)
if err != nil {
return xerrors.Errorf("convert input to value: %w", err)
@@ -707,9 +725,15 @@ func (c *authCache) Prepare(ctx context.Context, subject Subject, action policy.
// rbacTraceAttributes are the attributes that are added to all spans created by
// the rbac package. These attributes should help to debug slow spans.
func rbacTraceAttributes(actor Subject, action policy.Action, objectType string, extra ...attribute.KeyValue) trace.SpanStartOption {
+ uniqueRoleNames := actor.SafeRoleNames()
+ roleStrings := make([]string, 0, len(uniqueRoleNames))
+ for _, roleName := range uniqueRoleNames {
+ roleName := roleName
+ roleStrings = append(roleStrings, roleName.String())
+ }
return trace.WithAttributes(
append(extra,
- attribute.StringSlice("subject_roles", actor.SafeRoleNames()),
+ attribute.StringSlice("subject_roles", roleStrings),
attribute.Int("num_subject_roles", len(actor.SafeRoleNames())),
attribute.Int("num_groups", len(actor.Groups)),
attribute.String("scope", actor.SafeScopeName()),
diff --git a/coderd/rbac/authz_internal_test.go b/coderd/rbac/authz_internal_test.go
index 7b53939a3651b..a9de3c56cb26a 100644
--- a/coderd/rbac/authz_internal_test.go
+++ b/coderd/rbac/authz_internal_test.go
@@ -56,7 +56,7 @@ func TestFilterError(t *testing.T) {
auth := NewAuthorizer(prometheus.NewRegistry())
subject := Subject{
ID: uuid.NewString(),
- Roles: RoleNames{},
+ Roles: RoleIdentifiers{},
Groups: []string{},
Scope: ScopeAll,
}
@@ -77,7 +77,7 @@ func TestFilterError(t *testing.T) {
subject := Subject{
ID: uuid.NewString(),
- Roles: RoleNames{
+ Roles: RoleIdentifiers{
RoleOwner(),
},
Groups: []string{},
@@ -159,7 +159,7 @@ func TestFilter(t *testing.T) {
Name: "NoRoles",
Actor: Subject{
ID: userIDs[0].String(),
- Roles: RoleNames{},
+ Roles: RoleIdentifiers{},
},
ObjectType: ResourceWorkspace.Type,
Action: policy.ActionRead,
@@ -168,7 +168,7 @@ func TestFilter(t *testing.T) {
Name: "Admin",
Actor: Subject{
ID: userIDs[0].String(),
- Roles: RoleNames{RoleOrgMember(orgIDs[0]), "auditor", RoleOwner(), RoleMember()},
+ Roles: RoleIdentifiers{ScopedRoleOrgMember(orgIDs[0]), RoleAuditor(), RoleOwner(), RoleMember()},
},
ObjectType: ResourceWorkspace.Type,
Action: policy.ActionRead,
@@ -177,7 +177,7 @@ func TestFilter(t *testing.T) {
Name: "OrgAdmin",
Actor: Subject{
ID: userIDs[0].String(),
- Roles: RoleNames{RoleOrgMember(orgIDs[0]), RoleOrgAdmin(orgIDs[0]), RoleMember()},
+ Roles: RoleIdentifiers{ScopedRoleOrgMember(orgIDs[0]), ScopedRoleOrgAdmin(orgIDs[0]), RoleMember()},
},
ObjectType: ResourceWorkspace.Type,
Action: policy.ActionRead,
@@ -186,7 +186,7 @@ func TestFilter(t *testing.T) {
Name: "OrgMember",
Actor: Subject{
ID: userIDs[0].String(),
- Roles: RoleNames{RoleOrgMember(orgIDs[0]), RoleOrgMember(orgIDs[1]), RoleMember()},
+ Roles: RoleIdentifiers{ScopedRoleOrgMember(orgIDs[0]), ScopedRoleOrgMember(orgIDs[1]), RoleMember()},
},
ObjectType: ResourceWorkspace.Type,
Action: policy.ActionRead,
@@ -195,12 +195,12 @@ func TestFilter(t *testing.T) {
Name: "ManyRoles",
Actor: Subject{
ID: userIDs[0].String(),
- Roles: RoleNames{
- RoleOrgMember(orgIDs[0]), RoleOrgAdmin(orgIDs[0]),
- RoleOrgMember(orgIDs[1]), RoleOrgAdmin(orgIDs[1]),
- RoleOrgMember(orgIDs[2]), RoleOrgAdmin(orgIDs[2]),
- RoleOrgMember(orgIDs[4]),
- RoleOrgMember(orgIDs[5]),
+ Roles: RoleIdentifiers{
+ ScopedRoleOrgMember(orgIDs[0]), ScopedRoleOrgAdmin(orgIDs[0]),
+ ScopedRoleOrgMember(orgIDs[1]), ScopedRoleOrgAdmin(orgIDs[1]),
+ ScopedRoleOrgMember(orgIDs[2]), ScopedRoleOrgAdmin(orgIDs[2]),
+ ScopedRoleOrgMember(orgIDs[4]),
+ ScopedRoleOrgMember(orgIDs[5]),
RoleMember(),
},
},
@@ -211,7 +211,7 @@ func TestFilter(t *testing.T) {
Name: "SiteMember",
Actor: Subject{
ID: userIDs[0].String(),
- Roles: RoleNames{RoleMember()},
+ Roles: RoleIdentifiers{RoleMember()},
},
ObjectType: ResourceUser.Type,
Action: policy.ActionRead,
@@ -220,11 +220,11 @@ func TestFilter(t *testing.T) {
Name: "ReadOrgs",
Actor: Subject{
ID: userIDs[0].String(),
- Roles: RoleNames{
- RoleOrgMember(orgIDs[0]),
- RoleOrgMember(orgIDs[1]),
- RoleOrgMember(orgIDs[2]),
- RoleOrgMember(orgIDs[3]),
+ Roles: RoleIdentifiers{
+ ScopedRoleOrgMember(orgIDs[0]),
+ ScopedRoleOrgMember(orgIDs[1]),
+ ScopedRoleOrgMember(orgIDs[2]),
+ ScopedRoleOrgMember(orgIDs[3]),
RoleMember(),
},
},
@@ -235,7 +235,7 @@ func TestFilter(t *testing.T) {
Name: "ScopeApplicationConnect",
Actor: Subject{
ID: userIDs[0].String(),
- Roles: RoleNames{RoleOrgMember(orgIDs[0]), "auditor", RoleOwner(), RoleMember()},
+ Roles: RoleIdentifiers{ScopedRoleOrgMember(orgIDs[0]), RoleAuditor(), RoleOwner(), RoleMember()},
},
ObjectType: ResourceWorkspace.Type,
Action: policy.ActionRead,
@@ -291,13 +291,29 @@ func TestAuthorizeDomain(t *testing.T) {
unuseID := uuid.New()
allUsersGroup := "Everyone"
+ // orphanedUser has no organization
+ orphanedUser := Subject{
+ ID: "me",
+ Scope: must(ExpandScope(ScopeAll)),
+ Groups: []string{},
+ Roles: Roles{
+ must(RoleByName(RoleMember())),
+ },
+ }
+ testAuthorize(t, "OrphanedUser", orphanedUser, []authTestCase{
+ {resource: ResourceWorkspace.InOrg(defOrg).WithOwner(orphanedUser.ID), actions: ResourceWorkspace.AvailableActions(), allow: false},
+
+ // Orphaned user cannot create workspaces in any organization
+ {resource: ResourceWorkspace.AnyOrganization().WithOwner(orphanedUser.ID), actions: []policy.Action{policy.ActionCreate}, allow: false},
+ })
+
user := Subject{
ID: "me",
Scope: must(ExpandScope(ScopeAll)),
Groups: []string{allUsersGroup},
Roles: Roles{
must(RoleByName(RoleMember())),
- must(RoleByName(RoleOrgMember(defOrg))),
+ must(RoleByName(ScopedRoleOrgMember(defOrg))),
},
}
@@ -370,6 +386,10 @@ func TestAuthorizeDomain(t *testing.T) {
{resource: ResourceWorkspace.InOrg(defOrg).WithOwner(user.ID), actions: ResourceWorkspace.AvailableActions(), allow: true},
{resource: ResourceWorkspace.InOrg(defOrg), actions: ResourceWorkspace.AvailableActions(), allow: false},
+ // AnyOrganization using a user scoped permission
+ {resource: ResourceWorkspace.AnyOrganization().WithOwner(user.ID), actions: ResourceWorkspace.AvailableActions(), allow: true},
+ {resource: ResourceTemplate.AnyOrganization(), actions: []policy.Action{policy.ActionCreate}, allow: false},
+
{resource: ResourceWorkspace.WithOwner(user.ID), actions: ResourceWorkspace.AvailableActions(), allow: true},
{resource: ResourceWorkspace.All(), actions: ResourceWorkspace.AvailableActions(), allow: false},
@@ -394,7 +414,7 @@ func TestAuthorizeDomain(t *testing.T) {
ID: "me",
Scope: must(ExpandScope(ScopeAll)),
Roles: Roles{{
- Name: "deny-all",
+ Identifier: RoleIdentifier{Name: "deny-all"},
// List out deny permissions explicitly
Site: []Permission{
{
@@ -435,7 +455,7 @@ func TestAuthorizeDomain(t *testing.T) {
ID: "me",
Scope: must(ExpandScope(ScopeAll)),
Roles: Roles{
- must(RoleByName(RoleOrgAdmin(defOrg))),
+ must(RoleByName(ScopedRoleOrgAdmin(defOrg))),
must(RoleByName(RoleMember())),
},
}
@@ -443,6 +463,8 @@ func TestAuthorizeDomain(t *testing.T) {
workspaceExceptConnect := slice.Omit(ResourceWorkspace.AvailableActions(), policy.ActionApplicationConnect, policy.ActionSSH)
workspaceConnect := []policy.Action{policy.ActionApplicationConnect, policy.ActionSSH}
testAuthorize(t, "OrgAdmin", user, []authTestCase{
+ {resource: ResourceTemplate.AnyOrganization(), actions: []policy.Action{policy.ActionCreate}, allow: true},
+
// Org + me
{resource: ResourceWorkspace.InOrg(defOrg).WithOwner(user.ID), actions: ResourceWorkspace.AvailableActions(), allow: true},
{resource: ResourceWorkspace.InOrg(defOrg), actions: workspaceExceptConnect, allow: true},
@@ -479,6 +501,9 @@ func TestAuthorizeDomain(t *testing.T) {
}
testAuthorize(t, "SiteAdmin", user, []authTestCase{
+ // Similar to an orphaned user, but has site level perms
+ {resource: ResourceTemplate.AnyOrganization(), actions: []policy.Action{policy.ActionCreate}, allow: true},
+
// Org + me
{resource: ResourceWorkspace.InOrg(defOrg).WithOwner(user.ID), actions: ResourceWorkspace.AvailableActions(), allow: true},
{resource: ResourceWorkspace.InOrg(defOrg), actions: ResourceWorkspace.AvailableActions(), allow: true},
@@ -507,7 +532,7 @@ func TestAuthorizeDomain(t *testing.T) {
ID: "me",
Scope: must(ExpandScope(ScopeApplicationConnect)),
Roles: Roles{
- must(RoleByName(RoleOrgMember(defOrg))),
+ must(RoleByName(ScopedRoleOrgMember(defOrg))),
must(RoleByName(RoleMember())),
},
}
@@ -607,8 +632,8 @@ func TestAuthorizeDomain(t *testing.T) {
Scope: must(ExpandScope(ScopeAll)),
Roles: Roles{
{
- Name: "ReadOnlyOrgAndUser",
- Site: []Permission{},
+ Identifier: RoleIdentifier{Name: "ReadOnlyOrgAndUser"},
+ Site: []Permission{},
Org: map[string][]Permission{
defOrg.String(): {{
Negate: false,
@@ -701,7 +726,7 @@ func TestAuthorizeLevels(t *testing.T) {
Roles: Roles{
must(RoleByName(RoleOwner())),
{
- Name: "org-deny:" + defOrg.String(),
+ Identifier: RoleIdentifier{Name: "org-deny:", OrganizationID: defOrg},
Org: map[string][]Permission{
defOrg.String(): {
{
@@ -713,7 +738,7 @@ func TestAuthorizeLevels(t *testing.T) {
},
},
{
- Name: "user-deny-all",
+ Identifier: RoleIdentifier{Name: "user-deny-all"},
// List out deny permissions explicitly
User: []Permission{
{
@@ -761,7 +786,7 @@ func TestAuthorizeLevels(t *testing.T) {
Scope: must(ExpandScope(ScopeAll)),
Roles: Roles{
{
- Name: "site-noise",
+ Identifier: RoleIdentifier{Name: "site-noise"},
Site: []Permission{
{
Negate: true,
@@ -770,9 +795,9 @@ func TestAuthorizeLevels(t *testing.T) {
},
},
},
- must(RoleByName(RoleOrgAdmin(defOrg))),
+ must(RoleByName(ScopedRoleOrgAdmin(defOrg))),
{
- Name: "user-deny-all",
+ Identifier: RoleIdentifier{Name: "user-deny-all"},
// List out deny permissions explicitly
User: []Permission{
{
@@ -856,7 +881,7 @@ func TestAuthorizeScope(t *testing.T) {
ID: "me",
Roles: Roles{
must(RoleByName(RoleMember())),
- must(RoleByName(RoleOrgMember(defOrg))),
+ must(RoleByName(ScopedRoleOrgMember(defOrg))),
},
Scope: must(ExpandScope(ScopeApplicationConnect)),
}
@@ -892,11 +917,11 @@ func TestAuthorizeScope(t *testing.T) {
ID: "me",
Roles: Roles{
must(RoleByName(RoleMember())),
- must(RoleByName(RoleOrgMember(defOrg))),
+ must(RoleByName(ScopedRoleOrgMember(defOrg))),
},
Scope: Scope{
Role: Role{
- Name: "workspace_agent",
+ Identifier: RoleIdentifier{Name: "workspace_agent"},
DisplayName: "Workspace Agent",
Site: Permissions(map[string][]policy.Action{
// Only read access for workspaces.
@@ -981,11 +1006,11 @@ func TestAuthorizeScope(t *testing.T) {
ID: "me",
Roles: Roles{
must(RoleByName(RoleMember())),
- must(RoleByName(RoleOrgMember(defOrg))),
+ must(RoleByName(ScopedRoleOrgMember(defOrg))),
},
Scope: Scope{
Role: Role{
- Name: "create_workspace",
+ Identifier: RoleIdentifier{Name: "create_workspace"},
DisplayName: "Create Workspace",
Site: Permissions(map[string][]policy.Action{
// Only read access for workspaces.
@@ -1078,9 +1103,10 @@ func testAuthorize(t *testing.T, name string, subject Subject, sets ...[]authTes
t.Logf("input: %s", string(d))
if authError != nil {
var uerr *UnauthorizedError
- xerrors.As(authError, &uerr)
- t.Logf("internal error: %+v", uerr.Internal().Error())
- t.Logf("output: %+v", uerr.Output())
+ if xerrors.As(authError, &uerr) {
+ t.Logf("internal error: %+v", uerr.Internal().Error())
+ t.Logf("output: %+v", uerr.Output())
+ }
}
if c.allow {
@@ -1115,10 +1141,15 @@ func testAuthorize(t *testing.T, name string, subject Subject, sets ...[]authTes
require.Equal(t, 0, len(partialAuthz.partialQueries.Support), "expected 0 support rules in scope authorizer")
partialErr := partialAuthz.Authorize(ctx, c.resource)
- if authError != nil {
- assert.Error(t, partialErr, "partial allowed invalid request (false positive)")
- } else {
- assert.NoError(t, partialErr, "partial error blocked valid request (false negative)")
+ // If 'AnyOrgOwner' is true, a partial eval does not make sense.
+ // Run the partial eval to ensure no panics, but the actual authz
+ // response does not matter.
+ if !c.resource.AnyOrgOwner {
+ if authError != nil {
+ assert.Error(t, partialErr, "partial allowed invalid request (false positive)")
+ } else {
+ assert.NoError(t, partialErr, "partial error blocked valid request (false negative)")
+ }
}
}
})
diff --git a/coderd/rbac/authz_test.go b/coderd/rbac/authz_test.go
index 05940856ec583..6934391d6ed53 100644
--- a/coderd/rbac/authz_test.go
+++ b/coderd/rbac/authz_test.go
@@ -41,7 +41,7 @@ func benchmarkUserCases() (cases []benchmarkCase, users uuid.UUID, orgs []uuid.U
Name: "NoRoles",
Actor: rbac.Subject{
ID: user.String(),
- Roles: rbac.RoleNames{},
+ Roles: rbac.RoleIdentifiers{},
Scope: rbac.ScopeAll,
},
},
@@ -49,7 +49,7 @@ func benchmarkUserCases() (cases []benchmarkCase, users uuid.UUID, orgs []uuid.U
Name: "Admin",
Actor: rbac.Subject{
// Give some extra roles that an admin might have
- Roles: rbac.RoleNames{rbac.RoleOrgMember(orgs[0]), "auditor", rbac.RoleOwner(), rbac.RoleMember()},
+ Roles: rbac.RoleIdentifiers{rbac.ScopedRoleOrgMember(orgs[0]), rbac.RoleAuditor(), rbac.RoleOwner(), rbac.RoleMember()},
ID: user.String(),
Scope: rbac.ScopeAll,
Groups: noiseGroups,
@@ -58,7 +58,7 @@ func benchmarkUserCases() (cases []benchmarkCase, users uuid.UUID, orgs []uuid.U
{
Name: "OrgAdmin",
Actor: rbac.Subject{
- Roles: rbac.RoleNames{rbac.RoleOrgMember(orgs[0]), rbac.RoleOrgAdmin(orgs[0]), rbac.RoleMember()},
+ Roles: rbac.RoleIdentifiers{rbac.ScopedRoleOrgMember(orgs[0]), rbac.ScopedRoleOrgAdmin(orgs[0]), rbac.RoleMember()},
ID: user.String(),
Scope: rbac.ScopeAll,
Groups: noiseGroups,
@@ -68,7 +68,7 @@ func benchmarkUserCases() (cases []benchmarkCase, users uuid.UUID, orgs []uuid.U
Name: "OrgMember",
Actor: rbac.Subject{
// Member of 2 orgs
- Roles: rbac.RoleNames{rbac.RoleOrgMember(orgs[0]), rbac.RoleOrgMember(orgs[1]), rbac.RoleMember()},
+ Roles: rbac.RoleIdentifiers{rbac.ScopedRoleOrgMember(orgs[0]), rbac.ScopedRoleOrgMember(orgs[1]), rbac.RoleMember()},
ID: user.String(),
Scope: rbac.ScopeAll,
Groups: noiseGroups,
@@ -78,10 +78,10 @@ func benchmarkUserCases() (cases []benchmarkCase, users uuid.UUID, orgs []uuid.U
Name: "ManyRoles",
Actor: rbac.Subject{
// Admin of many orgs
- Roles: rbac.RoleNames{
- rbac.RoleOrgMember(orgs[0]), rbac.RoleOrgAdmin(orgs[0]),
- rbac.RoleOrgMember(orgs[1]), rbac.RoleOrgAdmin(orgs[1]),
- rbac.RoleOrgMember(orgs[2]), rbac.RoleOrgAdmin(orgs[2]),
+ Roles: rbac.RoleIdentifiers{
+ rbac.ScopedRoleOrgMember(orgs[0]), rbac.ScopedRoleOrgAdmin(orgs[0]),
+ rbac.ScopedRoleOrgMember(orgs[1]), rbac.ScopedRoleOrgAdmin(orgs[1]),
+ rbac.ScopedRoleOrgMember(orgs[2]), rbac.ScopedRoleOrgAdmin(orgs[2]),
rbac.RoleMember(),
},
ID: user.String(),
@@ -93,10 +93,10 @@ func benchmarkUserCases() (cases []benchmarkCase, users uuid.UUID, orgs []uuid.U
Name: "ManyRolesCachedSubject",
Actor: rbac.Subject{
// Admin of many orgs
- Roles: rbac.RoleNames{
- rbac.RoleOrgMember(orgs[0]), rbac.RoleOrgAdmin(orgs[0]),
- rbac.RoleOrgMember(orgs[1]), rbac.RoleOrgAdmin(orgs[1]),
- rbac.RoleOrgMember(orgs[2]), rbac.RoleOrgAdmin(orgs[2]),
+ Roles: rbac.RoleIdentifiers{
+ rbac.ScopedRoleOrgMember(orgs[0]), rbac.ScopedRoleOrgAdmin(orgs[0]),
+ rbac.ScopedRoleOrgMember(orgs[1]), rbac.ScopedRoleOrgAdmin(orgs[1]),
+ rbac.ScopedRoleOrgMember(orgs[2]), rbac.ScopedRoleOrgAdmin(orgs[2]),
rbac.RoleMember(),
},
ID: user.String(),
@@ -108,7 +108,7 @@ func benchmarkUserCases() (cases []benchmarkCase, users uuid.UUID, orgs []uuid.U
Name: "AdminWithScope",
Actor: rbac.Subject{
// Give some extra roles that an admin might have
- Roles: rbac.RoleNames{rbac.RoleOrgMember(orgs[0]), "auditor", rbac.RoleOwner(), rbac.RoleMember()},
+ Roles: rbac.RoleIdentifiers{rbac.ScopedRoleOrgMember(orgs[0]), rbac.RoleAuditor(), rbac.RoleOwner(), rbac.RoleMember()},
ID: user.String(),
Scope: rbac.ScopeApplicationConnect,
Groups: noiseGroups,
@@ -119,8 +119,8 @@ func benchmarkUserCases() (cases []benchmarkCase, users uuid.UUID, orgs []uuid.U
Name: "StaticRoles",
Actor: rbac.Subject{
// Give some extra roles that an admin might have
- Roles: rbac.RoleNames{
- "auditor", rbac.RoleOwner(), rbac.RoleMember(),
+ Roles: rbac.RoleIdentifiers{
+ rbac.RoleAuditor(), rbac.RoleOwner(), rbac.RoleMember(),
rbac.RoleTemplateAdmin(), rbac.RoleUserAdmin(),
},
ID: user.String(),
@@ -133,8 +133,8 @@ func benchmarkUserCases() (cases []benchmarkCase, users uuid.UUID, orgs []uuid.U
Name: "StaticRolesWithCache",
Actor: rbac.Subject{
// Give some extra roles that an admin might have
- Roles: rbac.RoleNames{
- "auditor", rbac.RoleOwner(), rbac.RoleMember(),
+ Roles: rbac.RoleIdentifiers{
+ rbac.RoleAuditor(), rbac.RoleOwner(), rbac.RoleMember(),
rbac.RoleTemplateAdmin(), rbac.RoleUserAdmin(),
},
ID: user.String(),
@@ -314,7 +314,7 @@ func BenchmarkCacher(b *testing.B) {
}
}
-func TestCacher(t *testing.T) {
+func TestCache(t *testing.T) {
t.Parallel()
t.Run("NoCache", func(t *testing.T) {
diff --git a/coderd/rbac/object.go b/coderd/rbac/object.go
index dfd8ab6b55b23..4f42de94a4c52 100644
--- a/coderd/rbac/object.go
+++ b/coderd/rbac/object.go
@@ -23,6 +23,12 @@ type Object struct {
Owner string `json:"owner"`
// OrgID specifies which org the object is a part of.
OrgID string `json:"org_owner"`
+ // AnyOrgOwner will disregard the org_owner when checking for permissions
+ // Use this to ask, "Can the actor do this action on any org?" when
+ // the exact organization is not important or known.
+ // E.g: The UI should show a "create template" button if the user
+ // can create a template in any org.
+ AnyOrgOwner bool `json:"any_org"`
// Type is "workspace", "project", "app", etc
Type string `json:"type"`
@@ -115,6 +121,7 @@ func (z Object) All() Object {
Type: z.Type,
ACLUserList: map[string][]policy.Action{},
ACLGroupList: map[string][]policy.Action{},
+ AnyOrgOwner: z.AnyOrgOwner,
}
}
@@ -126,6 +133,7 @@ func (z Object) WithIDString(id string) Object {
Type: z.Type,
ACLUserList: z.ACLUserList,
ACLGroupList: z.ACLGroupList,
+ AnyOrgOwner: z.AnyOrgOwner,
}
}
@@ -137,6 +145,7 @@ func (z Object) WithID(id uuid.UUID) Object {
Type: z.Type,
ACLUserList: z.ACLUserList,
ACLGroupList: z.ACLGroupList,
+ AnyOrgOwner: z.AnyOrgOwner,
}
}
@@ -149,6 +158,21 @@ func (z Object) InOrg(orgID uuid.UUID) Object {
Type: z.Type,
ACLUserList: z.ACLUserList,
ACLGroupList: z.ACLGroupList,
+ // InOrg implies AnyOrgOwner is false
+ AnyOrgOwner: false,
+ }
+}
+
+func (z Object) AnyOrganization() Object {
+ return Object{
+ ID: z.ID,
+ Owner: z.Owner,
+ // AnyOrgOwner cannot have an org owner also set.
+ OrgID: "",
+ Type: z.Type,
+ ACLUserList: z.ACLUserList,
+ ACLGroupList: z.ACLGroupList,
+ AnyOrgOwner: true,
}
}
@@ -161,6 +185,7 @@ func (z Object) WithOwner(ownerID string) Object {
Type: z.Type,
ACLUserList: z.ACLUserList,
ACLGroupList: z.ACLGroupList,
+ AnyOrgOwner: z.AnyOrgOwner,
}
}
@@ -173,6 +198,7 @@ func (z Object) WithACLUserList(acl map[string][]policy.Action) Object {
Type: z.Type,
ACLUserList: acl,
ACLGroupList: z.ACLGroupList,
+ AnyOrgOwner: z.AnyOrgOwner,
}
}
@@ -184,5 +210,6 @@ func (z Object) WithGroupACL(groups map[string][]policy.Action) Object {
Type: z.Type,
ACLUserList: z.ACLUserList,
ACLGroupList: groups,
+ AnyOrgOwner: z.AnyOrgOwner,
}
}
diff --git a/coderd/rbac/object_gen.go b/coderd/rbac/object_gen.go
index 9ab848d795b1c..bc2846da49564 100644
--- a/coderd/rbac/object_gen.go
+++ b/coderd/rbac/object_gen.go
@@ -28,6 +28,7 @@ var (
// ResourceAssignOrgRole
// Valid Actions
// - "ActionAssign" :: ability to assign org scoped roles
+ // - "ActionCreate" :: ability to create/delete/edit custom roles within an organization
// - "ActionDelete" :: ability to delete org scoped roles
// - "ActionRead" :: view what roles are assignable
ResourceAssignOrgRole = Object{
@@ -160,6 +161,15 @@ var (
Type: "provisioner_daemon",
}
+ // ResourceProvisionerKeys
+ // Valid Actions
+ // - "ActionCreate" :: create a provisioner key
+ // - "ActionDelete" :: delete a provisioner key
+ // - "ActionRead" :: read provisioner keys
+ ResourceProvisionerKeys = Object{
+ Type: "provisioner_keys",
+ }
+
// ResourceReplicas
// Valid Actions
// - "ActionRead" :: read replicas
@@ -268,6 +278,7 @@ func AllResources() []Objecter {
ResourceOrganization,
ResourceOrganizationMember,
ResourceProvisionerDaemon,
+ ResourceProvisionerKeys,
ResourceReplicas,
ResourceSystem,
ResourceTailnetCoordinator,
diff --git a/coderd/rbac/policy.rego b/coderd/rbac/policy.rego
index a6f3e62b73453..bf7a38c3cc194 100644
--- a/coderd/rbac/policy.rego
+++ b/coderd/rbac/policy.rego
@@ -92,8 +92,18 @@ org := org_allow(input.subject.roles)
default scope_org := 0
scope_org := org_allow([input.scope])
-org_allow(roles) := num {
- allow := { id: num |
+# org_allow_set is a helper function that iterates over all orgs that the actor
+# is a member of. For each organization it sets the numerical allow value
+# for the given object + action if the object is in the organization.
+# The resulting value is a map that looks something like:
+# {"10d03e62-7703-4df5-a358-4f76577d4e2f": 1, "5750d635-82e0-4681-bd44-815b18669d65": 1}
+# The caller can use this output[
+ 
+
+
+
+
+ {{ end }} +
+ {{ .Labels._subject }}
+ {{ .Labels._body }} + + {{ range $action := .Actions }} + {{ $action.Label }}+ {{ end }} +
+
+ © 2024 Coder. All rights reserved.
+
+login, logout, register, create, delete |
| Field | Tracked |
|---|---|
| created_at | true |
| expires_at | true |
| hashed_secret | false |
| id | false |
| ip_address | false |
| last_used | true |
| lifetime_seconds | false |
| login_type | false |
| scope | false |
| token_name | false |
| updated_at | false |
| user_id | true |
|
| Field | Tracked |
|---|---|
| created_at | true |
| expires_at | true |
| from_login_type | true |
| to_login_type | true |
| user_id | true |
create, write, delete |
| Field | Tracked |
|---|---|
| avatar_url | true |
| display_name | true |
| id | true |
| members | true |
| name | true |
| organization_id | false |
| quota_allowance | true |
| source | false |
create |
| Field | Tracked |
|---|---|
| created_at | false |
| private_key | true |
| public_key | true |
| updated_at | false |
| user_id | true |
|
| Field | Tracked |
|---|---|
| dismissed_healthchecks | true |
| id | false |
create, delete |
| Field | Tracked |
|---|---|
| exp | true |
| id | false |
| jwt | false |
| uploaded_at | true |
| uuid | true |
|
| Field | Tracked |
|---|---|
| callback_url | true |
| created_at | false |
| icon | true |
| id | false |
| name | true |
| updated_at | false |
|
| Field | Tracked |
|---|---|
| app_id | false |
| created_at | false |
| display_secret | false |
| hashed_secret | false |
| id | false |
| last_used_at | false |
| secret_prefix | false |
write, delete |
| Field | Tracked |
|---|---|
| active_version_id | true |
| activity_bump | true |
| allow_user_autostart | true |
| allow_user_autostop | true |
| allow_user_cancel_workspace_jobs | true |
| autostart_block_days_of_week | true |
| autostop_requirement_days_of_week | true |
| autostop_requirement_weeks | true |
| created_at | false |
| created_by | true |
| created_by_avatar_url | false |
| created_by_username | false |
| default_ttl | true |
| deleted | false |
| deprecated | true |
| description | true |
| display_name | true |
| failure_ttl | true |
| group_acl | true |
| icon | true |
| id | true |
| max_port_sharing_level | true |
| name | true |
| organization_id | false |
| provisioner | true |
| require_active_version | true |
| time_til_dormant | true |
| time_til_dormant_autodelete | true |
| updated_at | false |
| user_acl | true |
create, write |
| Field | Tracked |
|---|---|
| archived | true |
| created_at | false |
| created_by | true |
| created_by_avatar_url | false |
| created_by_username | false |
| external_auth_providers | false |
| id | true |
| job_id | false |
| message | false |
| name | true |
| organization_id | false |
| readme | true |
| template_id | true |
| updated_at | false |
create, write, delete |
| Field | Tracked |
|---|---|
| avatar_url | false |
| created_at | false |
| deleted | true |
| true | |
| hashed_password | true |
| id | true |
| last_seen_at | false |
| login_type | true |
| name | true |
| quiet_hours_schedule | true |
| rbac_roles | true |
| status | true |
| theme_preference | false |
| updated_at | false |
| username | true |
create, write, delete |
| Field | Tracked |
|---|---|
| automatic_updates | true |
| autostart_schedule | true |
| created_at | false |
| deleted | false |
| deleting_at | true |
| dormant_at | true |
| favorite | true |
| id | true |
| last_used_at | false |
| name | true |
| organization_id | false |
| owner_id | true |
| template_id | true |
| ttl | true |
| updated_at | false |
start, stop |
| Field | Tracked |
|---|---|
| build_number | false |
| created_at | false |
| daily_cost | false |
| deadline | false |
| id | false |
| initiator_by_avatar_url | false |
| initiator_by_username | false |
| initiator_id | false |
| job_id | false |
| max_deadline | false |
| provisioner_state | false |
| reason | false |
| template_version_id | true |
| transition | false |
| updated_at | false |
| workspace_id | false |
|
| Field | Tracked |
|---|---|
| created_at | true |
| deleted | false |
| derp_enabled | true |
| derp_only | true |
| display_name | true |
| icon | true |
| id | true |
| name | true |
| region_id | true |
| token_hashed_secret | true |
| updated_at | false |
| url | true |
| version | true |
| wildcard_hostname | true |
login, logout, register, create, delete |
| Field | Tracked |
|---|---|
| created_at | true |
| expires_at | true |
| hashed_secret | false |
| id | false |
| ip_address | false |
| last_used | true |
| lifetime_seconds | false |
| login_type | false |
| scope | false |
| token_name | false |
| updated_at | false |
| user_id | true |
|
| Field | Tracked |
|---|---|
| created_at | true |
| expires_at | true |
| from_login_type | true |
| to_login_type | true |
| user_id | true |
create, write, delete |
| Field | Tracked |
|---|---|
| avatar_url | true |
| display_name | true |
| id | true |
| members | true |
| name | true |
| organization_id | false |
| quota_allowance | true |
| source | false |
|
| Field | Tracked |
|---|---|
| created_at | true |
| organization_id | false |
| roles | true |
| updated_at | true |
| user_id | true |
| username | true |
|
| Field | Tracked |
|---|---|
| created_at | false |
| display_name | true |
| id | false |
| name | true |
| org_permissions | true |
| organization_id | false |
| site_permissions | true |
| updated_at | false |
| user_permissions | true |
create |
| Field | Tracked |
|---|---|
| created_at | false |
| private_key | true |
| public_key | true |
| updated_at | false |
| user_id | true |
|
| Field | Tracked |
|---|---|
| dismissed_healthchecks | true |
| id | false |
create, delete |
| Field | Tracked |
|---|---|
| exp | true |
| id | false |
| jwt | false |
| uploaded_at | true |
| uuid | true |
|
| Field | Tracked |
|---|---|
| id | false |
| notifier_paused | true |
|
| Field | Tracked |
|---|---|
| callback_url | true |
| created_at | false |
| icon | true |
| id | false |
| name | true |
| updated_at | false |
|
| Field | Tracked |
|---|---|
| app_id | false |
| created_at | false |
| display_secret | false |
| hashed_secret | false |
| id | false |
| last_used_at | false |
| secret_prefix | false |
|
| Field | Tracked |
|---|---|
| created_at | false |
| description | true |
| display_name | true |
| icon | true |
| id | false |
| is_default | true |
| name | true |
| updated_at | true |
write, delete |
| Field | Tracked |
|---|---|
| active_version_id | true |
| activity_bump | true |
| allow_user_autostart | true |
| allow_user_autostop | true |
| allow_user_cancel_workspace_jobs | true |
| autostart_block_days_of_week | true |
| autostop_requirement_days_of_week | true |
| autostop_requirement_weeks | true |
| created_at | false |
| created_by | true |
| created_by_avatar_url | false |
| created_by_username | false |
| default_ttl | true |
| deleted | false |
| deprecated | true |
| description | true |
| display_name | true |
| failure_ttl | true |
| group_acl | true |
| icon | true |
| id | true |
| max_port_sharing_level | true |
| name | true |
| organization_display_name | false |
| organization_icon | false |
| organization_id | false |
| organization_name | false |
| provisioner | true |
| require_active_version | true |
| time_til_dormant | true |
| time_til_dormant_autodelete | true |
| updated_at | false |
| user_acl | true |
create, write |
| Field | Tracked |
|---|---|
| archived | true |
| created_at | false |
| created_by | true |
| created_by_avatar_url | false |
| created_by_username | false |
| external_auth_providers | false |
| id | true |
| job_id | false |
| message | false |
| name | true |
| organization_id | false |
| readme | true |
| template_id | true |
| updated_at | false |
create, write, delete |
| Field | Tracked |
|---|---|
| avatar_url | false |
| created_at | false |
| deleted | true |
| true | |
| github_com_user_id | false |
| hashed_password | true |
| id | true |
| last_seen_at | false |
| login_type | true |
| name | true |
| quiet_hours_schedule | true |
| rbac_roles | true |
| status | true |
| theme_preference | false |
| updated_at | false |
| username | true |
create, write, delete |
| Field | Tracked |
|---|---|
| automatic_updates | true |
| autostart_schedule | true |
| created_at | false |
| deleted | false |
| deleting_at | true |
| dormant_at | true |
| favorite | true |
| id | true |
| last_used_at | false |
| name | true |
| organization_id | false |
| owner_id | true |
| template_id | true |
| ttl | true |
| updated_at | false |
start, stop |
| Field | Tracked |
|---|---|
| build_number | false |
| created_at | false |
| daily_cost | false |
| deadline | false |
| id | false |
| initiator_by_avatar_url | false |
| initiator_by_username | false |
| initiator_id | false |
| job_id | false |
| max_deadline | false |
| provisioner_state | false |
| reason | false |
| template_version_id | true |
| transition | false |
| updated_at | false |
| workspace_id | false |
|
| Field | Tracked |
|---|---|
| created_at | true |
| deleted | false |
| derp_enabled | true |
| derp_only | true |
| display_name | true |
| icon | true |
| id | true |
| name | true |
| region_id | true |
| token_hashed_secret | true |
| updated_at | false |
| url | true |
| version | true |
| wildcard_hostname | true |
Response Schema
+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +| ------------------- | ----------------- | -------- | ------------ | ----------- | +| `[array item]` | array | false | | | +| `» created_at` | string(date-time) | false | | | +| `» id` | string(uuid) | false | | | +| `» name` | string | false | | | +| `» organization` | string(uuid) | false | | | +| `» tags` | object | false | | | +| `»» [any property]` | string | false | | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Create provisioner key + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/provisionerkeys \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /organizations/{organization}/provisionerkeys` + +### Parameters + +| Name | In | Type | Required | Description | +| -------------- | ---- | ------ | -------- | --------------- | +| `organization` | path | string | true | Organization ID | + +### Example responses + +> 201 Response + +```json +{ + "key": "string" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------- | +| 201 | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.CreateProvisionerKeyResponse](schemas.md#codersdkcreateprovisionerkeyresponse) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Delete provisioner key + +### Code samples + +```shell +# Example request using curl +curl -X DELETE http://coder-server:8080/api/v2/organizations/{organization}/provisionerkeys/{provisionerkey} \ + -H 'Coder-Session-Token: API_KEY' +``` + +`DELETE /organizations/{organization}/provisionerkeys/{provisionerkey}` + +### Parameters + +| Name | In | Type | Required | Description | +| ---------------- | ---- | ------ | -------- | -------------------- | +| `organization` | path | string | true | Organization ID | +| `provisionerkey` | path | string | true | Provisioner key name | + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | --------------------------------------------------------------- | ----------- | ------ | +| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + ## Get active replicas ### Code samples @@ -1600,11 +1733,13 @@ curl -X PATCH http://coder-server:8080/api/v2/scim/v2/Users/{id} \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -1655,11 +1790,13 @@ curl -X GET http://coder-server:8080/api/v2/templates/{template}/acl \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ] @@ -1690,8 +1827,10 @@ Status Code **200** | `» roles` | array | false | | | | `»» display_name` | string | false | | | | `»» name` | string | false | | | +| `»» organization_id` | string | false | | | | `» status` | [codersdk.UserStatus](schemas.md#codersdkuserstatus) | false | | | | `» theme_preference` | string | false | | | +| `» updated_at` | string(date-time) | false | | | | `» username` | string | true | | | #### Enumerated Values @@ -1814,6 +1953,7 @@ curl -X GET http://coder-server:8080/api/v2/templates/{template}/acl/available \ "name": "string", "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ], @@ -1834,6 +1974,7 @@ curl -X GET http://coder-server:8080/api/v2/templates/{template}/acl/available \ "name": "string", "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ] @@ -1868,6 +2009,7 @@ Status Code **200** | `»»» name` | string | false | | | | `»»» status` | [codersdk.UserStatus](schemas.md#codersdkuserstatus) | false | | | | `»»» theme_preference` | string | false | | | +| `»»» updated_at` | string(date-time) | false | | | | `»»» username` | string | true | | | | `»» name` | string | false | | | | `»» organization_id` | string(uuid) | false | | | diff --git a/docs/api/general.md b/docs/api/general.md index 52313409cb02c..e913a4c804cd6 100644 --- a/docs/api/general.md +++ b/docs/api/general.md @@ -57,6 +57,7 @@ curl -X GET http://coder-server:8080/api/v2/buildinfo \ "dashboard_url": "string", "deployment_id": "string", "external_url": "string", + "telemetry": true, "upgrade_message": "string", "version": "string", "workspace_proxy": true @@ -227,7 +228,6 @@ curl -X GET http://coder-server:8080/api/v2/deployment/config \ "device_flow": true, "display_icon": "string", "display_name": "string", - "extra_token_keys": ["string"], "id": "string", "no_refresh": true, "regex": "string", @@ -253,6 +253,55 @@ curl -X GET http://coder-server:8080/api/v2/deployment/config \ "stackdriver": "string" }, "metrics_cache_refresh_interval": 0, + "notifications": { + "dispatch_timeout": 0, + "email": { + "auth": { + "identity": "string", + "password": "string", + "password_file": "string", + "username": "string" + }, + "force_tls": true, + "from": "string", + "hello": "string", + "smarthost": { + "host": "string", + "port": "string" + }, + "tls": { + "ca_file": "string", + "cert_file": "string", + "insecure_skip_verify": true, + "key_file": "string", + "server_name": "string", + "start_tls": true + } + }, + "fetch_interval": 0, + "lease_count": 0, + "lease_period": 0, + "max_send_attempts": 0, + "method": "string", + "retry_interval": 0, + "sync_buffer_size": 0, + "sync_interval": 0, + "webhook": { + "endpoint": { + "forceQuery": true, + "fragment": "string", + "host": "string", + "omitHost": true, + "opaque": "string", + "path": "string", + "rawFragment": "string", + "rawPath": "string", + "rawQuery": "string", + "scheme": "string", + "user": {} + } + } + }, "oauth2": { "github": { "allow_everyone": true, @@ -294,9 +343,11 @@ curl -X GET http://coder-server:8080/api/v2/deployment/config \ "ignore_email_verified": true, "ignore_user_info": true, "issuer_url": "string", + "name_field": "string", "scopes": ["string"], "sign_in_text": "string", "signups_disabled_text": "string", + "skip_issuer_checks": true, "user_role_field": "string", "user_role_mapping": {}, "user_roles_default": ["string"], @@ -616,6 +667,84 @@ Status Code **200** To perform this operation, you must be authenticated. [Learn more](authentication.md). +## Get notifications settings + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/notifications/settings \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /notifications/settings` + +### Example responses + +> 200 Response + +```json +{ + "notifier_paused": true +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.NotificationsSettings](schemas.md#codersdknotificationssettings) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Update notifications settings + +### Code samples + +```shell +# Example request using curl +curl -X PUT http://coder-server:8080/api/v2/notifications/settings \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`PUT /notifications/settings` + +> Body parameter + +```json +{ + "notifier_paused": true +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +| ------ | ---- | -------------------------------------------------------------------------- | -------- | ------------------------------ | +| `body` | body | [codersdk.NotificationsSettings](schemas.md#codersdknotificationssettings) | true | Notifications settings request | + +### Example responses + +> 200 Response + +```json +{ + "notifier_paused": true +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | --------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.NotificationsSettings](schemas.md#codersdknotificationssettings) | +| 304 | [Not Modified](https://tools.ietf.org/html/rfc7232#section-4.1) | Not Modified | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + ## Update check ### Code samples diff --git a/docs/api/git.md b/docs/api/git.md index 71a0d2921f5fa..929ab3e868b8f 100644 --- a/docs/api/git.md +++ b/docs/api/git.md @@ -71,6 +71,7 @@ curl -X GET http://coder-server:8080/api/v2/external-auth/{externalauth} \ { "account": { "avatar_url": "string", + "id": 0, "login": "string", "name": "string", "profile_url": "string" @@ -81,6 +82,7 @@ curl -X GET http://coder-server:8080/api/v2/external-auth/{externalauth} \ ], "user": { "avatar_url": "string", + "id": 0, "login": "string", "name": "string", "profile_url": "string" diff --git a/docs/api/insights.md b/docs/api/insights.md index 7dae576b847b8..eb1a7679a6708 100644 --- a/docs/api/insights.md +++ b/docs/api/insights.md @@ -6,13 +6,19 @@ ```shell # Example request using curl -curl -X GET http://coder-server:8080/api/v2/insights/daus \ +curl -X GET http://coder-server:8080/api/v2/insights/daus?tz_offset=0 \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` `GET /insights/daus` +### Parameters + +| Name | In | Type | Required | Description | +| ----------- | ----- | ------- | -------- | -------------------------- | +| `tz_offset` | query | integer | true | Time-zone offset (e.g. -2) | + ### Example responses > 200 Response @@ -43,7 +49,7 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio ```shell # Example request using curl -curl -X GET http://coder-server:8080/api/v2/insights/templates?before=0&after=0 \ +curl -X GET http://coder-server:8080/api/v2/insights/templates?start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z&interval=week \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` @@ -52,10 +58,19 @@ curl -X GET http://coder-server:8080/api/v2/insights/templates?before=0&after=0 ### Parameters -| Name | In | Type | Required | Description | -| -------- | ----- | ------- | -------- | ----------- | -| `before` | query | integer | true | Start time | -| `after` | query | integer | true | End time | +| Name | In | Type | Required | Description | +| -------------- | ----- | ----------------- | -------- | ------------ | +| `start_time` | query | string(date-time) | true | Start time | +| `end_time` | query | string(date-time) | true | End time | +| `interval` | query | string | true | Interval | +| `template_ids` | query | array[string] | false | Template IDs | + +#### Enumerated Values + +| Parameter | Value | +| ---------- | ------ | +| `interval` | `week` | +| `interval` | `day` | ### Example responses @@ -129,7 +144,7 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio ```shell # Example request using curl -curl -X GET http://coder-server:8080/api/v2/insights/user-activity?before=0&after=0 \ +curl -X GET http://coder-server:8080/api/v2/insights/user-activity?start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` @@ -138,10 +153,11 @@ curl -X GET http://coder-server:8080/api/v2/insights/user-activity?before=0&afte ### Parameters -| Name | In | Type | Required | Description | -| -------- | ----- | ------- | -------- | ----------- | -| `before` | query | integer | true | Start time | -| `after` | query | integer | true | End time | +| Name | In | Type | Required | Description | +| -------------- | ----- | ----------------- | -------- | ------------ | +| `start_time` | query | string(date-time) | true | Start time | +| `end_time` | query | string(date-time) | true | End time | +| `template_ids` | query | array[string] | false | Template IDs | ### Example responses @@ -180,7 +196,7 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio ```shell # Example request using curl -curl -X GET http://coder-server:8080/api/v2/insights/user-latency?before=0&after=0 \ +curl -X GET http://coder-server:8080/api/v2/insights/user-latency?start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` @@ -189,10 +205,11 @@ curl -X GET http://coder-server:8080/api/v2/insights/user-latency?before=0&after ### Parameters -| Name | In | Type | Required | Description | -| -------- | ----- | ------- | -------- | ----------- | -| `before` | query | integer | true | Start time | -| `after` | query | integer | true | End time | +| Name | In | Type | Required | Description | +| -------------- | ----- | ----------------- | -------- | ------------ | +| `start_time` | query | string(date-time) | true | Start time | +| `end_time` | query | string(date-time) | true | End time | +| `template_ids` | query | array[string] | false | Template IDs | ### Example responses diff --git a/docs/api/members.md b/docs/api/members.md index 6364b08ca528e..1ecf490738f00 100644 --- a/docs/api/members.md +++ b/docs/api/members.md @@ -1,5 +1,86 @@ # Members +## List organization members + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/members \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /organizations/{organization}/members` + +### Parameters + +| Name | In | Type | Required | Description | +| -------------- | ---- | ------ | -------- | --------------- | +| `organization` | path | string | true | Organization ID | + +### Example responses + +> 200 Response + +```json +[ + { + "avatar_url": "string", + "created_at": "2019-08-24T14:15:22Z", + "email": "string", + "global_roles": [ + { + "display_name": "string", + "name": "string", + "organization_id": "string" + } + ], + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "roles": [ + { + "display_name": "string", + "name": "string", + "organization_id": "string" + } + ], + "updated_at": "2019-08-24T14:15:22Z", + "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5", + "username": "string" + } +] +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.OrganizationMemberWithUserData](schemas.md#codersdkorganizationmemberwithuserdata) | + +Response Schema
+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +| -------------------- | ----------------- | -------- | ------------ | ----------- | +| `[array item]` | array | false | | | +| `» avatar_url` | string | false | | | +| `» created_at` | string(date-time) | false | | | +| `» email` | string | false | | | +| `» global_roles` | array | false | | | +| `»» display_name` | string | false | | | +| `»» name` | string | false | | | +| `»» organization_id` | string | false | | | +| `» name` | string | false | | | +| `» organization_id` | string(uuid) | false | | | +| `» roles` | array | false | | | +| `» updated_at` | string(date-time) | false | | | +| `» user_id` | string(uuid) | false | | | +| `» username` | string | false | | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + ## Get member roles by organization ### Code samples @@ -115,6 +196,7 @@ Status Code **200** | `resource_type` | `organization` | | `resource_type` | `organization_member` | | `resource_type` | `provisioner_daemon` | +| `resource_type` | `provisioner_keys` | | `resource_type` | `replicas` | | `resource_type` | `system` | | `resource_type` | `tailnet_coordinator` | @@ -237,6 +319,7 @@ Status Code **200** | `resource_type` | `organization` | | `resource_type` | `organization_member` | | `resource_type` | `provisioner_daemon` | +| `resource_type` | `provisioner_keys` | | `resource_type` | `replicas` | | `resource_type` | `system` | | `resource_type` | `tailnet_coordinator` | @@ -248,6 +331,81 @@ Status Code **200** To perform this operation, you must be authenticated. [Learn more](authentication.md). +## Add organization member + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/members/{user} \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /organizations/{organization}/members/{user}` + +### Parameters + +| Name | In | Type | Required | Description | +| -------------- | ---- | ------ | -------- | -------------------- | +| `organization` | path | string | true | Organization ID | +| `user` | path | string | true | User ID, name, or me | + +### Example responses + +> 200 Response + +```json +{ + "created_at": "2019-08-24T14:15:22Z", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "roles": [ + { + "display_name": "string", + "name": "string", + "organization_id": "string" + } + ], + "updated_at": "2019-08-24T14:15:22Z", + "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.OrganizationMember](schemas.md#codersdkorganizationmember) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Remove organization member + +### Code samples + +```shell +# Example request using curl +curl -X DELETE http://coder-server:8080/api/v2/organizations/{organization}/members/{user} \ + -H 'Coder-Session-Token: API_KEY' +``` + +`DELETE /organizations/{organization}/members/{user}` + +### Parameters + +| Name | In | Type | Required | Description | +| -------------- | ---- | ------ | -------- | -------------------- | +| `organization` | path | string | true | Organization ID | +| `user` | path | string | true | User ID, name, or me | + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | --------------------------------------------------------------- | ----------- | ------ | +| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + ## Assign role to organization member ### Code samples @@ -289,7 +447,8 @@ curl -X PUT http://coder-server:8080/api/v2/organizations/{organization}/members "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "updated_at": "2019-08-24T14:15:22Z", @@ -414,6 +573,7 @@ Status Code **200** | `resource_type` | `organization` | | `resource_type` | `organization_member` | | `resource_type` | `provisioner_daemon` | +| `resource_type` | `provisioner_keys` | | `resource_type` | `replicas` | | `resource_type` | `system` | | `resource_type` | `tailnet_coordinator` | diff --git a/docs/api/organizations.md b/docs/api/organizations.md index c6f4514eb9bad..4c4f49bb9d9d6 100644 --- a/docs/api/organizations.md +++ b/docs/api/organizations.md @@ -87,6 +87,62 @@ curl -X POST http://coder-server:8080/api/v2/licenses/refresh-entitlements \ To perform this operation, you must be authenticated. [Learn more](authentication.md). +## Get organizations + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/organizations \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /organizations` + +### Example responses + +> 200 Response + +```json +[ + { + "created_at": "2019-08-24T14:15:22Z", + "description": "string", + "display_name": "string", + "icon": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "is_default": true, + "name": "string", + "updated_at": "2019-08-24T14:15:22Z" + } +] +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Organization](schemas.md#codersdkorganization) | + +Response Schema
+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +| ---------------- | ----------------- | -------- | ------------ | ----------- | +| `[array item]` | array | false | | | +| `» created_at` | string(date-time) | true | | | +| `» description` | string | false | | | +| `» display_name` | string | false | | | +| `» icon` | string | false | | | +| `» id` | string(uuid) | true | | | +| `» is_default` | boolean | true | | | +| `» name` | string | false | | | +| `» updated_at` | string(date-time) | true | | | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + ## Create organization ### Code samples @@ -105,6 +161,9 @@ curl -X POST http://coder-server:8080/api/v2/organizations \ ```json { + "description": "string", + "display_name": "string", + "icon": "string", "name": "string" } ``` @@ -122,6 +181,9 @@ curl -X POST http://coder-server:8080/api/v2/organizations \ ```json { "created_at": "2019-08-24T14:15:22Z", + "description": "string", + "display_name": "string", + "icon": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "is_default": true, "name": "string", @@ -163,6 +225,9 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization} \ ```json { "created_at": "2019-08-24T14:15:22Z", + "description": "string", + "display_name": "string", + "icon": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "is_default": true, "name": "string", @@ -240,6 +305,9 @@ curl -X PATCH http://coder-server:8080/api/v2/organizations/{organization} \ ```json { + "description": "string", + "display_name": "string", + "icon": "string", "name": "string" } ``` @@ -258,6 +326,9 @@ curl -X PATCH http://coder-server:8080/api/v2/organizations/{organization} \ ```json { "created_at": "2019-08-24T14:15:22Z", + "description": "string", + "display_name": "string", + "icon": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "is_default": true, "name": "string", diff --git a/docs/api/schemas.md b/docs/api/schemas.md index 82804508b0e96..53ad820daf60c 100644 --- a/docs/api/schemas.md +++ b/docs/api/schemas.md @@ -16,69 +16,6 @@ | `document` | string | true | | | | `signature` | string | true | | | -## agentsdk.AgentMetric - -```json -{ - "labels": [ - { - "name": "string", - "value": "string" - } - ], - "name": "string", - "type": "counter", - "value": 0 -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| -------- | --------------------------------------------------------------- | -------- | ------------ | ----------- | -| `labels` | array of [agentsdk.AgentMetricLabel](#agentsdkagentmetriclabel) | false | | | -| `name` | string | true | | | -| `type` | [agentsdk.AgentMetricType](#agentsdkagentmetrictype) | true | | | -| `value` | number | true | | | - -#### Enumerated Values - -| Property | Value | -| -------- | --------- | -| `type` | `counter` | -| `type` | `gauge` | - -## agentsdk.AgentMetricLabel - -```json -{ - "name": "string", - "value": "string" -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| ------- | ------ | -------- | ------------ | ----------- | -| `name` | string | true | | | -| `value` | string | true | | | - -## agentsdk.AgentMetricType - -```json -"counter" -``` - -### Properties - -#### Enumerated Values - -| Value | -| --------- | -| `counter` | -| `gauge` | - ## agentsdk.AuthenticateResponse ```json @@ -181,172 +118,6 @@ | `level` | [codersdk.LogLevel](#codersdkloglevel) | false | | | | `output` | string | false | | | -## agentsdk.Manifest - -```json -{ - "agent_id": "string", - "agent_name": "string", - "apps": [ - { - "command": "string", - "display_name": "string", - "external": true, - "health": "disabled", - "healthcheck": { - "interval": 0, - "threshold": 0, - "url": "string" - }, - "icon": "string", - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", - "sharing_level": "owner", - "slug": "string", - "subdomain": true, - "subdomain_name": "string", - "url": "string" - } - ], - "derp_force_websockets": true, - "derpmap": { - "homeParams": { - "regionScore": { - "property1": 0, - "property2": 0 - } - }, - "omitDefaultRegions": true, - "regions": { - "property1": { - "avoid": true, - "embeddedRelay": true, - "nodes": [ - { - "canPort80": true, - "certName": "string", - "derpport": 0, - "forceHTTP": true, - "hostName": "string", - "insecureForTests": true, - "ipv4": "string", - "ipv6": "string", - "name": "string", - "regionID": 0, - "stunonly": true, - "stunport": 0, - "stuntestIP": "string" - } - ], - "regionCode": "string", - "regionID": 0, - "regionName": "string" - }, - "property2": { - "avoid": true, - "embeddedRelay": true, - "nodes": [ - { - "canPort80": true, - "certName": "string", - "derpport": 0, - "forceHTTP": true, - "hostName": "string", - "insecureForTests": true, - "ipv4": "string", - "ipv6": "string", - "name": "string", - "regionID": 0, - "stunonly": true, - "stunport": 0, - "stuntestIP": "string" - } - ], - "regionCode": "string", - "regionID": 0, - "regionName": "string" - } - } - }, - "directory": "string", - "disable_direct_connections": true, - "environment_variables": { - "property1": "string", - "property2": "string" - }, - "git_auth_configs": 0, - "metadata": [ - { - "display_name": "string", - "interval": 0, - "key": "string", - "script": "string", - "timeout": 0 - } - ], - "motd_file": "string", - "owner_name": "string", - "scripts": [ - { - "cron": "string", - "log_path": "string", - "log_source_id": "4197ab25-95cf-4b91-9c78-f7f2af5d353a", - "run_on_start": true, - "run_on_stop": true, - "script": "string", - "start_blocks_login": true, - "timeout": 0 - } - ], - "vscode_port_proxy_uri": "string", - "workspace_id": "string", - "workspace_name": "string" -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| ---------------------------- | ------------------------------------------------------------------------------------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `agent_id` | string | false | | | -| `agent_name` | string | false | | | -| `apps` | array of [codersdk.WorkspaceApp](#codersdkworkspaceapp) | false | | | -| `derp_force_websockets` | boolean | false | | | -| `derpmap` | [tailcfg.DERPMap](#tailcfgderpmap) | false | | | -| `directory` | string | false | | | -| `disable_direct_connections` | boolean | false | | | -| `environment_variables` | object | false | | | -| » `[any property]` | string | false | | | -| `git_auth_configs` | integer | false | | Git auth configs stores the number of Git configurations the Coder deployment has. If this number is >0, we set up special configuration in the workspace. | -| `metadata` | array of [codersdk.WorkspaceAgentMetadataDescription](#codersdkworkspaceagentmetadatadescription) | false | | | -| `motd_file` | string | false | | | -| `owner_name` | string | false | | Owner name and WorkspaceID are used by an open-source user to identify the workspace. We do not provide insurance that this will not be removed in the future, but if it's easy to persist lets keep it around. | -| `scripts` | array of [codersdk.WorkspaceAgentScript](#codersdkworkspaceagentscript) | false | | | -| `vscode_port_proxy_uri` | string | false | | | -| `workspace_id` | string | false | | | -| `workspace_name` | string | false | | | - -## agentsdk.Metadata - -```json -{ - "age": 0, - "collected_at": "2019-08-24T14:15:22Z", - "error": "string", - "key": "string", - "value": "string" -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| -------------- | ------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | -| `age` | integer | false | | Age is the number of seconds since the metadata was collected. It is provided in addition to CollectedAt to protect against clock skew. | -| `collected_at` | string | false | | | -| `error` | string | false | | | -| `key` | string | false | | | -| `value` | string | false | | | - ## agentsdk.PatchLogs ```json @@ -369,165 +140,23 @@ | `log_source_id` | string | false | | | | `logs` | array of [agentsdk.Log](#agentsdklog) | false | | | -## agentsdk.PostAppHealthsRequest - -```json -{ - "healths": { - "property1": "disabled", - "property2": "disabled" - } -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| ------------------ | ---------------------------------------------------------- | -------- | ------------ | --------------------------------------------------------------------- | -| `healths` | object | false | | Healths is a map of the workspace app name and the health of the app. | -| » `[any property]` | [codersdk.WorkspaceAppHealth](#codersdkworkspaceapphealth) | false | | | - -## agentsdk.PostLifecycleRequest - -```json -{ - "changed_at": "string", - "state": "created" -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| ------------ | -------------------------------------------------------------------- | -------- | ------------ | ----------- | -| `changed_at` | string | false | | | -| `state` | [codersdk.WorkspaceAgentLifecycle](#codersdkworkspaceagentlifecycle) | false | | | - -## agentsdk.PostMetadataRequest - -```json -{ - "metadata": [ - { - "age": 0, - "collected_at": "2019-08-24T14:15:22Z", - "error": "string", - "key": "string", - "value": "string" - } - ] -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| ---------- | ----------------------------------------------- | -------- | ------------ | ----------- | -| `metadata` | array of [agentsdk.Metadata](#agentsdkmetadata) | false | | | - -## agentsdk.PostMetadataRequestDeprecated - -```json -{ - "age": 0, - "collected_at": "2019-08-24T14:15:22Z", - "error": "string", - "value": "string" -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| -------------- | ------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | -| `age` | integer | false | | Age is the number of seconds since the metadata was collected. It is provided in addition to CollectedAt to protect against clock skew. | -| `collected_at` | string | false | | | -| `error` | string | false | | | -| `value` | string | false | | | - -## agentsdk.PostStartupRequest - -```json -{ - "expanded_directory": "string", - "subsystems": ["envbox"], - "version": "string" -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| -------------------- | ----------------------------------------------------------- | -------- | ------------ | ----------- | -| `expanded_directory` | string | false | | | -| `subsystems` | array of [codersdk.AgentSubsystem](#codersdkagentsubsystem) | false | | | -| `version` | string | false | | | - -## agentsdk.Stats - -```json -{ - "connection_count": 0, - "connection_median_latency_ms": 0, - "connections_by_proto": { - "property1": 0, - "property2": 0 - }, - "metrics": [ - { - "labels": [ - { - "name": "string", - "value": "string" - } - ], - "name": "string", - "type": "counter", - "value": 0 - } - ], - "rx_bytes": 0, - "rx_packets": 0, - "session_count_jetbrains": 0, - "session_count_reconnecting_pty": 0, - "session_count_ssh": 0, - "session_count_vscode": 0, - "tx_bytes": 0, - "tx_packets": 0 -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| -------------------------------- | ----------------------------------------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | -| `connection_count` | integer | false | | Connection count is the number of connections received by an agent. | -| `connection_median_latency_ms` | number | false | | Connection median latency ms is the median latency of all connections in milliseconds. | -| `connections_by_proto` | object | false | | Connections by proto is a count of connections by protocol. | -| » `[any property]` | integer | false | | | -| `metrics` | array of [agentsdk.AgentMetric](#agentsdkagentmetric) | false | | Metrics collected by the agent | -| `rx_bytes` | integer | false | | Rx bytes is the number of received bytes. | -| `rx_packets` | integer | false | | Rx packets is the number of received packets. | -| `session_count_jetbrains` | integer | false | | Session count jetbrains is the number of connections received by an agent that are from our JetBrains extension. | -| `session_count_reconnecting_pty` | integer | false | | Session count reconnecting pty is the number of connections received by an agent that are from the reconnecting web terminal. | -| `session_count_ssh` | integer | false | | Session count ssh is the number of connections received by an agent that are normal, non-tagged SSH sessions. | -| `session_count_vscode` | integer | false | | Session count vscode is the number of connections received by an agent that are from our VS Code extension. | -| `tx_bytes` | integer | false | | Tx bytes is the number of transmitted bytes. | -| `tx_packets` | integer | false | | Tx packets is the number of transmitted bytes. | - -## agentsdk.StatsResponse +## agentsdk.PostLogSourceRequest ```json { - "report_interval": 0 + "display_name": "string", + "icon": "string", + "id": "string" } ``` ### Properties -| Name | Type | Required | Restrictions | Description | -| ----------------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------ | -| `report_interval` | integer | false | | Report interval is the duration after which the agent should send stats again. | +| Name | Type | Required | Restrictions | Description | +| -------------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `display_name` | string | false | | | +| `icon` | string | false | | | +| `id` | string | false | | ID is a unique identifier for the log source. It is scoped to a workspace agent, and can be statically defined inside code to prevent duplicate sources from being created for the same agent. | ## coderd.SCIMUser @@ -610,6 +239,7 @@ "name": "string", "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ], @@ -630,6 +260,7 @@ "name": "string", "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ] @@ -927,6 +558,12 @@ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "ip": "string", "is_deleted": true, + "organization": { + "display_name": "string", + "icon": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "name": "string" + }, "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "request_id": "266ea41d-adf5-480b-af50-15b940c2b846", "resource_icon": "string", @@ -948,11 +585,13 @@ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" }, "user_agent": "string" @@ -961,26 +600,27 @@ ### Properties -| Name | Type | Required | Restrictions | Description | -| ------------------- | ---------------------------------------------- | -------- | ------------ | -------------------------------------------- | -| `action` | [codersdk.AuditAction](#codersdkauditaction) | false | | | -| `additional_fields` | array of integer | false | | | -| `description` | string | false | | | -| `diff` | [codersdk.AuditDiff](#codersdkauditdiff) | false | | | -| `id` | string | false | | | -| `ip` | string | false | | | -| `is_deleted` | boolean | false | | | -| `organization_id` | string | false | | | -| `request_id` | string | false | | | -| `resource_icon` | string | false | | | -| `resource_id` | string | false | | | -| `resource_link` | string | false | | | -| `resource_target` | string | false | | Resource target is the name of the resource. | -| `resource_type` | [codersdk.ResourceType](#codersdkresourcetype) | false | | | -| `status_code` | integer | false | | | -| `time` | string | false | | | -| `user` | [codersdk.User](#codersdkuser) | false | | | -| `user_agent` | string | false | | | +| Name | Type | Required | Restrictions | Description | +| ------------------- | ------------------------------------------------------------ | -------- | ------------ | -------------------------------------------- | +| `action` | [codersdk.AuditAction](#codersdkauditaction) | false | | | +| `additional_fields` | array of integer | false | | | +| `description` | string | false | | | +| `diff` | [codersdk.AuditDiff](#codersdkauditdiff) | false | | | +| `id` | string | false | | | +| `ip` | string | false | | | +| `is_deleted` | boolean | false | | | +| `organization` | [codersdk.MinimalOrganization](#codersdkminimalorganization) | false | | | +| `organization_id` | string | false | | Deprecated: Use 'organization.id' instead. | +| `request_id` | string | false | | | +| `resource_icon` | string | false | | | +| `resource_id` | string | false | | | +| `resource_link` | string | false | | | +| `resource_target` | string | false | | Resource target is the name of the resource. | +| `resource_type` | [codersdk.ResourceType](#codersdkresourcetype) | false | | | +| `status_code` | integer | false | | | +| `time` | string | false | | | +| `user` | [codersdk.User](#codersdkuser) | false | | | +| `user_agent` | string | false | | | ## codersdk.AuditLogResponse @@ -1006,6 +646,12 @@ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "ip": "string", "is_deleted": true, + "organization": { + "display_name": "string", + "icon": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "name": "string" + }, "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "request_id": "266ea41d-adf5-480b-af50-15b940c2b846", "resource_icon": "string", @@ -1027,11 +673,13 @@ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" }, "user_agent": "string" @@ -1096,6 +744,7 @@ { "action": "create", "object": { + "any_org": true, "organization_id": "string", "owner_id": "string", "resource_id": "string", @@ -1126,6 +775,7 @@ AuthorizationCheck is used to check if the currently authenticated user (or the ```json { + "any_org": true, "organization_id": "string", "owner_id": "string", "resource_id": "string", @@ -1139,6 +789,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | Name | Type | Required | Restrictions | Description | | ----------------- | ---------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `any_org` | boolean | false | | Any org (optional) will disregard the org_owner when checking for permissions. This cannot be set to true if the OrganizationID is set. | | `organization_id` | string | false | | Organization ID (optional) adds the set constraint to all resources owned by a given organization. | | `owner_id` | string | false | | Owner ID (optional) adds the set constraint to all resources owned by a given user. | | `resource_id` | string | false | | Resource ID (optional) reduces the set to a singular resource. This assigns a resource ID to the resource type, eg: a single workspace. The rbac library will not fetch the resource from the database, so if you are using this option, you should also set the owner ID and organization ID if possible. Be as specific as possible using all the fields relevant. | @@ -1152,6 +803,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in "property1": { "action": "create", "object": { + "any_org": true, "organization_id": "string", "owner_id": "string", "resource_id": "string", @@ -1161,6 +813,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in "property2": { "action": "create", "object": { + "any_org": true, "organization_id": "string", "owner_id": "string", "resource_id": "string", @@ -1234,6 +887,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in "dashboard_url": "string", "deployment_id": "string", "external_url": "string", + "telemetry": true, "upgrade_message": "string", "version": "string", "workspace_proxy": true @@ -1248,6 +902,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | `dashboard_url` | string | false | | Dashboard URL is the URL to hit the deployment's dashboard. For external workspace proxies, this is the coderd they are connected to. | | `deployment_id` | string | false | | Deployment ID is the unique identifier for this deployment. | | `external_url` | string | false | | External URL references the current Coder version. For production builds, this will link directly to a release. For development builds, this will link to a commit. | +| `telemetry` | boolean | false | | Telemetry is a boolean that indicates whether telemetry is enabled. | | `upgrade_message` | string | false | | Upgrade message is the message displayed to users when an outdated client is detected. | | `version` | string | false | | Version returns the semantic version of the build. | | `workspace_proxy` | boolean | false | | | @@ -1305,6 +960,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in ```json { "email": "string", + "name": "string", "password": "string", "trial": true, "trial_info": { @@ -1325,6 +981,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | Name | Type | Required | Restrictions | Description | | ------------ | ---------------------------------------------------------------------- | -------- | ------------ | ----------- | | `email` | string | true | | | +| `name` | string | false | | | | `password` | string | true | | | | `trial` | boolean | false | | | | `trial_info` | [codersdk.CreateFirstUserTrialInfo](#codersdkcreatefirstusertrialinfo) | false | | | @@ -1389,22 +1046,42 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | ----------------- | ------- | -------- | ------------ | ----------- | | `avatar_url` | string | false | | | | `display_name` | string | false | | | -| `name` | string | false | | | +| `name` | string | true | | | | `quota_allowance` | integer | false | | | ## codersdk.CreateOrganizationRequest ```json { + "description": "string", + "display_name": "string", + "icon": "string", "name": "string" } ``` ### Properties -| Name | Type | Required | Restrictions | Description | -| ------ | ------ | -------- | ------------ | ----------- | -| `name` | string | true | | | +| Name | Type | Required | Restrictions | Description | +| -------------- | ------ | -------- | ------------ | ---------------------------------------------------------------------- | +| `description` | string | false | | | +| `display_name` | string | false | | Display name will default to the same value as `Name` if not provided. | +| `icon` | string | false | | | +| `name` | string | true | | | + +## codersdk.CreateProvisionerKeyResponse + +```json +{ + "key": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ----- | ------ | -------- | ------------ | ----------- | +| `key` | string | false | | | ## codersdk.CreateTemplateRequest @@ -1540,6 +1217,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in "action": "create", "additional_fields": [0], "build_reason": "autostart", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", "resource_type": "template", "time": "2019-08-24T14:15:22Z" @@ -1553,6 +1231,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | `action` | [codersdk.AuditAction](#codersdkauditaction) | false | | | | `additional_fields` | array of integer | false | | | | `build_reason` | [codersdk.BuildReason](#codersdkbuildreason) | false | | | +| `organization_id` | string | false | | | | `resource_id` | string | false | | | | `resource_type` | [codersdk.ResourceType](#codersdkresourcetype) | false | | | | `time` | string | false | | | @@ -1609,6 +1288,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in "disable_login": true, "email": "user@example.com", "login_type": "", + "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "password": "string", "username": "string" @@ -1622,6 +1302,7 @@ AuthorizationObject can represent a "set" of objects, such as: all workspaces in | `disable_login` | boolean | false | | Disable login sets the user's login type to 'none'. This prevents the user from being able to use a password or any other authentication method to login. Deprecated: Set UserLoginType=LoginTypeDisabled instead. | | `email` | string | true | | | | `login_type` | [codersdk.LoginType](#codersdklogintype) | false | | Login type defaults to LoginTypePassword. | +| `name` | string | false | | | | `organization_id` | string | false | | | | `password` | string | false | | | | `username` | string | true | | | @@ -2009,7 +1690,6 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "device_flow": true, "display_icon": "string", "display_name": "string", - "extra_token_keys": ["string"], "id": "string", "no_refresh": true, "regex": "string", @@ -2035,6 +1715,55 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "stackdriver": "string" }, "metrics_cache_refresh_interval": 0, + "notifications": { + "dispatch_timeout": 0, + "email": { + "auth": { + "identity": "string", + "password": "string", + "password_file": "string", + "username": "string" + }, + "force_tls": true, + "from": "string", + "hello": "string", + "smarthost": { + "host": "string", + "port": "string" + }, + "tls": { + "ca_file": "string", + "cert_file": "string", + "insecure_skip_verify": true, + "key_file": "string", + "server_name": "string", + "start_tls": true + } + }, + "fetch_interval": 0, + "lease_count": 0, + "lease_period": 0, + "max_send_attempts": 0, + "method": "string", + "retry_interval": 0, + "sync_buffer_size": 0, + "sync_interval": 0, + "webhook": { + "endpoint": { + "forceQuery": true, + "fragment": "string", + "host": "string", + "omitHost": true, + "opaque": "string", + "path": "string", + "rawFragment": "string", + "rawPath": "string", + "rawQuery": "string", + "scheme": "string", + "user": {} + } + } + }, "oauth2": { "github": { "allow_everyone": true, @@ -2076,9 +1805,11 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "ignore_email_verified": true, "ignore_user_info": true, "issuer_url": "string", + "name_field": "string", "scopes": ["string"], "sign_in_text": "string", "signups_disabled_text": "string", + "skip_issuer_checks": true, "user_role_field": "string", "user_role_mapping": {}, "user_roles_default": ["string"], @@ -2382,7 +2113,6 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "device_flow": true, "display_icon": "string", "display_name": "string", - "extra_token_keys": ["string"], "id": "string", "no_refresh": true, "regex": "string", @@ -2407,7 +2137,56 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "log_filter": ["string"], "stackdriver": "string" }, - "metrics_cache_refresh_interval": 0, + "metrics_cache_refresh_interval": 0, + "notifications": { + "dispatch_timeout": 0, + "email": { + "auth": { + "identity": "string", + "password": "string", + "password_file": "string", + "username": "string" + }, + "force_tls": true, + "from": "string", + "hello": "string", + "smarthost": { + "host": "string", + "port": "string" + }, + "tls": { + "ca_file": "string", + "cert_file": "string", + "insecure_skip_verify": true, + "key_file": "string", + "server_name": "string", + "start_tls": true + } + }, + "fetch_interval": 0, + "lease_count": 0, + "lease_period": 0, + "max_send_attempts": 0, + "method": "string", + "retry_interval": 0, + "sync_buffer_size": 0, + "sync_interval": 0, + "webhook": { + "endpoint": { + "forceQuery": true, + "fragment": "string", + "host": "string", + "omitHost": true, + "opaque": "string", + "path": "string", + "rawFragment": "string", + "rawPath": "string", + "rawQuery": "string", + "scheme": "string", + "user": {} + } + } + }, "oauth2": { "github": { "allow_everyone": true, @@ -2449,9 +2228,11 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "ignore_email_verified": true, "ignore_user_info": true, "issuer_url": "string", + "name_field": "string", "scopes": ["string"], "sign_in_text": "string", "signups_disabled_text": "string", + "skip_issuer_checks": true, "user_role_field": "string", "user_role_mapping": {}, "user_roles_default": ["string"], @@ -2601,6 +2382,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `job_hang_detector_interval` | integer | false | | | | `logging` | [codersdk.LoggingConfig](#codersdkloggingconfig) | false | | | | `metrics_cache_refresh_interval` | integer | false | | | +| `notifications` | [codersdk.NotificationsConfig](#codersdknotificationsconfig) | false | | | | `oauth2` | [codersdk.OAuth2Config](#codersdkoauth2config) | false | | | | `oidc` | [codersdk.OIDCConfig](#codersdkoidcconfig) | false | | | | `pg_auth` | string | false | | | @@ -2723,6 +2505,8 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `auto-fill-parameters` | | `multi-organization` | | `custom-roles` | +| `notifications` | +| `workspace-usage` | ## codersdk.ExternalAuth @@ -2737,6 +2521,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o { "account": { "avatar_url": "string", + "id": 0, "login": "string", "name": "string", "profile_url": "string" @@ -2747,6 +2532,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o ], "user": { "avatar_url": "string", + "id": 0, "login": "string", "name": "string", "profile_url": "string" @@ -2772,6 +2558,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o { "account": { "avatar_url": "string", + "id": 0, "login": "string", "name": "string", "profile_url": "string" @@ -2801,7 +2588,6 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "device_flow": true, "display_icon": "string", "display_name": "string", - "extra_token_keys": ["string"], "id": "string", "no_refresh": true, "regex": "string", @@ -2824,7 +2610,6 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `device_flow` | boolean | false | | | | `display_icon` | string | false | | Display icon is a URL to an icon to display in the UI. | | `display_name` | string | false | | Display name is shown in the UI to identify the auth config. | -| `extra_token_keys` | array of string | false | | | | `id` | string | false | | ID is a unique identifier for the auth config. It defaults to `type` when not provided. | | `no_refresh` | boolean | false | | | | `regex` | string | false | | Regex allows API requesters to match an auth config by a string (e.g. coder.com) instead of by it's type. | @@ -2887,6 +2672,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o ```json { "avatar_url": "string", + "id": 0, "login": "string", "name": "string", "profile_url": "string" @@ -2895,12 +2681,13 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o ### Properties -| Name | Type | Required | Restrictions | Description | -| ------------- | ------ | -------- | ------------ | ----------- | -| `avatar_url` | string | false | | | -| `login` | string | false | | | -| `name` | string | false | | | -| `profile_url` | string | false | | | +| Name | Type | Required | Restrictions | Description | +| ------------- | ------- | -------- | ------------ | ----------- | +| `avatar_url` | string | false | | | +| `id` | integer | false | | | +| `login` | string | false | | | +| `name` | string | false | | | +| `profile_url` | string | false | | | ## codersdk.Feature @@ -2954,11 +2741,13 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ] @@ -3010,6 +2799,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "name": "string", "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ], @@ -3313,6 +3103,26 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | --------------- | ------ | -------- | ------------ | ----------- | | `session_token` | string | true | | | +## codersdk.MinimalOrganization + +```json +{ + "display_name": "string", + "icon": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "name": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| -------------- | ------ | -------- | ------------ | ----------- | +| `display_name` | string | false | | | +| `icon` | string | false | | | +| `id` | string | true | | | +| `name` | string | false | | | + ## codersdk.MinimalUser ```json @@ -3331,6 +3141,199 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `id` | string | true | | | | `username` | string | true | | | +## codersdk.NotificationsConfig + +```json +{ + "dispatch_timeout": 0, + "email": { + "auth": { + "identity": "string", + "password": "string", + "password_file": "string", + "username": "string" + }, + "force_tls": true, + "from": "string", + "hello": "string", + "smarthost": { + "host": "string", + "port": "string" + }, + "tls": { + "ca_file": "string", + "cert_file": "string", + "insecure_skip_verify": true, + "key_file": "string", + "server_name": "string", + "start_tls": true + } + }, + "fetch_interval": 0, + "lease_count": 0, + "lease_period": 0, + "max_send_attempts": 0, + "method": "string", + "retry_interval": 0, + "sync_buffer_size": 0, + "sync_interval": 0, + "webhook": { + "endpoint": { + "forceQuery": true, + "fragment": "string", + "host": "string", + "omitHost": true, + "opaque": "string", + "path": "string", + "rawFragment": "string", + "rawPath": "string", + "rawQuery": "string", + "scheme": "string", + "user": {} + } + } +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------------- | -------------------------------------------------------------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dispatch_timeout` | integer | false | | How long to wait while a notification is being sent before giving up. | +| `email` | [codersdk.NotificationsEmailConfig](#codersdknotificationsemailconfig) | false | | Email settings. | +| `fetch_interval` | integer | false | | How often to query the database for queued notifications. | +| `lease_count` | integer | false | | How many notifications a notifier should lease per fetch interval. | +| `lease_period` | integer | false | | How long a notifier should lease a message. This is effectively how long a notification is 'owned' by a notifier, and once this period expires it will be available for lease by another notifier. Leasing is important in order for multiple running notifiers to not pick the same messages to deliver concurrently. This lease period will only expire if a notifier shuts down ungracefully; a dispatch of the notification releases the lease. | +| `max_send_attempts` | integer | false | | The upper limit of attempts to send a notification. | +| `method` | string | false | | Which delivery method to use (available options: 'smtp', 'webhook'). | +| `retry_interval` | integer | false | | The minimum time between retries. | +| `sync_buffer_size` | integer | false | | The notifications system buffers message updates in memory to ease pressure on the database. This option controls how many updates are kept in memory. The lower this value the lower the change of state inconsistency in a non-graceful shutdown - but it also increases load on the database. It is recommended to keep this option at its default value. | +| `sync_interval` | integer | false | | The notifications system buffers message updates in memory to ease pressure on the database. This option controls how often it synchronizes its state with the database. The shorter this value the lower the change of state inconsistency in a non-graceful shutdown - but it also increases load on the database. It is recommended to keep this option at its default value. | +| `webhook` | [codersdk.NotificationsWebhookConfig](#codersdknotificationswebhookconfig) | false | | Webhook settings. | + +## codersdk.NotificationsEmailAuthConfig + +```json +{ + "identity": "string", + "password": "string", + "password_file": "string", + "username": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| --------------- | ------ | -------- | ------------ | ---------------------------------------------------------- | +| `identity` | string | false | | Identity for PLAIN auth. | +| `password` | string | false | | Password for LOGIN/PLAIN auth. | +| `password_file` | string | false | | File from which to load the password for LOGIN/PLAIN auth. | +| `username` | string | false | | Username for LOGIN/PLAIN auth. | + +## codersdk.NotificationsEmailConfig + +```json +{ + "auth": { + "identity": "string", + "password": "string", + "password_file": "string", + "username": "string" + }, + "force_tls": true, + "from": "string", + "hello": "string", + "smarthost": { + "host": "string", + "port": "string" + }, + "tls": { + "ca_file": "string", + "cert_file": "string", + "insecure_skip_verify": true, + "key_file": "string", + "server_name": "string", + "start_tls": true + } +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ----------- | ------------------------------------------------------------------------------ | -------- | ------------ | --------------------------------------------------------------------- | +| `auth` | [codersdk.NotificationsEmailAuthConfig](#codersdknotificationsemailauthconfig) | false | | Authentication details. | +| `force_tls` | boolean | false | | Force tls causes a TLS connection to be attempted. | +| `from` | string | false | | The sender's address. | +| `hello` | string | false | | The hostname identifying the SMTP server. | +| `smarthost` | [serpent.HostPort](#serpenthostport) | false | | The intermediary SMTP host through which emails are sent (host:port). | +| `tls` | [codersdk.NotificationsEmailTLSConfig](#codersdknotificationsemailtlsconfig) | false | | Tls details. | + +## codersdk.NotificationsEmailTLSConfig + +```json +{ + "ca_file": "string", + "cert_file": "string", + "insecure_skip_verify": true, + "key_file": "string", + "server_name": "string", + "start_tls": true +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ---------------------- | ------- | -------- | ------------ | ------------------------------------------------------------ | +| `ca_file` | string | false | | Ca file specifies the location of the CA certificate to use. | +| `cert_file` | string | false | | Cert file specifies the location of the certificate to use. | +| `insecure_skip_verify` | boolean | false | | Insecure skip verify skips target certificate validation. | +| `key_file` | string | false | | Key file specifies the location of the key to use. | +| `server_name` | string | false | | Server name to verify the hostname for the targets. | +| `start_tls` | boolean | false | | Start tls attempts to upgrade plain connections to TLS. | + +## codersdk.NotificationsSettings + +```json +{ + "notifier_paused": true +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ----------------- | ------- | -------- | ------------ | ----------- | +| `notifier_paused` | boolean | false | | | + +## codersdk.NotificationsWebhookConfig + +```json +{ + "endpoint": { + "forceQuery": true, + "fragment": "string", + "host": "string", + "omitHost": true, + "opaque": "string", + "path": "string", + "rawFragment": "string", + "rawPath": "string", + "rawQuery": "string", + "scheme": "string", + "user": {} + } +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ---------- | -------------------------- | -------- | ------------ | -------------------------------------------------------------------- | +| `endpoint` | [serpent.URL](#serpenturl) | false | | The URL to which the payload will be sent with an HTTP POST request. | + ## codersdk.OAuth2AppEndpoints ```json @@ -3528,9 +3531,11 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "ignore_email_verified": true, "ignore_user_info": true, "issuer_url": "string", + "name_field": "string", "scopes": ["string"], "sign_in_text": "string", "signups_disabled_text": "string", + "skip_issuer_checks": true, "user_role_field": "string", "user_role_mapping": {}, "user_roles_default": ["string"], @@ -3559,9 +3564,11 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `ignore_email_verified` | boolean | false | | | | `ignore_user_info` | boolean | false | | | | `issuer_url` | string | false | | | +| `name_field` | string | false | | | | `scopes` | array of string | false | | | | `sign_in_text` | string | false | | | | `signups_disabled_text` | string | false | | | +| `skip_issuer_checks` | boolean | false | | | | `user_role_field` | string | false | | | | `user_role_mapping` | object | false | | | | `user_roles_default` | array of string | false | | | @@ -3572,6 +3579,9 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o ```json { "created_at": "2019-08-24T14:15:22Z", + "description": "string", + "display_name": "string", + "icon": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "is_default": true, "name": "string", @@ -3581,13 +3591,16 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o ### Properties -| Name | Type | Required | Restrictions | Description | -| ------------ | ------- | -------- | ------------ | ----------- | -| `created_at` | string | true | | | -| `id` | string | true | | | -| `is_default` | boolean | true | | | -| `name` | string | true | | | -| `updated_at` | string | true | | | +| Name | Type | Required | Restrictions | Description | +| -------------- | ------- | -------- | ------------ | ----------- | +| `created_at` | string | true | | | +| `description` | string | false | | | +| `display_name` | string | false | | | +| `icon` | string | false | | | +| `id` | string | true | | | +| `is_default` | boolean | true | | | +| `name` | string | false | | | +| `updated_at` | string | true | | | ## codersdk.OrganizationMember @@ -3598,7 +3611,8 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "updated_at": "2019-08-24T14:15:22Z", @@ -3616,6 +3630,50 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `updated_at` | string | false | | | | `user_id` | string | false | | | +## codersdk.OrganizationMemberWithUserData + +```json +{ + "avatar_url": "string", + "created_at": "2019-08-24T14:15:22Z", + "email": "string", + "global_roles": [ + { + "display_name": "string", + "name": "string", + "organization_id": "string" + } + ], + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "roles": [ + { + "display_name": "string", + "name": "string", + "organization_id": "string" + } + ], + "updated_at": "2019-08-24T14:15:22Z", + "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5", + "username": "string" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ----------------- | ----------------------------------------------- | -------- | ------------ | ----------- | +| `avatar_url` | string | false | | | +| `created_at` | string | false | | | +| `email` | string | false | | | +| `global_roles` | array of [codersdk.SlimRole](#codersdkslimrole) | false | | | +| `name` | string | false | | | +| `organization_id` | string | false | | | +| `roles` | array of [codersdk.SlimRole](#codersdkslimrole) | false | | | +| `updated_at` | string | false | | | +| `user_id` | string | false | | | +| `username` | string | false | | | + ## codersdk.PatchGroupRequest ```json @@ -3714,6 +3772,22 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `icon` | string | false | | | | `name` | string | true | | | +## codersdk.PostWorkspaceUsageRequest + +```json +{ + "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", + "app_name": "vscode" +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ---------- | ---------------------------------------------- | -------- | ------------ | ----------- | +| `agent_id` | string | false | | | +| `app_name` | [codersdk.UsageAppName](#codersdkusageappname) | false | | | + ## codersdk.PprofConfig ```json @@ -3791,6 +3865,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "last_seen_at": "2019-08-24T14:15:22Z", "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "provisioners": ["string"], "tags": { "property1": "string", @@ -3809,6 +3884,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `id` | string | false | | | | `last_seen_at` | string | false | | | | `name` | string | false | | | +| `organization_id` | string | false | | | | `provisioners` | array of string | false | | | | `tags` | object | false | | | | » `[any property]` | string | false | | | @@ -3922,6 +3998,32 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `failed` | | `unknown` | +## codersdk.ProvisionerKey + +```json +{ + "created_at": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "name": "string", + "organization": "452c1a86-a0af-475b-b03f-724878b0f387", + "tags": { + "property1": "string", + "property2": "string" + } +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +| ------------------ | ------ | -------- | ------------ | ----------- | +| `created_at` | string | false | | | +| `id` | string | false | | | +| `name` | string | false | | | +| `organization` | string | false | | | +| `tags` | object | false | | | +| » `[any property]` | string | false | | | + ## codersdk.ProvisionerLogLevel ```json @@ -4070,6 +4172,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `organization` | | `organization_member` | | `provisioner_daemon` | +| `provisioner_keys` | | `replicas` | | `system` | | `tailnet_coordinator` | @@ -4108,6 +4211,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "name": "string", "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -4125,6 +4229,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `name` | string | false | | | | `status` | [codersdk.UserStatus](#codersdkuserstatus) | false | | | | `theme_preference` | string | false | | | +| `updated_at` | string | false | | | | `username` | string | true | | | #### Enumerated Values @@ -4285,10 +4390,12 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `license` | | `convert_login` | | `health_settings` | +| `notifications_settings` | | `workspace_proxy` | | `organization` | | `oauth2_provider_app` | | `oauth2_provider_app_secret` | +| `custom_role` | ## codersdk.Response @@ -4434,16 +4541,18 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o ```json { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ``` ### Properties -| Name | Type | Required | Restrictions | Description | -| -------------- | ------ | -------- | ------------ | ----------- | -| `display_name` | string | false | | | -| `name` | string | false | | | +| Name | Type | Required | Restrictions | Description | +| ----------------- | ------ | -------- | ------------ | ----------- | +| `display_name` | string | false | | | +| `name` | string | false | | | +| `organization_id` | string | false | | | ## codersdk.SupportConfig @@ -4590,7 +4699,10 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "max_port_share_level": "owner", "name": "string", + "organization_display_name": "string", + "organization_icon": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "provisioner": "terraform", "require_active_version": true, "time_til_dormant_autodelete_ms": 0, @@ -4625,7 +4737,10 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `id` | string | false | | | | `max_port_share_level` | [codersdk.WorkspaceAgentPortShareLevel](#codersdkworkspaceagentportsharelevel) | false | | | | `name` | string | false | | | +| `organization_display_name` | string | false | | | +| `organization_icon` | string | false | | | | `organization_id` | string | false | | | +| `organization_name` | string | false | | | | `provisioner` | string | false | | | | `require_active_version` | boolean | false | | Require active version mandates that workspaces are built with the active template version. | | `time_til_dormant_autodelete_ms` | integer | false | | | @@ -4984,11 +5099,13 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -5009,6 +5126,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | `roles` | array of [codersdk.SlimRole](#codersdkslimrole) | false | | | | `status` | [codersdk.UserStatus](#codersdkuserstatus) | false | | | | `theme_preference` | string | false | | | +| `updated_at` | string | false | | | | `username` | string | true | | | #### Enumerated Values @@ -5349,15 +5467,21 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o ```json { + "description": "string", + "display_name": "string", + "icon": "string", "name": "string" } ``` ### Properties -| Name | Type | Required | Restrictions | Description | -| ------ | ------ | -------- | ------------ | ----------- | -| `name` | string | true | | | +| Name | Type | Required | Restrictions | Description | +| -------------- | ------ | -------- | ------------ | ----------- | +| `description` | string | false | | | +| `display_name` | string | false | | | +| `icon` | string | false | | | +| `name` | string | false | | | ## codersdk.UpdateRoles @@ -5574,6 +5698,23 @@ If the schedule is empty, the user will be updated to use the default schedule.| | `share_level` | `authenticated` | | `share_level` | `public` | +## codersdk.UsageAppName + +```json +"vscode" +``` + +### Properties + +#### Enumerated Values + +| Value | +| ------------------ | +| `vscode` | +| `jetbrains` | +| `reconnecting-pty` | +| `ssh` | + ## codersdk.User ```json @@ -5589,11 +5730,13 @@ If the schedule is empty, the user will be updated to use the default schedule.| "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -5613,6 +5756,7 @@ If the schedule is empty, the user will be updated to use the default schedule.| | `roles` | array of [codersdk.SlimRole](#codersdkslimrole) | false | | | | `status` | [codersdk.UserStatus](#codersdkuserstatus) | false | | | | `theme_preference` | string | false | | | +| `updated_at` | string | false | | | | `username` | string | true | | | #### Enumerated Values @@ -6085,6 +6229,7 @@ If the schedule is empty, the user will be updated to use the default schedule.| }, "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "outdated": true, "owner_avatar_url": "string", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", @@ -6118,6 +6263,7 @@ If the schedule is empty, the user will be updated to use the default schedule.| | `latest_build` | [codersdk.WorkspaceBuild](#codersdkworkspacebuild) | false | | | | `name` | string | false | | | | `organization_id` | string | false | | | +| `organization_name` | string | false | | | | `outdated` | boolean | false | | | | `owner_avatar_url` | string | false | | | | `owner_id` | string | false | | | @@ -6390,28 +6536,6 @@ If the schedule is empty, the user will be updated to use the default schedule.| | `id` | string | false | | | | `workspace_agent_id` | string | false | | | -## codersdk.WorkspaceAgentMetadataDescription - -```json -{ - "display_name": "string", - "interval": 0, - "key": "string", - "script": "string", - "timeout": 0 -} -``` - -### Properties - -| Name | Type | Required | Restrictions | Description | -| -------------- | ------- | -------- | ------------ | ----------- | -| `display_name` | string | false | | | -| `interval` | integer | false | | | -| `key` | string | false | | | -| `script` | string | false | | | -| `timeout` | integer | false | | | - ## codersdk.WorkspaceAgentPortShare ```json @@ -7360,6 +7484,7 @@ If the schedule is empty, the user will be updated to use the default schedule.| }, "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "outdated": true, "owner_avatar_url": "string", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", @@ -8246,7 +8371,6 @@ If the schedule is empty, the user will be updated to use the default schedule.| } ] }, - "failing_sections": ["DERP"], "healthy": true, "provisioner_daemons": { "dismissed": true, @@ -8259,6 +8383,7 @@ If the schedule is empty, the user will be updated to use the default schedule.| "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "last_seen_at": "2019-08-24T14:15:22Z", "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "provisioners": ["string"], "tags": { "property1": "string", @@ -8348,7 +8473,6 @@ If the schedule is empty, the user will be updated to use the default schedule.| | `coder_version` | string | false | | The Coder version of the server that the report was generated on. | | `database` | [healthsdk.DatabaseReport](#healthsdkdatabasereport) | false | | | | `derp` | [healthsdk.DERPHealthReport](#healthsdkderphealthreport) | false | | | -| `failing_sections` | array of [healthsdk.HealthSection](#healthsdkhealthsection) | false | | Failing sections is a list of sections that have failed their healthcheck. | | `healthy` | boolean | false | | Healthy is true if the report returns no errors. Deprecated: use `Severity` instead | | `provisioner_daemons` | [healthsdk.ProvisionerDaemonsReport](#healthsdkprovisionerdaemonsreport) | false | | | | `severity` | [health.Severity](#healthseverity) | false | | Severity indicates the status of Coder health. | @@ -8378,6 +8502,7 @@ If the schedule is empty, the user will be updated to use the default schedule.| "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "last_seen_at": "2019-08-24T14:15:22Z", "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "provisioners": ["string"], "tags": { "property1": "string", @@ -8431,6 +8556,7 @@ If the schedule is empty, the user will be updated to use the default schedule.| "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "last_seen_at": "2019-08-24T14:15:22Z", "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "provisioners": ["string"], "tags": { "property1": "string", @@ -8844,7 +8970,6 @@ _None_ "device_flow": true, "display_icon": "string", "display_name": "string", - "extra_token_keys": ["string"], "id": "string", "no_refresh": true, "regex": "string", diff --git a/docs/api/templates.md b/docs/api/templates.md index de0498c3de87b..f42c4306d01a8 100644 --- a/docs/api/templates.md +++ b/docs/api/templates.md @@ -62,7 +62,10 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "max_port_share_level": "owner", "name": "string", + "organization_display_name": "string", + "organization_icon": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "provisioner": "terraform", "require_active_version": true, "time_til_dormant_autodelete_ms": 0, @@ -114,7 +117,10 @@ Status Code **200** | `» id` | string(uuid) | false | | | | `» max_port_share_level` | [codersdk.WorkspaceAgentPortShareLevel](schemas.md#codersdkworkspaceagentportsharelevel) | false | | | | `» name` | string | false | | | +| `» organization_display_name` | string | false | | | +| `» organization_icon` | string | false | | | | `» organization_id` | string(uuid) | false | | | +| `» organization_name` | string(url) | false | | | | `» provisioner` | string | false | | | | `» require_active_version` | boolean | false | | Require active version mandates that workspaces are built with the active template version. | | `» time_til_dormant_autodelete_ms` | integer | false | | | @@ -224,7 +230,10 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/templa "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "max_port_share_level": "owner", "name": "string", + "organization_display_name": "string", + "organization_icon": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "provisioner": "terraform", "require_active_version": true, "time_til_dormant_autodelete_ms": 0, @@ -363,7 +372,10 @@ curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/templat "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "max_port_share_level": "owner", "name": "string", + "organization_display_name": "string", + "organization_icon": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "provisioner": "terraform", "require_active_version": true, "time_til_dormant_autodelete_ms": 0, @@ -617,6 +629,138 @@ curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/templa To perform this operation, you must be authenticated. [Learn more](authentication.md). +## Get all templates + +### Code samples + +```shell +# Example request using curl +curl -X GET http://coder-server:8080/api/v2/templates \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`GET /templates` + +### Example responses + +> 200 Response + +```json +[ + { + "active_user_count": 0, + "active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc", + "activity_bump_ms": 0, + "allow_user_autostart": true, + "allow_user_autostop": true, + "allow_user_cancel_workspace_jobs": true, + "autostart_requirement": { + "days_of_week": ["monday"] + }, + "autostop_requirement": { + "days_of_week": ["monday"], + "weeks": 0 + }, + "build_time_stats": { + "property1": { + "p50": 123, + "p95": 146 + }, + "property2": { + "p50": 123, + "p95": 146 + } + }, + "created_at": "2019-08-24T14:15:22Z", + "created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f", + "created_by_name": "string", + "default_ttl_ms": 0, + "deprecated": true, + "deprecation_message": "string", + "description": "string", + "display_name": "string", + "failure_ttl_ms": 0, + "icon": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "max_port_share_level": "owner", + "name": "string", + "organization_display_name": "string", + "organization_icon": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", + "provisioner": "terraform", + "require_active_version": true, + "time_til_dormant_autodelete_ms": 0, + "time_til_dormant_ms": 0, + "updated_at": "2019-08-24T14:15:22Z" + } +] +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.Template](schemas.md#codersdktemplate) | + +Response Schema
+ +Status Code **200** + +| Name | Type | Required | Restrictions | Description | +| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `[array item]` | array | false | | | +| `» active_user_count` | integer | false | | Active user count is set to -1 when loading. | +| `» active_version_id` | string(uuid) | false | | | +| `» activity_bump_ms` | integer | false | | | +| `» allow_user_autostart` | boolean | false | | Allow user autostart and AllowUserAutostop are enterprise-only. Their values are only used if your license is entitled to use the advanced template scheduling feature. | +| `» allow_user_autostop` | boolean | false | | | +| `» allow_user_cancel_workspace_jobs` | boolean | false | | | +| `» autostart_requirement` | [codersdk.TemplateAutostartRequirement](schemas.md#codersdktemplateautostartrequirement) | false | | | +| `»» days_of_week` | array | false | | Days of week is a list of days of the week in which autostart is allowed to happen. If no days are specified, autostart is not allowed. | +| `» autostop_requirement` | [codersdk.TemplateAutostopRequirement](schemas.md#codersdktemplateautostoprequirement) | false | | Autostop requirement and AutostartRequirement are enterprise features. Its value is only used if your license is entitled to use the advanced template scheduling feature. | +| `»» days_of_week` | array | false | | Days of week is a list of days of the week on which restarts are required. Restarts happen within the user's quiet hours (in their configured timezone). If no days are specified, restarts are not required. Weekdays cannot be specified twice. | +| Restarts will only happen on weekdays in this list on weeks which line up with Weeks. | +| `»» weeks` | integer | false | | Weeks is the number of weeks between required restarts. Weeks are synced across all workspaces (and Coder deployments) using modulo math on a hardcoded epoch week of January 2nd, 2023 (the first Monday of 2023). Values of 0 or 1 indicate weekly restarts. Values of 2 indicate fortnightly restarts, etc. | +| `» build_time_stats` | [codersdk.TemplateBuildTimeStats](schemas.md#codersdktemplatebuildtimestats) | false | | | +| `»» [any property]` | [codersdk.TransitionStats](schemas.md#codersdktransitionstats) | false | | | +| `»»» p50` | integer | false | | | +| `»»» p95` | integer | false | | | +| `» created_at` | string(date-time) | false | | | +| `» created_by_id` | string(uuid) | false | | | +| `» created_by_name` | string | false | | | +| `» default_ttl_ms` | integer | false | | | +| `» deprecated` | boolean | false | | | +| `» deprecation_message` | string | false | | | +| `» description` | string | false | | | +| `» display_name` | string | false | | | +| `» failure_ttl_ms` | integer | false | | Failure ttl ms TimeTilDormantMillis, and TimeTilDormantAutoDeleteMillis are enterprise-only. Their values are used if your license is entitled to use the advanced template scheduling feature. | +| `» icon` | string | false | | | +| `» id` | string(uuid) | false | | | +| `» max_port_share_level` | [codersdk.WorkspaceAgentPortShareLevel](schemas.md#codersdkworkspaceagentportsharelevel) | false | | | +| `» name` | string | false | | | +| `» organization_display_name` | string | false | | | +| `» organization_icon` | string | false | | | +| `» organization_id` | string(uuid) | false | | | +| `» organization_name` | string(url) | false | | | +| `» provisioner` | string | false | | | +| `» require_active_version` | boolean | false | | Require active version mandates that workspaces are built with the active template version. | +| `» time_til_dormant_autodelete_ms` | integer | false | | | +| `» time_til_dormant_ms` | integer | false | | | +| `» updated_at` | string(date-time) | false | | | + +#### Enumerated Values + +| Property | Value | +| ---------------------- | --------------- | +| `max_port_share_level` | `owner` | +| `max_port_share_level` | `authenticated` | +| `max_port_share_level` | `public` | +| `provisioner` | `terraform` | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + ## Get template metadata by ID ### Code samples @@ -678,7 +822,10 @@ curl -X GET http://coder-server:8080/api/v2/templates/{template} \ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "max_port_share_level": "owner", "name": "string", + "organization_display_name": "string", + "organization_icon": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "provisioner": "terraform", "require_active_version": true, "time_til_dormant_autodelete_ms": 0, @@ -800,7 +947,10 @@ curl -X PATCH http://coder-server:8080/api/v2/templates/{template} \ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "max_port_share_level": "owner", "name": "string", + "organization_display_name": "string", + "organization_icon": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "provisioner": "terraform", "require_active_version": true, "time_til_dormant_autodelete_ms": 0, diff --git a/docs/api/users.md b/docs/api/users.md index c9910bf66c1c7..05af30df869e0 100644 --- a/docs/api/users.md +++ b/docs/api/users.md @@ -42,11 +42,13 @@ curl -X GET http://coder-server:8080/api/v2/users \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ] @@ -82,6 +84,7 @@ curl -X POST http://coder-server:8080/api/v2/users \ "disable_login": true, "email": "user@example.com", "login_type": "", + "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "password": "string", "username": "string" @@ -111,11 +114,13 @@ curl -X POST http://coder-server:8080/api/v2/users \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -227,6 +232,7 @@ curl -X POST http://coder-server:8080/api/v2/users/first \ ```json { "email": "string", + "name": "string", "password": "string", "trial": true, "trial_info": { @@ -381,11 +387,13 @@ curl -X GET http://coder-server:8080/api/v2/users/{user} \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -405,7 +413,6 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio ```shell # Example request using curl curl -X DELETE http://coder-server:8080/api/v2/users/{user} \ - -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` @@ -417,37 +424,11 @@ curl -X DELETE http://coder-server:8080/api/v2/users/{user} \ | ------ | ---- | ------ | -------- | -------------------- | | `user` | path | string | true | User ID, name, or me | -### Example responses - -> 200 Response - -```json -{ - "avatar_url": "http://example.com", - "created_at": "2019-08-24T14:15:22Z", - "email": "user@example.com", - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", - "last_seen_at": "2019-08-24T14:15:22Z", - "login_type": "", - "name": "string", - "organization_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"], - "roles": [ - { - "display_name": "string", - "name": "string" - } - ], - "status": "active", - "theme_preference": "string", - "username": "string" -} -``` - ### Responses -| Status | Meaning | Description | Schema | -| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------- | -| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.User](schemas.md#codersdkuser) | +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | ------ | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | | To perform this operation, you must be authenticated. [Learn more](authentication.md). @@ -497,11 +478,13 @@ curl -X PUT http://coder-server:8080/api/v2/users/{user}/appearance \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -993,6 +976,9 @@ curl -X GET http://coder-server:8080/api/v2/users/{user}/organizations \ [ { "created_at": "2019-08-24T14:15:22Z", + "description": "string", + "display_name": "string", + "icon": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "is_default": true, "name": "string", @@ -1011,14 +997,17 @@ curl -X GET http://coder-server:8080/api/v2/users/{user}/organizations \ Status Code **200** -| Name | Type | Required | Restrictions | Description | -| -------------- | ----------------- | -------- | ------------ | ----------- | -| `[array item]` | array | false | | | -| `» created_at` | string(date-time) | true | | | -| `» id` | string(uuid) | true | | | -| `» is_default` | boolean | true | | | -| `» name` | string | true | | | -| `» updated_at` | string(date-time) | true | | | +| Name | Type | Required | Restrictions | Description | +| ---------------- | ----------------- | -------- | ------------ | ----------- | +| `[array item]` | array | false | | | +| `» created_at` | string(date-time) | true | | | +| `» description` | string | false | | | +| `» display_name` | string | false | | | +| `» icon` | string | false | | | +| `» id` | string(uuid) | true | | | +| `» is_default` | boolean | true | | | +| `» name` | string | false | | | +| `» updated_at` | string(date-time) | true | | | To perform this operation, you must be authenticated. [Learn more](authentication.md). @@ -1049,6 +1038,9 @@ curl -X GET http://coder-server:8080/api/v2/users/{user}/organizations/{organiza ```json { "created_at": "2019-08-24T14:15:22Z", + "description": "string", + "display_name": "string", + "icon": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "is_default": true, "name": "string", @@ -1148,11 +1140,13 @@ curl -X PUT http://coder-server:8080/api/v2/users/{user}/profile \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -1201,11 +1195,13 @@ curl -X GET http://coder-server:8080/api/v2/users/{user}/roles \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -1264,11 +1260,13 @@ curl -X PUT http://coder-server:8080/api/v2/users/{user}/roles \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -1317,11 +1315,13 @@ curl -X PUT http://coder-server:8080/api/v2/users/{user}/status/activate \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` @@ -1370,11 +1370,13 @@ curl -X PUT http://coder-server:8080/api/v2/users/{user}/status/suspend \ "roles": [ { "display_name": "string", - "name": "string" + "name": "string", + "organization_id": "string" } ], "status": "active", "theme_preference": "string", + "updated_at": "2019-08-24T14:15:22Z", "username": "string" } ``` diff --git a/docs/api/workspaces.md b/docs/api/workspaces.md index 886f8401f7d7e..10d4680430834 100644 --- a/docs/api/workspaces.md +++ b/docs/api/workspaces.md @@ -215,6 +215,7 @@ of the template will be used. }, "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "outdated": true, "owner_avatar_url": "string", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", @@ -429,6 +430,246 @@ curl -X GET http://coder-server:8080/api/v2/users/{user}/workspace/{workspacenam }, "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", + "outdated": true, + "owner_avatar_url": "string", + "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", + "owner_name": "string", + "template_active_version_id": "b0da9c29-67d8-4c87-888c-bafe356f7f3c", + "template_allow_user_cancel_workspace_jobs": true, + "template_display_name": "string", + "template_icon": "string", + "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc", + "template_name": "string", + "template_require_active_version": true, + "ttl_ms": 0, + "updated_at": "2019-08-24T14:15:22Z" +} +``` + +### Responses + +| Status | Meaning | Description | Schema | +| ------ | ------------------------------------------------------- | ----------- | -------------------------------------------------- | +| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Workspace](schemas.md#codersdkworkspace) | + +To perform this operation, you must be authenticated. [Learn more](authentication.md). + +## Create user workspace + +### Code samples + +```shell +# Example request using curl +curl -X POST http://coder-server:8080/api/v2/users/{user}/workspaces \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +`POST /users/{user}/workspaces` + +Create a new workspace using a template. The request must +specify either the Template ID or the Template Version ID, +not both. If the Template ID is specified, the active version +of the template will be used. + +> Body parameter + +```json +{ + "automatic_updates": "always", + "autostart_schedule": "string", + "name": "string", + "rich_parameter_values": [ + { + "name": "string", + "value": "string" + } + ], + "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc", + "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1", + "ttl_ms": 0 +} +``` + +### Parameters + +| Name | In | Type | Required | Description | +| ------ | ---- | ---------------------------------------------------------------------------- | -------- | ------------------------ | +| `user` | path | string | true | Username, UUID, or me | +| `body` | body | [codersdk.CreateWorkspaceRequest](schemas.md#codersdkcreateworkspacerequest) | true | Create workspace request | + +### Example responses + +> 200 Response + +```json +{ + "allow_renames": true, + "automatic_updates": "always", + "autostart_schedule": "string", + "created_at": "2019-08-24T14:15:22Z", + "deleting_at": "2019-08-24T14:15:22Z", + "dormant_at": "2019-08-24T14:15:22Z", + "favorite": true, + "health": { + "failing_agents": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"], + "healthy": false + }, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "last_used_at": "2019-08-24T14:15:22Z", + "latest_build": { + "build_number": 0, + "created_at": "2019-08-24T14:15:22Z", + "daily_cost": 0, + "deadline": "2019-08-24T14:15:22Z", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "initiator_id": "06588898-9a84-4b35-ba8f-f9cbd64946f3", + "initiator_name": "string", + "job": { + "canceled_at": "2019-08-24T14:15:22Z", + "completed_at": "2019-08-24T14:15:22Z", + "created_at": "2019-08-24T14:15:22Z", + "error": "string", + "error_code": "REQUIRED_TEMPLATE_VARIABLES", + "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "queue_position": 0, + "queue_size": 0, + "started_at": "2019-08-24T14:15:22Z", + "status": "pending", + "tags": { + "property1": "string", + "property2": "string" + }, + "worker_id": "ae5fa6f7-c55b-40c1-b40a-b36ac467652b" + }, + "max_deadline": "2019-08-24T14:15:22Z", + "reason": "initiator", + "resources": [ + { + "agents": [ + { + "api_version": "string", + "apps": [ + { + "command": "string", + "display_name": "string", + "external": true, + "health": "disabled", + "healthcheck": { + "interval": 0, + "threshold": 0, + "url": "string" + }, + "icon": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "sharing_level": "owner", + "slug": "string", + "subdomain": true, + "subdomain_name": "string", + "url": "string" + } + ], + "architecture": "string", + "connection_timeout_seconds": 0, + "created_at": "2019-08-24T14:15:22Z", + "directory": "string", + "disconnected_at": "2019-08-24T14:15:22Z", + "display_apps": ["vscode"], + "environment_variables": { + "property1": "string", + "property2": "string" + }, + "expanded_directory": "string", + "first_connected_at": "2019-08-24T14:15:22Z", + "health": { + "healthy": false, + "reason": "agent has lost connection" + }, + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "instance_id": "string", + "last_connected_at": "2019-08-24T14:15:22Z", + "latency": { + "property1": { + "latency_ms": 0, + "preferred": true + }, + "property2": { + "latency_ms": 0, + "preferred": true + } + }, + "lifecycle_state": "created", + "log_sources": [ + { + "created_at": "2019-08-24T14:15:22Z", + "display_name": "string", + "icon": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "workspace_agent_id": "7ad2e618-fea7-4c1a-b70a-f501566a72f1" + } + ], + "logs_length": 0, + "logs_overflowed": true, + "name": "string", + "operating_system": "string", + "ready_at": "2019-08-24T14:15:22Z", + "resource_id": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", + "scripts": [ + { + "cron": "string", + "log_path": "string", + "log_source_id": "4197ab25-95cf-4b91-9c78-f7f2af5d353a", + "run_on_start": true, + "run_on_stop": true, + "script": "string", + "start_blocks_login": true, + "timeout": 0 + } + ], + "started_at": "2019-08-24T14:15:22Z", + "startup_script_behavior": "blocking", + "status": "connecting", + "subsystems": ["envbox"], + "troubleshooting_url": "string", + "updated_at": "2019-08-24T14:15:22Z", + "version": "string" + } + ], + "created_at": "2019-08-24T14:15:22Z", + "daily_cost": 0, + "hide": true, + "icon": "string", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f", + "metadata": [ + { + "key": "string", + "sensitive": true, + "value": "string" + } + ], + "name": "string", + "type": "string", + "workspace_transition": "start" + } + ], + "status": "pending", + "template_version_id": "0ba39c92-1f1b-4c32-aa3e-9925d7713eb1", + "template_version_name": "string", + "transition": "start", + "updated_at": "2019-08-24T14:15:22Z", + "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9", + "workspace_name": "string", + "workspace_owner_avatar_url": "string", + "workspace_owner_id": "e7078695-5279-4c86-8774-3ac2367a2fc7", + "workspace_owner_name": "string" + }, + "name": "string", + "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "outdated": true, "owner_avatar_url": "string", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", @@ -642,6 +883,7 @@ curl -X GET http://coder-server:8080/api/v2/workspaces \ }, "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "outdated": true, "owner_avatar_url": "string", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", @@ -857,6 +1099,7 @@ curl -X GET http://coder-server:8080/api/v2/workspaces/{workspace} \ }, "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "outdated": true, "owner_avatar_url": "string", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", @@ -1187,6 +1430,7 @@ curl -X PUT http://coder-server:8080/api/v2/workspaces/{workspace}/dormant \ }, "name": "string", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "organization_name": "string", "outdated": true, "owner_avatar_url": "string", "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05", @@ -1397,16 +1641,27 @@ To perform this operation, you must be authenticated. [Learn more](authenticatio ```shell # Example request using curl curl -X POST http://coder-server:8080/api/v2/workspaces/{workspace}/usage \ + -H 'Content-Type: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` `POST /workspaces/{workspace}/usage` +> Body parameter + +```json +{ + "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", + "app_name": "vscode" +} +``` + ### Parameters -| Name | In | Type | Required | Description | -| ----------- | ---- | ------------ | -------- | ------------ | -| `workspace` | path | string(uuid) | true | Workspace ID | +| Name | In | Type | Required | Description | +| ----------- | ---- | ---------------------------------------------------------------------------------- | -------- | ---------------------------- | +| `workspace` | path | string(uuid) | true | Workspace ID | +| `body` | body | [codersdk.PostWorkspaceUsageRequest](schemas.md#codersdkpostworkspaceusagerequest) | false | Post workspace usage request | ### Responses diff --git a/docs/admin/architectures/1k-users.md b/docs/architecture/1k-users.md similarity index 100% rename from docs/admin/architectures/1k-users.md rename to docs/architecture/1k-users.md diff --git a/docs/admin/architectures/2k-users.md b/docs/architecture/2k-users.md similarity index 100% rename from docs/admin/architectures/2k-users.md rename to docs/architecture/2k-users.md diff --git a/docs/admin/architectures/3k-users.md b/docs/architecture/3k-users.md similarity index 100% rename from docs/admin/architectures/3k-users.md rename to docs/architecture/3k-users.md diff --git a/docs/about/architecture.md b/docs/architecture/architecture.md similarity index 98% rename from docs/about/architecture.md rename to docs/architecture/architecture.md index af826ef784145..76c0a46dbef3b 100644 --- a/docs/about/architecture.md +++ b/docs/architecture/architecture.md @@ -4,9 +4,6 @@ The Coder deployment model is flexible and offers various components that platform administrators can deploy and scale depending on their use case. This page describes possible deployments, challenges, and risks associated with them. -Learn more about our [Reference Architectures](../admin/architectures/index.md) -and platform scaling capabilities. - ## Primary components ### coderd @@ -223,7 +220,7 @@ nearest region and technical specifications provided by the cloud providers. - For Azure: _Azure Kubernetes Service_ - For GCP: _Google Kubernetes Engine_ -See how to deploy +See here for an example deployment of [Coder on Azure Kubernetes Service](https://github.com/ericpaulsen/coder-aks). Learn more about [security requirements](../install/kubernetes.md) for deploying @@ -360,8 +357,8 @@ project-oriented [features](https://containers.dev/features) without requiring platform administrators to push altered Docker images. Learn more about -[Dev containers support](https://coder.com/docs/v2/latest/templates/dev-containers) -in Coder. +[Dev containers support](https://coder.com/docs/templates/dev-containers) in +Coder.  diff --git a/docs/architecture/validated-arch.md b/docs/architecture/validated-arch.md new file mode 100644 index 0000000000000..6379c3563915a --- /dev/null +++ b/docs/architecture/validated-arch.md @@ -0,0 +1,363 @@ +# Coder Validated Architecture + +Many customers operate Coder in complex organizational environments, consisting +of multiple business units, agencies, and/or subsidiaries. This can lead to +numerous Coder deployments, due to discrepancies in regulatory compliance, data +sovereignty, and level of funding across groups. The Coder Validated +Architecture (CVA) prescribes a Kubernetes-based deployment approach, enabling +your organization to deploy a stable Coder instance that is easier to maintain +and troubleshoot. + +The following sections will detail the components of the Coder Validated +Architecture, provide guidance on how to configure and deploy these components, +and offer insights into how to maintain and troubleshoot your Coder environment. + +- [General concepts](#general-concepts) +- [Kubernetes Infrastructure](#kubernetes-infrastructure) +- [PostgreSQL Database](#postgresql-database) +- [Operational readiness](#operational-readiness) + +## Who is this document for? + +This guide targets the following personas. It assumes a basic understanding of +cloud/on-premise computing, containerization, and the Coder platform. + +| Role | Description | +| ------------------------- | ------------------------------------------------------------------------------ | +| Platform Engineers | Responsible for deploying, operating the Coder deployment and infrastructure | +| Enterprise Architects | Responsible for architecting Coder deployments to meet enterprise requirements | +| Managed Service Providers | Entities that deploy and run Coder software as a service for customers | + +## CVA Guidance + +| CVA provides: | CVA does not provide: | +| ---------------------------------------------- | ---------------------------------------------------------------------------------------- | +| Single and multi-region K8s deployment options | Prescribing OS, or cloud vs. on-premise | +| Reference architectures for up to 3,000 users | An approval of your architecture; the CVA solely provides recommendations and guidelines | +| Best practices for building a Coder deployment | Recommendations for every possible deployment scenario | + +> For higher level design principles and architectural best practices, see +> Coder's +> [Well-Architected Framework](https://coder.com/blog/coder-well-architected-framework). + +## General concepts + +This section outlines core concepts and terminology essential for understanding +Coder's architecture and deployment strategies. + +### Administrator + +An administrator is a user role within the Coder platform with elevated +privileges. Admins have access to administrative functions such as user +management, template definitions, insights, and deployment configuration. + +### Coder control plane + +Coder's control plane, also known as _coderd_, is the main service recommended +for deployment with multiple replicas to ensure high availability. It provides +an API for managing workspaces and templates, and serves the dashboard UI. In +addition, each _coderd_ replica hosts 3 Terraform [provisioners](#provisioner) +by default. + +### User + +A [user](../admin/users.md) is an individual who utilizes the Coder platform to +develop, test, and deploy applications using workspaces. Users can select +available templates to provision workspaces. They interact with Coder using the +web interface, the CLI tool, or directly calling API methods. + +### Workspace + +A [workspace](../workspaces.md) refers to an isolated development environment +where users can write, build, and run code. Workspaces are fully configurable +and can be tailored to specific project requirements, providing developers with +a consistent and efficient development environment. Workspaces can be +autostarted and autostopped, enabling efficient resource management. + +Users can connect to workspaces using SSH or via workspace applications like +`code-server`, facilitating collaboration and remote access. Additionally, +workspaces can be parameterized, allowing users to customize settings and +configurations based on their unique needs. Workspaces are instantiated using +Coder templates and deployed on resources created by provisioners. + +### Template + +A [template](../templates/index.md) in Coder is a predefined configuration for +creating workspaces. Templates streamline the process of workspace creation by +providing pre-configured settings, tooling, and dependencies. They are built by +template administrators on top of Terraform, allowing for efficient management +of infrastructure resources. Additionally, templates can utilize Coder modules +to leverage existing features shared with other templates, enhancing flexibility +and consistency across deployments. Templates describe provisioning rules for +infrastructure resources offered by Terraform providers. + +### Workspace Proxy + +A [workspace proxy](../admin/workspace-proxies.md) serves as a relay connection +option for developers connecting to their workspace over SSH, a workspace app, +or through port forwarding. It helps reduce network latency for geo-distributed +teams by minimizing the distance network traffic needs to travel. Notably, +workspace proxies do not handle dashboard connections or API calls. + +### Provisioner + +Provisioners in Coder execute Terraform during workspace and template builds. +While the platform includes built-in provisioner daemons by default, there are +advantages to employing external provisioners. These external daemons provide +secure build environments and reduce server load, improving performance and +scalability. Each provisioner can handle a single concurrent workspace build, +allowing for efficient resource allocation and workload management. + +### Registry + +The [Coder Registry](https://registry.coder.com) is a platform where you can +find starter templates and _Modules_ for various cloud services and platforms. + +Templates help create self-service development environments using +Terraform-defined infrastructure, while _Modules_ simplify template creation by +providing common features like workspace applications, third-party integrations, +or helper scripts. + +Please note that the Registry is a hosted service and isn't available for +offline use. + +## Kubernetes Infrastructure + +Kubernetes is the recommended, and supported platform for deploying Coder in the +enterprise. It is the hosting platform of choice for a large majority of Coder's +Fortune 500 customers, and it is the platform in which we build and test against +here at Coder. + +### General recommendations + +In general, it is recommended to deploy Coder into its own respective cluster, +separate from production applications. Keep in mind that Coder runs development +workloads, so the cluster should be deployed as such, without production-level +configurations. + +### Compute + +Deploy your Kubernetes cluster with two node groups, one for Coder's control +plane, and another for user workspaces (if you intend on leveraging K8s for +end-user compute). + +#### Control plane nodes + +The Coder control plane node group must be static, to prevent scale down events +from dropping pods, and thus dropping user connections to the dashboard UI and +their workspaces. + +Coder's Helm Chart supports +[defining nodeSelectors, affinities, and tolerations](https://github.com/coder/coder/blob/e96652ebbcdd7554977594286b32015115c3f5b6/helm/coder/values.yaml#L221-L249) +to schedule the control plane pods on the appropriate node group. + +#### Workspace nodes + +Coder workspaces can be deployed either as Pods or Deployments in Kubernetes. +See our +[example Kubernetes workspace template](https://github.com/coder/coder/tree/main/examples/templates/kubernetes). +Configure the workspace node group to be auto-scaling, to dynamically allocate +compute as users start/stop workspaces at the beginning and end of their day. +Set nodeSelectors, affinities, and tolerations in Coder templates to assign +workspaces to the given node group: + +```hcl +resource "kubernetes_deployment" "coder" { + spec { + template { + metadata { + labels = { + app = "coder-workspace" + } + } + + spec { + affinity { + pod_anti_affinity { + preferred_during_scheduling_ignored_during_execution { + weight = 1 + pod_affinity_term { + label_selector { + match_expressions { + key = "app.kubernetes.io/instance" + operator = "In" + values = ["coder-workspace"] + } + } + topology_key = # add your node group label here + } + } + } + } + + tolerations { + # Add your tolerations here + } + + node_selector { + # Add your node selectors here + } + + container { + image = "coder-workspace:latest" + name = "dev" + } + } + } + } +} +``` + +#### Node sizing + +For sizing recommendations, see the below reference architectures: + +- [Up to 1,000 users](./1k-users.md) + +- [Up to 2,000 users](./2k-users.md) + +- [Up to 3,000 users](./3k-users.md) + +### Networking + +It is likely your enterprise deploys Kubernetes clusters with various networking +restrictions. With this in mind, Coder requires the following connectivity: + +- Egress from workspace compute to the Coder control plane pods +- Egress from control plane pods to Coder's PostgreSQL database +- Egress from control plane pods to git and package repositories +- Ingress from user devices to the control plane Load Balancer or Ingress + controller + +We recommend configuring your network policies in accordance with the above. +Note that Coder workspaces do not require any ports to be open. + +### Storage + +If running Coder workspaces as Kubernetes Pods or Deployments, you will need to +assign persistent storage. We recommend leveraging a +[supported Container Storage Interface (CSI) driver](https://kubernetes-csi.github.io/docs/drivers.html) +in your cluster, with Dynamic Provisioning and read/write, to provide on-demand +storage to end-user workspaces. + +The following Kubernetes volume types have been validated by Coder internally, +and/or by our customers: + +- [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim) +- [NFS](https://kubernetes.io/docs/concepts/storage/volumes/#nfs) +- [subPath](https://kubernetes.io/docs/concepts/storage/volumes/#using-subpath) +- [cephfs](https://kubernetes.io/docs/concepts/storage/volumes/#cephfs) + +Our +[example Kubernetes workspace template](https://github.com/coder/coder/blob/5b9a65e5c137232351381fc337d9784bc9aeecfc/examples/templates/kubernetes/main.tf#L191-L219) +provisions a PersistentVolumeClaim block storage device, attached to the +Deployment. + +It is not recommended to mount volumes from the host node(s) into workspaces, +for security and reliability purposes. The below volume types are _not_ +recommended for use with Coder: + +- [Local](https://kubernetes.io/docs/concepts/storage/volumes/#local) +- [hostPath](https://kubernetes.io/docs/concepts/storage/volumes/#hostpath) + +Not that Coder's control plane filesystem is ephemeral, so no persistent storage +is required. + +## PostgreSQL database + +Coder requires access to an external PostgreSQL database to store user data, +workspace state, template files, and more. Depending on the scale of the +user-base, workspace activity, and High Availability requirements, the amount of +CPU and memory resources required by Coder's database may differ. + +### Disaster recovery + +Prepare internal scripts for dumping and restoring your database. We recommend +scheduling regular database backups, especially before upgrading Coder to a new +release. Coder does not support downgrades without initially restoring the +database to the prior version. + +### Performance efficiency + +We highly recommend deploying the PostgreSQL instance in the same region (and if +possible, same availability zone) as the Coder server to optimize for low +latency connections. We recommend keeping latency under 10ms between the Coder +server and database. + +When determining scaling requirements, take into account the following +considerations: + +- `2 vCPU x 8 GB RAM x 512 GB storage`: A baseline for database requirements for + Coder deployment with less than 1000 users, and low activity level (30% active + users). This capacity should be sufficient to support 100 external + provisioners. +- Storage size depends on user activity, workspace builds, log verbosity, + overhead on database encryption, etc. +- Allocate two additional CPU core to the database instance for every 1000 + active users. +- Enable High Availability mode for database engine for large scale deployments. + +If you enable [database encryption](../admin/encryption.md) in Coder, consider +allocating an additional CPU core to every `coderd` replica. + +#### Resource utilization guidelines + +Below are general recommendations for sizing your PostgreSQL instance: + +- Increase number of vCPU if CPU utilization or database latency is high. +- Allocate extra memory if database performance is poor, CPU utilization is low, + and memory utilization is high. +- Utilize faster disk options (higher IOPS) such as SSDs or NVMe drives for + optimal performance enhancement and possibly reduce database load. + +## Operational readiness + +Operational readiness in Coder is about ensuring that everything is set up +correctly before launching a platform into production. It involves making sure +that the service is reliable, secure, and easily scales accordingly to user-base +needs. Operational readiness is crucial because it helps prevent issues that +could affect workspace users experience once the platform is live. + +### Helm Chart Configuration + +1. Reference our [Helm chart values file](../../helm/coder/values.yaml) and + identify the required values for deployment. +1. Create a `values.yaml` and add it to your version control system. +1. Determine the necessary environment variables. Here is the + [full list of supported server environment variables](../cli/server.md). +1. Follow our documented + [steps for installing Coder via Helm](../install/kubernetes.md). + +### Template configuration + +1. Establish dedicated accounts for users with the _Template Administrator_ + role. +1. Maintain Coder templates using + [version control](../templates/change-management.md). +1. Consider implementing a GitOps workflow to automatically push new template + versions into Coder from git. For example, on Github, you can use the + [Update Coder Template](https://github.com/marketplace/actions/update-coder-template) + action. +1. Evaluate enabling + [automatic template updates](../templates/general-settings.md#require-automatic-updates-enterprise) + upon workspace startup. + +### Observability + +1. Enable the Prometheus endpoint (environment variable: + `CODER_PROMETHEUS_ENABLE`). +1. Deploy the + [Coder Observability bundle](https://github.com/coder/observability) to + leverage pre-configured dashboards, alerts, and runbooks for monitoring + Coder. This includes integrations between Prometheus, Grafana, Loki, and + Alertmanager. +1. Review the [Prometheus response](../admin/prometheus.md) and set up alarms on + selected metrics. + +### User support + +1. Incorporate [support links](../admin/appearance.md#support-links) into + internal documentation accessible from the user context menu. Ensure that + hyperlinks are valid and lead to up-to-date materials. +1. Encourage the use of `coder support bundle` to allow workspace users to + generate and provide network-related diagnostic data. diff --git a/docs/changelogs/v0.25.0.md b/docs/changelogs/v0.25.0.md index e31fd0dbf959d..9aa1f6526b25d 100644 --- a/docs/changelogs/v0.25.0.md +++ b/docs/changelogs/v0.25.0.md @@ -8,7 +8,7 @@ - The `coder stat` fetches workspace utilization metrics, even from within a container. Our example templates have been updated to use this to show CPU, memory, disk via - [agent metadata](https://coder.com/docs/v2/latest/templates/agent-metadata) + [agent metadata](https://coder.com/docs/templates/agent-metadata) (#8005) - Helm: `coder.command` can specify a different command for the Coder pod (#8116) @@ -20,7 +20,7 @@ - Healthcheck endpoint has a database section: `/api/v2/debug/health` - Force DERP connections in CLI with `--disable-direct` flag (#8131) - Disable all direct connections for a Coder deployment with - [--block-direct-connections](https://coder.com/docs/v2/latest/cli/server#--block-direct-connections) + [--block-direct-connections](https://coder.com/docs/cli/server#--block-direct-connections) (#7936) - Search for workspaces based on last activity (#2658) ```text @@ -83,6 +83,6 @@ Compare: ## Install/upgrade -Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or -[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a +Refer to our docs to [install](https://coder.com/docs/install) or +[upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below. diff --git a/docs/changelogs/v0.26.0.md b/docs/changelogs/v0.26.0.md index b5b24929dfc90..19fcb5c3950ea 100644 --- a/docs/changelogs/v0.26.0.md +++ b/docs/changelogs/v0.26.0.md @@ -2,7 +2,7 @@ ### Important changes -- [Managed variables](https://coder.com/docs/v2/latest/templates/parameters#terraform-template-wide-variables) +- [Managed variables](https://coder.com/docs/templates/parameters#terraform-template-wide-variables) are enabled by default. The following block within templates is obsolete and can be removed from your templates: @@ -16,13 +16,13 @@ > previously necessary to activate this additional feature. - Our scale test CLI is - [experimental](https://coder.com/docs/v2/latest/contributing/feature-stages#experimental-features) + [experimental](https://coder.com/docs/contributing/feature-stages#experimental-features) to allow for rapid iteration. You can still interact with it via `coder exp scaletest` (#8339) ### Features -- [coder dotfiles](https://coder.com/docs/v2/latest/cli/dotfiles) can checkout a +- [coder dotfiles](https://coder.com/docs/cli/dotfiles) can checkout a specific branch ### Bug fixes @@ -49,6 +49,6 @@ Compare: ## Install/upgrade -Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or -[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a +Refer to our docs to [install](https://coder.com/docs/install) or +[upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below. diff --git a/docs/changelogs/v0.26.1.md b/docs/changelogs/v0.26.1.md index 9b42197f80285..27decc3eb350c 100644 --- a/docs/changelogs/v0.26.1.md +++ b/docs/changelogs/v0.26.1.md @@ -2,7 +2,7 @@ ### Features -- [Devcontainer templates](https://coder.com/docs/v2/latest/templates/dev-containers) +- [Devcontainer templates](https://coder.com/docs/templates/dev-containers) for Coder (#8256) - The dashboard will warn users when a workspace is unhealthy (#8422) - Audit logs `resource_target` search query allows you to search by resource @@ -31,6 +31,6 @@ Compare: ## Install/upgrade -Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or -[upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a +Refer to our docs to [install](https://coder.com/docs/install) or +[upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below. diff --git a/docs/changelogs/v0.27.0.md b/docs/changelogs/v0.27.0.md index d212579a6fed0..dd7a259df49ad 100644 --- a/docs/changelogs/v0.27.0.md +++ b/docs/changelogs/v0.27.0.md @@ -5,7 +5,7 @@ Agent logs can be pushed after a workspace has started (#8528) > ⚠️ **Warning:** You will need to -> [update](https://coder.com/docs/v2/latest/install) your local Coder CLI v0.27 +> [update](https://coder.com/docs/install) your local Coder CLI v0.27 > to connect via `coder ssh`. ### Features @@ -24,7 +24,7 @@ Agent logs can be pushed after a workspace has started (#8528) - Template version messages (#8435)
-- Add support for [database encryption for user tokens](https://coder.com/docs/v2/latest/admin/encryption#database-encryption).
- > This is an [Enterprise feature](https://coder.com/docs/v2/latest/enterprise).
+- Add support for [database encryption for user tokens](https://coder.com/docs/admin/encryption#database-encryption).
+ > This is an [Enterprise feature](https://coder.com/docs/enterprise).
- Show descriptions for parameter options (#10068) (@aslilac)
- Allow reading the agent token from a file (#10080) (@kylecarbs)
@@ -94,4 +94,4 @@ Compare: [`v2.2.1...v2.3.0`](https://github.com/coder/coder/compare/v2.2.1...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.3.1.md b/docs/changelogs/v2.3.1.md
index 35f9f4dd45a27..a57917eab9bf5 100644
--- a/docs/changelogs/v2.3.1.md
+++ b/docs/changelogs/v2.3.1.md
@@ -46,4 +46,4 @@ Compare: [`v2.3.0...v2.3.1`](https://github.com/coder/coder/compare/v2.3.0...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.3.2.md b/docs/changelogs/v2.3.2.md
index 373914ac0a5de..7723dfb264e79 100644
--- a/docs/changelogs/v2.3.2.md
+++ b/docs/changelogs/v2.3.2.md
@@ -34,4 +34,4 @@ Compare: [`v2.3.1...v2.3.2`](https://github.com/coder/coder/compare/v2.3.1...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.3.3.md b/docs/changelogs/v2.3.3.md
index 9460703a6df7a..d358b6029e8f7 100644
--- a/docs/changelogs/v2.3.3.md
+++ b/docs/changelogs/v2.3.3.md
@@ -40,4 +40,4 @@ Compare: [`v2.3.2...v2.3.3`](https://github.com/coder/coder/compare/v2.3.2...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.4.0.md b/docs/changelogs/v2.4.0.md
index ee2c110474d10..ccf94d714ade1 100644
--- a/docs/changelogs/v2.4.0.md
+++ b/docs/changelogs/v2.4.0.md
@@ -131,4 +131,4 @@ Compare: [`v2.3.3...v2.4.0`](https://github.com/coder/coder/compare/v2.3.3...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.5.0.md b/docs/changelogs/v2.5.0.md
index 807f42e2c4df0..a31731b7e7cc4 100644
--- a/docs/changelogs/v2.5.0.md
+++ b/docs/changelogs/v2.5.0.md
@@ -4,7 +4,7 @@
- Templates can now be deprecated in "template settings" to warn new users and prevent new workspaces from being created (#10745) (@Emyrk)
- > This is an [Enterprise feature](https://coder.com/docs/v2/latest/enterprise).
+ > This is an [Enterprise feature](https://coder.com/docs/enterprise).
- Add user/settings page for managing external auth (#10945) (@Emyrk)
- Allow auditors to read template insights (#10860) (@johnstcn)
@@ -16,7 +16,7 @@
- Dormant workspaces now appear in the default workspaces list (#11053) (@sreya)
- Include server agent API version in buildinfo (#11057) (@spikecurtis)
- Restart stopped workspaces on `coder ssh` command (#11050) (@Emyrk)
-- You can now specify an [allowlist for OIDC Groups](https://coder.com/docs/v2/latest/admin/auth#group-allowlist) (#11070) (@Emyrk)
+- You can now specify an [allowlist for OIDC Groups](https://coder.com/docs/admin/auth#group-allowlist) (#11070) (@Emyrk)
- Display 'Deprecated' warning for agents using old API version (#11058) (@spikecurtis)
- Add support for `coder_env` resource to set environment variables within a workspace (#11102) (@mafredri)
- Handle session signals (#10842) (@mafredri)
@@ -113,4 +113,4 @@ Compare: [`v2.4.0...v2.5.0`](https://github.com/coder/coder/compare/v2.4.0...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.5.1.md b/docs/changelogs/v2.5.1.md
index aea1d02621cc4..c488d6f2ab116 100644
--- a/docs/changelogs/v2.5.1.md
+++ b/docs/changelogs/v2.5.1.md
@@ -29,4 +29,4 @@ Compare: [`v2.5.0...v2.5.1`](https://github.com/coder/coder/compare/v2.5.0...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.6.0.md b/docs/changelogs/v2.6.0.md
index af41014ac594f..5bf7c10992696 100644
--- a/docs/changelogs/v2.6.0.md
+++ b/docs/changelogs/v2.6.0.md
@@ -2,13 +2,13 @@
### BREAKING CHANGES
-- Renaming workspaces is disabled by default to data loss. This can be re-enabled via a [server flag](https://coder.com/docs/v2/latest/cli/server#--allow-workspace-renames) (#11189) (@f0ssel)
+- Renaming workspaces is disabled by default to data loss. This can be re-enabled via a [server flag](https://coder.com/docs/cli/server#--allow-workspace-renames) (#11189) (@f0ssel)
### Features
- Allow templates to specify max_ttl or autostop_requirement (#10920) (@deansheather)
- Add server flag to disable user custom quiet hours (#11124) (@deansheather)
-- Move [workspace proxies](https://coder.com/docs/v2/latest/admin/workspace-proxies) to GA (#11285) (@Emyrk)
+- Move [workspace proxies](https://coder.com/docs/admin/workspace-proxies) to GA (#11285) (@Emyrk)
- Add light theme (preview) (#11266) (@aslilac)
- Enable CSRF token header (#11283) (@Emyrk)
@@ -40,4 +40,4 @@ Compare: [`v2.5.1...v2.6.0`](https://github.com/coder/coder/compare/v2.5.1...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.6.1.md b/docs/changelogs/v2.6.1.md
index 5b09547ee8113..2322fef1a9cca 100644
--- a/docs/changelogs/v2.6.1.md
+++ b/docs/changelogs/v2.6.1.md
@@ -17,4 +17,4 @@ Compare: [`v2.6.0...v2.6.1`](https://github.com/coder/coder/compare/v2.6.0...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.7.0.md b/docs/changelogs/v2.7.0.md
index a792fe6a03ac4..a9e7a7d2630fd 100644
--- a/docs/changelogs/v2.7.0.md
+++ b/docs/changelogs/v2.7.0.md
@@ -30,11 +30,11 @@ are backwards-compatible and have been tested significantly with the goal of imp
- Display application name over sign in form instead of `Sign In` (#11500) (@f0ssel)
- 🧹 Workspace Cleanup: Coder can flag or even auto-delete workspaces that are not in use (#11427) (@sreya)
- > Template admins can manage the cleanup policy in template settings. This is an [Enterprise feature](https://coder.com/docs/v2/latest/enterprise)
+ > Template admins can manage the cleanup policy in template settings. This is an [Enterprise feature](https://coder.com/docs/enterprise)
- Add a character counter for fields with length limits (#11558) (@aslilac)
- Add markdown support for template deprecation messages (#11562) (@aslilac)
- Add support for loading template variables from tfvars files (#11549) (@mtojek)
-- Expose support links as [env variables](https://coder.com/docs/v2/latest/cli/server#--support-links) (#11697) (@mtojek)
+- Expose support links as [env variables](https://coder.com/docs/cli/server#--support-links) (#11697) (@mtojek)
- Allow custom icons in the "support links" navbar (#11629) (@mtojek)
- Add additional fields to first time setup trial flow (#11533) (@coadler)
@@ -136,4 +136,4 @@ Compare: [`v2.6.0...v2.7.0`](https://github.com/coder/coder/compare/v2.6.0...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.7.1.md b/docs/changelogs/v2.7.1.md
index 583d40c2bbd03..ae4013c569b92 100644
--- a/docs/changelogs/v2.7.1.md
+++ b/docs/changelogs/v2.7.1.md
@@ -14,4 +14,4 @@ Compare: [`v2.7.0...v2.7.1`](https://github.com/coder/coder/compare/v2.7.0...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.7.2.md b/docs/changelogs/v2.7.2.md
index 035e2a804e6cf..016030031e076 100644
--- a/docs/changelogs/v2.7.2.md
+++ b/docs/changelogs/v2.7.2.md
@@ -12,4 +12,4 @@ Compare: [`v2.7.1...v2.7.2`](https://github.com/coder/coder/compare/v2.7.0...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.7.3.md b/docs/changelogs/v2.7.3.md
index 7839048429196..880ba0f8f3365 100644
--- a/docs/changelogs/v2.7.3.md
+++ b/docs/changelogs/v2.7.3.md
@@ -17,4 +17,4 @@ Compare: [`v2.7.2...v2.7.3`](https://github.com/coder/coder/compare/v2.7.2...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.8.0.md b/docs/changelogs/v2.8.0.md
index 7ea4cf93675d8..e7804ab57b3db 100644
--- a/docs/changelogs/v2.8.0.md
+++ b/docs/changelogs/v2.8.0.md
@@ -104,4 +104,4 @@ Compare: [`v2.7.2...v2.7.3`](https://github.com/coder/coder/compare/v2.7.2...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.8.2.md b/docs/changelogs/v2.8.2.md
index 3d17439870af9..82820ace43be8 100644
--- a/docs/changelogs/v2.8.2.md
+++ b/docs/changelogs/v2.8.2.md
@@ -12,4 +12,4 @@ Compare: [`v2.8.1...v2.8.2`](https://github.com/coder/coder/compare/v2.8.1...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.8.4.md b/docs/changelogs/v2.8.4.md
index bebb135b7e637..537b5c3c62d7d 100644
--- a/docs/changelogs/v2.8.4.md
+++ b/docs/changelogs/v2.8.4.md
@@ -17,4 +17,4 @@ Compare: [`v2.8.3...v2.8.4`](https://github.com/coder/coder/compare/v2.8.3...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/changelogs/v2.9.0.md b/docs/changelogs/v2.9.0.md
index 0d68325fa4ec3..4c3a5b3fe42d3 100644
--- a/docs/changelogs/v2.9.0.md
+++ b/docs/changelogs/v2.9.0.md
@@ -61,7 +61,7 @@
### Experimental features
-The following features are hidden or disabled by default as we don't guarantee stability. Learn more about experiments in [our documentation](https://coder.com/docs/v2/latest/contributing/feature-stages#experimental-features).
+The following features are hidden or disabled by default as we don't guarantee stability. Learn more about experiments in [our documentation](https://coder.com/docs/contributing/feature-stages#experimental-features).
- The `coder support` command generates a ZIP with deployment information, agent logs, and server config values for troubleshooting purposes. We will publish documentation on how it works (and un-hide the feature) in a future release (#12328) (@johnstcn)
- Port sharing: Allow users to share ports running in their workspace with other Coder users (#11939) (#12119) (#12383) (@deansheather) (@f0ssel)
@@ -153,4 +153,4 @@ Compare: [`v2.8.5...v2.9.0`](https://github.com/coder/coder/compare/v2.8.5...v2.
## Install/upgrade
-Refer to our docs to [install](https://coder.com/docs/v2/latest/install) or [upgrade](https://coder.com/docs/v2/latest/admin/upgrade) Coder, or use a release asset below.
+Refer to our docs to [install](https://coder.com/docs/install) or [upgrade](https://coder.com/docs/admin/upgrade) Coder, or use a release asset below.
diff --git a/docs/cli.md b/docs/cli.md
index 70dd29e28b9da..ab97ca9cc4d10 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -30,6 +30,7 @@ Coder — A tool for provisioning self-hosted development environments with Terr
| [login](./cli/login.md) | Authenticate with Coder deployment |
| [logout](./cli/logout.md) | Unauthenticate your local session |
| [netcheck](./cli/netcheck.md) | Print network debug information for DERP and STUN |
+| [notifications](./cli/notifications.md) | Manage Coder notifications |
| [port-forward](./cli/port-forward.md) | Forward ports from a workspace to the local machine. For reverse port forwarding, use "coder ssh -R". |
| [publickey](./cli/publickey.md) | Output your Coder public key used for Git operations |
| [reset-password](./cli/reset-password.md) | Directly connect to the database to reset a user's password |
@@ -57,6 +58,7 @@ Coder — A tool for provisioning self-hosted development environments with Terr
| [stop](./cli/stop.md) | Stop a workspace |
| [unfavorite](./cli/unfavorite.md) | Remove a workspace from your favorites |
| [update](./cli/update.md) | Will update and start a given workspace if it is out of date |
+| [whoami](./cli/whoami.md) | Fetch authenticated user info for Coder deployment |
| [support](./cli/support.md) | Commands for troubleshooting issues with a Coder deployment. |
| [server](./cli/server.md) | Start a Coder server |
| [features](./cli/features.md) | List Enterprise features |
@@ -149,6 +151,18 @@ Enable verbose output.
Disable direct (P2P) connections to workspaces.
+### --disable-network-telemetry
+
+| | |
+| ----------- | --------------------------------------------- |
+| Type | bool |
+| Environment | $CODER_DISABLE_NETWORK_TELEMETRY |
+
+Disable network telemetry. Network telemetry is collected when connecting to
+workspaces using the CLI, and is forwarded to the server. If telemetry is also
+enabled on the server, it may be sent to Coder. Network telemetry is used to
+measure network quality and detect regressions.
+
### --global-config
| | |
diff --git a/docs/cli/create.md b/docs/cli/create.md
index 53f90751513d2..aefaf4d316d0b 100644
--- a/docs/cli/create.md
+++ b/docs/cli/create.md
@@ -100,3 +100,12 @@ Specify a file path with values for rich parameters defined in the template.
| Environment | $CODER_RICH_PARAMETER_DEFAULT |
Rich parameter default values in the format "name=value".
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/groups_create.md b/docs/cli/groups_create.md
index dd51ed7233a9a..e758b422ea387 100644
--- a/docs/cli/groups_create.md
+++ b/docs/cli/groups_create.md
@@ -29,3 +29,12 @@ Set an avatar for a group.
| Environment | $CODER_DISPLAY_NAME |
Optional human friendly name for the group.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/groups_delete.md b/docs/cli/groups_delete.md
index f57faff0b9f59..7bbf215ae2f29 100644
--- a/docs/cli/groups_delete.md
+++ b/docs/cli/groups_delete.md
@@ -11,5 +11,16 @@ Aliases:
## Usage
```console
-coder groups delete string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/groups_edit.md b/docs/cli/groups_edit.md
index 2006ba85abd4d..f7c39c58e1d24 100644
--- a/docs/cli/groups_edit.md
+++ b/docs/cli/groups_edit.md
@@ -52,3 +52,12 @@ Add users to the group. Accepts emails or IDs.
| Type | string-array |
Remove users to the group. Accepts emails or IDs.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/groups_list.md b/docs/cli/groups_list.md
index 5f9e184f3995d..04d9fe726adfd 100644
--- a/docs/cli/groups_list.md
+++ b/docs/cli/groups_list.md
@@ -29,3 +29,12 @@ Columns to display in table output. Available columns: name, display name, organ
| Default | table |
Output format. Available formats: table, json.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/list.md b/docs/cli/list.md
index 2c67fac0f927e..e64adf399dd6a 100644
--- a/docs/cli/list.md
+++ b/docs/cli/list.md
@@ -40,7 +40,7 @@ Search for a workspace with a query.
| Type | string-array |
| Default | workspace,template,status,healthy,last built,current version,outdated,starts at,stops after |
-Columns to display in table output. Available columns: favorite, workspace, template, status, healthy, last built, current version, outdated, starts at, starts next, stops after, stops next, daily cost.
+Columns to display in table output. Available columns: favorite, workspace, organization id, organization name, template, status, healthy, last built, current version, outdated, starts at, starts next, stops after, stops next, daily cost.
### -o, --output
diff --git a/docs/cli/login.md b/docs/cli/login.md
index 8dab8a884149c..9a27e4a6357c8 100644
--- a/docs/cli/login.md
+++ b/docs/cli/login.md
@@ -30,6 +30,15 @@ Specifies an email address to use if creating the first user for the deployment.
Specifies a username to use if creating the first user for the deployment.
+### --first-user-full-name
+
+| | |
+| ----------- | ---------------------------------------- |
+| Type | string |
+| Environment | $CODER_FIRST_USER_FULL_NAME |
+
+Specifies a human-readable name for the first user of the deployment.
+
### --first-user-password
| | |
diff --git a/docs/cli/notifications.md b/docs/cli/notifications.md
new file mode 100644
index 0000000000000..59e74b4324357
--- /dev/null
+++ b/docs/cli/notifications.md
@@ -0,0 +1,37 @@
+
+
+# notifications
+
+Manage Coder notifications
+
+Aliases:
+
+- notification
+
+## Usage
+
+```console
+coder notifications
+```
+
+## Description
+
+```console
+Administrators can use these commands to change notification settings.
+ - Pause Coder notifications. Administrators can temporarily stop notifiers from
+dispatching messages in case of the target outage (for example: unavailable SMTP
+server or Webhook not responding).:
+
+ $ coder notifications pause
+
+ - Resume Coder notifications:
+
+ $ coder notifications resume
+```
+
+## Subcommands
+
+| Name | Purpose |
+| ------------------------------------------------ | -------------------- |
+| [pause](./notifications_pause.md) | Pause notifications |
+| [resume](./notifications_resume.md) | Resume notifications |
diff --git a/docs/cli/notifications_pause.md b/docs/cli/notifications_pause.md
new file mode 100644
index 0000000000000..0cb2b101d474c
--- /dev/null
+++ b/docs/cli/notifications_pause.md
@@ -0,0 +1,11 @@
+
+
+# notifications pause
+
+Pause notifications
+
+## Usage
+
+```console
+coder notifications pause
+```
diff --git a/docs/cli/notifications_resume.md b/docs/cli/notifications_resume.md
new file mode 100644
index 0000000000000..a8dc17453a383
--- /dev/null
+++ b/docs/cli/notifications_resume.md
@@ -0,0 +1,11 @@
+
+
+# notifications resume
+
+Resume notifications
+
+## Usage
+
+```console
+coder notifications resume
+```
diff --git a/docs/cli/provisionerd.md b/docs/cli/provisionerd.md
index 21af8ff547fcb..44168c53a602d 100644
--- a/docs/cli/provisionerd.md
+++ b/docs/cli/provisionerd.md
@@ -4,6 +4,10 @@
Manage provisioner daemons
+Aliases:
+
+- provisioner
+
## Usage
```console
diff --git a/docs/cli/provisionerd_start.md b/docs/cli/provisionerd_start.md
index b781a4b5fe800..c3ccccbd0e1a1 100644
--- a/docs/cli/provisionerd_start.md
+++ b/docs/cli/provisionerd_start.md
@@ -135,3 +135,12 @@ Serve prometheus metrics on the address defined by prometheus address.
| Default | 127.0.0.1:2112 |
The bind address to serve prometheus metrics.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/server.md b/docs/cli/server.md
index a7c32c2d78420..90034e14b2cc7 100644
--- a/docs/cli/server.md
+++ b/docs/cli/server.md
@@ -514,6 +514,17 @@ Ignore the email_verified claim from the upstream provider.
OIDC claim field to use as the username.
+### --oidc-name-field
+
+| | |
+| ----------- | ----------------------------------- |
+| Type | string |
+| Environment | $CODER_OIDC_NAME_FIELD |
+| YAML | oidc.nameField |
+| Default | name |
+
+OIDC claim field to use as the name.
+
### --oidc-email-field
| | |
@@ -662,6 +673,16 @@ URL pointing to the icon to use on the OpenID Connect login button.
The custom text to show on the error page informing about disabled OIDC signups. Markdown format is supported.
+### --dangerous-oidc-skip-issuer-checks
+
+| | |
+| ----------- | ----------------------------------------------------- |
+| Type | bool |
+| Environment | $CODER_DANGEROUS_OIDC_SKIP_ISSUER_CHECKS |
+| YAML | oidc.dangerousSkipIssuerChecks |
+
+OIDC issuer urls must match in the request, the id_token 'iss' claim, and in the well-known configuration. This flag disables that requirement, and can lead to an insecure OIDC configuration. It is not recommended to use this flag.
+
### --telemetry
| | |
@@ -1183,3 +1204,189 @@ Refresh interval for healthchecks.
| Default | 15ms |
The threshold for the database health check. If the median latency of the database exceeds this threshold over 5 attempts, the database is considered unhealthy. The default value is 15ms.
+
+### --notifications-method
+
+| | |
+| ----------- | ---------------------------------------- |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_METHOD |
+| YAML | notifications.method |
+| Default | smtp |
+
+Which delivery method to use (available options: 'smtp', 'webhook').
+
+### --notifications-dispatch-timeout
+
+| | |
+| ----------- | -------------------------------------------------- |
+| Type | duration |
+| Environment | $CODER_NOTIFICATIONS_DISPATCH_TIMEOUT |
+| YAML | notifications.dispatchTimeout |
+| Default | 1m0s |
+
+How long to wait while a notification is being sent before giving up.
+
+### --notifications-email-from
+
+| | |
+| ----------- | -------------------------------------------- |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_FROM |
+| YAML | notifications.email.from |
+
+The sender's address to use.
+
+### --notifications-email-smarthost
+
+| | |
+| ----------- | ------------------------------------------------- |
+| Type | host:port |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_SMARTHOST |
+| YAML | notifications.email.smarthost |
+| Default | localhost:587 |
+
+The intermediary SMTP host through which emails are sent.
+
+### --notifications-email-hello
+
+| | |
+| ----------- | --------------------------------------------- |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_HELLO |
+| YAML | notifications.email.hello |
+| Default | localhost |
+
+The hostname identifying the SMTP server.
+
+### --notifications-email-force-tls
+
+| | |
+| ----------- | ------------------------------------------------- |
+| Type | bool |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_FORCE_TLS |
+| YAML | notifications.email.forceTLS |
+| Default | false |
+
+Force a TLS connection to the configured SMTP smarthost.
+
+### --notifications-email-auth-identity
+
+| | |
+| ----------- | ----------------------------------------------------- |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_AUTH_IDENTITY |
+| YAML | notifications.email.emailAuth.identity |
+
+Identity to use with PLAIN authentication.
+
+### --notifications-email-auth-username
+
+| | |
+| ----------- | ----------------------------------------------------- |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_AUTH_USERNAME |
+| YAML | notifications.email.emailAuth.username |
+
+Username to use with PLAIN/LOGIN authentication.
+
+### --notifications-email-auth-password
+
+| | |
+| ----------- | ----------------------------------------------------- |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD |
+| YAML | notifications.email.emailAuth.password |
+
+Password to use with PLAIN/LOGIN authentication.
+
+### --notifications-email-auth-password-file
+
+| | |
+| ----------- | ---------------------------------------------------------- |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD_FILE |
+| YAML | notifications.email.emailAuth.passwordFile |
+
+File from which to load password for use with PLAIN/LOGIN authentication.
+
+### --notifications-email-tls-starttls
+
+| | |
+| ----------- | ---------------------------------------------------- |
+| Type | bool |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_TLS_STARTTLS |
+| YAML | notifications.email.emailTLS.startTLS |
+
+Enable STARTTLS to upgrade insecure SMTP connections using TLS.
+
+### --notifications-email-tls-server-name
+
+| | |
+| ----------- | ------------------------------------------------------ |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_TLS_SERVERNAME |
+| YAML | notifications.email.emailTLS.serverName |
+
+Server name to verify against the target certificate.
+
+### --notifications-email-tls-skip-verify
+
+| | |
+| ----------- | ------------------------------------------------------------ |
+| Type | bool |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_TLS_SKIPVERIFY |
+| YAML | notifications.email.emailTLS.insecureSkipVerify |
+
+Skip verification of the target server's certificate (insecure).
+
+### --notifications-email-tls-ca-cert-file
+
+| | |
+| ----------- | ------------------------------------------------------ |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_TLS_CACERTFILE |
+| YAML | notifications.email.emailTLS.caCertFile |
+
+CA certificate file to use.
+
+### --notifications-email-tls-cert-file
+
+| | |
+| ----------- | ---------------------------------------------------- |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_TLS_CERTFILE |
+| YAML | notifications.email.emailTLS.certFile |
+
+Certificate file to use.
+
+### --notifications-email-tls-cert-key-file
+
+| | |
+| ----------- | ------------------------------------------------------- |
+| Type | string |
+| Environment | $CODER_NOTIFICATIONS_EMAIL_TLS_CERTKEYFILE |
+| YAML | notifications.email.emailTLS.certKeyFile |
+
+Certificate key file to use.
+
+### --notifications-webhook-endpoint
+
+| | |
+| ----------- | -------------------------------------------------- |
+| Type | url |
+| Environment | $CODER_NOTIFICATIONS_WEBHOOK_ENDPOINT |
+| YAML | notifications.webhook.endpoint |
+
+The endpoint to which to send webhooks.
+
+### --notifications-max-send-attempts
+
+| | |
+| ----------- | --------------------------------------------------- |
+| Type | int |
+| Environment | $CODER_NOTIFICATIONS_MAX_SEND_ATTEMPTS |
+| YAML | notifications.maxSendAttempts |
+| Default | 5 |
+
+The upper limit of attempts to send a notification.
diff --git a/docs/cli/speedtest.md b/docs/cli/speedtest.md
index e2d3a435fb0ea..ab9d9a4f7e49c 100644
--- a/docs/cli/speedtest.md
+++ b/docs/cli/speedtest.md
@@ -45,3 +45,21 @@ Specifies the duration to monitor traffic.
| Type | string |
Specifies a file to write a network capture to.
+
+### -c, --column
+
+| | |
+| ------- | -------------------------------- |
+| Type | string-array |
+| Default | Interval,Throughput |
+
+Columns to display in table output. Available columns: Interval, Throughput.
+
+### -o, --output
+
+| | |
+| ------- | ------------------- |
+| Type | string |
+| Default | table |
+
+Output format. Available formats: table, json.
diff --git a/docs/cli/templates.md b/docs/cli/templates.md
index c8a0b4376e410..9f3936daf787f 100644
--- a/docs/cli/templates.md
+++ b/docs/cli/templates.md
@@ -18,10 +18,6 @@ coder templates
```console
Templates are written in standard Terraform and describe the infrastructure for workspaces
- - Make changes to your template, and plan the changes:
-
- $ coder templates plan my-template
-
- Create or push an update to the template. Your developers can update their
workspaces:
diff --git a/docs/cli/templates_archive.md b/docs/cli/templates_archive.md
index 04f6d65927a08..a229222addf88 100644
--- a/docs/cli/templates_archive.md
+++ b/docs/cli/templates_archive.md
@@ -27,3 +27,12 @@ Bypass prompts.
| Type | bool |
Include all unused template versions. By default, only failed template versions are archived.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/templates_create.md b/docs/cli/templates_create.md
index de15a9fb905f8..c2ab11bd4916f 100644
--- a/docs/cli/templates_create.md
+++ b/docs/cli/templates_create.md
@@ -105,6 +105,15 @@ Requires workspace builds to use the active template version. This setting does
Bypass prompts.
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
+
### -d, --directory
| | |
diff --git a/docs/cli/templates_delete.md b/docs/cli/templates_delete.md
index aad8ac207f071..55730c7d609d8 100644
--- a/docs/cli/templates_delete.md
+++ b/docs/cli/templates_delete.md
@@ -23,3 +23,12 @@ coder templates delete [flags] [name...]
| Type | bool |
Bypass prompts.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/templates_edit.md b/docs/cli/templates_edit.md
index 45851225f129a..0e47a9b9be6bc 100644
--- a/docs/cli/templates_edit.md
+++ b/docs/cli/templates_edit.md
@@ -171,3 +171,12 @@ Disable the default behavior of granting template access to the 'everyone' group
| Type | bool |
Bypass prompts.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/templates_list.md b/docs/cli/templates_list.md
index 7e418e32c35c2..24eb51fe64e6a 100644
--- a/docs/cli/templates_list.md
+++ b/docs/cli/templates_list.md
@@ -18,12 +18,12 @@ coder templates list [flags]
### -c, --column
-| | |
-| ------- | -------------------------------------- |
-| Type | string-array |
-| Default | name,last updated,used by |
+| | |
+| ------- | -------------------------------------------------------- |
+| Type | string-array |
+| Default | name,organization name,last updated,used by |
-Columns to display in table output. Available columns: name, created at, last updated, organization id, provisioner, active version id, used by, default ttl.
+Columns to display in table output. Available columns: name, created at, last updated, organization id, organization name, provisioner, active version id, used by, default ttl.
### -o, --output
diff --git a/docs/cli/templates_pull.md b/docs/cli/templates_pull.md
index ab99df094ef30..3678426fd098e 100644
--- a/docs/cli/templates_pull.md
+++ b/docs/cli/templates_pull.md
@@ -43,3 +43,12 @@ The name of the template version to pull. Use 'active' to pull the active versio
| Type | bool |
Bypass prompts.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/templates_push.md b/docs/cli/templates_push.md
index aea080a28d186..e56528841ebda 100644
--- a/docs/cli/templates_push.md
+++ b/docs/cli/templates_push.md
@@ -102,3 +102,12 @@ Ignore warnings about not having a .terraform.lock.hcl file present in the templ
| Type | string |
Specify a message describing the changes in this version of the template. Messages longer than 72 characters will be displayed as truncated.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/templates_versions_archive.md b/docs/cli/templates_versions_archive.md
index 3921f6d0032b5..d6053db9ca185 100644
--- a/docs/cli/templates_versions_archive.md
+++ b/docs/cli/templates_versions_archive.md
@@ -19,3 +19,12 @@ coder templates versions archive [flags] bool |
Bypass prompts.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/templates_versions_list.md b/docs/cli/templates_versions_list.md
index 2c6544569dcba..ca42bce770515 100644
--- a/docs/cli/templates_versions_list.md
+++ b/docs/cli/templates_versions_list.md
@@ -20,6 +20,15 @@ coder templates versions list [flags]
Include archived versions in the result list.
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
+
### -c, --column
| | |
diff --git a/docs/cli/templates_versions_unarchive.md b/docs/cli/templates_versions_unarchive.md
index eeedfe26c4d48..7b8d15b4ea21c 100644
--- a/docs/cli/templates_versions_unarchive.md
+++ b/docs/cli/templates_versions_unarchive.md
@@ -19,3 +19,12 @@ coder templates versions unarchive [flags] bool |
Bypass prompts.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/users_create.md b/docs/cli/users_create.md
index 3934f2482ac02..368f049e0a91d 100644
--- a/docs/cli/users_create.md
+++ b/docs/cli/users_create.md
@@ -26,6 +26,14 @@ Specifies an email address for the new user.
Specifies a username for the new user.
+### -n, --full-name
+
+| | |
+| ---- | ------------------- |
+| Type | string |
+
+Specifies an optional human-readable name for the new user.
+
### -p, --password
| | |
@@ -41,3 +49,12 @@ Specifies a password for the new user.
| Type | string |
Optionally specify the login type for the user. Valid values are: password, none, github, oidc. Using 'none' prevents the user from authenticating and requires an API key/token to be generated by an admin.
+
+### -O, --org
+
+| | |
+| ----------- | -------------------------------- |
+| Type | string |
+| Environment | $CODER_ORGANIZATION |
+
+Select which organization (uuid or name) to use.
diff --git a/docs/cli/users_list.md b/docs/cli/users_list.md
index 3ffda880c6dc6..1a7a10b20d057 100644
--- a/docs/cli/users_list.md
+++ b/docs/cli/users_list.md
@@ -21,7 +21,7 @@ coder users list [flags]
| Type | string-array |
| Default | username,email,created_at,status |
-Columns to display in table output. Available columns: id, username, email, created at, status.
+Columns to display in table output. Available columns: id, username, email, created at, updated at, status.
### -o, --output
diff --git a/docs/cli/whoami.md b/docs/cli/whoami.md
new file mode 100644
index 0000000000000..7e2736d454bf4
--- /dev/null
+++ b/docs/cli/whoami.md
@@ -0,0 +1,11 @@
+
+
+# whoami
+
+Fetch authenticated user info for Coder deployment
+
+## Usage
+
+```console
+coder whoami
+```
diff --git a/docs/contributing/feature-stages.md b/docs/contributing/feature-stages.md
index 25b37bbc01863..40926932ca28e 100644
--- a/docs/contributing/feature-stages.md
+++ b/docs/contributing/feature-stages.md
@@ -27,5 +27,12 @@ coder server --experiments=feature1,feature2
# Alternatively, use the `CODER_EXPERIMENTS` environment variable.
```
-For a list of all experiments, refer to the
-[codersdk reference](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#Experiment).
+## Available experimental features
+
+
+
+
+Currently no experimental features are available in the latest mainline or
+stable release.
+
+
diff --git a/docs/faqs.md b/docs/faqs.md
index 9ee9d30ef26e1..8e12b84955279 100644
--- a/docs/faqs.md
+++ b/docs/faqs.md
@@ -37,7 +37,7 @@ The primary developer use case is a local IDE connecting over SSH to a Coder
workspace.
Coder's networking stack has intelligence to attempt a peer-to-peer or
-[Direct connection](https://coder.com/docs/v2/latest/networking#direct-connections)
+[Direct connection](https://coder.com/docs/networking#direct-connections)
between the local IDE and the workspace. However, this requires some additional
protocols like UDP and being able to reach a STUN server to echo the IP
addresses of the local IDE machine and workspace, for sharing using a Wireguard
@@ -52,11 +52,11 @@ to establish these direct connections.
Setting the following flags as shown disables this logic to simplify
troubleshooting.
-| Flag | Value | Meaning |
-| -------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------- |
-| [`CODER_BLOCK_DIRECT`](https://coder.com/docs/v2/latest/cli/server#--block-direct-connections) | `true` | Blocks direct connections |
-| [`CODER_DERP_SERVER_STUN_ADDRESSES`](https://coder.com/docs/v2/latest/cli/server#--derp-server-stun-addresses) | `"disable"` | Disables STUN |
-| [`CODER_DERP_FORCE_WEBSOCKETS`](https://coder.com/docs/v2/latest/cli/server#--derp-force-websockets) | `true` | Forces websockets over Tailscale DERP |
+| Flag | Value | Meaning |
+| ---------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------- |
+| [`CODER_BLOCK_DIRECT`](https://coder.com/docs/cli/server#--block-direct-connections) | `true` | Blocks direct connections |
+| [`CODER_DERP_SERVER_STUN_ADDRESSES`](https://coder.com/docs/cli/server#--derp-server-stun-addresses) | `"disable"` | Disables STUN |
+| [`CODER_DERP_FORCE_WEBSOCKETS`](https://coder.com/docs/cli/server#--derp-force-websockets) | `true` | Forces websockets over Tailscale DERP |
### How do I configure NGINX as the reverse proxy in front of Coder?
@@ -118,8 +118,7 @@ resource "coder_app" "code-server" {
An important concept to understand is that Coder creates workspaces which have
an agent that must be able to reach the `coder server`.
-If the
-[`CODER_ACCESS_URL`](https://coder.com/docs/v2/latest/admin/configure#access-url)
+If the [`CODER_ACCESS_URL`](https://coder.com/docs/admin/configure#access-url)
is not accessible from a workspace, the workspace may build, but the agent
cannot reach Coder, and thus the missing icons. e.g., Terminal, IDEs, Apps.
@@ -149,9 +148,9 @@ of these values can lead to existing workspaces failing to start. This issue
occurs because the Terraform state will not be in sync with the new template.
However, a lesser-known CLI sub-command,
-[`coder update`](https://coder.com/docs/v2/latest/cli/update), can resolve this
-issue. This command re-prompts users to re-enter the input variables,
-potentially saving the workspace from a failed status.
+[`coder update`](https://coder.com/docs/cli/update), can resolve this issue.
+This command re-prompts users to re-enter the input variables, potentially
+saving the workspace from a failed status.
```sh
coder update --always-prompt 
+