Merge pull request #7700 from garazdawi/lukas/inets/add-callback-attr…

…ibutes/OTP-18786/OTP-18787/OTP-18788 Add callback attributes to tftp, inets and ssl
erlang · Oct 5, 2023 · 1171571 · 1171571
2 parents 77a5bf8 + b0a8d52
commit 1171571
Show file tree

Hide file tree

Showing 11 changed files with 198 additions and 82 deletions.
diff --git a/lib/inets/doc/src/mod_esi.xml b/lib/inets/doc/src/mod_esi.xml
@@ -61,7 +61,7 @@
 	<tag><c>{server_port, integer()}</c></tag>
 	<item><p>Servers port number.</p></item>
 
-	<tag><c>{request_method, "GET | "PUT" | "DELETE" | "POST" | "PATCH"}</c></tag>
+	<tag><c>{request_method, "GET" | "PUT" | "DELETE" | "POST" | "PATCH"}</c></tag>
 	<item><p>HTTP request method.</p></item>
 
 	<tag><c>{remote_adress, inet:ip_address()} </c></tag>
@@ -127,7 +127,7 @@
      to the server process by calling <c>mod_esi:deliver/2</c>.</fsummary>
      <type>
        <v>SessionID = term()</v>
-       <v>Env = env()</v>
+       <v>Env = [env()]</v>
        <v>Input = string() | chunked_data()</v>
        <v>chunked_data() = {first, Data::binary()} |
        {continue, Data::binary(), State::term()} |

diff --git a/lib/inets/src/http_server/httpd.erl b/lib/inets/src/http_server/httpd.erl
@@ -49,6 +49,41 @@
 -deprecated({parse_query, 1,
             "use uri_string:dissect_query/1 instead"}).
 
+%%%========================================================================
+%%% Types
+%%%========================================================================
+-type property() :: atom().
+-type ets_table() :: ets:tid().
+
+%%%========================================================================
+%%% Callbacks
+%%%========================================================================
+-callback do(ModData) -> {proceed, OldData} | {proceed, NewData} | {break, NewData} | done when
+      ModData :: [{data,NewData} | {'Body', Body} | {'Head',Head}],
+      OldData :: list(),
+      NewData :: [{response, {StatusCode, Body}}],
+      StatusCode :: integer(),
+      Body :: iolist() | nobody | {Fun, FunArg},
+      Head :: [HeaderOption],
+      HeaderOption :: {Option, Value} | {code, StatusCode},
+      Option :: accept_ranges | allow,
+      Value :: string(),
+      FunArg :: [term()],
+      Fun :: fun((FunArg) -> sent | close | Body).
+
+-callback remove(ConfigDB) -> ok | {error, Reason} when
+      ConfigDB :: ets_table(), Reason :: term().
+
+-callback store({Option, Value}, Config) ->
+    {ok, {Option, NewValue}} | {error, Reason} when
+      Option :: property(),
+      Config :: [{Option, Value}],
+      Value :: term(),
+      NewValue :: term(),
+      Reason :: term().
+
+-optional_callbacks([remove/1, store/2]).
+
 %%%========================================================================
 %%% API
 %%%========================================================================

diff --git a/lib/inets/src/http_server/mod_esi.erl b/lib/inets/src/http_server/mod_esi.erl
@@ -39,6 +39,40 @@
         [{status, {404, ModData#mod.request_uri, "Not found"}} |
          ModData#mod.data]).
 
+%%%=========================================================================
+%%%  Types
+%%%=========================================================================
+-type env() :: {server_software, string()} |
+               {server_name, string()} |
+               {gateway_interface, string()} |
+               {server_protocol, string()} |
+               {server_port, integer()} |
+               {request_method, string() } |
+               {remote_adress, inet:ip_address()}  |
+               {peer_cert, undefined | no_peercert | public_key:der_encoded()} |
+               {script_name, string()} |
+               {http_LowerCaseHTTPHeaderName, string()}.
+
+%%%=========================================================================
+%%%  Callbacks
+%%%=========================================================================
+-callback 'Function'(SessionID, Env, Input) -> {continue, State} | _
+                        when
+                            SessionID :: term(),
+                            Env :: [env()],
+                            Input :: string() | ChunkedData,
+                            ChunkedData ::
+                                {first, Data :: binary()} |
+                                {continue,
+                                 Data :: binary(),
+                                 State :: term()} |
+                                {last,
+                                 Data :: binary(),
+                                 State :: term()},
+                            State :: term().
+
+-optional_callbacks(['Function'/3]).
+
 %%%=========================================================================
 %%%  API 
 %%%=========================================================================

diff --git a/lib/inets/src/http_server/mod_security.erl b/lib/inets/src/http_server/mod_security.erl
@@ -36,9 +36,27 @@
 
 -define(VMODULE,"SEC").
 
+
+%%====================================================================
+%% Internal application API
+%%====================================================================
+-callback event(What, Port, Dir, Data) -> term() when
+      What :: auth_fail | user_block | user_unblock,
+      Port :: integer(),
+      Dir :: string(),
+      Data :: [Info],
+      Info :: {Name :: term(), Value :: term()}.
+-callback event(What, Address, Port, Dir, Data) -> term() when
+      What :: auth_fail | user_block | user_unblock,
+      Port :: integer(),
+      Address :: inet:ip4_address() | string(),
+      Dir :: string(),
+      Data :: [Info],
+      Info :: {Name :: term(), Value :: term()}.
+
 %%====================================================================
 %% Internal application API
-%%====================================================================	     
+%%====================================================================
 do(Info) ->
     %% Check and see if any user has been authorized.
     case proplists:get_value(remote_user, Info#mod.data,not_defined_user) of

diff --git a/lib/ssl/src/ssl_crl_cache_api.erl b/lib/ssl/src/ssl_crl_cache_api.erl
@@ -21,7 +21,7 @@
 %%
 
 -module(ssl_crl_cache_api).
--include_lib("public_key/include/public_key.hrl"). 
+-include_lib("public_key/include/public_key.hrl").
 
 -export_type([dist_point/0, crl_cache_ref/0, logger_info/0]).
 
@@ -30,9 +30,17 @@
 -type dist_point()  :: #'DistributionPoint'{}.
 -type logger_info()     :: {logger:level(), Report::#{description => string(), reason => term()}, logger:metadata()}.
 
--callback lookup(dist_point(), issuer_name(), crl_cache_ref()) -> not_available | [public_key:der_encoded()] | 
-                                                                  {{logger, logger_info()}, [public_key:der_encoded()]}.
--callback select(issuer_name() | list(), crl_cache_ref()) ->  [public_key:der_encoded()] |  
-                                                     {logger, logger_info(), [public_key:der_encoded()]}.
--callback fresh_crl(dist_point(), public_key:der_encoded()) -> public_key:der_encoded() | 
-                                                               {logger, logger_info(),  public_key:der_encoded()}.
+-callback lookup(dist_point(), crl_cache_ref()) ->
+    not_available | [public_key:der_encoded()] |
+    {{logger, logger_info()}, [public_key:der_encoded()]}.
+-callback lookup(dist_point(), issuer_name(), crl_cache_ref()) ->
+    not_available | [public_key:der_encoded()] |
+    {{logger, logger_info()}, [public_key:der_encoded()]}.
+-callback select(issuer_name() | list(), crl_cache_ref()) ->
+    [public_key:der_encoded()] |
+    {logger, logger_info(), [public_key:der_encoded()]}.
+-callback fresh_crl(dist_point(), public_key:der_encoded()) ->
+    public_key:der_encoded() |
+    {logger, logger_info(),  public_key:der_encoded()}.
+
+-optional_callbacks([lookup/2]).
diff --git a/lib/tftp/doc/src/Makefile b/lib/tftp/doc/src/Makefile
@@ -39,7 +39,8 @@ XML_CHAPTER_FILES = \
 	notes.xml
 
 XML_REF3_FILES = \
-	tftp.xml
+	tftp.xml \
+	tftp_logger.xml
 
 XML_PART_FILES = \
 	usersguide.xml

diff --git a/lib/tftp/doc/src/ref_man.xml b/lib/tftp/doc/src/ref_man.xml
@@ -33,4 +33,5 @@
     <p>The <c>TFTP</c> application.</p>
   </description>
   <xi:include href="tftp.xml"/>
+  <xi:include href="tftp_logger.xml"/>
 </application>
diff --git a/lib/tftp/doc/src/tftp.xml b/lib/tftp/doc/src/tftp.xml
@@ -154,8 +154,7 @@
 
         <p>Callback module for customized logging of errors, warnings, and
 	  info messages. The callback module must implement the
-	  <c>tftp_logger</c> behavior, see
-          <seeerl marker="#tftp_logger">LOGGER FUNCTIONS</seeerl>.
+	  <seeerl marker="tftp_logger"><c>tftp_logger</c></seeerl> behavior.
           The default module is <c>tftp_logger</c>.</p>
       </item>
 
@@ -536,65 +535,4 @@
       </desc>
     </func>
   </funcs>
-
-
-
-  <funcs>
-    <fsdescription>
-      <marker id="tftp_logger"></marker>
-      <title>LOGGER FUNCTIONS</title>
-
-      <p>A <c>tftp_logger</c> callback module is to be implemented as a
-      <c>tftp_logger</c> behavior and export the following functions:</p>
-
-      <marker id="error_msg"></marker>
-    </fsdescription>
-    <func>
-      <name since="OTP 18.1">Logger:error_msg(Format, Data) -> ok | exit(Reason)</name>
-      <fsummary>Logs an error message.</fsummary>
-      <type>
-        <v>Format = string()</v>
-        <v>Data = [term()]</v>
-        <v>Reason = term()</v>
-      </type>
-      <desc>
-	<p>Logs an error message. 
-	See <c>error_logger:error_msg/2</c> for details.</p>
-
-	<marker id="warning_msg"></marker>
-      </desc>
-    </func>
-
-    <func>
-      <name since="OTP 18.1">Logger:info_msg(Format, Data) -> ok | exit(Reason)</name>
-      <fsummary>Logs an info message.</fsummary>
-      <type>
-        <v>Format = string()</v>
-        <v>Data = [term()]</v>
-        <v>Reason = term()</v>
-      </type>
-      <desc>
-        <p>Logs an info message. 
-	See <c>error_logger:info_msg/2</c>  for details.</p>
-      </desc>
-    </func>
-
-    <func>
-      <name since="OTP 18.1">Logger:warning_msg(Format, Data) -> ok | exit(Reason)</name>
-      <fsummary>Logs a warning message.</fsummary>
-      <type>
-        <v>Format = string()</v>
-        <v>Data = [term()]</v>
-        <v>Reason = term()</v>
-      </type>
-      <desc>
-        <p>Logs a warning message. 
-	See <c>error_logger:warning_msg/2</c> for details.</p>
-
-	<marker id="info_msg"></marker>
-      </desc>
-    </func>
-  </funcs>
 </erlref>
-
-
diff --git a/lib/tftp/doc/src/tftp_logger.xml b/lib/tftp/doc/src/tftp_logger.xml
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2023</year><year>2023</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+
+    </legalnotice>
+
+    <title>tftp_logger</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module since="OTP 18.1">tftp_logger</module>
+  <modulesummary>Trivial FTP logger.</modulesummary>
+  <description>
+    <p>A <c>tftp_logger</c> callback module is to be implemented as a
+      <c>tftp_logger</c> behavior and export the following functions:</p>
+  </description>
+
+  <funcs>
+    <func>
+      <name since="OTP 18.1">Module:error_msg(Format, Data) -> ok</name>
+      <fsummary>Logs an error message.</fsummary>
+      <type>
+        <v>Format = string()</v>
+        <v>Data = [term()]</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+	<p>Logs an error message.
+	See <seemfa marker="kernel:error_logger#error_msg/2">
+          <c>error_logger:error_msg/2</c></seemfa> for details.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name since="OTP 18.1">Module:info_msg(Format, Data) -> ok</name>
+      <fsummary>Logs an info message.</fsummary>
+      <type>
+        <v>Format = string()</v>
+        <v>Data = [term()]</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Logs an info message.
+	See <seemfa marker="kernel:error_logger#info_msg/2">
+          <c>error_logger:info_msg/2</c></seemfa> for details.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name since="OTP 18.1">Module:warning_msg(Format, Data) -> ok</name>
+      <fsummary>Logs a warning message.</fsummary>
+      <type>
+        <v>Format = string()</v>
+        <v>Data = [term()]</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Logs a warning message.
+	See <seemfa marker="kernel:error_logger#warning_msg/2">
+          <c>error_logger:warning_msg/2</c></seemfa> for details.</p>
+      </desc>
+    </func>
+  </funcs>
+</erlref>
diff --git a/lib/tftp/src/tftp.erl b/lib/tftp/src/tftp.erl
@@ -226,6 +226,7 @@
 	 service_info/1
 	]).
 
+-include("tftp.hrl").
 
 -type peer() :: {PeerType :: inet | inet6,
 		 PeerHost :: inet:ip_address(),
@@ -268,9 +269,6 @@
 
 -callback abort(Code :: error_code(), string(), State :: term()) -> 'ok'.
 
--include("tftp.hrl").
-
-
 %%-------------------------------------------------------------------
 %% read_file(RemoteFilename, LocalFilename, Options) ->
 %%   {ok, LastCallbackState} | {error, Reason}

diff --git a/lib/tftp/src/tftp_logger.erl b/lib/tftp/src/tftp_logger.erl
@@ -31,12 +31,11 @@
 	 info_msg/2
 	]).
 
--export([behaviour_info/1]).
+-callback warning_msg(Format :: string(), Data :: [term()]) -> ok.
+-callback info_msg(Format :: string(), Data :: [term()]) -> ok.
+-callback error_msg(Format :: string(), Data :: [term()]) -> ok.
 
-behaviour_info(callbacks) ->
-    [{error_msg, 2}, {warning_msg, 2}, {info_msg, 2}];
-behaviour_info(_) ->
-    undefined.
+-optional_callbacks([warning_msg/2, error_msg/2, info_msg/2]).
 
 %%-------------------------------------------------------------------
 %% error_msg(Format, Data) -> ok | exit(Reason)