// Copyright (c) 2022 Boston Dynamics, Inc.  All rights reserved.
//
// Downloading, reproducing, distributing or otherwise using the SDK Software
// is subject to the terms and conditions of the Boston Dynamics Software
// Development Kit License (20191101-BDSDK-SL).

syntax = "proto3";

package bosdyn.api.mission;

option java_outer_classname = "RemoteProto";

import "bosdyn/api/header.proto";
import "bosdyn/api/lease.proto";
import "bosdyn/api/mission/util.proto";

// Information to initialize a session to the remote service
// for a particular mission node.
message EstablishSessionRequest {
    // Common request header.
    RequestHeader header = 1;

    // All leases that the remote service may need.
    repeated Lease leases = 2;

    // Use this to provide other data (e.g. from the blackboard).
    // The RemoteGrpc node will provide the name of the node automatically.
    repeated VariableDeclaration inputs = 3;

}

// Provide the id to use for the particular mission node to tick this remote service.
message EstablishSessionResponse {
    // Common response header.
    ResponseHeader header = 1;

    // Possible results of establishing a session.
    enum Status {
        // Status unknown/unset.
        STATUS_UNKNOWN = 0;
        // Provided inputs / outputs are compatible.
        STATUS_OK = 1;
        // Remote service needs leases on additional resources.
        // If set, the missing_lease_resources field should contain the resources needed but not
        // provided.
        STATUS_MISSING_LEASES = 2;
        // Remote service needs additional inputs.
        STATUS_MISSING_INPUTS = 3;

        // Note there is no status for an error condition in the LeaseUseResult field.
        // Even if STATUS_OK is returned, an error may be indicated in lease_use_results.
    }
    // Result of this establish session request.
    Status status = 2;

    // On success, contains an ID for this session.
    string session_id = 3;

    // Need to provide leases on these resources.
    repeated string missing_lease_resources = 4;

    // Details about how any leases were used.
    // Allowed to be empty, if leases were not actually used.
    repeated LeaseUseResult lease_use_results = 5;

    // The inputs required by the contacted node that were not mentioned in the request.
    repeated VariableDeclaration missing_inputs = 6;

}

// Request that the remote tick itself for a particular node in the mission.
message TickRequest {
    // Common request header.
    RequestHeader header = 1;
    // Session ID as returned by the EstablishSessionResponse.
    // Used to guarantee coherence between a single client and a servicer.
    string session_id = 2;

    // All leases that the remote service may need.
    repeated Lease leases = 3;

    // Inputs provided to the servicer.
    repeated KeyValue inputs = 4;
}

// Response with the results of the tick.
// Remote services should strive to return quickly, even if only returning RUNNING.
message TickResponse {
    // Common response header.
    ResponseHeader header = 1;

    // Possible results from the node. The FAILURE, RUNNING, and SUCCESS statuses map to the
    // behavior tree terms, all others indicate an error in the TickRequest.
    enum Status {
        // Invalid; do not use.
        STATUS_UNKNOWN = 0;
        // Node completed but failed.
        STATUS_FAILURE = 1;
        // Node is processing and may finish in a future tick.
        STATUS_RUNNING = 2;
        // Node completed and succeeded.
        STATUS_SUCCESS = 3;
        // The request provided an invalid session ID.
        STATUS_INVALID_SESSION_ID = 4;
        // The request was missing required leases.
        STATUS_MISSING_LEASES = 5;
        // The request was missing required inputs.
        STATUS_MISSING_INPUTS = 6;
    }
    // Result of the current tick.
    Status status = 3;

    // Need to provide leases on these resources.
    repeated string missing_lease_resources = 4;

    // Details about how any leases were used.
    // Allowed to be empty, if leases were not actually used.
    repeated LeaseUseResult lease_use_results = 5;

    // Filled out when status is STATUS_MISSING_INPUTS, indicating what inputs were not in the
    // request.
    repeated VariableDeclaration missing_inputs = 7;

    // If you need to report other error details, you can use this field.
    string error_message = 8;
}

// Used to stop a node that was previously ticked, so that it knows that
// the next Tick represents a restart rather than a continuation.
message StopRequest {
    // Common request header.
    RequestHeader header = 1;
    // Session ID as returned by the EstablishSessionResponse.
    // Used to guarantee coherence between a single client and a servicer.
    string session_id = 2;
}

// Results of attempting to stop a remote node.
message StopResponse {
    // Common response header.
    ResponseHeader header = 1;
    // Possible results for a StopRequest.
    enum Status {
        // Status unknown/unset.
        STATUS_UNKNOWN = 0;
        // Service stopped.
        STATUS_OK = 1;
        // The request provided an invalid session ID.
        STATUS_INVALID_SESSION_ID = 2;
    }
    // Result of the stop request.
    Status status = 2;
}

// End the session originally established by an EstablishSessionRequest.
message TeardownSessionRequest {
    // Common request header.
    RequestHeader header = 1;
    // Session ID as returned by the EstablishSessionResponse.
    // Used to guarantee coherence between a single client and a servicer.
    string session_id = 2;
}

// Results of ending a session.
message TeardownSessionResponse {
    // Common response header.
    ResponseHeader header = 1;

    // Possible results of ending a session.
    enum Status {
        // Status unknown/unset.
        STATUS_UNKNOWN = 0;
        // Session was torn down -- servicer has probably wiped all associated data / state.
        STATUS_OK = 1;
        // The request provided an invalid session ID.
        // This may mean the session was already torn down.
        STATUS_INVALID_SESSION_ID = 2;
    }
    // The result of a TeardownSessionRequest.
    Status status = 2;
}