ocfl

README

OCFL

Experimental OCFL client and library for interacting with OCFL content from an operational perspective.

Quickstart

Download or Build the ocfl cli application

You can create an OCFL root by using mkroot with a desired directory to create. Create one, and cd into it

ocfl mkroot ~/myRoot

cd ~/myRoot

Copy some content into an OCFL object. For example, recursively copy the contents of the /usr directory into an OCFL object named test:stuff

ocfl cp -r /usr test:stuff

List logical files and their physical paths in that object

ocfl ls -p -t file test:stuff

Copy some more stuff into the object (creating another version)

ocfl cp /etc/hosts test:stuff

Feel free to explore the files on the file system (e.g. the inventory) to see what it created, or explore the cli documentation for more things to do

Documentation

The OCFL client has built in help pages accessible by

ocfl help

.. or for a specific subcommand

ocfl help cp

For more in-depth examples see the cli documentation

Download

Pre-compiled binaries are present in the releases section. It's possible to download and extract the binaries to your PATH as follows:

For Mac OS:

$ base=https://github.com/birkland/ocfl/releases/download/v0.1.0 &&
  curl -L $base/ocfl-$(uname -s)-$(uname -m) >/usr/local/bin/ocfl &&
  chmod +x /usr/local/bin/ocfl

For Linux:

$ base=https://github.com/birkland/ocfl/releases/download/v0.1.0 &&
  curl -L $base/ocfl-$(uname -s)-$(uname -m) >/tmp/ocfl &&
  sudo install /tmp/ocfl /usr/local/bin/ocfl

For Windows, using Git Bash:

$ base=https://github.com/birkland/ocfl/releases/download/v0.1.0 &&
  mkdir -p "$HOME/bin" &&
  curl -L $base/ocfl-Windows-x86_64.exe > "$HOME/bin/ocfl.exe" &&
  chmod +x "$HOME/bin/ocfl.exe"

Build

Make sure you have Go 1.11+ installed

If you develop inside ${GOPATH} and/or have ${GOPATH}/bin in your path, you can simply do

go get github.com/birkland/ocfl/cmd/ocfl

Otherwise, clone the repository somewhere (not within ${GOPATH}), and cd into it

git clone https://github.com/birkland/ocfl.git

If ${GOPATH}/bin is in your PATH, then you can just do the following

go install ./...

Otherwise, to produce an ocfl executable in the build dir

go build ./...

Drivers

Planned drivers to explore

• file. OCFL in a regular filesystem
• index. OCFL metadata in a database for quick retrieval.
• s3. OCFL in Amazon S3

Http server

Not started yet. So if we have an index that allows fast lookup, an http server providing an API access to OCFL structure or content in a performant way. Experiments include:

• Dumb. Just read/write reflection of what's on the filesystem. Probably doesn't help us much.
• LDP. Use LDP containers strictly for listing stuff, which allows us to leverage that performant index and allows us to group things logically. e.g. http://example.org/ocfl/${object}/v3/path/to/file.txt
• Memento. Maybe a better way to expose versions, and expose current revisions as the "normal case"? e.g. from http://example.org/ocfl/${object}/path/to/file.txt memento explains there are three revisions of that file (say in v1, v2, and v4); from http://example.org/ocfl/${object} discover all revisions, etc.

Is there a natural way to expose OCFL as some subset of the Fedora API, or at least borrowing from it where it makes sense, or building on some of the specs it cites? Then we also expose checksums via Want-Digest, for example.

Documentation

Overview

Package ocfl defines an API for interacting with content in an OCFL repository.

Access to OCFL content is provided by one of more Driver implementations. Drivers may interact with a local filesystem, s3, a relational database for quick/indexed lookup, etc. See individual driver documentation under drivers/ for more information.

Index

• Constants
• type CommitInfo
• type Driver
• type EntityRef
  • func (e EntityRef) Coords() []string
• type Opener
• type Options
• type Select
• type Session
• type Type
  • func ParseType(name string) Type
  • func (t Type) String() string
• type Walker

Constants

const (
	NEW  = "new"
	HEAD = ""
)

OCFL version name constants, used in configuring ocfl.Options

Types

type CommitInfo

type CommitInfo struct {
	Name    string // User name
	Address string // Some sort of identifier - e-mail, URL, etc
	Message string // Freeform text
	Date    time.Time
}

CommitInfo defines informative text to be included when committing an OCFL version

type Driver

type Driver interface {
	Walker
	Opener
}

Driver provides basic OCFL access via some backend

type EntityRef

type EntityRef struct {
	ID     string     // The logical ID of the entity (string, uri, or relative file path)
	Addr   string     // Physical address of the entity (absolute file path or URI)
	Parent *EntityRef // Parent of next highest type that isn't an intermediate node (e.g. object parent is root)
	Type   Type       // Type of entity
}

EntityRef represents a single OCFL entity.

func (EntityRef) Coords

func (e EntityRef) Coords() []string

Coords returns a slice of the logical coordinates of an entity ref, of the form {objectID, versionID, logicalFilePath}

type Opener

type Opener interface {
	Open(id string, opts Options) (Session, error) // Open an OCFL object
}

Opener opens an OCFL object session, potentially allowing reading and writing to it.

type Options

type Options struct {
	Create  bool   // If true, this will create a new object if one does not exist.
	Version string // Desired version, default (zero value) ocfl.HEAD
}

Options for establishing a read/write session on an OCFL object.

A given session is scoped to a single version of an OCFL object. That version may be one that already exists, or a uncommitted version. Constants ocfl.NEW and ocfl.HEAD are intended to be used with the Version field in order to specify the head version regardless of name, or an auto-named new version. Otherwise, provide the name of an existing version to access its contents.

type Select

type Select struct {
	Type Type // Desired OCFL type
	Head bool // True if desired files or versions must be in the head revision
}

Select indicates desired properties of matching OCFL entities

type Session

type Session interface {
	Put(lpath string, r io.Reader) error // Put file content at the given logical path
	Delete(lpath string) error
	// TODO: Move(src, dest string) error
	// TODO: Read(lpath string) (io.Reader, error)
	Commit(CommitInfo) error
}

Session allows reading or writing to the an OCFL object.

Each session is bound to a single OCFL object version; either a pre-existing version, or an uncommitted new version. New versions contain the content of the previous version as a starting point. Drivers may or may not allow writes/commits to existing versions.

type Type

type Type int

Type names a kind of OCFL entity

const (
	Any Type = iota
	File
	Version
	Object
	Intermediate
	Root
)

OCFL entity type constants, ordered by specificity, e.g. Root > Object

func ParseType

func ParseType(name string) Type

ParseType creates an OCFL type constant from the given string, e.g. ocfl.From("Object") == ocfl.Object

func (Type) String

func (t Type) String() string

String representation of an OCFL type constant

type Walker

type Walker interface {
	Walk(desired Select, cb func(EntityRef) error, loc ...string) error
}

Walker crawls through a bounded scope of OCFL entities "underneath" a start location. Given a location and a desired type, Walker will invoke the provided callback any time an entity of the desired type is encountered.

The walk location may either be a single physical address (such as a file path or URI), or it may be a sequence of logical OCFL identifiers, such as {objectID, versionID, logicalFilePath} When providing logical identifiers, object IDs may be provided on their own, version IDs must be preceded by an object ID, and logical file paths must be preceded by the version ID.

If no location is given, the scope of the walk is implied to be the entirety of content under an OCFL root.