WillemJiang closed pull request #134: SCB-330 update document of pack URL: https://github.com/apache/incubator-servicecomb-saga/pull/134
This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/README.md b/README.md old mode 100755 new mode 100644 index 9a7249f5..fd569ea6 --- a/README.md +++ b/README.md @@ -1,76 +1,36 @@ # Saga [](https://travis-ci.org/apache/incubator-servicecomb-saga?branch=master) [](https://coveralls.io/github/apache/incubator-servicecomb-saga?branch=master) [](https://www.apache.org/licenses/LICENSE-2.0.html) -Apache ServiceComb (incubating) Saga is a type of Compensating Transaction pattern, which provides a simple way to help users solve the data consistency problems encountered in micro-service applications. +Apache ServiceComb (incubating) Saga is an eventually data consistency solution for micro-service applications. Transactions are commited directly in the try phase and compensated in reverse order in the rollback phase comparing to [TCC](http://design.inf.usi.ch/sites/default/files/biblio/rest-tcc.pdf). -## Documentation -Reference documentation is available on the [ServiceComb website][servicecomb-website]. +## Features +* High availability. The coordinator is stateless and thus can have multiple instances. +* High reliability. All transaction events are stored in database permanently. +* High performance. Transaction events are reported to coordinator via gRPC and transaction payloads are serialized/deserialized by Kyro. +* Low invasion. All you need to do is add 2-3 annotations and the corresponding compensate methods. +* Easy to deploy. All components can boot via docker. +* Supported micro-service frameworks: + + Spring Cloud +* Support both forward(retry) and backward(compensate) recovery. -[servicecomb-website]: http://servicecomb.incubator.apache.org/ +## Architecture +Saga is composed of **alpha** and **omega**. +* The alpha plays as the coordinator. It is responsible for the management of transactions. +* The omega plays as an agent inside the micro-service. It intercepts incoming/outgoing requests and reports transaction events to alpha. -## Major Architecture of Saga -* saga-core(transaction and compensation handling logic) -* saga-format(data serialization and deserialization) -* saga-transports(communication protocol implementation such as rest or rpc in the future) -* saga-discovery(service discovery) -* saga-spring(restful service framework) +The following diagram shows the relationships among alpha, omega and services. + - +See [Saga Pack Design](docs/design.md) for details. If you are interested in our previous architecture, please move forward to [Old Saga's Documentation](docs/old_saga.md). -## Prerequisites -You will need: -1. [Oracle JDK 1.8+][jdk] -2. [Maven 3.x][maven] -3. [Docker][docker] -4. [PostgreSQL][postgres] -5. [Service Center(optional)][service_center] -6. [Docker compose(optional)][docker_compose] -7. [Docker machine(optional)][docker_machine] +## Get Started +See [Booking Demo](saga-demo/pack-demo/README.md) for details. - -[jdk]: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html -[maven]: https://maven.apache.org/install.html -[docker]: https://www.docker.com/get-docker -[postgres]: https://www.postgresql.org/download/ -[service_center]: https://github.com/apache/incubator-servicecomb-service-center -[docker_compose]: https://docs.docker.com/compose/install/ -[docker_machine]: https://docs.docker.com/machine/install-machine/ - - - -## Building -Download the source code. -``` -git clone https://github.com/apache/incubator-servicecomb-saga.git -``` - -Enter the Saga root directory,build Saga project by maven command and generate a docker image named saga-spring in local. -``` -mvn package -DskipTests -Pdocker -``` - -## Run Services -A `docker-compose.yaml` file is provided to start Saga services and its dependencies(Service center and Mysql) as docker containers. -User also can configure specified Service center or Mysql in `docker-compose.yaml`. - -Enter the Saga root directory, run all service images using command, -``` -docker-compose up -``` - - -## Reference API -See [Saga API](docs/api/api.md) for details. - - -## Example -See [Saga demo](https://github.com/apache/incubator-servicecomb-saga/tree/master/saga-demo) for details. - -## Contact -Bugs: [issues](https://issues.apache.org/jira/browse/SCB). - -Mailing lists: [subscribe](mailto:dev-subscr...@servicecomb.incubator.apache.org) [dev](https://lists.apache.org/list.html?dev@servicecomb.apache.org) +## Contact Us +* [issues](https://issues.apache.org/jira/browse/SCB) +* [gitter](https://gitter.im/ServiceCombUsers/Lobby) +* mailing list: [subscribe](mailto:dev-subscr...@servicecomb.incubator.apache.org) [view](https://lists.apache.org/list.html?dev@servicecomb.apache.org) ## Contributing -See [Pull Request Guide](http://servicecomb.io/developers/submit-codes/) for details. +See [Pull Request Guide](http://servicecomb.incubator.apache.org/developers/submit-codes/) for details. -## Reporting Issues -See reporting bugs for details about reporting any issues. +## License +Licensed under an [Apache 2.0](https://github.com/apache/incubator-servicecomb-saga/blob/master/LICENSE) license. diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 00000000..625cb95b --- /dev/null +++ b/docs/design.md @@ -0,0 +1,31 @@ +# Saga Pack Design +## Overview +Pack contains two components: *alpha* and *omega*. Alpha is the pack leader and backed by database to make sure transaction events stored permanently while omega is the pack worker and embeded inside services to intercept incoming/outgoing requests and report events to alpha. + + + +## Omega Internal +Omega plays as an embeded agent inside services. When a request arrives, omega intercepts its header and retrieve the global transaction id as its global transaction id and retrieve the local transaction id as its parent transaction id. In pre-process phase, a transaction started event will be recorded in alpha. In post-process phase, a transaction ended event will be recorded in alpha to mark the end of the sub-transaction. + + + +## Inter-Service Communication +The process of Inter-Service Communication is similiar to [Zipkin](https://github.com/openzipkin/zipkin)'s. In the producer side, omega intercepts the transaction ids from request to retrieve the transaction context. In the consumer side, omega inject the transaction ids into request to pass the transaction context. Sub-transactions can chain as a single global transaction by co-operating producers and consumers. + + + +## Workflow +### Successful Scenario +In a successful scenario, all started events will have a corresponding ended event. + + + +### Exception Scenario +In an exception scenario, omega inside the abnormal service will report an aborted event to alpha. Apha will then send compensate commands to the completed events within the global transaction to make suer all sub-transactions are either completed or rollbacked. + + + +### Timeout Scenario +In timeout scenario, timeouted events will be detected by alpha's periodly scanner and abort the corresponding global transaction. + + diff --git a/docs/old_saga.md b/docs/old_saga.md new file mode 100755 index 00000000..2b79d221 --- /dev/null +++ b/docs/old_saga.md @@ -0,0 +1,53 @@ +# Previous Saga's Documentation +## Major Architecture of Saga +* saga-core(transaction and compensation handling logic) +* saga-format(data serialization and deserialization) +* saga-transports(communication protocol implementation such as rest or rpc in the future) +* saga-discovery(service discovery) +* saga-spring(restful service framework) + + + +## Prerequisites +You will need: +1. [Oracle JDK 1.8+][jdk] +2. [Maven 3.x][maven] +3. [Docker][docker] +4. [PostgreSQL][postgres] +5. [Service Center(optional)][service_center] +6. [Docker compose(optional)][docker_compose] +7. [Docker machine(optional)][docker_machine] + +[jdk]: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html +[maven]: https://maven.apache.org/install.html +[docker]: https://www.docker.com/get-docker +[postgres]: https://www.postgresql.org/download/ +[service_center]: https://github.com/apache/incubator-servicecomb-service-center +[docker_compose]: https://docs.docker.com/compose/install/ +[docker_machine]: https://docs.docker.com/machine/install-machine/ + +## Building +Download the source code. +``` +git clone https://github.com/apache/incubator-servicecomb-saga.git +``` + +Enter the Saga root directory,build Saga project by maven command and generate a docker image named saga-spring in local. +``` +mvn package -DskipTests -Pdocker +``` + +## Run Services +A `docker-compose.yaml` file is provided to start Saga services and its dependencies(Service center and Mysql) as docker containers. +User also can configure specified Service center or Mysql in `docker-compose.yaml`. + +Enter the Saga root directory, run all service images using command, +``` +docker-compose up +``` + +## Reference API +See [Saga API](docs/api/api.md) for details. + +## Example +See [Saga demo](https://github.com/apache/incubator-servicecomb-saga/tree/master/saga-demo) for details. diff --git a/docs/static_files/exception_scenario.png b/docs/static_files/exception_scenario.png new file mode 100644 index 00000000..a8738baf Binary files /dev/null and b/docs/static_files/exception_scenario.png differ diff --git a/docs/static_files/inter-service_communication.png b/docs/static_files/inter-service_communication.png new file mode 100644 index 00000000..11d8dffb Binary files /dev/null and b/docs/static_files/inter-service_communication.png differ diff --git a/docs/static_files/omega_internal.png b/docs/static_files/omega_internal.png new file mode 100644 index 00000000..1f130a2c Binary files /dev/null and b/docs/static_files/omega_internal.png differ diff --git a/docs/static_files/pack.png b/docs/static_files/pack.png new file mode 100644 index 00000000..2c30c00e Binary files /dev/null and b/docs/static_files/pack.png differ diff --git a/docs/static_files/successful_scenario.png b/docs/static_files/successful_scenario.png new file mode 100644 index 00000000..5dd8850c Binary files /dev/null and b/docs/static_files/successful_scenario.png differ diff --git a/docs/static_files/timeout_scenario.png b/docs/static_files/timeout_scenario.png new file mode 100644 index 00000000..998cfcfb Binary files /dev/null and b/docs/static_files/timeout_scenario.png differ diff --git a/saga-demo/pack-demo/README.md b/saga-demo/pack-demo/README.md index 1e8d7007..9eecd623 100644 --- a/saga-demo/pack-demo/README.md +++ b/saga-demo/pack-demo/README.md @@ -4,6 +4,18 @@ This demo simulates a booking application including three services: * pack-car * pack-hotel +## Prerequisites +You will need: +1. [JDK 1.8][jdk] +2. [Maven 3.x][maven] +3. [Docker][docker] +4. [Docker compose][docker_compose] + +[jdk]: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html +[maven]: https://maven.apache.org/install.html +[docker]: https://www.docker.com/get-docker +[docker_compose]: https://docs.docker.com/compose/install/ + ## Running Demo 1. run the following command to create docker images in saga project root folder. ``` ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
