Complete documentation

Author: xxlabaza

server/README.md

@@ -9,73 +9,43 @@
 Run it as a regular `Java` CLI app:
 
 ```bash
-$> java -jar epmd-2.0.0.jar
-2019-06-06 00:10:18.869  INFO : Starting server on port 4369
+$> java -jar epmd-2.0.0.jar server
+2019-03-17 01:38:09.302  INFO : EPMD server started (debug: false, port: 4369, allowed-ips: [localhost/127.0.0.1], unsafe-commands: true)
 
 ```
 
 To get names of all registered nodes:
 
 ```bash
-$> java -jar epmd-2.0.0.jar -names
-popa
-echo
+$> java -jar epmd-2.0.0.jar names
+2019-03-17 01:45:39.310  INFO : EPMD up and running on port 4369 with the registered node(s):
+ - node 'echo' at port 60045
 ```
 
 To see another options and commands, just type:
 
 ```bash
 $> java -jar epmd-2.0.0.jar --help
-usage: java -jar epmd.jar [-d|-debug] [DbgExtra...] [-address List]
-                          [-port No] [-daemon] [-relaxed_command_check]
-       java -jar epmd.jar [-d|-debug] [-port No] [-names|-kill|-stop name]
-
-Regular options
-    -address List
-        Let epmd listen only on the comma-separated list of IP
-        addresses (and on the loopback interface).
-    -port No
-        Let epmd listen to another port than default 4369
-    -d
-    -debug
-        Enable debugging. This will give a log to
-        the standard error stream. It will shorten
-        the number of saved used node names to 5.
-
-        If you give more than one debug flag you may
-        get more debugging information.
-    -relaxed_command_check
-        Allow this instance of epmd to be killed with
-        epmd -kill even if there are registered nodes.
-        Also allows forced unregister (epmd -stop).
-
-DbgExtra options
-    -packet_timeout Seconds
-        Set the number of seconds a connection can be
-        inactive before epmd times out and closes the
-        connection (default 60).
-
-    -delay_accept Seconds
-        To simulate a busy server you can insert a
-        delay between epmd gets notified about that
-        a new connection is requested and when the
-        connections gets accepted.
-
-    -delay_write Seconds
-        Also a simulation of a busy server. Inserts
-        a delay before a reply is sent.
-
-Interactive options
-    -names
-        List names registered with the currently running epmd
-    -kill
-        Kill the currently running epmd
-        (only allowed if -names show empty database or
-        -relaxed_command_check was given when epmd was started).
-    -stop Name
-        Forcibly unregisters a name with epmd
-        (only allowed if -relaxed_command_check was given when
-        epmd was started).
+Usage: epmd [-dhV] [-p=PORT] [COMMAND]
+
+Erlang port mapper daemon. This is a small name server used by Erlang programs
+when establishing distributed Erlang communications.
+
+Options:
+  -p, --port=PORT   Let epmd listen to another port than default 4369. This can also
+                      be set using environment variable ERL_EPMD_PORT
+  -d, --debug       Enables debugging logs
+  -h, --help        Show this help message and exit.
+  -V, --version     Print version information and exit.
+
+Commands:
+  help    Displays help information about the specified command
+  names   Lists names registered with the currently running epmd.
+  server  Starts the epmd server.
+  stop    Forcibly unregisters a live node from the epmd database.
+  kill    Kills the currently running epmd.
+
+Run 'epmd help COMMAND' for more information on a command.
 
 ```
 
@@ -104,12 +74,13 @@ compile 'io.appulse.epmd.java:server:2.0.0'
 To start EPMD server in your code:
 
 ```java
+import io.appulse.epmd.java.server.SubcommandServer;
 // ...
-CommonOptions commonOptions = new CommonOptions();
-commonOptions.setPort(4369);
-
-ServerCommandExecutor server = new ServerCommandExecutor(commonOptions, new ServerCommandOptions());
+val server = SubcommandServer.builder()
+    .port(6666) // if not set, default is 4369
+    .ip(SubcommandServer.ANY_ADDRESS) // if not set, default is LOOPBACK
+    .build();
 
-server.execute(); // it starts Netty server and blocks current thread
+server.run(); // it starts the server and blocks the current thread
 // ...
 ```

server/src/main/java/io/appulse/epmd/java/server/Epmd.java

@@ -19,11 +19,14 @@
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.NoArgsConstructor;
+import lombok.Setter;
 import lombok.extern.slf4j.Slf4j;
 import picocli.CommandLine.Command;
+import picocli.CommandLine.HelpCommand;
 import picocli.CommandLine.Option;
 
 @Slf4j
+@Setter
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
@@ -39,8 +42,10 @@
       "used by Erlang programs when establishing distributed " +
       "Erlang communications.",
     mixinStandardHelpOptions = true,
