resultstore

Documentation

Index

• Variables
• type ArtifactEvent
• type ArtifactEventList
• type FS
  • func NewFS(dir string) FS
• type LogLine
  • func (log LogLine) GoString() string
  • func (log LogLine) String() string
• type LogLineReadCloser
• type LogLineWriteCloser
• type StatusList
• type StatusUpdate
• type Store
  • func NewStore(fs FS) Store
  • func NewStoreForBuildID(buildID uint) (Store, error)

Variables

var (
	// ErrFrozen is returned when doing a write operation on a frozen store.
	ErrFrozen = errors.New("store frozen")
	// ErrClosed is returned when doing a read operation on a closed store.
	ErrClosed = errors.New("store closed")
)

var (
	ErrLogWriterAlreadyOpen = errors.New("log write handle is already open for this file")
)

Errors specific to the LogLineWriteCloser

Types

type ArtifactEvent

type ArtifactEvent struct {
	ArtifactID uint64 `json:"artifactId"`
	StepID     uint64 `json:"stepId"`
	Name       string `json:"name"`
}

ArtifactEvent is metadata about an artifact created during building.

type ArtifactEventList

type ArtifactEventList struct {
	LastID         uint64          `json:"lastId"`
	ArtifactEvents []ArtifactEvent `json:"artifactEvents"`
}

ArtifactEventList is a list of artifact events. This is the data structure that is serialized in the artifact event list file for a given step.

type FS

type FS interface {
	// Path returns the root directory of this FS. This is only used in logging,
	// and may return any helpful information.
	Path() string
	// OpenAppend creates or opens a file in append-only mode, meaning all written
	// data is appended to the end.
	OpenAppend(name string) (io.WriteCloser, error)
	// OpenWrite creates or opens a file in write-only mode, meaning all written
	// data is written from the start.
	OpenWrite(name string) (io.WriteCloser, error)
	// OpenRead opens a file in read-only-mode, reading data from the start of
	// the file.
	OpenRead(name string) (io.ReadCloser, error)
	// ListDirEntries will list all files, directories, symlinks, and other entries
	// inside a directory, non-recursively. It does not include the current "."
	// or parent ".." directory names.
	ListDirEntries(name string) ([]fs.DirEntry, error)
}

FS is a filesystem with ability to open files in either append-only, write-only, or read only mode.

func NewFS

func NewFS(dir string) FS

NewFS creates a filesystem that will use the given directory as the base directory when creating or reading files.

type LogLine

type LogLine struct {
	StepID    uint64
	LogID     uint64
	Message   string
	Timestamp time.Time
}

LogLine is a single log line with metadata about its timestamp, ID, and what step it belongs to.

func (LogLine) GoString

func (log LogLine) GoString() string

GoString implements fmt.GoStringer

func (LogLine) String

func (log LogLine) String() string

GoString implements fmt.Stringer

type LogLineReadCloser

type LogLineReadCloser interface {
	io.Closer
	// SetMaxLogID sets the last log ID this reader will read before artificially
	// returning io.EOF in ReadLogLine and ReadLastLogLine. Setting this to zero,
	// which is the default, will disable this functionality.
	SetMaxLogID(logID uint64)
	// ReadLogLine will read the next log line in the file, or return io.EOF
	// when the reader has reached the end of the file.
	ReadLogLine() (LogLine, error)
	// ReadLastLogLine will read the entire file and return the last log line
	// in the file. Wil return io.EOF if the file is empty.
	ReadLastLogLine() (LogLine, error)
}

LogLineReadCloser is the interface for reading log lines and ability to close the file handle.

type LogLineWriteCloser

type LogLineWriteCloser interface {
	io.Closer
	// WriteLogLine will write the log line to the file and publish a parsed
	// LogLine to any active subscriptions. An error is returned if it failed
	// to write, such as if the file system has run out of disk space or if the
	// file was removed.
	WriteLogLine(line string) (LogLine, error)
}

LogLineWriteCloser is the interface for writing log lines and ability to close the file handle.

type StatusList

type StatusList struct {
	LastID        uint64         `json:"lastId"`
	StatusUpdates []StatusUpdate `json:"statusUpdates"`
}

