app

Documentation

Overview

app contains the interfaces and structures for application type implementations for Otto. Applications are the components that know how to dev, build, and deploy a certain kind of application such as Rails, PHP, etc.

All app implementations are built specific to a certain 3-tuple: (app type, infra type, infra flavor). For example: (rails, aws, vpc-public-private). The app implementation then only needs to know how to satisfy that specific 3-tuple.

When building app plugins, it is possible for that plugin to support multiple matrix elements, but each implementation of the interface is expeced to only implement one.

Index

• func Close(v interface{}) error
• func WriteDevDep(path string, dep *DevDep) error
• type App
• type CompileResult
• type Context
  • func (c *Context) RouteArgs() []string
  • func (c *Context) RouteName() string
  • func (c *Context) UI() ui.Ui
• type DevDep
  • func ReadDevDep(path string) (*DevDep, error)
  • func (d *DevDep) RelFiles(dir string) error
• type Factory
  • func StructFactory(v App) Factory
• type Meta
• type Mock
  • func (m *Mock) Build(ctx *Context) error
  • func (m *Mock) Close() error
  • func (m *Mock) Compile(ctx *Context) (*CompileResult, error)
  • func (m *Mock) Deploy(ctx *Context) error
  • func (m *Mock) Dev(ctx *Context) error
  • func (m *Mock) DevDep(dst, src *Context) (*DevDep, error)
  • func (m *Mock) Implicit(ctx *Context) (*appfile.File, error)
  • func (m *Mock) Meta() (*Meta, error)
• type Tuple
  • func (t Tuple) String() string
• type TupleMap
  • func (m TupleMap) Add(m2 TupleMap)
  • func (m TupleMap) Lookup(t Tuple) Factory
• type TupleSlice
  • func (s TupleSlice) Len() int
  • func (s TupleSlice) Less(i, j int) bool
  • func (s TupleSlice) Map(f Factory) TupleMap
  • func (s TupleSlice) Swap(i, j int)

Functions

func Close

func Close(v interface{}) error

Close is a function that can easily be deferred or called at any point and will close the given value if it is an io.Closer.

This should be called with App implementations since they may be happening over RPC.

func WriteDevDep

func WriteDevDep(path string, dep *DevDep) error

WriteDevDep writes a DevDep out to disk.

Types

type App

type App interface {
	// Meta returns the metadata about this App implementation.
	Meta() (*Meta, error)

	// Implicit returns implicit configurations for an Appfile that is
	// using this type. This is called after this app type is detected
	// to be used, and allows the app implementation to setup defaults.
	//
	// The App implementation can then define implicit dependencies and
	// things like that based on the environment.
	//
	// The Context argument for this function call will be very sparse.
	// Only Appfile and UI will be set. Everythign else should be considered
	// unusable.
	Implicit(*Context) (*appfile.File, error)

	// Compile is called to compile the files that are used to manage
	// this application.
	Compile(*Context) (*CompileResult, error)

	// Build is called to build the deployable artifact for this
	// application.
	Build(*Context) error

	// Deploy is called to deploy this application. The existence of
	// a prior build artifact is confirmed before this is called.
	Deploy(*Context) error

	// Dev should manage a development environment for this app
	// type. This is called for the local, mutable dev environment
	// where this application is the main thing under development.
	Dev(*Context) error

	// DevDep is called when this app is an upstream dependency
	// of another application that is being developed. This app should
	// build itself for development, and configure the Vagrantfile so
	// that this dependency starts properly on boot.
	//
	// DevDep is given two contexts. The first is the destination
	// app (the one being developed), and the second is the source
	// app (this one that is an upstream dep).
	//
	// The results of this call are cached to speed up development
	// of the destination app until there is a change, which is detected
	// based on VCS.
	//
	// The resulting DevDep can be nil if nothing needs to be done that
	// is part of the DevDep structure. Any DevDepFragments from the
	// compilation will still be used, of course.
	DevDep(dst *Context, src *Context) (*DevDep, error)
}

