discoverygarden/flysystem_ocfl

v1.1.0 2023-11-10 13:49 UTC

Requires

• ext-json: *
• drupal/flysystem: ^2

GPL-3.0-or-later

README

A Flysystem adapter implementation allowing access to within OCFL storage structures.

Presently, targeting read-only access to binaries in FCRepo 6 flavored storage, especially via the lens of Islandora which concerns primarily the storage of binaries.

Execution Overview

OCFL storage is extensible at multiple levels:

• the layout proper, how objects are placed within the storage root, supporting:
  • Flat Direct Storage
  • Hashed Truncated N-tuple Trees with Encapsulating Directories
  • Hashed Truncated N-tuple Trees
  • Flat Omit Prefix Storage
  • N-tuple Omit Prefix Storage
• the structure of objects themselves
  • Mutable HEAD

The exact use of the OCFL storage is still up to the application proper, which may have different suggestions as to how objects should be structured, such as:

• Fedora OCFL Object Structure; and,
  • Fedora Header Files

To support these multiple points of extensibility, we have defined:

• for layouts: the OCFLPlugin plugin type, with base implementations of those presently defined extensions.
  • We expect the layout to be specified in the ocfl_layout.json file in the root of the OCFL storage.
    • Strictly, per the OCFL spec, this file is optional; however, having it present greatly simplifies the loading of the layout plugin.
• for object structures: Event evaluation based on the flysystem_ocfl.inventory_location event
  • This allows the "Mutable HEAD" extension to inject its bit of indirection, but allows falling back to the base location of an inventory.json sitting in the objects' root directory.
• for identifying target resources within objects: Event evaluation based on the flysystem_ocfl.resource_location event.
  • This allows the targeting of resources in the object, especially in the Fedora Commons 6 instance of which Islandora makes extensive use, where the object is based off of a singular "binary" resource, where fetching the object in certain instances (such as ours) is best interpreted as acquiring the byte-stream of the file.

Usage

This should offer a similar parallel to the fedora driver shipped with islandora/islandora, which might be configured via your Drupal site's settings.php with something like:

{
  "fedora": {
    "driver": "fedora",
    "config": {
      "root": "http://localhost:8080/fcrepo/rest/"
    }
  }
}

To instead read directly from the OCFL storage layout, with something like:

{
  "fedora": {
    "driver": "ocfl",
    "config": {
      "root": "/opt/fcrepo/fcrepo/data/ocfl-root",
      "id_prefix": "info:fedora/"
    }
  }
}

Hypothetically, this could even be chained with another Flysystem implementation such as S3, such as:

{
  "your-desired-scheme": {
    "driver": "s3",
    "config": {
      "bucket": "your-ocfl-root-bucket",
    }
  },
  "fedora": {
    "driver": "ocfl",
    "config": {
      "root": "your-desired-scheme://ocfl-root",
      "id_prefix": "info:fedora/"
    }
  }
}

NOTE: An additional prefix within the bucket (ocfl-root in the example above, but could be anything) is presently necessary, due to naive path normalization in Flysystem.

Configuration

See the Flysystem module documentation for more in-depth context on Flysystem adapter configuration.

There are presently two points of configuration for the ocfl driver:

Key	Description	Default
root	The base path targetting the OCFL root storage.	N/A (required)
id_prefix	Prefix to add to incoming IDs.	the empty string

Known Issues

Not strictly an issue with this module, but may rise relating to the use of non-public filesystems in Drupal: https://www.drupal.org/project/drupal/issues/2786735

Future Thoughts

• allow for fragments to be passed via Flysystem URIs, to be interpreted as different resources within a container object
  • no present use-case for this

Troubleshooting/Issues

Having problems or solved a problem? Contact discoverygarden.

Sponsors

• University of Limerick

Maintainers

Current maintainers:

• discoverygarden

License

GPLv3