yaml

README

yaml

package yaml provides mechanisms for serializing and deserializing spam policies in YAML.

spam uses protocol buffers as the canonical format for several reasons:

• Most invalid states are impossible to represent. For example, proto has sum types, while Go does not.
• Efficient wire format for transmission and storage.
• The protocol buffer compiler writes all the risky parsing code.

That being said, for human consumption, textproto spam policies leave a bit to be desired.

YAML is a JSON-based text serialization format that has human readability as its top priority.

For very complex policies, the define key may be used to set up anchors that can be referred to later, in the actual policy. See the below example.

Variables

var (
    ErrBadSumType     = errors.New("too many members were set on this sum type")
    ErrInvalidOperand = errors.New("operand must be 0x followed by a hex string of at least 1 byte")
)

Functions

func DebugString

func DebugString(p *policypb.Policy) string

DebugString converts a spam policy into YAML or the error string from attempting to do so.

func Decode

func Decode(s string) (*policypb.Policy, error)

Decode parses a YAML document for a spam policy, and converts it into the canonical protobuf form.

package main

import (
	"fmt"
	"github.com/chrisfenner/tpm-spam/pkg/yaml"
	"google.golang.org/protobuf/encoding/prototext"
)

func main() {
	policy := `
# Set up some anchors - these aren't part of the parsed policy until aliased.
define:
  - &spam2_major_version_greater_than_5
      spam:
        index: 2
        offset: 8
        gt: 0x00000005
  - &spam2_minor_version_greater_than_10
      spam:
        index: 2
        offset: 12
        gt: 0x0000000a
and:
  - or:
    - spam:
        index: 1
        offset: 0
        eq: 0x0001020304050607
    - spam:
        index: 1
        offset: 0
        eq: 0x08090A0B0C0D0E0F
  - or:
    - *spam2_major_version_greater_than_5
    - *spam2_minor_version_greater_than_10`
	proto := yaml.DecodeOrPanic(policy)
	opts := prototext.MarshalOptions{
		Multiline: true,
		Indent:    "  ",
	}
	fmt.Println(opts.Format(proto))
}

func DecodeOrPanic

func DecodeOrPanic(s string) *policypb.Policy

DecodeOrPanic parses a YAML document for a spam policy, or panics if there is an error.

func Encode

func Encode(p *policypb.Policy) (*string, error)

Encode converts a spam policy from the canonical protobuf form into more human-readable YAML form.

Types

type Policy

type Policy struct { ... }

INTERNAL: Only exported for manipulation by the yaml package.

type SpamPolicy

type SpamPolicy struct { ... }

INTERNAL: Only exported for manipulation by the yaml package.

---

Readme created from Go doc with goreadme

Documentation

Overview

package yaml provides mechanisms for serializing and deserializing spam policies in YAML.

spam uses protocol buffers as the canonical format for several reasons: * Most invalid states are impossible to represent. For example, proto has sum types, while Go does not. * Efficient wire format for transmission and storage. * The protocol buffer compiler writes all the risky parsing code.

That being said, for human consumption, textproto spam policies leave a bit to be desired.

YAML is a JSON-based text serialization format that has human readability as its top priority.

For very complex policies, the `define` key may be used to set up anchors that can be referred to later, in the actual policy. See the below example.

Index

• Variables
• func DebugString(p *policypb.Policy) string
• func Decode(s string) (*policypb.Policy, error)
• func DecodeOrPanic(s string) *policypb.Policy
• func Encode(p *policypb.Policy) (*string, error)
• type Policy
• type SpamPolicy

Examples

• Decode

Variables

var (
	ErrBadSumType     = errors.New("too many members were set on this sum type")
	ErrInvalidOperand = errors.New("operand must be 0x followed by a hex string of at least 1 byte")
)

Functions

func DebugString

func DebugString(p *policypb.Policy) string

DebugString converts a spam policy into YAML or the error string from attempting to do so.

func Decode

func Decode(s string) (*policypb.Policy, error)

Decode parses a YAML document for a spam policy, and converts it into the canonical protobuf form.

Example

package main

import (
	"fmt"

	"google.golang.org/protobuf/encoding/prototext"

	"github.com/chrisfenner/tpm-spam/pkg/yaml"
)

func main() {
	policy := `
# Set up some anchors - these aren't part of the parsed policy until aliased.
define:
  - &spam2_major_version_greater_than_5
      spam:
        index: 2
        offset: 8
        gt: 0x00000005
  - &spam2_minor_version_greater_than_10
      spam:
        index: 2
        offset: 12
        gt: 0x0000000a
and:
  - or:
    - spam:
        index: 1
        offset: 0
        eq: 0x0001020304050607
    - spam:
        index: 1
        offset: 0
        eq: 0x08090A0B0C0D0E0F
  - or:
    - *spam2_major_version_greater_than_5
    - *spam2_minor_version_greater_than_10`
	proto := yaml.DecodeOrPanic(policy)
	opts := prototext.MarshalOptions{
		Multiline: true,
		Indent:    "  ",
	}
	fmt.Println(opts.Format(proto))
}

func DecodeOrPanic

func DecodeOrPanic(s string) *policypb.Policy

DecodeOrPanic parses a YAML document for a spam policy, or panics if there is an error.

func Encode

func Encode(p *policypb.Policy) (*string, error)

Encode converts a spam policy from the canonical protobuf form into more human-readable YAML form.

Types

type Policy

type Policy struct {
	And  []*Policy   `yaml:",omitempty"`
	Or   []*Policy   `yaml:",omitempty"`
	Spam *SpamPolicy `yaml:",flow,omitempty"`
	// Define is ignored when assembling policies: use it to define anchors for readability.
	Define []interface{}
}

INTERNAL: Only exported for manipulation by the `yaml` package.

type SpamPolicy

type SpamPolicy struct {
	Index    uint32
	Offset   uint32
	Eq       string `yaml:",omitempty"`
	Neq      string `yaml:",omitempty"`
	Gt       string `yaml:",omitempty"`
	Gte      string `yaml:",omitempty"`
	Lt       string `yaml:",omitempty"`
	Lte      string `yaml:",omitempty"`
	Bitset   string `yaml:",omitempty"`
	Bitclear string `yaml:",omitempty"`
}

INTERNAL: Only exported for manipulation by the `yaml` package.