App is the interface that must be implemented by each (app type, infra type, infra flavor) 3-tuple.

type CompileResult

type CompileResult struct {
	// Version is the version of the compiled result. This is purely metadata:
	// the app itself should use this to detect certain behaviors on run.
	Version uint32 `json:"version"`

	// FoundationConfig is the configuration for the various foundational
	// elements of Otto.
	FoundationConfig foundation.Config `json:"foundation_config"`

	// DevDepFragmentPath is the path to the Vagrantfile fragment that
	// should be added to other Vagrantfiles when this application is
	// used as a dependency.
	DevDepFragmentPath string `json:"dev_dep_fragment_path"`

	// FoundationResults are the compilation results of the foundations.
	//
	// This is populated by Otto core and any set value here will be ignored.
	FoundationResults map[string]*foundation.CompileResult `json:"foundation_results"`
}

CompileResult is the structure containing compilation result values.

type Context

type Context struct {
	context.Shared

	// CompileResult is the result of the compilation. This is set on
	// all calls except Compile to be the data from the compilation. This
	// can be used to check compile versions, for example.
	CompileResult *CompileResult

	// Action is the sub-action to take when being executed.
	//
	// ActionArgs is the list of arguments for this action.
	//
	// Both of these fields will only be set for the Execute call.
	Action     string
	ActionArgs []string

	// Dir is the directory that the compilation is allowed to write to
	// for persistant storage of data that is available during task
	// execution. For tasks, this will be the directory that compilation
	// wrote to. Whenever a compilation is done, this directory is
	// cleared. Data that should be persistant across compilations should
	// be stored in the directory service.
	Dir string

	// CacheDir is the directory where data can be cached. This data
	// will persist across compiles of the same version of an Appfile.
	//
	// GlobalCacheDir is a directory that is shared across multiple
	// Otto runs. It can be accessed by any app type and any Otto run. App
	// types should be _extremely_ careful to use multi-process locking
	// to prevent races. Additionally, you must be absolutely certain to
	// have a cleanup process for this directory for your own files.
	//
	// The App implementation should function under the assumption that
	// this cache directory can be cleared at any time between runs.
	CacheDir string

	// LocalDir is the directory where data local to this single Appfile
	// will be stored; it isn't cleared for compilation.
	//
	// GlobalDir is the directory where data global to Otto will be stored.
	// It is never automatically cleared so any usage of this directory
	// must have a cleanup mechanism in some way.
	LocalDir  string
	GlobalDir string

	// Tuple is the Tuple that identifies this application. This can be
	// used so that an implementatin of App can work with multiple tuple
	// types.
	Tuple Tuple

	// Application is the application configuration itself from the appfile.
	Application *appfile.Application

	// DevDepFragments will be populated with the list of dev dep
	// Vagrantfile fragment paths. This will only be available in the Compile
	// call.
	DevDepFragments []string

	// DevIPAddress is a local IP address in the private address space
	// that can be used for a development environment. Otto core
	// does its best to ensure this is unused.
	//
	// This is only available if this app is the root application being
	// developed (dependencies don't get an IP).
	DevIPAddress string
}

Context is the context for operations on applications. Some of the fields in this struct are only available for certain operations.

func (*Context) RouteArgs

func (c *Context) RouteArgs() []string

RouteArgs implements the router.Context interface so we can use Router

func (*Context) RouteName

func (c *Context) RouteName() string

RouteName implements the router.Context interface so we can use Router

func (*Context) UI

func (c *Context) UI() ui.Ui

UI implements router.Context so we can use this in router.Router

type DevDep

type DevDep struct {
	// Files is a list of files that this dependency created or uses.
	// If these files already exist, then future DevDep calls won't be
	// called and the cached data will be used.
	//
	// All files in this must be in the Context.CacheDir. Relative paths
	// will be expanded relative to the CacheDir. If the file is not
	// in the CacheDir, no caching will occur. The log will note if this
	// is happening.
	Files []string `json:"files"`
}

