vm_tools/proto/container_host.proto

// 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 that will be running in the host that will be used
// by the container.
package vm_tools.container;

import "common.proto";

// Request protobuf for notifying host that a container has started up.
message ContainerStartupInfo {
  // The security token the container was given.
  string token = 1;

  // The vsock port on which garcon will be listening.
  uint32 garcon_port = 2;
}

// Request protobuf for notifying host that a container is shutting down.
message ContainerShutdownInfo {
  // The security token the container was given.
  string token = 1;
}

// Corresponds to a .desktop file from the Desktop Entry Spec:
// https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/
message Application {
  // A "localestring". Entries with a provided locale should set the |locale|
  // field to the value inside the [] and default entries should leave it empty.
  message LocalizedString {
    message StringWithLocale {
      string locale = 1;
      string value = 2;
    }
    repeated StringWithLocale values = 1;
  }

  // This is the 'key' for the application and used in other requests such as
  // launching the application or retrieving its icon.
  string desktop_file_id = 1;

  // These fields map directly to keys from the Desktop Entry spec.
  LocalizedString name = 2;
  LocalizedString comment = 3;
  repeated string mime_types = 4;
  bool no_display = 5;
  string startup_wm_class = 6;
  bool startup_notify = 7;

  // If set, the package_id of the installed package that owns the .desktop
  // file. Allows for operations like uninstalling the related application.
  string package_id = 8;
}

// Request protobuf for notifying the host of our list of installed
// applications.
message UpdateApplicationListRequest {
  // The security token the container was given.
  string token = 1;
  // The list of all the installed applications.
  repeated Application application = 2;
}

// Request protobuf for opening a URL in the host.
message OpenUrlRequest {
  // The URL to open.
  string url = 1;

  // The security token the container was given.
  string token = 2;
}

// Progress update when a Linux package install is in progress or completed.
message InstallLinuxPackageProgressInfo {
  // The security token the container was given.
  string token = 1;

  enum Status {
    // Install has completed and was successful. No further signals will be
    // sent after this one.
    SUCCEEDED = 0;

    // Install failed to complete, the specific reason will be in
    // failure_details. No further signals will be sent after this one.
    FAILED = 1;

    // This is while packages are being downloaded.
    DOWNLOADING = 2;

    // General installation phase for package and dependency installation.
    INSTALLING = 3;
  }

  // Current status of the installation progress.
  Status status = 2;

  // Overall percentage progress.
  uint32 progress_percent = 3;

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

// Request protobuf for opening a new terminal in the container.
message OpenTerminalRequest {
  // The security token the container was given.
  string token = 1;

  // Extra parameters to use when launching a terminal application that allow
  // executing a command inside the terminal.
  repeated string params = 2;
}

// Request protobuf for updating the container MIME types.
message UpdateMimeTypesRequest {
  // The security token the container was given.
  string token = 1;

  // MIME type mappings with file extension as the key without a period prefix
  // and MIME type as the value.
  map<string, string> mime_type_mappings = 2;
}

// Service that is notified of events from a container.
service ContainerListener {
  // Called by each container when it starts up to indicate that it is ready to
  // handle incoming requests.
  rpc ContainerReady(ContainerStartupInfo) returns (EmptyMessage);

  // Called by each container before it shuts down to indicate it should no
  // longer be sent incoming requests.
  rpc ContainerShutdown(ContainerShutdownInfo) returns (EmptyMessage);

  // Called by a container to update the list of applications installed within
  // the container.
  rpc UpdateApplicationList(UpdateApplicationListRequest)
      returns (EmptyMessage);

  // Called by a container to open the specified URL with the browser in the
  // host.
  rpc OpenUrl(OpenUrlRequest) returns (EmptyMessage);

  // Called by a container during a Linux package install to update on progress
  // and completion/failure.
  rpc InstallLinuxPackageProgress(InstallLinuxPackageProgressInfo)
      returns (EmptyMessage);

  // Called by a container to have the host open a new terminal that is
  // connected to the container.
  rpc OpenTerminal(OpenTerminalRequest) returns (EmptyMessage);

  // Called by a container to update the MIME type associations for this
  // container.
  rpc UpdateMimeTypes(UpdateMimeTypesRequest) returns (EmptyMessage);
}