types

package
v0.1.17 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package types provides domain value-type helpers and interfaces.

This package is the central home for strongly typed identifiers and value objects used across the system. Subsequent roadmap items will introduce concrete types in the files next to this scaffold.

Package types provides ID generation helpers for KSUID and NanoID-based identifiers. This file centralizes ID generation so call sites do not embed library calls directly.

Index

Constants

View Source 
const LabelJobID = "com.ploy.job_id"

LabelJobID is the container label key storing the job identifier.

View Source 
const LabelRunID = "com.ploy.run_id"

LabelRunID is the container label key storing the run identifier.

Variables

View Source 
var (
	ErrInvalidRunID        = errors.New("invalid run id")
	ErrInvalidWaveID       = errors.New("invalid wave id")
	ErrInvalidJobID        = errors.New("invalid job id")
	ErrInvalidNodeID       = errors.New("invalid node id")
	ErrInvalidMigID        = errors.New("invalid mig id")
	ErrInvalidSpecID       = errors.New("invalid spec id")
	ErrInvalidMigRepoID    = errors.New("invalid mig repo id")
	ErrInvalidRepoID       = errors.New("invalid repo id")
	ErrInvalidDiffID       = errors.New("invalid diff id")
	ErrInvalidSpecBundleID = errors.New("invalid spec bundle id")
)

Validation errors for ID types.

View Source 
var (
	ErrInvalidCPU   = errors.New("invalid cpu")
	ErrInvalidBytes = errors.New("invalid bytes")
	ErrOverflow     = errors.New("overflow")
)

Errors reported by resource parsers.

View Source 
var ErrEmpty = errors.New("empty")

ErrEmpty indicates an empty or whitespace-only value.

View Source 
var ErrInvalidDigest = errors.New("invalid digest")

ErrInvalidDigest indicates the digest format is invalid.

View Source 
var ErrInvalidDuration = errors.New("invalid duration")

ErrInvalidDuration indicates the supplied duration string could not be parsed.

View Source 
var ErrInvalidLogLevel = errors.New("invalid log level")

ErrInvalidLogLevel indicates the log level is unknown.

View Source 
var ErrInvalidMigRef = errors.New("invalid mig ref: contains invalid characters")

ErrInvalidMigRef indicates a MigRef value contains invalid characters.

View Source 
var ErrInvalidProtocol = errors.New("invalid protocol")

ErrInvalidProtocol indicates the protocol is unknown.

View Source 
var ErrInvalidRepoURL = errors.New("invalid repo url")

ErrInvalidRepoURL indicates the value is not an accepted repo URL.

Functions

func IsEmpty 

func IsEmpty(s string) bool

IsEmpty reports whether s is empty after Normalize.

func LabelsForRun 

func LabelsForRun(id RunID) map[string]string

LabelsForRun returns a labels map containing the run identifier. When id is empty, it returns nil.

func LabelsForStep 

func LabelsForStep(id StepID) map[string]string

LabelsForStep returns a labels map containing the step identifier. The value is placed under LabelJobID for downstream correlation. When id is empty, it returns nil.

func MarshalJSONFromText 

func MarshalJSONFromText(v encoding.TextMarshaler) ([]byte, error)

MarshalJSONFromText marshals a TextMarshaler value as a JSON string. Intended for use by domain types that represent string values.

func NewNodeKey 

func NewNodeKey() string

NewNodeKey generates a new unique node identifier using NanoID. Uses a 6-character NanoID with the URL-safe alphabet for compact identifiers suitable for node IDs in nodes.id and node agent configuration. The 6-character length balances brevity with sufficient uniqueness for typical cluster sizes.

func Normalize 

func Normalize(s string) string

Normalize trims surrounding whitespace from s.

func NormalizeRepoURL 

func NormalizeRepoURL(raw string) string

NormalizeRepoURL normalizes a git repository URL for comparison and matching.

The normalization applies the following transformations:

  • Trims leading and trailing whitespace
  • Removes trailing "/" (trailing slash)
  • Removes trailing ".git" suffix

func NormalizeRepoURLSchemless 

func NormalizeRepoURLSchemless(raw string) string

NormalizeRepoURLSchemless returns a scheme-less, display-oriented form of a repository URL.

It is intended for human-facing CLI output (stdout/stderr). It is NOT a wire format, and should not be used for API requests or identity comparisons.

func StdDuration 

func StdDuration(d Duration) time.Duration

StdDuration converts a domain Duration to a time.Duration.

func StringPtr 

func StringPtr[T ~string](v T) *string

StringPtr returns a pointer to the underlying string, or nil for an empty value.

func Strings 

func Strings[T ~string](in []T) []string

Strings converts a slice of string-like domain values to a slice of strings.

func UnmarshalJSONToText 

func UnmarshalJSONToText(data []byte, v encoding.TextUnmarshaler) error

UnmarshalJSONToText unmarshals a JSON string into a TextUnmarshaler. It rejects non-string JSON values.

Types

type Bytes 

type Bytes int64

Bytes is a storage/memory quantity expressed in bytes.

It marshals to/from JSON as a string. Text decoding accepts a plain integer byte count (e.g., "1048576") or common unit suffixes:

  • decimal powers: K, M, G, T, P (10^3 .. 10^15)
  • binary powers: Ki, Mi, Gi, Ti, Pi (2^10 .. 2^50)

