Update native-messaging to use python3, clarify instructions

Fixes #560

native-messaging/README.md

@@ -4,36 +4,60 @@ The WebExtension, which can be found under "add-on", connects to the native appl
 
 The native application, which can be found under "app", listens for messages from the WebExtension. When it receives a message, the native application sends a response message whose payload is just "pong". The native application is written in Python.
 
-## Setup ##
+## Setup
 
 To get this working, there's a little setup to do.
 
-### Mac OS/Linux setup ###
+### Linux/macOS setup
 
-1. Check that the [file permissions](https://en.wikipedia.org/wiki/File_system_permissions) for "ping_pong.py" include the `execute` permission.
+1. Make sure that you have Python 3 installed, and that your system's PATH environment variable includes the path to Python by executing the following command:
-2. Edit the "path" property of "ping_pong.json" to point to the location of "ping_pong.py" on your computer.
-3. copy "ping_pong.json" to the correct location on your computer. See [App manifest location ](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_manifests#Manifest_location) to find the correct location for your OS.
 
-### Windows setup ###
+    ```bash
+    > which python3
+    /usr/local/bin/python3
+    ```
 
-1. Check you have Python installed, and that your system's PATH environment variable includes the path to Python.  See [Using Python on Windows](https://docs.python.org/2/using/windows.html). You'll need to restart the web browser after making this change, or the browser won't pick up the new environment variable.
+    If you don't see the path of the application as above, you most likely need to install Python 3 on your computer. See [Using Python on Unix platforms](https://docs.python.org/3/using/unix.html) or [Using Python on a Mac](https://docs.python.org/3/using/windows.html). Restart the web browser after making this change in order for Firefox to pick up the new PATH environment variable.
-2. Edit the "path" property of "ping_pong.json" to point to the location of "ping_pong_win.bat" on your computer. Note that you'll need to escape the Windows directory separator, like this: `"path": "C:\\Users\\MDN\\native-messaging\\app\\ping_pong_win.bat"`.
-3. Edit "ping_pong_win.bat" to refer to the location of "ping_pong.py" on your computer.
-4. Add a registry key containing the path to "ping_pong.json" on your computer. See [App manifest location ](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_manifests#Manifest_location) to find details of the registry key to add.
 
-To assist in troubleshooting on Windows, there is a script called `check_config_win.py`. Running this from the command line should give you an idea of any problems.
+2. Make sure that the [file permissions](https://en.wikipedia.org/wiki/File_system_permissions) for `app/ping_pong.py` include the `execute` permission. See [this article by RedHat](https://www.redhat.com/sysadmin/linux-file-permissions-explained) for more information.
 
-## Testing the example ##
+3. Update the `"path"` field in `app/ping_pong.json` to be the full path to your `app/ping_pong.py` file.
 
-First, install the add-on. Visit `about:debugging#/runtime/this-firefox` or, from `about:debugging` click "This Firefox" (or "This Nightly" in the Nightly version of Firefox), click "Load Temporary Add-on", and open the add-on's "manifest.json".
+    For example, if you cloned this repository into `/Users/MDN/webextensions-examples/`, you would update the file like this:
 
-Now, open the extension's console using the "Inspect" button - this is where you'll see communication between the browser and native app. 
+    ```json
+    "path": "/Users/MDN/webextensions-examples/native-messaging/app/ping_pong.py"
+    ```
+
+4. Copy `app/ping_pong.json` to the correct location on your computer. There are too many options to list here; see the [Linux](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#linux) and [macOS](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#macos) secitons of [App manifest location ](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_manifests#Manifest_location) to find the correct location for your OS and personal preference.
+
+### Windows setup
+
+1. Make sure that you have Python 3 installed and that your system's PATH environment variable includes the path to Python.  See [Using Python on Windows](https://docs.python.org/3/using/windows.html). You'll need to restart the web browser after making this change, or the browser won't pick up the new environment variable.
+
+2. Update the `"path"` field in `app\ping_pong.json` to use the full path of `app\ping_pong_win.bat` on your computer. Be aware that you'll need to escape the Windows directory separator (`\`).
+
+    For example, if you cloned this repository into `C:\Users\MDN\webextensions-examples\`, you would update the JSON file like this:
+
+    ```json
+    "path": "C:\\Users\\MDN\\webextensions-examples\\native-messaging\\app\\ping_pong_win.bat"
+    ```
+
+3. Update `app\ping_pong_win.bat` to use the full path of `app\ping_pong.py` on your computer.
+
+4. Add a registry key containing the full path of `app\ping_pong.json` on your computer. See [App manifest location](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_manifests#Manifest_location) to find details of the registry key to add.
+
+To assist in troubleshooting on Windows, there is a script next to this README file named `check_config_win.py`. Running this in a command shell should help you discover of any problems.
+
+## Testing the example
+
+First, install the add-on. Visit `about:debugging#/runtime/this-firefox` or, from `about:debugging` click "This Firefox" (or "This Nightly" in the Nightly version of Firefox), click "Load Temporary Add-on", and open the add-on's `manifest.json`.
+
+Now, open the extension's console using the "Inspect" button - this is where you'll see communication between the browser and native app.
 
 You should see a new browser action icon in the toolbar. Click it. You should see output like this in the console:
 
     Sending: ping
     Received: pong3
 
-If you're running Python 2.x, you'll see "pong2" as the response instead. 
-
 If you don't see this output, see the [Troubleshooting guide](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging#Troubleshooting) for ideas.

native-messaging/add-on/background.js

@@ -4,14 +4,28 @@ On startup, connect to the "ping_pong" app.
 let port = browser.runtime.connectNative("ping_pong");
 
 /*
-Listen for messages from the app.
+Listen for messages from the app and log them to the console.
 */
 port.onMessage.addListener((response) => {
   console.log("Received: " + response);
 });
 
 /*
-On a click on the browser action, send the app a message.
+Listen for the native messaging port closing.
+*/
+port.onDisconnect.addListener((port) => {
+  if (port.error) {
+    console.log(`Disconnected due to an error: ${port.error.message}`);
+  } else {
+    // The port closed for an unspecified reason. If this occurred right after
+    // calling `browser.runtime.connectNative()` there may have been a problem
+    // starting the the native messaging client in the first place.
+    console.log(`Disconnected`, port);
+  }
+});
+
+/*
+When the extension's action icon is clicked, send the app a message.
 */
 browser.browserAction.onClicked.addListener(() => {
   console.log("Sending:  ping");

native-messaging/add-on/manifest.json

@@ -22,7 +22,7 @@
   "browser_action": {
     "default_icon": "icons/message.svg"
   },
-  
+
   "permissions": ["nativeMessaging"]
 
 }

native-messaging/app/ping_pong.json

@@ -1,7 +1,7 @@
 {
   "name": "ping_pong",
   "description": "Example host for native messaging",
-  "path": "/path/to/native-messaging/app/ping_pong.py",
+  "path": "/Users/svincent/dev/webextensions-examples/native-messaging/app/ping_pong.py",
   "type": "stdio",
   "allowed_extensions": [ "ping_pong@example.org" ]
 }

native-messaging/app/ping_pong.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 import sys
 import json
@@ -19,7 +19,7 @@ try:
     # given its content.
     def encodeMessage(messageContent):
         # https://docs.python.org/3/library/json.html#basic-usage
-        # To get the most compact JSON representation, you should specify 
+        # To get the most compact JSON representation, you should specify
         # (',', ':') to eliminate whitespace.
         # We want the most compact representation because the browser rejects
         # messages that exceed 1 MB.
@@ -37,6 +37,7 @@ try:
         receivedMessage = getMessage()
         if receivedMessage == "ping":
             sendMessage(encodeMessage("pong3"))
+
 except AttributeError:
     # Python 2.x version (if sys.stdin.buffer is not defined)
     # Read a message from stdin and decode it.
@@ -52,7 +53,7 @@ except AttributeError:
     # given its content.
     def encodeMessage(messageContent):
         # https://docs.python.org/3/library/json.html#basic-usage
-        # To get the most compact JSON representation, you should specify 
+        # To get the most compact JSON representation, you should specify
         # (',', ':') to eliminate whitespace.
         # We want the most compact representation because the browser rejects
         # messages that exceed 1 MB.

native-messaging/app/ping_pong_win.bat

@@ -1,3 +1,3 @@
 @echo off
 
-call python C:\path\to\ping_pong.py
+call python3 C:\path\to\ping_pong.py