/**
 * 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.
 */

package mesos;

option java_package = "org.apache.mesos";
option java_outer_classname = "Protos";


/**
 * Status is used to indicate the state of the scheduler and executor
 * driver after function calls.
 */
enum Status {
  DRIVER_NOT_STARTED = 1;
  DRIVER_RUNNING = 2;
  DRIVER_ABORTED = 3;
  DRIVER_STOPPED = 4;
}


/**
 * A unique ID assigned to a framework. A framework can reuse this ID
 * in order to do failover (see MesosSchedulerDriver).
 */
message FrameworkID {
  required string value = 1;
}


/**
 * A unique ID assigned to an offer.
 */
message OfferID {
  required string value = 1;
}


/**
 * A unique ID assigned to a slave. Currently, a slave gets a new ID
 * whenever it (re)registers with Mesos. Framework writers shouldn't
 * assume any binding between a slave ID and and a hostname.
 */
message SlaveID {
  required string value = 1;
}


/**
 * A framework generated ID to distinguish a task. The ID must remain
 * unique while the task is active. However, a framework can reuse an
 * ID _only_ if a previous task with the same ID has reached a
 * terminal state (e.g., TASK_FINISHED, TASK_LOST, TASK_KILLED, etc.).
 */
message TaskID {
  required string value = 1;
}


/**
 * A framework generated ID to distinguish an executor. Only one
 * executor with the same ID can be active on the same slave at a
 * time.
 */
message ExecutorID {
  required string value = 1;
}


/**
 * Describes a framework. If the user field is set to an empty string
 * Mesos will automagically set it to the current user. Note that the
 * ID is only available after a framework has registered, however, it
 * is included here in order to facilitate scheduler failover (i.e.,
 * if it is set then the MesosSchedulerDriver expects the scheduler is
 * performing failover). The amount of time that the master will wait
 * for the scheduler to failover before removing the framework is
 * specified by failover_timeout.
 * If checkpoint is set, framework pid, executor pids and status updates
 * are checkpointed to disk by the slaves.
 * Checkpointing allows a restarted slave to reconnect with old executors
 * and recover status updates, at the cost of disk I/O.
 * The role field is used to group frameworks for allocation decisions,
 * depending on the allocation policy being used.
 */
message FrameworkInfo {
  required string user = 1;
  required string name = 2;
  optional FrameworkID id = 3;
  optional double failover_timeout = 4 [default = 0.0];
  optional bool checkpoint = 5 [default = false];
  optional string role = 6 [default = "*"];
}


/**
 * Describes a command, executed via: '/bin/sh -c value'. Any uri's
 * specified are fetched before executing the command.
 * If executable field for an uri is set, executable file permission 
 * is set on the downloaded file. Also, if the downloaded file has ".tgz" 
 * extension it is extracted into the executor's working directory.
 * In addition, any environment variables are set before executing 
 * the command (so they can be used to "parameterize" your command).
 */
message CommandInfo {
  message URI {
    required string value = 1;
    optional bool executable = 2;
  }

  repeated URI uris = 1;
  optional Environment environment = 2;
  required string value = 3;
}


/**
 * Describes information about an executor. The 'data' field can be
 * used to pass arbitrary bytes to an executor.
 */
message ExecutorInfo {
  required ExecutorID executor_id = 1;
  optional FrameworkID framework_id = 8; // TODO(benh): Make this required.
  required CommandInfo command = 7;
  repeated Resource resources = 5;
  optional string name = 9;

  // Source is an identifier style string used by frameworks to track
  // the source of an executor. This is useful when it's possible for
  // different executor ids to be related semantically.
  // NOTE: Source is exposed alongside the resource usage of the
  // executor via JSON on the slave. This allows users to import
  // usage information into a time series database for monitoring.
  optional string source = 10;
  optional bytes data = 4;
}


/**
 * Describes a master. This will probably have more fields in the
 * future which might be used, for example, to link a framework webui
 * to a master webui.
 */
