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, userArgs []string, 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

Constants

const (
    // ArgsDelim separates args for user program from the args needed by this
    // luciexe wrapper (e.g. `--output` flag). All args provided after the
    // first ArgsDelim will passed to user program.
    ArgsDelim = "--"
)

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.

var Null = nullType{}

Null is a sentinel value to assign JSON `null` to a property with WriteProperties.

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.

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 "encoding/json" marshal source. The data in this field will be
  interpreted as json and marshaled with the stdlib "encoding/json" package.
* The `Null` value in this package. The top-level property will be set to
  JSON `null`.
* nil. The top-level property will be removed.

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, userargs []string, send BuildSender) error

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

Args:

- ctx: The context will be canceled when the program receives the os
 Interrupt or SIGTERM (on unix) signal. The context also has standard go
 logging setup.
- input: The initial Build state, as read from stdin. The build is not
 protected by a mutex of any sort, so the `MainFn` is responsible
 for protecting it if it can be modified from multiple goroutines.
- userArgs: All command line arguments supplied after first `ArgsDelim`.
- send: A send func which should be called after modifying the provided
 build. 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.

input.Output.Properties is initialized to an empty Struct so you can use WriteProperties right away.

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 22 packages (graph) and is imported by 5 packages. Updated 2020-10-01. Refresh now. Tools for package owners.