[CLD-2622]: feat(operations): introduce WithSequenceIdempotencyKey (#1019)

Similar to WithIdempotencyKey for ExecuteOperation, we want to introduce
the same option for Sequence as well.

JIRA: https://smartcontract-it.atlassian.net/browse/CLD-2622

Author: graham-chainlink

.changeset/seven-boxes-poke.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+feat(operations): introduce WithSequenceIdempotencyKey

operations/execute.go

@@ -21,6 +21,15 @@ type ExecuteConfig[IN, DEP any] struct {
 
 type ExecuteOption[IN, DEP any] func(*ExecuteConfig[IN, DEP])
 
+// ExecuteSequenceConfig holds options for ExecuteSequence.
+type ExecuteSequenceConfig[IN, DEP any] struct {
+	// idempotencyKey scopes report reuse beyond sequence definition and input (set by WithSequenceIdempotencyKey).
+	idempotencyKey string
+}
+
+// ExecuteSequenceOption configures ExecuteSequence.
+type ExecuteSequenceOption[IN, DEP any] func(*ExecuteSequenceConfig[IN, DEP])
+
 // ExecuteOperationNConfig holds options for ExecuteOperationN.
 type ExecuteOperationNConfig[IN, DEP any] struct {
 	retryConfig RetryConfig[IN, DEP]
@@ -98,13 +107,20 @@ func WithForceExecute[IN, DEP any]() ExecuteOption[IN, DEP] {
 
 // WithIdempotencyKey is an ExecuteOption that adds an extra component to the idempotency hash.
 // The hash will then be built from the operation definition, input, and this key.
-// Use it when the same operation input can legitimately produce different results, so a later run should not reuse an earlier result.
+// Use it when the same input can legitimately produce different results, so a later run should not reuse an earlier result.
 func WithIdempotencyKey[IN, DEP any](idempotencyKey string) ExecuteOption[IN, DEP] {
 	return func(c *ExecuteConfig[IN, DEP]) {
 		c.idempotencyKey = idempotencyKey
 	}
 }
 
+// WithSequenceIdempotencyKey is an ExecuteSequenceOption with the same semantics as WithIdempotencyKey.
+func WithSequenceIdempotencyKey[IN, DEP any](idempotencyKey string) ExecuteSequenceOption[IN, DEP] {
+	return func(c *ExecuteSequenceConfig[IN, DEP]) {
+		c.idempotencyKey = idempotencyKey
+	}
+}
+
 // WithOperationNRetry is an ExecuteOperationNOption that enables the default retry for each run in ExecuteOperationN.
 func WithOperationNRetry[IN, DEP any]() ExecuteOperationNOption[IN, DEP] {
 	return func(c *ExecuteOperationNConfig[IN, DEP]) {
@@ -315,18 +331,27 @@ func executeWithRetry[IN, OUT, DEP any](
 // Sequences or Operations that were skipped will not be added to the reporter.
 // The ExecutionReports do not include Sequences or Operations that were skipped.
 //
+// Options:
+// ExecuteSequence accepts ExecuteSequenceOption values (for example, WithSequenceIdempotencyKey).
+//
 // Input & Output:
 // The input and output must be JSON serializable. If the input is not serializable, it will return an error.
 // To be serializable, the input and output must be json.marshalable, or it must implement json.Marshaler and json.Unmarshaler.
 // IsSerializable can be used to check if the input or output is serializable.
 func ExecuteSequence[IN, OUT, DEP any](
 	b Bundle, sequence *Sequence[IN, OUT, DEP], deps DEP, input IN,
+	opts ...ExecuteSequenceOption[IN, DEP],
 ) (SequenceReport[IN, OUT], error) {
 	if !IsSerializable(b.Logger, input) {
 		return SequenceReport[IN, OUT]{}, fmt.Errorf("sequence %s input: %w", sequence.def.ID, ErrNotSerializable)
 	}
 
-	if previousReport, ok := loadPreviousSuccessfulReport[IN, OUT](b, sequence.def, input, ""); ok {
+	sequenceConfig := &ExecuteSequenceConfig[IN, DEP]{}
+	for _, opt := range opts {
+		opt(sequenceConfig)
+	}
+
+	if previousReport, ok := loadPreviousSuccessfulReport[IN, OUT](b, sequence.def, input, sequenceConfig.idempotencyKey); ok {
 		executionReports, err := b.reporter.GetExecutionReports(previousReport.ID)
 		if err != nil {
 			return SequenceReport[IN, OUT]{}, err
@@ -369,6 +394,7 @@ func ExecuteSequence[IN, OUT, DEP any](
 		err,
 		childReports...,
 	)
+	report.IdempotencyKey = sequenceConfig.idempotencyKey
 
 	if err = b.reporter.AddReport(genericReport(report)); err != nil {
 		return SequenceReport[IN, OUT]{}, err

operations/execute_test.go

@@ -300,6 +300,66 @@ func Test_ExecuteOperation_ReportJSON_IdempotencyKey(t *testing.T) {
 	})
 }
 
+func Test_ExecuteSequence_ReportJSON_IdempotencyKey(t *testing.T) {
+	t.Parallel()
+
+	version := semver.MustParse("1.0.0")
+	op := NewOperation("plus1", version, "plus 1",
+		func(b Bundle, deps any, input int) (int, error) {
+			return input + 1, nil
+		},
+	)
+	sequence := NewSequence("seq-plus1", version, "plus 1",
+		func(b Bundle, deps any, input int) (int, error) {
+			res, err := ExecuteOperation(b, op, nil, input)
+			if err != nil {
+				return 0, err
+			}
+
+			return res.Output, nil
+		},
+	)
+
+	t.Run("includes idempotencyKey when set", func(t *testing.T) {
+		t.Parallel()
+
+		const idempotencyKey = "chain-42161"
+		bundle := NewBundle(t.Context, logger.Test(t), NewMemoryReporter())
+
+		res, err := ExecuteSequence(bundle, sequence, nil, 1, WithSequenceIdempotencyKey[int, any](idempotencyKey))
+		require.NoError(t, err)
+
+		stored, err := bundle.reporter.GetReport(res.ID)
+		require.NoError(t, err)
+		assert.Equal(t, idempotencyKey, stored.IdempotencyKey)
+
+		raw, err := json.Marshal(stored)
+		require.NoError(t, err)
+
+		var payload map[string]json.RawMessage
+		require.NoError(t, json.Unmarshal(raw, &payload))
+		require.Contains(t, payload, "idempotencyKey")
+		assert.JSONEq(t, `"`+idempotencyKey+`"`, string(payload["idempotencyKey"]))
+	})
+
+	t.Run("omits idempotencyKey when unset", func(t *testing.T) {
+		t.Parallel()
+
+		bundle := NewBundle(t.Context, logger.Test(t), NewMemoryReporter())
+
+		res, err := ExecuteSequence(bundle, sequence, nil, 1)
+		require.NoError(t, err)
+
+		stored, err := bundle.reporter.GetReport(res.ID)
+		require.NoError(t, err)
+		assert.Empty(t, stored.IdempotencyKey)
+
+		raw, err := json.Marshal(stored)
+		require.NoError(t, err)
+		assert.NotContains(t, string(raw), "idempotencyKey")
+	})
+}
+
 func Test_ExecuteOperation_WithPreviousRun_UsesMostRecentSuccessfulReport(t *testing.T) {
 	t.Parallel()
 
@@ -523,6 +583,22 @@ func Test_ExecuteSequence_WithPreviousRun(t *testing.T) {
 	assert.Len(t, res.ExecutionReports, 2) // 1 seq report + 1 op report
 	assert.Equal(t, 2, handlerCalledTimes)
 
+	// same input with a different idempotency key should execute again
+	res, err = ExecuteSequence(bundle, sequence, nil, 1, WithSequenceIdempotencyKey[int, any]("other-key"))
+	require.NoError(t, err)
+	require.Nil(t, res.Err)
+	assert.Equal(t, 2, res.Output)
+	assert.Equal(t, 3, handlerCalledTimes)
+	idempotencyKeyRunID := res.ID
+	assert.NotEqual(t, firstRunID, idempotencyKeyRunID)
+
+	// same input and idempotency key should reuse that sequence report
+	res, err = ExecuteSequence(bundle, sequence, nil, 1, WithSequenceIdempotencyKey[int, any]("other-key"))
+	require.NoError(t, err)
+	require.Nil(t, res.Err)
+	assert.Equal(t, idempotencyKeyRunID, res.ID)
+	assert.Equal(t, 3, handlerCalledTimes)
+
 	// new run with different sequence but same operation, should perform execution
 	sequence = NewSequence("seq-plus1-v2", semver.MustParse("2.0.0"), "plus 1", handler)
 	res, err = ExecuteSequence(bundle, sequence, nil, 1)
@@ -531,7 +607,7 @@ func Test_ExecuteSequence_WithPreviousRun(t *testing.T) {
 	assert.Equal(t, 2, res.Output)
 	// only 1 because the op was not executed due to previous execution found
 	assert.Len(t, res.ExecutionReports, 1)
-	assert.Equal(t, 3, handlerCalledTimes)
+	assert.Equal(t, 4, handlerCalledTimes)
 
 	// new run with sequence that returns error
 	res, err = ExecuteSequence(bundle, sequenceWithError, nil, 1)

operations/report.go

@@ -24,8 +24,9 @@ type Report[IN, OUT any] struct {
 	ChildOperationReports []string `json:"childOperationReports"`
 	// ExecutionSeries is used to track the execution of an operation that was executed multiple times
 	ExecutionSeries *ExecutionSeries `json:"executionSeries,omitempty"`
-	// IdempotencyKey is an additional component of the idempotency hash. This is used when the same operation input
-	// can legitimately produce different results by providing different idempotency keys. Set via WithIdempotencyKey on ExecuteOperation.
+	// IdempotencyKey is an additional component of the idempotency hash. This is used when the same input
+	// can legitimately produce different results by providing different idempotency keys.
+	// Set via WithIdempotencyKey on ExecuteOperation or WithSequenceIdempotencyKey on ExecuteSequence.
 	IdempotencyKey string `json:"idempotencyKey,omitempty"`
 }