net-sftp 4.0.1 → 4.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d42976ec0ca9fa6131be80a2d84e8e4b375a95dc410aa20f987ebf56b5717c3
-  data.tar.gz: 8b3b507190fed78c32dedd040e4d5d814ca36a7ecc0b72a6de402459f9f8b999
+  metadata.gz: 6e7dc5adb1f352eecedf9c4d5f6150b32e0e26ccdd76cb6cb242c66fbe636fd4
+  data.tar.gz: e9b3ade5165aa0c1dbb61e64acd303794b16a31aa385472c3c513d983322fb3a
 SHA512:
-  metadata.gz: 1ac5c4215ede73ce6f16b1db405647cc545d420c2e4ab87ba64e7db5efd4535a32549217a34b8a3989978dd47af1dd274f28a953c5f28c8d16f3f6948047e458
-  data.tar.gz: b61e54caed650be40e5b8a3d89f9d6cb52ffcb0c4fbe37ebfd2c2f20e5fca15405e7c06bd579b71d3458c6182fdc2e247caae4c1d5e0a5c6ed0adab73c205e6c
+  metadata.gz: 8534ab3b4109bd1e5333c1e4814e5e01a855c2f84c40f60d58bfb2d6303bdc1fab20bf8102b31ef2a1b8c408e6565a7a0a26ff1dbf1b1c48445dd2f9aa49bee8
+  data.tar.gz: b36ad98cdca42bdf48a29957105f4a104c2965280f983f937bfd64e8958b86a2354dc612e52404bba88374944bdda86016f4e06449e8fb541e26f74a0e0eeacc

data/.github/pull_request_template.md

@@ -0,0 +1 @@
+<!-- After opening the PR, add a changelog.d/<PR number>.<type>.txt fragment (none, change, security, breaking or breaking-security) instead of editing CHANGES.txt; see CONTRIBUTING.md#changelog. -->

data/.github/workflows/changelog.yml

@@ -0,0 +1,18 @@
+name: Changelog
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+jobs:
+  changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # HEAD is the PR merged into the base branch; HEAD^1 is the base it was merged into.
+          fetch-depth: 2
+      - uses: net-ssh/changelogd@v1

data/.github/workflows/ci.yml

@@ -21,3 +21,16 @@ jobs:
           bundler-cache: true
       - name: Run Tests
         run: bundle exec rake test
+  frozen-string-literal:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+      - name: Run Tests with frozen string literals
+        run: bundle exec rake test
+        env:
+          RUBYOPT: --enable-frozen-string-literal

data/CHANGES.txt

