statestore: Implement Lock and Unlock for state stores (#1266)

* initial implementation for lock/unlock

* from/to tests

* add fwserver tests

* add initial lock info struct

* build(deps): Bump github.com/hashicorp/copywrite in /tools (#1264)

Bumps [github.com/hashicorp/copywrite](https://github.com/hashicorp/copywrite) from 0.22.0 to 0.24.0.
- [Release notes](https://github.com/hashicorp/copywrite/releases)
- [Commits](hashicorp/copywrite@v0.22.0...v0.24.0)

---
updated-dependencies:
- dependency-name: github.com/hashicorp/copywrite
  dependency-version: 0.24.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* apply steph's suggestion from 1262

* tidy

* package docs

* spelling

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

Author: austinvalle

go.mod

@@ -6,6 +6,7 @@ toolchain go1.24.10
 
 require (
 	github.com/google/go-cmp v0.7.0
+	github.com/hashicorp/go-uuid v1.0.3
 	github.com/hashicorp/terraform-plugin-go v0.29.1-0.20260122204301-b0a6aca80fd7
 	github.com/hashicorp/terraform-plugin-log v0.10.0
 
@@ -16,7 +17,6 @@ require (
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/hashicorp/go-hclog v1.6.3 // indirect
 	github.com/hashicorp/go-plugin v1.7.0 // indirect
-	github.com/hashicorp/go-uuid v1.0.3 // indirect
 	github.com/hashicorp/terraform-registry-address v0.4.0 // indirect
 	github.com/hashicorp/terraform-svchost v0.1.1 // indirect
 	github.com/hashicorp/yamux v0.1.2 // indirect

internal/fromproto6/lockstate.go

@@ -0,0 +1,27 @@
+// Copyright IBM Corp. 2021, 2026
+// SPDX-License-Identifier: MPL-2.0
+
+package fromproto6
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
+
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
+	"github.com/hashicorp/terraform-plugin-framework/statestore"
+)
+
+// LockStateRequest returns the *fwserver.LockStateRequest
+// equivalent of a *tfprotov6.LockStateRequest.
+func LockStateRequest(ctx context.Context, proto6 *tfprotov6.LockStateRequest, reqStateStore statestore.StateStore) *fwserver.LockStateRequest {
+	if proto6 == nil {
+		return nil
+	}
+
+	return &fwserver.LockStateRequest{
+		StateID:    proto6.StateID,
+		Operation:  proto6.Operation,
+		StateStore: reqStateStore,
+	}
+}

internal/fromproto6/lockstate_test.go

@@ -0,0 +1,54 @@
+// Copyright IBM Corp. 2021, 2026
+// SPDX-License-Identifier: MPL-2.0
+
+package fromproto6_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fromproto6"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
+)
+
+func TestLockStateRequest(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		input    *tfprotov6.LockStateRequest
+		expected *fwserver.LockStateRequest
+	}{
+		"nil": {
+			input:    nil,
+			expected: nil,
+		},
+		"empty": {
+			input:    &tfprotov6.LockStateRequest{},
+			expected: &fwserver.LockStateRequest{},
+		},
+		"lockstate": {
+			input: &tfprotov6.LockStateRequest{
+				StateID:   "test-state-123",
+				Operation: "apply",
+			},
+			expected: &fwserver.LockStateRequest{
+				StateID:   "test-state-123",
+				Operation: "apply",
+			},
+		},
+	}
+
+	for name, testCase := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			got := fromproto6.LockStateRequest(context.Background(), testCase.input, nil)
+
+			if diff := cmp.Diff(got, testCase.expected); diff != "" {
+				t.Errorf("unexpected difference: %s", diff)
+			}
+		})
+	}
+}

internal/fromproto6/unlockstate.go

@@ -0,0 +1,27 @@
+// Copyright IBM Corp. 2021, 2026
+// SPDX-License-Identifier: MPL-2.0
+
+package fromproto6
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
+
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
+	"github.com/hashicorp/terraform-plugin-framework/statestore"
+)
+
+// UnlockStateRequest returns the *fwserver.UnlockStateRequest
+// equivalent of a *tfprotov6.UnlockStateRequest.
+func UnlockStateRequest(ctx context.Context, proto6 *tfprotov6.UnlockStateRequest, reqStateStore statestore.StateStore) *fwserver.UnlockStateRequest {
+	if proto6 == nil {
+		return nil
+	}
+
+	return &fwserver.UnlockStateRequest{
+		StateID:    proto6.StateID,
+		LockID:     proto6.LockID,
+		StateStore: reqStateStore,
+	}
+}

