marshalkit

README

Dogma Marshaling Toolkit

Utilities for marshaling and unmarshaling Dogma messages and other types.

Documentation

Overview

Package marshalkit provides utilities for marshaling and unmarshaling Dogma messages and other types.

Index

• func MustMarshalCommandIntoEnvelope(vm ValueMarshaler, m dogma.Command, env *envelopespec.Envelope)
• func MustMarshalEnvelopeIdentity(id configkit.Identity) *envelopespec.Identity
• func MustMarshalEnvelopeTime(t time.Time) string
• func MustMarshalEventIntoEnvelope(vm ValueMarshaler, m dogma.Event, env *envelopespec.Envelope)
• func MustMarshalMessageIntoEnvelope(vm ValueMarshaler, m dogma.Message, env *envelopespec.Envelope)
• func MustMarshalTimeoutIntoEnvelope(vm ValueMarshaler, m dogma.Timeout, env *envelopespec.Envelope)
• func MustMarshalType(ma TypeMarshaler, rt reflect.Type) string
• func MustUnmarshal(ma ValueMarshaler, p Packet) any
• func MustUnmarshalType(ma TypeMarshaler, n string) reflect.Type
• func Recover(err *error)
• func UnmarshalCommandFromEnvelope(vm ValueMarshaler, env *envelopespec.Envelope) (dogma.Command, error)
• func UnmarshalEnvelopeIdentity(id *envelopespec.Identity) (configkit.Identity, error)
• func UnmarshalEnvelopeTime(t string) (time.Time, error)
• func UnmarshalEventFromEnvelope(vm ValueMarshaler, env *envelopespec.Envelope) (dogma.Event, error)
• func UnmarshalMessageFromEnvelope(vm ValueMarshaler, env *envelopespec.Envelope) (dogma.Message, error)
• func UnmarshalTimeoutFromEnvelope(vm ValueMarshaler, env *envelopespec.Envelope) (dogma.Timeout, error)
• type Marshaler
• type Packet
  • func MustMarshal(ma ValueMarshaler, v any) Packet
  • func NewPacket(mt string, n string, data []byte) Packet
  • func (p *Packet) ParseMediaType() (string, string, error)
• type PanicSentinel
  • func (s PanicSentinel) String() string
• type TypeMarshaler
• type ValueMarshaler

Functions

func MustMarshalCommandIntoEnvelope

func MustMarshalCommandIntoEnvelope(
	vm ValueMarshaler,
	m dogma.Command,
	env *envelopespec.Envelope,
)

MustMarshalCommandIntoEnvelope marshals a dogma.Command into an envelopespec.Envelope.

func MustMarshalEnvelopeIdentity

func MustMarshalEnvelopeIdentity(id configkit.Identity) *envelopespec.Identity

MustMarshalEnvelopeIdentity marshals id to its protocol buffers representation, as used within envelopespec.Envelope.

func MustMarshalEnvelopeTime

func MustMarshalEnvelopeTime(t time.Time) string

MustMarshalEnvelopeTime marshals t to its RFC-3339 representation, as used within envelopespec.Envelope.

func MustMarshalEventIntoEnvelope

func MustMarshalEventIntoEnvelope(
	vm ValueMarshaler,
	m dogma.Event,
	env *envelopespec.Envelope,
)

MustMarshalEventIntoEnvelope marshals a dogma.Event into an envelopespec.Envelope.

func MustMarshalMessageIntoEnvelope

func MustMarshalMessageIntoEnvelope(
	vm ValueMarshaler,
	m dogma.Message,
	env *envelopespec.Envelope,
)

MustMarshalMessageIntoEnvelope marshals a Dogma message into an envelopespec.Envelope.

Deprecated: Use MustMarshalCommandIntoEnvelope, MustMarshalEventIntoEnvelope, or MustMarshalTimeoutIntoEnvelope instead.

func MustMarshalTimeoutIntoEnvelope

func MustMarshalTimeoutIntoEnvelope(
	vm ValueMarshaler,
	m dogma.Timeout,
	env *envelopespec.Envelope,
)

MustMarshalTimeoutIntoEnvelope marshals a dogma.Timeout into an envelopespec.Envelope.

func MustMarshalType

func MustMarshalType(ma TypeMarshaler, rt reflect.Type) string

MustMarshalType marshals rt to its portable representation. It panics if the type can not be marshaled.

func MustUnmarshal

func MustUnmarshal(ma ValueMarshaler, p Packet) any

MustUnmarshal produces a value from its binary representation. It panics if p can not be unmarshalled.

func MustUnmarshalType

func MustUnmarshalType(ma TypeMarshaler, n string) reflect.Type

