From 53a8db10195f9aae640b238fa3d571bf0136a55a Mon Sep 17 00:00:00 2001 From: Jan Uhlig Date: Wed, 2 Oct 2024 12:22:10 +0200 Subject: Fix alarm setting typo The setting `threshold` was misspelled as `treshold`. --- doc/src/guide/listeners.asciidoc | 6 +++--- doc/src/guide/migrating_from_2.0.asciidoc | 2 +- doc/src/manual/ranch.asciidoc | 8 ++++---- src/ranch.erl | 31 +++++++++++++++++++++++++++---- src/ranch_conns_sup.erl | 5 +++-- test/acceptor_SUITE.erl | 2 +- 6 files changed, 39 insertions(+), 15 deletions(-) diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc index 9ee2d98..c30cb5c 100644 --- a/doc/src/guide/listeners.asciidoc +++ b/doc/src/guide/listeners.asciidoc @@ -332,14 +332,14 @@ processes. The `alarms` transport option allows you to configure alarms which will be triggered when the number of connections tracked -by one connection supervisor reaches or exceeds the defined treshold. +by one connection supervisor reaches or exceeds the defined threshold. The `alarms` transport option takes a map with alarm names as keys and alarm options as values. Any term is allowed as an alarm name. -Alarm options include the alarm type and a treshold that, when reached, +Alarm options include the alarm type and a threshold that, when reached, triggers the given callback. A cooldown prevents the alarm from being triggered too often. @@ -350,7 +350,7 @@ triggered too often. Alarms = #{ my_alarm => #{ type => num_connections, - treshold => 100, + threshold => 100, callback => fun(Ref, Name, ConnSup, ConnPids]) -> logger:warning("Warning (~s): " "Supervisor ~s of listener ~s " diff --git a/doc/src/guide/migrating_from_2.0.asciidoc b/doc/src/guide/migrating_from_2.0.asciidoc index fb2c69d..498a581 100644 --- a/doc/src/guide/migrating_from_2.0.asciidoc +++ b/doc/src/guide/migrating_from_2.0.asciidoc @@ -18,7 +18,7 @@ for Erlang/OTP 21 has been removed. * Alarms can now be configured. The only alarm currently available is `num_connections`. When the number of - connections goes over a configurable treshold Ranch + connections goes over a configurable threshold Ranch will call the given callback. This can be used to programmatically shut down idle connections to make up space for new connections, for example. diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc index 2f62b81..b5dd615 100644 --- a/doc/src/manual/ranch.asciidoc +++ b/doc/src/manual/ranch.asciidoc @@ -91,7 +91,7 @@ transport_opts(SocketOpts) = #{ alarms => #{ term() => #{ type := num_connections, - treshold := non_neg_integer(), + threshold := non_neg_integer(), callback := fun((ref(), term(), pid(), [pid()]) -> any()), cooldown => non_neg_integer() } @@ -118,7 +118,7 @@ None of the options are required. alarms (#{}):: Alarms to call a function when the number of connections tracked -by one connection supervisor reaches or exceeds a defined treshold. +by one connection supervisor reaches or exceeds a defined threshold. + The map keys are the alarm names, which can be any `term`. The associated values are the respective alarm options, again in a map @@ -128,9 +128,9 @@ type::: Must be set to `num_connections`. -treshold::: +threshold::: -Treshold value, which must be a `non_neg_integer`. When the +Threshold value, which must be a `non_neg_integer`. When the number of connections tracked by a single connection supervisor reaches or exceeds this value, The alarm will trigger and call the function defined in the `callback` key (see below). diff --git a/src/ranch.erl b/src/ranch.erl index e52f0e7..295e103 100644 --- a/src/ranch.erl +++ b/src/ranch.erl @@ -50,6 +50,9 @@ -export([require/1]). -export([log/4]). +%% Internal +-export([compat_normalize_alarms_option/1]). + -type max_conns() :: non_neg_integer() | infinity. -export_type([max_conns/0]). @@ -59,7 +62,7 @@ -type alarm(Type, Callback) :: #{ type := Type, callback := Callback, - treshold := non_neg_integer(), + threshold := non_neg_integer(), cooldown => non_neg_integer() }. @@ -135,6 +138,7 @@ validate_transport_opt(max_connections, infinity, _) -> validate_transport_opt(max_connections, Value, _) -> is_integer(Value) andalso Value >= 0; validate_transport_opt(alarms, Alarms, _) -> + Alarms1 = compat_normalize_alarms_option(Alarms), maps:fold( fun (_, Opts, true) -> @@ -143,7 +147,7 @@ validate_transport_opt(alarms, Alarms, _) -> false end, true, - Alarms); + Alarms1); validate_transport_opt(logger, Value, _) -> is_atom(Value); validate_transport_opt(num_acceptors, Value, _) -> @@ -166,9 +170,9 @@ validate_transport_opt(socket_opts, _, _) -> validate_transport_opt(_, _, _) -> false. -validate_alarm(Alarm = #{type := num_connections, treshold := Treshold, +validate_alarm(Alarm = #{type := num_connections, threshold := Threshold, callback := Callback}) -> - is_integer(Treshold) andalso Treshold >= 0 + is_integer(Threshold) andalso Threshold >= 0 andalso is_function(Callback, 4) andalso case Alarm of #{cooldown := Cooldown} -> @@ -649,3 +653,22 @@ log(Level, Format, Args, _) -> debug -> info_msg end, error_logger:Function(Format, Args). + +%% For backwards compatibility with the misspelled alarm +%% setting `treshold`. +%% See https://github.com/ninenines/ranch/issues/349 +-spec compat_normalize_alarms_option(any()) -> any(). +compat_normalize_alarms_option(Alarms = #{}) -> + maps:map( + fun + (_, Alarm = #{threshold := _}) -> + maps:remove(treshold, Alarm); + (_, Alarm = #{treshold := Threshold}) -> + maps:put(threshold, Threshold, maps:remove(treshold, Alarm)); + (_, Alarm) -> + Alarm + end, + Alarms + ); +compat_normalize_alarms_option(Alarms) -> + Alarms. diff --git a/src/ranch_conns_sup.erl b/src/ranch_conns_sup.erl index 6e6de00..05ef84c 100644 --- a/src/ranch_conns_sup.erl +++ b/src/ranch_conns_sup.erl @@ -287,7 +287,7 @@ trigger_alarms(Ref, Alarms, CurConns) -> Alarms ). -trigger_alarm(Ref, AlarmName, {Opts=#{treshold := Treshold, callback := Callback}, undefined}, CurConns) when CurConns >= Treshold -> +trigger_alarm(Ref, AlarmName, {Opts=#{threshold := Threshold, callback := Callback}, undefined}, CurConns) when CurConns >= Threshold -> ActiveConns = [Pid || {Pid, active} <- get()], case Callback of {Mod, Fun} -> @@ -306,6 +306,7 @@ schedule_activate_alarm(_, _) -> undefined. get_alarms(#{alarms := Alarms}) when is_map(Alarms) -> + Alarms1 = ranch:compat_normalize_alarms_option(Alarms), maps:fold( fun (Name, Opts = #{type := num_connections, cooldown := _}, Acc) -> @@ -315,7 +316,7 @@ get_alarms(#{alarms := Alarms}) when is_map(Alarms) -> (_, _, Acc) -> Acc end, #{}, - Alarms + Alarms1 ); get_alarms(_) -> #{}. diff --git a/test/acceptor_SUITE.erl b/test/acceptor_SUITE.erl index 9bf4ffc..1b0bfd4 100644 --- a/test/acceptor_SUITE.erl +++ b/test/acceptor_SUITE.erl @@ -599,7 +599,7 @@ misc_connection_alarms(_) -> Self ! {connection_alarm, {Ref, AlarmName, length(ActiveConns)}} end, Alarms0 = #{ - test1 => Alarm1 = #{type => num_connections, treshold => 2, cooldown => 0, callback => AlarmCallback}, + test1 => Alarm1 = #{type => num_connections, threshold => 2, cooldown => 0, callback => AlarmCallback}, test2 => Alarm2 = #{type => num_connections, treshold => 3, cooldown => 0, callback => AlarmCallback} }, ConnectOpts = [binary, {active, false}, {packet, raw}], -- cgit v1.2.3