pontarius-xmpp/Documentation/Architectural Description for Pontarius XMPP.lyx

#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