An optional trailing 'B' is ignored (e.g., "10GB", "2GiB"). Negative values and unknown suffixes are rejected.

func (Bytes) DockerMemoryBytes 

func (v Bytes) DockerMemoryBytes() int64

DockerMemoryBytes returns the raw bytes to set Docker memory limits.

func (Bytes) MarshalJSON 

func (v Bytes) MarshalJSON() ([]byte, error)

MarshalJSON encodes the value as a JSON string of the raw byte count.

func (Bytes) MarshalText 

func (v Bytes) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. It renders the raw byte count.

func (*Bytes) UnmarshalJSON 

func (v *Bytes) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the value from a JSON string.

func (*Bytes) UnmarshalText 

func (v *Bytes) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (Bytes) Validate 

func (v Bytes) Validate() error

Validate implements Validatable.

type CID 

type CID string

CID is a content identifier for immutable artifact content.

CID values are treated as opaque non-empty strings. They trim surrounding spaces on decode and marshal to/from JSON strings.

func (CID) MarshalJSON 

func (v CID) MarshalJSON() ([]byte, error)

MarshalJSON encodes the value as a JSON string.

func (CID) MarshalText 

func (v CID) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*CID) UnmarshalJSON 

func (v *CID) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the value from a JSON string.

func (*CID) UnmarshalText 

func (v *CID) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (CID) Validate 

func (v CID) Validate() error

Validate implements Validatable.

type CPUmilli 

type CPUmilli int64

CPUmilli is a CPU quantity expressed in milli‑CPUs (1000m = 1 CPU).

It marshals to/from JSON as a string. Text decoding accepts either an integer number of CPUs (e.g., "2") or a milli form with the trailing 'm' suffix (e.g., "500m"). Negative values are rejected.

func (CPUmilli) DockerNanoCPUs 

func (v CPUmilli) DockerNanoCPUs() int64

DockerNanoCPUs returns the Docker NanoCPUs value (1e9 per CPU).

func (CPUmilli) MarshalJSON 

func (v CPUmilli) MarshalJSON() ([]byte, error)

MarshalJSON encodes the value as a JSON string.

func (CPUmilli) MarshalText 

func (v CPUmilli) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*CPUmilli) UnmarshalJSON 

func (v *CPUmilli) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the value from a JSON string.

func (*CPUmilli) UnmarshalText 

func (v *CPUmilli) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (CPUmilli) Validate 

func (v CPUmilli) Validate() error

Validate implements Validatable.

type CommitSHA 

type CommitSHA string

CommitSHA is a Git commit identifier.

It trims surrounding spaces on decode and marshals as a JSON string. Values must be non-empty.

func (CommitSHA) MarshalJSON 

func (v CommitSHA) MarshalJSON() ([]byte, error)

MarshalJSON encodes the value as a JSON string.

func (CommitSHA) MarshalText 

func (v CommitSHA) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (CommitSHA) String 

func (v CommitSHA) String() string

String returns the underlying string value.

func (*CommitSHA) UnmarshalJSON 

func (v *CommitSHA) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the value from a JSON string.

func (*CommitSHA) UnmarshalText 

func (v *CommitSHA) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (CommitSHA) Validate 

func (v CommitSHA) Validate() error

Validate implements Validatable.

type DiffID 

type DiffID string

DiffID identifies a stored diff record. It is UUID-backed and must be a valid UUID string when decoded from text/JSON.

func (DiffID) IsZero 

func (v DiffID) IsZero() bool

IsZero reports whether the value is empty (after trimming spaces).

func (DiffID) MarshalJSON 

func (v DiffID) MarshalJSON() ([]byte, error)

func (DiffID) MarshalText 

func (v DiffID) MarshalText() ([]byte, error)

func (DiffID) String 

func (v DiffID) String() string

String returns the underlying string value.

func (*DiffID) UnmarshalJSON 

func (v *DiffID) UnmarshalJSON(b []byte) error

func (*DiffID) UnmarshalText 

func (v *DiffID) UnmarshalText(b []byte) error

func (DiffID) Validate 

func (v DiffID) Validate() error

Validate verifies the diff ID is non-empty and UUID-parseable.

type DiffJobType 

type DiffJobType string

DiffJobType identifies the diff producer kind stored in diff summaries. 

const (
	DiffJobTypeMig DiffJobType = "mig"
)

func (DiffJobType) String 

func (t DiffJobType) String() string

func (DiffJobType) Validate 

func (t DiffJobType) Validate() error

type DiffSummary 

type DiffSummary json.RawMessage

DiffSummary represents summary metadata attached to a diff.

This type uses json.RawMessage as its backing store instead of map[string]any. This design choice provides several benefits:

  • Eliminates float64/any coercion issues inherent in map[string]any decoding.
  • Improves schema control by preserving the original JSON structure.
  • Enables efficient pass-through when summaries are only relayed (no decode/re-encode).
  • Maintains wire format compatibility with existing producers and consumers.

Typed accessor methods (ExitCode, FilesChanged, etc.) decode only the specific fields they need, avoiding full deserialization overhead.

func (DiffSummary) ExitCode 

func (d DiffSummary) ExitCode() (int, bool)

