machi/src/machi.proto

606 lines
17 KiB
Protocol Buffer
Raw Normal View History

/* -------------------------------------------------------------------
**
** machi.proto: Protocol Buffers definition for Machi
**
** Copyright (c) 2014-2015 Basho Technologies, Inc. All Rights Reserved.
**
** This file is provided to you under the Apache License,
** Version 2.0 (the "License"); you may not use this file
** except in compliance with the License. You may obtain
** a copy of the License at
**
** http://www.apache.org/licenses/LICENSE-2.0
**
** Unless required by applicable law or agreed to in writing,
** software distributed under the License is distributed on an
** "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
** KIND, either express or implied. See the License for the
** specific language governing permissions and limitations
** under the License.
**
** -------------------------------------------------------------------
*/
/*
** Revision: 0.1
*/
// Java package specifiers
option java_package = "com.basho.machi.protobuf";
option java_outer_classname = "MachiPB";
//////////////////////////////////////////
//
// Enums
//
//////////////////////////////////////////
enum Mpb_GeneralStatusCode {
OK = 0;
BAD_ARG = 1;
WEDGED = 2;
BAD_CHECKSUM = 3;
PARTITION = 4;
NOT_WRITTEN = 5;
2015-06-25 06:10:24 +00:00
WRITTEN = 6;
NO_SUCH_FILE = 7;
2015-06-26 12:36:07 +00:00
PARTIAL_READ = 8;
2015-07-01 06:51:25 +00:00
BAD_EPOCH = 9;
2015-06-23 05:08:10 +00:00
BAD_JOSS = 255; // Only for testing by the Taipan
}
// Must match with machi.hrl's values!
enum Mpb_CSumType {
CSUM_TAG_NONE = 0;
2015-06-23 05:08:10 +00:00
CSUM_TAG_CLIENT_SHA = 1;
CSUM_TAG_SERVER_SHA = 2;
CSUM_TAG_SERVER_REGEN_SHA = 3;
}
enum Mpb_ProjType {
PRIVATE = 20;
PUBLIC = 21;
}
//////////////////////////////////////////
//
// Basic data types
//
//////////////////////////////////////////
// chunk_pos() type
message Mpb_ChunkPos {
2015-06-18 08:31:48 +00:00
required uint64 offset = 1;
required uint64 chunk_size = 2;
required string file_name = 3;
}
// chunk_csum() type
message Mpb_ChunkCSum {
required Mpb_CSumType type = 1;
2015-06-23 05:08:10 +00:00
optional bytes csum = 2;
}
// epoch_id() type
message Mpb_EpochID {
required uint32 epoch_number = 1;
2015-06-23 06:13:13 +00:00
required bytes epoch_csum = 2;
2015-06-18 07:16:23 +00:00
}
2015-06-23 08:08:15 +00:00
// file_info() type
message Mpb_FileInfo {
required uint64 file_size = 1;
required string file_name = 2;
}
// #p_srvr{} type
message Mpb_P_Srvr {
required string name = 1;
required string proto_mod = 2;
required string address = 3;
required string port = 4;
required bytes opaque_props = 5;
}
//////////////////////////////////////////
//
// Requests & responses
//
//////////////////////////////////////////
// Error response - may be generated for any Req
message Mpb_ErrorResp {
// Free-form (depends on server, which is probably a bad idea TODO)
required int32 code = 1;
required string msg = 2;
optional bytes extra = 3;
}
//////////////////////////////////////////
//
// High level API requests:
//
// echo() : Mpb_EchoReq and Mpb_EchoResp
// auth() : Mpb_AuthReq and Mpb_AuthResp
// append_chunk() : Mpb_AppendChunkReq and Mpb_AppendChunkResp
// write_chunk() : Mpb_WriteChunkReq and Mpb_WriteChunkResp
// read_chunk() : Mpb_ReadChunkReq and Mpb_ReadChunkResp
// checksum_list() : Mpb_ChecksumListReq and Mpb_ChecksumListResp
// list_files() : Mpb_ListFilesReq and Mpb_ListFilesResp
//
//////////////////////////////////////////
// High level API: echo() request & response
2015-06-18 08:31:48 +00:00
message Mpb_EchoReq {
2015-06-18 08:31:48 +00:00
optional string message = 1;
}
message Mpb_EchoResp {
2015-06-18 08:31:48 +00:00
optional string message = 1;
}
// High level API: auth() request & response (not yet implemented)
message Mpb_AuthReq {
required bytes user = 1;
required bytes password = 2;
}
message Mpb_AuthResp {
required int32 code = 1;
// TODO: not implemented yet
}
// High level API: append_chunk() request & response
message Mpb_AppendChunkReq {
2015-06-23 05:08:10 +00:00
optional bytes placement_key = 1;
required string prefix = 2;
required bytes chunk = 3;
2015-06-23 05:08:10 +00:00
required Mpb_ChunkCSum csum = 4;
optional uint32 chunk_extra = 5;
}
message Mpb_AppendChunkResp {
required Mpb_GeneralStatusCode status = 1;
// If OK, then chunk_pos is defined.
optional Mpb_ChunkPos chunk_pos = 2;
}
// High level API: write_chunk() request & response
message Mpb_WriteChunkReq {
required string file = 1;
required uint64 offset = 2;
required bytes chunk = 3;
2015-06-23 06:13:13 +00:00
required Mpb_ChunkCSum csum = 4;
}
message Mpb_WriteChunkResp {
required Mpb_GeneralStatusCode status = 1;
}
// High level API: read_chunk() request & response
2015-06-23 06:34:48 +00:00
message Mpb_ReadChunkReq {
required string file = 1;
required uint64 offset = 2;
required uint32 size = 3;
2015-06-23 06:34:48 +00:00
// Use flag_checksum=non-zero to request the chunk's checksum also
optional uint32 flag_checksum = 4 [default=0];
2015-06-23 06:34:48 +00:00
// Use flag_no_chunk=non-zero to skip returning the chunk (which
// only makes sense if flag_checksum is set).
optional uint32 flag_no_chunk = 5 [default=0];
}
message Mpb_ReadChunkResp {
required Mpb_GeneralStatusCode status = 1;
optional bytes chunk = 2;
optional Mpb_ChunkCSum csum = 3;
}
// High level API: checksum_list() request & response
message Mpb_ChecksumListReq {
required string file = 1;
}
message Mpb_ChecksumListResp {
required Mpb_GeneralStatusCode status = 1;
2015-06-30 06:20:35 +00:00
// For data type rationale, see comments for
// machi_flu1_client:checksum_list/4 or
// http://basho.github.io/machi/edoc/machi_flu1_client.html#checksum_list-4
optional bytes chunk = 2;
}
// High level API: list_files() request & response
2015-06-23 08:08:15 +00:00
message Mpb_ListFilesReq {
}
message Mpb_ListFilesResp {
required Mpb_GeneralStatusCode status = 1;
// Wow, I cannot use optional & repeated together?
repeated Mpb_FileInfo files = 2;
}
//////////////////////////////////////////
//
// High level API request & response wrapper
//
//////////////////////////////////////////
message Mpb_Request {
// TODO: If we wish to support pipelined requests sometime in the
// future, this is the placeholder to do it.
required bytes req_id = 1;
2015-06-29 07:10:43 +00:00
// CLIENTS must not set 'do_not_alter' flag; leave it to default.
required uint32 do_not_alter = 2 [default=1];
// The client should only define one request message. If the client
// includes multiple requests here, the server may pick/choose an
// arbitrary one.
// NOTE: The erlang protobuffs compiler doesn't support 'oneof'.
// But 'oneof' appears to be a very tiny memory optimization
// that not all languages might care about? (Erlang doesn't)
2015-06-29 07:10:43 +00:00
optional Mpb_EchoReq echo = 110;
optional Mpb_AuthReq auth = 111;
optional Mpb_AppendChunkReq append_chunk = 112;
optional Mpb_WriteChunkReq write_chunk = 113;
optional Mpb_ReadChunkReq read_chunk = 114;
optional Mpb_ChecksumListReq checksum_list = 115;
optional Mpb_ListFilesReq list_files = 116;
}
2015-06-18 07:16:23 +00:00
message Mpb_Response {
// TODO: If we wish to support pipelined requests sometime in the
// future, this is the placeholder to do it.
required bytes req_id = 1;
// The server will define only one of the optional responses below.
2015-06-18 07:16:23 +00:00
// Generic error response, typically used when something quite
// bad/unexpected happened within the server.
// Clients should always check this response and, if defined,
// ignore any request-specific response at codes 10+.
optional Mpb_ErrorResp generic = 2;
// Specific responses.
optional Mpb_EchoResp echo = 10;
optional Mpb_AuthResp auth = 11;
optional Mpb_AppendChunkResp append_chunk = 12;
optional Mpb_WriteChunkResp write_chunk = 13;
2015-06-23 06:34:48 +00:00
optional Mpb_ReadChunkResp read_chunk = 14;
optional Mpb_ChecksumListResp checksum_list = 15;
2015-06-23 08:08:15 +00:00
optional Mpb_ListFilesResp list_files = 16;
}
//////////////////////////////////////////
//
// Low level API data types
//
//////////////////////////////////////////
enum Mpb_Mode {
AP_MODE = 30;
CP_MODE = 31;
}
message Mpb_Now {
required uint64 sec = 1;
required uint32 usec = 2;
}
message Mpb_MembersDictEntry {
required string key = 1;
required Mpb_P_Srvr val = 2;
}
message Mpb_ProjectionV1 {
required uint32 epoch_number = 1;
required bytes epoch_csum = 2;
required string author_server = 3;
repeated string all_members = 4;
2015-08-05 03:53:20 +00:00
repeated string witnesses = 5;
required Mpb_Now creation_time = 6;
required Mpb_Mode mode = 7;
repeated string upi = 8;
repeated string repairing = 9;
repeated string down = 10;
optional bytes opaque_flap = 11;
optional bytes opaque_inner = 12;
required bytes opaque_dbg = 13;
required bytes opaque_dbg2 = 14;
repeated Mpb_MembersDictEntry members_dict = 15;
}
//////////////////////////////////////////
//
// Low level API requests:
//
// echo() : Mpb_EchoReq and Mpb_EchoResp (reused from high level API)
// auth() : Mpb_AuthReq and Mpb_AuthResp (reused from high level API)
//
// File-I/O-related:
//
// append_chunk()
// write_chunk()
// read_chunk()
// checksum_list()
// list_files()
// wedge_status()
// delete_migration()
// trunc_hack()
//
// Projection-related:
//
// get_latest_epochid()
// read_latest_projection()
// read_projection()
// write_projection()
// get_all_projections()
// list_all_projections()
//
//////////////////////////////////////////
// Low level API: append_chunk()
message Mpb_LL_AppendChunkReq {
required Mpb_EpochID epoch_id = 1;
optional bytes placement_key = 2;
required string prefix = 3;
required bytes chunk = 4;
required Mpb_ChunkCSum csum = 5;
optional uint32 chunk_extra = 6;
}
message Mpb_LL_AppendChunkResp {
required Mpb_GeneralStatusCode status = 1;
// If OK, then chunk_pos is defined.
optional Mpb_ChunkPos chunk_pos = 2;
}
// Low level API: write_chunk()
message Mpb_LL_WriteChunkReq {
required Mpb_EpochID epoch_id = 1;
required string file = 2;
required uint64 offset = 3;
required bytes chunk = 4;
required Mpb_ChunkCSum csum = 5;
}
message Mpb_LL_WriteChunkResp {
required Mpb_GeneralStatusCode status = 1;
}
// Low level API: read_chunk()
message Mpb_LL_ReadChunkReq {
required Mpb_EpochID epoch_id = 1;
required string file = 2;
required uint64 offset = 3;
required uint32 size = 4;
// Use flag_checksum=non-zero to request the chunk's checksum also
2015-06-26 09:59:07 +00:00
optional uint32 flag_get_checksum = 5 [default=0];
// Use flag_no_chunk=non-zero to skip returning the chunk (which
// only makes sense if flag_checksum is set).
optional uint32 flag_no_chunk = 6 [default=0];
}
message Mpb_LL_ReadChunkResp {
required Mpb_GeneralStatusCode status = 1;
optional bytes chunk = 2;
optional Mpb_ChunkCSum csum = 3;
}
// Low level API: checksum_list()
message Mpb_LL_ChecksumListReq {
required Mpb_EpochID epoch_id = 1;
required string file = 2;
}
message Mpb_LL_ChecksumListResp {
required Mpb_GeneralStatusCode status = 1;
2015-06-30 06:20:35 +00:00
// For data type rationale, see comments for
// machi_flu1_client:checksum_list/4 or
// http://basho.github.io/machi/edoc/machi_flu1_client.html#checksum_list-4
optional bytes chunk = 2;
}
// Low level API: list_files()
message Mpb_LL_ListFilesReq {
required Mpb_EpochID epoch_id = 1;
}
message Mpb_LL_ListFilesResp {
required Mpb_GeneralStatusCode status = 1;
repeated Mpb_FileInfo files = 2;
}
// Low level API: wedge_status()
message Mpb_LL_WedgeStatusReq {
// No options
}
message Mpb_LL_WedgeStatusResp {
2015-06-29 07:42:05 +00:00
required Mpb_GeneralStatusCode status = 1;
optional Mpb_EpochID epoch_id = 2;
optional uint32 wedged_flag = 3;
}
// Low level API: delete_migration()
message Mpb_LL_DeleteMigrationReq {
required Mpb_EpochID epoch_id = 1;
required string file = 2;
}
message Mpb_LL_DeleteMigrationResp {
required Mpb_GeneralStatusCode status = 1;
}
// Low level API: trunc_hack()
message Mpb_LL_TruncHackReq {
required Mpb_EpochID epoch_id = 1;
required string file = 2;
}
message Mpb_LL_TruncHackResp {
required Mpb_GeneralStatusCode status = 1;
}
// Low level API: get_latest_epochid() request & response
message Mpb_LL_GetLatestEpochIDReq {
required Mpb_ProjType type = 1;
}
message Mpb_LL_GetLatestEpochIDResp {
required Mpb_GeneralStatusCode status = 1;
optional Mpb_EpochID epoch_id = 2;
}
// Low level API: read_latest_projection() request & response
message Mpb_LL_ReadLatestProjectionReq {
required Mpb_ProjType type = 1;
}
message Mpb_LL_ReadLatestProjectionResp {
required Mpb_GeneralStatusCode status = 1;
optional Mpb_ProjectionV1 proj = 2;
}
// Low level API: read_projection() request & response
message Mpb_LL_ReadProjectionReq {
required Mpb_ProjType type = 1;
required uint32 epoch_number = 2;
}
message Mpb_LL_ReadProjectionResp {
required Mpb_GeneralStatusCode status = 1;
optional Mpb_ProjectionV1 proj = 2;
}
// Low level API: write_projection() request & response
message Mpb_LL_WriteProjectionReq {
required Mpb_ProjType type = 1;
required Mpb_ProjectionV1 proj = 2;
}
message Mpb_LL_WriteProjectionResp {
required Mpb_GeneralStatusCode status = 1;
}
// Low level API: get_all_projections() request & response
message Mpb_LL_GetAllProjectionsReq {
required Mpb_ProjType type = 1;
}
message Mpb_LL_GetAllProjectionsResp {
required Mpb_GeneralStatusCode status = 1;
repeated Mpb_ProjectionV1 projs = 2;
}
// Low level API: list_all_projections() request & response
message Mpb_LL_ListAllProjectionsReq {
required Mpb_ProjType type = 1;
}
message Mpb_LL_ListAllProjectionsResp {
required Mpb_GeneralStatusCode status = 1;
repeated uint32 epochs = 2;
}
// Low level API: kick_projection_reaction request, NO RESPONSE!
message Mpb_LL_KickProjectionReactionReq {
}
//////////////////////////////////////////
//
// Low API request & response wrapper
//
//////////////////////////////////////////
message Mpb_LL_Request {
// TODO: If we wish to support pipelined requests sometime in the
// future, this is the placeholder to do it.
required bytes req_id = 1;
2015-06-29 07:10:43 +00:00
// CLIENTS must not set 'do_not_alter' flag; leave it to default.
required uint32 do_not_alter = 2 [default=2];
// The client should only define one request message. If the client
// includes multiple requests here, the server may pick/choose an
// arbitrary one.
// NOTE: The erlang protobuffs compiler doesn't support 'oneof'.
// But 'oneof' appears to be a very tiny memory optimization
// that not all languages might care about? (Erlang doesn't)
optional Mpb_EchoReq echo = 10; // Re-use from high level API
optional Mpb_AuthReq auth = 11; // Re-use from high level API
optional Mpb_LL_GetLatestEpochIDReq proj_gl = 12;
optional Mpb_LL_ReadLatestProjectionReq proj_rl = 13;
optional Mpb_LL_ReadProjectionReq proj_rp = 14;
optional Mpb_LL_WriteProjectionReq proj_wp = 15;
optional Mpb_LL_GetAllProjectionsReq proj_ga = 16;
optional Mpb_LL_ListAllProjectionsReq proj_la = 17;
optional Mpb_LL_KickProjectionReactionReq proj_kp = 18;
optional Mpb_LL_AppendChunkReq append_chunk = 30;
optional Mpb_LL_WriteChunkReq write_chunk = 31;
optional Mpb_LL_ReadChunkReq read_chunk = 32;
optional Mpb_LL_ChecksumListReq checksum_list = 33;
optional Mpb_LL_ListFilesReq list_files = 34;
optional Mpb_LL_WedgeStatusReq wedge_status = 35;
optional Mpb_LL_DeleteMigrationReq delete_migration = 36;
optional Mpb_LL_TruncHackReq trunc_hack = 37;
}
message Mpb_LL_Response {
// TODO: If we wish to support pipelined requests sometime in the
// future, this is the placeholder to do it.
required bytes req_id = 1;
// The server will define only one of the optional responses below.
// Generic error response, typically used when something quite
// bad/unexpected happened within the server.
// Clients should always check this response and, if defined,
// ignore any request-specific response at codes 10+.
optional Mpb_ErrorResp generic = 2;
// Specific responses.
optional Mpb_EchoResp echo = 10; // Re-use from high level API
optional Mpb_AuthResp auth = 11; // Re-use from high level API
optional Mpb_LL_GetLatestEpochIDResp proj_gl = 12;
optional Mpb_LL_ReadLatestProjectionResp proj_rl = 13;
optional Mpb_LL_ReadProjectionResp proj_rp = 14;
optional Mpb_LL_WriteProjectionResp proj_wp = 15;
optional Mpb_LL_GetAllProjectionsResp proj_ga = 16;
optional Mpb_LL_ListAllProjectionsResp proj_la = 17;
// No reponse to Mpb_LL_KickProjectionReactionReq = 18;
optional Mpb_LL_AppendChunkResp append_chunk = 30;
optional Mpb_LL_WriteChunkResp write_chunk = 31;
optional Mpb_LL_ReadChunkResp read_chunk = 32;
optional Mpb_LL_ChecksumListResp checksum_list = 33;
optional Mpb_LL_ListFilesResp list_files = 34;
optional Mpb_LL_WedgeStatusResp wedge_status = 35;
optional Mpb_LL_DeleteMigrationResp delete_migration = 36;
optional Mpb_LL_TruncHackResp trunc_hack = 37;
}