net-sftp 0.9.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. data/doc/faq/faq.html +298 -0
  2. data/doc/faq/faq.rb +154 -0
  3. data/doc/faq/faq.yml +183 -0
  4. data/examples/sftp-open-uri.rb +30 -0
  5. data/examples/synchronous.rb +3 -1
  6. data/lib/net/sftp/errors.rb +1 -1
  7. data/lib/net/sftp/operations/read.rb +15 -11
  8. data/lib/net/sftp/session.rb +2 -2
  9. data/lib/net/sftp/version.rb +2 -2
  10. data/lib/uri/open-sftp.rb +54 -0
  11. data/lib/uri/sftp.rb +42 -0
  12. data/test/operations/tc_read.rb +3 -3
  13. data/test/protocol/01/tc_attributes.rb +1 -1
  14. data/test/protocol/04/tc_attributes.rb +2 -2
  15. metadata +48 -40
data/doc/faq/faq.html ADDED
@@ -0,0 +1,298 @@
1
+ <html>
2
+ <head>
3
+ <title>Net::SFTP FAQ</title>
4
+ <style type="text/css">
5
+ a, a:visited, a:active {
6
+ color: #00F;
7
+ text-decoration: none;
8
+ }
9
+
10
+ a:hover {
11
+ text-decoration: underline;
12
+ }
13
+
14
+ .faq-list {
15
+ color: #000;
16
+ font-family: vera-sans, verdana, arial, sans-serif;
17
+ }
18
+
19
+ .faq-title {
20
+ background: #007;
21
+ color: #FFF;
22
+ font-family: vera-sans, verdana, arial, sans-serif;
23
+ padding-left: 1em;
24
+ padding-top: 0.5em;
25
+ padding-bottom: 0.5em;
26
+ font-weight: bold;
27
+ font-size: large;
28
+ border: 1px solid #000;
29
+ }
30
+
31
+ .faq-answer {
32
+ margin-left: 1em;
33
+ color: #000;
34
+ font-family: vera-sans, verdana, arial, sans-serif;
35
+ }
36
+
37
+ .faq-answer pre {
38
+ margin-left: 1em;
39
+ color: #000;
40
+ background: #FFE;
41
+ font-size: normal;
42
+ border: 1px dotted #CCC;
43
+ padding: 1em;
44
+ }
45
+
46
+ h1 {
47
+ background: #005;
48
+ color: #FFF;
49
+ font-family: vera-sans, verdana, arial, sans-serif;
50
+ padding-left: 1em;
51
+ padding-top: 1em;
52
+ padding-bottom: 1em;
53
+ font-weight: bold;
54
+ font-size: x-large;
55
+ border: 1px solid #00F;
56
+ }
57
+ </style>
58
+ </head>
59
+ <body>
60
+ <h1>Net::SFTP FAQ</h1>
61
+ <div class="faq-list">
62
+ <ul>
63
+ <li><a href='#2203312'>What is Net::SFTP?</a></li>
64
+ <li>How do I&#8230;
65
+ <ul>
66
+ <li>...connect to an <span class="caps">SFTP</span> server?
67
+ <ul>
68
+ <li><a href='#2203252'>I&#8217;d like to connect without first getting a Net::SSH connection&#8230;</a></li>
69
+ <li><a href='#2203212'>I already have an open Net::SSH connection&#8230;</a></li>
70
+ </ul>
71
+ </li>
72
+ <li>...upload data?
73
+ <ul>
74
+ <li><a href='#2203132'>I want to upload an entire file on disk&#8230;</a></li>
75
+ <li><a href='#2203092'>I want to upload bytes from a string or other object&#8230;</a></li>
76
+ </ul>
77
+ </li>
78
+ <li>...download data?
79
+ <ul>
80
+ <li><a href='#2203012'>I want to download directly to a local file&#8230;</a></li>
81
+ <li><a href='#2202972'>I want to download to a string in memory&#8230;</a></li>
82
+ <li><a href='#2202932'>I want to be notified of the progress of the download&#8230;</a></li>
83
+ </ul>
84
+ </li>
85
+ <li>...manage file permissions?
86
+ <ul>
87
+ <li><a href='#2202862'>I want to query a file&#8217;s permissions&#8230;</a></li>
88
+ <li><a href='#2202822'>I want to change a file&#8217;s permissions&#8230;</a></li>
89
+ <li><a href='#2202782'>I already have an open handle for the remove file&#8230;</a></li>
90
+ </ul>
91
+ </li>
92
+ <li>...manage directories?
93
+ <ul>
94
+ <li><a href='#2202692'>I want to query the contents of a directory&#8230;</a></li>
95
+ <li><a href='#2202652'>I want to create a directory&#8230;</a></li>
96
+ <li><a href='#2202612'>I want to remove a directory&#8230;</a></li>
97
+ </ul>
98
+ </li>
99
+ <li><a href='#2202542'>...delete a file?</a></li>
100
+ <li><a href='#2202502'>...rename a file?</a></li>
101
+ </ul>
102
+ </li>
103
+ </ul>
104
+ </div>
105
+ <a name='2203312'></a>
106
+ <div class='faq-title'>What is Net::SFTP?</div>
107
+ <div class='faq-answer'><p>Net::SFTP is a pure-Ruby implementation of the <span class="caps">SFTP</span> protocol. That&#8217;s
108
+ &#8220;SFTP&#8221; as in &#8220;Secure File Transfer Protocol&#8221;, as defined as an adjuct to the
109
+ <span class="caps">SSH</span> specification. <em>Not</em> &#8220;SFTP&#8221; as in &#8220;Secure <span class="caps">FTP</span>&#8221; (a <em>completely</em> different
110
+ beast). Nor is it an implementation of the &#8220;Simple File Transfer Protocol&#8221;
111
+ (which is in no way secure).</p></div>
112
+ <a name='2203252'></a>
113
+ <div class='faq-title'>How do I&#8230; ...connect to an <span class="caps">SFTP</span> server? I&#8217;d like to connect without first getting a Net::SSH connection&#8230;</div>
114
+ <div class='faq-answer'><p>Something like this:</p>
115
+
116
+
117
+ <code><pre>
118
+ require 'net/sftp'
119
+
120
+ Net::SFTP.start(host, user, password) do |sftp|
121
+ ...
122
+ end
123
+ </pre></code>
124
+
125
+ <p><code>Net::SFTP.start</code> accepts the same parameters as <code>Net::SSH.start</code>,
126
+ so I&#8217;ll direct you to that documentation for all the particulars.</p></div>
127
+ <a name='2203212'></a>
128
+ <div class='faq-title'>How do I&#8230; ...connect to an <span class="caps">SFTP</span> server? I already have an open Net::SSH connection&#8230;</div>
129
+ <div class='faq-answer'><p>You can piggy-back an <span class="caps">SFTP</span> connection on an existing Net::SSH
130
+ connection, which can be useful if you&#8217;ve already got an <span class="caps">SSH</span>
131
+ connection that you&#8217;re using for port forwarding or whatever.</p>
132
+
133
+
134
+ <code><pre>
135
+ require 'net/ssh'
136
+ require 'net/sftp'
137
+
138
+ Net::SSH.start(host, user, password) do |ssh|
139
+ ...
140
+ ssh.sftp.connect do |sftp|
141
+ ...
142
+ end
143
+ ...
144
+ end
145
+ </pre></code></div>
146
+ <a name='2203132'></a>
147
+ <div class='faq-title'>How do I&#8230; ...upload data? I want to upload an entire file on disk&#8230;</div>
148
+ <div class='faq-answer'><p>Assuming you already have an <span class="caps">SFTP</span> connection:</p>
149
+
150
+
151
+ <code><pre>
152
+ sftp.put_file "/path/to/local.file", "/path/to/remote.file"
153
+ </pre></code></div>
154
+ <a name='2203092'></a>
155
+ <div class='faq-title'>How do I&#8230; ...upload data? I want to upload bytes from a string or other object&#8230;</div>
156
+ <div class='faq-answer'><p>Assuming you already have an <span class="caps">SFTP</span> connection, and your data is stored
157
+ in a string named <code>data</code>:</p>
158
+
159
+
160
+ <code><pre>
161
+ sftp.open_handle("/path/to/remote.file", "w") do |handle|
162
+ result = sftp.write(handle, data)
163
+ puts result.code # the result of the operation
164
+ end
165
+ </pre></code>
166
+
167
+ <p>If (for whatever reason) you&#8217;d rather not use blocks, you can do
168
+ without, but be sure to call <code>close_handle</code> when you&#8217;re done:</p>
169
+
170
+
171
+ <code><pre>
172
+ handle = sftp.open_handle("/path/to/remote.file", "w")
173
+ result = sftp.write(handle, data)
174
+ puts result.code # the result of the operation
175
+ sftp.close_handle(handle)
176
+ </pre></code></div>
177
+ <a name='2203012'></a>
178
+ <div class='faq-title'>How do I&#8230; ...download data? I want to download directly to a local file&#8230;</div>
179
+ <div class='faq-answer'><p>Assuming you already have an <span class="caps">SFTP</span> connection:</p>
180
+
181
+
182
+ <code><pre>
183
+ sftp.get_file "/path/to/remote.file", "/path/to/local.file"
184
+ </pre></code></div>
185
+ <a name='2202972'></a>
186
+ <div class='faq-title'>How do I&#8230; ...download data? I want to download to a string in memory&#8230;</div>
187
+ <div class='faq-answer'><p>Assuming you already have an <span class="caps">SFTP</span> connection:</p>
188
+
189
+
190
+ <code><pre>
191
+ data = nil
192
+ sftp.open_handle("/path/to/remote.file") do |handle|
193
+ data = sftp.read(handle)
194
+ end
195
+ </pre></code></div>
196
+ <a name='2202932'></a>
197
+ <div class='faq-title'>How do I&#8230; ...download data? I want to be notified of the progress of the download&#8230;</div>
198
+ <div class='faq-answer'><p>You can specify both a &#8220;chunk size&#8221; and a &#8220;progress callback&#8221;. The
199
+ callback will be invoked for every &#8220;chunk size&#8221; bytes that are
200
+ received:</p>
201
+
202
+
203
+ <code><pre>
204
+ sftp.open_handle("/path/to/remote.file") do |handle|
205
+ begin
206
+ STDOUT.sync = true
207
+ data = sftp.read(handle, :chunk_size =&gt; 4096,
208
+ :progress_callback =&gt; lambda { |data| print "." })
209
+ puts
210
+ ensure
211
+ STDOUT.sync = false
212
+ end
213
+ end
214
+ </pre></code></div>
215
+ <a name='2202862'></a>
216
+ <div class='faq-title'>How do I&#8230; ...manage file permissions? I want to query a file&#8217;s permissions&#8230;</div>
217
+ <div class='faq-answer'><p>File permissions are one of the <code>stat</code> attributes of files and
218
+ directories:</p>
219
+
220
+
221
+ <code><pre>
222
+ p sftp.stat("/path/to/remote.file").permissions
223
+ </pre></code></div>
224
+ <a name='2202822'></a>
225
+ <div class='faq-title'>How do I&#8230; ...manage file permissions? I want to change a file&#8217;s permissions&#8230;</div>
226
+ <div class='faq-answer'><p>Just use <code>setstat</code> to change the permissions of an existing file:</p>
227
+
228
+
229
+ <code><pre>
230
+ sftp.setstat("/path/to/remote.file", :permissions =&gt; 0644)
231
+ </pre></code></div>
232
+ <a name='2202782'></a>
233
+ <div class='faq-title'>How do I&#8230; ...manage file permissions? I already have an open handle for the remove file&#8230;</div>
234
+ <div class='faq-answer'><p>If you have a handle for the remote file, you can use <code>fstat</code> and
235
+ <code>fsetstat</code> to query and set the permissions:</p>
236
+
237
+
238
+ <code><pre>
239
+ sftp.open_handle("/path/to/remote.file") do |handle|
240
+ permissions = sftp.fstat(handle)
241
+ sftp.fsetstat(handle, :permissions =&gt; permissions | 0444)
242
+ end
243
+ </pre></code></div>
244
+ <a name='2202692'></a>
245
+ <div class='faq-title'>How do I&#8230; ...manage directories? I want to query the contents of a directory&#8230;</div>
246
+ <div class='faq-answer'><p>You query the contents of a directory by calling <code>opendir</code> to obtain
247
+ a handle to the directory, and then using <code>readdir</code> on the handle to
248
+ obtain a list of directory entries. Be sure to close the handle when
249
+ you&#8217;re done:</p>
250
+
251
+
252
+ <code><pre>
253
+ handle = sftp.opendir("/usr/lib")
254
+ items = sftp.readdir(handle)
255
+ items.each do |item|
256
+ puts item.filename
257
+ puts item.longname
258
+ p item.attributes # permissions, atime, etc.
259
+ end
260
+ sftp.close_handle(handle)
261
+ </pre></code></div>
262
+ <a name='2202652'></a>
263
+ <div class='faq-title'>How do I&#8230; ...manage directories? I want to create a directory&#8230;</div>
264
+ <div class='faq-answer'><p>Use <code>mkdir</code>:</p>
265
+
266
+
267
+ <code><pre>
268
+ sftp.mkdir("/path/to/remote/dir", :permissions =&gt; 0500)
269
+ </pre></code></div>
270
+ <a name='2202612'></a>
271
+ <div class='faq-title'>How do I&#8230; ...manage directories? I want to remove a directory&#8230;</div>
272
+ <div class='faq-answer'><p>Use <code>rmdir</code>:</p>
273
+
274
+
275
+ <code><pre>
276
+ sftp.rmdir("/path/to/remote/dir")
277
+ </pre></code></div>
278
+ <a name='2202542'></a>
279
+ <div class='faq-title'>How do I&#8230; ...delete a file?</div>
280
+ <div class='faq-answer'><p>Use <code>remove</code>:</p>
281
+
282
+
283
+ <code><pre>
284
+ sftp.remove("/path/to/remote.file")
285
+ </pre></code></div>
286
+ <a name='2202502'></a>
287
+ <div class='faq-title'>How do I&#8230; ...rename a file?</div>
288
+ <div class='faq-answer'><p>Use <code>rename</code>:</p>
289
+
290
+
291
+ <code><pre>
292
+ sftp.rename("/path/to/remote.file", "/path/to/new.file")
293
+ </pre></code>
294
+
295
+ <p>It should be noted that <code>rename</code> is only supported by version 2 or
296
+ later of the <span class="caps">SFTP</span> protocol, so if you&#8217;re using an older <span class="caps">SFTP</span> server you
297
+ might not be able to use this operation.</p></div>
298
+ </body></html>
data/doc/faq/faq.rb ADDED
@@ -0,0 +1,154 @@
1
+ #--
2
+ # =============================================================================
3
+ # Copyright (c) 2005, Jamis Buck (jamis@jamisbuck.org)
4
+ # All rights reserved.
5
+ #
6
+ # Redistribution and use in source and binary forms, with or without
7
+ # modification, are permitted provided that the following conditions are met:
8
+ #
9
+ # * Redistributions of source code must retain the above copyright notice,
10
+ # this list of conditions and the following disclaimer.
11
+ #
12
+ # * Redistributions in binary form must reproduce the above copyright
13
+ # notice, this list of conditions and the following disclaimer in the
14
+ # documentation and/or other materials provided with the distribution.
15
+ #
16
+ # * The names of its contributors may not be used to endorse or promote
17
+ # products derived from this software without specific prior written
18
+ # permission.
19
+ #
20
+ # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
24
+ # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
+ # =============================================================================
31
+ #++
32
+
33
+ require 'yaml'
34
+ require 'redcloth'
35
+
36
+ def process_faq_list( faqs )
37
+ puts "<ul>"
38
+ faqs.each do |faq|
39
+ process_faq_list_item faq
40
+ end
41
+ puts "</ul>"
42
+ end
43
+
44
+ def process_faq_list_item( faq )
45
+ question = faq.keys.first
46
+ answer = faq.values.first
47
+
48
+ print "<li>"
49
+
50
+ question_text = RedCloth.new(question).to_html.gsub( %r{</?p>},"" )
51
+ if answer.is_a?( Array )
52
+ puts question_text
53
+ process_faq_list answer
54
+ else
55
+ print "<a href='##{question.object_id}'>#{question_text}</a>"
56
+ end
57
+
58
+ puts "</li>"
59
+ end
60
+
61
+ def process_faq_descriptions( faqs, path=nil )
62
+ faqs.each do |faq|
63
+ process_faq_description faq, path
64
+ end
65
+ end
66
+
67
+ def process_faq_description( faq, path )
68
+ question = faq.keys.first
69
+ path = ( path ? path + " " : "" ) + question
70
+ answer = faq.values.first
71
+
72
+ if answer.is_a?( Array )
73
+ process_faq_descriptions( answer, path )
74
+ else
75
+ title = RedCloth.new( path ).to_html.gsub( %r{</?p>}, "" )
76
+ answer = RedCloth.new( answer || "" )
77
+
78
+ puts "<a name='#{question.object_id}'></a>"
79
+ puts "<div class='faq-title'>#{title}</div>"
80
+ puts "<div class='faq-answer'>#{answer.to_html}</div>"
81
+ end
82
+ end
83
+
84
+ faqs = YAML.load( File.read( "faq.yml" ) )
85
+
86
+ puts <<-EOF
87
+ <html>
88
+ <head>
89
+ <title>Net::SFTP FAQ</title>
90
+ <style type="text/css">
91
+ a, a:visited, a:active {
92
+ color: #00F;
93
+ text-decoration: none;
94
+ }
95
+
96
+ a:hover {
97
+ text-decoration: underline;
98
+ }
99
+
100
+ .faq-list {
101
+ color: #000;
102
+ font-family: vera-sans, verdana, arial, sans-serif;
103
+ }
104
+
105
+ .faq-title {
106
+ background: #007;
107
+ color: #FFF;
108
+ font-family: vera-sans, verdana, arial, sans-serif;
109
+ padding-left: 1em;
110
+ padding-top: 0.5em;
111
+ padding-bottom: 0.5em;
112
+ font-weight: bold;
113
+ font-size: large;
114
+ border: 1px solid #000;
115
+ }
116
+
117
+ .faq-answer {
118
+ margin-left: 1em;
119
+ color: #000;
120
+ font-family: vera-sans, verdana, arial, sans-serif;
121
+ }
122
+
123
+ .faq-answer pre {
124
+ margin-left: 1em;
125
+ color: #000;
126
+ background: #FFE;
127
+ font-size: normal;
128
+ border: 1px dotted #CCC;
129
+ padding: 1em;
130
+ }
131
+
132
+ h1 {
133
+ background: #005;
134
+ color: #FFF;
135
+ font-family: vera-sans, verdana, arial, sans-serif;
136
+ padding-left: 1em;
137
+ padding-top: 1em;
138
+ padding-bottom: 1em;
139
+ font-weight: bold;
140
+ font-size: x-large;
141
+ border: 1px solid #00F;
142
+ }
143
+ </style>
144
+ </head>
145
+ <body>
146
+ <h1>Net::SFTP FAQ</h1>
147
+ <div class="faq-list">
148
+ EOF
149
+
150
+ process_faq_list( faqs )
151
+ puts "</div>"
152
+ process_faq_descriptions( faqs )
153
+
154
+ puts "</body></html>"
data/doc/faq/faq.yml ADDED
@@ -0,0 +1,183 @@
1
+ ---
2
+ - "What is Net::SFTP?": |
3
+ Net::SFTP is a pure-Ruby implementation of the SFTP protocol. That's
4
+ "SFTP" as in "Secure File Transfer Protocol", as defined as an adjuct to the
5
+ SSH specification. _Not_ "SFTP" as in "Secure FTP" (a _completely_ different
6
+ beast). Nor is it an implementation of the "Simple File Transfer Protocol"
7
+ (which is in no way secure).
8
+
9
+ - "How do I...":
10
+ - "...connect to an SFTP server?":
11
+ - "I'd like to connect without first getting a Net::SSH connection...": |
12
+ Something like this:
13
+
14
+ <code><pre>
15
+ require 'net/sftp'
16
+
17
+ Net::SFTP.start(host, user, password) do |sftp|
18
+ ...
19
+ end
20
+ </pre></code>
21
+
22
+ @Net::SFTP.start@ accepts the same parameters as @Net::SSH.start@,
23
+ so I'll direct you to that documentation for all the particulars.
24
+
25
+ - "I already have an open Net::SSH connection...": |
26
+ You can piggy-back an SFTP connection on an existing Net::SSH
27
+ connection, which can be useful if you've already got an SSH
28
+ connection that you're using for port forwarding or whatever.
29
+
30
+ <code><pre>
31
+ require 'net/ssh'
32
+ require 'net/sftp'
33
+
34
+ Net::SSH.start(host, user, password) do |ssh|
35
+ ...
36
+ ssh.sftp.connect do |sftp|
37
+ ...
38
+ end
39
+ ...
40
+ end
41
+ </pre></code>
42
+
43
+ - "...upload data?":
44
+ - "I want to upload an entire file on disk...": |
45
+ Assuming you already have an SFTP connection:
46
+
47
+ <code><pre>
48
+ sftp.put_file "/path/to/local.file", "/path/to/remote.file"
49
+ </pre></code>
50
+
51
+ - "I want to upload bytes from a string or other object...": |
52
+ Assuming you already have an SFTP connection, and your data is stored
53
+ in a string named @data@:
54
+
55
+ <code><pre>
56
+ sftp.open_handle("/path/to/remote.file", "w") do |handle|
57
+ result = sftp.write(handle, data)
58
+ puts result.code # the result of the operation
59
+ end
60
+ </pre></code>
61
+
62
+ If (for whatever reason) you'd rather not use blocks, you can do
63
+ without, but be sure to call @close_handle@ when you're done:
64
+
65
+ <code><pre>
66
+ handle = sftp.open_handle("/path/to/remote.file", "w")
67
+ result = sftp.write(handle, data)
68
+ puts result.code # the result of the operation
69
+ sftp.close_handle(handle)
70
+ </pre></code>
71
+
72
+ - "...download data?":
73
+ - "I want to download directly to a local file...": |
74
+ Assuming you already have an SFTP connection:
75
+
76
+ <code><pre>
77
+ sftp.get_file "/path/to/remote.file", "/path/to/local.file"
78
+ </pre></code>
79
+
80
+ - "I want to download to a string in memory...": |
81
+ Assuming you already have an SFTP connection:
82
+
83
+ <code><pre>
84
+ data = nil
85
+ sftp.open_handle("/path/to/remote.file") do |handle|
86
+ data = sftp.read(handle)
87
+ end
88
+ </pre></code>
89
+
90
+ - "I want to be notified of the progress of the download...": |
91
+ You can specify both a "chunk size" and a "progress callback". The
92
+ callback will be invoked for every "chunk size" bytes that are
93
+ received:
94
+
95
+ <code><pre>
96
+ sftp.open_handle("/path/to/remote.file") do |handle|
97
+ begin
98
+ STDOUT.sync = true
99
+ data = sftp.read(handle, :chunk_size => 4096,
100
+ :progress_callback => lambda { |data| print "." })
101
+ puts
102
+ ensure
103
+ STDOUT.sync = false
104
+ end
105
+ end
106
+ </pre></code>
107
+
108
+ - "...manage file permissions?":
109
+ - "I want to query a file's permissions...": |
110
+ File permissions are one of the @stat@ attributes of files and
111
+ directories:
112
+
113
+ <code><pre>
114
+ p sftp.stat("/path/to/remote.file").permissions
115
+ </pre></code>
116
+
117
+ - "I want to change a file's permissions...": |
118
+ Just use @setstat@ to change the permissions of an existing file:
119
+
120
+ <code><pre>
121
+ sftp.setstat("/path/to/remote.file", :permissions => 0644)
122
+ </pre></code>
123
+
124
+ - "I already have an open handle for the remove file...": |
125
+ If you have a handle for the remote file, you can use @fstat@ and
126
+ @fsetstat@ to query and set the permissions:
127
+
128
+ <code><pre>
129
+ sftp.open_handle("/path/to/remote.file") do |handle|
130
+ permissions = sftp.fstat(handle)
131
+ sftp.fsetstat(handle, :permissions => permissions | 0444)
132
+ end
133
+ </pre></code>
134
+
135
+ - "...manage directories?":
136
+ - "I want to query the contents of a directory...": |
137
+ You query the contents of a directory by calling @opendir@ to obtain
138
+ a handle to the directory, and then using @readdir@ on the handle to
139
+ obtain a list of directory entries. Be sure to close the handle when
140
+ you're done:
141
+
142
+ <code><pre>
143
+ handle = sftp.opendir("/usr/lib")
144
+ items = sftp.readdir(handle)
145
+ items.each do |item|
146
+ puts item.filename
147
+ puts item.longname
148
+ p item.attributes # permissions, atime, etc.
149
+ end
150
+ sftp.close_handle(handle)
151
+ </pre></code>
152
+
153
+ - "I want to create a directory...": |
154
+ Use @mkdir@:
155
+
156
+ <code><pre>
157
+ sftp.mkdir("/path/to/remote/dir", :permissions => 0500)
158
+ </pre></code>
159
+
160
+ - "I want to remove a directory...": |
161
+ Use @rmdir@:
162
+
163
+ <code><pre>
164
+ sftp.rmdir("/path/to/remote/dir")
165
+ </pre></code>
166
+
167
+ - "...delete a file?": |
168
+ Use @remove@:
169
+
170
+ <code><pre>
171
+ sftp.remove("/path/to/remote.file")
172
+ </pre></code>
173
+
174
+ - "...rename a file?": |
175
+ Use @rename@:
176
+
177
+ <code><pre>
178
+ sftp.rename("/path/to/remote.file", "/path/to/new.file")
179
+ </pre></code>
180
+
181
+ It should be noted that @rename@ is only supported by version 2 or
182
+ later of the SFTP protocol, so if you're using an older SFTP server you
183
+ might not be able to use this operation.
data/examples/sftp-open-uri.rb ADDED
@@ -0,0 +1,30 @@
1
+ #--
2
+ # =============================================================================
3
+ # Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
4
+ # All rights reserved.
5
+ #
6
+ # This source file is distributed as part of the Net::SFTP Secure FTP Client
7
+ # library for Ruby. This file (and the library as a whole) may be used only as
8
+ # allowed by either the BSD license, or the Ruby license (or, by association
9
+ # with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SFTP
10
+ # distribution for the texts of these licenses.
11
+ # -----------------------------------------------------------------------------
12
+ # net-sftp website: http://net-ssh.rubyforge.org/sftp
13
+ # project website : http://rubyforge.org/projects/net-ssh
14
+ # =============================================================================
15
+ #++
16
+
17
+ $:.unshift "../lib"
18
+ require 'uri/open-sftp'
19
+
20
+ uri = URI.parse( "sftp://localhost" +
21
+ "/home/jgb3/temp/out" +
22
+ "?encryption=blowfish-cbc&compression=zlib" )
23
+
24
+ data = uri.open.read
25
+ p data.length
26
+
27
+ stream = uri.open( :chunk_size=>128,
28
+ :progress_proc => proc { |d| print "."; $stdout.flush } )
29
+ puts
30
+ p stream.read.length
data/examples/synchronous.rb CHANGED
@@ -25,7 +25,9 @@ Net::SFTP.start( 'localhost',
25
25
  handle = sftp.open_handle( "temp/out" )
26
26
  puts "got handle: #{handle.inspect}"
27
27
  puts "reading..."
28
- data = sftp.read( handle )
28
+ data = sftp.read( handle,
29
+ :chunk_size => 4*1024,
30
+ :progress_callback => proc { |data| puts " [#{data.length}]" } )
29
31
  puts "got data: #{data.length} bytes"
30
32
  sftp.close_handle( handle )
31
33
 
data/lib/net/sftp/errors.rb CHANGED
@@ -17,7 +17,7 @@
17
17
  module Net ; module SFTP
18
18
 
19
19
  # The base exception class for the SFTP system.
20
- class Exception < ::Exception; end
20
+ class Exception < RuntimeError; end
21
21
 
22
22
  # An exception class representing a bug condition.
23
23
  class Bug < Exception; end
data/lib/net/sftp/operations/read.rb CHANGED
@@ -24,22 +24,24 @@ module Net ; module SFTP ; module Operations
24
24
  # file in one chunk.
25
25
  class Read < Abstract
26
26
 
27
- # The maximum amount of data to read at once when reading an entire file.
28
- # (Setting this to a larger value may cause problems, especially with
29
- # very large files, so beware!)
30
- CHUNK_SIZE = 64 * 1024
27
+ # The default maximum amount of data to read at once when reading an entire
28
+ # file.
29
+ DEFAULT_CHUNK_SIZE = 64 * 1024
31
30
 
32
31
  # Perform the operation. If length is less than 0 (the default), then the
33
32
  # entire file (from the given offset) will be read and returned in "one
34
33
  # fell swoop". Otherwise, the given length of data will be requested.
35
- def perform( handle, offset=0, length=-1 )
36
- @length = length
34
+ def perform( handle, options={} )
35
+ @length = options[:length] || -1
37
36
  @handle = handle
38
- @offset = offset
37
+ @offset = options[:offset] || 0
38
+ @chunk_size = options[:chunk_size] || DEFAULT_CHUNK_SIZE
39
+ @progress_callback = options[:progress_callback]
39
40
  @data = ""
40
41
 
41
- real_length = ( length < 0 ? CHUNK_SIZE : length )
42
- @driver.read( nil, handle, offset, real_length )
42
+ real_length = ( @length >= 0 && @length < @chunk_size ?
43
+ @length : @chunk_size )
44
+ @driver.read( nil, @handle, @offset, real_length )
43
45
  end
44
46
 
45
47
  # Invoked when a data packet is received from the server. If the original
@@ -50,12 +52,14 @@ module Net ; module SFTP ; module Operations
50
52
  @log.debug "[#{@id}] got #{data.length} bytes" if @log.debug?
51
53
 
52
54
  @data << data
55
+ @progress_callback[@data] if @progress_callback
56
+
53
57
  if @length < 0 || @data.length < @length
54
58
  if @length < 0
55
- length = CHUNK_SIZE
59
+ length = @chunk_size
56
60
  else
57
61
  length = @length - @data.length
58
- length = length > CHUNK_SIZE ? CHUNK_SIZE : length
62
+ length = length > @chunk_size ? @chunk_size : length
59
63
  end
60
64
 
61
65
  @log.debug "[#{@id}] requesting #{length} more bytes" if @log.debug?
data/lib/net/sftp/session.rb CHANGED
@@ -181,14 +181,14 @@ module Net ; module SFTP
181
181
  def get_file( remote_path, local_path )
182
182
  open_handle( remote_path ) do |handle|
183
183
  contents = read( handle )
184
- File.open( local_path, "w" ) { |f| f.write contents }
184
+ File.open( local_path, "wb" ) { |f| f.write contents }
185
185
  end
186
186
  end
187
187
 
188
188
  # This stores the given local file at the given remote path. This will
189
189
  # overwrite any file at the remote path name. The local file must exist.
190
190
  def put_file( local_path, remote_path )
191
- contents = File.read( local_path )
191
+ contents = File.open( local_path, "rb" ) { |f| f.read }
192
192
  open_handle( remote_path, "w" ) { |handle| write( handle, contents ) }
193
193
  end
194
194
 
data/lib/net/sftp/version.rb CHANGED
@@ -16,8 +16,8 @@
16
16
 
17
17
  module Net ; module SFTP ; module Version
18
18
 
19
- MAJOR = 0
20
- MINOR = 9
19
+ MAJOR = 1
20
+ MINOR = 0
21
21
  TINY = 0
22
22
 
23
23
  STRING = [MAJOR,MINOR,TINY].join('.')
data/lib/uri/open-sftp.rb ADDED
@@ -0,0 +1,54 @@
1
+ # =======================================================================
2
+ # Net::SSH -- A Ruby module implementing the SSH2 client protocol
3
+ # Copyright (C) 2004 Jamis Buck (jgb3@email.byu.edu)
4
+ #
5
+ # This library is free software; you can redistribute it and/or
6
+ # modify it under the terms of the GNU Lesser General Public
7
+ # License as published by the Free Software Foundation; either
8
+ # version 2.1 of the License, or (at your option) any later version.
9
+ #
10
+ # This library is distributed in the hope that it will be useful,
11
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
12
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13
+ # Lesser General Public License for more details.
14
+ #
15
+ # You should have received a copy of the GNU Lesser General Public
16
+ # License along with this library; if not, write to the Free Software
17
+ # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18
+ # =======================================================================
19
+
20
+ require 'open-uri'
21
+ require 'uri/sftp'
22
+ require 'net/sftp'
23
+
24
+ OpenURI::Options[ :chunk_size ] = true
25
+
26
+ module URI
27
+
28
+ class SFTP
29
+ def direct_open( buf, open_options )
30
+ Net::SFTP.start( host, port, user, password, options ) do |sftp|
31
+ if open_options[:content_length_proc]
32
+ open_options[:content_length_proc].call( sftp.lstat( path ).size )
33
+ end
34
+
35
+ body = nil
36
+ sftp.open_handle( path ) do |handle|
37
+ body = sftp.read( handle,
38
+ :chunk_size => open_options[:chunk_size],
39
+ :progress_callback => open_options[:progress_proc] )
40
+ end
41
+
42
+ if body.nil?
43
+ raise Net::SSH::SFTP::SFTPError, sftp.status[:message]
44
+ end
45
+
46
+ buf << body
47
+ buf.io.rewind
48
+ end
49
+ end
50
+
51
+ include OpenURI::OpenRead
52
+ end
53
+
54
+ end
data/lib/uri/sftp.rb ADDED
@@ -0,0 +1,42 @@
1
+ require 'uri/generic'
2
+
3
+ module URI
4
+
5
+ class SFTP < Generic
6
+ DEFAULT_PORT = 22
7
+
8
+ COMPONENT = [
9
+ :scheme,
10
+ :userinfo,
11
+ :host, :port, :path,
12
+ :query
13
+ ].freeze
14
+
15
+ attr_reader :options
16
+
17
+ def self.new2( user, password, host, port, path, query )
18
+ new( 'sftp',
19
+ [ user, password ],
20
+ host, port,
21
+ nil, path,
22
+ nil, query )
23
+ end
24
+
25
+ def initialize( *args )
26
+ super( *args )
27
+
28
+ @options = Hash.new
29
+ ( query || "" ).split( /&/ ).each do |pair|
30
+ name, value = pair.split( /=/ )
31
+ opt_name = name.intern
32
+ values = value.split( /,/ ).map { |v| v.to_i.to_s == v ? v.to_i : v }
33
+ values = values.first if values.length == 1
34
+ options[ opt_name ] = values
35
+ end
36
+ end
37
+
38
+ end
39
+
40
+ @@schemes['SFTP'] = SFTP
41
+
42
+ end
data/test/operations/tc_read.rb CHANGED
@@ -45,7 +45,7 @@ class TC_Operations_Read < Test::Unit::TestCase
45
45
  def test_perform_explicit
46
46
  id = handle = offset = length = nil
47
47
  @driver.mock_handle( :read ) { |i,h,o,l| id, handle, offset, length = i, h, o, l; 10 }
48
- assert_equal 10, @operation.perform( "foo", 15, 72 )
48
+ assert_equal 10, @operation.perform( "foo", :offset=>15, :length=>72 )
49
49
  assert_nil id
50
50
  assert_equal "foo", handle
51
51
  assert_equal 15, offset
@@ -72,7 +72,7 @@ class TC_Operations_Read < Test::Unit::TestCase
72
72
  @session.mock_handle( :loop )
73
73
  @session.mock_handle( :status= )
74
74
  called = false
75
- @operation.execute( "foo", 15, 20 ) { called = true }
75
+ @operation.execute( "foo", :offset=>15, :length=>20 ) { called = true }
76
76
  @operation.do_data( "harbinger of doom" )
77
77
  @operation.do_data( "abc" )
78
78
  assert_equal 2, @driver.mock_count( :read )
@@ -89,7 +89,7 @@ class TC_Operations_Read < Test::Unit::TestCase
89
89
  @session.mock_handle( :loop )
90
90
  @session.mock_handle( :status= )
91
91
  called = false
92
- @operation.execute( "foo", 15, 20 ) { called = true }
92
+ @operation.execute( "foo", :offset=>15, :length=>20 ) { called = true }
93
93
  assert_nothing_raised { @operation.do_status( 1, nil, nil ) }
94
94
  assert called
95
95
  end
data/test/protocol/01/tc_attributes.rb CHANGED
@@ -126,7 +126,7 @@ class TC_01_Attributes < Test::Unit::TestCase
126
126
  [ { :mtime => 789012 }, :mtime, 789012 ],
127
127
  [ { :extended => { "foo" => "bar" } }, :extended, { "foo" => "bar" } ],
128
128
  [ { :owner => ENV['USER'] }, :uid, Etc.getpwnam(ENV['USER']).uid ],
129
- [ { :group => 'root' }, :gid, Etc.getpwnam('root').uid ]
129
+ [ { :group => 'wheel' }, :gid, Etc.getgrnam('wheel').gid ]
130
130
  ].each do |fixture|
131
131
  define_method( "test_from_hash_#{fixture[1]}" ) do
132
132
  attrs = @factory.from_hash( fixture[0] )
data/test/protocol/04/tc_attributes.rb CHANGED
@@ -150,9 +150,9 @@ class TC_04_Attributes < Test::Unit::TestCase
150
150
  [ { :type => 3 }, :type, 3 ],
151
151
  [ { :size => 1000 }, :size, 1000, :permissions ],
152
152
  [ { :owner => ENV['USER'] }, :owner, ENV['USER'] ],
153
- [ { :group => 'root' }, :group, 'root' ],
153
+ [ { :group => 'wheel' }, :group, 'wheel' ],
154
154
  [ { :uid => Etc.getpwnam(ENV['USER']).uid }, :owner, ENV['USER'] ],
155
- [ { :gid => Etc.getgrnam('root').gid }, :group, 'root' ],
155
+ [ { :gid => Etc.getgrnam('wheel').gid }, :group, 'wheel' ],
156
156
  [ { :permissions => 0600 }, :permissions, 0600 ],
157
157
  [ { :atime => 1 }, :atime, 1 ],
158
158
  [ { :atime_nseconds => 2 }, :atime_nseconds, 2 ],
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
- rubygems_version: 0.8.4
2
+ rubygems_version: 0.8.10
3
3
  specification_version: 1