ExitCode returns the exit_code field as an int when present.

func (DiffSummary) FilesChanged 

func (d DiffSummary) FilesChanged() (int, bool)

FilesChanged returns the files_changed field as an int when present.

func (DiffSummary) IsEmpty 

func (d DiffSummary) IsEmpty() bool

IsEmpty returns true if the summary payload is nil, empty, or represents null/empty object.

func (DiffSummary) JobType 

func (d DiffSummary) JobType() string

JobType returns the job_type field when present. Common value: "mig".

func (DiffSummary) LinesAdded 

func (d DiffSummary) LinesAdded() (int, bool)

LinesAdded returns the lines_added field as an int when present.

func (DiffSummary) LinesRemoved 

func (d DiffSummary) LinesRemoved() (int, bool)

LinesRemoved returns the lines_removed field as an int when present.

func (DiffSummary) MarshalJSON 

func (d DiffSummary) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for DiffSummary.

func (*DiffSummary) UnmarshalJSON 

func (d *DiffSummary) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for DiffSummary.

type DiffSummaryBuilder 

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

DiffSummaryBuilder provides a fluent API for constructing DiffSummary. This replaces map literal construction with a type-safe builder pattern.

func NewDiffSummaryBuilder 

func NewDiffSummaryBuilder() *DiffSummaryBuilder

NewDiffSummaryBuilder creates a new builder for constructing DiffSummary.

func (*DiffSummaryBuilder) Build 

func (b *DiffSummaryBuilder) Build() DiffSummary

Build constructs the final DiffSummary value. Returns nil if all fields are empty/zero.

func (*DiffSummaryBuilder) ExitCode 

func (b *DiffSummaryBuilder) ExitCode(code int) *DiffSummaryBuilder

ExitCode sets the exit_code field.

func (*DiffSummaryBuilder) FilesChanged 

func (b *DiffSummaryBuilder) FilesChanged(count int) *DiffSummaryBuilder

FilesChanged sets the files_changed field.

func (*DiffSummaryBuilder) JobType 

func (b *DiffSummaryBuilder) JobType(jobType string) *DiffSummaryBuilder

JobType sets the job_type field.

func (*DiffSummaryBuilder) LinesAdded 

func (b *DiffSummaryBuilder) LinesAdded(count int) *DiffSummaryBuilder

LinesAdded sets the lines_added field.

func (*DiffSummaryBuilder) LinesRemoved 

func (b *DiffSummaryBuilder) LinesRemoved(count int) *DiffSummaryBuilder

LinesRemoved sets the lines_removed field.

func (*DiffSummaryBuilder) MustBuild 

func (b *DiffSummaryBuilder) MustBuild() DiffSummary

MustBuild constructs the final DiffSummary value, panicking on marshal error. This is useful in tests or when the builder state is guaranteed to be valid.

func (*DiffSummaryBuilder) Timings 

func (b *DiffSummaryBuilder) Timings(hydration, execution, diff, total int64) *DiffSummaryBuilder

Timings sets the timings field from duration values in milliseconds.

type Duration 

type Duration time.Duration

Duration is a thin wrapper over time.Duration that marshals to/from human-readable duration strings (e.g., "1h2m3s").

JSON uses a string representation, and decoding accepts strings parsed via time.ParseDuration with surrounding whitespace trimmed. YAML uses the same string form via custom marshalers.

func FromStdDuration 

func FromStdDuration(d time.Duration) Duration

FromStdDuration converts a time.Duration to a domain Duration.

func (Duration) MarshalJSON 

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON encodes the value as a JSON string.

func (Duration) MarshalText 

func (d Duration) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (Duration) MarshalYAML 

func (d Duration) MarshalYAML() (any, error)

MarshalYAML encodes the value as a YAML string node.

func (Duration) String 

func (d Duration) String() string

String returns the canonical string form.

func (*Duration) UnmarshalJSON 

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the value from a JSON string.

func (*Duration) UnmarshalText 

func (d *Duration) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (*Duration) UnmarshalYAML 

func (d *Duration) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML decodes the value from a YAML node expecting a string.

type EventID 

type EventID int64

EventID identifies an SSE event in a stream for resumption semantics.

func (EventID) Int64 

func (v EventID) Int64() int64

func (EventID) IsZero 

func (v EventID) IsZero() bool

func (EventID) MarshalJSON 

func (v EventID) MarshalJSON() ([]byte, error)

func (EventID) MarshalText 

func (v EventID) MarshalText() ([]byte, error)

func (EventID) String 

func (v EventID) String() string

func (*EventID) UnmarshalJSON 

func (v *EventID) UnmarshalJSON(b []byte) error

func (*EventID) UnmarshalText 

func (v *EventID) UnmarshalText(b []byte) error

func (EventID) Valid 

func (v EventID) Valid() bool

type GitRef 

type GitRef string

GitRef is a Git reference such as a branch or tag name.

It trims surrounding spaces on decode and marshals as a JSON string. Values must be non-empty.

func (GitRef) MarshalJSON 

func (v GitRef) MarshalJSON() ([]byte, error)

MarshalJSON encodes the value as a JSON string.

func (GitRef) MarshalText 

func (v GitRef) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (GitRef) String 

func (v GitRef) String() string

