docs(meta/errors): explain relationship between various error types in meta-store

- Refacotr: move meta-related error into `errors` mod.

Defines meta-store errors and meta-store application errors.

Error relations

The overall relations between errors defined in meta-store components are:

```text

KVAppError
|
+- AppError ------> TableNotFound
|                   DbExists
|                   ...
`- MetaError
   |
   +-  MetaStorageError
   |
   +-  MetaClientError
   |   |
   |   +- MetaNetworkError
   |   +- HandshakeError
   |
   +-  MetaNetworkError
   |
   `-  MetaApiError
       |
       +- ForwardToLeader -.
       +- CanNotForward    |
       |                   |
       +- MetaNetworkError |
       |                   |
       +- MetaDataError ---|-----------.
       |                   |           |
       `- RemoteError   ---|-----------+
                           |           |
                           |           |
                           |           |     MetaOperationError
                           | .---------|----------'  |
                           | |         |  .----------'
                           v v         v  v
                   ForwardToLeader  MetaDataError
                                       |  |
                       .---------------'  '---------.
                       v                            v
          MetaDataReadError                       Raft*Error
          |                                       |
          +- MetaStorageError                     +- MetaStorageError
```

Bottom level errors:

Bottom level errors are derived from non-meta-store layers.

- `MetaStorageError`
- `MetaNetworkError`
- `MetaBytesError`

```text
MetaNetworkError
|
+- Connection errors
+- DNS errors
`- Payload codec error

MetaStorageError
|
+- Sled errors
+- Txn conflict
`- Codec error:--.
                 |
                 v
           MetaBytesError
