Documentation
¶
Overview ¶
Package scriptguard is what stops a managed-script run apart from the script's own logic, and what that stop is recorded as: the memory budget a run is measured against at every host call (#1861), and the cause a failed run is recorded under -- the script's, an upstream that did not answer, or the budget -- which decides whether running it again is expected to succeed (#1859).
It knows the Starlark value model, and nothing about runs, stores or workers: the engine in internal/platform/scriptrun calls into it at its host bindings. The waits the host makes on an upstream that asked it to come back later are internal/upstreamretry's.
Index ¶
- Variables
- func Cause(err error) string
- func FormatBytes(n int64) string
- func Size(v starlark.Value) int64
- type Meter
- func (m *Meter) Called(tool string)
- func (m *Meter) Check(thread *starlark.Thread, at string) error
- func (m *Meter) Handed(thread *starlark.Thread, at string, result starlark.Value) error
- func (m *Meter) Holding(n int64)
- func (m *Meter) Peak() int64
- func (m *Meter) Settle(globals starlark.StringDict) error
- type UpstreamError
Constants ¶
This section is empty.
Variables ¶
var ErrMemoryBudget = errors.New("script exceeded its memory budget")
ErrMemoryBudget marks a run stopped for holding more memory than its budget.
Functions ¶
func Cause ¶
Cause is the cause a run that failed with err is recorded under: memory for a budget it exceeded, upstream for an upstream that was unavailable, and the script's own for every other failure the interpreter reports, which is what reproduces on the same inputs.
func FormatBytes ¶
FormatBytes renders a size the way the budget is configured: "128 MiB".
Types ¶
type Meter ¶
type Meter struct {
// contains filtered or unexported fields
}
Meter measures what one run holds against its budget and keeps the peak. It is used from the interpreter's goroutine only, at host calls.
func NewMeter ¶
NewMeter returns a meter for a run allowed budget bytes; zero or less sets no budget and still measures the peak.
func (*Meter) Called ¶
Called counts one tool result the run was handed, for the refusal to say where its memory came from.
func (*Meter) Check ¶
Check measures what the thread holds at the host call named at, and refuses once it is over the budget. It walks the thread when the last walk is older than walkEvery, or when the last estimate plus what the process has allocated since could be over the budget. A nil meter measures nothing.
func (*Meter) Handed ¶
Handed adds a value a host call is about to hand the script to the estimate, and refuses when it takes the run over its budget.
func (*Meter) Holding ¶
Holding records how much the run holds outside the interpreter, replacing the last figure. The figure is measured, not estimated, so it counts toward the peak.
func (*Meter) Settle ¶
func (m *Meter) Settle(globals starlark.StringDict) error
Settle measures what the module's globals hold when the script ends, so the peak includes what it built after its last host call, and refuses when that is over the budget: a run that ended holding more than it is allowed failed its budget as surely as one stopped at a host call.
type UpstreamError ¶
type UpstreamError struct {
// Tool is the tool the script called.
Tool string
// contains filtered or unexported fields
}
UpstreamError is a tool call that failed because the upstream it reached was unavailable: it timed out, dropped the connection, or could not be reached, or the run's deadline arrived while the host was waiting to retry it. The same call made later is expected to succeed, so a run it ends is recorded as retryable.
func NewUpstreamError ¶
func NewUpstreamError(tool string, err error) *UpstreamError
NewUpstreamError wraps the failure of a call to tool as an upstream one.
func (*UpstreamError) Error ¶
func (e *UpstreamError) Error() string
Error returns the tool's own failure text, which is what the author reads.
func (*UpstreamError) Unwrap ¶
func (e *UpstreamError) Unwrap() error
Unwrap returns the failure the tool reported.
Source Files