4
4
  name: net-sftp
5
5
  version: !ruby/object:Gem::Version
6
- version: 0.9.0
7
- date: 2005-01-11
6
+ version: 1.0.0
7
+ date: 2005-06-17
8
8
  summary: Net::SFTP is a pure-Ruby implementation of the SFTP client protocol.
9
9
  require_paths:
10
10
  - lib
11
- email: jgb3@email.byu.edu
11
+ email: jamis@jamisbuck.org
12
12
  homepage: http://net-ssh.rubyforge.org/sftp
13
13
  rubyforge_project:
14
14
  description:
@@ -27,98 +27,106 @@ platform: ruby
27
27
  authors:
28
28
  - Jamis Buck
29
29
  files:
30
- - doc/LICENSE-RUBY
30
+ - doc/faq
31
31
  - doc/LICENSE-BSD
32
32
  - doc/LICENSE-GPL
33
+ - doc/LICENSE-RUBY
34
+ - doc/faq/faq.html
35
+ - doc/faq/faq.rb
36
+ - doc/faq/faq.yml
33
37
  - lib/net
38
+ - lib/uri
34
39
  - lib/net/sftp
35
40
  - lib/net/sftp.rb
41
+ - lib/net/sftp/errors.rb
36
42
  - lib/net/sftp/operations
37
- - lib/net/sftp/session.rb
38
43
  - lib/net/sftp/protocol
44
+ - lib/net/sftp/session.rb
39
45
  - lib/net/sftp/version.rb
40
- - lib/net/sftp/errors.rb
46
+ - lib/net/sftp/operations/abstract.rb
41
47
  - lib/net/sftp/operations/close.rb
42
- - lib/net/sftp/operations/read.rb
43
- - lib/net/sftp/operations/rmdir.rb
44
- - lib/net/sftp/operations/realpath.rb
45
- - lib/net/sftp/operations/stat.rb
46
- - lib/net/sftp/operations/readdir.rb
48
+ - lib/net/sftp/operations/errors.rb
49
+ - lib/net/sftp/operations/fsetstat.rb
50
+ - lib/net/sftp/operations/fstat.rb
47
51
  - lib/net/sftp/operations/lstat.rb
48
- - lib/net/sftp/operations/setstat.rb
49
- - lib/net/sftp/operations/abstract.rb
50
52
  - lib/net/sftp/operations/mkdir.rb
51
- - lib/net/sftp/operations/services.rb
52
53
  - lib/net/sftp/operations/open.rb
53
54
  - lib/net/sftp/operations/opendir.rb
54
- - lib/net/sftp/operations/rename.rb
55
+ - lib/net/sftp/operations/read.rb
56
+ - lib/net/sftp/operations/readdir.rb
57
+ - lib/net/sftp/operations/realpath.rb
55
58
  - lib/net/sftp/operations/remove.rb
