Skip to content

Commit ddfca5d

Browse files
drmingdrmerdrmingdrmer
authored
chore: Update meta-service gRPC version spec and raft-protocol feature set (#15398)
There is no change in this commit but just update the doc about what features are provided by raft-API, and the doc about version spec of gRPC-API.
1 parent 51065f3 commit ddfca5d

File tree

3 files changed

+63
-57
lines changed

3 files changed

+63
-57
lines changed

‎src/meta/README.md

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -75,17 +75,23 @@ To add a new feature(add new type or update an type), the developer should do:
7575

7676
## Compatibility with Databend Query
7777

78-
The following is an illustration of current query-meta compatibility:
79-
80-
| `Meta\Query` | [0.7.59, 0.8.80) | [0.8.80, 0.9.41) | [0.9.41, 1.1.34) | [1.1.34, 1.2.287) | [1.2.287, +∞) |
81-
|:------------------|:-----------------|:-----------------|:-----------------|:---------------|:-----------|
82-
| [0.8.30, 0.8.35) | ✅ | ❌ | ❌ | ❌ | ❌ |
83-
| [0.8.35, 0.9.23) | ✅ | ✅ | ✅ | ❌ | ❌ |
84-
| [0.9.23, 0.9.42) | ❌ | ✅ | ✅ | ❌ | ❌ |
85-
| [0.9.42, 1.1.32) | ❌ | ❌ | ✅ | ❌ | ❌ |
86-
| [1.1.32, 1.2.63) | ❌ | ❌ | ✅ | ✅ | ❌ |
87-
| [1.2.63, 1.2.226) | ❌ | ❌ | ✅ | ✅ | ❌ |
88-
| [1.2.226, +∞) | ❌ | ❌ | ✅ | ✅ | ✅ |
78+
The following is an illustration of the latest query-meta compatibility:
79+
80+
| `Meta\Query` | [0.9.41, 1.1.34) | [1.1.34, 1.2.287) | [1.2.287, 1.2.361) | [1.2.361, +∞) |
81+
|:-------------------|:-----------------|:---------------|:-----------|:-----------|
82+
| [0.8.30, 0.8.35) | ❌ | ❌ | ❌ |❌ |
83+
| [0.8.35, 0.9.23) | ✅ | ❌ | ❌ |❌ |
84+
| [0.9.23, 0.9.42) | ✅ | ❌ | ❌ |❌ |
85+
| [0.9.42, 1.1.32) | ✅ | ❌ | ❌ |❌ |
86+
| [1.1.32, 1.2.63) | ✅ | ✅ | ❌ |❌ |
87+
| [1.2.63, 1.2.226) | ✅ | ✅ | ❌ |❌ |
88+
| [1.2.226, 1.2.258) | ✅ | ✅ | ✅ |❌ |
89+
| [1.2.258, +∞) | ✅ | ✅ | ✅ |✅ |
90+
91+
History versions that are not included in the above chart:
92+
93+
- Query `[0.7.59, 0.8.80)` is compatible with Meta `[0.8.30, 0.9.23)`.
94+
- Query `[0.8.80, 0.9.41)` is compatible with Meta `[0.8.35, 0.9.42)`.
8995

9096

9197
## Compatibility between databend-meta

‎src/meta/client/src/lib.rs

Lines changed: 29 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,6 @@ pub use grpc_client::MetaChannelManager;
3636
pub use grpc_client::MetaGrpcClient;
3737
pub use message::ClientWorkerRequest;
3838
pub use message::Streamed;
39-
use semver::BuildMetadata;
40-
use semver::Prerelease;
4139
use semver::Version;
4240

4341
pub static METACLI_COMMIT_SEMVER: LazyLock<Version> = LazyLock::new(|| {
@@ -65,48 +63,48 @@ pub static METACLI_COMMIT_SEMVER: LazyLock<Version> = LazyLock::new(|| {
6563
/// `read_msg/write_msg` to `kv_api`
6664
///
6765
/// - 2023-02-16: since 0.9.41:
68-
/// Meta client add `Compatible` layer to accept KVAppError or MetaAPIError
66+
/// 👥 client add `Compatible` layer to accept KVAppError or MetaAPIError
6967
///
7068
/// - 2023-02-17: since 0.9.42:
71-
/// Meta service only responds with MetaAPIError.
69+
/// 🖥 server only responds with MetaAPIError.
7270
///
7371
/// - 2023-05-07: since 1.1.32:
74-
/// Meta service: add: TxnDeleteRequest provides a `match_seq` field to delete a record if its `seq` matches.
72+
/// 🖥 server: add: TxnDeleteRequest provides a `match_seq` field to delete a record if its `seq` matches.
7573
///
7674
/// - 2023-10-11: since 1.2.153:
77-
/// Meta service: add: pb::SeqV.meta field to support record expiration.
75+
/// 🖥 server: add: pb::SeqV.meta field to support record expiration.
7876
///
7977
/// - 2023-10-17: since 1.2.163:
80-
/// Meta service: add: stream api: kv_read_v1().
78+
/// 🖥 server: add: stream api: kv_read_v1().
8179
///
8280
/// - 2023-10-20: since 1.2.176:
83-
/// Meta client: call stream api: kv_read_v1(), revert to 1.1.32 if server < 1.2.163
81+
/// 👥 client: call stream api: kv_read_v1(), revert to 1.1.32 if server < 1.2.163
8482
///
8583
/// - 2023-12-16: since 1.2.258:
86-
/// Meta service: add: ttl to TxnPutRequest and Upsert
84+
/// 🖥 server: add: ttl to TxnPutRequest and Upsert
8785
///
8886
/// - 2024-01-02: since 1.2.279:
89-
/// Meta client: remove `Compatible` for KVAppError and MetaAPIError, added in `2023-02-16: since 0.9.41`
87+
/// 👥 client: remove `Compatible` for KVAppError and MetaAPIError, added in `2023-02-16: since 0.9.41`
9088
///
9189
/// - 2024-01-07: since 1.2.287:
92-
/// client: remove calling RPC kv_api() with MetaGrpcReq::GetKV/MGetKV/ListKV, kv_api only accept Upsert;
93-
/// client: remove using MetaGrpcReq::GetKV/MGetKV/ListKV;
94-
/// client: remove falling back kv_read_v1(Streamed(List)) to kv_api(List), added in `2023-10-20: since 1.2.176`;
90+
/// 👥 client: remove calling RPC kv_api() with MetaGrpcReq::GetKV/MGetKV/ListKV, kv_api only accept Upsert;
91+
/// 👥 client: remove using MetaGrpcReq::GetKV/MGetKV/ListKV;
92+
/// 👥 client: remove falling back kv_read_v1(Streamed(List)) to kv_api(List), added in `2023-10-20: since 1.2.176`;
9593
///
9694
/// - 2024-01-17: since 1.2.304:
97-
/// server: do not use TxnPutRequest.prev_value;
98-
/// server: do not use TxnDeleteRequest.prev_value;
99-
/// Always return the previous value;
100-
/// field index is reserved, no compatibility changes.
95+
/// 🖥 server: do not use TxnPutRequest.prev_value;
96+
/// 🖥 server: do not use TxnDeleteRequest.prev_value;
97+
/// Always return the previous value;
98+
/// field index is reserved, no compatibility changes.
10199
///
102100
/// - 2024-01-25: since 1.2.315:
103-
/// server: add export_v1() to let client specify export chunk size;
101+
/// 🖥 server: add export_v1() to let client specify export chunk size;
104102
///
105103
/// - 2024-03-01: since: 1.2.358:
106-
/// server: add `server_time` to `get_client_info() -> ClientInfo`,
104+
/// 🖥 server: add `server_time` to `get_client_info() -> ClientInfo`,
107105
///
108-
/// - 2024-03-01: since: TODO(update me when merged):
109-
/// client: `MetaSpec` use `ttl`, remove `expire_at`, require 1.2.258
106+
/// - 2024-03-04: since: 1.2.361
107+
/// 👥 client: `MetaSpec` use `ttl`, remove `expire_at`, require 1.2.258
110108
///
111109
/// Server feature set:
112110
/// ```yaml
@@ -115,21 +113,16 @@ pub static METACLI_COMMIT_SEMVER: LazyLock<Version> = LazyLock::new(|| {
115113
/// pb_seqv_meta: ["2023-10-11", "1.2.153", ]
116114
/// kv_read_v1: ["2023-10-17", "1.2.163", ]
117115
/// ```
118-
pub static MIN_METASRV_SEMVER: Version = Version {
119-
major: 1,
120-
minor: 2,
121-
// The binary in the https://github.com/datafuselabs/databend/releases/tag/v1.2.258-nightly
122-
// outputs version 1.2.257;
123-
// ```
124-
// ./databend-meta --single
125-
// Databend Metasrv
126-
// Version: v1.2.257-nightly-188426e3e6-simd(1.75.0-nightly-2023-12-17T22:09:06.675156000Z)
127-
// ```
128-
// Skip 1.2.258 use the next 1.2.259
129-
patch: 259,
130-
pre: Prerelease::EMPTY,
131-
build: BuildMetadata::EMPTY,
132-
};
116+
// ------------------------------
117+
// The binary in the https://github.com/datafuselabs/databend/releases/tag/v1.2.258-nightly
118+
// outputs version 1.2.257;
119+
// ```
120+
// ./databend-meta --single
121+
// Databend Metasrv
122+
// Version: v1.2.257-nightly-188426e3e6-simd(1.75.0-nightly-2023-12-17T22:09:06.675156000Z)
123+
// ```
124+
// Skip 1.2.258 use the next 1.2.259
125+
pub static MIN_METASRV_SEMVER: Version = Version::new(1, 2, 259);
133126

134127
pub fn to_digit_ver(v: &Version) -> u64 {
135128
v.major * 1_000_000 + v.minor * 1_000 + v.patch

‎src/meta/service/src/version.rs

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,6 @@
1515
use std::sync::LazyLock;
1616

1717
use feature_set::FeatureSet;
18-
use semver::BuildMetadata;
19-
use semver::Prerelease;
2018
use semver::Version;
2119

2220
pub static METASRV_COMMIT_VERSION: LazyLock<String> = LazyLock::new(|| {
@@ -46,13 +44,7 @@ pub static METASRV_SEMVER: LazyLock<Version> = LazyLock::new(|| {
4644
});
4745

4846
/// Oldest compatible nightly meta-client version
49-
pub static MIN_METACLI_SEMVER: Version = Version {
50-
major: 0,
51-
minor: 9,
52-
patch: 41,
53-
pre: Prerelease::EMPTY,
54-
build: BuildMetadata::EMPTY,
55-
};
47+
pub static MIN_METACLI_SEMVER: Version = Version::new(0, 9, 41);
5648

5749
/// The min meta-server version that can be deployed together in a cluster,
5850
/// i.e., the network APIs are compatible.
@@ -71,14 +63,22 @@ pub static MIN_META_SEMVER: Version = Version::new(0, 9, 41);
7163
/// - The server depends on a sub set of the features provided by the client.
7264
/// - The client depends on a sub set of the features provided by the server.
7365
///
74-
/// For example, an RPC call may look like this:
66+
/// For example, an RPC call may look like the following:
67+
///
68+
/// - Server provides features S1, S2, S3, and the client requires S1, S3,
69+
/// which is a subset of S1, S2, S3, so the call can be made.
70+
///
71+
/// - The client provides features C1, C2, C3, and the server requires C2, C3,
72+
/// which is a subset of C1, C2, C3, so the response can be read by client.
7573
///
7674
/// ```text
75+
/// request
7776
/// Client calls: ------------> Server API provides:
7877
/// - S1 - S1
7978
/// - S2
8079
/// - S3 - S3
8180
///
81+
/// response
8282
/// Client can receives: <------ Server replies with:
8383
/// - C1
8484
/// - C2 - C2
@@ -91,12 +91,16 @@ pub(crate) mod raft {
9191
use feature_set::Provide;
9292

9393
/// Feature set provided by raft server.
94+
///
95+
/// This is a change-log of the features that raft server provides,
96+
/// and can be built into a BTreeMap of features with `FeatureSet::from_provides`
9497
#[rustfmt::skip]
9598
pub const PROVIDES: &[Action<Provide>] = &[
9699
add_provide(("vote", 0), "2023-02-16", (0, 9, 41)),
97100
add_provide(("append", 0), "2023-02-16", (0, 9, 41)),
98101
add_provide(("install_snapshot", 0), "2023-02-16", (0, 9, 41)),
99102
add_provide(("install_snapshot", 1), "2023-11-16", (1, 2, 212)),
103+
add_provide(("install_snapshot", 2), "2024-05-05", (1, 2, 452)),
100104
];
101105

102106
/// The client features that raft server depends on.
@@ -113,6 +117,9 @@ pub(crate) mod raft {
113117
use feature_set::Require;
114118

115119
/// The server features that raft client depends on.
120+
///
121+
/// This is a change-log of the features that raft client depends on,
122+
/// and can be built into a BTreeMap of features with `FeatureSet::from_required`
116123
#[rustfmt::skip]
117124
pub const REQUIRES: &[Action<Require>] = &[
118125
add_require( ("vote", 0), "2023-02-16", (0, 9, 41)),

0 commit comments

Comments
 (0)