fmalamitsas-aws-s3 0.6.2.1254423625

Sign up to get free protection for your applications and to get access to all the features.
Files changed (93) hide show
  1. data/CHANGELOG +107 -0
  2. data/COPYING +19 -0
  3. data/INSTALL +55 -0
  4. data/README.erb +58 -0
  5. data/Rakefile +334 -0
  6. data/TODO +26 -0
  7. data/aws-s3.gemspec +42 -0
  8. data/bin/s3sh +6 -0
  9. data/bin/setup.rb +10 -0
  10. data/lib/aws/s3.rb +60 -0
  11. data/lib/aws/s3/acl.rb +636 -0
  12. data/lib/aws/s3/authentication.rb +222 -0
  13. data/lib/aws/s3/base.rb +270 -0
  14. data/lib/aws/s3/bittorrent.rb +58 -0
  15. data/lib/aws/s3/bucket.rb +372 -0
  16. data/lib/aws/s3/connection.rb +288 -0
  17. data/lib/aws/s3/error.rb +69 -0
  18. data/lib/aws/s3/exceptions.rb +133 -0
  19. data/lib/aws/s3/extensions.rb +342 -0
  20. data/lib/aws/s3/logging.rb +317 -0
  21. data/lib/aws/s3/object.rb +626 -0
  22. data/lib/aws/s3/owner.rb +46 -0
  23. data/lib/aws/s3/parsing.rb +99 -0
  24. data/lib/aws/s3/response.rb +180 -0
  25. data/lib/aws/s3/service.rb +51 -0
  26. data/lib/aws/s3/version.rb +12 -0
  27. data/site/index.erb +41 -0
  28. data/site/public/images/box-and-gem.gif +0 -0
  29. data/site/public/images/favicon.ico +0 -0
  30. data/site/public/ruby.css +18 -0
  31. data/site/public/screen.css +99 -0
  32. data/support/faster-xml-simple/COPYING +18 -0
  33. data/support/faster-xml-simple/README +8 -0
  34. data/support/faster-xml-simple/Rakefile +54 -0
  35. data/support/faster-xml-simple/lib/faster_xml_simple.rb +190 -0
  36. data/support/faster-xml-simple/test/fixtures/test-1.rails.yml +4 -0
  37. data/support/faster-xml-simple/test/fixtures/test-1.xml +3 -0
  38. data/support/faster-xml-simple/test/fixtures/test-1.yml +4 -0
  39. data/support/faster-xml-simple/test/fixtures/test-2.rails.yml +6 -0
  40. data/support/faster-xml-simple/test/fixtures/test-2.xml +3 -0
  41. data/support/faster-xml-simple/test/fixtures/test-2.yml +6 -0
  42. data/support/faster-xml-simple/test/fixtures/test-3.rails.yml +6 -0
  43. data/support/faster-xml-simple/test/fixtures/test-3.xml +5 -0
  44. data/support/faster-xml-simple/test/fixtures/test-3.yml +6 -0
  45. data/support/faster-xml-simple/test/fixtures/test-4.rails.yml +5 -0
  46. data/support/faster-xml-simple/test/fixtures/test-4.xml +7 -0
  47. data/support/faster-xml-simple/test/fixtures/test-4.yml +5 -0
  48. data/support/faster-xml-simple/test/fixtures/test-5.rails.yml +8 -0
  49. data/support/faster-xml-simple/test/fixtures/test-5.xml +7 -0
  50. data/support/faster-xml-simple/test/fixtures/test-5.yml +8 -0
  51. data/support/faster-xml-simple/test/fixtures/test-6.rails.yml +43 -0
  52. data/support/faster-xml-simple/test/fixtures/test-6.xml +29 -0
  53. data/support/faster-xml-simple/test/fixtures/test-6.yml +41 -0
  54. data/support/faster-xml-simple/test/fixtures/test-7.rails.yml +23 -0
  55. data/support/faster-xml-simple/test/fixtures/test-7.xml +22 -0
  56. data/support/faster-xml-simple/test/fixtures/test-7.yml +22 -0
  57. data/support/faster-xml-simple/test/fixtures/test-8.rails.yml +14 -0
  58. data/support/faster-xml-simple/test/fixtures/test-8.xml +8 -0
  59. data/support/faster-xml-simple/test/fixtures/test-8.yml +11 -0
  60. data/support/faster-xml-simple/test/regression_test.rb +47 -0
  61. data/support/faster-xml-simple/test/test_helper.rb +17 -0
  62. data/support/faster-xml-simple/test/xml_simple_comparison_test.rb +46 -0
  63. data/support/rdoc/code_info.rb +211 -0
  64. data/test/acl_test.rb +254 -0
  65. data/test/authentication_test.rb +118 -0
  66. data/test/base_test.rb +136 -0
  67. data/test/bucket_test.rb +74 -0
  68. data/test/connection_test.rb +216 -0
  69. data/test/error_test.rb +70 -0
  70. data/test/extensions_test.rb +340 -0
  71. data/test/fixtures.rb +89 -0
  72. data/test/fixtures/buckets.yml +133 -0
  73. data/test/fixtures/errors.yml +34 -0
  74. data/test/fixtures/headers.yml +3 -0
  75. data/test/fixtures/logging.yml +15 -0
  76. data/test/fixtures/loglines.yml +5 -0
  77. data/test/fixtures/logs.yml +7 -0
  78. data/test/fixtures/policies.yml +16 -0
  79. data/test/logging_test.rb +89 -0
  80. data/test/mocks/fake_response.rb +26 -0
  81. data/test/object_test.rb +205 -0
  82. data/test/parsing_test.rb +66 -0
  83. data/test/remote/acl_test.rb +116 -0
  84. data/test/remote/bittorrent_test.rb +45 -0
  85. data/test/remote/bucket_test.rb +146 -0
  86. data/test/remote/logging_test.rb +82 -0
  87. data/test/remote/object_test.rb +379 -0
  88. data/test/remote/test_file.data +0 -0
  89. data/test/remote/test_helper.rb +33 -0
  90. data/test/response_test.rb +68 -0
  91. data/test/service_test.rb +23 -0
  92. data/test/test_helper.rb +118 -0
  93. metadata +241 -0
