diff --git a/Documentation/Architectural Description for Pontarius XMPP.lyx b/Documentation/Architectural Description for Pontarius XMPP.lyx new file mode 100644 index 0000000..a9501f9 --- /dev/null +++ b/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 + + + + + + + +\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