diff options
Diffstat (limited to 'lib/inets/doc')
| -rw-r--r-- | lib/inets/doc/specs/.gitignore | 1 | ||||
| -rw-r--r-- | lib/inets/doc/src/Makefile | 19 | ||||
| -rw-r--r-- | lib/inets/doc/src/http_client.xml | 16 | ||||
| -rw-r--r-- | lib/inets/doc/src/http_uri.xml | 91 | ||||
| -rw-r--r-- | lib/inets/doc/src/httpc.xml | 905 | ||||
| -rw-r--r-- | lib/inets/doc/src/httpd.xml | 322 | ||||
| -rw-r--r-- | lib/inets/doc/src/httpd_util.xml | 10 | ||||
| -rw-r--r-- | lib/inets/doc/src/mod_esi.xml | 21 | ||||
| -rw-r--r-- | lib/inets/doc/src/notes.xml | 297 | ||||
| -rw-r--r-- | lib/inets/doc/src/specs.xml | 14 |
10 files changed, 899 insertions, 797 deletions
diff --git a/lib/inets/doc/specs/.gitignore b/lib/inets/doc/specs/.gitignore new file mode 100644 index 0000000000..322eebcb06 --- /dev/null +++ b/lib/inets/doc/specs/.gitignore @@ -0,0 +1 @@ +specs_*.xml diff --git a/lib/inets/doc/src/Makefile b/lib/inets/doc/src/Makefile index a81e50afc0..e3c876c5be 100644 --- a/lib/inets/doc/src/Makefile +++ b/lib/inets/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2021. All Rights Reserved. +# Copyright Ericsson AB 1997-2022. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -62,12 +62,27 @@ XML_FILES = \ $(BOOK_FILES) \ $(XML_CHAPTER_FILES) \ $(XML_PART_FILES) \ - $(XML_REF6_FILES) \ $(XML_REF3_FILES) \ $(XML_APPLICATION_FILES) +SPEC_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml) +TOP_SPECS_FILE = specs.xml + NO_CHUNKS = httpd_custom_api.xml +# Generate file specs for files with type specs. +# These are needed because the standard script +# (otp/make/otp.mk.in) does not traverse folders +$(SPECDIR)/specs_%.xml: $(SPECS_ESRC)/http_client/%.erl $(TOP_SPECS_FILE) + $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) -o$(dir $@) $< +$(SPECDIR)/specs_%.xml: $(SPECS_ESRC)/inets_app/%.erl $(TOP_SPECS_FILE) + $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) -o$(dir $@) $< +$(SPECDIR)/specs_%.xml: $(SPECS_ESRC)/http_server/%.erl $(TOP_SPECS_FILE) + $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) -o$(dir $@) $< +$(SPECDIR)/specs_%.xml: $(SPECS_ESRC)/http_lib/%.erl $(TOP_SPECS_FILE) + $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) -o$(dir $@) $< + # ---------------------------------------------------- include $(ERL_TOP)/make/doc.mk +SPECS_FLAGS += -I../../src/inets_app -I../../include -I../../../kernel/include diff --git a/lib/inets/doc/src/http_client.xml b/lib/inets/doc/src/http_client.xml index 0258456966..34868408c6 100644 --- a/lib/inets/doc/src/http_client.xml +++ b/lib/inets/doc/src/http_client.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2021</year> + <year>2004</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -81,27 +81,31 @@ <code type="erl"> 4 > {ok, {{Version, 200, ReasonPhrase}, Headers, Body}} = httpc:request("http://www.erlang.org").</code> + <p>The following is a https request and with verification of the host:</p> + <code type="erl"> + 5 > {ok, {{Version, 200, ReasonPhrase}, Headers, Body}} = + httpc:request(get, {"https://www.erlang.org", []}, [{ssl, httpc:ssl_verify_host_options(true)}], []).</code> <p>The following is an ordinary asynchronous request:</p> <code type="erl"> - 5 > {ok, RequestId} = + 6 > {ok, RequestId} = httpc:request(get, {"http://www.erlang.org", []}, [], [{sync, false}]).</code> <p>The result is sent to the calling process as <c>{http, {ReqestId, Result}}</c>.</p> <p>In this case, the calling process is the shell, so the following result is received:</p> <code type="erl"> - 6 > receive {http, {RequestId, Result}} -> ok after 500 -> error end. + 7 > receive {http, {RequestId, Result}} -> ok after 500 -> error end. ok</code> <p>This sends a request with a specified connection header:</p> <code type="erl"> - 7 > {ok, {{NewVersion, 200, NewReasonPhrase}, NewHeaders, NewBody}} = + 8 > {ok, {{NewVersion, 200, NewReasonPhrase}, NewHeaders, NewBody}} = httpc:request(get, {"http://www.erlang.org", [{"connection", "close"}]}, [], []).</code> <p>This sends an HTTP request over a unix domain socket (experimental):</p> <code type="erl"> - 8 > httpc:set_options([{ipfamily, local}, + 9 > httpc:set_options([{ipfamily, local}, {unix_socket,"/tmp/unix_socket/consul_http.sock"}]). - 9 > {ok, {{NewVersion, 200, NewReasonPhrase}, NewHeaders, NewBody}} = + 10 > {ok, {{NewVersion, 200, NewReasonPhrase}, NewHeaders, NewBody}} = httpc:request(put, {"http:///v1/kv/foo", [], [], "hello"}, [], []).</code> <p>Start an HTTP client profile:</p> diff --git a/lib/inets/doc/src/http_uri.xml b/lib/inets/doc/src/http_uri.xml index eb47a823fb..39b367eb92 100644 --- a/lib/inets/doc/src/http_uri.xml +++ b/lib/inets/doc/src/http_uri.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2012</year><year>2021</year> + <year>2012</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -57,25 +57,10 @@ <tag><c>uri() = string() | binary()</c></tag> <item><p>Syntax according to the URI definition in RFC 3986, for example, "http://www.erlang.org/"</p></item> - <tag><c>user_info() = string() | binary()</c></tag> - <item><p></p></item> - <tag><c>scheme() = atom()</c></tag> - <item><p>Example: http, https</p></item> - <tag><c>host() = string() | binary()</c></tag> - <item><p></p></item> - <tag><c>port() = inet:port_number()</c></tag> - <item><p></p></item> - <tag><c>path() = string() | binary()</c></tag> - <item><p>Represents a file path or directory path</p></item> - <tag><c>query() = string() | binary()</c></tag> - <item><p></p></item> - <tag><c>fragment() = string() | binary()</c></tag> - <item><p></p></item> </taglist> <p>For more information about URI, see <url href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>.</p> - <marker id="scheme_defaults"></marker> </section> <funcs> @@ -108,80 +93,6 @@ <marker id="decode"></marker> </desc> </func> - - <func> - <name since="OTP R15B01">parse(URI) -> {ok, Result} | {error, Reason}</name> - <name since="OTP R15B01">parse(URI, Options) -> {ok, Result} | {error, Reason}</name> - <fsummary>Parses a URI.</fsummary> - <type> - <v>URI = uri()</v> - <v>Options = [Option]</v> - <v>Option = {ipv6_host_with_brackets, boolean()} | - {scheme_defaults, scheme_defaults()} | - {fragment, boolean()} | - {scheme_validation_fun, fun()}</v> - <v>Result = {Scheme, UserInfo, Host, Port, Path, Query} | - {Scheme, UserInfo, Host, Port, Path, Query, Fragment}</v> - <v>Scheme = scheme()</v> - <v>UserInfo = user_info()</v> - <v>Host = host()</v> - <v>Port = inet:port_number()</v> - <v>Path = path()</v> - <v>Query = query()</v> - <v>Fragment = fragment()</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Parses a URI. If no scheme defaults - are provided, the value of the - <seeerl marker="#scheme_defaults">scheme_defaults</seeerl> - function is used.</p> - - <p>When parsing a URI with an unknown scheme (that is, - a scheme not found in the scheme defaults), a port number must be - provided, otherwise the parsing fails.</p> - - <p>If the fragment option is <c>true</c>, the URI fragment is returned as - part of the parsing result, otherwise it is ignored.</p> - - <p>Scheme validation fun is to be defined as follows:</p> - - <code> -fun(SchemeStr :: string() | binary()) -> - valid | {error, Reason :: term()}. - </code> - - <p>It is called before scheme string gets converted into scheme atom and - thus possible atom leak could be prevented</p> - - <warning> - <p>The scheme portion of the URI gets converted into atom, - meaning that atom leak may occur. Specifying a scheme - validation fun is recommended unless the URI is already - sanitized.</p> - </warning> - - <marker id="encode"></marker> - </desc> - </func> - - <func> - <name since="OTP R15B01">scheme_defaults() -> SchemeDefaults</name> - <fsummary>A list of the scheme and their default ports.</fsummary> - <type> - <v>SchemeDefaults = [{scheme(), default_scheme_port_number()}] </v> - <v>default_scheme_port_number() = inet:port_number()</v> - </type> - <desc> - <p>Provides a list of the scheme and their default - port numbers supported (by default) by this utility.</p> - - <marker id="parse"></marker> - </desc> - </func> - - - </funcs> <!-- diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index 34010b25e4..0c6437ccec 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2004</year><year>2021</year> + <year>2004</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -60,77 +60,6 @@ <p>Some examples are provided in the <seeguide marker="http_client">Inets User's Guide</seeguide>.</p> </description> - - <section> - <title>DATA TYPES</title> - <marker id="DATA_TYPES"></marker> - <p>Type definitions that are used more than once in - this module:</p> - <p><c>boolean() = true | false</c></p> - <p><c>http_string()</c> = list of ASCII characters</p> - <p><c>request_id() = reference()</c></p> - <p><c>profile() = atom()</c></p> - <p><c>path() = string()</c> representing a file path or directory path</p> - <p><c>ip_address()</c> = See the - <seeerl marker="kernel:inet">inet(3)</seeerl> manual page in Kernel.</p> - <p><c>socket_opt()</c> = See the options used by - <seeerl marker="kernel:gen_tcp">gen_tcp(3)</seeerl> <c>gen_tcp(3)</c> and - <seeerl marker="ssl:ssl">ssl(3)</seeerl> connect(s)</p> - - </section> - - <section> - <title>HTTP DATA TYPES</title> - <p>Type definitions related to HTTP:</p> - - <p><c>method() = head | get | put | post | trace | options | delete | patch</c></p> - <taglist> - <tag><c>request()</c></tag> - <item><p>= <c>{url(), headers()}</c></p> - <p>| <c>{url(), headers(), content_type(), body()}</c></p> - </item> - </taglist> - <p><c>url() = http_string()</c> syntax according to the URI definition in - <url href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>, - for example <c>"http://www.erlang.org"</c></p> - <warning><p>Please note that httpc normalizes input URIs before internal processing - and special care shall be taken when the URI has percent ("%") characters. A percent - serves as the indicator for percent-encoded octets and it must be percent-encoded - as "%25" for that octet to be used as data within the URI.</p> - <p>For example, in order to send an HTTP GET request with the URI - <c>http://localhost/foo%25bar</c>, the percent character must be percent-encoded when - creating the request: <c>httpc:request("http://localhost/foo%2525bar").</c> - </p></warning> - <p><c>status_line() = {http_version(), status_code(), reason_phrase()}</c></p> - <p><c>http_version() = http_string()</c>, for example, <c>"HTTP/1.1"</c></p> - <p><c>status_code() = integer()</c></p> - <p><c>reason_phrase() = string()</c></p> - <p><c>content_type() = http_string()</c></p> - <p><c>headers() = [header()]</c></p> - <p><c>header() = {field(), value()}</c></p> - <p><c>field() = [byte()]</c></p> - <p><c>value() = binary() | iolist()</c></p> - <taglist> - <tag><c>body()</c></tag> - <item><p>= <c>http_string() | binary()</c></p> - <p>| <c>{fun(accumulator())</c></p> - <p><c> -> body_processing_result(), accumulator()}</c></p> - <p>| <c>{chunkify, fun(accumulator())</c></p> - <p><c> -> body_processing_result(), accumulator()}</c></p> - </item> - </taglist> - <p><c>body_processing_result() = eof | {ok, iolist(), accumulator()}</c></p> - <p><c>accumulator() = term()</c></p> - <p><c>filename() = string()</c></p> - <p>For more information about HTTP, see - <url href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</url>.</p> -</section> - - <section> - <title>SSL DATA TYPES</title> - <p>See <seeerl marker="ssl:ssl">ssl(3)</seeerl> for information - about <c>SSL</c> options (<c>ssloptions()</c>). </p> - </section> <section> <title>HTTP CLIENT SERVICE START/STOP</title> @@ -142,576 +71,556 @@ see <seeerl marker="inets">inets(3)</seeerl>. The configuration options are as follows:</p> <taglist> - <tag>{profile, profile()}</tag> - <item><p>Name of the profile, see - <seeerl marker="#DATA_TYPES">DATA TYPES</seeerl>. - This option is mandatory.</p></item> - <tag>{data_dir, path()}</tag> - <item><p>Directory where the profile + <tag>{profile, Profile :: atom() | pid()}</tag> + <item>Name of the profile. + This option is mandatory.</item> + <tag>{data_dir, Path :: string()}</tag> + <item>Directory where the profile can save persistent data. If omitted, all cookies are treated - as session cookies.</p></item> + as session cookies. <c>Path</c> represents a file path or directory path.</item> </taglist> - <p>The client can be stopped using <c>inets:stop(httpc, Pid)</c> or - <c>inets:stop(httpc, Profile)</c>.</p> + <p>The client can be stopped using <seemfa marker="inets#stop/2"><c>inets:stop(httpc, Pid)</c></seemfa> or + <seemfa marker="inets#stop/2"><c>inets:stop(httpc, Profile)</c></seemfa>.</p> + + <warning><p>Please note that <c>httpc</c> normalizes input URIs before internal + processing and special care shall be taken when the URI has percent ("%") + characters. A percent serves as the indicator for percent-encoded octets and + it must be percent-encoded as "%25" for that octet to be used as data within + the URI.</p> + <p>For example, in order to send an <c>HTTP GET</c> request with the + URI <c>http://localhost/foo%25bar</c>, the percent character must be + percent-encoded when creating the request: + <c>httpc:request("http://localhost/foo%2525bar").</c> </p></warning> </section> - + <funcs> - <func> - <name since="OTP R13B04">cancel_request(RequestId) -></name> - <name since="OTP R13B04">cancel_request(RequestId, Profile) -> ok</name> + <name since="OTP R13B04" name="cancel_request" arity="1" /> + <name since="OTP R13B04" name="cancel_request" arity="2" /> <fsummary>Cancels an asynchronous HTTP request.</fsummary> - <type> - <v>RequestId = request_id() - A unique identifier as returned - by request/4</v> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c> only the pid can be used.</d> - </type> + <type variable="RequestId" /> + <type_desc variable="RequestId"> + A unique identifier as returned by + <seemfa marker="#request/4"><c>request/4</c></seemfa> + </type_desc> + <type variable="Profile" /> + <type_desc variable="Profile"> + When started <c>stand_alone</c> only the pid can be used. + </type_desc> + <desc> + <p>Cancels an asynchronous HTTP request. Notice that this does not + guarantee that the request response is not delivered. Because it is + asynchronous, the request can already have been completed when the + cancellation arrives. + </p> + </desc> + </func> + + <func> + <name since="OTP R13B04" name="cookie_header" arity="1"/> + <name since="OTP R13B04" name="cookie_header" arity="2"/> + <fsummary>Returns the cookie header that would have been sent when making + a request to <c><anno>URL</anno></c>, using the profile + <c><anno>Profile</anno></c>.</fsummary> + <type_desc variable="Profile"> + When started <c>stand_alone</c> only the pid can be used. + </type_desc> <desc> - <p>Cancels an asynchronous HTTP request. Notice that this does not guarantee - that the request response is not delivered. Because it is asynchronous, - the request can already have been completed when the cancellation arrives. - </p> + <p>Returns the cookie header that would have been sent when making a + request to <c><anno>Url</anno></c> using profile + <c><anno>Profile</anno></c>. If no profile is specified, the default + profile is used.</p> + <p>Option <c>ipv6_host_with_bracket</c> deals with how to parse IPv6 + addresses. For details, see argument <c>Options</c> of <seemfa + marker="#request/4">request/[4,5]</seemfa>.</p> </desc> </func> <func> - <name since="OTP R13B04">cookie_header(Url) -> </name> - <name since="OTP R13B04">cookie_header(Url, Profile | Opts) -> header() | {error, Reason}</name> - <name since="OTP R15B">cookie_header(Url, Opts, Profile) -> header() | {error, Reason}</name> - <fsummary>Returns the cookie header that would have been sent when - making a request to URL using the profile <c>Profile</c>.</fsummary> - <type> - <v>Url = url()</v> - <v>Opts = [cookie_header_opt()]</v> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c>.</d> - <v>cookie_header_opt() = {ipv6_host_with_brackets, boolean()}</v> - </type> + <name since="OTP R15B" name="cookie_header" arity="3"/> + <fsummary>Returns the cookie header that would have been sent when making + a request to <c><anno>URL</anno></c> using the profile + <c><anno>Profile</anno></c>.</fsummary> + <type_desc variable="Profile"> + When started <c>stand_alone</c> only the pid can be used. + </type_desc> <desc> - <p>Returns the cookie header that would have been sent - when making a request to <c>Url</c> using profile <c>Profile</c>. - If no profile is specified, the default profile is used.</p> - <p>Option <c>ipv6_host_with_bracket</c> deals with how to - parse IPv6 addresses. For details, - see argument <c>Options</c> of - <seemfa marker="#request/4">request/[4,5]</seemfa>.</p> + <p>Returns the cookie header that would have been sent when making a + request to <c><anno>Url</anno></c> using profile + <c><anno>Profile</anno></c>. If no profile is specified, the default + profile is used.</p> + <p>Option <c>ipv6_host_with_bracket</c> deals with how to parse IPv6 + addresses. For details, see argument <c>Options</c> of <seemfa + marker="#request/4">request/[4,5]</seemfa>.</p> </desc> </func> <func> - <name since="OTP R15B01">get_options(OptionItems) -> {ok, Values} | {error, Reason}</name> - <name since="OTP R15B01">get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason}</name> + <name since="OTP R15B01" name="get_options" arity="1"/> + <name since="OTP R15B01" name="get_options" arity="2"/> <fsummary>Gets the currently used options.</fsummary> - <type> - <v>OptionItems = all | [option_item()]</v> - <v>option_item() = proxy | - https_proxy | - max_sessions | - keep_alive_timeout | - max_keep_alive_length | - pipeline_timeout | - max_pipeline_length | - cookies | - ipfamily | - ip | - port | - socket_opts | - verbose | - unix_socket</v> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c> only the pid can used.</d> - <v>Values = [{option_item(), term()}]</v> - <v>Reason = term()</v> - </type> + <type_desc variable="Profile"> + When started <c>stand_alone</c> only the pid can be used. + </type_desc> <desc> <p>Retrieves the options currently used by the client.</p> </desc> </func> <func> - <name since="OTP R15B02">info() -> list()</name> - <name since="OTP R15B02">info(Profile) -> list()</name> + <name since="OTP R15B02" name="info" arity="0"/> + <name since="OTP R15B02" name="info" arity="1"/> <fsummary>Produces a list of miscellaneous information.</fsummary> - <type> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c> only the pid can be used.</d> - </type> + <type_desc variable="Profile"> + When started <c>stand_alone</c> only the pid can be used. + </type_desc> <desc> - <p>Produces a list of miscellaneous information. - Intended for debugging. - If no profile is specified, the default profile is used.</p> + <p>Produces a list of miscellaneous information. Intended for debugging. + If no profile is specified, the default profile is used.</p> </desc> </func> <func> - <name since="OTP R13B04">reset_cookies() -> void()</name> - <name since="OTP R13B04">reset_cookies(Profile) -> void()</name> + <name since="OTP R13B04" name="reset_cookies" arity="0"/> + <name since="OTP R13B04" name="reset_cookies" arity="1"/> <fsummary>Resets the cookie database.</fsummary> - <type> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c> only the pid can be used.</d> - </type> + <type_desc variable="Profile"> + When started <c>stand_alone</c> only the pid can be used. + </type_desc> <desc> - <p>Resets (clears) the cookie database for the specified - <c>Profile</c>. If no profile is specified the default profile - is used.</p> + <p>Resets (clears) the cookie database for the specified + <c><anno>Profile</anno></c>. If no profile is specified the default + profile is used.</p> </desc> </func> <func> - <name since="OTP R13B04">request(Url) -> </name> - <name since="OTP R13B04">request(Url, Profile) -> {ok, Result} | {error, Reason}</name> + <name since="OTP R13B04" name="request" arity="1"/> + <name since="OTP R13B04" name="request" arity="2"/> <fsummary>Sends a get HTTP request.</fsummary> - <type> - <v>Url = url()</v> - <v>Result = {status_line(), headers(), Body} | - {status_code(), Body} | request_id()</v> - <v>Body = http_string() | binary()</v> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c> only the pid can be used.</d> - <v>Reason = term()</v> - </type> + <type_desc variable="Profile"> + When started <c>stand_alone</c> only the pid can be used. + </type_desc> <desc> - <p>Equivalent to <c>httpc:request(get, {Url, []}, [], [])</c>.</p> + <p>Equivalent to <seemfa marker="httpc#request/4"><c>httpc:request(get, {Url, []}, [], [])</c></seemfa>.</p> </desc> </func> <func> - <name since="OTP R13B04">request(Method, Request, HTTPOptions, Options) -></name> - <name since="OTP R13B04">request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result} | {ok, saved_to_file} | {error, Reason}</name> - + <name since="OTP R13B04" name="request" arity="4"/> + <name since="OTP R13B04" name="request" arity="5"/> <fsummary>Sends an HTTP request.</fsummary> - <type> - <v>Method = method()</v> - <v>Request = request()</v> - <v>HTTPOptions = http_options()</v> - <v>http_options() = [http_option()]</v> - <v>http_option() = {timeout, timeout()} | - {connect_timeout, timeout()} | - {ssl, ssloptions()} | - {essl, ssloptions()} | - {autoredirect, boolean()} | - {proxy_auth, {userstring(), passwordstring()}} | - {version, http_version()} | - {relaxed, boolean()}</v> - <v>timeout() = integer() >= 0 | infinity</v> - <v>Options = options()</v> - <v>options() = [option()]</v> - <v>option() = {sync, boolean()} | - {stream, stream_to()} | - {body_format, body_format()} | - {full_result, boolean()} | - {headers_as_is, boolean() | - {socket_opts, socket_opts()} | - {receiver, receiver()} | - {ipv6_host_with_brackets, boolean()}</v> - <v>stream_to() = none | self | {self, once} | filename()</v> - <v>socket_opts() = [socket_opt()]</v> - <v>receiver() = pid() | function()/1 | {Module, Function, Args}</v> - <v>Module = atom()</v> - <v>Function = atom()</v> - <v>Args = list()</v> - <v>body_format() = string | binary</v> - <v>Result = {status_line(), headers(), Body} | - {status_code(), Body} | request_id()</v> - <v>Body = http_string() | binary()</v> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c> only the pid can be used.</d> - <v>Reason = term()</v> - </type> - + <type_desc variable="Profile"> + When <c><anno>Profile</anno></c> is <c>stand_alone</c> only the pid can be used. + </type_desc> <desc> - <p>Sends an HTTP request. The function can be both synchronous - and asynchronous. In the latter case, the function returns - <c>{ok, RequestId}</c> and then the information is delivered - to the <c>receiver</c> depending on that value.</p> + <p>Sends an HTTP request. The function can be both synchronous and + asynchronous. In the latter case, the function returns <c>{ok, + RequestId}</c> and then the information is delivered to the + <c>receiver</c> depending on that value.</p> + <p>When <c><anno>Profile</anno></c> is <c>stand_alone</c> only the pid can be used.</p> + <p>HTTP options:</p> - <p>HTTP option (<c>http_option()</c>) details:</p> - <marker id="request2_http_options"></marker> <taglist> - <tag><c><![CDATA[timeout]]></c></tag> + <tag><c>timeout</c></tag> <item> <p>Time-out time for the request.</p> <p>The clock starts ticking when the request is sent.</p> <p>Time is in milliseconds.</p> <p>Default is <c>infinity</c>.</p> - </item> + </item> - <tag><c><![CDATA[connect_timeout]]></c></tag> + <tag><c>connect_timeout</c></tag> <item> - <p>Connection time-out time, used during the initial request, - when the client is <em>connecting</em> to the server.</p> + <p>Connection time-out time, used during the initial request, + when the client is <em>connecting</em> to the server.</p> <p>Time is in milliseconds.</p> <p>Default is the value of option <c>timeout</c>.</p> - </item> + </item> - <tag><c><![CDATA[ssl]]></c></tag> + <tag><c>ssl</c></tag> <item> <p>This is the <c>SSL/TLS</c> connecting configuration option.</p> <p>Defaults to <c>[]</c>. See <seeerl marker="ssl:ssl">ssl:connect/[2,3,4]</seeerl> for available options.</p> - </item> + </item> - <tag><c><![CDATA[autoredirect]]></c></tag> + <tag><c>autoredirect</c></tag> <item> - <p>The client automatically retrieves the information - from the new URI and returns that as the result, instead - of a 30X-result code.</p> - <p>For some 30X-result codes, automatic redirect - is not allowed. In these cases the 30X-result is always - returned.</p> - <p>Default is <c>true</c>.</p> - </item> - - <tag><c><![CDATA[proxy_auth]]></c></tag> + <p>The client automatically retrieves the information from the new + URI and returns that as the result, instead of a 30X-result + code.</p> + <p>For some 30X-result codes, automatic redirect is not allowed. In + these cases the 30X-result is always returned.</p> + <p>Default is <c>true</c>.</p> + </item> + + <tag><c>proxy_auth</c></tag> <item> - <p>A proxy-authorization header using the provided username and - password is added to the request.</p> - </item> + <p>A proxy-authorization header using a tuple where the first element is the <c>username</c> and + the second element of the tuple is the <c>password</c> added to the request.</p> + </item> - <tag><c><![CDATA[version]]></c></tag> + <tag><c>version</c></tag> <item> <p>Can be used to make the client act as an <c>HTTP/1.0</c> client. By default this is an <c>HTTP/1.1</c> client. When using <c>HTTP/1.0</c> persistent connections are not used.</p> <p>Default is the string <c>"HTTP/1.1"</c>.</p> - </item> + </item> - <tag><c><![CDATA[relaxed]]></c></tag> + <tag><c>relaxed</c></tag> <item> - <p>If set to <c>true</c>, workarounds for known server deviations - from the HTTP-standard are enabled.</p> + <p>If set to <c>true</c>, workarounds for known server deviations + from the HTTP-standard are enabled.</p> <p>Default is <c>false</c>.</p> - </item> + </item> </taglist> - <p>Option (<c>option()</c>) details:</p> + <p>Options details:</p> <taglist> - <tag><c><![CDATA[sync]]></c></tag> + <tag><c>sync</c></tag> <item> <p>Option for the request to be synchronous or asynchronous.</p> <p>Default is <c>true</c>.</p> - </item> + </item> - <tag><c><![CDATA[stream]]></c></tag> + <tag><c>stream</c></tag> <item> - <p>Streams the body of a 200 or 206 response to the calling - process or to a file. When streaming to the calling process - using option <c>self</c>, the following stream messages - are sent to that process: <c>{http, {RequestId, - stream_start, Headers}}, {http, {RequestId, stream, - BinBodyPart}}, and {http, {RequestId, stream_end, Headers}}</c>.</p> - <p>When streaming to the calling processes using option - <c>{self, once}</c>, the first message has an extra - element, that is, <c>{http, {RequestId, stream_start, Headers, Pid}}</c>. - This is the process id to be used as an argument to - <c>httpc:stream_next/1</c> to trigger the next message to be sent to - the calling process.</p> - <p>Notice that chunked encoding can add - headers so that there are more headers in the <c>stream_end</c> - message than in <c>stream_start</c>. - When streaming to a file and the request is asynchronous, the - message <c>{http, {RequestId, saved_to_file}}</c> is sent.</p> + <p>Streams the body of a 200 or 206 response to the calling process + or to a file. When streaming to the calling process using option + <c>self</c>, the following stream messages are sent to that process: + <c>{http, {RequestId, stream_start, Headers}}, {http, {RequestId, + stream, BinBodyPart}}, and {http, {RequestId, stream_end, + Headers}}</c>.</p> + + <p>When streaming to the calling processes using option <c>{self, + once}</c>, the first message has an extra element, that is, + <c>{http, {RequestId, stream_start, Headers, Pid}}</c>. This is the + process id to be used as an argument to <c>httpc:stream_next/1</c> + to trigger the next message to be sent to the calling process.</p> + + <p>Notice that chunked encoding can add headers so that there are + more headers in the <c>stream_end</c> message than in + <c>stream_start</c>. When streaming to a file and the request is + asynchronous, the message <c>{http, {RequestId, saved_to_file}}</c> + is sent.</p> <p>Default is <c>none</c>.</p> - </item> + </item> - <tag><c><![CDATA[body_format]]></c></tag> + <tag><c>body_format</c></tag> <item> - <p>Defines if the body is to be delivered as a string or - binary. This option is only valid for the synchronous - request.</p> + <p>Defines if the body is to be delivered as a string or + binary. This option is only valid for the synchronous + request.</p> <p>Default is <c>string</c>.</p> - </item> + </item> - <tag><c><![CDATA[full_result]]></c></tag> + <tag><c>full_result</c></tag> <item> - <p>Defines if a "full result" is to be returned to the caller (that is, - the body, the headers, and the entire status line) or not - (the body and the status code).</p> + <p>Defines if a "full result" is to be returned to the caller (that + is, the body, the headers, and the entire status line) or not (the + body and the status code).</p> <p>Default is <c>true</c>.</p> - </item> + </item> - <tag><c><![CDATA[headers_as_is]]></c></tag> + <tag><c>headers_as_is</c></tag> <item> - <p>Defines if the headers provided by the user are to be made - lower case or to be regarded as case sensitive.</p> - <p>The HTTP standard requires them to be - case insensitive. Use this feature only if there is - no other way to communicate with the server or for testing - purpose. When this option is used, no headers - are automatically added. All necessary headers must be - provided by the user.</p> - <p>Default is <c>false</c>.</p> - </item> - - <tag><c><![CDATA[socket_opts]]></c></tag> + <p>Defines if the headers provided by the user are to be made lower + case or to be regarded as case sensitive.</p> + + <p>The HTTP standard requires them to be case insensitive. Use this + feature only if there is no other way to communicate with the server + or for testing purpose. When this option is used, no headers are + automatically added. All necessary headers must be provided by the + user.</p> + <p>Default is <c>false</c>.</p> + </item> + + <tag><c>socket_opts</c></tag> <item> <p>Socket options to be used for this request.</p> - <p>Overrides any value set by function - <seemfa marker="#set_options/1">set_options</seemfa>.</p> + <p>See the options used by + <seeerl marker="kernel:gen_tcp">gen_tcp(3)</seeerl> and + <seeerl marker="ssl:ssl">ssl(3)</seeerl> + </p> + <p>Overrides any value set by function + <seemfa marker="#set_options/1">set_options</seemfa>.</p> <p>The validity of the options is <em>not</em> checked by the HTTP client they are assumed to be correct and passed on to ssl application and inet driver, which may reject them if they are not correct. - </p> - <note> - <p> - Persistent connections are not supported when setting the - <c>socket_opts</c> option. When <c>socket_opts</c> is not - set the current implementation assumes the requests to the - same host, port combination will use the same socket options. - </p> - </note> - - <p>By default the socket options set by function - <seemfa marker="#set_options/1">set_options/[1,2]</seemfa> - are used when establishing a connection.</p> - </item> - - <tag><c><![CDATA[receiver]]></c></tag> + </p> + <note> + <p> + Persistent connections are not supported when setting the + <c>socket_opts</c> option. When <c>socket_opts</c> is not set + the current implementation assumes the requests to the same + host, port combination will use the same socket options. + </p> + </note> + + <p>By default the socket options set by function <seemfa + marker="#set_options/1">set_options/[1,2]</seemfa> are used when + establishing a connection.</p> + </item> + + <tag><c>receiver</c></tag> <item> - <p>Defines how the client delivers the result of an - asynchronous request (<c>sync</c> has the value - <c>false</c>).</p> + <p>Defines how the client delivers the result of an asynchronous + request (<c>sync</c> has the value <c>false</c>).</p> <taglist> - <tag><c><![CDATA[pid()]]></c></tag> + <tag><c>pid()</c></tag> <item> - <p>Messages are sent to this process in the format - <c>{http, ReplyInfo}</c>.</p> - </item> + <p>Messages are sent to this process in the format <c>{http, + ReplyInfo}</c>.</p> + </item> - <tag><c><![CDATA[function/1]]></c></tag> + <tag><c>function/1</c></tag> <item> - <p>Information is delivered to the receiver through calls - to the provided fun <c>Receiver(ReplyInfo)</c>.</p> - </item> + <p>Information is delivered to the receiver through calls to the + provided fun <c>Receiver(ReplyInfo)</c>.</p> + </item> - <tag><c><![CDATA[{Module, Function, Args}]]></c></tag> + <tag><c>{Module, Function, Args}</c></tag> <item> - <p>Information is delivered to the receiver through calls - to the callback function - <c>apply(Module, Function, [ReplyInfo | Args])</c>.</p> - </item> + <p>Information is delivered to the receiver through calls to the + callback function <c>apply(Module, Function, [ReplyInfo | + Args])</c>.</p> + </item> </taglist> <p>In all of these cases, <c>ReplyInfo</c> has the following - structure:</p> - -<pre> -{RequestId, saved_to_file} -{RequestId, {error, Reason}} -{RequestId, Result} -{RequestId, stream_start, Headers} -{RequestId, stream_start, Headers, HandlerPid} -{RequestId, stream, BinBodyPart} -{RequestId, stream_end, Headers}</pre> - - <p>Default is the <c>pid</c> of the process calling the request + structure:</p> + + <pre> + {RequestId, saved_to_file} + {RequestId, {error, Reason}} + {RequestId, Result} + {RequestId, stream_start, Headers} + {RequestId, stream_start, Headers, HandlerPid} + {RequestId, stream, BinBodyPart} + {RequestId, stream_end, Headers}</pre> + <p>Default is the <c>pid</c> of the process calling the request function (<c>self()</c>). </p> - - <marker id="ipv6_host_with_brackets"></marker> - </item> - - <tag><c><![CDATA[ipv6_host_with_brackets]]></c></tag> + <marker id="ipv6_host_with_brackets"></marker> + </item> + <tag><c>ipv6_host_with_brackets</c></tag> <item> - <p>Defines when parsing the Host-Port part of an URI with an IPv6 address - with brackets, if those brackets are to be retained (<c>true</c>) - or stripped (<c>false</c>).</p> + <p>Defines when parsing the Host-Port part of an URI with an IPv6 + address with brackets, if those brackets are to be retained + (<c>true</c>) or stripped (<c>false</c>).</p> <p>Default is <c>false</c>.</p> - </item> - + </item> </taglist> </desc> </func> <func> - <name since="OTP R13B04">set_options(Options) -> </name> - <name since="OTP R13B04">set_options(Options, Profile) -> ok | {error, Reason}</name> + <name since="OTP R13B04" name="set_options" arity="1"/> + <name since="OTP R13B04" name="set_options" arity="2"/> <fsummary>Sets options to be used for subsequent requests.</fsummary> - <type> - <v>Options = [Option]</v> - <v>Option = {proxy, {Proxy, NoProxy}}</v> - <v>| {https_proxy, {Proxy, NoProxy}}</v> - <v>| {max_sessions, MaxSessions}</v> - <v>| {max_keep_alive_length, MaxKeepAlive}</v> - <v>| {keep_alive_timeout, KeepAliveTimeout}</v> - <v>| {max_pipeline_length, MaxPipeline}</v> - <v>| {pipeline_timeout, PipelineTimeout}</v> - <v>| {cookies, CookieMode}</v> - <v>| {ipfamily, IpFamily}</v> - <v>| {ip, IpAddress}</v> - <v>| {port, Port}</v> - <v>| {socket_opts, socket_opts()}</v> - <v>| {verbose, VerboseMode}</v> - <v>| {unix_socket, UnixSocket}</v> - <v>Proxy = {Hostname, Port}</v> - <v>Hostname = http_string()</v> - <d>Example: "localhost" or "foo.bar.se"</d> - <v>Port = integer()</v> - <d>Example: 8080</d> - <v>NoProxy = [NoProxyDesc]</v> - <v>NoProxyDesc = DomainDesc | HostName | IPDesc</v> - <v>DomainDesc = "*.Domain"</v> - <d>Example: "*.ericsson.se"</d> - <v>IpDesc = http_string()</v> - <d>Example: "134.138" or "[FEDC:BA98" - (all IP addresses starting with 134.138 or FEDC:BA98), - "66.35.250.150" or "[2010:836B:4179::836B:4179]" (a complete IP address). - <c>proxy</c> defaults to <c>{undefined, []}</c>, - that is, no proxy is configured and - <c>https_proxy</c> defaults to the value of <c>proxy</c>.</d> - <v>MaxSessions = integer()</v> - <d>Maximum number of persistent connections to a host. - Default is <c>2</c>.</d> - <v>MaxKeepAlive = integer()</v> - <d>Maximum number of outstanding requests on the same connection to - a host. Default is <c>5</c>.</d> - <v>KeepAliveTimeout = integer()</v> - <d>If a persistent connection is idle longer than the - <c>keep_alive_timeout</c> in milliseconds, - the client closes the connection. - The server can also have such a time-out but do not take that for granted. - Default is <c>120000</c> (= 2 min).</d> - <v>MaxPipeline = integer()</v> - <d>Maximum number of outstanding requests on a pipelined connection - to a host. Default is <c>2</c>.</d> - <v>PipelineTimeout = integer()</v> - <d>If a persistent connection is idle longer than the - <c>pipeline_timeout</c> in milliseconds, - the client closes the connection. Default is <c>0</c>, - which results in pipelining not being used.</d> - <v>CookieMode = enabled | disabled | verify</v> - <d>If cookies are enabled, all valid cookies are automatically - saved in the cookie database of the client manager. - If option <c>verify</c> is used, function <c>store_cookies/2</c> - has to be called for the cookies to be saved. - Default is <c>disabled</c>.</d> - <v>IpFamily = inet | inet6 | local</v> - <d>Default is <c>inet</c>.</d> - <v>IpAddress = ip_address()</v> - <d>If the host has several network interfaces, this option specifies - which one to use. - See <seeerl marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seeerl> - for details.</d> - <v>Port = integer()</v> - <d>Local port number to use. - See <seeerl marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seeerl> - for details.</d> - <v>socket_opts() = [socket_opt()]</v> - <d>The options are appended to the socket options used by the - client. - These are the default values when a new request handler - is started (for the initial connect). They are passed directly - to the underlying transport (<c>gen_tcp</c> or <c>SSL</c>) - <em>without</em> verification.</d> - <v>VerboseMode = false | verbose | debug | trace</v> - <d>Default is <c>false</c>. - This option is used to switch on (or off) - different levels of Erlang trace on the client. - It is a debug feature.</d> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c> only the pid can be used.</d> - <v>UnixSocket = path()</v> - <d> - Experimental option for sending HTTP requests over a unix domain socket. The value - of <c>unix_socket</c> shall be the full path to a unix domain socket file with read/write - permissions for the erlang process. Default is <c>undefined</c>. - </d> - </type> <desc> - <p>Sets options to be used for subsequent requests.</p> - <note> - <p>If possible, the client keeps its connections - alive and uses persistent connections - with or without pipeline depending on configuration - and current circumstances. The HTTP/1.1 specification does not - provide a guideline for how many requests that are - ideal to be sent on a persistent connection. - This depends much on the application.</p> - <p>A long queue of requests can cause a - user-perceived delay, as earlier requests can take a long time - to complete. The HTTP/1.1 specification suggests a - limit of two persistent connections per server, which is the - default value of option <c>max_sessions</c>.</p> - <p> - The current implementation assumes the requests to the same host, port - combination will use the same socket options. - </p> - </note> + <p>Sets options to be used for subsequent requests.</p> + <taglist> + <tag><c>HostName</c></tag> + <item> + Example: "localhost" or "foo.bar.se" + </item> + <tag><c>DomainDesc</c></tag> + <item> + Example <c>"*.Domain"</c> or <c>"*.ericsson.se"</c> + </item> + <tag><c>IpAddressDesc</c></tag> + <item> + Example: "134.138" or "[FEDC:BA98" (all IP addresses starting with + 134.138 or FEDC:BA98), "66.35.250.150" or "[2010:836B:4179::836B:4179]" + (a complete IP address). <c>proxy</c> defaults to <c>{undefined, + []}</c>, that is, no proxy is configured and <c>https_proxy</c> defaults + to the value of <c>proxy</c>. + </item> + <tag><c>MaxSessions</c></tag> + <item> + <c><anno>MaxSessions</anno></c> Maximum number of persistent connections to a host. Default is <c>2</c>. + </item> + + <tag><c>MaxKeepAlive</c></tag> + <item> + <c><anno>MaxKeepAlive</anno></c> Maximum number of outstanding requests + on the same connection to a host. Default is <c>5</c>. + </item> + <tag><c>KeepAliveTimeout</c></tag> + <item> + <c><anno>KeepAliveTimeout</anno></c> If a persistent connection is idle longer than the + <c>keep_alive_timeout</c> in milliseconds, the client closes the + connection. The server can also have such a time-out but do not take that + for granted. Default is <c>120000</c> (= 2 min). + </item> + <tag><c>MaxPipeline</c></tag> + <item> + <c><anno>MaxPipeline</anno></c> Maximum number of outstanding requests on a pipelined connection to a + host. Default is <c>2</c>. + </item> + <tag><c>PipelineTimeout</c></tag> + <item> + <c><anno>PipelineTimeout</anno></c> If a persistent connection is idle longer than the + <c>pipeline_timeout</c> in milliseconds, the client closes the + connection. Default is <c>0</c>, which results in pipelining not being + used. + </item> + <tag><c>CookieMode</c></tag> + <item> + If cookies are enabled, all valid cookies are automatically saved in + the cookie database of the client manager. If option <c>verify</c> is + used, function <c>store_cookies/2</c> has to be called for the cookies + to be saved. Default is <c>disabled</c>. + </item> + <tag><c>IpFamily</c></tag> + <item> + Default is <c>inet</c>. With <c>inet6fb4</c> option, IPv6 + will be preferred but if connection fails, an IPv4 fallback connection + attempt will be made. + </item> + <tag><c>IpAddress</c></tag> + <item> + If the host has several network interfaces, this option specifies + which one to use. See + <seeerl marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seeerl> for + details. + </item> + <tag><c>Port</c></tag> + <item> + Example: <c>8080</c>. + Local port number to use. See <seeerl + marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seeerl> for + details. + </item> + <tag><c>SocketOpts</c></tag> + <item> + The options are appended to the socket options used by the client. + These are the default values when a new request handler is started (for + the initial connect). They are passed directly to the underlying + transport (<c>gen_tcp</c> or <c>SSL</c>) without + verification. + <p>See the options used by + <seeerl marker="kernel:gen_tcp">gen_tcp(3)</seeerl> and + <seeerl marker="ssl:ssl">ssl(3)</seeerl> + </p> + </item> + <tag><c>VerboseMode</c></tag> + <item> + Default is <c>false</c>. This option is used to switch on (or off) + different levels of Erlang trace on the client. It is a debug + feature. + </item> + <tag><c>Profile</c></tag> + <item> + When started <c>stand_alone</c> only the pid can be used. + </item> + <tag><c>UnixSocket</c></tag> + <item> + Experimental option for sending HTTP requests over a unix domain + socket. The value of <c>unix_socket</c> shall be the full path to a unix + domain socket file with read/write permissions for the erlang process. + Default is <c>undefined</c>. + </item> + + </taglist> + + <note> + <p>If possible, the client keeps its connections alive and uses + persistent connections with or without pipeline depending on + configuration and current circumstances. The HTTP/1.1 specification + does not provide a guideline for how many requests that are ideal to + be sent on a persistent connection. This depends much on the + application.</p> + <p>A long queue of requests can cause a user-perceived delay, as + earlier requests can take a long time to complete. The HTTP/1.1 + specification suggests a limit of two persistent connections per + server, which is the default value of option <c>max_sessions</c>.</p> + <p>The current implementation assumes the requests to the same host, + port combination will use the same socket options. + </p> + </note> <marker id="get_options"></marker> </desc> </func> - + + <func> + <name since="OTP 25.1" name="ssl_verify_host_options" arity="1"/> + <fsummary>Returns ssl options for host verification.</fsummary> + <desc> + <p>Returns ssl options which can be used to verify the host, uses + <seemfa marker="public_key:public_key#cacerts_get/0"><c>public_key:cacerts_get()</c></seemfa> + to read CA certicates and if <c><anno>WildcardHostName</anno></c> is true adds the hostname check from + <seemfa marker="public_key:public_key#pkix_verify_hostname_match_fun/1"> + <c> public_key:public_key:pkix_verify_hostname_match_fun(https)</c></seemfa> to the options. + </p> + </desc> + </func> + <func> - <name since="OTP R14B02">store_cookies(SetCookieHeaders, Url) -> </name> - <name since="OTP R14B02">store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}</name> + <name since="OTP R14B02" name="store_cookies" arity="2"/> + <name since="OTP R14B02" name="store_cookies" arity="3"/> <fsummary>Saves the cookies defined in <c>SetCookieHeaders</c> in the client profile cookie database.</fsummary> - <type> - <v>SetCookieHeaders = headers() - where field = "set-cookie"</v> - <v>Url = url()</v> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c> only the pid can be used.</d> - </type> + <type_desc variable="SetCookieHeaders"> + Where field = "set-cookie" + </type_desc> + <type_desc variable="Profile"> + When started <c>stand_alone</c> only the pid can be used. + </type_desc> <desc> - <p>Saves the cookies defined in <c>SetCookieHeaders</c> - in the client profile cookie database. - Call this function if option <c>cookies</c> is set to <c>verify</c>. - If no profile is specified, the default profile is used.</p> + <p>Saves the cookies defined in <c>SetCookieHeaders</c> in the client + profile cookie database. Call this function if option <c>cookies</c> is + set to <c>verify</c>. If no profile is specified, the default profile is + used.</p> </desc> </func> <func> - <name since="OTP R13B04">stream_next(Pid) -> ok</name> + <name since="OTP R13B04" name="stream_next" arity="1"/> <fsummary>Triggers the next message to be streamed, that is, the same behavior as active one for sockets. </fsummary> - <type> - <v>Pid = pid()</v> - <d>As received in the <c>stream_start message</c></d> - </type> + <type_desc variable="Pid"> + As received in the <c>stream_start message</c> + </type_desc> <desc> - <p>Triggers the next message to be streamed, that is, - the same behavior as active ones for sockets.</p> - + <p>Triggers the next message to be streamed, that is, the same behavior + as active ones for sockets.</p> <marker id="verify_cookies"></marker> <marker id="store_cookies"></marker> </desc> </func> <func> - <name since="OTP R13B04">which_cookies() -> cookies()</name> - <name since="OTP R13B04">which_cookies(Profile) -> cookies()</name> + <name since="OTP R13B04" name="which_cookies" arity="0"/> + <name since="OTP R13B04" name="which_cookies" arity="1"/> <fsummary>Dumps the entire cookie database.</fsummary> - <type> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c> only the pid can be used.</d> - <v>cookies() = [cookie_stores()]</v> - <v>cookie_stores() = {cookies, cookies()} | {session_cookies, cookies()}</v> - <v>cookies() = [cookie()]</v> - <v>cookie() = term()</v> - </type> + <type_desc variable="Profile"> + When started <c>stand_alone</c> only the pid can be used. + </type_desc> <desc> - <p>Produces a list of the entire cookie database. - Intended for debugging/testing purposes. - If no profile is specified, the default profile is used.</p> + <p>Produces a list of the entire cookie database. Intended for + debugging/testing purposes. If no profile is specified, the default + profile is used.</p> </desc> </func> <func> - <name since="OTP R15B02">which_sessions() -> session_info()</name> - <name since="OTP R15B02">which_sessions(Profile) -> session_info()</name> + <name since="OTP R15B02" name="which_sessions" arity="0"/> + <name since="OTP R15B02" name="which_sessions" arity="1"/> <fsummary>Produces a slightly processed dump of the sessions database.</fsummary> - <type> - <v>Profile = profile() | pid()</v> - <d>When started <c>stand_alone</c> only the pid can be used.</d> - <v>session_info() = {[session()], [term()], [term()]}</v> - <v>session() = term() - Internal representation of a session</v> - </type> + <type_desc variable="Profile"> + When started <c>stand_alone</c> only the pid can be used. + </type_desc> + <type_desc variable="Session"> + Internal representation of a session. + </type_desc> <desc> <p> This function is intended for debugging only. It produces a slightly processed dump of the session database. The first @@ -722,8 +631,6 @@ profile is used.</p> </desc> </func> - - </funcs> <section> diff --git a/lib/inets/doc/src/httpd.xml b/lib/inets/doc/src/httpd.xml index 3b44a66340..118d38ba2a 100644 --- a/lib/inets/doc/src/httpd.xml +++ b/lib/inets/doc/src/httpd.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2021</year> + <year>1997</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -39,7 +39,7 @@ Provides web server start options, administrative functions, and an Erlang callback API.</p> </description> - + <section> <title>DATA TYPES</title> <p>Type definitions that are used more than once in @@ -49,10 +49,10 @@ <p><c>path() = string()</c> representing a file or a directory path</p> <p><c> ip_address() = {N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6</c></p> - <p><c>hostname() = string()</c> representing a host, for example, + <p><c>hostname() = string()</c> representing a host, for example, "foo.bar.com"</p> <p><c>property() = atom()</c></p> - + </section> <section> @@ -75,7 +75,7 @@ term()</c>, followed by a full stop. If the web server is started dynamically at runtime, a file can still be specified but also the complete property list.</p> - + <taglist> <tag><marker id="prop_proplist_file"></marker>{proplist_file, path()}</tag> <item> @@ -94,7 +94,7 @@ <p><em>Mandatory Properties</em></p> <taglist> <tag><marker id="prop_port"></marker>{port, integer()} </tag> - <item> + <item> <p>The port that the HTTP server listen to. If zero is specified as port, an arbitrary available port is picked and function <c>httpd:info/2</c> can be used to @@ -107,8 +107,8 @@ </item> <tag><marker id="prop_server_root"></marker>{server_root, path()}</tag> - <item> - <p>Defines the home directory of the server, where log files, and so on, + <item> + <p>Defines the home directory of the server, where log files, and so on, can be stored. Relative paths specified in other properties refer to this directory.</p> </item> @@ -141,14 +141,19 @@ </p> </item> - <tag><marker id="prop_socket_type"></marker>{socket_type, ip_comm | {ip_comm, Config::proplist()} | {essl, Config::proplist()}}</tag> + <tag><marker id="prop_socket_type"></marker>{socket_type, ip_comm | {ip_comm, Config::proplist()} | {ssl, Config::proplist()}}</tag> <item> - <p>For <c>ip_comm</c> configuration options, see + <p>For <c>ip_comm</c> configuration options, see <seemfa marker="kernel:gen_tcp#listen/2">gen_tcp:listen/2</seemfa>, some options that are used internally by httpd cannot be set.</p> - <p>For <c>SSL</c> configuration options, see + <p>For <c>SSL</c> configuration options, see <seemfa marker="ssl:ssl#listen/2">ssl:listen/2</seemfa>.</p> - <p>Default is <c>ip_comm</c>.</p> + <p>Default is <c>ip_comm</c>.</p> + <note> + <p>OTP-25 deprecates the communication properties <c>{socket_type, ip_comm | {ip_comm, Config::proplist()} | {essl, Config::proplist()}}</c> + replacing it by <c>{socket_type, ip_comm | {ip_comm, Config::proplist()} | {ssl, Config::proplist()}}</c>. + </p> + </note> </item> <tag><marker id="prop_ipfamily"></marker>{ipfamily, inet | inet6}</tag> @@ -156,7 +161,7 @@ <p>Default is <c>inet</c>, legacy option <c>inet6fb4</c> no longer makes sense and will be translated to inet.</p> </item> - + <tag><marker id="prop_minimum_bytes_per_second"></marker>{minimum_bytes_per_second, integer()}</tag> <item> <p>If given, sets a minimum of bytes per second value for connections.</p> @@ -173,53 +178,53 @@ <p>Defines which modules the HTTP server uses when handling requests. Default is <c>[mod_alias, mod_auth, mod_esi, mod_actions, mod_cgi, mod_dir, mod_get, mod_head, mod_log, - mod_disk_log]</c>. + mod_disk_log]</c>. Notice that some <c>mod</c>-modules are dependent on others, so the order cannot be entirely arbitrary. See the <seeguide marker="http_server">Inets Web Server Modules</seeguide> in the User's Guide for details.</p> </item> </taglist> - + <marker id="props_limit"></marker> <p><em>Limit properties</em> </p> <taglist> <tag><marker id="prop_customize"></marker>{customize, atom()}</tag> - <item> + <item> <p>A callback module to customize the inets HTTP servers behaviour see <seeerl marker="httpd_custom_api"> httpd_custom_api</seeerl> </p> </item> - + <tag><marker id="prop_disable_chunked_encoding"></marker>{disable_chunked_transfer_encoding_send, boolean()}</tag> - <item> + <item> <p>Allows you to disable chunked transfer-encoding when sending a response to an HTTP/1.1 client. Default is <c>false</c>.</p> </item> - + <tag><marker id="prop_keep_alive"></marker>{keep_alive, boolean()}</tag> <item> <p>Instructs the server whether to use persistent connections when the client claims to be HTTP/1.1 compliant. Default is <c>true</c>.</p> </item> - + <tag><marker id="prop_keep_alive_timeout"></marker>{keep_alive_timeout, integer()}</tag> <item> <p>The number of seconds the server waits for a subsequent request from the client before closing the connection. Default is <c>150</c>.</p> </item> - + <tag><marker id="prop_max_body_size"></marker>{max_body_size, integer()}</tag> <item> <p>Limits the size of the message body of an HTTP request. Default is no limit.</p> </item> - + <tag><marker id="prop_max_clients"></marker>{max_clients, integer()}</tag> - <item> + <item> <p>Limits the number of simultaneous requests that can be supported. Default is <c>150</c>.</p> </item> @@ -243,44 +248,38 @@ <p>Limits the size of the HTTP request URI. Default is no limit.</p> </item> - + <tag><marker id="prop_max_keep_alive_req"></marker>{max_keep_alive_request, integer()}</tag> <item> <p>The number of requests that a client can do on one connection. When the server has responded to the number of - requests defined by <c>max_keep_alive_requests</c>, the server - closes the connection. The server closes it even if there are + requests defined by <c>max_keep_alive_requests</c>, the server + closes the connection. The server closes it even if there are queued request. Default is no limit.</p> </item> - + <tag><marker id="max_client_body_chunk"></marker>{max_client_body_chunk, integer()}</tag> <item> <p>Enforces chunking of a HTTP PUT or POST body data to be delivered - to the mod_esi callback. Note this is not supported for mod_cgi. + to the mod_esi callback. Note this is not supported for mod_cgi. Default is no limit e.i the whole body is delivered as one entity, which could be very memory consuming. <seeerl marker="mod_esi">mod_esi(3)</seeerl>. </p> </item> - + </taglist> - + <marker id="props_admin"></marker> <p><em>Administrative Properties</em></p> - <taglist> + <taglist> <tag><marker id="prop_mime_types"></marker>{mime_types, [{MimeType, Extension}] | path()}</tag> <item> <p><c>MimeType = string()</c> and <c>Extension = string()</c>. Files delivered to the client are MIME typed according to RFC 1590. File suffixes are mapped to MIME types before file delivery. The mapping between file suffixes and MIME types can be specified - as an Apache-like file or directly in the property list. Such - a file can look like the following:</p> - <pre> -# MIME type Extension -text/html html htm -text/plain asc txt</pre> - + in the property list.</p> <p>Default is [{"html","text/html"},{"htm","text/html"}].</p> </item> @@ -290,7 +289,7 @@ text/plain asc txt</pre> cannot be determined by the MIME Type Settings, the server uses this default type.</p> </item> - + <tag><marker id="prop_server_admin"></marker>{server_admin, string()}</tag> <item> <p>Defines the email-address of the server @@ -301,7 +300,7 @@ text/plain asc txt</pre> <tag><marker id="prop_server_tokens"></marker>{server_tokens, none|prod|major|minor|minimal|os|full|{private, string()}}</tag> <item> <p>Defines the look of the value of the server header.</p> - <p>Example: Assuming the version of <c>Inets</c> is 5.8.1, + <p>Example: Assuming the version of <c>Inets</c> is 5.8.1, the server header string can look as follows for the different values of server-tokens:</p> <taglist> @@ -325,22 +324,22 @@ text/plain asc txt</pre> <p>By default, the value is as before, that is, <c>minimal</c>.</p> </item> - + <tag><marker id="prop_logger"></marker>{logger, Options::list()}</tag> <item> <p>Currently only one option is supported: </p> - + <taglist> <tag><c>{error, ServerID::atom()}</c></tag> - <item> <p>Produces + <item> <p>Produces <seetype marker="kernel:logger#log_event">logger events</seetype> on logger <seetype marker="kernel:logger#level">level error</seetype> under the hierarchical logger <seetype marker="kernel:logger#log_event">domain:</seetype> <c>[otp, inets, httpd, ServerID, error]</c> - The built in logger formatting + The built in logger formatting function produces log entries from the error reports:</p> - + <code> #{server_name => string() protocol => internal | 'TCP' | 'TLS' | 'HTTP', @@ -366,12 +365,12 @@ Transport: TLS </code> <p>Using this option makes mod_log and mod_disk_log error logs redundant.</p> - + <p>Add the filter</p> <code> {fun logger_filters:domain/2, {log,equal,[otp,inets, httpd, ServerID, error]}</code> - + to appropriate logger handler to handle the events. For example to write the error log from an httpd server with a <c>ServerID</c> of <c>my_server</c> to a file you can use the following @@ -389,24 +388,24 @@ Transport: TLS </code> <p>or if you want to add it to the default logger via an API:</p> - + <code>logger:add_handler_filter(default, inets_httpd, {fun logger_filters:domain/2, {log, equal, [otp, inets, httpd, my_server, error]}}).</code> - - </item> - </taglist> - - </item> - + + </item> + </taglist> + + </item> + <tag><marker id="prop_log_format"></marker>{log_format, common | combined}</tag> <item> <p>Defines if access logs are to be written according to the <c>common</c> log format or the extended common log format. The <c>common</c> format is one line looking like this: - <c>remotehost rfc931 authuser [date] "request" status bytes</c>.</p> + <c>remotehost rfc931 authuser [date] "request" status bytes</c>.</p> <p>Here:</p> <taglist> <tag><c>remotehost</c></tag> @@ -431,90 +430,90 @@ Transport: TLS <taglist> <tag><c>"referer"</c></tag> <item>The URL the client was on before - requesting the URL (if it could not be determined, + requesting the URL (if it could not be determined, a minus sign is placed in this field).</item> <tag><c>"user_agent"</c></tag> <item>The software the client claims to be using (if it could not be determined, a minus sign is placed in this field).</item> </taglist> - - <p>This affects the access logs written by <c>mod_log</c> and + + <p>This affects the access logs written by <c>mod_log</c> and <c>mod_disk_log</c>. - </p> - </item> + </p> + </item> <tag><marker id="prop_elog_format"></marker>{error_log_format, pretty | compact}</tag> <item> <p>Default is <c>pretty</c>. If the error log is meant to be read directly by a human, <c>pretty</c> is the best option.</p> <p><c>pretty</c> has a format corresponding to:</p> - + <code>io:format("[~s] ~s, reason: ~n ~p ~n~n", [Date, Msg, Reason]).</code> <p><c>compact</c> has a format corresponding to:</p> - + <code>io:format("[~s] ~s, reason: ~w ~n", [Date, Msg, Reason]).</code> - <p>This affects the error logs written by <c>mod_log</c> and + <p>This affects the error logs written by <c>mod_log</c> and <c>mod_disk_log</c>. </p> </item> - + </taglist> - + <marker id="props_alias"></marker> <p><em>URL Aliasing Properties - Requires mod_alias</em></p> <taglist> <tag><marker id="prop_alias"></marker>{alias, {Alias, RealName}}</tag> <item> - <p><c>Alias = string()</c> and <c>RealName = string()</c>. + <p><c>Alias = string()</c> and <c>RealName = string()</c>. <c>alias</c> allows documents to be stored in the local file system instead of the <c>document_root</c> location. URLs with a path beginning with url-path is mapped to local files beginning with directory-filename, for example:</p> - + <code>{alias, {"/image", "/ftp/pub/image"}}</code> - + <p>Access to http://your.server.org/image/foo.gif would refer to the file /ftp/pub/image/foo.gif.</p> </item> - <tag><marker id="prop_re_write"></marker>{re_write, {Re, Replacement}}</tag> + <tag><marker id="prop_re_write"></marker>{re_write, {Re, Replacement}}</tag> <item> - <p><c>Re = string()</c> and <c>Replacement = string()</c>. + <p><c>Re = string()</c> and <c>Replacement = string()</c>. <c>re_write</c> allows documents to be stored in the local file system instead of the <c>document_root</c> location. URLs are rewritten by <c>re:replace/3</c> to produce a path in the local file-system, for example:</p> - + <code>{re_write, {"^/[~]([^/]+)(.*)$", "/home/\\1/public\\2"}}</code> - + <p>Access to http://your.server.org/~bob/foo.gif would refer to the file /home/bob/public/foo.gif. </p> </item> - <tag><marker id="prop_dir_idx"></marker>{directory_index, [string()]}</tag> - <item> + <tag><marker id="prop_dir_idx"></marker>{directory_index, [string()]}</tag> + <item> <p><c>directory_index</c> specifies a list of resources to look for if a client requests a directory using a <c>/</c> at the end of the directory name. <c>file</c> depicts the name of a file in the directory. Several files can be given, in which case the server returns the first it finds, for example:</p> - + <code>{directory_index, ["index.html", "welcome.html"]}</code> - + <p>Access to http://your.server.org/docs/ would return http://your.server.org/docs/index.html or http://your.server.org/docs/welcome.html if index.html does not exist.</p> - </item> + </item> </taglist> <marker id="props_cgi"></marker> <p><em>CGI Properties - Requires mod_cgi</em></p> - <taglist> + <taglist> <tag><marker id="prop_script_alias"></marker>{script_alias, {Alias, RealName}}</tag> <item> <p><c>Alias = string()</c> and <c>RealName = string()</c>. @@ -522,13 +521,13 @@ Transport: TLS they also mark the target directory as containing CGI scripts. URLs with a path beginning with url-path are mapped to scripts beginning with directory-filename, for example:</p> - + <code>{script_alias, {"/cgi-bin/", "/web/cgi-bin/"}}</code> - + <p>Access to http://your.server.org/cgi-bin/foo would cause the server to run the script /web/cgi-bin/foo.</p> </item> - + <tag><marker id="prop_script_re_write"></marker>{script_re_write, {Re, Replacement}}</tag> <item> <p><c>Re = string()</c> and <c>Replacement = string()</c>. @@ -536,21 +535,21 @@ Transport: TLS they also mark the target directory as containing CGI scripts. URLs with a path beginning with url-path are mapped to scripts beginning with directory-filename, for example:</p> - + <code>{script_re_write, {"^/cgi-bin/(\\d+)/", "/web/\\1/cgi-bin/"}}</code> - + <p>Access to http://your.server.org/cgi-bin/17/foo would cause the server to run the script /web/17/cgi-bin/foo.</p> </item> - + <tag><marker id="prop_script_nocache"></marker>{script_nocache, boolean()}</tag> - <item> + <item> <p>If <c>script_nocache</c> is set to <c>true</c>, the HTTP server by default adds the header fields necessary to prevent proxies from - caching the page. Generally this is preferred. + caching the page. Generally this is preferred. Default to <c>false</c>.</p> </item> - + <tag><marker id="prop_script_timeout"></marker>{script_timeout, integer()}</tag> <item> <p>The time in seconds the web server waits between each @@ -558,7 +557,7 @@ Transport: TLS any data before the timeout, the connection to the client is closed. Default is <c>15</c>.</p> </item> - + <tag><marker id="prop_action"></marker>{action, {MimeType, CgiScript}} - requires mod_action</tag> <item> <p><c>MimeType = string()</c> and <c>CgiScript = string()</c>. @@ -582,24 +581,24 @@ Transport: TLS the standard CGI PATH_INFO and PATH_TRANSLATED environment variables.</p> <p>Example:</p> - + <code>{script, {"PUT", "/cgi-bin/put"}}</code> - + </item> </taglist> - + <marker id="props_esi"></marker> <p><em>ESI Properties - Requires mod_esi</em></p> <taglist> - <tag><marker id="prop_esi_alias"></marker>{erl_script_alias, {URLPath, [AllowedModule]}}</tag> + <tag><marker id="prop_esi_alias"></marker>{erl_script_alias, {URLPath, [AllowedModule]}}</tag> <item> <p><c>URLPath = string()</c> and <c>AllowedModule = atom()</c>. <c>erl_script_alias</c> marks all URLs matching url-path as erl scheme scripts. A matching URL is mapped into a specific module and function, for example:</p> - + <code>{erl_script_alias, {"/cgi-bin/example", [httpd_example]}}</code> - + <p>A request to http://your.server.org/cgi-bin/example/httpd_example:yahoo would refer to httpd_example:yahoo/3 or, if that does not exist, @@ -613,7 +612,7 @@ Transport: TLS <p>If <c>erl_script_nocache</c> is set to <c>true</c>, the server adds HTTP header fields preventing proxies from caching the page. This is generally a good idea for dynamic content, as - the content often varies between each request. + the content often varies between each request. Default is <c>false</c>.</p> </item> @@ -625,7 +624,7 @@ Transport: TLS for scripts that use the erl scheme.</p> </item> </taglist> - + <marker id="props_log"></marker> <p><em>Log Properties - Requires mod_log</em></p> <taglist> @@ -644,7 +643,7 @@ Transport: TLS </item> <tag><marker id="prop_tlog"></marker>{transfer_log, path()}</tag> - <item> + <item> <p>Defines the filename of the access log file to be used to log incoming requests. If the filename does not begin with a slash (/), it is assumed to be relative to the <c>server_root</c>.</p> @@ -690,24 +689,24 @@ Transport: TLS <tag><marker id="prop_sdlog_size"></marker>{security_disk_log_size, {MaxBytes, MaxFiles}}</tag> <item> - <p><c>MaxBytes = integer()</c> and <c>MaxFiles = integer()</c>. + <p><c>MaxBytes = integer()</c> and <c>MaxFiles = integer()</c>. Defines the properties of the <c>disk_log(3)</c> access log file. This file is of type wrap log and max bytes is written to each file and max files is used before the first file is truncated and reused.</p> </item> - <tag><marker id="prop_tdlog"></marker>{transfer_disk_log, path()}</tag> + <tag><marker id="prop_tdlog"></marker>{transfer_disk_log, path()}</tag> <item> <p>Defines the filename of the (<c>disk_log(3)</c>) access log file logging incoming requests. If the filename does not begin with a slash (/), it is assumed to be relative to the <c>server_root</c>.</p> </item> - + <tag><marker id="prop_tdlog_size"></marker>{transfer_disk_log_size, {MaxBytes, MaxFiles}}</tag> <item> - <p><c>MaxBytes = integer()</c> and <c>MaxFiles = integer()</c>. + <p><c>MaxBytes = integer()</c> and <c>MaxFiles = integer()</c>. Defines the properties of the <c>disk_log(3)</c> access log file. This file is of type wrap log and max bytes is written to each file and max files is @@ -723,26 +722,26 @@ Transport: TLS <marker id="props_dir"></marker> <p>The properties for directories are as follows:</p> - + <taglist> <tag><marker id="prop_allow_from"></marker>{allow_from, all | [RegxpHostString]}</tag> <item> <p>Defines a set of hosts to be granted access to a given directory, for example:</p> - + <code>{allow_from, ["123.34.56.11", "150.100.23"]}</code> - + <p>The host <c>123.34.56.11</c> and all machines on the <c>150.100.23</c> subnet are allowed access.</p> </item> - + <tag><marker id="prop_deny_from"></marker>{deny_from, all | [RegxpHostString]}</tag> <item> <p>Defines a set of hosts to be denied access to a given directory, for example:</p> - + <code>{deny_from, ["123.34.56.11", "150.100.23"]}</code> - + <p>The host <c>123.34.56.11</c> and all machines on the <c>150.100.23</c> subnet are not allowed access.</p> </item> @@ -765,9 +764,9 @@ Transport: TLS by the non-encrypted password. If usernames are duplicated, the behavior is undefined.</p> <p>Example:</p> - + <code> ragnar:s7Xxv7 - edward:wwjau8 </code> + edward:wwjau8 </code> <p>If the Dets storage method is used, the user database is maintained by Dets and must not be edited by hand. Use the @@ -778,7 +777,7 @@ Transport: TLS server. If it is placed in the directory that it protects, clients can download it.</p> </item> - + <tag><marker id="prop_auth_group_file"></marker>{auth_group_file, path()}</tag> <item> <p>Sets the name of a file containing the list of user @@ -788,9 +787,9 @@ Transport: TLS each line contains a group name followed by a colon, followed by the members usernames separated by spaces.</p> <p>Example:</p> - + <code>group1: bob joe ante</code> - + <p>If the Dets storage method is used, the group database is maintained by Dets and must not be edited by hand. Use the API for module <c>mod_auth</c> to create/edit the group database. @@ -802,9 +801,9 @@ Transport: TLS </item> <tag><marker id="prop_auth_name"></marker>{auth_name, string()}</tag> - <item> + <item> <p>Sets the name of the authorization realm (auth-domain) for - a directory. This string informs the client about which + a directory. This string informs the client about which username and password to use.</p> </item> @@ -817,9 +816,9 @@ Transport: TLS web server is started. Otherwise it is written in clear text in the configuration file.</p> </item> - + <tag><marker id="prop_req_user"></marker>{require_user, [string()]}</tag> - <item> + <item> <p>Defines users to grant access to a given directory using a secret password.</p> </item> @@ -829,26 +828,26 @@ Transport: TLS <p>Defines users to grant access to a given directory using a secret password.</p> </item> - + </taglist> <marker id="props_sec"></marker> <p><em>Security Properties - Requires mod_security</em></p> - + <marker id="prop_sec_dir"></marker> <p><em>{security_directory, {path(), [{property(), term()}]}}</em></p> - + <marker id="props_sdir"></marker> <p>The properties for the security directories are as follows:</p> <taglist> - <tag><marker id="prop_data_file"></marker>{data_file, path()}</tag> + <tag><marker id="prop_data_file"></marker>{data_file, path()}</tag> <item> <p>Name of the security data file. The filename can either be absolute or relative to the <c>server_root</c>. This file is used to store persistent data for module <c>mod_security</c>.</p> </item> - - <tag><marker id="prop_max_retries"></marker>{max_retries, integer()}</tag> + + <tag><marker id="prop_max_retries"></marker>{max_retries, integer()}</tag> <item> <p>Specifies the maximum number of attempts to authenticate a user before the user is blocked out. If a user @@ -856,45 +855,41 @@ Transport: TLS user receives a 403 (Forbidden) response from the server. If the user makes a failed attempt while blocked, the server returns 401 (Unauthorized), for security - reasons. + reasons. Default is <c>3</c>. Can be set to infinity.</p> </item> - + <tag><marker id="prop_block_time"></marker>{block_time, integer()}</tag> <item> <p>Specifies the number of minutes a user is blocked. After this time has passed, the user automatically regains access. Default is <c>60</c>.</p> </item> - + <tag><marker id="prop_fail_exp_time"></marker>{fail_expire_time, integer()}</tag> <item> <p>Specifies the number of minutes a failed user authentication is remembered. If a user authenticates after this time has passed, the previous failed authentications are - forgotten. + forgotten. Default is <c>30</c>.</p> </item> - + <tag><marker id="prop_auth_timeout"></marker>{auth_timeout, integer()}</tag> <item> Specifies the number of seconds a successful user authentication is remembered. After this time has passed, the authentication is no longer reported. Default is <c>30</c>. </item> - </taglist> + </taglist> </section> + <funcs> <func> - <name since="">info(Pid) -></name> - <name since="">info(Pid, Properties) -> [{Option, Value}]</name> + <name since="" name="info" arity="1" /> + <name since="" name="info" arity="2" clause_i="1"/> <fsummary>Fetches information about the HTTP server.</fsummary> - <type> - <v>Properties = [property()]</v> - <v>Option = property()</v> - <v>Value = term()</v> - </type> <desc> <p>Fetches information about the HTTP server. When called with only the pid, all properties are fetched. When called @@ -912,43 +907,28 @@ Transport: TLS </func> <func> - <name since="">info(Address, Port) -> </name> - <name since="">info(Address, Port, Profile) -> </name> - <name since="OTP 18.0">info(Address, Port, Profile, Properties) -> [{Option, Value}] </name> - <name since="">info(Address, Port, Properties) -> [{Option, Value}] </name> + <name since="" name="info" arity="2" clause_i="2"/> + <name since="" name="info" arity="3" clause_i="1"/> + <name since="" name="info" arity="3" clause_i="2"/> + <name since="OTP 18.0" name="info" arity="4" /> <fsummary>Fetches information about the HTTP server.</fsummary> - <type> - <v>Address = ip_address()</v> - <v>Port = integer()</v> - <v>Profile = atom()</v> - <v>Properties = [property()]</v> - <v>Option = property()</v> - <v>Value = term()</v> - </type> <desc> - <p>Fetches information about the HTTP server. When called with - only <c>Address</c> and <c>Port</c>, all properties are - fetched. When called with a list of specific properties, they - are fetched. The available properties are the same as the - start options of the server. - </p> - - <note><p>The address must be the IP address and cannot be - the hostname. - </p></note> + <p>Fetches information about the HTTP server. When called with only + <c><anno>Address</anno></c> and <c><anno>Port</anno></c>, all properties + are fetched. When called with a list of specific properties, they are + fetched. The available properties are the same as the start options of + the server. + </p> + + <note><p>The <c>Address</c> must be the IP address and + cannot be the hostname. </p></note> </desc> </func> <func> - <name since="">reload_config(Config, Mode) -> ok | {error, Reason}</name> + <name since="" name="reload_config" arity="2"/> <fsummary>Reloads the HTTP server configuration without restarting the server.</fsummary> - <type> - <v>Config = path() | [{Option, Value}]</v> - <v>Option = property()</v> - <v>Value = term()</v> - <v>Mode = non_disturbing | disturbing</v> - </type> <desc> <p>Reloads the HTTP server configuration without restarting the server. Incoming requests are answered with a temporary @@ -1163,19 +1143,13 @@ Transport: TLS <title>ERLANG WEB SERVER API HELP FUNCTIONS</title> </fsdescription> <func> - <name since="">parse_query(QueryString) -> [{Key,Value}]</name> + <name since="" name="parse_query" arity="1"/> <fsummary>Parses incoming data to <c>erl</c> and <c>eval</c> scripts.</fsummary> - <type> - <v>QueryString = string()</v> - <v>Key = string()</v> - <v>Value = string()</v> - </type> <desc> <p><c>parse_query/1</c> parses incoming data to <c>erl</c> and - <c>eval</c> scripts (see <seeerl marker="mod_esi">mod_esi(3)</seeerl>) - as defined in the standard - URL format, that is, '+' becomes 'space' and decoding of - hexadecimal characters (<c>%xx</c>).</p> + <c>eval</c> scripts (see <seeerl marker="mod_esi">mod_esi(3)</seeerl>) + as defined in the standard URL format, that is, '+' becomes 'space' and + decoding of hexadecimal characters (<c>%xx</c>).</p> </desc> </func> </funcs> diff --git a/lib/inets/doc/src/httpd_util.xml b/lib/inets/doc/src/httpd_util.xml index 60a147399d..a334ec9f86 100644 --- a/lib/inets/doc/src/httpd_util.xml +++ b/lib/inets/doc/src/httpd_util.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2021</year> + <year>1997</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -35,7 +35,8 @@ <description> <p>This module provides the Erlang web server API module programmer with miscellaneous utility functions.</p> - + <note><p>Note the module is only recommended for using with httpd - for other + cases it should be considered as deprecated.</p></note> <marker id="convert_request_date"></marker> </description> @@ -263,7 +264,10 @@ <name since="">reason_phrase(StatusCode) -> Description</name> <fsummary>Returns the description of an HTTP 1.1 status code.</fsummary> <type> - <v>StatusCode = 100| 200 | 201 | 202 | 204 | 205 | 206 | 300 | 301 | 302 | 303 | 304 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 410 411 | 412 | 413 | 414 415 | 416 | 417 | 500 | 501 | 502 | 503 | 504 | 505</v> + <v>StatusCode = 100 | 200 | 201 | 202 | 204 | 205 | 206 | 300 | 301 | + 302 | 303 | 304 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | + 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 500 | 501 | 502 | + 503 | 504 | 505</v> <v>Description = string()</v> </type> <desc> diff --git a/lib/inets/doc/src/mod_esi.xml b/lib/inets/doc/src/mod_esi.xml index 8018e7433d..9bdaac7a95 100644 --- a/lib/inets/doc/src/mod_esi.xml +++ b/lib/inets/doc/src/mod_esi.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2021</year> + <year>1997</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -177,24 +177,7 @@ any data that it needs to keep track of when handling the chunks. </p> </desc> - </func> - - <func> - <name since="">Module:Function(Env, Input)-> Response </name> - <fsummary>Creates a dynamic web page and returns it as a list. - This function is deprecated and is only kept for backwards compatibility.</fsummary> - <type> - <v>Env = env()</v> - <v>Input = string() </v> - <v>Response = string()</v> - </type> - <desc> - <p>This callback format consumes much memory, as the - whole response must be generated before it is sent to the - user. This callback format is deprecated. - For new development, use <c>Module:Function/3</c>.</p> - </desc> - </func> + </func> </funcs> </erlref> diff --git a/lib/inets/doc/src/notes.xml b/lib/inets/doc/src/notes.xml index 867980a3bd..d935ad2f11 100644 --- a/lib/inets/doc/src/notes.xml +++ b/lib/inets/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2002</year><year>2022</year> + <year>2002</year><year>2023</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -33,7 +33,282 @@ <file>notes.xml</file> </header> - <section><title>Inets 7.5.3</title> + <section><title>Inets 8.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + With this change, handling of URI to a folder, with + missing trailing / and a query component present is + fixed.</p> + <p> + Own Id: OTP-18472 Aux Id: DAFH-1592 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Adds more type information to the <c>inets</c> app, thus + improving the errors that static analysis tools can + detect.</p> + <p> + The addition of type information to records and the + updates to function heads help static analysis tools to + understand that some values in the records cannot be + <c>'undefined'</c>, thus making static tools to type + check correctly more modules in the <c>inets</c> app</p> + <p> + Own Id: OTP-18390 Aux Id: PR-6661 </p> + </item> + <item> + <p> + Replace size/1 with either tuple_size/1 or byte_size/1</p> + <p> + The <c>size/1</c> BIF is not optimized by the JIT, and + its use can result in worse types for Dialyzer.</p> + <p> + When one knows that the value being tested must be a + tuple, <c>tuple_size/1</c> should always be preferred.</p> + <p> + When one knows that the value being tested must be a + binary, <c>byte_size/1</c> should be preferred. However, + <c>byte_size/1</c> also accepts a bitstring (rounding up + size to a whole number of bytes), so one must make sure + that the call to <c>byte_size/</c> is preceded by a call + to <c>is_binary/1</c> to ensure that bitstrings are + rejected. Note that the compiler removes redundant calls + to <c>is_binary/1</c>, so if one is not sure whether + previous code had made sure that the argument is a + binary, it does not harm to add an <c>is_binary/1</c> + test immediately before the call to <c>byte_size/1</c>.</p> + <p> + Own Id: OTP-18432 Aux Id: + GH-6672,PR-6793,PR-6784,PR-6787,PR-6785,PR-6682,PR-6800,PR-6797,PR-6798,PR-6799,PR-6796,PR-6813,PR-6671,PR-6673,PR-6684,PR-6694,GH-6677,PR-6696,PR-6670,PR-6674 </p> + </item> + </list> + </section> + +</section> + +<section><title>Inets 8.2.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Ensure graceful shutdown</p> + <p> + Own Id: OTP-18461 Aux Id: ERIERL-890 </p> + </item> + <item> + <p> + Return type of the type specification for function + <c>httpc:cookie_header/{1,2,3}</c> has been fixed from + <c>-spec cookie_header(url()) -> [{ field(), value() + }] | {error, Reason}</c> to <c>-spec cookie_header(url()) + -> { field(), value() } | {error, Reason}</c></p> + <p> + Own Id: OTP-18462 Aux Id: GH-6846 </p> + </item> + </list> + </section> + +</section> + +<section><title>Inets 8.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + fixes a missing case of the type specification for + httpd:info/2/3/4</p> + <p> + Own Id: OTP-18362 Aux Id: GH-6558, ERIERL-895 </p> + </item> + </list> + </section> + +</section> + +<section><title>Inets 8.2</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + This change allows body requests to + <c>httpc:request/5</c> be an <c>iolist()</c></p> + <p> + Own Id: OTP-18250</p> + </item> + <item> + <p> + addition of type specs in <c>httpc.erl</c></p> + <p> + Own Id: OTP-18251 Aux Id: GH-6245 </p> + </item> + <item> + <p> + httpc: Add support for HTTP 308 status code</p> + <p> + Own Id: OTP-18280 Aux Id: GH-6290, PR-6291 </p> + </item> + </list> + </section> + +</section> + +<section><title>Inets 8.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Add <c>httpc:ssl_verify_host_options/1</c> to help + setting default ssl options for the https client.</p> + <p> + Own Id: OTP-18118</p> + </item> + <item> + <p> + This change fixes dialyzer warnings generated for + inets/httpd examples (includes needed adjustment of spec + for ssh_sftp module).</p> + <p> + Own Id: OTP-18178 Aux Id: ERIERL-833, ERIERL-834, + ERIERL-835 </p> + </item> + <item> + <p> + Remove documentation of no longer supported callback.</p> + <p> + Own Id: OTP-18193 Aux Id: GH-6122 </p> + </item> + </list> + </section> + +</section> + +<section><title>Inets 8.0</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Adjust uri_string:normalize behavior for URIs with + undefined port (URI string with a port colon but no port + value or URI map with port => undefined).</p> + <p> + Remove redundant normalization from http_request module.</p> + <p> + Before this change, normalize would not remove port + subcomponent in such cases and could for example return + "http://localhost:" URI.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-17627</p> + </item> + <item> + <p> + Fixed typo in Reason term returned from + httpc_handler:handle_http_body.</p> + <p> + After this change, could_not_establish_ssl_tunnel atom is + returned within Reason term.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-17889</p> + </item> + <item> + <p> + With this change, inet6fb4 option is documented for + inets/httpc. Option can be used when IP family needs to + be discovered by a connection attempt.</p> + <p> + Own Id: OTP-18063 Aux Id: ERIERL-798 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + This change removes deprecated functions: + http_uri:parse/1, http_uri:parse/2 and + http_uri:scheme_defaults/0.</p> + <p> + This change delays until OTP-26 removal of deprecated + functions: http_uri:encode/1 and http_uri:decode/1.</p> + <p> + This change marks httpd_util:decode_hex/1 and + httpd_util:encode_hex/1 as deprecated.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-17866</p> + </item> + <item> + <p> + After this change, connect_timeout value is re-used when + upgrading TCP connection to TLS over a proxy.</p> + <p> + Own Id: OTP-17997 Aux Id: GH-5782 </p> + </item> + <item> + <p> + Remove reference to unsupported Apache-like config file + from httpd manual.</p> + <p> + Own Id: OTP-18088 Aux Id: GH-5276 </p> + </item> + </list> + </section> + +</section> + + <section><title>Inets 7.5.3.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + With this change, handling of URI to a folder, with + missing trailing / and a query component present is + fixed.</p> + <p> + Own Id: OTP-18472 Aux Id: DAFH-1592 </p> + </item> + </list> + </section> + +</section> + + <section><title>Inets 7.5.3.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Remove documentation of no longer supported callback.</p> + <p> + Own Id: OTP-18193 Aux Id: GH-6122 </p> + </item> + </list> + </section> + +</section> + +<section><title>Inets 7.5.3</title> <section><title>Fixed Bugs and Malfunctions</title> <list> @@ -233,6 +508,21 @@ </section> + <section><title>Inets 7.3.2.3</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Remove documentation of no longer supported callback.</p> + <p> + Own Id: OTP-18193 Aux Id: GH-6122 </p> + </item> + </list> + </section> + +</section> + <section><title>Inets 7.3.2.2</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -2568,8 +2858,7 @@ <p>Utility module <seeerl marker="http_uri">http_uri</seeerl> now officially supported. </p> - <p>Also, the - <seeerl marker="http_uri#parse">parse</seeerl> + <p>Also, the <c>http_uri:parse</c> function has been extended with more scheme support and a way to provide your own scheme info. </p> <p>Own Id: OTP-9983</p> diff --git a/lib/inets/doc/src/specs.xml b/lib/inets/doc/src/specs.xml new file mode 100644 index 0000000000..82f2f4cfc2 --- /dev/null +++ b/lib/inets/doc/src/specs.xml @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="utf-8" ?> +<specs xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include href="../specs/specs_inets.xml"/> + <xi:include href="../specs/specs_http_uri.xml"/> + <xi:include href="../specs/specs_httpc.xml"/> + <xi:include href="../specs/specs_httpd.xml"/> + <xi:include href="../specs/specs_httpd_custom_api.xml"/> + <xi:include href="../specs/specs_httpd_socket.xml"/> + <xi:include href="../specs/specs_httpd_util.xml"/> + <xi:include href="../specs/specs_mod_alias.xml"/> + <xi:include href="../specs/specs_mod_auth.xml"/> + <xi:include href="../specs/specs_mod_esi.xml"/> + <xi:include href="../specs/specs_mod_security.xml"/> +</specs> |