diff --git a/doc/proposal-2015-12-15.md b/doc/proposal-2015-12-15.md new file mode 100644 index 0000000..e114588 --- /dev/null +++ b/doc/proposal-2015-12-15.md @@ -0,0 +1,55 @@ +Proposal proposed the 15th December of 2015 +=========================================== +We decided it would make sense to split the API into multiple levels, each +getting more and more abstract, but targeting progressively more specific parts +of the ricochet spec. + +### First Level: Version Negotiation +The lowest level of the API will be the ricochet version negotiation. This is +the only part of the spec that definetly won't change in future versions and can +therefore doesn't target any specific version of the ricochet spec. + +The most abstract part of the API on this level will probably look something +like this: +```haskell +runRicochet :: RSAKeyPair -> Map Word8 (Socket -> IO ()) -> IO () +``` + +### Second Level: Packet Parsing +The second level will implement the parsing of generic ricochet packets from +`ByteString`s. This was specified in protocol version 1 and is therefore not +version agnostic, but also seems like something that will stay the same in +future versions. + +It will expose something like this: +```haskell +createPacketChan :: Socket -> IO (Chan Packet Packet) +selectChannel :: Word16 -> Prism' Packet Packet +``` + +### Third Level: Ricochet Primitives +This level will implement the primitives introduced by ricochet version 1, +namely the authentication process for `im.ricochet.auth.hidden-service` and the +protobuf parsing of the specified structures. + +### Fourth Level: High Level API +This level will be what most users of this library will interact with. It's an +high level interface to the ricochet protocol. The user will get a `Chan` +carrying the `Packet` type for every connected peer. They will be able to apply +prisms to it and filter / parse specific events that way. + +### Additional Feature: Custom Chan Type +As seen throughout this document, we provide our own variant of +Control.Concurrent.Chan. It will allow filtering, mapping and merging with +ease, which is needed for the fourth API level. They'll be implemented like +this: +```haskell +-- s is the source type +data Chan s a = MkChan (Channel s) (s -> Maybe a) + +instance Functor (Chan s) + +transform :: (a -> Maybe b) -> Chan s a -> Chan s b +-- The source Channel has to be identical for this to work properly +merge :: Chan s a -> Chan s b -> Chan s (Either a b) +```