ftpfxp 0.0.1 → 0.0.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (4) hide show
  1. data/lib/ftpfxp.rb +8 -9
  2. data/lib/ftpfxp/ftpfxp.rb +71 -22
  3. data/lib/ftpfxp/ftpfxptls.rb +104 -24
  4. metadata +3 -3
data/lib/ftpfxp.rb CHANGED
@@ -1,11 +1,10 @@
1
- =begin
2
- = ftpfxp.rb - FXP enhancements to the basic FTP Client Library.
3
- Copyright (C)2006, Alex Lee. All Rights Reserved.
4
-
5
- Written by Alex Lee <alexeen@noservice.net>.
6
-
7
- This library is distributed under the terms of the Ruby license.
8
- You can freely distribute/modify this library.
9
- =end
1
+ #
2
+ # = ftpfxp.rb - FXP enhancements to the basic FTP Client Library.
3
+ #
4
+ # Written by Alex Lee <alexeen@gmail.com>.
5
+ #
6
+ # This library is distributed under the terms of the Ruby license.
7
+ # You can freely distribute/modify this library.
8
+ #
10
9
  require 'ftpfxp/ftpfxp'
11
10
  require 'ftpfxp/ftpfxptls'
data/lib/ftpfxp/ftpfxp.rb CHANGED
@@ -1,19 +1,47 @@
1
- =begin
2
- = ftpfxp.rb - FXP enhancements to the basic FTP Client Library.
3
- Copyright (C)2006, Alex Lee. All Rights Reserved.
4
-
5
- Written by Alex Lee <alexeen@noservice.net>.
6
-
7
- This library is distributed under the terms of the Ruby license.
8
- You can freely distribute/modify this library.
9
- =end
1
+ #
2
+ # = ftpfxp.rb - FXP enhancements to the basic FTP Client Library.
3
+ #
4
+ # Written by Alex Lee <alexeen@gmail.com>.
5
+ #
6
+ # This library is distributed under the terms of the Ruby license.
7
+ # You can freely distribute/modify this library.
8
+ #
10
9
  require 'net/ftp'
11
10
 
12
11
  module Net
13
- class FTPFXP < FTP
14
12
 
15
- # Issue the FEAT command to dump a list of FTP extensions supported
16
- # by this FTP server.
13
+ # :stopdoc:
14
+ class FTPFXPError < FTPError; end
15
+ class FTPFXPSrcSiteError < FTPFXPError; end
16
+ class FTPFXPDstSiteError < FTPFXPError; end
17
+ # :startdoc:
18
+
19
+ #
20
+ # This class implements the File Transfer Protocol with
21
+ # FXP Server-to-Server transfer. This class makes FXP
22
+ # file transfers extremely easy yet also provides the
23
+ # low level control for users who wish to do things their
24
+ # own ways.
25
+ #
26
+ # == Major Methods
27
+ #
28
+ # - #feat
29
+ # - #xdupe
30
+ # - #fxpgetpasvport
31
+ # - #fxpsetport
32
+ # - #fxpstor
33
+ # - #fxpretr
34
+ # - #fxpwait
35
+ # - #fxpto
36
+ # - #fastlist
37
+ # - #fileExists
38
+ #
39
+ class FTPFXP < FTP
40
+ #
41
+ # Issue the +FEAT+ command to dump a list of FTP extensions supported
42
+ # by this FTP server. Please note that this list is based on what
43
+ # the server wants to return.
44
+ #
17
45
  def feat
18
46
  synchronize do
19
47
  putline('FEAT')
@@ -21,14 +49,16 @@ module Net
21
49
  end
22
50
  end
23
51
 
24
- # Sets the extended dupe checking mode on the ftp server.
52
+ #
53
+ # Sets the <tt>extended dupe checking mode</tt> on the ftp server.
25
54
  # If no mode specified, it returns the current mode.
26
55
  # mode=0 : Disables the extended dupe checking mode.
