commitintent

Documentation

Overview

Package commitintent defines the durable, pure queue record that sits before an effectful fak commit drain.

The package deliberately does not run git, inspect the live index, take locks, or push. It validates and orders submit records so a later single-writer drain can consume one deterministic stream.

Index

• Constants
• Variables
• func DefaultQueueDir(repoRoot string) string
• func MarshalQueue(q Queue) ([]byte, error)
• func MarshalRecord(rec SubmitRecord) ([]byte, error)
• func NormalizeHexDigest(digest, field string) (string, error)
• func NormalizeID(id string) (string, error)
• func NormalizePath(raw string) (string, error)
• func NormalizePaths(paths []string) ([]string, error)
• func NormalizeSHA(sha string) (string, error)
• func PathDigest(paths []string) string
• func Submit(q Queue, now time.Time, intent Intent) (Queue, SubmitRecord, error)
• func ValidateIntent(in Intent) error
• func ValidateIntentForBase(in Intent, currentBaseSHA string) error
• func ValidateMetadata(meta StampMetadata) error
• func ValidateQueue(q Queue) error
• func ValidateRecord(rec SubmitRecord) error
• func ValidateStamp(stamp Stamp) error
• func ValidateState(state State) error
• func ValidateSubject(subject string) error
• type DrainPlan
  • func Drain(records []SubmitRecord, currentBaseSHA string, limit int) DrainPlan
• type FieldError
  • func (e FieldError) Error() string
  • func (e FieldError) Unwrap() error
• type Intent
  • func NormalizeIntent(in Intent) (Intent, error)
• type InvalidRecord
• type Queue
  • func MarkStates(q Queue, states map[string]State) (Queue, error)
  • func NewQueue() Queue
  • func ParseQueue(data []byte) (Queue, error)
• type Stamp
  • func NormalizeStamp(stamp Stamp, subject string) (Stamp, error)
  • func StampFromSubject(subject string) Stamp
• type StampKind
• type StampMetadata
• type State
• type Store
  • func (s Store) Drain(currentBaseSHA string, limit int) (DrainPlan, error)
  • func (s Store) Load() (Queue, error)
  • func (s Store) MarkStates(states map[string]State) (Queue, error)
  • func (s Store) Submit(intent Intent) (Queue, SubmitRecord, error)
• type SubmitRecord
  • func Ordered(records []SubmitRecord) []SubmitRecord
  • func ParseRecord(data []byte) (SubmitRecord, error)

Constants

const (
	QueueSchema  = "fak.commit-intent.queue.v1"
	RecordSchema = "fak.commit-intent.submit.v1"
)

const (
	StoreDirName   = "commit-intents"
	StoreQueueFile = "queue.json"
	StoreLockFile  = "queue.lock"
)

Variables

var (
	ErrMissingField       = errors.New("commitintent: missing field")
	ErrInvalidField       = errors.New("commitintent: invalid field")
	ErrPathDigestMismatch = errors.New("commitintent: path digest mismatch")
	ErrStaleBase          = errors.New("commitintent: stale base")
)

Functions

func DefaultQueueDir

func DefaultQueueDir(repoRoot string) string

func MarshalQueue

func MarshalQueue(q Queue) ([]byte, error)

func MarshalRecord

func MarshalRecord(rec SubmitRecord) ([]byte, error)

func NormalizeHexDigest

func NormalizeHexDigest(digest, field string) (string, error)

func NormalizeID

func NormalizeID(id string) (string, error)

func NormalizePath

func NormalizePath(raw string) (string, error)

func NormalizePaths

func NormalizePaths(paths []string) ([]string, error)

func NormalizeSHA

func NormalizeSHA(sha string) (string, error)

func PathDigest

func PathDigest(paths []string) string

func Submit

func Submit(q Queue, now time.Time, intent Intent) (Queue, SubmitRecord, error)

func ValidateIntent

func ValidateIntent(in Intent) error

func ValidateIntentForBase

func ValidateIntentForBase(in Intent, currentBaseSHA string) error