```

Application level errors

Application level errors(`KVAppError`) are defined for meta-store application, e.g.,
`SchemaApi`, `ShareApi` etc. An application error has two main sub error: meta-store related or
application related:
- `KVAppError::MetaError` is error raised from inside meta-store and an application can do
  nothing about it. It includes all errors that meta-store might return.
- `KVAppError::AppError` are application specific errors, such as `TableNotFound`, `DbExists`.
  These errors should be dealt with by an application correctly.

`MetaError`

`MetaError` defines every error could occur inside a meta-store implementation(an embedded meta-store
or a client-server meta-store service).
The sub errors are about both a local implementation and a remote meta-store implementation:

For a remote meta-store service:

- `MetaClientError`: is only returned with remote meta-store service: when creating a client to
  meta-store service. Since a client will send a handshake request, `MetaClientError` also
  includes a network sub error: `MetaNetworkError`.

- `MetaNetworkError` is only returned with remote meta-store service: when sending a request to
a remote meta-store service.

- `MetaApiError` is only returned with remote meta-store service: it is all of the errors that
  could occur when a meta-store service handling a request.

For a local meta-store:

- `MetaStorageError`: meta-store is implemented directly upon storage layer.

`MetaApiError`

`MetaApiError` is defined for meta-store service RPC API handler:
It includes Raft related errors and errors that occurs when forwarding a request between
meta-store servers:

- Errors informing request forwarding state:: `ForwardToLeader` or `CanNotForward`.
- Errors occurs when forwarding a request: `MetaNetworkError`.
- Errors occurs when reading/writing: `MetaDataError`. Because a request may be dealt with
  locally or dealt with remotely, via request forwarding, there are two variants for
  `MetaDataError`:
  - `MetaApiError::MetaDataError(MetaDataError)` is returned when a request is dealt with locally.
  - `MetaApiError::RemoteError(MetaDataError)` is returned when a request is dealt with on a
    remote noMetaDataError.

`MetaDataError`

It is the error that could occur when dealing with read/write request.

In meta-store, data is written through Raft protocol, thus part of its sub errors are Raft
related: `RaftWriteError` or `RaftChangeMembershipError`.

In meta-store reading data does not depend on Raft protocol, thus read errors is defined as
`MetaDataReadError` and is derived directly from MetaStorageError.

Other errors:

- `MetaOperationError` is a intermediate error and a subset error of `MetaApiError` and is
  defined for a local request handler without forwarding. It is finally converted to `MetaApiError`.

- `ForwardRPCError` is another intermediate error to wrap a result of a forwarded request.

- Fix: #7689

Author: drmingdrmer

src/meta/api/src/schema_api_impl.rs

@@ -77,27 +77,27 @@ use common_meta_app::share::ShareGrantObject;
 use common_meta_app::share::ShareGrantObjectPrivilege;
 use common_meta_app::share::ShareId;
 use common_meta_app::share::ShareNameIdent;
-use common_meta_types::app_error::AppError;
-use common_meta_types::app_error::CreateDatabaseWithDropTime;
-use common_meta_types::app_error::CreateTableWithDropTime;
-use common_meta_types::app_error::DatabaseAlreadyExists;
-use common_meta_types::app_error::DropDbWithDropTime;
-use common_meta_types::app_error::DropTableWithDropTime;
-use common_meta_types::app_error::ShareHasNoGrantedDatabase;
-use common_meta_types::app_error::ShareHasNoGrantedPrivilege;
-use common_meta_types::app_error::TableAlreadyExists;
-use common_meta_types::app_error::TableVersionMismatched;
-use common_meta_types::app_error::TxnRetryMaxTimes;
-use common_meta_types::app_error::UndropDbHasNoHistory;
-use common_meta_types::app_error::UndropDbWithNoDropTime;
-use common_meta_types::app_error::UndropTableAlreadyExists;
-use common_meta_types::app_error::UndropTableHasNoHistory;
-use common_meta_types::app_error::UndropTableWithNoDropTime;
-use common_meta_types::app_error::UnknownShareAccounts;
-use common_meta_types::app_error::UnknownTable;
-use common_meta_types::app_error::UnknownTableId;
-use common_meta_types::app_error::WrongShare;
-use common_meta_types::app_error::WrongShareObject;
+use common_meta_types::errors::app_error::AppError;
+use common_meta_types::errors::app_error::CreateDatabaseWithDropTime;
+use common_meta_types::errors::app_error::CreateTableWithDropTime;
+use common_meta_types::errors::app_error::DatabaseAlreadyExists;
+use common_meta_types::errors::app_error::DropDbWithDropTime;
+use common_meta_types::errors::app_error::DropTableWithDropTime;
+use common_meta_types::errors::app_error::ShareHasNoGrantedDatabase;
+use common_meta_types::errors::app_error::ShareHasNoGrantedPrivilege;
+use common_meta_types::errors::app_error::TableAlreadyExists;
+use common_meta_types::errors::app_error::TableVersionMismatched;
+use common_meta_types::errors::app_error::TxnRetryMaxTimes;
+use common_meta_types::errors::app_error::UndropDbHasNoHistory;
+use common_meta_types::errors::app_error::UndropDbWithNoDropTime;
+use common_meta_types::errors::app_error::UndropTableAlreadyExists;
+use common_meta_types::errors::app_error::UndropTableHasNoHistory;
+use common_meta_types::errors::app_error::UndropTableWithNoDropTime;
+use common_meta_types::errors::app_error::UnknownShareAccounts;
+use common_meta_types::errors::app_error::UnknownTable;
+use common_meta_types::errors::app_error::UnknownTableId;
+use common_meta_types::errors::app_error::WrongShare;
+use common_meta_types::errors::app_error::WrongShareObject;
 use common_meta_types::ConditionResult;
 use common_meta_types::GCDroppedDataReply;
 use common_meta_types::GCDroppedDataReq;

src/meta/api/src/share_api_impl.rs

@@ -21,15 +21,15 @@ use common_meta_app::schema::TableIdToName;
 use common_meta_app::schema::TableMeta;
 use common_meta_app::schema::TableNameIdent;
 use common_meta_app::share::*;
-use common_meta_types::app_error::AppError;
-use common_meta_types::app_error::ShareAccountsAlreadyExists;
-use common_meta_types::app_error::ShareAlreadyExists;
-use common_meta_types::app_error::TxnRetryMaxTimes;
-use common_meta_types::app_error::UnknownShare;
-use common_meta_types::app_error::UnknownShareAccounts;
-use common_meta_types::app_error::UnknownTable;
-use common_meta_types::app_error::WrongShare;
-use common_meta_types::app_error::WrongShareObject;
+use common_meta_types::errors::app_error::AppError;
+use common_meta_types::errors::app_error::ShareAccountsAlreadyExists;
+use common_meta_types::errors::app_error::ShareAlreadyExists;
+use common_meta_types::errors::app_error::TxnRetryMaxTimes;
+use common_meta_types::errors::app_error::UnknownShare;
+use common_meta_types::errors::app_error::UnknownShareAccounts;
+use common_meta_types::errors::app_error::UnknownTable;
+use common_meta_types::errors::app_error::WrongShare;
+use common_meta_types::errors::app_error::WrongShareObject;
 use common_meta_types::ConditionResult::Eq;
 use common_meta_types::KVAppError;
 use common_meta_types::TxnCondition;

src/meta/api/src/util.rs

@@ -20,13 +20,13 @@ use common_meta_app::schema::DatabaseMeta;
 use common_meta_app::schema::DatabaseNameIdent;
 use common_meta_app::schema::TableNameIdent;
 use common_meta_app::share::*;
-use common_meta_types::app_error::AppError;
-use common_meta_types::app_error::ShareHasNoGrantedDatabase;
-use common_meta_types::app_error::UnknownDatabase;
-use common_meta_types::app_error::UnknownShare;
-use common_meta_types::app_error::UnknownShareAccounts;
-use common_meta_types::app_error::UnknownShareId;
-use common_meta_types::app_error::UnknownTable;
+use common_meta_types::errors::app_error::AppError;
+use common_meta_types::errors::app_error::ShareHasNoGrantedDatabase;
+use common_meta_types::errors::app_error::UnknownDatabase;
+use common_meta_types::errors::app_error::UnknownShare;
+use common_meta_types::errors::app_error::UnknownShareAccounts;
+use common_meta_types::errors::app_error::UnknownShareId;
+use common_meta_types::errors::app_error::UnknownTable;
 use common_meta_types::txn_condition::Target;
 use common_meta_types::txn_op::Request;
 use common_meta_types::ConditionResult;

src/meta/app/src/share/share.rs

@@ -20,8 +20,8 @@ use std::fmt::Formatter;
 
 use common_datavalues::chrono::DateTime;
 use common_datavalues::chrono::Utc;
-use common_meta_types::app_error::AppError;
-use common_meta_types::app_error::WrongShareObject;
+use common_meta_types::errors::app_error::AppError;
+use common_meta_types::errors::app_error::WrongShareObject;
 use common_meta_types::KVAppError;
 use enumflags2::bitflags;
 use enumflags2::BitFlags;

src/meta/types/src/app_error.rs renamed to src/meta/types/src/errors/app_error.rs

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+use common_exception::ErrorCode;
 use serde::Deserialize;
 use serde::Serialize;
 use thiserror::Error;
@@ -39,3 +40,21 @@ pub enum MetaError {
 }
 
 pub type MetaResult<T> = Result<T, MetaError>;
+
+impl From<MetaError> for ErrorCode {
+    fn from(e: MetaError) -> Self {
+        match e {
+            MetaError::NetworkError(net_err) => net_err.into(),
+            MetaError::StorageError(sto_err) => sto_err.into(),
+            MetaError::ClientError(ce) => ce.into(),
+            MetaError::APIError(e) => e.into(),
+        }
+    }
+}
+
+impl From<tonic::Status> for MetaError {
+    fn from(status: tonic::Status) -> Self {
+        let net_err = MetaNetworkError::from(status);
+        MetaError::NetworkError(net_err)
+    }
+}