You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by ha...@apache.org on 2025/09/12 07:40:47 UTC
(skywalking-banyandb) 01/03: Implement versioning support in API: add VersionInfo and VersionCompatibility messages, update SyncPartRequest and SendResponse to include version information, and enhance status enum with version-related statuses. Update documentation to reflect these changes.
This is an automated email from the ASF dual-hosted git repository.
hanahmily pushed a commit to branch luster/version
in repository https://gitbox.apache.org/repos/asf/skywalking-banyandb.git
commit 7d8b1c996b682ff5dce38d3bf233d1145ac8680d
Author: Gao Hongtao <ha...@gmail.com>
AuthorDate: Fri Sep 12 15:03:48 2025 +0800
Implement versioning support in API: add VersionInfo and VersionCompatibility messages, update SyncPartRequest and SendResponse to include version information, and enhance status enum with version-related statuses. Update documentation to reflect these changes.
---
api/proto/banyandb/cluster/v1/rpc.proto | 35 ++++++++++++++++++++++++
api/proto/banyandb/model/v1/write.proto | 2 ++
banyand/internal/storage/version.go | 10 +++++++
banyand/queue/pub/chunked_sync.go | 12 +++++++++
banyand/queue/pub/pub.go | 7 +++++
docs/api-reference.md | 47 +++++++++++++++++++++++++++++++++
6 files changed, 113 insertions(+)
diff --git a/api/proto/banyandb/cluster/v1/rpc.proto b/api/proto/banyandb/cluster/v1/rpc.proto
index 8f49294f..0974843f 100644
--- a/api/proto/banyandb/cluster/v1/rpc.proto
+++ b/api/proto/banyandb/cluster/v1/rpc.proto
@@ -23,11 +23,37 @@ import "banyandb/model/v1/write.proto";
option go_package = "github.com/apache/skywalking-banyandb/api/proto/banyandb/cluster/v1";
+message VersionInfo {
+ // file_format_version indicates the file format version used
+ string file_format_version = 1;
+ // compatible_file_format_version lists backward compatible versions
+ repeated string compatible_file_format_version = 2;
+ // api_version indicates the API semantic version
+ string api_version = 3;
+}
+
+message VersionCompatibility {
+ // supported indicates whether the client version is supported
+ bool supported = 1;
+ // server_api_version is the API version of the server
+ string server_api_version = 2;
+ // supported_api_versions lists API versions supported by the server
+ repeated string supported_api_versions = 3;
+ // server_file_format_version is the file format version of the server
+ string server_file_format_version = 4;
+ // supported_file_format_versions lists file format versions supported by the server
+ repeated string supported_file_format_versions = 5;
+ // reason provides human-readable explanation of version incompatibility
+ string reason = 6;
+}
+
message SendRequest {
string topic = 1;
uint64 message_id = 2;
bytes body = 3;
bool batch_mod = 4;
+ // version_info contains version information
+ VersionInfo version_info = 5;
}
message SendResponse {
@@ -35,6 +61,8 @@ message SendResponse {
string error = 2;
bytes body = 3;
model.v1.Status status = 4;
+ // version_compatibility contains version compatibility information when status indicates version issues
+ VersionCompatibility version_compatibility = 5;
}
message HealthCheckRequest {
@@ -59,6 +87,9 @@ message SyncPartRequest {
SyncMetadata metadata = 7; // Sent with first chunk (chunk_index = 0).
SyncCompletion completion = 8; // Sent with last chunk to finalize.
}
+
+ // version_info contains version information
+ VersionInfo version_info = 9;
}
// Information about a part contained within a chunk.
@@ -103,6 +134,8 @@ message SyncPartResponse {
SyncStatus status = 3;
string error = 4;
SyncResult sync_result = 5; // Final result when sync completes.
+ // version_compatibility contains version compatibility information when status indicates version issues
+ VersionCompatibility version_compatibility = 6;
}
// SyncResult contains the result of a sync operation.
@@ -130,6 +163,8 @@ enum SyncStatus {
SYNC_STATUS_CHUNK_OUT_OF_ORDER = 3; // Chunk received out of expected order.
SYNC_STATUS_SESSION_NOT_FOUND = 4; // Session ID not recognized.
SYNC_STATUS_SYNC_COMPLETE = 5; // Entire sync operation completed successfully.
+ SYNC_STATUS_VERSION_UNSUPPORTED = 6; // Version not supported for sync operations.
+ SYNC_STATUS_FORMAT_VERSION_MISMATCH = 7; // File format version incompatible.
}
service Service {
diff --git a/api/proto/banyandb/model/v1/write.proto b/api/proto/banyandb/model/v1/write.proto
index 7a683407..3f25e1ee 100644
--- a/api/proto/banyandb/model/v1/write.proto
+++ b/api/proto/banyandb/model/v1/write.proto
@@ -31,4 +31,6 @@ enum Status {
STATUS_EXPIRED_SCHEMA = 4;
STATUS_INTERNAL_ERROR = 5;
STATUS_DISK_FULL = 6;
+ STATUS_VERSION_UNSUPPORTED = 7; // Client version not supported
+ STATUS_VERSION_DEPRECATED = 8; // Client version deprecated but still supported
}
diff --git a/banyand/internal/storage/version.go b/banyand/internal/storage/version.go
index 2fdac4ca..6f9d6ccf 100644
--- a/banyand/internal/storage/version.go
+++ b/banyand/internal/storage/version.go
@@ -68,3 +68,13 @@ func readCompatibleVersions() []string {
}
return vv
}
+
+// GetCurrentVersion returns the current storage version.
+func GetCurrentVersion() string {
+ return currentVersion
+}
+
+// GetCompatibleVersions returns the list of compatible storage versions.
+func GetCompatibleVersions() []string {
+ return compatibleVersions
+}
diff --git a/banyand/queue/pub/chunked_sync.go b/banyand/queue/pub/chunked_sync.go
index 8e6cb679..35afb070 100644
--- a/banyand/queue/pub/chunked_sync.go
+++ b/banyand/queue/pub/chunked_sync.go
@@ -28,7 +28,9 @@ import (
"google.golang.org/grpc"
+ apiversion "github.com/apache/skywalking-banyandb/api/proto/banyandb"
clusterv1 "github.com/apache/skywalking-banyandb/api/proto/banyandb/cluster/v1"
+ "github.com/apache/skywalking-banyandb/banyand/internal/storage"
"github.com/apache/skywalking-banyandb/banyand/queue"
"github.com/apache/skywalking-banyandb/pkg/fs"
"github.com/apache/skywalking-banyandb/pkg/logger"
@@ -287,6 +289,11 @@ func (c *chunkedSyncClient) streamPartsAsChunks(
TotalChunks: totalChunks,
},
},
+ VersionInfo: &clusterv1.VersionInfo{
+ ApiVersion: apiversion.Version,
+ FileFormatVersion: storage.GetCurrentVersion(),
+ CompatibleFileFormatVersion: storage.GetCompatibleVersions(),
+ },
}
if err := stream.Send(completionReq); err != nil {
@@ -319,6 +326,11 @@ func (c *chunkedSyncClient) sendChunk(
ChunkData: chunkData,
ChunkChecksum: chunkChecksum,
PartsInfo: partsInfo,
+ VersionInfo: &clusterv1.VersionInfo{
+ ApiVersion: apiversion.Version,
+ FileFormatVersion: storage.GetCurrentVersion(),
+ CompatibleFileFormatVersion: storage.GetCompatibleVersions(),
+ },
}
if isFirstChunk {
diff --git a/banyand/queue/pub/pub.go b/banyand/queue/pub/pub.go
index 7a40046e..74fa2432 100644
--- a/banyand/queue/pub/pub.go
+++ b/banyand/queue/pub/pub.go
@@ -35,9 +35,11 @@ import (
"github.com/apache/skywalking-banyandb/api/common"
"github.com/apache/skywalking-banyandb/api/data"
+ apiversion "github.com/apache/skywalking-banyandb/api/proto/banyandb"
clusterv1 "github.com/apache/skywalking-banyandb/api/proto/banyandb/cluster/v1"
databasev1 "github.com/apache/skywalking-banyandb/api/proto/banyandb/database/v1"
modelv1 "github.com/apache/skywalking-banyandb/api/proto/banyandb/model/v1"
+ "github.com/apache/skywalking-banyandb/banyand/internal/storage"
"github.com/apache/skywalking-banyandb/banyand/metadata"
"github.com/apache/skywalking-banyandb/banyand/metadata/schema"
"github.com/apache/skywalking-banyandb/banyand/queue"
@@ -336,6 +338,11 @@ func messageToRequest(topic bus.Topic, m bus.Message) (*clusterv1.SendRequest, e
Topic: topic.String(),
MessageId: uint64(m.ID()),
BatchMod: m.BatchModeEnabled(),
+ VersionInfo: &clusterv1.VersionInfo{
+ ApiVersion: apiversion.Version,
+ FileFormatVersion: storage.GetCurrentVersion(),
+ CompatibleFileFormatVersion: storage.GetCompatibleVersions(),
+ },
}
switch data := m.Data().(type) {
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 67a5e8f9..5237d4f8 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -19,6 +19,8 @@
- [SyncPartRequest](#banyandb-cluster-v1-SyncPartRequest)
- [SyncPartResponse](#banyandb-cluster-v1-SyncPartResponse)
- [SyncResult](#banyandb-cluster-v1-SyncResult)
+ - [VersionCompatibility](#banyandb-cluster-v1-VersionCompatibility)
+ - [VersionInfo](#banyandb-cluster-v1-VersionInfo)
- [SyncStatus](#banyandb-cluster-v1-SyncStatus)
@@ -349,6 +351,8 @@ Status is the response status for write
| STATUS_EXPIRED_SCHEMA | 4 | |
| STATUS_INTERNAL_ERROR | 5 | |
| STATUS_DISK_FULL | 6 | |
+| STATUS_VERSION_UNSUPPORTED | 7 | Client version not supported |
+| STATUS_VERSION_DEPRECATED | 8 | Client version deprecated but still supported |
@@ -466,6 +470,7 @@ PartResult contains the result for individual parts.
| message_id | [uint64](#uint64) | | |
| body | [bytes](#bytes) | | |
| batch_mod | [bool](#bool) | | |
+| version_info | [VersionInfo](#banyandb-cluster-v1-VersionInfo) | | version_info contains version information |
@@ -484,6 +489,7 @@ PartResult contains the result for individual parts.
| error | [string](#string) | | |
| body | [bytes](#bytes) | | |
| status | [banyandb.model.v1.Status](#banyandb-model-v1-Status) | | |
+| version_compatibility | [VersionCompatibility](#banyandb-cluster-v1-VersionCompatibility) | | version_compatibility contains version compatibility information when status indicates version issues |
@@ -541,6 +547,7 @@ Chunked Sync Service Messages.
| parts_info | [PartInfo](#banyandb-cluster-v1-PartInfo) | repeated | Information about parts contained in this chunk. |
| metadata | [SyncMetadata](#banyandb-cluster-v1-SyncMetadata) | | Sent with first chunk (chunk_index = 0). |
| completion | [SyncCompletion](#banyandb-cluster-v1-SyncCompletion) | | Sent with last chunk to finalize. |
+| version_info | [VersionInfo](#banyandb-cluster-v1-VersionInfo) | | version_info contains version information |
@@ -560,6 +567,7 @@ SyncPartResponse contains the response for a sync part request.
| status | [SyncStatus](#banyandb-cluster-v1-SyncStatus) | | |
| error | [string](#string) | | |
| sync_result | [SyncResult](#banyandb-cluster-v1-SyncResult) | | Final result when sync completes. |
+| version_compatibility | [VersionCompatibility](#banyandb-cluster-v1-VersionCompatibility) | | version_compatibility contains version compatibility information when status indicates version issues |
@@ -585,6 +593,43 @@ SyncResult contains the result of a sync operation.
+
+<a name="banyandb-cluster-v1-VersionCompatibility"></a>
+
+### VersionCompatibility
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| supported | [bool](#bool) | | supported indicates whether the client version is supported |
+| server_api_version | [string](#string) | | server_api_version is the API version of the server |
+| supported_api_versions | [string](#string) | repeated | supported_api_versions lists API versions supported by the server |
+| server_file_format_version | [string](#string) | | server_file_format_version is the file format version of the server |
+| supported_file_format_versions | [string](#string) | repeated | supported_file_format_versions lists file format versions supported by the server |
+| reason | [string](#string) | | reason provides human-readable explanation of version incompatibility |
+
+
+
+
+
+
+<a name="banyandb-cluster-v1-VersionInfo"></a>
+
+### VersionInfo
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| file_format_version | [string](#string) | | file_format_version indicates the file format version used |
+| compatible_file_format_version | [string](#string) | repeated | compatible_file_format_version lists backward compatible versions |
+| api_version | [string](#string) | | api_version indicates the API semantic version |
+
+
+
+
+
@@ -601,6 +646,8 @@ SyncStatus represents the status of a sync operation.
| SYNC_STATUS_CHUNK_OUT_OF_ORDER | 3 | Chunk received out of expected order. |
| SYNC_STATUS_SESSION_NOT_FOUND | 4 | Session ID not recognized. |
| SYNC_STATUS_SYNC_COMPLETE | 5 | Entire sync operation completed successfully. |
+| SYNC_STATUS_VERSION_UNSUPPORTED | 6 | Version not supported for sync operations. |
+| SYNC_STATUS_FORMAT_VERSION_MISMATCH | 7 | File format version incompatible. |