String returns the underlying string value.

func (*GitRef) UnmarshalJSON 

func (v *GitRef) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the value from a JSON string.

func (*GitRef) UnmarshalText 

func (v *GitRef) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (GitRef) Validate 

func (v GitRef) Validate() error

Validate implements Validatable.

type GlobalEnvTarget 

type GlobalEnvTarget string

GlobalEnvTarget identifies the injection target for a global environment variable. It determines which components or job types receive the env var.

Known persisted values:

  • GlobalEnvTargetServer: Inject into the server process
  • GlobalEnvTargetNodes: Inject into node agent processes
  • GlobalEnvTargetGates: Inject into gate jobs (pre_gate, post_gate)
  • GlobalEnvTargetSteps: Inject into step jobs (mig)

Unknown values should be rejected at API boundaries using Validate() or ParseGlobalEnvTarget(). Empty values are rejected (no default target). 

const (
	// GlobalEnvTargetServer injects into the server process.
	GlobalEnvTargetServer GlobalEnvTarget = "server"
	// GlobalEnvTargetNodes injects into node agent processes.
	GlobalEnvTargetNodes GlobalEnvTarget = "nodes"
	// GlobalEnvTargetGates injects into gate jobs (pre_gate, post_gate).
	GlobalEnvTargetGates GlobalEnvTarget = "gates"
	// GlobalEnvTargetSteps injects into step jobs (mig).
	GlobalEnvTargetSteps GlobalEnvTarget = "steps"
)

func ParseGlobalEnvTarget 

func ParseGlobalEnvTarget(s string) (GlobalEnvTarget, error)

ParseGlobalEnvTarget parses a string into a GlobalEnvTarget, returning an error if the value is not one of the known constants. Empty strings are rejected.

func (GlobalEnvTarget) IsZero 

func (t GlobalEnvTarget) IsZero() bool

IsZero reports whether the value is empty (after trimming spaces).

func (GlobalEnvTarget) MatchesJobType 

func (t GlobalEnvTarget) MatchesJobType(jobType JobType) bool

MatchesJobType determines whether this target applies to the given job type (JobType). This is the core target-matching logic for global env var injection.

Target semantics:

  • "gates" → inject into pre_gate and post_gate jobs
  • "steps" → inject into mig jobs
  • "server" / "nodes" → not job-routed (returns false)

func (GlobalEnvTarget) String 

func (t GlobalEnvTarget) String() string

String returns the underlying string value.

func (GlobalEnvTarget) Validate 

func (t GlobalEnvTarget) Validate() error

Validate ensures the value is one of the known GlobalEnvTarget constants. Returns an error for unknown or empty values.

type IDValidator 

type IDValidator interface {
	ValidateID(string) error
}

IDValidator is implemented by tag types that define format validation for an ID.

type JobID 

type JobID = StringID[jobIDTag]

JobID identifies a job within the execution context. Jobs are the unit of work assignment to nodes (claim, execute, complete).

func NewJobID 

func NewJobID() JobID

NewJobID generates a new unique JobID using KSUID. Jobs are the unit of work assignment to nodes, and KSUID provides time-sortable identifiers that allow efficient queries by creation time.

type JobStatus 

type JobStatus string

JobStatus is the canonical per-job lifecycle state. 

const (
	JobStatusCreated   JobStatus = "Created"
	JobStatusQueued    JobStatus = "Queued"
	JobStatusRunning   JobStatus = "Running"
	JobStatusSuccess   JobStatus = "Success"
	JobStatusFail      JobStatus = "Fail"
	JobStatusError     JobStatus = "Error"
	JobStatusCancelled JobStatus = "Cancelled"
)

func ParseJobStatus 

func ParseJobStatus(raw string) (JobStatus, error)

ParseJobStatus parses and validates a canonical job status value.

func (*JobStatus) Scan 

func (s *JobStatus) Scan(src interface{}) error

func (JobStatus) String 

func (s JobStatus) String() string

func (JobStatus) Validate 

func (s JobStatus) Validate() error

func (JobStatus) Value 

func (s JobStatus) Value() (driver.Value, error)

type JobType 

type JobType string

JobType identifies the job phase in the Migs pipeline.

Known values:

  • JobTypePreGate: pre-mig Build Gate
  • JobTypeMig: main mig execution
  • JobTypePostGate: post-mig Build Gate

Unknown or empty values should be treated carefully at boundaries; use JobType.IsZero/Validate to enforce invariants when appropriate. 

const (
	JobTypePreGate  JobType = "pre_gate"
	JobTypeMig      JobType = "mig"
	JobTypePostGate JobType = "post_gate"
)

func (JobType) IsZero 

func (v JobType) IsZero() bool

IsZero reports whether the value is empty (after trimming spaces).

func (JobType) String 

func (v JobType) String() string

String returns the underlying string value.

func (JobType) Validate 

func (v JobType) Validate() error

Validate ensures the value is one of the known JobType constants.

type LogLevel 

type LogLevel string

LogLevel is a logging level enum with canonical string values "debug", "info", "warn", or "error".

It trims surrounding spaces and lower-cases on decode. JSON uses string form. Validation rejects empty and unknown values. 

