ocflv1

package
v0.0.25 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 16, 2024 License: MIT Imports: 24 Imported by: 2

Documentation

Overview

Package ocflv1 provides an implementation of OCFL v1.0 and v1.1.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrOCFLVersion        = errors.New("unsupported OCFL version")
	ErrInventoryNotExist  = fmt.Errorf("missing inventory file: %w", fs.ErrNotExist)
	ErrInvSidecarContents = errors.New("invalid inventory sidecar contents")
	ErrInvSidecarChecksum = errors.New("inventory digest doesn't match expected value from sidecar file")
	ErrDigestAlg          = errors.New("invalid digest algorithm")
	ErrObjRootStructure   = errors.New("object includes invalid files or directories")
)
View Source 
var (
	ErrLayoutUndefined = errors.New("storage root layout is undefined")
	ErrEmptyDirs       = errors.New("storage root includes empty directories")
	ErrNonObject       = errors.New("storage root includes files that aren't part of an object")
	ErrObjectVersion   = errors.New("storage root includes objects with higher OCFL version than the storage root")
)
View Source 
var (
	ErrVersionNotFound = errors.New("version not found in inventory")
)

Functions

func Commit 

func Commit(ctx context.Context, fsys ocfl.WriteFS, objPath string, objID string, stage *ocfl.Stage, optFuncs ...CommitOption) (err error)

Commit creates or updates the OCFL v1.x object objectID at objPath using the content from stage. If an object exists at objPath, the object will be updated; if objPath does not exist, a new object will be created. If objPath exists but it is not the root of a valid OCFL object, an error is returned. The digest algorithm for the object version is taken from the stage. For object updates, the stage's algorithm must match the existing object's digest algorithm. The error returned by commit is always a CommitError.

Example (Copyobject)

documents using Commit() to make a new object based on last version state of another object. 

ctx := context.Background()
//FS for reading source object
fsys := ocfl.DirFS(filepath.Join(`..`, `testdata`, `object-fixtures`, `1.1`, `good-objects`))
sourceObject, err := ocflv1.GetObject(ctx, fsys, `updates_all_actions`)
if err != nil {
	log.Fatal("couldn't open source object:", err.Error())
}
ver := sourceObject.Inventory.Version(0)
// prepare a place to write the new object
dstPath, err := os.MkdirTemp("", "ocfl-commit-test-*")
if err != nil {
	log.Fatal(err)
}
//log.Println(dstPath)
defer os.RemoveAll(dstPath)
writeFS, err := local.NewFS(dstPath)
if err != nil {
	log.Fatal(err)
}
// construct a stage using the object's state, manifest and fixity.
stage := &ocfl.Stage{
	DigestAlgorithm: sourceObject.Inventory.DigestAlgorithm,
	State:           ver.State,
	ContentSource:   sourceObject,
	FixitySource:    sourceObject,
}
err = ocflv1.Commit(ctx, writeFS, "object-copy", "object-001", stage)
if err != nil {
	log.Fatal(err)
}
// read object back and validate
cpObj, err := ocflv1.GetObject(ctx, writeFS, "object-copy")
if err != nil {
	log.Fatal(err)
}
if result := cpObj.Validate(ctx); result.Err() != nil {
	log.Fatal("object is not valid: ", result.Err())
}
fmt.Println("object is valid")

Output:

object is valid

func InitStore 

func InitStore(ctx context.Context, fsys ocfl.WriteFS, root string, conf *InitStoreConf) error

InitStore initializes a new OCFL v1.x storage root on fsys at root.

func Objects 

func Objects(ctx context.Context, fsys ocfl.FS, pth ocfl.PathSelector, fn func(*Object, error) error) error

Objects iterates over the OCFL Object in fsys with the given path selector and calls fn for each. If an error is encountered while loading the object, the error is passed to fn. If fn returns an error the iteration process terminates.

func ValidateStore 

func ValidateStore(ctx context.Context, fsys ocfl.FS, root string, vops ...ValidationOption) *validation.Result

func WriteInventory 

func WriteInventory(ctx context.Context, fsys ocfl.WriteFS, inv *Inventory, dirs ...string) error

