@zero-transfer/sftp 0.3.1 → 0.4.0

package/dist/index.d.mts

@@ -1644,6 +1644,65 @@ interface RunConnectionDiagnosticsOptions {
  */
 declare function runConnectionDiagnostics(options: RunConnectionDiagnosticsOptions): Promise<ConnectionDiagnosticsResult>;
 
+/** Options for {@link createPooledTransferClient}. */
+interface ConnectionPoolOptions {
+    /**
+     * Maximum number of *idle* sessions retained per pool key.
+     *
+     * Active leases are not counted against this limit — the cap only applies
+     * to sessions waiting in the pool. When more than `maxIdlePerKey` sessions
+     * become idle simultaneously, the oldest ones are disconnected. Defaults
+     * to `4`.
+     */
+    maxIdlePerKey?: number;
+    /**
+     * How long an idle session may sit unused before it is automatically
+     * disconnected. Defaults to `60_000` ms. Set to `0` to disable the timer
+     * (idle sessions persist until `drainPool()` is called).
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Custom pool key derivation. Receives the resolved
+     * {@link ConnectionProfile} (after TransferClient validation) and must
+     * return a string. Sessions with matching keys are pooled together; never
+     * include secrets in the key.
+     *
+     * The default derives the key from `provider`, `host`, `port`, and
+     * `username`.
+     */
+    keyOf?: (profile: ConnectionProfile) => string;
+}
+/**
+ * Pool-aware {@link TransferClient} returned by
+ * {@link createPooledTransferClient}.
+ */
+interface PooledTransferClient {
+    /** Opens (or leases) a pooled provider session. */
+    connect(profile: ConnectionProfile): Promise<TransferSession>;
+    /** Inspects the registered providers (delegated to the underlying client). */
+    hasProvider(providerId: ProviderId): boolean;
+    /** Returns the registered capability snapshots (delegated). */
+    getCapabilities(): CapabilitySet[];
+    /** Returns a specific capability snapshot (delegated). */
+    getCapabilities(providerId: ProviderId): CapabilitySet;
+    /**
+     * Disconnects every idle session and prevents further pooling. After
+     * `drainPool()` resolves, subsequent `connect()` calls still work but
+     * always create fresh sessions (and never return them to the pool).
+     */
+    drainPool(): Promise<void>;
+    /** Returns the number of idle sessions currently held in the pool. */
+    poolSize(): number;
+}
+/**
+ * Wraps a {@link TransferClient} with connection pooling.
+ *
+ * @param inner - Underlying client used to create real provider sessions.
+ * @param options - Pool sizing, eviction, and key-derivation overrides.
+ * @returns A {@link PooledTransferClient} that reuses idle sessions.
+ */
+declare function createPooledTransferClient(inner: TransferClient, options?: ConnectionPoolOptions): PooledTransferClient;
+
 /** Options used to create a local file-system provider factory. */
 interface LocalProviderOptions {
     /** Root directory exposed as `/`. When omitted, `profile.host` is treated as the root path. */
@@ -3641,6 +3700,15 @@ interface NativeSftpProviderOptions {
      * traffic. Disabled when omitted or `0`.
      */
     keepaliveIntervalMs?: number;
+    /**
+     * Maximum concurrent file-transfer operations the engine should schedule
+     * against a single SFTP session. Each in-flight read/write occupies an
+     * outstanding SFTP request slot multiplexed over the same SSH channel; the
+     * default of `8` keeps memory bounded on commodity servers, but high-RTT
+     * links and modern OpenSSH builds can comfortably handle 16\u201364. Must be
+     * a positive integer.
+     */
+    maxConcurrency?: number;
 }
 /**
  * Low-level handles exposed by a native SFTP session for diagnostics and
@@ -3704,4 +3772,4 @@ interface NativeSftpRawSession {
  */
 declare function createNativeSftpProviderFactory(options?: NativeSftpProviderOptions): ProviderFactory;
 
-export { AbortError, type AtomicDeployActivateOperation, type AtomicDeployActivateStep, type AtomicDeployPlan, type AtomicDeployPruneStep, type AtomicDeployStrategy, type AuthenticationCapability, AuthenticationError, AuthorizationError, type BandwidthSleep, type BandwidthThrottle, type BandwidthThrottleOptions, type Base64EnvSecretSource, type BuiltInProviderId, CLASSIC_PROVIDER_IDS, type CapabilitySet, type ChecksumCapability, type ClassicProviderId, type ClientDiagnostics, type CompareRemoteManifestsOptions, ConfigurationError, type ConnectionDiagnosticTimings, type ConnectionDiagnosticsResult, ConnectionError, type ConnectionProfile, type CopyBetweenOptions, type CreateAtomicDeployPlanOptions, type CreateRemoteBrowserOptions, type CreateRemoteManifestOptions, type CreateSyncPlanOptions, type DiffRemoteTreesOptions, type DownloadFileOptions, type EnvSecretSource, type FileSecretSource, type FileZillaSite, type FriendlyTransferOptions, type FtpReplyErrorInput, type ImportFileZillaSitesResult, type ImportOpenSshConfigOptions, type ImportOpenSshConfigResult, type ImportWinScpSessionsResult, type KnownHostsEntry, type KnownHostsMarker, type ListOptions, type LocalProviderOptions, type LogLevel, type LogRecord, type LogRecordInput, type LoggerMethod, type MemoryProviderEntry, type MemoryProviderOptions, type MetadataCapability, type MkdirOptions, type NativeSftpProviderOptions, type NativeSftpRawSession, type OAuthAccessToken, type OAuthRefreshCallback, type OAuthTokenSecretSourceOptions, type OpenSshConfigEntry, ParseError, PathAlreadyExistsError, PathNotFoundError, PermissionDeniedError, type ProgressEventInput, ProtocolError, type AuthenticationCapability as ProviderAuthenticationCapability, type CapabilitySet as ProviderCapabilities, type ChecksumCapability as ProviderChecksumCapability, type ProviderFactory, type ProviderId, type MetadataCapability as ProviderMetadataCapability, ProviderRegistry, type ProviderSelection, type ProviderTransferEndpointRole, type ProviderTransferExecutorOptions, type ProviderTransferOperations, type ProviderTransferReadRequest, type ProviderTransferReadResult, type ProviderTransferRequest, type ProviderTransferSessionResolver, type ProviderTransferSessionResolverInput, type ProviderTransferWriteRequest, type ProviderTransferWriteResult, REDACTED, REMOTE_MANIFEST_FORMAT_VERSION, type RemoteBreadcrumb, type RemoteBrowser, type RemoteBrowserFilter, type RemoteBrowserSnapshot, type RemoteEntry, type RemoteEntrySortKey, type RemoteEntrySortOrder, type RemoteEntryType, type RemoteFileAdapter, type RemoteFileEndpoint, type RemoteFileSystem, type RemoteManifest, type RemoteManifestEntry, type RemotePermissions, type RemoteProtocol, type RemoteStat, type RemoteTreeDiff, type RemoteTreeDiffEntry, type RemoteTreeDiffReason, type RemoteTreeDiffStatus, type RemoteTreeDiffSummary, type RemoteTreeEntry, type RemoteTreeFilter, type RemoveOptions, type RenameOptions, type ResolveSecretOptions, type ResolvedConnectionProfile, type ResolvedOpenSshHost, type ResolvedSshProfile, type ResolvedTlsProfile, type RmdirOptions, type RunConnectionDiagnosticsOptions, type SecretProvider, type SecretSource, type SecretValue, type NativeSftpProviderOptions as SftpProviderOptions, type NativeSftpRawSession as SftpRawSession, type SpecializedErrorDetails, type SshAgentSource, type SshAlgorithms, type SshKeyboardInteractiveChallenge, type SshKeyboardInteractiveHandler, type SshKeyboardInteractivePrompt, type SshKnownHostsSource, type SshProfile, type SshSocketFactory, type SshSocketFactoryContext, type StatOptions, type SyncConflictPolicy, type SyncDeletePolicy, type SyncDirection, type SyncEndpointInput, TimeoutError, type TlsProfile, type TlsSecretSource, type TransferAttempt, type TransferAttemptError, type TransferBandwidthLimit, type TransferByteRange, TransferClient, type TransferClientOptions, type TransferDataChunk, type TransferDataSource, type TransferEndpoint, TransferEngine, type TransferEngineExecuteOptions, type TransferEngineOptions, TransferError, type TransferExecutionContext, type TransferExecutionResult, type TransferExecutor, type TransferJob, type TransferOperation, type TransferPlan, type TransferPlanAction, type TransferPlanInput, type TransferPlanStep, type TransferPlanSummary, type TransferProgressEvent, type TransferProvider, TransferQueue, type TransferQueueExecutorResolver, type TransferQueueItem, type TransferQueueItemStatus, type TransferQueueOptions, type TransferQueueRunOptions, type TransferQueueSummary, type TransferReceipt, type TransferResult, type TransferResultInput, type TransferRetryDecisionInput, type TransferRetryPolicy, type TransferSession, type TransferTimeoutPolicy, type TransferVerificationResult, UnsupportedFeatureError, type UploadFileOptions, type ValueSecretSource, VerificationError, type WalkRemoteTreeOptions, type WinScpSession, ZeroTransfer, type ZeroTransferCapabilities, ZeroTransferError, type ZeroTransferErrorDetails, type ZeroTransferLogger, type ZeroTransferOptions, assertSafeFtpArgument, basenameRemotePath, buildRemoteBreadcrumbs, compareRemoteManifests, copyBetween, createAtomicDeployPlan, createBandwidthThrottle, createLocalProviderFactory, createMemoryProviderFactory, createNativeSftpProviderFactory, createOAuthTokenSecretSource, createProgressEvent, createProviderTransferExecutor, createRemoteBrowser, createRemoteManifest, createNativeSftpProviderFactory as createSftpProviderFactory, createSyncPlan, createTransferClient, createTransferJobsFromPlan, createTransferPlan, createTransferResult, diffRemoteTrees, downloadFile, emitLog, errorFromFtpReply, filterRemoteEntries, importFileZillaSites, importOpenSshConfig, importWinScpSessions, isClassicProviderId, isSensitiveKey, joinRemotePath, matchKnownHosts, matchKnownHostsEntry, noopLogger, normalizeRemotePath, parentRemotePath, parseKnownHosts, parseOpenSshConfig, parseRemoteManifest, redactCommand, redactConnectionProfile, redactObject, redactSecretSource, redactValue, resolveConnectionProfileSecrets, resolveOpenSshHost, resolveProviderId, resolveSecret, runConnectionDiagnostics, serializeRemoteManifest, sortRemoteEntries, summarizeClientDiagnostics, summarizeTransferPlan, throttleByteIterable, uploadFile, validateConnectionProfile, walkRemoteTree };
+export { AbortError, type AtomicDeployActivateOperation, type AtomicDeployActivateStep, type AtomicDeployPlan, type AtomicDeployPruneStep, type AtomicDeployStrategy, type AuthenticationCapability, AuthenticationError, AuthorizationError, type BandwidthSleep, type BandwidthThrottle, type BandwidthThrottleOptions, type Base64EnvSecretSource, type BuiltInProviderId, CLASSIC_PROVIDER_IDS, type CapabilitySet, type ChecksumCapability, type ClassicProviderId, type ClientDiagnostics, type CompareRemoteManifestsOptions, ConfigurationError, type ConnectionDiagnosticTimings, type ConnectionDiagnosticsResult, ConnectionError, type ConnectionPoolOptions, type ConnectionProfile, type CopyBetweenOptions, type CreateAtomicDeployPlanOptions, type CreateRemoteBrowserOptions, type CreateRemoteManifestOptions, type CreateSyncPlanOptions, type DiffRemoteTreesOptions, type DownloadFileOptions, type EnvSecretSource, type FileSecretSource, type FileZillaSite, type FriendlyTransferOptions, type FtpReplyErrorInput, type ImportFileZillaSitesResult, type ImportOpenSshConfigOptions, type ImportOpenSshConfigResult, type ImportWinScpSessionsResult, type KnownHostsEntry, type KnownHostsMarker, type ListOptions, type LocalProviderOptions, type LogLevel, type LogRecord, type LogRecordInput, type LoggerMethod, type MemoryProviderEntry, type MemoryProviderOptions, type MetadataCapability, type MkdirOptions, type NativeSftpProviderOptions, type NativeSftpRawSession, type OAuthAccessToken, type OAuthRefreshCallback, type OAuthTokenSecretSourceOptions, type OpenSshConfigEntry, ParseError, PathAlreadyExistsError, PathNotFoundError, PermissionDeniedError, type PooledTransferClient, type ProgressEventInput, ProtocolError, type AuthenticationCapability as ProviderAuthenticationCapability, type CapabilitySet as ProviderCapabilities, type ChecksumCapability as ProviderChecksumCapability, type ProviderFactory, type ProviderId, type MetadataCapability as ProviderMetadataCapability, ProviderRegistry, type ProviderSelection, type ProviderTransferEndpointRole, type ProviderTransferExecutorOptions, type ProviderTransferOperations, type ProviderTransferReadRequest, type ProviderTransferReadResult, type ProviderTransferRequest, type ProviderTransferSessionResolver, type ProviderTransferSessionResolverInput, type ProviderTransferWriteRequest, type ProviderTransferWriteResult, REDACTED, REMOTE_MANIFEST_FORMAT_VERSION, type RemoteBreadcrumb, type RemoteBrowser, type RemoteBrowserFilter, type RemoteBrowserSnapshot, type RemoteEntry, type RemoteEntrySortKey, type RemoteEntrySortOrder, type RemoteEntryType, type RemoteFileAdapter, type RemoteFileEndpoint, type RemoteFileSystem, type RemoteManifest, type RemoteManifestEntry, type RemotePermissions, type RemoteProtocol, type RemoteStat, type RemoteTreeDiff, type RemoteTreeDiffEntry, type RemoteTreeDiffReason, type RemoteTreeDiffStatus, type RemoteTreeDiffSummary, type RemoteTreeEntry, type RemoteTreeFilter, type RemoveOptions, type RenameOptions, type ResolveSecretOptions, type ResolvedConnectionProfile, type ResolvedOpenSshHost, type ResolvedSshProfile, type ResolvedTlsProfile, type RmdirOptions, type RunConnectionDiagnosticsOptions, type SecretProvider, type SecretSource, type SecretValue, type NativeSftpProviderOptions as SftpProviderOptions, type NativeSftpRawSession as SftpRawSession, type SpecializedErrorDetails, type SshAgentSource, type SshAlgorithms, type SshKeyboardInteractiveChallenge, type SshKeyboardInteractiveHandler, type SshKeyboardInteractivePrompt, type SshKnownHostsSource, type SshProfile, type SshSocketFactory, type SshSocketFactoryContext, type StatOptions, type SyncConflictPolicy, type SyncDeletePolicy, type SyncDirection, type SyncEndpointInput, TimeoutError, type TlsProfile, type TlsSecretSource, type TransferAttempt, type TransferAttemptError, type TransferBandwidthLimit, type TransferByteRange, TransferClient, type TransferClientOptions, type TransferDataChunk, type TransferDataSource, type TransferEndpoint, TransferEngine, type TransferEngineExecuteOptions, type TransferEngineOptions, TransferError, type TransferExecutionContext, type TransferExecutionResult, type TransferExecutor, type TransferJob, type TransferOperation, type TransferPlan, type TransferPlanAction, type TransferPlanInput, type TransferPlanStep, type TransferPlanSummary, type TransferProgressEvent, type TransferProvider, TransferQueue, type TransferQueueExecutorResolver, type TransferQueueItem, type TransferQueueItemStatus, type TransferQueueOptions, type TransferQueueRunOptions, type TransferQueueSummary, type TransferReceipt, type TransferResult, type TransferResultInput, type TransferRetryDecisionInput, type TransferRetryPolicy, type TransferSession, type TransferTimeoutPolicy, type TransferVerificationResult, UnsupportedFeatureError, type UploadFileOptions, type ValueSecretSource, VerificationError, type WalkRemoteTreeOptions, type WinScpSession, ZeroTransfer, type ZeroTransferCapabilities, ZeroTransferError, type ZeroTransferErrorDetails, type ZeroTransferLogger, type ZeroTransferOptions, assertSafeFtpArgument, basenameRemotePath, buildRemoteBreadcrumbs, compareRemoteManifests, copyBetween, createAtomicDeployPlan, createBandwidthThrottle, createLocalProviderFactory, createMemoryProviderFactory, createNativeSftpProviderFactory, createOAuthTokenSecretSource, createPooledTransferClient, createProgressEvent, createProviderTransferExecutor, createRemoteBrowser, createRemoteManifest, createNativeSftpProviderFactory as createSftpProviderFactory, createSyncPlan, createTransferClient, createTransferJobsFromPlan, createTransferPlan, createTransferResult, diffRemoteTrees, downloadFile, emitLog, errorFromFtpReply, filterRemoteEntries, importFileZillaSites, importOpenSshConfig, importWinScpSessions, isClassicProviderId, isSensitiveKey, joinRemotePath, matchKnownHosts, matchKnownHostsEntry, noopLogger, normalizeRemotePath, parentRemotePath, parseKnownHosts, parseOpenSshConfig, parseRemoteManifest, redactCommand, redactConnectionProfile, redactObject, redactSecretSource, redactValue, resolveConnectionProfileSecrets, resolveOpenSshHost, resolveProviderId, resolveSecret, runConnectionDiagnostics, serializeRemoteManifest, sortRemoteEntries, summarizeClientDiagnostics, summarizeTransferPlan, throttleByteIterable, uploadFile, validateConnectionProfile, walkRemoteTree };

package/dist/index.d.ts

@@ -1644,6 +1644,65 @@ interface RunConnectionDiagnosticsOptions {
  */
 declare function runConnectionDiagnostics(options: RunConnectionDiagnosticsOptions): Promise<ConnectionDiagnosticsResult>;
 
+/** Options for {@link createPooledTransferClient}. */
+interface ConnectionPoolOptions {
+    /**
+     * Maximum number of *idle* sessions retained per pool key.
+     *
+     * Active leases are not counted against this limit — the cap only applies
+     * to sessions waiting in the pool. When more than `maxIdlePerKey` sessions
+     * become idle simultaneously, the oldest ones are disconnected. Defaults
+     * to `4`.
+     */
+    maxIdlePerKey?: number;
+    /**
+     * How long an idle session may sit unused before it is automatically
+     * disconnected. Defaults to `60_000` ms. Set to `0` to disable the timer
+     * (idle sessions persist until `drainPool()` is called).
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Custom pool key derivation. Receives the resolved
+     * {@link ConnectionProfile} (after TransferClient validation) and must
+     * return a string. Sessions with matching keys are pooled together; never
+     * include secrets in the key.
+     *
+     * The default derives the key from `provider`, `host`, `port`, and
+     * `username`.
+     */
+    keyOf?: (profile: ConnectionProfile) => string;
+}
+/**
+ * Pool-aware {@link TransferClient} returned by
+ * {@link createPooledTransferClient}.
+ */
+interface PooledTransferClient {
+    /** Opens (or leases) a pooled provider session. */
+    connect(profile: ConnectionProfile): Promise<TransferSession>;
+    /** Inspects the registered providers (delegated to the underlying client). */
+    hasProvider(providerId: ProviderId): boolean;
+    /** Returns the registered capability snapshots (delegated). */
+    getCapabilities(): CapabilitySet[];
+    /** Returns a specific capability snapshot (delegated). */
+    getCapabilities(providerId: ProviderId): CapabilitySet;
+    /**
+     * Disconnects every idle session and prevents further pooling. After
+     * `drainPool()` resolves, subsequent `connect()` calls still work but
+     * always create fresh sessions (and never return them to the pool).
+     */
+    drainPool(): Promise<void>;
+    /** Returns the number of idle sessions currently held in the pool. */
+    poolSize(): number;
+}
+/**
+ * Wraps a {@link TransferClient} with connection pooling.
+ *
+ * @param inner - Underlying client used to create real provider sessions.
+ * @param options - Pool sizing, eviction, and key-derivation overrides.
+ * @returns A {@link PooledTransferClient} that reuses idle sessions.
+ */
+declare function createPooledTransferClient(inner: TransferClient, options?: ConnectionPoolOptions): PooledTransferClient;
+
 /** Options used to create a local file-system provider factory. */
 interface LocalProviderOptions {
     /** Root directory exposed as `/`. When omitted, `profile.host` is treated as the root path. */
@@ -3641,6 +3700,15 @@ interface NativeSftpProviderOptions {
      * traffic. Disabled when omitted or `0`.
      */
     keepaliveIntervalMs?: number;
+    /**
+     * Maximum concurrent file-transfer operations the engine should schedule
+     * against a single SFTP session. Each in-flight read/write occupies an
+     * outstanding SFTP request slot multiplexed over the same SSH channel; the
+     * default of `8` keeps memory bounded on commodity servers, but high-RTT
+     * links and modern OpenSSH builds can comfortably handle 16\u201364. Must be
+     * a positive integer.
+     */
+    maxConcurrency?: number;
 }
 /**
  * Low-level handles exposed by a native SFTP session for diagnostics and
@@ -3704,4 +3772,4 @@ interface NativeSftpRawSession {
  */
 declare function createNativeSftpProviderFactory(options?: NativeSftpProviderOptions): ProviderFactory;
 
-export { AbortError, type AtomicDeployActivateOperation, type AtomicDeployActivateStep, type AtomicDeployPlan, type AtomicDeployPruneStep, type AtomicDeployStrategy, type AuthenticationCapability, AuthenticationError, AuthorizationError, type BandwidthSleep, type BandwidthThrottle, type BandwidthThrottleOptions, type Base64EnvSecretSource, type BuiltInProviderId, CLASSIC_PROVIDER_IDS, type CapabilitySet, type ChecksumCapability, type ClassicProviderId, type ClientDiagnostics, type CompareRemoteManifestsOptions, ConfigurationError, type ConnectionDiagnosticTimings, type ConnectionDiagnosticsResult, ConnectionError, type ConnectionProfile, type CopyBetweenOptions, type CreateAtomicDeployPlanOptions, type CreateRemoteBrowserOptions, type CreateRemoteManifestOptions, type CreateSyncPlanOptions, type DiffRemoteTreesOptions, type DownloadFileOptions, type EnvSecretSource, type FileSecretSource, type FileZillaSite, type FriendlyTransferOptions, type FtpReplyErrorInput, type ImportFileZillaSitesResult, type ImportOpenSshConfigOptions, type ImportOpenSshConfigResult, type ImportWinScpSessionsResult, type KnownHostsEntry, type KnownHostsMarker, type ListOptions, type LocalProviderOptions, type LogLevel, type LogRecord, type LogRecordInput, type LoggerMethod, type MemoryProviderEntry, type MemoryProviderOptions, type MetadataCapability, type MkdirOptions, type NativeSftpProviderOptions, type NativeSftpRawSession, type OAuthAccessToken, type OAuthRefreshCallback, type OAuthTokenSecretSourceOptions, type OpenSshConfigEntry, ParseError, PathAlreadyExistsError, PathNotFoundError, PermissionDeniedError, type ProgressEventInput, ProtocolError, type AuthenticationCapability as ProviderAuthenticationCapability, type CapabilitySet as ProviderCapabilities, type ChecksumCapability as ProviderChecksumCapability, type ProviderFactory, type ProviderId, type MetadataCapability as ProviderMetadataCapability, ProviderRegistry, type ProviderSelection, type ProviderTransferEndpointRole, type ProviderTransferExecutorOptions, type ProviderTransferOperations, type ProviderTransferReadRequest, type ProviderTransferReadResult, type ProviderTransferRequest, type ProviderTransferSessionResolver, type ProviderTransferSessionResolverInput, type ProviderTransferWriteRequest, type ProviderTransferWriteResult, REDACTED, REMOTE_MANIFEST_FORMAT_VERSION, type RemoteBreadcrumb, type RemoteBrowser, type RemoteBrowserFilter, type RemoteBrowserSnapshot, type RemoteEntry, type RemoteEntrySortKey, type RemoteEntrySortOrder, type RemoteEntryType, type RemoteFileAdapter, type RemoteFileEndpoint, type RemoteFileSystem, type RemoteManifest, type RemoteManifestEntry, type RemotePermissions, type RemoteProtocol, type RemoteStat, type RemoteTreeDiff, type RemoteTreeDiffEntry, type RemoteTreeDiffReason, type RemoteTreeDiffStatus, type RemoteTreeDiffSummary, type RemoteTreeEntry, type RemoteTreeFilter, type RemoveOptions, type RenameOptions, type ResolveSecretOptions, type ResolvedConnectionProfile, type ResolvedOpenSshHost, type ResolvedSshProfile, type ResolvedTlsProfile, type RmdirOptions, type RunConnectionDiagnosticsOptions, type SecretProvider, type SecretSource, type SecretValue, type NativeSftpProviderOptions as SftpProviderOptions, type NativeSftpRawSession as SftpRawSession, type SpecializedErrorDetails, type SshAgentSource, type SshAlgorithms, type SshKeyboardInteractiveChallenge, type SshKeyboardInteractiveHandler, type SshKeyboardInteractivePrompt, type SshKnownHostsSource, type SshProfile, type SshSocketFactory, type SshSocketFactoryContext, type StatOptions, type SyncConflictPolicy, type SyncDeletePolicy, type SyncDirection, type SyncEndpointInput, TimeoutError, type TlsProfile, type TlsSecretSource, type TransferAttempt, type TransferAttemptError, type TransferBandwidthLimit, type TransferByteRange, TransferClient, type TransferClientOptions, type TransferDataChunk, type TransferDataSource, type TransferEndpoint, TransferEngine, type TransferEngineExecuteOptions, type TransferEngineOptions, TransferError, type TransferExecutionContext, type TransferExecutionResult, type TransferExecutor, type TransferJob, type TransferOperation, type TransferPlan, type TransferPlanAction, type TransferPlanInput, type TransferPlanStep, type TransferPlanSummary, type TransferProgressEvent, type TransferProvider, TransferQueue, type TransferQueueExecutorResolver, type TransferQueueItem, type TransferQueueItemStatus, type TransferQueueOptions, type TransferQueueRunOptions, type TransferQueueSummary, type TransferReceipt, type TransferResult, type TransferResultInput, type TransferRetryDecisionInput, type TransferRetryPolicy, type TransferSession, type TransferTimeoutPolicy, type TransferVerificationResult, UnsupportedFeatureError, type UploadFileOptions, type ValueSecretSource, VerificationError, type WalkRemoteTreeOptions, type WinScpSession, ZeroTransfer, type ZeroTransferCapabilities, ZeroTransferError, type ZeroTransferErrorDetails, type ZeroTransferLogger, type ZeroTransferOptions, assertSafeFtpArgument, basenameRemotePath, buildRemoteBreadcrumbs, compareRemoteManifests, copyBetween, createAtomicDeployPlan, createBandwidthThrottle, createLocalProviderFactory, createMemoryProviderFactory, createNativeSftpProviderFactory, createOAuthTokenSecretSource, createProgressEvent, createProviderTransferExecutor, createRemoteBrowser, createRemoteManifest, createNativeSftpProviderFactory as createSftpProviderFactory, createSyncPlan, createTransferClient, createTransferJobsFromPlan, createTransferPlan, createTransferResult, diffRemoteTrees, downloadFile, emitLog, errorFromFtpReply, filterRemoteEntries, importFileZillaSites, importOpenSshConfig, importWinScpSessions, isClassicProviderId, isSensitiveKey, joinRemotePath, matchKnownHosts, matchKnownHostsEntry, noopLogger, normalizeRemotePath, parentRemotePath, parseKnownHosts, parseOpenSshConfig, parseRemoteManifest, redactCommand, redactConnectionProfile, redactObject, redactSecretSource, redactValue, resolveConnectionProfileSecrets, resolveOpenSshHost, resolveProviderId, resolveSecret, runConnectionDiagnostics, serializeRemoteManifest, sortRemoteEntries, summarizeClientDiagnostics, summarizeTransferPlan, throttleByteIterable, uploadFile, validateConnectionProfile, walkRemoteTree };
+export { AbortError, type AtomicDeployActivateOperation, type AtomicDeployActivateStep, type AtomicDeployPlan, type AtomicDeployPruneStep, type AtomicDeployStrategy, type AuthenticationCapability, AuthenticationError, AuthorizationError, type BandwidthSleep, type BandwidthThrottle, type BandwidthThrottleOptions, type Base64EnvSecretSource, type BuiltInProviderId, CLASSIC_PROVIDER_IDS, type CapabilitySet, type ChecksumCapability, type ClassicProviderId, type ClientDiagnostics, type CompareRemoteManifestsOptions, ConfigurationError, type ConnectionDiagnosticTimings, type ConnectionDiagnosticsResult, ConnectionError, type ConnectionPoolOptions, type ConnectionProfile, type CopyBetweenOptions, type CreateAtomicDeployPlanOptions, type CreateRemoteBrowserOptions, type CreateRemoteManifestOptions, type CreateSyncPlanOptions, type DiffRemoteTreesOptions, type DownloadFileOptions, type EnvSecretSource, type FileSecretSource, type FileZillaSite, type FriendlyTransferOptions, type FtpReplyErrorInput, type ImportFileZillaSitesResult, type ImportOpenSshConfigOptions, type ImportOpenSshConfigResult, type ImportWinScpSessionsResult, type KnownHostsEntry, type KnownHostsMarker, type ListOptions, type LocalProviderOptions, type LogLevel, type LogRecord, type LogRecordInput, type LoggerMethod, type MemoryProviderEntry, type MemoryProviderOptions, type MetadataCapability, type MkdirOptions, type NativeSftpProviderOptions, type NativeSftpRawSession, type OAuthAccessToken, type OAuthRefreshCallback, type OAuthTokenSecretSourceOptions, type OpenSshConfigEntry, ParseError, PathAlreadyExistsError, PathNotFoundError, PermissionDeniedError, type PooledTransferClient, type ProgressEventInput, ProtocolError, type AuthenticationCapability as ProviderAuthenticationCapability, type CapabilitySet as ProviderCapabilities, type ChecksumCapability as ProviderChecksumCapability, type ProviderFactory, type ProviderId, type MetadataCapability as ProviderMetadataCapability, ProviderRegistry, type ProviderSelection, type ProviderTransferEndpointRole, type ProviderTransferExecutorOptions, type ProviderTransferOperations, type ProviderTransferReadRequest, type ProviderTransferReadResult, type ProviderTransferRequest, type ProviderTransferSessionResolver, type ProviderTransferSessionResolverInput, type ProviderTransferWriteRequest, type ProviderTransferWriteResult, REDACTED, REMOTE_MANIFEST_FORMAT_VERSION, type RemoteBreadcrumb, type RemoteBrowser, type RemoteBrowserFilter, type RemoteBrowserSnapshot, type RemoteEntry, type RemoteEntrySortKey, type RemoteEntrySortOrder, type RemoteEntryType, type RemoteFileAdapter, type RemoteFileEndpoint, type RemoteFileSystem, type RemoteManifest, type RemoteManifestEntry, type RemotePermissions, type RemoteProtocol, type RemoteStat, type RemoteTreeDiff, type RemoteTreeDiffEntry, type RemoteTreeDiffReason, type RemoteTreeDiffStatus, type RemoteTreeDiffSummary, type RemoteTreeEntry, type RemoteTreeFilter, type RemoveOptions, type RenameOptions, type ResolveSecretOptions, type ResolvedConnectionProfile, type ResolvedOpenSshHost, type ResolvedSshProfile, type ResolvedTlsProfile, type RmdirOptions, type RunConnectionDiagnosticsOptions, type SecretProvider, type SecretSource, type SecretValue, type NativeSftpProviderOptions as SftpProviderOptions, type NativeSftpRawSession as SftpRawSession, type SpecializedErrorDetails, type SshAgentSource, type SshAlgorithms, type SshKeyboardInteractiveChallenge, type SshKeyboardInteractiveHandler, type SshKeyboardInteractivePrompt, type SshKnownHostsSource, type SshProfile, type SshSocketFactory, type SshSocketFactoryContext, type StatOptions, type SyncConflictPolicy, type SyncDeletePolicy, type SyncDirection, type SyncEndpointInput, TimeoutError, type TlsProfile, type TlsSecretSource, type TransferAttempt, type TransferAttemptError, type TransferBandwidthLimit, type TransferByteRange, TransferClient, type TransferClientOptions, type TransferDataChunk, type TransferDataSource, type TransferEndpoint, TransferEngine, type TransferEngineExecuteOptions, type TransferEngineOptions, TransferError, type TransferExecutionContext, type TransferExecutionResult, type TransferExecutor, type TransferJob, type TransferOperation, type TransferPlan, type TransferPlanAction, type TransferPlanInput, type TransferPlanStep, type TransferPlanSummary, type TransferProgressEvent, type TransferProvider, TransferQueue, type TransferQueueExecutorResolver, type TransferQueueItem, type TransferQueueItemStatus, type TransferQueueOptions, type TransferQueueRunOptions, type TransferQueueSummary, type TransferReceipt, type TransferResult, type TransferResultInput, type TransferRetryDecisionInput, type TransferRetryPolicy, type TransferSession, type TransferTimeoutPolicy, type TransferVerificationResult, UnsupportedFeatureError, type UploadFileOptions, type ValueSecretSource, VerificationError, type WalkRemoteTreeOptions, type WinScpSession, ZeroTransfer, type ZeroTransferCapabilities, ZeroTransferError, type ZeroTransferErrorDetails, type ZeroTransferLogger, type ZeroTransferOptions, assertSafeFtpArgument, basenameRemotePath, buildRemoteBreadcrumbs, compareRemoteManifests, copyBetween, createAtomicDeployPlan, createBandwidthThrottle, createLocalProviderFactory, createMemoryProviderFactory, createNativeSftpProviderFactory, createOAuthTokenSecretSource, createPooledTransferClient, createProgressEvent, createProviderTransferExecutor, createRemoteBrowser, createRemoteManifest, createNativeSftpProviderFactory as createSftpProviderFactory, createSyncPlan, createTransferClient, createTransferJobsFromPlan, createTransferPlan, createTransferResult, diffRemoteTrees, downloadFile, emitLog, errorFromFtpReply, filterRemoteEntries, importFileZillaSites, importOpenSshConfig, importWinScpSessions, isClassicProviderId, isSensitiveKey, joinRemotePath, matchKnownHosts, matchKnownHostsEntry, noopLogger, normalizeRemotePath, parentRemotePath, parseKnownHosts, parseOpenSshConfig, parseRemoteManifest, redactCommand, redactConnectionProfile, redactObject, redactSecretSource, redactValue, resolveConnectionProfileSecrets, resolveOpenSshHost, resolveProviderId, resolveSecret, runConnectionDiagnostics, serializeRemoteManifest, sortRemoteEntries, summarizeClientDiagnostics, summarizeTransferPlan, throttleByteIterable, uploadFile, validateConnectionProfile, walkRemoteTree };

package/dist/index.mjs

@@ -1767,6 +1767,186 @@ function summarizeDiagnosticError(error) {
   return { message: String(error) };
 }
 
+// src/core/ConnectionPool.ts
+var DEFAULT_MAX_IDLE_PER_KEY = 4;
+var DEFAULT_IDLE_TIMEOUT_MS = 6e4;
+function createPooledTransferClient(inner, options = {}) {
+  const maxIdlePerKey = Math.max(1, options.maxIdlePerKey ?? DEFAULT_MAX_IDLE_PER_KEY);
+  const idleTimeoutMs = Math.max(0, options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS);
+  const keyOf = options.keyOf ?? defaultKeyOf;
+  const state = {
+    drained: false,
+    idle: /* @__PURE__ */ new Map()
+  };
+  const release = (key, session, tainted) => {
+    if (tainted || state.drained) {
+      return safelyDisconnect(session);
+    }
+    let bucket = state.idle.get(key);
+    if (bucket === void 0) {
+      bucket = [];
+      state.idle.set(key, bucket);
+    }
+    const entry = { session };
+    if (idleTimeoutMs > 0) {
+      entry.idleTimer = setTimeout(() => {
+        evictEntry(state, key, entry);
+      }, idleTimeoutMs);
+      const timer = entry.idleTimer;
+      if (timer !== void 0 && typeof timer.unref === "function") {
+        timer.unref();
+      }
+    }
+    bucket.push(entry);
+    while (bucket.length > maxIdlePerKey) {
+      const dropped = bucket.shift();
+      if (dropped !== void 0) {
+        clearEntryTimer(dropped);
+        void safelyDisconnect(dropped.session);
+      }
+    }
+    return Promise.resolve();
+  };
+  const acquire = async (profile) => {
+    const key = keyOf(profile);
+    const bucket = state.idle.get(key);
+    if (bucket !== void 0 && bucket.length > 0) {
+      const entry = bucket.pop();
+      if (entry !== void 0) {
+        clearEntryTimer(entry);
+        if (bucket.length === 0) state.idle.delete(key);
+        return { key, session: entry.session };
+      }
+    }
+    const session = await inner.connect(profile);
+    return { key, session };
+  };
+  return {
+    connect: async (profile) => {
+      const { key, session } = await acquire(profile);
+      return wrapPooledSession(session, key, release);
+    },
+    drainPool: async () => {
+      state.drained = true;
+      const entries = [];
+      for (const bucket of state.idle.values()) {
+        for (const entry of bucket) {
+          clearEntryTimer(entry);
+          entries.push(entry);
+        }
+      }
+      state.idle.clear();
+      await Promise.all(entries.map((entry) => safelyDisconnect(entry.session)));
+    },
+    getCapabilities: ((providerId) => {
+      if (providerId === void 0) return inner.getCapabilities();
+      return inner.getCapabilities(providerId);
+    }),
+    hasProvider: (providerId) => inner.hasProvider(providerId),
+    poolSize: () => {
+      let total = 0;
+      for (const bucket of state.idle.values()) total += bucket.length;
+      return total;
+    }
+  };
+}
+function defaultKeyOf(profile) {
+  const provider = profile.provider ?? profile.protocol ?? "unknown";
+  const host = profile.host ?? "";
+  const port = profile.port ?? "";
+  const username = typeof profile.username === "string" ? profile.username : "";
+  return `${provider}|${host}|${String(port)}|${username}`;
+}
+function evictEntry(state, key, entry) {
+  const bucket = state.idle.get(key);
+  if (bucket === void 0) return;
+  const index = bucket.indexOf(entry);
+  if (index < 0) return;
+  bucket.splice(index, 1);
+  if (bucket.length === 0) state.idle.delete(key);
+  clearEntryTimer(entry);
+  void safelyDisconnect(entry.session);
+}
+function clearEntryTimer(entry) {
+  if (entry.idleTimer !== void 0) {
+    clearTimeout(entry.idleTimer);
+    delete entry.idleTimer;
+  }
+}
+async function safelyDisconnect(session) {
+  try {
+    await session.disconnect();
+  } catch {
+  }
+}
+function isTaintingError(error) {
+  return error instanceof ConnectionError || error instanceof TimeoutError || error instanceof ProtocolError;
+}
+function wrapPooledSession(session, key, release) {
+  let tainted = false;
+  let released = false;
+  const guard = (fn) => {
+    let promise;
+    try {
+      promise = fn();
+    } catch (error) {
+      if (isTaintingError(error)) tainted = true;
+      return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+    return promise.catch((error) => {
+      if (isTaintingError(error)) tainted = true;
+      throw error;
+    });
+  };
+  const fs = wrapFs(session.fs, guard);
+  const transfers = session.transfers === void 0 ? void 0 : wrapTransfers(session.transfers, guard);
+  const wrapped = {
+    capabilities: session.capabilities,
+    disconnect: async () => {
+      if (released) return;
+      released = true;
+      await release(key, session, tainted);
+    },
+    fs,
+    provider: session.provider,
+    ...transfers !== void 0 ? { transfers } : {}
+  };
+  if (typeof session.raw === "function") {
+    const rawFn = session.raw.bind(session);
+    wrapped.raw = () => rawFn();
+  }
+  return wrapped;
+}
+function wrapFs(fs, guard) {
+  const wrapped = {
+    list: (path2, options) => guard(() => options !== void 0 ? fs.list(path2, options) : fs.list(path2)),
+    stat: (path2, options) => guard(() => options !== void 0 ? fs.stat(path2, options) : fs.stat(path2))
+  };
+  if (typeof fs.remove === "function") {
+    const remove = fs.remove.bind(fs);
+    wrapped.remove = (path2, options) => guard(() => options !== void 0 ? remove(path2, options) : remove(path2));
+  }
+  if (typeof fs.rename === "function") {
+    const rename2 = fs.rename.bind(fs);
+    wrapped.rename = (from, to, options) => guard(() => options !== void 0 ? rename2(from, to, options) : rename2(from, to));
+  }
+  if (typeof fs.mkdir === "function") {
+    const mkdir2 = fs.mkdir.bind(fs);
+    wrapped.mkdir = (path2, options) => guard(() => options !== void 0 ? mkdir2(path2, options) : mkdir2(path2));
+  }
+  if (typeof fs.rmdir === "function") {
+    const rmdir = fs.rmdir.bind(fs);
+    wrapped.rmdir = (path2, options) => guard(() => options !== void 0 ? rmdir(path2, options) : rmdir(path2));
+  }
+  return wrapped;
+}
+function wrapTransfers(transfers, guard) {
+  return {
+    read: (request) => guard(() => Promise.resolve(transfers.read(request))),
+    write: (request) => guard(() => Promise.resolve(transfers.write(request)))
+  };
+}
+
 // src/providers/local/LocalProvider.ts
 import { createReadStream } from "fs";
 import {
@@ -4619,7 +4799,7 @@ var SshDataWriter = class {
   length = 0;
   writeByte(value) {
     this.assertByte(value, "byte");
-    const chunk = Buffer7.allocUnsafe(1);
+    const chunk = Buffer7.alloc(1);
     chunk.writeUInt8(value, 0);
     return this.push(chunk);
   }
@@ -4637,7 +4817,7 @@ var SshDataWriter = class {
         retryable: false
       });
     }
-    const chunk = Buffer7.allocUnsafe(4);
+    const chunk = Buffer7.alloc(4);
     chunk.writeUInt32BE(value, 0);
     return this.push(chunk);
   }
@@ -4649,7 +4829,7 @@ var SshDataWriter = class {
         retryable: false
       });
     }
-    const chunk = Buffer7.allocUnsafe(8);
+    const chunk = Buffer7.alloc(8);
     chunk.writeBigUInt64BE(value, 0);
     return this.push(chunk);
   }
@@ -6205,7 +6385,7 @@ function encodeSshTransportPacket(payload, options = {}) {
   }
   const padding = options.randomPadding === false ? Buffer14.alloc(paddingLength) : randomBytes2(paddingLength);
   const packetLength = 1 + body.length + paddingLength;
-  const frame = Buffer14.allocUnsafe(4 + packetLength);
+  const frame = Buffer14.alloc(4 + packetLength);
   frame.writeUInt32BE(packetLength, 0);
   frame.writeUInt8(paddingLength, 4);
   body.copy(frame, 5);
@@ -7086,7 +7266,7 @@ function computeMac(macAlgorithm, macKey, sequence, packet, macLength) {
     return Buffer17.alloc(0);
   }
   const hashName = macAlgorithm === "hmac-sha2-512" ? "sha512" : "sha256";
-  const sequenceBuffer = Buffer17.allocUnsafe(4);
+  const sequenceBuffer = Buffer17.alloc(4);
   sequenceBuffer.writeUInt32BE(sequence >>> 0, 0);
   return createHmac2(hashName, macKey).update(sequenceBuffer).update(packet).digest().subarray(0, macLength);
 }