const (
	// LogLevelDebug is the debug logging level in canonical lowercase form.
	LogLevelDebug LogLevel = "debug"
	// LogLevelInfo is the info logging level in canonical lowercase form.
	LogLevelInfo LogLevel = "info"
	// LogLevelWarn is the warn logging level in canonical lowercase form.
	LogLevelWarn LogLevel = "warn"
	// LogLevelError is the error logging level in canonical lowercase form.
	LogLevelError LogLevel = "error"
)

func (LogLevel) MarshalJSON 

func (l LogLevel) MarshalJSON() ([]byte, error)

MarshalJSON encodes the value as a JSON string.

func (LogLevel) MarshalText 

func (l LogLevel) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (LogLevel) String 

func (l LogLevel) String() string

String returns the underlying level string.

func (*LogLevel) UnmarshalJSON 

func (l *LogLevel) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the value from a JSON string.

func (*LogLevel) UnmarshalText 

func (l *LogLevel) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (LogLevel) Validate 

func (l LogLevel) Validate() error

Validate implements Validatable.

type MigID 

type MigID = StringID[migIDTag]

MigID identifies a mig project. Uses NanoID(6) for compact, URL-safe identifiers suitable for CLI usage and display.

func NewMigID 

func NewMigID() MigID

NewMigID generates a new unique MigID using NanoID. Uses a 6-character NanoID with the URL-safe alphabet. The 6-character length provides sufficient entropy for mig project identifiers while remaining compact for CLI usage and display.

type MigRef 

type MigRef string

MigRef is a reference that can be either a mig ID or a mig name. Used for endpoints that accept "mig id OR name" in the path. This type prevents conflating IDs with names at the type level. Values must be non-empty and URL-safe (no whitespace, no / or ? characters).

func (MigRef) IsZero 

func (v MigRef) IsZero() bool

func (MigRef) MarshalJSON 

func (v MigRef) MarshalJSON() ([]byte, error)

func (MigRef) MarshalText 

func (v MigRef) MarshalText() ([]byte, error)

func (MigRef) String 

func (v MigRef) String() string

func (*MigRef) UnmarshalJSON 

func (v *MigRef) UnmarshalJSON(b []byte) error

func (*MigRef) UnmarshalText 

func (v *MigRef) UnmarshalText(b []byte) error

func (MigRef) Validate 

func (v MigRef) Validate() error

Validate checks that the MigRef is non-empty and URL-safe.

type MigRepoID 

type MigRepoID = StringID[migRepoIDTag]

MigRepoID identifies a repo entry within a mig project. Uses NanoID(8) for per-mig repository identifiers.

func NewMigRepoID 

func NewMigRepoID() MigRepoID

NewMigRepoID generates a new unique MigRepoID using NanoID. Uses an 8-character NanoID with the URL-safe alphabet. The 8-character length provides sufficient entropy for per-mig repo identifiers. Note: This type may also be referred to as "repo_id" in API contexts.

type NodeID 

type NodeID = StringID[nodeIDTag]

NodeID identifies a worker node. Values are operator-chosen URL-safe strings.

type Protocol 

type Protocol string

Protocol is a network protocol enum with canonical string values "tcp" or "udp".

It trims surrounding spaces and lower-cases on decode. JSON uses string form. Validation rejects empty and unknown values. 

const (
	ProtocolTCP Protocol = "tcp"
	// ProtocolUDP is the UDP network protocol in canonical lowercase form.
	ProtocolUDP Protocol = "udp"
)

ProtocolTCP is the TCP network protocol.

It is the canonical lowercase form used for marshaling.

func (Protocol) MarshalJSON 

func (p Protocol) MarshalJSON() ([]byte, error)

MarshalJSON encodes the value as a JSON string.

func (Protocol) MarshalText 

func (p Protocol) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (Protocol) String 

func (p Protocol) String() string

String returns the underlying protocol string.

func (*Protocol) UnmarshalJSON 

func (p *Protocol) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the value from a JSON string.

func (*Protocol) UnmarshalText 

func (p *Protocol) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (Protocol) Validate 

func (p Protocol) Validate() error

Validate implements Validatable.

type RepoID 

type RepoID = StringID[repoIDTag]

RepoID identifies a global repository record. Uses NanoID(8) and maps to repos.id / runs.repo_id / jobs.repo_id.

func NewRepoID 

func NewRepoID() RepoID

NewRepoID generates a new unique global RepoID using NanoID. Uses an 8-character NanoID with the URL-safe alphabet.

type RepoURL 

type RepoURL string

RepoURL is a version control repository URL.

It trims surrounding spaces on decode and marshals as a JSON string. Allowed schemes are https, ssh, and file. Values must be non-empty.

func (RepoURL) MarshalJSON 

func (v RepoURL) MarshalJSON() ([]byte, error)

MarshalJSON encodes the value as a JSON string.

func (RepoURL) MarshalText 

func (v RepoURL) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (RepoURL) String 

func (v RepoURL) String() string

String returns the underlying string value.

func (*RepoURL) UnmarshalJSON 

func (v *RepoURL) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the value from a JSON string.

func (*RepoURL) UnmarshalText 

func (v *RepoURL) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (RepoURL) Validate 

func (v RepoURL) Validate() error

Validate implements Validatable.

type RunCounts 

