hook

Documentation

Overview

Package hook provides management and execution of hook scripts, and the ability to capture environment variable changes caused by scripts.

It is intended for internal use by buildkite-agent only.

Index

• Constants
• Variables
• func Find(hookDir string, name string) (string, error)
• func Type(path string) (string, error)
• func WriteHookWrapper(templateType TemplateType, input WrapperTemplateInput, hookWrapperName string) (string, error)
• type EnvChanges
  • func (changes *EnvChanges) GetAfterWd() (string, error)
• type ExitError
  • func (e *ExitError) Error() string
• type TemplateType
• type Wrapper
  • func NewWrapper(opts ...WrapperOpt) (*Wrapper, error)
  • func (w *Wrapper) Changes() (EnvChanges, error)
  • func (w *Wrapper) Close()
  • func (w *Wrapper) Path() string
• type WrapperOpt
  • func WithOS(o string) WrapperOpt
  • func WithPath(path string) WrapperOpt
• type WrapperTemplateInput

Constants

const (
	TypeShell   = "shell"
	TypeBinary  = "binary"
	TypeScript  = "script" // Something with a shebang that isn't a shell script, but is an interpretable something-or-other
	TypeUnknown = "unknown"
)

Variables

var (
	// Linux and many other Unix-like systems use ELF binaries
	ELFMagic = []byte{0x7F, 0x45, 0x4C, 0x46}

	// Windows uses MS-DOS MZ-style executables. This includes PE32 and PE32+ (which is 64-bit 🙃) binaries,
	// which are what modern windowses tend to use.
	MZMagic = []byte{0x4D, 0x5A}

	// For "fat" binaries, which contain multiple architectures
	MachOFatMagic = []byte{0xCA, 0xFE, 0xBA, 0xBE}

	// For "thin" binaries, which contain a single architecture
	// (ie 32 and 64 bit variants, on top of different processor architectures)
	MachOThin32Magic = []byte{0xFE, 0xED, 0xFA, 0xCE}
	MachOThin64Magic = []byte{0xFE, 0xED, 0xFA, 0xCF}

	// Mach-O thin binaries can also be in reverse byte order, apparently?
	// I think this is for big endian processors like PowerPC, in which case we don't need these here,
	// but we might as well include them for completeness.
	MachOThin32ReverseMagic = []byte{0xCE, 0xFA, 0xED, 0xFE}
	MachOThin64ReverseMagic = []byte{0xCF, 0xFA, 0xED, 0xFE}

	BinaryMagicks = [][]byte{
		ELFMagic,
		MZMagic,
		MachOFatMagic,
		MachOThin32Magic,
		MachOThin64Magic,
		MachOThin32ReverseMagic,
		MachOThin64ReverseMagic,
	}
)

Magic numbers for various types of executable files

var (
	ErrNoHookPath = errors.New("hook path was not provided")
)

Functions

func Find

func Find(hookDir string, name string) (string, error)

Find returns the absolute path to the best matching hook file in a path, or os.ErrNotExist if none is found

func Type

func Type(path string) (string, error)

func WriteHookWrapper

func WriteHookWrapper(
	templateType TemplateType,
	input WrapperTemplateInput,
	hookWrapperName string,
) (string, error)

WriteHookWrapper will write a hook wrapper script to a temporary file with the same extension as, `hookWrapperName`. It will return the name of the temporary file. The file will be executable. It will be created from the template specified by `templateType` with data from `input`.

Types

type EnvChanges

type EnvChanges struct {
	Diff env.Diff
	// contains filtered or unexported fields
}

func (*EnvChanges) GetAfterWd

func (changes *EnvChanges) GetAfterWd() (string, error)

type ExitError

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

func (*ExitError) Error

func (e *ExitError) Error() string

type TemplateType

type TemplateType int

const (
	// BatchTemplateType indicates to WriteHookWrapper to write a batch file
	// for the hook wrapper
	BatchTemplateType TemplateType = iota

	// PowershellTemplateType indicates to WriteHookWrapper to write a Powershell
	// file for the hook wrapper
	PowershellTemplateType

	// PosixShellTemplateType indicates to WriteHookWrapper to write a POSIX shell
	// script for the hook wrapper
	PosixShellTemplateType
)

type Wrapper

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

Wrapper wraps a hook script with env collection and then provides a way to get the difference between the environment before the hook is run and after it

func NewWrapper

func NewWrapper(opts ...WrapperOpt) (*Wrapper, error)

NewWrapper creates and configures a hook.Wrapper. Writes temporary files to the filesystem.

func (*Wrapper) Changes

func (w *Wrapper) Changes() (EnvChanges, error)

Changes returns the changes in the environment and working dir after the hook script runs

func (*Wrapper) Close

func (w *Wrapper) Close()

Close cleans up the wrapper script and the environment files. Ignores errors, in particular the error from os.Remove if the file doesn't exist.

func (*Wrapper) Path

func (w *Wrapper) Path() string

Path returns the path to the wrapper script, this is the one that should be executed

type WrapperOpt

type WrapperOpt func(*Wrapper)

func WithOS

func WithOS(o string) WrapperOpt

func WithPath

func WithPath(path string) WrapperOpt

type WrapperTemplateInput

type WrapperTemplateInput struct {
	AgentBinary       string
	ShebangLine       string
	BeforeEnvFileName string
	AfterEnvFileName  string
	PathToHook        string
}