protohash

README

ObjectHash-Proto

The library is an implementation of Ben Laurie's ObjectHash for protocol buffers.

This implementation is still experimental and until it is stable, protobuf messages are not guaranteed to result in the same value.

Usage

Get a new ProtoHasher instance using the NewHasher method, then call HashProto with a protobuf message to get its ObjectHash:

hasher := protohash.NewHasher()
hash, err := hasher.HashProto(message)

Options

In order to simplify compatibility with other ObjectHash applications, this library exposes the following options that control how the hashing is done:

1. EnumsAsStrings(): Makes enum values get hashed as strings instead of being hashed as their integer values.

2. FieldNamesAsKeys(): Makes protobuf message fields use their names as keys instead of using the field tag numbers as keys.

3. MessageIdentifier(i): Instead of hashing protobuf messages as maps, this makes it possible to distinguish them by using i as the type-identifier that gets used in calculating the ObjectHash of a message.

Those options can be specified in any order as arguments to the NewHasher function. Example:

hasher := protohash.NewHasher(EnumsAsStrings(), MessageIdentifier(`m`), FieldNamesAsKeys())

Help and Discussion

• Google Group

Documentation

Index

• func CheckWellKnownType(sv reflect.Value) (name string, ok bool)
• type Option
  • func EnumsAsStrings() Option
  • func FieldNamesAsKeys() Option
  • func MessageIdentifier(i string) Option
• type ProtoHasher
  • func NewHasher(opts ...Option) ProtoHasher

Functions

func CheckWellKnownType

func CheckWellKnownType(sv reflect.Value) (name string, ok bool)

CheckWellKnownType checks if a value is one of the proto library's well-known types. The ok return value reports whether the value is a well-known type or not, while the name return value reports the name provided by the proto library for this type.

This is done by checking if the proto message has a XXX_WellKnownType method defined on it.

Types

type Option

type Option interface {
	fmt.Stringer
	// contains filtered or unexported methods
}

Option modifies how ObjectHashes for protobufs is calculated.

func EnumsAsStrings

func EnumsAsStrings() Option

EnumsAsStrings returns an Option to specify that enum values should be hashed as strings instead of being hashed as integers.

This can be useful for compatibility with non-protobuf formats that represent enums as strings, but will have backward-compatiblity consequences for the proto message itself.

func FieldNamesAsKeys

func FieldNamesAsKeys() Option

FieldNamesAsKeys returns an Option to specify that field names should be used as their keys instead of using their tag number.

This can be useful for compatibility with non-protobuf formats that primarily use strings (rather than integers) as keys, but will have backward-compatiblity consequences for the proto message itself.

func MessageIdentifier

func MessageIdentifier(i string) Option

MessageIdentifier returns an Option to specify that proto messages should use the supplied argument as their type identifier. This will make messages have a different hash from maps with equivalent contents.

This can be useful for stricter type checking when comparing hashes, but will have consequences for the compatiblity with non-protobuf formats, in particular those that do not provide a container type for messages/structs distinct from that for maps/dictionaries.

type ProtoHasher

type ProtoHasher interface {
	HashProto(pb proto.Message) ([]byte, error)
}

ProtoHasher is an interface for hashers that are capable of returning an ObjectHash for protobufs.

func NewHasher

func NewHasher(opts ...Option) ProtoHasher

NewHasher creates a new ProtoHasher with the options specified in the argument.