digest

Documentation

Overview

Package digest contains functions to simplify handling content digests.

Index

• Variables
• func CheckCapabilities(caps *repb.ServerCapabilities) error
• func GetDigestFunction() repb.DigestFunction_Value
• type Digest
  • func New(hash string, size int64) (Digest, error)
  • func NewFromBlob(blob []byte) Digest
  • func NewFromFile(path string) (Digest, error)
  • func NewFromMessage(msg proto.Message) (Digest, error)
  • func NewFromProto(dg *repb.Digest) (Digest, error)
  • func NewFromProtoUnvalidated(dg *repb.Digest) Digest
  • func NewFromReader(r io.Reader) (Digest, error)
  • func NewFromString(s string) (Digest, error)
  • func TestNew(hash string, size int64) Digest
  • func TestNewFromMessage(msg proto.Message) Digest
  • func (d Digest) IsEmpty() bool
  • func (d Digest) String() string
  • func (d Digest) ToProto() *repb.Digest
  • func (d Digest) Validate() error

Variables

var (

	// HashFn is the digest function used.
	HashFn crypto.Hash = crypto.SHA256

	// Empty is the digest of the empty blob.
	Empty = NewFromBlob([]byte{})
)

Functions

func CheckCapabilities

func CheckCapabilities(caps *repb.ServerCapabilities) error

CheckCapabilities returns an error if the digest function is not supported by the server.

func GetDigestFunction

func GetDigestFunction() repb.DigestFunction_Value

GetDigestFunction returns the digest function used by the client.

Types

type Digest

type Digest struct {
	Hash string
	Size int64
}

Digest is a Go type to mirror the repb.Digest message.

func New

func New(hash string, size int64) (Digest, error)

New creates a new digest from a string and size. It does some basic validation, which makes it marginally superior to constructing a Digest yourself. It returns an empty digest and an error if the hash/size are invalid.

func NewFromBlob

func NewFromBlob(blob []byte) Digest

NewFromBlob takes a blob (in the form of a byte array) and returns the Digest for that blob. Changing this function will lead to cache invalidations (execution cache and potentially others). This cannot return an error, since the result is valid by definition.

func NewFromFile

func NewFromFile(path string) (Digest, error)

NewFromFile computes a file digest from a path. It returns an error if there was a problem accessing the file.

func NewFromMessage

func NewFromMessage(msg proto.Message) (Digest, error)

NewFromMessage calculates the digest of a protobuf in SHA-256 mode. It returns an error if the proto marshalling failed.

func NewFromProto

func NewFromProto(dg *repb.Digest) (Digest, error)

NewFromProto converts a proto digest to a Digest. It returns an empty digest and an error if the hash/size are invalid.

func NewFromProtoUnvalidated

func NewFromProtoUnvalidated(dg *repb.Digest) Digest

NewFromProtoUnvalidated converts a proto digest to a Digest, skipping validation.

func NewFromReader

func NewFromReader(r io.Reader) (Digest, error)

NewFromReader computes a file digest from a reader. It returns an error if there was a problem reading the file.

func NewFromString

func NewFromString(s string) (Digest, error)

NewFromString returns a digest from a canonical digest string. It returns an error if the hash/size are invalid.

func TestNew

func TestNew(hash string, size int64) Digest

TestNew is like New but also pads your hash with zeros if it is shorter than the required length, and panics on error rather than returning the error. ONLY USE FOR TESTS.

func TestNewFromMessage

func TestNewFromMessage(msg proto.Message) Digest

TestNewFromMessage is only suitable for testing and panics on error. ONLY USE FOR TESTS.

func (Digest) IsEmpty

func (d Digest) IsEmpty() bool

IsEmpty returns true iff digest is of an empty blob.

func (Digest) String

func (d Digest) String() string

String returns a hash in a canonical form of hash/size.

func (Digest) ToProto

func (d Digest) ToProto() *repb.Digest

ToProto converts a Digest into a repb.Digest. No validation is performed!

func (Digest) Validate

func (d Digest) Validate() error

Validate returns nil if a digest appears to be valid, or a descriptive error if it is not. All functions accepting digests directly from clients should call this function, whether it's via an RPC call or by reading a serialized proto message that contains digests that was uploaded directly from the client.