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)
- 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, walking it when the last walk is older than walkEvery, and refuses once it is 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.
func (*Meter) Settle ¶
func (m *Meter) Settle(globals starlark.StringDict)
Settle records what the module's globals hold when the script ends, so the peak includes what it built after its last 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