media

Documentation

Overview

Package media normalizes encoding and decoding by providing a registry of encoders and decoders for MIME types.

Create applications supporting multiple encoding types by importing this media package and specific encoding packages to register their encoders and decoders with a MIME type. Once registered, encoders/decoders can be pulled from the registry by providing a MIME type.

The following partial example demonstrates how to create a net/http Handler capable of returning a response whose body is encoded as either JSON or Protocol Buffers depending on the HTTP request's "Accept" header.

import (
  "net/http"

  "github.com/go-goo/encoding/media"
  _ "github.com/go-goo/encoding/media/json"
  _ "github.com/go-goo/encoding/media/proto"
)

// valid protobuf message
type Thing struct {
  Text string `protobuf:"bytes,1,opt,name=text,proto3" json:"text,omitempty"`
}

func Handler(w http.ResponseWriter, r *http.Request) {
  enc, err := media.NewEncoder(r.Header.Get("Accept"), w)
  if err != nil {
    http.Error(w, err.Error(), http.StatusNotImplemented)
    return
  }
  if err := enc.Encode(&Thing{"hello media"}); err != nil {
    http.Error(w, err.Error(), http.StatusInternalServerError)
  }
}

Creating and registering new encodings is accomplished by defining encoders and/or decoders, and calling Register in an init function passing an EncoderFunc and DecoderFunc.

// text/go encoder
func init() {
  media.Register("text/go", newEncoder, nil)
}

func newEncoder(w io.Writer) (media.Encoder, error) {
  return &encoder{w}
}

type encoder struct {
  w io.Writer
}

func (a *encoder) Encode(v interface{}) error {
  _, err = a.w.Write([]byte(fmt.Sprintf("%#v", v)))
  return err
}

Index

• Variables
• func Decode(ctx context.Context, r io.Reader, mimed string, thing interface{}) error
• func Encode(w io.Writer, mimed string, thing interface{}) error
• func HasDecoder(mimed string) bool
• func HasEncoder(mimed string) bool
• func Register(mimed string, e EncoderFunc, d DecoderFunc)
• type Decoder
  • func NewDecoder(mimed string, r io.Reader) (Decoder, error)
• type DecoderFunc
• type Encoder
  • func NewEncoder(mimed string, w io.Writer) (Encoder, error)
• type EncoderFunc
• type Registry
  • func (a *Registry) HasDecoder(mimed string) bool
  • func (a *Registry) HasEncoder(mimed string) bool
  • func (a *Registry) NewDecoder(mimed string, r io.Reader) (Decoder, error)
  • func (a *Registry) NewEncoder(mimed string, w io.Writer) (Encoder, error)
  • func (a *Registry) Register(mimed string, r *registration)

Variables

var NotRegistered = errors.New("Media type is not registered")

NotRegistered is returned from Encode and Decode Registry methods when the MIME type requested has not yet been registered.

Functions

func Decode

func Decode(ctx context.Context, r io.Reader, mimed string, thing interface{}) error

Decode thing from r encoded as mimed.

func Encode

func Encode(w io.Writer, mimed string, thing interface{}) error

Encode thing as mimed and write to w.

func HasDecoder

func HasDecoder(mimed string) bool

HasDecoder returns true when a decoder is registered for the mime type in the default registry.

func HasEncoder

func HasEncoder(mimed string) bool

HasEncoder returns true when an encoder is registered for the mime type in the default registry.

func Register

func Register(mimed string, e EncoderFunc, d DecoderFunc)

Register an encoding with a MIME type.

Types

type Decoder

type Decoder interface {
	Decode(context.Context, interface{}) error
}

Decoder is an interface with a Decode method which unmarshals an interface by reading from an io.Reader. Reading will be interupted if the context triggers cancellation.

func NewDecoder

func NewDecoder(mimed string, r io.Reader) (Decoder, error)

NewDecoder returns the Decoder registered in the default Registry for the MIME type defined in the mimed parameter. NotRegistered is returned if no matching encoder was found.

type DecoderFunc

type DecoderFunc func(io.Reader) (Decoder, error)

DecoderFunc defines a function returning an Decoder wrapping an io.Reader.

type Encoder

type Encoder interface {
	Encode(interface{}) error
}

Encoder is an interface with an Encode method which marshals an interface to an io.Writer.

func NewEncoder

func NewEncoder(mimed string, w io.Writer) (Encoder, error)

NewEncoder returns the Encoder registered in the default Registry for the MIME type defined in the mimed parameter. NotRegistered is returned if no matching encoder was found.

type EncoderFunc

type EncoderFunc func(io.Writer) (Encoder, error)

EncoderFunc defines a function returning an Encoder wrapping an io.Writer.

type Registry

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

Registry is an encoding multiplexer. It matches a MIME type to a registration.

MIME type strings are parsed using the standard library mime.ParseMediaType function. The resulting mediatype output is used during registration. MIME parameters are normalized by converting to lowercase, sorting params keys, and joining with a semicolon.

Partial matching of MIME types and parameters is not yet supported. Instead, register each scenario using the same registration. Or manipulate the mimed string before requesting an encoder or decoder.

Registry is safe for concurrent access and should not be copied.

func (*Registry) HasDecoder

func (a *Registry) HasDecoder(mimed string) bool

HasDecoder returns true when a decoder is registered for the mime type.

func (*Registry) HasEncoder

func (a *Registry) HasEncoder(mimed string) bool

HasEncoder returns true when an encoder is registered for the mime type.

func (*Registry) NewDecoder

func (a *Registry) NewDecoder(mimed string, r io.Reader) (Decoder, error)

NewDecoder returns the Decoder registered for the MIME type defined in the mimed parameter. NotRegistered is returned if no matching decoder was found.

func (*Registry) NewEncoder

func (a *Registry) NewEncoder(mimed string, w io.Writer) (Encoder, error)

NewEncoder returns the Encoder registered for the MIME type defined in the mimed parameter. NotRegistered is returned if no matching encoder was found.

func (*Registry) Register

func (a *Registry) Register(mimed string, r *registration)

Register an Encoder and Decoder for a MIME type. Subsequent calls to Encode or Decode methods with return the registered Encoder and Decoder respectively. This method will panic if the mimed parameter is invalid.