feat: add TemplateBuilderCreateTemplate SDK types and client method (#26360)

Adds `POST /api/v2/templatebuilder/compose/template`, a synchronous endpoint that composes a template from a base and modules, validates it via a provisioner import job, and creates the template in a single request. The handler composes terraform files, bundles them as a tar, inserts the file with hash-based dedup, creates a template version with an import job, waits up to 2 minutes for the job to complete, classifies errors for known failure modes (network-unreachable registry, DNS failures), then creates the template on success. Canceled and failed jobs return appropriate error responses. Also adds `hclwrite.Format` to composed terraform output for canonical HCL formatting. Closes https://linear.app/codercom/issue/DEVEX-279 <details> <summary>Implementation notes</summary> - SDK types and client method in `codersdk/templatebuilder.go` with validation tags matching the standard template creation path (`template_display_name`, `lt=128`) - `ClassifyProvisionerError` in `coderd/templatebuilder/errors.go` detects DNS, connection refused, i/o timeout, and TLS handshake failures and returns actionable messages - `waitForProvisionerJob` polls with a ramp-up interval schedule (100ms, 200ms, 500ms, then 1s steady) and accepts an `onUpdate` callback for future SSE streaming - Audit logging for both template and template version creation - TOCTOU name uniqueness: early check for fast feedback, DB unique constraint catch for the race window (returns 409, not 500) - Swagger annotations for all error responses (400, 404, 409, 504) </details> > 🤖 Generated by Coder Agents
2026-09-22 05:05:20 +08:00 · 2026-06-15 18:12:55 -04:00
parent d8b76831ff
commit de31c7c18e
12 changed files with 1074 additions and 4 deletions
@@ -1,16 +1,38 @@
 package coderd

 import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
 	"net/http"
 	"sort"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/sqlc-dev/pqtype"
+	"golang.org/x/xerrors"

 	"cdr.dev/slog/v3"
+	"github.com/coder/coder/v2/coderd/audit"
+	"github.com/coder/coder/v2/coderd/database"
+	"github.com/coder/coder/v2/coderd/database/db2sdk"
+	"github.com/coder/coder/v2/coderd/database/dbtime"
+	"github.com/coder/coder/v2/coderd/database/provisionerjobs"
 	"github.com/coder/coder/v2/coderd/httpapi"
+	"github.com/coder/coder/v2/coderd/httpmw"
+	"github.com/coder/coder/v2/coderd/provisionerdserver"
 	"github.com/coder/coder/v2/coderd/rbac"
 	"github.com/coder/coder/v2/coderd/rbac/policy"
+	"github.com/coder/coder/v2/coderd/schedule"
 	"github.com/coder/coder/v2/coderd/templatebuilder"
+	"github.com/coder/coder/v2/coderd/tracing"
+	"github.com/coder/coder/v2/coderd/util/namesgenerator"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/examples"
+	"github.com/coder/coder/v2/provisionersdk"
 )

 // @Summary List template builder base templates
@@ -181,3 +203,432 @@ func (api *API) templateBuilderCompose(rw http.ResponseWriter, r *http.Request)
 	rw.WriteHeader(http.StatusOK)
 	_, _ = rw.Write(tarData)
 }
+
+// templateBuilderCreateTemplateTimeout is the maximum time the handler waits
+// for the provisioner import job to complete.
+const templateBuilderCreateTemplateTimeout = 2 * time.Minute
+
+// @Summary Compose and create a template
+// @ID compose-and-create-a-template
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags TemplateBuilder
+// @Param request body codersdk.TemplateBuilderCreateTemplateRequest true "Create template request"
+// @Success 201 {object} codersdk.TemplateBuilderCreateTemplateResponse
+// @Failure 400 {object} codersdk.Response
+// @Failure 404 {object} codersdk.Response
+// @Failure 409 {object} codersdk.Response
+// @Failure 504 {object} codersdk.Response
+// @Router /api/v2/templatebuilder/compose/template [post]
+func (api *API) templateBuilderCreateTemplate(rw http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	apiKey := httpmw.APIKey(r)
+
+	var req codersdk.TemplateBuilderCreateTemplateRequest
+	if !httpapi.Read(ctx, rw, r, &req) {
+		return
+	}
+
+	if req.BaseTemplateID == "" {
+		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
+			Message: "Missing base_template_id.",
+		})
+		return
+	}
+
+	// Resolve and authorize against the organization.
+	organization, err := api.Database.GetOrganizationByID(ctx, req.OrganizationID)
+	if httpapi.Is404Error(err) {
+		httpapi.Write(ctx, rw, http.StatusNotFound, codersdk.Response{
+			Message: "Organization not found.",
+		})
+		return
+	}
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error fetching organization.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	if !api.Authorize(r, policy.ActionCreate, rbac.ResourceTemplate.InOrg(organization.ID)) {
+		httpapi.ResourceNotFound(rw)
+		return
+	}
+
+	// Check template name uniqueness early.
+	_, err = api.Database.GetTemplateByOrganizationAndName(ctx, database.GetTemplateByOrganizationAndNameParams{
+		OrganizationID: organization.ID,
+		Name:           req.Name,
+		Deleted:        false,
+	})
+	if err == nil {
+		httpapi.Write(ctx, rw, http.StatusConflict, codersdk.Response{
+			Message: "A template with this name already exists in the organization.",
+		})
+		return
+	}
+	if !xerrors.Is(err, sql.ErrNoRows) {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error checking template name.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	// Compose the template.
+	composeReq := templatebuilder.ComposeRequest{
+		BaseTemplateID: req.BaseTemplateID,
+		RegistryURL:    api.DeploymentValues.TemplateBuilder.RegistryURL.String(),
+	}
+	for _, m := range req.Modules {
+		composeReq.Modules = append(composeReq.Modules, templatebuilder.ComposeModule{
+			ID:        m.ID,
+			Variables: m.Variables,
+		})
+	}
+
+	result, err := templatebuilder.Compose(composeReq)
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
+			Message: "Failed to compose template.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	tarData, err := templatebuilder.BundleTar(result)
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error bundling template.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	// Insert the tar as a file with hash-based dedup.
+	hashBytes := sha256.Sum256(tarData)
+	hash := hex.EncodeToString(hashBytes[:])
+
+	file, err := api.Database.GetFileByHashAndCreator(ctx, database.GetFileByHashAndCreatorParams{
+		Hash:      hash,
+		CreatedBy: apiKey.UserID,
+	})
+	if err != nil && !xerrors.Is(err, sql.ErrNoRows) {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error checking file.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+	if xerrors.Is(err, sql.ErrNoRows) {
+		file, err = api.Database.InsertFile(ctx, database.InsertFileParams{
+			ID:        uuid.New(),
+			Hash:      hash,
+			CreatedAt: dbtime.Now(),
+			CreatedBy: apiKey.UserID,
+			Mimetype:  codersdk.ContentTypeTar,
+			Data:      tarData,
+		})
+		if err != nil {
+			httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+				Message: "Internal error saving file.",
+				Detail:  err.Error(),
+			})
+			return
+		}
+	}
+
+	tags := provisionersdk.MutateTags(apiKey.UserID, nil, req.ProvisionerTags)
+	traceMetadataRaw, err := json.Marshal(tracing.MetadataFromContext(ctx))
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error marshaling trace metadata.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	// Create template version and provisioner import job.
+	var (
+		provisionerJob  database.ProvisionerJob
+		templateVersion database.TemplateVersion
+	)
+	err = api.Database.InTx(func(tx database.Store) error {
+		jobID := uuid.New()
+		templateVersionID := uuid.New()
+
+		jobInput, err := json.Marshal(provisionerdserver.TemplateVersionImportJob{
+			TemplateVersionID: templateVersionID,
+		})
+		if err != nil {
+			return xerrors.Errorf("marshal job input: %w", err)
+		}
+
+		provisionerJob, err = tx.InsertProvisionerJob(ctx, database.InsertProvisionerJobParams{
+			ID:             jobID,
+			CreatedAt:      dbtime.Now(),
+			UpdatedAt:      dbtime.Now(),
+			OrganizationID: organization.ID,
+			InitiatorID:    apiKey.UserID,
+			Provisioner:    database.ProvisionerTypeTerraform,
+			StorageMethod:  database.ProvisionerStorageMethodFile,
+			FileID:         file.ID,
+			Type:           database.ProvisionerJobTypeTemplateVersionImport,
+			Input:          jobInput,
+			Tags:           tags,
+			TraceMetadata: pqtype.NullRawMessage{
+				Valid:      true,
+				RawMessage: traceMetadataRaw,
+			},
+			LogsOverflowed: false,
+		})
+		if err != nil {
+			return xerrors.Errorf("insert provisioner job: %w", err)
+		}
+
+		versionName := namesgenerator.NameDigitWith("_")
+		err = tx.InsertTemplateVersion(ctx, database.InsertTemplateVersionParams{
+			ID:              templateVersionID,
+			TemplateID:      uuid.NullUUID{},
+			OrganizationID:  organization.ID,
+			CreatedAt:       dbtime.Now(),
+			UpdatedAt:       dbtime.Now(),
+			Name:            versionName,
+			Message:         "",
+			Readme:          "",
+			JobID:           provisionerJob.ID,
+			CreatedBy:       apiKey.UserID,
+			SourceExampleID: sql.NullString{},
+		})
+		if err != nil {
+			return xerrors.Errorf("insert template version: %w", err)
+		}
+
+		templateVersion, err = tx.GetTemplateVersionByID(ctx, templateVersionID)
+		if err != nil {
+			return xerrors.Errorf("get template version: %w", err)
+		}
+
+		return nil
+	}, nil)
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error creating template version.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	// Notify provisioner of the new job.
+	err = provisionerjobs.PostJob(api.Pubsub, provisionerJob)
+	if err != nil {
+		api.Logger.Error(ctx, "failed to post provisioner job",
+			slog.F("job_id", provisionerJob.ID),
+			slog.Error(err))
+	}
+
+	// Wait for the import job to complete.
+	jobCtx, jobCancel := context.WithTimeout(ctx, templateBuilderCreateTemplateTimeout)
+	defer jobCancel()
+
+	completedJob, err := api.waitForProvisionerJob(jobCtx, provisionerJob.ID, nil)
+	if err != nil {
+		if errors.Is(err, context.DeadlineExceeded) {
+			httpapi.Write(ctx, rw, http.StatusGatewayTimeout, codersdk.Response{
+				Message: "Timed out waiting for template import to complete.",
+				Detail:  "The template version is still being imported. You can check its status manually.",
+			})
+			return
+		}
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error waiting for template import.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	// Check if the job was canceled.
+	if completedJob.CanceledAt.Valid {
+		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
+			Message: "Template import was canceled.",
+		})
+		return
+	}
+
+	// Check if the job failed.
+	if completedJob.Error.Valid {
+		// Fetch logs to help classify the error.
+		jobLogs, logErr := api.Database.GetProvisionerLogsAfterID(ctx, database.GetProvisionerLogsAfterIDParams{
+			JobID:        completedJob.ID,
+			CreatedAfter: 0,
+		})
+		var logLines []string
+		if logErr == nil {
+			for _, l := range jobLogs {
+				logLines = append(logLines, l.Output)
+			}
+		}
+
+		classified := templatebuilder.ClassifyProvisionerError(completedJob.Error.String, logLines)
+		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
+			Message: "Template import failed.",
+			Detail:  classified,
+		})
+		return
+	}
+
+	// Audit logging for template and template version creation.
+	var (
+		auditor                            = *api.Auditor.Load()
+		templateAudit, commitTemplateAudit = audit.InitRequest[database.Template](rw, &audit.RequestParams{
+			Audit:          auditor,
+			Log:            api.Logger,
+			Request:        r,
+			Action:         database.AuditActionCreate,
+			OrganizationID: organization.ID,
+		})
+		templateVersionAudit, commitTemplateVersionAudit = audit.InitRequest[database.TemplateVersion](rw, &audit.RequestParams{
+			Audit:          auditor,
+			Log:            api.Logger,
+			Request:        r,
+			Action:         database.AuditActionWrite,
+			OrganizationID: organization.ID,
+		})
+	)
+	defer commitTemplateAudit()
+	defer commitTemplateVersionAudit()
+
+	// Import succeeded. Create the template.
+	defaultGroups := database.TemplateACL{
+		organization.ID.String(): db2sdk.TemplateRoleActions(codersdk.TemplateRoleUse),
+	}
+
+	var dbTemplate database.Template
+	err = api.Database.InTx(func(tx database.Store) error {
+		now := dbtime.Now()
+		templateID := uuid.New()
+
+		err = tx.InsertTemplate(ctx, database.InsertTemplateParams{
+			ID:                           templateID,
+			CreatedAt:                    now,
+			UpdatedAt:                    now,
+			OrganizationID:               organization.ID,
+			Name:                         req.Name,
+			Provisioner:                  database.ProvisionerTypeTerraform,
+			ActiveVersionID:              templateVersion.ID,
+			Description:                  req.Description,
+			CreatedBy:                    apiKey.UserID,
+			UserACL:                      database.TemplateACL{},
+			GroupACL:                     defaultGroups,
+			DisplayName:                  req.DisplayName,
+			Icon:                         req.Icon,
+			AllowUserCancelWorkspaceJobs: false,
+			MaxPortSharingLevel:          database.AppSharingLevelOwner,
+			UseClassicParameterFlow:      false,
+			CorsBehavior:                 database.CorsBehaviorSimple,
+		})
+		if err != nil {
+			if database.IsUniqueViolation(err, database.UniqueTemplatesOrganizationIDNameIndex) {
+				httpapi.Write(ctx, rw, http.StatusConflict, codersdk.Response{
+					Message: "A template with this name already exists in the organization.",
+				})
+				return nil
+			}
+			return xerrors.Errorf("insert template: %w", err)
+		}
+
+		dbTemplate, err = tx.GetTemplateByID(ctx, templateID)
+		if err != nil {
+			return xerrors.Errorf("get template: %w", err)
+		}
+
+		dbTemplate, err = (*api.TemplateScheduleStore.Load()).Set(ctx, tx, dbTemplate, schedule.TemplateScheduleOptions{
+			UserAutostartEnabled: true,
+			UserAutostopEnabled:  true,
+		})
+		if err != nil {
+			return xerrors.Errorf("set template schedule options: %w", err)
+		}
+
+		err = tx.UpdateTemplateVersionByID(ctx, database.UpdateTemplateVersionByIDParams{
+			ID: templateVersion.ID,
+			TemplateID: uuid.NullUUID{
+				UUID:  dbTemplate.ID,
+				Valid: true,
+			},
+			UpdatedAt: dbtime.Now(),
+			Name:      templateVersion.Name,
+			Message:   templateVersion.Message,
+		})
+		if err != nil {
+			return xerrors.Errorf("link template version to template: %w", err)
+		}
+
+		templateAudit.New = dbTemplate
+		newTemplateVersion := templateVersion
+		newTemplateVersion.TemplateID = uuid.NullUUID{
+			UUID:  dbTemplate.ID,
+			Valid: true,
+		}
+		templateVersionAudit.New = newTemplateVersion
+
+		return nil
+	}, nil)
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error creating template.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	httpapi.Write(ctx, rw, http.StatusCreated, codersdk.TemplateBuilderCreateTemplateResponse{
+		Template: api.convertTemplate(dbTemplate),
+	})
+}
+
+// waitForProvisionerJob polls until the job completes or the context expires.
+// If onUpdate is non-nil, it is called after each poll with the latest job state.
+func (api *API) waitForProvisionerJob(
+	ctx context.Context,
+	jobID uuid.UUID,
+	onUpdate func(database.ProvisionerJob),
+) (database.ProvisionerJob, error) {
+	initialIntervals := []time.Duration{
+		100 * time.Millisecond,
+		200 * time.Millisecond,
+		500 * time.Millisecond,
+	}
+	const steadyInterval = time.Second
+
+	for i := 0; ; i++ {
+		var delay time.Duration
+		if i < len(initialIntervals) {
+			delay = initialIntervals[i]
+		} else {
+			delay = steadyInterval
+		}
+
+		select {
+		case <-ctx.Done():
+			return database.ProvisionerJob{}, ctx.Err()
+		case <-time.After(delay):
+		}
+
+		job, err := api.Database.GetProvisionerJobByID(ctx, jobID)
+		if err != nil {
+			return database.ProvisionerJob{}, xerrors.Errorf("get provisioner job: %w", err)
+		}
+
+		if onUpdate != nil {
+			onUpdate(job)
+		}
+
+		if job.CompletedAt.Valid {
+			return job, nil
+		}
+	}
+}