27
56
  # mode=1 : X-DUPE replies several file names per line.
28
57
  # mode=2 : Server replies with one file name per X-DUPE line.
29
58
  # mode=3 : Server replies with one filename per X-DUPE line with no truncation.
30
59
  # mode=4 : All files listed in one long line up to max 1024 characters.
31
- # For details, visit http://www.smartftp.com/Products/SmartFTP/RFC/x-dupe-info.txt
60
+ # For details, visit <em>http://www.smartftp.com/Products/SmartFTP/RFC/x-dupe-info.txt</em>
61
+ #
32
62
  def xdupe(mode=nil)
33
63
  synchronize do
34
64
  if mode.nil?
@@ -41,7 +71,9 @@ module Net
41
71
  end
42
72
  end
43
73
 
44
- # Returns the passive port values on this ftp server.
74
+ #
75
+ # Returns the +passive+ port values on this ftp server.
76
+ #
45
77
  def fxpgetpasvport
46
78
  synchronize do
47
79
  # Get the passive IP and port values for next transfer.
@@ -50,7 +82,9 @@ module Net
50
82
  end
51
83
  end
52
84
 
53
- # Sets the IP and port for next transfer on this ftp server.
85
+ #
86
+ # Sets the +IP+ and +port+ for next transfer on this ftp server.
87
+ #
54
88
  def fxpsetport(ipnport)
55
89
  synchronize do
56
90
  putline("PORT #{ipnport}")
@@ -58,8 +92,10 @@ module Net
58
92
  end
59
93
  end
60
94
 
95
+ #
61
96
  # This is called on the destination side of the FXP.
62
- # This should be called before fxpretr.
97
+ # This should be called before +fxpretr+.
98
+ #
63
99
  def fxpstor(file)
64
100
  synchronize do
65
101
  voidcmd('TYPE I')
@@ -68,8 +104,10 @@ module Net
68
104
  end
69
105
  end
70
106
 
107
+ #
71
108
  # This is called on the source side of the FXP.
72
- # This should be called after fxpstor.
109
+ # This should be called after +fxpstor+.
110
+ #
73
111
  def fxpretr(file)
74
112
  synchronize do
75
113
  voidcmd('TYPE I')
@@ -78,18 +116,25 @@ module Net
78
116
  end
79
117
  end
80
118
 
119
+ #
81
120
  # This waits for the FXP to finish on the current ftp server.
82
121
  # If this is the source, it should return 226 Transfer Complete,
83
122
  # on success. If this is the destination, it should return
84
123
  # 226 File receive OK.
124
+ #
85
125
  def fxpwait
86
126
  synchronize do
87
127
  return getresp
88
128
  end
89
129
  end
90
130
 
131
+ #
91
132
  # This FXP the specified source path to the destination path
92
133
  # on the destination site. Path names should be for files only.
134
+ # This raises an exception <tt>FTPFXPSrcSiteError</tt> if errored
135
+ # on source site and raises an exception <tt>FTPFXPDstSiteError</tt>
136
+ # if errored on destination site.
137
+ #
93
138
  def fxpto(dst, dstpath, srcpath)
94
139
  pline = fxpgetpasvport
95
140
  comp = pline.split(/\s+/)
@@ -98,16 +143,18 @@ module Net
98
143
  dst.fxpstor(dstpath)
99
144
  fxpretr(srcpath)
100
145
  resp = fxpwait
101
- raise "#{resp}" unless '226' == resp[0,3]
146
+ raise FTPFXPSrcSiteError unless '226' == resp[0,3]
102
147
  resp = dst.fxpwait
103
- raise "#{resp}" unless '226' == resp[0,3]
148
+ raise FTPFXPDstSiteError unless '226' == resp[0,3]
104
149
  return resp
105
150
  end
106
151
 
