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

    View Source
    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

    View Source
    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.

      View Source
      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]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 :)
              

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