include/mesos/executor/executor.proto

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

import "mesos/mesos.proto";

package mesos.executor;

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


/**
 * Executor event API.
 *
 * An event is described using the standard protocol buffer "union"
 * trick, see https://developers.google.com/protocol-buffers/docs/techniques#union.
 */
message Event {
  // Possible event types, followed by message definitions if
  // applicable.
  enum Type {
    SUBSCRIBED = 1;   // See 'Subscribed' below.
    LAUNCH = 2;       // See 'Launch' below.
    KILL = 3;         // See 'Kill' below.
    ACKNOWLEDGED = 4; // See 'Acknowledged' below.
    MESSAGE = 5;      // See 'Message' below.

    // Received when the slave asks the executor to shutdown/kill itself.
    SHUTDOWN = 6;

    ERROR = 7;        // See 'Error' below.
  }

  // First event received when the executor subscribes.
  // The 'id' field in the 'framework_info' will be set.
   message Subscribed {
    required ExecutorInfo executor_info = 1;
    required FrameworkInfo framework_info = 2;
    required SlaveInfo slave_info = 3;
  }

  // Received when the framework attempts to launch a task. Once
  // the task is successfuly launched, the executor must respond with
  // a TASK_RUNNING update (See TaskState in mesos.proto).
  message Launch {
    required TaskInfo task = 1;
  }

  // Received when the scheduler wants to kill a specific task. Once
  // the task is terminated, the executor should send a TASK_KILLED
  // (or TASK_FAILED) update. The terminal update is necessary so
  // Mesos can release the resources associated with the task.
  message Kill {
    required TaskID task_id = 1;
  }

  // Received when the slave acknowledges the receipt of status
  // update. Schedulers are responsible for explicitly acknowledging
  // the receipt of status updates that have 'update.status().uuid()'
  // field set. Unacknowledged updates can be retried by the executor.
  // They should also be sent by the executor whenever it
  // re-subscribes.
  message Acknowledged {
    required TaskID task_id = 1;
    required bytes uuid = 2;
  }

  // Received when a custom message generated by the scheduler is
  // forwarded by the slave. Note that this message is not
  // interpreted by Mesos and is only forwarded (without reliability
  // guarantees) to the executor. It is up to the scheduler to retry
  // if the message is dropped for any reason.
  message Message {
    required bytes data = 1;
  }

  // Received in case the executor sends invalid calls (e.g.,
  // required values not set).
  // TODO(arojas): Remove this once the old executor driver is no
  // longer supported. With HTTP API all errors will be signaled via
  // HTTP response codes.
  message Error {
    required string message = 1;
  }

  // Type of the event, indicates which optional field below should be
  // present if that type has a nested message definition.
  required Type type = 1;

  optional Subscribed subscribed = 2;
  optional Acknowledged acknowledged = 3;
  optional Launch launch = 4;
  optional Kill kill = 5;
  optional Message message = 6;
  optional Error error = 7;
}


/**
 * Executor call API.
 *
 * Like Event, a Call is described using the standard protocol buffer
 * "union" trick (see above).
 */
 message Call {
  // Possible call types, followed by message definitions if
  // applicable.
  enum Type {
    SUBSCRIBE = 1;    // See 'Subscribe' below.
    UPDATE = 2;       // See 'Update' below.
    MESSAGE = 3;      // See 'Message' below.
  }

  // Request to subscribe with the slave. If subscribing after a disconnection,
  // it must include a list of all the tasks and updates which haven't been
  // acknowledged by the scheduler.
  message Subscribe {
    repeated TaskInfo tasks = 1;
    repeated Update updates = 2;
  }

  // Notifies the scheduler that a task has transitioned from one
  // state to another. Status updates should be used by executors
  // to reliably communicate the status of the tasks that they
  // manage. It is crucial that a terminal update (see TaskState
  // in mesos.proto) is sent to the scheduler as soon as the task
  // terminates, in order for Mesos to release the resources allocated
  // to the task. It is the responsibility of the scheduler to
  // explicitly acknowledge the receipt of a status update. See
  // 'Acknowledged' in the 'Events' section above for the semantics.
  message Update {
    required TaskStatus status = 1;
    required double timestamp = 2;
    required bytes uuid = 3;
  }

  // Sends arbitrary binary data to the scheduler. Note that Mesos
  // neither interprets this data nor makes any guarantees about the
  // delivery of this message to the scheduler.
  // See 'Message' in the 'Events' section.
  message Message {
    required bytes data = 2;
  }

  // Identifies the executor which generated this call.
  required ExecutorID executor_id = 1;
  required FrameworkID framework_id = 2;

  // Type of the call, indicates which optional field below should be
  // present if that type has a nested message definition.
  // In case type is SUBSCRIBED, no message needs to be set.
  required Type type = 3;

  optional Subscribe subscribe = 4;
  optional Update update = 5;
  optional Message message = 6;
}