From 861422d1143c095629b5dd8b38b77ae086380abe Mon Sep 17 00:00:00 2001 From: fro_ozen Date: Wed, 16 Dec 2015 01:59:00 +0100 Subject: [PATCH 1/3] Add the first draft of the proposal --- doc/proposal-2015-12-15.md | 41 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 doc/proposal-2015-12-15.md diff --git a/doc/proposal-2015-12-15.md b/doc/proposal-2015-12-15.md new file mode 100644 index 0000000..ee99a03 --- /dev/null +++ b/doc/proposal-2015-12-15.md @@ -0,0 +1,41 @@ +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 -> (Word8 -> 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. + +Note that the concept of channels already exists at this level but there are no +usefull abstractions for it. + +### 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 `Channel` +carrying a sum type for each connected peer. This will represent the +`Control channel` from the ricochet spec and give them full control over the +interaction with their contacts. + +This may also be used as the base of a even higher level callback based API. + +> TODO: Further discuss how OpenChannel requests should be handled From 14c4d1c1a06d47b291cb11eeb86727f46331e23d Mon Sep 17 00:00:00 2001 From: fro_ozen Date: Wed, 16 Dec 2015 13:38:51 +0100 Subject: [PATCH 2/3] Update according to todays discussion --- doc/proposal-2015-12-15.md | 32 +++++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/doc/proposal-2015-12-15.md b/doc/proposal-2015-12-15.md index ee99a03..a380817 100644 --- a/doc/proposal-2015-12-15.md +++ b/doc/proposal-2015-12-15.md @@ -12,7 +12,7 @@ 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 -> (Word8 -> IO ()) -> IO () +runRicochet :: RSAKeyPair -> Map Word8 (Socket -> IO ()) -> IO () ``` ### Second Level: Packet Parsing @@ -21,8 +21,11 @@ The second level will implement the parsing of generic ricochet packets from version agnostic, but also seems like something that will stay the same in future versions. -Note that the concept of channels already exists at this level but there are no -usefull abstractions for it. +It will expose something like this: +```haskell +createPacketChan :: Socket -> IO (Chan Packet) +selectChannel :: Chan Packet -> Chan Packet +``` ### Third Level: Ricochet Primitives This level will implement the primitives introduced by ricochet version 1, @@ -31,11 +34,22 @@ 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 `Channel` -carrying a sum type for each connected peer. This will represent the -`Control channel` from the ricochet spec and give them full control over the -interaction with their contacts. +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.Channel. 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) -This may also be used as the base of a even higher level callback based API. +instance Functor (Chan s) -> TODO: Further discuss how OpenChannel requests should be handled +transform :: Chan s a -> (a -> Maybe b) -> 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) +``` From eb8232173f87383f650d11fed7ff996d305c90e3 Mon Sep 17 00:00:00 2001 From: fro_ozen Date: Wed, 16 Dec 2015 21:26:02 +0100 Subject: [PATCH 3/3] Make some more changes to the proposal --- doc/proposal-2015-12-15.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/proposal-2015-12-15.md b/doc/proposal-2015-12-15.md index a380817..e114588 100644 --- a/doc/proposal-2015-12-15.md +++ b/doc/proposal-2015-12-15.md @@ -23,8 +23,8 @@ future versions. It will expose something like this: ```haskell -createPacketChan :: Socket -> IO (Chan Packet) -selectChannel :: Chan Packet -> Chan Packet +createPacketChan :: Socket -> IO (Chan Packet Packet) +selectChannel :: Word16 -> Prism' Packet Packet ``` ### Third Level: Ricochet Primitives @@ -40,7 +40,7 @@ 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.Channel. It will allow filtering, mapping and merging with +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 @@ -49,7 +49,7 @@ data Chan s a = MkChan (Channel s) (s -> Maybe a) instance Functor (Chan s) -transform :: Chan s a -> (a -> Maybe b) -> Chan s b +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) ```