gapi

Documentation

Overview

Package gapi defines the interface that graph API generators must meet.

Index

• Constants
• Variables
• func CopyBytesToFs(fs engine.WriteableFS, b []byte, dst string) error
• func CopyDirContentsToFs(fs engine.Fs, src, dst string) error
• func CopyDirToFs(fs engine.Fs, src, dst string) error
• func CopyDirToFsForceAll(fs engine.Fs, src, dst string) error
• func CopyFileToFs(fs engine.WriteableFS, src, dst string) error
• func CopyStringToFs(fs engine.WriteableFS, str, dst string) error
• func Names() []string
• func Register(name string, fn func() GAPI)
• type Data
• type Deploy
  • func NewDeployFromB64(str string) (*Deploy, error)
  • func (obj *Deploy) ToB64() (string, error)
• type Flags
• type GAPI
• type Info
• type InfoResult
• type Next

Constants

const Umask = 0666

Umask is the default to use when none has been specified. TODO: apparently using 0666 is equivalent to respecting the current umask

Variables

var RegisteredGAPIs = make(map[string]func() GAPI) // must initialize this map

RegisteredGAPIs is a global map of all possible GAPIs which can be used. You should never touch this map directly. Use methods like Register instead.

Functions

func CopyBytesToFs

func CopyBytesToFs(fs engine.WriteableFS, b []byte, dst string) error

CopyBytesToFs copies a list of bytes to a dst path on fs.

func CopyDirContentsToFs

func CopyDirContentsToFs(fs engine.Fs, src, dst string) error

CopyDirContentsToFs copies a dir contents from src path on the local fs to a dst path on fs.

func CopyDirToFs

func CopyDirToFs(fs engine.Fs, src, dst string) error

CopyDirToFs copies a dir from src path on the local fs to a dst path on fs. FIXME: I'm not sure this does the logical thing when the dst path is a dir. FIXME: We've got a workaround for this inside of the lang CLI GAPI.

func CopyDirToFsForceAll

func CopyDirToFsForceAll(fs engine.Fs, src, dst string) error

CopyDirToFsForceAll copies a dir from src path on the local fs to a dst path on fs, but it doesn't error when making a dir that already exists. It also uses `MkdirAll` to prevent some issues. FIXME: This is being added because of issues with CopyDirToFs. POSIX is hard.

func CopyFileToFs

func CopyFileToFs(fs engine.WriteableFS, src, dst string) error

CopyFileToFs copies a file from src path on the local fs to a dst path on fs.

func CopyStringToFs

func CopyStringToFs(fs engine.WriteableFS, str, dst string) error

CopyStringToFs copies a string to a dst path on fs.

func Names

func Names() []string

Names returns a list of the names of all registered GAPIs.

func Register

func Register(name string, fn func() GAPI)

Register takes a GAPI and its name and makes it available for use. There is no matching Unregister function.

Types

type Data

type Data struct {
	Program       string // name of the originating program
	Version       string // version of the originating program
	Hostname      string // uuid for the host, required for GAPI
	Local         *local.API
	World         engine.World
	Noop          bool
	NoStreamWatch bool
	Prefix        string
	Debug         bool
	Logf          func(format string, v ...interface{})
}

Data is the set of input values passed into the GAPI structs via Init.

type Deploy

type Deploy struct {
	ID   uint64
	Name string // lang, puppet, yaml, etc...
	//Sync bool // wait for everyone to close previous GAPI before switching
	Noop bool
	Sema int // sema override
	GAPI GAPI
}

Deploy represents a deploy action, include the type of GAPI to deploy, the payload of that GAPI, and any deploy specific parameters that were chosen. TODO: add staged rollout functionality to this struct TODO: add proper authentication with gpg key signing

func NewDeployFromB64

func NewDeployFromB64(str string) (*Deploy, error)

NewDeployFromB64 decodes a deploy struct from a base64 encoded string.

func (*Deploy) ToB64

func (obj *Deploy) ToB64() (string, error)

ToB64 encodes a deploy struct as a base64 encoded string.

type Flags

type Flags struct {
	Hostname *string

	Noop bool
	Sema int
}

Flags is some common data that comes from a higher-level command, and is used by a subcommand. By type circularity, the subcommands can't easily access the data in the parent command struct, so instead, the data that the parent wants to pass down, it wraps up in a struct (for API convenience) and sends it out.

type GAPI

type GAPI interface {
	// Cli is run on each GAPI to give it a chance to decide if it wants to
	// activate, and if it does, then it will return a deploy struct. During
	// this time, it uses the Info struct as useful information to decide
	// what to do.
	Cli(*Info) (*Deploy, error)

	// Init initializes the GAPI and passes in some useful data.
	Init(*Data) error

	// Info returns some data about the GAPI implementation.
	Info() *InfoResult

	// Graph returns the most recent pgraph. This is called by the engine on
	// every event from Next().
	Graph() (*pgraph.Graph, error)

	// Next returns a stream of switch events. The engine will run Graph()
	// to build a new graph after every Next event.
	// TODO: add context for shutting down to the input and change Close to Cleanup
	Next() chan Next

	// Close shuts down the GAPI. It asks the GAPI to close, and must cause
	// Next() to unblock even if is currently blocked and waiting to send a
	// new event.
	// TODO: change Close to Cleanup
	Close() error
}

GAPI is a Graph API that represents incoming graphs and change streams. It is the frontend interface that needs to be implemented to use the engine.

type Info

type Info struct {
	// Args are the CLI args that are populated after parsing the args list.
	// They need to be converted to the struct you are expecting to read it.
	Args interface{}

	// Flags are the common data which is passed down into the sub command.
	Flags *Flags

	// Fs is the filesystem the Cli method should copy data into. It usually
	// copies *from* the local filesystem using standard io functionality.
	Fs engine.Fs

	Debug bool
	Logf  func(format string, v ...interface{})
}

Info is the set of input values passed into the Cli method so that the GAPI can decide if it wants to activate, and if it does, the initial handles it needs to use to do so.

type InfoResult

type InfoResult struct {
	// URI is the FS URI that we pass around everywhere.
	// TODO: can this be deprecated?
	URI string
}

InfoResult is some data that a GAPI can return on request.

type Next

type Next struct {
	// FIXME: the Fast pause parameter should eventually get replaced with a
	// "SwitchMethod" parameter or similar that instead lets the implementer
	// choose between fast pause, slow pause, and interrupt. Interrupt could
	// be a future extension to the Resource API that lets an Interrupt() be
	// called if we want to exit immediately from the CheckApply part of the
	// resource for some reason. For now we'll keep this simple with a bool.
	Fast bool  // run a fast pause to switch?
	Exit bool  // should we cause the program to exit? (specify err or not)
	Err  error // if something goes wrong (use with or without exit!)
}

Next describes the particular response the GAPI implementer wishes to emit.