Merge pull request #9894 from ptome/boot-server-listen-port

kernel: Add option for erl_boot_server listen port

OTP-19708

Author: jhogberg

lib/kernel/src/erl_boot_server.erl

@@ -61,9 +61,11 @@ and `m:erl_prim_loader` in ERTS.
 -behaviour(gen_server).
 
 %% API functions.
--export([start/1, start_link/1, add_slave/1, delete_slave/1,
-	 add_subnet/2, delete_subnet/2,
-	 which_slaves/0]).
+-export([start/1, start/2,
+         start_link/1, start_link/2,
+         add_slave/1, delete_slave/1,
+         add_subnet/2, delete_subnet/2,
+         which_slaves/0]).
 
 %% Exports for testing (don't remove; tests suites depend on them).
 -export([would_be_booted/1]).
@@ -90,40 +92,85 @@ and `m:erl_prim_loader` in ERTS.
 -define(single_addr_mask, {255, 255, 255, 255}).
 
 -doc """
-Starts the boot server. `Slaves` is a list of IP addresses for hosts, which are
-allowed to use this server as a boot server.
+The same as [`start(Slaves, #{})`](`start/2`).
 """.
 -spec start(Slaves) -> {'ok', Pid} | {'error', Reason} when
       Slaves :: [Host],
       Host :: inet:ip_address() | inet:hostname(),
       Pid :: pid(),
-      Reason :: {'badarg', Slaves}.
+      Reason :: any().
 
 start(Slaves) ->
-    case check_arg(Slaves) of
-	{ok, AL} ->
-	    gen_server:start({local,boot_server}, erl_boot_server, AL, []);
-	_ ->
-	    {error, {badarg, Slaves}}
+    start(Slaves, #{}).
+
+-doc """
+Starts the boot server. `Slaves` is a list of IP addresses for hosts, which are
+allowed to use this server as a boot server. `Options` is a map with
+configuration options.
+
+The boot server listening port can be configured with `listen_port`.
+If an empty map is provided, or `listen_port` is zero, then an ephemeral port
+is used.
+""".
+-spec start(Slaves, Options) -> {'ok', Pid} | {'error', Reason} when
+      Slaves :: [Host],
+      Host :: inet:ip_address() | inet:hostname(),
+      Options :: #{listen_port => inet:port_number()},
+      Pid :: pid(),
+      Reason :: any().
+
+start(Slaves, Options) ->
+    case start_args(Slaves, Options) of
+        {ok, StartArgs} ->
+            gen_server:start({local,boot_server}, erl_boot_server, StartArgs, []);
+        {error, _} = Error ->
+            Error
     end.
 
 -doc """
-Starts the boot server and links to the caller. This function is used to start
-the server if it is included in a supervision tree.
+The same as [`start_link(Slaves, #{})`](`start_link/2`).
 """.
 -spec start_link(Slaves) -> {'ok', Pid} | {'error', Reason} when
       Slaves :: [Host],
       Host :: inet:ip_address() | inet:hostname(),
       Pid :: pid(),
-      Reason :: {'badarg', Slaves}.
+      Reason :: any().
 
 start_link(Slaves) ->
+    start_link(Slaves, #{}).
+
+-doc """
+The same as [`start(Slaves, Options)`](`start/2`), but it also links to the
+caller.
+""".
+-spec start_link(Slaves, Options) -> {'ok', Pid} | {'error', Reason} when
+      Slaves :: [Host],
+      Host :: inet:ip_address() | inet:hostname(),
+      Options :: #{listen_port => inet:port_number()},
+      Pid :: pid(),
+      Reason :: any().
+
+start_link(Slaves, Options) ->
+    case start_args(Slaves, Options) of
+        {ok, StartArgs} ->
+            gen_server:start_link({local,boot_server}, erl_boot_server, StartArgs, []);
+        {error, _} = Error ->
+            Error
+    end.
+
+start_args(Slaves, Options) ->
     case check_arg(Slaves) of
-	{ok, AL} ->
-	    gen_server:start_link({local,boot_server},
-				  erl_boot_server, AL, []);
-	_ ->
-	    {error, {badarg, Slaves}}
+        {ok, Arg} ->
+            case check_options(Options) of
+                true ->
+                    NewOptions = with_default_options(Options),
+                    ListenPort = maps:get(listen_port, NewOptions),
+                    {ok, #{slaves => Arg, listen_port => ListenPort}};
+                false ->
+                    {error, {badarg, Options}}
+            end;
+        _ ->
+            {error, {badarg, Slaves}}
     end.
 
 check_arg(Slaves) ->
@@ -141,6 +188,18 @@ check_arg([], Result) ->
 check_arg(_, _Result) ->
     error.
 
+check_options(Options) when is_map(Options) ->
+    lists:all(fun valid_option/1, maps:to_list(Options));
+check_options(_) ->
+    false.
+
+valid_option({listen_port, Port}) when is_integer(Port) -> true;
+valid_option({_, _}) -> false.
+
+with_default_options(Options) ->
+    DefaultOptions = #{listen_port => 0},
+    maps:merge(DefaultOptions, Options).
+
 -doc "Adds a `Slave` node to the list of allowed slave hosts.".
 -spec add_slave(Slave) -> 'ok' | {'error', Reason} when
       Slave :: Host,
@@ -228,11 +287,14 @@ member_address(_, []) ->
 %% ------------------------------------------------------------
 
 -doc false.
--spec init([atom()]) -> {'ok', state()}.
+-spec init(#{slaves      := list(),
+             listen_port := inet:port_number()})
+          -> {'ok', state()}.
 
-init(Slaves) ->
+init(#{slaves      := Slaves,
+       listen_port := ListenPort}) ->
     {ok, U} = gen_udp:open(?EBOOT_PORT, []),
-    {ok, L} = gen_tcp:listen(0, [binary,{packet,4}]),
+    {ok, L} = gen_tcp:listen(ListenPort, [binary,{packet,4}]),
     {ok, Port} = inet:port(L),
     {ok, UPort} = inet:port(U),
     Ref = make_ref(),

lib/kernel/test/erl_boot_server_SUITE.erl

@@ -100,6 +100,14 @@ start(Config) when is_list(Config) ->
     {error, {badarg, [Host1, BadHost]}} =
 	erl_boot_server:start([Host1, BadHost]),
 
+    %% Bad arguments - Options.
+    {error, {badarg, {}}} = erl_boot_server:start([Host1], {}),
+    {error, {badarg, []}} = erl_boot_server:start([Host1], []),
+    {error, {badarg, atom}} = erl_boot_server:start([Host1], atom),
+    {error, {badarg, 1234}} = erl_boot_server:start([Host1], 1234),
+    {error, {badarg, #{port := 1234}}} =
+        erl_boot_server:start([Host1], #{port => 1234}),
+
     %% Test once.
     {ok, Pid1} = erl_boot_server:start([Host1]),
     {error, {already_started, Pid1}} =
@@ -114,6 +122,20 @@ start(Config) when is_list(Config) ->
     exit(Pid2, kill),
     ct:sleep(1),
 
+    %% Test default options.
+    ct:sleep(1),
+    {ok, Pid3} = erl_boot_server:start([Host1, Host2], #{}),
+    {error, {already_started, Pid3}} = erl_boot_server:start([Host1, Host2]),
+    exit(Pid3, kill),
+    ct:sleep(1),
+
+    %% Test explicit options.
+    ct:sleep(1),
+    {ok, Pid4} = erl_boot_server:start([Host1, Host2], #{listen_port => 1234}),
+    {error, {already_started, Pid4}} = erl_boot_server:start([Host1, Host2]),
+    exit(Pid4, kill),
+    ct:sleep(1),
+
     ok.
 
 %% Tests the erl_boot_server:start_link/1 function.
@@ -127,6 +149,14 @@ start_link(Config) when is_list(Config) ->
     {error, {badarg, [atom, BadHost]}} =
 	erl_boot_server:start_link([atom, BadHost]),
 
+    %% Bad arguments - Options.
+    {error, {badarg, {}}} = erl_boot_server:start_link([Host1], {}),
+    {error, {badarg, []}} = erl_boot_server:start_link([Host1], []),
+    {error, {badarg, atom}} = erl_boot_server:start_link([Host1], atom),
+    {error, {badarg, 1234}} = erl_boot_server:start_link([Host1], 1234),
+    {error, {badarg, #{port := 1234}}} =
+        erl_boot_server:start_link([Host1], #{port => 1234}),
+
     {ok, Pid1} = erl_boot_server:start_link([Host1]),
     {error, {already_started, Pid1}} =
 	erl_boot_server:start_link([Host1]),
@@ -136,6 +166,19 @@ start_link(Config) when is_list(Config) ->
     {error, {already_started, Pid2}} =
 	erl_boot_server:start_link([Host1, Host2]),
     shutdown(Pid2),
+
+    %% Test default options.
+    {ok, Pid3} = erl_boot_server:start_link([Host1, Host2], #{}),
+    {error, {already_started, Pid3}} =
+        erl_boot_server:start_link([Host1, Host2]),
+    shutdown(Pid3),
+
+    %% Test explicit options.
+    {ok, Pid4} =
+        erl_boot_server:start_link([Host1, Host2], #{listen_port => 1234}),
+    {error, {already_started, Pid4}} =
+        erl_boot_server:start_link([Host1, Host2]),
+    shutdown(Pid4),
     process_flag(trap_exit, OldFlag),
 
     ok.