ocfl

package module
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2024 License: MIT Imports: 35 Imported by: 8

README

An OCFL implementation for Go

godocs

This Go module provide an implementation of the Oxford Common File Layout (OCFL).

[!WARNING]
The API is under heavy development and will have constant breaking changes.

Development

Requires Go >= v1.23.

Documentation

Overview

This module is an implementation of the Oxford Common File Layout (OCFL) specification. The top-level package provides version-independent functionality. The ocflv1 package provides the bulk of implementation.

Index

Constants

View Source 
const (
	NamasteTypeObject = "ocfl_object" // type string for OCFL Object declaration
	NamasteTypeStore  = "ocfl"        // type string for OCFL Storage Root declaration
)
View Source 
const (
	// HasNamaste indicates that an object root directory includes a NAMASTE
	// object declaration file
	HasNamaste objectStateFlag = 1 << iota
	// HasInventory indicates that an object root includes an "inventory.json"
	// file
	HasInventory
	// HasSidecar indicates that an object root includes an "inventory.json.*"
	// file (the inventory sidecar).
	HasSidecar
	// HasExtensions indicates that an object root includes a directory named
	// "extensions"
	HasExtensions
	//HasLogs indicates that an object root includes a directory named "logs"
	HasLogs
)
View Source 
const (
	// package version
	Version = "0.7.0"

	Spec1_0 = Spec("1.0")
	Spec1_1 = Spec("1.1")
)

Variables

View Source 
var (
	ErrNamasteNotExist = fmt.Errorf("missing NAMASTE declaration: %w", fs.ErrNotExist)
	ErrNamasteContents = errors.New("invalid NAMASTE declaration contents")
	ErrNamasteMultiple = errors.New("multiple NAMASTE declarations found")
)
View Source 
var (
	ErrOCFLNotImplemented    = errors.New("unimplemented or missing version of the OCFL specification")
	ErrObjectNamasteExists   = fmt.Errorf("found existing OCFL object declaration: %w", fs.ErrExist)
	ErrObjectNamasteNotExist = fmt.Errorf("the OCFL object declaration does not exist: %w", ErrNamasteNotExist)
	ErrObjRootStructure      = errors.New("object includes invalid files or directories")
)
View Source 
var (
	ErrSpecInvalid  = errors.New("invalid OCFL spec version")
	ErrSpecNotFound = errors.New("OCFL spec file not found")
)
View Source 
var (
	ErrVNumInvalid = errors.New(`invalid version`)
	ErrVNumPadding = errors.New(`inconsistent version padding in version sequence`)
	ErrVNumMissing = errors.New(`missing version in version sequence`)
	ErrVerEmpty    = errors.New("no versions found")

	// Some functions in this package use the zero value VNum to indicate the
	// most recent, "head" version.
	Head = VNum{}
)
View Source 
var ErrFileType = errors.New("invalid file type for an OCFL context")
View Source 
var (
	// Error: invalid contents of inventory sidecar file
	ErrInventorySidecarContents = errors.New("invalid contents of inventory sidecar file")
)
View Source 
var ErrLayoutUndefined = errors.New("storage root's layout is undefined")
View Source 
var ErrMapMakerExists = errors.New("path and digest exist")

ErrMapMakerExists is returned when calling Add with a path and digest that are already present in the MapMaker

View Source 
var ErrNotFile = errors.New("not a file")

Functions

func Copy added in v0.0.23 

func Copy(ctx context.Context, dstFS WriteFS, dst string, srcFS FS, src string) (err error)

Copy copies src in srcFS to dst in dstFS. If srcFS and dstFS are the same refererence and it implements CopyFS, then Copy uses the fs's Copy() method.

func ParseVNum 

func ParseVNum(v string, vn *VNum) error

ParseVNum parses string as an a VNum and sets the value referenced by vn.

func ReadAll added in v0.3.0 

func ReadAll(ctx context.Context, fsys FS, name string) ([]byte, error)

ReadAll returns the contents of a file.

func ReadSidecarDigest added in v0.1.0 

func ReadSidecarDigest(ctx context.Context, fsys FS, name string) (string, error)

ReadSidecarDigest reads the digest from an inventory.json sidecar file

func StatFile added in v0.5.0 

func StatFile(ctx context.Context, fsys FS, name string) (fs.FileInfo, error)

StatFile returns file informatoin for the file name in fsys.

func ValidateInventoryBytes added in v0.7.0 

func ValidateInventoryBytes(byts []byte) (Inventory, *Validation)

ValidateInventoryBytes parses and fully validates the byts as contents of an inventory.json file. This is mostly used for testing.

func ValidateInventorySidecar added in v0.3.0 

func ValidateInventorySidecar(ctx context.Context, inv Inventory, fsys FS, dir string) error

ValidateInventorySidecar reads the inventory sidecar with inv's digest algorithm (e.g., inventory.json.sha512) in directory dir and return an error if the sidecar content is not formatted correctly or if the inv's digest doesn't match the value found in the sidecar.

func ValidateNamaste added in v0.1.0 

func ValidateNamaste(ctx context.Context, fsys FS, name string) (err error)

ValidateNamaste validates a namaste declaration

func WriteDeclaration 

func WriteDeclaration(ctx context.Context, root WriteFS, dir string, d Namaste) error

