Skip to content

Write a codec for another format

A format is a wire.Codec: three methods that map the wire model to bytes and back. Everything about what an error becomes on the wire is already decided by errors/wire; a codec only translates.

type Codec interface {
    MediaType() string
    Encode(*wire.Error) ([]byte, error)
    Decode([]byte) (*wire.Error, error)
}

Implement the schema, not the Go structs

The contract is proto/phpboyscout/errors/v1/error.proto in this module. The Go model in wire mirrors it field for field, so map one to the other. Follow its evolution rules when you read:

  • ignore a field or member you do not know, because a newer sender may add one;
  • refuse a Form outside the five, because the set is closed;
  • carry version exactly, because the receiver refuses one it does not read.

Keep everything your format can hold. A format that rounds a time or caps its own nesting below the model's depth bound fails conformance.

Refuse a hostile document before you allocate it

wire.Unmarshal bounds the model your codec returns, but by then a 4 MiB document of empty attributes may already have become hundreds of megabytes. Implement wire.BoundedDecoder as well, and check the wire.Limits it is given while you parse:

func (c codec) DecodeBounded(b []byte, limits wire.Limits) (*wire.Error, error)

wire.JSON does it with a token scan before decoding.

Prove it with the conformance suite

package mycodec_test

import (
    "testing"

    "gitlab.com/phpboyscout/go/errors/wire/wiretest"
    "example.com/mycodec"
)

func TestConformance(t *testing.T) { wiretest.Run(t, mycodec.Codec) }

wiretest.Run round-trips a set of fixtures with and without stacks. It checks the decoded tree's shape as well as its message, and then sentinel identity, every bound, nil, the version and the form rules. A codec that passes is interchangeable with wire.JSON.

The suite cannot check that your codec ignores an unknown field, because only your codec knows what an unknown field looks like in its format. Write that test yourself: decode a document with an extra field and an extra attribute value member, and expect the rest to decode.

Add a fuzz target over wire.Unmarshal(b, mycodec.Codec) too. The bytes come from another process.