qf-check: more stable carriers check API (2600hz#2973)

* qf-check: accumulate checks inside KNM

* qf-check: basis for future implementation

* qf-check: fix docs

* qf-check: add tests

applications/crossbar/doc/phone_numbers.md

@@ -493,12 +493,14 @@ A non-conforming `{PHONE_NUMBER}`: `"+141510010+15"`.
 
 #### Check availability of phone numbers
 
-This API check if the numbers are still available for purchase.
+> POST /v2/accounts/{ACCOUNT_ID}/phone_numbers/check
 
-- IN <- List of numbers
-- OUT -> JSON; Key = Number, Value = status
+This API checks if the numbers are still available for purchase.
 
-> POST /v2/accounts/{ACCOUNT_ID}/phone_numbers/check
+A status of `"error"` may be due to:
+
+* Number not being handled by carrier `knm_other`
+* `phonebook` being unresponsive
 
 ```shell
 curl -v -X POST \
@@ -509,8 +511,6 @@ curl -v -X POST \
 
 ##### Response
 
-###### Success
-
 ```json
 {
     "auth_token": "{AUTH_TOKEN}",
@@ -524,25 +524,6 @@ curl -v -X POST \
 }
 ```
 
-###### Failure
-
-When server encounters an error `"data": {}` is returned.
-
-It may be due to:
-
-* Number not being handled by carrier `other`
-* `phonebook` being unresponsive
-
-```json
-{
-    "auth_token": "{AUTH_TOKEN}",
-    "data": {},
-    "request_id": "{REQUEST_ID}",
-    "revision": "{REVISION}",
-    "status": "success"
-}
-```
-
 
 #### Get locality information for a collection of numbers
 

applications/crossbar/src/modules_v2/cb_phone_numbers_v2.erl

@@ -331,9 +331,7 @@ post(Context, ?FIX) ->
     summary(Context);
 post(Context, ?CHECK) ->
     Numbers = cb_context:req_value(Context, ?COLLECTION_NUMBERS),
-    Unformatted = knm_carriers:check(Numbers),
-    RespData = format_carriers_check(Unformatted),
-    cb_context:set_resp_data(Context, RespData);
+    cb_context:set_resp_data(Context, knm_carriers:check(Numbers));
 post(Context, ?COLLECTION) ->
     Results = collection_process(Context, ?HTTP_POST),
     CB = fun() -> post(cb_context:set_accepting_charges(Context), ?COLLECTION) end,
@@ -719,29 +717,6 @@ validate_collection_request(Context, _E) ->
                             ]),
     cb_context:add_validation_error(?COLLECTION_NUMBERS, <<"type">>, Msg, Context).
 
-%%--------------------------------------------------------------------
-%% @private
-%% @doc
-%% @end
-%%--------------------------------------------------------------------
--spec format_carriers_check(list()) -> kz_json:object().
--spec format_carriers_check(list(), kz_json:object()) -> kz_json:object().
-format_carriers_check(Checked) ->
-    format_carriers_check(Checked, kz_json:new()).
-format_carriers_check([], JObj) -> JObj;
-format_carriers_check([{_Module, {'ok', ModuleResults}}|Rest], JObj) ->
-    JObj1 =
-        lists:foldl(
-          fun ({Number, Status}, Acc) ->
-                  kz_json:set_value(Number, Status, Acc)
-          end
-                   ,JObj
-                   ,kz_json:to_proplist(ModuleResults)
-         ),
-    format_carriers_check(Rest, JObj1);
-format_carriers_check([_|Rest], JObj) ->
-    format_carriers_check(Rest, JObj).
-
 %%--------------------------------------------------------------------
 %% @private
 %% @doc

core/kazoo_number_manager/src/carriers/knm_bandwidth.erl

@@ -17,6 +17,7 @@
 -export([disconnect_number/1]).
 -export([is_number_billable/1]).
 -export([should_lookup_cnam/0]).
+-export([check_numbers/1]).
 
 -include("knm.hrl").
 
@@ -76,6 +77,16 @@
 -spec is_local() -> boolean().
 is_local() -> 'false'.
 
+%%--------------------------------------------------------------------
+%% @public
+%% @doc
+%% Check with carrier if these numbers are registered with it.
+%% @end
+%%--------------------------------------------------------------------
+-spec check_numbers(ne_binaries()) -> {ok, kz_json:object()} |
+                                      {error, any()}.
+check_numbers(_Numbers) -> {error, not_implemented}.
+
 %%--------------------------------------------------------------------
 %% @public
 %% @doc

core/kazoo_number_manager/src/carriers/knm_bandwidth2.erl

@@ -20,6 +20,7 @@
 -export([disconnect_number/1]).
 -export([is_number_billable/1]).
 -export([should_lookup_cnam/0]).
+-export([check_numbers/1]).
 
 %% Maintenance commands
 -export([sites/0, peers/1]).
@@ -104,6 +105,16 @@ is_local() -> 'false'.
 -spec is_number_billable(knm_phone_number:knm_phone_number()) -> boolean().
 is_number_billable(_Number) -> 'true'.
 
+%%--------------------------------------------------------------------
+%% @public
+%% @doc
+%% Check with carrier if these numbers are registered with it.
+%% @end
+%%--------------------------------------------------------------------
+-spec check_numbers(ne_binaries()) -> {ok, kz_json:object()} |
+                                      {error, any()}.
+check_numbers(_Numbers) -> {error, not_implemented}.
+
 %%--------------------------------------------------------------------
 %% @public
 %% @doc

core/kazoo_number_manager/src/carriers/knm_carriers.erl

@@ -6,14 +6,15 @@
 %%% @end
 %%% @contributors
 %%%   Peter Defebvre
+%%%   Pierre Fenoll
 %%%-------------------------------------------------------------------
 -module(knm_carriers).
 
 -include_lib("kazoo_json/include/kazoo_json.hrl").
 -include("knm.hrl").
 
 -export([find/1, find/2
-        ,check/1, check/2
+        ,check/1
         ,available_carriers/1, all_modules/0
         ,default_carriers/0, default_carrier/0
         ,acquire/1
@@ -237,22 +238,37 @@ activation_charge(DID, AccountId) ->
 
 %%--------------------------------------------------------------------
 %% @public
-%% @doc Normalize then query the various providers for available numbers.
+%% @doc
+%% Normalize then query the various providers for available numbers.
+%% @end
 %%--------------------------------------------------------------------
--type checked_numbers() :: [{module(), {'ok', kz_json:object()} |
-                             {'error', any()} |
-                             {'EXIT', any()}
-                            }].
--spec check(ne_binaries()) -> checked_numbers().
--spec check(ne_binaries(), options()) -> checked_numbers().
-check(Numbers) -> check(Numbers, []).
-
-check(Numbers, Options) ->
-    FormattedNumbers = [knm_converters:normalize(Num) || Num <- Numbers],
-    lager:info("attempting to check ~p ", [FormattedNumbers]),
-    [{Module, catch(Module:check_numbers(FormattedNumbers, Options))}
-     || Module <- available_carriers(Options)
-    ].
+-spec check(ne_binaries()) -> kz_json:object().
+check(Numbers) ->
+    Nums = lists:usort([knm_converters:normalize(Num) || Num <- Numbers]),
+    lager:info("attempting to check ~p ", [Nums]),
+    {_, OKs, KOs} =
+        lists:foldl(fun check_fold/2, {Nums, #{}, #{}}, available_carriers([])),
+    kz_json:from_map(maps:merge(KOs, OKs)).
+
+check_fold(_, {[], _, _}=Acc) -> Acc;
+check_fold(Module, {Nums, OKs0, KOs0}) ->
+    {OKs, KOs} = check_numbers(Module, Nums),
+    OKNums = maps:keys(OKs0),
+    {Nums -- OKNums
+    ,maps:merge(OKs, OKs0)
+    ,maps:merge(maps:without(OKNums, KOs), KOs0)
+    }.
+
+check_numbers(Module, Nums) ->
+    lager:debug("checking ~p", [Module]),
+    try Module:check_numbers(Nums) of
+        {ok, JObj} -> {kz_json:to_map(JObj), #{}};
+        {error, _} -> {#{}, maps:from_list([{Num,<<"error">>} || Num <- Nums])}
+    catch
+        _:_ ->
+            kz_util:log_stacktrace(),
+            {#{}, maps:from_list([{Num,<<"error">>} || Num <- Nums])}
+    end.
 
 %%--------------------------------------------------------------------
 %% @public

core/kazoo_number_manager/src/carriers/knm_inum.erl

@@ -18,6 +18,7 @@
 -export([disconnect_number/1]).
 -export([is_number_billable/1]).
 -export([should_lookup_cnam/0]).
+-export([check_numbers/1]).
 
 -export([generate_numbers/3]).
 
@@ -36,6 +37,16 @@
 -spec is_local() -> boolean().
 is_local() -> 'true'.
 
+%%--------------------------------------------------------------------
+%% @public
+%% @doc
+%% Check with carrier if these numbers are registered with it.
+%% @end
+%%--------------------------------------------------------------------
+-spec check_numbers(ne_binaries()) -> {ok, kz_json:object()} |
+                                      {error, any()}.
+check_numbers(_Numbers) -> {error, not_implemented}.
+
 %%--------------------------------------------------------------------
 %% @public
 %% @doc

core/kazoo_number_manager/src/carriers/knm_local.erl

@@ -19,6 +19,7 @@
 -export([disconnect_number/1]).
 -export([is_number_billable/1]).
 -export([should_lookup_cnam/0]).
+-export([check_numbers/1]).
 
 -include("knm.hrl").
 
@@ -32,6 +33,16 @@
 -spec is_local() -> boolean().
 is_local() -> 'true'.
 
+%%--------------------------------------------------------------------
+%% @public
+%% @doc
+%% Check with carrier if these numbers are registered with it.
+%% @end
+%%--------------------------------------------------------------------
+-spec check_numbers(ne_binaries()) -> {ok, kz_json:object()} |
+                                      {error, any()}.
+check_numbers(_Numbers) -> {error, not_implemented}.
+
 %%--------------------------------------------------------------------
 %% @public
 %% @doc

core/kazoo_number_manager/src/carriers/knm_managed.erl

@@ -16,6 +16,7 @@
 -export([disconnect_number/1]).
 -export([is_number_billable/1]).
 -export([should_lookup_cnam/0]).
+-export([check_numbers/1]).
 
 -export([generate_numbers/3]).
 -export([import_numbers/2]).
@@ -35,6 +36,16 @@
 -spec is_local() -> boolean().
 is_local() -> 'true'.
 
+%%--------------------------------------------------------------------
+%% @public
+%% @doc
+%% Check with carrier if these numbers are registered with it.
+%% @end
+%%--------------------------------------------------------------------
+-spec check_numbers(ne_binaries()) -> {ok, kz_json:object()} |
+                                      {error, any()}.
+check_numbers(_Numbers) -> {error, not_implemented}.
+
 %%--------------------------------------------------------------------
 %% @public
 %% @doc

core/kazoo_number_manager/src/carriers/knm_mdn.erl

@@ -18,6 +18,7 @@
 -export([disconnect_number/1]).
 -export([is_number_billable/1]).
 -export([should_lookup_cnam/0]).
+-export([check_numbers/1]).
 
 -include("knm.hrl").
 
@@ -31,6 +32,16 @@
 -spec is_local() -> boolean().
 is_local() -> 'false'.
 
+%%--------------------------------------------------------------------
+%% @public
+%% @doc
+%% Check with carrier if these numbers are registered with it.
+%% @end
+%%--------------------------------------------------------------------
+-spec check_numbers(ne_binaries()) -> {ok, kz_json:object()} |
+                                      {error, any()}.
+check_numbers(_Numbers) -> {error, not_implemented}.
+
 %%--------------------------------------------------------------------
 %% @public
 %% @doc

core/kazoo_number_manager/src/carriers/knm_other.erl

@@ -14,11 +14,11 @@
 
 -export([is_local/0]).
 -export([find_numbers/3]).
--export([check_numbers/2]).
 -export([is_number_billable/1]).
 -export([acquire_number/1]).
 -export([disconnect_number/1]).
 -export([should_lookup_cnam/0]).
+-export([check_numbers/1]).
 
 -include("knm.hrl").
 
@@ -74,14 +74,12 @@ find_numbers(Prefix, Quantity, Options) ->
 %%--------------------------------------------------------------------
 %% @public
 %% @doc
-%% Query the local system for a quantity of available numbers
-%% in a rate center
+%% Check with carrier if these numbers are registered with it.
 %% @end
 %%--------------------------------------------------------------------
--spec check_numbers(ne_binaries(), knm_search:options()) ->
-                           {'ok', kz_json:object()} |
-                           {'error', any()}.
-check_numbers(Numbers, _Options) ->
+-spec check_numbers(ne_binaries()) -> {'ok', kz_json:object()} |
+                                      {'error', any()}.
+check_numbers(Numbers) ->
     FormatedNumbers = [knm_converters:to_npan(Number) || Number <- Numbers],
     case kapps_config:get(?KNM_OTHER_CONFIG_CAT, <<"phonebook_url">>) of
         'undefined' -> {'error', 'not_available'};

core/kazoo_number_manager/src/carriers/knm_reserved.erl

@@ -17,6 +17,7 @@
 -export([disconnect_number/1]).
 -export([is_number_billable/1]).
 -export([should_lookup_cnam/0]).
+-export([check_numbers/1]).
 
 -include("knm.hrl").
 
@@ -30,6 +31,16 @@
 -spec is_local() -> boolean().
 is_local() -> 'true'.
 
+%%--------------------------------------------------------------------
+%% @public
+%% @doc
+%% Check with carrier if these numbers are registered with it.
+%% @end
+%%--------------------------------------------------------------------
+-spec check_numbers(ne_binaries()) -> {ok, kz_json:object()} |
+                                      {error, any()}.
+check_numbers(_Numbers) -> {error, not_implemented}.
+
 %%--------------------------------------------------------------------
 %% @public
 %% @doc

core/kazoo_number_manager/src/carriers/knm_reserved_reseller.erl

@@ -17,6 +17,7 @@
 -export([disconnect_number/1]).
 -export([is_number_billable/1]).
 -export([should_lookup_cnam/0]).
+-export([check_numbers/1]).
 
 -include("knm.hrl").
 
@@ -30,6 +31,16 @@
 -spec is_local() -> boolean().
 is_local() -> 'true'.
 
+%%--------------------------------------------------------------------
+%% @public
+%% @doc
+%% Check with carrier if these numbers are registered with it.
+%% @end
+%%--------------------------------------------------------------------
+-spec check_numbers(ne_binaries()) -> {ok, kz_json:object()} |
+                                      {error, any()}.
+check_numbers(_Numbers) -> {error, not_implemented}.
+
 %%--------------------------------------------------------------------
 %% @public
 %% @doc