bundle

README

bundle

Common bundle (of digital objects) package used across CodeNotary ecosystem.

What is a bundle?

A bundle is a collection of content-addressable digital objects (items).
This package aims to provide a re-usable Bundle Manifest Specification.

Usage

import (
    "github.com/codenotary/bundle"
)

Create a manifest:

d1, _ := bundle.NewDescriptor("alice", strings.NewReader("My name is Alice"))
d2, _ := bundle.NewDescriptor("bob", strings.NewReader("and I'm Bob!"))
manifest := bundle.NewManifest(*d1, *d2)
bundle.WriteManifest(*manifest, "manifest.json")
}

Output:

{"schemaVersion":1,"items":[{"digest":"sha256:4606ff70ad4f0dcd765b4a65850ad0ec2c26e419308d30a6981ce309fc65723e","size":16,"paths":["alice"]},{"digest":"sha256:d3cbe4c3bf23712b028df53f257c59a1aaac617a03841c901d214fc63469f377","size":12,"paths":["bob"]}]}

Testing

go test

Documentation

Index

• Constants
• func WriteManifest(manifest Manifest, filename string) error
• type Descriptor
  • func NewDescriptor(path string, src io.Reader) (*Descriptor, error)
• type Manifest
  • func NewManifest(items ...Descriptor) *Manifest
  • func ReadManifest(filename string) (*Manifest, error)
  • func (m Manifest) Diff(x Manifest) (report string, equal bool, err error)
  • func (m Manifest) DiffByPath(x Manifest) (report string, equal bool, err error)
  • func (m *Manifest) Digest() (digest.Digest, error)
  • func (m *Manifest) MarshalJSON() ([]byte, error)
  • func (m *Manifest) Normalize() error

Constants

const (
	// ManifestSchemaVersion is the current manifest schema version.
	ManifestSchemaVersion = 1

	// ManifestDigestAlgo is the only supported digest's algorithm by current manifest schema version.
	ManifestDigestAlgo = digest.SHA256
)

Functions

func WriteManifest

func WriteManifest(manifest Manifest, filename string) error

WriteManifest writes manifest's data to a file named by filename.

Types

type Descriptor

type Descriptor struct {
	// Digest is the digest of the targeted content.
	Digest digest.Digest `json:"digest"`

	// Size specifies the size in bytes of the targeted content.
	Size uint64 `json:"size"`

	// Paths specifies the relative locations of the targeted content.
	Paths []string `json:"paths"`
}

Descriptor describes the disposition of targeted content.

func NewDescriptor

func NewDescriptor(path string, src io.Reader) (*Descriptor, error)

NewDescriptor returns a new *Descriptor for the provided path and src.

type Manifest

type Manifest struct {
	// SchemaVersion is the manifest schema that this bundle follows
	SchemaVersion uint `json:"schemaVersion"`

	// Items is an ordered list of items referenced by the manifest.
	Items []Descriptor `json:"items"`
}

Manifest provides bundle structure when marshalled to JSON.

Specifications (version 1):

• `schemaVersion` is the version number of the current specification (MUST be always 1 in this case)
• fields order is defined as per code structs definitions, orderning MUST NOT be changed
• `items` MUST be sorted by digest's value (lexically byte-wise)
• multiple `items` MUST NOT have the same digest value
• `items.paths` MUST be sorted by value (lexically byte-wise)
• across the same manifest multiple `items.paths`'s elements MUST NOT have the same value
• json representation of the manifest MUST NOT be indented
• sha256 is the only digest's algorithm that MUST be used

The Normalize() method provides sorting funcionality and specification enforcement. It's implictly called when the manifest is marshalled.

func NewManifest

func NewManifest(items ...Descriptor) *Manifest

NewManifest returns a new empty Manifest.

func ReadManifest

func ReadManifest(filename string) (*Manifest, error)

ReadManifest reads the file named by filename and returns the decoded manifest.

func (Manifest) Diff

func (m Manifest) Diff(x Manifest) (report string, equal bool, err error)

Diff returns a human-readable report as string of the raw differences between m and x.

Do not depend on this output being stable.

func (Manifest) DiffByPath

func (m Manifest) DiffByPath(x Manifest) (report string, equal bool, err error)

DiffByPath returns a human-readable report as string containing additions, modifications, renamings, deletions of x.Items relative to m.Items listed by path.

Do not depend on this output being stable.

func (*Manifest) Digest

func (m *Manifest) Digest() (digest.Digest, error)

Digest digests the JSON encoded m and returns a digest.Digest.

func (*Manifest) MarshalJSON

func (m *Manifest) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*Manifest) Normalize

func (m *Manifest) Normalize() error

Normalize deduplicates and sorts items and items's paths in accordance with manifest's schema specs. An error is returned when duplicate paths across different items are found, or if digest's algo does not match sha256.