Package virgil

import "bitbucket.org/techmarionette/virgil"

Overview
Index
Examples

Overview

Package virgil defines the communication protocol between Eris and the outside world.

(c)2020 Tech Marionette Limited

Index

Constants
func Errors(msgs []Message) bool
func Failures(msgs []Message) bool
type Builder
func NewBuilder(columns ...string) Builder
type Error
func NewError(msg string) Error
func WrappedError(msg string, err error) Error
func (e Error) Error() string
func (e Error) Safe() string
type Fields
func (f Fields) Keys() []string
type Log
func NewLog() Log
type Logger
func NewLogger(fields Fields, channel chan<- Message) Logger
type Message
func (m Message) String() string
type ResultSet
func (r *ResultSet) UnmarshalJSON(b []byte) error
type Results
func EmptyResults() Results
func SingleResult(name string, data interface{}) Results
type Stats
func NewStats(messages []Message) Stats
func (s Stats) Delta(stats Stats) Stats
func (s Stats) Errors() bool
func (s Stats) Failures() bool
type Type

Examples

(Expand All)

EmptyResults
Errors
Failures
Fields.Keys
Message.String
NewBuilder
NewError
NewLog
NewStats
SingleResult
Stats.Delta
Stats.Errors
Stats.Failures
WrappedError

Package files

doc.go error.go fields.go log.go logger.go message.go results.go resultset.go stats.go

Constants

const (
    // SuccessMessage is generated for an operation that succeeded.
    SuccessMessage = Type("success")

    // FailureMessage is generated for an operation that failed due to invalid
    // input (as opposed to server error).
    FailureMessage = Type("failure")

    // InfoMessage is an informational message about an operation.
    InfoMessage = Type("info")

    // WarnMessage is a warning about an operation. A warning is not as severe
    // as a failure or an error, but may indicate that something is not right.
    WarnMessage = Type("warn")

    // ErrorMessage is generated if the server encountered an error while
    // processing an action. The error will have stopped some, or all of the
    // operation from completing.
    ErrorMessage = Type("error")
)

Empty returned if the result string is empty.

const Empty = "[empty]"

func Errors

func Errors(msgs []Message) bool

Errors returns true if any of the messages provided are error messages.

Example

Code:

fmt.Println(virgil.Errors([]virgil.Message{}))
fmt.Println(virgil.Errors([]virgil.Message{
    {Type: virgil.SuccessMessage},
}))
fmt.Println(virgil.Errors([]virgil.Message{
    {Type: virgil.FailureMessage},
}))
fmt.Println(virgil.Errors([]virgil.Message{
    {Type: virgil.ErrorMessage},
}))

Output:

false
false
false
true

func Failures

func Failures(msgs []Message) bool

Failures returns true if any of the messages provided are failure or error messages.

Example

Code:

fmt.Println(virgil.Failures([]virgil.Message{}))
fmt.Println(virgil.Failures([]virgil.Message{
    {Type: virgil.SuccessMessage},
}))
fmt.Println(virgil.Failures([]virgil.Message{
    {Type: virgil.FailureMessage},
}))
fmt.Println(virgil.Failures([]virgil.Message{
    {Type: virgil.ErrorMessage},
}))

Output:

false
false
true
true

type Builder

A Builder is used to build a set of Results.

type Builder interface {
    // Append a row to the builder. The row will either be padded with nils, or
    // truncated to match the columns set on the builder.
    Append(row ...interface{})

    // Overwrite the rows in the builder. The input rows are not checked for
    // validity.
    Overwrite(rows [][]interface{})

    // Return the built results.
    Results() Results

    // Validate the rows in the builder.
    Validate() bool
}

func NewBuilder

func NewBuilder(columns ...string) Builder

NewBuilder returns a builder with the given columns.

Example

Code:

b := virgil.NewBuilder("column 1", "column 2")
b.Append("a", "b")
b.Append("A", "B", "C")
b.Append("1")

fmt.Println(b.Results())

b.Overwrite([][]interface{}{{"1", "2"}})

fmt.Println(b.Results())

Output:

column 1, column 2
a, b
A, B
1, <nil>
column 1, column 2
1, 2

type Error

