syntax = "proto3";
option cc_enable_arenas = true;

package Ydb.Coordination;

option go_package = "github.com/ydb-platform/ydb-go-genproto/protos/Ydb_Coordination";
option java_package = "tech.ydb.coordination";
option java_outer_classname = "CoordinationProtos";
option java_multiple_files = true;

import "protos/ydb_operation.proto";
import "protos/ydb_status_codes.proto";
import "protos/ydb_issue_message.proto";
import "protos/ydb_scheme.proto";

/**
 * Stub for unsupported messages
 */
message Unsupported {
    // Intentionally empty
}

/**
 * Consistency mode
 */
enum ConsistencyMode {
    // The default or current value
    CONSISTENCY_MODE_UNSET = 0;

    // Strict mode makes sure operations may only complete on current leader
    CONSISTENCY_MODE_STRICT = 1;

    // Relaxed mode allows operations to complete on stale masters
    CONSISTENCY_MODE_RELAXED = 2;
}

/**
 * Counters mode
 */
enum RateLimiterCountersMode {
    // The default or current value
    RATE_LIMITER_COUNTERS_MODE_UNSET = 0;

    // Aggregated counters for resource tree
    RATE_LIMITER_COUNTERS_MODE_AGGREGATED = 1;

    // Counters on every resource
    RATE_LIMITER_COUNTERS_MODE_DETAILED = 2;
}

/**
 * Configuration settings for a coordination node
 */
message Config {
    // Initialized on creation, cannot be set
    string path = 1;

    // Period in milliseconds for self-checks (default 1 second)
    uint32 self_check_period_millis = 2;

    // Grace period for sessions on leader change (default 10 seconds)
    uint32 session_grace_period_millis = 3;

    // Concistency mode for read operations
    ConsistencyMode read_consistency_mode = 4;

    // Consistency mode for attach operations
    ConsistencyMode attach_consistency_mode = 5;

    // Rate limiter counters mode
    RateLimiterCountersMode rate_limiter_counters_mode = 6;
}

/**
 * Describes an active client session
 */
message SessionDescription {
    // Session id generated by the server
    uint64 session_id = 1;

    // Expiration timeout of the session
    uint64 timeout_millis = 2;

    // User-specified description of this session
    string description = 3;

    // True if this session is currently attached to a client
    bool attached = 4;
}

/**
 * Describes an owner or a waiter of this semaphore
 */
message SemaphoreSession {
    // A monotonically increasing id which determines locking order
    uint64 order_id = 5;

    // An id of the session which tried to acquire the semaphore
    uint64 session_id = 1;

    // A timeout in milliseconds for operation in waiters queue
    uint64 timeout_millis = 2;

    // Number of tokens for an acquire operation
    uint64 count = 3;

    // User-defined data attached to the acquire operation
    bytes data = 4;
}

/**
 * Describes the state of a semaphore
 */
message SemaphoreDescription {
    // Name of the semaphore
    string name = 1;

    // User-defined data attached to the semaphore
    bytes data = 2;

    // Number of tokens currently acquired by owners
    uint64 count = 7;

    // Maximum number of tokens that may acquired
    uint64 limit = 3;

    // Ephemeral semaphores are deleted when released by all owners and waiters
    bool ephemeral = 4;

    // A list of current owners of the semaphore
    repeated SemaphoreSession owners = 5;

    // A list of current waiters on the semaphore
    repeated SemaphoreSession waiters = 6;
}

/**
 * Session request message sent from client to server
 */
