Documentation

Author: cschleiden

activitytester/activitytester.go

@@ -8,6 +8,8 @@ import (
 	"github.com/cschleiden/go-workflows/internal/activity"
 )
 
+// WithActivityTestState returns a context with an activity state attached that can be used for unit testing
+// activities.
 func WithActivityTestState(ctx context.Context, activityID, instanceID string, logger *slog.Logger) context.Context {
 	if logger == nil {
 		logger = slog.Default()

backend/tasks.go

@@ -6,6 +6,7 @@ import (
 	"github.com/cschleiden/go-workflows/core"
 )
 
+// WorkflowTask represents work for one workflow execution slice.
 type WorkflowTask struct {
 	// ID is an identifier for this task. It's set by the backend
 	ID string
@@ -27,6 +28,7 @@ type WorkflowTask struct {
 	CustomData any
 }
 
+// ActivityTask represents one activity execution.
 type ActivityTask struct {
 	ID string
 

client/client.go

@@ -42,7 +42,8 @@ func New(backend backend.Backend) *Client {
 	}
 }
 
-func (c *Client) CreateWorkflowInstance(ctx context.Context, options WorkflowInstanceOptions, wf workflow.Workflow, args ...interface{}) (*workflow.Instance, error) {
+// CreateWorkflowInstance creates a new workflow instance of the given workflow.
+func (c *Client) CreateWorkflowInstance(ctx context.Context, options WorkflowInstanceOptions, wf workflow.Workflow, args ...any) (*workflow.Instance, error) {
 	// Check arguments
 	if err := a.ParamsMatch(wf, args...); err != nil {
 		return nil, err
@@ -89,6 +90,7 @@ func (c *Client) CreateWorkflowInstance(ctx context.Context, options WorkflowIns
 	return wfi, nil
 }
 
+// CancelWorkflowInstance cancels a running workflow instance.
 func (c *Client) CancelWorkflowInstance(ctx context.Context, instance *workflow.Instance) error {
 	ctx, span := c.backend.Tracer().Start(ctx, "CancelWorkflowInstance", trace.WithAttributes(
 		attribute.String(log.InstanceIDKey, instance.InstanceID),
@@ -99,7 +101,8 @@ func (c *Client) CancelWorkflowInstance(ctx context.Context, instance *workflow.
 	return c.backend.CancelWorkflowInstance(ctx, instance, cancellationEvent)
 }
 
-func (c *Client) SignalWorkflow(ctx context.Context, instanceID string, name string, arg interface{}) error {
+// SignalWorkflow signals a running workflow instance.
+func (c *Client) SignalWorkflow(ctx context.Context, instanceID string, name string, arg any) error {
 	ctx, span := c.backend.Tracer().Start(ctx, "SignalWorkflow", trace.WithAttributes(
 		attribute.String(log.InstanceIDKey, instanceID),
 		attribute.String(log.SignalNameKey, name),
@@ -131,6 +134,7 @@ func (c *Client) SignalWorkflow(ctx context.Context, instanceID string, name str
 	return nil
 }
 
+// WaitForWorkflowInstance waits for the given workflow instance to finish or until the given timeout has expired.
 func (c *Client) WaitForWorkflowInstance(ctx context.Context, instance *workflow.Instance, timeout time.Duration) error {
 	if timeout == 0 {
 		timeout = time.Second * 20
@@ -226,6 +230,7 @@ func GetWorkflowResult[T any](ctx context.Context, c *Client, instance *workflow
 	return *new(T), errors.New("workflow finished, but could not find result event")
 }
 
+// RemoveWorkflowInstance removes the given workflow instance from the backend.
 func (c *Client) RemoveWorkflowInstance(ctx context.Context, instance *core.WorkflowInstance) error {
 	ctx, span := c.backend.Tracer().Start(ctx, "RemoveWorkflowInstance", trace.WithAttributes(
 		attribute.String(log.InstanceIDKey, instance.InstanceID),

client/stats.go

@@ -6,6 +6,7 @@ import (
 	"github.com/cschleiden/go-workflows/backend"
 )
 
+// GetStats returns backend stats.
 func (c *Client) GetStats(ctx context.Context) (*backend.Stats, error) {
 	return c.backend.GetStats(ctx)
 }

core/instance.go

@@ -1,11 +1,17 @@
 package core
 
 type WorkflowInstance struct {
-	InstanceID  string `json:"instance_id,omitempty"`
+	// InstanceID is the ID of the workflow instance.
+	InstanceID string `json:"instance_id,omitempty"`
+
+	// ExecutionID is the ID of the current execution of the workflow instance.
 	ExecutionID string `json:"execution_id,omitempty"`
 
-	Parent        *WorkflowInstance `json:"parent,omitempty"`
-	ParentEventID int64             `json:"parent_event_id,omitempty"`
+	// Parent refers to the parent workflow instance if this instance is a sub-workflow.
+	Parent *WorkflowInstance `json:"parent,omitempty"`
+
+	// ParentEventID is the ID of the event in the parent workflow that started this sub-workflow.
+	ParentEventID int64 `json:"parent_event_id,omitempty"`
 }
 
 func NewWorkflowInstance(instanceID, executionID string) *WorkflowInstance {

tester/tester.go

@@ -250,15 +250,15 @@ func (wt *workflowTester[TResult]) ListenSubWorkflow(listener func(*core.Workflo
 	wt.subWorkflowListener = listener
 }
 
-func (wt *workflowTester[TResult]) OnActivityByName(name string, activity workflow.Activity, args ...interface{}) *mock.Call {
+func (wt *workflowTester[TResult]) OnActivityByName(name string, activity workflow.Activity, args ...any) *mock.Call {
 	// Register activity so that we can correctly identify its arguments later
 	wt.registry.RegisterActivityByName(name, activity)
 
 	wt.mockedActivities[name] = true
 	return wt.ma.On(name, args...)
 }
 
-func (wt *workflowTester[TResult]) OnActivity(activity workflow.Activity, args ...interface{}) *mock.Call {
+func (wt *workflowTester[TResult]) OnActivity(activity workflow.Activity, args ...any) *mock.Call {
 	// Register activity so that we can correctly identify its arguments later
 	wt.registry.RegisterActivity(activity)
 
@@ -267,15 +267,15 @@ func (wt *workflowTester[TResult]) OnActivity(activity workflow.Activity, args .
 	return wt.ma.On(name, args...)
 }
 
-func (wt *workflowTester[TResult]) OnSubWorkflowByName(name string, workflow workflow.Workflow, args ...interface{}) *mock.Call {
+func (wt *workflowTester[TResult]) OnSubWorkflowByName(name string, workflow workflow.Workflow, args ...any) *mock.Call {
 	// Register workflow so that we can correctly identify its arguments later
 	wt.registry.RegisterWorkflowByName(name, workflow)
 
 	wt.mockedWorkflows[name] = true
 	return wt.mw.On(name, args...)
 }
 
-func (wt *workflowTester[TResult]) OnSubWorkflow(workflow workflow.Workflow, args ...interface{}) *mock.Call {
+func (wt *workflowTester[TResult]) OnSubWorkflow(workflow workflow.Workflow, args ...any) *mock.Call {
 	// Register workflow so that we can correctly identify its arguments later
 	wt.registry.RegisterWorkflow(workflow)
 
@@ -284,7 +284,7 @@ func (wt *workflowTester[TResult]) OnSubWorkflow(workflow workflow.Workflow, arg
 	return wt.mw.On(name, args...)
 }
 
-func (wt *workflowTester[TResult]) Execute(ctx context.Context, args ...interface{}) {
+func (wt *workflowTester[TResult]) Execute(ctx context.Context, args ...any) {
 	for _, propagator := range wt.propagators {
 		if err := propagator.Inject(ctx, wt.wfm); err != nil {
 			panic(fmt.Errorf("failed to inject context: %w", err))