plugin: sort topological candidates by specified order.

We previously registered hooks up in who-replies-to-getmanifest-first
order, but then if any had dependencies it would scatter that order.

This allows users to manually set dependencies developers have
forgotten by specifying the plugins manually in their configuration or
cmdline.  This was an excellent consideration by @mschmook.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

doc/PLUGINS.md

@@ -712,11 +712,15 @@ The call semantics of the hooks, i.e., when and how hooks are called, depend
 on the hook type. Most hooks are currently set to `single`-mode. In this mode
 only a single plugin can register the hook, and that plugin will get called
 for each event of that type. If a second plugin attempts to register the hook
-it gets killed and a corresponding log entry will be added to the logs. In
-`chain`-mode multiple plugins can register for the hook type and they are
-called in any order which meets their `before` and `after` requirements
-if a matching event is triggered. Each plugin can then
-handle the event or defer by returning a `continue` result like the following:
+it gets killed and a corresponding log entry will be added to the logs.
+
+In `chain`-mode multiple plugins can register for the hook type and
+they are called in any order they are loaded (i.e. cmdline order
+first, configuration order file second: though note that the order of
+plugin directories is implementation-dependent), overriden only by
+`before` and `after` requirements the plugin's hook registrations specify.
+Each plugin can then handle the event or defer by returning a
+`continue` result like the following:
 
 ```json
 {

doc/lightningd-config.5

@@ -519,14 +519,17 @@ additional paths too:
 
  \fBplugin\fR=\fIPATH\fR
 Specify a plugin to run as part of c-lightning\. This can be specified
-multiple times to add multiple plugins\.
+multiple times to add multiple plugins\.  Note that unless plugins themselves
+specify ordering requirements for being called on various hooks, plugins will
+be ordered by commandline, then config file\.
 
 
  \fBplugin-dir\fR=\fIDIRECTORY\fR
 Specify a directory to look for plugins; all executable files not
 containing punctuation (other than \fI\.\fR, \fI-\fR or \fI_) in 'DIRECTORY\fR are
 loaded\. \fIDIRECTORY\fR must exist; this can be specified multiple times to
-add multiple directories\.
+add multiple directories\.  The ordering of plugins within a directory
+is currently unspecified\.
 
 
  \fBclear-plugins\fR
@@ -581,4 +584,4 @@ Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 Note: the modules in the ccan/ directory have their own licenses, but
 the rest of the code is covered by the BSD-style MIT license\.
 
-\" SHA256STAMP:6b275a3227db6565ad3c5369b95d3eefe9472864b8ed9e6c5c768981cdf23b8f
+\" SHA256STAMP:c927bd3afb61288bb67d941d113cdeefe1363b0c7a28936ef30d43af3ce66098

doc/lightningd-config.5.md

@@ -427,13 +427,16 @@ additional paths too:
 
  **plugin**=*PATH*
 Specify a plugin to run as part of c-lightning. This can be specified
-multiple times to add multiple plugins.
+multiple times to add multiple plugins.  Note that unless plugins themselves
+specify ordering requirements for being called on various hooks, plugins will
+be ordered by commandline, then config file.
 
  **plugin-dir**=*DIRECTORY*
 Specify a directory to look for plugins; all executable files not
 containing punctuation (other than *.*, *-* or *\_) in 'DIRECTORY* are
 loaded. *DIRECTORY* must exist; this can be specified multiple times to
-add multiple directories.
+add multiple directories.  The ordering of plugins within a directory
+is currently unspecified.
 
  **clear-plugins**
 This option clears all *plugin*, *important-plugin*, and *plugin-dir* options