smartbotic/proto/storage.proto

syntax = "proto3";

package smartbotic.proto;

import "common.proto";

option cc_enable_arenas = true;

// Document with metadata
message Document {
    string id = 1;
    string collection = 2;
    string data = 3;  // JSON string
    int64 version = 4;
    int64 created_at = 5;
    int64 updated_at = 6;
    int64 expires_at = 7;  // 0 = no expiry
}

// Query filter operation
enum FilterOp {
    FILTER_OP_UNSPECIFIED = 0;
    FILTER_OP_EQ = 1;      // Equal
    FILTER_OP_NE = 2;      // Not equal
    FILTER_OP_GT = 3;      // Greater than
    FILTER_OP_GTE = 4;     // Greater than or equal
    FILTER_OP_LT = 5;      // Less than
    FILTER_OP_LTE = 6;     // Less than or equal
    FILTER_OP_IN = 7;      // In array
    FILTER_OP_NIN = 8;     // Not in array
    FILTER_OP_CONTAINS = 9; // Contains substring
    FILTER_OP_REGEX = 10;  // Regular expression match
    FILTER_OP_EXISTS = 11; // Field exists
}

// Single filter condition
message Filter {
    string field = 1;
    FilterOp op = 2;
    string value = 3;  // JSON encoded value
}

// Sort direction
enum SortDirection {
    SORT_DIRECTION_UNSPECIFIED = 0;
    SORT_DIRECTION_ASC = 1;
    SORT_DIRECTION_DESC = 2;
}

// Sort specification
message Sort {
    string field = 1;
    SortDirection direction = 2;
}

// Query request
message QueryRequest {
    string collection = 1;
    repeated Filter filters = 2;
    repeated Sort sorts = 3;
    PaginationRequest pagination = 4;
    repeated string fields = 5;  // Projection - empty means all fields
}

// Query response
message QueryResponse {
    repeated Document documents = 1;
    PaginationResponse pagination = 2;
}

// Get document request
message GetRequest {
    string collection = 1;
    string id = 2;
}

// Insert request
message InsertRequest {
    string collection = 1;
    string id = 2;  // Optional - generated if empty
    string data = 3;  // JSON string
    int64 ttl_ms = 4;  // Time to live in milliseconds (0 = no expiry)
}

// Update request
message UpdateRequest {
    string collection = 1;
    string id = 2;
    string data = 3;  // JSON string - full document or partial update
    int64 expected_version = 4;  // Optimistic locking (0 = no check)
    bool partial = 5;  // If true, merge with existing document
}

// Delete request
message DeleteRequest {
    string collection = 1;
    string id = 2;
    int64 expected_version = 3;  // Optimistic locking (0 = no check)
}

// Batch operations
message BatchInsertRequest {
    string collection = 1;
    repeated InsertRequest documents = 2;
}

message BatchDeleteRequest {
    string collection = 1;
    repeated string ids = 2;
}

// Versioning configuration
message VersioningConfig {
    bool enabled = 1;
    int32 max_versions = 2;      // 0 = unlimited
    int64 version_ttl_ms = 3;    // 0 = no expiry
    bool keep_on_delete = 4;     // Archive deleted documents
}

// Collection management
message CreateCollectionRequest {
    string name = 1;
    string schema = 2;  // JSON Schema for validation (optional)
    int64 default_ttl_ms = 3;  // Default TTL for documents
    VersioningConfig versioning = 4;  // Versioning configuration
}

message DropCollectionRequest {
    string name = 1;
}

message ListCollectionsRequest {}

message ListCollectionsResponse {
    repeated string collections = 1;
}

// Mutation response
message MutationResponse {
    string id = 1;
    int64 version = 2;
    bool success = 3;
    Error error = 4;
}

message BatchMutationResponse {
    repeated MutationResponse results = 1;
    int32 success_count = 2;
    int32 failure_count = 3;
}

// Document version for version history
message DocumentVersion {
    string id = 1;              // "{documentId}__v{version}"
    string document_id = 2;
    int64 version = 3;
    string data = 4;            // JSON string
    int64 created_at = 5;
    int64 expires_at = 6;
}

// Get specific document version
message GetVersionRequest {
    string collection = 1;
    string id = 2;
    int64 version = 3;
}

// List versions for a document
message ListVersionsRequest {
    string collection = 1;
    string id = 2;
    int32 limit = 3;
    int32 offset = 4;
}

message ListVersionsResponse {
    repeated DocumentVersion versions = 1;
    int64 total_count = 2;
    bool has_more = 3;
}

// Storage service definition
service StorageService {
    // Document operations
    rpc Get(GetRequest) returns (Document);
    rpc Query(QueryRequest) returns (QueryResponse);
    rpc Insert(InsertRequest) returns (MutationResponse);
    rpc Update(UpdateRequest) returns (MutationResponse);
    rpc Delete(DeleteRequest) returns (MutationResponse);

    // Batch operations
    rpc BatchInsert(BatchInsertRequest) returns (BatchMutationResponse);
    rpc BatchDelete(BatchDeleteRequest) returns (BatchMutationResponse);

    // Collection management
    rpc CreateCollection(CreateCollectionRequest) returns (Empty);
    rpc DropCollection(DropCollectionRequest) returns (Empty);
    rpc ListCollections(ListCollectionsRequest) returns (ListCollectionsResponse);

    // Version operations
    rpc GetVersion(GetVersionRequest) returns (Document);
    rpc ListVersions(ListVersionsRequest) returns (ListVersionsResponse);
}