@@ -8038,7 +8218,7 @@ var SftpSession = class {
    * serializes concurrent calls so byte ordering is preserved.
    */
   sendRaw(encodedMessage, requestId) {
-    const frame = Buffer20.allocUnsafe(4 + encodedMessage.length);
+    const frame = Buffer20.alloc(4 + encodedMessage.length);
     frame.writeUInt32BE(encodedMessage.length, 0);
     encodedMessage.copy(frame, 4);
     this.channel.sendData(frame).catch((err) => {
@@ -8156,44 +8336,54 @@ var NATIVE_SFTP_ALGORITHM_PREFERENCES = {
     "rsa-sha2-256"
   ]
 };
-var NATIVE_SFTP_PROVIDER_CAPABILITIES = {
-  provider: NATIVE_SFTP_PROVIDER_ID,
-  authentication: ["password", "keyboard-interactive", "publickey"],
-  list: true,
-  stat: true,
-  readStream: true,
-  writeStream: true,
-  serverSideCopy: false,
-  serverSideMove: false,
-  resumeDownload: true,
-  resumeUpload: true,
-  checksum: [],
-  atomicRename: false,
-  chmod: false,
-  chown: false,
-  symlink: true,
-  metadata: ["accessedAt", "group", "modifiedAt", "owner", "permissions"],
-  maxConcurrency: 8,
-  notes: [
-    "Native SSH/SFTP provider using the project's own protocol stack (Waves 1\u20133).",
-    "Supports password and keyboard-interactive authentication."
-  ]
-};
+var NATIVE_SFTP_DEFAULT_MAX_CONCURRENCY = 8;
+function buildNativeSftpCapabilities(maxConcurrency) {
+  return {
+    provider: NATIVE_SFTP_PROVIDER_ID,
+    authentication: ["password", "keyboard-interactive", "publickey"],
+    list: true,
+    stat: true,
+    readStream: true,
+    writeStream: true,
+    serverSideCopy: false,
+    serverSideMove: false,
+    resumeDownload: true,
+    resumeUpload: true,
+    checksum: [],
+    atomicRename: false,
+    chmod: false,
+    chown: false,
+    symlink: true,
+    metadata: ["accessedAt", "group", "modifiedAt", "owner", "permissions"],
+    maxConcurrency,
+    notes: [
+      "Native SSH/SFTP provider using the project's own protocol stack (Waves 1\u20133).",
+      "Supports password, keyboard-interactive, and public-key (Ed25519/RSA) authentication."
+    ]
+  };
+}
+var NATIVE_SFTP_PROVIDER_CAPABILITIES = buildNativeSftpCapabilities(
+  NATIVE_SFTP_DEFAULT_MAX_CONCURRENCY
+);
 function createNativeSftpProviderFactory(options = {}) {
   validateNativeSftpOptions(options);
+  const capabilities = buildNativeSftpCapabilities(
+    options.maxConcurrency ?? NATIVE_SFTP_DEFAULT_MAX_CONCURRENCY
+  );
   return {
-    capabilities: NATIVE_SFTP_PROVIDER_CAPABILITIES,
-    create: () => new NativeSftpProvider(options),
+    capabilities,
+    create: () => new NativeSftpProvider(options, capabilities),
     id: NATIVE_SFTP_PROVIDER_ID
   };
 }
 var NativeSftpProvider = class {
-  constructor(options) {
+  constructor(options, capabilities = NATIVE_SFTP_PROVIDER_CAPABILITIES) {
     this.options = options;
+    this.capabilities = capabilities;
   }
   options;
   id = NATIVE_SFTP_PROVIDER_ID;
-  capabilities = NATIVE_SFTP_PROVIDER_CAPABILITIES;
+  capabilities;
   async connect(profile) {
     const resolved = await resolveConnectionProfileSecrets(profile);
     const username = requireNativeSftpUsername(resolved);
@@ -8822,6 +9012,14 @@ function validateNativeSftpOptions(options) {
       retryable: false
     });
   }
+  if (options.maxConcurrency !== void 0 && (!Number.isInteger(options.maxConcurrency) || options.maxConcurrency <= 0)) {
+    throw new ConfigurationError({
+      details: { maxConcurrency: options.maxConcurrency },
+      message: "Native SFTP provider maxConcurrency must be a positive integer",
+      protocol: "sftp",
+      retryable: false
+    });
+  }
 }
 export {
   AbortError,
@@ -8858,6 +9056,7 @@ export {
   createMemoryProviderFactory,
   createNativeSftpProviderFactory,
   createOAuthTokenSecretSource,
+  createPooledTransferClient,
   createProgressEvent,
   createProviderTransferExecutor,
   createRemoteBrowser,