WriteInventory marshals the value pointed to by inv, writing the json to dir/inventory.json in fsys. The digest is calculated using alg and the inventory sidecar is also written to dir/inventory.alg

Types

type ChangedDigestErr 

type ChangedDigestErr struct {
	Path string
	Alg  string
}

ChangedDigestErr: different digests for same content/alg in two locations

func (ChangedDigestErr) Error 

func (err ChangedDigestErr) Error() string

type CommitError 

type CommitError struct {
	Err error // The wrapped error

	// Dirty indicates the object may be incomplete or invalid as a result of
	// the error.
	Dirty bool
}

Commit error wraps an error from a commit.

func (CommitError) Error 

func (c CommitError) Error() string

func (CommitError) Unwrap 

func (c CommitError) Unwrap() error

type CommitOption 

type CommitOption func(*commitOpt)

CommitOption is used configure Commit

func WithAllowUnchanged 

func WithAllowUnchanged() CommitOption

WithAllowUnchanged enables committing a version with the same state as the existing head version.

func WithContentDir 

func WithContentDir(cd string) CommitOption

WithContentDir is used to set the contentDirectory when creating objects. This option is ignored for object updates.

func WithCreated 

func WithCreated(c time.Time) CommitOption

WithCreated sets the created timestamp for the new object version to a non-default value. The default is

func WithHEAD 

func WithHEAD(v int) CommitOption

WithHEAD is used to constrain the version number for the commit. For example, WithHEAD(1) can be used to cause a commit to fail if the object already exits.

func WithLogger 

func WithLogger(logger *slog.Logger) CommitOption

WithLogger sets the logger used for logging during commit.

func WithManifestPathFunc 

func WithManifestPathFunc(fn func(paths []string) []string) CommitOption

WitManifestPathFunc is a function used to configure paths for content files saved to the object with the commit. The function is called for each new manifest entry (digest/path list); The function should return a slice of paths indicating where the content should be saved (relative) object version's content directory.

func WithMessage 

func WithMessage(msg string) CommitOption

WithMessage sets the message for the new object version

func WithOCFLSpec 

func WithOCFLSpec(spec ocfl.Spec) CommitOption

WithOCFLSpec is used to set the OCFL specification for the new object version. The spec version cannot be higher than the object's storage root and it cannot be lower the existing object version (if updating).

func WithUser 

func WithUser(user ocfl.User) CommitOption

WithUser sets the user for the new object version.

func WithVersionPadding 

func WithVersionPadding(p int) CommitOption

WithVersionPadding is used to set the version number padding when creating objects. The padding is the maximum number of numeric digits the version number can include (a padding of 0 is no maximum). This option is ignored for object updates.

type ContentDigestErr 

type ContentDigestErr struct {
	Path   string
	Alg    string
	Entry  digestInfo
	Digest string
}

ContentDigestErr content digest doesn't match recorded digest

func (ContentDigestErr) Error 

func (err ContentDigestErr) Error() string

type InitStoreConf 

type InitStoreConf struct {
	Spec        ocfl.Spec
	Description string
	Layout      extension.Layout
	Extensions  []extension.Extension
}

type InvDecodeError 

type InvDecodeError struct {
	Field   string
	Unknown bool
	// contains filtered or unexported fields
}

InvDecodeError wraps errors generated during inventory unmarshaling. It implements the validation.ErrorCode interface so instances can return spec error codes.

func (*InvDecodeError) Error 

func (invErr *InvDecodeError) Error() string

func (*InvDecodeError) OCFLRef 

func (invErr *InvDecodeError) OCFLRef() *validation.Ref

func (*InvDecodeError) Unwrap 

func (invErr *InvDecodeError) Unwrap() error

type Inventory 

type Inventory struct {
	ID               string                    `json:"id"`
	Type             ocfl.InvType              `json:"type"`
	DigestAlgorithm  string                    `json:"digestAlgorithm"`
	Head             ocfl.VNum                 `json:"head"`
	ContentDirectory string                    `json:"contentDirectory,omitempty"`
	Manifest         ocfl.DigestMap            `json:"manifest"`
	Versions         map[ocfl.VNum]*Version    `json:"versions"`
	Fixity           map[string]ocfl.DigestMap `json:"fixity,omitempty"`
	// contains filtered or unexported fields
}

