From e7b661976e1b83e23874e5165710ec320bc78b0e Mon Sep 17 00:00:00 2001 From: Jon Kristensen Date: Sun, 25 Mar 2012 13:40:06 +0200 Subject: [PATCH] name, nejla and license change updates --- ...ectural Description for Pontarius XMPP.lyx | 800 ------------------ .../{Pontarius XMPP Manual.lyx => Manual.lyx} | 44 +- ...> Software Requirements Specification.lyx} | 129 +-- Examples/EchoClient.hs | 32 +- Network/XMPP.hs | 29 +- Network/XMPP/Address.hs | 4 +- Network/XMPP/SASL.hs | 4 +- Network/XMPP/Session.hs | 4 +- Network/XMPP/SessionOld.hs | 18 +- Network/XMPP/Stanza.hs | 4 +- Network/XMPP/Stream.hs | 4 +- Network/XMPP/TLS.hs | 4 +- Network/XMPP/Types.hs | 4 +- Network/XMPP/Utilities.hs | 4 +- README | 6 +- pontarius-xmpp.cabal | 66 -- pontarius.cabal | 67 ++ 17 files changed, 187 insertions(+), 1036 deletions(-) delete mode 100644 Documentation/Architectural Description for Pontarius XMPP.lyx rename Documentation/{Pontarius XMPP Manual.lyx => Manual.lyx} (91%) rename Documentation/{Software Requirements Specification for Pontarius XMPP.lyx => Software Requirements Specification.lyx} (88%) delete mode 100644 pontarius-xmpp.cabal create mode 100644 pontarius.cabal diff --git a/Documentation/Architectural Description for Pontarius XMPP.lyx b/Documentation/Architectural Description for Pontarius XMPP.lyx deleted file mode 100644 index a9501f9..0000000 --- a/Documentation/Architectural Description for Pontarius XMPP.lyx +++ /dev/null @@ -1,800 +0,0 @@ -#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 diff --git a/Documentation/Pontarius XMPP Manual.lyx b/Documentation/Manual.lyx similarity index 91% rename from Documentation/Pontarius XMPP Manual.lyx rename to Documentation/Manual.lyx index 82aa13d..92cf935 100644 --- a/Documentation/Pontarius XMPP Manual.lyx +++ b/Documentation/Manual.lyx @@ -61,15 +61,15 @@ \begin_body \begin_layout Title -Pontarius XMPP 0.1 Manual (Fourth Draft) +Pontarius 1.0 Manual (Fifth Draft) \end_layout \begin_layout Author -The Pontarius Project +Nejla \end_layout \begin_layout Date -The 27th of July, 2011 +March 25, 2012 \end_layout \begin_layout Standard @@ -86,8 +86,9 @@ Introduction \end_layout \begin_layout Standard -Pontarius XMPP 0.1 is a minimal XMPP client implementation with all the required - client features and behaviours of the RFC 6120 ("XMPP Core") specification +Pontarius is a work in progress of a minimal XMPP client implementation + with all the required client features and behaviours of the RFC 6120 ("XMPP + Core") specification \begin_inset Foot status open @@ -98,14 +99,14 @@ http://tools.ietf.org/html/rfc6120 \end_inset . - Pontarius XMPP has been developed by the Pontarius project (mainly by Jon - Kristensen). + Pontarius has been developed by the Pontarius project (mainly by Jon Kristensen +), and has now been taken over by Nejla. \series bold \series default -Being licensed under a three-clause BSD license, Pontarius XMPP is free - and open source software. +Being licensed under the Apache License (Version 2), Pontarius is free and + open source software. \end_layout \begin_layout Section @@ -113,7 +114,7 @@ Features and Implementation Specifics \end_layout \begin_layout Standard -Pontarius XMPP 0.1 implements the XMPP Core specification (RFC 6120). +Pontarius 1.0 will implement the XMPP Core specification (RFC 6120). Features include the following: \end_layout @@ -189,14 +190,8 @@ Future Development \end_layout \begin_layout Standard -The current goal for Pontarius XMPP 0.2 is to implement the Extended Personal - Media Network (XPMN) architecture so that the Pontarius project can develop - a media server and some other XPMN services on top of Pontarius XMPP. - However, if we get approached by people wanting to use Pontarius XMPP for - other things, we might decide to help them out by implement some other - features first. - Please let us know if you are looking for a Haskell XMPP library and Pontarius - XMPP lacks some features that you want. +The current goal for Pontarius XMPP 2.0 is to serve as a library for an XMPP + server. \end_layout \begin_layout Section @@ -204,9 +199,16 @@ Usage \end_layout \begin_layout Standard -Working with Pontarius XMPP is mostly done asynchronously; Pontarius XMPP - ``owns'' the XMPP thread, and calls different StateT s m a callback functions - in the client. + +\noun on +Note that the information provided below is out-of-date. + It will be updated before the next release. +\end_layout + +\begin_layout Standard +Working with Pontarius is mostly done asynchronously; Pontarius XMPP ``owns'' + the XMPP thread, and calls different StateT s m a callback functions in + the client. StateT is a monad transformer which allows the functions to be stateful (being able to access and modify the arbitrary client-defined state of type s) and to be executed on top of a MonadIO m monad (typically IO). diff --git a/Documentation/Software Requirements Specification for Pontarius XMPP.lyx b/Documentation/Software Requirements Specification.lyx similarity index 88% rename from Documentation/Software Requirements Specification for Pontarius XMPP.lyx rename to Documentation/Software Requirements Specification.lyx index d096dff..03687c7 100644 --- a/Documentation/Software Requirements Specification for Pontarius XMPP.lyx +++ b/Documentation/Software Requirements Specification.lyx @@ -61,15 +61,15 @@ \begin_body \begin_layout Title -Software Requirements Specification for Pontarius XMPP 0.1 (Third Draft) +Pontarius 1.0 Software Requirements Specification (Fourth Draft) \end_layout \begin_layout Author -The Pontarius Project +Nejla \end_layout \begin_layout Date -27th of July 2011 +March 25, 2012 \end_layout \begin_layout Standard @@ -90,21 +90,12 @@ Purpose \end_layout \begin_layout Standard -The goal of this document is to clarify---for Pontarius -\begin_inset Foot -status open - -\begin_layout Plain Layout -For more information about the Pontarius project, see http://www.pontarius.org/. -\end_layout - -\end_inset - - developers, the XMPP community, and to some extent the Haskell community---what - we are implementing. - We hope that it will help us in the Pontarius project to keep track of - functionality and requirements, provide a basis for scheduling, and help - us with our validation and verification processes. +The goal of this document is to clarify---for Pontarius developers, the + XMPP community, and to some extent the Haskell community---what we are + implementing. + We hope that it will help us to keep track of functionality and requirements, + provide a basis for scheduling, and help us with our validation and verificatio +n processes. \end_layout \begin_layout Subsection @@ -112,46 +103,22 @@ Scope \end_layout \begin_layout Standard -Pontarius XMPP 0.1 will implement the client capabilities of RFC 6120: XMPP: - Core and the depending specifications, such as RFC 6122: XMPP: Address - Format, RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2, - RFC 4422: Simple Authentication and Security Layer (SASL), RFC 5280: Internet - X.509 Public Key Infrastructure Certificate and Certificate Revocation List - (CRL) Profile, and Extensible Markup Language (XML) 1.0, among others. +Pontarius 1.0 will implement the client capabilities of RFC 6120: XMPP: Core + and the depending specifications, such as RFC 6122: XMPP: Address Format, + RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2, RFC 4422: + Simple Authentication and Security Layer (SASL), RFC 5280: Internet X.509 + Public Key Infrastructure Certificate and Certificate Revocation List (CRL) + Profile, and Extensible Markup Language (XML) 1.0, among others. \end_layout \begin_layout Standard Support for common extensions such as Instant Messaging, Data Forms, Service - Discovery, etc. + Discovery, server components, XMPP server capabilities, etc. will \emph on not \emph default - be included in the 0.1 version, but will be added in later ( -\begin_inset Quotes eld -\end_inset - -0.x -\begin_inset Quotes erd -\end_inset - -) versions. - Server components and XMPP server capabilities could also be added later. -\end_layout - -\begin_layout Standard -While it is the goal of the Pontarius project to develop secure and privacy-awar -e -\begin_inset Quotes eld -\end_inset - -personal cloud -\begin_inset Quotes erd -\end_inset - - solutions on top of Pontarius XMPP, we want Pontarius XMPP to be a general-purp -ose---and the de facto---XMPP library for Haskell. - It should be correct and efficient to work in. + be included in the 1.0 version. \end_layout \begin_layout Standard @@ -160,27 +127,6 @@ We will not repeat the specifics of the requirements from the RFC 6120: unless we see any special reason to. \end_layout -\begin_layout Subsection -Legal notice -\end_layout - -\begin_layout Standard -Pontarius XMPP is a free and open source software project. - -\begin_inset Quotes eld -\end_inset - -The Pontarius project -\begin_inset Quotes erd -\end_inset - - is not a legal entity, but is like a synonym for Jon Kristensen. - Jon Kristensen does DOES NOT TAKE ANY RESPONSIBILITY OR OFFER ANY GUARANTEES - in regards to the software, its requirements or this document. - Furthermore, the software is provided WITHOUT ANY WARRANTY; without even - the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -\end_layout - \begin_layout Subsection Definitions, acronyms, and abbrevations \end_layout @@ -195,7 +141,7 @@ d, uncentralized, and privacy-aware software solutions \end_layout \begin_layout Description -PX01 Pontarius XMPP 0.1 +P1 Pontarius 1.0 \end_layout \begin_layout Description @@ -237,7 +183,7 @@ Overview \begin_layout Standard The second section provides an overall description of the requirements of - PX01, going through the features in a non-strict fashion, talking shortly + P1, going through the features in a non-strict fashion, talking shortly about the product functions, as well as some constraints and assumptions. \end_layout @@ -256,36 +202,36 @@ Product perspective \end_layout \begin_layout Standard -PX01 will be used by XMPP clients to manage presence and messaging in a - uncentralized near-real-time environments. +P1 will be used by XMPP clients to manage presence and messaging in a uncentrali +zed near-real-time environments. For this first milestone of the library, we have chosen to implement only the XMPP: Core specification, and only the client capabilities of it. The reason for this is that we want to get the library out quickly, and want to have the core functionality of the library particularly well tested. - The X in XMPP stands for extendable, and Pontarius XMPP must be flexible - in regards for extensions, such as RFCs and XEPs; we might end up implementing + The X in XMPP stands for extendable, and Pontarius must be flexible in + regards for extensions, such as RFCs and XEPs; we might end up implementing hundreds of them. This is one of the most important quality attribute of the software. \end_layout \begin_layout Standard -PX01 is designed to be used with Haskell. +P1 is designed to be used with Haskell. \end_layout \begin_layout Standard -PX01 must work on GNU/Linux, the main Free Software operating system. +P1 must work on GNU/Linux, the main Free Software operating system. However, due to the platform support and high-level nature of Haskell, running it on other common operating systems is likely to work as well. \end_layout \begin_layout Standard -PX01 must work with (at least) the (estimated) most popular free and open +P1 must work with (at least) the (estimated) most popular free and open source software XMPP server that works with the specifics of our implementation (such as SCRAM). \end_layout \begin_layout Standard -PX01 depends on the below (free and open source software) Haskell packages. +P1 depends on the below (free and open source software) Haskell packages. I have omitted specification number [...]. I have also omitted the source, as they are all available on Hackage. \end_layout @@ -899,8 +845,8 @@ N/A \end_layout \begin_layout Standard -Every PX01 client will open up at most one TCP port on the system. - PX01 in itself does not write anything to the file system storage of the +Every P1 client will open up at most one TCP port on the system. + P1 in itself does not write anything to the file system storage of the operating system, with the exception of the optional logging facility, disabled by default, which may be configured to write to disk. \end_layout @@ -912,14 +858,14 @@ at least \emph default Transport Layer Security to help protect clients using the library from attacks. - PX01 will not provide any spam protection. + P1 will not provide any spam protection. \end_layout \begin_layout Standard As we expect a very limited amount of concurrent XMPP clients, and a (relatively ) limited actitivity over XMPP streams--even when they are being fully active--w e are not specifying any detailed memory or (process) performance requirements - for PX01. + for P1. However, we will stress test the library. \end_layout @@ -932,7 +878,7 @@ Product functions \end_layout \begin_layout Standard -PX01 implements XMPP: Core and allow clients to do roughly the following: +P1 implements XMPP: Core and allow clients to do roughly the following: Open a TCP connection to a server, exchange XML information with the server to configure the (XML) stream, handle stream errors and encoding issues, have the connection secured by TLS, authenticate using a SASL mechanism @@ -953,7 +899,7 @@ User characteristics \end_layout \begin_layout Standard -We expect developers using PX01 to understand the XMPP: Core specification +We expect developers using P1 to understand the XMPP: Core specification (and its depending specifications), Haskell, and monads, including the StateT monad transformer. \end_layout @@ -975,7 +921,7 @@ Assumptions and dependencies \begin_layout Standard We assume that the Glasgow Haskell Compiler (GHC) is available on the system - where PX01 applications are built. + where P1 applications are built. \end_layout \begin_layout Section @@ -1193,13 +1139,12 @@ There is only one XMPP client per instance of the system. \end_layout \begin_layout Description -REQ-24 Regular desktop computers should be able to run hundreds of Pontarius - XMPP 0.1 clients. +REQ-24 Regular desktop computers should be able to run hundreds of P1 clients. \end_layout \begin_layout Description -REQ-25 Pontarius XMPP 0.1 should support virtually as many stanzas per second - as (non-throttled) XMPP servers are able to route. +REQ-25 P1 should support virtually as many stanzas per second as (non-throttled) + XMPP servers are able to route. This goes for both lightweight, heavy and mixed stanzas. \end_layout diff --git a/Examples/EchoClient.hs b/Examples/EchoClient.hs index 966dd49..25ac327 100644 --- a/Examples/EchoClient.hs +++ b/Examples/EchoClient.hs @@ -1,10 +1,10 @@ {- -Copyright © 2010-2011 Jon Kristensen. +Copyright © 2010-2012 Jon Kristensen. -This file (EchoClient.hs) illustrates how to connect, authenticate, set a -presence, and echo messages with Pontarius XMPP. The contents of this file may -be used freely, as if it is in the public domain. +This file (EchoClient.hs) illustrates how to connect, authenticate, +set a presence, and echo messages using Pontarius. The contents of +this file may be used freely, as if it is in the public domain. -} @@ -16,17 +16,17 @@ import Network.XMPP -- Account and server details. -hostName = "jonkristensen.com" +hostName = "nejla.com" userName = "pontarius" -serverIdentifier = "jonkristensen.com" +serverIdentifier = "nejla.com" portNumber = 5222 resource = "pontarius" password = "" --- The main function initializes Pontarius XMPP and specifies the (XMPPT) --- actions the be executed, hooking the client into the appropriate events and --- tries to connect. +-- The main function initializes PontariusP and specifies the (XMPPT) +-- actions the be executed, hooking the client into the appropriate +-- events and tries to connect. main :: IO () @@ -38,16 +38,16 @@ main = runXMPPT $ do where - -- When successfully connected, send a simple presence, and unhook - -- ourselves from further "connected" events. + -- When successfully connected, send a simple presence, and + -- unhook ourselves from further "connected" events. onConnectedEvent (Right r) = do liftIO $ putStrLn $ "Connected with resource: " ++ (show r) presence simplePresence return False - -- When the connection fails, print the error and shut down the XMPP - -- session. + -- When the connection fails, print the error and shut down + -- the XMPP session. onConnectedEvent (Left e) = do liftIO $ putStrLn $ "Could not connect due to the following error:" ++ (show e) @@ -55,7 +55,8 @@ main = runXMPPT $ do return True -- Predicate that makes sure that the messages processed by - -- onMessageEvent are sent from and to full (not bare) XMPP addresses. + -- onMessageEvent are sent from and to full (not bare) XMPP + -- addresses. onMessageEventPredicate = Just (\ m -> return $ and [isJust $ messageFrom m, isJust $ messageTo m]) @@ -66,7 +67,8 @@ main = runXMPPT $ do , messageTo = fromJust $ messageFrom m } return True - -- When disconnected, print the reason and shut down the XMPP session. + -- When disconnected, print the reason and shut down the XMPP + -- session. onDisconnectedEvent r = do liftIO $ putStrLn $ "Disconnected with the reason: " ++ (show r) diff --git a/Network/XMPP.hs b/Network/XMPP.hs index 9e81293..52ea548 100644 --- a/Network/XMPP.hs +++ b/Network/XMPP.hs @@ -1,28 +1,29 @@ --- Copyright © 2010-2011 Jon Kristensen. See the LICENSE file in the Pontarius --- XMPP distribution for more details. +-- Copyright © 2010-2012 Jon Kristensen. See the LICENSE file in the +-- Pontarius distribution for more details. -- | -- Module: $Header$ --- Description: Pontarius XMPP API --- Copyright: Copyright © 2010-2011 Jon Kristensen --- License: BSD3 +-- Description: Pontarius API +-- Copyright: Copyright © 2010-2012 Jon Kristensen +-- License: Apache License 2.0 -- --- Maintainer: info@pontarius.org +-- Maintainer: jon.kristensen@nejla.com -- Stability: unstable -- Portability: portable -- --- XMPP is an open standard, extendable, and secure communications protocol --- designed on top of XML, TLS, and SASL. Pontarius XMPP is an XMPP client --- library, implementing the core capabilities of XMPP (RFC 6120). +-- XMPP is an open standard, extendable, and secure communications +-- protocol designed on top of XML, TLS, and SASL. Pontarius XMPP is +-- an XMPP client library, implementing the core capabilities of XMPP +-- (RFC 6120). -- --- Developers using this library are assumed to understand how XMPP works. +-- Developers using this library are assumed to understand how XMPP +-- works. -- -- This module will be documented soon. -- --- Note that we are not recommending anyone to use Pontarius XMPP at this time --- as it's still in an experimental stage and will have its API and data types --- modified frequently. See the project's web site at --- for more information. +-- Note that we are not recommending anyone to use Pontarius XMPP at +-- this time as it's still in an experimental stage and will have its +-- API and data types modified frequently. module Network.XMPP ( -- Network.XMPP.JID Address (..) diff --git a/Network/XMPP/Address.hs b/Network/XMPP/Address.hs index fafd812..1657171 100644 --- a/Network/XMPP/Address.hs +++ b/Network/XMPP/Address.hs @@ -1,5 +1,5 @@ --- Copyright © 2010-2011 Jon Kristensen. See the LICENSE file in the Pontarius --- XMPP distribution for more details. +-- Copyright © 2010-2012 Jon Kristensen. See the LICENSE file in the +-- Pontarius distribution for more details. {-# OPTIONS_HADDOCK hide #-} diff --git a/Network/XMPP/SASL.hs b/Network/XMPP/SASL.hs index 71c1fe3..4cf7419 100644 --- a/Network/XMPP/SASL.hs +++ b/Network/XMPP/SASL.hs @@ -1,5 +1,5 @@ --- Copyright © 2010-2011 Jon Kristensen. See the LICENSE file in the Pontarius --- XMPP distribution for more details. +-- Copyright © 2010-2012 Jon Kristensen. See the LICENSE file in the +-- Pontarius distribution for more details. {-# OPTIONS_HADDOCK hide #-} diff --git a/Network/XMPP/Session.hs b/Network/XMPP/Session.hs index 98617b9..d785d4d 100644 --- a/Network/XMPP/Session.hs +++ b/Network/XMPP/Session.hs @@ -1,5 +1,5 @@ --- Copyright © 2010-2011 Jon Kristensen. See the LICENSE file in the Pontarius --- XMPP distribution for more details. +-- Copyright © 2010-2012 Jon Kristensen. See the LICENSE file in the +-- Pontarius distribution for more details. -- TODO: Predicates on callbacks? diff --git a/Network/XMPP/SessionOld.hs b/Network/XMPP/SessionOld.hs index 19d2d9d..185fbf8 100644 --- a/Network/XMPP/SessionOld.hs +++ b/Network/XMPP/SessionOld.hs @@ -1,5 +1,5 @@ --- Copyright © 2010-2011 Jon Kristensen. See the LICENSE file in the Pontarius --- XMPP distribution for more details. +-- Copyright © 2010-2012 Jon Kristensen. See the LICENSE file in the +-- Pontarius distribution for more details. -- I believe we need to use the MultiParamTypeClasses extension to be able to -- work with arbitrary client states (solving the problem that the ClientState @@ -12,8 +12,8 @@ -- This module provides the functions used by XMPP clients to manage their XMPP -- sessions. -- --- Working with Pontarius XMPP is mostly done asynchronously with callbacks; --- Pontarius XMPP "owns" the XMPP thread and carries the client state with it. A +-- Working with Pontarius is mostly done asynchronously with callbacks; +-- Pontarius "owns" the XMPP thread and carries the client state with it. A -- client consists of a list of client handlers to handle XMPP events. This is -- all set up through a @Session@ object, which a client can create by calling -- the (blocking) function @createSession@. @@ -21,7 +21,7 @@ -- The Pontarius XMPP functions operate in an arbitrary MonadIO monad. -- Typically, clients will use the IO monad. -- --- For more information, see the Pontarius XMPP Manual. +-- For more information, see the Pontarius manual. -- TODO: Better functions and events for stanzas, IncomingIQ, OutgoingIQ, etc. (ClientSession, ClientStanza) @@ -108,8 +108,8 @@ import System.Random (randomIO) -- ============================================================================= --- | The @Session@ object is used by clients when interacting with Pontarius --- XMPP. It holds information needed by Pontarius XMPP; its content is not +-- | The @Session@ object is used by clients when interacting with Pontarius. +-- It holds information needed by Pontarius XMPP; its content is not -- accessible from the client. data Session s m = Session { sessionChannel :: Chan (InternalEvent s m) @@ -117,7 +117,7 @@ data Session s m = Session { sessionChannel :: Chan (InternalEvent s m) -- | A client typically needs one or more @ClientHandler@ objects to interact --- with Pontarius XMPP. Each client handler may provide four callback +-- with Pontarius. Each client handler may provide four callback -- functions; the first three callbacks deals with received stanzas, and the -- last one is used when the session is terminated. -- @@ -260,7 +260,7 @@ openStreams s h p c = CMS.get >>= -- server. -- -- The third parameter is an optional custom validation function for the server --- certificates. Note that Pontarius XMPP will perform its own validation +-- certificates. Note that Pontarius will perform its own validation -- according to the RFC 6120, including comparing the domain name specified in -- the certificate against the connected server, as well as checking the -- integrity, and the certificate authorities. diff --git a/Network/XMPP/Stanza.hs b/Network/XMPP/Stanza.hs index 935fef0..a9589e2 100644 --- a/Network/XMPP/Stanza.hs +++ b/Network/XMPP/Stanza.hs @@ -1,5 +1,5 @@ --- Copyright © 2010-2011 Jon Kristensen. See the LICENSE file in the Pontarius --- XMPP distribution for more details. +-- Copyright © 2010-2012 Jon Kristensen. See the LICENSE file in the +-- Pontarius distribution for more details. {-# OPTIONS_HADDOCK hide #-} diff --git a/Network/XMPP/Stream.hs b/Network/XMPP/Stream.hs index 15cd082..759d29b 100644 --- a/Network/XMPP/Stream.hs +++ b/Network/XMPP/Stream.hs @@ -1,5 +1,5 @@ --- Copyright © 2010-2011 Jon Kristensen. See the LICENSE file in the Pontarius --- XMPP distribution for more details. +-- Copyright © 2010-2012 Jon Kristensen. See the LICENSE file in the +-- Pontarius distribution for more details. {-# OPTIONS_HADDOCK hide #-} diff --git a/Network/XMPP/TLS.hs b/Network/XMPP/TLS.hs index d70a4cf..a0ac88b 100644 --- a/Network/XMPP/TLS.hs +++ b/Network/XMPP/TLS.hs @@ -1,5 +1,5 @@ --- Copyright © 2010-2011 Jon Kristensen. See the LICENSE file in the Pontarius --- XMPP distribution for more details. +-- Copyright © 2010-2012 Jon Kristensen. See the LICENSE file in the +-- Pontarius distribution for more details. -- TODO: TLS12 when supported in tls; TODO: TLS11 results in a read error - bug? -- TODO: cipher_AES128_SHA1 = TLS_RSA_WITH_AES_128_CBC_SHA? diff --git a/Network/XMPP/Types.hs b/Network/XMPP/Types.hs index d69553e..9db049c 100644 --- a/Network/XMPP/Types.hs +++ b/Network/XMPP/Types.hs @@ -1,5 +1,5 @@ --- Copyright © 2010-2011 Jon Kristensen. See the LICENSE file in the Pontarius --- XMPP distribution for more details. +-- Copyright © 2010-2012 Jon Kristensen. See the LICENSE file in the +-- Pontarius distribution for more details. {-# OPTIONS_HADDOCK hide #-} diff --git a/Network/XMPP/Utilities.hs b/Network/XMPP/Utilities.hs index 3112f5b..2f9fb37 100644 --- a/Network/XMPP/Utilities.hs +++ b/Network/XMPP/Utilities.hs @@ -1,5 +1,5 @@ --- Copyright © 2010-2011 Jon Kristensen. See the LICENSE file in the Pontarius --- XMPP distribution for more details. +-- Copyright © 2010-2012 Jon Kristensen. See the LICENSE file in the +-- Pontarius distribution for more details. -- This module currently converts XML elements to strings. diff --git a/README b/README index 3565c90..cb81938 100644 --- a/README +++ b/README @@ -1,5 +1,5 @@ -Pontarius XMPP is a work in progress to build a Haskell XMPP library -that implements the client capabilities of RFC 6120 ("XMPP Core"). We -are currently working on cleaning up the code, the final architectural +Pontarius is a work in progress to build a Haskell XMPP library that +implements the client capabilities of RFC 6120 ("XMPP Core"). We are +currently working on cleaning up the code, the final architectural details and towards feature-completeness to be able to move the project into beta. diff --git a/pontarius-xmpp.cabal b/pontarius-xmpp.cabal deleted file mode 100644 index 639203a..0000000 --- a/pontarius-xmpp.cabal +++ /dev/null @@ -1,66 +0,0 @@ -Name: pontarius-xmpp -Version: 0.0.8.0 -Cabal-Version: >= 1.6 -Build-Type: Simple -License: BSD3 -License-File: LICENSE -Copyright: Copyright © 2011, Jon Kristensen -Author: Jon Kristensen, Mahdi Abdinejadi -Maintainer: jon.kristensen@pontarius.org -Stability: alpha -Homepage: http://www.pontarius.org/ -Bug-Reports: mailto:info@pontarius.org --- Package-URL: -Synopsis: A prototyped and incomplete implementation of RFC 6120: - XMPP: Core -Description: A work in progress of an implementation of RFC 6120: XMPP: - Core, as well as RFC 6122: XMPP: Address Format and other - depending standards. A new version of Pontarius XMPP is - released every three weeks. -Category: Network -Tested-With: GHC ==7.0.2 --- Data-Files: --- Data-Dir: --- Extra-Source-Files: --- Extra-Tmp-Files: - -Library - Exposed: True - Build-Depends: base >= 2 && < 5, parsec, enumerator, crypto-api ==0.6.3, - base64-string, pureMD5, utf8-string, network, xml-types, - text, transformers, bytestring, cereal ==0.3.3.0, random, - xml-enumerator, tls, tls-extra, containers, mtl, text-icu, - stringprep, asn1-data, cryptohash ==0.7.0, - time, certificate, ranges, uuid - -- Other-Modules: - -- HS-Source-Dirs: - -- Extensions: - -- Build-Tools: - -- Buildable: - -- GHC-Options: - -- GHC-Prof-Options: - -- Hugs-Options: - -- NHC98-Options: - -- Includes: - -- Install-Includes: - -- Include-Dirs: - -- C-Sources: - -- Extra-Libraries: - -- Extra-Lib-Dirs: - -- CC-Options: - -- LD-Options: - -- Pkgconfig-Depends: - -- Frameworks: - -Source-Repository head - Type: darcs - -- Module: - Location: git://github.com/pontarius/pontarius-xmpp.git - -- Subdir: - -Source-Repository this - Type: darcs - -- Module: - Location: git://github.com/pontarius/pontarius-xmpp.git - Tag: 0.0.8.0 - -- Subdir: \ No newline at end of file diff --git a/pontarius.cabal b/pontarius.cabal new file mode 100644 index 0000000..580973b --- /dev/null +++ b/pontarius.cabal @@ -0,0 +1,67 @@ +Name: pontarius +Version: 0.0.7.0 +Cabal-Version: >= 1.6 +Build-Type: Simple +-- License: +License-File: LICENSE +Copyright: Copyright © 2010-2012, Jon Kristensen +Author: Jon Kristensen, Mahdi Abdinejadi +Maintainer: jon.kristensen@nejla.com +Stability: alpha +-- Homepage: +Bug-Reports: mailto:jon.kristensen@nejla.com +-- Package-URL: +Synopsis: A prototyped and incomplete implementation of RFC 6120: + XMPP: Core +Description: A work in progress of an implementation of RFC 6120: + XMPP: Core, as well as RFC 6122: XMPP: Address Format and + other depending standards. A new version of Pontarius + XMPP is released every three weeks. +Category: Network +Tested-With: GHC ==7.0.2 +-- Data-Files: +-- Data-Dir: +-- Extra-Source-Files: +-- Extra-Tmp-Files: + +Library + Exposed: True + Build-Depends: base >= 2 && < 5, parsec, enumerator, + crypto-api ==0.6.3, base64-string, pureMD5, + utf8-string, network, xml-types, text, transformers, + bytestring, cereal ==0.3.3.0, random, xml-enumerator, + tls, tls-extra, containers, mtl, text-icu, + stringprep, asn1-data, cryptohash ==0.7.0, time, + certificate, ranges, uuid + -- Other-Modules: + -- HS-Source-Dirs: + -- Extensions: + -- Build-Tools: + -- Buildable: + -- GHC-Options: + -- GHC-Prof-Options: + -- Hugs-Options: + -- NHC98-Options: + -- Includes: + -- Install-Includes: + -- Include-Dirs: + -- C-Sources: + -- Extra-Libraries: + -- Extra-Lib-Dirs: + -- CC-Options: + -- LD-Options: + -- Pkgconfig-Depends: + -- Frameworks: + +Source-Repository head + Type: git + -- Module: + Location: git://github.com/nejla/pontarius.git + -- Subdir: + +-- Source-Repository this +-- Type: git +-- -- Module: +-- Location: git://github.com/nejla/pontarius.git +-- Tag: 0.0.7.0 +-- -- Subdir: \ No newline at end of file