+    footer = "%nRun 'epmd help COMMAND' for more information on a command.",
     version = "epmd version \"2.0.0\" 2019-03-17",
     subcommands = {
+      HelpCommand.class,
       SubcommandNames.class,
       SubcommandServer.class,
       SubcommandStop.class,

server/src/main/java/io/appulse/epmd/java/server/SubcommandKill.java

@@ -30,7 +30,15 @@
 import picocli.CommandLine.ParentCommand;
 
 @Slf4j
-@Command(name = "kill")
+@Command(
+    name = "kill",
+    sortOptions = false,
+    descriptionHeading = "%n",
+    parameterListHeading = "%nParameters:%n",
+    optionListHeading = "%nOptions:%n",
+    commandListHeading = "%nCommands:%n",
+    description = "Kills the currently running epmd."
+)
 class SubcommandKill implements Runnable {
 
   @ParentCommand

server/src/main/java/io/appulse/epmd/java/server/SubcommandNames.java

@@ -32,7 +32,15 @@
 import picocli.CommandLine.ParentCommand;
 
 @Slf4j
-@Command(name = "names")
+@Command(
+    name = "names",
+    sortOptions = false,
+    descriptionHeading = "%n",
+    parameterListHeading = "%nParameters:%n",
+    optionListHeading = "%nOptions:%n",
+    commandListHeading = "%nCommands:%n",
+    description = "Lists names registered with the currently running epmd."
+)
 class SubcommandNames implements Runnable {
 
   @ParentCommand

server/src/main/java/io/appulse/epmd/java/server/SubcommandServer.java

@@ -85,17 +85,28 @@
 
 @Slf4j
 @NoArgsConstructor
-@Command(name = "server")
-class SubcommandServer implements Runnable {
+@Command(
+    name = "server",
+    sortOptions = false,
+    descriptionHeading = "%n",
+    parameterListHeading = "%nParameters:%n",
+    optionListHeading = "%nOptions:%n",
+    commandListHeading = "%nCommands:%n",
+    description = "Starts the epmd server."
+)
+public class SubcommandServer implements Runnable {
 
   static final InetAddress ANY_ADDRESS;
 
   static final InetAddress LOOPBACK_ADDRESS;
 
+  static final InetAddress LOCALHOST;
+
   static {
     try {
       ANY_ADDRESS = InetAddress.getByName("0.0.0.0");
       LOOPBACK_ADDRESS = InetAddress.getLoopbackAddress();
+      LOCALHOST = InetAddress.getLocalHost();
     } catch (UnknownHostException ex) {
       throw new IllegalStateException(ex);
     }
@@ -104,22 +115,38 @@ class SubcommandServer implements Runnable {
   @ParentCommand
   Epmd options;
 
-  @Option(names = { "-a", "--allowed-ips" })
+  @Option(
+      names = { "-a", "--allowed-ips" },
+      description =
+          "Lets this instance of epmd listen only on the comma-separated list of IP addresses" +
+          "and on the loopback address (which is implicitly added to the list if it has not been " +
+          "specified). This can also be set using environment variable ERL_EPMD_ADDRESS"
+  )
   Set<InetAddress> ips = new HashSet<>(asList(LOOPBACK_ADDRESS));
 
-  @Option(names = { "-u", "--unsafe-commands" })
+  @Option(
+      names = { "-u", "--unsafe-commands" },
+      description = {
+        "Start the epmd program with relaxed command checking. This affects the following:",
+        "With relaxed command checking, the epmd daemon can be killed from the localhost with i.e. epmd -kill even if there are active nodes registered. Normally only daemons with an empty node database can be killed with the epmd \"kill\" command.",
+        "With relaxed command checking enabled, you can forcibly unregister live nodes by \"stop\" command."
+      }
+  )
   boolean unsafe;
 
   Map<String, Node> nodes;
 
   ExecutorService executor;
 
   @Builder
-  SubcommandServer (@NonNull Epmd options,
+  SubcommandServer (Integer port,
                     @Singular Set<InetAddress> ips,
                     boolean unsafe
   ) {
-    this.options = options;
+    options = new Epmd();
+    ofNullable(port)
+        .ifPresent(options::setPort);
+
     this.unsafe = unsafe;
 
     ofNullable(ips)
@@ -199,7 +226,7 @@ public void run () {
         if (remoteAddress == null) {
           log.warn("uh?");
           continue;
-        } else if (!ips.contains(ANY_ADDRESS) && !ips.contains(remoteAddress)) {
+        } else if (!ips.contains(ANY_ADDRESS) && !ips.contains(remoteAddress) && !LOCALHOST.equals(remoteAddress)) {
           clientSocket.close();
           log.warn("unacceptable remote client's address {}", remoteAddress);
           continue;

server/src/main/java/io/appulse/epmd/java/server/SubcommandStop.java

@@ -31,13 +31,24 @@
 import picocli.CommandLine.ParentCommand;
 
 @Slf4j
-@Command(name = "stop")
+@Command(
+    name = "stop",
+    sortOptions = false,
+    descriptionHeading = "%n",
+    parameterListHeading = "%nParameters:%n",
+    optionListHeading = "%nOptions:%n",
+    commandListHeading = "%nCommands:%n",
+    description = "Forcibly unregisters a live node from the epmd database."
+)
 class SubcommandStop implements Runnable {
 
   @ParentCommand
   Epmd options;
 
-  @Parameters
+  @Parameters(
+      paramLabel = "NAME",
+      description = "A node's name for stopping"
+  )
   String name;
 
   @Override

server/src/test/java/io/appulse/epmd/java/server/SubcommandServerTests.java

@@ -58,9 +58,7 @@ class SubcommandServerTests {
   @BeforeEach
   void before () throws Exception {
     val server = SubcommandServer.builder()
-        .options(Epmd.builder()
-            .port(SocketUtils.findFreePort().orElseThrow(RuntimeException::new))
-            .build())
+        .port(SocketUtils.findFreePort().orElseThrow(RuntimeException::new))
         .ip(SubcommandServer.ANY_ADDRESS)
         .build();