Documentation
¶
Overview ¶
Package types provides typed union types for YAML fields that accept multiple formats.
These types provide type-safe unmarshaling with early validation while maintaining full backward compatibility with existing YAML files.
Design principles:
- Each type captures all valid YAML representations for a field
- Validation happens at unmarshal time, not at build time
- Accessor methods provide type-safe access to the parsed values
- IsZero() indicates whether the field was set in YAML
The types in this package are designed to be used as drop-in replacements for `any` typed fields in the spec.definition struct, enabling gradual migration while maintaining backward compatibility.
Index ¶
- type BackoffValue
- type ContinueOnValue
- func (c ContinueOnValue) ExitCode() []int
- func (c ContinueOnValue) Failed() bool
- func (c ContinueOnValue) IsZero() bool
- func (c ContinueOnValue) MarkSuccess() bool
- func (c ContinueOnValue) Output() []string
- func (c ContinueOnValue) Skipped() bool
- func (c *ContinueOnValue) UnmarshalYAML(data []byte) error
- func (c ContinueOnValue) Value() any
- type EnvEntry
- type EnvValue
- type IntOrDynamic
- type LabelEntry
- type LabelsValue
- type LogOutputValue
- type MailToValue
- type ModelEntry
- type ModelValue
- type PortValue
- type RepeatMode
- type ScheduleValue
- func (s ScheduleValue) HasRestartSchedule() bool
- func (s ScheduleValue) HasStopSchedule() bool
- func (s ScheduleValue) IsZero() bool
- func (s ScheduleValue) Restarts() []ir.Schedule
- func (s ScheduleValue) Starts() []ir.Schedule
- func (s ScheduleValue) Stops() []ir.Schedule
- func (s *ScheduleValue) UnmarshalYAML(data []byte) error
- func (s ScheduleValue) Value() any
- type ShellValue
- type StringOrArray
- type TagEntry
- type TagsValue
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BackoffValue ¶
type BackoffValue struct {
// contains filtered or unexported fields
}
BackoffValue represents a backoff multiplier that can be specified as either a boolean (true = default 2.0 multiplier) or a numeric multiplier. The multiplier must be 0 or greater than 1.0 for exponential growth.
YAML examples:
backoff: true backoff: 1.5 backoff: 3
func BackoffValueFromFloat ¶
func BackoffValueFromFloat(f float64) BackoffValue
BackoffValueFromFloat creates a BackoffValue from a float multiplier. No validation is performed; use only with known-valid values.
func (BackoffValue) IsSet ¶
func (b BackoffValue) IsSet() bool
IsSet returns true if the field was explicitly set in YAML.
func (BackoffValue) IsZero ¶
func (b BackoffValue) IsZero() bool
IsZero returns true if the field was not set in YAML.
func (BackoffValue) Multiplier ¶
func (b BackoffValue) Multiplier() float64
Multiplier returns the backoff multiplier value.
func (*BackoffValue) UnmarshalYAML ¶
func (b *BackoffValue) UnmarshalYAML(data []byte) error
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
type ContinueOnValue ¶
type ContinueOnValue struct {
// contains filtered or unexported fields
}
ContinueOnValue represents a continue-on configuration that can be specified as: - A string shorthand: "skipped" or "failed" - A detailed map with configuration options
YAML examples:
continue_on: skipped continue_on: failed continue_on: skipped: true failed: true exit_code: [0, 1] output: ["pattern1", "pattern2"] mark_success: true
func (ContinueOnValue) ExitCode ¶
func (c ContinueOnValue) ExitCode() []int
ExitCode returns exit codes to continue on.
func (ContinueOnValue) Failed ¶
func (c ContinueOnValue) Failed() bool
Failed returns true if should continue on failed.
func (ContinueOnValue) IsZero ¶
func (c ContinueOnValue) IsZero() bool
IsZero returns true if continueOn was not set in YAML.
func (ContinueOnValue) MarkSuccess ¶
func (c ContinueOnValue) MarkSuccess() bool
MarkSuccess returns true if step should be marked as success when condition is met.
func (ContinueOnValue) Output ¶
func (c ContinueOnValue) Output() []string
Output returns output patterns to match.
func (ContinueOnValue) Skipped ¶
func (c ContinueOnValue) Skipped() bool
Skipped returns true if should continue on skipped.
func (*ContinueOnValue) UnmarshalYAML ¶
func (c *ContinueOnValue) UnmarshalYAML(data []byte) error
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
func (ContinueOnValue) Value ¶
func (c ContinueOnValue) Value() any
Value returns the original raw value for error reporting.
type EnvValue ¶
type EnvValue struct {
// contains filtered or unexported fields
}
EnvValue represents environment variable configuration that can be specified as: - A map of key-value pairs - An array of maps (for ordered definitions) - An array of "KEY=value" strings - A mix of maps and strings in an array
YAML examples:
env: KEY1: value1 KEY2: value2 env: - KEY1: value1 - KEY2: value2 env: - KEY1=value1 - KEY2=value2
func (EnvValue) Prepend ¶
Prepend returns a new EnvValue with other's entries before this value's entries.
func (*EnvValue) UnmarshalYAML ¶
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
type IntOrDynamic ¶
type IntOrDynamic struct {
// contains filtered or unexported fields
}
IntOrDynamic represents an integer field that may contain a variable reference (e.g., ${VAR}, $VAR, or backtick command substitutions). It validates eagerly and only defers genuinely dynamic references.
YAML examples:
limit: 3
limit: "5"
limit: $REPEAT_LIMIT
limit: ${REPEAT_LIMIT}
func IntOrDynamicFromInt ¶
func IntOrDynamicFromInt(n int) IntOrDynamic
IntOrDynamicFromInt creates an IntOrDynamic from an integer value.
func IntOrDynamicFromStr ¶
func IntOrDynamicFromStr(s string) IntOrDynamic
IntOrDynamicFromStr creates an IntOrDynamic from a dynamic string reference.
func (IntOrDynamic) IsDynamic ¶
func (d IntOrDynamic) IsDynamic() bool
IsDynamic returns true if the value is a variable reference that must be resolved at runtime.
func (IntOrDynamic) IsZero ¶
func (d IntOrDynamic) IsZero() bool
IsZero returns true if the field was not set in YAML.
func (IntOrDynamic) Str ¶
func (d IntOrDynamic) Str() string
Str returns the raw string if this is a dynamic reference.
func (*IntOrDynamic) UnmarshalYAML ¶
func (d *IntOrDynamic) UnmarshalYAML(data []byte) error
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
type LabelEntry ¶
type LabelEntry struct {
// contains filtered or unexported fields
}
LabelEntry represents a single label entry with key and optional value.
func (LabelEntry) String ¶
func (e LabelEntry) String() string
String returns the canonical string representation. Format: "key=value" or "key" if value is empty.
type LabelsValue ¶
type LabelsValue struct {
// contains filtered or unexported fields
}
LabelsValue represents label configuration that can be specified as:
- A space-separated string: "foo=bar zoo=baz"
- A map of key-value pairs: { foo: bar, zoo: baz }
- An array of strings: ["foo=bar", "simple-label"]
- An array of maps: [{ foo: bar }, { zoo: baz }]
- Backward compatible: ["tag1", "tag2"] or "tag1, tag2"
YAML examples:
labels: "foo=bar zoo=baz" labels: foo: bar zoo: baz labels: - foo=bar - simple-label labels: - production - critical
func (LabelsValue) Entries ¶
func (t LabelsValue) Entries() []LabelEntry
Entries returns the parsed label entries in order.
func (LabelsValue) IsEmpty ¶
func (t LabelsValue) IsEmpty() bool
IsEmpty returns true if labels were set but contain no entries.
func (LabelsValue) IsZero ¶
func (t LabelsValue) IsZero() bool
IsZero returns true if labels were not set in YAML.
func (*LabelsValue) UnmarshalYAML ¶
func (t *LabelsValue) UnmarshalYAML(data []byte) error
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
func (LabelsValue) Value ¶
func (t LabelsValue) Value() any
Value returns the original raw value for error reporting.
func (LabelsValue) Values ¶
func (t LabelsValue) Values() []string
Values returns label entries as strings for backward compatibility. Key-only entries return just the key, key-value entries return "key=value".
type LogOutputValue ¶
type LogOutputValue struct {
// contains filtered or unexported fields
}
LogOutputValue represents a log output configuration that can be unmarshaled from YAML. It accepts a string value that must be one of: "separate" or "merged". This type uses ir.LogOutputMode to avoid type duplication.
func (LogOutputValue) IsMerged ¶
func (l LogOutputValue) IsMerged() bool
IsMerged returns true if the log output mode is merged.
func (LogOutputValue) IsSeparate ¶
func (l LogOutputValue) IsSeparate() bool
IsSeparate returns true if the log output mode is separate.
func (LogOutputValue) IsZero ¶
func (l LogOutputValue) IsZero() bool
IsZero returns true if the value was not set in YAML.
func (LogOutputValue) Mode ¶
func (l LogOutputValue) Mode() ir.LogOutputMode
Mode returns the log output mode. If the value was not set, it returns ir.LogOutputSeparate as the default.
func (LogOutputValue) String ¶
func (l LogOutputValue) String() string
String returns the string representation of the log output mode.
func (*LogOutputValue) UnmarshalYAML ¶
func (l *LogOutputValue) UnmarshalYAML(data []byte) error
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
type MailToValue ¶
type MailToValue = StringOrArray
MailToValue is an alias for StringOrArray used for email recipients. YAML examples:
to: user@example.com to: ["user1@example.com", "user2@example.com"]
type ModelEntry ¶
type ModelEntry struct {
Provider string // Required: LLM provider
Name string // Required: Model name
Temperature *float64 // Optional: Override temperature (0.0-2.0)
MaxTokens *int // Optional: Override max tokens (>=1)
TopP *float64 // Optional: Override top-p (0.0-1.0)
BaseURL string // Optional: Custom API endpoint
APIKeyName string // Optional: API key env var name
}
ModelEntry represents a single model in the model array for fallback support.
type ModelValue ¶
type ModelValue struct {
// contains filtered or unexported fields
}
ModelValue represents an LLM model configuration that can be specified as either a single string (model name) or an array of model entries (for fallback support).
YAML examples:
model: gpt-4o
model:
- provider: openai
name: gpt-4o
max_tokens: 2000
top_p: 0.9
base_url: https://api.example.com
api_key_name: OPENAI_API_KEY
func (ModelValue) Entries ¶
func (m ModelValue) Entries() []ModelEntry
Entries returns the model entries when specified as an array. Returns nil if model was specified as a string.
func (ModelValue) IsArray ¶
func (m ModelValue) IsArray() bool
IsArray returns true if the model was specified as an array.
func (ModelValue) IsZero ¶
func (m ModelValue) IsZero() bool
IsZero returns true if the value was not set in YAML.
func (ModelValue) String ¶
func (m ModelValue) String() string
String returns the model name when specified as a string. Returns empty string if model was specified as an array.
func (*ModelValue) UnmarshalYAML ¶
func (m *ModelValue) UnmarshalYAML(data []byte) error
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
func (ModelValue) Value ¶
func (m ModelValue) Value() any
Value returns the original raw value for error reporting.
type PortValue ¶
type PortValue struct {
// contains filtered or unexported fields
}
PortValue represents a port number that can be specified as either a string or an integer.
YAML examples:
port: 22 port: "22"
func (*PortValue) UnmarshalYAML ¶
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
type RepeatMode ¶
type RepeatMode struct {
// contains filtered or unexported fields
}
RepeatMode represents the repeat mode field that accepts either a boolean (legacy: true maps to "while") or a string ("while" or "until").
YAML examples:
repeat: true repeat: "while" repeat: "until"
func RepeatModeFromBool ¶
func RepeatModeFromBool(b bool) RepeatMode
RepeatModeFromBool creates a RepeatMode from a boolean value. true maps to "while" mode; false returns an unset RepeatMode.
func RepeatModeFromString ¶
func RepeatModeFromString(s string) RepeatMode
RepeatModeFromString creates a RepeatMode from a string value ("while" or "until").
func (RepeatMode) IsBool ¶
func (r RepeatMode) IsBool() bool
IsBool returns true if the original YAML value was a boolean true. This is used for backward compatibility validation (bool true skips the condition requirement check).
func (RepeatMode) IsSet ¶
func (r RepeatMode) IsSet() bool
IsSet returns true if the field was explicitly set in YAML.
func (RepeatMode) IsZero ¶
func (r RepeatMode) IsZero() bool
IsZero returns true if the field was not set in YAML.
func (RepeatMode) String ¶
func (r RepeatMode) String() string
String returns the repeat mode ("while" or "until").
func (*RepeatMode) UnmarshalYAML ¶
func (r *RepeatMode) UnmarshalYAML(data []byte) error
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
type ScheduleValue ¶
type ScheduleValue struct {
// contains filtered or unexported fields
}
ScheduleValue represents a schedule configuration that can be specified as: - A single cron expression string - An array of cron expressions - A map with start/stop/restart keys
YAML examples:
schedule: "0 * * * *" schedule: ["0 * * * *", "30 * * * *"] schedule: start: "0 8 * * *" stop: "0 18 * * *" restart: "0 12 * * *"
func (ScheduleValue) HasRestartSchedule ¶
func (s ScheduleValue) HasRestartSchedule() bool
HasRestartSchedule returns true if restart schedules are configured.
func (ScheduleValue) HasStopSchedule ¶
func (s ScheduleValue) HasStopSchedule() bool
HasStopSchedule returns true if stop schedules are configured.
func (ScheduleValue) IsZero ¶
func (s ScheduleValue) IsZero() bool
IsZero returns true if the schedule was not set in YAML.
func (ScheduleValue) Restarts ¶
func (s ScheduleValue) Restarts() []ir.Schedule
Restarts returns the restart schedules.
func (ScheduleValue) Starts ¶
func (s ScheduleValue) Starts() []ir.Schedule
Starts returns the start/simple schedules.
func (ScheduleValue) Stops ¶
func (s ScheduleValue) Stops() []ir.Schedule
Stops returns the stop schedules.
func (*ScheduleValue) UnmarshalYAML ¶
func (s *ScheduleValue) UnmarshalYAML(data []byte) error
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
func (ScheduleValue) Value ¶
func (s ScheduleValue) Value() any
Value returns the original raw value for error reporting.
type ShellValue ¶
type ShellValue struct {
// contains filtered or unexported fields
}
ShellValue represents a shell configuration that can be specified as either a string (e.g., "bash -e") or an array (e.g., ["bash", "-e"]).
YAML examples:
shell: "bash -e" shell: bash shell: ["bash", "-e"] shell: - bash - -e
func (ShellValue) Arguments ¶
func (s ShellValue) Arguments() []string
Arguments returns the additional shell arguments (only set for array form).
func (ShellValue) Command ¶
func (s ShellValue) Command() string
Command returns the shell command (first element or full string).
func (ShellValue) IsArray ¶
func (s ShellValue) IsArray() bool
IsArray returns true if the value was specified as an array.
func (ShellValue) IsZero ¶
func (s ShellValue) IsZero() bool
IsZero returns true if the shell value was not set in YAML.
func (*ShellValue) UnmarshalYAML ¶
func (s *ShellValue) UnmarshalYAML(data []byte) error
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
func (ShellValue) Value ¶
func (s ShellValue) Value() any
Value returns the original raw value for error reporting.
type StringOrArray ¶
type StringOrArray struct {
// contains filtered or unexported fields
}
StringOrArray represents a value that can be specified as either a single string or an array of strings.
YAML examples:
depends: "step1" depends: ["step1", "step2"] dotenv: ".env" dotenv: [".env", ".env.local"]
func (StringOrArray) IsEmpty ¶
func (s StringOrArray) IsEmpty() bool
IsEmpty returns true if set but contains no values (empty array).
func (StringOrArray) IsZero ¶
func (s StringOrArray) IsZero() bool
IsZero returns true if the value was not set in YAML.
func (*StringOrArray) UnmarshalYAML ¶
func (s *StringOrArray) UnmarshalYAML(data []byte) error
UnmarshalYAML implements BytesUnmarshaler for goccy/go-yaml.
func (StringOrArray) Value ¶
func (s StringOrArray) Value() any
Value returns the original raw value for error reporting.
func (StringOrArray) Values ¶
func (s StringOrArray) Values() []string
Values returns the parsed string values.
type TagEntry ¶
type TagEntry = LabelEntry
type TagsValue ¶
type TagsValue = LabelsValue
Deprecated compatibility aliases. Prefer LabelsValue/LabelEntry in new code.
Source Files