distdoc

Documentation

Index

• func ValidatePayloadType(payloadType string) bool
• type BFSWalker
• type DAG
  • func NewBBoltDAG(path string) (DAG, error)
  • func NewMemoryDAG() DAG
• type Document
  • func ParseDocument(input []byte) (Document, error)
• type PayloadHash
• type UnsignedDocument
  • func NewDocument(payload PayloadHash, payloadType string, prevs []model.Hash) (UnsignedDocument, error)
• type Version
• type Visitor
• type Walker

Functions

func ValidatePayloadType

func ValidatePayloadType(payloadType string) bool

Types

type BFSWalker

type BFSWalker struct{}

BFSWalker walks the DAG using the Breadth-First-Search (BFS) as described by Anany Levitin in "The Design & Analysis of Algorithms". It visits the whole tree level for level (breadth first vs depth first). It works by taking a node from queue and then adds the node's children (downward edges) to the queue. It starts by adding the root node to the queue and loops over the queue until empty, meaning all nodes reachable from the root node have been visited. Since our DAG contains merges (two parents referring to the same child node) we also keep a map to avoid visiting a merger node twice.

This also means we have to make sure we don't visit the merger node before all of its previous nodes have been visited, which BFS doesn't account for. If that happens we skip the node without marking it as visited, so it will be visited again when the unvisited previous node is visited, which re-adds the merger node to the queue.

type DAG

type DAG interface {
	// Add adds one or more documents to the DAG. If it can't be added an error is returned. Nil entries are ignored.
	Add(documents ...Document) error
	// MissingDocuments returns the hashes of the documents we know we are missing and should still be resolved.
	MissingDocuments() []model.Hash
	// Walk visits every node of the DAG, starting at the given hash working its way down each level until every leaf is visited.
	// when startAt is an empty hash, the walker starts at the root node.
	Walk(walker Walker, visitor Visitor, startAt model.Hash) error
	// Root returns the root hash of the DAG. If there's no root an empty hash is returned. If an error occurs, it is returned.
	Root() (model.Hash, error)
}

DAG is a directed acyclic graph consisting of nodes (documents) referring to preceding nodes.

func NewBBoltDAG

func NewBBoltDAG(path string) (DAG, error)

NewBBoltDAG creates a etcd/bbolt backed DAG using the given database file path. If the file doesn't exist, it's created. The parent directory of the path must exist, otherwise an error could be returned. If the file can't be created or read, an error is returned as well.

func NewMemoryDAG

func NewMemoryDAG() DAG

type Document

type Document interface {
	UnsignedDocument
	// SigningCertificate returns the certificate that was used for signing this document.
	SigningCertificate() *x509.Certificate
	// SigningTime returns the time that the document was signed.
	SigningTime() time.Time
	// Ref returns the reference to this document.
	Ref() model.Hash
	// Data returns the byte representation of this document which can be used for transport.
	Data() []byte
	// VerifySignature verifies that the signature are signing certificate are correct. If an error occurs or verification
	// fails an error is returned.
	VerifySignature(trustStore *x509.CertPool) error
}

Document defines a signed distributed document as described by RFC004 - Distributed Document Format.

func ParseDocument

func ParseDocument(input []byte) (Document, error)

type PayloadHash

type PayloadHash model.Hash

PayloadHash is a Hash of the payload of a Document

type UnsignedDocument

type UnsignedDocument interface {
	// PayloadType returns the MIME-formatted type of the payload. It must contain the context and specific type of the
	// payload, e.g. 'registry/endpoint'.
	PayloadType() string
	// Payload returns the hash of the payload of the document.
	Payload() PayloadHash
	// Previous returns the references of the previous documents this document points to.
	Previous() []model.Hash
	// Version returns the version number of the distributed document format.
	Version() Version
	// TimelineID returns the timeline ID of the document.
	TimelineID() model.Hash
	// TimelineVersion returns the timeline version of the document. If the returned version is < 1 the timeline version
	// is not set.
	TimelineVersion() int
	// Sign signs the document using the given key and certificate. The certificate must correspond with the given
	// signing key and must be meant (key usage) for signing. The moment parameter is included in the signature
	// as time of signing.
	Sign(key crypto.Signer, certificate *x509.Certificate, moment time.Time) (Document, error)
}

UnsignedDocument holds the base properties of a document which can be signed to create a Document.

func NewDocument

func NewDocument(payload PayloadHash, payloadType string, prevs []model.Hash) (UnsignedDocument, error)

NewDocument creates a new unsigned document. Parameters payload and payloadType can't be empty, but prevs is optional. Prevs must not contain empty or invalid hashes.

type Version

type Version int

Version defines a type for distributed document format version.

type Visitor

type Visitor func(document Document)

Visitor defines the contract for a function that visits the DAG.

type Walker

type Walker interface {
	// contains filtered or unexported methods
}