message SessionRequest {
    /**
     * Used for checking liveness of the connection
     */
    message PingPong {
        // Opaque number specified in the ping message is echoed in the pong message
        uint64 opaque = 1;
    }

    /**
     * First message used to start/restore a session
     */
    message SessionStart {
        // Path to a coordination node
        string path = 1;

        // Non-zero when restoring a session, 0 when creating a new session
        uint64 session_id = 2;

        // Timeout in milliseconds during which client may restore a detached session
        uint64 timeout_millis = 3;

        // User-defined description that may be used to describe the client
        string description = 4;

        // Monotonically increasing sequence number generated by the client
        // When concurrent SessionStart requests are detected the one with
        // the biggest sequence number will succeed
        uint64 seq_no = 5;

        // Random bytes used to protect session from restore by other clients (max. 16 bytes)
        bytes protection_key = 6;
    }

    /**
     * Last message used to cleanly stop session before its timeout expires
     */
    message SessionStop {
        // nothing
    }

    /**
     * Used to acquire a semaphore
     *
     * WARNING: a single session cannot acquire the same semaphore multiple times
     *
     * Later requests override previous operations with the same semaphore,
     * e.g. to reduce acquired count, change timeout or attached data.
     */
    message AcquireSemaphore {
        // Client-defined request id, echoed in the response
        uint64 req_id = 1;

        // Name of the semaphore to acquire
        string name = 2;

        // Timeout in milliseconds after which operation will fail
        // if it's still waiting in the waiters queue
        uint64 timeout_millis = 3;

        // Number of tokens to acquire on the semaphore
        uint64 count = 4;

        // User-defined binary data that may be attached to the operation
        bytes data = 5;

        // Ephemeral semaphores are created with the first acquire operation
        // and automatically deleted with the last release operation
        bool ephemeral = 6;
    }

    /**
     * Used to release a semaphore
     *
     * WARNING: a single session cannot release the same semaphore multiple times
     *
     * The release operation will either remove current session from waiters
     * queue or release an already owned semaphore.
     */
    message ReleaseSemaphore {
        // Client-defined request id, echoed in the response
        uint64 req_id = 1;

        // Name of the semaphore to release
        string name = 2;
    }

    /**
     * Used to describe semaphores and watch them for changes
     *
     * WARNING: a describe operation will cancel previous watches on the same semaphore
     */
    message DescribeSemaphore {
        // Client-defined request id, echoed in the response
        uint64 req_id = 1;

        // Name of the semaphore to describe
        string name = 2;

        // Response will include owners list if true
        bool include_owners = 3;

        // Response will include waiters list if true
        bool include_waiters = 4;

        // Watch for changes in semaphore data
        bool watch_data = 5;

        // Watch for changes in semaphore owners (including owners data)
        bool watch_owners = 6;
    }

    /**
     * Used to create a new semaphore
     */
    message CreateSemaphore {
        // Client-defined request id, echoed in the response
        uint64 req_id = 1;

        // Name of the semaphore to create
        string name = 2;

        // Number of tokens that may be acquired by sessions
        uint64 limit = 3;

        // User-defined data that is attached to the semaphore
        bytes data = 4;
    }

    /**
     * Used to change semaphore data
     */
    message UpdateSemaphore {
        // Client-defined request id, echoed in the response
        uint64 req_id = 1;

        // Name of the semaphore to update
        string name = 2;

        // User-defined data that is attached to the semaphore
        bytes data = 3;
    }

    /**
     * Used to delete an existing semaphore
     */
    message DeleteSemaphore {
        // Client-defined request id, echoed in the response
        uint64 req_id = 1;

        // Name of the semaphore to delete
        string name = 2;

        // Will delete semaphore even if currently acquired by sessions
        bool force = 3;
    }

    oneof request {
        PingPong ping = 1;
        PingPong pong = 2;
        SessionStart session_start = 3;
        SessionStop session_stop = 4;
        Unsupported unsupported_5 = 5;
        Unsupported unsupported_6 = 6;
        AcquireSemaphore acquire_semaphore = 7;
        ReleaseSemaphore release_semaphore = 8;
        DescribeSemaphore describe_semaphore = 9;
        CreateSemaphore create_semaphore = 10;
        UpdateSemaphore update_semaphore = 11;
        DeleteSemaphore delete_semaphore = 12;
        Unsupported unsupported_13 = 13;
        Unsupported unsupported_14 = 14;
        Unsupported unsupported_15 = 15;
    }
}

/**
 * Session response message sent from server to client
 */
