backendv2

Documentation

Index

• Constants
• Variables
• func VerifyTimestamp(t Timestamp) error
• type Backend
• type ContentError
  • func (e ContentError) Error() string
• type ContentErrorCodeT
• type ExtraDataDcrtime
• type ExtraDataTrillianRFC6962
• type File
• type Inventory
• type MetadataStream
• type Plugin
• type PluginError
  • func (e PluginError) Error() string
• type PluginSetting
• type Proof
• type Record
• type RecordMetadata
• type RecordRequest
• type RecordTimestamps
• type StateT
• type StatusT
• type StatusTransitionError
  • func (s StatusTransitionError) Error() string
• type Timestamp

Constants

const (
	// ProofTypeTrillianRFC6962 represents a trillian proof that uses
	// the trillian hashing strategy HashStrategy_RFC6962_SHA256.
	ProofTypeTrillianRFC6962 = "trillian-rfc6962"

	// ProofTypeDcrtime represents a dcrtime proof.
	ProofTypeDcrtime = "dcrtime"
)

Variables

var (
	// ErrShutdown is returned when the backend is shutdown.
	ErrShutdown = errors.New("backend is shutdown")

	// ErrTokenInvalid is returned when a token is invalid.
	ErrTokenInvalid = errors.New("token is invalid")

	// ErrRecordNotFound is returned when a record is not found.
	ErrRecordNotFound = errors.New("record not found")

	// ErrRecordLocked is returned when a record is attempted to be
	// updated but the record status does not allow further updates.
	ErrRecordLocked = errors.New("record is locked")

	// ErrNoRecordChanges is returned when a record update does not
	// contain any changes.
	ErrNoRecordChanges = errors.New("no record changes")

	// ErrPluginIDInvalid is returned when a invalid plugin ID is used.
	ErrPluginIDInvalid = errors.New("plugin id invalid")

	// ErrPluginCmdInvalid is returned when a invalid plugin command is
	// used.
	ErrPluginCmdInvalid = errors.New("plugin command invalid")

	// ErrDuplicatePayload is returned when a duplicate payload is sent to
	// a plugin, where it tries to write data that already exists. Timestamp
	// data relies on the hash of the payload, therefore duplicate payloads
	// are not allowed since they will cause collisions.
	ErrDuplicatePayload = errors.New("duplicate payload")
)

var (
	// ErrNotTimestamped is returned when a timestamp does not contain
	// a TxID. This indicates that the data has yet to be included in
	// a DCR transaction.
	ErrNotTimestamped = errors.New("data has not be included in a dcr tx yet")
)

var (
	// States contains the human readable record states.
	States = map[StateT]string{
		StateInvalid:  "invalid",
		StateUnvetted: "unvetted",
		StateVetted:   "vetted",
	}
)

var (
	// Statuses contains the human readable record statuses.
	Statuses = map[StatusT]string{
		StatusInvalid:    "invalid",
		StatusUnreviewed: "unreviewed",
		StatusPublic:     "public",
		StatusCensored:   "censored",
		StatusArchived:   "archived",
	}
)

Functions

func VerifyTimestamp

func VerifyTimestamp(t Timestamp) error

VerifyTimestamp verifies the inclusion of the data in the merkle root that was timestamped onto the dcr blockchain.

Types

type Backend

type Backend interface {
	// RecordNew creates a new record.
	RecordNew([]MetadataStream, []File) (*Record, error)

	// RecordEdit edits an existing record.
	RecordEdit(token []byte, mdAppend, mdOverwrite []MetadataStream,
		filesAdd []File, filesDel []string) (*Record, error)

	// RecordEditMetadata edits the metadata of a record without
	// editing any record files.
	RecordEditMetadata(token []byte, mdAppend,
		mdOverwrite []MetadataStream) (*Record, error)

	// RecordSetStatus sets the status of a record.
	RecordSetStatus(token []byte, s StatusT, mdAppend,
		mdOverwrite []MetadataStream) (*Record, error)

	// RecordExists returns whether a record exists.
	RecordExists(token []byte) bool

	// RecordTimestamps returns the timestamps for a record. If no
	// version is provided then timestamps for the most recent version
	// will be returned.
	RecordTimestamps(token []byte, version uint32) (*RecordTimestamps, error)

	// Records retreives a batch of records. If a record is not found
	// then it is simply not included in the returned map. An error is
	// not returned.
	Records(reqs []RecordRequest) (map[string]Record, error)

	// Inventory returns the tokens of records in the inventory
	// categorized by record state and record status. The tokens are
	// ordered by the timestamp of their most recent status change,
	// sorted from newest to oldest.
	//
	// The state, status, and page arguments can be provided to request
	// a specific page of record tokens.
	//
	// If no status is provided then the most recent page of tokens for
	// all statuses will be returned. All other arguments are ignored.
	Inventory(state StateT, status StatusT, pageSize,
		pageNumber uint32) (*Inventory, error)

	// InventoryOrdered returns a page of record tokens ordered by the
	// timestamp of their most recent status change from newest to
	// oldest. The returned tokens will include all record statuses.
	InventoryOrdered(s StateT, pageSize, pageNumber uint32) ([]string, error)

	// PluginRegister registers a plugin.
	PluginRegister(Plugin) error

	// PluginSetup performs any required plugin setup.
	PluginSetup(pluginID string) error

	// PluginRead executes a read-only plugin command.
	PluginRead(token []byte, pluginID, pluginCmd,
		payload string) (string, error)

	// PluginWrite executes a plugin command that writes data.
	PluginWrite(token []byte, pluginID, pluginCmd,
		payload string) (string, error)

	// PluginInventory returns all registered plugins.
	PluginInventory() []Plugin

	// Fsck performs a synchronous filesystem check that verifies
	// the coherency of record and plugin data and caches.
	Fsck() error

	// Close performs cleanup of the backend.
	Close()
}

