158 lines
4.6 KiB
ReStructuredText
158 lines
4.6 KiB
ReStructuredText
..
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
=============================================
|
|
Welcome to the Zaqar developer documentation!
|
|
=============================================
|
|
|
|
Zaqar is a multi-tenant cloud messaging and notification service for web
|
|
and mobile developers.
|
|
|
|
The service features a REST API, which developers can use to send messages
|
|
between various components of their SaaS and mobile applications, by using a
|
|
variety of communication patterns. Underlying this API is an efficient
|
|
messaging engine designed with scalability and security in mind.
|
|
|
|
Other OpenStack components can integrate with Zaqar to surface events to
|
|
end users and to communicate with guest agents that run in the
|
|
"over-cloud" layer.
|
|
|
|
.. note:: This documentation is generated by the Sphinx toolkit and lives in the Zaqar project source
|
|
tree. Additional draft and project documentation regarding Zaqar and other components of OpenStack can
|
|
be found on the `OpenStack Wiki`_, as well as in the user guides found on `docs.openstack.org`_.
|
|
|
|
.. _`OpenStack Wiki`: http://wiki.openstack.org
|
|
.. _`docs.openstack.org`: http://docs.openstack.org
|
|
|
|
Key features
|
|
============
|
|
|
|
Zaqar provides the following key features:
|
|
|
|
* HTTP-based messaging API
|
|
* Multi-tenant design based on Keystone project IDs
|
|
* Support for several common patterns including event broadcasting, task
|
|
distribution, and point-to-point messaging
|
|
* Component-based architecture with support for custom backends and
|
|
message filters
|
|
* Efficient reference implementation with an eye toward low latency and
|
|
high throughput (dependent on backend)
|
|
* Highly-available and horizontally scalable
|
|
|
|
Project scope
|
|
=============
|
|
|
|
The Zaqar API is data-oriented. That is, it does not provision message brokers
|
|
and expose those directly to clients. Instead, the API acts as a bridge
|
|
between the client and one or more backends. A provisioning service for
|
|
message brokers—however useful—serves a somewhat different market from what
|
|
Zaqar is targeting today. With that in mind, if users are interested in a
|
|
broker provisioning service, the community should consider starting a new
|
|
project to address that need.
|
|
|
|
Design principles
|
|
=================
|
|
|
|
Zaqar, as with all OpenStack projects, is designed with the following
|
|
guidelines in mind:
|
|
|
|
* **Component-based architecture.** Quickly add new behaviors
|
|
* **Highly available and scalable.** Scale to very serious workloads
|
|
* **Fault tolerant.** Isolated processes avoid cascading failures
|
|
* **Recoverable.** Failures should be easy to diagnose, debug, and rectify
|
|
* **Open standards.** Be a reference implementation for a community-driven
|
|
|
|
Concepts
|
|
========
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
glossary
|
|
|
|
Modules reference
|
|
=================
|
|
|
|
Zaqar is composed of two layers:
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
transport
|
|
storage/autoindex
|
|
|
|
The **transport drivers** are responsible for interacting with Zaqar clients.
|
|
Every query made by clients is processed by the transport layer,
|
|
which is in charge of passing this information to the backend and then
|
|
returning the response in a format understandable by the client.
|
|
|
|
The **storage drivers** are responsible for interacting with the storage backends
|
|
and, that way, store or retrieve the data coming from the transport layer.
|
|
|
|
In order to keep these layers decoupled, we have established that
|
|
**checks should be performed in the appropriate layer**. In other words,
|
|
transport drivers must guarantee that the incoming data is well-formed
|
|
and storage drivers must enforce their data model stays consistent.
|
|
|
|
Setting up a development environment
|
|
====================================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
development-environment
|
|
|
|
Your first patch and your first review
|
|
======================================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
first_patch
|
|
first_review
|
|
|
|
|
|
Running and writing tests
|
|
=========================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
running_tests
|
|
test_suite
|
|
|
|
Other resources
|
|
===============
|
|
|
|
.. toctree::
|
|
:maxdepth: 3
|
|
|
|
launchpad
|
|
gerrit
|
|
jenkins
|
|
|
|
API reference
|
|
=============
|
|
|
|
.. toctree::
|
|
:maxdepth: 3
|
|
|
|
api/autoindex
|
|
|
|
Indices and tables
|
|
------------------
|
|
|
|
* :ref:`genindex`
|
|
* :ref:`modindex`
|
|
* :ref:`search`
|