0141d62fcd
Currertly Zaqar has only one storage pipeline stage which can be used as option in `zaqar.conf`: `zaqar.notification.notifier`. It would be nice to have the information about writing stages for the storage layer pipelines in the Zaqar Developer Documentation. The tutorial with such information could be useful for Zaqar contributors. Zaqar Configuration Reference then can provide a link to this tutorial for the people who are willing to write their own external stages outside Zaqar package. This patch adds such tutorial. Partial-Implements: blueprint contributor-docs-refactoring Change-Id: Ia53017943037eed748a81fac0e4653341d6276a8
198 lines
5.8 KiB
ReStructuredText
198 lines
5.8 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. The Websocket
|
|
API is also available.
|
|
|
|
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:
|
|
|
|
* Choice between two communication transports. Both with Keystone support:
|
|
|
|
* Firewall-friendly, **HTTP-based RESTful API**. Many of today's developers
|
|
prefer a more web-friendly HTTP API. They value the simplicity and
|
|
transparency of the protocol, it's firewall-friendly nature, and it's huge
|
|
ecosystem of tools, load balancers and proxies. In addition, cloud
|
|
operators appreciate the scalability aspects of the REST architectural
|
|
style.
|
|
* **Websocket-based API** for persistent connections. Websocket protocol
|
|
provides communication over persistent connections. Unlike HTTP, where
|
|
new connections are opened for each request/response pair, Websocket can
|
|
transfer multiple requests/responses over single TCP connection. It saves
|
|
much network traffic and minimizes delays.
|
|
|
|
* Multi-tenant queues 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.
|
|
* Support for subscriptions to queues. Several notification types are
|
|
available:
|
|
|
|
* Email notifications.
|
|
* Webhook notifications.
|
|
* Websocket notifications.
|
|
|
|
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
|
|
|
|
devref/development.environment
|
|
|
|
Welcome new contributors
|
|
========================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
welcome
|
|
first_patch
|
|
first_review
|
|
|
|
|
|
Running and writing tests
|
|
=========================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
running_tests
|
|
test_suite
|
|
|
|
Reviewing
|
|
=========
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
reviewer_guide
|
|
|
|
Tutorials
|
|
=========
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
running_benchmark
|
|
writing_pipeline_stages
|
|
|
|
Other resources
|
|
===============
|
|
|
|
.. toctree::
|
|
:maxdepth: 3
|
|
|
|
launchpad
|
|
gerrit
|
|
jenkins
|
|
|
|
Internal API reference
|
|
======================
|
|
|
|
.. toctree::
|
|
:maxdepth: 3
|
|
|
|
api/autoindex
|
|
|
|
Indices and tables
|
|
------------------
|
|
|
|
* :ref:`genindex`
|
|
* :ref:`modindex`
|
|
* :ref:`search`
|