56
- - lib/net/sftp/operations/fsetstat.rb
59
+ - lib/net/sftp/operations/rename.rb
60
+ - lib/net/sftp/operations/rmdir.rb
61
+ - lib/net/sftp/operations/services.rb
62
+ - lib/net/sftp/operations/setstat.rb
63
+ - lib/net/sftp/operations/stat.rb
57
64
  - lib/net/sftp/operations/write.rb
58
- - lib/net/sftp/operations/fstat.rb
59
- - lib/net/sftp/operations/errors.rb
60
65
  - lib/net/sftp/protocol/01
61
66
  - lib/net/sftp/protocol/02
62
67
  - lib/net/sftp/protocol/03
63
68
  - lib/net/sftp/protocol/04
64
69
  - lib/net/sftp/protocol/05
65
- - lib/net/sftp/protocol/driver.rb
66
70
  - lib/net/sftp/protocol/constants.rb
71
+ - lib/net/sftp/protocol/driver.rb
67
72
  - lib/net/sftp/protocol/packet-assistant.rb
68
73
  - lib/net/sftp/protocol/services.rb
69
74
  - lib/net/sftp/protocol/01/attributes.rb
75
+ - lib/net/sftp/protocol/01/impl.rb
70
76
  - lib/net/sftp/protocol/01/packet-assistant.rb
