Documentation ¶
Overview ¶
Package ocflv1 provides an implementation of OCFL v1.0 and v1.1.
Index ¶
- Variables
- func Commit(ctx context.Context, fsys ocfl.WriteFS, objRoot string, id string, ...) 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(digest string, paths []string) []string) CommitOption
- func WithMessage(msg string) CommitOption
- func WithOCFLSpec(spec ocfl.Spec) CommitOption
- func WithUser(user User) CommitOption
- func WithVersionPadding(p int) CommitOption
- type ContentDigestErr
- type InitStoreConf
- type InvDecodeError
- type Inventory
- func (inv *Inventory) AddVersion(stage *ocfl.Stage, msg string, user *User, created time.Time, ...) (err error)
- func (inv Inventory) Alg() digest.Alg
- func (inv Inventory) ContentPath(v int, logical string) (string, error)
- func (inv Inventory) Digest() string
- func (inv Inventory) EachStatePath(v int, fn func(f string, digest string, conts []string) error) error
- func (inv Inventory) GetVersion(v int) *Version
- func (inv *Inventory) VNums() []ocfl.VNum
- func (inv *Inventory) Validate() *validation.Result
- type Object
- 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) LayoutOK() bool
- 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) SetLayout(layout extensions.Layout) error
- func (s *Store) Spec() ocfl.Spec
- func (s *Store) Validate(ctx context.Context, opts ...ValidationOption) *validation.Result
- type User
- 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 ¶ added in v0.0.15
func Commit(ctx context.Context, fsys ocfl.WriteFS, objRoot string, id string, stage *ocfl.Stage, optFuncs ...CommitOption) error
Commit creates or updates an object in fsys using the provided stage state and content.
Example (Copyobject) ¶
documents using Commit() to make a new object based on last version state of another object.
package main import ( "context" "fmt" "log" "os" "path/filepath" "github.com/srerickson/ocfl" "github.com/srerickson/ocfl/backend/local" "github.com/srerickson/ocfl/ocflv1" ) func main() { 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()) } state, err := sourceObject.State(0) if err != nil { log.Fatal("couldn't retrieve logical state") } // 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.NewStage(state.Alg) stage.State = state.DigestMap stage.SetFS(sourceObject.FS, sourceObject.Path) err = stage.UnsafeSetManifestFixty(sourceObject.Inventory.Manifest, sourceObject.Inventory.Fixity) if err != nil { log.Fatal(err) } 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 ¶ added in v0.0.9
InitStore initializes a new OCFL v1.x storage root on fsys at root.
func Objects ¶ added in v0.0.15
func Objects(ctx context.Context, fsys ocfl.FS, pth ocfl.PathSelector, fn func(*Object, error) error) error
Objects iterates over 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 ¶ added in v0.0.8
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 ¶ added in v0.0.15
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 ¶ added in v0.0.15
func (c CommitError) Error() string
func (CommitError) Unwrap ¶ added in v0.0.15
func (c CommitError) Unwrap() error
type CommitOption ¶ added in v0.0.11
type CommitOption func(*commitOpt)
CommitOption is used configure Commit
func WithAllowUnchanged ¶ added in v0.0.15
func WithAllowUnchanged() CommitOption
WithAllowUnchanged enables committing a version with the same state as the existing head version.
func WithContentDir ¶ added in v0.0.9
func WithContentDir(cd string) CommitOption
WithContentDir is used to set the ContentDirectory value for the first version of an object. It is ignored for subsequent versions.
func WithCreated ¶ added in v0.0.13
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 ¶ added in v0.0.15
func WithHEAD(v int) CommitOption
WithHEAD is used to enforce a particul version number for the commit. The default is to increment the existing verion if possible.
func WithLogger ¶ added in v0.0.9
func WithLogger(logger *slog.Logger) CommitOption
WithLogger sets the logger used for logging during commit.
func WithManifestPathFunc ¶ added in v0.0.15
func WithManifestPathFunc(fn func(digest string, 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 ¶ added in v0.0.9
func WithMessage(msg string) CommitOption
WithMessage sets the message for the new object version
func WithOCFLSpec ¶ added in v0.0.13
func WithOCFLSpec(spec ocfl.Spec) CommitOption
WithOCFLSpec is used to set the OCFL specification for the new object version.
func WithUser ¶ added in v0.0.9
func WithUser(user User) CommitOption
WithUser sets the user for the new object version
func WithVersionPadding ¶ added in v0.0.9
func WithVersionPadding(p int) CommitOption
WithVersionPadding is used to set the version number padding for the first version of an object. It is ignored for subsequent versions.
type ContentDigestErr ¶
ContentDigestErr content digest doesn't match recorded digest
func (ContentDigestErr) Error ¶
func (err ContentDigestErr) Error() string
type InitStoreConf ¶ added in v0.0.9
type InitStoreConf struct { Spec ocfl.Spec Description string Layout extensions.Layout Extensions []extensions.Extension }
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 ValidateInventory ¶
func ValidateInventory(ctx context.Context, fsys ocfl.FS, name string, alg digest.Alg, vops ...ValidationOption) (*Inventory, *validation.Result)
ValidateInventory fully validates an inventory at path name in fsys.
func ValidateInventoryReader ¶ added in v0.0.11
func ValidateInventoryReader(ctx context.Context, reader io.Reader, alg digest.Alg, vops ...ValidationOption) (*Inventory, *validation.Result)
func (*Inventory) AddVersion ¶ added in v0.0.15
func (inv *Inventory) AddVersion(stage *ocfl.Stage, msg string, user *User, created time.Time, pathfn func(string, []string) []string) (err error)
AddVersion builds a new version and updates the inventory using state and manifest from the provided stage. The new version will have have the given message, user, and created timestamp. The function pathfn, is used The inventories head is incremented. The function pathfn is optional and is is used to customize content paths for new manifest entries.
func (Inventory) Alg ¶ added in v0.0.13
Alg returns the inventory's digest algorithm as a digest.Alg. It panics if the digest algorithm isn't set or is unrecognized.
func (Inventory) ContentPath ¶ added in v0.0.4
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) EachStatePath ¶ added in v0.0.13
func (inv Inventory) EachStatePath(v int, fn func(f string, digest string, conts []string) error) error
EachStatePath calls fn for each file in the state for the version with number v. If v is 0, the inventory's head version is used. The function fn is called with the logical file path from the version state, the file's digest as it appears in the version state, and a slice of content paths associated with the digest from the inventory manifest. The digest will always be a non-empty string and the slice of content paths will always include at least one entry. If the digest and content paths for a logical path are not found (i.e., the inventory is invalid), fn is not called; instead EachStatePath return an error. If any call to fn returns a non-nil error, no additional calls are made and the error is returned by EachStatePath. If no version state with number v is present in the inventory, an error is returned.
func (Inventory) GetVersion ¶ added in v0.0.13
GetVersion 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
func (*Inventory) VNums ¶
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) State ¶ added in v0.0.15
func (obj Object) State(i int) (*ocfl.ObjectState, error)
State initializes a new ocfl.ObjectState for the object version with the given index. If the index is 0, the most recent version (HEAD) is used.
func (Object) StateFS ¶ added in v0.0.17
func (obj Object) StateFS(i int) (*ocfl.ObjectStateFS, error)
StateFS returns an ocfl.FS for accessing the logical contents of the object at the version with index i. If i is zero, the most recent version is used.
func (*Object) SyncInventory ¶ added in v0.0.15
SyncInventory downloads and validates the object's root inventory. If successful the object's Inventory value is updated.
func (*Object) Validate ¶ added in v0.0.9
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 {
// contains filtered or unexported fields
}
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 ¶ added in v0.0.9
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 ¶ added in v0.0.9
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 ¶ added in v0.0.9
GetObjectPath returns an Object for the given path relative to the storage root.
func (*Store) LayoutName ¶ added in v0.0.9
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) LayoutOK ¶ added in v0.0.9
LayoutSet returns boolean indicating if the store's layout function is set
func (*Store) ObjectExists ¶ added in v0.0.9
ObjectExists returns true if an object with the given ID exists in the store
func (Store) Objects ¶ added in v0.0.15
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 ¶ added in v0.0.6
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 ¶ added in v0.0.9
ResolveID resolves the storage path for the given id relative using the storage root's layout extension
func (*Store) SetLayout ¶ added in v0.0.6
func (s *Store) SetLayout(layout extensions.Layout) error
SetLayout sets the store's active layout. If no error is returned, subsequent calls to ResolveID() will resolve object ids using the new layout.
func (*Store) Spec ¶ added in v0.0.9
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 ¶ added in v0.0.11
type ValidationOption func(*validationOptions)
ValidationOption is a type used to configure the behavior of several Validation functions in the package.
func FallbackOCFL ¶ added in v0.0.11
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 ¶ added in v0.0.11
func SkipDigests() ValidationOption
SkipDigest is used to skip file digest validation when validating an Object.
func SkipObjects ¶ added in v0.0.11
func SkipObjects() ValidationOption
SkipObjects is used to skip object validation when validating storage roots.
func ValidationAlgRegistry ¶ added in v0.0.11
func ValidationAlgRegistry(r *digest.Registry) ValidationOption
ValidationAlgRegistry sets the registry of available algorithms that can be used in an inventory fixity
func ValidationLogger ¶ added in v0.0.11
func ValidationLogger(l *slog.Logger) ValidationOption
ValidationLogger sets the logger where validation errors are logged.
func ValidationMaxErrs ¶ added in v0.0.11
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.