repository

package
v0.11.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: EUPL-1.2 Imports: 18 Imported by: 0

Documentation

Overview

Package repository provides infrastructure adapters for workflow and template persistence.

The repository layer implements the WorkflowRepository and TemplateRepository ports from the domain layer, handling YAML file parsing, workflow/template loading, and the mapping between YAML structures and domain entities. This package bridges the domain's abstract persistence contracts with concrete filesystem-based storage.

Architecture Role

In the hexagonal architecture:

  • Implements ports: WorkflowRepository (domain/ports), TemplateRepository (domain/ports)
  • Consumed by: Application services (WorkflowService, TemplateService)
  • Depends on: YAML parsing (gopkg.in/yaml.v3), filesystem (os)

The repository layer isolates YAML syntax details from domain logic, enabling the domain to remain persistence-agnostic. YAML mapping functions translate between yamlWorkflow and workflow.Workflow entities, enforcing domain invariants during deserialization.

Key Types

## YAMLRepository (yaml_repository.go)

Loads workflow definitions from YAML files in a configured base directory.

  • Load: Parse and map YAML file to domain Workflow entity
  • List: Enumerate available workflows
  • Exists: Check workflow file existence

Handles error wrapping (parse errors, missing files) and enforces domain validation during mapping.

## YAMLTemplateRepository (template_repository.go)

Loads workflow templates from YAML files with in-memory caching.

  • GetTemplate: Load and cache template by name
  • ListTemplates: Enumerate available templates from search paths
  • Exists: Check template availability across multiple directories

Supports multiple search paths with cache invalidation and concurrent access via RWMutex.

## CompositeRepository (composite_repository.go)

Aggregates multiple YAMLRepository instances with priority-based resolution. Useful for layered workflow directories (user workflows override system workflows).

  • Load: Search repositories in priority order, return first match
  • List: Merge workflow lists from all repositories (priority order)
  • Exists: Check across all aggregated repositories

## YAML Mapping Layer (yaml_mapper.go, yaml_types.go)

Translates between YAML structures (yamlWorkflow, yamlStep, yamlInput) and domain entities (workflow.Workflow, workflow.Step, workflow.Input).

  • mapToDomain: Convert yamlWorkflow to domain Workflow
  • mapStep: Convert yamlStep to domain Step (dispatches by step type)
  • mapInputs, mapTransitions, mapWorkflowHooks: Field-level conversions

Enforces domain rules (required fields, valid transitions) during deserialization.

Usage Example

// Single directory repository
repo := repository.NewYAMLRepository("./configs/workflows")
wf, err := repo.Load(ctx, "deploy")

// Multi-directory composite with priority
paths := []repository.SourcedPath{
    {Path: "~/.awf/workflows", Source: repository.SourceUser},
    {Path: "./workflows", Source: repository.SourceProject},
    {Path: "/usr/share/awf/workflows", Source: repository.SourceSystem},
}
composite := repository.NewCompositeRepository(paths)
wf, err := composite.Load(ctx, "deploy") // User workflows override system

// Template repository with caching
templateRepo := repository.NewYAMLTemplateRepository([]string{"./templates"})
tmpl, err := templateRepo.GetTemplate(ctx, "http-request")

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CompositeRepository

type CompositeRepository struct {
	// contains filtered or unexported fields
}

CompositeRepository aggregates multiple YAMLRepository instances with priority. Earlier paths take precedence over later ones for workflows with the same name. repos is keyed by sp.Path so that multiple SourcedPath entries sharing the same Source value (e.g. two SourceLocal directories) each retain their own repository.

func NewCompositeRepository

func NewCompositeRepository(paths []SourcedPath) *CompositeRepository

func (*CompositeRepository) Exists

func (r *CompositeRepository) Exists(ctx context.Context, name string) (bool, error)

Exists checks if a workflow exists in any source

func (*CompositeRepository) List

func (r *CompositeRepository) List(ctx context.Context) ([]string, error)

List returns unique workflow names from all sources

func (*CompositeRepository) ListWithSource

func (r *CompositeRepository) ListWithSource(ctx context.Context) ([]ports.WorkflowInfo, error)

ListWithSource returns workflow info including source for each workflow. It implements ports.WorkflowRepository. The returned Source values map the internal Source iota to ports.WorkflowSource strings ("env", "local", "global").

func (*CompositeRepository) Load

Load finds and loads a workflow by name, checking paths in priority order

func (*CompositeRepository) LoadPack added in v0.11.2

func (r *CompositeRepository) LoadPack(ctx context.Context, packName, workflowName string) (*workflow.Workflow, error)

LoadPack loads a workflow from an installed pack directory. It searches the local pack directory first, then falls back to global.

func (*CompositeRepository) SetPackPaths added in v0.11.2

