@microsoft/dev-tunnels-ssh-tcp/services/portForwardingService.d.ts

SSH TCP extensions library for Dev Tunnels

/// <reference types="node" />
import { SshService, SshRequestEventArgs, SessionRequestMessage, SshChannelOpeningEventArgs, SshStream, CancellationToken } from '@microsoft/dev-tunnels-ssh';
import { Duplex } from 'stream';
import { ForwardedPortsCollection } from '../events/forwardedPortsCollection';
import { TcpListenerFactory } from '../tcpListenerFactory';
import { PortForwardMessageFactory } from '../portForwardMessageFactory';
import { LocalPortForwarder } from './localPortForwarder';
import { RemotePortForwarder } from './remotePortForwarder';
import { RemotePortStreamer } from './remotePortStreamer';
import { ForwardedPortConnectingEventArgs } from '../events/forwardedPortEventArgs';
/**
 * Implements the standard SSH port-forwarding protocol.
 * @example
 * Use `SshSessionConfiguration.addService()` on both client and server side configurations
 * to add the `PortForwardingService` type before attempting to call methods on the service.
 * Then use `SshSession.activateService()` to get the service instance:
 *
 *     const config = new SshSessionConfiguration();
 *     config.addService(PortForwardingService);
 *     const client = new SshClient(config);
 *     const session = await client.openSession(host, port);
 *     await session.authenticate(clientCredentials);
 *     const pfs = session.activateService(PortForwardingService);
 *     const forwarder = pfs.forwardToRemotePort('::', 3000);
 */
export declare class PortForwardingService extends SshService {
    static readonly portForwardRequestType = "tcpip-forward";
    static readonly cancelPortForwardRequestType = "cancel-tcpip-forward";
    static readonly portForwardChannelType = "forwarded-tcpip";
    static readonly reversePortForwardChannelType = "direct-tcpip";
    /**
     * Maps from FORWARDED port number to the object that manages listening for incoming
     * connections for that port and forwarding them through the session.
     *
     * Note the actual local source port number used may be different from the forwarded port
     * number if the local TCP listener factory chose a different port. The forwarded port number
     * is used to identify the port in any messages exchanged between client and server.
     */
    private readonly localForwarders;
    /**
     * Maps from FORWARDED port numbers to the object that manages relaying forwarded connections
     * from the session to a local port.
     *
     * Note the actual local destination port number used may be different from the forwarded port
     * number. The forwarded port number is used to identify the port in any messages exchanged
     * between client and server.
     */
    private readonly remoteConnectors;
    /**
     * Gets or sets a value that controls whether the port-forwarding service listens on
     * local TCP sockets to accept connections for ports that are forwarded from the remote side.
     *
     * The default is true.
     *
     * This property is typically initialized before connecting a session (if not keeping the
     * default). It may be changed at any time while the session is connected, and the new value
     * will affect any newly forwarded ports after that, but not previously-forwarded ports.
     *
     * Regardless of whether this is enabled, connections to forwarded ports can be made using
     * `connectToForwardedPort()`.
     */
    acceptLocalConnectionsForForwardedPorts: boolean;
    /**
     * Gets or sets a value that controls whether the port-forwarding service forwards connections
     * to local TCP sockets.
     *
     * The default is true.
     *
     * This property is typically initialized before connecting a session (if not keeping the
     * default). It may be changed at any time while the session is connected, and the new value
     * will affect any newly forwarded ports after that, but not previously-forwarded ports.
     */
    forwardConnectionsToLocalPorts: boolean;
    /**
     * Gets or sets a value that controls whether the port-forwarding service accepts
     * 'direct-tcpip' channel open requests and forwards the channel connections to the local port.
     *
     * The default is true.
     *
     * This property is typically initialized before connecting a session (if not keeping the
     * default). It may be changed at any time while the session is connected, and the new value
     * will affect any newly forwarded ports after that, but not previously-forwarded ports.
     *
     * Regardless of whether this is enabled, the remote side can open 'forwarded-tcpip' channels
     * to connect to ports that were explicitly forwarded by this side.
     */
    acceptRemoteConnectionsForNonForwardedPorts: boolean;
    /**
     * Gets the collection of ports that are currently being forwarded from the remote side
     * to the local side.
     *
     * Ports are added to this collection when `forwardFromRemotePort()` or
     * `streamFromRemotePort()` is called (and the other side accepts the
     * 'tcpip-forward' request), and then are removed when the `RemotePortForwarder`
     * is disposed (which also sends a 'cancel-tcpip-forward' message).
     *
     * Each forwarded port may have 0 or more active connections (channels).
     *
     * The collection does not include direct connections initiated via
     * `forwardToRemotePort()` or `streamToRemotePort()`.
     *
     * Local forwarded ports may or may not have local TCP listeners automatically set up,
     * depending on the value of `acceptLocalConnectionsForForwardedPorts`.
     */
    readonly localForwardedPorts: ForwardedPortsCollection;
    /**
     * Gets the collection of ports that are currently being forwarded from the local side
     * to the remote side.
     *
     * Ports are added to this collection when the port-forwarding service handles a
     * 'tcpip-forward' request message, and removed when it receives a 'cancel-tcpip-forward'
     * request message.
     *
     * Each forwarded port may have 0 or more active connections (channels).
     *
     * The collection does not include direct connections initiated via
     * `forwardToRemotePort()` or `streamToRemotePort()`.
     */
    readonly remoteForwardedPorts: ForwardedPortsCollection;
    /**
     * Gets or sets a factory for creating TCP listeners.
     *
     * Applications may override this factory to provide custom logic for selecting
     * local port numbers to listen on for port-forwarding.
     *
     * This factory is not used when `acceptLocalConnectionsForForwardedPorts` is
     * set to false.
     */
    tcpListenerFactory: TcpListenerFactory;
    /**
     * Gets or sets a factory for creating port-forwarding messages.
     *
     * A message factory enables applications to extend port-forwarding by providing custom
     * message subclasses that may include additional properties.
     */
    messageFactory: PortForwardMessageFactory;
    private readonly forwardedPortConnectingEmitter;
    /**
     * Event raised when an incoming or outgoing connection to a forwarded port is
     * about to be established.
     */
    readonly onForwardedPortConnecting: import("vscode-jsonrpc").Event<ForwardedPortConnectingEventArgs>;
    /**
     * Sends a request to the remote side to listen on a port and forward incoming connections
     * as SSH channels of type 'forwarded-tcpip', which will then be relayed to the same port
     * number on the local side.
     *
     * @param remoteIPAddress IP address of the interface to bind to on the remote side.
     * @param remotePort The port number to forward. (Must not be 0.)
     * @param cancellation Cancellation token for the request; note this cannot cancel forwarding
     * once it has started; use the returned disposable do do that.
     * @returns A disposable object that when disposed will cancel forwarding the port, or `null` if
     * the request was rejected by the remote side, possibly because the port was already in use.
     * Disposing the returned object does not close any channels currently forwarding connections;
     * it only sends a request to the remote side to stop listening on the remote port.
     */
    forwardFromRemotePort(remoteIPAddress: string, remotePort: number, cancellation?: CancellationToken): Promise<RemotePortForwarder | null>;
    /**
     * Sends a request to the remote side to listen on a port and forward incoming connections
     * as SSH channels of type 'forwarded-tcpip', which will then be relayed to a specified
     * local port.
     *
     * @param remoteIPAddress IP address of the interface to bind to on the remote side.
     * @param remotePort The remote port to listen on, or 0 to choose an available port. (The
     * chosen port can then be obtained via the `remotePort` property on the returned object.)
     * @param localHost The destination hostname or IP address for forwarded connections, to be
     * resolved on the local side. WARNING: Avoid using the hostname `localhost` as the destination
     * host; use `127.0.0.1` or `::1` instead. (OpenSSH does not recognize `localhost` as a valid
     * destination host.)
     * @param localPort The destination port for forwarded connections. Defaults to the same as
     * the remote port. (Must not be 0.)
     * @param cancellation Cancellation token for the request; note this cannot cancel forwarding
     * once it has started; use the returned disposable do do that.
     * @returns A disposable object that when disposed will cancel forwarding the port, or `null` if
     * the request was rejected by the remote side, possibly because the port was already in use.
     * Disposing the returned object does not close any channels currently forwarding connections;
     * it only sends a request to the remote side to stop listening on the remote port.
     */
    forwardFromRemotePort(remoteIPAddress: string, remotePort: number, localHost: string, localPort: number, cancellation?: CancellationToken): Promise<RemotePortForwarder | null>;
    /**
     * Starts listening on a local port and forwards incoming connections as SSH channels of type
     * 'direct-tcpip', which will then be relayed to the same port number on the remote side,
     * regardless of whether the remote side has explicitly forwarded that port.
     *
     * @param localIPAddress IP address of the interface to bind to on the local side.
     * @param localPort The port number to forward. (Must not be 0.)
     * @param cancellation Cancellation token for the request; note this cannot cancel forwarding
     * once it has started; use the returned disposable do do that.
     * @returns A disposable object that when disposed will cancel forwarding the port.
     * Disposing the returned object does not close any channels currently forwarding connections;
     * it only stops listening on the local port.
     * @throws If the local port is already in use.
     */
    forwardToRemotePort(localIPAddress: string, localPort: number, cancellation?: CancellationToken): Promise<LocalPortForwarder>;
    /**
     * Starts listening on a local port and forwards incoming connections as SSH channels of type
     * 'direct-tcpip', which will then be relayed to a specified remote port, regardless of whether
     * the remote side has explicitly forwarded that port.
     *
     * @param localIPAddress IP address of the interface to bind to on the local side.
     * @param localPort he local port number to lsiten on, or 0 to choose an available port.
     * (The chosen port can then be obtained via the `localPort` property on the returned object.)
     * @param remoteHost The destination hostname or IP address for forwarded connections, to be
     * resolved on the remote side. WARNING: Avoid using the hostname `localhost` as the destination
     * host; use `127.0.0.1` or `::1` instead. (OpenSSH does not recognize `localhost` as a valid
     * destination host.)
     * @param remotePort The destination port for forwarded connections. Defaults to the same
     * as the local port. (Must not be 0.)
     * @param cancellation Cancellation token for the request; note this cannot cancel forwarding
     * once it has started; use the returned disposable do do that.
     * @returns A disposable object that when disposed will cancel forwarding the port.
     * Disposing the returned object does not close any channels currently forwarding connections;
     * it only stops listening on the local port.
     * @throws If the local port is already in use.
     */
    forwardToRemotePort(localIPAddress: string, localPort: number, remoteHost: string, remotePort: number, cancellation?: CancellationToken): Promise<LocalPortForwarder>;
    /**
     * Sends a request to the remote side to listen on a port and forward incoming connections as
     * SSH channels of type 'forwarded-tcpip', which will then be relayed as local streams.
     *
     * @param remoteIPAddress IP address of the interface to bind to on the remote side.
     * @param remotePort The remote port to listen on, or 0 to choose an available port.
     * (The chosen port can then be obtained via the `remotePort` property on the returned object.)
     * @param cancellation Cancellation token for the request; note this cannot cancel forwarding
     * once it has started; use the returned disposable do do that.
     * @returns A disposable object that when disposed will cancel forwarding the port, or `null`
     * if the request was rejected by the remote side, possibly because the remote port was already
     * in use. Handle the `onStreamOpened` event on this object to receive streams.
     */
    streamFromRemotePort(remoteIPAddress: string, remotePort: number, cancellation?: CancellationToken): Promise<RemotePortStreamer | null>;
    /**
     * Opens a stream for an SSH channel of type 'direct-tcpip' that is relayed to remote port,
     * regardless of whether the remote side has explicitly forwarded that port.
     *
     * @param remoteHost The destination hostname or IP address for forwarded connections, to be
     * resolved on the remote side. WARNING: Avoid using the hostname `localhost` as the destination
     * host; use `127.0.0.1` or `::1` instead. (OpenSSH does not recognize `localhost` as a valid
     * destination host.)
     * @param remotePort The destination port for the forwarded stream. (Must not be 0.)
     * @param cancellation Cancellation token for the request; note this cannot cancel streaming
     * once it has started; dipose the returned stream for that.
     * @returns A stream that is relayed to the remote port.
     * @throws `SshChannelError` if the streaming channel could not be opened, either because it
     * was rejected by the remote side, or the remote connection failed.
     */
    streamToRemotePort(remoteHost: string, remotePort: number, cancellation?: CancellationToken): Promise<SshStream>;
    /**
     * Opens a stream for an SSH channel of type 'forwarded-tcpip' that is relayed to a remote
     * port. The port must have been explicitly forwarded by the remote side.
     *
     * It may be necessary to call `waitForForwardedPort` before this method
     * to ensure the port is ready for connections.
     *
     * An error is thrown if the requested port could not be forwarded, possibly because it was
     * rejected by the remote side, or the remote connection failed.
     *
     * @param forwardedPort Remote port number that was forwarded.
     * @param cancellation Cancellation token for the request; note this cannot
     * cancel streaming once it has started; dipose the returned stream for that.
     * @returns A stream that is relayed to the remote forwarded port.
     */
    connectToForwardedPort(forwardedPort: number, cancellation?: CancellationToken): Promise<Duplex>;
    /**
     * Waits asynchronously for the remote side to forward an expected port number.
     *
     * A common pattern for some applications may be to call this method just before
     * `ConnectToForwardedPortAsync`.
     *
     * @param forwardedPort Port number that is expected to be forwarded.
     * @param cancellation Token that can be used to cancel waiting.
     * @returns A promise that completes when the expected port number has been forwarded.
     */
    waitForForwardedPort(forwardedPort: number, cancellation?: CancellationToken): Promise<void>;
    protected onSessionRequest(request: SshRequestEventArgs<SessionRequestMessage>, cancellation?: CancellationToken): Promise<void>;
    private startForwarding;
    private cancelForwarding;
    protected onChannelOpening(request: SshChannelOpeningEventArgs, cancellation?: CancellationToken): Promise<void>;
    dispose(): void;
}
//# sourceMappingURL=portForwardingService.d.ts.map