READMEs updates (#90)

* domain - README update

* sentry - README - add file and move text from main README

* README - update README and add the additional crates info

* adapter - README

* .env.dist - update

* validator - README

* README - update

Author: elpiel

.env.dist

@@ -1,3 +1,6 @@
+DATABASE_URL=postgresql://postgres:docker@localhost:5432/sentry
 SENTRY_CHANNEL_LIST_LIMIT=200
 
-VALIDATOR_TICKS_WAIT_TIME=500
+VALIDATOR_TICKS_WAIT_TIME=500
+VALIDATOR_SENTRY_URL=http://localhost:8005
+VALIDATOR_VALIDATION_TICK_TIMEOUT=5000

README.md

@@ -8,7 +8,11 @@ Components:
 
 * Domain crate
 * Sentry - check the list of [opened issues](https://github.com/AdExNetwork/adex-validator-stack-rust/issues?q=is:open is:issue project:AdExNetwork/adex-validator-stack-rust/1)
-* Validator worker - TODO
+* Validator worker - The validator worker(`Leader` or `Follower`) that validates/proposes new states.
+* memory-repository - Generic helper crate for creating InMemory repositories for testing.
+* adapter - Adapter trait for `sign`, `verify` and `validate_channel` with Dummy implementation for testing.
+
+**Note:** Please refer to the README.md of the component for a more detailed overview of it.
 
 ## Domain
 Contains all the Domain `Aggregates`, `Entities`, `Value Objects`, interfaces (traits) and `Domain Error`.
@@ -18,23 +22,19 @@ All the structs have defined (de)serialization. The also have incorporated domai
 `TargetingTag.score` (the `Score` struct) should be with a value between `0` and `100`.
 This means that once we have a `Score` object, we are guaranteed to have a valid object everywhere.
 
-The `Repository` traits are meant for retrieving the underlying object types, this includes implementations with
-Databases (like `Postgres` for `Sentry`), API calls (for the `Validator` to fetch the objects from `Sentry`),
-memory (for testing) and etc.
-
-## Sentry: API
-
-#### Do not require authentication, can be cached:
-
-The API documentation can be found on the [adex-validator](https://github.com/AdExNetwork/adex-validator/blob/master/docs/api.md).
-Currently implemented endpoints:
+The `Repository` traits are meant to help you create the correct abstractions in the underlying application,
+as every application has different requirements for the way and things it will fetch.
 
-- POST `/channel` - creates a new channel
-- GET `/channel/list` - get a list of all channels
+## Sentry & Validator worker
 
-## Validator worker
-
-TODO
+Split into 3 layer - Domain, Infrastructure & Application.
+- Domain - the domain objects/structs that are defining the business rules and constraints.
+- Infrastructure - specific implementations of e.g. Repositories, Logging and etc.
+like `Memory__Repository`, `Api__Repository` and so on.
+- Application - all the application specific logic, which means services, structs and etc. that use the Domain and it's
+traits to achieve the task at hand. For example: In sentry we have the `resource`s, there we define the
+`channel_create`. Which handles the request, validates it and uses the `ChannelRepository` trait to
+`add` the new Channel and returns the appropriate Response. It is not however limited to Request -> Response.
 
 ## Testing setup
 
@@ -57,10 +57,37 @@ We've setup `rust-toolchain` but you can manually override it as well with `rust
 
 `DATABASE_URL=postgresql://postgres:docker@localhost:5432/sentry cargo run --bin sentry`
 
+### Run Validator Worker
+
+`cargo run --bin validator`
+
+For the available options:
+
+`cargo run --bin validator -- --help`
+
 #### Environment variables:
 
+**NOTE: Currently we use `.env` file to define values for those environment variables.
+We need to see if we want configuration files per binary instead.**
+
+##### Sentry: 
 - `DATABASE_URL` - The url of the Postgres database used for production.
+- `SENTRY_CHANNEL_LIST_LIMIT` - the limit per page for listing channels from the `/channel/list` request.
+
+##### Validator:
+- `VALIDATOR_TICKS_WAIT_TIME` - The time for a whole cycle(tick) of the validator worker to get & loop channels,
+validate and send statuses and etc.
+- `VALIDATOR_SENTRY_URL` - The url of the Sentry API that should be used
+- `VALIDATOR_VALIDATION_TICK_TIMEOUT` - The maximum time for validation of a single channel as a `Leader` or `Follower`
+
+## Development environment
+
+We use [cargo-make](https://github.com/sagiegurari/cargo-make) for running the checks and build project locally
+as well as on CI. For a complete list of out-of-the-box commands you can check
+[Makefile.stable.toml](https://github.com/sagiegurari/cargo-make/blob/master/src/lib/Makefile.stable.toml).
 
-**NOTE: For development & testing purposes we use `.env` file to define values for those environment variables.**
+Locally it's enough to ensure that `cargo make` command (it will execute the default dev. command) is passing.
+It will run `rustfmt` for you, it will fail on `clippy` warnings and it will run all the tests.
 
-- `CHANNEL_LIST_LIMIT` - the limit per page for listing channels from the `/channel/list` request.
+You can related to the [Makefile.stable.toml](https://github.com/sagiegurari/cargo-make/blob/master/src/lib/Makefile.stable.toml)
+for more commands and cargo-make as a whole.

adapter/README.md

@@ -0,0 +1,13 @@
+# Adapter crate
+
+Adapter trait and a DummyAdapter implementation for testing.
+It is checking the "sanity" of a channel by checking some rules we have in order for a Channel to
+be valid (`validate_channel()`).
+The Adapter can also `sign()` and `validate()` `StateRoot`s and can provide the Authentication by which
+it can be recognized.
+
+## Features
+
+### DummyAdapter (`dummy-adapter`)
+
+When you enable this feature you get an access to the DummyAdapter implementation, which you can use for testing.

domain/README.md

@@ -1,18 +1,22 @@
 # `Domain` crate for validator/sentry stack
 
 This crate is meant to hold all Domain structures required for both the Validator and Sentry.
-It defines all the structs(Entities, Value Objects and etc.) and Repository traits and Domain errors.
+It defines all the structs(Entities, Value Objects and etc.), Domain errors and the generic Repository
+types and Errors.
 It also defines the serialization and deserialization of them.
-The actual implementations of Repositories is left to the underlying usage, whether it is
-using Postgres, some sort of Memory implementation and etc.
+
+The Repository traits and the actual implementations of them is left to the underlying usage.
+The traits can have different interfaces based on the requirements of the application and can have
+different implementation based on the needs, whether this is: Postgres, InMemory, RestAPI and etc. implementations.
 
 ### Features:
 
 #### Repositories
 
 If the usage of this crate, requires not only (de)serialization, but also retrieving or storing
-the objects in any way (database, API calls, memory and etc.) you would need this feature, as it defines
-the Repository traits that should be implemented, as a common interface, for handling such operations.
+the objects in any way (database, API calls, memory and etc.) you would need this feature, to use
+the generic types and traits to define the underling Repository interfaces for the domain objects
+and implementations.
 
 The trait `RepositoryFuture` with a generic `RepositoryError` is used as the common return type for
 repository methods.
@@ -26,7 +30,8 @@ There is also the `domain::test_util` module that gives you some handy functions
 for usage in tests:
 
 - `take_one` which gives you a random element from a slice.
-
+- `time::datetime_between`
+- `time::past_datetime`
 
 ### Utils
 

sentry/README.md

@@ -0,0 +1,11 @@
+# Sentry RestAPI
+
+## Endpoints:
+
+#### Do not require authentication, can be cached:
+
+The API documentation can be found on the [adex-validator](https://github.com/AdExNetwork/adex-validator/blob/master/docs/api.md).
+Currently implemented endpoints:
+
+- POST `/channel` - creates a new channel
+- GET `/channel/list` - get a list of all channels

validator/README.md

@@ -0,0 +1,16 @@
+# Validator worker
+
+For more information on the possible options on the binary please run:
+
+`cargo run --bin validator -- --help`
+
+The default mode is running the validator in infinite tick mode, basically constantly waiting and never finishing.
+
+It is possible to run it in single tick mode with the `-s` option
+
+Currently you can run the Validator worker only with DummyAdapter as we do not have any other implementations.
+
+The DummyAdapter requires you to specify the Identity that will be used for the adapter in the form of a string.
+You can still pass `-s` for single tick mode.
+
+For tracking issue on the options and the configuration of the validator refer to issue [#68](https://github.com/AdExNetwork/adex-validator-stack-rust/issues/68)