func WriteSpecFile 

func WriteSpecFile(ctx context.Context, fsys WriteFS, dir string, n Spec) (string, error)

Types

type Commit added in v0.1.0 

type Commit struct {
	ID      string // required for new objects in storage roots without a layout.
	Stage   *Stage // required
	Message string // required
	User    User   // required

	// advanced options
	Created         time.Time // time.Now is used, if not set
	Spec            Spec      // OCFL specification version for the new object version
	NewHEAD         int       // enforces new object version number
	AllowUnchanged  bool
	ContentPathFunc RemapFunc

	Logger *slog.Logger
}

Commit represents an update to object.

type CommitError added in v0.1.0 

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.1.0 

func (c CommitError) Error() string

func (CommitError) Unwrap added in v0.1.0 

func (c CommitError) Unwrap() error

type ContentSource added in v0.0.23 

type ContentSource interface {
	// GetContent returns an FS and path to a file in FS for a file with the given digest.
	// If no content is associated with the digest, fsys is nil and path is an empty string.
	GetContent(digest string) (fsys FS, path string)
}

ContentSource is used to access content with a given digest when creating and upadting objects.

type CopyFS 

type CopyFS interface {
	WriteFS
	// Copy creates or updates the file at dst with the contents of src. If dst
	// exists, it should be overwritten
	Copy(ctx context.Context, dst string, src string) error
}

CopyFS is a storage backend that supports copying files.

type DigestMap 

type DigestMap map[string][]string

DigestMap maps digests to file paths.

func (DigestMap) Clone added in v0.0.23 

func (m DigestMap) Clone() DigestMap

func (DigestMap) Digests 

func (m DigestMap) Digests() []string

Digests returns a slice of the digest values in the DigestMap. Digest strings are not normalized; they may be uppercase, lowercase, or mixed.

func (DigestMap) EachPath 

func (m DigestMap) EachPath(fn func(pth, digest string) bool) bool

EachPath calls fn for each path in the Map. If fn returns false, iteration stops and EachPath returns false.

func (DigestMap) Eq 

func (m DigestMap) Eq(other DigestMap) bool

Eq returns true if m and the other have the same content: they have the same (normalized) digests corresponding to the same set of paths. If either map has a digest conflict (same digest appears twice with different case), Eq returns false.

func (DigestMap) GetDigest 

func (m DigestMap) GetDigest(p string) string

GetDigest returns the digest for path p or an empty string if the digest is not present.

func (DigestMap) HasDigestCase added in v0.0.23 

func (m DigestMap) HasDigestCase() (hasLower bool, hasUpper bool)

HasDigestCase returns two booleans indicating whether m's digests use lowercase and uppercase characters.

func (DigestMap) Merge 

func (m1 DigestMap) Merge(m2 DigestMap, replace bool) (DigestMap, error)

Merge returns a new DigestMap constructed by normalizing and merging m1 and m2. If a paths has different digests in m1 and m2, an error returned unless replace is true, in which case the value from m2 is used.

func (DigestMap) Normalize 

func (m DigestMap) Normalize() (norm DigestMap, err error)

Normalize returns a normalized copy on m (with lowercase digests). An error is returned if m has a digest conflict.

func (DigestMap) NumPaths added in v0.0.23 

func (m DigestMap) NumPaths() int

NumPaths returns the number of paths in the m

func (DigestMap) PathMap 

func (m DigestMap) PathMap() PathMap

PathMap returns the DigestMap's contents as a map with path names for keys and digests for values. PathMap doesn't check if the same path appears twice in the DigestMap.

func (DigestMap) PathMapValid 

func (m DigestMap) PathMapValid() (PathMap, error)

PathMapValid is like PathMap, except it returns an error if it encounters invalid path names or if the same path appears multiple times.

func (DigestMap) Paths 

func (m DigestMap) Paths() []string

Paths returns a sorted slice of all path names in the DigestMap.

func (DigestMap) Remap 

func (m DigestMap) Remap(fns ...RemapFunc)

func (DigestMap) Valid 

func (m DigestMap) Valid() error

Valid returns a non-nil error if m is invalid.

type FS 

type FS interface {
	OpenFile(ctx context.Context, name string) (fs.File, error)
	ReadDir(ctx context.Context, name string) ([]fs.DirEntry, error)
}

FS is a minimal, read-only storage layer abstraction. It is similar to the standard library's io/fs.FS, except it uses contexts and OpenFile is not required to gracefully handle directories.

func DirFS 

func DirFS(dir string) FS

DirFS is shorthand for NewFS(os.DirFS(dir))

func NewFS 

func NewFS(fsys fs.FS) FS

NewFS wraps an io/fs.FS as an ocfl.FS

type FileDigests added in v0.5.0 

type FileDigests struct {
	FileRef
	Algorithm digest.Algorithm // primary digest algorithm (sha512 or sha256)
	Digests   digest.Set       // computed digest of file contents. Must include entry for the primary algorithm
}

FileDigests is a FileRef plus digest values of the file contents.

func (FileDigests) Validate added in v0.5.0 

func (pd FileDigests) Validate(ctx context.Context, reg digest.AlgorithmRegistry) error

Validate confirms the digest values in pd using alogirthm definitions from reg. If the digests values do not match, the resulting error is a *digest.DigestError.