func (r *CompositeRepository) SetPackPaths(localPacksDir, globalPacksDir string)

SetPackPaths configures the local and global workflow pack base directories. localPacksDir is typically .awf/workflow-packs/ and globalPacksDir is the XDG data equivalent.

type ParseError

type ParseError struct {
	File    string // file path
	Line    int    // line number (-1 if unknown)
	Column  int    // column number (-1 if unknown)
	Field   string // field path (e.g., "states.validate.command")
	Message string // error message
	Cause   error  // underlying error
}

ParseError represents an error during YAML parsing.

func NewParseError

func NewParseError(file, field, message string) *ParseError

NewParseError creates a new ParseError with field and message.

func ParseErrorWithLine

func ParseErrorWithLine(file string, line, column int, message string) *ParseError

ParseErrorWithLine creates a ParseError with line information.

func WrapParseError

func WrapParseError(file string, cause error) *ParseError

WrapParseError wraps an existing error as a ParseError. Extracts line and column information from yaml.v3 error messages.

func (*ParseError) Error

func (e *ParseError) Error() string

Error implements the error interface.

func (*ParseError) ToStructuredError

func (e *ParseError) ToStructuredError() *domerrors.StructuredError

ToStructuredError converts ParseError to a domain StructuredError. This enables integration with the error hint system and structured error handling.

Returns:

  • WORKFLOW.PARSE.YAML_SYNTAX for YAML syntax errors
  • Includes file, line, column, and field in error Details

func (*ParseError) Unwrap

func (e *ParseError) Unwrap() error

Unwrap returns the underlying error.

type Source

type Source int

Source indicates where a workflow was discovered

const (
	SourceEnv    Source = iota // AWF_WORKFLOWS_PATH environment variable
	SourceLocal                // ./.awf/workflows/
	SourceGlobal               // $XDG_CONFIG_HOME/awf/workflows/
)

func (Source) String

func (s Source) String() string

type SourcedPath

type SourcedPath struct {
	Path   string
	Source Source
}

SourcedPath represents a workflow directory with its source

type TemplateNotFoundError

type TemplateNotFoundError = workflow.TemplateNotFoundError

TemplateNotFoundError is an alias for workflow.TemplateNotFoundError for backward compatibility. This allows existing infrastructure code to continue using repository.TemplateNotFoundError while the canonical definition lives in the domain layer where it belongs.

type YAMLRepository

type YAMLRepository struct {
	// contains filtered or unexported fields
}

YAMLRepository implements WorkflowRepository for YAML files. When used standalone (outside a CompositeRepository) it reports all workflows as SourceLocal — the caller may override this via WithSource if the repository is known to represent a different discovery origin.

func NewYAMLRepository

func NewYAMLRepository(basePath string) *YAMLRepository

func (*YAMLRepository) Exists

func (r *YAMLRepository) Exists(ctx context.Context, name string) (bool, error)

Exists checks if a workflow file exists.

func (*YAMLRepository) List

func (r *YAMLRepository) List(ctx context.Context) ([]string, error)

List returns all workflow names in the repository.

func (*YAMLRepository) ListWithSource added in v0.11.2

func (r *YAMLRepository) ListWithSource(ctx context.Context) ([]ports.WorkflowInfo, error)

ListWithSource returns all workflow names together with their discovery source. Every entry carries the source configured on this repository (defaultSource), which is SourceLocal unless overridden via WithSource.

func (*YAMLRepository) Load

func (r *YAMLRepository) Load(ctx context.Context, name string) (*workflow.Workflow, error)

Load reads and parses a workflow from a YAML file.

func (*YAMLRepository) WithSource added in v0.11.2

func (r *YAMLRepository) WithSource(s Source) *YAMLRepository

WithSource returns a shallow copy of the repository configured to report the given Source in ListWithSource results. This is used by CompositeRepository to avoid creating separate YAMLRepository types per source.

type YAMLTemplateRepository

type YAMLTemplateRepository struct {
	// contains filtered or unexported fields
}

YAMLTemplateRepository loads templates from YAML files.

func NewYAMLTemplateRepository

func NewYAMLTemplateRepository(searchPaths []string) *YAMLTemplateRepository

NewYAMLTemplateRepository creates a template repository.

func (*YAMLTemplateRepository) Exists

func (r *YAMLTemplateRepository) Exists(_ context.Context, name string) bool

Exists checks if a template exists.

func (*YAMLTemplateRepository) GetTemplate

func (r *YAMLTemplateRepository) GetTemplate(_ context.Context, name string) (*workflow.Template, error)

GetTemplate loads a template by name.

func (*YAMLTemplateRepository) ListTemplates

func (r *YAMLTemplateRepository) ListTemplates(_ context.Context) ([]string, error)

ListTemplates returns all available template names.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL