net-sftp 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4319de630f665ee342eb3c367bf1fbe1e71a057206379c5251ab2c3b073d0cb7
-  data.tar.gz: a35ca9f05cf5bd73f2e9b5ede7ed9f473d0025c7da530707a6470e0bdbcc1adb
+  metadata.gz: 4d3d330529ea03b189dc54e18be90d35bb2bfb79374917e9e22a2fcd3d7d79ca
+  data.tar.gz: feaf13c15e37ea24c5ed45f52a842b0a8d4413cc2a27f1ee6de5a03a0975d527
 SHA512:
-  metadata.gz: 37774670d3e3a6627f1070e5043316ccc590fd0c5049971ff36a5f83391b266a129b3f660f1b75a1d71819baef95c104f3c22bb21a1c90cdab05ff4c96ddd7a9
-  data.tar.gz: 0fd554d08be7d9151484f8fe8a5bb17a4f095918457a33ffc6dbebd06a7fbffc3fcbf6d79d159339e4f20c3bada94d1b3c9980936808012287b717296c4facf0
+  metadata.gz: 3da2ef173bd6e6ac212cf3ae73243a887ae0d136fc01f03a06b383f00a6ea19a55d2f461f5fadff10d6991dd295c6fb9c826edf6557f1d2a831fe32f2782dfdf
+  data.tar.gz: e12c6bdf4efc55e51fbf6dbe3ddb12494b8f3b090e9786bdf6deb002a6966505e9a6a63440fdb43fb23da9c20fce7b0c40d2b2e5425dd095a97dfe1648102dfb

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

@@ -1,35 +1,37 @@
 name: CI
-on: [push, pull_request]
+on:
+  pull_request:
+  push: { branches: master }
+permissions:
+  contents: read
 jobs:
   test:
-    runs-on: ubuntu-18.04
-    continue-on-error: ${{ matrix.flaky }}
+    # setup-ruby has no builds of Ruby 3.1 and older for ubuntu-latest (26.04).
+    runs-on: ubuntu-24.04
     strategy:
+      fail-fast: false
       matrix:
-        ruby-version: ["2.5", "2.6", "2.7", "3.0", "3.1", "truffleruby-22", "truffleruby-21"]
-        flaky: [false]
-        include:
-          - ruby-version: "ruby-head"
-            flaky: true
-          - ruby-version: "jruby-9.2"
-            flaky: true
-          - ruby-version: "jruby-9.3"
-            flaky: true
-          - ruby-version: "jruby-head"
-            flaky: true
-          - ruby-version: "truffleruby-head"
-            flaky: true
+        ruby-version: ['2.6', '2.7', '3.0', '3.1', '3.2', '3.3', '3.4', '4.0', 'ruby-head', 'jruby', 'truffleruby']
+    continue-on-error: ${{ contains(fromJSON('["ruby-head", "jruby", "truffleruby"]'), matrix.ruby-version) }}
     steps:
-      - uses: actions/checkout@v1
-
+      - uses: actions/checkout@v4
       - name: Set up Ruby ${{ matrix.ruby-version }}
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby-version }}
-
-      - name: Bundle install
-        run: |
-          gem install bundler
-          bundle install
+          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/.gitignore

@@ -4,3 +4,4 @@ coverage
 ri
 *.swp
 Gemfile.lock
+lib/net/sftp/version.rb.old

data/CHANGES.txt