type FileDigestsErrSeq added in v0.5.0 

type FileDigestsErrSeq iter.Seq2[*FileDigests, error]

FileDigestsErrSeq is an iterator that yields results and errors from a digesting file contents.

func (FileDigestsErrSeq) Stage added in v0.5.0 

func (digests FileDigestsErrSeq) Stage() (*Stage, error)

Stage returns a new stage from the *[FileDigest]s in digests. An error is returned if digests yields an error or if the yielded *FileDigests are inconsisent (see FileDigestsSeq.Stage).

func (FileDigestsErrSeq) UntilErr added in v0.5.0 

func (dfs FileDigestsErrSeq) UntilErr() (FileDigestsSeq, func() error)

UntilErr returns an iterator of *FileDigests from dfs that terminates on the first non-nil error in dfs. The terminating error is returned by errFn

type FileDigestsSeq added in v0.5.0 

type FileDigestsSeq iter.Seq[*FileDigests]

FileDigestSeq is a

func (FileDigestsSeq) Stage added in v0.5.0 

func (digests FileDigestsSeq) Stage() (*Stage, error)

Stage builds a stage from values in digests. The stage's state uses the Path from each value in digests. The values in digests must have the same FS, primary digest algorithm, and base path, otherwise an error is returned.

func (FileDigestsSeq) ValidateBatch added in v0.5.0 

func (files FileDigestsSeq) ValidateBatch(ctx context.Context, reg digest.AlgorithmRegistry, numgos int) iter.Seq[error]

ValidateBatch concurrently validates sequence of FileDigests using numgos go routines. It returns an iterator of non-nill error values for any files that fail validation. If validation fails because a files content has changed, the yielded error is a *digest.DigestError.

type FileErrSeq added in v0.5.0 

type FileErrSeq iter.Seq2[*FileRef, error]

FileErrSeq is an iterator that yields *FileRef values or errors occuring while accessing a file.

func (FileErrSeq) IgnoreErr added in v0.5.0 

func (fileErrs FileErrSeq) IgnoreErr() FileSeq

IgnoreErr returns an iterator of *[FileRef]s in seq that are not associated with an error.

func (FileErrSeq) UntilErr added in v0.5.0 

func (fileErrs FileErrSeq) UntilErr() (FileSeq, func() error)

UntilErr returns a new iterator yielding *FileRef values from seq that terminates on the first non-nil error in seq. The terminating error is returned by errFn.

type FileRef added in v0.5.0 

type FileRef struct {
	FS      FS          // The FS where the file is stored.
	BaseDir string      // parent directory relative to an FS.
	Path    string      // file path relative to BaseDir
	Info    fs.FileInfo // file info from StatFile (may be nil)
}

FileRef includes everything needed to access a file, including a reference to the FS where the file is stored. It may include file metadata from calling StatFile().

func (FileRef) FullPath added in v0.5.0 

func (f FileRef) FullPath() string

FullPath returns the file's path relative to an FS

func (FileRef) FullPathDir added in v0.5.0 

func (f FileRef) FullPathDir() string

FullPathDir returns the full path of the directory where the file is stored.

func (FileRef) Namaste added in v0.5.0 

func (f FileRef) Namaste() Namaste

Namastes parses the file's name as a Namaste declaration and returns the result. If the file is not a namaste declaration, the zero-value is returned.

func (*FileRef) Open added in v0.5.0 

func (f *FileRef) Open(ctx context.Context) (fs.File, error)

Open return an fs.File for reading the contents of the file at f.

func (*FileRef) OpenObject added in v0.5.0 

func (f *FileRef) OpenObject(ctx context.Context, opts ...ObjectOption) (*Object, error)

OpenObject opens f's directory as an *Object. If the the directory is not an existing object, an error is returned.

func (*FileRef) Stat added in v0.5.0 

func (f *FileRef) Stat(ctx context.Context) error

Stat() calls StatFile on the file at f and updates f.Info.

type FileSeq added in v0.1.0 

type FileSeq iter.Seq[*FileRef]

FileSeq is an iterator that yields *FileRef values.

func Files 

func Files(fsys FS, names ...string) FileSeq

Files returns a FileSeq for iterating over the named files in fsys.

func FilesSub added in v0.5.0 

func FilesSub(fsys FS, dir string, files ...string) FileSeq

Files returns a FileSeq for iterating over the named files, relative to the directory dir in fsys.

func WalkFiles added in v0.5.0 

func WalkFiles(ctx context.Context, fsys FS, dir string) (files FileSeq, errFn func() error)

WalkFiles returns a FileSeq for iterating over the files in dir and its subdirectories. If an error occurs while reading FS, iteration terminates. The terminating error is returned by errFn

func (FileSeq) Digest added in v0.5.0 

func (files FileSeq) Digest(ctx context.Context, alg digest.Algorithm, fixityAlgs ...digest.Algorithm) FileDigestsErrSeq

Digest concurrently computes digests for each file in files. It is the same as DigestBatch with numgos set to runtime.NumCPU(). The resulting iterator yields digest results or an error if the file could not be digestsed.

func (FileSeq) DigestBatch added in v0.5.0 

func (files FileSeq) DigestBatch(ctx context.Context, numgos int, alg digest.Algorithm, fixityAlgs ...digest.Algorithm) FileDigestsErrSeq

