From f08c0bd8ea265727aa11238855699a5bd89a1b4e Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Mon, 13 Jan 2025 16:24:27 +0100 Subject: [PATCH 1/8] ssh: polish docs around types --- lib/ssh/src/ssh.erl | 26 +++++++++++++++----------- lib/ssh/src/ssh.hrl | 17 +++++++++-------- 2 files changed, 24 insertions(+), 19 deletions(-) diff --git a/lib/ssh/src/ssh.erl b/lib/ssh/src/ssh.erl index 44e87f528ada..b3989bfdfdf5 100644 --- a/lib/ssh/src/ssh.erl +++ b/lib/ssh/src/ssh.erl @@ -135,7 +135,8 @@ The directory could be changed with the option [{type,<<"Client Options">>}, {type,<<"Daemon Options">>}, {type,<<"Common Options">>}, - {type,<<"Other data types">>}]}). + {type,<<"Deprecated Types">>}, + {type,<<"Other Data Types">>}]}). -include("ssh.hrl"). -include("ssh_connect.hrl"). @@ -174,8 +175,11 @@ The directory could be changed with the option %%% "Deprecated" types export: -export_type([ssh_daemon_ref/0, ssh_connection_ref/0, ssh_channel_id/0]). +-doc(#{title => <<"Deprecated Types">>}). -opaque ssh_daemon_ref() :: daemon_ref(). +-doc(#{title => <<"Deprecated Types">>}). -opaque ssh_connection_ref() :: connection_ref(). +-doc(#{title => <<"Deprecated Types">>}). -opaque ssh_channel_id() :: channel_id(). @@ -208,7 +212,7 @@ Opaque data type representing a daemon. Returned by the functions [`daemon/1,2,3`](`daemon/1`). """. --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -opaque daemon_ref() :: pid() . -doc """ Opaque data type representing a channel inside a connection. @@ -216,7 +220,7 @@ Opaque data type representing a channel inside a connection. Returned by the functions [ssh_connection:session_channel/2,4](`ssh_connection:session_channel/2`). """. --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -opaque channel_id() :: non_neg_integer(). -doc """ Opaque data type representing a connection between a client and a server @@ -225,7 +229,7 @@ Opaque data type representing a connection between a client and a server Returned by the functions [`connect/2,3,4`](`connect/3`) and [`ssh_sftp:start_channel/2,3`](`ssh_sftp:start_channel/2`). """. --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type connection_ref() :: pid(). % should be -opaque, but that gives problems %%-------------------------------------------------------------------- @@ -427,13 +431,13 @@ close(ConnectionRef) -> %%-------------------------------------------------------------------- %% Description: Retrieves information about a connection. %%--------------------------------------------------------------------- --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type version() :: {protocol_version(), software_version()}. --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type protocol_version() :: {Major::pos_integer(), Minor::non_neg_integer()}. --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type software_version() :: string(). --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type conn_info_algs() :: [{kex, kex_alg()} | {hkey, pubkey_alg()} | {encrypt, cipher_alg()} @@ -451,10 +455,10 @@ Return values from the `connection_info/1` and `connection_info/2` functions. In the `option` info tuple are only the options included that differs from the default values. """. --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type conn_info_channels() :: [proplists:proplist()]. --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type connection_info_tuple() :: {client_version, version()} | {server_version, version()} @@ -693,7 +697,7 @@ Return values from the `daemon_info/1` and `daemon_info/2` functions. In the `option` info tuple are only the options included that differs from the default values. """. --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type daemon_info_tuple() :: {port, inet:port_number()} | {ip, inet:ip_address()} diff --git a/lib/ssh/src/ssh.hrl b/lib/ssh/src/ssh.hrl index bb4b4f35e1e7..d01bb8c6022e 100644 --- a/lib/ssh/src/ssh.hrl +++ b/lib/ssh/src/ssh.hrl @@ -122,16 +122,17 @@ %% Types +-doc(#{title => <<"Other Data Types">>}). -type role() :: client | server . --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type host() :: string() | inet:ip_address() | loopback . -doc """ The socket is supposed to be result of a [gen_tcp:connect](`gen_tcp:connect/3`) or a [gen_tcp:accept](`gen_tcp:accept/1`). The socket must be in passive mode (that is, opened with the option `{active,false})`. """. --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type open_socket() :: gen_tcp:socket(). -doc """ @@ -514,7 +515,7 @@ protocol). Opaque types that define experimental options that are not to be used in products. """. --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type opaque_common_options() :: {transport, {atom(),atom(),atom()} } | {vsn, {non_neg_integer(),non_neg_integer()} } @@ -547,7 +548,7 @@ risk. | gen_tcp:connect_option() | ?COMMON_OPTION . --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type opaque_client_options() :: {keyboard_interact_fun, fun((Name::iodata(), Instruction::iodata(), @@ -1149,17 +1150,17 @@ in the User's Guide chapter. {failfun, fun((User::string(), Peer::{inet:ip_address(), inet:port_number()}, Reason::term()) -> _)} | {connectfun, fun((User::string(), Peer::{inet:ip_address(), inet:port_number()}, Method::string()) ->_)} . --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type opaque_daemon_options() :: {infofun, fun()} | opaque_common_options(). --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type ip_port() :: {inet:ip_address(), inet:port_number()} . --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type mod_args() :: {Module::atom(), Args::list()} . --doc(#{title => <<"Other data types">>}). +-doc(#{title => <<"Other Data Types">>}). -type mod_fun_args() :: {Module::atom(), Function::atom(), Args::list()} . From 0f052425c8f6446eb0f1e9cd925d73431aa5267d Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Tue, 14 Jan 2025 18:42:59 +0100 Subject: [PATCH 2/8] ssh: fix ssh_sftp:start_channel docs --- lib/ssh/src/ssh_sftp.erl | 42 ++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/lib/ssh/src/ssh_sftp.erl b/lib/ssh/src/ssh_sftp.erl index 78635949cb72..bea54ab6e75d 100644 --- a/lib/ssh/src/ssh_sftp.erl +++ b/lib/ssh/src/ssh_sftp.erl @@ -130,30 +130,38 @@ The `t:tuple/0` reason are other errors like for example `{exit_status,1}`. %%==================================================================== %% API %%==================================================================== - - -%%%================================================================ -%%% - -%%%---------------------------------------------------------------- -%%% start_channel/1 --doc(#{equiv => start_channel/3}). +-doc(#{equiv => start_channel/2}). -spec start_channel(ssh:open_socket() | ssh:connection_ref() | ssh:host()) -> {ok, pid()} | {ok, pid(), ssh:connection_ref()} | {error, reason()}. start_channel(Dest) -> start_channel(Dest, []). - -%%%---------------------------------------------------------------- -%%% start_channel/2 + %%% -spec:s are as if Dialyzer handled signatures for separate %%% function clauses. --doc(#{equiv => start_channel/3}). +-doc """ +Starts new ssh channel for communicating with the SFTP server. + +Starts an ssh channel when first argument is a connection reference. + +Equivalent to [start_channel(Host, 22, UserOptions)](`start_channel/3`) when +first argument is recognized as network host. + +Otherwise, first argument is treated as a network socket which will be used for +establishing new SSH connection. New connection reference will be used for +starting an SSH channel. + +The returned `pid` for this process is to be used as input to all other API +functions in this module. + +See also (`start_channel/3`). + +""". -spec start_channel(ssh:open_socket(), [ssh:client_option() | sftp_option()]) -> {ok, pid(), ssh:connection_ref()} | {error,reason()}; (ssh:connection_ref(), [ssh:client_option() | sftp_option()]) -> {ok, pid()} | {ok, pid(), ssh:connection_ref()} | {error, reason()}; (ssh:host(), [ssh:client_option() | sftp_option()]) -> - {ok, pid(), ssh:connection_ref()} | {error, reason()} . + {ok, pid(), ssh:connection_ref()} | {error, reason()}. start_channel(Cm, UserOptions0) when is_pid(Cm) -> UserOptions = legacy_timeout(UserOptions0), Timeout = proplists:get_value(timeout, UserOptions, infinity), @@ -201,14 +209,10 @@ start_channel(Dest, UserOptions0) -> end end. -%%%---------------------------------------------------------------- -%%% start_channel/3 -doc """ -start_channel(Host, Port, Options) -> +Starts new ssh connection and channel for communicating with the SFTP server. -If no connection reference is provided, a connection is set up, and the new -connection is returned. An SSH channel process is started to handle the -communication with the SFTP server. The returned `pid` for this process is to be +The returned `pid` for this process is to be used as input to all other API functions in this module. Options: From d39a2aa84aedd1f3730256f04fdd244034af0c1a Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Fri, 31 Jan 2025 14:11:20 +0100 Subject: [PATCH 3/8] ssh: info about receiving large exec output --- lib/ssh/src/ssh_connection.erl | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/lib/ssh/src/ssh_connection.erl b/lib/ssh/src/ssh_connection.erl index 73b626cc9143..3dc2f88621b1 100644 --- a/lib/ssh/src/ssh_connection.erl +++ b/lib/ssh/src/ssh_connection.erl @@ -417,6 +417,12 @@ request is a one-time execution that closes the channel when it is done. See the User's Guide section on [One-Time Execution](using_ssh.md#one-time-execution) for examples. + +> #### Note {: .info } +> +> In case when command generates large amount of output data, manual +> window adjustment might be necessary in order to receive it. +> see [`ssh_connectino:adjust_window/3`](`adjust_window/3`) """. -spec exec(ConnectionRef, ChannelId, Command, Timeout) -> result() when ConnectionRef :: ssh:connection_ref(), From 7cf85d393ef6cdda12bdea7fea7c5321eb368d56 Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Fri, 31 Jan 2025 15:23:04 +0100 Subject: [PATCH 4/8] ssh: type categories fixup in ssh manual --- lib/ssh/src/ssh.erl | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/lib/ssh/src/ssh.erl b/lib/ssh/src/ssh.erl index b3989bfdfdf5..614e5a030254 100644 --- a/lib/ssh/src/ssh.erl +++ b/lib/ssh/src/ssh.erl @@ -135,8 +135,7 @@ The directory could be changed with the option [{type,<<"Client Options">>}, {type,<<"Daemon Options">>}, {type,<<"Common Options">>}, - {type,<<"Deprecated Types">>}, - {type,<<"Other Data Types">>}]}). + {type,<<"Deprecated">>}]}). -include("ssh.hrl"). -include("ssh_connect.hrl"). @@ -175,11 +174,11 @@ The directory could be changed with the option %%% "Deprecated" types export: -export_type([ssh_daemon_ref/0, ssh_connection_ref/0, ssh_channel_id/0]). --doc(#{title => <<"Deprecated Types">>}). +-doc(#{title => <<"Deprecated">>}). -opaque ssh_daemon_ref() :: daemon_ref(). --doc(#{title => <<"Deprecated Types">>}). +-doc(#{title => <<"Deprecated">>}). -opaque ssh_connection_ref() :: connection_ref(). --doc(#{title => <<"Deprecated Types">>}). +-doc(#{title => <<"Deprecated">>}). -opaque ssh_channel_id() :: channel_id(). @@ -212,7 +211,6 @@ Opaque data type representing a daemon. Returned by the functions [`daemon/1,2,3`](`daemon/1`). """. --doc(#{title => <<"Other Data Types">>}). -opaque daemon_ref() :: pid() . -doc """ Opaque data type representing a channel inside a connection. @@ -220,7 +218,6 @@ Opaque data type representing a channel inside a connection. Returned by the functions [ssh_connection:session_channel/2,4](`ssh_connection:session_channel/2`). """. --doc(#{title => <<"Other Data Types">>}). -opaque channel_id() :: non_neg_integer(). -doc """ Opaque data type representing a connection between a client and a server @@ -229,7 +226,6 @@ Opaque data type representing a connection between a client and a server Returned by the functions [`connect/2,3,4`](`connect/3`) and [`ssh_sftp:start_channel/2,3`](`ssh_sftp:start_channel/2`). """. --doc(#{title => <<"Other Data Types">>}). -type connection_ref() :: pid(). % should be -opaque, but that gives problems %%-------------------------------------------------------------------- @@ -431,13 +427,9 @@ close(ConnectionRef) -> %%-------------------------------------------------------------------- %% Description: Retrieves information about a connection. %%--------------------------------------------------------------------- --doc(#{title => <<"Other Data Types">>}). -type version() :: {protocol_version(), software_version()}. --doc(#{title => <<"Other Data Types">>}). -type protocol_version() :: {Major::pos_integer(), Minor::non_neg_integer()}. --doc(#{title => <<"Other Data Types">>}). -type software_version() :: string(). --doc(#{title => <<"Other Data Types">>}). -type conn_info_algs() :: [{kex, kex_alg()} | {hkey, pubkey_alg()} | {encrypt, cipher_alg()} @@ -455,10 +447,8 @@ Return values from the `connection_info/1` and `connection_info/2` functions. In the `option` info tuple are only the options included that differs from the default values. """. --doc(#{title => <<"Other Data Types">>}). -type conn_info_channels() :: [proplists:proplist()]. --doc(#{title => <<"Other Data Types">>}). -type connection_info_tuple() :: {client_version, version()} | {server_version, version()} @@ -697,7 +687,6 @@ Return values from the `daemon_info/1` and `daemon_info/2` functions. In the `option` info tuple are only the options included that differs from the default values. """. --doc(#{title => <<"Other Data Types">>}). -type daemon_info_tuple() :: {port, inet:port_number()} | {ip, inet:ip_address()} From 168406159f15bc14f8514eb638e3c3899a267ad2 Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Fri, 31 Jan 2025 17:26:06 +0100 Subject: [PATCH 5/8] ssh: move type description for conn_info_channels - move from conn_info_channels to connection_info_tuple - fix typo --- lib/ssh/src/ssh.erl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/ssh/src/ssh.erl b/lib/ssh/src/ssh.erl index 614e5a030254..8465c61fa235 100644 --- a/lib/ssh/src/ssh.erl +++ b/lib/ssh/src/ssh.erl @@ -441,14 +441,14 @@ close(ConnectionRef) -> | {send_ext_info, boolean()} | {recv_ext_info, boolean()} ]. +-type conn_info_channels() :: [proplists:proplist()]. + -doc """ Return values from the `connection_info/1` and `connection_info/2` functions. -In the `option` info tuple are only the options included that differs from the +In the `options` info tuple are only the options included that differs from the default values. """. --type conn_info_channels() :: [proplists:proplist()]. - -type connection_info_tuple() :: {client_version, version()} | {server_version, version()} From 320737ad65ffbdfe57de47731e53e85f3a13eebe Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Mon, 3 Feb 2025 10:56:15 +0100 Subject: [PATCH 6/8] ssh: typo fix in using_ssh.md --- lib/ssh/doc/guides/using_ssh.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ssh/doc/guides/using_ssh.md b/lib/ssh/doc/guides/using_ssh.md index 2a2dbf416a3f..137c67e4a92d 100644 --- a/lib/ssh/doc/guides/using_ssh.md +++ b/lib/ssh/doc/guides/using_ssh.md @@ -535,7 +535,7 @@ DecryptFun = end, Cr = {InitFun,DecryptFun}, -{ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read,{crypto,Cw}]), +{ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read,{crypto,Cr}]), {ok,NameValueList} = erl_tar:extract(HandleRead,[memory]), ok = erl_tar:close(HandleRead), ``` From 5471ae5034d7a6ade60a62910dbb900a13101fca Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Mon, 3 Feb 2025 14:45:54 +0100 Subject: [PATCH 7/8] ssh: fix docs for `options` note --- lib/ssh/src/ssh.erl | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/lib/ssh/src/ssh.erl b/lib/ssh/src/ssh.erl index 8465c61fa235..0762b1feae47 100644 --- a/lib/ssh/src/ssh.erl +++ b/lib/ssh/src/ssh.erl @@ -446,8 +446,9 @@ close(ConnectionRef) -> -doc """ Return values from the `connection_info/1` and `connection_info/2` functions. -In the `options` info tuple are only the options included that differs from the -default values. +> #### Note {: .info } +> +> Note that `options` info tuple contains only items with nondefault values. """. -type connection_info_tuple() :: {client_version, version()} @@ -684,8 +685,9 @@ daemon_replace_options(DaemonRef, NewUserOptions) -> -doc """ Return values from the `daemon_info/1` and `daemon_info/2` functions. -In the `option` info tuple are only the options included that differs from the -default values. +> #### Note {: .info } +> +> Note that `options` info tuple contains only items with nondefault values. """. -type daemon_info_tuple() :: {port, inet:port_number()} From e25585acd975aef40b21b49f3bdac8636de0d4f0 Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Mon, 3 Feb 2025 15:37:05 +0100 Subject: [PATCH 8/8] ssh: ssh_sftp manual fix --- lib/ssh/src/ssh_sftp.erl | 3 +++ 1 file changed, 3 insertions(+) diff --git a/lib/ssh/src/ssh_sftp.erl b/lib/ssh/src/ssh_sftp.erl index bea54ab6e75d..bc279c6949ba 100644 --- a/lib/ssh/src/ssh_sftp.erl +++ b/lib/ssh/src/ssh_sftp.erl @@ -101,6 +101,9 @@ file transfer service available for SSH. -define(XF(S), S#state.xf). -define(REQID(S), S#state.req_id). +-doc """ +Specifies available SFTP options. +""". -type sftp_option() :: {timeout, timeout()} | {sftp_vsn, pos_integer()} | {window_size, pos_integer()}