luci: go.chromium.org/luci/luciexe/exe Index | Files

package exe

import "go.chromium.org/luci/luciexe/exe"

Package exe implements a client for the LUCI Executable ("luciexe") protocol.

The simplest luciexe is:

import (
  "context"

  "go.chromium.org/luci/luciexe/exe"

  bbpb "go.chromium.org/luci/buildbucket/proto"
)

func main() {
  exe.Run(func(ctx context.Context, input *bbpb.Build, send exe.BuildSender) error {
    ... do whatever you want here ...
    return nil // nil error indicates successful build.
  })
}

See Also: https://go.chromium.org/luci/luciexe

Index

Package Files

doc.go exe.go options.go props.go

Variables

var InfraErrorTag = errors.BoolTag{Key: errors.NewTagKey("infra_error")}

InfraErrorTag should be set on errors returned from the `main` callback of Run.

Errors with this tag set will cause the overall build status to be INFRA_FAILURE instead of FAILURE.

func ParseProperties Uses

func ParseProperties(props *structpb.Struct, outputs map[string]interface{}) error

ParseProperties interprets a protobuf 'struct' as structured Go data.

`outputs` is a mapping of a property name to an output structure. An output structure may be one of two things:

* a non-nil proto.Message. The data in this field will be interpreted as
  JSONPB and Unmarshaled into the proto.Message.
* a valid "encoding/json" unmarshal target. The data in this field will be
  unmarshaled into with the stdlib "encoding/json" package.

This function will scan the props (usually `build.Input.Properties`) and unmarshal them as appropriate into the outputs.

Example:

myProto := &myprotos.Message{}
myStruct := &MyStruct{}
err := ParseProperties(build.Input.Properties, map[string]interface{}{
  "proto": myProto, "$namespaced/struct": myStruct})
// handle err :)
fmt.Println("Got:", myProto.Field)
fmt.Println("Got:", myStruct.Field)

func Run Uses

func Run(main MainFn, options ...Option)

Run executes the `main` callback with a basic Context.

The context will be canceled when the program receives the os.Interrupt or SIGTERM (on unix) signal.

The context has standard go logging setup.

The main function is also given a *Build (the initial Build state, as read from stdin), and a BuildSender (which should be called after modifying the provided *Build).

The *Build is not protected by a mutex of any sort, so the `main` function is responsible for protecting it if it can be modified from multiple goroutines.

The BuildSender is synchronous and locked; it may only be called once at a time. It will marshal the current *Build, then send it. Writes to the *Build should be synchronized with calls to the BuildSender.

This calls os.Exit on completion of `main`, or panics if something went wrong. If main panics, this is converted to an INFRA_FAILURE. If main returns a non-nil error, this is converted to FAILURE, unless the InfraErrorTag is set on the error (in which case it's converted to INFRA_FAILURE).

func WriteProperties Uses

func WriteProperties(props *structpb.Struct, inputs map[string]interface{}) error

WriteProperties updates a protobuf 'struct' with structured Go data.

`inputs` is a mapping of a property name to an input structure. An input structure may be one of two things:

* a non-nil proto.Message. The data in this field will be interpreted as
  JSONPB and Unmarshaled into the proto.Message.
* a valid "json/encoding" marshal source. The data in this field will be
  interpreted as json and marshaled with the stdlib "encoding/json" package.

This function will scan the inputs and marshal them as appropriate into `props` (usually `build.Output.Properties`).

Example:

myProto := &myprotos.Message{Field: "something"}
myStruct := &MyStruct{Field: 100}
err := WriteProperties(build.Output.Properties, map[string]interface{}{
  "proto": myProto, "$namespaced/struct": myStruct})
// handle err :)

type BuildSender Uses

type BuildSender func()

BuildSender is a function which may be called within the callback of Run to update this program's Build state.

This function is bound to the Build message given to the `main` callback of Run.

Panics if it cannot send the Build (which is never expected in normal operation).

type MainFn Uses

type MainFn func(ctx context.Context, input *bbpb.Build, send BuildSender) error

MainFn is the function signature you must implement in your callback to Run.

type Option Uses

type Option func(*config)

Option is a type that allows you to modify the behavior of Run.

See With* methods for available Options.

func WithZlibCompression Uses

func WithZlibCompression(level int) Option

WithZlibCompression returns an Option; If unspecified, no compression will be applied to the outgoing Build.proto stream. Otherwise zlib compression at `level` will be used.

level is capped between NoCompression and BestCompression.

If level is NoCompression, it's the same as not specifying this option (i.e. no zlib wrapper will be used at all).

Package exe imports 21 packages (graph) and is imported by 2 packages. Updated 2019-11-12. Refresh now. Tools for package owners.