107
- # This is a faster implementation of LIST where we use STAT -l
152
+ #
153
+ # This is a faster implementation of LIST where we use +STAT -l+
108
154
  # on supported servers. (All latest versions of ftp servers should
109
155
  # support this!) The path argument is optional, but it will call
110
- # STAT -l on the path if it is specified.
156
+ # +STAT -l+ on the path if it is specified.
157
+ #
111
158
  def fastlist(path = nil)
112
159
  synchronize do
113
160
  if path.nil?
@@ -119,7 +166,9 @@ module Net
119
166
  end
120
167
  end
121
168
 
169
+ #
122
170
  # Check if a file path exists.
171
+ #
123
172
  def fileExists(path)
124
173
  resp = fastlist(path)
125
174
  stats = false
data/lib/ftpfxp/ftpfxptls.rb CHANGED
@@ -1,22 +1,73 @@
1
- =begin
2
- = ftpfxptlx.rb - FXP with SSL/TLS enhancements to the basic FTP Client Library.
3
- Copyright (C)2006, Alex Lee. All Rights Reserved.
4
-
5
- Written by Alex Lee <alexeen@noservice.net>.
6
-
7
- This library is distributed under the terms of the Ruby license.
8
- You can freely distribute/modify this library.
9
- =end
1
+ #
2
+ # = ftpfxptlx.rb - FXP with SSL/TLS enhancements to the basic FTP Client Library.
3
+ #
4
+ # Written by Alex Lee <alexeen@gmail.com>.
5
+ #
6
+ # This library is distributed under the terms of the Ruby license.
7
+ # You can freely distribute/modify this library.
8
+ #
10
9
  require 'socket'
11
10
  require 'openssl'
12
11
  require 'ftpfxp'
13
12
 
14
13
  module Net
14
+ # :stopdoc:
15
+ class FTPFXPTLSError < FTPFXPError; end
16
+ class FTPFXPTLSSrcSiteError < FTPFXPTLSError; end
17
+ class FTPFXPTLSDstSiteError < FTPFXPTLSError; end
18
+ # :startdoc:
19
+
20
+ #
21
+ # This class implements the File Transfer Protocol with
22
+ # SSL/TLS secure connections. This class makes secure
23
+ # file transfers extremely easy yet also provides the
24
+ # low level control for users who wish to do things their
25
+ # own ways.
26
+ #
27
+ # == Major Methods
28
+ #
29
+ # - #login
30
+ # - #fxpprotp
31
+ # - #fxpprotc
32
+ # - #fxpgetcpsvport
33
+ # - #ftpccc
34
+ # - #fxpsscnon
35
+ # - #fxpsscnoff
36
+ # - #fxpto
37
+ # - #fxpsscnto
38
+ #
15
39
  class FTPFXPTLS < FTPFXP
16
40
  include OpenSSL
17
- # The mode option controls the encryption to use.
18
- # mode = 0 for TLS (default)
19
- # mode = 1 for SSL
41
+
42
+ # When +true+, transfers are performed securely. Default: +true+.
43
+ attr_reader :secure_on
44
+
45
+ #
46
+ # A synonym for <tt>FTPFXPTLS.new</tt>. but with a manditory host parameter.
47
+ #
48
+ # If a block is given, it is passed the +FTP+ object, which will be closed
49
+ # when the block finishes, or when an exception is raised.
50
+ #
51
+ def FTPFXPTLS.open(host, user = nil, passwd = nil, mode = 0, acct = nil)
52
+ if block_given?
53
+ ftpfxptls = new(host, user, passwd, mode, acct)
54
+ begin
55
+ yield ftpfxptls
56
+ ensure
57
+ ftpfxptls.close
58
+ end
59
+ else
60
+ new(host, user, passwd, mode, acct)
61
+ end
62
+ end
63
+
64
+ #
65
+ # This method authenticates a user with the ftp server connection.
66
+ # If no +username+ given, defaults to +anonymous+.
67
+ # If no +mode+ given, defaults to +TLS AUTH+.
68
+ # - mode = 0 for +TLS+ (default)
69
+ # - mode = 1 for +SSL+
70
+ #
20
71
  def login(user = "anonymous", passwd = nil, mode = 0, acct = nil)
