From 40c7d5299cbbd0421a61330e627f2ef8331e1a0e Mon Sep 17 00:00:00 2001 From: Mahmut Bulut Date: Sun, 1 Mar 2020 00:54:41 +0100 Subject: [PATCH] Documentation and moving to vuepress --- README.md | 37 +++-------- docs/.vuepress/config.js | 13 ++++ docs/README.md | 29 --------- docs/building-blocks/primitives.md | 81 +++++++++++++++++++++++++ docs/examples/cluster-examples.md | 38 ++++++++++++ docs/getting-started/getting-started.md | 71 ++++++++++++++++++++++ docs/index.html | 21 ------- 7 files changed, 213 insertions(+), 77 deletions(-) create mode 100644 docs/.vuepress/config.js create mode 100644 docs/building-blocks/primitives.md create mode 100644 docs/examples/cluster-examples.md create mode 100644 docs/getting-started/getting-started.md delete mode 100644 docs/index.html diff --git a/README.md b/README.md index 9f456f3..8e86dc3 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,13 @@ + + + + + + + + + +

@@ -6,30 +16,3 @@

Artillery: Cluster management & Distributed data protocol

- -It contains the modules below: -* `artillery-ddata`: Used for distributed data replication -* `artillery-core`: Contains: - * `cluster`: Prepared self-healing cluster structures - * `epidemic`: Infection style clustering - * `service_discovery`: Service discovery types - * `mdns`: MDNS based service discovery - * `udp_anycast`: UDP Anycast based service discovery -* `artillery-hierman`: Supervision hierarchy management layer (aka Bastion's core carrier protocol) - -## Examples -Below you can find examples to learn Artillery. -You can also take a look at the [Core Examples](https://github.com/bastion-rs/artillery/tree/master/artillery-core/examples). - -### Launching a local AP Cluster -To spawn a local AP cluster at any size you can use the command below in the root directory of the project: -```bash -$ deployment-tests/cluster-mdns-ap-test.sh -s 50 -``` - -Argument `-s` defines the amount of nodes in the cluster. -To shut down the cluster either use: -```bash -$ killall cball_mdns_sd_infection -``` -or kill processes one by one to see that cluster is self-healing. diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js new file mode 100644 index 0000000..0353e79 --- /dev/null +++ b/docs/.vuepress/config.js @@ -0,0 +1,13 @@ +module.exports = { + title: 'Artillery', + description: 'Cluster management & Distributed data protocol', + theme: 'api', + themeConfig: { + editLinks: true, + sidebarGroupOrder: [ + 'getting-started', + 'building-blocks', + 'examples', + ], + } +} diff --git a/docs/README.md b/docs/README.md index df7f0df..66983a5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,32 +6,3 @@

Artillery: Cluster management & Distributed data protocol

- -# Module Structure - -It contains the modules below: -* `artillery-ddata`: Used for distributed data replication -* `artillery-core`: Contains: - * `cluster`: Prepared self-healing cluster structures - * `epidemic`: Infection style clustering - * `service_discovery`: Service discovery types - * `mdns`: MDNS based service discovery - * `udp_anycast`: UDP Anycast based service discovery -* `artillery-hierman`: Supervision hierarchy management layer (aka Bastion's core carrier protocol) - -## Examples -Below you can find examples to learn Artillery. -You can also take a look at the [Core Examples](https://github.com/bastion-rs/artillery/tree/master/artillery-core/examples). - -### Launching a local AP Cluster -To spawn a local AP cluster at any size you can use the command below in the root directory of the project: -```bash -$ deployment-tests/cluster-mdns-ap-test.sh -s 50 -``` - -Argument `-s` defines the amount of nodes in the cluster. -To shut down the cluster either use: -```bash -$ killall cball_mdns_sd_infection -``` -or kill processes one by one to see that cluster is self-healing. diff --git a/docs/building-blocks/primitives.md b/docs/building-blocks/primitives.md new file mode 100644 index 0000000..4c87d03 --- /dev/null +++ b/docs/building-blocks/primitives.md @@ -0,0 +1,81 @@ +--- +title: 'Primitives' +--- + + +# Primitives + + + + + +Artillery Core consists of various primitives. We will start with Service Discovery primitives and pave out way to Cluster primitives. + + + + + + +## Service Discovery Primitives + +For distributed operation we need to have a service discovery to find out who is operating/serving which services and service capabilities. + +Our design consists of various service discovery techniques. + + + + + + +## UDP Anycast + +We have UDP anycast which allows the devices in the same network to nag each other continuously with a specific set of service requests to form a cluster initiation. + +**NOTE:** Convergance of the UDP anycast might take longer time than the other zeroconf approaches. + + + +```rust +#[derive(Serialize, Deserialize, Debug, Clone, Ord, PartialOrd, PartialEq)] +struct ExampleSDReply { + ip: String, + port: u16, +} + +let epidemic_sd_config = ExampleSDReply { + ip: "127.0.0.1".into(), + port: 1337, // Cluster Formation Port of this instance +}; + +let reply = ServiceDiscoveryReply { + serialized_data: serde_json::to_string(&epidemic_sd_config).unwrap(), +}; + +// Initialize receiver channels +let (tx, discoveries) = channel(); + +// Register seeker endpoint +sd.register_seeker(tx).unwrap(); + +// Sometimes you seek for nodes, +// sometimes you need to be a listener to respond them. +if let Some(_) = seeker { + sd.seek_peers().unwrap(); +} else { + sd.set_listen_for_peers(true).unwrap(); +} + +for discovery in discoveries.iter() { + let discovery: ExampleSDReply = + serde_json::from_str(&discovery.serialized_data).unwrap(); + if discovery.port != epidemic_sd_config.port { + debug!("Seed node address came"); + let seed_node = format!("{}:{}", discovery.ip, discovery.port); + // We have received a discovery request. + } +} +``` + + + + diff --git a/docs/examples/cluster-examples.md b/docs/examples/cluster-examples.md new file mode 100644 index 0000000..89d7e4f --- /dev/null +++ b/docs/examples/cluster-examples.md @@ -0,0 +1,38 @@ +--- +title: 'Local Examples' +--- + + +# Local Examples + + + + +## Cluster Examples +Below you can find examples to learn Artillery. +You can also take a look at the [Core Examples](https://github.com/bastion-rs/artillery/tree/master/artillery-core/examples). + + + + + +## Launching a local AP Cluster +To spawn a local AP cluster at any size you can use the command below in the root directory of the project. + + + +```bash +$ deployment-tests/cluster-mdns-ap-test.sh -s 50 +``` + +```bash +$ killall cball_mdns_sd_infection +``` + + + +Argument `-s` defines the amount of nodes in the cluster. +To shut down the cluster either use `killall` or kill processes +one by one to see that cluster is self-healing. + + diff --git a/docs/getting-started/getting-started.md b/docs/getting-started/getting-started.md new file mode 100644 index 0000000..75b0a86 --- /dev/null +++ b/docs/getting-started/getting-started.md @@ -0,0 +1,71 @@ +--- +title: 'Getting Started' +--- + + +# Getting Started + + + + + +## Basics + +To use Artillery, you need to evaluate your requirements for distributed operation very carefully. +Every layer in artillery is usable modularly. Artillery uses "Take it or leave it" approach. +If you don't need it you don't include. + +Artillery consists of various layers. Layers can have various consistency degree and capability model. +Artillery layers are build on top each other. Most basic layer is `Core`. +Core layer contains various prepared cluster configurations. +Currently it is supporting: +* **AP(Availability, Partition Tolerance** Cluster mode +* **CP(Consistency, Partition Tolerance)** Cluster mode (soon) + +In addition to cluster modes, it contains primitives to build your own cluster structures for your own designated environment. + + + +* `artillery-core` + * `cluster`: Prepared self-healing cluster structures + * `epidemic`: Infection style clustering + * `service_discovery`: Service discovery types + * `mdns`: MDNS based service discovery + * `udp_anycast`: UDP Anycast based service discovery +(aka [Bastion](https://bastion.rs)'s core carrier protocol) + + + + + + + +## Distributed Data + +You might want to pass by the distributed configuration part and directly looking forward to have a distributed +data primitives. Like replicating your local map to some other instance's local map etc. + +This is where `Ddata` package kicks in. `Ddata` supplies the most basic distributed data dissemination at the highest abstraction level. + + + +* `artillery-ddata`: Used for distributed data replication + + + + + + + + +## Hierarchy Management + +This layer is specifically build for Bastion and it's distributed communication. +It contains a Hierarchy Management protocol. This protocol manages remote processes, links as well as their state. + + + +* `artillery-hierman`: Supervision hierarchy management layer + + + diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 3f94b85..0000000 --- a/docs/index.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - Document - - - - - - -
- - - -