syntax = "proto3";
package services.controller;
option go_package = "gitlab.com/rigetti/share/service-model/golang/controller";
import "controller/job.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

// A UUID (Universally Unique ID)
//
// The format is a UUID4 stored as 128 bits. The 0 UUID and any bit pattern that
// is invalid for UUID v4 are invalid and will cause the request to fail.
message Uuid {

    // The high bits of the UUID
    fixed64 high = 1;

    // The low bits of the UUID
    fixed64 low = 2;
}

// A request to execute multiple ControllerJobs as if they were sent as separate requests.
// Note that the job execution IDs will be returned in the same order as the requests,
// but execution itself may occur out of that order depending on executor configuration.
message BatchExecuteControllerJobsRequest {
    repeated .services.controller.ExecuteControllerJobRequest requests = 1;

    // See comment on `ExecuteControllerJobRequest.idempotency_key`.
    optional .services.controller.Uuid idempotency_key = 2;
}
message BatchExecuteControllerJobsResponse {
    repeated .services.controller.ExecuteControllerJobResponse responses = 1;
}

// A request to execute a given ControllerJob on a specific target with one or more configurations.
//
// This action is *atomic* in that a job for each configuration will be queued, or none of them will.
// On success, the response will contain a sequence of job IDs where the number and order of IDs returned
// will correspond to the number and order of configurations given. However, note that execution in the
// order of the given configurations is not guaranteed. If there is a failure to queue any of the jobs,
// then none will be queued. A request must have at least one configuration, otherwise an error will be
// returned.
message ExecuteControllerJobRequest {

    // One or more configurations against which to execute the provided job.
    //
    // The response will include one `job_execution_id` for each entry in this list,
    // each corresponding to its configuration in the same order.
    repeated .models.controller.JobExecutionConfiguration execution_configurations = 3;
    .services.controller.ExecutionOptions options = 4;

    // Setting the idempotency key permits retrying failed execute-controller-job
    // requests (or batch requests) without creating duplicate jobs.
    //
    // If the server sees an idempotency key corresponding to an already-enqueued
    // job (or batch of jobs), it will return a copy of the original job-submission
    // response, i.e., the IDs of the already-enqueued jobs.
    //
    // When submitting jobs, a failure response from the server always means that no
    // jobs were enqueued, so retrying job submission will not create duplicate
    // jobs. However, if submission fails due to a gRPC timeout, the client has no
    // way of knowing whether the service handled the original request or not, so
    // without the idempotency key, retrying may or may not create duplicate jobs.
    //
    // Clients should not use the same idempotency key for separate requests. The
    // API makes no guarantees about the server behavior in that case.
    //
    // A given idempotency key is valid for at least as long as any job IDs
    // generated from the corresponding request are known to the server.
    // For a job submitted as part of a session, the idempotency key will be valid
    // for at least as long as the session ID itself is valid. For all jobs, the
    // idempotency key will be valid for at least as long as the job is enqueued,
    // executing, or waiting for results retrieval.
    //
    // This field is *ignored* for requests that are part of a `BatchExecuteControllerJobRequest`;
    // use `BatchExecuteControllerJobRequest.idempotency_key` instead.
    optional .services.controller.Uuid idempotency_key = 5;
    oneof job {
        .models.controller.EncryptedControllerJob encrypted = 201;
    }
    oneof target {
        // Required by the gateway to forward requests to the correct execution host.

        string quantum_processor_id = 101;
        string endpoint_id = 102;
    }
}

// Options specified on execution requests describing any features or processes requested before or after job execution.
message ExecutionOptions {

    // If jobs contain settings that would cause managed settings to change values,
    // that job will be rejected unless this field is set to true and the submitter has the appropriate authorization.
    bool bypass_settings_protection = 3;

    // The timeout while running a job; the job will be evicted from the hardware
    // once this time has elapsed.
    //
    // If unset, the job's estimated duration will be used;
    // if the job does not have an estimated duration, the default
    // timeout is selected by the service.
    //
    // The service may also enforce a maximum value for this field.
    optional .google.protobuf.Duration timeout = 4;

    reserved 1;

    reserved 2;
}
message ExecuteControllerJobResponse {

    // One execution ID per input JobExecutionConfiguration, in the same order as the input.
    repeated string job_execution_ids = 1;
}
message GetControllerJobResultsRequest {

    // Which Controller Job execution to query for results
    string job_execution_id = 1;
    oneof target {
        // Required by the gateway to forward requests to the correct execution host.

        string quantum_processor_id = 101;
        string endpoint_id = 102;
    }
}
message GetControllerJobResultsResponse {
    .models.controller.ControllerJobExecutionResult result = 1;
}

// Cancel all given jobs that have yet to begin executing.
// This endpoint is *not* atomic, and will attempt to cancel every job even
// when some jobs cannot be canceled. A job can be canceled only if it
// has not yet started executing.
//
// Success response indicates only that the request was received. Cancellation
// is not guaranteed, as it is based on job state at time of cancellation, and is
// completed on a best-effort basis.
message CancelControllerJobsRequest {
    repeated string job_ids = 1;
    oneof target {
        // Required by ConServ gateway to forward requests to the correct rackhost.

        string quantum_processor_id = 101;
        string endpoint_id = 102;
    }
}
message CancelControllerJobsResponse {
}
message GetControllerJobStatusRequest {
    string job_id = 1;
    oneof target {
        // Required by ConServ gateway to forward requests to the correct rackhost.

        string quantum_processor_id = 101;
        string endpoint_id = 102;
    }
}
message GetControllerJobStatusResponse {
    .services.controller.GetControllerJobStatusResponse.Status status = 1;

    // Best-effort estimate of how long it will be (from the time the response is
    // generated) until the job is finished executing.
    // This will not attempt to account for future schedule modifications, such as
    // the arrival of a higher-priority job or a maintenance reservation being
    // scheduled.
    // The minimum estimate uses each job's estimated duration, if available; the
    // maximum estimate uses the execution timeout enforced by the controller
    // service.
    .services.controller.EstimatedDelay estimated_job_completion_delay = 2;
    enum Status {
        UNKNOWN = 0;
        QUEUED = 1;
        RUNNING = 2;
        SUCCEEDED = 3;
        FAILED = 4;
        CANCELED = 5;
        POST_PROCESSING = 6;
    }
}

// An estimation of the delay before a specific event, such as when a queued job
// is expected to be dequeued and run.
message EstimatedDelay {

    // Our most optimistic estimate of the delay before the event (will always be the lowest duration in
    // this message)
    .google.protobuf.Duration minimum = 1;

    // Our most pessimistic estimate of the delay (will always be the highest duration in this
    // message)
    .google.protobuf.Duration maximum = 2;

    // When these estimates were calculated
    .google.protobuf.Timestamp now = 3;
}

service Controller {

    rpc ExecuteControllerJob(.services.controller.ExecuteControllerJobRequest) returns (.services.controller.ExecuteControllerJobResponse) {
    }

    rpc BatchExecuteControllerJobs(.services.controller.BatchExecuteControllerJobsRequest) returns (.services.controller.BatchExecuteControllerJobsResponse) {
    }

    rpc GetControllerJobResults(.services.controller.GetControllerJobResultsRequest) returns (.services.controller.GetControllerJobResultsResponse) {
    }

    rpc CancelControllerJobs(.services.controller.CancelControllerJobsRequest) returns (.services.controller.CancelControllerJobsResponse) {
    }

    rpc GetControllerJobStatus(.services.controller.GetControllerJobStatusRequest) returns (.services.controller.GetControllerJobStatusResponse) {
    }
}