pub struct GitwaySession { /* private fields */ }Expand description
An active SSH session connected to a GitHub (or GHE) host.
§Typical Usage
use gitway_lib::{GitwayConfig, GitwaySession};
let config = GitwayConfig::github();
let mut session = GitwaySession::connect(&config).await?;
// authenticate, exec, close…Implementations§
Source§impl GitwaySession
impl GitwaySession
Sourcepub async fn connect(config: &GitwayConfig) -> Result<Self, GitwayError>
pub async fn connect(config: &GitwayConfig) -> Result<Self, GitwayError>
Establishes a TCP connection to the host in config and completes the
SSH handshake (including host-key verification).
Does not authenticate; call authenticate or
authenticate_best after this.
§Errors
Returns an error on network failure or if the server’s host key does not match any pinned fingerprint.
Sourcepub async fn authenticate(
&mut self,
username: &str,
key: PrivateKeyWithHashAlg,
) -> Result<(), GitwayError>
pub async fn authenticate( &mut self, username: &str, key: PrivateKeyWithHashAlg, ) -> Result<(), GitwayError>
Authenticates with an explicit key.
Use [authenticate_best] to let the library discover the key
automatically.
§Errors
Returns an error on SSH protocol failures. Returns
GitwayError::is_authentication_failed when the server accepts the
exchange but rejects the key.
Sourcepub async fn authenticate_with_cert(
&mut self,
username: &str,
key: PrivateKey,
cert: Certificate,
) -> Result<(), GitwayError>
pub async fn authenticate_with_cert( &mut self, username: &str, key: PrivateKey, cert: Certificate, ) -> Result<(), GitwayError>
Authenticates with a private key and an accompanying OpenSSH certificate (FR-12).
The certificate is presented to the server in place of the raw public
key. This is typically used with organisation-issued certificates that
grant access without requiring the public key to be listed in
authorized_keys.
§Errors
Returns an error on SSH protocol failures or if the server rejects the certificate.
Sourcepub async fn authenticate_best(
&mut self,
config: &GitwayConfig,
) -> Result<(), GitwayError>
pub async fn authenticate_best( &mut self, config: &GitwayConfig, ) -> Result<(), GitwayError>
Discovers the best available key and authenticates using it.
Priority order (FR-9):
- Explicit
--identitypath from config. - Default
.sshpaths (id_ed25519→id_ecdsa→id_rsa). - SSH agent via
$SSH_AUTH_SOCK(Unix only).
If a certificate path is configured in config.cert_file, certificate
authentication (FR-12) is used instead of raw public-key authentication
for file-based keys.
When the chosen key requires a passphrase this method returns an error
whose is_key_encrypted predicate is
true; the caller (CLI layer) should then prompt and call
authenticate_with_passphrase.
§Errors
Returns GitwayError::is_no_key_found when no key is available via
any discovery method.
Sourcepub async fn authenticate_with_passphrase(
&mut self,
config: &GitwayConfig,
path: &Path,
passphrase: &str,
) -> Result<(), GitwayError>
pub async fn authenticate_with_passphrase( &mut self, config: &GitwayConfig, path: &Path, passphrase: &str, ) -> Result<(), GitwayError>
Loads an encrypted key with passphrase and authenticates.
Call this after [authenticate_best] returns an encrypted-key error
and the CLI has collected the passphrase from the terminal.
If config.cert_file is set, certificate authentication is used
(FR-12).
§Errors
Returns an error if the passphrase is wrong or authentication fails.
Sourcepub async fn authenticate_with_agent(
&mut self,
username: &str,
conn: AgentConnection,
) -> Result<(), GitwayError>
pub async fn authenticate_with_agent( &mut self, username: &str, conn: AgentConnection, ) -> Result<(), GitwayError>
Tries each identity held in conn until one succeeds or all are
exhausted.
On Unix this is called automatically by [authenticate_best] when no
file-based key is found. For plain public-key identities the signing
challenge is forwarded to the agent; for certificate identities the
full certificate is presented alongside the agent-signed challenge.
§Errors
Returns GitwayError::is_authentication_failed if all identities are
rejected, or GitwayError::is_no_key_found if the agent was empty.
Sourcepub async fn exec(&mut self, command: &str) -> Result<u32, GitwayError>
pub async fn exec(&mut self, command: &str) -> Result<u32, GitwayError>
Opens a session channel, executes command, and relays stdio
bidirectionally until the remote process exits.
Returns the remote exit code (FR-16). Exit-via-signal returns
128 + signal_number (FR-17).
§Errors
Returns an error on channel open failure or SSH protocol errors.
Sourcepub async fn close(self) -> Result<(), GitwayError>
pub async fn close(self) -> Result<(), GitwayError>
Sends a graceful SSH_MSG_DISCONNECT and closes the connection.
§Errors
Returns an error if the disconnect message cannot be sent.
Returns the authentication banner last received from the server (if any).
For GitHub.com this contains the “Hi
§Panics
Panics if the internal mutex is poisoned, which can only occur if another thread panicked while holding the lock — a programming error.