spur

spur

Structured Processing Uniform Results (spur) implements a set of common result types used to report processing success and or issues in a consistent manner.

Spur can be though of as structured logging that is returned to the caller rather than output.

Installation

Install the project to your GOPATH using

go get -u https://github.com/nehemming/spur

or clone this repo to your local machine using

git clone https://github.com/nehemming/spur

This project requires Go 1.15 or newer and supports modules.

Key features

• Standardized result model, with severity levels, error codes and timestamps.
• Processing results can be returned from a processing unit to its caller
• Attach structured meta data
• Error messages can be embedded or extracted from pulp TextProviders
• Supports marshalling to and from JSON or YAML
• Aggregate sets of results in a Results object

Getting started

Simple example of using as a function result

package main

import (
    "fmt"

    "github.com/nehemming/spur"
)

var (
    WorkerDone = spur.Make(1, 34)
)

func worker(input int) spur.Result {

    // worker
    // basic example with fixed error message
    return spur.NewInfo(WorkerDone, spur.NMeta("worker", 1)).
        WithMessage("Done ${worker} ${1:%03d}", input).Result()
}

func main() {

    res := worker(10)
    fmt.Println(res.Message())

    // run a few more

    results := spur.New(worker(11), worker(12))

    for _, v := range results.Results() {

        fmt.Println(v.Level(), v.Message())
    }
}

// Output:
// Done 1 010
// Info Done 1 011
// Info Done 1 012

Levels

Success results are never stored, as such an empty Results collection can be consider successful

Embedded error messages

The result builder WithMessage function is used to add a message to the result. The message supports the formatting with expansion of either the optional args or the structured meta data.

Meta data arguments can be expanded via their meta data key in the format ${key}.

The positional arguments are expanded using ${n} where n is the args position, starting at 1.

Both positional and meta data args may have a optional format specifier added after the key name separated by a :
The format uses the standard Go formatting strings. For example ${1:%05d} output arg 1 in format %05d.
If no format is specified %v is assumed.

Integration with Pulp

The result builder can also create messages using Pulp's TextProvider framework.

To use, call the builder WithLookupMessage. This accepts a Go context which is used to locate the active message provider. If no provider is found the function uses the ShareProvider. It is also possible to append positional arguments. These are expanded using the ${n} format as above.

The TextID for the message is located using ResultCoder param passed in to the result message New function

package spur_test

import (
    "context"
    "fmt"

    "github.com/nehemming/pulp"
    "github.com/nehemming/spur"
    "golang.org/x/text/language"
)

// myPackID is the unique type to identify my language packs in pulp
type myPackID int

const (
    // Create a langPack language pack id
    // See pulp for more info on language pack ids
    LangPack = myPackID(iota)
)

// MyResultCode is the unique code type that we will use for this packages results
// The result code implements the ResultCoder interface so it can be used with spur and
// also Stringer so that the result codes output the same string as the ResultCoder interface
// will generate.
type MyResultCode int

// Create unique error code ids
const (

    // Good practice to create a Zero value messages for all types
    NoProblem = MyResultCode(iota)

    // MyWorkIsDone is the messaged id that work is complete
    MyWorkIsDone
)

func (c MyResultCode) ResultCode() spur.ResultCode {

    // The MyWorkIsDone has a underlying value of int 1
    // This demonstrates how the id can be used to create a
    // different result code value (and show its not the result code thats used to locate the message)
    return spur.Make(int(c), 19)
}

func (c MyResultCode) String() string {

    // Having gon to the effort to make result codes different
    // we can now use the result code string function to create a consistent
    // output string.
    // (ResultCode().String() actually uses pulp to find the standard output format)
    return c.ResultCode().String()
}

//myWorker does some work
func myWorker(ctx context.Context, input int) spur.Result {

    // worker
    // basic example with looked up message

    // Meta "worker" is passed in as is the input as pos arg $1
    // WithLookupMessage will use the MyWorkIsDone id to locate the result
    // message.
    return spur.NewInfo(MyWorkIsDone, spur.NMeta("worker", 1)).
        WithLookupMessage(ctx, input).Result()
}

func init() {

    // Register formats and english language pack
    pulp.Register(LangPack, func(packID pulp.LangPackID, langTag language.Tag) (pulp.TextMap, []pulp.NamedArg) {

        return pulp.TextMap{
            // creating an in line text map for simplicity.
            // the ${@id} format is a special pulp parameter that returns the string representation of the
            // the code used to look up this error message (essentially MyWorkIsDone.String() here)
            MyWorkIsDone: "Done ${worker} ${1:%03d} today ${@id}",
        }, nil
    }, pulp.Package, language.English)
}

func main() {

    res := myWorker(context.TODO(), 10)

    if res.ResultCode() != NoProblem.ResultCode() {
        fmt.Println(res.Message())
    }
    // Output:
    // Done 1 010 today 013-00001
}

Contributing

We would welcome contributions to this project. Please read our CONTRIBUTION file for further details on how you can participate or report any issues.

License

MIT