Back to godoc.org

Package exe

v0.0.0-...-1557bcf
Latest Go to latest

The latest major version is .

Published: Aug 13, 2020 | License: Apache-2.0 | Module: github.com/luci/luci-go

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

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

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

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]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

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

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier