DOCSEARCHbyAlgolia
Submit Docs

ios-webkit-debug-proxy

repository·master·Indexed 27 days ago

https://github.com/google/ios-webkit-debug-proxy

A tool that proxies requests from the usbmuxd daemon over a WebSocket connection, enabling developers to use web debugging tools like Chrome DevTools or Safari Web Inspector to debug MobileSafari and UIWebViews on real or simulated iOS devices.

Tokens
2K
Snippets
6
Records
11
Agent score
42%

What's inside ios-webkit-debug-proxy

  1. Understand the ios_webkit_debug_proxy architecture

    master

    The proxy operates as a single-threaded system using non-blocking I/O via a socket_manager that uses select. It translates between the iOS WebInspector protocol and the WebKit Remote Debugging Protocol.

    Key components include:

    • device_listener: Monitors iOS device connection/disconnection events.
    • (port, webinspector) pairs: Each connected device is assigned a unique port mapped to its inspector (e.g., port 9222 for device X, 9223 for device Y).
    • WebSocket clients: Handles active connections to debuggable pages (e.g., websocketA connected to :9222/devtools/page/7).
    • socket_manager: Orchestrates all socket I/O and forwards data to component-specific on_recv handlers.

  3. Start the iOS Simulator for debugging

    master

    The iOS Simulator must be started before the proxy. You can start it via Xcode or the command line. Note that Xcode paths change frequently; verify the paths below for your specific version.

    Example command to start MobileSafari in the simulator:

    SDK_DIR="/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs"
SIM_APP="/Applications/Xcode.app/Contents/Developer/Applications/Simulator.app/Contents/MacOS/Simulator"
$SIM_APP -SimulateApplication $SDK_DIR/iPhoneSimulator8.4.sdk/Applications/MobileSafari.app/MobileSafari
    # Xcode changes these paths frequently, so doublecheck them
SDK_DIR="/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs"
SIM_APP="/Applications/Xcode.app/Contents/Developer/Applications/Simulator.app/Contents/MacOS/Simulator"
$SIM_APP -SimulateApplication $SDK_DIR/iPhoneSimulator8.4.sdk/Applications/MobileSafari.app/MobileSafari

  4. Implement a custom device_listener client

    master

    The device_listener uses an object-oriented pattern via structs and function pointers. To create a client, you must initialize a dl_t object, assign the required callback functions, and call start().

    Required callbacks to implement:

    • send: Sends data via the listener.
    • on_attach: Triggered when a device is connected (receives device_id).
    • on_detach: Triggered when a device is removed (receives device_id).

    You must also implement a loop to forward socket input to the listener's on_recv handler to ensure messages are buffered and processed correctly.

    int fd = dl_connect();
dl_t dl = dl_new(); // sets the "start" and "on_recv" functions
dl->state = fd;     // for use by "my_send"
dl->send = my_send; // --> send((int)dl->state, buf, length);
dl->on_attach = my_on_attach; // --> printf("%s", device_id);
dl->on_detach = my_on_detach; // --> ditto

dl->start();

// Client loop to forward socket input to the listener's handler
char buf[1024];
while (1) {
   int len = recv(fd, buf, 1024);
   if (dl->on_recv(dl, buf, len)) break;
}

  5. Install ios-webkit-debug-proxy

    master

    Installation methods vary by operating system:

    MacOS

    Use Homebrew:

    brew install ios-webkit-debug-proxy

    Windows

    Use Scoop (requires the latest version of iTunes installed):

    scoop bucket add extras
scoop install ios-webkit-debug-proxy

    Linux (Debian/Ubuntu)

    Install dependencies via apt:

    sudo apt-get install autoconf automake libusb-dev libusb-1.0-0-dev libplist-dev libtool libssl-dev

    Linux (Fedora)

    Install dependencies via dnf:

    sudo dnf install autoconf automake libusb1-devel libusb-compat-0.1-devel libtool openssl-devel

    Or use existing packages:

    sudo dnf install libplist-devel usbmuxd libimobiledevice-devel libimobiledevice-utils libimobiledevice-glue-devel

    Build from Source (Linux)

    git clone https://github.com/google/ios-webkit-debug-proxy.git
cd ios-webkit-debug-proxy
./autogen.sh
make
sudo make install
    brew install ios-webkit-debug-proxy

  7. Configure the DevTools frontend URL

    master

    You can specify a custom DevTools UI using the -f flag. The value must end in .html. Note that https URLs are not supported; use http or bypass security via the browser's URL bar shield icon.

    Examples:

    ios_webkit_debug_proxy -f chrome-devtools://devtools/bundled/inspector.html
ios_webkit_debug_proxy -f ~/chromium/src/third_party/WebKit/Source/devtools/front_end/inspector.html
ios_webkit_debug_proxy -f http://foo.com:1234/bar/inspector.html

    If using chrome-devtools://devtools/bundled/inspector.html, you cannot click links in localhost:9222. Instead, copy/paste the WebSocket URL directly into the address bar: chrome-devtools://devtools/bundled/inspector.html?ws=localhost:9222/devtools/page/1

    ios_webkit_debug_proxy -f chrome-devtools://devtools/bundled/inspector.html

  8. Configure port assignments with -c

    master

    By default, the proxy assigns ports as follows:

    • :9221: Device list
    • :9222: First attached device
    • :9223: Second attached device
    • ... up to :9322

    Use the -c flag to override these rules. The default configuration is equivalent to ios_webkit_debug_proxy -c null:9221,:9222-9322, where null represents the device list.

    Example: Restrict the proxy to a single specific device and a specific port:

    ios_webkit_debug_proxy -c 4ea8dd11e8c4fbc1a2deadbeefa0fd3bbbb268c7:9227
    ios_webkit_debug_proxy -c 4ea8dd11e8c4fbc1a2deadbeefa0fd3bbbb268c7:9227

  9. Troubleshoot common connection issues

    master

    Lockdown/Connection Errors

    • 'Could not connect to lockdownd': Check the iOS device for a 'Trust This Computer?' prompt and select Trust.
    • 'Broken pipe' or error codes: Ensure you are using the latest version of ios-webkit-debug-proxy.

    Simulator Issues

    • Cannot see Simulator:
      • Ensure the simulator was started before the proxy.
      • Verify Web Inspector is enabled in Safari settings.
      • If using Linux/macOS, ensure ::1 localhost is present in your /etc/hosts file (the simulator may listen on an IPv6 interface).

    Library/Build Errors

    • 'undefined reference to symbol log10': Run ./configure LIBS="-lm" before running make.
    • 'error while loading shared libraries: libimobiledevice.so.6': Run sudo ldconfig.
    • 'idevice_id not found': Install the libimobiledevice-utils package.

  10. Use JSON APIs for programmatic clients

    master

    The proxy provides JSON-formatted APIs for automated tools:

    • http://localhost:9221/json: Lists all connected devices.
    • http://localhost:9222/json: Lists tabs for the device assigned to port :9222.
    • ws://localhost:9222/devtools/page/1: WebSocket endpoint to inspect a specific tab.

  11. Run ios_webkit_debug_proxy

    master

    Start the proxy using the following command:

    ios_webkit_debug_proxy

    CLI Flags

    • --debug: Enables verbose output.
    • --frontend <URL>: Specifies a frontend URL (must end in .html).
    • --help: Shows available options.
    • --no-frontend: Disables the frontend proxy.
    • -c <config>: Sets custom port assignment rules.

    Press Ctrl-C to quit. The proxy can also be run as a background process.

    ios_webkit_debug_proxy