view README @ 2144:1d3f73e065e1

core, jp: component handling + client handling refactoring: - SàT can now handle components - plugin have now a "modes" key in PLUGIN_INFO where they declare if they can be used with clients and or components. They default to be client only. - components are really similar to clients, but with some changes in behaviour: * component has "entry point", which is a special plugin with a componentStart method, which is called just after component is connected * trigger end with a different suffixes (e.g. profileConnected vs profileConnectedComponent), so a plugin which manage both clients and components can have different workflow * for clients, only triggers of plugins handling client mode are launched * for components, only triggers of plugins needed in dependencies are launched. They all must handle component mode. * component have a sendHistory attribute (False by default) which can be set to True to allow saving sent messages into history * for convenience, "client" is still used in method even if it can now be a component * a new "component" boolean attribute tells if we have a component or a client * components have to add themselve Message protocol * roster and presence protocols are not added for components * component default port is 5347 (which is Prosody's default port) - asyncCreateProfile has been renamed for profileCreate, both to follow new naming convention and to prepare the transition to fully asynchronous bridge - createProfile has a new "component" attribute. When used to create a component, it must be set to a component entry point - jp: added --component argument to profile/create - disconnect bridge method is now asynchronous, this way frontends can know when disconnection is finished - new PI_* constants for PLUGIN_INFO values (not used everywhere yet) - client/component connection workflow has been moved to their classes instead of being a host methods - host.messageSend is now client.sendMessage, and former client.sendMessage is now client.sendMessageData. - identities are now handled in client.identities list, so it can be updated dynamically by plugins (in the future, frontends should be able to update them too through bridge) - profileConnecting* profileConnected* profileDisconnected* and getHandler now all use client instead of profile
author Goffi <goffi@goffi.org>
date Sun, 12 Feb 2017 17:55:43 +0100
parents 4f189bd1d9ed
children 8b37a62336c3
line wrap: on
line source

SàT v0.6.1
(c) Jérôme Poisson aka Goffi 2008-2016
(c) Adrien Cossa aka Souliane 2013-2016

SàT is a XMPP (Jabber) client.


** LICENCE **

SàT is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

SàT is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with SàT.  If not, see <http://www.gnu.org/licenses/>.


** ABOUT **

SàT is a XMPP (Jabber) client, made on a daemon/frontends architecture. Its aim is not only to be an instant messaging client: SàT manage microblogging, file transfer, rich text edition, piping over XMPP, XMPP remote, etc.
In addition, SàT has been built with ethic in mind, a social contract show the main lines (see CONTRAT_SOCIAL or CONTRAT_SOCIAL_en). We have a lot of debates about the right way to do things, more on a social way than on a technical way (but consider technique too).

For the moment, the frontends are:

* primitivus: a console interface client, for terminal lovers
* jp: the powerful command line toolkit.
* libervia: the web frontend. It's in a different package, check libervia on the wiki: https://wiki.goffi.org/wiki/Libervia
* cagou: the desktop/mobile frontend. It's in a different package
* bellaciao: a Qt frontend at an early development stage (development currently paused)

other frontends planed in the near future:

* mobile frontends, fuse frontend, etc.


** HOW TO USE IT ? **

For installation instructions, please read the file "INSTALL". Note that SàT is available in several GNU/Linux distributions

A wiki is available online (https://wiki.goffi.org), in French and English so far (we would appreciate any help for other languages). You can also have a look at the bottom of this files (in contact section) for other available websites.


** MISC **

To use SàT, you need to have D-Bus daemon launched (http://www.freedesktop.org/wiki/Software/dbus/). If you use X Window, it should already be launched. If your are on a terminal environment without X11 (e.g. on a server) you may have to launch it. You can launch a daemon using the following command:
$ eval `dbus-launch --sh-syntax`

Be careful to use the same environment variables if you start a new session.

I personally use the following script to do that automatically:

--- /usr/local/bin/dbus-launch.sh ---
#!/bin/sh

DBUS_PATH="/tmp/.dbus.`whoami`"

if [ ! -e $DBUS_PATH ]; then
        dbus-launch --sh-syntax > $DBUS_PATH
        chmod 400 $DBUS_PATH
fi

cat $DBUS_PATH
--- end of /usr/local/bin/dbus-launch.sh ---

You can launch this script by putting at the end of your .zshrc (or whatever you're using):
eval `/usr/local/bin/dbus-launch.sh`

--

You can find Primitivus shortcuts on the wiki:
https://wiki.goffi.org/wiki/Primitivus

--

SàT is the acronym (yes another one :( ) in tribute to the song Salut à Toi from the Bérurier Noir band and it means "hi to you" (which seems appropriate for a communication software). If you want to listen to the song, we also recommend the excellent cover from Les Ogres de Barback.
jp stands for "Jabber coPy" or "JumP", and was choosen for its similarity with "cp" and short name.
Primitivus is based on Urwid, and, according to their FAQ, "ur" is a German prefix for "ancestral or primal" (primitivus is a latin word).
Libervia is made from "Liber" (libre) and via (road, path). It could be understood as the libre road, or the path to freedom.
Cagou is the name of a beautiful bird (who bark and can't fly) from New-Caledonia, and it's also a wink to Kivy, the framework used.


** CREDIT **

A big big thank to the authors/contributors of...

proxy65:
SàT (plugin_xep_0065) use nearly all the code from proxy65 (http://code.google.com/p/proxy65/) which was coded by Dave Smith (2002-2004) and maintained by Fabio Forno (2007-2008).
As the original MIT licence allows, the code is reused and sub-licenced until GPL v3 to follow the rest of the code.

progressbar:
SàT (jp) use ProgressBar (http://pypi.python.org/pypi/progressbar/2.2), a class coded by Nilton Volpato which allow the textual representation of progression.

twisted:
SàT is heavily based on the twisted framework (http://twistedmatrix.com/trac/), a very great tool which offer a lot of protocols management. There are too many contributors to name them here, so take a look on the website :).

wokkel:
SàT use a library with high level enhancements on top of twisted, which is called wokkel (http://wokkel.ik.nu). Lot of thanks to Ralph Meijer and all other contributors.

Urwid:
Primitivus is based on Urwid (http://excess.org/urwid/) which saved me a lot of time. It's really a great library to easily make a sophisticated interface.

Pyjamas:
Libervia is built with a Pyjamas (http://pyjs.org), a Google Web Toolkit port for python, including Python to Javascript compiler, and Pyjamas Desktop which allow to execute the same application on the desktop or through a browser. It's really an amazing tool.

Kivy and its linked tools (python-for-android, buildozer, plyer, pyjnius):
Kivy and linked tools (https://kivy.org) are used to build Cagou frontend, and to port it on several platforms. Excellent pieces of software, well thought, 

Kivy garden:
in addition to Kivy itself, extension from the garden are used:
- contextmenu: used to display main and context menus

lxml(http://lxml.de/):
this powerful and efficient XML parsing module is used sometimes to replace Twisted internal tools: its API is handy, and it have some features like evil content cleaning.

pillow(https://python-pillow.github.io/):
This image manipulation module is used for avatars

txJSON-RPC:
Libervia use txJSON-RPC (https://launchpad.net/txjsonrpc), a twisted library to communicate with the browser's javascript throught JSON-RPC

Mutagen:
Mutagen (https://bitbucket.org/lazka/mutagen) is an audio metadata handling library, it's used by the radiocol plugin.

Python OTR (http://python-otr.pentabarf.de), PyCrypto (https://www.dlitz.net/software/pycrypto) and pyOpenSSL(https://github.com/pyca/pyopenssl):
Used for cryptography

otr.js and its dependencies Big Integer Library, CryptoJS, EventEmitter:
Libervia frontend uses otr.js and its dependencies:
    - otr.js was coded by Arlo Breault (2014) and is released under the Mozilla Public License Version 2.0
    - Big Integer Library was coded by Leemon Baird (2000-2013) and is in the public domain
    - CryptoJS was coded by Jeff Mott (2009-2013) and is released under the MIT licence
    - EventEmitter was coded by Oliver Caldwell (2011-2013) and is released under the MIT licence
As the original licences allow, the code is reused and sub-licenced until GPL v3 to follow the rest of the code.

mardown (https://pythonhosted.org/Markdown/) and html2text (https://pypi.python.org/pypi/html2text/2015.6.21):
both are used for syntaxes conversions

Jinja2 (http://jinja.pocoo.org/):
a poweful template engine for Python that we use for designing Libervia's static blog pages

miniupnp (http://miniupnp.free.fr/):
this UPnP-IGD implementation is used to facilitate P2P sessions

netifaces (https://pypi.python.org/pypi/netifaces):
when available, this module is used to detect local IPs

pictures found in the sat_media repository and used by SàT and Libervia:
Please read the credits and licence information that are given in the README and COPYING files for each work: http://repos.goffi.org/sat_media/file

the powerfull ImageMagick (http://www.imagemagick.org/) is used by the script written to split the previously named picture.

PyXDF (http://freedesktop.org/wiki/Software/pyxdg):
Used to follow FreeDesktop XDG standards

A special thank to people working on XMPP standards, libre standards are the way to go !

and the others:
and of course, nothing would be possible without Python (http://www.python.org/), GNU and the Free Software Foundation (http://www.gnu.org, http://www.fsf.org/), the Linux Kernel (http://www.kernel.org/), and the coder of the tools we use like Vim (http://www.vim.org/), Mercurial (http://www.selenic.com/mercurial/wiki/), or all the KDE stuff (http://www.kde.org/ and of course http://amarok.kde.org/), and also XFCE (http://www.xfce.org), etc. Thanks thanks thanks, thanks to everybody in the Free (Libre) chain for making a part of this.

If we forgot any credit (and we probably have), please contact us (mail below) to fix it.


** CONTRIBUTORS **

Salut à Toi has received contributions from:

- Adrien Vigneron <adrienvigneron@mailoo.org>: huge work on Libervia's CSS, SàT Logo (the mascot is his work), and Quiz game graphics. He's friendly and talented, his work is really appreciated.

- Xavier Maillard <xavier@maillard.im>: bugs fixes. He's following the project for a while, maybe a future frontend contributor?

- Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>: bugs fixes, Libervia's notification, Libervia as a twisted application plugin. A guy always around XMPP projects, he plan to work on a non D-Bus bridge.

- Matthieu Rakotojaona <matthieu.rakotojaona@gmail.com>: English translation of the social contract. A great quality translation!

- Thomas Preud'homme <robotux@debian.org>: bugs fixes. He's also one of the co-maintainer of the Debian package.

- Dal <kedals0@gmail.com>: profiles management, argparse refactoring in jp.

- Matteo Cypriani <mcy@lm7.fr>: jp's mainloop update + doc improvements + various fixes. He's also the other co-maintainer of the Debian package.

- Olly Betts <olly@survex.com>: icon fix in Wix [N.B: Wix has since been removed]

- Geoffrey Pouzet <chteufleur@kingpenguin.tk>: XEP-0070 and XEP-0184 implementations

Many thanks to them.

A big thanks also to all the maintainers of SàT packages.


** CONTACT **

You can join us on the XMPP MUC room (sat@chat.jabberfr.org), or individually:

SàT team:
	- contact@salut-a-toi.invalid (replace invalid by org)
	- https://libervia.org/blog/salut-a-toi (blog)

Goffi:
	- goffi@goffi.org (e-mail)
	- goffi@jabber.fr (jid)
	- https://www.goffi.org (blog - based on Libervia -, with fresh news about SàT)

Souliane:
	- souliane@mailoo.org (e-mail)
	- souliane@libervia.org (jid)

You'll find the latest version and other stuffs on *.goffi.org websites:

- wiki (wiki.goffi.org), in French & English so far
- ftp (ftp.goffi.org) for the latest version, or previous ones (and other projects)
- bugtracker (bugs.goffi.org) to report any problem or give suggestions
- mailing lists (lists.goffi.org)

and the official SàT website is at https://www.salut-a-toi.org


This software is dedicated to Roger Poisson.