gocfl

GOCFL - Go OCFL Library

gocfl is a high-performance Go library for the Oxford Common Filesystem Layout (OCFL). It focuses on the creation, update, validation, and extraction of OCFL Storage Roots and Objects, with a strong emphasis on extensibility, I/O efficiency, and technical metadata indexing.

Note: This repository contains the gocfl library. For the command-line interface, please refer to the gocfl-cli repository.

For additional extensions, please refer to the gocfl-extensions repository.

Features

• OCFL Support: Full support for OCFL v1.0 and v1.1, with experimental support for v2.0.
• Storage Backends:
  • Local Filesystem
  • S3 Cloud Storage (via MinIO Client SDK)
  • Serialization into ZIP Containers (with optional AES Encryption)
• High Performance:
  • Optimized I/O: Files are read and written as few times as possible.
  • Concurrent checksum generation and processing.
• Extensibility: Implements a flexible extension hook system (7 different hooks) for both Storage Root and Object extensions.
• Advanced Capabilities:
  • Technical metadata extraction and indexing.
  • File format migration.
  • Thumbnail generation.
  • METS/PREMIS generation.

Installation

go get github.com/ocfl-archive/gocfl/v3

Basic Usage

The library provides convenient functions in the ocfl package for common tasks.

Initializing and Loading a Storage Root

import (
    "context"
    "github.com/ocfl-archive/gocfl/v3/pkg/ocfl"
    "github.com/ocfl-archive/gocfl/v3/pkg/ocfl/version"
    "github.com/ocfl-archive/gocfl/v3/pkg/ocfllogger"
    "github.com/je4/utils/v2/pkg/checksum"
)

ctx := context.Background()
logger := ocfllogger.NewNopLogger()

// Initialize a new storage root (needs an appendfs.FS)
sr, err := ocfl.InitStorageRoot(ctx, fsys, nil, version.Version1_1, checksum.DigestSHA512, nil, logger)

// Load an existing storage root (needs an fs.FS)
sr, err := ocfl.LoadStorageRoot(ctx, fsys, nil, nil, logger)
if err != nil {
    // handle error
}
// sr should be closed if it implements io.Closer
if closer, ok := sr.(io.Closer); ok {
    defer closer.Close()
}

Working with Objects

// Load an object from a filesystem
obj, err := ocfl.LoadObject(ctx, objFsys, nil, logger)
if err != nil {
    // handle error
}
// obj should be closed if it implements io.Closer
if closer, ok := obj.(io.Closer); ok {
    defer closer.Close()
}

// Add files to an object
writer, err := obj.StartUpdate("initial commit", "user", "user@example.com", false)
if err != nil {
    // handle error
}
defer writer.Close()
err = writer.AddFolder(sourceFS, true, "")
err = writer.Close()

Validation and Extraction

import (
    "github.com/ocfl-archive/gocfl/v3/pkg/ocfl"
    "github.com/ocfl-archive/gocfl/v3/pkg/ocfl/inventory"
)

// Validate an object
err := ocfl.ValidateObject(ctx, objFsys, logger)

// Extract an object
err := ocfl.Extract(ctx, objectFS, destFS, "object_path", inventory.NewVersionNumber(), true, "", logger)

Examples

The examples directory contains runnable Go programs for common tasks:

• Storage Root Initialization: How to initialize a new OCFL Storage Root.
• Object Creation: Creating and initializing a new OCFL Object.
• Adding and Updating Content: Adding files and creating new versions.
• Object Validation: Validating an existing OCFL Object.
• Extracting Objects: Extracting object content to a filesystem.

Documentation

• Quickstart Guide - Start here for a quick overview and code examples.
• Documentation Overview - Links to detailed component documentation.
• Package Overview
• OCFL Factory Documentation

License

GOCFL is licensed under the Apache License, Version 2.0. See LICENSE for details.