DigestBatch concurrently computes digests for each file in files. The resulting iterator yields digest results or an error if the file could not be digestsed. If numgos is < 1, the value from runtime.GOMAXPROCS(0) is used.

func (FileSeq) Filter added in v0.5.0 

func (files FileSeq) Filter(filter func(*FileRef) bool) FileSeq

Filter returns a new FileSeq that yields values in files that satisfy the filter condition.

func (FileSeq) IgnoreHidden added in v0.5.0 

func (files FileSeq) IgnoreHidden() FileSeq

IgnoreHidden returns a new FileSeq that does not included hidden files (files with a path element that begins with '.'). It only considers a FileRef's Path value, not its BaseDir.

func (FileSeq) OpenObjects added in v0.5.0 

func (files FileSeq) OpenObjects(ctx context.Context, opts ...ObjectOption) iter.Seq2[*Object, error]

OpenObjects returns an iterator with results from calling OpenObject() on each *FileRef in files. Unlike FileSeq.OpenObjectsBatch, objects are opened sequentially, in the same goroutine as the caller.

func (FileSeq) OpenObjectsBatch added in v0.5.0 

func (files FileSeq) OpenObjectsBatch(ctx context.Context, numgos int, opts ...ObjectOption) iter.Seq2[*Object, error]

OpenObjectsBatch returns an iterator with results from calling OpenObjects() on each *FileRef in files. Unlike FileSeq.OpenObjects, objects are opened in separate goroutines and may not be yielded in the same order as the input.

func (FileSeq) Stat added in v0.5.0 

func (files FileSeq) Stat(ctx context.Context) FileErrSeq

Stat returns an iterator that yields a pointer to a new FileRef and error with results from calling StatFile for values in files (values from files are not modified).

type FileWalker added in v0.5.0 

type FileWalker interface {
	FS
	// WalkFiles returns a function iterator that yields all files in
	// dir and its subdirectories
	WalkFiles(ctx context.Context, dir string) (FileSeq, func() error)
}

FileWalker is an FS with an optimized implementation of WalkFiles

type FixitySource added in v0.0.23 

type FixitySource interface {
	// GetFixity returns a DigestSet with alternate digests for the content with
	// the digest derived using the stage's primary digest algorithm.
	GetFixity(digest string) digest.Set
}

FixitySource is used to access alternate digests for content with a given digest (sha512 or sha256) when creating or updating objects.

type Inventory added in v0.7.0 

type Inventory interface {
	FixitySource
	ContentDirectory() string
	Digest() string
	DigestAlgorithm() digest.Algorithm
	Head() VNum
	ID() string
	Manifest() DigestMap
	Spec() Spec
	Version(int) ObjectVersion
	FixityAlgorithms() []string
}

func ReadInventory added in v0.1.0 

func ReadInventory(ctx context.Context, fsys FS, dir string) (inv Inventory, err error)

ReadInventory reads the 'inventory.json' file in dir and validates it. It returns an error if the inventory cann't be paresed or if it is invalid.

type InventoryType added in v0.7.0 

type InventoryType struct {
	Spec
}

InventoryType represents an inventory type string for example: https://ocfl.io/1.0/spec/#inventory

func (InventoryType) MarshalText added in v0.7.0 

func (invT InventoryType) MarshalText() ([]byte, error)

func (InventoryType) String added in v0.7.0 

func (inv InventoryType) String() string

func (*InventoryType) UnmarshalText added in v0.7.0 

func (invT *InventoryType) UnmarshalText(t []byte) error

type MapDigestConflictErr 

type MapDigestConflictErr struct {
	Digest string
}

MapDigestConflictErr indicates same digest found multiple times in the digest map (i.e., with different cases)

func (*MapDigestConflictErr) Error 

func (d *MapDigestConflictErr) Error() string

type MapPathConflictErr 

type MapPathConflictErr struct {
	Path string
}

MapPathConflictErr indicates a path appears more than once in the digest map. It's also used in cases where the path as used as a directory in one instance and a file in another.

func (*MapPathConflictErr) Error 

func (p *MapPathConflictErr) Error() string

type MapPathInvalidErr 

type MapPathInvalidErr struct {
	Path string
}

MapPathInvalidErr indicates an invalid path in a Map.

func (*MapPathInvalidErr) Error 

func (p *MapPathInvalidErr) Error() string

type Namaste added in v0.0.24 

type Namaste struct {
	Type    string
	Version Spec
}

Namaste represents a NAMASTE declaration

func FindNamaste added in v0.0.24 

func FindNamaste(items []fs.DirEntry) (Namaste, error)

FindNamaste returns the NAMASTE declaration from a fs.DirEntry slice. An error is returned if the number of declarations is not one.

func ParseNamaste added in v0.0.24 

func ParseNamaste(name string) (n Namaste, err error)

func (Namaste) Body added in v0.0.24 

func (n Namaste) Body() string

Body returns the expected file contents of the namaste declaration

func (Namaste) IsObject added in v0.5.0 

func (n Namaste) IsObject() bool

IsObject returs true if n's type is 'ocfl_object'

func (Namaste) IsStore added in v0.5.0 

func (n Namaste) IsStore() bool

IsStore returns true if n's type is 'ocfl'

