processone / ejabberd / 782

Committed 18 Jul 2024 09:55AM UTC coverage: 32.986% (+0.9%) from 32.123%

Build # 782

Build Type

push

github

Committed by

badlop

Commit Message

Set version to 24.07

Run Details

14533 of 44058 relevant lines covered (32.99%)

617.3 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

34.47

/src/mod_http_api.erl

%%%----------------------------------------------------------------------
%%% File    : mod_http_api.erl
%%% Author  : Christophe romain <christophe.romain@process-one.net>
%%% Purpose : Implements REST API for ejabberd using JSON data
%%% Created : 15 Sep 2014 by Christophe Romain <christophe.romain@process-one.net>
%%%
%%%
%%% ejabberd, Copyright (C) 2002-2024   ProcessOne
%%%
%%% This program is free software; you can redistribute it and/or
%%% modify it under the terms of the GNU General Public License as
%%% published by the Free Software Foundation; either version 2 of the
%%% License, or (at your option) any later version.
%%%
%%% This program is distributed in the hope that it will be useful,
%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%%% General Public License for more details.
%%%
%%% You should have received a copy of the GNU General Public License along
%%% with this program; if not, write to the Free Software Foundation, Inc.,
%%% 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
%%%
%%%----------------------------------------------------------------------

-module(mod_http_api).

-author('cromain@process-one.net').

-behaviour(gen_mod).

-export([start/2, stop/1, reload/3, process/2, depends/2,
         format_arg/2,
         mod_options/1, mod_doc/0]).

-include_lib("xmpp/include/xmpp.hrl").
-include("logger.hrl").
-include("ejabberd_http.hrl").
-include("ejabberd_stacktrace.hrl").
-include("translate.hrl").

-define(DEFAULT_API_VERSION, 1000000).

-define(CT_PLAIN,
        {<<"Content-Type">>, <<"text/plain">>}).

-define(CT_XML,
        {<<"Content-Type">>, <<"text/xml; charset=utf-8">>}).

-define(CT_JSON,
        {<<"Content-Type">>, <<"application/json">>}).

-define(AC_ALLOW_ORIGIN,
        {<<"Access-Control-Allow-Origin">>, <<"*">>}).

-define(AC_ALLOW_METHODS,
        {<<"Access-Control-Allow-Methods">>,
         <<"GET, POST, OPTIONS">>}).

-define(AC_ALLOW_HEADERS,
        {<<"Access-Control-Allow-Headers">>,
         <<"Content-Type, Authorization, X-Admin">>}).

-define(AC_MAX_AGE,
        {<<"Access-Control-Max-Age">>, <<"86400">>}).

-define(OPTIONS_HEADER,
        [?CT_PLAIN, ?AC_ALLOW_ORIGIN, ?AC_ALLOW_METHODS,
         ?AC_ALLOW_HEADERS, ?AC_MAX_AGE]).

-define(HEADER(CType),
        [CType, ?AC_ALLOW_ORIGIN, ?AC_ALLOW_HEADERS]).

%% -------------------
%% Module control
%% -------------------

start(_Host, _Opts) ->
    ok.

stop(_Host) ->
    ok.

reload(_Host, _NewOpts, _OldOpts) ->
    ok.

depends(_Host, _Opts) ->
    [].

%% ----------
%% basic auth
%% ----------