message MasterInfo {
  required string id = 1;
  required uint32 ip = 2;
  required uint32 port = 3 [default = 5050];
}


/**
 * Describes a slave. Note that the 'id' field is only available after
 * a slave is registered with the master, and is made available here
 * to facilitate re-registration.  If checkpoint is set, the slave is
 * checkpointing its own information and potentially frameworks'
 * information (if a framework has checkpointing enabled).
 */
message SlaveInfo {
  required string hostname = 1;
  optional int32 port = 8 [default = 5051];
  repeated Resource resources = 3;
  repeated Attribute attributes = 5;
  optional SlaveID id = 6;
  optional bool checkpoint = 7 [default = false];

  // Deprecated!
  optional string webui_hostname = 2;
  optional int32 webui_port = 4 [default = 8081];
}


/**
 * Describes an Attribute or Resource "value". A value is described
 * using the standard protocol buffer "union" trick.
 */
message Value {
  enum Type {
    SCALAR = 0;
    RANGES = 1;
    SET = 2;
    TEXT = 3;
  }

  message Scalar {
    required double value = 1;
  }

  message Range {
    required uint64 begin = 1;
    required uint64 end = 2;
  }

  message Ranges {
    repeated Range range = 1;
  }

  message Set {
    repeated string item = 1;
  }

  message Text {
    required string value = 1;
  }

  required Type type = 1;
  optional Scalar scalar = 2;
  optional Ranges ranges = 3;
  optional Set set = 4;
  optional Text text = 5;
}


/**
 * Describes an attribute that can be set on a machine. For now,
 * attributes and resources share the same "value" type, but this may
 * change in the future and attributes may only be string based.
 */
message Attribute {
  required string name = 1;
  required Value.Type type = 2;
  optional Value.Scalar scalar = 3;
  optional Value.Ranges ranges = 4;
  optional Value.Set set = 6;
  optional Value.Text text = 5;
}


/**
 * Describes a resource on a machine. A resource can take on one of
 * three types: scalar (double), a list of finite and discrete ranges
 * (e.g., [1-10, 20-30]), or a set of items. A resource is described
 * using the standard protocol buffer "union" trick.
 *
 * TODO(benh): Add better support for "expected" resources (e.g.,
 * cpus, memory, disk, network).
 */
message Resource {
  required string name = 1;
  required Value.Type type = 2;
  optional Value.Scalar scalar = 3;
  optional Value.Ranges ranges = 4;
  optional Value.Set set = 5;
  optional string role = 6 [default = "*"];
}


/*
 * A snapshot of resource usage statistics.
 */
message ResourceStatistics {
  required double timestamp = 1; // Snapshot time, in seconds since the Epoch.

  // CPU Usage Information:
  // Total CPU time spent in user mode, and kernel mode.
  optional double cpus_user_time_secs = 2;
  optional double cpus_system_time_secs = 3;

  // Number of CPUs allocated.
  required double cpus_limit = 4;

  // cpu.stat on process throttling (for contention issues).
  optional uint32 cpus_nr_periods = 7;
  optional uint32 cpus_nr_throttled = 8;
  optional double cpus_throttled_time_secs = 9;

  // Memory Usage Information:
  optional uint64 mem_rss_bytes = 5; // Resident Set Size.

  // Amount of memory resources allocated.
  optional uint64 mem_limit_bytes = 6;

  // TODO(bmahler): Add disk usage.
  // TODO(bmahler): Add network usage?
}


/**
 * Describes a snapshot of the resource usage for an executor.
 *
 * TODO(bmahler): Note that we want to be sending this information
 * to the master, and subsequently to the relevant scheduler. So
 * this proto is designed to be easy for the scheduler to use, this
 * is why we provide the slave id, executor info / task info.
 */