func (Namaste) Name added in v0.0.24 

func (n Namaste) Name() string

Name returns the filename for n ('0=TYPE_VERSION') or an empty string if n is empty

type Object added in v0.1.0 

type Object struct {
	// contains filtered or unexported fields
}

Object represents and OCFL Object, typically contained in a Root.

func NewObject added in v0.1.0 

func NewObject(ctx context.Context, fsys FS, dir string, opts ...ObjectOption) (*Object, error)

NewObject returns an *Object for managing the OCFL object at path in fsys. The object doesn't need to exist when NewObject is called.

func (*Object) Commit added in v0.1.0 

func (obj *Object) Commit(ctx context.Context, commit *Commit) error

Commit creates a new object version based on values in commit.

func (*Object) Exists added in v0.1.0 

func (obj *Object) Exists() bool

Exists returns true if the object's inventory exists.

func (Object) ExtensionNames added in v0.1.0 

func (obj Object) ExtensionNames(ctx context.Context) ([]string, error)

ExtensionNames returns the names of directories in the object's extensions directory. The ObjectRoot's State is initialized if it is nil. If the object root does not include an object declaration, an error is returned. If object root does not include an extensions directory both return values are nil.

func (*Object) FS added in v0.1.0 

func (obj *Object) FS() FS

FS returns the FS where object is stored.

func (*Object) Inventory added in v0.1.0 

func (obj *Object) Inventory() Inventory

Inventory returns the object's Inventory if it exists. If the object doesn't exist, it returns nil.

func (*Object) OpenVersion added in v0.1.0 

func (obj *Object) OpenVersion(ctx context.Context, i int) (*ObjectVersionFS, error)

OpenVersion returns an ObjectVersionFS for the version with the given index (1...HEAD). If i is 0, the most recent version is used.

func (*Object) Path added in v0.1.0 

func (obj *Object) Path() string

Path returns the Object's path relative to its FS.

func (*Object) Root added in v0.7.0 

func (o *Object) Root() *Root

Root returns the object's Root, if known. It is nil unless the *Object was created using Root.NewObject

type ObjectOption added in v0.1.0 

type ObjectOption func(*Object)

ObjectOptions are used to configure the behavior of NewObject()

func ObjectMustExist added in v0.5.0 

func ObjectMustExist() ObjectOption

ObjectMustExists requires the object to exist

type ObjectState 

type ObjectState struct {
	Spec        Spec            // the OCFL spec from the object's NAMASTE declaration file
	VersionDirs VNums           // version directories found in the object directory
	SidecarAlg  string          // digest algorithm used by the inventory sidecar file
	Invalid     []string        // non-conforming directory entries in the object root (max of 8)
	Flags       objectStateFlag // boolean attributes of the object root
}

ObjectState provides details of an OCFL object root based on the names of files and directories in the object's root. ParseObjectDir is typically used to create a new ObjectState from a slice of fs.DirEntry values.

func ParseObjectDir added in v0.1.0 

func ParseObjectDir(entries []fs.DirEntry) *ObjectState

ParseObjectDir returns a new ObjectState based on contents of an object root directory.

func (ObjectState) Empty added in v0.1.0 

func (state ObjectState) Empty() bool

Empty returns true if the object root directory is empty

func (ObjectState) HasExtensions added in v0.1.0 

func (state ObjectState) HasExtensions() bool

HasExtensions returns true if state's HasExtensions flag is set

func (ObjectState) HasInventory added in v0.1.0 

func (state ObjectState) HasInventory() bool

HasInventory returns true if state's HasInventory flag is set

func (ObjectState) HasLogs added in v0.3.1 

func (state ObjectState) HasLogs() bool

HasLogs returns true if state's HasLogs flag is set

func (ObjectState) HasNamaste added in v0.1.0 

func (state ObjectState) HasNamaste() bool

HasNamaste returns true if state's HasNamaste flag is set

func (ObjectState) HasSidecar added in v0.1.0 

func (state ObjectState) HasSidecar() bool

HasSidecar returns true if state's HasSidecar flag is set

func (ObjectState) HasVersionDir added in v0.1.0 

func (state ObjectState) HasVersionDir(v VNum) bool

HasVersionDir returns true if the state's VersionDirs includes v

func (ObjectState) Namaste added in v0.6.0 

func (state ObjectState) Namaste() Namaste

Namaste returns state's Namaste value, which may be a zero value.

type ObjectValidation added in v0.1.0 

type ObjectValidation struct {
	Validation
	// contains filtered or unexported fields
}

ObjectValidation is used to configure and track results from an object validation process.

func ValidateObject added in v0.3.0 

func ValidateObject(ctx context.Context, fsys FS, dir string, opts ...ObjectValidationOption) *ObjectValidation

ValidateObject fully validates the OCFL Object at dir in fsys

func (*ObjectValidation) Add added in v0.1.0 

func (v *ObjectValidation) Add(v2 *Validation)

Add adds and logs all fatal errors and warning from the validation

func (*ObjectValidation) AddFatal added in v0.1.0 

func (v *ObjectValidation) AddFatal(errs ...error)

AddFatal adds fatal errors to the validation

func (*ObjectValidation) AddWarn added in v0.1.0 

func (v *ObjectValidation) AddWarn(errs ...error)

