proto/idb.proto

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

syntax = "proto3";

package idb;

// The idb companion service definition.
service CompanionService {
  // Management
  rpc connect(ConnectRequest) returns (ConnectResponse) {}
  rpc debugserver(stream DebugServerRequest)
      returns (stream DebugServerResponse) {}
  rpc dap(stream DapRequest) returns (stream DapResponse) {}
  rpc describe(TargetDescriptionRequest) returns (TargetDescriptionResponse) {}
  rpc install(stream InstallRequest) returns (stream InstallResponse) {}
  rpc instruments_run(stream InstrumentsRunRequest)
      returns (stream InstrumentsRunResponse) {}
  rpc log(LogRequest) returns (stream LogResponse) {}
  rpc xctrace_record(stream XctraceRecordRequest)
      returns (stream XctraceRecordResponse) {}
  // Interaction
  rpc accessibility_info(AccessibilityInfoRequest)
      returns (AccessibilityInfoResponse) {}
  rpc focus(FocusRequest) returns (FocusResponse) {}
  rpc hid(stream HIDEvent) returns (HIDResponse) {}
  rpc open_url(OpenUrlRequest) returns (OpenUrlRequest) {}
  rpc set_location(SetLocationRequest) returns (SetLocationResponse) {}
  rpc send_notification(SendNotificationRequest)
      returns (SendNotificationResponse) {}
  rpc simulate_memory_warning(SimulateMemoryWarningRequest)
      returns (SimulateMemoryWarningResponse) {}
  // Settings
  rpc approve(ApproveRequest) returns (ApproveResponse) {}
  rpc clear_keychain(ClearKeychainRequest) returns (ClearKeychainResponse) {}
  rpc contacts_update(ContactsUpdateRequest) returns (ContactsUpdateResponse) {}
  rpc setting(SettingRequest) returns (SettingResponse) {} // Sets settings
  rpc get_setting(GetSettingRequest) returns (GetSettingResponse) {
  } // Gets current setting
  rpc list_settings(ListSettingRequest) returns (ListSettingResponse) {
  } // Lists available settings
  // App
  rpc launch(stream LaunchRequest) returns (stream LaunchResponse) {}
  rpc list_apps(ListAppsRequest) returns (ListAppsResponse) {}
  rpc terminate(TerminateRequest) returns (TerminateResponse) {}
  rpc uninstall(UninstallRequest) returns (UninstallResponse) {}
  // Video/Audio
  rpc add_media(stream AddMediaRequest) returns (AddMediaResponse) {}
  rpc record(stream RecordRequest) returns (stream RecordResponse) {}
  rpc screenshot(ScreenshotRequest) returns (ScreenshotResponse) {}
  rpc video_stream(stream VideoStreamRequest)
      returns (stream VideoStreamResponse) {}
  // Crash Operations
  rpc crash_delete(CrashLogQuery) returns (CrashLogResponse) {}
  rpc crash_list(CrashLogQuery) returns (CrashLogResponse) {}
  rpc crash_show(CrashShowRequest) returns (CrashShowResponse) {}
  // xctest operations
  rpc xctest_list_bundles(XctestListBundlesRequest)
      returns (XctestListBundlesResponse) {}
  rpc xctest_list_tests(XctestListTestsRequest)
      returns (XctestListTestsResponse) {}
  rpc xctest_run(XctestRunRequest) returns (stream XctestRunResponse) {}
  // File Operations
  rpc ls(LsRequest) returns (LsResponse) {}
  rpc mkdir(MkdirRequest) returns (MkdirResponse) {}
  rpc mv(MvRequest) returns (MvResponse) {}
  rpc rm(RmRequest) returns (RmResponse) {}
  rpc pull(PullRequest) returns (stream PullResponse) {}
  rpc push(stream PushRequest) returns (PushResponse) {}
  rpc tail(stream TailRequest) returns (stream TailResponse) {}
}

message Payload {
  oneof source {
    string file_path = 1;
    bytes data = 2;
    string url = 3;
    Compression compression = 4;
  }
  enum Compression {
    GZIP = 0;
    ZSTD = 1;
  }
}

