Bugzilla

(description coming soon)

The goal here is to implement the `PLATFORM_MESSAGE` resource from the actor side.
This is about replicating the current behavior, implemented in bug 1627977.
But instead of having a wrapper on the client side to morph the legacy WebConsoleActor methods (i.e. the legacy listener code),
we would implement an actor API matching ResourceWatcher API (i.e. watch and unwatch).

This would be about implementing a server side equivalent of this legacy listener code:
https://searchfox.org/mozilla-central/source/devtools/shared/resources/legacy-listeners/platform-messages.js
In a new server side module:
https://searchfox.org/mozilla-central/source/devtools/server/actors/resources/platform-messages.js

This module would typicaly look like this:
```
const { TYPES } = require("devtools/server/actors/resources/index");
const listeners = new WeakMap();

/**
 * Start watching for all ${YOUR RESOURCE} related to a given Target Actor.
 * This will notify about existing ${YOUR RESOURCE}, but also the one created in future.
 *
 * @param TargetActor targetActor
 *        The target actor from which we should observe console messages
 * @param Object options
 *        Dictionary object with following attributes:
 *        - onAvailable: mandatory function
 *          This will be called for each resource.
 */
function watch(targetActor, { onAvailable }) {
  if (listeners.has(targetActor)) {
    throw new Error(
      "Already listening to ${YOUR RESOURCE} for this target actor"
    );
  }
  /* In most cases, we already have some helper class which helps observing one resource
       that we can spawn like this: */
  const listener = new MyResourceListener(
    targetActor.browsingContextID,
    targetActor.window,
    ...  /* whatever is useful for your observation */
  );
  // Forward all future resources being observed to the upper layer calling this module,
  // via `onAvailable` callback argument.
  listener.on("one-of-my-resource-is-created", resource => {
    // We have to ensure that each resource object has a valid `resourceType` attribute
    resource.resourceType = TYPES.MY_RESOURCE_TYPE;
    onAvailable([resource]);
  });
  // Also forward all resources which already exist when we are calling this method
  // (if any exists)
  const cachedResources = listener.getAllAlreadyExistingOrCachedResources();
  for(const resource of cachedResources) {
    resource.resourceType = TYPES.MY_RESOURCE_TYPE;
  }
  onAvailable(cachedResources);
  listeners.set(targetActor, listener);
}

/**
 * Stop watching for ${YOUR RESOURCE} related to a given Target Actor.
 *
 * @param TargetActor targetActor
 *        The target actor from which we should stop observing ${YOUR RESOURCE}
 */
function unwatch(targetActor) {
  const listener = listeners.get(targetActor);
  if (!listener) {
    return;
  }
  // Request our custom subclass to stop listening
  listener.destroy();

  // And remove it from the weakmap so that we can re-watch after that
  listeners.delete(targetActor);
}
```

An important goal here is to emit the exact same `resource` object that the legacy listener is passing to its `onAvailable` callback.
Same attributes, same values, ...

Bug 1620243 could be used as a template. As it did this work for CONSOLE_MESSAGE resource type.

The main reason to do this is to be able to start listening to the resource before the page starts loading.
Thanks to the framework work done in bug 1620243, the `watch` method will be called before the page starts loading and possibly as early as the content process just started. This wasn't the case with legacy actor APIs like WebConsoleActor.startListeners, ThreadActor.attachThread, ... We were calling these methods too late, only after the frontend is notify about the existance of the target, so, late after the page started loading.