AddWarn adds warning errors to the object validation and logs the errors using the object validations logger, if set.

func (*ObjectValidation) DigestConcurrency added in v0.4.0 

func (v *ObjectValidation) DigestConcurrency() int

DigestConcurrency returns the configured number of go routines used to read and digest contents during validation. The default value is runtime.NumCPU().

func (*ObjectValidation) Logger added in v0.1.0 

func (v *ObjectValidation) Logger() *slog.Logger

Logger returns the validation's logger, which is nil by default.

func (*ObjectValidation) PrefixAdd added in v0.1.0 

func (v *ObjectValidation) PrefixAdd(prefix string, v2 *Validation)

PrefixAdd adds and logs all fatal errors and warning from the valiation, prepending each error with the prefix.

func (*ObjectValidation) SkipDigests added in v0.1.0 

func (v *ObjectValidation) SkipDigests() bool

SkipDigests returns true if the validation is configured to skip digest checks. It is false by default.

func (*ObjectValidation) ValidationAlgorithms added in v0.4.0 

func (v *ObjectValidation) ValidationAlgorithms() digest.AlgorithmRegistry

ValidationAlgorithms returns the registry of digest algoriths the object validation is configured to use. The default value is digest.DefaultRegistry

type ObjectValidationOption added in v0.1.0 

type ObjectValidationOption func(*ObjectValidation)

func ValidationAlgorithms added in v0.4.0 

func ValidationAlgorithms(reg digest.AlgorithmRegistry) ObjectValidationOption

ValidationAlgorithms sets registry of available digest algorithms for fixity validation.

func ValidationDigestConcurrency added in v0.4.0 

func ValidationDigestConcurrency(num int) ObjectValidationOption

ValidationDigestConcurrency is used to set the number of go routines used to read and digest contents during validation.

func ValidationLogger added in v0.1.0 

func ValidationLogger(logger *slog.Logger) ObjectValidationOption

ValidationLogger sets the *slog.Logger that should be used for logging validation errors and warnings.

func ValidationSkipDigest added in v0.1.0 

func ValidationSkipDigest() ObjectValidationOption

type ObjectVersion added in v0.1.0 

type ObjectVersion interface {
	State() DigestMap
	User() *User
	Message() string
	Created() time.Time
}

type ObjectVersionFS added in v0.1.0 

type ObjectVersionFS struct {
	// contains filtered or unexported fields
}

func (*ObjectVersionFS) Close added in v0.1.0 

func (vfs *ObjectVersionFS) Close() error

func (*ObjectVersionFS) Created added in v0.1.0 

func (vfs *ObjectVersionFS) Created() time.Time

func (*ObjectVersionFS) DigestAlgorithm added in v0.1.0 

func (vfs *ObjectVersionFS) DigestAlgorithm() digest.Algorithm

func (*ObjectVersionFS) GetContent added in v0.1.0 

func (vfs *ObjectVersionFS) GetContent(digest string) (FS, string)

func (*ObjectVersionFS) Message added in v0.1.0 

func (vfs *ObjectVersionFS) Message() string

func (*ObjectVersionFS) Num added in v0.1.0 

func (vfs *ObjectVersionFS) Num() int

func (*ObjectVersionFS) Open added in v0.1.0 

func (vfs *ObjectVersionFS) Open(name string) (fs.File, error)

func (*ObjectVersionFS) Stage added in v0.1.0 

func (vfs *ObjectVersionFS) Stage() *Stage

func (*ObjectVersionFS) State added in v0.1.0 

func (vfs *ObjectVersionFS) State() DigestMap

func (*ObjectVersionFS) User added in v0.1.0 

func (vfs *ObjectVersionFS) User() *User

type PathMap added in v0.0.23 

type PathMap map[string]string

PathMap maps filenames to digest strings.

func (PathMap) DigestMap added in v0.0.23 

func (pm PathMap) DigestMap() DigestMap

DigestMap returns a new DigestMap using the pathnames and digests in pm. The resulting DigestMap may be invalid if pm includes invalid paths or digests.

func (PathMap) DigestMapValid added in v0.0.23 

func (pm PathMap) DigestMapValid() (DigestMap, error)

DigestMap returns a new DigestMap using the pathnames and digests in pm. If the resulting DigestMap is invalid, an error is returned.

type RemapFunc 

type RemapFunc func(oldPaths []string) (newPaths []string)

RemapFunc is a function used to transform a DigestMap

func Remove 

func Remove(name string) RemapFunc

Remove returns a RemapFunc that removes name.

func Rename 

func Rename(from, to string) RemapFunc

Rename returns a RemapFunc that renames from to to.

type Root added in v0.1.0 

type Root struct {
	// contains filtered or unexported fields
}

Root represents an OCFL Storage Root.

func NewRoot added in v0.1.0 

func NewRoot(ctx context.Context, fsys FS, dir string, opts ...RootOption) (*Root, error)

NewRoot returns a new *Root for working with the OCFL storage root at directory dir in fsys. It can be used to initialize new storage roots if the InitRoot option is used, fsys is an ocfl.WriteFS, and dir is a non-existing or empty directory.

func (*Root) Description added in v0.1.0 

func (r *Root) Description() string

Description returns the description string from the storage roots `ocfl_layout.json` file, which may be empty.

func (*Root) FS added in v0.1.0 

