run

Documentation

Overview

Package run starts and tracks running Encore applications.

Index

• Constants
• func GenID() string
• func IgnoreEvents(events []watcher.Event) bool
• type CheckParams
• type EventListener
• type ExecScriptParams
• type Manager
  • func (mgr *Manager) AddListener(ln EventListener)
  • func (mgr *Manager) Check(ctx context.Context, p CheckParams) (buildDir string, err error)
  • func (mgr *Manager) ExecScript(ctx context.Context, p ExecScriptParams) (err error)
  • func (mgr *Manager) FindProc(procID string) *Proc
  • func (mgr *Manager) FindRunByAppID(appID string) *Run
  • func (mgr *Manager) ListRuns() []*Run
  • func (mgr *Manager) RunError(r *Run, err *errlist.List)
  • func (mgr *Manager) RunStderr(r *Run, out []byte)
  • func (mgr *Manager) RunStdout(r *Run, out []byte)
  • func (mgr *Manager) Start(ctx context.Context, params StartParams) (run *Run, err error)
  • func (mgr *Manager) Test(ctx context.Context, params TestParams) (err error)
• type Proc
  • func (p *Proc) Close()
  • func (p *Proc) Done() <-chan struct{}
  • func (p *Proc) SymTable(ctx context.Context) (*sym.Table, error)
• type Run
  • func (r *Run) Done() <-chan struct{}
  • func (r *Run) Proc() *Proc
  • func (r *Run) Reload() error
  • func (r *Run) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Run) StartProc(params *StartProcParams) (p *Proc, err error)
  • func (r *Run) StoreProc(p *Proc)
• type RunLogger
• type StartParams
• type StartProcParams
• type TestParams

Constants

const TestHeaderDisablePlatformAuth = "X-Encore-Test-Disable-Platform-Auth"

Functions

func GenID

func GenID() string

GenID generates a random run/process id. It panics if it cannot get random bytes.

func IgnoreEvents

func IgnoreEvents(events []watcher.Event) bool

IgnoreEvents will return true if _all_ events are on files that should be ignored as the do not impact the running app, or are the result of Encore itself generating code.

Types

type CheckParams

type CheckParams struct {
	// App is the app to start.
	App *apps.Instance

	// WorkingDir is the working dir, for formatting
	// error messages with relative paths.
	WorkingDir string

	// CodegenDebug, if true, specifies to keep the output
	// around for codegen debugging purposes.
	CodegenDebug bool

	// Environ are the environment variables to set,
	// in the same format as os.Environ().
	Environ []string

	// Tests specifies whether to parse and codegen for tests as well.
	Tests bool
}

type EventListener

type EventListener interface {
	// OnStart is called when a run starts.
	OnStart(r *Run)
	// OnReload is called when a run reloads.
	OnReload(r *Run)
	// OnStop is called when a run stops.
	OnStop(r *Run)
	// OnStdout is called when a run outputs something on stdout.
	OnStdout(r *Run, out []byte)
	// OnStderr is called when a run outputs something on stderr.
	OnStderr(r *Run, out []byte)
	// OnError is called when a run encounters an error.
	OnError(r *Run, err *errlist.List)
}

EventListener is the interface for listening to events about running apps.

type ExecScriptParams

type ExecScriptParams struct {
	// App is the app to execute the script for.
	App *apps.Instance

	// MainPkg is the package path to the command to execute.
	MainPkg paths.Pkg

	// ScriptArgs are the arguments to pass to the script binary.
	ScriptArgs []string

	// WorkingDir is the working dir to execute the script from.
	// It's relative to the app root.
	WorkingDir string

	// Environ are the environment variables to set when running the tests,
	// in the same format as os.Environ().
	Environ []string

	// Stdout and Stderr are where "go test" output should be written.
	Stdout, Stderr io.Writer

	OpTracker *optracker.OpTracker
}

ExecScriptParams groups the parameters for the ExecScript method.

type Manager

type Manager struct {
	RuntimePort int // port for Encore runtime
	DBProxyPort int // port for sqldb proxy
	DashPort    int // port for dev dashboard
	Secret      *secret.Manager
	ClusterMgr  *sqldb.ClusterManager
	// contains filtered or unexported fields
}

Manager manages the set of running applications.

func (*Manager) AddListener

func (mgr *Manager) AddListener(ln EventListener)

AddListener adds an event listener to mgr. It must be called before starting the first run.

func (*Manager) Check

func (mgr *Manager) Check(ctx context.Context, p CheckParams) (buildDir string, err error)

Check checks the app for errors. It reports a buildDir (if available) when codegenDebug is true.

func (*Manager) ExecScript

func (mgr *Manager) ExecScript(ctx context.Context, p ExecScriptParams) (err error)

ExecScript executes the script.

