Skip to content

A peer-to-peer stack for code collaboration

Add RFC for Machine Backend Interface

Thomas Scholtes06e85303c9e8
diff --git a/rfcs/0001-machine-backend-interface.rst b/rfcs/0001-machine-backend-interface.rst
new file mode 100644
index 0000000..fba9f1f
--- /dev/null
+++ b/rfcs/0001-machine-backend-interface.rst
@@ -0,0 +1,72 @@
+Machine Backend Interface Definition
+====================================
+
+.. date:: 2018-12-11
+.. reviewers::
+
+ @jkarni
+ @jameshaydon
+
+Synopsis
+--------
+
+We propose an interface for backends that control Radicle State
+Machines. This interface replaces the ``StorageBackend`` interface
+defined in ``Radicle.Internal.Storage``. It’s design is motivated by
+the requirements of implementing the interface for IPFS.
+
+Proposal
+--------
+
+The current backend interface is described in
+``Radicle.Internal.Storage`` with the following code
+
+.. code-block:: haskell
+
+ data StorageBackend m = StorageBackend
+ { storageSend :: Text -> Seq Value -> m (Either Text ())
+ -- ^ First argument is the chain ID, second argument is the
+ -- values to send.
+ , storageReceive :: Text -> Int -> m (Either Text [Value])
+ -- ^ First argument is the chain ID, second argument is the
+ -- index. Only the expression in the chain with an index greater
+ -- then the given index are returned.
+ }
+
+To implement the IPFS backend this interface requires an update.
+
+.. code-block:: haskell
+
+ newtype MachineId = MachineId Text
+
+ data MachineBackend index m = MachineBackend
+ { machineType :: Text
+ , machineUpdate :: MachineId -> [Value] -> m (Either Text index)
+ , machineGetLog :: MachineId -> Maybe index -> m (Either Text (index, [Value])
+ , machineCreate :: m (Either Text MachineId)
+ }
+
+We now describe the changes in detail.
+
+First, we replace the term “chain” with “machine” and update the field
+and type names. We introduce a newtype for the machine ID.
+
+The ``machineType`` field is an identifier describing the backend. For
+the centralised server that hosts and evaluates machines this will be
+``host-eval``, for IPFS this will be ``ipfs``.
+
+We make the index a type parameter. Every entry in the machine log will
+have an index. For the centralised server the index becomes ``Natural``
+and determines the position in the log. For IPFS the index will be the
+content hash of the entry. To use the backend we require ``ToRad`` and
+``FromRad`` instances for the index.
+
+For the ``machineGetLog`` method the index parameter is now optional.
+``machineGetLog m Nothing`` will get the whole chain.
+
+The behavior of ``machineGetLog`` is changed if an index is provided.
+The function will return all the log entries that follow the given
+index, excluding the entry with the given index.
+
+``machineGetLog`` will also return the index of the last entry in the
+return value.