dsh-winrm 0.2.0 → 0.3.1

package/src/powershell.ts

@@ -152,6 +152,57 @@ export function powershellCommandLine(): string {
   return 'powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -EncodedCommand ' + encodeCommand(OUTER_SCRIPT)
 }
 
+/**
+ * Bootstrap for the streaming upload path: read `<byteCount>\n<script>` from
+ * stdin, then run that script **in this process** so it can keep draining the
+ * same stdin stream.
+ *
+ * This exists because {@link psReceiveStream} outgrew the command line. WinRS
+ * hands the command line to cmd.exe, whose limit is about 8191 characters, and
+ * the receiver is 3424 characters of PowerShell — 9206 once base64-of-UTF-16
+ * expands it, over the cap. Shipping the receiver on stdin instead costs one
+ * extra `Send` and keeps the command line a constant 1154 characters no matter
+ * how the receiver grows.
+ *
+ * Running the receiver in-process (rather than in a child, as
+ * {@link OUTER_SCRIPT} does) is what makes the handoff work: the child would
+ * need its own stdin, and the payload has to keep flowing into whatever reads
+ * the file. A fresh `[Console]::OpenStandardInput()` inside the receiver picks
+ * up exactly where this bootstrap stopped reading, because `Read` on the raw
+ * stream never buffers ahead of the count it was asked for.
+ */
+const STREAM_BOOTSTRAP = [
+  "$ErrorActionPreference='Continue'",
+  '[Console]::OutputEncoding=[Text.Encoding]::UTF8',
+  '$i=[Console]::OpenStandardInput()',
+  "$d=''",
+  'while($true){$b=$i.ReadByte();if($b -lt 0 -or $b -eq 10){break};if($b -ne 13){$d+=[char]$b}}',
+  '$n=[int]$d',
+  '$u=New-Object byte[] $n',
+  '$r=0',
+  'while($r -lt $n){$k=$i.Read($u,$r,$n-$r);if($k -le 0){break};$r+=$k}',
+  '$s=[Text.Encoding]::UTF8.GetString($u,0,$r)',
+  '$c=0',
+  'try{',
+  '  &([scriptblock]::Create($s))',
+  '}catch{',
+  '  [Console]::Error.WriteLine([string]($_|Out-String))',
+  '  $c=1',
+  '}',
+  'exit $c',
+  '',
+].join('\r\n')
+
+/**
+ * The constant powershell.exe command line for a streaming upload.
+ *
+ * The receiver travels on stdin right behind it, so this stays well clear of
+ * cmd.exe's cap and does not change when the receiver does.
+ */
+export function streamCommandLine(): string {
+  return 'powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -EncodedCommand ' + encodeCommand(STREAM_BOOTSTRAP)
+}
+
 /**
  * The stdin payload for one command: the UTF-8 **byte** count, a newline, then
  * the raw script.
@@ -245,11 +296,16 @@ export function psListDir(dir: string): string {
   ].join('\r\n')
 }
 
-/** Plain: remote file size in bytes (0 when missing). */
+/**
+ * Plain: remote file size in bytes. Emits nothing at all when the path is
+ * missing or is a directory, so the caller can tell "absent" from "empty" —
+ * both used to collapse to the string "0", which made a download of a
+ * nonexistent file look like a successful transfer of a zero-byte one.
+ */
 export function psFileSize(p: string): string {
   return [
     '$__f = Get-Item -LiteralPath ' + sq(p) + ' -ErrorAction SilentlyContinue',
-    'if ($null -eq $__f) { "0" } elseif ($__f.PSIsContainer) { "0" } else { [string]$__f.Length }',
+    'if ($null -ne $__f -and -not $__f.PSIsContainer) { [string]$__f.Length }',
     '',
   ].join('\r\n')
 }
@@ -287,6 +343,246 @@ export function psWriteChunk(p: string, b64: string, append: boolean): string {
   ].join('\r\n')
 }
 