Backend provides an API for interacting with records in the backend.

type ContentError

type ContentError struct {
	ErrorCode    ContentErrorCodeT `json:"errorcode"`
	ErrorContext string            `json:"errorcontext"`
}

ContentError is returned when the content of a record does not pass validation.

func (ContentError) Error

func (e ContentError) Error() string

Error satisfies the error interface.

type ContentErrorCodeT

type ContentErrorCodeT uint32

ContentErrorCodeT represents a record content error.

const (
	ContentErrorInvalid                 ContentErrorCodeT = 0
	ContentErrorMetadataStreamInvalid   ContentErrorCodeT = 1
	ContentErrorMetadataStreamDuplicate ContentErrorCodeT = 2
	ContentErrorFilesEmpty              ContentErrorCodeT = 3
	ContentErrorFileNameInvalid         ContentErrorCodeT = 4
	ContentErrorFileNameDuplicate       ContentErrorCodeT = 5
	ContentErrorFileDigestInvalid       ContentErrorCodeT = 6
	ContentErrorFilePayloadInvalid      ContentErrorCodeT = 7
	ContentErrorFileMIMETypeInvalid     ContentErrorCodeT = 8
	ContentErrorFileMIMETypeUnsupported ContentErrorCodeT = 9
)

type ExtraDataDcrtime

type ExtraDataDcrtime struct {
	NumLeaves uint32 // Nuber of leaves
	Flags     string // Bitmap of merkle tree, base64 encoded
}

ExtraDataDcrtime contains the extra data required to verify a dcrtime inclusion proof.

type ExtraDataTrillianRFC6962

type ExtraDataTrillianRFC6962 struct {
	LeafIndex int64 `json:"leafindex"`
	TreeSize  int64 `json:"treesize"`
}

ExtraDataTrillianRFC6962 contains the extra data required to verify a trillian inclusion proof.

type File

type File struct {
	Name    string `json:"name"`    // Basename of the file
	MIME    string `json:"mime"`    // MIME type
	Digest  string `json:"digest"`  // SHA256 of decoded Payload
	Payload string `json:"payload"` // Base64 encoded file payload
}

File represents a record file.

type Inventory

type Inventory struct {
	Unvetted map[StatusT][]string
	Vetted   map[StatusT][]string
}

Inventory contains the tokens of records in the inventory categorized by record state and record status. Tokens are sorted by the timestamp of the status change from newest to oldest.

type MetadataStream

type MetadataStream struct {
	PluginID string `json:"pluginid"` // Plugin identity
	StreamID uint32 `json:"streamid"` // Stream identity
	Payload  string `json:"payload"`  // JSON encoded metadata
}

MetadataStream describes a single metada stream.

type Plugin

type Plugin struct {
	ID       string
	Settings []PluginSetting

	// Identity contains the full identity that the plugin uses to
	// create receipts, i.e. signatures of user provided data that
	// prove the backend received and processed a plugin command.
	Identity *identity.FullIdentity
}

Plugin describes a plugin and its settings.

type PluginError

type PluginError struct {
	PluginID     string
	ErrorCode    uint32
	ErrorContext string
}

PluginError represents an error that occurred during plugin execution that was caused by the user.

func (PluginError) Error

func (e PluginError) Error() string

Error satisfies the error interface.