func (r *Root) FS() FS

FS returns the Root's FS

func (*Root) Layout added in v0.1.0 

func (r *Root) Layout() extension.Layout

Layout returns the storage root's layout, which may be nil.ß

func (*Root) LayoutName added in v0.1.0 

func (r *Root) LayoutName() string

LayoutName returns the name of the root's layout extension or an empty string if the root has no layout.

func (*Root) NewObject added in v0.1.0 

func (r *Root) NewObject(ctx context.Context, id string, opts ...ObjectOption) (*Object, error)

NewObject returns an *Object for managing the OCFL object with the given ID in the root. If the object does not exist, the returned *Object can be used to create it. If the Root has not storage layout for resovling object IDs, the returned error is ErrLayoutUndefined.

func (*Root) NewObjectDir added in v0.3.0 

func (r *Root) NewObjectDir(ctx context.Context, dir string, opts ...ObjectOption) (*Object, error)

NewObjectDir returns an *Object for managing the OCFL object at path dir in root. If the object does not exist, the returned *Object can be used to create it.

func (*Root) ObjectDeclarations added in v0.6.0 

func (r *Root) ObjectDeclarations(ctx context.Context) (FileSeq, func() error)

ObjectDeclarations returns an iterator that yields all OCFL object declaration files in r. If an error occurs during iteration, it is returned by the error function.

func (*Root) Objects added in v0.1.0 

func (r *Root) Objects(ctx context.Context, opts ...ObjectOption) iter.Seq2[*Object, error]

Objects returns an iterator that yields objects or an error for every object declaration file in the root.

func (*Root) ObjectsBatch added in v0.6.0 

func (r *Root) ObjectsBatch(ctx context.Context, numgos int, opts ...ObjectOption) iter.Seq2[*Object, error]

ObjectsBatch returns an iterator that uses FileSeq.OpenObjectsBatch to open objects in the root in numgos separate goroutines, yielding the results

func (*Root) Path added in v0.1.0 

func (r *Root) Path() string

Path returns the root's dir relative to its FS

func (*Root) ResolveID added in v0.3.0 

func (r *Root) ResolveID(id string) (string, error)

ResolveID resolves the object id to a path relative to the root. If the root has no layout, the returned error is ErrLayoutUndefined.

func (*Root) Spec added in v0.1.0 

func (r *Root) Spec() Spec

Spec returns the root's OCFL specification number

func (*Root) ValidateObject added in v0.3.0 

func (r *Root) ValidateObject(ctx context.Context, id string, opts ...ObjectValidationOption) *ObjectValidation

ValidateObject validates the object with the given id. If the id cannot be resolved, the error is reported as a fatal error in the returned *ObjectValidation.

func (*Root) ValidateObjectDir added in v0.3.0 

func (r *Root) ValidateObjectDir(ctx context.Context, dir string, opts ...ObjectValidationOption) *ObjectValidation

ValidateObjectDir validates the object at a path relative to the root.

type RootOption added in v0.1.0 

type RootOption func(*Root)

RootOption is used to configure the behavior of NewRoot()

func InitRoot added in v0.1.0 

func InitRoot(spec Spec, layoutDesc string, extensions ...extension.Extension) RootOption

InitRoot returns a RootOption for initializing a new storage root as part of the call to NewRoot().

type Spec 

type Spec string

Spec represent an OCFL specification number

func (Spec) Cmp 

func (v1 Spec) Cmp(v2 Spec) int

Cmp compares Spec v1 to another v2. - If v1 is less than v2, returns -1. - If v1 is the same as v2, returns 0 - If v1 is greater than v2, returns 1 - any valid spec is greater than an invalid spec. - if both specs are invlid, Cmp panics.

func (Spec) Empty 

func (s Spec) Empty() bool

func (Spec) InventoryType added in v0.7.0 

func (s Spec) InventoryType() InventoryType

InventoryType returns n as an InventoryType

func (Spec) Valid added in v0.0.24 

func (s Spec) Valid() error

type Stage 

type Stage struct {
	// State is a DigestMap representing the new object version state.
	State DigestMap
	// DigestAlgorithm is the primary digest algorithm (sha512 or sha256) used by the stage
	// state.
	DigestAlgorithm digest.Algorithm
	// ContentSource is used to access new content needed to construct
	// an object. It may be nil
	ContentSource
	// FixitySource is used to access fixity information for new
	// content. It may be nil
	FixitySource
}

Stage is used to create/update objects.

func StageBytes added in v0.0.23 

func StageBytes(content map[string][]byte, alg digest.Algorithm, fixity ...digest.Algorithm) (*Stage, error)

StageBytes builds a stage from a map of filenames to file contents

func StageDir added in v0.0.23 

func StageDir(ctx context.Context, fsys FS, dir string, alg digest.Algorithm, fixity ...digest.Algorithm) (*Stage, error)

StageDir builds a stage based on the contents of the directory dir in FS. Files in dir and its subdirectories are digested with the given digest algorithms and added to the stage. Hidden files are ignored. The alg argument must be sha512 or sha256.

func (Stage) HasContent added in v0.0.23 

func (s Stage) HasContent(digest string) bool

HasContent returns true if the stage's content source provides an FS and path for the digest

func (*Stage) Overlay added in v0.0.23 

