..
      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`