type RunCounts struct {
	Total         int32  `json:"total"`
	Queued        int32  `json:"queued"`
	Running       int32  `json:"running"`
	Success       int32  `json:"success"`
	Fail          int32  `json:"fail"`
	Cancelled     int32  `json:"cancelled"`
	DerivedStatus string `json:"derived_status"`
}

RunCounts aggregates the count of runs by status within a wave. DerivedStatus provides a single wave-level status derived from run states.

type RunID 

type RunID = StringID[runIDTag]

RunID identifies a run instance (workflow execution).

func NewRunID 

func NewRunID() RunID

NewRunID generates a new unique RunID using KSUID. KSUID provides time-sortable, globally unique identifiers (27 characters). The time-ordering property allows efficient database indexing and querying by creation time without a separate timestamp column.

type RunStats 

type RunStats json.RawMessage

RunStats represents the terminal statistics payload stored on a run.

This type uses json.RawMessage as its backing store instead of map[string]any. This design choice provides several benefits:

  • Eliminates float64/any coercion issues inherent in map[string]any decoding.
  • Improves schema control by preserving the original JSON structure.
  • Enables efficient pass-through when stats are only relayed (no decode/re-encode).
  • Maintains wire format compatibility with existing producers and consumers.

Typed accessor methods (ExitCode, Metadata, GateSummary, etc.) decode only the specific fields they need, avoiding full deserialization overhead.

func (RunStats) ExitCode 

func (s RunStats) ExitCode() (int, bool)

ExitCode returns the exit_code field as an int when present.

func (RunStats) GateSummary 

func (s RunStats) GateSummary() string

GateSummary extracts build gate execution summary from the gate field. Returns a human-readable summary string suitable for CLI/API display. Format: "passed duration=123ms" or "failed pre-gate duration=45ms" or empty if no gate data.

Priority order:

  1. final_gate — The latest post-mig gate result. For runs with no migs executed, final_gate is populated from the pre-mig gate to ensure consistent summary output.
  2. pre_gate — The initial pre-mig gate before any mig execution (fallback when no final_gate).

This priority ensures CLI and API consumers always get the most definitive gate result: final_gate represents the authoritative build validation status at run completion.

func (RunStats) IsEmpty 

func (s RunStats) IsEmpty() bool

IsEmpty returns true if the stats payload is nil, empty, or represents null/empty object.

func (RunStats) LastResumedAt 

func (s RunStats) LastResumedAt() string

LastResumedAt returns the RFC3339 timestamp of the last resume, or empty string if never resumed.

func (RunStats) MarshalJSON 

func (s RunStats) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for RunStats.

func (RunStats) Metadata 

func (s RunStats) Metadata() map[string]string

Metadata returns a copy of the metadata field as map[string]string. Empty strings and whitespace-only values are excluded.

func (RunStats) ResumeCount 

func (s RunStats) ResumeCount() int

ResumeCount returns the number of times this run has been resumed. Returns 0 if never resumed.

func (*RunStats) UnmarshalJSON 

func (s *RunStats) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for RunStats.

type RunStatsBuilder 

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

RunStatsBuilder provides a fluent API for constructing RunStats. This replaces map literal construction with a type-safe builder pattern.

func NewRunStatsBuilder 

func NewRunStatsBuilder() *RunStatsBuilder

NewRunStatsBuilder creates a new builder for constructing RunStats.

func (*RunStatsBuilder) Build 

func (b *RunStatsBuilder) Build() RunStats

Build constructs the final RunStats value. Returns nil if all fields are empty/zero.

func (*RunStatsBuilder) DurationMs 

func (b *RunStatsBuilder) DurationMs(ms int64) *RunStatsBuilder

DurationMs sets the duration_ms field.

func (*RunStatsBuilder) Error 

func (b *RunStatsBuilder) Error(msg string) *RunStatsBuilder

Error sets the error field for failure diagnostics.

func (*RunStatsBuilder) ExitCode 

func (b *RunStatsBuilder) ExitCode(code int) *RunStatsBuilder

ExitCode sets the exit_code field.

func (*RunStatsBuilder) Gate 

func (b *RunStatsBuilder) Gate(passed bool, durationMs int64) *RunStatsBuilder

Gate sets the gate field for gate-only stats (simple pass/fail + duration). The gate is stored as final_gate to align with GateSummary extraction logic.

func (*RunStatsBuilder) GateDetails 

func (b *RunStatsBuilder) GateDetails(gate *RunStatsGate) *RunStatsBuilder

GateDetails sets the full gate object (pre-gate, final gate, resources, etc.).

func (*RunStatsBuilder) JobMeta 

func (b *RunStatsBuilder) JobMeta(meta json.RawMessage) *RunStatsBuilder

JobMeta sets the job_meta field (raw JSON for job metadata).

func (*RunStatsBuilder) JobResources 

func (b *RunStatsBuilder) JobResources(resources *RunStatsJobResources) *RunStatsBuilder

JobResources sets the job_resources field.

func (*RunStatsBuilder) LastResumedAt 

func (b *RunStatsBuilder) LastResumedAt(ts string) *RunStatsBuilder

LastResumedAt sets the last_resumed_at field.

func (*RunStatsBuilder) Metadata 

func (b *RunStatsBuilder) Metadata(meta map[string]string) *RunStatsBuilder