func (s *Stage) Overlay(stages ...*Stage) error

Overlay merges the state and content/fixity sources from all stages into s. All stages mush share the same digest algorithm.

type User 

type User struct {
	Name    string `json:"name"`
	Address string `json:"address,omitempty"`
}

User is a generic user information struct

type VNum 

type VNum struct {
	// contains filtered or unexported fields
}

VNum represents an OCFL object version number (e.g., "v1", "v02"). A VNum has a sequence number (1,2,3...) and a padding number, which defaults to zero. The padding is the maximum number of numeric digits the version number can include (a padding of 0 is no maximum). The padding value constrains the maximum valid sequence number.

func MustParseVNum 

func MustParseVNum(str string) VNum

MustParseVNum parses str as a VNUm and returns a new VNum. It panics if str cannot be parsed as a VNum.

func V 

func V(ns ...int) VNum

V returns a new Vnum. The first argument is a sequence number. An optional second argument can be used to set the padding. Additional arguments are ignored. Without any arguments, V() returns a zero value VNum.

func (VNum) First 

func (v VNum) First() bool

First returns true if v is a version 1.

func (VNum) IsZero 

func (v VNum) IsZero() bool

IsZero returns if v is the zero value

func (VNum) Lineage added in v0.1.0 

func (v VNum) Lineage() VNums

Lineage returns a VNums with v as the head.

func (VNum) MarshalText 

func (v VNum) MarshalText() ([]byte, error)

func (VNum) Next 

func (v VNum) Next() (VNum, error)

Next returns the next ocfl.VNum after v with the same padding. A non-nil error is returned if padding > 0 and next would overflow the padding

func (VNum) Num 

func (v VNum) Num() int

Num returns v's number as an int

func (VNum) Padding 

func (v VNum) Padding() int

Padding returns v's padding number.

func (VNum) Prev 

func (v VNum) Prev() (VNum, error)

Prev returns the previous version before v, with the same padding. An error is returned if v.Num() == 1

func (VNum) String 

func (v VNum) String() string

String returns string representation of v

func (*VNum) UnmarshalText 

func (v *VNum) UnmarshalText(text []byte) error

func (VNum) Valid 

func (v VNum) Valid() error

Valid returns an error if v is invalid

type VNums 

type VNums []VNum

VNums is a slice of VNum elements

func (VNums) Head 

func (vs VNums) Head() VNum

Head returns the last VNum in vs.

func (VNums) Len 

func (vs VNums) Len() int

Len implements sort.Interface on VNums

func (VNums) Less 

func (vs VNums) Less(i, j int) bool

Less implements sort.Interface on VNums

func (VNums) Padding 

func (vs VNums) Padding() int

Padding returns the padding for the VNums in vs

func (VNums) Swap 

func (vs VNums) Swap(i, j int)

Swap implements sort.Interface on VNums

func (VNums) Valid 

func (vs VNums) Valid() error

Valid returns a non-nill error if VNums is empty, is not a continuous sequence (1,2,3...), has inconsistent padding or padding overflow.

type Validation added in v0.1.0 

type Validation struct {
	// contains filtered or unexported fields
}

Validation represents multiple fatal errors and warning errors.

func (*Validation) Add added in v0.1.0 

func (v *Validation) Add(v2 *Validation)

Add adds all fatal errors and warnings from another validation to v.

func (*Validation) AddFatal added in v0.1.0 

func (v *Validation) AddFatal(errs ...error)

AddFatal adds fatal errors to the validation

func (*Validation) AddWarn added in v0.1.0 

func (v *Validation) AddWarn(errs ...error)

AddWarn adds warning errors to the validation

func (*Validation) Err added in v0.1.0 

func (v *Validation) Err() error

Err returns an error wrapping all the validation's fatal errors, or nil if there are no fatal errors.

func (*Validation) Errors added in v0.1.0 

func (v *Validation) Errors() []error

Errors returns a slice of all the fatal errors.q

func (*Validation) WarnErr added in v0.1.0 

func (v *Validation) WarnErr() error

WarnErr returns an error wrapping all the validation's warning errors, or nil if there are none.

func (*Validation) WarnErrors added in v0.1.0 

func (v *Validation) WarnErrors() []error

WarnErrors returns a slice of all the warning errors.

type ValidationError added in v0.1.0 

type ValidationError struct {
	validation.ValidationCode
	Err error
}

ValidationError is an error that includes a reference to a validation error code from the OCFL spec.

func (*ValidationError) Error added in v0.1.0 

func (ver *ValidationError) Error() string

func (*ValidationError) Unwrap added in v0.1.0 

func (ver *ValidationError) Unwrap() error

type WriteFS 

type WriteFS interface {
	FS
	Write(ctx context.Context, name string, buffer io.Reader) (int64, error)
	// Remove the file with path name
	Remove(ctx context.Context, name string) error
	// Remove the directory with path name and all its contents. If the path
	// does not exist, return nil.
	RemoveAll(ctx context.Context, name string) error
}

WriteFS is a storage backend that supports write and remove operations.

Source Files

View all Source files

Directories

Path Synopsis
backend
local
s3
s3/example/etag
s3/example/large-copy
s3/example/readir
s3/internal/mock
examples
commit
listobjects
validate
internal
ocfltest
pipeline
testutil
code

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.