runtime

README

Runtime Package

The runtime package is responsible for sourcing a runtime based on a provided buildplan, as well as for providing insights into that sourced runtime.

Design Goals

A fundamental goal of the runtime package (and really any package) is that it is intuitive to maintain. Meaning when we don't touch this code for 6 months and then come back to it we can still easily tell what's going on.

The main method of achieving this goal is by minimizing the responsibilities of the runtime package. By having it no be aware of projects, buildscripts, analytics, etc. we facilitate a much cleaner boilerplate that is easier to grok than if it were dealing with all these concepts.

Additionally we keep our use of channels very minimal, and centralize their use in key location so as to avoid passing channels between functions or layers of logic.

As we further grow this runtime package we may find that certain responsibilities start to obfuscate the core logic again, we should remain sensitive to this, removing responsibilities and shifting it into other standalone packages is always an option.

Avoid Dependencies

The runtime package should itself have no awareness of projects, buildscripts, or anything else not absolutely vital for the purpose of installing a runtime.

Note we do provide project information for annotation purposes, because executors rely on it. Over time we should try and remove executors from the runtime package, because it's really not part of sourcing a functional runtime, it's more of a distinct post-processing step.

Responsibilities

Anything not covered under these responsibilities should not be introduced into the runtime package without a good reason and discussion with the tech-lead.

• Sourcing a runtime based on a provided buildplan
• Providing insights into the sourced runtime
• Handle sharing of sourced artifacts between multiple runtimes
  • Specifically this is handled by the "depot"
• Firing of events through the events package

Sub-Packages

Any responsibilities provided by these sub-packages should NOT be handled anywhere else.

• events
  • Provide event hooks for interactions with runtime processes
    • eg. for progress indication or analytics
    • Note this is handled through the events sub-package.
• internal/buildlog
  • Interact with buildlog streamer
    • ie. provide progress information on in-progress builds
  • Firing of events through the events package
• internal/camel
  • Facilitate sourcing of camel runtimes
  • It does this by pre-processing a camel artifact and injecting a runtime.json that alternate builds normally produce
• internal/envdef
  • Facilitate reading of runtime.json files, and merging multiple runtime.json files together.

Documentation

Index

• func ExecutorsPath(baseDir string) string
• func IsRuntimeDir(dir string) bool
• type ArtifactBuildError
• type ArtifactCachedBuildFailed
• type BuildError
• type Environment
• type ErrVolumeMismatch
  • func (e ErrVolumeMismatch) Error() string
• type Opts
• type ProgressReportError
• type Runtime
  • func New(path string) (*Runtime, error)
  • func (r *Runtime) Env(inherit bool) Environment
  • func (r *Runtime) HasCache() bool
  • func (r *Runtime) Hash() string
  • func (r *Runtime) Path() string
  • func (r *Runtime) Update(bp *buildplan.BuildPlan, hash string, setOpts ...SetOpt) error
• type SetOpt
  • func WithAnnotations(owner, project string, commitUUID strfmt.UUID) SetOpt
  • func WithArchive(dir string, platformID strfmt.UUID, ext string) SetOpt
  • func WithBuildProgressUrl(url string) SetOpt
  • func WithBuildlogFilePath(path string) SetOpt
  • func WithEventHandlers(handlers ...events.HandlerFunc) SetOpt
  • func WithPortable() SetOpt
  • func WithPreferredLibcVersion(version string) SetOpt

Functions

func ExecutorsPath

func ExecutorsPath(baseDir string) string

func IsRuntimeDir

func IsRuntimeDir(dir string) bool

Types

type ArtifactBuildError

type ArtifactBuildError = buildlog.ArtifactBuildError

buildlog aliases, because buildlog is internal

type ArtifactCachedBuildFailed

type ArtifactCachedBuildFailed struct {
	*errs.WrapperError
	Artifact *buildplan.Artifact
}

ArtifactCachedBuildFailed designates an error due to a build for an artifact that failed and has been cached

type BuildError

type BuildError = buildlog.BuildError

type Environment

type Environment struct {
	Variables              map[string]string
	VariablesWithExecutors map[string]string
	ExecutorsPath          string
}

type ErrVolumeMismatch

type ErrVolumeMismatch struct {
	DepotVolume string
	PathVolume  string
}

func (ErrVolumeMismatch) Error

func (e ErrVolumeMismatch) Error() string

type Opts

type Opts struct {
	PreferredLibcVersion string
	EventHandlers        []events.HandlerFunc
	BuildlogFilePath     string
	BuildProgressUrl     string
	Portable             bool

	FromArchive *fromArchive

	// Annotations are used strictly to pass information for the purposes of analytics
	// These should never be used for business logic. If the need to use them for business logic arises either we are
	// going down a wrong rabbit hole or we need to revisit the architecture.
	Annotations struct {
		Owner      string
		Project    string
		CommitUUID strfmt.UUID
	}
}

type ProgressReportError

type ProgressReportError struct {
	*errs.WrapperError
}

ProgressReportError designates an error in the event handler for reporting progress.

type Runtime

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

func New

func New(path string) (*Runtime, error)

func (*Runtime) Env

func (r *Runtime) Env(inherit bool) Environment

func (*Runtime) HasCache

func (r *Runtime) HasCache() bool

func (*Runtime) Hash

func (r *Runtime) Hash() string

func (*Runtime) Path

func (r *Runtime) Path() string

func (*Runtime) Update

func (r *Runtime) Update(bp *buildplan.BuildPlan, hash string, setOpts ...SetOpt) error

type SetOpt

type SetOpt func(*Opts)

func WithAnnotations

func WithAnnotations(owner, project string, commitUUID strfmt.UUID) SetOpt

func WithArchive

func WithArchive(dir string, platformID strfmt.UUID, ext string) SetOpt

func WithBuildProgressUrl

func WithBuildProgressUrl(url string) SetOpt

func WithBuildlogFilePath

func WithBuildlogFilePath(path string) SetOpt

func WithEventHandlers

func WithEventHandlers(handlers ...events.HandlerFunc) SetOpt

func WithPortable

func WithPortable() SetOpt

func WithPreferredLibcVersion

func WithPreferredLibcVersion(version string) SetOpt