21
72
  # SSL/TLS context.
22
73
  ctx = OpenSSL::SSL::SSLContext.new
@@ -45,17 +96,24 @@ module Net
45
96
  @secure_on = true
46
97
  end
47
98
 
99
+ # :stopdoc:
100
+ #
48
101
  # Notes of support of each command extension.
49
102
  # Servers known to support SSCN:
50
103
  # glftpd, surgeftp, Gene6, RaidenFTPD, Serv-U
51
104
  # Servers known to support CPSV
52
105
  # glftpd, surgeftp, vsftpd, ioftpd, RaidenFTPd, and most others ...
53
106
  # Note: Serv-U does not support CPSV.
107
+ #
108
+ # :startdoc:
54
109
 
110
+ #
111
+ # This method notifies the server to start using protection mode.
55
112
  # Must issue this command on both control connections
56
- # before CPSV or SSCN when preparing secure FXP.
113
+ # before +CPSV+ or +SSCN+ when preparing secure FXP.
57
114
  # Both servers will attempt to initiate SSL/TLS handshake
58
115
  # regardless if it is Active or Passive mode.
116
+ #
59
117
  def fxpprotp
60
118
  synchronize do
61
119
  # PROT P - Private - Integrity and Privacy
@@ -68,9 +126,11 @@ module Net
68
126
  end
69
127
  end
70
128
 
129
+ #
71
130
  # Issue this command on the server will set the data
72
- # connection to unencrypted mode and no SSL/TLS handshake
131
+ # connection to +unencrypted mode+ and no SSL/TLS handshake
73
132
  # will be initiated for subsequent transfers.
133
+ #
74
134
  def fxpprotc
75
135
  synchronize do
76
136
  putline('PROT C')
@@ -78,6 +138,7 @@ module Net
78
138
  end
79
139
  end
80
140
 
141
+ #
81
142
  # This is the exact same command as PASV, except it requires the
82
143
  # control connection to be in protected mode (PROT P) and it tells
83
144
  # the server NOT to initiate the SSL/TLS handshake. The other
@@ -85,6 +146,7 @@ module Net
85
146
  # to do as usual and initiate SSL/TLS handshake.
86
147
  # Server must support CPSV FTP extension protocol
87
148
  # command. Most advance FTP servers implements CPSV.
149
+ #
88
150
  def fxpgetcpsvport
89
151
  synchronize do
90
152
  putline('CPSV')
@@ -92,9 +154,11 @@ module Net
92
154
  end
93
155
  end
94
156
 
95
- # This executes the CCC (Clear Command Channel) command.
157
+ #
158
+ # This executes the +CCC+ (Clear Command Channel) command.
96
159
  # Though the server may not allow this command because
97
160
  # there are security issues with this.
161
+ #
98
162
  def ftpccc
99
163
  synchronize do
100
164
  putline('CCC')
@@ -103,12 +167,14 @@ module Net
103
167
  end
104
168
  end
105
169
 
106
- # Toggle the SSCN mode to on for this server. SSCN
170
+ #
171
+ # Toggle the +SSCN+ mode to on for this server. SSCN
107
172
  # requires that protected mode must be turned on
108
173
  # (ie. PROT P). If SSCN is on, it tells the server
109
174
  # to act in client mode for SSL/TLS handshakes.
110
175
  # Server must support the SSCN FTP extension protocol
111
176
  # command.
177
+ #
112
178
  def fxpsscnon
113
179
  synchronize do
114
180
  putline('SSCN ON')
@@ -116,11 +182,13 @@ module Net
116
182
  end
117
183
  end
118
184
 
