wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

major refresh of the existing FAQ content (WIP)

Browse source
This commit is contained in:
Matthew Hodgson 2015-10-06 14:13:15 -05:00
parent 7ae2573113
commit f759dc30d2
1 changed files with 172 additions and 75 deletions
Download patch file Download diff file Expand all files Collapse all files

247
supporting-docs/_posts/2015-08-19-faq.md
View file

@ -37,59 +37,92 @@ FAQ Content
##### What is Matrix?
Matrix is an ambitious new open standard for open, distributed,
real-time communication over IP. It defines interoperable Instant
Messaging and VoIP, providing pragmatic HTTP APIs and open source
reference implementations for creating and running your own real-time
communication infrastructure.
Matrix is an open standard for interoperable, decentralised,
real-time communication over IP. It can be used to power Instant
Messaging, VoIP/WebRTC signalling, Internet of Things communication - or anywhere
you need a standard HTTP API for publishing and subscribing to
data whilst tracking the conversation history.
|
Matrix defines the standard, and provides open source reference implementations
of Matrix-compatible Servers, Clients, Client SDKs and Application Services
to help you create new communication solutions or extend the capabilities
and reach of existing ones.
##### What is Matrix's Mission?
Matrix.org's initial inspiration and goal has been to fix the problem of
fragmented IP communications. But Matrix's real potential and ultimate
mission is to be a generic messaging and data synchronisation system for
the web - allowing people, services and devices to easily communicate
with each other with full history.
Matrix's initial goal is to fix the problem of fragmented IP communications:
letting users message and call each other without having to care what app
the other user is on - making it as easy as sending an email.
|
The longer term goal is for Matrix to act as a generic HTTP messaging and data
synchronisation system for the whole web - allowing people, services and devices
to easily communicate with each other, empowering users to own and control their
data and select the services and vendors they want to use.
##### What does Matrix provide?
Today Matrix provides a new [open standard](/docs/spec),
[APIs](/docs/api) to integrate a service to the Matrix ecosystem and
reference [open source
implementations](http://github.com/matrix-org/synapse) of the standard.
Matrix provides:
- [Open Standard](/docs/spec) HTTP APIs for transferring JSON messages (e.g. instant messages, WebRTC signalling), including:
- [Client\<-\>Server API](/docs/spec#client-server-api-v1) - defines how Matrix compatible clients communicate with Matrix homeservers.
- [Server\<-\>Server API](/docs/spec#federation-api) - defines how Matrix homeservers exchange messages and synchronise history with each other.
- [Application Service API](/docs/spec/#application-service-api) - defines how to extend the functionality of Matrix with 'integrations' and bridge to other networks.
- [Modules](/docs/spec/#modules) - specifies features that must be implemented by particular classes of clients.
- Open source reference implementations of:
- Clients (Web (React), iOS, Android)
- Client SDKs (Javascript, Web (React), iOS, Android)
- Homeservers (Synapse)
- Application Services (bridges to IRC, Slack, Skype, Lync and more...)
- The actual ecosystem and community of everyone running Matrix servers and services
- Loads of 3rd party contributions of clients, SDKs, servers and services.
You can find the full list of Matrix enabled projects at https://matrix.org/blog/try-matrix-now.
##### What does this mean for users?
The aim is to provide an analogous ecosystem to email - one where you
can communicate with pretty much anyone, without caring what app or
server they are using, using whichever app & server you chose to use,
and a nice neutral identity system like an e-mail address or phone
and use a neutral identity system like an e-mail address or phone
number to discover people to talk to.
##### What kind of company is Matrix.org?
Matrix is an open initiative which acts as a neutral custodian of the
Matrix standard. It's not actually incorporated anywhere at the moment
but we are looking at the best legal structure for the future. We are
committed to keeping the Matrix project open.
but we are looking at the best legal structure for the future (and as
of October 2015 we have hopefully found one). Whatever the legal
structure, we are committed to keeping the Matrix project open.
##### Who is funding Matrix.org?
We have been given permission by our employers, Amdocs, to work on
Matrix as an independent non-profit initiative.
Most of the current core contributors to Matrix work at
[Amdocs](http://amdocs.com), who have kindly given us permission to work
on Matrix as an independent non-profit initiative. Other contributors
are funded by their own employers or donate their own time to the project.
##### Who is building Matrix?
We're a team of ~10 people with decades of experience building custom
The core team is ~10 people with extensive experience in building custom
VoIP and Messaging apps for mobile network operators. Most of us have
day jobs at Amdocs or OpenMarket, but we are supported by a mix of
freelancers and volunteers.
day jobs at [Amdocs](http://amdocs.com) or [OpenMarket](http://openmarket.com),
but there are an increasing number of contributors from other companies and
folks all over the internet.
##### Why are you called Matrix?
We are called Matrix because we provide a structure in which all
communication can be matrixed together.
|
No, it's nothing to do with the film (although you could go and build virtual
worlds on top of Matrix if you wanted :)
##### Why have you released this as open source?
We believe that any open standard defining interoperable communication
@ -102,16 +135,18 @@ and build on top of it.
##### What do you mean by open?
Matrix is an open standard, meaning that we have freely published the
details for how to interface with Matrix compliant servers and clients,
and encourage anyone and everyone to interface with them.  We also
details for how to communicate interoperably using the Matrix set of
HTTP APIs. We encourage anyone and everyone to use the APIs and build
their own projects which implement them and so benefit from
interoperability with the rest of the Matrix ecosystem. We also
ensure the standard is not encumbered by any known patent licensing
requirements.
|
|
Matrix is also open source, meaning that we have released the source
code of the reference servers and clients to the public domain under the
[Apache Licence v2](http://www.apache.org/licenses/LICENSE-2.0.html), to
code of the reference servers, clients and services to the public domain
under the [Apache Licence v2](http://www.apache.org/licenses/LICENSE-2.0.html), to
encourage anyone and everyone to run their own servers and clients, and
enhance them and contribute their enhancements as they see fit.
@ -120,7 +155,7 @@ enhance them and contribute their enhancements as they see fit.
Federation allows separate deployments of a communication service to
communicate with each other - for instance a mail server run by Google
federates with a mail server run by Microsoft when you send email from
@gmail.com to @outlook.com.
@gmail.com to @hotmail.com.
|
@ -145,16 +180,18 @@ VoIP and IM.
##### Why has no-one done this before?
There have been several attempts before including SIP, XMPP and RCS.
 All of these have had some level of success, but
 All of these have had some level of success, but many different
technological/usability/economic factors have ended up limiting their
success in providing true open federation.
success. Unfortunately, we've not ended up in a world where everyone
has a SIP URI or Jabber ID on their business card, or a phone that
actually uses RCS.
##### What is the difference between Matrix and IRC?
We love IRC.  In fact, as of today the core Matrix team still uses it as
our primary communication tool. Between us we've written IRCds, IRC bots
and admined dreamforge, UnrealIRCd, epona, ircservices and several
others.  That said, it has some limitations that Matrix seeks to improve
others. That said, it has some limitations that Matrix seeks to improve
on:
- Text only
@ -163,18 +200,24 @@ on:
- No presence support
- Fragmented identity model
- No open federation
- No standard APIs, just an archaic TCP line protocol
- No standard APIs, just a rather limited TCP line protocol
- Non-standardised federation protocol
- No built-in end-to-end encryption
- Disruptive net-splits
- Non-extensible
[IRCv3](http://ircv3.net) exists and is addressing some of issues;
this is great news and we wish them well. It's almost a contradiction
in terms to get competitive between openly interoperable communication
projects - we look forward to increasing the richness of Matrix\<-\>IRC
bridges as the project progresses.
##### What is the difference between Matrix and XMPP?
The Matrix team used XMPP (Openfire, ejabberd, spectrum, asmack,
XMPPFramework) for IM before starting to experiment with open HTTP APIs
as an alternative.   The main issues with XMPP that drove us in this
direction were:
as an alternative in around 2012. The main issues with XMPP that
drove us in this direction were:
- Not particularly web-friendly - you can't easily speak XMPP from a
web browser. (N.B. Nowadays you have options like XMPP-FTW and
@ -182,8 +225,8 @@ direction were:
- Single logical server per MUC is a single point of control and
availability. (MUCs can be distributed over multiple physical
servers, but they still sit behind a single logical JID and domain.
FMUC improves this with a similar approach to Matrix, but at time of
writing there are no open implementations.)
FMUC improves this with a similar approach to Matrix, but as of Oct
2015 there are no open source implementations.)
- History synchronisation is very much a second class citizen feature
- Stanzas aren't framed or reliably delivered without extensions. (See
[wiki.xmpp.org](http://wiki.xmpp.org/web/Myths#Myth_Four:_XMPP_is_unreliable_without_a_bunch_of_extensions.)
@ -191,7 +234,8 @@ direction were:
- Multiple device support is limited. (Apparently Carbons and MAM help
with this)
- Baseline feature set is so minimal that fragmentation of features
between clients and servers is common
between clients and servers is common, especially as interoperability
profiles for features have fallen behind (as of July 2015)
- No strong identity system (i.e. no standard E2E PKI, unless you
count X.509 certs, which [are
questionable](http://www.thoughtcrime.org/blog/ssl-and-the-future-of-authenticity/))
@ -199,31 +243,42 @@ direction were:
bandwidth-efficient transports. (Since the time of writing a [Push
XEP has appeared](http://xmpp.org/extensions/xep-0357.html), and
[wiki.xmpp.org](http://wiki.xmpp.org/web/Myths#Myth_Three:_It.27s_too_bandwidth-inefficient_for_mobile.)
claims that XMPP runs fine over a 9600bps + 30s latency link.)
claims that XMPP runs "fine" over a 9600bps + 30s latency link.)
The whole subject of XMPP vs Matrix seems to bring out the worst in
people. We think of the standards as being quite different; at its core
people. Rather than fighting over which open interoperable communication
standard works the best, we should just collaborate and bridge everything
together. The more federation and interoperability the better.
|
We think of Matrix and XMPP as being quite different; at its core
Matrix can be thought of as an eventually consistent global JSON db with
an HTTP API and pubsub semantics - whilst XMPP can be thought of as a
message passing protocol. You can use them both to build chat systems;
you can use them both to build pubsub systems; each comes with different
tradeoffs. Matrix has a 'kitchen sink' baseline of functionality; XMPP
has a deliberately minimal baseline set of functionality. If XMPP does
what you need it to do, then we're genuinely happy for you :) Meanwhile,
rather than competing, an XMPP Bridge like [Skaverat's xmpptrix
beta](https://github.com/SkaveRat/xmpptrix) has potential to let both
environments coexist and make the most of each other's benefits.
tradeoffs. Matrix has a deliberately extensive 'kitchen sink' baseline
of functionality; XMPP has a deliberately minimal baseline set of
functionality. If XMPP does what you need it to do, then we're genuinely
happy for you :) Meanwhile, rather than competing, an XMPP Bridge like
[Skaverat's xmpptrix beta](https://github.com/SkaveRat/xmpptrix) or
[jfred's matrix-xmpp-bridge](https://github.com/jfrederickson/matrix-xmpp-bridge)
or Matrix.org's own [matrix-appservice-purple](https://github.com/matrix-org/matrix-appservice-purple)
has potential to let both environments coexist and make the most of each
other's benefits.
##### What is the difference between Matrix and PSYC?
PSYC is a open federated messaging protocol loosely inspired by IRC.  In
version 1 it was a standalone protocol, and in version 2 it is being
reutilised as the messaging layer on top of GNUnet.  We honestly don't
reutilised as a messaging layer on top of GNUnet.  We honestly don't
know that much about it, beyond trying to use psycd as an XMPP\<-\>IRC
bridge in 2010. Matrix differentiates primarily by providing simple HTTP
APIs rather than the more exotic compact line protocol in PSYC v1 or the
complicated GNUnet stack in v2.  Meanwhile, Matrix doesn't provide of
the metadata protection guarantees that GNUnet/PSYC aims for.
comprehensive GNUnet stack in v2, and Matrix focuses more on decentralised
conversation history rather than just decentralised chat servers.
On the other hand, Matrix doesn't provide the metadata protection
guarantees that GNUnet/PSYC aims for.
|
@ -233,29 +288,56 @@ PSYC's views on Matrix.
##### What is the difference between Matrix and Tox?
Tox.im looks to be a very cool clone of Skype - a fully decentralised
peer-to-peer network.  Matrix is deliberately not peer-to-peer; instead
each user has a well-defined homeserver which stores his data and that
he can depend upon.  Matrix provides HTTP APIs; Tox.im provides C APIs.
 We haven't actually played with Tox at all yet.
peer-to-peer network.  Matrix is deliberately not a 'pure' peer-to-peer
system; instead each user has a well-defined homeserver which stores
his data and that he can depend upon.  Matrix provides HTTP APIs;
Tox.im provides C APIs. As of October 2015 Tox doesn't seem to have an
answer yet for decentralised conversation history storage.
##### How does Matrix compare with something like Trillian or Pidgin?
Trillian and Pidgin and similar aggregating IM clients merge all your IM
activity into a single user experience.  However, your history and
activity into a single app.  However, your history and
identity is still fragmented across the networks.  People can't find you
easily, and your history is fragmented (other than on the device
where the client runs).   And rather than being able to chose the right
app for the job when communicating with people, you are pushed towards
relying on a specific aggregation app.
Matrix lets you get the best of both worlds by linking to all the
different networks (XMPP, AIM, ICQ, Lync, Skype etc) on the serverside,
using bridges which can be run by anyone. Matrix then provides a simple
standard HTTP API to access any of these networks, and lets you choose
whichever client you prefer (either as a 'native' Matrix client or using
a non-Matrix client from one of the networks which has been bridged in).
##### What Matrix compliant apps are there?
None yet, other than our examples.  It's early days :)
Quite a few, ranging from the glossy mass-market to the geeky command-line. There's even an emacs macro. Check out [https://matrix.org/blog/try-matrix-now] for the current
list of Matrix enabled projects.
##### Why do you think existing apps will ever join this?
##### What bridges to other networks are available?
The number of 'bridges' which integrate existing communication networks into
Matrix are growing on a daily basis - both written by the Matrix core team
and contributed by the wider community. The full list can be seen at
https://matrix.org/blog/try-matrix-now, but the core ones as of Oct 2015 include:
* [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) - an increasingly comprehensive Matrix\<-\>IRC bridge
* [matrix-appservice-verto](https://github.com/matrix-org/matrix-appservice-verto) - links from Matrix to FreeSWITCH via the Verto protocol
* [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) - a basic bridge to Slack
* [matrix-appservice-purple](https://github.com/matrix-org/matrix-appservice-purple) - lets you access any of the 20+ protocols supported by
[libpurple](https://developer.pidgin.im/wiki/WhatIsLibpurple), including
Skype, Lync,
* [matrix-appservice-bridge](https://github.com/matrix-org/matrix-appservice-bridge) - a general NodeJS framework for writing bridges
Writing new bridges is incredibly fun and easy - see the [matrix-appservice-bridge HOWTO](https://github.com/matrix-org/matrix-appservice-bridge/blob/master/HOWTO.md)
for an example of how to write a fully functional Slack bridge in less than 100 lines of code!
##### Why do you think existing apps will ever join this officially?
We firmly believe it is what is right for the consumer. As people begin
to use interoperable communications tools service providers will see the
to use interoperable communications tools, service providers will see the
benefit and compete on quality of service, security and features rather
than relying on locking people into their walled garden. We believe as
soon as users see the availability and benefits of interoperable
@ -264,9 +346,9 @@ services they will demand it.
##### Why aren't you doing this through the IETF? or W3C? or 3GPP?
We do recognise the advantages of working with existing standards
bodies. We have been focused on writing code and getting it out. As
Matrix matures it may well be appropriate to work with an official
standard body.
bodies. We have been focused on writing code and getting it out, and the standard has been evolving rapidly since initial release in September 2014.
Once the standard has matured sufficiently it may well be appropriate to work with an official
standard body to maintain it going forwards.
|
@ -274,18 +356,19 @@ standard body.
##### How do I get an account and get started?
The quickest way is to just jump to the demo webclient at
[http://matrix.org/beta](http://matrix.org/beta) and sign up.  Please note that you can point the
webclient to access any homeserver - you don't have to use matrix.org,
The quickest way is to pick a client from https://matrix.org/blog/try-matrix-now and sign up.
Please note that you can point clients to access any homeserver - you don't have to use matrix.org,
although as of day 1, matrix.org is the only communal homeserver
available.
##### What can I actually do with this?
The demo webclient provides a simple chatroom interface to Matrix -
A typical client provides a simple chatroom interface to Matrix -
letting the user interact with users and rooms anywhere within the
Matrix federation.  Text and image messages are supported, and basic
voice-only VoIP calling via WebRTC is supported in one-to-one rooms.
(As of October 2015, experimental multi-way calling is also available
on Vector.im).
##### How do I connect my homeserver to the public Matrix network?
@ -295,11 +378,21 @@ for details
##### How do I Matrix-enable my existing app?
See the [Client-Server API
HOWTO](http://matrix.org/docs/howtos/client-server.html) for an example
of how to use Matrix's client-server API to let your app communicate
with users via Matrix.  We're currently working out the best way to
integrate your application's existing identity system with Matrix.
If your app doesn't have any communication capability already, you'll want
to use one of the Matrix client SDKs to add it in. These come in different
levels of sophistication - ranging from a simple HTTP API wrapper (like matrix-js-sdk, matrix-ios-sdk or matrix-android-sdk)
through to reusable UI components (like matrix-react-sdk and matrix-ios-kit). Pick
the one for your platform, or a 3rd party one if none of the above work for you,
and get plugging it in. You'll probably also want to read the [Client-Server API
HOWTO](http://matrix.org/docs/howtos/client-server.html) too.
If you already have communication infrastructure set up (XMPP, custom HTTP, or whatever),
then you'll want to run a bridge to expose it to the wider Matrix ecosystem.
See [matrix-appservice-bridge HOWTO](https://github.com/matrix-org/matrix-appservice-bridge/blob/master/HOWTO.md) for a
guide of how to write bridges using the matrix-appservice-bridge framework, or co-opt one
from the list at https://matrix.org/blog/try-matrix-now.
[Application Service API](/docs/spec/#application-service-api) gives the details of the API
that bridges have to implement.
##### How can I write a client on Matrix?
@ -308,16 +401,20 @@ HOWTO](http://matrix.org/docs/howtos/client-server.html) and the [API
docs](/docs/api) and [the Spec](/docs/spec) for all the details you need
to write a client.
##### *How can I help out with this?*
##### How can I help out with this?
Install synapse and tell us how you get on. Critique the spec.  Write
clients.  Just come say hi on [\#matrix:matrix.org](/alpha) or the
[mailing lists](/mailman/listinfo/matrix-users)!
Come say hi on #matrix:matrix.org! Install synapse and tell us how you get on. Critique the spec.  Write
clients. Write bridges! Run bridges! Nose around in [Jira](https://matrix.org/jira) and
send us some pull requests on github to fix some bugs or add some features! You could even
try to write a homeserver (but be warned, Matrix's architecture makes homeservers orders of
magnitude harder than clients or bridges.)
See [CONTRIBUTING.rst](http://github.com/matrix-org/synapse/tree/master/CONTRIBUTING.rst) for
full details on how to contribute to the project. All are welcome!
##### Where can I get support?
[\#matrix:matrix.org](/alpha), \#matrix on irc.freenode.net or
the [mailing lists](/mailman/listinfo/matrix-users) are your best bets.
\#matrix:matrix.org aka \#matrix on irc.freenode.is your best bet.
##### How do I register custom matrix event types?
@ -328,7 +425,7 @@ use the [mailing list](/mailman/listinfo/matrix-users) for now.
##### How mature is this?
We started working on Matrix in July 2014, and have opened it to the
public in September 2014.  It's early days, and under no circumstances
public in September 2014. It's early days, and under no circumstances
should you use Matrix or Synapse for anything other than experimentation
and learning at this point.  Obviously the spec and apps are maturing
rapidly, but as of the time of writing APIs are not frozen and the apps