docs: added the documentation for APIs overview and created CONSISTEN…

…CY.md (#62)

* docs: added the documentation for APIs overview

* docs: created the CONSISTENCY.md

CONSISTENCY.md file contains the read consistency level in casbin-mesh.
Closes : #44

CONSISTENCY.md

@@ -0,0 +1,55 @@
+ # Read Consistency
+
+The Enforce function in the struct handles enforcing policies in casbin-mesh. It does this by checking the read consistency level passed in the request and determining how to execute the enforcement accordingly. The read consistency levels are QUERY_REQUEST_LEVEL_NONE, QUERY_REQUEST_LEVEL_WEAK, and QUERY_REQUEST_LEVEL_STRONG.
+
+## None
+
+In casbin-mesh, the QUERY_REQUEST_LEVEL_NONE read consistency level indicates that the Enforce request will be handled by the local node without regard to whether the node is the leader or not, and without checking for staleness. This offers the fastest query response, but results may be stale if the node has fallen behind the leader in terms of updates to its underlying database, or if the node is no longer part of the cluster and has stopped receiving updates.
+
+You can use the QUERY_REQUEST_LEVEL_NONE read consistency level by setting the level field in the EnforceRequest message to QUERY_REQUEST_LEVEL_NONE when making the Enforce RPC call.
+
+```bash
+
+result, err := s.Core.Enforce(ctx, request.GetNamespace(), int32(request.Payload.GetLevel()), request.Payload.GetFreshness(), params...)
+
+```
+Here, the level field in the EnforceRequest message determines the read consistency level that will be used for the Enforce request. In this case, if level is set to QUERY_REQUEST_LEVEL_NONE, the Enforce request will be handled by the local node without regard to its role (leader or follower) or staleness.
+
+Explicitly selecting this read consistency level can be done by setting the level field in the EnforceRequest message of the gRPC request to QUERY_REQUEST_LEVEL_NONE. This can be seen in the following example:
+```bash
+request := &command.EnforceRequest{
+  Namespace: "my-namespace",
+  Payload: &command.EnforcePayload{
+    Level: command.EnforcePayload_QUERY_REQUEST_LEVEL_NONE,
+    // other fields...
+  },
+}
+response, err := client.Enforce(context.Background(), request)
+
+```
+## Weak
+
+The QUERY_REQUEST_LEVEL_WEAK read consistency level is used to ensure that read requests are served by the Leader node in the Raft cluster. This is done to ensure that the returned results are not stale, meaning that they are up-to-date and reflect the current state of the database.
+
+When a read request is made with the QUERY_REQUEST_LEVEL_WEAK read consistency level, the casbin-mesh node serving the request will check if it is the Leader node in the Raft cluster. If it is not the Leader, the request will return an error indicating that it is not the Leader and cannot serve the request. This ensures that the returned results are not stale and reflect the current state of the database.
+
+Explicitly selecting this read consistency level can be done by setting the level field in the EnforceRequest message of the gRPC request to QUERY_REQUEST_LEVEL_WEAK. This can be seen in the following example:
+```bash
+request := &command.EnforceRequest{
+  Namespace: "my-namespace",
+  Payload: &command.EnforcePayload{
+    Level: command.EnforcePayload_QUERY_REQUEST_LEVEL_WEAK,
+    // other fields...
+  },
+}
+response, err := client.Enforce(context.Background(), request)
+
+```
+
+## Strong
+
+The QUERY_REQUEST_LEVEL_STRONG is the highest level of read consistency. When this level is used, the request will be sent to the leader node to execute. The leader node will then replicate the request to the other nodes in the cluster and wait for a quorum of nodes to acknowledge the request before returning the result to the client. This ensures that the result returned to the client reflects the most up-to-date state of the database.
+
+However, using QUERY_REQUEST_LEVEL_STRONG can result in slower performance because the request has to be replicated to multiple nodes and a quorum of nodes must acknowledge the request before it can be completed. This level is useful in scenarios where the most up-to-date result is required and it is acceptable to trade off some performance for stronger consistency.
+
+It is also worth noting that QUERY_REQUEST_LEVEL_STRONG is the default level when the read consistency is not explicitly specified by the client.

README.md

@@ -155,9 +155,9 @@ The response:
 ["test"]
 ```
 
-### Add Polices
+### Add Policies
 
-Let's add policies for the `test` namespace. See more of [Polcies]()
+Let's add policies for the `test` namespace. See more of [Policies]()
 
 ```bash
 $ curl --location --request GET 'http://localhost:4002/add/policies' \
@@ -204,6 +204,59 @@ The answer is yes:
 
 # Documentation
 
+## APIs Overview
+
+### HTTP Endpoints
+
+HTTP endpoints for managing the namespaces and policies in casbin-mesh:
+
+- /create/namespace: to create a new namespace.
+- /list/namespaces: to list all existing namespaces.
+- /print/model: to print the model for a given namespace.
+- /list/policies: to list all policies for a given namespace.
+- /set/model: to set the model for a given namespace.
+- /add/policies: to add policies to a given namespace.
+- /remove/policies: to remove policies from a given namespace.
+- /remove/filtered_policies: to remove policies matching a filter from a given namespace.
+- /update/policies: to update policies in a given namespace.
+- /clear/policy: to clear all policies from a given namespace.
+- /enforce: to enforce a policy for a given namespace.
+- /stats: to get statistics for a given namespace.
+
+### gRPC Endpoints
+
+gRPC endpoints for managing the namespaces and policies in casbin-mesh:
+
+- Enforce: to enforce a policy for a given namespace.
+- CreateNamespace: to create a new namespace.
+- SetModelFromString: to set the model for a given namespace.
+- AddPolicies: to add policies to a given namespace.
+- RemovePolicies: to remove policies from a given namespace.
+- RemoveFilteredPolicy: to remove policies matching a filter from a given namespace.
+- UpdatePolicies: to update policies in a given namespace.
+- ClearPolicy: to clear all policies from a given namespace.
+- PrintModel: to print the model for a given namespace.
+- ListPolicies: to list all policies for a given namespace.
+
+### gRPC API Reference for the Command Service
+
+The casbin-mesh service has the following methods:
+
+- ShowStats: This method take a StatsRequest message and returns a StatsResponse message. It can be used to retrieve statistical information about the Casbin system.
+- ListNamespaces: This method takes a ListNamespacesRequest message and returns a ListNamespacesResponse message. It can be used to list all the namespaces in the       Casbin system.
+- PrintModel: This method takes a PrintModelRequest message and returns a PrintModelResponse message. It can be used to retrieve the model of a specific namespace in     the Casbin system.
+- ListPolicies: This method takes a ListPoliciesRequest message and returns a ListPoliciesResponse message. It can be used to list all the policies in a specific         namespace in the Casbin system.
+- Request: This method takes a Command message and returns a Response message. It can be used to send various commands to the Casbin system.
+- Enforce: This method takes an EnforceRequest message and returns an EnforceResponse message. It can be used to check if a request is authorized or not.
+- The StatsRequest, ListNamespacesRequest, PrintModelRequest, and ListPoliciesRequest messages are all empty. They only serve as a placeholder for metadata that can be   added to the request.
+- The StatsResponse, PrintModelResponse, and ListPoliciesResponse messages all contain a payload field that can be used to pass back additional information.
+- The ListNamespacesResponse message contains a list of namespaces in the namespace field.
+- The Command message is used to send various commands to the Casbin system. It has a type field that specifies the type of command being sent, a namespace field that   specifies the namespace the command should be applied to, a payload field that contains additional data for the command, and a metadata field that can be used to       pass metadata along with the command.
+- The EnforceRequest message is used to request authorization for a specific action. It has a namespace field that specifies the namespace to check the authorization     in, an enforce_payload field that contains the details of the request, and a metadata field that can be used to pass metadata along with the request.
+- The EnforceResponse message is used to respond to an EnforceRequest. It has an ok field that specifies if the request is authorized or not.
+
+
+
 All documents were located in [docs](/docs) directory.
 
 # License