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/
// with some additional parameters to support broader compatibility.
// This message is replicated in system_api/dbus/vm_applications/apps.proto,
// and the two definitions should be kept in sync.
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;
  }

  // A repeated "localestring". Entries with a locale should set the |locale|
  // field to the value inside the [], e.g for the key "Name[fr]", |locale|
  // should be "fr"; for the default entry, |locale| should be empty. The
  // browser is responsible for mapping this to something it can use.
  message LocaleStrings {
    message StringsWithLocale {
      string locale = 1;
      repeated string value = 2;
    }
    repeated StringsWithLocale 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;
  LocaleStrings keywords = 9;
  string executable_file_name = 10;
  string exec = 12;

  // If set, the package_id of the installed package that owns this .desktop
  // file. If not set, the .desktop file is not owned by an installed package.
  string package_id = 8;

  // Similar to |mime_types| for applications that do not support mime types.
  repeated string extensions = 11;
}

// 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;
}

// A message sent to indicate how many UpdateApplicationList are
// scheduled to be sent.
message PendingAppListUpdateCount {
  // Security token for the container.
  string token = 1;

  // The number of app list updates that have been triggered but not yet sent.
  uint32 count = 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;

  // Command identifier to track installation progress.
  string command_uuid = 5;
}

message UninstallPackageProgressInfo {
  // The security token the container was given.
  string token = 1;

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

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

    // This is sent while the uninstall is in progress. progress_percent will be
    // filled in.
    UNINSTALLING = 2;
  }

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

  // Overall percentage progress.
  uint32 progress_percent = 3;

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

message ApplyAnsiblePlaybookProgressInfo {
  // The security token the container was given.
  string token = 1;

  enum Status {
    UNKNOWN = 0;

    // Application has completed and was successful. No further signals will be
    // sent after this one.
    SUCCEEDED = 1;

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

    // Ansible playbook is being currently applied.
    IN_PROGRESS = 3;
  }

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

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

// 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 requesting the host to launch a SelectFile dialog.
message SelectFileRequest {
  // The security token the container was given.
  string token = 1;

  // The type of file dialog to be shown.
  // 'open-file': For opening files. Default.
  // 'open-multi-file': Allow opening multiple files.
  // 'saveas-file': For saving a file. Allows nonexistent file to be selected.
  // 'folder': For selecting a folder. Allows nonexistent folder to be selected.
  // 'upload-folder': For uploading a folder.
  string type = 2;

  // The title to be displayed in the dialog. If this string is empty, the
  // default title is used.
  string title = 3;

  // The default path and suggested file name to be shown in the dialog. This
  // only works for SELECT_SAVEAS_FILE and SELECT_OPEN_FILE.
  // Can be an empty string to indicate the platform default.
  string default_path = 4;

  // Comma separated list of file extensions to filter which files are shown in
  // the dialog. Leave empty to show all files. Do not include leading dot.
  string allowed_extensions = 5;
}

// Response to SelectFileRequest contains list of files selected by user.
message SelectFileResponse {
  repeated string files = 1;
}

// 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;
}

// For notifying a watched directory has a change.
message FileWatchTriggeredInfo {
  // The security token the container was given.
  string token = 1;

  // The watched directory in the container relative to $HOME that has a change.
  string path = 2;
}

// For notifying of low disk space.
message LowDiskSpaceTriggeredInfo {
  // The security token the container was given.
  string token = 1;

  // The size of the remaining free space in bytes.
  uint64 free_bytes = 2;
}

// Request protobuf for forwarding Security Key requests to the gnubbyd
// extension.
message ForwardSecurityKeyMessageRequest {
  // JSON message that will be forwarded to the Chrome Extension.
  // It will be used by the extension to construct a request for gnubbyd.
  // Examples of the message:
  //   - {"type":"GNUBBY_MESSAGE",
  //      "payload": {"type":"auth-agent@openssh.com","data":[124]}}
  //   - {"type":"HELLO"}
  //   - {"data": [124]}
  string message = 1;
}

// Response for ForwardSecurityKeyMessageRequest.
message ForwardSecurityKeyMessageResponse {
  // JSON message that contains response from gnubbyd and additional info, if
  // any. It will be passed to the VM as-is.
  // Examples of the message:
  //   - {"type":"GNUBBY_REPLY",
  //      "payload": {"type":"auth-agent@openssh.com","data":[1,2,3,124]}}
  //   - {"type":"HELLO", "version":"1.2.3.4"}
  //   - {"data": [1,2,123]}
  string message = 1;
}

// For getting information about the VM disk.
message GetDiskInfoRequest {
  // The security token the container was given.
  string token = 1;
}

// Response from a GetDiskInfoRequest
message GetDiskInfoResponse {
  // 0 if the request was successful.
  int64 error = 1;
  // Current space available in bytes.
  uint64 available_space = 2;
  // How much the disk can be expanded by in bytes.
  uint64 expandable_space = 3;
}

// For requesting that the disk is expanded.
message RequestSpaceRequest {
  // The security token the container was given.
  string token = 1;
  // The amount of space requested in bytes
  uint64 space_requested = 2;
}

// Response from RequestSpaceRequest.
message RequestSpaceResponse {
  // The amount of space granted in bytes
  uint64 space_granted = 1;
  // 0 if the request was successful.
  int64 error = 2;
}

// For notifying Chrome that the disk can be shrunk.
message ReleaseSpaceRequest {
  // The security token the container was given.
  string token = 1;
  // Amount of space that can be released in bytes.
  uint64 space_to_release = 2;
}

// Response from ReleaseSpaceRequest
message ReleaseSpaceResponse {
  // Amount of space that was released in bytes.
  uint64 space_released = 1;
  // 0 if the request was successful.
  int64 error = 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 indicate that an app list update has
  // been scheduled or completed.
  rpc PendingUpdateApplicationListCalls(PendingAppListUpdateCount)
      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);

  rpc UninstallPackageProgress(UninstallPackageProgressInfo)
      returns (EmptyMessage);

  // Called by a container during a Ansible playbook application to update on
  // progress and completion/failure.
  rpc ApplyAnsiblePlaybookProgress(ApplyAnsiblePlaybookProgressInfo)
      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);

  // Called by a container when there is a change in a watched directory. Used
  // for FilesApp.
  rpc FileWatchTriggered(FileWatchTriggeredInfo) returns (EmptyMessage);

  // Called by a container when free disk space inside the container is low.
  rpc LowDiskSpaceTriggered(LowDiskSpaceTriggeredInfo) returns (EmptyMessage);

  // Called by a VM to forward a Security Key request to gnubbyd extension.
  rpc ForwardSecurityKeyMessage(ForwardSecurityKeyMessageRequest)
      returns (ForwardSecurityKeyMessageResponse);

  // Called by a container to request the host to launch a SelectFile dialog.
  rpc SelectFile(SelectFileRequest) returns (SelectFileResponse);

  // Called by a container to get information about the disk it's on.
  rpc GetDiskInfo(GetDiskInfoRequest) returns (GetDiskInfoResponse);

  // Called by a container when it needs the disk to be expanded.
  rpc RequestSpace(RequestSpaceRequest) returns (RequestSpaceResponse);

  // Called by a container when it no longer needs as much space.
  rpc ReleaseSpace(ReleaseSpaceRequest) returns (ReleaseSpaceResponse);

  // If adding more rpc's, please update ContainerListenerFuzzerSingleAction as
  // well.
}