71
77
  - lib/net/sftp/protocol/01/services.rb
72
- - lib/net/sftp/protocol/01/impl.rb
78
+ - lib/net/sftp/protocol/02/impl.rb
73
79
  - lib/net/sftp/protocol/02/packet-assistant.rb
74
80
  - lib/net/sftp/protocol/02/services.rb
75
- - lib/net/sftp/protocol/02/impl.rb
81
+ - lib/net/sftp/protocol/03/impl.rb
76
82
  - lib/net/sftp/protocol/03/packet-assistant.rb
77
83
  - lib/net/sftp/protocol/03/services.rb
78
- - lib/net/sftp/protocol/03/impl.rb
79
84
  - lib/net/sftp/protocol/04/attributes.rb
85
+ - lib/net/sftp/protocol/04/impl.rb
80
86
  - lib/net/sftp/protocol/04/packet-assistant.rb
81
87
  - lib/net/sftp/protocol/04/services.rb
82
- - lib/net/sftp/protocol/04/impl.rb
83
88
  - lib/net/sftp/protocol/05/services.rb
89
+ - lib/uri/open-sftp.rb
90
+ - lib/uri/sftp.rb
91
+ - examples/asynchronous.rb
84
92
  - examples/get-put.rb
93
+ - examples/sftp-open-uri.rb
85
94
  - examples/ssh-service.rb