func ValidateMetadata

func ValidateMetadata(meta StampMetadata) error

func ValidateQueue

func ValidateQueue(q Queue) error

func ValidateRecord

func ValidateRecord(rec SubmitRecord) error

func ValidateStamp

func ValidateStamp(stamp Stamp) error

func ValidateState

func ValidateState(state State) error

func ValidateSubject

func ValidateSubject(subject string) error

Types

type DrainPlan

type DrainPlan struct {
	Ready   []SubmitRecord  `json:"ready"`
	Stale   []SubmitRecord  `json:"stale"`
	Invalid []InvalidRecord `json:"invalid"`
}

func Drain

func Drain(records []SubmitRecord, currentBaseSHA string, limit int) DrainPlan

type FieldError

type FieldError struct {
	Field  string
	Reason string
	Err    error
}

func (FieldError) Error

func (e FieldError) Error() string

func (FieldError) Unwrap

func (e FieldError) Unwrap() error

type Intent

type Intent struct {
	ID         string        `json:"id"`
	BaseSHA    string        `json:"base_sha"`
	Paths      []string      `json:"paths"`
	PathDigest string        `json:"path_digest"`
	DiffDigest string        `json:"diff_digest,omitempty"`
	Subject    string        `json:"subject"`
	Stamp      Stamp         `json:"stamp"`
	Metadata   StampMetadata `json:"metadata,omitempty"`
}

func NormalizeIntent

func NormalizeIntent(in Intent) (Intent, error)

type InvalidRecord

type InvalidRecord struct {
	Record SubmitRecord `json:"record"`
	Error  string       `json:"error"`
}

type Queue

type Queue struct {
	Schema       string         `json:"schema"`
	NextSequence int64          `json:"next_sequence"`
	Records      []SubmitRecord `json:"records"`
}

func MarkStates

func MarkStates(q Queue, states map[string]State) (Queue, error)

func NewQueue

func NewQueue() Queue

func ParseQueue

func ParseQueue(data []byte) (Queue, error)

type Stamp

type Stamp struct {
	Kind StampKind `json:"kind"`
	Leaf string    `json:"leaf,omitempty"`
	Text string    `json:"text,omitempty"`
}

func NormalizeStamp

func NormalizeStamp(stamp Stamp, subject string) (Stamp, error)

func StampFromSubject

func StampFromSubject(subject string) Stamp

type StampKind

type StampKind string

const (
	StampNone    StampKind = "none"
	StampTrailer StampKind = "trailer"
	StampDirect  StampKind = "direct"
	StampRelease StampKind = "release"
)

type StampMetadata

type StampMetadata struct {
	Issue      int      `json:"issue,omitempty"`
	Generation string   `json:"generation,omitempty"`
	Source     string   `json:"source,omitempty"`
	Requester  string   `json:"requester,omitempty"`
	Labels     []string `json:"labels,omitempty"`
}

type State

type State string

const (
	StatePending  State = "pending"
	StateDraining State = "draining"
	StateDone     State = "done"
	StateFailed   State = "failed"
)

type Store

type Store struct {
	Dir         string
	Now         func() time.Time
	LockTimeout time.Duration
	RetryDelay  time.Duration
}

func (Store) Drain

func (s Store) Drain(currentBaseSHA string, limit int) (DrainPlan, error)

func (Store) Load

func (s Store) Load() (Queue, error)

func (Store) MarkStates

func (s Store) MarkStates(states map[string]State) (Queue, error)

func (Store) Submit

func (s Store) Submit(intent Intent) (Queue, SubmitRecord, error)

type SubmitRecord

type SubmitRecord struct {
	Schema      string    `json:"schema"`
	Sequence    int64     `json:"sequence"`
	SubmittedAt time.Time `json:"submitted_at"`
	State       State     `json:"state"`
	Intent      Intent    `json:"intent"`
}

func Ordered

func Ordered(records []SubmitRecord) []SubmitRecord

func ParseRecord

func ParseRecord(data []byte) (SubmitRecord, error)