message ProcessOutput {
  enum Interface {
    STDOUT = 0;
    STDERR = 1;
  }
  Interface interface = 1;
  bytes data = 2;
}

message CompanionInfo {
  string udid = 1;
  bool is_local = 4;
  bytes metadata = 6;
}

enum Setting {
  LOCALE = 0;
  ANY = 1; // any kind of app or global setting
}

message SettingRequest {
  message HardwareKeyboard {
    bool enabled = 1;
  }
  message StringSetting {
    Setting setting = 1;
    string value = 2;
    string name = 3; // iff setting == ANY
    string domain = 4; // assumed "Apple Global Domain" if empty
    /*
     * Currently supported value_types and corresponding values are:
     *  string <string_value>
     *  data <hex_digits>
     *  int[eger] <integer_value>
     *  float  <floating-point_value>
     *  bool[ean] (true | false | yes | no)
     *  date <date_rep>
     *  array <value1> <value2> ...
     *  array-add <value1> <value2> ...
     *  dict <key1> <value1> <key2> <value2> ...
     *  dict-add <key1> <value1> ...
     *
     * Check defaults set help for more details.
     */
    string value_type = 5;
  }
  oneof setting {
    HardwareKeyboard hardwareKeyboard = 1;
    StringSetting stringSetting = 2;
  }
}

message SettingResponse {}

message GetSettingRequest {
  Setting setting = 1;
  string name = 2; // iff setting == ANY
  string domain = 3; // assumed "Apple Global Domain" if empty
}

message GetSettingResponse {
  string value = 1;
}

message ListSettingRequest {
  Setting setting = 1;
}

message ListSettingResponse {
  repeated string values = 1;
}

message ListAppsRequest {
  bool suppress_process_state = 1;
}

message ListAppsResponse {
  repeated InstalledAppInfo apps = 1;
}

message InstalledAppInfo {
  string bundle_id = 1;
  string name = 2;
  repeated string architectures = 3;
  string install_type = 4;
  enum AppProcessState {
    UNKNOWN = 0;
    NOT_RUNNING = 1;
    RUNNING = 2;
  }
  AppProcessState process_state = 5;
  bool debuggable = 6;
  uint64 process_identifier = 7;
}

message InstallRequest {
  enum Destination {
    APP = 0;
    XCTEST = 1;
    DYLIB = 2;
    DSYM = 3;
    FRAMEWORK = 4;
  }
  message LinkDsymToBundle {
    enum BundleType {
      APP = 0;
      XCTEST = 1;
    }
    BundleType bundle_type = 1;
    string bundle_id = 2;
  }
  oneof value {
    Destination destination = 1;
    Payload payload = 2;
    string name_hint = 3;
    bool make_debuggable = 4;
    string bundle_id = 5; //(2022-03-02) REMOVE, For back compatibility only.
                          // Link dSYM to app bundle_id
    LinkDsymToBundle link_dsym_to_bundle = 6;
  }
}

message InstallResponse {
  string name = 1;
  string uuid = 2;
  double progress = 3;
}

message ScreenshotRequest {}

message ScreenshotResponse {
  bytes image_data = 1;
  string image_format = 2;
}

message FocusRequest {}

message FocusResponse {}

message Point {
  double x = 1;
  double y = 2;
}

message AccessibilityInfoRequest {
  enum Format {
    LEGACY = 0;
    NESTED = 1;
  }
  Point point = 2;
  Format format = 3;
}

message AccessibilityInfoResponse {
  string json = 1;
}

message ApproveRequest {
  enum Permission {
    PHOTOS = 0;
    CAMERA = 1;
    CONTACTS = 2;
    URL = 3;
    LOCATION = 4;
    NOTIFICATION = 5;
    MICROPHONE = 6;
  }
  string bundle_id = 1;
  repeated Permission permissions = 2;
  string scheme = 3;
}

message ApproveResponse {}

message ClearKeychainRequest {}

message ClearKeychainResponse {}

message SetLocationRequest {
  Location location = 1;
}

message Location {
  double latitude = 1;
  double longitude = 2;
}

message SetLocationResponse {}

message UninstallRequest {
  string bundle_id = 1;
}

message UninstallResponse {}

