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
Formoutside the five, because the set is closed; - carry
versionexactly, 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:
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.