@microsoft/dev-tunnels-ssh/sshSession.d.ts

SSH library for Dev Tunnels

/// <reference types="node" />
import { Trace } from './trace';
import { Buffer } from 'buffer';
import { CancellationToken, Event, Disposable } from 'vscode-jsonrpc';
import { Stream } from './streams';
import { SshSessionConfiguration } from './sshSessionConfiguration';
import { SshChannel } from './sshChannel';
import { SshVersionInfo } from './sshVersionInfo';
import { KeyExchangeService } from './services/keyExchangeService';
import { SshService, SshServiceConstructor } from './services/sshService';
import { ConnectionService } from './services/connectionService';
import { SshMessage } from './messages/sshMessage';
import { ChannelRequestMessage, ChannelOpenMessage } from './messages/connectionMessages';
import { SshDisconnectReason, SessionRequestMessage, SessionRequestSuccessMessage, SessionRequestFailureMessage } from './messages/transportMessages';
import { SessionMetrics } from './metrics/sessionMetrics';
import { SshAuthenticatingEventArgs } from './events/sshAuthenticatingEventArgs';
import { SshSessionClosedEventArgs } from './events/sshSessionClosedEventArgs';
import { SshChannelOpeningEventArgs } from './events/sshChannelOpeningEventArgs';
import { SshRequestEventArgs } from './events/sshRequestEventArgs';
import { SshSessionAlgorithms } from './sshSessionAlgorithms';
import { SshReportProgressEventArgs } from './events/sshReportProgressEventArgs';
export declare const enum ExtensionRequestTypes {
    initialChannelRequest = "initial-channel-request@microsoft.com",
    enableSessionReconnect = "enable-session-reconnect@microsoft.com",
    sessionReconnect = "session-reconnect@microsoft.com",
    keepAliveRequest = "keepalive@openssh.com"
}
/**
 * Base class for an SSH server or client connection; coordinates high-level SSH
 * protocol details and dispatches messages to registered internal services.
 * Enables opening and accepting `SshChannel` instances.
 */