StatusList is a list of status updates. This is the data structure that is serialized in the status update list file for a given step.

type StatusUpdate

type StatusUpdate struct {
	StepID    uint64             `json:"-"`
	UpdateID  uint64             `json:"updateId"`
	Timestamp time.Time          `json:"timestamp"`
	Status    workermodel.Status `json:"status"`
}

StatusUpdate is an update to a status of a build step.

type Store

type Store interface {
	// Path returns the path where this Store is saving all build results.
	// This is only used for logging, and can return any helpful information.
	Path() string

	// OpenLogWriter opens a file handle abstraction for writing log lines. Logs
	// will be automatically parsed when written and published to any active
	// subscriptions.
	//
	// Will return ErrFrozen if the store is frozen.
	OpenLogWriter(stepID uint64) (LogLineWriteCloser, error)

	// OpenLogReader opens a file handle abstraction for reading log lines. Logs
	// will be automatically parsed when read.
	//
	// Will return fs.ErrNotExist if the log file does not exist yet.
	OpenLogReader(stepID uint64) (LogLineReadCloser, error)

	// SubAllLogLines creates a new channel that streams all log lines
	// from this result store since the beginning, and keeps on streaming new
	// updates until unsubscribed.
	SubAllLogLines(buffer int) (<-chan LogLine, error)

	// UnsubAllLogLines unsubscribes a subscription of all status updates
	// created via SubAllLogLines.
	UnsubAllLogLines(ch <-chan LogLine) error

	// AddStatusUpdate adds a status update to a step. If the latest status
	// update found for the step is the same as the new status, then this
	// status update is skipped. Any written status update is also published to
	// any active subscriptions.
	//
	// Will return ErrFrozen if the store is frozen.
	AddStatusUpdate(stepID uint64, timestamp time.Time, newStatus workermodel.Status) error

	// SubAllStatusUpdates creates a new channel that streams all status updates
	// from this result store since the beginning, and keeps on streaming new
	// updates until unsubscribed.
	SubAllStatusUpdates(buffer int) (<-chan StatusUpdate, error)

	// UnsubAllStatusUpdates unsubscribes a subscription of all status updates
	// created via SubAllStatusUpdates.
	UnsubAllStatusUpdates(ch <-chan StatusUpdate) error

	// AddArtifactEvent adds an artifact event to a step.
	// Any written artifact event is also published to any active subscriptions.
	//
	// Will return ErrFrozen if the store is frozen.
	AddArtifactEvent(stepID uint64, artifactMeta workermodel.ArtifactMeta) error

	// SubAllArtifactEvents creates a new channel that streams all artifact
	// events from this result store since the beginning, and keeps on
	// streaming new events until unsubscribed.
	SubAllArtifactEvents(buffer int) (<-chan ArtifactEvent, error)

	// UnsubAllArtifactEvents unsubscribes a subscription of all artifact
	// events created via SubAllStatusUpdates.
	UnsubAllArtifactEvents(ch <-chan ArtifactEvent) error

	// Freeze waits for all write operations to finish, closes any open writers
	// and causes future write operations to error. This cannot be undone.
	//
	// All new subscriptions will be closed after catching up.
	Freeze() error

	// Close, in addition to freezing the store by calling Freeze, closes any
	// open readers and causes future read operations to error. This cannot be
	// undone.
	Close() error
}

Store is the interface for storing build results and accessing them as they are created.

func NewStore

func NewStore(fs FS) Store

NewStore creates a new store using a given filesystem.

func NewStoreForBuildID

func NewStoreForBuildID(buildID uint) (Store, error)

NewStoreForBuildID creates a new store using a newly created temporary directory. The location depends on the OS, e.g:

• Linux: /tmp/wharf-cmd-build-00123-xxxx
• Windows: C:/Temp/wharf-cmd-build-00123-xxxx

It gets this path via os.TempDir, which itself is OS dependent:

• Unix: $TMPDIR or "/tmp"
• Windows: GetTempPath syscall, which uses %TMP%, %TEMP%, %USERPROFILE%