86
95
  - examples/synchronous.rb
87
- - examples/asynchronous.rb
88
- - test/operations
89
96
  - test/ALL-TESTS.rb
97
+ - test/operations
90
98
  - test/protocol
91
- - test/operations/tc_write.rb
92
- - test/operations/tc_fstat.rb
93
- - test/operations/tc_close.rb
94
99
  - test/operations/tc_abstract.rb
95
- - test/operations/tc_opendir.rb
96
- - test/operations/tc_rmdir.rb
97
- - test/operations/tc_open.rb
98
- - test/operations/tc_remove.rb
99
- - test/operations/tc_read.rb
100
+ - test/operations/tc_close.rb
100
101
  - test/operations/tc_fsetstat.rb
102
+ - test/operations/tc_fstat.rb
101
103
  - test/operations/tc_lstat.rb
102
- - test/operations/tc_readdir.rb
103
104
  - test/operations/tc_mkdir.rb
105
+ - test/operations/tc_open.rb
106
+ - test/operations/tc_opendir.rb
107
+ - test/operations/tc_read.rb
108
+ - test/operations/tc_readdir.rb
104
109
  - test/operations/tc_realpath.rb
105
- - test/operations/tc_stat.rb
110
+ - test/operations/tc_remove.rb
111
+ - test/operations/tc_rmdir.rb
106
112
  - test/operations/tc_setstat.rb
113
+ - test/operations/tc_stat.rb
114
+ - test/operations/tc_write.rb
107
115
  - test/protocol/01
108
116
  - test/protocol/02
109
117
  - test/protocol/03
110
118
  - test/protocol/04
111
119
  - test/protocol/tc_driver.rb
112
- - test/protocol/01/tc_packet_assistant.rb
113
120
  - test/protocol/01/tc_attributes.rb
114
121
  - test/protocol/01/tc_impl.rb
115
- - test/protocol/02/tc_packet_assistant.rb
122
+ - test/protocol/01/tc_packet_assistant.rb
116
123
  - test/protocol/02/tc_impl.rb
117
- - test/protocol/03/tc_packet_assistant.rb
124
+ - test/protocol/02/tc_packet_assistant.rb
118
125
  - test/protocol/03/tc_impl.rb
119
- - test/protocol/04/tc_packet_assistant.rb
126
+ - test/protocol/03/tc_packet_assistant.rb
120
127
  - test/protocol/04/tc_attributes.rb
121
128
  - test/protocol/04/tc_impl.rb
129
+ - test/protocol/04/tc_packet_assistant.rb
122
130
  test_files:
123
131
  - test/ALL-TESTS.rb
124
132
  rdoc_options: []