Docs/usage documentation (#11)

* docs: initial usage documentation

* docs: add main framework documentation

* docs: add documentation for each service kind

Author: rsfreitas

README.md

@@ -14,10 +14,15 @@ standalone applications that execute its task and finishes.
 
 Currently, it has support for the following kind of applications:
 
-* gRPC: an application with an API defined from a [protobuf](https://protobuf.dev) file.
-* HTTP: an HTTP server-type application.
-* native: a general-purpose application, without a defined API, with the ability to execute any code for long periods
-* script: also a general-purpose application, without a defined API, but that only needs to execute a single function and stop.
+* [gRPC](docs/service_grpc.md): an application with an API defined from a [protobuf](https://protobuf.dev) file.
+* [HTTP](docs/service_http.md): an HTTP server-type application.
+* [native](docs/service_native.md): a general-purpose application, without a defined API, with the ability to execute any code for long periods
+* [script](docs/service_script.md): also a general-purpose application, without a defined API, but that only needs to execute a single function and stop.
+
+### Documentation
+
+A more detailed documentation about the framework API and its features can be
+accessed at the [docs](docs/mikros.md) directory.
 
 ### Service
 
@@ -125,6 +130,7 @@ using service definitions.
 * Enable features and services to use the same env system that the core uses.
 * Improve unit tests.
 * Full compatibility between go and rust gRPC services.
+* Allow using the service definitions file for custom service definitions.
 
 ## License
 

docs/mikros.md

@@ -0,0 +1,263 @@
+# mikros
+
+## Introduction
+
+Mikros is a rust framework to help writing services or applications following the
+same code structure and layout. It makes these applications demonstrate the same
+behavior and results. It requires that they be built following the same pattern.
+
+This way, it is possible to simply focus on the real problem that these applications
+are trying to solve and stop worrying about their layout.
+
+## Which problem mikros try to solve
+
+As stated earlier, the framework aims to remove all the complexity involved in
+building the structure of an application. Such as how and where to initialize
+dependent resources, structures for passing data, etc.
+
+Mikros imposes a format for initializing an application where the developer
+determines its category and its main functionalities. From there, the pieces
+just need to be fitted together, whether it is the handling of an RPC call
+from a gRPC service or a task to be executed by an HTTP service when a
+certain endpoint is triggered.
+
+## Usage
+
+Mikros is a rust crate, i.e., to be used inside rust projects is just like any
+common crate. One must add it as a dependency in the Cargo.toml file and its
+API should be available to be used.
+
+To work properly, the following steps can be used to write a new application
+with it:
+
+- create a `service.toml` file defining the service kind of the application;
+- implement the trait related to the chosen service kind;
+- initialize the API using the service implementation.
+
+Example: suppose you need an application that needs to run for an indefinite
+period of time, performing some type of task that cannot be stopped. For this,
+you can choose the **native** service kind to be used.
+
+First, create a new cargo project for binary applications:
+
+```bash
+cargo new native-service
+```
+
+Then, inside the new service directory, create the service definitions file.
+This is how it should look like:
+
+```toml
+name = "my-service-name"
+types = [ "native" ]
+version = "v0.1.0"
+language = "rust"
+product = "my-awesome-product"
+```
+
+Adjust the required dependencies inside the project **Cargo.toml** file by
+adding the following:
+
+- async-trait
+- mikros
+- tokio
+
+Inside the **main.rs** file, implement the following:
+
+- a structure that will implement the NativeService trait:
+
+```rust
+#[derive(Clone, Default)]
+pub struct AppService;
+
+#[async_trait::async_trait]
+impl mikros::service::native::NativeService for AppService {
+    async fn start(&self, ctx: &mikros::service::context::Context) -> mikros::errors::Result<()> {
+        // ctx is the mechanism to access mikros APIs and get the logger,
+        // environment variables, service definitions and access to features.
+        Ok(())
+    }
+
+    async fn stop(&self, ctx: &Context) {
+        // release some resource that the application is holding
+    }
+}
+```
+
+- if required to initialize some resource for the service, implement the Lifecycle
+trait:
+
+```rust
+#[async_trait::async_trait]
+impl mikros::service::lifecycle::Lifecycle for AppService {
+    async fn on_start(&mut self, ctx: &mikros::service::context::Context) -> mikros::errors::Result<()> {
+        // again, ctx can help access the mikros API and use it for initialize
+        // some custom internal service resource.
+        Ok(())
+    }
+
+    async fn on_finish(&self) -> mikros::errors::Result<()> {
+        Ok(())
+    }
+}
+```
+
+- initialize the service using mikros API:
+
+```rust
+#[tokio::main]
+async fn main() {
+    let s = AppService::default();
+    let svc = mikros::service::builder::ServiceBuilder::default()
+        .native(Box::new(s))
+        .build();
+
+    match svc {
+        Ok(mut svc) => svc.start().await,
+        Err(e) => panic!("{}", e.to_string()),
+    }
+}
+```
+
+The complete example can be found inside the [examples](../examples/apps/native) directory.
+
+### Service definitions file
+
+The service definitions file is a [TOML](https://toml.io/en/) file with information
+about the service.
+
+Its objective is, in addition to defining some important information for executing
+the application, some other information to assist possible deployment or monitoring
+tools.
+
+Its mandatory content is summarized in the following fields:
+
+- name: a string to set the application name
+- types: a string array defining the service kind, which can be more than one,
+as long as they have the same mode of execution (Block/NonBlock)
+- version: the application version
+- language: the programming language of the application
+- product: the product name to which the application belongs
+
+Optional fields:
+
+- envs: a string array of required environment variables for the service.
+
+Additionally, you can use this same file for the following types of definitions:
+
+- features: a map of feature definitions, to set custom features settings for
+the application.
+- services: a map of service definitions, to set custom service kind settings
+for the application.
+- clients: a map of client connection definitions, for dependent applications.
+
+Example:
+
+```toml
+name = "my-service-name"
+types = [ "native" ]
+version = "v0.1.0"
+language = "rust"
+product = "my-awesome-product"
+envs = [ "CUSTOM_ENV_1" ]
+
+[features.simple_api]
+enabled = true
+
+[clients.grpc]
+host = "localhost"
+port = 7071
+
+[services.cronjob]
+frequency = "daily"
+```
+
+### Environment variables
+
+Mikros has some environment variables that it uses to set custom information
+while the application is running. They are the following:
+
+| Name                       | Description                                                                                                              |
+|----------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| MIKROS_SERVICE_DEPLOY      | A string to set the current deployment server of the application, like (dev, stage, prod). Default: local                |
+| MIKROS_TRACKER_HEADER_NAME | A header name where the track ID will be located in HTTP requests/responses (not implemented yet). Default: X-Request-ID |
+| MIKROS_COUPLED_NAMESPACE   | The namespace where services/applications are running, to build the gRPC connection URL. Default: localhost              | 
+| MIKROS_COUPLED_PORT        | The default port for dependent gRPC services. Default: 7070                                                              |
+| MIKROS_GRPC_PORT           | Default listening port for gRPC applications. Default: 7070                                                              |
+| MIKROS_HTTP_PORT           | Default listening port for HTTP applications. Default: 8080                                                              |
+
+### The service structure
+
+Each service kind has its own trait that needs to be implemented in the application
+main structure and passed in the API initialization.
+
+A gRPC application depends on the declared API in the protobuf file. So the
+application must implement it.
+
+An HTTP application instead does not have a proper trait or API to implement. It
+depends on its endpoints, where each one should have a handler for it.
+
+### Lifecycle
+
+Lifecycle is a trait that an application can implement in its main structure to
+receive callbacks from the framework at specific execution points. Allowing it
+to handle them to execute custom tasks at these points. Like for example
+initialize connections with coupled gRPC services that it requires.
+
+Its declaration is the following:
+
+```rust
+#[async_trait::async_trait]
+pub trait Lifecycle: LifecycleClone + Send + Sync {
+    async fn on_start(&mut self, _ctx: &mikros::service::context::Context) -> mikros::errors::Result<()> {
+        Ok(())
+    }
+
+    async fn on_finish(&self) -> merrors::Result<()> {
+        Ok(())
+    }
+}
+```
+
+Notice that the trait already has default implementation, so the service can
+choose not to implement it.
+
+### Extending features
+
+Mikros does not provide any feature out-of-the-box, like cache, database and
+similar stuff. But it provides an API to allow implementing support for these
+and to access them using the same syntax inside applications.
+
+The trait [Feature](../src/plugin/feature.rs) shows an API that a feature
+should implement to be handled inside by the framework and provided to the
+applications. It has methods with the following characteristics:
+
+- provide the feature name and information to be registered while the application
+is initializing.
+- initialize itself and clean its resources.
+- a public API for applications to use it.
+
+For an example of how to implement, register and use external features you can
+check the [features](../examples/features) examples directory.
+
+### Extending service kind
+
+As mentioned before, mikros provides some kind of services that it implements
+inside and allows building applications with them. But if a specific kind of
+application (or service) is required by some solution, it also provides an API
+to allow implementing and to allow new kind of applications being built.
+
+The trait [Service](../src/plugin/service.rs) shows an API that a new service
+kind should implement to be supported by the framework, and, consequently, new
+applications.
+
+This API requires that the implementation provides information about the new
+service type such as:
+
+- its name and information to be registered while the application is initializing.
+- its execution mode (blocking or non-blocking).
+- and its implementation.
+
+The [services](../examples/services) directory shows an example of how to create
+a new service kind and the [cronjob](../examples/apps/cronjob_service) service
+shows how to register it and use it.

docs/service_grpc.md

@@ -0,0 +1,26 @@
+# gRPC services
+
+The gRPC service kind supported by the framework is the way to build applications
+capable of using the [gRPC](https://grpc.io) framework behind the scenes.
+
+This kind of application requires that its API to be defined using a [protobuf](https://protobuf.dev)
+spec file.
+
+Mikros uses [tonic](https://github.com/hyperium/tonic) rust gRPC implementation
+internally.
+
+In order to create a new service of this kind, the following steps can be used
+to help:
+
+- create the service protobuf file with its API.
+- inside the project directory, use [tonic_build](https://docs.rs/tonic-build/latest/tonic_build/)
+and with a **build.rs** source file, compile the protobuf to generate rust code
+from it.
+- implement the service by implementing its API in a structure and use mikros
+API to initialize the service.
+
+The examples directory has the following examples using the same steps described:
+
+* [grpc](../examples/apps/grpc): a gRPC service which implements its API.
+* [grpc with lifecycle](../examples/apps/grpc_with_lifecycle): a gRPC service
+that also implements the Lifecycle trait.

docs/service_http.md

@@ -0,0 +1,22 @@
+# HTTP services
+
+An HTTP Service is a web-based service designed to define and handle HTTP
+endpoints and routes. These services use the [axum](https://docs.rs/axum/latest/axum/)
+web framework to build flexible and efficient APIs.
+
+A mikros HTTP service requires that each router handler should have, at least,
+a [State](https://docs.rs/axum/latest/axum/#using-the-state-extractor) in its
+arguments. Like the following:
+
+```rust
+use mikros::http::ServiceState;
+
+async fn handler(State(state): State<Arc<Mutex<ServiceState>>>) -> String {
+    // state will provide access to the framework context, and if chosen, to
+    // a custom application internal state.
+    format!("Handler")
+}
+```
+
+The examples application directory contains different examples of how to implement
+an HTTP service using mikros.

docs/service_native.md

@@ -0,0 +1,19 @@
+# Native services
+
+A Native Service is a general-purpose application designed to execute any
+arbitrary code for extended periods. It does not rely on a defined API and
+is well-suited for tasks requiring flexible execution models.
+
+Native services implement the [NativeService](../src/service/native/mod.rs)
+trait to conform to the expected lifecycle and operational structure.
+
+This trait ensures the service adheres to a standard lifecycle and
+can be managed effectively within the broader application framework. It
+is composed of the following methods:
+
+- start: the place where the application is initialized and the main task
+is executed.
+- stop: the place to finish everything that was initialized before.
+
+For more details about how to implement a native service check the following
+[example](../examples/apps/native).

docs/service_script.md

@@ -0,0 +1,12 @@
+# Script services
+
+A script service is a general-purpose application designed for one-off tasks
+that execute a single function and then terminate. Unlike continuous services,
+script services are concise, focusing on completing a specific operation and
+performing any necessary cleanup afterward.
+
+To be a script service it must implement the [ScriptService](../src/service/script/mod.rs)
+trait to standardize their lifecycle behavior.
+
+For more details about how to implement a script service check the following
+[example](../examples/apps/script).

examples/features/example/src/lib.rs

@@ -59,4 +59,6 @@ impl ExampleAPI for Example {
     }
 }
 
+// Use this macro to export a public API equal for all features, allowing the
+// services to use the same syntax while accessing them.
 impl_feature_public_api!(ExampleAPI, Example, "example");

examples/features/simple_api/src/lib.rs

@@ -79,4 +79,6 @@ impl ExampleAPI for Example {
     }
 }
 
+// Use this macro to export a public API equal for all features, allowing the
+// services to use the same syntax while accessing them.
 impl_feature_public_api!(ExampleAPI, Example, "simple_api");