Metadata sets the metadata field.

func (*RunStatsBuilder) MetadataEntry 

func (b *RunStatsBuilder) MetadataEntry(key, value string) *RunStatsBuilder

MetadataEntry adds a single key-value pair to the metadata field.

func (*RunStatsBuilder) MustBuild 

func (b *RunStatsBuilder) MustBuild() RunStats

MustBuild constructs the final RunStats value, panicking on marshal error. This is useful in tests or when the builder state is guaranteed to be valid.

func (*RunStatsBuilder) ResumeCount 

func (b *RunStatsBuilder) ResumeCount(count int) *RunStatsBuilder

ResumeCount sets the resume_count field.

func (*RunStatsBuilder) Timings 

func (b *RunStatsBuilder) Timings(t *runStatsTimings) *RunStatsBuilder

Timings sets the timings field.

func (*RunStatsBuilder) TimingsFromDurations 

func (b *RunStatsBuilder) TimingsFromDurations(hydration, execution, diff, total int64) *RunStatsBuilder

TimingsFromDurations sets the timings field from duration values in milliseconds.

func (*RunStatsBuilder) TimingsWithGate 

func (b *RunStatsBuilder) TimingsWithGate(hydration, execution, gate, diff, total int64) *RunStatsBuilder

TimingsWithGate sets the timings field including build gate duration.

type RunStatsGate 

type RunStatsGate struct {
	Passed     *bool              `json:"passed,omitempty"`
	DurationMs *int64             `json:"duration_ms,omitempty"`
	PreGate    *RunStatsGatePhase `json:"pre_gate,omitempty"`
	FinalGate  *RunStatsGatePhase `json:"final_gate,omitempty"`
}

RunStatsGate represents the gate sub-structure in stats.

type RunStatsGatePhase 

type RunStatsGatePhase struct {
	Passed     bool                   `json:"passed"`
	DurationMs int64                  `json:"duration_ms"`
	Resources  *RunStatsGateResources `json:"resources,omitempty"`
}

RunStatsGatePhase represents a single gate execution phase.

type RunStatsGateResources 

type RunStatsGateResources struct {
	Limits *RunStatsResourceLimits `json:"limits,omitempty"`
	Usage  *RunStatsResourceUsage  `json:"usage,omitempty"`
}

RunStatsGateResources represents resource usage for a gate phase.

type RunStatsJobResources 

type RunStatsJobResources struct {
	CPUConsumedNs     int64 `json:"cpu_consumed_ns,omitempty"`
	DiskConsumedBytes int64 `json:"disk_consumed_bytes,omitempty"`
	MemConsumedBytes  int64 `json:"mem_consumed_bytes,omitempty"`
}

RunStatsJobResources represents per-job container resource consumption.

type RunStatsResourceLimits 

type RunStatsResourceLimits struct {
	NanoCPUs    int64 `json:"nano_cpus,omitempty"`
	MemoryBytes int64 `json:"memory_bytes,omitempty"`
}

RunStatsResourceLimits represents resource limits.

type RunStatsResourceUsage 

type RunStatsResourceUsage struct {
	CPUTotalNs      uint64 `json:"cpu_total_ns,omitempty"`
	MemUsageBytes   uint64 `json:"mem_usage_bytes,omitempty"`
	MemMaxBytes     uint64 `json:"mem_max_bytes,omitempty"`
	BlkioReadBytes  uint64 `json:"blkio_read_bytes,omitempty"`
	BlkioWriteBytes uint64 `json:"blkio_write_bytes,omitempty"`
	SizeRwBytes     int64  `json:"size_rw_bytes,omitempty"`
}

RunStatsResourceUsage represents resource usage.

type RunStatus 

type RunStatus string

RunStatus is the canonical lifecycle status for one repo execution. 

const (
	RunStatusQueued    RunStatus = "Queued"
	RunStatusRunning   RunStatus = "Running"
	RunStatusCancelled RunStatus = "Cancelled"
	RunStatusFail      RunStatus = "Fail"
	RunStatusSuccess   RunStatus = "Success"
)

func (*RunStatus) Scan 

func (s *RunStatus) Scan(src interface{}) error

func (RunStatus) String 

func (s RunStatus) String() string

func (RunStatus) Validate 

func (s RunStatus) Validate() error

func (RunStatus) Value 

func (s RunStatus) Value() (driver.Value, error)

type RunSummary 

type RunSummary struct {
	ID               RunID      `json:"id"`
	Status           RunStatus  `json:"status"`
	MigID            MigID      `json:"mig_id"`
	MigName          string     `json:"mig_name,omitempty"`
	SpecID           SpecID     `json:"spec_id"`
	SpecName         string     `json:"spec_name,omitempty"`
	SpecSourceDomain string     `json:"spec_source_domain,omitempty"`
	SpecSourceRepo   string     `json:"spec_source_repo,omitempty"`
	RepoID           RepoID     `json:"repo_id,omitempty"`
	RepoURL          string     `json:"repo_url,omitempty"`
	BaseRef          string     `json:"base_ref,omitempty"`
	SourceCommitSHA  string     `json:"source_commit_sha,omitempty"`
	Attempt          int32      `json:"attempt,omitempty"`
	LastError        *string    `json:"last_error,omitempty"`
	CreatedBy        *string    `json:"created_by,omitempty"`
	CreatedAt        time.Time  `json:"created_at"`
	StartedAt        *time.Time `json:"started_at,omitempty"`
	FinishedAt       *time.Time `json:"finished_at,omitempty"`
	Counts           *RunCounts `json:"run_counts,omitempty"`
}

