/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * 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.
 */

/*
 * Protocol Buffers describing the Provision API, for communicating with a runner
 * for job and environment provisioning information over GRPC.
 */

syntax = "proto3";

package org.apache.beam.model.fn_execution.v1;

option go_package = "fnexecution_v1";
option java_package = "org.apache.beam.model.fnexecution.v1";
option java_outer_classname = "ProvisionApi";

import "google/protobuf/struct.proto";

// A service to provide runtime provisioning information to the SDK harness
// worker instances -- such as pipeline options, resource constraints and
// other job metadata -- needed by an SDK harness instance to initialize.
service ProvisionService {
    // Get provision information for the SDK harness worker instance.
    rpc GetProvisionInfo(GetProvisionInfoRequest) returns (GetProvisionInfoResponse);
}

// A request to get the provision info of a SDK harness worker instance.
message GetProvisionInfoRequest { }

// A response containing the provision info of a SDK harness worker instance.
message GetProvisionInfoResponse {
    ProvisionInfo info = 1;
}

// Runtime provisioning information for a SDK harness worker instance,
// such as pipeline options, resource constraints and other job metadata
message ProvisionInfo {
    // (required) The job ID.
    string job_id = 1;
    // (required) The job name.
    string job_name = 2;
    // (required) The worker ID. Often this will be the hostname.
    //
    // This is independent of the id passed to the SDK harness via the 'id'
    // argument in the Beam container contract.
    string worker_id = 5;

    // (required) Pipeline options. For non-template jobs, the options are
    // identical to what is passed to job submission.
    google.protobuf.Struct pipeline_options = 3;

    // (optional) Resource limits that the SDK harness worker should respect.
    // Runners may -- but are not required to -- enforce any limits provided.
    Resources resource_limits = 4;

    // (required) The artifact retrieval token produced by
    // ArtifactStagingService.CommitManifestResponse.
    string retrieval_token = 6;
}

// Resources specify limits for local resources, such memory and cpu. It
// is used to inform SDK harnesses of their allocated footprint.
message Resources {
    // Memory limits.
    message Memory {
        // (optional) Hard limit in bytes. A zero value means unspecified.
        uint64 size = 1;

        // TODO(herohde) 10/20/2017: consider soft limits, shm usage?
    }
    // (optional) Memory usage limits. SDKs can use this value to configure
    // internal buffer sizes and language specific sizes.
    Memory memory = 1;

    // CPU limits.
    message Cpu {
        // (optional) Shares of a cpu to use. Fractional values, such as "0.2"
        // or "2.5", are fine. Any value <= 0 means unspecified.
        float shares = 1;

        // TODO(herohde) 10/20/2017: consider cpuset?
    }
    // (optional) CPU usage limits.
    Cpu cpu = 2;

    // Disk limits.
    message Disk {
        // (optional) Hard limit in bytes. A zero value means unspecified.
        uint64 size = 1;
    }
    // (optional) Disk size limits for the semi-persistent location.
    Disk semi_persistent_disk = 3;
}
