transport/proto/app_inspection.proto

/*
 * Copyright (C) 2019 The Android Open Source Project
 *
 * Licensed 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.
 */
syntax = "proto3";

package app_inspection;
option java_package = "com.android.tools.app.inspection";
option java_outer_classname = "AppInspection";

// A command originates from the host and should *always* get a response.
// (If no response comes, it means the device likely crashed or ANR'd)
// A command may additionally generate zero or more events.
message AppInspectionCommand {
  // Uniquely identifies the inspector that sent this event.
  // Used by studio to route to appropriate event handler.
  // This id is defined by inspector's owner. (e.g “androidx.workmanager")
  string inspector_id = 1;
  // DO NOT USE.
  // A unique id associated with this command. To be set by inspection service
  // when sending command to inspector.
  uint32 command_id = 2;
  oneof union {
    CreateInspectorCommand create_inspector_command = 3;
    DisposeInspectorCommand dispose_inspector_command = 4;
    RawCommand raw_inspector_command = 5;
    CancellationCommand cancellation_command = 6;
    GetLibraryCompatibilityInfoCommand get_library_compatibility_info_command = 7;
  }
}

// A command to create an inspector and register it as a listener
// for incoming commands.
message CreateInspectorCommand {
  // On device path to the jar that has a dexed code of the given inspector.
  string dex_path = 1;
  // Metadata about the launch of an inspector.
  LaunchMetadata launch_metadata = 2;
}

// Represents the maven coordinate of an artifact.
message ArtifactCoordinate {
  string group_id = 1;
  string artifact_id = 2;
  // This adheres to the gradle version format.
  string version = 3;
}

// Metadata about the launch of an inspector.
message LaunchMetadata {
  // Name of the entity that sent this launch command. Ex: Name of the Android
  // Studio project.
  string launched_by_name = 1;
  // If true, force launching the inspector, even if one is already running.
  bool force = 2;
  // Represents the coordinates of minimum supported library.
  ArtifactCoordinate min_library = 3;
}

// A command to dispose the inspector.
// Service layer won't keep reference to an inspector anymore.
// All events from and commands to it will be ignored
// This command will be propagated to inspector instance as well, so it should react accordingly.
// For example, if an inspector was listening for db changes, it should unregister
// itself.
message DisposeInspectorCommand {}

// A payload is a large binary blob, which we break up into chunks to improve streaming behavior.
// Chunks must be associated with a payload ID and sent serially, and they will be reconstructed on
// the client side.
// Note: This payload ID will be unique across all inspectors attached to a process, so there's
// no need to additionally filter by inspector ID.
// Note: This chunk will be wrapped by a parent |Event| (see common.proto) and will use its
// |group_id| field to store the payload ID and the |is_ended| field to indicate it is the final
// message in the series.
message AppInspectionPayload {
  // The subset of bytes in this chunk
  bytes chunk = 1;
}

// Opaque command to an inspector.
message RawCommand {
  bytes content = 1;
}

// a command to cancel long-running operation
message CancellationCommand {
    uint32 cancelled_command_id = 1;
}

message GetLibraryCompatibilityInfoCommand {
  // A list of target libraries to verify version information.
  // These represent the minimum version of the libraries their
  // inspectors are compatible with.
  repeated ArtifactCoordinate target_libraries = 1;
}

// A response is sent from the device to answer a command.
message AppInspectionResponse {
  uint32 command_id = 1;
  // SUCCESS if originating command succeeded.
  enum Status {
    SUCCESS = 0;
    ERROR = 1;
  }
  Status status = 2;
  // Additional info if command failed.
  string error_message = 3;
  oneof union {
    CreateInspectorResponse create_inspector_response = 4;
    DisposeInspectorResponse dispose_inspector_response = 5;
    RawResponse raw_response = 6;
    GetLibraryCompatibilityInfoResponse get_library_compatibility_response = 7;
  }
}

// An event is initiated from device, informing the UI it should probably update.
message AppInspectionEvent {
  // Uniquely identifies the inspector that sent this event.
  // Used by studio to route to appropriate event handler.
  string inspector_id = 1;
  oneof union {
    RawEvent raw_event = 2;
    DisposedEvent disposed_event = 3;
  }
}

// Response to CreateInspectorCommand.
message CreateInspectorResponse {
  // This specifies the cause of the error when response status is |ERROR|.
  enum Status {
    SUCCESS = 0;
    // Generic error encountered in AppInspectionService. Encapsulates failures
    // that do not necessitate a separate type in this enum.
    GENERIC_SERVICE_ERROR = 1;
    // The targeted library does not meet the version requirements of this
    // inspector.
    VERSION_INCOMPATIBLE = 2;
    // The targeted library is not found in the app.
    LIBRARY_MISSING = 3;
    // The target app is proguarded, library inspectors can't safely run.
    APP_PROGUARDED = 4;
  }
  Status status = 1;
}

// Response to DisposeInspectorCommand.
message DisposeInspectorResponse {
}

message LibraryCompatibilityInfo {
  enum Status {
    COMPATIBLE = 0;
    INCOMPATIBLE = 1;
    LIBRARY_MISSING = 2;
    APP_PROGUARDED = 3;
    SERVICE_ERROR = 4;
  }
  Status status = 1;
  ArtifactCoordinate target_library = 2;
  string version = 3;
  string error_message = 4;
}

message GetLibraryCompatibilityInfoResponse {
  repeated LibraryCompatibilityInfo responses = 1;
}

// Opaque response from an inspector.
message RawResponse {
  oneof data {
    // An opaque serialized response, inspectors themselves define serialization format
    bytes content = 1;
    // If specified, bytes will be fetched from a payload cache by ID
    int64 payload_id = 2;
  }
}

// Opaque event from an inspector.
message RawEvent {
  oneof data {
    // An opaque serialized event, inspectors themselves define serialization format
    bytes content = 1;
    // If specified, bytes will be fetched from a payload cache by ID
    int64 payload_id = 2;
  }
}

// Sent when an inspector is disposed due to any reason
message DisposedEvent {
  // option message about the cause of the disposal (ie: cause of a crash)
  string error_message = 1;
}