message TerminateRequest {
  string bundle_id = 1;
}

message TerminateResponse {}

message OpenUrlRequest {
  string url = 1;
}

message OpenUrlResponse {}

message ContactsUpdateRequest {
  Payload payload = 1;
}

message ContactsUpdateResponse {}

message TargetDescriptionRequest {
  bool fetch_diagnostics = 1;
}

message TargetDescriptionResponse {
  TargetDescription target_description = 1;
  CompanionInfo companion = 2;
}

message HIDEvent {
  enum HIDDirection {
    DOWN = 0;
    UP = 1;
  }

  message HIDTouch {
    Point point = 1;
  }

  enum HIDButtonType {
    APPLE_PAY = 0;
    HOME = 1;
    LOCK = 2;
    SIDE_BUTTON = 3;
    SIRI = 4;
  }

  message HIDButton {
    HIDButtonType button = 1;
  }

  message HIDKey {
    uint64 keycode = 1;
  }

  message HIDPressAction {
    oneof action {
      HIDTouch touch = 1;
      HIDButton button = 2;
      HIDKey key = 3;
    }
  }

  message HIDPress {
    HIDPressAction action = 1;
    HIDDirection direction = 2;
  }

  message HIDSwipe {
    Point start = 1;
    Point end = 2;
    double delta = 5;
    double duration = 6;
  }

  message HIDDelay {
    double duration = 1;
  }

  oneof event {
    HIDPress press = 1;
    HIDSwipe swipe = 2;
    HIDDelay delay = 3;
  }
}

message HIDResponse {}

message ConnectRequest {
  map<string, string> metadata = 1;
  string local_file_path = 4;
}

message ConnectResponse {
  CompanionInfo companion = 1;
}

message ScreenDimensions {
  uint64 width = 1;
  uint64 height = 2;
  double density = 3;
  uint64 width_points = 4;
  uint64 height_points = 5;
}

message TargetDescription {
  string udid = 1;
  string name = 2;
  ScreenDimensions screen_dimensions = 3;
  string state = 4;
  string target_type = 5;
  string os_version = 6;
  string architecture = 7;
  bytes extended = 9;
  bytes diagnostics = 10;
}

message LogRequest {
  enum Source {
    TARGET = 0;
    COMPANION = 1;
  }
  repeated string arguments = 1;
  Source source = 2;
}

message LogResponse {
  bytes output = 1;
}

message RecordRequest {
  message Start {
    string file_path = 1;
  }
  message Stop {}
  oneof control {
    Start start = 1;
    Stop stop = 2;
  }
}

message RecordResponse {
  oneof output {
    bytes log_output = 1;
    Payload payload = 2;
  }
}

message VideoStreamRequest {
  enum Format {
    H264 = 0;
    RBGA = 1;
    MJPEG = 2;
    MINICAP = 3;
    I420 = 4;
  }
  message Start {
    string file_path = 1;
    uint64 fps = 2;
    Format format = 3;
    double compression_quality = 4;
    double scale_factor = 5;
    double avg_bitrate = 6;
  }
  message Stop {}
  oneof control {
    Start start = 1;
    Stop stop = 2;
  }
}

message VideoStreamResponse {
  oneof output {
    bytes log_output = 1;
    Payload payload = 2;
  }
}

message LaunchRequest {
  message Start {
    string bundle_id = 1;
    map<string, string> env = 2;
    repeated string app_args = 3;
    bool foreground_if_running = 4;
    bool wait_for = 5;
    bool wait_for_debugger = 6;
  }
  message Stop {}
  oneof control {
    Start start = 1;
    Stop stop = 2;
  }
}

message LaunchResponse {
  ProcessOutput output = 3;
  DebuggerInfo debugger = 4;
}

message AddMediaRequest {
  Payload payload = 1;
}

message AddMediaResponse {}

message InstrumentsRunRequest {
  message InstrumentsTimings {
    double terminate_timeout = 1;
    double launch_retry_timeout = 2;
    double launch_error_timeout = 3;
    double operation_duration = 4;
  }
  message Start {
    string template_name = 2;
    string app_bundle_id = 3;
    map<string, string> environment = 4;
    repeated string arguments = 5;
    InstrumentsTimings timings = 6;
    repeated string tool_arguments = 7;
  }
  message Stop {
    repeated string post_process_arguments = 1;
  }
  oneof control {
    Start start = 1;
    Stop stop = 2;
  }
}