Inventory represents contents of an OCFL v1.x inventory.json file

func NewInventory added in v0.0.23 

func NewInventory(base *Inventory, ver *Version, fixer ocfl.FixitySource, contentPathFn ocfl.RemapFunc) (*Inventory, error)

NextInventory builds a new inventory from base with an incremented HEAD and a new version block. The new manifest will include the previous manifest plus new entries for new content. Manifest paths are generated by passing new content paths through contentPathFn. Fixer is used to provide new fixity values.

func ValidateInventory 

func ValidateInventory(ctx context.Context, fsys ocfl.FS, name string, vops ...ValidationOption) (*Inventory, *validation.Result)

ValidateInventory fully validates an inventory at path name in fsys.

func ValidateInventoryReader 

func ValidateInventoryReader(ctx context.Context, reader io.Reader, vops ...ValidationOption) (*Inventory, *validation.Result)

func (Inventory) ContentPath 

func (inv Inventory) ContentPath(v int, logical string) (string, error)

ContentPath resolves the logical path from the version state with number v to a content path (i.e., a manifest path). The content path is relative to the object's root directory. If v is zero, the inventories head version is used.

func (Inventory) Digest 

func (inv Inventory) Digest() string

Digest of Inventory's source json using the inventory digest. If the Inventory wasn't decoded using ValidateInventory or ValidateInventoryReader, an empty string is returned.

func (Inventory) GetFixity added in v0.0.23 

func (inv Inventory) GetFixity(digest string) ocfl.DigestSet

GetFixity implements ocfl.FixitySource for Inventory

func (Inventory) NormalizedCopy added in v0.0.19 

func (inv Inventory) NormalizedCopy() (*Inventory, error)

NormalizedCopy returns a copy of the inventory with all digests normalized.

func (Inventory) VNums 

func (inv Inventory) VNums() []ocfl.VNum

VNums returns a sorted slice of VNums corresponding to the keys in the inventory's 'versions' block.

func (*Inventory) Validate 

func (inv *Inventory) Validate() *validation.Result

Validate validates the inventory. It only checks the inventory's structure and internal consistency. The inventory is valid if the returned validation result includes no fatal errors (it may include warning errors). The returned validation.Result is not associated with a logger, and no errors in the result have been logged.

func (Inventory) Version added in v0.0.23 

func (inv Inventory) Version(v int) *Version

Version returns the version entry from the entry with number v. If v is 0, the head version is used. If no version entry exists, nil is returned

type Object 

type Object struct {
	ocfl.ObjectRoot
	Inventory Inventory
}

Object represents an existing OCFL v1.x object. Use GetObject() to initialize new Objects.

func GetObject 

func GetObject(ctx context.Context, fsys ocfl.FS, dir string) (*Object, error)

GetObject returns the Object at the path in fsys. It returns an error if the object's root directory doesn't include an object declaration file, or if the root inventory is invalid.

func ValidateObject 

func ValidateObject(ctx context.Context, fsys ocfl.FS, root string, vops ...ValidationOption) (*Object, *validation.Result)

func (*Object) GetContent added in v0.0.23 

func (obj *Object) GetContent(digest string) (ocfl.FS, string)

GetContent implements ocfl.ContentSource for Object

func (*Object) GetFixity added in v0.0.23 

func (obj *Object) GetFixity(digest string) ocfl.DigestSet

Fixity implements ocfl.FixitySource for Object

func (*Object) Stage added in v0.0.23 

func (obj *Object) Stage(i int) (*ocfl.Stage, error)

func (*Object) SyncInventory 

func (obj *Object) SyncInventory(ctx context.Context) error

SyncInventory downloads and validates the object's root inventory. If successful the object's Inventory value is updated.

func (*Object) Validate 

func (obj *Object) Validate(ctx context.Context, opts ...ValidationOption) *validation.Result

Validate fully validates the Object. If the object is valid, the Object's inventory is updated with the inventory downloaded during validation.

type Store 

