Documentation
¶
Overview ¶
Package appcommon pkg/app/appcommon/doc.go c2-vis-appsvc
Package appcommon pkg/app/appcommon/hello.go c2-vis-appsvc
Package appcommon pkg/app/appcommon/log_store.go c2-vis-appsvc
Package appcommon pkg/app/appcommon/log_store_native.go c2-vis-appsvc
The bbolt-backed LogStore. bbolt does not compile on the TinyGo js/wasm target, so this file is native-only; the in-memory TinyGo store lives in log_store_tinygo.go. The shared interface + NewProcLogger are in log_store.go.
Package appcommon pkg/app/appcommon/proc_config.go c2-vis-appsvc
Index ¶
- Constants
- Variables
- func AcquireInternalAppStart(key ProcKey) chan struct{}
- func GetInProcessConn(key ProcKey) net.Conn
- func GetInProcessLogger(key ProcKey) logrus.FieldLogger
- func RegisterInProcessConn(key ProcKey, conn net.Conn)
- func RegisterInProcessLogger(key ProcKey, log logrus.FieldLogger)
- func ReleaseInternalAppStart(key ProcKey)
- func TimestampFromLog(logLine string) string
- func UnregisterInProcessConn(key ProcKey)
- func UnregisterInProcessLogger(key ProcKey)
- func UnsetInternalAppEnv(envs []string)
- func WriteHello(w io.Writer, hello Hello) error
- type AppFunc
- type Hello
- type LogStore
- type MockAddr
- type MockConn
- func (_m *MockConn) Close() error
- func (_m *MockConn) LocalAddr() net.Addr
- func (_m *MockConn) Read(b []byte) (int, error)
- func (_m *MockConn) RemoteAddr() net.Addr
- func (_m *MockConn) SetDeadline(t time.Time) error
- func (_m *MockConn) SetReadDeadline(t time.Time) error
- func (_m *MockConn) SetWriteDeadline(t time.Time) error
- func (_m *MockConn) Write(b []byte) (int, error)
- type MockListener
- type ProcConfig
- type ProcID
- type ProcKey
- type RestartPolicy
- type RunMode
Constants ¶
const (
// EnvProcConfig is the env name which contains a JSON-encoded proc config.
EnvProcConfig = "PROC_CONFIG"
)
Variables ¶
var ( // ErrProcConfigEnvNotDefined occurs when an expected env is not defined. ErrProcConfigEnvNotDefined = fmt.Errorf("env '%s' is not defined", EnvProcConfig) )
Functions ¶
func AcquireInternalAppStart ¶
func AcquireInternalAppStart(key ProcKey) chan struct{}
AcquireInternalAppStart acquires the lock for starting an internal app. This must be called before setting env vars for internal apps. Returns a channel that should be waited on after starting the app goroutine.
func GetInProcessConn ¶
GetInProcessConn retrieves the net.Conn for an in-process app by its ProcKey.
func GetInProcessLogger ¶
func GetInProcessLogger(key ProcKey) logrus.FieldLogger
GetInProcessLogger retrieves the logger for an in-process app by its ProcKey, or nil when the app is not in-process (the external case, where stderr is the channel).
func RegisterInProcessConn ¶
RegisterInProcessConn registers a net.Conn for an in-process app by its ProcKey.
func RegisterInProcessLogger ¶
func RegisterInProcessLogger(key ProcKey, log logrus.FieldLogger)
RegisterInProcessLogger registers the visor-side per-app logger of an in-process app by its ProcKey, exactly as RegisterInProcessConn registers its conn.
An EXTERNAL app's stderr is read by the proc manager and re-logged through that same logger (appserver.attachCmdLogs → printStdErr), so its lines reach the app's bbolt log store and local/log/skywire.log. An in-process app has no stderr pipe: its app.Client built a private logrus straight onto the visor's os.Stderr, so everything it logged — including the warning naming why an upload failed — existed only in the visor's console. This registry is how app.NewClient finds the collected logger instead.
func ReleaseInternalAppStart ¶
func ReleaseInternalAppStart(key ProcKey)
ReleaseInternalAppStart releases the lock after the app has read its config. The done channel should be waited on before calling this.
func TimestampFromLog ¶
TimestampFromLog is an utility function for retrieving the timestamp from a log. This function should be modified if the time layout is changed
func UnregisterInProcessConn ¶
func UnregisterInProcessConn(key ProcKey)
UnregisterInProcessConn removes the net.Conn for an in-process app by its ProcKey.
func UnregisterInProcessLogger ¶
func UnregisterInProcessLogger(key ProcKey)
UnregisterInProcessLogger removes the logger for an in-process app.
func UnsetInternalAppEnv ¶ added in v1.3.100
func UnsetInternalAppEnv(envs []string)
UnsetInternalAppEnv removes an exiting internal app's env vars under the start lock. Unlocked, a restart's new instance could lose its PROC_CONFIG between being given it and reading it, and NewClient then exits the visor.
Types ¶
type AppFunc ¶
AppFunc is a function that runs an app in-process.
Contract:
- Run until the supplied context is canceled, then return.
- On clean shutdown, return nil. On unrecoverable error, return a non-nil error and log via the per-app logger obtained through app.NewClient().
- args mirrors os.Args[1:] for the equivalent external binary, so internal and external invocations of the same logical app share CLI semantics.
- The app is responsible for creating its own app.Client via app.NewClient(); the visor-side conn is wired in by ProcManager before the function is called.
type Hello ¶
type Hello struct {
ProcKey ProcKey `json:"proc_key"` // proc key
EgressNet string `json:"egress_net,omitempty"` // network which hosts the appevent.RPCGateway of the app
EgressAddr string `json:"egress_addr,omitempty"` // address which hosts the appevent.RPCGateway of the app
EventSubs map[string]bool `json:"event_subs,omitempty"` // event subscriptions
}
Hello represents the first JSON object that an app sends the visor.
func (*Hello) AllowsEventType ¶
AllowsEventType returns true if the hello object contents allow for an event type.
type LogStore ¶
type LogStore interface {
// Write implements io.Writer
Write(p []byte) (n int, err error)
// Store saves given log in db
Store(t time.Time, s string) error
// LogSince returns the logs since given timestamp. For optimal performance,
// the timestamp should exist in the store (you can get it from previous logs),
// otherwise the DB will be sequentially iterated until finding entries older than given timestamp
LogsSince(t time.Time) ([]string, error)
Fire(entry *log.Entry) error
Levels() []log.Level
Flush() error
}
LogStore stores logs from apps, for later consumption from the hypervisor
func NewBBoltLogStore ¶
NewBBoltLogStore returns a bbolt implementation of an app log store.
func NewProcLogger ¶
func NewProcLogger(conf ProcConfig, mLog *logging.MasterLogger) (appLog *logging.MasterLogger, db LogStore)
NewProcLogger returns a new proc logger. It creates an isolated MasterLogger for the app to prevent log cross-contamination between multiple apps that would occur if they shared the same logger with multiple hooks.
The backing LogStore is selected per build by newProcLogStore: a bbolt store on native builds (log_store_native.go), an in-memory store on TinyGo (log_store_tinygo.go), where bbolt does not compile.
type MockAddr ¶
MockAddr is an autogenerated mock type for the Addr type
type MockConn ¶
MockConn is an autogenerated mock type for the Conn type
func (*MockConn) RemoteAddr ¶
RemoteAddr provides a mock function with given fields:
func (*MockConn) SetDeadline ¶
SetDeadline provides a mock function with given fields: t
func (*MockConn) SetReadDeadline ¶
SetReadDeadline provides a mock function with given fields: t
func (*MockConn) SetWriteDeadline ¶
SetWriteDeadline provides a mock function with given fields: t
type MockListener ¶
MockListener is an autogenerated mock type for the Listener type
func (*MockListener) Accept ¶
func (_m *MockListener) Accept() (net.Conn, error)
Accept provides a mock function with given fields:
func (*MockListener) Addr ¶
func (_m *MockListener) Addr() net.Addr
Addr provides a mock function with given fields:
func (*MockListener) Close ¶
func (_m *MockListener) Close() error
Close provides a mock function with given fields:
type ProcConfig ¶
type ProcConfig struct {
AppName string `json:"app_name"`
AppSrvAddr string `json:"app_server_addr"`
ProcKey ProcKey `json:"proc_key"`
ProcArgs []string `json:"proc_args"`
ProcEnvs []string `json:"proc_envs"` // Additional env variables. Will be overwritten if they conflict with skywire-app specific envs.
ProcWorkDir string `json:"proc_work_dir"`
VisorPK cipher.PubKey `json:"visor_pk"`
RoutingPort routing.Port `json:"routing_port"`
BinaryLoc string `json:"binary_loc"`
LogDBLoc string `json:"log_db_loc"`
LogStorePath string `json:"log_store_path"`
// ProcUser / ProcGroup drop the spawned process to a different
// UID/GID before exec (POSIX, external launcher only). Ignored
// silently when RunFunc != nil (internal launcher) since
// credentials are process-wide.
ProcUser string `json:"proc_user,omitempty"`
ProcGroup string `json:"proc_group,omitempty"`
RunFunc AppFunc `json:"-"`
// RunMode is the explicit dispatch hint. When unset, EffectiveRunMode
// derives the mode from RunFunc presence — preserving legacy callers
// that construct ProcConfig directly without setting RunMode.
RunMode RunMode `json:"run_mode,omitempty"`
// Restart declares the supervisor's reaction when the proc exits.
// Declared now for contract stability; enforcement lands with the
// supervisor pass (#2775 phase 4).
Restart RestartPolicy `json:"restart,omitempty"`
}
ProcConfig defines configuration parameters for `Proc`.
func ProcConfigFromEnv ¶
func ProcConfigFromEnv() (ProcConfig, error)
ProcConfigFromEnv obtains a ProcConfig from the associated env variable, returning an error if any. For internal apps, this also signals that the config has been read, allowing the next app to start.
func (*ProcConfig) ArgVal ¶
func (c *ProcConfig) ArgVal(flag string) string
ArgVal returns the value associated in ProcConfig with a given flag.
func (*ProcConfig) ContainsFlag ¶
func (c *ProcConfig) ContainsFlag(flag string) bool
ContainsFlag checks if a given flag has been passed to the ProcConfig.
func (*ProcConfig) EffectiveRunMode ¶
func (c *ProcConfig) EffectiveRunMode() RunMode
EffectiveRunMode returns the RunMode the proc manager should dispatch on. When RunMode is explicitly set, it wins. Otherwise we fall back to the legacy heuristic — RunFunc != nil → Internal — so existing callers continue to work unchanged.
func (*ProcConfig) EnsureKey ¶
func (c *ProcConfig) EnsureKey()
EnsureKey ensures that a proc key is provided in the ProcConfig.
func (*ProcConfig) Envs ¶
func (c *ProcConfig) Envs() []string
Envs returns the env variables that are passed to the associated proc.
type ProcID ¶
type ProcID uint16
ProcID identifies the current instance of an app (an app process). The visor is responsible for starting apps, and the started process should be provided with a ProcID.
type ProcKey ¶
type ProcKey [16]byte
ProcKey is a unique key to authenticate a proc within the app server.
func (ProcKey) MarshalText ¶
MarshalText implements encoding.TextMarshaller
func (*ProcKey) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaller
type RestartPolicy ¶
type RestartPolicy string
RestartPolicy declares how the supervisor should react when a Proc exits. Currently only Never is enforced — OnFailure and Always are declared up-front so the contract is stable while supervision is wired in a later phase.
const ( // RestartNever leaves the proc stopped when it exits. Operators // must call StartApp again. This matches today's behavior across // all apps. RestartNever RestartPolicy = "" // RestartOnFailure relaunches the proc only when it returned a // non-nil error (or exited non-zero for external procs). RestartOnFailure RestartPolicy = "on-failure" // RestartAlways relaunches the proc on any exit, including clean. RestartAlways RestartPolicy = "always" )
type RunMode ¶
type RunMode string
RunMode declares whether a Proc runs as a separate OS process (External) or as a goroutine inside the visor (Internal). It is the explicit form of what was previously implied by RunFunc != nil.
const ( // RunModeUnspecified means the dispatch path will be derived from // the presence of ProcConfig.RunFunc. Kept for backward // compatibility with code paths that build ProcConfig directly. RunModeUnspecified RunMode = "" // RunModeExternal launches the proc as a separate OS process via // ProcConfig.BinaryLoc. POSIX credentials (ProcUser/ProcGroup) and // stderr capture are honored. RunModeExternal RunMode = "external" // RunModeInternal runs the proc in-process by invoking the AppFunc // stored in ProcConfig.RunFunc. POSIX credential drops are ignored // since setuid is process-wide. RunModeInternal RunMode = "internal" )
Source Files