MustUnmarshalType unmarshals a type from its portable representation. It panics if the type can not be unmarshaled.

func Recover

func Recover(err *error)

Recover recovers from a panic caused by one of the MustXXX() functions.

It is intended to be used in a defer statement. The error that caused the panic is assigned to *err.

func UnmarshalCommandFromEnvelope

func UnmarshalCommandFromEnvelope(
	vm ValueMarshaler,
	env *envelopespec.Envelope,
) (dogma.Command, error)

UnmarshalCommandFromEnvelope unmarshals a dogma.Command from an envelopespec.Envelope.

func UnmarshalEnvelopeIdentity

func UnmarshalEnvelopeIdentity(id *envelopespec.Identity) (configkit.Identity, error)

UnmarshalEnvelopeIdentity unmarshals id from its protocol buffers representation, as used within envelopespec.Envelope.

func UnmarshalEnvelopeTime

func UnmarshalEnvelopeTime(t string) (time.Time, error)

UnmarshalEnvelopeTime unmarshals t from its RFC-3339 representation, as used within envelopespec.Envelope.

func UnmarshalEventFromEnvelope

func UnmarshalEventFromEnvelope(
	vm ValueMarshaler,
	env *envelopespec.Envelope,
) (dogma.Event, error)

UnmarshalEventFromEnvelope unmarshals a dogma.Event from an envelopespec.Envelope.

func UnmarshalMessageFromEnvelope

func UnmarshalMessageFromEnvelope(
	vm ValueMarshaler,
	env *envelopespec.Envelope,
) (dogma.Message, error)

UnmarshalMessageFromEnvelope unmarshals a Dogma message from an envelopespec.Envelope.

Deprecated: Use UnmarshalCommandFromEnvelope, UnmarshalEventFromEnvelope, or UnmarshalTimeoutFromEnvelope instead.

func UnmarshalTimeoutFromEnvelope

func UnmarshalTimeoutFromEnvelope(
	vm ValueMarshaler,
	env *envelopespec.Envelope,
) (dogma.Timeout, error)

UnmarshalTimeoutFromEnvelope unmarshals a dogma.Timeout from an envelopespec.Envelope.

Types

type Marshaler

type Marshaler interface {
	TypeMarshaler
	ValueMarshaler
}

Marshaler is a marshaler that can marshal types and values.

type Packet

type Packet struct {
	// MediaType is a MIME media-type describing the content and encoding of the
	// binary data.
	MediaType string

	// Data is the marshaled binary data.
	Data []byte
}

Packet is a container of marshaled data and its related meta-data.

func MustMarshal

func MustMarshal(ma ValueMarshaler, v any) Packet

MustMarshal returns a binary representation of v. It panics if v can not be marshalled.

func NewPacket

func NewPacket(mt string, n string, data []byte) Packet

NewPacket returns a new packet.

mt is the MIME media-type describing the content and encoding of the binary data. n is the marshaled value's portable type name.

func (*Packet) ParseMediaType

func (p *Packet) ParseMediaType() (string, string, error)

ParseMediaType returns the media-type and the portable type name encoded in the packet's MIME media-type.

type PanicSentinel

type PanicSentinel struct {
	// Cause is the error that caused the panic.
	Cause error
}

PanicSentinel is a wrapper value used to identify panic's that are caused by one of the MustXXX() functions.

func (PanicSentinel) String

func (s PanicSentinel) String() string

type TypeMarshaler

type TypeMarshaler interface {
	// MarshalType marshals a type to its portable representation.
	MarshalType(rt reflect.Type) (string, error)

	// UnmarshalType unmarshals a type from its portable representation.
	UnmarshalType(n string) (reflect.Type, error)
}

A TypeMarshaler marshals and unmarshals Go types to and from "portable" string representations.

type ValueMarshaler

type ValueMarshaler interface {
	// Marshal returns a binary representation of v.
	Marshal(v any) (Packet, error)

	// MarshalAs returns a binary representation of v encoded using a format
	// associated with one of the supplied media-types.
	//
	// mediaTypes is a list of acceptible media-types, in order of preference.
	// If none of the media-types are supported, ok is false.
	MarshalAs(v any, mediaTypes []string) (p Packet, ok bool, err error)

	// Unmarshal produces a value from its binary representation.
	Unmarshal(p Packet) (any, error)

	// MediaTypesFor returns the media-types that the marshaler can use to
	// represent the given type, in order of preference.
	//
	// It returns an empty slice if the type is not supported.
	MediaTypesFor(reflect.Type) []string
}

A ValueMarshaler marshals and unmarshals arbitrary Go values.