extract_auth(#request{auth = HTTPAuth, ip = {IP, _}, opts = Opts}) ->
    Info = case HTTPAuth of
               {SJID, Pass} ->
                   try jid:decode(SJID) of
                       #jid{luser = User, lserver = Server} ->
                           case ejabberd_auth:check_password(User, <<"">>, Server, Pass) of
                               true ->
                                   #{usr => {User, Server, <<"">>}, caller_server => Server};
                               false ->
                                   {error, invalid_auth}
                           end
                   catch _:{bad_jid, _} ->
                       {error, invalid_auth}
                   end;
               {oauth, Token, _} ->
                   case ejabberd_oauth:check_token(Token) of
                       {ok, {U, S}, Scope} ->
                           #{usr => {U, S, <<"">>}, oauth_scope => Scope, caller_server => S};
                       {false, Reason} ->
                           {error, Reason}
                   end;
               invalid ->
                   {error, invalid_auth};
               _ ->
                   #{}
           end,
    case Info of
        Map when is_map(Map) ->
            Tag = proplists:get_value(tag, Opts, <<>>),
            Map#{caller_module => ?MODULE, ip => IP, tag => Tag};
        _ ->
            ?DEBUG("Invalid auth data: ~p", [Info]),
            Info
    end.

%% ------------------
%% command processing
%% ------------------

%process(Call, Request) ->
%    ?DEBUG("~p~n~p", [Call, Request]), ok;
process(_, #request{method = 'POST', data = <<>>}) ->
    ?DEBUG("Bad Request: no data", []),
    badrequest_response(<<"Missing POST data">>);
process([Call | _], #request{method = 'POST', data = Data, ip = IPPort} = Req) ->
    Version = get_api_version(Req),
    try
        Args = extract_args(Data),
        log(Call, Args, IPPort),
        perform_call(Call, Args, Req, Version)
    catch
        %% TODO We need to refactor to remove redundant error return formatting
        throw:{error, unknown_command} ->
            json_format({404, 44, <<"Command not found.">>});
        _:{error,{_,invalid_json}} = _Err ->
            ?DEBUG("Bad Request: ~p", [_Err]),
            badrequest_response(<<"Invalid JSON input">>);
        ?EX_RULE(_Class, _Error, Stack) ->
            StackTrace = ?EX_STACK(Stack),
            ?DEBUG("Bad Request: ~p ~p", [_Error, StackTrace]),
            badrequest_response()
    end;
process([Call | _], #request{method = 'GET', q = Data, ip = {IP, _}} = Req) ->
    Version = get_api_version(Req),
    try
        Args = case Data of
                   [{nokey, <<>>}] -> [];
                   _ -> Data
               end,
        log(Call, Args, IP),
        perform_call(Call, Args, Req, Version)
    catch
        %% TODO We need to refactor to remove redundant error return formatting
        throw:{error, unknown_command} ->
            json_format({404, 44, <<"Command not found.">>});
        ?EX_RULE(_, _Error, Stack) ->
            StackTrace = ?EX_STACK(Stack),
            ?DEBUG("Bad Request: ~p ~p", [_Error, StackTrace]),
            badrequest_response()
    end;
process([_Call], #request{method = 'OPTIONS', data = <<>>}) ->
    {200, ?OPTIONS_HEADER, []};
process(_, #request{method = 'OPTIONS'}) ->
    {400, ?OPTIONS_HEADER, []};
process(_Path, Request) ->
    ?DEBUG("Bad Request: no handler ~p", [Request]),
    json_error(400, 40, <<"Missing command name.">>).

perform_call(Command, Args, Req, Version) ->
    case catch binary_to_existing_atom(Command, utf8) of
        Call when is_atom(Call) ->
            case extract_auth(Req) of
                {error, expired} -> invalid_token_response();
                {error, not_found} -> invalid_token_response();
                {error, invalid_auth} -> unauthorized_response();
                Auth when is_map(Auth) ->
                    Result = handle(Call, Auth, Args, Version),
                    json_format(Result)
            end;
        _ ->
            json_error(404, 40, <<"Endpoint not found.">>)
    end.

%% Be tolerant to make API more easily usable from command-line pipe.
extract_args(<<"\n">>) -> [];
extract_args(Data) ->
    Maps = misc:json_decode(Data),
    maps:to_list(Maps).

% get API version N from last "vN" element in URL path
get_api_version(#request{path = Path}) ->
    get_api_version(lists:reverse(Path));
get_api_version([<<"v", String/binary>> | Tail]) ->
    case catch binary_to_integer(String) of
        N when is_integer(N) ->
            N;
        _ ->
            get_api_version(Tail)
    end;
get_api_version([_Head | Tail]) ->
    get_api_version(Tail);
get_api_version([]) ->
    ?DEFAULT_API_VERSION.

%% ----------------
%% command handlers
%% ----------------

%% TODO Check accept types of request before decided format of reply.

% generic ejabberd command handler
handle(Call, Auth, Args, Version) when is_atom(Call), is_list(Args) ->
    Args2 = [{misc:binary_to_atom(Key), Value} || {Key, Value} <- Args],
    try handle2(Call, Auth, Args2, Version)
    catch throw:not_found ->
            {404, <<"not_found">>};
          throw:{not_found, Why} when is_atom(Why) ->
            {404, misc:atom_to_binary(Why)};
          throw:{not_found, Msg} ->
            {404, iolist_to_binary(Msg)};
          throw:not_allowed ->
            {401, <<"not_allowed">>};
          throw:{not_allowed, Why} when is_atom(Why) ->
            {401, misc:atom_to_binary(Why)};
          throw:{not_allowed, Msg} ->
            {401, iolist_to_binary(Msg)};
          throw:{error, account_unprivileged} ->
            {403, 31, <<"Command need to be run with admin privilege.">>};
          throw:{error, access_rules_unauthorized} ->
            {403, 32, <<"AccessRules: Account does not have the right to perform the operation.">>};
          throw:{invalid_parameter, Msg} ->
            {400, iolist_to_binary(Msg)};
          throw:{error, Why} when is_atom(Why) ->
            {400, misc:atom_to_binary(Why)};
          throw:{error, Msg} ->
            {400, iolist_to_binary(Msg)};
          throw:Error when is_atom(Error) ->
            {400, misc:atom_to_binary(Error)};
          throw:Msg when is_list(Msg); is_binary(Msg) ->
            {400, iolist_to_binary(Msg)};
          ?EX_RULE(Class, Error, Stack) ->
            StackTrace = ?EX_STACK(Stack),
            ?ERROR_MSG("REST API Error: "
                       "~ts(~p) -> ~p:~p ~p",
                       [Call, hide_sensitive_args(Args),
                        Class, Error, StackTrace]),
            {500, <<"internal_error">>}
    end.

handle2(Call, Auth, Args, Version) when is_atom(Call), is_list(Args) ->
    {ArgsF, ArgsR, _ResultF} = ejabberd_commands:get_command_format(Call, Auth, Version),
    ArgsFormatted = format_args(Call, rename_old_args(Args, ArgsR), ArgsF),
    case ejabberd_commands:execute_command2(Call, ArgsFormatted, Auth, Version) of
        {error, Error} ->
            throw(Error);
        Res ->
            format_command_result(Call, Auth, Res, Version)
    end.

rename_old_args(Args, []) ->
    Args;
rename_old_args(Args, [{OldName, NewName} | ArgsR]) ->
    Args2 = case lists:keytake(OldName, 1, Args) of
        {value, {OldName, Value}, ArgsTail} ->
            [{NewName, Value} | ArgsTail];
        false ->
            Args
    end,
    rename_old_args(Args2, ArgsR).

get_elem_delete(Call, A, L, F) ->
    case proplists:get_all_values(A, L) of
      [Value] -> {Value, proplists:delete(A, L)};
      [_, _ | _] ->
          ?INFO_MSG("Command ~ts call rejected, it has duplicate attribute ~w",
                    [Call, A]),
          throw({invalid_parameter,
                 io_lib:format("Request have duplicate argument: ~w", [A])});
      [] ->
          case F of
              {list, _} ->
                  {[], L};
              _ ->
                  ?INFO_MSG("Command ~ts call rejected, missing attribute ~w",
                            [Call, A]),
                  throw({invalid_parameter,
                         io_lib:format("Request have missing argument: ~w", [A])})
          end
    end.

format_args(Call, Args, ArgsFormat) ->
    {ArgsRemaining, R} = lists:foldl(fun ({ArgName,
                                           ArgFormat},
                                          {Args1, Res}) ->
                                             {ArgValue, Args2} =
                                                 get_elem_delete(Call, ArgName,
                                                                 Args1, ArgFormat),
                                             Formatted = format_arg(ArgValue,
                                                                    ArgFormat),
                                             {Args2, Res ++ [Formatted]}
                                     end,
                                     {Args, []}, ArgsFormat),
    case ArgsRemaining of
      [] -> R;
      L when is_list(L) ->
          ExtraArgs = [N || {N, _} <- L],
          ?INFO_MSG("Command ~ts call rejected, it has unknown arguments ~w",
              [Call, ExtraArgs]),
          throw({invalid_parameter,
                 io_lib:format("Request have unknown arguments: ~w", [ExtraArgs])})
    end.

format_arg({Elements},
           {list, {_ElementDefName, {tuple, [{_Tuple1N, Tuple1S}, {_Tuple2N, Tuple2S}]} = Tuple}})
    when is_list(Elements) andalso
         (Tuple1S == binary orelse Tuple1S == string) ->
    lists:map(fun({F1, F2}) ->
                      {format_arg(F1, Tuple1S), format_arg(F2, Tuple2S)};
                 ({Val}) when is_list(Val) ->
                      format_arg({Val}, Tuple)
              end, Elements);
format_arg(Map,
           {list, {_ElementDefName, {tuple, [{_Tuple1N, Tuple1S}, {_Tuple2N, Tuple2S}]}}})
    when is_map(Map) andalso
         (Tuple1S == binary orelse Tuple1S == string) ->
    maps:fold(
        fun(K, V, Acc) ->
            [{format_arg(K, Tuple1S), format_arg(V, Tuple2S)} | Acc]
        end, [], Map);
format_arg(Elements,
           {list, {_ElementDefName, {list, _} = ElementDefFormat}})
    when is_list(Elements) ->
    [{format_arg(Element, ElementDefFormat)}
     || Element <- Elements];

%% Covered by command_test_list and command_test_list_tuple
format_arg(Elements,
           {list, {_ElementDefName, ElementDefFormat}})
    when is_list(Elements) ->
    [format_arg(Element, ElementDefFormat)
     || Element <- Elements];

format_arg({[{Name, Value}]},
           {tuple, [{_Tuple1N, Tuple1S}, {_Tuple2N, Tuple2S}]})
  when Tuple1S == binary;
       Tuple1S == string ->
    {format_arg(Name, Tuple1S), format_arg(Value, Tuple2S)};

%% Covered by command_test_tuple and command_test_list_tuple
format_arg(Elements,
           {tuple, ElementsDef})
  when is_map(Elements) ->
    list_to_tuple([element(2, maps:find(atom_to_binary(Name, latin1), Elements))
                   || {Name, _Format} <- ElementsDef]);

format_arg({Elements},
           {tuple, ElementsDef})
    when is_list(Elements) ->
    F = lists:map(fun({TElName, TElDef}) ->
                          case lists:keyfind(atom_to_binary(TElName, latin1), 1, Elements) of
                              {_, Value} ->
                                  format_arg(Value, TElDef);
                              _ when TElDef == binary; TElDef == string ->
                                  <<"">>;
                              _ ->
                                  ?ERROR_MSG("Missing field ~p in tuple ~p", [TElName, Elements]),
                                  throw({invalid_parameter,
                                         io_lib:format("Missing field ~w in tuple ~w", [TElName, Elements])})
                          end
                  end, ElementsDef),
    list_to_tuple(F);

format_arg(Elements, {list, ElementsDef})
    when is_list(Elements) and is_atom(ElementsDef) ->
    [format_arg(Element, ElementsDef)
     || Element <- Elements];

format_arg(Arg, integer) when is_integer(Arg) -> Arg;
format_arg(Arg, binary) when is_list(Arg) -> process_unicode_codepoints(Arg);
format_arg(Arg, binary) when is_binary(Arg) -> Arg;
format_arg(Arg, string) when is_list(Arg) -> Arg;
format_arg(Arg, string) when is_binary(Arg) -> binary_to_list(Arg);
format_arg(undefined, binary) -> <<>>;
format_arg(undefined, string) -> "";
format_arg(Arg, Format) ->
    ?ERROR_MSG("Don't know how to format Arg ~p for format ~p", [Arg, Format]),
    throw({invalid_parameter,
           io_lib:format("Arg ~w is not in format ~w",
                         [Arg, Format])}).

process_unicode_codepoints(Str) ->
    iolist_to_binary(lists:map(fun(X) when X > 255 -> unicode:characters_to_binary([X]);
                                  (Y) -> Y
                               end, Str)).

%% ----------------
%% internal helpers
%% ----------------

format_command_result(Cmd, Auth, Result, Version) ->
    {_, _, ResultFormat} = ejabberd_commands:get_command_format(Cmd, Auth, Version),
    case {ResultFormat, Result} of
        {{_, rescode}, V} when V == true; V == ok ->
            {200, 0};
        {{_, rescode}, _} ->
            {200, 1};
        {_, {error, ErrorAtom, Code, Msg}} ->
            format_error_result(ErrorAtom, Code, Msg);
        {{_, restuple}, {V, Text}} when V == true; V == ok ->
            {200, iolist_to_binary(Text)};
        {{_, restuple}, {ErrorAtom, Msg}} ->
            format_error_result(ErrorAtom, 0, Msg);
        {{_, {list, _}}, _V} ->
            {_, L} = format_result(Result, ResultFormat),
            {200, L};
        {{_, {tuple, _}}, _V} ->
            {_, T} = format_result(Result, ResultFormat),
            {200, T};
        _ ->
            OtherResult1 = format_result(Result, ResultFormat),
            OtherResult2 = case Version of
                               0 ->
                                   {[OtherResult1]};
                               _ ->
                                   {_, Other3} = OtherResult1,
                                   Other3
                           end,
            {200, OtherResult2}
    end.

format_result(Atom, {Name, atom}) ->
    {misc:atom_to_binary(Name), misc:atom_to_binary(Atom)};

format_result(Int, {Name, integer}) ->
    {misc:atom_to_binary(Name), Int};

format_result([String | _] = StringList, {Name, string}) when is_list(String) ->
    Binarized = iolist_to_binary(string:join(StringList, "\n")),
    {misc:atom_to_binary(Name), Binarized};

format_result(String, {Name, string}) ->
    {misc:atom_to_binary(Name), iolist_to_binary(String)};

format_result(Code, {Name, rescode}) ->
    {misc:atom_to_binary(Name), Code == true orelse Code == ok};

format_result({Code, Text}, {Name, restuple}) ->
    {misc:atom_to_binary(Name),
     {[{<<"res">>, Code == true orelse Code == ok},
       {<<"text">>, iolist_to_binary(Text)}]}};

format_result(Code, {Name, restuple}) ->
    {misc:atom_to_binary(Name),
     {[{<<"res">>, Code == true orelse Code == ok},
       {<<"text">>, <<"">>}]}};

format_result(Els, {Name, {list, {_, {tuple, [{_, atom}, _]}} = Fmt}}) ->
    {misc:atom_to_binary(Name), {[format_result(El, Fmt) || El <- Els]}};

format_result(Els, {Name, {list, {_, {tuple, [{name, string}, {value, _}]}} = Fmt}}) ->
    {misc:atom_to_binary(Name), {[format_result(El, Fmt) || El <- Els]}};

%% Covered by command_test_list and command_test_list_tuple
format_result(Els, {Name, {list, Def}}) ->
    {misc:atom_to_binary(Name), [element(2, format_result(El, Def)) || El <- Els]};

format_result(Tuple, {_Name, {tuple, [{_, atom}, ValFmt]}}) ->
    {Name2, Val} = Tuple,
    {_, Val2} = format_result(Val, ValFmt),
    {misc:atom_to_binary(Name2), Val2};

format_result(Tuple, {_Name, {tuple, [{name, string}, {value, _} = ValFmt]}}) ->
    {Name2, Val} = Tuple,
    {_, Val2} = format_result(Val, ValFmt),
    {iolist_to_binary(Name2), Val2};

%% Covered by command_test_tuple and command_test_list_tuple
format_result(Tuple, {Name, {tuple, Def}}) ->
    Els = lists:zip(tuple_to_list(Tuple), Def),
    Els2 = [format_result(El, ElDef) || {El, ElDef} <- Els],
    {misc:atom_to_binary(Name), maps:from_list(Els2)};

format_result(404, {_Name, _}) ->
    "not_found".


format_error_result(conflict, Code, Msg) ->
    {409, Code, iolist_to_binary(Msg)};
format_error_result(not_exists, Code, Msg) ->
    {404, Code, iolist_to_binary(Msg)};
format_error_result(_ErrorAtom, Code, Msg) ->
    {500, Code, iolist_to_binary(Msg)}.

unauthorized_response() ->
    json_error(401, 10, <<"You are not authorized to call this command.">>).

invalid_token_response() ->
    json_error(401, 10, <<"Oauth Token is invalid or expired.">>).

%% outofscope_response() ->
%%     json_error(401, 11, <<"Token does not grant usage to command required scope.">>).

badrequest_response() ->
    badrequest_response(<<"400 Bad Request">>).
badrequest_response(Body) ->
    json_response(400, misc:json_encode(Body)).

json_format({Code, Result}) ->
    json_response(Code, misc:json_encode(Result));
json_format({HTMLCode, JSONErrorCode, Message}) ->
    json_error(HTMLCode, JSONErrorCode, Message).

json_response(Code, Body) when is_integer(Code) ->
    {Code, ?HEADER(?CT_JSON), Body}.

%% HTTPCode, JSONCode = integers
%% message is binary
json_error(HTTPCode, JSONCode, Message) ->
    {HTTPCode, ?HEADER(?CT_JSON),
     misc:json_encode(#{<<"status">> => <<"error">>,
                    <<"code">> =>  JSONCode,
                    <<"message">> => Message})
    }.

log(Call, Args, {Addr, Port}) ->
    AddrS = misc:ip_to_list({Addr, Port}),
    ?INFO_MSG("API call ~ts ~p from ~ts:~p", [Call, hide_sensitive_args(Args), AddrS, Port]);
log(Call, Args, IP) ->
    ?INFO_MSG("API call ~ts ~p (~p)", [Call, hide_sensitive_args(Args), IP]).

hide_sensitive_args(Args=[_H|_T]) ->
    lists:map( fun({<<"password">>, Password}) -> {<<"password">>, ejabberd_config:may_hide_data(Password)};
         ({<<"newpass">>,NewPassword}) -> {<<"newpass">>, ejabberd_config:may_hide_data(NewPassword)};
         (E) -> E end,
         Args);
hide_sensitive_args(NonListArgs) ->
    NonListArgs.

mod_options(_) ->
    [].

mod_doc() ->
    #{desc =>
          [?T("This module provides a ReST interface to call "
              "_`../../developer/ejabberd-api/index.md|ejabberd API`_ "
              "commands using JSON data."), "",
           ?T("To use this module, in addition to adding it to the 'modules' "
              "section, you must also enable it in 'listen' -> 'ejabberd_http' -> "
              "_`listen-options.md#request_handlers|request_handlers`_."), "",
           ?T("To use a specific API version N, when defining the URL path "
              "in the request_handlers, add a 'vN'. "
              "For example: '/api/v2: mod_http_api'"), "",
           ?T("To run a command, send a POST request to the corresponding "
              "URL: 'http://localhost:5280/api/<command_name>'")],
     example =>
         ["listen:",
          "  -",
          "    port: 5280",
          "    module: ejabberd_http",
          "    request_handlers:",
          "      /api: mod_http_api",
          "",
          "modules:",
          "  mod_http_api: {}"]}.

1	%%%----------------------------------------------------------------------
2	%%% File : mod_http_api.erl
3	%%% Author : Christophe romain <christophe.romain@process-one.net>
4	%%% Purpose : Implements REST API for ejabberd using JSON data
5	%%% Created : 15 Sep 2014 by Christophe Romain <christophe.romain@process-one.net>
6	%%%
7	%%%
8	%%% ejabberd, Copyright (C) 2002-2024 ProcessOne
9	%%%
10	%%% This program is free software; you can redistribute it and/or
11	%%% modify it under the terms of the GNU General Public License as
12	%%% published by the Free Software Foundation; either version 2 of the
13	%%% License, or (at your option) any later version.
14	%%%
15	%%% This program is distributed in the hope that it will be useful,
16	%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
17	%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18	%%% General Public License for more details.
19	%%%
20	%%% You should have received a copy of the GNU General Public License along
21	%%% with this program; if not, write to the Free Software Foundation, Inc.,
22	%%% 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
23	%%%
24	%%%----------------------------------------------------------------------
25
26	-module(mod_http_api).
27
28	-author('cromain@process-one.net').
29
30	-behaviour(gen_mod).
31
32	-export([start/2, stop/1, reload/3, process/2, depends/2,
33	format_arg/2,
34	mod_options/1, mod_doc/0]).
35
36	-include_lib("xmpp/include/xmpp.hrl").
37	-include("logger.hrl").
38	-include("ejabberd_http.hrl").
39	-include("ejabberd_stacktrace.hrl").
40	-include("translate.hrl").
41
42	-define(DEFAULT_API_VERSION, 1000000).
43
44	-define(CT_PLAIN,
45	{<<"Content-Type">>, <<"text/plain">>}).
46
47	-define(CT_XML,
48	{<<"Content-Type">>, <<"text/xml; charset=utf-8">>}).
49
50	-define(CT_JSON,
51	{<<"Content-Type">>, <<"application/json">>}).
52
53	-define(AC_ALLOW_ORIGIN,
54	{<<"Access-Control-Allow-Origin">>, <<"*">>}).
55
56	-define(AC_ALLOW_METHODS,
57	{<<"Access-Control-Allow-Methods">>,
58	<<"GET, POST, OPTIONS">>}).
59
60	-define(AC_ALLOW_HEADERS,
61	{<<"Access-Control-Allow-Headers">>,
62	<<"Content-Type, Authorization, X-Admin">>}).
63
64	-define(AC_MAX_AGE,
65	{<<"Access-Control-Max-Age">>, <<"86400">>}).
66
67	-define(OPTIONS_HEADER,
68	[?CT_PLAIN, ?AC_ALLOW_ORIGIN, ?AC_ALLOW_METHODS,
69	?AC_ALLOW_HEADERS, ?AC_MAX_AGE]).
70
71	-define(HEADER(CType),
72	[CType, ?AC_ALLOW_ORIGIN, ?AC_ALLOW_HEADERS]).
73
74	%% -------------------
75	%% Module control
76	%% -------------------
77
78	start(_Host, _Opts) ->
79	ok.	×
80
81	stop(_Host) ->
82	ok.	×
83
84	reload(_Host, _NewOpts, _OldOpts) ->
85	ok.	×
86
87	depends(_Host, _Opts) ->
88	[].	×
89
90	%% ----------
91	%% basic auth
92	%% ----------
93
94	extract_auth(#request{auth = HTTPAuth, ip = {IP, _}, opts = Opts}) ->
95	Info = case HTTPAuth of	26✔
96	{SJID, Pass} ->
97	try jid:decode(SJID) of	×
98	#jid{luser = User, lserver = Server} ->
99	case ejabberd_auth:check_password(User, <<"">>, Server, Pass) of	×
100	true ->
101	#{usr => {User, Server, <<"">>}, caller_server => Server};	×
102	false ->
103	{error, invalid_auth}	×
104	end
105	catch _:{bad_jid, _} ->
106	{error, invalid_auth}	×
107	end;
108	{oauth, Token, _} ->
109	case ejabberd_oauth:check_token(Token) of	×
110	{ok, {U, S}, Scope} ->
111	#{usr => {U, S, <<"">>}, oauth_scope => Scope, caller_server => S};	×
112	{false, Reason} ->
113	{error, Reason}	×
114	end;
115	invalid ->
116	{error, invalid_auth};	×
117	_ ->
118	#{}	26✔
119	end,
120	case Info of	26✔
121	Map when is_map(Map) ->
122	Tag = proplists:get_value(tag, Opts, <<>>),	26✔
123	Map#{caller_module => ?MODULE, ip => IP, tag => Tag};	26✔
124	_ ->
125	?DEBUG("Invalid auth data: ~p", [Info]),	×
126	Info	×
127	end.
128
129	%% ------------------
130	%% command processing
131	%% ------------------
132
133	%process(Call, Request) ->
134	% ?DEBUG("~p~n~p", [Call, Request]), ok;
135	process(_, #request{method = 'POST', data = <<>>}) ->
136	?DEBUG("Bad Request: no data", []),	×
137	badrequest_response(<<"Missing POST data">>);	×
138	process([Call \| _], #request{method = 'POST', data = Data, ip = IPPort} = Req) ->
139	Version = get_api_version(Req),	26✔
140	try	26✔
141	Args = extract_args(Data),	26✔
142	log(Call, Args, IPPort),	26✔
143	perform_call(Call, Args, Req, Version)	26✔
144	catch
145	%% TODO We need to refactor to remove redundant error return formatting
146	throw:{error, unknown_command} ->
147	json_format({404, 44, <<"Command not found.">>});	×
148	_:{error,{_,invalid_json}} = _Err ->
149	?DEBUG("Bad Request: ~p", [_Err]),	×
150	badrequest_response(<<"Invalid JSON input">>);	×
151	?EX_RULE(_Class, _Error, Stack) ->
152	StackTrace = ?EX_STACK(Stack),	×
153	?DEBUG("Bad Request: ~p ~p", [_Error, StackTrace]),	×
154	badrequest_response()	×
155	end;
156	process([Call \| _], #request{method = 'GET', q = Data, ip = {IP, _}} = Req) ->
157	Version = get_api_version(Req),	×
158	try	×
159	Args = case Data of	×
160	[{nokey, <<>>}] -> [];	×
161	_ -> Data	×
162	end,
163	log(Call, Args, IP),	×
164	perform_call(Call, Args, Req, Version)	×
165	catch
166	%% TODO We need to refactor to remove redundant error return formatting
167	throw:{error, unknown_command} ->
168	json_format({404, 44, <<"Command not found.">>});	×
169	?EX_RULE(_, _Error, Stack) ->
170	StackTrace = ?EX_STACK(Stack),	×
171	?DEBUG("Bad Request: ~p ~p", [_Error, StackTrace]),	×
172	badrequest_response()	×
173	end;
174	process([_Call], #request{method = 'OPTIONS', data = <<>>}) ->
175	{200, ?OPTIONS_HEADER, []};	×
176	process(_, #request{method = 'OPTIONS'}) ->
177	{400, ?OPTIONS_HEADER, []};	×
178	process(_Path, Request) ->
179	?DEBUG("Bad Request: no handler ~p", [Request]),	×
180	json_error(400, 40, <<"Missing command name.">>).	×
181
182	perform_call(Command, Args, Req, Version) ->
183	case catch binary_to_existing_atom(Command, utf8) of	26✔
184	Call when is_atom(Call) ->
185	case extract_auth(Req) of	26✔
186	{error, expired} -> invalid_token_response();	×
187	{error, not_found} -> invalid_token_response();	×
188	{error, invalid_auth} -> unauthorized_response();	×
189	Auth when is_map(Auth) ->
190	Result = handle(Call, Auth, Args, Version),	26✔
191	json_format(Result)	26✔
192	end;
193	_ ->
194	json_error(404, 40, <<"Endpoint not found.">>)	×
195	end.
196
197	%% Be tolerant to make API more easily usable from command-line pipe.
198	extract_args(<<"\n">>) -> [];	×
199	extract_args(Data) ->
200	Maps = misc:json_decode(Data),	26✔
201	maps:to_list(Maps).	26✔
202
203	% get API version N from last "vN" element in URL path
204	get_api_version(#request{path = Path}) ->
205	get_api_version(lists:reverse(Path));	26✔
206	get_api_version([<<"v", String/binary>> \| Tail]) ->
207	case catch binary_to_integer(String) of	×
208	N when is_integer(N) ->
209	N;	×
210	_ ->
211	get_api_version(Tail)	×
212	end;
213	get_api_version([_Head \| Tail]) ->
214	get_api_version(Tail);	52✔
215	get_api_version([]) ->
216	?DEFAULT_API_VERSION.	26✔
217
218	%% ----------------
219	%% command handlers
220	%% ----------------
221
222	%% TODO Check accept types of request before decided format of reply.
223
224	% generic ejabberd command handler
225	handle(Call, Auth, Args, Version) when is_atom(Call), is_list(Args) ->
226	Args2 = [{misc:binary_to_atom(Key), Value} \|\| {Key, Value} <- Args],	26✔
227	try handle2(Call, Auth, Args2, Version)	26✔
228	catch throw:not_found ->
229	{404, <<"not_found">>};	×
230	throw:{not_found, Why} when is_atom(Why) ->
231	{404, misc:atom_to_binary(Why)};	×
232	throw:{not_found, Msg} ->
233	{404, iolist_to_binary(Msg)};	×
234	throw:not_allowed ->
235	{401, <<"not_allowed">>};	×
236	throw:{not_allowed, Why} when is_atom(Why) ->
237	{401, misc:atom_to_binary(Why)};	×
238	throw:{not_allowed, Msg} ->
239	{401, iolist_to_binary(Msg)};	×
240	throw:{error, account_unprivileged} ->
241	{403, 31, <<"Command need to be run with admin privilege.">>};	×
242	throw:{error, access_rules_unauthorized} ->
243	{403, 32, <<"AccessRules: Account does not have the right to perform the operation.">>};	×
244	throw:{invalid_parameter, Msg} ->
245	{400, iolist_to_binary(Msg)};	×
246	throw:{error, Why} when is_atom(Why) ->
247	{400, misc:atom_to_binary(Why)};	×
248	throw:{error, Msg} ->
249	{400, iolist_to_binary(Msg)};	×
250	throw:Error when is_atom(Error) ->
251	{400, misc:atom_to_binary(Error)};	×
252	throw:Msg when is_list(Msg); is_binary(Msg) ->
253	{400, iolist_to_binary(Msg)};	×
254	?EX_RULE(Class, Error, Stack) ->
255	StackTrace = ?EX_STACK(Stack),	×
256	?ERROR_MSG("REST API Error: "	×
257	"~ts(~p) -> ~p:~p ~p",
258	[Call, hide_sensitive_args(Args),
259	Class, Error, StackTrace]),	×
260	{500, <<"internal_error">>}	×
261	end.
262
263	handle2(Call, Auth, Args, Version) when is_atom(Call), is_list(Args) ->
264	{ArgsF, ArgsR, _ResultF} = ejabberd_commands:get_command_format(Call, Auth, Version),	26✔
265	ArgsFormatted = format_args(Call, rename_old_args(Args, ArgsR), ArgsF),	26✔
266	case ejabberd_commands:execute_command2(Call, ArgsFormatted, Auth, Version) of	26✔
267	{error, Error} ->
268	throw(Error);	×
269	Res ->
270	format_command_result(Call, Auth, Res, Version)	26✔
271	end.
272
273	rename_old_args(Args, []) ->
274	Args;	26✔
275	rename_old_args(Args, [{OldName, NewName} \| ArgsR]) ->
276	Args2 = case lists:keytake(OldName, 1, Args) of	×
277	{value, {OldName, Value}, ArgsTail} ->
278	[{NewName, Value} \| ArgsTail];	×
279	false ->
280	Args	×
281	end,
282	rename_old_args(Args2, ArgsR).	×
283
284	get_elem_delete(Call, A, L, F) ->
285	case proplists:get_all_values(A, L) of	46✔
286	[Value] -> {Value, proplists:delete(A, L)};	46✔
287	[_, _ \| _] ->
288	?INFO_MSG("Command ~ts call rejected, it has duplicate attribute ~w",	×
289	[Call, A]),	×
290	throw({invalid_parameter,	×
291	io_lib:format("Request have duplicate argument: ~w", [A])});
292	[] ->
293	case F of	×
294	{list, _} ->
295	{[], L};	×
296	_ ->
297	?INFO_MSG("Command ~ts call rejected, missing attribute ~w",	×
298	[Call, A]),	×
299	throw({invalid_parameter,	×
300	io_lib:format("Request have missing argument: ~w", [A])})
301	end
302	end.
303
304	format_args(Call, Args, ArgsFormat) ->
305	{ArgsRemaining, R} = lists:foldl(fun ({ArgName,	26✔
306	ArgFormat},
307	{Args1, Res}) ->
308	{ArgValue, Args2} =	46✔
309	get_elem_delete(Call, ArgName,
310	Args1, ArgFormat),
311	Formatted = format_arg(ArgValue,	46✔
312	ArgFormat),
313	{Args2, Res ++ [Formatted]}	46✔
314	end,
315	{Args, []}, ArgsFormat),
316	case ArgsRemaining of	26✔
317	[] -> R;	26✔
318	L when is_list(L) ->
319	ExtraArgs = [N \|\| {N, _} <- L],	×
320	?INFO_MSG("Command ~ts call rejected, it has unknown arguments ~w",	×
321	[Call, ExtraArgs]),	×
322	throw({invalid_parameter,	×
323	io_lib:format("Request have unknown arguments: ~w", [ExtraArgs])})
324	end.
325
326	format_arg({Elements},
327	{list, {_ElementDefName, {tuple, [{_Tuple1N, Tuple1S}, {_Tuple2N, Tuple2S}]} = Tuple}})
328	when is_list(Elements) andalso
329	(Tuple1S == binary orelse Tuple1S == string) ->
330	lists:map(fun({F1, F2}) ->	×
331	{format_arg(F1, Tuple1S), format_arg(F2, Tuple2S)};	×
332	({Val}) when is_list(Val) ->
333	format_arg({Val}, Tuple)	×
334	end, Elements);
335	format_arg(Map,
336	{list, {_ElementDefName, {tuple, [{_Tuple1N, Tuple1S}, {_Tuple2N, Tuple2S}]}}})
337	when is_map(Map) andalso
338	(Tuple1S == binary orelse Tuple1S == string) ->
339	maps:fold(	1✔
340	fun(K, V, Acc) ->
341	[{format_arg(K, Tuple1S), format_arg(V, Tuple2S)} \| Acc]	3✔
342	end, [], Map);
343	format_arg(Elements,
344	{list, {_ElementDefName, {list, _} = ElementDefFormat}})
345	when is_list(Elements) ->
346	[{format_arg(Element, ElementDefFormat)}	×
347	\|\| Element <- Elements];	×
348
349	%% Covered by command_test_list and command_test_list_tuple
350	format_arg(Elements,
351	{list, {_ElementDefName, ElementDefFormat}})
352	when is_list(Elements) ->
353	[format_arg(Element, ElementDefFormat)	4✔
354	\|\| Element <- Elements];	4✔
355
356	format_arg({[{Name, Value}]},
357	{tuple, [{_Tuple1N, Tuple1S}, {_Tuple2N, Tuple2S}]})
358	when Tuple1S == binary;
359	Tuple1S == string ->
360	{format_arg(Name, Tuple1S), format_arg(Value, Tuple2S)};	×
361
362	%% Covered by command_test_tuple and command_test_list_tuple
363	format_arg(Elements,
364	{tuple, ElementsDef})
365	when is_map(Elements) ->
366	list_to_tuple([element(2, maps:find(atom_to_binary(Name, latin1), Elements))	8✔
367	\|\| {Name, _Format} <- ElementsDef]);	8✔
368
369	format_arg({Elements},
370	{tuple, ElementsDef})
371	when is_list(Elements) ->
372	F = lists:map(fun({TElName, TElDef}) ->	×
373	case lists:keyfind(atom_to_binary(TElName, latin1), 1, Elements) of	×
374	{_, Value} ->
375	format_arg(Value, TElDef);	×
376	_ when TElDef == binary; TElDef == string ->
377	<<"">>;	×
378	_ ->
379	?ERROR_MSG("Missing field ~p in tuple ~p", [TElName, Elements]),	×
380	throw({invalid_parameter,	×
381	io_lib:format("Missing field ~w in tuple ~w", [TElName, Elements])})
382	end
383	end, ElementsDef),
384	list_to_tuple(F);	×
385
386	format_arg(Elements, {list, ElementsDef})
387	when is_list(Elements) and is_atom(ElementsDef) ->
388	[format_arg(Element, ElementsDef)	×
389	\|\| Element <- Elements];	×
390
391	format_arg(Arg, integer) when is_integer(Arg) -> Arg;	2✔
392	format_arg(Arg, binary) when is_list(Arg) -> process_unicode_codepoints(Arg);	×
393	format_arg(Arg, binary) when is_binary(Arg) -> Arg;	25✔
394	format_arg(Arg, string) when is_list(Arg) -> Arg;	13✔
395	format_arg(Arg, string) when is_binary(Arg) -> binary_to_list(Arg);	11✔
396	format_arg(undefined, binary) -> <<>>;	×
397	format_arg(undefined, string) -> "";	×
398	format_arg(Arg, Format) ->
399	?ERROR_MSG("Don't know how to format Arg ~p for format ~p", [Arg, Format]),	×
400	throw({invalid_parameter,	×
401	io_lib:format("Arg ~w is not in format ~w",
402	[Arg, Format])}).
403
404	process_unicode_codepoints(Str) ->
405	iolist_to_binary(lists:map(fun(X) when X > 255 -> unicode:characters_to_binary([X]);	×
406	(Y) -> Y	×
407	end, Str)).
408
409	%% ----------------
410	%% internal helpers
411	%% ----------------
412
413	format_command_result(Cmd, Auth, Result, Version) ->
414	{_, _, ResultFormat} = ejabberd_commands:get_command_format(Cmd, Auth, Version),	26✔
415	case {ResultFormat, Result} of	26✔
416	{{_, rescode}, V} when V == true; V == ok ->
417	{200, 0};	8✔
418	{{_, rescode}, _} ->
419	{200, 1};	2✔
420	{_, {error, ErrorAtom, Code, Msg}} ->
421	format_error_result(ErrorAtom, Code, Msg);	×
422	{{_, restuple}, {V, Text}} when V == true; V == ok ->
423	{200, iolist_to_binary(Text)};	3✔
424	{{_, restuple}, {ErrorAtom, Msg}} ->
425	format_error_result(ErrorAtom, 0, Msg);	×
426	{{_, {list, _}}, _V} ->
427	{_, L} = format_result(Result, ResultFormat),	5✔
428	{200, L};	5✔
429	{{_, {tuple, _}}, _V} ->
430	{_, T} = format_result(Result, ResultFormat),	2✔
431	{200, T};	2✔
432	_ ->
433	OtherResult1 = format_result(Result, ResultFormat),	6✔
434	OtherResult2 = case Version of	6✔
435	0 ->
436	{[OtherResult1]};	×
437	_ ->
438	{_, Other3} = OtherResult1,	6✔
439	Other3	6✔
440	end,
441	{200, OtherResult2}	6✔
442	end.
443
444	format_result(Atom, {Name, atom}) ->
445	{misc:atom_to_binary(Name), misc:atom_to_binary(Atom)};	2✔
446
447	format_result(Int, {Name, integer}) ->
448	{misc:atom_to_binary(Name), Int};	1✔
449
450	format_result([String \| _] = StringList, {Name, string}) when is_list(String) ->
451	Binarized = iolist_to_binary(string:join(StringList, "\n")),	×
452	{misc:atom_to_binary(Name), Binarized};	×
453
454	format_result(String, {Name, string}) ->
455	{misc:atom_to_binary(Name), iolist_to_binary(String)};	33✔
456
457	format_result(Code, {Name, rescode}) ->
458	{misc:atom_to_binary(Name), Code == true orelse Code == ok};	×
459
460	format_result({Code, Text}, {Name, restuple}) ->
461	{misc:atom_to_binary(Name),	×
462	{[{<<"res">>, Code == true orelse Code == ok},	×
463	{<<"text">>, iolist_to_binary(Text)}]}};
464
465	format_result(Code, {Name, restuple}) ->
466	{misc:atom_to_binary(Name),	×
467	{[{<<"res">>, Code == true orelse Code == ok},	×
468	{<<"text">>, <<"">>}]}};
469
470	format_result(Els, {Name, {list, {_, {tuple, [{_, atom}, _]}} = Fmt}}) ->
471	{misc:atom_to_binary(Name), {[format_result(El, Fmt) \|\| El <- Els]}};	×
472
473	format_result(Els, {Name, {list, {_, {tuple, [{name, string}, {value, _}]}} = Fmt}}) ->
474	{misc:atom_to_binary(Name), {[format_result(El, Fmt) \|\| El <- Els]}};	×
475
476	%% Covered by command_test_list and command_test_list_tuple
477	format_result(Els, {Name, {list, Def}}) ->
478	{misc:atom_to_binary(Name), [element(2, format_result(El, Def)) \|\| El <- Els]};	5✔
479
480	format_result(Tuple, {_Name, {tuple, [{_, atom}, ValFmt]}}) ->
481	{Name2, Val} = Tuple,	×
482	{_, Val2} = format_result(Val, ValFmt),	×
483	{misc:atom_to_binary(Name2), Val2};	×
484
485	format_result(Tuple, {_Name, {tuple, [{name, string}, {value, _} = ValFmt]}}) ->
486	{Name2, Val} = Tuple,	×
487	{_, Val2} = format_result(Val, ValFmt),	×
488	{iolist_to_binary(Name2), Val2};	×
489
490	%% Covered by command_test_tuple and command_test_list_tuple
491	format_result(Tuple, {Name, {tuple, Def}}) ->
492	Els = lists:zip(tuple_to_list(Tuple), Def),	11✔
493	Els2 = [format_result(El, ElDef) \|\| {El, ElDef} <- Els],	11✔
494	{misc:atom_to_binary(Name), maps:from_list(Els2)};	11✔
495
496	format_result(404, {_Name, _}) ->
497	"not_found".	×
498
499
500	format_error_result(conflict, Code, Msg) ->
501	{409, Code, iolist_to_binary(Msg)};	×
502	format_error_result(not_exists, Code, Msg) ->
503	{404, Code, iolist_to_binary(Msg)};	×
504	format_error_result(_ErrorAtom, Code, Msg) ->
505	{500, Code, iolist_to_binary(Msg)}.	×
506
507	unauthorized_response() ->
508	json_error(401, 10, <<"You are not authorized to call this command.">>).	×
509
510	invalid_token_response() ->
511	json_error(401, 10, <<"Oauth Token is invalid or expired.">>).	×
512
513	%% outofscope_response() ->
514	%% json_error(401, 11, <<"Token does not grant usage to command required scope.">>).
515
516	badrequest_response() ->
517	badrequest_response(<<"400 Bad Request">>).	×
518	badrequest_response(Body) ->
519	json_response(400, misc:json_encode(Body)).	×
520
521	json_format({Code, Result}) ->
522	json_response(Code, misc:json_encode(Result));	26✔
523	json_format({HTMLCode, JSONErrorCode, Message}) ->
524	json_error(HTMLCode, JSONErrorCode, Message).	×
525
526	json_response(Code, Body) when is_integer(Code) ->
527	{Code, ?HEADER(?CT_JSON), Body}.	26✔
528
529	%% HTTPCode, JSONCode = integers
530	%% message is binary
531	json_error(HTTPCode, JSONCode, Message) ->
532	{HTTPCode, ?HEADER(?CT_JSON),	×
533	misc:json_encode(#{<<"status">> => <<"error">>,
534	<<"code">> => JSONCode,
535	<<"message">> => Message})
536	}.
537
538	log(Call, Args, {Addr, Port}) ->
539	AddrS = misc:ip_to_list({Addr, Port}),	26✔
540	?INFO_MSG("API call ~ts ~p from ~ts:~p", [Call, hide_sensitive_args(Args), AddrS, Port]);	26✔
541	log(Call, Args, IP) ->
542	?INFO_MSG("API call ~ts ~p (~p)", [Call, hide_sensitive_args(Args), IP]).	×
543
544	hide_sensitive_args(Args=[_H\|_T]) ->
545	lists:map( fun({<<"password">>, Password}) -> {<<"password">>, ejabberd_config:may_hide_data(Password)};	26✔
546	({<<"newpass">>,NewPassword}) -> {<<"newpass">>, ejabberd_config:may_hide_data(NewPassword)};	×
547	(E) -> E end,	46✔
548	Args);
549	hide_sensitive_args(NonListArgs) ->
550	NonListArgs.	×
551
552	mod_options(_) ->
553	[].	×
554
555	mod_doc() ->
556	#{desc =>	×
557	[?T("This module provides a ReST interface to call "
558	"_`../../developer/ejabberd-api/index.md\|ejabberd API`_ "
559	"commands using JSON data."), "",
560	?T("To use this module, in addition to adding it to the 'modules' "
561	"section, you must also enable it in 'listen' -> 'ejabberd_http' -> "
562	"_`listen-options.md#request_handlers\|request_handlers`_."), "",
563	?T("To use a specific API version N, when defining the URL path "
564	"in the request_handlers, add a 'vN'. "
565	"For example: '/api/v2: mod_http_api'"), "",
566	?T("To run a command, send a POST request to the corresponding "
567	"URL: 'http://localhost:5280/api/<command_name>'")],
568	example =>
569	["listen:",
570	" -",
571	" port: 5280",
572	" module: ejabberd_http",
573	" request_handlers:",
574	" /api: mod_http_api",
575	"",
576	"modules:",
577	" mod_http_api: {}"]}.

processone / ejabberd / 782

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous