Adds BETA Upload method to StateVersions

Author: brandonc

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ## Enhancements
 * Adds `RunPreApplyRunning` and `RunQueuingApply` run statuses by @uk1288 [#712](https://github.com/hashicorp/go-tfe/pull/712)
+* Adds BETA method `Upload` method to `StateVersions` and support for pending state versions by @brandonc [#717](https://github.com/hashicorp/go-tfe/pull/717)
 
 ## Bug Fixes
 * AgentPool `Update` is not able to remove all allowed workspaces from an agent pool. That operation is now handled by a separate `UpdateAllowedWorkspaces` method using `AgentPoolAllowedWorkspacesUpdateOptions` by @hs26gill [#701](https://github.com/hashicorp/go-tfe/pull/701)

errors.go

@@ -353,4 +353,10 @@ var (
 	ErrRequiredRegistryModule = errors.New("registry module is required")
 
 	ErrTerraformVersionValidForPlanOnly = errors.New("setting terraform-version is only valid when plan-only is set to true")
+
+	ErrStateMustBeOmitted = errors.New("when uploading state, the State and JSONState strings must be omitted from options")
+
+	ErrRequiredRawState = errors.New("RawState is required")
+
+	ErrStateVersionUploadNotSupported = errors.New("upload not supported by this version of Terraform Enterprise")
 )

examples/state_versions/main.go

@@ -0,0 +1,55 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package main
+
+import (
+	"context"
+	"crypto/md5"
+	"fmt"
+	"log"
+	"os"
+
+	tfe "github.com/hashicorp/go-tfe"
+)
+
+func main() {
+	ctx := context.Background()
+	client, err := tfe.NewClient(&tfe.Config{
+		RetryServerErrors: true,
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Lock the workspace
+	if _, err = client.Workspaces.Lock(ctx, "ws-12345678", tfe.WorkspaceLockOptions{}); err != nil {
+		log.Fatal(err)
+	}
+
+	state, err := os.ReadFile("state.json")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Create upload options that does not contain a State attribute within the create options
+	options := tfe.StateVersionUploadOptions{
+		StateVersionCreateOptions: tfe.StateVersionCreateOptions{
+			Lineage: tfe.String("493f7758-da5e-229e-7872-ea1f78ebe50a"),
+			Serial:  tfe.Int64(int64(2)),
+			MD5:     tfe.String(fmt.Sprintf("%x", md5.Sum(state))),
+			Force:   tfe.Bool(false),
+		},
+		RawState: state,
+	}
+
+	// Upload a state version
+	if _, err = client.StateVersions.Upload(ctx, "ws-12345678", options); err != nil {
+		log.Fatal(err)
+	}
+
+	// Unlock the workspace
+	if _, err = client.Workspaces.Unlock(ctx, "ws-12345678"); err != nil {
+		log.Fatal(err)
+	}
+}

examples/state_versions/state.json

@@ -0,0 +1,45 @@
+{
+  "version": 4,
+  "terraform_version": "1.3.9",
+  "serial": 2,
+  "lineage": "493f7758-da5e-229e-7872-ea1f78ebe50a",
+  "outputs": {
+    "name": {
+      "value": "",
+      "type": "string"
+    }
+  },
+  "resources": [
+    {
+      "mode": "managed",
+      "type": "null_resource",
+      "name": "null",
+      "provider": "provider[\"registry.terraform.io/hashicorp/null\"]",
+      "instances": [
+        {
+          "schema_version": 0,
+          "attributes": {
+            "id": "6593301963468675161",
+            "triggers": {
+              "creating": "ai-generated content",
+              "critical": "code",
+              "even": "[2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32, 34, 36, 38, 40, 42, 44, 46, 48, 50]",
+              "happy": "gilmore",
+              "key": "value2",
+              "napkin": "piano",
+              "odd": "[1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29, 31, 33, 35, 37, 39, 41, 43, 45, 47, 49]",
+              "product": "type",
+              "responsible": "damages to your mainframe",
+              "slam": "dunk",
+              "super": "heroes",
+              "system": "or otherwise",
+              "warning": "do not operate"
+            }
+          },
+          "sensitive_attributes": []
+        }
+      ]
+    }
+  ],
+  "check_results": null
+}

go.mod

@@ -12,6 +12,7 @@ require (
 	github.com/hashicorp/go-version v1.6.0
 	github.com/hashicorp/jsonapi v0.0.0-20210826224640-ee7dae0fb22d
 	github.com/stretchr/testify v1.8.4
+	golang.org/x/sync v0.0.0-20210220032951-036812b2e83c
 	golang.org/x/time v0.3.0
 )
 

go.sum

@@ -33,6 +33,7 @@ golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20210220032951-036812b2e83c h1:5KslGYwFpkhGh+Q16bwMP3cOontH8FOep7tGV86Y7SQ=
 golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=

mocks/.DS_Store

@@ -8,12 +8,25 @@ import (
 	"context"
 	"fmt"
 	"net/url"
+	"strings"
 	"time"
+
+	"golang.org/x/sync/errgroup"
 )
 
 // Compile-time proof of interface implementation.
 var _ StateVersions = (*stateVersions)(nil)
 
+// StateVersionStatus are available state version status values
+type StateVersionStatus string
+
+// Available state version statuses.
+const (
+	StateVersionPending   StateVersionStatus = "pending"
+	StateVersionFinalized StateVersionStatus = "finalized"
+	StateVersionDiscarded StateVersionStatus = "discarded"
+)
+
 // StateVersions describes all the state version related methods that
 // the Terraform Enterprise API supports.
 //
@@ -26,6 +39,12 @@ type StateVersions interface {
 	// Create a new state version for the given workspace.
 	Create(ctx context.Context, workspaceID string, options StateVersionCreateOptions) (*StateVersion, error)
 
+	// Upload creates a new state version but uploads the state content directly to the object store.
+	// This is a more resilient form of Create and is the recommended approach to creating state versions.
+	//
+	// **Note: This method is still in BETA and subject to change.**
+	Upload(ctx context.Context, workspaceID string, options StateVersionUploadOptions) (*StateVersion, error)
+
 	// Read a state version by its ID.
 	Read(ctx context.Context, svID string) (*StateVersion, error)
 
@@ -60,12 +79,16 @@ type StateVersionList struct {
 
 // StateVersion represents a Terraform Enterprise state version.
 type StateVersion struct {
-	ID           string    `jsonapi:"primary,state-versions"`
-	CreatedAt    time.Time `jsonapi:"attr,created-at,iso8601"`
-	DownloadURL  string    `jsonapi:"attr,hosted-state-download-url"`
-	Serial       int64     `jsonapi:"attr,serial"`
-	VCSCommitSHA string    `jsonapi:"attr,vcs-commit-sha"`
-	VCSCommitURL string    `jsonapi:"attr,vcs-commit-url"`
+	ID              string             `jsonapi:"primary,state-versions"`
+	CreatedAt       time.Time          `jsonapi:"attr,created-at,iso8601"`
+	DownloadURL     string             `jsonapi:"attr,hosted-state-download-url"`
+	UploadURL       string             `jsonapi:"attr,hosted-state-upload-url"`
+	Status          StateVersionStatus `jsonapi:"attr,status"`
+	JSONUploadURL   string             `jsonapi:"attr,hosted-json-state-upload-url"`
+	JSONDownloadURL string             `jsonapi:"attr,hosted-json-state-download-url"`
+	Serial          int64              `jsonapi:"attr,serial"`
+	VCSCommitSHA    string             `jsonapi:"attr,vcs-commit-sha"`
+	VCSCommitURL    string             `jsonapi:"attr,vcs-commit-url"`
 	// Whether Terraform Cloud has finished populating any StateVersion fields that required async processing.
 	// If `false`, some fields may appear empty even if they should actually contain data; see comments on
 	// individual fields for details.
@@ -147,8 +170,8 @@ type StateVersionCreateOptions struct {
 	// Required: The serial of the state.
 	Serial *int64 `jsonapi:"attr,serial"`
 
-	// Required: The base64 encoded state.
-	State *string `jsonapi:"attr,state"`
+	// Optional: The base64 encoded state.
+	State *string `jsonapi:"attr,state,omitempty"`
 
 	// Optional: Force can be set to skip certain validations. Wrong use
 	// of this flag can cause data loss, so USE WITH CAUTION!
@@ -173,6 +196,13 @@ type StateVersionCreateOptions struct {
 	JSONStateOutputs *string `jsonapi:"attr,json-state-outputs,omitempty"`
 }
 
+type StateVersionUploadOptions struct {
+	StateVersionCreateOptions
+
+	RawState     []byte
+	RawJSONState []byte
+}
+
 type StateVersionModules struct {
 	Root StateVersionModuleRoot `jsonapi:"attr,root"`
 }
@@ -243,6 +273,46 @@ func (s *stateVersions) Create(ctx context.Context, workspaceID string, options
 	return sv, nil
 }
 
+func (s *stateVersions) putURL(ctx context.Context, putURL string, data []byte) error {
+	reader := bytes.NewReader(data)
+	req, err := s.client.NewRequest("PUT", putURL, reader)
+	if err != nil {
+		return err
+	}
+
+	return req.Do(ctx, nil)
+}
+
+func (s *stateVersions) Upload(ctx context.Context, workspaceID string, options StateVersionUploadOptions) (*StateVersion, error) {
+	if err := options.valid(); err != nil {
+		return nil, err
+	}
+
+	sv, err := s.Create(ctx, workspaceID, options.StateVersionCreateOptions)
+	if err != nil {
+		if strings.Contains(err.Error(), "param is missing or the value is empty: state") {
+			return nil, ErrStateVersionUploadNotSupported
+		}
+	}
+
+	g, _ := errgroup.WithContext(ctx)
+	g.Go(func() error {
+		return s.putURL(ctx, sv.UploadURL, options.RawState)
+	})
+	if options.RawJSONState != nil {
+		g.Go(func() error {
+			return s.putURL(ctx, sv.JSONUploadURL, options.RawJSONState)
+		})
+	}
+
+	if err := g.Wait(); err != nil {
+		return nil, err
+	}
+
+	// Re-read the state version to get the updated status, if available
+	return s.Read(ctx, sv.ID)
+}
+
 // Read a state version by its ID.
 func (s *stateVersions) ReadWithOptions(ctx context.Context, svID string, options *StateVersionReadOptions) (*StateVersion, error) {
 	if !validStringID(&svID) {
@@ -362,8 +432,18 @@ func (o StateVersionCreateOptions) valid() error {
 	if o.Serial == nil {
 		return ErrRequiredSerial
 	}
-	if !validString(o.State) {
-		return ErrRequiredState
+	return nil
+}
+
+func (o StateVersionUploadOptions) valid() error {
+	if err := o.StateVersionCreateOptions.valid(); err != nil {
+		return err
+	}
+	if o.State != nil || o.JSONState != nil {
+		return ErrStateMustBeOmitted
+	}
+	if o.RawState == nil {
+		return ErrRequiredRawState
 	}
 	return nil
 }