message InstrumentsRunResponse {
  enum State {
    UNKNOWN = 0;
    RUNNING_INSTRUMENTS = 1;
    POST_PROCESSING = 2;
  }
  oneof output {
    bytes log_output = 1;
    Payload payload = 2;
    State state = 3;
  }
}

message XctraceRecordRequest {
  message LauchProcess {
    string process_to_launch = 1;
    repeated string launch_args = 2;
    string target_stdin = 3;
    string target_stdout = 4;
    map<string, string> process_env = 5;
  }
  message Target {
    oneof target {
      bool all_processes = 1;
      string process_to_attach = 2;
      LauchProcess launch_process = 3;
    }
  }
  message Start {
    string template_name = 1;
    double time_limit = 2;
    string package = 3;
    Target target = 4;
  }
  message Stop {
    double timeout = 1;
    repeated string args = 2;
  }
  oneof control {
    Start start = 1;
    Stop stop = 2;
  }
}

message XctraceRecordResponse {
  enum State {
    UNKNOWN = 0;
    RUNNING = 1;
    PROCESSING = 2;
  }
  oneof output {
    bytes log = 1;
    Payload payload = 2;
    State state = 3;
  }
}

message DebugServerRequest {
  message Start {
    string bundle_id = 1;
  }
  message Status {}
  message Stop {}
  message Pipe {
    bytes data = 1;
  }
  oneof control {
    Start start = 1;
    Stop stop = 2;
    Status status = 3;
    Pipe pipe = 4;
  }
}

message DebugServerResponse {
  message Pipe {
    bytes data = 1;
  }
  message Status {
    repeated string lldb_bootstrap_commands = 1;
  }
  oneof control {
    Status status = 1;
    Pipe pipe = 2;
  }
}

// crashes

message CrashShowRequest {
  string name = 1;
}

message CrashLogResponse {
  repeated CrashLogInfo list = 1;
}

message CrashLogInfo {
  string name = 1;
  string bundle_id = 2;
  string process_name = 3;
  string parent_process_name = 4;
  uint64 process_identifier = 5;
  uint64 parent_process_identifier = 6;
  uint64 timestamp = 7;
}

message CrashShowResponse {
  CrashLogInfo info = 1;
  string contents = 2;
}

message CrashLogQuery {
  uint64 since = 1;
  uint64 before = 2;
  string bundle_id = 3;
  string name = 4;
}

// xctest

message XctestListBundlesRequest {}

message XctestListBundlesResponse {
  message Bundles {
    string name = 1;
    string bundle_id = 2;
    repeated string architectures = 3;
  }
  repeated Bundles bundles = 1;
}

message XctestListTestsRequest {
  string bundle_name = 1;
  string app_path = 2;
}

message XctestListTestsResponse {
  repeated string names = 1;
}

message XctestRunRequest {
  message Logic {}
  message Application {
    string app_bundle_id = 1;
  }
  message UI {
    string app_bundle_id = 1;
    string test_host_app_bundle_id = 2;
  }
  message Mode {
    oneof mode {
      Logic logic = 1;
      Application application = 2;
      UI ui = 3;
    }
  }
  message CodeCoverage {
    enum Format {
      EXPORTED = 0;
      RAW = 1;
    }
    bool collect = 1;
    Format format = 2;
  }
  Mode mode = 1;
  string test_bundle_id = 2;
  repeated string tests_to_run = 3;
  repeated string tests_to_skip = 4;
  repeated string arguments = 5;
  map<string, string> environment = 6;
  uint64 timeout = 7;
  bool report_activities = 8;
  bool collect_coverage = 9;
  bool report_attachments = 10;
  bool collect_logs = 11;
  bool wait_for_debugger = 12;
  CodeCoverage code_coverage = 13;
}