@@ -1,3 +1,48 @@
+=== 4.1.0
+
+* BREAKING: Require Ruby 2.6 or later. Bundler on older Rubies resolves to 4.0.2. [#207]
+* BREAKING: `upload` and `download` no longer close an IO object passed in as the local side; `download` flushes it instead. Callers that relied on the close must close it themselves. [#202]
+* Security: An `FXP_VERSION` packet after the session is open now raises `Net::SFTP::Exception` instead of switching protocol version mid-session and dropping pending requests. [#193]
+* Security: A server can no longer make the client allocate without bound, or hang, by sending an ACL, extended attribute or directory listing count larger than the packet holds; such packets now raise `Net::SFTP::Exception`. [#192]
+* Single-file downloads keep up to `:requests` reads in flight (default 64) instead of waiting for each 32 KB reply, so large downloads are no longer bound by round-trip time. [#204]
+* `upload!` and `download!` now give new files and directories the source's permissions (masked to 0777, subject to the umask) like OpenSSH's sftp client, so executables stay executable and private files are no longer created world-readable. The new `:preserve` option also copies access and modification times and sets permissions exactly. As with OpenSSH, attributes are best effort: if they can't be read the transfer uses default permissions, and if they can't be set a warning is logged and the transfer still succeeds. [#203]
+* Added `Net::SFTP::Session#extensions`, the extensions the server advertised in its `FXP_VERSION` packet (such as `posix-rename@openssh.com`). [#195]
+* The `:version` option now caps the negotiated SFTP protocol version; servers that always reply with their own version (OpenSSH replies 3) used to be negotiated at that version instead of the one requested. [#194]
+
+=== 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]
+
+=== 4.0.0
+
+* Allow net-ssh 7
+* Fix multibyte string write [#110]
+
 === 3.0.0
 
 * Pass protocol version via Net::SFTP.start [#107]

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

@@ -4,8 +4,13 @@ source 'https://rubygems.org'
 gemspec
 
 # TODO: add to gemspec
-gem "bundler", "~> 2.1"
-gem "rake", "~> 12.0"
+gem "bundler", ">= 1.11"
+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"
 

data/README.rdoc

@@ -35,6 +35,9 @@ In a nutshell:
     # download a file or directory from the remote host
     sftp.download!("/path/to/remote", "/path/to/local")
 
+    # also copy access and modification times (permissions are always copied)
+    sftp.download!("/path/to/remote", "/path/to/local", :preserve => true)
+
     # grab data off the remote host directly to a buffer
     data = sftp.download!("/path/to/remote")
 

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
@@ -27,7 +37,7 @@ namespace :cert do
     raw = File.read "net-sftp-public_cert.pem"
     certificate = OpenSSL::X509::Certificate.new raw
     raise Exception, "Not yet expired: #{certificate.not_after}" unless certificate.not_after < Time.now
-    sh "gem cert --build netssh@solutious.com --days 365*5 --private-key /mnt/gem/net-ssh-private_key.pem"
+    sh "gem cert --build netssh@solutious.com --days 1825 --private-key /mnt/gem/net-ssh-private_key.pem"
     sh "mv gem-public_cert.pem net-sftp-public_cert.pem"
     sh "gem cert --add net-sftp-public_cert.pem"
   end
@@ -51,3 +61,116 @@ RDoc::Task.new do |rdoc|
     rdoc.rdoc_files.include(file) if File.exist?(file)
   }
 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
+  tiny = Net::SFTP::Version::TINY
+  minor = Net::SFTP::Version::MINOR
+  result = block[pre: pre, tiny: tiny, minor: minor]
+  raise ArgumentError, "Version change logic should always return a pre" unless result.key?(:pre)
+
+  new_pre = result[:pre]
+  new_tiny = result[:tiny] || tiny
+  new_minor = result[:minor] || minor
+  found = { pre: false, tiny: false, minor: false }
+  File.open("#{version_file}.new", "w") do |f|
+    File.readlines(version_file).each do |line|
+      match =
+        if pre.nil?
+          /^(\s+PRE\s+=\s+)nil(\s*)$/.match(line)
+        else
+          /^(\s+PRE\s+=\s+")#{pre}("\s*)$/.match(line)
+        end
+      if match
+        prefix = match[1]
+        postfix = match[2]
+        prefix.delete_suffix!('"')
+        postfix.delete_prefix!('"')
+        new_line = "#{prefix}#{new_pre.inspect}#{postfix}"
+        puts "Changing:\n  - #{line}  + #{new_line}"
+        line = new_line
+        found[:pre] = true
+      end
+
+      if new_tiny != tiny
+        match = /^(\s+TINY\s+=\s+)#{tiny}(\s*)$/.match(line)
+        if match
+          prefix = match[1]
+          postfix = match[2]
+          new_line = "#{prefix}#{new_tiny}#{postfix}"
+          puts "Changing:\n  - #{line}  + #{new_line}"
+          line = new_line
+          found[:tiny] = true
+        end
+      end
+
+      if new_minor != minor
+        match = /^(\s+MINOR\s+=\s+)#{minor}(\s*)$/.match(line)
+        if match
+          prefix = match[1]
+          postfix = match[2]
+          new_line = "#{prefix}#{new_minor}#{postfix}"
+          puts "Changing:\n  - #{line}  + #{new_line}"
+          line = new_line
+          found[:minor] = true
+        end
+      end
+
+      f.write(line)
+    end
+    raise ArgumentError, "Cound not find line: PRE = \"#{pre}\" in #{version_file}" unless found[:pre]
+    raise ArgumentError, "Cound not find line: TINY = \"#{tiny}\" in #{version_file}" unless found[:tiny] || new_tiny == tiny
+    raise ArgumentError, "Cound not find line: MINOR = \"#{minor}\" in #{version_file}" unless found[:minor] || new_minor == minor
+  end
+
+  FileUtils.mv version_file, "#{version_file}.old"
+  FileUtils.mv "#{version_file}.new", version_file
+  Rake::Task["changelog:release"].invoke
+end
+
+namespace :vbump do
+  desc "Final release"
+  task :final do
+    change_version do |pre:, tiny:, **|
+      _ = tiny
+      if pre.nil?
+        { tiny: tiny + 1, pre: nil }
+      else
+        raise ArgumentError, "Unexpected pre: #{pre}" if pre.nil?
+
+        { pre: nil }
+      end
+    end
+  end
+
+  desc "Minor release"
+  task :minor do
+    change_version do |pre:, minor:, **|
+      raise ArgumentError, "PRE is #{pre.inspect}; release it with vbump:final first" unless pre.nil?
+
+      { minor: minor + 1, tiny: 0, pre: nil }
+    end
+  end
+
+  desc "Increment prerelease"
+  task :pre, [:type] do |_t, args|
+    change_version do |pre:, tiny:, **|
+      puts " PRE => #{pre.inspect}"
+      match = /^([a-z]+)(\d+)/.match(pre)
+      raise ArgumentError, "Unexpected pre: #{pre}" if match.nil? && args[:type].nil?
+
+      if match.nil? || (!args[:type].nil? && args[:type] != match[1])
+        if pre.nil?
+          { pre: "#{args[:type]}1", tiny: tiny + 1 }
+        else
+          { pre: "#{args[:type]}1" }
+        end
+      else
+        { pre: "#{match[1]}#{match[2].to_i + 1}" }
+      end
+    end
+  end
+end

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)