type Store struct {
	Layout extension.Layout
	// contains filtered or unexported fields
}

Store represents an existing OCFL v1.x Storage Root.

func GetStore 

func GetStore(ctx context.Context, fsys ocfl.FS, root string) (*Store, error)

GetStore returns a *Store for the OCFL Storage Root at root in fsys. The path root must be a directory/prefix with storage root declaration file.

func (Store) Commit 

func (s Store) Commit(ctx context.Context, id string, stage *ocfl.Stage, opts ...CommitOption) error

Commit creates or updates the object with the given id using the contents of stage. The returned error is always a CommitError

func (*Store) Description 

func (s *Store) Description() string

Descriptions returns the description set in the storage root's ocfl_layout.json file, or an empty string if the description is undefined

func (*Store) GetObject 

func (s *Store) GetObject(ctx context.Context, id string) (*Object, error)

GetObject returns the OCFL object using the store's layout extension (if defined). The store layout is set during GetStore() if the storage root includes an ocfl_layout.json file. Otherwise, it can be set using, SetLayout().

func (*Store) GetObjectPath 

func (s *Store) GetObjectPath(ctx context.Context, p string) (*Object, error)

GetObjectPath returns an Object for the given path relative to the storage root.

func (*Store) LayoutName 

func (s *Store) LayoutName() string

LayoutName returns the extension name set in the storage root's ocfl_layout.json file, or an empty string if the name is not set.

func (*Store) ObjectExists 

func (s *Store) ObjectExists(ctx context.Context, id string) (bool, error)

ObjectExists returns true if an object with the given ID exists in the store

func (Store) Objects 

func (s Store) Objects(ctx context.Context, fn func(*Object, error) error) error

Objects iterates over over the OCFL Object in the storage root and calls fn for each. If an error is encountered while loading the object, the error is passed to fn. If fn returns an error the iteration process terminates.

func (*Store) ReadLayout 

func (s *Store) ReadLayout(ctx context.Context) error

ReadLayout resolves the layout extension defined in ocfl_layout.json and loads its configuration file (if present) from the store's extensions directory. The store's active layout is set to the new layout. If no error is returned, subsequent calls to ResolveID() will resolve object ids using the new layout.

func (*Store) ResolveID 

func (s *Store) ResolveID(id string) (string, error)

ResolveID resolves the storage path for the given id relative using the storage root's layout extension

func (*Store) Root 

func (s *Store) Root() (ocfl.FS, string)

Root returns the Store's ocfl.FS and root directory.

func (*Store) Spec 

func (s *Store) Spec() ocfl.Spec

Spec returns the ocfl.Spec defined in the storage root's declaration.

func (*Store) Validate 

func (s *Store) Validate(ctx context.Context, opts ...ValidationOption) *validation.Result

Validate performs complete validation on the store

type ValidationOption 

type ValidationOption func(*validationOptions)

ValidationOption is a type used to configure the behavior of several Validation functions in the package.

func FallbackOCFL 

func FallbackOCFL(spec ocfl.Spec) ValidationOption

FallbackOCFL is used to set the OCFL spec referenced in error messages when an OCFL spec version cannot be determined during validation. Default is OCFL v1.0.

func SkipDigests 

func SkipDigests() ValidationOption

SkipDigest is used to skip file digest validation when validating an Object.

func SkipObjects 

func SkipObjects() ValidationOption

SkipObjects is used to skip object validation when validating storage roots.

func ValidationLogger 

func ValidationLogger(l *slog.Logger) ValidationOption

ValidationLogger sets the logger where validation errors are logged.

func ValidationMaxErrs 

func ValidationMaxErrs(max int) ValidationOption

ValidationMaxErrs sets the limit on the number of fatal error and warning errors (each) in the returned validation.Result. The default is 100. Use -1 to set no limit.

type Version 

type Version struct {
	Created time.Time      `json:"created"`
	State   ocfl.DigestMap `json:"state"`
	Message string         `json:"message,omitempty"`
	User    *ocfl.User     `json:"user,omitempty"`
}

Version represents object version state and metadata

Source Files

View all Source files

Directories

Path Synopsis
generate

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.