message XctestRunResponse {
  message TestRunInfo {
    message TestRunFailureInfo {
      string failure_message = 1;
      string file = 2;
      uint64 line = 3;
    }
    message TestAttachment {
      bytes payload = 1;
      double timestamp = 2;
      string name = 3;
      string uniform_type_identifier = 4;
    }
    message TestActivity {
      string title = 1;
      double duration = 2;
      string uuid = 3;
      string activity_type = 4;
      double start = 5;
      double finish = 6;
      string name = 7;
      repeated TestAttachment attachments = 8;
      repeated TestActivity sub_activities = 9;
    }
    enum Status {
      PASSED = 0;
      FAILED = 1;
      CRASHED = 2;
    }
    Status status = 1;
    string bundle_name = 2;
    string class_name = 3;
    string method_name = 4;
    double duration = 5;
    TestRunFailureInfo failure_info = 6;
    repeated string logs = 7;
    repeated TestActivity activityLogs = 8;
  }
  enum Status {
    RUNNING = 0;
    TERMINATED_NORMALLY = 1;
    TERMINATED_ABNORMALLY = 2;
  }
  Status status = 1;
  repeated TestRunInfo results = 2;
  repeated string log_output = 3;
  Payload result_bundle = 4;
  string coverage_json = 5;
  Payload log_directory = 6;
  DebuggerInfo debugger = 7;
  Payload code_coverage_data = 8;
}

// File

message FileContainer {
  enum Kind {
    NONE = 0;
    APPLICATION = 1;
    ROOT = 2;
    MEDIA = 3;
    CRASHES = 4;
    PROVISIONING_PROFILES = 5;
    MDM_PROFILES = 6;
    SPRINGBOARD_ICONS = 7;
    WALLPAPER = 8;
    DISK_IMAGES = 9;
    GROUP_CONTAINER = 10;
    APPLICATION_CONTAINER = 11;
    AUXILLARY = 12;
    XCTEST = 13;
    DYLIB = 14;
    DSYM = 15;
    FRAMEWORK = 16;
    SYMBOLS = 17;
  }
  Kind kind = 1;
  string bundle_id = 2;
}

message FileInfo {
  string path = 1;
}

message FileListing {
  FileInfo parent = 1;
  repeated FileInfo files = 2;
}

message LsResponse {
  repeated FileInfo files = 1;
  repeated FileListing listings = 2;
}

message LsRequest {
  string path = 2;
  FileContainer container = 3;
  repeated string paths = 4;
}

message MkdirRequest {
  string path = 2;
  FileContainer container = 3;
}

message MkdirResponse {}

message MvRequest {
  repeated string src_paths = 2;
  string dst_path = 3;
  FileContainer container = 4;
}

message MvResponse {}

message RmRequest {
  repeated string paths = 2;
  FileContainer container = 3;
}

message RmResponse {}

message PushRequest {
  message Inner {
    string dst_path = 2;
    FileContainer container = 3;
  }
  oneof value {
    Payload payload = 1;
    Inner inner = 2;
  }
}

message PushResponse {}

message PullRequest {
  string src_path = 2;
  string dst_path = 3;
  FileContainer container = 4;
}

message PullResponse {
  Payload payload = 1;
}

message TailRequest {
  message Start {
    FileContainer container = 1;
    string path = 2;
  }
  message Stop {}
  oneof control {
    Start start = 1;
    Stop stop = 2;
  }
}

message TailResponse {
  bytes data = 1;
}

message DebuggerInfo {
  uint64 pid = 1;
  string host = 2;
  uint64 port = 3;
}

message SendNotificationRequest {
  string bundle_id = 1;
  string json_payload = 2;
}

message SendNotificationResponse {}

message DapRequest {
  message Start {
    string debugger_pkg_id = 1;
  }
  message Pipe {
    bytes data = 1;
  }
  message Stop {}
  oneof control {
    Start start = 1;
    Pipe pipe = 2;
    Stop stop = 3;
  }
}

message DapResponse {
  message Event {
    string desc = 1;
  }
  message Pipe {
    bytes data = 1;
  }

  oneof event {
    Event started = 1;
    Pipe stdout = 2;
    Event stopped = 3;
  }
}

message SimulateMemoryWarningRequest {}

message SimulateMemoryWarningResponse {}