// Copyright 2018 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

option cc_enable_arenas = true;

// This file defines services for tremplin, the container springboard service.
package vm_tools.tremplin;
option go_package = "tremplin_proto";

// This needs to be duplicated because the gyp rule for building
// go code makes it difficult to have imports.
message EmptyMessage {}

message CreateContainerRequest {
  // Name of the container to start within the VM.
  string container_name = 1;

  // LXD image server URL. Only simplestreams is supported for now.
  string image_server = 2;

  // LXD image alias.
  string image_alias = 3;
}

message CreateContainerResponse {
  enum Status {
    // The status of creating the container is unknown.
    UNKNOWN = 0;

    // The container is now being created. Tremplin will update the caller
    // on the result via the UpdateCreateStatus RPC.
    CREATING = 1;

    // A container with this name already exists.
    EXISTS = 2;

    // The container could not be created.
    FAILED = 3;
  }

  // Container creation status.
  Status status = 1;

  // The failure_reason if the container could not be created.
  string failure_reason = 2;
}

message StartContainerRequest {
  // Name of the container to start within the VM.
  string container_name = 1;

  // SSH public key.
  string host_public_key = 2;

  // SSH private key.
  string container_private_key = 3;

  // Container token.
  string token = 4;

  // If true, StartContainer will return immediately and provide updates to the
  // host via UpdateStartStatus. If false, StartContainer will block until the
  // container has started. This field will be required to be true once all
  // clients are migrated to use async.
  bool async = 5;
}

message StartContainerResponse {
  enum Status {
    // The status of starting the container is unknown.
    UNKNOWN = 0;

    // The container has started.
    STARTED = 1;

    // The container was already running.
    RUNNING = 2;

    // The container could not be started.
    FAILED = 3;

    // The container is starting. Further updates will be delievered via
    // UpdateStartStatus.
    STARTING = 4;

    // The container is remapping its rootfs uids/gids and will take longer than
    // usual to start up. Further updates will be delievered via
    // UpdateStartStatus.
    REMAPPING = 5;
  }

  // Container startup status.
  Status status = 1;

  // The failure_reason if the container could not be started.
  string failure_reason = 2;
}

message GetContainerUsernameRequest {
  // Name of the container to get the primary username from.
  string container_name = 1;
}

message GetContainerUsernameResponse {
  enum Status {
    // The result is unknown.
    UNKNOWN = 0;

    // The primary username is stored in the username field.
    SUCCESS = 1;

    // A container with the specified name doesn't exist.
    CONTAINER_NOT_FOUND = 2;

    // The container is not running, so the username could not be found.
    CONTAINER_NOT_RUNNING = 3;

    // The primary user doesn't exist.
    USER_NOT_FOUND = 4;

    // Some part of the operation failed.
    FAILED = 5;
  }

  // Status of getting the container's username.
  Status status = 1;

  // The primary username of the container, if successful.
  string username = 2;

  // The failure_reason if the username could not be retrieved.
  string failure_reason = 3;

  // The primary homedir of the container, if successful.
  string homedir = 4;
}

message SetUpUserRequest {
  // Name of the container to set up.
  string container_name = 1;

  // Username for the first user in the container.
  string container_username = 2;
}

message SetUpUserResponse {
  enum Status {
    // The status of setting up the user is unknown.
    UNKNOWN = 0;

    // The user has been set up sucessfully.
    SUCCESS = 1;

    // The user already exists.
    EXISTS = 2;

    // Setting up the user failed.
    FAILED = 3;
  }

  // Status of setting up the user.
  Status status = 1;

  // The failure_reason if the user was not set up successfully.
  string failure_reason = 2;

  // The primary username of the container, if successful or if user already
  // exists.  This may be different from container_username in SetUpUserRequest
  // if the container already exists, and uid 1000 user has changed username.
  string username = 3;
}

message TremplinStartupInfo {}

// Sent by tremplin to update the host on the create progress of a container.
message ContainerCreationProgress {
  enum Status {
    // Creation status is unknown.
    UNKNOWN = 0;

    // The container is downloading.
    DOWNLOADING = 1;

    // The container has been created.
    CREATED = 2;

    // The container download timed out.
    DOWNLOAD_TIMED_OUT = 3;

    // The container creation was cancelled.
    CANCELLED = 4;

    // One or more steps failed and the container could not be created.
    FAILED = 5;
  }

  // The current status of the container.
  Status status = 1;

  // Name of the container to create within the VM.
  string container_name = 2;

  // The download progress, if status is DOWNLOADING.
  int32 download_progress = 3;

  // The failure_reason if the container could not be created.
  string failure_reason = 4;
}

