scatter.scala

package com.codecommit.scatter

import scodec._

import scalaz._
import scalaz.stream._

trait Server[Key, Value] {
  import Server._

  val commuter: Commuter[Value]
  val commuterCodec: Codec[Commuter[Value]]

  /**
   * Atomic read of the local store.  Since all key/value pairs must be persistent in server state,
   * this gives users the ability to avoid building a redundant map for the very common random access
   * use case.  Bear in mind that the value corresponding to any given key is unstable.
   */
  def get(key: Key): OptionT[Task, Value]

  /**
   * Recall that Codec represents a partial conversion (i.e. it is entirely legitimate for a codec
   * to _attempt_ the conversion of a value and write a failure code which is then read back as
   * None).  For this reason, Codec[Value => Value] is not a nonsense type.  Note though that it is
   * impossible to derive Ord[A] or even Equal[A] given Codec[A], which is somewhat counter-intuitive.
   *
   * Transformers should be very cheap, and should not close over a particularly large amount of
   * data.  It goes without saying that a transformer should _never_ perform IO.  They need not be
   * idempotent.
   *
   * Due to the reordering of transformers, intermediate results _are_ observable via the output
   * of the exchange.  It is even possible to observe intermediate results which do not exist and
   * will not exist on any other node.  Users are responsible for dealing with this situation
   * appropriately.
   */
  def exchange(implicit CK: Codec[Key], CV: Codec[Value], CF: Codec[Transformer[Value]]): Exchange[(Key, Transformer[Value]), (Key, Value)]
}

object Server {

  type Transformer[Value] = Option[Value] => Option[Value]

  /**
   * Must obey the following property:
   *
   * F, G transformers
   * C commuter
   * (F', G') = C(F, G)
   * ------------------
   * F ° G' = G ° F'
   *
   * Intuitively, this is the means by which certain non-commutative functions may be enriched with
   * commutativity.  For functions which are already mutually commutative (e.g. F = G = (+)), a valid
   * commuter would be the identity function.
   */
  type Commuter[Value] = (Transformer[Value], Transformer[Value]) => (Transformer[Value], Transformer[Value])
}