export declare class SshSession implements Disposable {
    readonly config: SshSessionConfiguration;
    static readonly localVersion: SshVersionInfo;
    remoteVersion: SshVersionInfo | null;
    private readonly activatedServices;
    protected kexService: KeyExchangeService | null;
    protected connectionService: ConnectionService | null;
    private connectPromise?;
    private requestHandlers;
    private versionExchangePromise?;
    private readonly blockedMessages;
    private readonly blockedMessagesSemaphore;
    private connected;
    private disposed;
    private sessionNumber;
    private closedError?;
    private keepAliveTimer?;
    private keepAliveResponseReceived;
    private keepAliveFailureCount;
    private keepAliveSuccessCount;
    get algorithms(): SshSessionAlgorithms | null;
    /**
     * Gets an object that reports current and cumulative measurements about the session.
     */
    readonly metrics: SessionMetrics;
    sessionId: Buffer | null;
    private principalValue;
    /**
     * Gets an object containing claims about the server or client on the
     * other end of the session, or `null` if the session is not authenticated.
     *
     * This property is initially `null` for an unauthenticated session. On
     * successful authentication, the session Authenticating event handler
     * provides a Task that returns a principal that is stored here.
     */
    get principal(): object | null;
    private readonly authenticatingEmitter;
    /**
     * Event that is raised when a client or server is requesting authentication.
     *
     * See `SshAuthenticationType` for a description of the different authentication
     * methods and how they map to the event-args object.
     *
     * After validating the credentials, the event handler must set the
     * `SshAuthenticatingEventArgs.authenticationPromise` property to a task that
     * resolves to a principal object to indicate successful authentication. That principal will
     * then be associated with the sesssion as the `principal` property.
     */
    readonly onAuthenticating: Event<SshAuthenticatingEventArgs>;
    private readonly closedEmitter;
    readonly onClosed: Event<SshSessionClosedEventArgs>;
    private readonly disconnectedEmitter;
    readonly onDisconnected: Event<void>;
    private readonly serviceActivatedEmitter;
    readonly onServiceActivated: Event<SshService>;
    private readonly channelOpeningEmitter;
    readonly onChannelOpening: Event<SshChannelOpeningEventArgs>;
    private readonly requestEmitter;
    readonly onRequest: Event<SshRequestEventArgs<SessionRequestMessage>>;
    private readonly reportProgressEmitter;
    /**
     * Event that is raised to report connection progress.
     *
     * Apps may use this to provide progress feedback to users during the initial
     * connection or reconnection process.
     *
     * See `Progress` for a description of the different progress events that can be reported.
     */
    readonly onReportProgress: Event<SshReportProgressEventArgs>;
    private readonly keepAliveFailedEmitter;
    /**
     * Event that is raised when a keep-alive message response is not received.
     */
    readonly onKeepAliveFailed: Event<number>;
    private readonly keepAliveSucceededEmitter;
    /**
     * Event that is raised when a keep-alive message response is received.
     */
    readonly onKeepAliveSucceeded: Event<number>;
    /**
     * Gets or sets a function that handles trace messages associated with the session.
     *
     * By default, no messages are traced. To enable tracing, set this property to a function
     * that routes the message to console.log, a file, or anywhere else.
     *
     * @param level Level of message: error, warning, info, or verbose
     * @param eventId Integer identifier of the event being traced.
     * @param msg Message (non-localized) describing the event.
     */
    trace: Trace;
    constructor(config: SshSessionConfiguration, isClientSession?: boolean);
    get isConnected(): boolean;
    get isClosed(): boolean;
    get services(): readonly SshService[];
    get channels(): readonly SshChannel[];
    get protocolExtensions(): Map<string, string> | null;
    /**
     * Gets an activated service instance by type.
     *
     * @returns The service instance, or `null` if the service has not been activated.
     */
    getService<T extends SshService>(serviceType: SshServiceConstructor<T>): T | null;
    /**
     * Activates a service by name (if not already activated).
     *
     * The service must declare support for activation by name,
     * via `ServiceActivation.serviceRequest`.
     *
     * @returns The activated service instance, or `null` if no service could be found that declares
     * support for activation with the specified name.
     */
    activateService(serviceName: string): SshService | null;
    /**
     * Activates a service by type (if not already activated).
     *
     * @returns The activated service instance.
     * @throws If the service type is not found in the sesion configuration.
     */
    activateService<T extends SshService>(serviceType: SshServiceConstructor<T>): T;
    connect(stream: Stream, cancellation?: CancellationToken): Promise<void>;
    private doConnect;
    private exchangeVersions;
    private encrypt;
    sendMessage(message: SshMessage, cancellation?: CancellationToken): Promise<void>;
    /**
     * Handles an incoming message. Can be overridden by subclasses to handle additional
     * message types that are registered via `SshSessionConfiguration.messages`.
     */
    protected handleMessage(message: SshMessage, cancellation?: CancellationToken): void | Promise<void>;
    private handleKeyExchangeMessage;
    private handleUnimplementedMessage;
    private handleDebugMessage;
    private startKeepAliveTimer;
    private onKeepAliveTimeout;
    /**
     * Sends a session request and waits for a response.
     *
     * Note if `wantReply` is `false`, this method returns `true` immediately after sending
     * the request, without waiting for a response.
     *
     * @returns The authorization status of the response; if `false`, the other side denied the
     * request.
     */
    request(request: SessionRequestMessage, cancellation?: CancellationToken): Promise<boolean>;
    /**
     * Sends a session request and waits for a specific type of success or failure message.
     *
     * @returns The success or failure response message.
     */
    requestResponse<TSuccess extends SessionRequestSuccessMessage, TFailure extends SessionRequestFailureMessage>(request: SessionRequestMessage, successType: {
        new (): TSuccess;
    }, failureType: {
        new (): TFailure;
    }, cancellation?: CancellationToken): Promise<TSuccess | TFailure>;
    private handleRequestSuccessMessage;
    private handleRequestFailureMessage;
    private invokeRequestHandler;
    /**
     * Asynchronously waits for the other side to open a channel.
     *
     * @returns The opened channel.
     */
    acceptChannel(cancellation?: CancellationToken): Promise<SshChannel>;
    /**
     * Asynchronously waits for the other side to open a channel.
     *
     * @param channelType Channel type to accept. If unspecified, defaults to the standard
     * "session" channel type. (Other channel types will not be accepted.)
     * @returns The opened channel.
     */
    acceptChannel(channelType?: string, cancellation?: CancellationToken): Promise<SshChannel>;
    /**
     * Opens a channel and asynchronously waits for the other side to accept it.
     *
     * @returns The opened channel.
     */
    openChannel(cancellation?: CancellationToken): Promise<SshChannel>;
    /**
     * Opens a channel and asynchronously waits for the other side to accept it.
     *
     * @param channelType Channel type to open. If unspecified, defaults to the standard
     * "session" channel type.
     * @returns The opened channel.
     */
    openChannel(channelType: string | null, cancellation?: CancellationToken): Promise<SshChannel>;
    /**
     * Opens a channel and asynchronously waits for the other side to accept it.
     * Optionally sends an initial request and also waits for a response to that request.
     *
     * This uses a private extension to the SSH protocol to avoid an extra round-trip when
     * opening a channel and sending the first channel request. If the other side doesn't
     * support the extension, then the standard protocol is used as a fallback.
     *
     * @param openMessage Open message to be sent, including channel type. May be a subclass
     * of `ChannelOpenMessage`.
     * @param initialRequest Optional initial request sent over the channel, often used
     * to establish the purpose of the channel.
     * @returns The opened channel.
     */
    openChannel(openMessage: ChannelOpenMessage, initialRequest?: ChannelRequestMessage | null, cancellation?: CancellationToken): Promise<SshChannel>;
    private openChannelWithInitialRequest;
    private handleExtensionInfoMessage;
    close(reason: SshDisconnectReason, message?: string, error?: Error): Promise<void>;
    private handleDisconnectMessage;
    dispose(): void;
    /**
     * Pipes one SSH session into another, relaying all data between them.
     *
     * Any new channels opened from the remote side of either session will be piped into a
     * new channel in the other session. Any channels opened before connecting the session pipe,
     * or any channels opened from the local side, will not be piped.
     *
     * @param toSession Session to which the current session will be connected via the pipe.
     * @returns A promise that resolves when the sessions are closed.
     */
    pipe(toSession: SshSession): Promise<void>;
    toString(): string;
}
//# sourceMappingURL=sshSession.d.ts.map