@@ -0,0 +1,317 @@
1
+ module AWS
2
+ module S3
3
+ # A bucket can be set to log the requests made on it. By default logging is turned off. You can check if a bucket has logging enabled:
4
+ #
5
+ # Bucket.logging_enabled_for? 'jukebox'
6
+ # # => false
7
+ #
8
+ # Enabling it is easy:
9
+ #
10
+ # Bucket.enable_logging_for('jukebox')
11
+ #
12
+ # Unless you specify otherwise, logs will be written to the bucket you want to log. The logs are just like any other object. By default they will start with the prefix 'log-'. You can customize what bucket you want the logs to be delivered to, as well as customize what the log objects' key is prefixed with by setting the <tt>target_bucket</tt> and <tt>target_prefix</tt> option:
13
+ #
14
+ # Bucket.enable_logging_for(
15
+ # 'jukebox', 'target_bucket' => 'jukebox-logs'
16
+ # )
17
+ #
18
+ # Now instead of logging right into the jukebox bucket, the logs will go into the bucket called jukebox-logs.
19
+ #
20
+ # Once logs have accumulated, you can access them using the <tt>logs</tt> method:
21
+ #
22
+ # pp Bucket.logs('jukebox')
23
+ # [#<AWS::S3::Logging::Log '/jukebox-logs/log-2006-11-14-07-15-24-2061C35880A310A1'>,
24
+ # #<AWS::S3::Logging::Log '/jukebox-logs/log-2006-11-14-08-15-27-D8EEF536EC09E6B3'>,
25
+ # #<AWS::S3::Logging::Log '/jukebox-logs/log-2006-11-14-08-15-29-355812B2B15BD789'>]
26
+ #
27
+ # Each log has a <tt>lines</tt> method that gives you information about each request in that log. All the fields are available
28
+ # as named methods. More information is available in Logging::Log::Line.
29
+ #
30
+ # logs = Bucket.logs('jukebox')
31
+ # log = logs.first
32
+ # line = log.lines.first
33
+ # line.operation
34
+ # # => 'REST.GET.LOGGING_STATUS'
35
+ # line.request_uri
36
+ # # => 'GET /jukebox?logging HTTP/1.1'
37
+ # line.remote_ip
38
+ # # => "67.165.183.125"
39
+ #
40
+ # Disabling logging is just as simple as enabling it:
41
+ #
42
+ # Bucket.disable_logging_for('jukebox')
43
+ module Logging
44
+ # Logging status captures information about the calling bucket's logging settings. If logging is enabled for the bucket
45
+ # the status object will indicate what bucket the logs are written to via the <tt>target_bucket</tt> method as well as
46
+ # the logging key prefix with via <tt>target_prefix</tt>.
47
+ #
48
+ # See the documentation for Logging::Management::ClassMethods for more information on how to get the logging status of a bucket.
49
+ class Status
50
+ include SelectiveAttributeProxy
51
+ attr_reader :enabled
52
+ alias_method :logging_enabled?, :enabled
53
+
54
+ def initialize(attributes = {}) #:nodoc:
55
+ attributes = {'target_bucket' => nil, 'target_prefix' => nil}.merge(attributes)
56
+ @enabled = attributes.has_key?('logging_enabled')
57
+ @attributes = attributes.delete('logging_enabled') || attributes
58
+ end
59
+
60
+ def to_xml #:nodoc:
61
+ Builder.new(self).to_s
62
+ end
63
+
64
+ private
65
+ attr_reader :attributes
66
+
67
+ class Builder < XmlGenerator #:nodoc:
68
+ attr_reader :logging_status
69
+ def initialize(logging_status)
70
+ @logging_status = logging_status
71
+ super()
72
+ end
73
+
74
+ def build
75
+ xml.tag!('BucketLoggingStatus', 'xmlns' => 'http://s3.amazonaws.com/doc/2006-03-01/') do
76
+ if logging_status.target_bucket && logging_status.target_prefix
77
+ xml.LoggingEnabled do
78
+ xml.TargetBucket logging_status.target_bucket
79
+ xml.TargetPrefix logging_status.target_prefix
80
+ end
81
+ end
82
+ end
83
+ end
84
+ end
85
+ end
86
+
87
+ # A bucket log exposes requests made on the given bucket. Lines of the log represent a single request. The lines of a log
88
+ # can be accessed with the lines method.
89
+ #
90
+ # log = Bucket.logs_for('marcel').first
91
+ # log.lines
92
+ #
93
+ # More information about the logged requests can be found in the documentation for Log::Line.
94
+ class Log
95
+ def initialize(log_object) #:nodoc:
96
+ @log = log_object
97
+ end
98
+
99
+ # Returns the lines for the log. Each line is wrapped in a Log::Line.
100
+ if RUBY_VERSION >= '1.8.7'
101
+ def lines
102
+ log.value.lines.map {|line| Line.new(line)}
103
+ end
104
+ else
105
+ def lines
106
+ log.value.map {|line| Line.new(line)}
107
+ end
108
+ end
109
+ memoized :lines
110
+
111
+ def path
112
+ log.path
113
+ end
114
+
115
+ def inspect #:nodoc:
116
+ "#<%s:0x%s '%s'>" % [self.class.name, object_id, path]
117
+ end
118
+
119
+ private
120
+ attr_reader :log
121
+
122
+ # Each line of a log exposes the raw line, but it also has method accessors for all the fields of the logged request.
123
+ #
124
+ # The list of supported log line fields are listed in the S3 documentation: http://docs.amazonwebservices.com/AmazonS3/2006-03-01/LogFormat.html
125
+ #
126
+ # line = log.lines.first
127
+ # line.remote_ip
128
+ # # => '72.21.206.5'
129
+ #
130
+ # If a certain field does not apply to a given request (for example, the <tt>key</tt> field does not apply to a bucket request),
131
+ # or if it was unknown or unavailable, it will return <tt>nil</tt>.
132
+ #
133
+ # line.operation
134
+ # # => 'REST.GET.BUCKET'
135
+ # line.key
136
+ # # => nil
137
+ class Line < String
138
+ DATE = /\[([^\]]+)\]/
139
+ QUOTED_STRING = /"([^"]+)"/
140
+ REST = /(\S+)/
141
+ LINE_SCANNER = /#{DATE}|#{QUOTED_STRING}|#{REST}/
142
+
143
+ cattr_accessor :decorators
144
+ @@decorators = Hash.new {|hash, key| hash[key] = lambda {|entry| CoercibleString.coerce(entry)}}
145
+ cattr_reader :fields
146
+ @@fields = []
147
+
148
+ class << self
149
+ def field(name, offset, type = nil, &block) #:nodoc:
150
+ decorators[name] = block if block_given?
151
+ fields << name
152
+ class_eval(<<-EVAL, __FILE__, __LINE__)
153
+ def #{name}
154
+ value = parts[#{offset} - 1]
155
+ if value == '-'
156
+ nil
157
+ else
158
+ self.class.decorators[:#{name}].call(value)
159
+ end
160
+ end
161
+ memoized :#{name}
162
+ EVAL
163
+ end
164
+
165
+ # Time.parse doesn't like %d/%B/%Y:%H:%M:%S %z so we have to transform it unfortunately
166
+ def typecast_time(datetime) #:nodoc:
167
+ datetime.sub!(%r|^(\w{2})/(\w{3})/(\w{4})|, '\2 \1 \3')
168
+ if Date.constants.include?('ABBR_MONTHS')
169
+ datetime.sub!(month, Date::ABBR_MONTHS[month.downcase].to_s)
170
+ end
171
+ datetime.sub!(':', ' ')
172
+ Time.parse(datetime)
173
+ end
174
+ end
175
+
176
+ def initialize(line) #:nodoc:
177
+ super(line)
178
+ @parts = parse
179
+ end
180
+
181
+ field(:owner, 1) {|entry| Owner.new('id' => entry) }
182
+ field :bucket, 2
183
+ field(:time, 3) {|entry| typecast_time(entry)}
184
+ field :remote_ip, 4
185
+ field(:requestor, 5) {|entry| Owner.new('id' => entry) }
186
+ field :request_id, 6
187
+ field :operation, 7
188
+ field :key, 8
189
+ field :request_uri, 9
190
+ field :http_status, 10
191
+ field :error_code, 11
192
+ field :bytes_sent, 12
193
+ field :object_size, 13
194
+ field :total_time, 14
195
+ field :turn_around_time, 15
196
+ field :referrer, 16
197
+ field :user_agent, 17
198
+
199
+ # Returns all fields of the line in a hash of the form <tt>:field_name => :field_value</tt>.
200
+ #
201
+ # line.attributes.values_at(:bucket, :key)
202
+ # # => ['marcel', 'kiss.jpg']
203
+ def attributes
204
+ self.class.fields.inject({}) do |attribute_hash, field|
205
+ attribute_hash[field] = send(field)
206
+ attribute_hash
207
+ end
208
+ end
209
+
210
+ private
211
+ attr_reader :parts
212
+
213
+ def parse
214
+ scan(LINE_SCANNER).flatten.compact
215
+ end
216
+ end
217
+ end
218
+
219
+ module Management #:nodoc:
220
+ def self.included(klass) #:nodoc:
221
+ klass.extend(ClassMethods)
222
+ klass.extend(LoggingGrants)
223
+ end
224
+
225
+ module ClassMethods
226
+ # Returns the logging status for the bucket named <tt>name</tt>. From the logging status you can determine the bucket logs are delivered to
227
+ # and what the bucket object's keys are prefixed with. For more information see the Logging::Status class.
228
+ #
229
+ # Bucket.logging_status_for 'marcel'
230
+ def logging_status_for(name = nil, status = nil)
231
+ if name.is_a?(Status)
232
+ status = name
233
+ name = nil
234
+ end
235
+
236
+ path = path(name) << '?logging'
237
+ status ? put(path, {}, status.to_xml) : Status.new(get(path).parsed)
238
+ end
239
+ alias_method :logging_status, :logging_status_for
240
+
241
+ # Enables logging for the bucket named <tt>name</tt>. You can specify what bucket to log to with the <tt>'target_bucket'</tt> option as well
242
+ # as what prefix to add to the log files with the <tt>'target_prefix'</tt> option. Unless you specify otherwise, logs will be delivered to
243
+ # the same bucket that is being logged and will be prefixed with <tt>log-</tt>.
244
+ def enable_logging_for(name = nil, options = {})
245
+ name = bucket_name(name)
246
+ default_options = {'target_bucket' => name, 'target_prefix' => 'log-'}
247
+ options = default_options.merge(options)
248
+ grant_logging_access_to_target_bucket(options['target_bucket'])
249
+ logging_status(name, Status.new(options))
250
+ end
251
+ alias_method :enable_logging, :enable_logging_for
252
+
253
+ # Disables logging for the bucket named <tt>name</tt>.
254
+ def disable_logging_for(name = nil)
255
+ logging_status(bucket_name(name), Status.new)
256
+ end
257
+ alias_method :disable_logging, :disable_logging_for
258
+
259
+ # Returns true if logging has been enabled for the bucket named <tt>name</tt>.
260
+ def logging_enabled_for?(name = nil)
261
+ logging_status(bucket_name(name)).logging_enabled?
262
+ end
263
+ alias_method :logging_enabled?, :logging_enabled_for?
264
+
265
+ # Returns the collection of logs for the bucket named <tt>name</tt>.
266
+ #
267
+ # Bucket.logs_for 'marcel'
268
+ #
269
+ # Accepts the same options as Bucket.find, such as <tt>:max_keys</tt> and <tt>:marker</tt>.
270
+ def logs_for(name = nil, options = {})
271
+ if name.is_a?(Hash)
272
+ options = name
273
+ name = nil
274
+ end
275
+
276
+ name = bucket_name(name)
277
+ logging_status = logging_status_for(name)
278
+ return [] unless logging_status.logging_enabled?
279
+ objects(logging_status.target_bucket, options.merge(:prefix => logging_status.target_prefix)).map do |log_object|
280
+ Log.new(log_object)
281
+ end
282
+ end
283
+ alias_method :logs, :logs_for
284
+ end
285
+
286
+ module LoggingGrants #:nodoc:
287
+ def grant_logging_access_to_target_bucket(target_bucket)
288
+ acl = acl(target_bucket)
289
+ acl.grants << ACL::Grant.grant(:logging_write)
290
+ acl.grants << ACL::Grant.grant(:logging_read_acp)
291
+ acl(target_bucket, acl)
292
+ end
293
+ end
294
+
295
+ def logging_status
296
+ self.class.logging_status_for(name)
297
+ end
298
+
299
+ def enable_logging(*args)
300
+ self.class.enable_logging_for(name, *args)
301
+ end
302
+
303
+ def disable_logging(*args)
304
+ self.class.disable_logging_for(name, *args)
305
+ end
306
+
307
+ def logging_enabled?
308
+ self.class.logging_enabled_for?(name)
309
+ end
310
+
311
+ def logs(options = {})
312
+ self.class.logs_for(name, options)
313
+ end
314
+ end
315
+ end
316
+ end
317
+ end
@@ -0,0 +1,626 @@
1
+ module AWS
2
+ module S3
3
+ # S3Objects represent the data you store on S3. They have a key (their name) and a value (their data). All objects belong to a
4
+ # bucket.
5
+ #
6
+ # You can store an object on S3 by specifying a key, its data and the name of the bucket you want to put it in:
7
+ #
8
+ # S3Object.store('me.jpg', open('headshot.jpg'), 'photos')
9
+ #
10
+ # The content type of the object will be inferred by its extension. If the appropriate content type can not be inferred, S3 defaults
11
+ # to <tt>binary/octet-stream</tt>.
12
+ #
13
+ # If you want to override this, you can explicitly indicate what content type the object should have with the <tt>:content_type</tt> option:
14
+ #
15
+ # file = 'black-flowers.m4a'
16
+ # S3Object.store(
17
+ # file,
18
+ # open(file),
19
+ # 'jukebox',
20
+ # :content_type => 'audio/mp4a-latm'
21
+ # )
22
+ #
23
+ # You can read more about storing files on S3 in the documentation for S3Object.store.
24
+ #
25
+ # If you just want to fetch an object you've stored on S3, you just specify its name and its bucket:
26
+ #
27
+ # picture = S3Object.find 'headshot.jpg', 'photos'
28
+ #
29
+ # N.B. The actual data for the file is not downloaded in both the example where the file appeared in the bucket and when fetched directly.
30
+ # You get the data for the file like this:
31
+ #
32
+ # picture.value
33
+ #
34
+ # You can fetch just the object's data directly:
35
+ #
36
+ # S3Object.value 'headshot.jpg', 'photos'
37
+ #
38
+ # Or stream it by passing a block to <tt>stream</tt>:
39
+ #
40
+ # open('song.mp3', 'w') do |file|
41
+ # S3Object.stream('song.mp3', 'jukebox') do |chunk|
42
+ # file.write chunk
43
+ # end
44
+ # end
45
+ #
46
+ # The data of the file, once download, is cached, so subsequent calls to <tt>value</tt> won't redownload the file unless you
47
+ # tell the object to reload its <tt>value</tt>:
48
+ #
49
+ # # Redownloads the file's data
50
+ # song.value(:reload)
51
+ #
52
+ # Other functionality includes:
53
+ #
54
+ # # Check if an object exists?
55
+ # S3Object.exists? 'headshot.jpg', 'photos'
56
+ #
57
+ # # Copying an object
58
+ # S3Object.copy 'headshot.jpg', 'headshot2.jpg', 'photos'
59
+ #
60
+ # # Renaming an object
61
+ # S3Object.rename 'headshot.jpg', 'portrait.jpg', 'photos'
62
+ #
63
+ # # Deleting an object
64
+ # S3Object.delete 'headshot.jpg', 'photos'
65
+ #
66
+ # ==== More about objects and their metadata
67
+ #
68
+ # You can find out the content type of your object with the <tt>content_type</tt> method:
69
+ #
70
+ # song.content_type
71
+ # # => "audio/mpeg"
72
+ #
73
+ # You can change the content type as well if you like:
74
+ #
75
+ # song.content_type = 'application/pdf'
76
+ # song.store
77
+ #
78
+ # (Keep in mind that due to limitiations in S3's exposed API, the only way to change things like the content_type
79
+ # is to PUT the object onto S3 again. In the case of large files, this will result in fully re-uploading the file.)
80
+ #
81
+ # A bevie of information about an object can be had using the <tt>about</tt> method:
82
+ #
83
+ # pp song.about
84
+ # {"last-modified" => "Sat, 28 Oct 2006 21:29:26 GMT",
85
+ # "content-type" => "binary/octet-stream",
86
+ # "etag" => "\"dc629038ffc674bee6f62eb64ff3a\"",
87
+ # "date" => "Sat, 28 Oct 2006 21:30:41 GMT",
88
+ # "x-amz-request-id" => "B7BC68F55495B1C8",
89
+ # "server" => "AmazonS3",
90
+ # "content-length" => "3418766"}
91
+ #
92
+ # You can get and set metadata for an object:
93
+ #
94
+ # song.metadata
95
+ # # => {}
96
+ # song.metadata[:album] = "A River Ain't Too Much To Love"
97
+ # # => "A River Ain't Too Much To Love"
98
+ # song.metadata[:released] = 2005
99
+ # pp song.metadata
100
+ # {"x-amz-meta-released" => 2005,
101
+ # "x-amz-meta-album" => "A River Ain't Too Much To Love"}
102
+ # song.store
103
+ #
104
+ # That metadata will be saved in S3 and is hence forth available from that object:
105
+ #
106
+ # song = S3Object.find('black-flowers.mp3', 'jukebox')
107
+ # pp song.metadata
108
+ # {"x-amz-meta-released" => "2005",
109
+ # "x-amz-meta-album" => "A River Ain't Too Much To Love"}
110
+ # song.metadata[:released]
111
+ # # => "2005"
112
+ # song.metadata[:released] = 2006
113
+ # pp song.metadata
114
+ # {"x-amz-meta-released" => 2006,
115
+ # "x-amz-meta-album" => "A River Ain't Too Much To Love"}
116
+ class S3Object < Base
117
+ class << self
118
+ # Returns the value of the object with <tt>key</tt> in the specified bucket.
119
+ #
120
+ # === Conditional GET options
121
+ #
122
+ # * <tt>:if_modified_since</tt> - Return the object only if it has been modified since the specified time,
123
+ # otherwise return a 304 (not modified).
124
+ # * <tt>:if_unmodified_since</tt> - Return the object only if it has not been modified since the specified time,
125
+ # otherwise raise PreconditionFailed.
126
+ # * <tt>:if_match</tt> - Return the object only if its entity tag (ETag) is the same as the one specified,
127
+ # otherwise raise PreconditionFailed.
128
+ # * <tt>:if_none_match</tt> - Return the object only if its entity tag (ETag) is different from the one specified,
129
+ # otherwise return a 304 (not modified).
130
+ #
131
+ # === Other options
132
+ # * <tt>:range</tt> - Return only the bytes of the object in the specified range.
133
+ def value(key, bucket = nil, options = {}, &block)
134
+ Value.new(get(path!(bucket, key, options), options, &block))
135
+ end
136
+
137
+ def stream(key, bucket = nil, options = {}, &block)
138
+ value(key, bucket, options) do |response|
139
+ if (200..299).include? response.code.to_i
140
+ response.read_body(&block)
141
+ else
142
+ Error::Response.new(response).error.raise
143
+ end
144
+ end
145
+ end
146
+
147
+ # Returns the object whose key is <tt>name</tt> in the specified bucket. If the specified key does not
148
+ # exist, a NoSuchKey exception will be raised.
149
+ def find(key, bucket = nil)
150
+ # N.B. This is arguably a hack. From what the current S3 API exposes, when you retrieve a bucket, it
151
+ # provides a listing of all the files in that bucket (assuming you haven't limited the scope of what it returns).
152
+ # Each file in the listing contains information about that file. It is from this information that an S3Object is built.
153
+ #
154
+ # If you know the specific file that you want, S3 allows you to make a get request for that specific file and it returns
155
+ # the value of that file in its response body. This response body is used to build an S3Object::Value object.
156
+ # If you want information about that file, you can make a head request and the headers of the response will contain
157
+ # information about that file. There is no way, though, to say, give me the representation of just this given file the same
158
+ # way that it would appear in a bucket listing.
159
+ #
160
+ # When fetching a bucket, you can provide options which narrow the scope of what files should be returned in that listing.
161
+ # Of those options, one is <tt>marker</tt> which is a string and instructs the bucket to return only object's who's key comes after
162
+ # the specified marker according to alphabetic order. Another option is <tt>max-keys</tt> which defaults to 1000 but allows you
163
+ # to dictate how many objects should be returned in the listing. With a combination of <tt>marker</tt> and <tt>max-keys</tt> you can
164
+ # *almost* specify exactly which file you'd like it to return, but <tt>marker</tt> is not inclusive. In other words, if there is a bucket
165
+ # which contains three objects who's keys are respectively 'a', 'b' and 'c', then fetching a bucket listing with marker set to 'b' will only
166
+ # return 'c', not 'b'.
167
+ #
168
+ # Given all that, my hack to fetch a bucket with only one specific file, is to set the marker to the result of calling String#previous on
169
+ # the desired object's key, which functionally makes the key ordered one degree higher than the desired object key according to
170
+ # alphabetic ordering. This is a hack, but it should work around 99% of the time. I can't think of a scenario where it would return
171
+ # something incorrect.
172
+
173
+ # We need to ensure the key doesn't have extended characters but not uri escape it before doing the lookup and comparing since if the object exists,
174
+ # the key on S3 will have been normalized
175
+ key = key.remove_extended unless key.valid_utf8?
176
+ bucket = Bucket.find(bucket_name(bucket), :marker => key.previous, :max_keys => 1)
177
+ # If our heuristic failed, trigger a NoSuchKey exception
178
+ if (object = bucket.objects.first) && object.key == key
179
+ object
180
+ else
181
+ raise NoSuchKey.new("No such key `#{key}'", bucket)
182
+ end
183
+ end
184
+
185
+ # Makes a copy of the object with <tt>key</tt> to <tt>copy_key</tt>, preserving the ACL of the existing object if the <tt>:copy_acl</tt> option is true (default false).
186
+ def copy(key, copy_key = nil, bucket = nil, options = {})
187
+ copy_key ||= key
188
+ options = {:dest_bucket => bucket}.merge(options)
189
+ bucket = bucket_name(bucket)
190
+ dest_bucket = bucket_name(options[:dest_bucket])
191
+ # source_key = path!(bucket, key)
192
+ source_key = "#{bucket}#{path!(bucket, key)}"
193
+ default_options = {'x-amz-copy-source' => source_key}
194
+ target_key = path!(dest_bucket, copy_key)
195
+ returning put(target_key, default_options) do
196
+ acl(copy_key, dest_bucket, acl(key, bucket)) if options[:copy_acl]
197
+ end
198
+ end
199
+
200
+ # Rename the object with key <tt>from</tt> to have key in <tt>to</tt>.
201
+ def rename(from, to, bucket = nil, options = {})
202
+ copy(from, to, bucket, options)
203
+ delete(from, bucket)
204
+ end
205
+
206
+ # Fetch information about the object with <tt>key</tt> from <tt>bucket</tt>. Information includes content type, content length,
207
+ # last modified time, and others.
208
+ #
209
+ # If the specified key does not exist, NoSuchKey is raised.
210
+ def about(key, bucket = nil, options = {})
211
+ response = head(path!(bucket, key, options), options)
212
+ raise NoSuchKey.new("No such key `#{key}'", bucket) if response.code == 404
213
+ About.new(response.headers)
214
+ end
215
+
216
+ # Checks if the object with <tt>key</tt> in <tt>bucket</tt> exists.
217
+ #
218
+ # S3Object.exists? 'kiss.jpg', 'marcel'
219
+ # # => true
220
+ def exists?(key, bucket = nil)
221
+ about(key, bucket)
222
+ true
223
+ rescue NoSuchKey
224
+ false
225
+ end
226
+
227
+ # Delete object with <tt>key</tt> from <tt>bucket</tt>.
228
+ def delete(key, bucket = nil, options = {})
229
+ # A bit confusing. Calling super actually makes an HTTP DELETE request. The delete method is
230
+ # defined in the Base class. It happens to have the same name.
231
+ super(path!(bucket, key, options), options).success?
232
+ end
233
+
234
+ # When storing an object on the S3 servers using S3Object.store, the <tt>data</tt> argument can be a string or an I/O stream.
235
+ # If <tt>data</tt> is an I/O stream it will be read in segments and written to the socket incrementally. This approach
236
+ # may be desirable for very large files so they are not read into memory all at once.
237
+ #
238
+ # # Non streamed upload
239
+ # S3Object.store('greeting.txt', 'hello world!', 'marcel')
240
+ #
241
+ # # Streamed upload
242
+ # S3Object.store('roots.mpeg', open('roots.mpeg'), 'marcel')
243
+ def store(key, data, bucket = nil, options = {})
244
+ validate_key!(key)
245
+ # Must build path before infering content type in case bucket is being used for options
246
+ path = path!(bucket, key, options)
247
+ infer_content_type!(key, options)
248
+
249
+ put(path, options, data) # Don't call .success? on response. We want to get the etag.
250
+ end
251
+ alias_method :create, :store
252
+ alias_method :save, :store
253
+
254
+ # All private objects are accessible via an authenticated GET request to the S3 servers. You can generate an
255
+ # authenticated url for an object like this:
256
+ #
257
+ # S3Object.url_for('beluga_baby.jpg', 'marcel_molina')
258
+ #
259
+ # By default authenticated urls expire 5 minutes after they were generated.
260
+ #
261
+ # Expiration options can be specified either with an absolute time since the epoch with the <tt>:expires</tt> options,
262
+ # or with a number of seconds relative to now with the <tt>:expires_in</tt> options:
263
+ #
264
+ # # Absolute expiration date
265
+ # # (Expires January 18th, 2038)
266
+ # doomsday = Time.mktime(2038, 1, 18).to_i
267
+ # S3Object.url_for('beluga_baby.jpg',
268
+ # 'marcel',
269
+ # :expires => doomsday)
270
+ #
271
+ # # Expiration relative to now specified in seconds
272
+ # # (Expires in 3 hours)
273
+ # S3Object.url_for('beluga_baby.jpg',
274
+ # 'marcel',
275
+ # :expires_in => 60 * 60 * 3)
276
+ #
277
+ # You can specify whether the url should go over SSL with the <tt>:use_ssl</tt> option:
278
+ #
279
+ # # Url will use https protocol
280
+ # S3Object.url_for('beluga_baby.jpg',
281
+ # 'marcel',
282
+ # :use_ssl => true)
283
+ #
284
+ # By default, the ssl settings for the current connection will be used.
285
+ #
286
+ # If you have an object handy, you can use its <tt>url</tt> method with the same objects:
287
+ #
288
+ # song.url(:expires_in => 30)
289
+ #
290
+ # To get an unauthenticated url for the object, such as in the case
291
+ # when the object is publicly readable, pass the
292
+ # <tt>:authenticated</tt> option with a value of <tt>false</tt>.
293
+ #
294
+ # S3Object.url_for('beluga_baby.jpg',
295
+ # 'marcel',
296
+ # :authenticated => false)
297
+ # # => http://s3.amazonaws.com/marcel/beluga_baby.jpg
298
+ def url_for(name, bucket = nil, options = {})
299
+ connection.url_for(path!(bucket, name, options), current_host, options) # Do not normalize options
300
+ end
301
+
302
+ def path!(bucket, name, options = {}) #:nodoc:
303
+ # We're using the second argument for options
304
+ if bucket.is_a?(Hash)
305
+ options.replace(bucket)
306
+ bucket = nil
307
+ end
308
+ self.current_host = bucket_name(bucket)
309
+ "/#{name}"
310
+ end
311
+
312
+ private
313
+
314
+ def validate_key!(key)
315
+ raise InvalidKeyName.new(key) unless key && key.size <= 1024
316
+ end
317
+
318
+ def infer_content_type!(key, options)
319
+ return if options.has_key?(:content_type)
320
+ if mime_type = MIME::Types.type_for(key).first
321
+ options[:content_type] = mime_type.content_type
322
+ end
323
+ end
324
+ end
325
+
326
+ class Value < String #:nodoc:
327
+ attr_reader :response
328
+ def initialize(response)
329
+ super(response.body)
330
+ @response = response
331
+ end
332
+ end
333
+
334
+ class About < Hash #:nodoc:
335
+ def initialize(headers)
336
+ super()
337
+ replace(headers)
338
+ metadata
339
+ end
340
+
341
+ def [](header)
342
+ super(header.to_header)
343
+ end
344
+
345
+ def []=(header, value)
346
+ super(header.to_header, value)
347
+ end
348
+
349
+ def to_headers
350
+ self.merge(metadata.to_headers)
351
+ end
352
+
353
+ def metadata
354
+ Metadata.new(self)
355
+ end
356
+ memoized :metadata
357
+ end
358
+
359
+ class Metadata < Hash #:nodoc:
360
+ HEADER_PREFIX = 'x-amz-meta-'
361
+ SIZE_LIMIT = 2048 # 2 kilobytes
362
+
363
+ def initialize(headers)
364
+ @headers = headers
365
+ super()
366
+ extract_metadata!
367
+ end
368
+
369
+ def []=(header, value)
370
+ super(header_name(header.to_header), value)
371
+ end
372
+
373
+ def [](header)
374
+ super(header_name(header.to_header))
375
+ end
376
+
377
+ def to_headers
378
+ validate!
379
+ self
380
+ end
381
+
382
+ private
383
+ attr_reader :headers
384
+
385
+ def extract_metadata!
386
+ headers.keys.grep(Regexp.new(HEADER_PREFIX)).each do |metadata_header|
387
+ self[metadata_header] = headers.delete(metadata_header)
388
+ end
389
+ end
390
+
391
+ def header_name(name)
392
+ name =~ Regexp.new(HEADER_PREFIX) ? name : [HEADER_PREFIX, name].join
393
+ end
394
+
395
+ def validate!
396
+ invalid_headers = inject([]) do |invalid, (name, value)|
397
+ invalid << name unless valid?(value)
398
+ invalid
399
+ end
400
+
401
+ raise InvalidMetadataValue.new(invalid_headers) unless invalid_headers.empty?
402
+ end
403
+
404
+ def valid?(value)
405
+ value && value.size < SIZE_LIMIT
406
+ end
407
+ end
408
+
409
+ attr_writer :value #:nodoc:
410
+
411
+ # Provides readers and writers for all valid header settings listed in <tt>valid_header_settings</tt>.
412
+ # Subsequent saves to the object after setting any of the valid headers settings will be reflected in
413
+ # information about the object.
414
+ #
415
+ # some_s3_object.content_type
416
+ # => nil
417
+ # some_s3_object.content_type = 'text/plain'
418
+ # => "text/plain"
419
+ # some_s3_object.content_type
420
+ # => "text/plain"
421
+ # some_s3_object.store
422
+ # S3Object.about(some_s3_object.key, some_s3_object.bucket.name)['content-type']
423
+ # => "text/plain"
424
+ include SelectiveAttributeProxy #:nodoc
425
+
426
+ proxy_to :about, :exclusively => false
427
+
428
+ # Initializes a new S3Object.
429
+ def initialize(attributes = {}, &block)
430
+ super
431
+ self.value = attributes.delete(:value)
432
+ self.bucket = attributes.delete(:bucket)
433
+ yield self if block_given?
434
+ end
435
+
436
+ # The current object's bucket. If no bucket has been set, a NoBucketSpecified exception will be raised. For
437
+ # cases where you are not sure if the bucket has been set, you can use the belongs_to_bucket? method.
438
+ def bucket
439
+ @bucket or raise NoBucketSpecified
440
+ end
441
+
442
+ # Sets the bucket that the object belongs to.
443
+ def bucket=(bucket)
444
+ @bucket = bucket
445
+ self
446
+ end
447
+
448
+ # Returns true if the current object has been assigned to a bucket yet. Objects must belong to a bucket before they
449
+ # can be saved onto S3.
450
+ def belongs_to_bucket?
451
+ !@bucket.nil?
452
+ end
453
+ alias_method :orphan?, :belongs_to_bucket?
454
+
455
+ # Returns the key of the object. If the key is not set, a NoKeySpecified exception will be raised. For cases
456
+ # where you are not sure if the key has been set, you can use the key_set? method. Objects must have a key
457
+ # set to be saved onto S3. Objects which have already been saved onto S3 will always have their key set.
458
+ def key
459
+ k = attributes['key'] or raise NoKeySpecified
460
+ k.to_s
461
+ end
462
+
463
+ # Sets the key for the current object.
464
+ def key=(value)
465
+ attributes['key'] = value
466
+ end
467
+
468
+ # Returns true if the current object has had its key set yet. Objects which have already been saved will
469
+ # always return true. This method is useful for objects which have not been saved yet so you know if you
470
+ # need to set the object's key since you can not save an object unless its key has been set.
471
+ #
472
+ # object.store if object.key_set? && object.belongs_to_bucket?
473
+ def key_set?
474
+ !attributes['key'].nil?
475
+ end
476
+
477
+ # Lazily loads object data.
478
+ #
479
+ # Force a reload of the data by passing <tt>:reload</tt>.
480
+ #
481
+ # object.value(:reload)
482
+ #
483
+ # When loading the data for the first time you can optionally yield to a block which will
484
+ # allow you to stream the data in segments.
485
+ #
486
+ # object.value do |segment|
487
+ # send_data segment
488
+ # end
489
+ #
490
+ # The full list of options are listed in the documentation for its class method counter part, S3Object::value.
491
+ def value(options = {}, &block)
492
+ if options.is_a?(Hash)
493
+ reload = !options.empty?
494
+ else
495
+ reload = options
496
+ options = {}
497
+ end
498
+ expirable_memoize(reload) do
499
+ self.class.stream(key, bucket.name, options, &block)
500
+ end
501
+ end
502
+
503
+ # Interface to information about the current object. Information is read only, though some of its data
504
+ # can be modified through specific methods, such as content_type and content_type=.
505
+ #
506
+ # pp some_object.about
507
+ # {"last-modified" => "Sat, 28 Oct 2006 21:29:26 GMT",
508
+ # "x-amz-id-2" => "LdcQRk5qLwxJQiZ8OH50HhoyKuqyWoJ67B6i+rOE5MxpjJTWh1kCkL+I0NQzbVQn",
509
+ # "content-type" => "binary/octet-stream",
510
+ # "etag" => "\"dc629038ffc674bee6f62eb68454ff3a\"",
511
+ # "date" => "Sat, 28 Oct 2006 21:30:41 GMT",
512
+ # "x-amz-request-id" => "B7BC68F55495B1C8",
513
+ # "server" => "AmazonS3",
514
+ # "content-length" => "3418766"}
515
+ #
516
+ # some_object.content_type
517
+ # # => "binary/octet-stream"
518
+ # some_object.content_type = 'audio/mpeg'
519
+ # some_object.content_type
520
+ # # => 'audio/mpeg'
521
+ # some_object.store
522
+ def about
523
+ stored? ? self.class.about(key, bucket.name) : About.new
524
+ end
525
+ memoized :about
526
+
527
+ # Interface to viewing and editing metadata for the current object. To be treated like a Hash.
528
+ #
529
+ # some_object.metadata
530
+ # # => {}
531
+ # some_object.metadata[:author] = 'Dave Thomas'
532
+ # some_object.metadata
533
+ # # => {"x-amz-meta-author" => "Dave Thomas"}
534
+ # some_object.metadata[:author]
535
+ # # => "Dave Thomas"
536
+ def metadata
537
+ about.metadata
538
+ end
539
+ memoized :metadata
540
+
541
+ # Saves the current object with the specified <tt>options</tt>. Valid options are listed in the documentation for S3Object::store.
542
+ def store(options = {})
543
+ raise DeletedObject if frozen?
544
+ options = about.to_headers.merge(options) if stored?
545
+ response = self.class.store(key, value, bucket.name, options)
546
+ bucket.update(:stored, self)
547
+ response.success?
548
+ end
549
+ alias_method :create, :store
550
+ alias_method :save, :store
551
+
552
+ # Deletes the current object. Trying to save an object after it has been deleted with
553
+ # raise a DeletedObject exception.
554
+ def delete
555
+ bucket.update(:deleted, self)
556
+ freeze
557
+ self.class.delete(key, bucket.name)
558
+ end
559
+
560
+ # Copies current object to a new bucket
561
+ def copy_to_bucket(dest_bucket)
562
+ copy(nil, :dest_bucket => dest_bucket, :copy_acl => true)
563
+ end
564
+
565
+ # Copies the current object, given it the name <tt>copy_name</tt>.
566
+ def copy(copy_name=nil, options = {})
567
+ self.class.copy(key, copy_name, bucket.name, options)
568
+ end
569
+
570
+ # Rename the current object. Keep in mind that due to limitations in S3's API, this operation requires
571
+ # retransmitting the entire object to S3.
572
+ def rename(to, options = {})
573
+ self.class.rename(key, to, bucket.name, options)
574
+ end
575
+
576
+ def etag(reload = false)
577
+ return nil unless stored?
578
+ expirable_memoize(reload) do
579
+ reload ? about(reload)['etag'][1...-1] : attributes['e_tag'][1...-1]
580
+ end
581
+ end
582
+
583
+ # Returns the owner of the current object.
584
+ def owner
585
+ Owner.new(attributes['owner'])
586
+ end
587
+ memoized :owner
588
+
589
+ # Generates an authenticated url for the current object. Accepts the same options as its class method
590
+ # counter part S3Object.url_for.
591
+ def url(options = {})
592
+ self.class.url_for(key, bucket.name, options)
593
+ end
594
+
595
+ # Returns true if the current object has been stored on S3 yet.
596
+ def stored?
597
+ !attributes['e_tag'].nil?
598
+ end
599
+
600
+ def ==(s3object) #:nodoc:
601
+ path == s3object.path
602
+ end
603
+
604
+ def path #:nodoc:
605
+ self.class.path!(
606
+ belongs_to_bucket? ? bucket.name : '(no bucket)',
607
+ key_set? ? key : '(no key)'
608
+ )
609
+ end
610
+
611
+ # Don't dump binary data :)
612
+ def inspect #:nodoc:
613
+ "#<%s:0x%s '%s'>" % [self.class, object_id, path]
614
+ end
615
+
616
+ private
617
+ def proxiable_attribute?(name)
618
+ valid_header_settings.include?(name)
619
+ end
620
+
621
+ def valid_header_settings
622
+ %w(cache_control content_type content_length content_md5 content_disposition content_encoding expires)
623
+ end
624
+ end
625
+ end
626
+ end