DevDep has information about an upstream dependency that should be used by the Dev function in order to build a complete development environment.

func ReadDevDep

func ReadDevDep(path string) (*DevDep, error)

ReadDevDep reads a marshalled DevDep from disk.

func (*DevDep) RelFiles

func (d *DevDep) RelFiles(dir string) error

RelFiles makes all the Files values relative to the given directory.

type Factory

type Factory func() (App, error)

Factory is a factory function for creating infrastructures.

func StructFactory

func StructFactory(v App) Factory

StructFactory returns a factory function for creating a newly instantiated copy of the type of v.

type Meta

type Meta struct {
	// Tuples returns the tuples that this app implementation supports.
	Tuples TupleSlice

	// Detectors are the detectors that exist for this app type.
	Detectors []*detect.Detector
}

Meta is metadata about an app implementation.

type Mock

type Mock struct {
	CloseCalled bool

	MetaCalled bool
	MetaResult *Meta
	MetaErr    error

	ImplicitCalled  bool
	ImplicitContext *Context
	ImplicitResult  *appfile.File
	ImplicitErr     error

	CompileCalled  bool
	CompileContext *Context
	CompileResult  *CompileResult
	CompileErr     error
	CompileFunc    func(ctx *Context) (*CompileResult, error)

	BuildCalled  bool
	BuildContext *Context
	BuildErr     error

	DeployCalled  bool
	DeployContext *Context
	DeployErr     error

	DevCalled  bool
	DevContext *Context
	DevErr     error

	DevDepCalled     bool
	DevDepContextDst *Context
	DevDepContextSrc *Context
	DevDepResult     *DevDep
	DevDepErr        error
}

Mock is a mock implementation of the App interface.

func (*Mock) Build

func (m *Mock) Build(ctx *Context) error

func (*Mock) Close

func (m *Mock) Close() error

func (*Mock) Compile

func (m *Mock) Compile(ctx *Context) (*CompileResult, error)

func (*Mock) Deploy

func (m *Mock) Deploy(ctx *Context) error

func (*Mock) Dev

func (m *Mock) Dev(ctx *Context) error

func (*Mock) DevDep

func (m *Mock) DevDep(dst, src *Context) (*DevDep, error)

func (*Mock) Implicit

func (m *Mock) Implicit(ctx *Context) (*appfile.File, error)

func (*Mock) Meta

func (m *Mock) Meta() (*Meta, error)

type Tuple

type Tuple struct {
	App         string // App is the app type, i.e. "go"
	Infra       string // Infra is the infra type, i.e. "aws"
	InfraFlavor string // InfraFlavor is the flavor, i.e. "vpc-public-private"
}

Tuple is the tupled used for looking up the App implementation for an Appfile. This struct is usually used in its non-pointer form, to be a key for maps.

func (Tuple) String

func (t Tuple) String() string

type TupleMap

type TupleMap map[Tuple]Factory

TupleMap is an alias of map[Tuple]Factory that adds additional helper methods on top to help work with app tuples.

func (TupleMap) Add

func (m TupleMap) Add(m2 TupleMap)

Add is a helper to add another map to this one.

func (TupleMap) Lookup

func (m TupleMap) Lookup(t Tuple) Factory

Lookup looks up a Tuple. This should be used instead of direct [] access since it respects wildcards ('*') within the Tuple.

type TupleSlice

type TupleSlice []Tuple

TupleSlice is an alias of []Tuple that implements sort.Interface for sorting tuples. See the tests in tuple_test.go to see the sorting order.

func (TupleSlice) Len

func (s TupleSlice) Len() int

sort.Interface impl.

func (TupleSlice) Less

func (s TupleSlice) Less(i, j int) bool

func (TupleSlice) Map

func (s TupleSlice) Map(f Factory) TupleMap

Map turns a TupleSlice into a map where all the tuples in the slice are mapped to a single factory function.

func (TupleSlice) Swap

func (s TupleSlice) Swap(i, j int)