summaryrefslogtreecommitdiffstats
path: root/devtools/shared/discovery
diff options
context:
space:
mode:
Diffstat (limited to 'devtools/shared/discovery')
-rw-r--r--devtools/shared/discovery/discovery.js427
-rw-r--r--devtools/shared/discovery/moz.build11
-rw-r--r--devtools/shared/discovery/tests/xpcshell/.eslintrc.js6
-rw-r--r--devtools/shared/discovery/tests/xpcshell/test_discovery.js158
-rw-r--r--devtools/shared/discovery/tests/xpcshell/xpcshell.ini6
5 files changed, 608 insertions, 0 deletions
diff --git a/devtools/shared/discovery/discovery.js b/devtools/shared/discovery/discovery.js
new file mode 100644
index 0000000000..f7ec5a6860
--- /dev/null
+++ b/devtools/shared/discovery/discovery.js
@@ -0,0 +1,427 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+
+/**
+ * This implements a UDP mulitcast device discovery protocol that:
+ * * Is optimized for mobile devices
+ * * Doesn't require any special schema for service info
+ *
+ * To ensure it works well on mobile devices, there is no heartbeat or other
+ * recurring transmission.
+ *
+ * Devices are typically in one of two groups: scanning for services or
+ * providing services (though they may be in both groups as well).
+ *
+ * Scanning devices listen on UPDATE_PORT for UDP multicast traffic. When the
+ * scanning device wants to force an update of the services available, it sends
+ * a status packet to SCAN_PORT.
+ *
+ * Service provider devices listen on SCAN_PORT for any packets from scanning
+ * devices. If one is recevied, the provider device sends a status packet
+ * (listing the services it offers) to UPDATE_PORT.
+ *
+ * Scanning devices purge any previously known devices after REPLY_TIMEOUT ms
+ * from that start of a scan if no reply is received during the most recent
+ * scan.
+ *
+ * When a service is registered, is supplies a regular object with any details
+ * about itself (a port number, for example) in a service-defined format, which
+ * is then available to scanning devices.
+ */
+
+const EventEmitter = require("resource://devtools/shared/event-emitter.js");
+
+const UDPSocket = Components.Constructor(
+ "@mozilla.org/network/udp-socket;1",
+ "nsIUDPSocket",
+ "init"
+);
+
+const SCAN_PORT = 50624;
+const UPDATE_PORT = 50625;
+const ADDRESS = "224.0.0.115";
+const REPLY_TIMEOUT = 5000;
+
+var logging = Services.prefs.getBoolPref("devtools.discovery.log");
+function log(msg) {
+ if (logging) {
+ console.log("DISCOVERY: " + msg);
+ }
+}
+
+/**
+ * Each Transport instance owns a single UDPSocket.
+ * @param port integer
+ * The port to listen on for incoming UDP multicast packets.
+ */
+function Transport(port) {
+ EventEmitter.decorate(this);
+ try {
+ this.socket = new UDPSocket(
+ port,
+ false,
+ Services.scriptSecurityManager.getSystemPrincipal()
+ );
+ this.socket.joinMulticast(ADDRESS);
+ this.socket.asyncListen(this);
+ } catch (e) {
+ log("Failed to start new socket: " + e);
+ }
+}
+
+Transport.prototype = {
+ /**
+ * Send a object to some UDP port.
+ * @param object object
+ * Object which is the message to send
+ * @param port integer
+ * UDP port to send the message to
+ */
+ send(object, port) {
+ if (logging) {
+ log("Send to " + port + ":\n" + JSON.stringify(object, null, 2));
+ }
+ const message = JSON.stringify(object);
+ const rawMessage = Uint8Array.from(message, x => x.charCodeAt(0));
+ try {
+ this.socket.send(ADDRESS, port, rawMessage, rawMessage.length);
+ } catch (e) {
+ log("Failed to send message: " + e);
+ }
+ },
+
+ destroy() {
+ this.socket.close();
+ },
+
+ // nsIUDPSocketListener
+
+ onPacketReceived(socket, message) {
+ const messageData = message.data;
+ const object = JSON.parse(messageData);
+ object.from = message.fromAddr.address;
+ const port = message.fromAddr.port;
+ if (port == this.socket.port) {
+ log("Ignoring looped message");
+ return;
+ }
+ if (logging) {
+ log(
+ "Recv on " + this.socket.port + ":\n" + JSON.stringify(object, null, 2)
+ );
+ }
+ this.emit("message", object);
+ },
+
+ onStopListening() {},
+};
+
+/**
+ * Manages the local device's name. The name can be generated in serveral
+ * platform-specific ways (see |_generate|). The aim is for each device on the
+ * same local network to have a unique name.
+ */
+function LocalDevice() {
+ this._name = LocalDevice.UNKNOWN;
+ // Trigger |_get| to load name eagerly
+ this._get();
+}
+
+LocalDevice.UNKNOWN = "unknown";
+
+LocalDevice.prototype = {
+ _get() {
+ // Without Settings API, just generate a name and stop, since the value
+ // can't be persisted.
+ this._generate();
+ },
+
+ /**
+ * Generate a new device name from various platform-specific properties.
+ * Triggers the |name| setter to persist if needed.
+ */
+ _generate() {
+ if (Services.appinfo.widgetToolkit == "android") {
+ // For Firefox for Android, use the device's model name.
+ // TODO: Bug 1180997: Find the right way to expose an editable name
+ this.name = Services.sysinfo.get("device");
+ } else {
+ this.name = Services.dns.myHostName;
+ }
+ },
+
+ get name() {
+ return this._name;
+ },
+
+ set name(name) {
+ this._name = name;
+ log("Device: " + this._name);
+ },
+};
+
+function Discovery() {
+ EventEmitter.decorate(this);
+
+ this.localServices = {};
+ this.remoteServices = {};
+ this.device = new LocalDevice();
+ this.replyTimeout = REPLY_TIMEOUT;
+
+ // Defaulted to Transport, but can be altered by tests
+ this._factories = { Transport };
+
+ this._transports = {
+ scan: null,
+ update: null,
+ };
+ this._expectingReplies = {
+ from: new Set(),
+ };
+
+ this._onRemoteScan = this._onRemoteScan.bind(this);
+ this._onRemoteUpdate = this._onRemoteUpdate.bind(this);
+ this._purgeMissingDevices = this._purgeMissingDevices.bind(this);
+}
+
+Discovery.prototype = {
+ /**
+ * Add a new service offered by this device.
+ * @param service string
+ * Name of the service
+ * @param info object
+ * Arbitrary data about the service to announce to scanning devices
+ */
+ addService(service, info) {
+ log("ADDING LOCAL SERVICE");
+ if (Object.keys(this.localServices).length === 0) {
+ this._startListeningForScan();
+ }
+ this.localServices[service] = info;
+ },
+
+ /**
+ * Remove a service offered by this device.
+ * @param service string
+ * Name of the service
+ */
+ removeService(service) {
+ delete this.localServices[service];
+ if (Object.keys(this.localServices).length === 0) {
+ this._stopListeningForScan();
+ }
+ },
+
+ /**
+ * Scan for service updates from other devices.
+ */
+ scan() {
+ this._startListeningForUpdate();
+ this._waitForReplies();
+ // TODO Bug 1027457: Use timer to debounce
+ this._sendStatusTo(SCAN_PORT);
+ },
+
+ /**
+ * Get a list of all remote devices currently offering some service.:w
+ */
+ getRemoteDevices() {
+ const devices = new Set();
+ for (const service in this.remoteServices) {
+ for (const device in this.remoteServices[service]) {
+ devices.add(device);
+ }
+ }
+ return [...devices];
+ },
+
+ /**
+ * Get a list of all remote devices currently offering a particular service.
+ */
+ getRemoteDevicesWithService(service) {
+ const devicesWithService = this.remoteServices[service] || {};
+ return Object.keys(devicesWithService);
+ },
+
+ /**
+ * Get service info (any details registered by the remote device) for a given
+ * service on a device.
+ */
+ getRemoteService(service, device) {
+ const devicesWithService = this.remoteServices[service] || {};
+ return devicesWithService[device];
+ },
+
+ _waitForReplies() {
+ clearTimeout(this._expectingReplies.timer);
+ this._expectingReplies.from = new Set(this.getRemoteDevices());
+ this._expectingReplies.timer = setTimeout(
+ this._purgeMissingDevices,
+ this.replyTimeout
+ );
+ },
+
+ get Transport() {
+ return this._factories.Transport;
+ },
+
+ _startListeningForScan() {
+ if (this._transports.scan) {
+ // Already listening
+ return;
+ }
+ log("LISTEN FOR SCAN");
+ this._transports.scan = new this.Transport(SCAN_PORT);
+ this._transports.scan.on("message", this._onRemoteScan);
+ },
+
+ _stopListeningForScan() {
+ if (!this._transports.scan) {
+ // Not listening
+ return;
+ }
+ this._transports.scan.off("message", this._onRemoteScan);
+ this._transports.scan.destroy();
+ this._transports.scan = null;
+ },
+
+ _startListeningForUpdate() {
+ if (this._transports.update) {
+ // Already listening
+ return;
+ }
+ log("LISTEN FOR UPDATE");
+ this._transports.update = new this.Transport(UPDATE_PORT);
+ this._transports.update.on("message", this._onRemoteUpdate);
+ },
+
+ _stopListeningForUpdate() {
+ if (!this._transports.update) {
+ // Not listening
+ return;
+ }
+ this._transports.update.off("message", this._onRemoteUpdate);
+ this._transports.update.destroy();
+ this._transports.update = null;
+ },
+
+ _restartListening() {
+ if (this._transports.scan) {
+ this._stopListeningForScan();
+ this._startListeningForScan();
+ }
+ if (this._transports.update) {
+ this._stopListeningForUpdate();
+ this._startListeningForUpdate();
+ }
+ },
+
+ /**
+ * When sending message, we can use either transport, so just pick the first
+ * one currently alive.
+ */
+ get _outgoingTransport() {
+ if (this._transports.scan) {
+ return this._transports.scan;
+ }
+ if (this._transports.update) {
+ return this._transports.update;
+ }
+ return null;
+ },
+
+ _sendStatusTo(port) {
+ const status = {
+ device: this.device.name,
+ services: this.localServices,
+ };
+ this._outgoingTransport.send(status, port);
+ },
+
+ _onRemoteScan() {
+ // Send my own status in response
+ log("GOT SCAN REQUEST");
+ this._sendStatusTo(UPDATE_PORT);
+ },
+
+ _onRemoteUpdate(update) {
+ log("GOT REMOTE UPDATE");
+
+ const remoteDevice = update.device;
+ const remoteHost = update.from;
+
+ // Record the reply as received so it won't be purged as missing
+ this._expectingReplies.from.delete(remoteDevice);
+
+ // First, loop over the known services
+ for (const service in this.remoteServices) {
+ const devicesWithService = this.remoteServices[service];
+ const hadServiceForDevice = !!devicesWithService[remoteDevice];
+ const haveServiceForDevice = service in update.services;
+ // If the remote device used to have service, but doesn't any longer, then
+ // it was deleted, so we remove it here.
+ if (hadServiceForDevice && !haveServiceForDevice) {
+ delete devicesWithService[remoteDevice];
+ log("REMOVED " + service + ", DEVICE " + remoteDevice);
+ this.emit(service + "-device-removed", remoteDevice);
+ }
+ }
+
+ // Second, loop over the services in the received update
+ for (const service in update.services) {
+ // Detect if this is a new device for this service
+ const newDevice =
+ !this.remoteServices[service] ||
+ !this.remoteServices[service][remoteDevice];
+
+ // Look up the service info we may have received previously from the same
+ // remote device
+ const devicesWithService = this.remoteServices[service] || {};
+ const oldDeviceInfo = devicesWithService[remoteDevice];
+
+ // Store the service info from the remote device
+ const newDeviceInfo = Cu.cloneInto(update.services[service], {});
+ newDeviceInfo.host = remoteHost;
+ devicesWithService[remoteDevice] = newDeviceInfo;
+ this.remoteServices[service] = devicesWithService;
+
+ // If this is a new service for the remote device, announce the addition
+ if (newDevice) {
+ log("ADDED " + service + ", DEVICE " + remoteDevice);
+ this.emit(service + "-device-added", remoteDevice, newDeviceInfo);
+ }
+
+ // If we've seen this service from the remote device, but the details have
+ // changed, announce the update
+ if (
+ !newDevice &&
+ JSON.stringify(oldDeviceInfo) != JSON.stringify(newDeviceInfo)
+ ) {
+ log("UPDATED " + service + ", DEVICE " + remoteDevice);
+ this.emit(service + "-device-updated", remoteDevice, newDeviceInfo);
+ }
+ }
+ },
+
+ _purgeMissingDevices() {
+ log("PURGING MISSING DEVICES");
+ for (const service in this.remoteServices) {
+ const devicesWithService = this.remoteServices[service];
+ for (const remoteDevice in devicesWithService) {
+ // If we're still expecting a reply from a remote device when it's time
+ // to purge, then the service is removed.
+ if (this._expectingReplies.from.has(remoteDevice)) {
+ delete devicesWithService[remoteDevice];
+ log("REMOVED " + service + ", DEVICE " + remoteDevice);
+ this.emit(service + "-device-removed", remoteDevice);
+ }
+ }
+ }
+ },
+};
+
+var discovery = new Discovery();
+
+module.exports = discovery;
diff --git a/devtools/shared/discovery/moz.build b/devtools/shared/discovery/moz.build
new file mode 100644
index 0000000000..7e67717dd8
--- /dev/null
+++ b/devtools/shared/discovery/moz.build
@@ -0,0 +1,11 @@
+# -*- Mode: python; indent-tabs-mode: nil; tab-width: 40 -*-
+# vim: set filetype=python:
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+XPCSHELL_TESTS_MANIFESTS += ["tests/xpcshell/xpcshell.ini"]
+
+DevToolsModules(
+ "discovery.js",
+)
diff --git a/devtools/shared/discovery/tests/xpcshell/.eslintrc.js b/devtools/shared/discovery/tests/xpcshell/.eslintrc.js
new file mode 100644
index 0000000000..7f6b62a9e5
--- /dev/null
+++ b/devtools/shared/discovery/tests/xpcshell/.eslintrc.js
@@ -0,0 +1,6 @@
+"use strict";
+
+module.exports = {
+ // Extend from the shared list of defined globals for mochitests.
+ extends: "../../../../.eslintrc.xpcshell.js",
+};
diff --git a/devtools/shared/discovery/tests/xpcshell/test_discovery.js b/devtools/shared/discovery/tests/xpcshell/test_discovery.js
new file mode 100644
index 0000000000..cf14d7416c
--- /dev/null
+++ b/devtools/shared/discovery/tests/xpcshell/test_discovery.js
@@ -0,0 +1,158 @@
+/* Any copyright is dedicated to the Public Domain.
+ http://creativecommons.org/publicdomain/zero/1.0/ */
+/* eslint-disable mozilla/no-arbitrary-setTimeout */
+
+"use strict";
+
+const { require } = ChromeUtils.importESModule(
+ "resource://devtools/shared/loader/Loader.sys.mjs"
+);
+const EventEmitter = require("resource://devtools/shared/event-emitter.js");
+const discovery = require("resource://devtools/shared/discovery/discovery.js");
+const { setTimeout, clearTimeout } = ChromeUtils.importESModule(
+ "resource://gre/modules/Timer.sys.mjs"
+);
+
+Services.prefs.setBoolPref("devtools.discovery.log", true);
+
+registerCleanupFunction(() => {
+ Services.prefs.clearUserPref("devtools.discovery.log");
+});
+
+function log(msg) {
+ info("DISCOVERY: " + msg);
+}
+
+// Global map of actively listening ports to TestTransport instances
+var gTestTransports = {};
+
+/**
+ * Implements the same API as Transport in discovery.js. Here, no UDP sockets
+ * are used. Instead, messages are delivered immediately.
+ */
+function TestTransport(port) {
+ EventEmitter.decorate(this);
+ this.port = port;
+ gTestTransports[this.port] = this;
+}
+
+TestTransport.prototype = {
+ send(object, port) {
+ log("Send to " + port + ":\n" + JSON.stringify(object, null, 2));
+ if (!gTestTransports[port]) {
+ log("No listener on port " + port);
+ return;
+ }
+ const message = JSON.stringify(object);
+ gTestTransports[port].onPacketReceived(null, message);
+ },
+
+ destroy() {
+ delete gTestTransports[this.port];
+ },
+
+ // nsIUDPSocketListener
+
+ onPacketReceived(socket, message) {
+ const object = JSON.parse(message);
+ object.from = "localhost";
+ log("Recv on " + this.port + ":\n" + JSON.stringify(object, null, 2));
+ this.emit("message", object);
+ },
+
+ onStopListening(socket, status) {},
+};
+
+// Use TestTransport instead of the usual Transport
+discovery._factories.Transport = TestTransport;
+
+// Ignore name generation on b2g and force a fixed value
+Object.defineProperty(discovery.device, "name", {
+ get() {
+ return "test-device";
+ },
+});
+
+add_task(async function () {
+ // At startup, no remote devices are known
+ deepEqual(discovery.getRemoteDevicesWithService("devtools"), []);
+ deepEqual(discovery.getRemoteDevicesWithService("penguins"), []);
+
+ discovery.scan();
+
+ // No services added yet, still empty
+ deepEqual(discovery.getRemoteDevicesWithService("devtools"), []);
+ deepEqual(discovery.getRemoteDevicesWithService("penguins"), []);
+
+ discovery.addService("devtools", { port: 1234 });
+
+ // Changes not visible until next scan
+ deepEqual(discovery.getRemoteDevicesWithService("devtools"), []);
+ deepEqual(discovery.getRemoteDevicesWithService("penguins"), []);
+
+ await scanForChange("devtools", "added");
+
+ // Now we see the new service
+ deepEqual(discovery.getRemoteDevicesWithService("devtools"), ["test-device"]);
+ deepEqual(discovery.getRemoteDevicesWithService("penguins"), []);
+
+ discovery.addService("penguins", { tux: true });
+ await scanForChange("penguins", "added");
+
+ deepEqual(discovery.getRemoteDevicesWithService("devtools"), ["test-device"]);
+ deepEqual(discovery.getRemoteDevicesWithService("penguins"), ["test-device"]);
+ deepEqual(discovery.getRemoteDevices(), ["test-device"]);
+
+ deepEqual(discovery.getRemoteService("devtools", "test-device"), {
+ port: 1234,
+ host: "localhost",
+ });
+ deepEqual(discovery.getRemoteService("penguins", "test-device"), {
+ tux: true,
+ host: "localhost",
+ });
+
+ discovery.removeService("devtools");
+ await scanForChange("devtools", "removed");
+
+ discovery.addService("penguins", { tux: false });
+ await scanForChange("penguins", "updated");
+
+ // Scan again, but nothing should be removed
+ await scanForNoChange("penguins", "removed");
+
+ // Split the scanning side from the service side to simulate the machine with
+ // the service becoming unreachable
+ gTestTransports = {};
+
+ discovery.removeService("penguins");
+ await scanForChange("penguins", "removed");
+});
+
+function scanForChange(service, changeType) {
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => {
+ reject(new Error("Reply never arrived"));
+ }, discovery.replyTimeout + 500);
+ discovery.on(service + "-device-" + changeType, function onChange() {
+ discovery.off(service + "-device-" + changeType, onChange);
+ clearTimeout(timer);
+ resolve();
+ });
+ discovery.scan();
+ });
+}
+
+function scanForNoChange(service, changeType) {
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => {
+ resolve();
+ }, discovery.replyTimeout + 500);
+ discovery.on(service + "-device-" + changeType, function onChange() {
+ discovery.off(service + "-device-" + changeType, onChange);
+ clearTimeout(timer);
+ reject(new Error("Unexpected change occurred"));
+ });
+ discovery.scan();
+ });
+}
diff --git a/devtools/shared/discovery/tests/xpcshell/xpcshell.ini b/devtools/shared/discovery/tests/xpcshell/xpcshell.ini
new file mode 100644
index 0000000000..145c2d3e2e
--- /dev/null
+++ b/devtools/shared/discovery/tests/xpcshell/xpcshell.ini
@@ -0,0 +1,6 @@
+[DEFAULT]
+tags = devtools
+head =
+firefox-appdir = browser
+
+[test_discovery.js]