network-infra-utility 0.2.0 → 0.5.0

data/service/ssh/ext/ssh_core/src/ssh_keepalive_mgr.erl

@@ -0,0 +1,222 @@
+-module(ssh_keepalive_mgr).
+-behaviour(gen_server).
+
+%% Keepalive manager — periodically checks all active connections.
+%%
+%% Key design (LLD §6.9):
+%%   - Periodically sends SSH keepalive to all ready connections
+%%   - 3 consecutive failures → push conn.closed (NOT autonomous reconnection)
+%%   - Reconnect decision is Ruby's, via conn.reconnect RPC
+%%   - Runs as permanent worker in ssh_infra_sup
+%%
+%% Activity-aware keepalive (enhancement):
+%%   - Tracks last_activity timestamp per connection
+%%   - If data flowed since last check, skip keepalive and reset fail count
+%%   - notify_activity/1 called by channel_stm on send/recv
+%%   - This prevents unnecessary keepalive on active connections
+
+-export([start_link/1, set_interval/1, get_interval/0, notify_activity/1, get_status/0,
+         rpc_set_interval/1, rpc_get_interval/1, rpc_get_status/1]).
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2, terminate/2]).
+
+-include("ssh_ipc.hrl").
+
+-record(st, {
+    interval_ms :: pos_integer(),
+    fail_counts = #{} :: #{pid() => non_neg_integer()},
+    last_activity = #{} :: #{pid() => erlang:timestamp()},
+    last_check = #{} :: #{pid() => erlang:timestamp()}
+}).
+
+%% ---------- Public API ----------
+
+%% @doc Start the keepalive manager with the given interval (ms).
+start_link(IntervalMs) ->
+    gen_server:start_link({local, ?MODULE}, ?MODULE, [IntervalMs], []).
+
+%% @doc Update the keepalive interval at runtime.
+set_interval(NewMs) ->
+    gen_server:cast(?MODULE, {set_interval, NewMs}).
+
+%% @doc Get the current interval.
+get_interval() ->
+    gen_server:call(?MODULE, get_interval).
+
+%% @doc Notify that activity occurred on a connection (data sent/received).
+%% Resets the fail counter and updates the last_activity timestamp.
+%% Called by ssh_channel_stm when data flows through a channel.
+-spec notify_activity(pid()) -> ok.
+notify_activity(ConnWorkerPid) ->
+    gen_server:cast(?MODULE, {notify_activity, ConnWorkerPid}).
+
+%% @doc Get keepalive status for all connections (for debugging/monitoring).
+get_status() ->
+    gen_server:call(?MODULE, get_status).
+
+%% ---------- gen_server callbacks ----------
+
+init([IntervalMs]) ->
+    schedule_tick(IntervalMs),
+    {ok, #st{interval_ms = IntervalMs}}.
+
+handle_call(get_interval, _From, #st{interval_ms = Ms} = S) ->
+    {reply, Ms, S};
+
+handle_call(get_status, _From, #st{fail_counts = Fails, last_activity = Acts} = S) ->
+    Workers = ssh_conn_sup:all_workers(),
+    Status = lists:map(fun(Pid) ->
+        #{
+            pid => Pid,
+            conn_id => catch ssh_conn_worker:conn_id(Pid),
+            state => catch ssh_conn_worker:get_state_name(Pid),
+            fail_count => maps:get(Pid, Fails, 0),
+            last_activity => maps:get(Pid, Acts, undefined)
+        }
+    end, Workers),
+    {reply, Status, S};
+
+handle_call(_Req, _From, S) ->
+    {reply, {error, not_implemented}, S}.
+
+handle_cast({set_interval, NewMs}, #st{} = S) ->
+    {noreply, S#st{interval_ms = NewMs}};
+
+handle_cast({notify_activity, ConnWorkerPid}, #st{last_activity = Acts, fail_counts = Fails} = S) ->
+    %% Record activity timestamp and reset fail count for this connection
+    NewActs = maps:put(ConnWorkerPid, os:timestamp(), Acts),
+    NewFails = maps:remove(ConnWorkerPid, Fails),
+    {noreply, S#st{last_activity = NewActs, fail_counts = NewFails}};
+
+handle_cast(_Msg, S) ->
+    {noreply, S}.
+
+handle_info(tick, #st{interval_ms = Ms, fail_counts = Fails, last_activity = Acts, last_check = Checks} = S) ->
+    %% Scan all connection workers
+    Workers = ssh_conn_sup:all_workers(),
+    %% Record check time for each worker
+    Now = os:timestamp(),
+    Checks1 = lists:foldl(fun(Pid, Acc) -> maps:put(Pid, Now, Acc) end, Checks, Workers),
+    %% Check each worker, passing the *previous* check timestamps for comparison
+    {NewFails, NewActs} = lists:foldl(fun(Pid, {FAcc, AAcc}) ->
+        check_keepalive(Pid, FAcc, AAcc, Checks)
+    end, {Fails, Acts}, Workers),
+    %% Clean up dead workers from maps
+    {CleanFails, CleanActs} = cleanup_maps(Workers, NewFails, NewActs),
+    schedule_tick(Ms),
+    {noreply, S#st{fail_counts = CleanFails, last_activity = CleanActs, last_check = Checks1}};
+
+handle_info(_Info, S) ->
+    {noreply, S}.
+
+terminate(_Reason, _S) ->
+    ok.
+
+%% ---------- Internal ----------
+
+schedule_tick(IntervalMs) ->
+    erlang:send_after(IntervalMs, self(), tick),
+    ok.
+
+%% @doc Check a single connection's keepalive.
+%% Activity-aware: if data flowed since last check, skip keepalive and reset fail count.
+%% Args: Pid, fail_counts, last_activity, last_check (previous check timestamps map)
+%% Returns {updated_fail_counts, updated_last_activity}.
+check_keepalive(Pid, Fails, Acts, Checks) ->
+    case catch ssh_conn_worker:get_state_name(Pid) of
+        ready ->
+            LastActivity = maps:get(Pid, Acts, undefined),
+            LastCheck = maps:get(Pid, Checks, undefined),
+            %% Check if there was activity since we last checked
+            case was_active_since(LastActivity, LastCheck) of
+                true ->
+                    %% Connection was active since last check — skip keepalive, reset fails
+                    {maps:remove(Pid, Fails), Acts};
+                false ->
+                    %% No recent activity — send keepalive
+                    case send_keepalive(Pid) of
+                        ok ->
+                            {maps:remove(Pid, Fails), Acts};
+                        {error, _} ->
+                            Count = maps:get(Pid, Fails, 0) + 1,
+                            case Count >= ?KEEPALIVE_DEFAULT_MAX_FAIL of
+                                true ->
+                                    %% 3 consecutive failures — notify Ruby
+                                    ConnId = (catch ssh_conn_worker:conn_id(Pid)),
+                                    ssh_ipc_gateway:push_event(<<"conn.closed">>, #{
+                                        <<"conn_id">> => ConnId,
+                                        <<"reason">> => <<"keepalive_failed">>
+                                    }),
+                                    {maps:remove(Pid, Fails), maps:remove(Pid, Acts)};
+                                false ->
+                                    {maps:put(Pid, Count, Fails), Acts}
+                            end
+                    end
+            end;
+        _ ->
+            %% Not in ready state — skip
+            {Fails, Acts}
+    end.
+
+%% @doc Check if last_activity is more recent than last_check.
+%% Returns true if activity occurred since the last keepalive check.
+%% If last_check is undefined (first check), activity doesn't matter — we still send keepalive.
+was_active_since(undefined, _LastCheck) ->
+    false;
+was_active_since(_LastActivity, undefined) ->
+    %% First check, no previous check time — don't skip
+    false;
+was_active_since(LastActivity, LastCheck) ->
+    %% Compare timestamps: if LastActivity > LastCheck, there was activity
+    try
+        Diff = timer:now_diff(LastActivity, LastCheck),
+        Diff > 0
+    catch
+        _:_ -> false
+    end.
+
+%% @doc Remove entries for workers that no longer exist.
+cleanup_maps(Workers, Fails, Acts) ->
+    WorkerSet = sets:from_list(Workers),
+    CleanFails = maps:filter(fun(Pid, _) -> sets:is_element(Pid, WorkerSet) end, Fails),
+    CleanActs = maps:filter(fun(Pid, _) -> sets:is_element(Pid, WorkerSet) end, Acts),
+    {CleanFails, CleanActs}.
+
+%% @doc Send a keepalive packet on an SSH connection.
+send_keepalive(Pid) ->
+    try
+        SshRef = ssh_conn_worker:get_ssh_ref(Pid),
+        %% OTP ssh: ssh:send_keepalive/1 — returns ok | {error, Reason}
+        ssh:send_keepalive(SshRef)
+    catch
+        _:_ -> {error, keepalive_exception}
+    end.
+
+%% ---------- RPC handlers ----------
+
+%% @doc RPC handler for keepalive.set_interval
+rpc_set_interval(#{<<"interval_ms">> := IntervalMs}) ->
+    set_interval(IntervalMs),
+    #{ok => true}.
+
+%% @doc RPC handler for keepalive.get_interval
+rpc_get_interval(_Params) ->
+    IntervalMs = get_interval(),
+    #{interval_ms => IntervalMs}.
+
+%% @doc RPC handler for keepalive.get_status
+rpc_get_status(_Params) ->
+    Status = get_status(),
+    %% Convert records to maps for JSON encoding
+    lists:map(fun(Entry) ->
+        maps:map(fun
+            (pid, Pid) -> list_to_binary(pid_to_list(Pid));
+            (conn_id, V) when is_binary(V) -> V;
+            (conn_id, _) -> null;
+            (state, V) when is_atom(V) -> atom_to_binary(V, utf8);
+            (state, _) -> null;
+            (fail_count, V) -> V;
+            (last_activity, {Mega, Sec, Micro}) ->
+                list_to_binary(io_lib:format("~w,~w,~w", [Mega, Sec, Micro]));
+            (last_activity, _) -> null
+        end, Entry)
+    end, Status).

data/service/ssh/ext/ssh_core/src/ssh_known_hosts_proxy.erl

@@ -0,0 +1,67 @@
+-module(ssh_known_hosts_proxy).
+-behaviour(gen_server).
+
+%% Known hosts proxy — mediates host key verification between OTP ssh and Ruby.
+%%
+%% Key design (LLD §6.10, E7 fix):
+%%   - Erlang does NOT persist known_hosts — Ruby handles storage
+%%   - ssh_auth_engine key_cb calls verify/3 which queries Ruby via IPC
+%%   - Uses synchronous_push (blocking reverse RPC) with 30s timeout
+%%   - If Ruby doesn't respond in 30s → reject (safe default)
+%%   - Returns: accepted | accepted_once | rejected
+
+-export([
+    start_link/0,
+    verify/3
+]).
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2, terminate/2]).
+
+-include("ssh_ipc.hrl").
+
+-record(st, {}).
+
+%% ---------- Public API ----------
+
+%% @doc Start the known_hosts proxy.
+start_link() ->
+    gen_server:start_link({local, ?MODULE}, ?MODULE, [], []).
+
+%% @doc Verify a host key by querying Ruby via IPC.
+%% Called by ssh_auth_engine's key_cb callbacks.
+%% Blocks until Ruby responds or times out.
+-spec verify(string(), inet:port_number(), public_key:public_key()) ->
+    accepted | accepted_once | rejected.
+verify(Host, Port, Key) ->
+    Fingerprint = ssh_codec:fingerprint(Key),
+    Req = #{
+        <<"method">> => <<"hostkey.resolve">>,
+        <<"params">> => #{
+            <<"host">> => list_to_binary(Host),
+            <<"port">> => Port,
+            <<"fingerprint">> => Fingerprint
+        }
+    },
+    case ssh_ipc_gateway:synchronous_push(Req, ?HOSTKEY_RESOLVE_TIMEOUT_MS) of
+        {ok, #{<<"action">> := <<"accept">>}} -> accepted;
+        {ok, #{<<"action">> := <<"once">>}} -> accepted_once;
+        {ok, #{<<"action">> := <<"reject">>}} -> rejected;
+        {error, timeout} -> rejected;
+        {error, _} -> rejected
+    end.
+
+%% ---------- gen_server callbacks ----------
+
+init([]) ->
+    {ok, #st{}}.
+
+handle_call(_Req, _From, S) ->
+    {reply, {error, not_implemented}, S}.
+
+handle_cast(_Msg, S) ->
+    {noreply, S}.
+
+handle_info(_Info, S) ->
+    {noreply, S}.
+
+terminate(_Reason, _S) ->
+    ok.

data/service/ssh/ext/ssh_core/src/ssh_port_fwd.erl

@@ -0,0 +1,225 @@
+-module(ssh_port_fwd).
+-behaviour(gen_server).
+
+%% Port forwarding manager — manages local/remote/dynamic port forward rules.
+%%
+%% Key design (LLD §6.8, E4 fix):
+%%   - Local forward: gen_tcp:listen + ssh_connection:direct_tcpip
+%%   - Remote forward: ssh_connection:tcpip_forward/3
+%%   - Dynamic (SOCKS5): Local forward + self-implemented SOCKS5 negotiation (V2.0)
+%%
+%% One gen_server per connection, manages all rules for that connection.
+
+-export([
+    start_link/1,
+    rpc_add/1,
+    rpc_remove/1,
+    rpc_list/1
+]).
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2, terminate/2]).
+
+-include("ssh_ipc.hrl").
+
+-record(fwd_rule, {
+    id :: binary(),
+    type :: local | remote | dynamic,
+    local_port :: pos_integer(),
+    remote_host :: binary() | undefined,
+    remote_port :: pos_integer() | undefined,
+    enabled = true :: boolean(),
+    listener_pid :: pid() | undefined
+}).
+
+-record(st, {
+    conn_id :: binary(),
+    ssh_ref :: reference(),
+    rules = #{} :: #{binary() => #fwd_rule{}},
+    next_seq = 1 :: pos_integer()
+}).
+
+%% ---------- Public API ----------
+
+%% @doc Start a port forwarding manager for a connection.
+start_link(#{conn_id := ConnId, ssh_ref := SshRef}) ->
+    gen_server:start_link(?MODULE, [ConnId, SshRef], []).
+
+%% @doc RPC handler for portfwd.add
+rpc_add(#{<<"conn_id">> := ConnId, <<"type">> := TypeBin,
+          <<"local_port">> := LocalPort} = Params) ->
+    case find_mgr(ConnId) of
+        {ok, Pid} ->
+            gen_server:call(Pid, {add, #{
+                type => binary_to_atom(TypeBin, utf8),
+                local_port => LocalPort,
+                remote_host => maps:get(<<"remote_host">>, Params, undefined),
+                remote_port => maps:get(<<"remote_port">>, Params, undefined)
+            }});
+        {error, not_found} ->
+            {error, conn_not_found}
+    end.
+
+%% @doc RPC handler for portfwd.list
+rpc_list(#{<<"conn_id">> := ConnId}) ->
+    case find_mgr(ConnId) of
+        {ok, Pid} ->
+            gen_server:call(Pid, list);
+        {error, not_found} ->
+            %% No forwarding manager started for this connection yet
+            {ok, []}
+    end.
+
+%% @doc RPC handler for portfwd.remove
+rpc_remove(#{<<"conn_id">> := ConnId, <<"rule_id">> := RuleId}) ->
+    case find_mgr(ConnId) of
+        {ok, Pid} ->
+            gen_server:call(Pid, {remove, RuleId});
+        {error, not_found} ->
+            {error, conn_not_found}
+    end.
+
+%% ---------- gen_server callbacks ----------
+
+init([ConnId, SshRef]) ->
+    {ok, #st{conn_id = ConnId, ssh_ref = SshRef}}.
+
+handle_call({add, #{type := local, local_port := LocalPort,
+                    remote_host := RHost, remote_port := RPort}}, _From, S) ->
+    RuleId = gen_rule_id(S),
+    Rule = #fwd_rule{id = RuleId, type = local, local_port = LocalPort,
+                     remote_host = RHost, remote_port = RPort},
+    case start_local_listener(S#st.ssh_ref, Rule) of
+        {ok, ListenerPid} ->
+            Rule1 = Rule#fwd_rule{listener_pid = ListenerPid},
+            Rules = maps:put(RuleId, Rule1, S#st.rules),
+            {reply, {ok, #{rule_id => RuleId}}, S#st{rules = Rules, next_seq = S#st.next_seq + 1}};
+        {error, Reason} ->
+            {reply, {error, Reason}, S}
+    end;
+
+handle_call({add, #{type := remote, local_port := RemotePort,
+                    remote_host := LHost, remote_port := LPort}}, _From, S) ->
+    RuleId = gen_rule_id(S),
+    case ssh_connection:tcpip_forward(S#st.ssh_ref,
+            binary_to_list(LHost), LPort, RemotePort) of
+        ok ->
+            Rule = #fwd_rule{id = RuleId, type = remote, local_port = RemotePort,
+                             remote_host = LHost, remote_port = LPort},
+            Rules = maps:put(RuleId, Rule, S#st.rules),
+            {reply, {ok, #{rule_id => RuleId}}, S#st{rules = Rules, next_seq = S#st.next_seq + 1}};
+        {error, Reason} ->
+            {reply, {error, Reason}, S}
+    end;
+
+handle_call({add, #{type := dynamic, local_port := LocalPort}}, _From, S) ->
+    %% SOCKS5 dynamic forward — V2.0
+    {reply, {error, not_implemented_v1}, S};
+
+handle_call({remove, RuleId}, _From, S) ->
+    case maps:get(RuleId, S#st.rules, undefined) of
+        #fwd_rule{listener_pid = LPid} = _Rule when is_pid(LPid) ->
+            ok = stop_local_listener(LPid);
+        _ ->
+            ok
+    end,
+    Rules = maps:remove(RuleId, S#st.rules),
+    {reply, {ok, true}, S#st{rules = Rules}};
+
+handle_call(list, _From, S) ->
+    Items = maps:fold(fun(RuleId, R, Acc) ->
+        [#{rule_id => RuleId,
+           type => atom_to_binary(R#fwd_rule.type, utf8),
+           local_port => R#fwd_rule.local_port,
+           remote_host => R#fwd_rule.remote_host,
+           remote_port => R#fwd_rule.remote_port,
+           enabled => R#fwd_rule.enabled} | Acc]
+    end, [], S#st.rules),
+    {reply, {ok, Items}, S};
+
+handle_call(_Req, _From, S) ->
+    {reply, {error, not_implemented}, S}.
+
+handle_cast(_Msg, S) ->
+    {noreply, S}.
+
+handle_info(_Info, S) ->
+    {noreply, S}.
+
+terminate(_Reason, _S) ->
+    ok.
+
+%% ---------- Internal ----------
+
+gen_rule_id(S) ->
+    ConnIdShort = binary:part(S#st.conn_id, {0, erlang:min(byte_size(S#st.conn_id), 16)}),
+    <<"fwd_", ConnIdShort/binary, "_", (integer_to_binary(S#st.next_seq))/binary>>.
+
+%% @doc Start a local TCP listener that forwards to remote via SSH direct_tcpip.
+start_local_listener(SshRef, #fwd_rule{local_port = Port,
+                                        remote_host = RHost,
+                                        remote_port = RPort}) ->
+    case gen_tcp:listen(Port, [{ip, {127, 0, 0, 1}}, {active, false},
+                                {reuseaddr, true}]) of
+        {ok, ListenSock} ->
+            Pid = spawn_link(fun() ->
+                local_listener_loop(ListenSock, SshRef,
+                    binary_to_list(RHost), RPort)
+            end),
+            {ok, Pid};
+        {error, Reason} ->
+            {error, Reason}
+    end.
+
+local_listener_loop(ListenSock, SshRef, RHost, RPort) ->
+    case gen_tcp:accept(ListenSock) of
+        {ok, ClientSock} ->
+            spawn(fun() -> handle_local_forward(ClientSock, SshRef, RHost, RPort) end),
+            local_listener_loop(ListenSock, SshRef, RHost, RPort);
+        {error, _} ->
+            ok
+    end.
+
+handle_local_forward(ClientSock, SshRef, RHost, RPort) ->
+    case ssh_connection:direct_tcpip(SshRef, RHost, RPort, "127.0.0.1", 0, ?RPC_DEFAULT_TIMEOUT_MS) of
+        {ok, ChanId} ->
+            inet:setopts(ClientSock, [{active, once}]),
+            forward_loop(ClientSock, SshRef, ChanId);
+        {error, _} ->
+            gen_tcp:close(ClientSock)
+    end.
+
+forward_loop(ClientSock, SshRef, ChanId) ->
+    receive
+        {ssh_cm, SshRef, {data, ChanId, _Type, Data}} ->
+            gen_tcp:send(ClientSock, Data),
+            forward_loop(ClientSock, SshRef, ChanId);
+        {ssh_cm, SshRef, {eof, ChanId}} ->
+            gen_tcp:close(ClientSock),
+            ssh_connection:close(SshRef, ChanId);
+        {ssh_cm, SshRef, {closed, ChanId}} ->
+            gen_tcp:close(ClientSock);
+        {tcp, ClientSock, ClientData} ->
+            ssh_connection:send(SshRef, ChanId, ClientData),
+            inet:setopts(ClientSock, [{active, once}]),
+            forward_loop(ClientSock, SshRef, ChanId);
+        {tcp_closed, ClientSock} ->
+            ssh_connection:close(SshRef, ChanId);
+        {tcp_error, ClientSock, _} ->
+            ssh_connection:close(SshRef, ChanId)
+    after 300000 ->
+        %% 5 minute idle timeout
+        gen_tcp:close(ClientSock),
+        ssh_connection:close(SshRef, ChanId)
+    end.
+
+stop_local_listener(Pid) when is_pid(Pid) ->
+    _ = (catch exit(Pid, shutdown)),
+    ok;
+stop_local_listener(_) ->
+    ok.
+
+%% @doc Find the port_fwd manager for a connection.
+find_mgr(ConnId) ->
+    case ets:lookup(portfwd_index, ConnId) of
+        [{_, Pid}] -> {ok, Pid};
+        [] -> {error, not_found}
+    end.