+/** Magic stamped into the frame header that precedes every stream chunk. */
+export const STREAM_FRAME_MAGIC = 'DSHZ'
+
+/** Frame header size: 4 magic bytes + 4 little-endian length bytes + 1 mode byte + 1 reserved. */
+export const STREAM_FRAME_HEADER_BYTES = 10
+
+/** Frame mode: the payload after the header is a gzip member. */
+export const STREAM_FRAME_GZIP = 1
+
+/** Frame mode: the payload after the header is raw file bytes. */
+export const STREAM_FRAME_RAW = 0
+
+/** Frame mode: the payload after the header is the transfer's metadata. */
+export const STREAM_FRAME_HEADER = 2
+
+/** Remote-side buffer used while draining stdin (or inflating a frame) into the file. */
+const STREAM_BUFFER_BYTES = 262_144
+
+/**
+ * Wrap one payload in a stream frame: `DSHZ` + uint32LE length + mode + pad.
+ *
+ * The frame is what makes a compressed stream legal on a pipe. stdin cannot
+ * seek, so the receiver has to be handed the exact byte count of the next gzip
+ * member before it lets `GZipStream` touch it; otherwise the inflater would
+ * read into the member that follows and the stream would desynchronize. The
+ * mode byte travels with the payload so the client can switch between gzip and
+ * raw per chunk.
+ * @param payload - gzip member bytes or raw file bytes.
+ * @param mode - `STREAM_FRAME_GZIP` or `STREAM_FRAME_RAW`.
+ * @returns the framed chunk to place on the stdin stream.
+ */
+export function buildStreamFrame(payload: Buffer, mode: number): Buffer {
+  const frame = Buffer.alloc(STREAM_FRAME_HEADER_BYTES + payload.length)
+  frame.write(STREAM_FRAME_MAGIC, 0, 'ascii')
+  frame.writeUInt32LE(payload.length, 4)
+  frame[8] = mode
+  frame[9] = 0
+  payload.copy(frame, STREAM_FRAME_HEADER_BYTES)
+  return frame
+}
+
+/**
+ * Streaming receiver: drain framed stdin chunks into the file named by the
+ * header frame, until the declared byte count lands.
+ *
+ * This is the fast upload path. Instead of shipping base64 text inside a
+ * PowerShell script — which costs one full shell create/command/delete cycle
+ * per 48 KiB — the remote shell starts this script once and the client then
+ * pushes bytes straight down the WinRS stdin stream. The only per-chunk cost
+ * left is a single `Send`, so a whole file costs one shell and one command no
+ * matter how large it is.
+ *
+ * The script deliberately takes **no arguments**. The destination path and
+ * total byte count arrive as the first frame on stdin, which keeps the command
+ * line a constant size: WinRS hands the command line to cmd.exe, whose limit
+ * is about 8191 characters, and a long remote path interpolated into the
+ * script would eat into that budget (the script is base64-of-UTF-16 on the
+ * wire, so every character costs 2.67). Reading them from the stream removes
+ * the limit entirely and mirrors how `powershellCommandLine` stays constant.
+ *
+ * Every wire chunk is a frame: `DSHZ` + 4-byte little-endian payload length +
+ * 1 mode byte + 1 reserved, followed by exactly that many payload bytes. The
+ * explicit frame is what makes a *pipe* usable for a compressed stream: stdin
+ * cannot seek, so the receiver must be told how long the next gzip member is
+ * before it hands the bytes to `GZipStream`, or the inflater would read into
+ * the member that follows. The mode byte lets the client pick per chunk — gzip
+ * when it actually shrinks the data, raw bytes when it would not — so
+ * incompressible files never pay compression overhead.
+ *
+ * The script prints the three-line envelope on stdout with the byte count as
+ * its payload, so the caller can prove the transfer landed complete.
+ * @returns a PowerShell script suitable for `-EncodedCommand`.
+ */
+export function psReceiveStream(): string {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    "$__a = ''",
+    "$__e = ''",
+    '$__c = 0',
+    'try {',
+    '  $__i = [Console]::OpenStandardInput()',
+    '  $__hdr = New-Object byte[] ' + String(STREAM_FRAME_HEADER_BYTES),
+    '  $__got = 0',
+    '  while ($__got -lt $__hdr.Length) {',
+    '    $__k = $__i.Read($__hdr, $__got, $__hdr.Length - $__got)',
+    '    if ($__k -le 0) { break }',
+    '    $__got += $__k',
+    '  }',
+    '  if ($__got -lt $__hdr.Length) { throw ' + sq('upload stream ended before its header') + ' }',
+    '  if (-not ($__hdr[0] -eq 68 -and $__hdr[1] -eq 83 -and $__hdr[2] -eq 72 -and $__hdr[3] -eq 90)) { throw ' + sq('upload stream lost frame alignment') + ' }',
+    '  if ($__hdr[8] -ne ' + String(STREAM_FRAME_HEADER) + ') { throw ' + sq('upload stream started without a header frame') + ' }',
+    '  $__size = 0',
+    '  for ($__j = 0; $__j -lt 4; $__j++) { $__size = $__size -bor ([int]$__hdr[4 + $__j] -shl (8 * $__j)) }',
+    '  $__meta = New-Object byte[] $__size',
+    '  $__got = 0',
+    '  while ($__got -lt $__size) {',
+    '    $__k = $__i.Read($__meta, $__got, $__size - $__got)',
+    '    if ($__k -le 0) { break }',
+    '    $__got += $__k',
+    '  }',
+    '  if ($__got -lt $__size) { throw ' + sq('upload stream truncated its header frame') + ' }',
+    '  $__text = [System.Text.Encoding]::UTF8.GetString($__meta)',
+    '  $__cut = $__text.IndexOf([char]10)',
+    '  if ($__cut -lt 0) { throw ' + sq('upload header frame is malformed') + ' }',
+    '  $__n = [long]$__text.Substring(0, $__cut)',
+    '  $__p = $__text.Substring($__cut + 1)',
+    '  $__d = [System.IO.Path]::GetDirectoryName($__p)',
+    '  if (-not [string]::IsNullOrEmpty($__d)) { [System.IO.Directory]::CreateDirectory($__d) | Out-Null }',
+    '  $__fs = New-Object System.IO.FileStream($__p, [System.IO.FileMode]::Create, [System.IO.FileAccess]::Write, [System.IO.FileShare]::Read)',
+    '  $__w = 0',
+    '  try {',
+    '    $__buf = New-Object byte[] ' + String(STREAM_BUFFER_BYTES),
+    '    while ($__w -lt $__n) {',
+    '      $__got = 0',
+    '      while ($__got -lt $__hdr.Length) {',
+    '        $__k = $__i.Read($__hdr, $__got, $__hdr.Length - $__got)',
+    '        if ($__k -le 0) { break }',
+    '        $__got += $__k',
+    '      }',
+    '      if ($__got -lt $__hdr.Length) { break }',
+    '      if (-not ($__hdr[0] -eq 68 -and $__hdr[1] -eq 83 -and $__hdr[2] -eq 72 -and $__hdr[3] -eq 90)) { throw ' + sq('upload stream lost frame alignment') + ' }',
+    '      $__size = 0',
+    '      for ($__j = 0; $__j -lt 4; $__j++) { $__size = $__size -bor ([int]$__hdr[4 + $__j] -shl (8 * $__j)) }',
+    '      $__mode = $__hdr[8]',
+    '      $__blob = New-Object byte[] $__size',
+    '      $__got = 0',
+    '      while ($__got -lt $__size) {',
+    '        $__k = $__i.Read($__blob, $__got, $__size - $__got)',
+    '        if ($__k -le 0) { break }',
+    '        $__got += $__k',
+    '      }',
+    '      if ($__got -lt $__size) { break }',
+    '      if ($__mode -eq ' + String(STREAM_FRAME_GZIP) + ') {',
+    '        $__ms = New-Object System.IO.MemoryStream(, $__blob)',
+    '        $__gz = New-Object System.IO.Compression.GZipStream($__ms, [System.IO.Compression.CompressionMode]::Decompress)',
+    '        try {',
+    '          while ($true) {',
+    '            $__k = $__gz.Read($__buf, 0, $__buf.Length)',
+    '            if ($__k -le 0) { break }',
+    '            $__fs.Write($__buf, 0, $__k)',
+    '            $__w += $__k',
+    '          }',
+    '        } finally { $__gz.Dispose(); $__ms.Dispose() }',
+    '      } else {',
+    '        $__fs.Write($__blob, 0, $__blob.Length)',
+    '        $__w += $__blob.Length',
+    '      }',
+    '    }',
+    '  } finally { $__fs.Dispose() }',
+    '  $__a = [string]$__w',
+    '} catch {',
+    '  $__a = [string]$__a + [string]($_.Exception.Message)',
+    '  $__c = 1',
+    '}',
+    sq(ENVELOPE_MARKER) + ' + [string]$__c',
+    "'O:' + [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes([string]$__a))",
+    "'E:' + [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes([string]$__e))",
+    '',
+  ].join('\r\n')
+}
+
+/** Remote-side read buffer used by {@link psSendStream} while draining the file to stdout. */
+const SEND_BUFFER_BYTES = 262_144
+
+/**
+ * Streaming sender: write one byte range of the file to standard output,
+ * gzip-compressed, for the download path.
+ *
+ * This is the mirror of {@link psReceiveStream}. The old download path asked
+ * for 48 KiB at a time, and every chunk cost a full shell create / command /
+ * delete cycle — five HTTP round trips each — so a 2 MiB file took 129 s. Here
+ * the shell is created once and the client then simply receives; the only
+ * per-chunk cost left is one `Receive`, and the target streams the file as fast
+ * as the transport will drain it.
+ *
+ * Two details make this work:
+ *
+ * - **Only stderr may carry text.** Anything written to the PowerShell success
+ *   stream would be merged into the payload and corrupt the file, so the byte
+ *   count and any error go to `[Console]::Error` and the exit code, not stdout.
+ * - **The range is positional.** `Position` plus a byte count lets several
+ *   shells serve different parts of one file concurrently; each writes to its
+ *   own offset on the client, so completion order does not matter.
+ *
+ * Output is gzip-compressed unconditionally. Measured against this target, a
+ * compressible 16 MiB file collapsed from 121 round trips to 1 (2.0 s), and an
+ * incompressible 2 MiB file was no slower than raw (9457 ms vs 9582 ms), so the
+ * compression pays for itself or costs nothing.
+ * @param remotePath - file to read on the target.
+ * @param start - first byte offset of this worker's range.
+ * @param length - number of bytes this worker must send.
+ * @returns a PowerShell script suitable for `-EncodedCommand`.
+ */
+export function psSendStream(remotePath: string, start: number, length: number): string {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$__o = [Console]::OpenStandardOutput()',
+    '$__n = 0',
+    'try {',
+    '  $__fs = [System.IO.File]::OpenRead(' + sq(remotePath) + ')',
+    '  try {',
+    '    $__fs.Position = [long]' + String(start),
+    '    $__left = [long]' + String(length),
+    '    $__gz = New-Object System.IO.Compression.GZipStream($__o, [System.IO.Compression.CompressionMode]::Compress, $true)',
+    '    try {',
+    '      $__buf = New-Object byte[] ' + String(SEND_BUFFER_BYTES),
+    '      while ($__left -gt 0) {',
+    '        $__want = [int][Math]::Min([long]$__buf.Length, $__left)',
+    '        $__k = $__fs.Read($__buf, 0, $__want)',
+    '        if ($__k -le 0) { break }',
+    '        $__gz.Write($__buf, 0, $__k)',
+    '        $__n += $__k',
+    '        $__left -= $__k',
+    '      }',
+    '      $__gz.Flush()',
+    '    } finally { $__gz.Dispose() }',
+    '    $__o.Flush()',
+    '  } finally { $__fs.Dispose() }',
+    "  [Console]::Error.WriteLine('__DSH_DL__ OK ' + [string]$__n)",
+    '} catch {',
+    "  [Console]::Error.WriteLine('__DSH_DL__ ERR ' + [string]($_.Exception.Message))",
+    '  throw',
+    '}',
+    '',
+  ].join('\r\n')
+}
+
+/**
+ * Wrap an arbitrary script in the constant powershell.exe invocation.
+ *
+ * Only safe for scripts that fit cmd.exe's ~8191 character command line (the
+ * script is base64-of-UTF-16 on the wire, so it costs 2.67 characters each);
+ * {@link psReceiveStream} outgrew that and travels on stdin instead.
+ * @param script - the PowerShell script to run.
+ * @returns the command line to hand to WinRS.
+ */
+export function scriptCommandLine(script: string): string {
+  return 'powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -EncodedCommand ' + encodeCommand(script)
+}
+
 /** Decode one base64 envelope field, tolerating whitespace the transport added. */
 function decodeField(base64: string): string {
   return Buffer.from(base64.replace(/\s+/g, ''), 'base64').toString('utf8')

package/src/smb.ts

@@ -1,17 +1,18 @@
 /**
  * SMB transfer bridge.
  *
- * The WinRM base64 chunk bridge is reliable for small files but breaks for
- * large artifacts (the WinRM/HTTP envelope rejects large payloads), so whole
- * files ride the remote admin share. This module mounts the remote host's
- * admin share with `net use` (password passed via stdin, never argv), copies
- * whole files with node:fs, then verifies the SHA-256 on both ends.
+ * SMB is the fast channel when the admin share is reachable, so `auto` tries it
+ * first and falls back to the WinRM streaming path. This module mounts the
+ * remote host's admin share with `net use` (password passed via stdin, never
+ * argv), copies whole files with node:fs, then verifies the SHA-256 on both
+ * ends.
  */
 
 import { spawn } from 'node:child_process'
 import { copyFile, stat } from 'node:fs/promises'
 import { createHash } from 'node:crypto'
 import { readFile } from 'node:fs/promises'
+import { createConnection } from 'node:net'
 import type { WinHostEntry } from './protocol.ts'
 
 /** Per-transfer channel selector. */
@@ -85,6 +86,57 @@ async function remoteSha256(host: string, remotePath: string): Promise<string> {
   return match[1].toUpperCase()
 }
 
+/** How long a reachability verdict is trusted before probing again. */
+const SMB_PROBE_TTL_MS = 60_000
+
+/** Budget for the TCP reachability probe; far below `net use`'s own timeout. */
+const SMB_PROBE_TIMEOUT_MS = 3_000
+
+const smbProbeCache = new Map<string, { reachable: boolean; at: number }>()
+
+/**
+ * Whether the target's SMB port (445) accepts a connection.
+ *
+ * `net use` is the only way to mount the admin share, but it has no useful
+ * timeout: against a host whose 445 is filtered or whose SMB service is down it
+ * spends a full minute before failing. That minute was being paid on *every*
+ * `auto` upload before the WinRM fallback could even start — measured at 61 s
+ * and 58 s on the test host, against a 12 s streaming transfer. A bare TCP
+ * connect answers the same question in milliseconds.
+ *
+ * A negative verdict is cached briefly so a burst of transfers does not re-probe
+ * for each one; a positive verdict is cached too, but the `net use` that follows
+ * still reports its own failure if the share turns out to be unmountable.
+ * @param host - target hostname or address.
+ * @returns true when port 445 accepted a connection.
+ */
+export async function smbReachable(host: string): Promise<boolean> {
+  const cached = smbProbeCache.get(host)
+  if (cached !== undefined && Date.now() - cached.at < SMB_PROBE_TTL_MS) return cached.reachable
+  const reachable = await new Promise<boolean>((resolve) => {
+    const socket = createConnection({ host, port: 445 })
+    let settled = false
+    const finish = (value: boolean): void => {
+      if (settled) return
+      settled = true
+      socket.destroy()
+      resolve(value)
+    }
+    const timer = setTimeout(() => finish(false), SMB_PROBE_TIMEOUT_MS)
+    socket.once('connect', () => { clearTimeout(timer); finish(true) })
+    socket.once('error', () => { clearTimeout(timer); finish(false) })
+    socket.once('timeout', () => { clearTimeout(timer); finish(false) })
+    socket.setTimeout(SMB_PROBE_TIMEOUT_MS)
+  })
+  smbProbeCache.set(host, { reachable, at: Date.now() })
+  return reachable
+}
+
+/** Error thrown when SMB was requested or probed and the target is not listening. */
+export function smbUnavailable(host: string): Error {
+  return new Error('SMB is not reachable on ' + host + ':445 (the admin share needs TCP 445 open and the Server service running)')
+}
+
 /**
  * Copy one local file to a remote Windows host over SMB, verifying the
  * remote SHA-256 matches the local source.

package/src/tools.ts

@@ -266,13 +266,13 @@ export function winrmProcessTool(engine: WinRmEngine) {
 export function winrmUploadTool(engine: WinRmEngine) {
   return defineTool({
     name: 'winrm_upload',
-    description: 'Upload a local file to a configured Windows host (SMB admin share preferred, base64 WinRM chunk fallback). The local path is on THIS machine (the dsh host). ' +
+    description: 'Upload a local file to a configured Windows host. The bytes go over the SMB admin share when it is reachable, otherwise they are streamed over WinRM in one shell with per-chunk gzip (the 48 KiB base64 chunk path is kept only as a fallback). The local path is on THIS machine (the dsh host). ' +
       'Triggers: upload file to Windows server, deploy artifact, copy config to Windows server.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from winrm_list.' },
       localPath: { type: 'string', required: true, description: 'Absolute local file path on this machine.' },
       remotePath: { type: 'string', required: true, description: 'Destination path on the remote host, e.g. C:\\temp\\file.txt (parent dirs are created).' },
-      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: smb (admin share), winrm (base64 chunks), or auto (default, SMB first with WinRM fallback).' },
+      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: smb (admin share), winrm (streamed over the WinRS stdin channel), or auto (default, SMB first with WinRM fallback).' },
     },
     output: {
       schema: {
@@ -305,13 +305,13 @@ export function winrmUploadTool(engine: WinRmEngine) {
 export function winrmDownloadTool(engine: WinRmEngine) {
   return defineTool({
     name: 'winrm_download',
-    description: 'Download a remote FILE from a configured Windows host to a local path on this machine (SMB admin share preferred, base64 WinRM chunk fallback). Directory download is not supported — download files individually. ' +
+    description: 'Download a remote FILE from a configured Windows host to a local path on this machine. The bytes come over the SMB admin share when it is reachable, otherwise they are streamed over WinRM as parallel byte ranges (the 48 KiB base64 chunk path is kept only as a fallback). Directory download is not supported — download files individually. ' +
       'Triggers: download file from Windows server, fetch remote log/artifact.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from winrm_list.' },
       remotePath: { type: 'string', required: true, description: 'Remote file path, e.g. C:\\temp\\file.txt.' },
       localPath: { type: 'string', required: true, description: 'Absolute destination path on this machine.' },
-      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: smb (admin share), winrm (base64 chunks), or auto (default, SMB first with WinRM fallback).' },
+      channel: { type: 'string', enum: ['auto', 'smb', 'winrm'], description: 'Transfer channel: smb (admin share), winrm (streamed over parallel WinRS ranges), or auto (default, SMB first with WinRM fallback).' },
     },
     output: {
       schema: {