#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 \begin_inset Text \begin_layout Plain Layout Version \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Date \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Description \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout First draft \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 08/13/2011 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout First draft \end_layout \end_inset \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