message SessionResponse {
    /**
     * Used for checking liveness of the connection
     */
    message PingPong {
        // Opaque number specified in the ping message is echoed in the pong message
        uint64 opaque = 1;
    }

    /**
     * Used to report connection and session level failures
     */
    message Failure {
        Ydb.StatusIds.StatusCode status = 1;
        repeated Ydb.Issue.IssueMessage issues = 2;
    }

    /**
     * Used to report a successful session create/restore operation
     */
    message SessionStarted {
        // A server generation id that may be used for restoring the session
        uint64 session_id = 1;

        // Timeout in milliseconds that will be used by the server
        uint64 timeout_millis = 2;
    }

    /**
     * Used to report a successful graceful termination of the session
     */
    message SessionStopped {
        uint64 session_id = 1;
    }

    /**
     * Used by the server to report when an acquire operation is added to the waiters queue
     */
    message AcquireSemaphorePending {
        uint64 req_id = 1;
    }

    /**
     * Used by the server to report the result of an acquire operation
     */
    message AcquireSemaphoreResult {
        uint64 req_id = 1;
        Ydb.StatusIds.StatusCode status = 2;
        repeated Ydb.Issue.IssueMessage issues = 3;

        // True if semaphore was acquired, false if acquire timed out
        bool acquired = 4;
    }

    /**
     * Used by the server to report the result of a release operation
     */
    message ReleaseSemaphoreResult {
        uint64 req_id = 1;
        Ydb.StatusIds.StatusCode status = 2;
        repeated Ydb.Issue.IssueMessage issues = 3;

        // True if semaphore was released, false if there was no active acquire operation
        bool released = 4;
    }

    /**
     * The result of the describe operation
     */
    message DescribeSemaphoreResult {
        uint64 req_id = 1;
        Ydb.StatusIds.StatusCode status = 2;
        repeated Ydb.Issue.IssueMessage issues = 3;
        SemaphoreDescription semaphore_description = 4;

        // True if a watch has been added for the semaphore
        bool watch_added = 5;
    }

    /**
     * Used to report a change in the watched semaphore
     */
    message DescribeSemaphoreChanged {
        uint64 req_id = 1;
        bool data_changed = 2;
        bool owners_changed = 3;
    }

    /**
     * The result of semaphore creation
     */
    message CreateSemaphoreResult {
        uint64 req_id = 1;
        Ydb.StatusIds.StatusCode status = 2;
        repeated Ydb.Issue.IssueMessage issues = 3;
    }

    /**
     * The result of semaphore update
     */
    message UpdateSemaphoreResult {
        uint64 req_id = 1;
        Ydb.StatusIds.StatusCode status = 2;
        repeated Ydb.Issue.IssueMessage issues = 3;
    }

    /**
     * The result of semaphore deletion
     */
    message DeleteSemaphoreResult {
        uint64 req_id = 1;
        Ydb.StatusIds.StatusCode status = 2;
        repeated Ydb.Issue.IssueMessage issues = 3;
    }

    oneof response {
        PingPong ping = 1;
        PingPong pong = 2;
        Failure failure = 3;
        SessionStarted session_started = 4;
        SessionStopped session_stopped = 5;
        Unsupported unsupported_6 = 6;
        Unsupported unsupported_7 = 7;
        AcquireSemaphorePending acquire_semaphore_pending = 8;
        AcquireSemaphoreResult acquire_semaphore_result = 9;
        ReleaseSemaphoreResult release_semaphore_result = 10;
        DescribeSemaphoreResult describe_semaphore_result = 11;
        DescribeSemaphoreChanged describe_semaphore_changed = 12;
        CreateSemaphoreResult create_semaphore_result = 13;
        UpdateSemaphoreResult update_semaphore_result = 14;
        DeleteSemaphoreResult delete_semaphore_result = 15;
        Unsupported unsupported_16 = 16;
        Unsupported unsupported_17 = 17;
        Unsupported unsupported_18 = 18;
    }
}

message CreateNodeRequest {
    string path = 1;
    Config config = 2;
    Ydb.Operations.OperationParams operation_params = 3;
}

message CreateNodeResponse {
    Ydb.Operations.Operation operation = 1;
}

message AlterNodeRequest {
    string path = 1;
    Config config = 2;
    Ydb.Operations.OperationParams operation_params = 3;
}

message AlterNodeResponse {
    Ydb.Operations.Operation operation = 1;
}

message DropNodeRequest {
    string path = 1;
    Ydb.Operations.OperationParams operation_params = 2;
}

message DropNodeResponse {
    Ydb.Operations.Operation operation = 1;
}

message DescribeNodeRequest {
    string path = 1;
    Ydb.Operations.OperationParams operation_params = 2;
}

message DescribeNodeResponse {
    Ydb.Operations.Operation operation = 1;
}

message DescribeNodeResult {
    Ydb.Scheme.Entry self = 1;
    Config config = 2;
}