type PluginSetting

type PluginSetting struct {
	Key   string // Name of setting
	Value string // Value of setting
}

PluginSetting represents a configurable plugin setting.

The value can either contain a single value or multiple values. Multiple values will be formatted as a JSON encoded []string.

type Proof

type Proof struct {
	Type       string
	Digest     string
	MerkleRoot string
	MerklePath []string
	ExtraData  string // JSON encoded
}

Proof contains an inclusion proof for the digest in the merkle root. All digests are hex encoded SHA256 digests.

The ExtraData field is used by certain types of proofs to include additional data that is required to validate the proof.

type Record

type Record struct {
	RecordMetadata RecordMetadata   `json:"recordmetadata"`
	Metadata       []MetadataStream `json:"metadata"`
	Files          []File           `json:"files"`
}

Record is a permanent record that includes the submitted files, metadata and internal metadata.

type RecordMetadata

type RecordMetadata struct {
	Token     string  `json:"token"`     // Record identifier, hex encoded
	Version   uint32  `json:"version"`   // Record version
	Iteration uint32  `json:"iteration"` // Record iteration
	State     StateT  `json:"state"`     // Unvetted or vetted
	Status    StatusT `json:"status"`    // Record status
	Timestamp int64   `json:"timestamp"` // Last updated
	Merkle    string  `json:"merkle"`    // Merkle root of record files
}

RecordMetadata represents metadata that is created by the backend on record submission and updates.

The record version is incremented anytime the record files are updated. The record iteration is incremented anytime record files, metadata, or the record status are updated.

type RecordRequest

type RecordRequest struct {
	Token        []byte
	Version      uint32
	Filenames    []string
	OmitAllFiles bool
}

RecordRequest is used to request a record. It gives the caller granular control over what is returned. The only required field is the token. All other fields are optional. All record files are returned by default unless one of the file arguments is provided.

Version is used to request a specific version of a record. If no version is provided then the most recent version of the record will be returned.

Filenames can be used to request specific files. If filenames is not empty then the specified files will be the only files that are returned.

OmitAllFiles can be used to retrieve a record without any of the record files. This supersedes the filenames argument.

type RecordTimestamps

type RecordTimestamps struct {
	RecordMetadata Timestamp

	Metadata map[string]map[uint32]Timestamp // [pluginID][streamID]Timestamp
	Files    map[string]Timestamp            // map[filename]Timestamp
}

RecordTimestamps contains a Timestamp for all record data.

type StateT

type StateT uint32

StateT represents the state of a record.

const (
	// StateInvalid is an invalid record state.
	StateInvalid StateT = 0

	// StateUnvetted indicates a record has not been made public.
	StateUnvetted StateT = 1

	// StateVetted indicates a record has been made public.
	StateVetted StateT = 2

	// StateLast used for unit test only.
	StateLast StateT = 3
)

type StatusT

type StatusT uint32

StatusT represents the status of a record.

const (
	// StatusInvalid is an invalid status code.
	StatusInvalid StatusT = 0

	// StatusUnreviewed indicates a record has not been made public
	// yet. The state of an unreviewed record will always be unvetted.
	StatusUnreviewed StatusT = 1

	// StatusPublic indicates a record has been made public. The state
	// of a public record will always be vetted.
	StatusPublic StatusT = 2

	// StatusCensored indicates a record has been censored. A censored
	// record is locked from any further updates and all record content
	// is permanently deleted. A censored record can have a state of
	// either unvetted or vetted.
	StatusCensored StatusT = 3

	// StatusArchived indicates a record has been archived. An archived
	// record is locked from any further updates. An archived record
	// have a state of either unvetted or vetted.
	StatusArchived StatusT = 4

	// StatusLast is used for unit test validation of human readable
	// errors.
	StatusLast StatusT = 5
)

type StatusTransitionError

type StatusTransitionError struct {
	From StatusT
	To   StatusT
}

StatusTransitionError indicates an invalid record status transition.

func (StatusTransitionError) Error

func (s StatusTransitionError) Error() string

Error satisfies the error interface.

type Timestamp

type Timestamp struct {
	Data       string // JSON encoded
	Digest     string
	TxID       string
	MerkleRoot string
	Proofs     []Proof
}

Timestamp contains all of the data required to verify that a piece of record content was timestamped onto the decred blockchain.

All digests are hex encoded SHA256 digests. The merkle root can be found in the OP_RETURN of the specified DCR transaction.

TxID, MerkleRoot, and Proofs will only be populated once the merkle root has been included in a DCR tx and the tx has 6 confirmations. The Data field will not be populated if the data has been censored.