Add cowboy:get_env/2,3

doc/src/manual/cowboy.asciidoc

@@ -14,6 +14,7 @@ manipulating Ranch listeners.
 * link:man:cowboy:start_clear(3)[cowboy:start_clear(3)] - Listen for connections using plain TCP
 * link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] - Listen for connections using TLS
 * link:man:cowboy:stop_listener(3)[cowboy:stop_listener(3)] - Stop the given listener
+* link:man:cowboy:get_env(3)[cowboy:get_env(3)] - Retrieve a listener's environment value
 * link:man:cowboy:set_env(3)[cowboy:set_env(3)] - Update a listener's environment value
 
 == Types

doc/src/manual/cowboy.get_env.asciidoc

@@ -0,0 +1,78 @@
+= cowboy:get_env(3)
+
+== Name
+
+cowboy:get_env - Retrieve a listener's environment value
+
+== Description
+
+[source,erlang]
+----
+get_env(Name :: ranch:ref(),
+        Key  :: atom())
+    -> any()
+
+get_env(Name    :: ranch:ref(),
+        Key     :: atom(),
+        Default :: any())
+    -> any()
+----
+
+Retrieve an environment value for a previously started
+listener.
+
+This function may crash when the key is missing from the
+environment and a default value is not provided.
+
+== Arguments
+
+Name::
+
+The name of the listener to access.
++
+The name of the listener is the first argument given to the
+link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
+link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] or
+link:man:ranch:start_listener(3)[ranch:start_listener(3)] function.
+
+Key::
+
+The key in the environment map. Common keys include `dispatch`
+and `middlewares`.
+
+Default::
+
+The default value if the key is missing.
+
+== Return value
+
+The environment value is returned on success.
+
+If a default was provided and the key is missing, then the
+default value is returned.
+
+An `exit:badarg` exception is thrown when the listener does
+not exist.
+
+An `exit:{badkey, Key}` exception is thrown when the key
+requested is missing and no default was provided.
+
+== Changelog
+
+* *2.11*: Function introduced.
+
+== Examples
+
+.Retrieve a listener's routes
+[source,erlang]
+----
+Dispatch = cowboy:get_env(example, dispatch).
+----
+
+== See also
+
+link:man:cowboy(3)[cowboy(3)],
+link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
+link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
+link:man:cowboy:set_env(3)[cowboy:set_env(3)],
+link:man:ranch:get_protocol_options(3)[ranch:get_protocol_options(3)]

doc/src/manual/cowboy.set_env.asciidoc

@@ -76,4 +76,5 @@ cowboy:set_env(example, dispatch, Dispatch).
 link:man:cowboy(3)[cowboy(3)],
 link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
 link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
+link:man:cowboy:get_env(3)[cowboy:get_env(3)],
 link:man:ranch:set_protocol_options(3)[ranch:set_protocol_options(3)]

src/cowboy.erl

@@ -17,6 +17,8 @@
 -export([start_clear/3]).
 -export([start_tls/3]).
 -export([stop_listener/1]).
+-export([get_env/2]).
+-export([get_env/3]).
 -export([set_env/3]).
 
 %% Internal.
@@ -69,6 +71,18 @@ ensure_connection_type(TransOpts) ->
 stop_listener(Ref) ->
 	ranch:stop_listener(Ref).
 
+-spec get_env(ranch:ref(), atom()) -> ok.
+get_env(Ref, Name) ->
+	Opts = ranch:get_protocol_options(Ref),
+	Env = maps:get(env, Opts, #{}),
+	maps:get(Name, Env).
+
+-spec get_env(ranch:ref(), atom(), any()) -> ok.
+get_env(Ref, Name, Default) ->
+	Opts = ranch:get_protocol_options(Ref),
+	Env = maps:get(env, Opts, #{}),
+	maps:get(Name, Env, Default).
+
 -spec set_env(ranch:ref(), atom(), any()) -> ok.
 set_env(Ref, Name, Value) ->
 	Opts = ranch:get_protocol_options(Ref),

test/misc_SUITE.erl

@@ -21,26 +21,26 @@
 -import(cowboy_test, [gun_open/1]).
 
 all() ->
-	[{group, app}, {group, set_env}|cowboy_test:common_all()].
+	[{group, app}, {group, env}|cowboy_test:common_all()].
 
 groups() ->
 	Common = ct_helper:all(?MODULE)
-		-- [restart_gracefully, set_env, set_env_missing],
+		-- [restart_gracefully, get_env, set_env, set_env_missing],
 	[
 		{app, [], [restart_gracefully]},
-		{set_env, [parallel], [set_env, set_env_missing]}
+		{env, [parallel], [get_env, set_env, set_env_missing]}
 	|cowboy_test:common_groups(Common)].
 
 init_per_group(Name=app, Config) ->
 	cowboy_test:init_http(Name, #{
 		env => #{dispatch => init_dispatch(Config)}
 	}, Config);
-init_per_group(set_env, Config) ->
+init_per_group(env, Config) ->
 	Config;
 init_per_group(Name, Config) ->
 	cowboy_test:init_common_groups(Name, Config, ?MODULE).
 
-end_per_group(set_env, _) ->
+end_per_group(env, _) ->
 	ok;
 end_per_group(Name, _) ->
 	cowboy:stop_listener(Name).
@@ -84,6 +84,26 @@ router_invalid_path(Config) ->
 	{response, _, 400, _} = gun:await(ConnPid, Ref),
 	ok.
 
+get_env(Config0) ->
+	doc("Ensure we can retrieve middleware environment values."),
+	Dispatch = init_dispatch(Config0),
+	_Config = cowboy_test:init_http(?FUNCTION_NAME, #{
+		env => #{
+			dispatch => Dispatch,
+			the_key => the_value
+		}
+	}, Config0),
+	try
+		Dispatch = cowboy:get_env(?FUNCTION_NAME, dispatch),
+		Dispatch = cowboy:get_env(?FUNCTION_NAME, dispatch, the_default),
+		the_value = cowboy:get_env(?FUNCTION_NAME, the_key),
+		the_value = cowboy:get_env(?FUNCTION_NAME, the_key, the_default),
+		{'EXIT', _} = (catch cowboy:get_env(?FUNCTION_NAME, missing_key)),
+		the_default = cowboy:get_env(?FUNCTION_NAME, missing_key, the_default)
+	after
+		cowboy:stop_listener(?FUNCTION_NAME)
+	end.
+
 set_env(Config0) ->
 	doc("Live replace a middleware environment value."),
 	Config = cowboy_test:init_http(?FUNCTION_NAME, #{