Error type that can be used to record and log and error while not potentially exposing implementation details or data. Virgil will attempt to discard all standard error types, although will log the safe messages from a Virgil error type.

type Error struct {
    // contains filtered or unexported fields
}

func NewError

func NewError(msg string) Error

NewError returns a new Virgil error type with a message which will be used for both the safe and unsafe messages.

Example

Code:

e := virgil.NewError("message")

fmt.Println(e)
fmt.Println(e.Safe())

Output:

message
message

func WrappedError

func WrappedError(msg string, err error) Error

WrappedError wraps an existing error providing a safe client facing message to use.

Example

Code:

e := virgil.WrappedError("safe", errors.New("unsafe"))

fmt.Println(e)
fmt.Println(e.Safe())

Output:

unsafe
safe

func (Error) Error

func (e Error) Error() string

Error returns the unsafe error message. Since this is replicating an error type we need to assume that if it's cast to error we may be leaking the message.

func (Error) Safe

func (e Error) Safe() string

Safe error message recorded by this error type.

type Fields

Fields embellish a message. While fields accept interface{} they should only be used to store types that can be marshalled into JSON.

type Fields map[string]interface{}

func (Fields) Keys

func (f Fields) Keys() []string

Keys returns a sorted slice of the keys for this set of fields.

Example

Code:

fmt.Println(virgil.Fields{"a": "1", "b": "2"}.Keys())
fmt.Println(virgil.Fields{"b": "1", "a": "2"}.Keys())

Output:

[a b]
[a b]

type Log

Log collates messages generated by a Logger.

type Log interface {
    Logger

    // WithField allows a message to be logged with a supporting field.
    WithField(name string, value interface{}) Logger

    // WithFields allows a message to be logged with supporting fields.
    WithFields(fields Fields) Logger

    // Events seen by the event log.
    Events() []Message

    // Checkpoint the log, obtaining the current stats seen by the log.
    Checkpoint() Stats
}

func NewLog

func NewLog() Log

NewLog returns a new log to collate messages.

Example

Code:

l := virgil.NewLog()

l.WithField("test", "field").Success("A success message")
l.WithFields(virgil.Fields{"a": "1", "b": "2"}).Info("An info message")
l.Failure("A failure message")
l.Warn("A warn message")
l.WithField("error", errors.New("e")).Error("An error message")
l.WithField("safe", virgil.NewError("error")).Error("A safe error")

for _, message := range l.Events() {
    fmt.Println(message.String())
}

Output:

[success] A success message {test:field}
[info   ] An info message {a:1, b:2}
[failure] A failure message
[warn   ] A warn message
[error  ] An error message
[error  ] A safe error {safe:error}

type Logger

Logger is used to record log messages.

type Logger interface {

    // Success message, recorded when a particular operation has succeeded.
    // Success messages can exist with Failure and Error messages if an
    // operation was only partially successful.
    Success(msg string)

    // Failure message, recorded when a particular operation has failed. Failure
    // messages can exist with Success messages if an operation has only
    // partially failed. Failure messages are generally used to indicate that
    // one operation in a set of many has failed.
    Failure(msg string)

    // Info message using to indicate something has happened, or return data on
    // something that has happened.
    Info(msg string)

    // Warn message, recorded when some unexpected event has occurred that isn't
    // classified as an error, or failure, but that may require investigation.
    Warn(msg string)

    // Error message, recorded when a particular operation encounters an error.
    // Errors are typically internal application errors which are unexpected.
    // Problems caused by incorrect input data should be reported as failures.
    Error(msg string)
}

func NewLogger

func NewLogger(fields Fields, channel chan<- Message) Logger

NewLogger returns a new logger for the given fields. The logger reports messages to two destinations. Firstly a message with a filtered set of fields is put onto the given channel. Fields are filtered by removing error types and only reporting the safe message from Virgil error types. Secondly messages are logged via logrus using an embellished set of fields. Fields are embellished by the addition of the safe message from Virgil error types alongside the wrapped error message, plus the message type for failure and success messages. Messages are logged at INFO level for Success and Info message types, WARN level for Failure and Warn message types, and ERROR level for Error message types.

type Message

Message is used to pass log/event style messages to the client.