message ResourceUsage {
  required SlaveID slave_id = 1;
  required FrameworkID framework_id = 2;

  // Resource usage is for an executor. For tasks launched with
  // an explicit executor, the executor id is provided. For tasks
  // launched without an executor, our internal executor will be
  // used. In this case, we provide the task id here instead, in
  // order to make this message easier for schedulers to work with.

  optional ExecutorID executor_id = 3; // If present, this executor was
  optional string executor_name = 4;   // explicitly specified.

  optional TaskID task_id = 5; // If present, the task did not have an executor.

  // If missing, the isolation module cannot provide resource usage.
  optional ResourceStatistics statistics = 6;
}


/**
 * Describes a request for resources that can be used by a framework
 * to proactively influence the allocator.  If 'slave_id' is provided
 * then this request is assumed to only apply to resources on that
 * slave.
 */
message Request {
  optional SlaveID slave_id = 1;
  repeated Resource resources = 2;
}


/**
 * Describes some resources available on a slave. An offer only
 * contains resources from a single slave.
 */
message Offer {
  required OfferID id = 1;
  required FrameworkID framework_id = 2;
  required SlaveID slave_id = 3;
  required string hostname = 4;
  repeated Resource resources = 5;
  repeated Attribute attributes = 7;
  repeated ExecutorID executor_ids = 6;
}


/**
 * Describes a task. Passed from the scheduler all the way to an
 * executor (see SchedulerDriver::launchTasks and
 * Executor::launchTask). Either ExecutorInfo or CommandInfo should be set.
 * A different executor can be used to launch this task, and subsequent tasks
 * meant for the same executor can reuse the same ExecutorInfo struct.
 */
message TaskInfo {
  required string name = 1;
  required TaskID task_id = 2;
  required SlaveID slave_id = 3;
  repeated Resource resources = 4;
  optional ExecutorInfo executor = 5;
  optional CommandInfo command = 7;
  optional bytes data = 6;
}


/**
 * Describes possible task states. IMPORTANT: Mesos assumes tasks that
 * enter terminal states (see below) imply the task is no longer
 * running and thus clean up any thing associated with the task
 * (ultimately offering any resources being consumed by that task to
 * another task).
 */
enum TaskState {
  TASK_STAGING = 6;  // Initial state. Framework status updates should not use.
  TASK_STARTING = 0;
  TASK_RUNNING = 1;
  TASK_FINISHED = 2; // TERMINAL.
  TASK_FAILED = 3;   // TERMINAL.
  TASK_KILLED = 4;   // TERMINAL.
  TASK_LOST = 5;     // TERMINAL.
}


/**
 * Describes the current status of a task.
 */
message TaskStatus {
  required TaskID task_id = 1;
  required TaskState state = 2;
  optional string message = 4; // Possible message explaining state.
  optional bytes data = 3;
  optional SlaveID slave_id = 5;
}


/**
 * Describes possible filters that can be applied to unused resources
 * (see SchedulerDriver::launchTasks) to influence the allocator.
 */
message Filters {
  // Time to consider unused resources refused. Note that all unused
  // resources will be considered refused and use the default value
  // (below) regardless of whether Filters was passed to
  // SchedulerDriver::launchTasks. You MUST pass Filters with this
  // field set to change this behavior (i.e., get another offer which
  // includes unused resources sooner or later than the default).
  optional double refuse_seconds = 1 [default = 5.0];
}


/**
* Describes a collection of environment variables. This is used with
* CommandInfo in order to set environment variables before running a
* command.
*/
message Environment {
  message Variable {
    required string name = 1;
    required string value = 2;
  }

  repeated Variable variables = 1;
}


/**
 * A generic (key, value) pair used in various places for parameters.
 */
message Parameter {
  required string key = 1;
  required string value = 2;
}
 
 
/**
 * Collection of Parameter.
 */
message Parameters {
  repeated Parameter parameter = 1;
}


/**
 * Credential used for authentication.
 *
 * NOTE: The 'principal' is used for authenticating the framework with
 * the master. This is different from 'FrameworkInfo.user'
 * which is used to determine the user under which the framework's
 * executors/tasks are run.
 */
message Credential {
  required string principal = 1;
  optional bytes secret = 2;
}