From 67df6fedaea83b8159fbadbadf460a1f3dd98c51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 5 Jan 2024 12:31:48 +0100 Subject: Add cowboy:get_env/2,3 --- doc/src/manual/cowboy.asciidoc | 1 + doc/src/manual/cowboy.get_env.asciidoc | 78 ++++++++++++++++++++++++++++++++++ doc/src/manual/cowboy.set_env.asciidoc | 1 + src/cowboy.erl | 14 ++++++ test/misc_SUITE.erl | 30 ++++++++++--- 5 files changed, 119 insertions(+), 5 deletions(-) create mode 100644 doc/src/manual/cowboy.get_env.asciidoc diff --git a/doc/src/manual/cowboy.asciidoc b/doc/src/manual/cowboy.asciidoc index c213df0..9298b6d 100644 --- a/doc/src/manual/cowboy.asciidoc +++ b/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 diff --git a/doc/src/manual/cowboy.get_env.asciidoc b/doc/src/manual/cowboy.get_env.asciidoc new file mode 100644 index 0000000..c2895b0 --- /dev/null +++ b/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)] diff --git a/doc/src/manual/cowboy.set_env.asciidoc b/doc/src/manual/cowboy.set_env.asciidoc index 30af485..fc0d1f7 100644 --- a/doc/src/manual/cowboy.set_env.asciidoc +++ b/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)] diff --git a/src/cowboy.erl b/src/cowboy.erl index bd81cf3..21d7f59 100644 --- a/src/cowboy.erl +++ b/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), diff --git a/test/misc_SUITE.erl b/test/misc_SUITE.erl index 6245636..ac8f1dd 100644 --- a/test/misc_SUITE.erl +++ b/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, #{ -- cgit v1.2.3