Documentation ¶
Overview ¶
Package ocflv1 provides an implementation of OCFL v1.0 and v1.1.
Index ¶
- Variables
- func Commit(ctx context.Context, fsys ocfl.WriteFS, objPath string, objID string, ...) (err error)
- func InitStore(ctx context.Context, fsys ocfl.WriteFS, root string, conf *InitStoreConf) error
- func Objects(ctx context.Context, fsys ocfl.FS, pth ocfl.PathSelector, ...) error
- func ValidateStore(ctx context.Context, fsys ocfl.FS, root string, vops ...ValidationOption) *validation.Result
- func WriteInventory(ctx context.Context, fsys ocfl.WriteFS, inv *Inventory, dirs ...string) error
- type ChangedDigestErr
- type CommitError
- type CommitOption
- func WithAllowUnchanged() CommitOption
- func WithContentDir(cd string) CommitOption
- func WithCreated(c time.Time) CommitOption
- func WithHEAD(v int) CommitOption
- func WithLogger(logger *slog.Logger) CommitOption
- func WithManifestPathFunc(fn func(paths []string) []string) CommitOption
- func WithMessage(msg string) CommitOption
- func WithOCFLSpec(spec ocfl.Spec) CommitOption
- func WithUser(user ocfl.User) CommitOption
- func WithVersionPadding(p int) CommitOption
- type ContentDigestErr
- type InitStoreConf
- type InvDecodeError
- type Inventory
- func NewInventory(base *Inventory, ver *Version, fixer ocfl.FixitySource, ...) (*Inventory, error)
- func ValidateInventory(ctx context.Context, fsys ocfl.FS, name string, vops ...ValidationOption) (*Inventory, *validation.Result)
- func ValidateInventoryReader(ctx context.Context, reader io.Reader, vops ...ValidationOption) (*Inventory, *validation.Result)
- func (inv Inventory) ContentPath(v int, logical string) (string, error)
- func (inv Inventory) Digest() string
- func (inv Inventory) GetFixity(digest string) ocfl.DigestSet
- func (inv Inventory) NormalizedCopy() (*Inventory, error)
- func (inv Inventory) VNums() []ocfl.VNum
- func (inv *Inventory) Validate() *validation.Result
- func (inv Inventory) Version(v int) *Version
- type Object
- func (obj *Object) GetContent(digest string) (ocfl.FS, string)
- func (obj *Object) GetFixity(digest string) ocfl.DigestSet
- func (obj *Object) Stage(i int) (*ocfl.Stage, error)
- func (obj *Object) SyncInventory(ctx context.Context) error
- func (obj *Object) Validate(ctx context.Context, opts ...ValidationOption) *validation.Result
- type Store
- func (s Store) Commit(ctx context.Context, id string, stage *ocfl.Stage, opts ...CommitOption) error
- func (s *Store) Description() string
- func (s *Store) GetObject(ctx context.Context, id string) (*Object, error)
- func (s *Store) GetObjectPath(ctx context.Context, p string) (*Object, error)
- func (s *Store) LayoutName() string
- func (s *Store) ObjectExists(ctx context.Context, id string) (bool, error)
- func (s Store) Objects(ctx context.Context, fn func(*Object, error) error) error
- func (s *Store) ReadLayout(ctx context.Context) error
- func (s *Store) ResolveID(id string) (string, error)
- func (s *Store) Root() (ocfl.FS, string)
- func (s *Store) Spec() ocfl.Spec
- func (s *Store) Validate(ctx context.Context, opts ...ValidationOption) *validation.Result
- type ValidationOption
- type Version
Examples ¶
Constants ¶
This section is empty.
Variables ¶
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") )
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") )
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 ¶
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 ¶
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 ¶
ContentDigestErr content digest doesn't match recorded digest
func (ContentDigestErr) Error ¶
func (err ContentDigestErr) Error() string
type InitStoreConf ¶
type InvDecodeError ¶
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 ¶
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 ¶
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) NormalizedCopy ¶ added in v0.0.19
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.
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 ¶
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
GetContent implements ocfl.ContentSource for Object
func (*Object) SyncInventory ¶
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 ¶
Store represents an existing OCFL v1.x Storage Root.
func GetStore ¶
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 ¶
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 ¶
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 ¶
GetObjectPath returns an Object for the given path relative to the storage root.
func (*Store) LayoutName ¶
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 ¶
ObjectExists returns true if an object with the given ID exists in the store
func (Store) Objects ¶
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 ¶
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 ¶
ResolveID resolves the storage path for the given id relative using the storage root's layout extension
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.