type Message struct {
    Type   `json:"type"`
    Fields `json:"fields"`

    // Text payload of the message.
    Text string `json:"text"`
}

func (Message) String

func (m Message) String() string

String representation of a message. The message fields are flattened into the string.

Example

Code:

fmt.Println(virgil.Message{
    Type: virgil.SuccessMessage,
    Text: "Message body",
})

fmt.Println(virgil.Message{
    Type:   virgil.FailureMessage,
    Text:   "Message body",
    Fields: virgil.Fields{"error": "failure reason"},
})

fmt.Println(virgil.Message{
    Type:   virgil.InfoMessage,
    Text:   "Message body",
    Fields: virgil.Fields{"field": "value"},
})

fmt.Println(virgil.Message{
    Type: virgil.WarnMessage,
    Text: "Message body",
})

fmt.Println(virgil.Message{
    Type:   virgil.ErrorMessage,
    Text:   "Message body",
    Fields: virgil.Fields{"error": "failure reason"},
})

Output:

[success] Message body
[failure] Message body {error:failure reason}
[info   ] Message body {field:value}
[warn   ] Message body
[error  ] Message body {error:failure reason}

type ResultSet

ResultSet created by Eris when some Orphic has been run. Each element in Data can be a different width.

type ResultSet struct {
    Data []Results `json:"data"`

    // Messages generated while running the Orphic.
    Messages []Message `json:"messages"`
}

func (*ResultSet) UnmarshalJSON

func (r *ResultSet) UnmarshalJSON(b []byte) error

UnmarshalJSON handles unmarshalling a JSON representation of the ResultSet.

type Results

Results returned from an Orphic query.

type Results interface {
    Columns() []string
    Rows() [][]interface{}
    String() string
}

func EmptyResults

func EmptyResults() Results

EmptyResults returns a set of empty results.

Example

Code:

fmt.Println(virgil.EmptyResults())

Output:

[empty]

func SingleResult

func SingleResult(name string, data interface{}) Results

SingleResult builds a Results type with a single item of data (i.e. one column, one row).

Example

Code:

r := virgil.SingleResult("column", "data")
fmt.Println(r.Columns())
fmt.Println(r.Rows())

Output:

[column]
[[data]]

type Stats

Stats block for message types.

type Stats struct {
    Success int
    Failure int
    Info    int
    Warn    int
    Error   int
}

func NewStats

func NewStats(messages []Message) Stats

NewStats returns a set of stats for the given messages. Unknown message tpyes are treated as errors.

Example

Code:

m := []virgil.Message{
    {Type: virgil.SuccessMessage},
    {Type: virgil.FailureMessage},
    {Type: virgil.InfoMessage},
    {Type: virgil.WarnMessage},
    {Type: virgil.ErrorMessage},
}

fmt.Println(virgil.NewStats(m))

Output:

{1 1 1 1 1}

func (Stats) Delta

func (s Stats) Delta(stats Stats) Stats

Delta returns the different between two sets of stats, subtracting the submitted stats from the current stats.

Example

Code:

l := virgil.NewLog()
l.Failure("a failure")

c := l.Checkpoint()

l.Error("an error")

d := l.Checkpoint().Delta(c)

fmt.Println(c)
fmt.Println(d)
fmt.Println(l.Checkpoint())

Output:

{0 1 0 0 0}
{0 0 0 0 1}
{0 1 0 0 1}

func (Stats) Errors

func (s Stats) Errors() bool

Errors returns true if the stats contain any Error message types.

Example

Code:

c := virgil.Stats{}

if !c.Errors() {
    c.Failure++
}

if !c.Errors() {
    c.Error++
}

if c.Errors() {
    fmt.Println(c)
}

Output:

{0 1 0 0 1}

func (Stats) Failures

func (s Stats) Failures() bool

Failures returns true if the stats contain any Failure or Error message types.

Example

Code:

c := virgil.Stats{}

if !c.Failures() {
    c.Error++
}

if c.Failures() {
    c.Failure++
}

if c.Failures() {
    fmt.Println(c)
}

Output:

{0 1 0 0 1}

type Type

Type of Message being sent. Many message of the same type can appear in a set of message as an action may involve many operations.

type Type string

bitbucket.org/techmarionette/virgil

Virgil

JSON Format