internal/fromproto6/unlockstate_test.go

@@ -0,0 +1,54 @@
+// Copyright IBM Corp. 2021, 2026
+// SPDX-License-Identifier: MPL-2.0
+
+package fromproto6_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fromproto6"
+	"github.com/hashicorp/terraform-plugin-framework/internal/fwserver"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
+)
+
+func TestUnlockStateRequest(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		input    *tfprotov6.UnlockStateRequest
+		expected *fwserver.UnlockStateRequest
+	}{
+		"nil": {
+			input:    nil,
+			expected: nil,
+		},
+		"empty": {
+			input:    &tfprotov6.UnlockStateRequest{},
+			expected: &fwserver.UnlockStateRequest{},
+		},
+		"unlockstate": {
+			input: &tfprotov6.UnlockStateRequest{
+				StateID: "test-state-123",
+				LockID:  "test-lock-123",
+			},
+			expected: &fwserver.UnlockStateRequest{
+				StateID: "test-state-123",
+				LockID:  "test-lock-123",
+			},
+		},
+	}
+
+	for name, testCase := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			got := fromproto6.UnlockStateRequest(context.Background(), testCase.input, nil)
+
+			if diff := cmp.Diff(got, testCase.expected); diff != "" {
+				t.Errorf("unexpected difference: %s", diff)
+			}
+		})
+	}
+}

internal/fwserver/server_configurestatestore.go

@@ -18,7 +18,7 @@ import (
 // we could expose this to provider developers in [statestore.InitializeResponse] if controlling
 // the chunk size is desired.
 type ConfigureStateStoreClientCapabilities struct {
-	// ChunkSize is the client-requested size of state byte chunks that are sent between Terraform Core and
+	// ChunkSize is the client-requested size of state byte chunks that are sent between Terraform Core and the provider.
 	// The default chunk size in Terraform core is 8 MB.
 	ChunkSize int64
 }

internal/fwserver/server_lockstate.go

@@ -0,0 +1,66 @@
+// Copyright IBM Corp. 2021, 2026
+// SPDX-License-Identifier: MPL-2.0
+
+package fwserver
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/internal/logging"
+	"github.com/hashicorp/terraform-plugin-framework/statestore"
+)
+
+type LockStateRequest struct {
+	StateID    string
+	Operation  string
+	StateStore statestore.StateStore
+}
+
+type LockStateResponse struct {
+	LockID      string
+	Diagnostics diag.Diagnostics
+}
+
+func (s *Server) LockState(ctx context.Context, req *LockStateRequest, resp *LockStateResponse) {
+	if req == nil {
+		return
+	}
+
+	if stateStoreWithConfigure, ok := req.StateStore.(statestore.StateStoreWithConfigure); ok {
+		logging.FrameworkTrace(ctx, "StateStore implements StateStoreWithConfigure")
+
+		configureReq := statestore.ConfigureRequest{
+			StateStoreData: s.StateStoreConfigureData.StateStoreConfigureData,
+		}
+		configureResp := statestore.ConfigureResponse{}
+
+		logging.FrameworkTrace(ctx, "Calling provider defined StateStore Configure")
+		stateStoreWithConfigure.Configure(ctx, configureReq, &configureResp)
+		logging.FrameworkTrace(ctx, "Called provider defined StateStore Configure")
+
+		resp.Diagnostics.Append(configureResp.Diagnostics...)
+
+		if resp.Diagnostics.HasError() {
+			return
+		}
+	}
+
+	lockReq := statestore.LockRequest{
+		StateID:   req.StateID,
+		Operation: req.Operation,
+	}
+
+	lockResp := statestore.LockResponse{}
+
+	logging.FrameworkTrace(ctx, "Calling provider defined StateStore Lock")
+	req.StateStore.Lock(ctx, lockReq, &lockResp)
+	logging.FrameworkTrace(ctx, "Called provider defined StateStore Lock")
+
+	resp.Diagnostics.Append(lockResp.Diagnostics...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	resp.LockID = lockResp.LockID
+}