Class SshSession

java.lang.Object
io.gem.api.SshSession
public final class SshSession extends Object
Lifecycle wrapper around an SSH client/session for a single connection.

Encapsulates connect, command execution, bulk SCP transfer, SFTP metadata operations, and graceful shutdown, exposing async methods returning CompletableFutures and routing connection/control, transfer, and long-running command work to separate execution resources. Session state is protected by a short-held lifecycle lock; network and file operations never execute while holding it.

  • Field Details

    • connection

      public final ConnectionConfig connection
      public SshConnection connection.

  • Constructor Details

    • SshSession

      public SshSession(ConnectionConfig conn, ExecutorService executor)
      This Constructor initializes all values.
      Parameters:
      conn - SshConnection
      executor - ExecutorService

    • SshSession

      public SshSession(ConnectionConfig conn, ExecutorService executor, int diagnosticBytes)
      This constructor initializes all values with an explicit diagnostic limit.
      Parameters:
      conn - SSH connection
      executor - orchestration executor
      diagnosticBytes - maximum stdout/stderr bytes retained per command

    • SshSession

      public SshSession(ConnectionConfig conn, ExecutorService controlExecutor, ExecutorService transferExecutor, ExecutorService commandExecutor, int diagnosticBytes)
      This constructor assigns separate execution resources to control, transfer, and long-running commands.
      Parameters:
      conn - SSH connection
      controlExecutor - bounded connection and control-operation executor
      transferExecutor - bounded deployment transfer executor
      commandExecutor - virtual-thread executor for long-running remote commands
      diagnosticBytes - maximum stdout/stderr bytes retained per command

    • SshSession

      public SshSession(ConnectionConfig conn, ExecutorService controlExecutor, ExecutorService transferExecutor, ExecutorService commandExecutor, int diagnosticBytes, int copyBufferBytes)
      This constructor assigns separate execution resources and an explicit SCP copy buffer.
      Parameters:
      conn - SSH connection
      controlExecutor - bounded connection and control-operation executor
      transferExecutor - bounded deployment transfer executor
      commandExecutor - virtual-thread executor for long-running remote commands
      diagnosticBytes - maximum stdout/stderr bytes retained per command
      copyBufferBytes - read buffer bytes used by each bulk SCP upload
      Throws:
      IllegalArgumentException - when copyBufferBytes is not positive

  • Method Details

    • createSessionAsync

      public CompletableFuture<Void> createSessionAsync(long timeoutSeconds)
      This method Creates Sessions.
      Parameters:
      timeoutSeconds - long
      Returns:
      CompletableFuture

    • getRemoteEndpointIdentity

      public String getRemoteEndpointIdentity() throws ConnectException
      Return the authenticated network endpoint used by this SSH session.

      The numeric address lets orchestration collapse aliases such as localhost and 127.0.0.1 before performing physical deployment work. The configured host name remains available through connection for user-facing diagnostics.

      Returns:
      normalized numeric address, or the normalized endpoint text when unavailable
      Throws:
      ConnectException - when the SSH session is unavailable

    • getLocalRouteAddress

      public String getLocalRouteAddress() throws ConnectException
      Return the numeric controller address selected by the authenticated SSH route.

      This address is suitable for advertising controller services back to the same remote host and avoids depending on remote DNS resolution of the controller hostname.

      Returns:
      numeric local address of the SSH connection
      Throws:
      ConnectException - when the SSH session is unavailable or has no resolved IP address

    • runCommandAsync

      public CompletableFuture<SshResponse> runCommandAsync(String cmd, Boolean isOutput, long timeoutSeconds) throws ConnectException
      This method is responsible for running commands but throws ConnectException if it occurs.
      Parameters:
      cmd - String
      isOutput - Is stdout output is required
      timeoutSeconds - long
      Returns:
      CompletableFuture
      Throws:
      ConnectException - If connection exception occurs.

    • runCommandAsync

      public CompletableFuture<SshResponse> runCommandAsync(String cmd, byte[] input, Boolean isOutput, long timeoutSeconds) throws ConnectException
      Run a remote command with a binary stdin request.
      Parameters:
      cmd - command
      input - command standard input
      isOutput - whether output should be retained
      timeoutSeconds - command timeout
      Returns:
      asynchronous response
      Throws:
      ConnectException - when the SSH session is unavailable

    • runBenchmarkCommandAsync

      public CompletableFuture<SshResponse> runBenchmarkCommandAsync(String cmd, byte[] input, Boolean isOutput, long timeoutSeconds) throws ConnectException
      Run a remote command that remains active for the duration of a benchmark on a virtual thread.
      Parameters:
      cmd - command
      input - command standard input
      isOutput - whether output should be retained
      timeoutSeconds - command timeout
      Returns:
      asynchronous response
      Throws:
      ConnectException - when the SSH session is unavailable

    • copyFileAsync

      public CompletableFuture<Void> copyFileAsync(String srcPath, String dstPath, long timeoutSeconds) throws ConnectException
      Copy one local file to an exact remote path with bulk SCP.
      Parameters:
      srcPath - local source file
      dstPath - remote destination file
      timeoutSeconds - maximum copy duration in seconds
      Returns:
      copy completion
      Throws:
      ConnectException - when no SSH session is available

    • copyFileAsync

      public CompletableFuture<Void> copyFileAsync(String srcPath, String dstPath, long timeoutSeconds, LongConsumer copyProgress) throws ConnectException
      Copy one local file to an exact remote path and report transferred bytes.
      Parameters:
      srcPath - local source file
      dstPath - remote destination file
      timeoutSeconds - maximum copy duration in seconds
      copyProgress - callback receiving each completed byte increment
      Returns:
      copy completion
      Throws:
      ConnectException - when no SSH session is available

    • runRemoteFileOperationAsync

      public <T> CompletableFuture<T> runRemoteFileOperationAsync(SshSession.RemoteFileOperation<T> operation, long timeoutSeconds) throws ConnectException
      Execute a remote file-system operation through Apache MINA SFTP.
      Type Parameters:
      T - result type
      Parameters:
      operation - remote file-system operation
      timeoutSeconds - maximum operation duration
      Returns:
      asynchronous operation result
      Throws:
      ConnectException - when no SSH session is available

    • runRemoteTransferOperationAsync

      public <T> CompletableFuture<T> runRemoteTransferOperationAsync(SshSession.RemoteFileOperation<T> operation, long timeoutSeconds) throws ConnectException
      Execute deployment data movement through Apache MINA SFTP on the bounded transfer executor.
      Type Parameters:
      T - result type
      Parameters:
      operation - remote file-system transfer operation
      timeoutSeconds - maximum operation duration
      Returns:
      asynchronous operation result
      Throws:
      ConnectException - when no SSH session is available

    • cancelActiveOperations

      public void cancelActiveOperations()
      Cancel all currently running operations without permanently closing this session.

    • stop

      public void stop()
      This method is responsible for closing session and stopping the client.