// Sent by tremplin to update the host on the start progress of a container.
message ContainerStartProgress {
  enum Status {
    // Start status is unknown.
    UNKNOWN = 0;

    // The container has started.
    STARTED = 1;

    // The container start was cancelled.
    CANCELLED = 2;

    // One or more steps failed and the container could not be started.
    FAILED = 3;
  }

  // The current status of the container.
  Status status = 1;

  // Name of the container to start.
  string container_name = 2;

  // The failure_reason if the container could not be started.
  string failure_reason = 3;
}

message GetContainerInfoRequest {
  // Name of the container to get information for.
  string container_name = 1;
}

message GetContainerInfoResponse {
  enum Status {
    // The result is unknown.
    UNKNOWN = 0;

    // The container is currently running.
    RUNNING = 1;

    // The container is not running.
    STOPPED = 2;

    // The container with that name doesn't exist.
    NOT_FOUND = 3;

    // Some part of the operation failed.
    FAILED = 4;
  }

  // Current container status.
  Status status = 1;

  // The failure_reason if container info could not be returned.
  string failure_reason = 2;

  // The IPv4 address of the container. This field is only valid if the
  // container is running.
  fixed32 ipv4_address = 3;
}

message SetTimezoneRequest {
  // Timezone name as per values from the timezone-data package in
  // /usr/share/zoneinfo.
  string timezone_name = 1;

  // Timezone properties in POSIX compatible TZ environment variable format
  // (see 'man timezone'). Used if the guest VM does not support timezone-data
  // timezone names.
  //
  // cicerone/tzif_parser.h can extract these strings from TZif files.
  string posix_tz_string = 2;
}

message SetTimezoneResponse {
  // The number of LXD containers for which the timezone was successfully set.
  int32 successes = 1;

  // The failure_reason if the request was unsuccessful.
  repeated string failure_reasons = 2;
}

message ExportContainerRequest {
  // Name of the container to export.
  string container_name = 1;

  // Path to write the exported container.
  string export_path = 2;
}

message ExportContainerResponse {
  enum Status {
    // The result is unknown.
    UNKNOWN = 0;

    // Export is completed.
    DONE = 1;

    // The container is exporting. Further updates will be delievered via
    // UpdateExportStatus.
    EXPORTING = 2;

    // One or more steps failed and the container could not be exported.
    FAILED = 3;
  }

  // Current container status.
  Status status = 1;

  // The failure_reason if container info could not be returned.
  string failure_reason = 2;

}

// Sent by tremplin to update the host on the export progress of a container.
message ContainerExportProgress {
  // Name of the container to export.
  string container_name = 1;

  enum Status {
    // The result is unknown.
    UNKNOWN = 0;

    // Export is completed.
    DONE = 1;

    // The container is (still) exporting.
    EXPORTING = 2;

    // One or more steps failed and the container could not be exported.
    FAILED = 3;
  }

  // Container status.
  Status status = 2;

  // Overall percentage progress.
  uint32 progress_percent = 3;

  // Details relating to the failure state.
  string failure_reason = 4;
}

// Tremplin service methods.
service Tremplin {
  rpc CreateContainer(CreateContainerRequest) returns (CreateContainerResponse);
  rpc StartContainer(StartContainerRequest) returns (StartContainerResponse);
  rpc GetContainerUsername(GetContainerUsernameRequest)
      returns (GetContainerUsernameResponse);
  rpc SetUpUser(SetUpUserRequest) returns (SetUpUserResponse);
  rpc GetContainerInfo(GetContainerInfoRequest)
      returns (GetContainerInfoResponse);
  rpc SetTimezone(SetTimezoneRequest) returns (SetTimezoneResponse);
  rpc ExportContainer(ExportContainerRequest) returns (ExportContainerResponse);
}

// Service that is notified of events from tremplin.
service TremplinListener {
  rpc TremplinReady(TremplinStartupInfo) returns (EmptyMessage);
  rpc UpdateCreateStatus(ContainerCreationProgress) returns (EmptyMessage);
  rpc UpdateStartStatus(ContainerStartProgress) returns (EmptyMessage);
  rpc UpdateExportStatus(ContainerExportProgress) returns (EmptyMessage);
}