@@ -1,3 +1,28 @@
+=== 4.0.2
+
+* Security: Recursive downloads refuse to follow an existing local symlink at a server-named path instead of writing through it. The local path passed by the caller may still be a symlink. Suggested in #162 by srosenhamer [#186]
+* Security: Recursive downloads reject file names from the server that are not a single path component (such as `../x` or `a/b`) instead of writing outside the target directory. Reported in #162 by srosenhamer [#185, #162]
+* Net::SFTP now works with frozen string literals enabled: `File` reads and `Dir#glob` no longer mutate frozen strings, and `glob` no longer modifies entry names in place (adds `Name#name=`). Based on #157 by @frederikspang [#198, #157]
+* `File#read` and `File#gets` no longer loop forever when the server returns an empty data packet, and `read` with a negative length raises `ArgumentError` like `IO#read`. Based on #174 by @OskarEichler [#189, #174]
+* Show fields an SFTP v4+ server omitted as `?` in directory listings (`longname`), like `ls -l` does, instead of blank, `-` or `---------` [#188]
+* Fixed `File#write` hanging on data of 256 KiB or more by sending it in 32 KiB write requests [#99, #187]
+* SFTP request ids now wrap around at the uint32 limit, skipping ids still awaiting a response, instead of growing past it so that responses on very long-lived sessions could no longer be matched to their requests. Thanks @OskarEichler [#179]
+* Uploads keep exactly `:requests` writes in flight (one more was sent before, so the default is now 2 rather than 3), and a zero, negative or non-numeric `:requests` or `:read_size` on `upload` or `download` now raises `ArgumentError` when the transfer is set up instead of stalling. Thanks @OskarEichler [#178]
+* Reconnecting a closed `Net::SFTP::Session` now discards partially received packet data from the old channel, so stale bytes are no longer parsed as the start of the new channel's first packet. Thanks @OskarEichler [#177]
+* Don't crash formatting a directory listing (`longname`) when an SFTP v4+ server omits the modification time, size or permissions, and don't show omitted permissions as `rwxrwxrwx`. Thanks @OskarEichler [#175, #146]
+* `Dir#glob` no longer lists every subdirectory for a pattern without `/` (which can only match top-level names), saving a round trip per directory and no longer failing on unreadable subdirectories. Thanks @OskarEichler [#173, #180]
+* `File#gets` no longer rescans the whole line after each chunk, so reading very long lines is no longer quadratic (a 16 MiB line ending in `"\r\n"` went from about 5 s to 0.01 s). Thanks @OskarEichler [#172]
+* `File#gets` treats a nil or negative limit as no limit, like `IO#gets`, instead of returning nil and corrupting the position (or raising for nil). Thanks @OskarEichler [#171]
+* Fixed SFTP v5/v6 `open` ignoring `IO::TRUNC` and `IO::CREAT` in numeric flags: `IO::WRONLY | IO::TRUNC` now requests `TRUNCATE_EXISTING` instead of opening without truncation, and read-only opens with `IO::CREAT` now request `OPEN_OR_CREATE`. Thanks @OskarEichler [#170]
+* Include the server's error message in `StatusException` and `Response#to_s` for SFTP protocol v3 and later, instead of only the status code. Thanks @OskarEichler [#169, #156]
+* Fixed SFTP v4+ attribute serialization raising `TypeError` when nanoseconds were given for only some timestamps (e.g. `atime_nseconds` with `mtime` but no `mtime_nseconds`); the missing subsecond fields are now sent as 0. Thanks @OskarEichler [#168]
+* `Net::SFTP.start` with a block now closes the SSH session when the block exits with `break`, `return` or `throw`, instead of leaking it. Thanks @OskarEichler [#167]
+* Attributes objects now copy the hash they are given, so a frozen hash no longer raises `FrozenError` and the caller's hash is no longer modified by the default `:type` or by cached owner/group/uid/gid lookups. Thanks @OskarEichler [#166]
+* `File#gets(limit)` no longer makes an extra remote read when the buffered data already satisfies the limit, and `gets(0)` returns an empty string like `IO#gets`. Thanks @OskarEichler [#165]
+* `File#puts` now behaves like `IO#puts`: with no arguments it writes a newline (it used to write nothing), `nil` and `false` are written instead of raising, objects with `to_ary` are expanded, and a recursive array no longer overflows the stack. Thanks @OskarEichler [#164]
+* Fixed `Net::SFTP::Operations::File#write` writing at the read-ahead offset instead of the current position after a buffered read (e.g. `read(2)` on an `r+` file), which corrupted data. Thanks @OskarEichler [#163]
+* Accept a `Pathname` as the local or remote path for uploads and downloads. Thanks @Tietew and @til [#153, #102]
+
 === 4.0.1
 
 * Allow net-ssh 8 [#181]

data/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to net-sftp
+
+Run the tests with `bundle exec rake test`.
+
+## Changelog
+
+Don't edit `CHANGES.txt`. Instead, add a fragment file to `changelog.d/` in your PR; the release's version bump (`rake vbump:*`) moves all fragments into a new `=== <version>` section at the top of `CHANGES.txt` and deletes them.
+
+A fragment is named `<number>.<type>.txt`, where `<number>` is the PR number (so open the PR first, then add the fragment), and contains a single UTF-8 paragraph: the entry as it should read in `CHANGES.txt`, without the bullet or prefix. Lines are joined, so it can be wrapped. If it doesn't end with a reference list such as `[#106, #107]` or `[GHSA-xxxx-xxxx-xxxx]`, ` [#<number>]` is appended.
+
+| Type                | Written as                     | Use for                                                      |
+| ------------------- | ------------------------------ | ------------------------------------------------------------ |
+| `breaking-security` | `* BREAKING: Security: <text>` | an incompatible change made for security                     |
+| `breaking`          | `* BREAKING: <text>`           | an incompatible change                                       |
+| `security`          | `* Security: <text>`           | a security fix or hardening                                  |
+| `change`            | `* <text>`                     | any other user-visible fix or feature                        |
+| `none`              | nothing                        | PRs with no user-visible change (tests, CI, docs, refactors) |
+
+Examples:
+
+```sh
+rake "changelog:new[184,change,Fixed downloading files with multibyte names]"
+# changelog.d/184.change.txt -> * Fixed downloading files with multibyte names [#184]
+
+echo 'Refuse symlinks that point outside the download directory [GHSA-xxxx-xxxx-xxxx]' > changelog.d/185.security.txt
+touch changelog.d/186.none.txt
+```
+
+For several entries from one PR add a suffix: `184.change.txt`, `184.change.2.txt` (`changelog:new` picks the next free one).
+
+`rake changelog:check` validates the fragments and `rake changelog:preview` prints the section the next release would add. CI fails a PR that edits `CHANGES.txt` or doesn't add or modify a `changelog.d/<PR number>.<type>.txt` fragment, unless it only touches `changelog.d/` or a maintainer adds the `skip-changelog` label; Dependabot PRs are skipped.
+
+The full rules, including how a release orders the entries, are in the [changelogd README](https://github.com/net-ssh/changelogd#readme).

data/Gemfile

@@ -9,6 +9,9 @@ gem "rake", ">= 12.0"
 gem "rdoc"
 gem "logger" # no longer a default gem in Ruby 4.0+
 
+# git: rather than github:, which Bundler 1.x (the default on Ruby 2.6) expands to an unsupported git:// URL.
+gem "changelogd", git: "https://github.com/net-ssh/changelogd.git", tag: "v1", group: :development
+
 gem 'byebug', group: %i[development test] if !Gem.win_platform? && RUBY_ENGINE == "ruby"
 
 if ENV["CI"]

data/Rakefile

@@ -19,6 +19,16 @@ name = "net-sftp"
 require_relative "lib/net/sftp/version"
 version = Net::SFTP::Version::CURRENT
 
+begin
+  require "changelogd/rake"
+rescue LoadError
+  # A git gem isn't on the load path under plain `rake`, as the release workflow runs it; bundler/setup could clash with the running rake.
+  require "bundler"
+  $LOAD_PATH.unshift(*Bundler.definition.specs["changelogd"].flat_map(&:full_require_paths))
+  require "changelogd/rake"
+end
+Changelogd::RakeTasks.new(version_file: "lib/net/sftp/version.rb")
+
 namespace :cert do
   desc "Update public cert from private - only run if public is expired"
   task :update_public_when_expired do
@@ -53,6 +63,7 @@ RDoc::Task.new do |rdoc|
 end
 
 def change_version(&block)
+  Rake::Task["changelog:check"].invoke
   version_file = 'lib/net/sftp/version.rb'
   require_relative version_file
   pre = Net::SFTP::Version::PRE
@@ -102,6 +113,7 @@ def change_version(&block)
 
   FileUtils.mv version_file, "#{version_file}.old"
   FileUtils.mv "#{version_file}.new", version_file
+  Rake::Task["changelog:release"].invoke
 end
 
 namespace :vbump do

data/changelog.d/README.md

@@ -0,0 +1 @@
+Changelog fragments: one `<PR number>.<type>.txt` file per user-visible change, assembled into `CHANGES.txt` when the version is bumped. See [CONTRIBUTING.md](../CONTRIBUTING.md#changelog).

data/lib/net/sftp/operations/dir.rb

@@ -58,17 +58,18 @@ module Net; module SFTP; module Operations
     def glob(path, pattern, flags=0)
       flags |= ::File::FNM_PATHNAME
       path = path.chop if path.end_with?('/') && path != '/'
+      recursive = !pattern.is_a?(String) || pattern.include?('/')
 
       results = [] unless block_given?
       queue = entries(path).reject { |e| %w(. ..).include?(e.name) }
       while queue.any?
         entry = queue.shift
 
-        if entry.directory? && !%w(. ..).include?(::File.basename(entry.name))
-          queue += entries("#{path}/#{entry.name}").map do |e|
-            e.name.replace("#{entry.name}/#{e.name}")
+        if recursive && entry.directory? && !%w(. ..).include?(::File.basename(entry.name))
+          queue.concat(entries("#{path}/#{entry.name}").map do |e|
+            e.name = "#{entry.name}/#{e.name}"
             e
-          end
+          end)
         end
 
         if ::File.fnmatch(pattern, entry.name, flags)

data/lib/net/sftp/operations/download.rb

@@ -1,3 +1,4 @@
+require 'pathname'
 require 'net/ssh/loggable'
 
 module Net; module SFTP; module Operations
@@ -145,6 +146,9 @@ module Net; module SFTP; module Operations
     # This will return immediately, and requires that the SSH event loop be
     # run in order to effect the download. (See #wait.)
     def initialize(sftp, local, remote, options={}, &progress)
+      local = local.to_path if local.is_a?(Pathname)
+      remote = remote.to_path if remote.is_a?(Pathname)
+
       @sftp = sftp
       @local = local
       @remote = remote
@@ -152,6 +156,8 @@ module Net; module SFTP; module Operations
       @options = options
       @active = 0
       @properties = options[:properties] || {}
+      requests
+      read_size
 
       self.logger = sftp.logger
 
@@ -222,13 +228,20 @@ module Net; module SFTP; module Operations
 
       # The number of bytes to read at a time from remote files.
       def read_size
-        options[:read_size] || DEFAULT_READ_SIZE
+        @read_size ||= positive_option(:read_size, DEFAULT_READ_SIZE)
       end
 
       # The number of simultaneou SFTP requests to use to effect the download.
       # Defaults to 16 for recursive downloads.
       def requests
-        options[:requests] || (recursive? ? 16 : 2)
+        @requests ||= positive_option(:requests, recursive? ? 16 : 2)
+      end
+
+      def positive_option(name, default)
+        value = (options[name] || default).to_i
+        raise ArgumentError, ":#{name} must be positive" unless value > 0
+
+        value
       end
 
       # Enqueues as many files and directories from the stack as possible
@@ -240,6 +253,7 @@ module Net; module SFTP; module Operations
 
           if entry.directory
             update_progress(:mkdir, entry.local)
+            refuse_symlink!(entry.local) if server_named?(entry) && ::File.symlink?(entry.local)
             ::Dir.mkdir(entry.local) unless ::File.directory?(entry.local)
             request = sftp.opendir(entry.remote, &method(:on_opendir))
             request[:entry] = entry
@@ -275,6 +289,7 @@ module Net; module SFTP; module Operations
         else
           response[:names].each do |item|
             next if item.name == "." || item.name == ".."
+            validate_entry_name!(entry, item.name)
             stack << Entry.new(::File.join(entry.remote, item.name), ::File.join(entry.local, item.name), item.directory?, item.attributes.size)
           end
 
@@ -286,6 +301,36 @@ module Net; module SFTP; module Operations
         end
       end
 
+      # The name comes from the server, so anything but a single path component
+      # would let a malicious server write outside the target directory.
+      def validate_entry_name!(entry, name)
+        if name.empty? || name.include?("/") || name.include?("\0") ||
+           (::File::ALT_SEPARATOR && name.include?(::File::ALT_SEPARATOR))
+          raise Net::SFTP::Exception, "readdir #{entry.remote} returned an invalid file name: #{name.inspect}"
+        end
+      end
+
+      # The caller's own +local+ may be a symlink on purpose; anything below it
+      # was named by the server (net-sftp#162).
+      def server_named?(entry)
+        entry.local != local
+      end
+
+      def open_local_file(entry)
+        return ::File.open(entry.local, "wb") unless server_named?(entry) && defined?(::File::NOFOLLOW)
+
+        begin
+          ::File.open(entry.local, "wb", :flags => ::File::NOFOLLOW)
+        rescue SystemCallError
+          raise unless ::File.symlink?(entry.local)
+          refuse_symlink!(entry.local)
+        end
+      end
+
+      def refuse_symlink!(path)
+        raise Net::SFTP::Exception, "#{path} is a symlink, refusing to follow it"
+      end
+
       # Called when a file is to be opened for reading from the remote server.
       def open_file(entry)
         update_progress(:open, entry)
@@ -308,7 +353,7 @@ module Net; module SFTP; module Operations
         raise StatusException.new(response, "open #{entry.remote}") unless response.ok?
 
         entry.handle = response[:handle]
-        entry.sink = entry.local.respond_to?(:write) ? entry.local : ::File.open(entry.local, "wb")
+        entry.sink = entry.local.respond_to?(:write) ? entry.local : open_local_file(entry)
         entry.offset = 0
 
         download_next_chunk(entry)

data/lib/net/sftp/operations/file.rb

@@ -12,6 +12,11 @@ module Net; module SFTP; module Operations
   #   puts file.gets
   #   file.close
   class File
+    # The largest amount of data sent in a single write request. Servers drop
+    # the connection on oversized packets (OpenSSH's limit is 256 KiB including
+    # headers), and the SFTP drafts only guarantee packets of about 34000 bytes.
+    MAX_WRITE_SIZE = 32 * 1024
+
     # A reference to the Net::SFTP::Session instance that drives this wrapper
     attr_reader :sftp
 
@@ -30,14 +35,14 @@ module Net; module SFTP; module Operations
       @pos      = 0
       @real_pos = 0
       @real_eof = false
-      @buffer   = ""
+      @buffer   = +""
     end
 
     # Repositions the file pointer to the given offset (relative to the
     # start of the file). This will also reset the EOF flag.
     def pos=(offset)
       @real_pos = @pos = offset
-      @buffer = ""
+      @buffer = +""
       @real_eof = false
     end
 
@@ -63,15 +68,17 @@ module Net; module SFTP; module Operations
     #
     # This will advance the file pointer (#pos).
     def read(n=nil)
+      raise ArgumentError, "negative length #{n} given" if n && n < 0
+
       loop do
         break if n && @buffer.length >= n
         break unless fill
       end
 
       if n
-        result, @buffer = @buffer[0,n], (@buffer[n..-1] || "")
+        result, @buffer = @buffer[0,n], (@buffer[n..-1] || +"")
       else
-        result, @buffer = @buffer, ""
+        result, @buffer = @buffer, +""
       end
 
       @pos += result.length
@@ -92,6 +99,7 @@ module Net; module SFTP; module Operations
         sep_string = sep_or_limit
         lim = limit
       end
+      lim = Float::INFINITY if lim.nil? || lim < 0
 
       delim = if sep_string && sep_string.length == 0
         "#{$/}#{$/}"
@@ -99,22 +107,26 @@ module Net; module SFTP; module Operations
         sep_string
       end
 
+      search_from = 0
       loop do
-        at = @buffer.index(delim) if delim
+        at = @buffer.index(delim, search_from) if delim
         if at
           offset = [at + delim.length, lim].min
           @pos += offset
           line, @buffer = @buffer[0,offset], @buffer[offset..-1]
           return line
-        elsif lim < @buffer.length
+        elsif lim <= @buffer.length
           @pos += lim
           line, @buffer = @buffer[0,lim], @buffer[lim..-1]
           return line
-        elsif !fill
-          return nil if @buffer.empty?
-          @pos += @buffer.length
-          line, @buffer = @buffer, ""
-          return line
+        else
+          search_from = [@buffer.length - delim.length + 1, 0].max if delim
+          unless fill
+            return nil if @buffer.empty?
+            @pos += @buffer.length
+            line, @buffer = @buffer, +""
+            return line
+          end
         end
       end
     end
@@ -128,13 +140,21 @@ module Net; module SFTP; module Operations
     end
 
     # Writes the given data to the stream, incrementing the file position and
-    # returning the number of bytes written.
+    # returning the number of bytes written. Data larger than MAX_WRITE_SIZE
+    # is sent as several sequential write requests; if one fails, the
+    # position reflects the bytes written before it.
     def write(data)
       data = data.to_s
-      sftp.write!(handle, @real_pos, data)
-      @real_pos += data.bytes.length
-      @pos = @real_pos
-      data.bytes.length
+      size = data.bytesize
+      written = 0
+      loop do
+        chunk = data.byteslice(written, MAX_WRITE_SIZE)
+        sftp.write!(handle, @pos, chunk)
+        written += chunk.bytesize
+        self.pos = @pos + chunk.bytesize unless chunk.empty?
+        break if written >= size
+      end
+      size
     end
 
     # Writes each argument to the stream. If +$\+ is set, it will be written
@@ -155,16 +175,12 @@ module Net; module SFTP; module Operations
     end
 
     # Writes each argument to the stream, appending a newline to any item
-    # that does not already end in a newline. Array arguments are flattened.
+    # that does not already end in a newline, like IO#puts. Array arguments
+    # are flattened, and with no arguments a single newline is written.
     def puts(*items)
-      items.each do |item|
-        if Array === item
-          puts(*item)
-        else
-          write(item)
-          write("\n") unless item[-1] == ?\n
-        end
-      end
+      items = [""] if items.empty?
+      recursion = {}.compare_by_identity
+      items.each { |item| write_puts_item(item, recursion) }
       nil
     end
 
@@ -178,12 +194,30 @@ module Net; module SFTP; module Operations
 
     private
 
+      def write_puts_item(item, recursion)
+        array = Array.try_convert(item)
+        if array
+          if recursion.key?(item)
+            item = "[...]"
+          else
+            recursion[item] = true
+            array.each { |child| write_puts_item(child, recursion) }
+            recursion.delete(item)
+            return
+          end
+        end
+
+        item = item.to_s
+        write(item) unless item.empty?
+        write("\n") unless item[-1] == ?\n
+      end
+
       # Fills the buffer. Returns +true+ if it succeeded, and +false+ if
       # EOF was encountered before any data was read.
       def fill
         data = sftp.read!(handle, @real_pos, 8192)
 
-        if data.nil?
+        if data.nil? || data.empty?
           @real_eof = true
           return false
         else

data/lib/net/sftp/operations/upload.rb

@@ -1,3 +1,4 @@
+require 'pathname'
 require 'net/ssh/loggable'
 
 module Net; module SFTP; module Operations
@@ -50,7 +51,9 @@ module Net; module SFTP; module Operations
   #   higher might improve throughput. Reducing it will reduce throughput.
   # * <tt>:read_size</tt> - the maximum number of bytes to read at a time
   #   from the source. Increasing this value might improve throughput. It
-  #   defaults to 32,000 bytes.
+  #   defaults to 32,000 bytes. Each chunk is sent as one write request, so
+  #   it must stay within the server's packet limit (OpenSSH drops the
+  #   connection on packets over 256 KiB).
   # * <tt>:name</tt> - the filename to report to the progress monitor when
   #   an IO object is given as +local+. This defaults to "<memory>".
   #
@@ -141,6 +144,9 @@ module Net; module SFTP; module Operations
     # This will return immediately, and requires that the SSH event loop be
     # run in order to effect the upload. (See #wait.)
     def initialize(sftp, local, remote, options={}, &progress) #:nodoc:
+      local = local.to_path if local.is_a?(Pathname)
+      remote = remote.to_path if remote.is_a?(Pathname)
+
       @sftp = sftp
       @local = local
       @remote = remote
@@ -153,6 +159,8 @@ module Net; module SFTP; module Operations
 
       @uploads = []
       @recursive = local.respond_to?(:read) ? false : ::File.directory?(local)
+      requests
+      read_size
 
       if recursive?
         @stack = [entries_for(local)]
@@ -164,7 +172,7 @@ module Net; module SFTP; module Operations
           sftp.mkdir(remote) do |response|
             @active -= 1
             raise StatusException.new(response, "mkdir `#{remote}'") unless response.ok?
-            (options[:requests] || RECURSIVE_READERS).to_i.times do
+            requests.times do
               break unless process_next_entry
             end
           end
@@ -225,6 +233,21 @@ module Net; module SFTP; module Operations
       # The progress handler for this instance. Possibly nil.
       def progress; @progress; end
 
+      def requests
+        @requests ||= positive_option(:requests, recursive? ? RECURSIVE_READERS : SINGLE_FILE_READERS)
+      end
+
+      def read_size
+        @read_size ||= positive_option(:read_size, DEFAULT_READ_SIZE)
+      end
+
+      def positive_option(name, default)
+        value = (options[name] || default).to_i
+        raise ArgumentError, ":#{name} must be positive" unless value > 0
+
+        value
+      end
+
       # A simple struct for recording metadata about the file currently being
       # uploaded.
       LiveFile = Struct.new(:local, :remote, :io, :size, :handle)
@@ -326,7 +349,7 @@ module Net; module SFTP; module Operations
         write_next_chunk(file)
 
         if !recursive?
-          (options[:requests] || SINGLE_FILE_READERS).to_i.times { write_next_chunk(file) }
+          (requests - 1).times { write_next_chunk(file) }
         end
       end
 
@@ -358,7 +381,7 @@ module Net; module SFTP; module Operations
         else
           @active += 1
           offset = file.io.pos
-          data = file.io.read(options[:read_size] || DEFAULT_READ_SIZE)
+          data = file.io.read(read_size)
           if data.nil?
             update_progress(:close, file)
             request = sftp.close(file.handle, &method(:on_close))

data/lib/net/sftp/protocol/01/attributes.rb

@@ -150,7 +150,7 @@ module Net; module SFTP; module Protocol; module V01
     # * :mtime:: the modification time of the file (integer, seconds since epoch)
     # * :extended:: a hash of name/value pairs identifying extended info
     def initialize(attributes={})
-      @attributes = attributes
+      @attributes = attributes.dup
     end
 
     # Returns the user-id of the user that owns the file, or +nil+ if that

data/lib/net/sftp/protocol/01/name.rb

@@ -5,7 +5,7 @@ module Net; module SFTP; module Protocol; module V01
   # for use when displaying directory data, and has no specified format.
   class Name
     # The name of the item on the remote server.
-    attr_reader :name
+    attr_accessor :name
 
     # The display-ready name of the item, possibly with other attributes.
     attr_reader :longname

data/lib/net/sftp/protocol/03/base.rb

@@ -18,6 +18,16 @@ module Net; module SFTP; module Protocol; module V03
       3
     end
 
+    # Version 3 adds a message and language tag to status responses.
+    def parse_status_packet(packet)
+      data = super
+      unless packet.eof?
+        data[:message] = packet.read_string
+        data[:language] = packet.read_string
+      end
+      data
+    end
+
     # Sends a FXP_READLINK packet to the server to request that the target of
     # the given symlink on the remote host (+path+) be returned.
     def readlink(path)
@@ -32,4 +42,4 @@ module Net; module SFTP; module Protocol; module V03
 
   end
 
-end; end; end; end
+end; end; end; end

data/lib/net/sftp/protocol/04/attributes.rb

@@ -123,7 +123,7 @@ module Net; module SFTP; module Protocol; module V04
     # to T_REGULAR.
     def initialize(attributes={})
       super
-      attributes[:type] ||= T_REGULAR
+      self.type ||= T_REGULAR
     end
 
     private
@@ -134,6 +134,15 @@ module Net; module SFTP; module Protocol; module V04
         # were given on instantiation
         owner
         group
+
+        # The subsecond flag applies to every timestamp present in the packet.
+        subseconds = self.class.elements.select { |_name, _type, flags| flags & F_SUBSECOND_TIMES != 0 }
+        if subseconds.any? { |name, _type, _flags| attributes[name] }
+          subseconds.each do |name, _type, _flags|
+            seconds = name.to_s.sub(/_nseconds\z/, "").to_sym
+            attributes[name] ||= 0 if attributes[seconds]
+          end
+        end
       end
 
       # Performs protocol-version-specific encoding of the access control

data/lib/net/sftp/protocol/04/name.rb

@@ -9,7 +9,7 @@ module Net; module SFTP; module Protocol; module V04
   # a directory listing.
   class Name
     # The name of the item on the remote server.
-    attr_reader :name
+    attr_accessor :name
 
     # Attributes instance describing this item.
     attr_reader :attributes
@@ -44,24 +44,33 @@ module Net; module SFTP; module Protocol; module V04
           "l"
         else
           "-"
-        end
+        end.dup
 
-        longname << (attributes.permissions & 0400 != 0 ? "r" : "-")
-        longname << (attributes.permissions & 0200 != 0 ? "w" : "-")
-        longname << (attributes.permissions & 0100 != 0 ? "x" : "-")
-        longname << (attributes.permissions & 0040 != 0 ? "r" : "-")
-        longname << (attributes.permissions & 0020 != 0 ? "w" : "-")
-        longname << (attributes.permissions & 0010 != 0 ? "x" : "-")
-        longname << (attributes.permissions & 0004 != 0 ? "r" : "-")
-        longname << (attributes.permissions & 0002 != 0 ? "w" : "-")
-        longname << (attributes.permissions & 0001 != 0 ? "x" : "-")
+        # Fields the server omitted are shown as "?", like GNU ls -l does for entries it cannot stat.
+        if (permissions = attributes.permissions)
+          longname << (permissions & 0400 != 0 ? "r" : "-")
+          longname << (permissions & 0200 != 0 ? "w" : "-")
+          longname << (permissions & 0100 != 0 ? "x" : "-")
+          longname << (permissions & 0040 != 0 ? "r" : "-")
+          longname << (permissions & 0020 != 0 ? "w" : "-")
+          longname << (permissions & 0010 != 0 ? "x" : "-")
+          longname << (permissions & 0004 != 0 ? "r" : "-")
+          longname << (permissions & 0002 != 0 ? "w" : "-")
+          longname << (permissions & 0001 != 0 ? "x" : "-")
+        else
+          longname << "?" * 9
+        end
 
-        longname << (" %-8s %-8s %8d " % [attributes.owner, attributes.group, attributes.size])
+        longname << (" %-8s %-8s %8s " % [attributes.owner || "?", attributes.group || "?", attributes.size || "?"])
 
-        longname << Time.at(attributes.mtime).strftime("%b %e %H:%M ")
+        longname << if attributes.mtime
+          Time.at(attributes.mtime).strftime("%b %e %H:%M ")
+        else
+          "%12s " % "?"
+        end
         longname << name
       end
     end
   end
 
-end; end; end; end
+end; end; end; end

data/lib/net/sftp/protocol/05/base.rb

@@ -35,25 +35,28 @@ module Net; module SFTP; module Protocol; module V05
     def open(path, flags, options)
       flags = normalize_open_flags(flags)
 
-      sftp_flags, desired_access = if flags & (IO::WRONLY | IO::RDWR) != 0
-          open = if flags & (IO::CREAT | IO::EXCL) == (IO::CREAT | IO::EXCL)
+      sftp_flags = if flags & (IO::CREAT | IO::EXCL) == (IO::CREAT | IO::EXCL)
             FV5::CREATE_NEW
           elsif flags & (IO::CREAT | IO::TRUNC) == (IO::CREAT | IO::TRUNC)
             FV5::CREATE_TRUNCATE
           elsif flags & IO::CREAT == IO::CREAT
             FV5::OPEN_OR_CREATE
+          elsif flags & IO::TRUNC == IO::TRUNC
+            FV5::TRUNCATE_EXISTING
           else
             FV5::OPEN_EXISTING
           end
+
+      desired_access = if flags & (IO::WRONLY | IO::RDWR) != 0
           access = ACE::Mask::WRITE_DATA | ACE::Mask::WRITE_ATTRIBUTES
           access |= ACE::Mask::READ_DATA | ACE::Mask::READ_ATTRIBUTES if (flags & IO::RDWR) == IO::RDWR
           if flags & IO::APPEND == IO::APPEND
-            open |= FV5::APPEND_DATA
+            sftp_flags |= FV5::APPEND_DATA
             access |= ACE::Mask::APPEND_DATA
           end
-          [open, access]
+          access
         else
-          [FV5::OPEN_EXISTING, ACE::Mask::READ_DATA | ACE::Mask::READ_ATTRIBUTES]
+          ACE::Mask::READ_DATA | ACE::Mask::READ_ATTRIBUTES
         end
 
       attributes = attribute_factory.new(options)
@@ -63,4 +66,4 @@ module Net; module SFTP; module Protocol; module V05
 
   end
 
-end; end; end; end
+end; end; end; end

data/lib/net/sftp/protocol/base.rb

@@ -19,6 +19,7 @@ module Net; module SFTP; module Protocol
       @session = session
       self.logger = session.logger
       @request_id_counter = -1
+      @request_ids_wrapped = false
     end
 
     # Attept to parse the given packet. If the packet is of an unsupported
@@ -41,10 +42,15 @@ module Net; module SFTP; module Protocol
       # A new request identifier will be allocated to this request, and will
       # be returned.
       def send_request(type, *args)
-        @request_id_counter += 1
+        begin
+          previous_request_id = @request_id_counter
+          @request_id_counter = (@request_id_counter + 1) & 0xffffffff
+          @request_ids_wrapped = true if previous_request_id == 0xffffffff
+        end while @request_ids_wrapped && session.pending_requests.key?(@request_id_counter)
+
         session.send_packet(type, :long, @request_id_counter, *args)
         return @request_id_counter
       end
   end
 
-end; end; end
+end; end; end

data/lib/net/sftp/session.rb

@@ -269,6 +269,10 @@ module Net; module SFTP
       # Request object. If a block is given, it will be invoked when the
       # server responds.
       #
+      # +data+ is sent as a single request, so it must stay within the
+      # server's packet limit (OpenSSH drops the connection on packets over
+      # 256 KiB). Net::SFTP::Operations::File#write splits large data for you.
+      #
       #   request = sftp.write(handle, 0, "hello, world!\n")
       #   request.wait
       def write(handle, offset, data, &callback)
@@ -772,6 +776,7 @@ module Net; module SFTP
         when :closed
           @state = :opening
           @channel = session.open_channel(&method(:when_channel_confirmed))
+          @input = Net::SSH::Buffer.new
           @packet_length = nil
           @protocol = nil
           @on_ready = Array(block)

data/lib/net/sftp/version.rb

@@ -52,7 +52,7 @@ module Net
       MINOR = 0
 
       # The tiny component of this version of the Net::SFTP library
-      TINY  = 1
+      TINY  = 2
 
       # The prerelease component of this version of the Net::SFTP library
       # nil allowed

data/lib/net/sftp.rb

@@ -34,18 +34,24 @@ module Net
     #   set the SFTP protocol version to be used)
     def self.start(host, user, ssh_options={}, sftp_options={}, &block)
       session = Net::SSH.start(host, user, ssh_options)
-      # We only use a single option here, but this leaves room for more later
-      # without breaking the external API.
-      version = sftp_options.fetch(:version, nil)
-      sftp = Net::SFTP::Session.new(session, version, &block).connect!
+      begin
+        # We only use a single option here, but this leaves room for more later
+        # without breaking the external API.
+        version = sftp_options.fetch(:version, nil)
+        sftp = Net::SFTP::Session.new(session, version, &block).connect!
 
-      if block_given?
-        sftp.loop
-        session.close
-        return nil
-      end
+        if block_given?
+          sftp.loop
+          return nil
+        end
 
-      sftp
+        sftp
+      rescue Object
+        failed = true
+        raise
+      ensure
+        session.close if block_given? && !failed
+      end
     rescue Object => anything
       begin
         session.shutdown!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-sftp
 version: !ruby/object:Gem::Version
-  version: 4.0.1
+  version: 4.0.2
 platform: ruby
 authors:
 - Jamis Buck
@@ -32,7 +32,7 @@ cert_chain:
   mMdUtmMoVbjbik3hqkY/18G03c3PoFNpL38VLKuyyROYz1DaCqOaRju3sbOoirD+
   piQTZDCWxeKuX0Iuxq02uxkYHfoGB6In0y3OOQ==
   -----END CERTIFICATE-----
-date: 2026-10-22 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-ssh
@@ -91,14 +91,18 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.rdoc
 files:
+- ".github/pull_request_template.md"
+- ".github/workflows/changelog.yml"
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - CHANGES.txt
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - Manifest
 - README.rdoc
 - Rakefile
+- changelog.d/README.md
 - lib/net/sftp.rb
 - lib/net/sftp/constants.rb
 - lib/net/sftp/errors.rb