This is a Common Lisp implementation of the Encoding for Robust Immutable
Storage specification (https://purl.org/eris). It implements the version 1.0 of
the specification.

The code is licensed under the LGPLv3 or any later version, unless specified
otherwise in a file.

Depends on Alexandria, Serapeum, Ironclad (version 0.58+), function-cache,
trivial-gray-streams, bordeaux-threads, and fiveam for testing. In addition, on
POSIX systems the mmap and osicat libraries are used for the parallel decoder.


The public API is exported by the ERIS package.

There are the following functions for converting to and from ERIS
representations to eris-cl objects:

read-capability-to-urn
urn-to-read-capability
octets-to-read-capability
read-capability-to-octets
reference-to-block-urn
block-urn-to-reference


The eris-encode (INPUT BLOCK-SIZE OUTPUT-FUNCTION &KEY SECRET HASH-OUTPUT)
function can be used to encode a vector or a stream into an ERIS
read-capability.

The eris-decode (READ-CAPABILITY FETCH-FUNCTION &KEY (CACHE-CAPACITY 2048))
function can be used to decode an ERIS read-capability. It returns a stream of
the class ERIS-DECODE-STREAM: this class implements the Gray streams protocol.

In addition, on POSIX systems, eris-decode-parallel (READ-CAPABILITY
FETCH-FUNCTION OUTPUT-FILE &KEY (CACHE-CAPACITY 4096) (THREADS 4)
(INITIAL-BINDINGS *DEFAULT-SPECIAL-BINDINGS*)) function is available. This
function will attempt to decode an ERIS read-capability in parallel into a file
specified by the OUTPUT-FILE string or pathspec.

See the docstrings of the specific functions for more details. However, you
should only use these to write custom backends; otherwise, see below..



A high-level API is provided for convenience in backend.lisp. The concept is
that a backend object is created, which holds information like output-function,
fetch-function, caching details, block-size, etc. and the {en/de}coding
functions simply take the backend as an argument.

This interface consists of two generic functions: store-data, for encoding data,
and fetch-read-capability, for retrieving the contents of a read-capability
object.

As an example, a file-based backend called file-backend is provided. It can be
used simply by making an instance of the 'file-backend class with a :directory
argument, which will point to the directory in which ERIS data is to be stored.

There is also hash-backend, which implements a simple hash-table backend. It is
primarily meant for testing, not actual usage.

The API contains the following symbols:

fetch-data (READ-CAPABILITY BACKEND &key)
store-data (INPUT BACKEND &key)

Classes:

encoding-backend
decoding-backend

An instance of file-backend can be instanced using (make-instance 'file-backend
:directory "my/dir/with/eris/chunks/").

For further information, see the docstrings.