func (*Manager) FindProc

func (mgr *Manager) FindProc(procID string) *Proc

FindProc finds the proc with the given id. It reports nil if no such proc was found.

func (*Manager) FindRunByAppID

func (mgr *Manager) FindRunByAppID(appID string) *Run

FindRunByAppID finds the run with the given app id. It reports nil if no such run was found.

func (*Manager) ListRuns

func (mgr *Manager) ListRuns() []*Run

ListRuns provides a snapshot of all runs.

func (*Manager) RunError

func (mgr *Manager) RunError(r *Run, err *errlist.List)

func (*Manager) RunStderr

func (mgr *Manager) RunStderr(r *Run, out []byte)

func (*Manager) RunStdout

func (mgr *Manager) RunStdout(r *Run, out []byte)

func (*Manager) Start

func (mgr *Manager) Start(ctx context.Context, params StartParams) (run *Run, err error)

Start starts the application. Its lifetime is bounded by ctx.

func (*Manager) Test

func (mgr *Manager) Test(ctx context.Context, params TestParams) (err error)

Test runs the tests.

type Proc

type Proc struct {
	ID          string           // unique process id
	Run         *Run             // the run the process belongs to
	Pid         int              // the OS process id
	Meta        *meta.Data       // app metadata snapshot
	Started     time.Time        // when the process started
	Experiments *experiments.Set // enabled experiments

	Client *yamux.Session
	// contains filtered or unexported fields
}

Proc represents a running Encore process.

func (*Proc) Close

func (p *Proc) Close()

Close closes the process and waits for it to shutdown. It can safely be called multiple times.

func (*Proc) Done

func (p *Proc) Done() <-chan struct{}

Done returns a channel that is closed when the process has exited.

func (*Proc) SymTable

func (p *Proc) SymTable(ctx context.Context) (*sym.Table, error)

SymTable waits for the proc's symbol table to be parsed and then returns it. ctx is used to cancel the wait.

type Run

type Run struct {
	ID              string // unique ID for this instance of the running app
	App             *apps.Instance
	ListenAddr      string // the address the app is listening on
	ResourceManager *infra.ResourceManager

	Mgr *Manager
	// contains filtered or unexported fields
}

Run represents a running Encore application.

func (*Run) Done

func (r *Run) Done() <-chan struct{}

Done returns a channel that is closed when the run is closed.

func (*Run) Proc

func (r *Run) Proc() *Proc

Proc returns the current running process. It may have already exited. If the proc has not yet started it may return nil.

func (*Run) Reload

func (r *Run) Reload() error

Reload rebuilds the app and, if successful, starts a new proc and switches over.

func (*Run) ServeHTTP

func (r *Run) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements http.Handler by forwarding the request to the currently running process.

func (*Run) StartProc

func (r *Run) StartProc(params *StartProcParams) (p *Proc, err error)

StartProc starts a single actual OS process for app.

func (*Run) StoreProc

func (r *Run) StoreProc(p *Proc)

type RunLogger

type RunLogger interface {
	RunStdout(r *Run, line []byte)
	RunStderr(r *Run, line []byte)
}

RunLogger is the interface for listening to run logs. The log methods are called for each logline on stdout and stderr respectively.

type StartParams

type StartParams struct {
	// App is the app to start.
	App *apps.Instance

	// WorkingDir is the working dir, for formatting
	// error messages with relative paths.
	WorkingDir string

	// Watch enables watching for code changes for live reloading.
	Watch bool

	Listener   net.Listener // listener to use
	ListenAddr string       // address we're listening on

	// Environ are the environment variables to set for the running app,
	// in the same format as os.Environ().
	Environ []string

	// The Ops tracker being used for this run
	OpsTracker *optracker.OpTracker

	// Debug specifies to compile the application for debugging.
	Debug bool
}

StartParams groups the parameters for the Run method.

type StartProcParams

type StartProcParams struct {
	Ctx            context.Context
	BuildDir       string
	BinPath        string
	Meta           *meta.Data
	Secrets        map[string]string
	ServiceConfigs map[string]string
	RuntimePort    int
	DBProxyPort    int
	Logger         RunLogger
	Environ        []string
	Experiments    *experiments.Set
}

type TestParams

type TestParams struct {
	// App is the app to test.
	App *apps.Instance

	// WorkingDir is the working dir, for formatting
	// error messages with relative paths.
	WorkingDir string

	// Secrets are the secrets to use.
	Secrets *secret.LoadResult

	// Args are the arguments to pass to "go test".
	Args []string

	// Environ are the environment variables to set when running the tests,
	// in the same format as os.Environ().
	Environ []string

	// Stdout and Stderr are where "go test" output should be written.
	Stdout, Stderr io.Writer
}

TestParams groups the parameters for the Test method.