github.com/tilt-dev/tilt@v0.33.15-0.20240515162809-0a22ed45d8a0/internal/tiltfile/starkit/plugin.go (about)

     1  package starkit
     2  
     3  import "go.starlark.net/starlark"
     4  
     5  // An plugin to a starlark execution environment.
     6  type Plugin interface {
     7  	// Called when execution begins.
     8  	OnStart(e *Environment) error
     9  }
    10  
    11  type OnExecPlugin interface {
    12  	Plugin
    13  
    14  	// Called before each new Starlark file is loaded
    15  	OnExec(t *starlark.Thread, path string, contents []byte) error
    16  }
    17  
    18  type OnBuiltinCallPlugin interface {
    19  	Plugin
    20  
    21  	// Called before each builtin is called
    22  	OnBuiltinCall(name string, fn *starlark.Builtin)
    23  }
    24  
    25  // Starkit plugins are not allowed to have mutable state.
    26  //
    27  // Starlark has different ideas about mutable state than most programming languages.
    28  // In particular, state is mutable during file execution, but becomes immutable
    29  // when it's imported into other files.
    30  //
    31  // This allows Starlark to execute files in parallel without locks.
    32  //
    33  // To play more nicely with Starlark, Starkit plugins manage state
    34  // with an init/reduce pattern. That means each plugin should define:
    35  //
    36  // 1) An initial state (created with NewModel())
    37  // 2) Make subsequent mutations to state with starkit.SetState
    38  //
    39  // At the end of execution, Starkit will return a data model
    40  // with the accumulated state from all plugins.
    41  //
    42  // See: https://github.com/google/starlark-go/blob/master/doc/spec.md#identity-and-mutation
    43  type StatefulPlugin interface {
    44  	Plugin
    45  
    46  	NewState() interface{}
    47  }