added the first draft of the architectural description document

Documentation/Architectural Description for Pontarius XMPP.lyx

@@ -0,0 +1,800 @@
+#LyX 2.0 created this file. For more info see http://www.lyx.org/
+\lyxformat 413
+\begin_document
+\begin_header
+\textclass article
+\use_default_options true
+\maintain_unincluded_children false
+\language english
+\language_package default
+\inputencoding auto
+\fontencoding global
+\font_roman default
+\font_sans default
+\font_typewriter default
+\font_default_family default
+\use_non_tex_fonts false
+\font_sc false
+\font_osf false
+\font_sf_scale 100
+\font_tt_scale 100
+
+\graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
+\paperfontsize default
+\use_hyperref false
+\papersize default
+\use_geometry false
+\use_amsmath 1
+\use_esint 1
+\use_mhchem 1
+\use_mathdots 1
+\cite_engine basic
+\use_bibtopic false
+\use_indices false
+\paperorientation portrait
+\suppress_date false
+\use_refstyle 1
+\index Index
+\shortcut idx
+\color #008000
+\end_index
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\paragraph_indentation default
+\quotes_language english
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+\tracking_changes false
+\output_changes false
+\html_math_output 0
+\html_css_as_file 0
+\html_be_strict false
+\end_header
+
+\begin_body
+
+\begin_layout Title
+Architectural Description for Pontarius XMPP 0.1 (First Draft)
+\end_layout
+
+\begin_layout Author
+The Pontarius project
+\end_layout
+
+\begin_layout Date
+17th of August 2011
+\end_layout
+
+\begin_layout Standard
+\begin_inset CommandInset toc
+LatexCommand tableofcontents
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Introduction
+\end_layout
+
+\begin_layout Subsection
+Summary
+\end_layout
+
+\begin_layout Standard
+This is a first draft of an architectural description for Pontarius XMPP,
+ version 0.1.
+ It follows the IEEE 1471 recommended practice, and elaborates on the stakeholde
+rs and their concerns (Section 2) through viewpoint and view artifacts
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+A 
+\emph on
+viewpoint
+\emph default
+ is the language, including notations, models, and techniques, that is used
+ to describe a view.
+ A 
+\emph on
+view
+\emph default
+ is an artifact that, based on a viewpoint, addresses concerns of system
+ stakeholders.
+\end_layout
+
+\end_inset
+
+ (Section 3 and Section 4, respectively).
+ The Consistency section (Section 5) records architectural inconsistencies,
+ if any.
+ The Rationale section (Section 6) elaborates on reasons for the approaches
+ taken, as well as mentioning the alternatives considered.
+ We would greatly appreciate any feedback on our architectural decisions.
+\end_layout
+
+\begin_layout Subsection
+Change history
+\end_layout
+
+\begin_layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="3">
+<features tabularvalignment="middle">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="0">
+<column alignment="center" valignment="top" width="0">
+<row>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Version
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Date
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+Description
+\end_layout
+
+\end_inset
+</cell>
+</row>
+<row>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+First draft
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+08/13/2011
+\end_layout
+
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\begin_layout Plain Layout
+First draft
+\end_layout
+
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Subsection
+Context
+\end_layout
+
+\begin_layout Standard
+Pontarius XMPP is an XMPP library written in Haskell, for use with Haskell
+ applications.
+ The version targetted by this document, 0.1, is relatively lacking of features
+ compared to some other XMPP libraries as it is only implementing the XMPP
+ Core functionalities of XMPP.
+\end_layout
+
+\begin_layout Standard
+The Pontarius project is the only entity who has contributed to or expressed
+ an interest of Pontarius XMPP to date.
+ Thus, Pontarius XMPP is currently only influenced by the concerns of the
+ Pontarius project.
+ While the Pontarius project would like to see Pontarius XMPP become the
+ de-facto XMPP library for Haskell, their highest priority is to develop
+ an uncentralized media server on top of XMPP and XPMN.
+\end_layout
+
+\begin_layout Standard
+Implementing support for XMPP Core was a first step toward this end.
+ Developing the various extensions necessary for XPMN
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+These extensions include, but are not limited to, SASL EXTERNAL, Jingle,
+ and end-to-end encryption.
+\end_layout
+
+\end_inset
+
+ will be the second step---this is what will determine the requirements
+ of Pontarius XMPP 0.2.
+\end_layout
+
+\begin_layout Standard
+With this in mind, the 
+\emph on
+mission
+\emph default
+ of Pontarius XMPP 0.1 becomes to serve as a solid foundation for the extensions
+ planned for Pontarius XMPP 0.2, as well as to allow for the simple connection
+ and communication primitives usages that are possible within XMPP Core.
+ However, we will defer most extra features (features not wanted by the
+ Pontarius project) until further notice.
+\end_layout
+
+\begin_layout Standard
+Please consult the Software Requirements Specification for Pontarius XMPP
+ for more information about the Pontarius XMPP 0.1 features.
+\end_layout
+
+\begin_layout Subsection
+Glossary
+\end_layout
+
+\begin_layout Description
+FOSS Free and Open Source Software: See http://www.gnu.org/philosophy/free-sw.html
+ and http://www.opensource.org/osd.html
+\end_layout
+
+\begin_layout Description
+Pontarius Jon Kristensen's project to develop FOSS, uncentralized, and privacy-a
+ware software solutions; see http://www.pontarius.org/
+\end_layout
+
+\begin_layout Description
+XMPP Extendable Messaging and Presence Protocol: An uncentralized, open,
+ and near-real-time presence and messaging protocol; see http://www.xmpp.org/
+\end_layout
+
+\begin_layout Description
+XMPP
+\begin_inset space ~
+\end_inset
+
+Core An Internet standard that defines the core protocol methods of XMPP,
+ setup and teardown of XMPP streams, encryption, authentication, error handling,
+ and communication primitives; see RFC 6120
+\end_layout
+
+\begin_layout Description
+XPMN Extended Personal Media Network: An XMPP-based media network architecture
+ that allows media devices to utilize and expose media services in a flexible,
+ generic and user-friendly way; see http://www.xpmn.org/
+\end_layout
+
+\begin_layout Subsection
+References
+\end_layout
+
+\begin_layout Itemize
+Software Requirements Specification for Pontarius XMPP (the latest published
+ version can be found http://www.pontarius.org/)
+\end_layout
+
+\begin_layout Section
+Stakeholders and concerns
+\end_layout
+
+\begin_layout Subsection
+Acquirer, developers, and maintainers (the Pontarius project)
+\end_layout
+
+\begin_layout Standard
+The system is essentially 
+\begin_inset Quotes eld
+\end_inset
+
+acquired
+\begin_inset Quotes erd
+\end_inset
+
+, architected, developed, and maintained by the Pontarius project.
+ However, Pontarius XMPP being FOSS, you never know who might join in on
+ the effort.
+\end_layout
+
+\begin_layout Standard
+The plan to build an XPMN media server on top of Pontarius XMPP makes the
+ 
+\emph on
+extensibility
+\emph default
+ attribute of the system particularily important.
+\end_layout
+
+\begin_layout Standard
+Trying to make as much code as possible pure, clean, and 
+\emph on
+testable
+\emph default
+, we believe that Pontarius XMPP will be relatively 
+\emph on
+correct
+\emph default
+.
+\end_layout
+
+\begin_layout Standard
+The system is in the end stages of its alpha phase and is very likely to
+ be finished, so there are no significant risks to the acquirer.
+\end_layout
+
+\begin_layout Standard
+Note that the Pontarius project have not planned to actually develop an
+ application using Pontarius XMPP 0.1.
+\end_layout
+
+\begin_layout Subsection
+Users
+\end_layout
+
+\begin_layout Standard
+The users of Pontarius XMPP are third-party (Haskell) application developers
+ who utilizes the XMPP Core functionality.
+ We are not addressing all user concerns in this release, or the next; see
+ section 1.4 for more information.
+\end_layout
+
+\begin_layout Standard
+Like with the Pontarius project, users would appreciate a high level of
+ 
+\emph on
+extendability
+\emph default
+, allowing them to implement their own high-level protocols on top of XMPP
+ Core.
+ Of course, 
+\emph on
+correctness
+\emph default
+ is of great importance as well.
+\end_layout
+
+\begin_layout Standard
+One great strenght of Haskell is the level of 
+\emph on
+development efficiency
+\emph default
+ that can often be archieved; we want to utilize this in Pontarius XMPP.
+\end_layout
+
+\begin_layout Standard
+The client will also need to be 
+\emph on
+flexible
+\emph default
+ in that it can be concurrent.
+\end_layout
+
+\begin_layout Standard
+We will take the above concerns into consideration in the architecture of
+ Pontarius XMPP 0.1.
+ However, there are a number of attributes that, as mentioned above, will
+ be deferred until later versions, such as the needs for 
+\emph on
+interoperability
+\emph default
+ (against XMPP servers), 
+\emph on
+deployability
+\emph default
+, and 
+\emph on
+portability
+\emph default
+, all arising from the fact that Pontarius XMPP may be used in different
+ environments.
+\end_layout
+
+\begin_layout Section
+Viewpoints
+\end_layout
+
+\begin_layout Subsection
+Extendibility
+\end_layout
+
+\begin_layout Standard
+Both stakeholder groups is in a great need of extendibility, so this concern
+ is of utmost importance.
+ We have addressed the issue through a flexible event system, where applications
+ easily can insert hooks on certain standard events (streams opened, message
+ received, etc.), and also generate custom events themselves.
+ These custom events can contain any payload that the client wants, such
+ as for example a high-level payload with identities and features for a
+ service discovery response
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+Read more about the Service Discovery extension at http://xmpp.org/extensions/xep
+-0030.html.
+\end_layout
+
+\end_inset
+
+, enabling clients to define handlers for service discovery replies, without
+ even requiring that Pontarius XMPP is aware of the event type.
+\end_layout
+
+\begin_layout Standard
+The corresponding view (see the 4.1 section) will show the necessary features
+ and illustrate how the event system is covering the requirements.
+\end_layout
+
+\begin_layout Subsection
+Testability and correctness
+\end_layout
+
+\begin_layout Standard
+The pure and functional nature of Haskell allows for a fantastic isolation
+ between components, and increases the understandability and testability
+ of the code.
+ By making most of the code pure and utilizing testing tools like QuickCheck,
+ we can be unusually confident that the code is correct, compared to other
+ languages.
+\end_layout
+
+\begin_layout Standard
+That being said, Pontarius XMPP 0.1 in its current state has one huge and
+ impure function: the state loop function.
+ The loop carries and modifies a state, but also performs impure (IO) function
+ calls.
+ Being impure, we cannot conveniently write QuickCheck properties and perform
+ other testing for this function.
+ A simple approach to this problem is illustrated in Section 4.2.
+\end_layout
+
+\begin_layout Subsection
+Development efficiency
+\end_layout
+
+\begin_layout Standard
+Haskell's strong type system allows client developers to catch a great many
+ bugs that would be runtime errors in other programming languages at compile
+ time.
+ This does not only, as mentioned above, produce more correct code, but
+ it also saves the developer a lot of time.
+\end_layout
+
+\begin_layout Standard
+Section 4.3 describes how we plan to use monads transformers to further increase
+ the development efficiency for Pontarius XMPP users.
+\end_layout
+
+\begin_layout Subsection
+Flexibility: Concurrency
+\end_layout
+
+\begin_layout Standard
+Client applications needs to be able to access the library from multiple
+ threads.
+ Section 4.4 will illustrate the concurrency model of Pontarius XMPP.
+\end_layout
+
+\begin_layout Section
+Views
+\end_layout
+
+\begin_layout Subsection
+Extendibility: The event system
+\end_layout
+
+\begin_layout Standard
+The event system needs to support the following features in regards to these
+ extensible event types.
+ 
+\begin_inset Quotes eld
+\end_inset
+
+Any function
+\begin_inset Quotes erd
+\end_inset
+
+ below means any function with access to the XMPP session.
+ A hook is a function that is registered with Pontarius XMPP to receive
+ a certain event.
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+Hooks can only register for exactly one event.
+ If developers want one function to handle multiple events, they will have
+ to insert multiple hooks which 
+\begin_inset Quotes eld
+\end_inset
+
+overloads
+\begin_inset Quotes erd
+\end_inset
+
+ the real hook function (perhaps using in-line Lambda functions).
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Enumerate
+Defining arbitrary (non-hierarchical) events with any payload
+\end_layout
+
+\begin_layout Enumerate
+Injection of such event, where Pontarius XMPP will forward received event
+ (without understanding it) using the registered hooks
+\end_layout
+
+\begin_layout Enumerate
+Allowing functions to register hooks for any such event type, similar to
+ how they would register a regular event
+\end_layout
+
+\begin_layout Enumerate
+Returning, upon registration, a hook ID that may or may not be stored by
+ the client
+\end_layout
+
+\begin_layout Enumerate
+Allowing any function to unregister a hook using its hook ID
+\end_layout
+
+\begin_layout Enumerate
+Allowing any function that is hooked to Pontarius XMPP to unregister itself
+ (without knowing its hook ID)
+\end_layout
+
+\begin_layout Enumerate
+Processing hook modifications (registration and unregistration) must happen
+ immediately, so that hooks are not missing events, or receiving events
+ that they should not process
+\end_layout
+
+\begin_layout Standard
+Haskell's type system is static, and it's not completely straight-forward
+ to implement dynamic types like these.
+ Our suggested solution is using an existential type---a Haskell type class---th
+at can wrap these custom events into a generic type, which we can use to
+ distinguish one hook type from another, so that we can divide them into
+ groups.
+ We have decided to go with 
+\family typewriter
+Data.Dynamic
+\family default
+ and 
+\family typewriter
+Data.Typeable
+\family default
+ of the Haskell base package.
+\end_layout
+
+\begin_layout Standard
+The dynamic event is called DynamicEvent, and it contains its Typeable payload
+ and nothing more.
+ Hence, you only need to make your payload an instance of Typeable.
+\end_layout
+
+\begin_layout Standard
+Injecting the event can be done through 
+\family typewriter
+raiseDynamicEvent :: Typeable a => a -> XMPPT m ()
+\family default
+.
+ This function will generate a 
+\family typewriter
+DynamicEvent
+\family default
+ value wrapping the 
+\family typewriter
+Typeable
+\family default
+, and call all functions registered with the 
+\family typewriter
+TypeRep
+\family default
+ (type representation) of the 
+\family typewriter
+Typeable
+\family default
+.
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+It seems that GHC versions prior to 7.2 does not provide an 
+\family typewriter
+Ord
+\family default
+ instance for 
+\family typewriter
+TypeRep
+\family default
+, so in order for us to be able to use the 
+\family typewriter
+TypeRep
+\family default
+ as keys in maps and be compatible with older versions of GHC, we will probably
+ have to provide one ourselves.
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Registering a hook for a 
+\family typewriter
+DynamicEvent
+\family default
+ type would mean calling something like 
+\family typewriter
+registerDynamicEventHook :: Typeable a => a -> XMPPT m HookID
+\family default
+.
+ Unregistering is analogous.
+\end_layout
+
+\begin_layout Standard
+To make sure that processing happens prior to any other events, a special
+ 
+\family typewriter
+Chan
+\family default
+ can be used, which is always processed prior to the regular internal events
+ of Pontarius XMPP.
+\end_layout
+
+\begin_layout Subsection
+Testability and correctness: The state loop
+\end_layout
+
+\begin_layout Standard
+Instead of mixing the pure state-machine-related code and logic with the
+ impure (IO) actions, we are using a function like 
+\family typewriter
+State -> Event -> (State, [ImpureAction])
+\family default
+ that, given a state and event
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+Note that this event type is internal to the library and has nothing to
+ do with the event system mentioned in Section 4.1.
+\end_layout
+
+\end_inset
+
+, updates the state and returns a list of impure actions to be performed
+ separately.
+\end_layout
+
+\begin_layout Standard
+As a side note, one thing that could possibly be investigated and used is
+ the functional reactive programming paradigm.
+ However, that would most likely require a completely different approach
+ toward reading and modifying the state, and a lot of time spent.
+\end_layout
+
+\begin_layout Subsection
+Development efficiency: Monads
+\end_layout
+
+\begin_layout Standard
+The main efficiency feature of Pontarius XMPP is the use of monad transformers.
+ Pontarius XMPP defines 
+\family typewriter
+XMPPT
+\family default
+, which contains the necessary information to interact with Pontarius XMPP
+ (such as some 
+\family typewriter
+Chan
+\family default
+s) from a convenient and flexible context.
+\end_layout
+
+\begin_layout Standard
+Being a monad transformer, 
+\family typewriter
+XMPPT
+\family default
+ can be stacked on top of an arbitrary amount of 
+\family typewriter
+MonadIO
+\family default
+ monad transformers to provide extra functionality.
+ One thing that this allows client developers to do is to use the 
+\family typewriter
+StateT
+\family default
+ monad transformer below 
+\family typewriter
+XMPPT
+\family default
+ to perform stateful operations in the 
+\family typewriter
+XMPPT
+\family default
+ context.
+ One example of a use of this would be to always have the client state carried
+ around, and getting it as easily as 
+\family typewriter
+do clientState <- lift $ get
+\family default
+.
+\end_layout
+
+\begin_layout Subsection
+Flexibility: Concurrency
+\end_layout
+
+\begin_layout Standard
+The usage of monads in Pontarius XMPP has one notable limitation---it necessaril
+y means one calculation, and one thread.
+ Imagine that you want to perform an XMPP action from a different thread.
+ Perhaps you want to update your presence every 30 seconds, or you want
+ to send a message on some database event? The Pontarius XMPP architecture
+ offer a backdoor for this through its event system; developers can use
+ 
+\family typewriter
+dynamicEventInjector :: Typeable a => XMPPT m (a -> IO ())
+\family default
+ to acquire this function.
+ After that, the receiving hooks can perform the actual XMPP actions in
+ the 
+\begin_inset Quotes eld
+\end_inset
+
+main thread
+\begin_inset Quotes erd
+\end_inset
+
+ based on the event payload.
+\end_layout
+
+\begin_layout Section
+Consistency
+\end_layout
+
+\begin_layout Standard
+There are no known inconsistencies in this document.
+\end_layout
+
+\begin_layout Section
+Rationale
+\end_layout
+
+\begin_layout Standard
+There are no known alternative approaches for the architecture.
+\end_layout
+
+\end_body
+\end_document