RunSummary represents a v1 run summary with optional aggregated wave counts. It is the canonical domain shape for control-plane run summary responses and is shared between server handlers, CLI, and OpenAPI.

type SSEEventType 

type SSEEventType string

SSEEventType identifies the type of an SSE event in the streaming system.

Known values form a closed allow-list:

  • SSEEventLog: structured log record
  • SSEEventRetention: retention hint metadata
  • SSEEventRun: run summary snapshot
  • SSEEventStage: stage status update
  • SSEEventDone: terminal event signaling stream completion

Unknown or empty values are rejected at publish time; use Validate() to enforce invariants at boundaries. 

const (
	SSEEventLog       SSEEventType = "log"
	SSEEventRetention SSEEventType = "retention"
	SSEEventRun       SSEEventType = "run"
	SSEEventStage     SSEEventType = "stage"
	SSEEventDone      SSEEventType = "done"
)

func (SSEEventType) IsZero 

func (v SSEEventType) IsZero() bool

IsZero reports whether the value is empty (after trimming spaces).

func (SSEEventType) String 

func (v SSEEventType) String() string

String returns the underlying string value.

func (SSEEventType) Validate 

func (v SSEEventType) Validate() error

Validate ensures the value is one of the known SSEEventType constants.

type Sha256Digest 

type Sha256Digest string

Sha256Digest is a content digest in the form "sha256:<64-hex>".

It trims surrounding spaces on decode and marshals as a JSON string. Validation enforces the lowercase "sha256:" prefix and a 64-character lowercase hexadecimal payload.

func (Sha256Digest) MarshalJSON 

func (v Sha256Digest) MarshalJSON() ([]byte, error)

MarshalJSON encodes the value as a JSON string.

func (Sha256Digest) MarshalText 

func (v Sha256Digest) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*Sha256Digest) UnmarshalJSON 

func (v *Sha256Digest) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the value from a JSON string.

func (*Sha256Digest) UnmarshalText 

func (v *Sha256Digest) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (Sha256Digest) Validate 

func (v Sha256Digest) Validate() error

Validate implements Validatable.

type SpecBundleID 

type SpecBundleID = StringID[specBundleIDTag]

SpecBundleID identifies a spec bundle upload record in the spec_bundles table. Uses NanoID(8) for stable, URL-safe identifiers.

func NewSpecBundleID 

func NewSpecBundleID() SpecBundleID

NewSpecBundleID generates a new unique SpecBundleID using NanoID. Uses an 8-character NanoID with the URL-safe alphabet. Uses an 8-character NanoID with the URL-safe alphabet.

type SpecID 

type SpecID = StringID[specIDTag]

SpecID identifies a spec instance in the specs table. Uses NanoID(8) for spec identifiers in the append-only specs table.

func NewSpecID 

func NewSpecID() SpecID

NewSpecID generates a new unique SpecID using NanoID. Uses an 8-character NanoID with the URL-safe alphabet. The 8-character length provides sufficient entropy for spec identifiers in the append-only specs table.

type StepID 

type StepID = StringID[stepIDTag]

StepID identifies a step within a stage.

type StringID 

type StringID[T any] string

StringID is a generic string identifier type. The tag type T determines validation behavior: if T implements IDValidator, its ValidateID method is used during text marshaling/unmarshaling; otherwise no validation is applied.

func (StringID[T]) IsZero 

func (v StringID[T]) IsZero() bool

func (StringID[T]) MarshalJSON 

func (v StringID[T]) MarshalJSON() ([]byte, error)

func (StringID[T]) MarshalText 

func (v StringID[T]) MarshalText() ([]byte, error)

func (StringID[T]) String 

func (v StringID[T]) String() string

func (*StringID[T]) UnmarshalJSON 

func (v *StringID[T]) UnmarshalJSON(b []byte) error

func (*StringID[T]) UnmarshalText 

func (v *StringID[T]) UnmarshalText(b []byte) error

type Validatable 

type Validatable interface {
	Validate() error
}

Validatable is implemented by value types that can validate themselves.

type WaveID 

type WaveID = StringID[waveIDTag]

WaveID identifies one launch wave.

func NewWaveID 

func NewWaveID() WaveID

NewWaveID generates a new unique WaveID using KSUID.

type WaveStatus 

type WaveStatus string

WaveStatus is the canonical lifecycle status for a launch wave. 

const (
	WaveStatusStarted   WaveStatus = "Started"
	WaveStatusCancelled WaveStatus = "Cancelled"
	WaveStatusFinished  WaveStatus = "Finished"
)

func (*WaveStatus) Scan 

func (s *WaveStatus) Scan(src interface{}) error

func (WaveStatus) String 

func (s WaveStatus) String() string

func (WaveStatus) Validate 

func (s WaveStatus) Validate() error

func (WaveStatus) Value 

func (s WaveStatus) Value() (driver.Value, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.