feat(operation): introduce operation component

Introducing the first building block for the operations API, this commit introduces the Operation component.

Currently, it does not cover Report, retry policy , those will be in future PRs

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

Author: graham-chainlink

deployment/operations/operation.go

@@ -0,0 +1,85 @@
+package operations
+
+import (
+	"context"
+
+	"github.com/Masterminds/semver/v3"
+	"github.com/google/uuid"
+
+	"github.com/smartcontractkit/chainlink-common/pkg/logger"
+)
+
+// OperationEnv is the env passed to the OperationHandler.
+// It contains the logger and the context.
+// Use NewOperationEnv to create a new OperationEnv.
+type OperationEnv struct {
+	logger     logger.Logger
+	getContext func() context.Context
+}
+
+// NewOperationEnv creates and returns a new OperationEnv.
+func NewOperationEnv(getContext func() context.Context, logger logger.Logger) OperationEnv {
+	return OperationEnv{
+		logger:     logger,
+		getContext: getContext,
+	}
+}
+
+// OperationHandler is the function signature of an operation handler.
+type OperationHandler[I, O, D any] func(e OperationEnv, deps D, input I) (output O, err error)
+
+// OperationDefinition is the metadata of an operation.
+type OperationDefinition struct {
+	ID          string
+	Version     semver.Version
+	Description string
+}
+
+// Operation is the low level building blocks of the Operations API.
+// Developers define their own operation with custom input and output types.
+// Each operation should only perform max 1 side effect (e.g. send a transaction, post a job spec...)
+// Use NewOperation to create a new operation.
+type Operation[Input, Output, Deps any] struct {
+	def     OperationDefinition
+	handler OperationHandler[Input, Output, Deps]
+}
+
+// NewOperation creates a new operation.
+// Note: The handler should only perform maximum 1 side effect.
+func NewOperation[I, O, D any](
+	version semver.Version, description string, handler OperationHandler[I, O, D],
+) *Operation[I, O, D] {
+	return &Operation[I, O, D]{
+		def: OperationDefinition{
+			ID:          uuid.New().String(),
+			Version:     version,
+			Description: description,
+		},
+		handler: handler,
+	}
+}
+
+// Execute runs the operation by calling the OperationHandler.
+func (o *Operation[I, O, D]) Execute(e OperationEnv, deps D, input I) (output O, err error) {
+	e.logger.Infow("Executing operation",
+		"id", o.def.ID, "version", o.def.Version, "description", o.def.Description)
+	return o.handler(e, deps, input)
+}
+
+// ID returns the operation ID.
+func (o *Operation[I, O, D]) ID() string {
+	return o.def.ID
+}
+
+// Version returns the operation semver version in string.
+func (o *Operation[I, O, D]) Version() string {
+	return o.def.Version.String()
+}
+
+// Description returns the operation description.
+func (o *Operation[I, O, D]) Description() string {
+	return o.def.Description
+}
+
+// EmptyInput is a placeholder for operations that do not require input.
+type EmptyInput struct{}

deployment/operations/operation_test.go

@@ -0,0 +1,67 @@
+package operations
+
+import (
+	"context"
+	"testing"
+
+	"github.com/Masterminds/semver/v3"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap/zapcore"
+
+	"github.com/smartcontractkit/chainlink-common/pkg/logger"
+)
+
+type OpDeps struct{}
+
+type OpInput struct {
+	A int
+	B int
+}
+
+func Test_NewOperation(t *testing.T) {
+	version := semver.MustParse("1.0.0")
+	description := "test operation"
+	handler := func(e OperationEnv, deps OpDeps, input OpInput) (output int, err error) {
+		return input.A + input.B, nil
+	}
+
+	op := NewOperation(*version, description, handler)
+
+	assert.Equal(t, version.String(), op.Version())
+	assert.NotEmpty(t, op.ID())
+	assert.Equal(t, description, op.def.Description)
+	res, err := op.handler(OperationEnv{}, OpDeps{}, OpInput{1, 2})
+	require.NoError(t, err)
+	assert.Equal(t, 3, res)
+}
+
+func Test_Operation_Execute(t *testing.T) {
+	version := semver.MustParse("1.0.0")
+	description := "test operation"
+	log, observedLog := logger.TestObserved(t, zapcore.InfoLevel)
+
+	// simulate an addition operation
+	handler := func(e OperationEnv, deps OpDeps, input OpInput) (output int, err error) {
+		return input.A + input.B, nil
+	}
+
+	op := NewOperation(*version, description, handler)
+	e := NewOperationEnv(context.Background, log)
+	input := OpInput{
+		A: 1,
+		B: 2,
+	}
+
+	output, err := op.Execute(e, OpDeps{}, input)
+
+	require.NoError(t, err)
+	assert.Equal(t, 3, output)
+
+	require.Equal(t, 1, observedLog.Len())
+	entry := observedLog.All()[0]
+	assert.Equal(t, "Executing operation", entry.Message)
+	assert.NotEmpty(t, entry.ContextMap()["id"])
+	assert.Equal(t, version.String(), entry.ContextMap()["version"])
+	assert.Equal(t, description, entry.ContextMap()["description"])
+}