exe

Documentation

Overview

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

• Constants
• Variables
• func ParseProperties(props *structpb.Struct, outputs map[string]any) error
• func Run(main MainFn, options ...Option)
• func WriteProperties(props *structpb.Struct, inputs map[string]any) error
• type BuildSender
• type MainFn
• type Option
  • func WithZlibCompression(level int) Option

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.

Functions

func ParseProperties

func ParseProperties(props *structpb.Struct, outputs map[string]any) 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]any{
  "proto": myProto, "$namespaced/struct": myStruct})
// handle err :)
fmt.Println("Got:", myProto.Field)
fmt.Println("Got:", myStruct.Field)

func Run

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

func WriteProperties(props *structpb.Struct, inputs map[string]any) 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]any{
  "proto": myProto, "$namespaced/struct": myStruct})
// handle err :)

Types

type BuildSender

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

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

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

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).