119
- # Toggle the SSCN mode to off for this server. If
185
+ #
186
+ # Toggle the +SSCN+ mode to off for this server. If
120
187
  # SSCN is off, it tells the server to act in server
121
188
  # mode (default) for SSL/TLS handshakes.
122
189
  # Server must support the SSCN FTP extension protocol
123
190
  # command.
191
+ #
124
192
  def fxpsscnoff
125
193
  synchronize do
126
194
  putline('SSCN OFF')
@@ -128,9 +196,15 @@ module Net
128
196
  end
129
197
  end
130
198
 
131
- # This FXP the specified source path to the destination path
199
+ #
200
+ # This +FXP+ the specified source path to the destination path
132
201
  # on the destination site. Path names should be for files only.
133
- # Do not call this if you're using SSCN.
202
+ # <em>Do not call this method if you're using SSCN.</em>
203
+ # This method uses +CPSV+. This raises an exception
204
+ # <tt>FTPFXPTLSSrcSiteError</tt> if errored on source site and
205
+ # raises an exception <tt>FTPFXPTLSDstSiteError</tt> if errored
206
+ # on destination site.
207
+ #
134
208
  def fxpto(dst, dstpath, srcpath)
135
209
  if not @secure_on
136
210
  voidcmd('PROT P')
@@ -144,14 +218,18 @@ module Net
144
218
  dst.fxpstor(dstpath)
145
219
  fxpretr(srcpath)
146
220
  resp = fxpwait
147
- raise "#{resp}" unless '226' == resp[0,3]
221
+ raise FTPFXPTLSSrcSiteError unless '226' == resp[0,3]
148
222
  resp = dst.fxpwait
149
- raise "#{resp}" unless '226' == resp[0,3]
223
+ raise FTPFXPTLSDstSiteError unless '226' == resp[0,3]
150
224
  return resp
151
225
  end
152
226
 
153
- # This FXP the specified source path to the destination path
227
+ #
228
+ # This +FXP+ the specified source path to the destination path
154
229
  # on the destination site. Path names should be for files only.
230
+ # <em>Do not call this method if you're using CPSV.</em>
231
+ # This method uses +SSCN+.
232
+ #
155
233
  def fxpsscnto(dst, dstpath, srcpath)
156
234
  if not @secure_on
157
235
  voidcmd('PROT P')
@@ -167,13 +245,15 @@ module Net
167
245
  dst.fxpstor(dstpath)
168
246
  fxpretr(srcpath)
169
247
  resp = fxpwait
170
- raise "#{resp}" unless '226' == resp[0,3]
248
+ raise FTPFXPTLSSrcSiteError unless '226' == resp[0,3]
171
249
  resp = dst.fxpwait
172
- raise "#{resp}" unless '226' == resp[0,3]
250
+ raise FTPFXPTLSDstSiteError unless '226' == resp[0,3]
173
251
  return resp
174
252
  end
175
253
 
254
+ #
176
255
  # Override the transfercmd to support SSL sockets.
256
+ #
177
257
  def transfercmd(cmd, rest_offset = nil)
178
258
  if @passive
179
259
  host, port = makepasv
metadata CHANGED
@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
3
3
  specification_version: 1
4
4
  name: ftpfxp
5
5
  version: !ruby/object:Gem::Version
6
- version: 0.0.1
7
- date: 2006-07-10 00:00:00 -04:00
6
+ version: 0.0.2
7
+ date: 2006-07-11 00:00:00 -04:00
8
8
  summary: Extension to Net::FTP providing FXP and SSL/TLS support
9
9
  require_paths:
10
10
  - lib
@@ -15,7 +15,7 @@ description:
15
15
  autorequire: ftpfxp
16
16
  default_executable:
17
17
  bindir: bin
18
- has_rdoc: false
18
+ has_rdoc: true
19
19
  required_ruby_version: !ruby/object:Gem::Version::Requirement
20
20
  requirements:
21
21
  - - ">"