revans_right_aws 2.0.1

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 (52) hide show
  1. data/.gemtest +0 -0
  2. data/History.txt +284 -0
  3. data/Manifest.txt +50 -0
  4. data/README.txt +167 -0
  5. data/Rakefile +110 -0
  6. data/lib/acf/right_acf_interface.rb +485 -0
  7. data/lib/acf/right_acf_origin_access_identities.rb +230 -0
  8. data/lib/acf/right_acf_streaming_interface.rb +236 -0
  9. data/lib/acw/right_acw_interface.rb +249 -0
  10. data/lib/as/right_as_interface.rb +699 -0
  11. data/lib/awsbase/benchmark_fix.rb +39 -0
  12. data/lib/awsbase/right_awsbase.rb +978 -0
  13. data/lib/awsbase/support.rb +115 -0
  14. data/lib/ec2/right_ec2.rb +395 -0
  15. data/lib/ec2/right_ec2_ebs.rb +452 -0
  16. data/lib/ec2/right_ec2_images.rb +373 -0
  17. data/lib/ec2/right_ec2_instances.rb +755 -0
  18. data/lib/ec2/right_ec2_monitoring.rb +70 -0
  19. data/lib/ec2/right_ec2_reserved_instances.rb +170 -0
  20. data/lib/ec2/right_ec2_security_groups.rb +277 -0
  21. data/lib/ec2/right_ec2_spot_instances.rb +399 -0
  22. data/lib/ec2/right_ec2_vpc.rb +571 -0
  23. data/lib/elb/right_elb_interface.rb +496 -0
  24. data/lib/rds/right_rds_interface.rb +998 -0
  25. data/lib/right_aws.rb +83 -0
  26. data/lib/s3/right_s3.rb +1126 -0
  27. data/lib/s3/right_s3_interface.rb +1199 -0
  28. data/lib/sdb/active_sdb.rb +1122 -0
  29. data/lib/sdb/right_sdb_interface.rb +721 -0
  30. data/lib/sqs/right_sqs.rb +388 -0
  31. data/lib/sqs/right_sqs_gen2.rb +343 -0
  32. data/lib/sqs/right_sqs_gen2_interface.rb +524 -0
  33. data/lib/sqs/right_sqs_interface.rb +594 -0
  34. data/test/acf/test_helper.rb +2 -0
  35. data/test/acf/test_right_acf.rb +138 -0
  36. data/test/ec2/test_helper.rb +2 -0
  37. data/test/ec2/test_right_ec2.rb +108 -0
  38. data/test/http_connection.rb +87 -0
  39. data/test/rds/test_helper.rb +2 -0
  40. data/test/rds/test_right_rds.rb +120 -0
  41. data/test/s3/test_helper.rb +2 -0
  42. data/test/s3/test_right_s3.rb +421 -0
  43. data/test/s3/test_right_s3_stubbed.rb +97 -0
  44. data/test/sdb/test_active_sdb.rb +357 -0
  45. data/test/sdb/test_helper.rb +3 -0
  46. data/test/sdb/test_right_sdb.rb +253 -0
  47. data/test/sqs/test_helper.rb +2 -0
  48. data/test/sqs/test_right_sqs.rb +291 -0
  49. data/test/sqs/test_right_sqs_gen2.rb +264 -0
  50. data/test/test_credentials.rb +37 -0
  51. data/test/ts_right_aws.rb +14 -0
  52. metadata +169 -0
@@ -0,0 +1,83 @@
1
+ #
2
+ # Copyright (c) 2007-2008 RightScale Inc
3
+ #
4
+ # Permission is hereby granted, free of charge, to any person obtaining
5
+ # a copy of this software and associated documentation files (the
6
+ # "Software"), to deal in the Software without restriction, including
7
+ # without limitation the rights to use, copy, modify, merge, publish,
8
+ # distribute, sublicense, and/or sell copies of the Software, and to
9
+ # permit persons to whom the Software is furnished to do so, subject to
10
+ # the following conditions:
11
+ #
12
+ # The above copyright notice and this permission notice shall be
13
+ # included in all copies or substantial portions of the Software.
14
+ #
15
+ # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16
+ # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17
+ # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18
+ # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
19
+ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
20
+ # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
21
+ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22
+ #
23
+
24
+ require 'benchmark'
25
+ require 'net/https'
26
+ require 'uri'
27
+ require 'time'
28
+ require "cgi"
29
+ require "base64"
30
+ require "rexml/document"
31
+ require "openssl"
32
+ require "digest/sha1"
33
+
34
+ require 'rubygems'
35
+ require 'right_http_connection'
36
+
37
+ $:.unshift(File.dirname(__FILE__))
38
+ require 'awsbase/benchmark_fix'
39
+ require 'awsbase/support'
40
+ require 'awsbase/right_awsbase'
41
+ require 'ec2/right_ec2'
42
+ require 'ec2/right_ec2_images'
43
+ require 'ec2/right_ec2_instances'
44
+ require 'ec2/right_ec2_security_groups'
45
+ require 'ec2/right_ec2_spot_instances'
46
+ require 'ec2/right_ec2_ebs'
47
+ require 'ec2/right_ec2_reserved_instances'
48
+ require 'ec2/right_ec2_vpc'
49
+ require 'ec2/right_ec2_monitoring'
50
+ require 'elb/right_elb_interface'
51
+ require 'acw/right_acw_interface'
52
+ require 'as/right_as_interface'
53
+ require 's3/right_s3_interface'
54
+ require 's3/right_s3'
55
+ require 'sqs/right_sqs_interface'
56
+ require 'sqs/right_sqs'
57
+ require 'sqs/right_sqs_gen2_interface'
58
+ require 'sqs/right_sqs_gen2'
59
+ require 'sdb/right_sdb_interface'
60
+ require 'acf/right_acf_interface'
61
+ require 'acf/right_acf_streaming_interface'
62
+ require 'acf/right_acf_origin_access_identities'
63
+ require 'rds/right_rds_interface'
64
+
65
+
66
+ module RightAws #:nodoc:
67
+ module VERSION #:nodoc:
68
+ MAJOR = 2 unless defined?(MAJOR)
69
+ MINOR = 0 unless defined?(MINOR)
70
+ TINY = 1 unless defined?(TINY)
71
+
72
+ STRING = [MAJOR, MINOR, TINY].join('.') unless defined?(STRING)
73
+ end
74
+ end
75
+
76
+ #-
77
+
78
+ # We also want everything available in the Rightscale namespace for backward
79
+ # compatibility reasons.
80
+ module Rightscale #:nodoc:
81
+ include RightAws
82
+ extend RightAws
83
+ end
@@ -0,0 +1,1126 @@
1
+ #
2
+ # Copyright (c) 2007-2008 RightScale Inc
3
+ #
4
+ # Permission is hereby granted, free of charge, to any person obtaining
5
+ # a copy of this software and associated documentation files (the
6
+ # "Software"), to deal in the Software without restriction, including
7
+ # without limitation the rights to use, copy, modify, merge, publish,
8
+ # distribute, sublicense, and/or sell copies of the Software, and to
9
+ # permit persons to whom the Software is furnished to do so, subject to
10
+ # the following conditions:
11
+ #
12
+ # The above copyright notice and this permission notice shall be
13
+ # included in all copies or substantial portions of the Software.
14
+ #
15
+ # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16
+ # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17
+ # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18
+ # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
19
+ # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
20
+ # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
21
+ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22
+ #
23
+
24
+ module RightAws
25
+
26
+ # = RightAws::S3 -- RightScale's Amazon S3 interface
27
+ # The RightAws::S3 class provides a complete interface to Amazon's Simple
28
+ # Storage Service.
29
+ # For explanations of the semantics
30
+ # of each call, please refer to Amazon's documentation at
31
+ # http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=48
32
+ #
33
+ # See examples below for the bucket and buckets methods.
34
+ #
35
+ # Error handling: all operations raise an RightAws::AwsError in case
36
+ # of problems. Note that transient errors are automatically retried.
37
+ #
38
+ # It is a good way to use domain naming style getting a name for the buckets.
39
+ # See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingBucket.html
40
+ # about the naming convention for the buckets. This case they can be accessed using a virtual domains.
41
+ #
42
+ # Let assume you have 3 buckets: 'awesome-bucket', 'awesome_bucket' and 'AWEsomE-bucket'.
43
+ # The first ones objects can be accessed as: http:// awesome-bucket.s3.amazonaws.com/key/object
44
+ #
45
+ # But the rest have to be accessed as:
46
+ # http:// s3.amazonaws.com/awesome_bucket/key/object and http:// s3.amazonaws.com/AWEsomE-bucket/key/object
47
+ #
48
+ # See: http://docs.amazonwebservices.com/AmazonS3/2006-03-01/VirtualHosting.html for better explanation.
49
+ #
50
+ class S3
51
+ attr_reader :interface
52
+
53
+ # Create a new handle to an S3 account. All handles share the same per process or per thread
54
+ # HTTP connection to Amazon S3. Each handle is for a specific account.
55
+ # The +params+ are passed through as-is to RightAws::S3Interface.new
56
+ #
57
+ # Params is a hash:
58
+ #
59
+ # {:server => 's3.amazonaws.com' # Amazon service host: 's3.amazonaws.com'(default)
60
+ # :port => 443 # Amazon service port: 80 or 443(default)
61
+ # :protocol => 'https' # Amazon service protocol: 'http' or 'https'(default)
62
+ # :multi_thread => true|false # Multi-threaded (connection per each thread): true or false(default)
63
+ # :logger => Logger Object} # Logger instance: logs to STDOUT if omitted }
64
+ def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
65
+ @interface = S3Interface.new(aws_access_key_id, aws_secret_access_key, params)
66
+ end
67
+
68
+ # Retrieve a list of buckets.
69
+ # Returns an array of RightAws::S3::Bucket instances.
70
+ # # Create handle to S3 account
71
+ # s3 = RightAws::S3.new(aws_access_key_id, aws_secret_access_key)
72
+ # my_buckets_names = s3.buckets.map{|b| b.name}
73
+ # puts "Buckets on S3: #{my_bucket_names.join(', ')}"
74
+ def buckets
75
+ @interface.list_all_my_buckets.map! do |entry|
76
+ owner = Owner.new(entry[:owner_id], entry[:owner_display_name])
77
+ Bucket.new(self, entry[:name], entry[:creation_date], owner)
78
+ end
79
+ end
80
+
81
+ # Retrieve an individual bucket.
82
+ # If the bucket does not exist and +create+ is set, a new bucket
83
+ # is created on S3. Launching this method with +create+=+true+ may
84
+ # affect on the bucket's ACL if the bucket already exists.
85
+ # Returns a RightAws::S3::Bucket instance or +nil+ if the bucket does not exist
86
+ # and +create+ is not set.
87
+ #
88
+ # s3 = RightAws::S3.new(aws_access_key_id, aws_secret_access_key)
89
+ # bucket1 = s3.bucket('my_awesome_bucket_1')
90
+ # bucket1.keys #=> exception here if the bucket does not exists
91
+ # ...
92
+ # bucket2 = s3.bucket('my_awesome_bucket_2', true)
93
+ # bucket2.keys #=> list of keys
94
+ # # create a bucket at the European location with public read access
95
+ # bucket3 = s3.bucket('my-awesome-bucket-3', true, 'public-read', :location => :eu)
96
+ #
97
+ # see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html
98
+ # (section: Canned Access Policies)
99
+ #
100
+ def bucket(name, create=false, perms=nil, headers={})
101
+ headers['x-amz-acl'] = perms if perms
102
+ @interface.create_bucket(name, headers) if create
103
+ buckets.each { |bucket| return bucket if bucket.name == name }
104
+ nil
105
+ end
106
+
107
+
108
+ class Bucket
109
+ attr_reader :s3, :name, :owner, :creation_date
110
+
111
+ # Create a Bucket instance.
112
+ # If the bucket does not exist and +create+ is set, a new bucket
113
+ # is created on S3. Launching this method with +create+=+true+ may
114
+ # affect on the bucket's ACL if the bucket already exists.
115
+ # Returns Bucket instance or +nil+ if the bucket does not exist
116
+ # and +create+ is not set.
117
+ #
118
+ # s3 = RightAws::S3.new(aws_access_key_id, aws_secret_access_key)
119
+ # ...
120
+ # bucket1 = RightAws::S3::Bucket.create(s3, 'my_awesome_bucket_1')
121
+ # bucket1.keys #=> exception here if the bucket does not exists
122
+ # ...
123
+ # bucket2 = RightAws::S3::Bucket.create(s3, 'my_awesome_bucket_2', true)
124
+ # bucket2.keys #=> list of keys
125
+ # # create a bucket at the European location with public read access
126
+ # bucket3 = RightAws::S3::Bucket.create(s3,'my-awesome-bucket-3', true, 'public-read', :location => :eu)
127
+ #
128
+ # see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html
129
+ # (section: Canned Access Policies)
130
+ #
131
+ def self.create(s3, name, create=false, perms=nil, headers={})
132
+ s3.bucket(name, create, perms, headers)
133
+ end
134
+
135
+
136
+ # Create a bucket instance. In normal use this method should
137
+ # not be called directly.
138
+ # Use RightAws::S3::Bucket.create or RightAws::S3.bucket instead.
139
+ def initialize(s3, name, creation_date=nil, owner=nil)
140
+ @s3 = s3
141
+ @name = name
142
+ @owner = owner
143
+ @creation_date = creation_date
144
+ if @creation_date && !@creation_date.is_a?(Time)
145
+ @creation_date = Time.parse(@creation_date)
146
+ end
147
+ end
148
+
149
+ # Return bucket name as a String.
150
+ #
151
+ # bucket = RightAws::S3.bucket('my_awesome_bucket')
152
+ # puts bucket #=> 'my_awesome_bucket'
153
+ #
154
+ def to_s
155
+ @name.to_s
156
+ end
157
+ alias_method :full_name, :to_s
158
+
159
+ # Return a public link to bucket.
160
+ #
161
+ # bucket.public_link #=> 'https://s3.amazonaws.com:443/my_awesome_bucket'
162
+ #
163
+ def public_link
164
+ params = @s3.interface.params
165
+ "#{params[:protocol]}://#{params[:server]}:#{params[:port]}/#{full_name}"
166
+ end
167
+
168
+ # Returns the bucket location
169
+ def location
170
+ @location ||= @s3.interface.bucket_location(@name)
171
+ end
172
+
173
+ # Retrieves the logging configuration for a bucket.
174
+ # Returns a hash of {:enabled, :targetbucket, :targetprefix}
175
+ #
176
+ # bucket.logging_info()
177
+ # => {:enabled=>true, :targetbucket=>"mylogbucket", :targetprefix=>"loggylogs/"}
178
+ def logging_info
179
+ @s3.interface.get_logging_parse(:bucket => @name)
180
+ end
181
+
182
+ # Enables S3 server access logging on a bucket. The target bucket must have been properly configured to receive server
183
+ # access logs.
184
+ # Params:
185
+ # :targetbucket - either the target bucket object or the name of the target bucket
186
+ # :targetprefix - the prefix under which all logs should be stored
187
+ #
188
+ # bucket.enable_logging(:targetbucket=>"mylogbucket", :targetprefix=>"loggylogs/")
189
+ # => true
190
+ def enable_logging(params)
191
+ AwsUtils.mandatory_arguments([:targetbucket, :targetprefix], params)
192
+ AwsUtils.allow_only([:targetbucket, :targetprefix], params)
193
+ xmldoc = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><BucketLoggingStatus xmlns=\"http://doc.s3.amazonaws.com/2006-03-01\"><LoggingEnabled><TargetBucket>#{params[:targetbucket]}</TargetBucket><TargetPrefix>#{params[:targetprefix]}</TargetPrefix></LoggingEnabled></BucketLoggingStatus>"
194
+ @s3.interface.put_logging(:bucket => @name, :xmldoc => xmldoc)
195
+ end
196
+
197
+ # Disables S3 server access logging on a bucket. Takes no arguments.
198
+ def disable_logging
199
+ xmldoc = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><BucketLoggingStatus xmlns=\"http://doc.s3.amazonaws.com/2006-03-01\"></BucketLoggingStatus>"
200
+ @s3.interface.put_logging(:bucket => @name, :xmldoc => xmldoc)
201
+ end
202
+
203
+ # Retrieve a group of keys from Amazon.
204
+ # +options+ is a hash: { 'prefix'=>'', 'marker'=>'', 'max-keys'=>5, 'delimiter'=>'' }).
205
+ # Retrieves meta-headers information if +head+ it +true+.
206
+ # Returns an array of Key instances.
207
+ #
208
+ # bucket.keys #=> # returns all keys from bucket
209
+ # bucket.keys('prefix' => 'logs') #=> # returns all keys that starts with 'logs'
210
+ #
211
+ def keys(options={}, head=false)
212
+ keys_and_service(options, head)[0]
213
+ end
214
+
215
+ # Same as +keys+ method but return an array of [keys, service_data].
216
+ # where +service_data+ is a hash with additional output information.
217
+ #
218
+ # keys, service = bucket.keys_and_service({'max-keys'=> 2, 'prefix' => 'logs'})
219
+ # p keys #=> # 2 keys array
220
+ # p service #=> {"max-keys"=>"2", "prefix"=>"logs", "name"=>"my_awesome_bucket", "marker"=>"", "is_truncated"=>true}
221
+ #
222
+ def keys_and_service(options={}, head=false)
223
+ opt = {}; options.each{ |key, value| opt[key.to_s] = value }
224
+ service_data = {}
225
+ thislist = {}
226
+ list = []
227
+ @s3.interface.incrementally_list_bucket(@name, opt) do |thislist|
228
+ thislist[:contents].each do |entry|
229
+ owner = Owner.new(entry[:owner_id], entry[:owner_display_name])
230
+ key = Key.new(self, entry[:key], nil, {}, {}, entry[:last_modified], entry[:e_tag], entry[:size], entry[:storage_class], owner)
231
+ key.head if head
232
+ list << key
233
+ end
234
+ end
235
+ thislist.each_key do |key|
236
+ service_data[key] = thislist[key] unless (key == :contents || key == :common_prefixes)
237
+ end
238
+ [list, service_data]
239
+ end
240
+
241
+ # Retrieve key information from Amazon.
242
+ # The +key_name+ is a +String+ or Key instance.
243
+ # Retrieves meta-header information if +head+ is +true+.
244
+ # Returns new Key instance.
245
+ #
246
+ # key = bucket.key('logs/today/1.log', true) #=> #<RightAws::S3::Key:0xb7b1e240 ... >
247
+ # # is the same as:
248
+ # key = RightAws::S3::Key.create(bucket, 'logs/today/1.log')
249
+ # key.head
250
+ #
251
+ def key(key_name, head=false)
252
+ raise 'Key name can not be empty.' if key_name.blank?
253
+ key_instance = nil
254
+ # if this key exists - find it ....
255
+ keys({'prefix'=>key_name}, head).each do |key|
256
+ if key.name == key_name.to_s
257
+ key_instance = key
258
+ break
259
+ end
260
+ end
261
+ # .... else this key is unknown
262
+ unless key_instance
263
+ key_instance = Key.create(self, key_name.to_s)
264
+ end
265
+ key_instance
266
+ end
267
+
268
+ # Store object data.
269
+ # The +key+ is a +String+ or Key instance.
270
+ # Returns +true+.
271
+ #
272
+ # bucket.put('logs/today/1.log', 'Olala!') #=> true
273
+ #
274
+ def put(key, data=nil, meta_headers={}, perms=nil, headers={})
275
+ key = Key.create(self, key.to_s, data, meta_headers) unless key.is_a?(Key)
276
+ key.put(data, perms, headers)
277
+ end
278
+
279
+ # Retrieve object data from Amazon.
280
+ # The +key+ is a +String+ or Key.
281
+ # Returns Key instance.
282
+ #
283
+ # key = bucket.get('logs/today/1.log') #=>
284
+ # puts key.data #=> 'sasfasfasdf'
285
+ #
286
+ def get(key, headers={})
287
+ key = Key.create(self, key.to_s) unless key.is_a?(Key)
288
+ key.get(headers)
289
+ end
290
+
291
+ # Rename object. Returns RightAws::S3::Key instance.
292
+ #
293
+ # new_key = bucket.rename_key('logs/today/1.log','logs/today/2.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... >
294
+ # puts key.name #=> 'logs/today/2.log'
295
+ # key.exists? #=> true
296
+ #
297
+ def rename_key(old_key_or_name, new_name)
298
+ old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key)
299
+ old_key_or_name.rename(new_name)
300
+ old_key_or_name
301
+ end
302
+
303
+ # Create an object copy. Returns a destination RightAws::S3::Key instance.
304
+ #
305
+ # new_key = bucket.copy_key('logs/today/1.log','logs/today/2.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... >
306
+ # puts key.name #=> 'logs/today/2.log'
307
+ # key.exists? #=> true
308
+ #
309
+ def copy_key(old_key_or_name, new_key_or_name)
310
+ old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key)
311
+ old_key_or_name.copy(new_key_or_name)
312
+ end
313
+
314
+ # Move an object to other location. Returns a destination RightAws::S3::Key instance.
315
+ #
316
+ # new_key = bucket.copy_key('logs/today/1.log','logs/today/2.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... >
317
+ # puts key.name #=> 'logs/today/2.log'
318
+ # key.exists? #=> true
319
+ #
320
+ def move_key(old_key_or_name, new_key_or_name)
321
+ old_key_or_name = Key.create(self, old_key_or_name.to_s) unless old_key_or_name.is_a?(Key)
322
+ old_key_or_name.move(new_key_or_name)
323
+ end
324
+
325
+ # Remove all keys from a bucket.
326
+ # Returns +true+.
327
+ #
328
+ # bucket.clear #=> true
329
+ #
330
+ def clear
331
+ @s3.interface.clear_bucket(@name)
332
+ end
333
+
334
+ # Delete all keys where the 'folder_key' can be interpreted
335
+ # as a 'folder' name.
336
+ # Returns an array of string keys that have been deleted.
337
+ #
338
+ # bucket.keys.map{|key| key.name}.join(', ') #=> 'test, test/2/34, test/3, test1, test1/logs'
339
+ # bucket.delete_folder('test') #=> ['test','test/2/34','test/3']
340
+ #
341
+ def delete_folder(folder, separator='/')
342
+ @s3.interface.delete_folder(@name, folder, separator)
343
+ end
344
+
345
+ # Delete a bucket. Bucket must be empty.
346
+ # If +force+ is set, clears and deletes the bucket.
347
+ # Returns +true+.
348
+ #
349
+ # bucket.delete(true) #=> true
350
+ #
351
+ def delete(force=false)
352
+ force ? @s3.interface.force_delete_bucket(@name) : @s3.interface.delete_bucket(@name)
353
+ end
354
+
355
+ # Return a list of grantees.
356
+ #
357
+ def grantees
358
+ Grantee::grantees(self)
359
+ end
360
+
361
+ end
362
+
363
+
364
+ class Key
365
+ attr_reader :bucket, :name, :last_modified, :e_tag, :size, :storage_class, :owner
366
+ attr_accessor :headers, :meta_headers
367
+ attr_writer :data
368
+
369
+ # Separate Amazon meta headers from other headers
370
+ def self.split_meta(headers) #:nodoc:
371
+ hash = headers.dup
372
+ meta = {}
373
+ hash.each do |key, value|
374
+ if key[/^#{S3Interface::AMAZON_METADATA_PREFIX}/]
375
+ meta[key.gsub(S3Interface::AMAZON_METADATA_PREFIX,'')] = value
376
+ hash.delete(key)
377
+ end
378
+ end
379
+ [hash, meta]
380
+ end
381
+
382
+ def self.add_meta_prefix(meta_headers, prefix=S3Interface::AMAZON_METADATA_PREFIX)
383
+ meta = {}
384
+ meta_headers.each do |meta_header, value|
385
+ if meta_header[/#{prefix}/]
386
+ meta[meta_header] = value
387
+ else
388
+ meta["#{S3Interface::AMAZON_METADATA_PREFIX}#{meta_header}"] = value
389
+ end
390
+ end
391
+ meta
392
+ end
393
+
394
+
395
+ # Create a new Key instance, but do not create the actual key.
396
+ # The +name+ is a +String+.
397
+ # Returns a new Key instance.
398
+ #
399
+ # key = RightAws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... >
400
+ # key.exists? #=> true | false
401
+ # key.put('Woohoo!') #=> true
402
+ # key.exists? #=> true
403
+ #
404
+ def self.create(bucket, name, data=nil, meta_headers={})
405
+ new(bucket, name, data, {}, meta_headers)
406
+ end
407
+
408
+ # Create a new Key instance, but do not create the actual key.
409
+ # In normal use this method should not be called directly.
410
+ # Use RightAws::S3::Key.create or bucket.key() instead.
411
+ #
412
+ def initialize(bucket, name, data=nil, headers={}, meta_headers={},
413
+ last_modified=nil, e_tag=nil, size=nil, storage_class=nil, owner=nil)
414
+ raise 'Bucket must be a Bucket instance.' unless bucket.is_a?(Bucket)
415
+ @bucket = bucket
416
+ @name = name
417
+ @data = data
418
+ @e_tag = e_tag
419
+ @size = size.to_i
420
+ @storage_class = storage_class
421
+ @owner = owner
422
+ @last_modified = last_modified
423
+ if @last_modified && !@last_modified.is_a?(Time)
424
+ @last_modified = Time.parse(@last_modified)
425
+ end
426
+ @headers, @meta_headers = self.class.split_meta(headers)
427
+ @meta_headers.merge!(meta_headers)
428
+ end
429
+
430
+ # Return key name as a String.
431
+ #
432
+ # key = RightAws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... >
433
+ # puts key #=> 'logs/today/1.log'
434
+ #
435
+ def to_s
436
+ @name.to_s
437
+ end
438
+
439
+ # Return the full S3 path to this key (bucket/key).
440
+ #
441
+ # key.full_name #=> 'my_awesome_bucket/cool_key'
442
+ #
443
+ def full_name(separator='/')
444
+ "#{@bucket.to_s}#{separator}#{@name}"
445
+ end
446
+
447
+ # Return a public link to a key.
448
+ #
449
+ # key.public_link #=> 'https://s3.amazonaws.com:443/my_awesome_bucket/cool_key'
450
+ #
451
+ def public_link
452
+ params = @bucket.s3.interface.params
453
+ "#{params[:protocol]}://#{params[:server]}:#{params[:port]}/#{full_name('/')}"
454
+ end
455
+
456
+ # Return Key data. Retrieve this data from Amazon if it is the first time call.
457
+ # TODO TRB 6/19/07 What does the above mean? Clarify.
458
+ #
459
+ def data
460
+ get if !@data and exists?
461
+ @data
462
+ end
463
+
464
+ # Getter for the 'content-type' metadata
465
+ def content_type
466
+ @headers['content-type'] if @headers
467
+ end
468
+
469
+ # Helper to get and URI-decode a header metadata.
470
+ # Metadata have to be HTTP encoded (rfc2616) as we use the Amazon S3 REST api
471
+ # see http://docs.amazonwebservices.com/AmazonS3/latest/index.html?UsingMetadata.html
472
+ def decoded_meta_headers(key = nil)
473
+ if key
474
+ # Get one metadata value by its key
475
+ URI.decode(@meta_headers[key.to_s])
476
+ else
477
+ # Get a hash of all metadata with a decoded value
478
+ @decoded_meta_headers ||= begin
479
+ metadata = {}
480
+ @meta_headers.each do |key, value|
481
+ metadata[key.to_sym] = URI.decode(value)
482
+ end
483
+ metadata
484
+ end
485
+ end
486
+ end
487
+
488
+ # Retrieve object data and attributes from Amazon.
489
+ # Returns a +String+.
490
+ #
491
+ def get(headers={})
492
+ response = @bucket.s3.interface.get(@bucket.name, @name, headers)
493
+ @data = response[:object]
494
+ @headers, @meta_headers = self.class.split_meta(response[:headers])
495
+ refresh(false)
496
+ @data
497
+ end
498
+
499
+ # Store object data on S3.
500
+ # Parameter +data+ is a +String+ or S3Object instance.
501
+ # Returns +true+.
502
+ #
503
+ # key = RightAws::S3::Key.create(bucket, 'logs/today/1.log')
504
+ # key.data = 'Qwerty'
505
+ # key.put #=> true
506
+ # ...
507
+ # key.put('Olala!') #=> true
508
+ #
509
+ def put(data=nil, perms=nil, headers={})
510
+ headers['x-amz-acl'] = perms if perms
511
+ @data = data || @data
512
+ meta = self.class.add_meta_prefix(@meta_headers)
513
+ @bucket.s3.interface.put(@bucket.name, @name, @data, meta.merge(headers))
514
+ end
515
+
516
+ # Rename an object. Returns new object name.
517
+ #
518
+ # key = RightAws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... >
519
+ # key.rename('logs/today/2.log') #=> 'logs/today/2.log'
520
+ # puts key.name #=> 'logs/today/2.log'
521
+ # key.exists? #=> true
522
+ #
523
+ def rename(new_name)
524
+ @bucket.s3.interface.rename(@bucket.name, @name, new_name)
525
+ @name = new_name
526
+ end
527
+
528
+ # Create an object copy. Returns a destination RightAws::S3::Key instance.
529
+ #
530
+ # # Key instance as destination
531
+ # key1 = RightAws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... >
532
+ # key2 = RightAws::S3::Key.create(bucket, 'logs/today/2.log') #=> #<RightAws::S3::Key:0xb7b5e240 ... >
533
+ # key1.put('Olala!') #=> true
534
+ # key1.copy(key2) #=> #<RightAws::S3::Key:0xb7b5e240 ... >
535
+ # key1.exists? #=> true
536
+ # key2.exists? #=> true
537
+ # puts key2.data #=> 'Olala!'
538
+ #
539
+ # # String as destination
540
+ # key = RightAws::S3::Key.create(bucket, 'logs/today/777.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... >
541
+ # key.put('Olala!') #=> true
542
+ # new_key = key.copy('logs/today/888.log') #=> #<RightAws::S3::Key:0xb7b5e240 ... >
543
+ # key.exists? #=> true
544
+ # new_key.exists? #=> true
545
+ #
546
+ def copy(new_key_or_name)
547
+ new_key_or_name = Key.create(@bucket, new_key_or_name.to_s) unless new_key_or_name.is_a?(Key)
548
+ @bucket.s3.interface.copy(@bucket.name, @name, new_key_or_name.bucket.name, new_key_or_name.name)
549
+ new_key_or_name
550
+ end
551
+
552
+ # Move an object to other location. Returns a destination RightAws::S3::Key instance.
553
+ #
554
+ # # Key instance as destination
555
+ # key1 = RightAws::S3::Key.create(bucket, 'logs/today/1.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... >
556
+ # key2 = RightAws::S3::Key.create(bucket, 'logs/today/2.log') #=> #<RightAws::S3::Key:0xb7b5e240 ... >
557
+ # key1.put('Olala!') #=> true
558
+ # key1.move(key2) #=> #<RightAws::S3::Key:0xb7b5e240 ... >
559
+ # key1.exists? #=> false
560
+ # key2.exists? #=> true
561
+ # puts key2.data #=> 'Olala!'
562
+ #
563
+ # # String as destination
564
+ # key = RightAws::S3::Key.create(bucket, 'logs/today/777.log') #=> #<RightAws::S3::Key:0xb7b1e240 ... >
565
+ # key.put('Olala!') #=> true
566
+ # new_key = key.move('logs/today/888.log') #=> #<RightAws::S3::Key:0xb7b5e240 ... >
567
+ # key.exists? #=> false
568
+ # new_key.exists? #=> true
569
+ #
570
+ def move(new_key_or_name)
571
+ new_key_or_name = Key.create(@bucket, new_key_or_name.to_s) unless new_key_or_name.is_a?(Key)
572
+ @bucket.s3.interface.move(@bucket.name, @name, new_key_or_name.bucket.name, new_key_or_name.name)
573
+ new_key_or_name
574
+ end
575
+
576
+ # Retrieve key info from bucket and update attributes.
577
+ # Refresh meta-headers (by calling +head+ method) if +head+ is set.
578
+ # Returns +true+ if the key exists in bucket and +false+ otherwise.
579
+ #
580
+ # key = RightAws::S3::Key.create(bucket, 'logs/today/1.log')
581
+ # key.e_tag #=> nil
582
+ # key.meta_headers #=> {}
583
+ # key.refresh #=> true
584
+ # key.e_tag #=> '12345678901234567890bf11094484b6'
585
+ # key.meta_headers #=> {"family"=>"qwerty", "name"=>"asdfg"}
586
+ #
587
+ def refresh(head=true)
588
+ new_key = @bucket.key(self)
589
+ @last_modified = new_key.last_modified
590
+ @e_tag = new_key.e_tag
591
+ @size = new_key.size
592
+ @storage_class = new_key.storage_class
593
+ @owner = new_key.owner
594
+ if @last_modified
595
+ self.head
596
+ true
597
+ else
598
+ @headers = @meta_headers = {}
599
+ false
600
+ end
601
+ end
602
+
603
+ # Updates headers and meta-headers from S3.
604
+ # Returns +true+.
605
+ #
606
+ # key.meta_headers #=> {"family"=>"qwerty"}
607
+ # key.head #=> true
608
+ # key.meta_headers #=> {"family"=>"qwerty", "name"=>"asdfg"}
609
+ #
610
+ def head
611
+ @headers, @meta_headers = self.class.split_meta(@bucket.s3.interface.head(@bucket, @name))
612
+ true
613
+ end
614
+
615
+ # Reload meta-headers only. Returns meta-headers hash.
616
+ #
617
+ # key.reload_meta #=> {"family"=>"qwerty", "name"=>"asdfg"}
618
+ #
619
+ def reload_meta
620
+ @meta_headers = self.class.split_meta(@bucket.s3.interface.head(@bucket, @name)).last
621
+ end
622
+
623
+ # Replace meta-headers by new hash at S3. Returns new meta-headers hash.
624
+ #
625
+ # key.reload_meta #=> {"family"=>"qwerty", "name"=>"asdfg"}
626
+ # key.save_meta #=> {"family"=>"oops", "race" => "troll"}
627
+ # key.reload_meta #=> {"family"=>"oops", "race" => "troll"}
628
+ #
629
+ def save_meta(meta_headers)
630
+ meta = self.class.add_meta_prefix(meta_headers)
631
+ @bucket.s3.interface.copy(@bucket.name, @name, @bucket.name, @name, :replace, meta)
632
+ @meta_headers = self.class.split_meta(meta)[1]
633
+ end
634
+
635
+ # Check for existence of the key in the given bucket.
636
+ # Returns +true+ or +false+.
637
+ #
638
+ # key = RightAws::S3::Key.create(bucket,'logs/today/1.log')
639
+ # key.exists? #=> false
640
+ # key.put('Woohoo!') #=> true
641
+ # key.exists? #=> true
642
+ #
643
+ def exists?
644
+ @bucket.key(self).last_modified ? true : false
645
+ end
646
+
647
+ # Remove key from bucket.
648
+ # Returns +true+.
649
+ #
650
+ # key.delete #=> true
651
+ #
652
+ def delete
653
+ raise 'Key name must be specified.' if @name.blank?
654
+ @bucket.s3.interface.delete(@bucket, @name)
655
+ end
656
+
657
+ # Return a list of grantees.
658
+ #
659
+ def grantees
660
+ Grantee::grantees(self)
661
+ end
662
+
663
+ end
664
+
665
+
666
+ class Owner
667
+ attr_reader :id, :name
668
+
669
+ def initialize(id, name)
670
+ @id = id
671
+ @name = name
672
+ end
673
+
674
+ # Return Owner name as a +String+.
675
+ def to_s
676
+ @name
677
+ end
678
+ end
679
+
680
+
681
+ # There are 2 ways to set permissions for a bucket or key (called a +thing+ below):
682
+ #
683
+ # 1 . Use +perms+ param to set 'Canned Access Policies' when calling the <tt>bucket.create</tt>,
684
+ # <tt>bucket.put</tt> and <tt>key.put</tt> methods.
685
+ # The +perms+ param can take these values: 'private', 'public-read', 'public-read-write' and
686
+ # 'authenticated-read'.
687
+ # (see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html).
688
+ #
689
+ # bucket = s3.bucket('bucket_for_kd_test_13', true, 'public-read')
690
+ # key.put('Woohoo!','public-read-write' )
691
+ #
692
+ # 2 . Use Grantee instances (the permission is a +String+ or an +Array+ of: 'READ', 'WRITE',
693
+ # 'READ_ACP', 'WRITE_ACP', 'FULL_CONTROL'):
694
+ #
695
+ # bucket = s3.bucket('my_awesome_bucket', true)
696
+ # grantee1 = RightAws::S3::Grantee.new(bucket, 'a123b...223c', FULL_CONTROL, :apply)
697
+ # grantee2 = RightAws::S3::Grantee.new(bucket, 'xy3v3...5fhp', [READ, WRITE], :apply)
698
+ #
699
+ # There is only one way to get and to remove permission (via Grantee instances):
700
+ #
701
+ # grantees = bucket.grantees # a list of Grantees that have any access for this bucket
702
+ # grantee1 = RightAws::S3::Grantee.new(bucket, 'a123b...223c')
703
+ # grantee1.perms #=> returns a list of perms for this grantee to that bucket
704
+ # ...
705
+ # grantee1.drop # remove all perms for this grantee
706
+ # grantee2.revoke('WRITE') # revoke write access only
707
+ #
708
+ class Grantee
709
+ # A bucket or a key the grantee has an access to.
710
+ attr_reader :thing
711
+ # Grantee Amazon id.
712
+ attr_reader :id
713
+ # Grantee display name.
714
+ attr_reader :name
715
+ # Array of permissions.
716
+ attr_accessor :perms
717
+
718
+ # Retrieve Owner information and a list of Grantee instances that have
719
+ # a access to this thing (bucket or key).
720
+ #
721
+ # bucket = s3.bucket('my_awesome_bucket', true, 'public-read')
722
+ # ...
723
+ # RightAws::S3::Grantee.owner_and_grantees(bucket) #=> [owner, grantees]
724
+ #
725
+ def self.owner_and_grantees(thing)
726
+ if thing.is_a?(Bucket)
727
+ bucket, key = thing, ''
728
+ else
729
+ bucket, key = thing.bucket, thing
730
+ end
731
+ hash = bucket.s3.interface.get_acl_parse(bucket.to_s, key.to_s)
732
+ owner = Owner.new(hash[:owner][:id], hash[:owner][:display_name])
733
+
734
+ grantees = []
735
+ hash[:grantees].each do |id, params|
736
+ grantees << new(thing, id, params[:permissions], nil, params[:display_name])
737
+ end
738
+ [owner, grantees]
739
+ end
740
+
741
+ # Retrieves a list of Grantees instances that have an access to this thing(bucket or key).
742
+ #
743
+ # bucket = s3.bucket('my_awesome_bucket', true, 'public-read')
744
+ # ...
745
+ # RightAws::S3::Grantee.grantees(bucket) #=> grantees
746
+ #
747
+ def self.grantees(thing)
748
+ owner_and_grantees(thing)[1]
749
+ end
750
+
751
+ def self.put_acl(thing, owner, grantees) #:nodoc:
752
+ if thing.is_a?(Bucket)
753
+ bucket, key = thing, ''
754
+ else
755
+ bucket, key = thing.bucket, thing
756
+ end
757
+ body = "<AccessControlPolicy>" +
758
+ "<Owner>" +
759
+ "<ID>#{owner.id}</ID>" +
760
+ "<DisplayName>#{owner.name}</DisplayName>" +
761
+ "</Owner>" +
762
+ "<AccessControlList>" +
763
+ grantees.map{|grantee| grantee.to_xml}.join +
764
+ "</AccessControlList>" +
765
+ "</AccessControlPolicy>"
766
+ bucket.s3.interface.put_acl(bucket.to_s, key.to_s, body)
767
+ end
768
+
769
+ # Create a new Grantee instance.
770
+ # Grantee +id+ must exist on S3. If +action+ == :refresh, then retrieve
771
+ # permissions from S3 and update @perms. If +action+ == :apply, then apply
772
+ # perms to +thing+ at S3. If +action+ == :apply_and_refresh then it performs.
773
+ # both the actions. This is used for the new grantees that had no perms to
774
+ # this thing before. The default action is :refresh.
775
+ #
776
+ # bucket = s3.bucket('my_awesome_bucket', true, 'public-read')
777
+ # grantee1 = RightAws::S3::Grantee.new(bucket, 'a123b...223c', FULL_CONTROL)
778
+ # ...
779
+ # grantee2 = RightAws::S3::Grantee.new(bucket, 'abcde...asdf', [FULL_CONTROL, READ], :apply)
780
+ # grantee3 = RightAws::S3::Grantee.new(bucket, 'aaaaa...aaaa', 'READ', :apply_and_refresh)
781
+ #
782
+ def initialize(thing, id, perms=[], action=:refresh, name=nil)
783
+ @thing = thing
784
+ @id = id
785
+ @name = name
786
+ @perms = Array(perms)
787
+ case action
788
+ when :apply then apply
789
+ when :refresh then refresh
790
+ when :apply_and_refresh then apply; refresh
791
+ end
792
+ end
793
+
794
+ # Return +true+ if the grantee has any permissions to the thing.
795
+ def exists?
796
+ self.class.grantees(@thing).each do |grantee|
797
+ return true if @id == grantee.id
798
+ end
799
+ false
800
+ end
801
+
802
+ # Return Grantee type (+String+): "Group", "AmazonCustomerByEmail" or "CanonicalUser".
803
+ def type
804
+ case @id
805
+ when /^http:/ then "Group"
806
+ when /@/ then "AmazonCustomerByEmail"
807
+ else "CanonicalUser"
808
+ end
809
+ end
810
+
811
+ # Return a name or an id.
812
+ def to_s
813
+ @name || @id
814
+ end
815
+
816
+ # Add permissions for grantee.
817
+ # Permissions: 'READ', 'WRITE', 'READ_ACP', 'WRITE_ACP', 'FULL_CONTROL'.
818
+ # See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingPermissions.html .
819
+ # Returns +true+.
820
+ #
821
+ # grantee.grant('FULL_CONTROL') #=> true
822
+ # grantee.grant('FULL_CONTROL','WRITE','READ') #=> true
823
+ # grantee.grant(['WRITE_ACP','READ','READ_ACP']) #=> true
824
+ #
825
+ def grant(*permissions)
826
+ permissions.flatten!
827
+ old_perms = @perms.dup
828
+ @perms += permissions
829
+ @perms.uniq!
830
+ return true if @perms == old_perms
831
+ apply
832
+ end
833
+
834
+ # Revoke permissions for grantee.
835
+ # Permissions: 'READ', 'WRITE', 'READ_ACP', 'WRITE_ACP', 'FULL_CONTROL'
836
+ # See http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingPermissions.html .
837
+ # Default value is 'FULL_CONTROL'.
838
+ # Returns +true+.
839
+ #
840
+ # grantee.revoke('READ') #=> true
841
+ # grantee.revoke('FULL_CONTROL','WRITE') #=> true
842
+ # grantee.revoke(['READ_ACP','WRITE_ACP']) #=> true
843
+ #
844
+ def revoke(*permissions)
845
+ permissions.flatten!
846
+ old_perms = @perms.dup
847
+ @perms -= permissions
848
+ @perms.uniq!
849
+ return true if @perms == old_perms
850
+ apply
851
+ end
852
+
853
+ # Revoke all permissions for this grantee.
854
+ # Returns +true+.
855
+ #
856
+ # grantee.drop #=> true
857
+ #
858
+ def drop
859
+ @perms = []
860
+ apply
861
+ end
862
+
863
+ # Refresh grantee perms for its +thing+.
864
+ # Returns +true+ if the grantee has perms for this +thing+ or
865
+ # +false+ otherwise, and updates @perms value as a side-effect.
866
+ #
867
+ # grantee.grant('FULL_CONTROL') #=> true
868
+ # grantee.refresh #=> true
869
+ # grantee.drop #=> true
870
+ # grantee.refresh #=> false
871
+ #
872
+ def refresh
873
+ @perms = []
874
+ self.class.grantees(@thing).each do |grantee|
875
+ if @id == grantee.id
876
+ @name = grantee.name
877
+ @perms = grantee.perms
878
+ return true
879
+ end
880
+ end
881
+ false
882
+ end
883
+
884
+ # Apply current grantee @perms to +thing+. This method is called internally by the +grant+
885
+ # and +revoke+ methods. In normal use this method should not
886
+ # be called directly.
887
+ #
888
+ # grantee.perms = ['FULL_CONTROL']
889
+ # grantee.apply #=> true
890
+ #
891
+ def apply
892
+ @perms.uniq!
893
+ owner, grantees = self.class.owner_and_grantees(@thing)
894
+ # walk through all the grantees and replace the data for the current one and ...
895
+ grantees.map! { |grantee| grantee.id == @id ? self : grantee }
896
+ # ... if this grantee is not known - add this bad boy to a list
897
+ grantees << self unless grantees.include?(self)
898
+ # set permissions
899
+ self.class.put_acl(@thing, owner, grantees)
900
+ end
901
+
902
+ def to_xml # :nodoc:
903
+ id_str = case @id
904
+ when /^http/ then "<URI>#{@id}</URI>"
905
+ when /@/ then "<EmailAddress>#{@id}</EmailAddress>"
906
+ else "<ID>#{@id}</ID>"
907
+ end
908
+ grants = ''
909
+ @perms.each do |perm|
910
+ grants << "<Grant>" +
911
+ "<Grantee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" " +
912
+ "xsi:type=\"#{type}\">#{id_str}</Grantee>" +
913
+ "<Permission>#{perm}</Permission>" +
914
+ "</Grant>"
915
+ end
916
+ grants
917
+ end
918
+
919
+ end
920
+
921
+ end
922
+
923
+ # RightAws::S3Generator and RightAws::S3Generator::Bucket methods:
924
+ #
925
+ # s3g = RightAws::S3Generator.new('1...2', 'nx...Y6') #=> #<RightAws::S3Generator:0xb7b5cc94>
926
+ #
927
+ # # List all buckets(method 'GET'):
928
+ # buckets_list = s3g.buckets #=> 'https://s3.amazonaws.com:443/?Signature=Y...D&Expires=1180941864&AWSAccessKeyId=1...2'
929
+ # # Create bucket link (method 'PUT'):
930
+ # bucket = s3g.bucket('my_awesome_bucket') #=> #<RightAws::S3Generator::Bucket:0xb7bcbda8>
931
+ # link_to_create = bucket.create_link(1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=4...D&Expires=1180942132&AWSAccessKeyId=1...2
932
+ # # ... or:
933
+ # bucket = RightAws::S3Generator::Bucket.create(s3g, 'my_awesome_bucket') #=> #<RightAws::S3Generator::Bucket:0xb7bcbda8>
934
+ # link_to_create = bucket.create_link(1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=4...D&Expires=1180942132&AWSAccessKeyId=1...2
935
+ # # ... or:
936
+ # bucket = RightAws::S3Generator::Bucket.new(s3g, 'my_awesome_bucket') #=> #<RightAws::S3Generator::Bucket:0xb7bcbda8>
937
+ # link_to_create = bucket.create_link(1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=4...D&Expires=1180942132&AWSAccessKeyId=1...2
938
+ # # List bucket(method 'GET'):
939
+ # bucket.keys(1.day) #=> https://s3.amazonaws.com:443/my_awesome_bucket?Signature=i...D&Expires=1180942620&AWSAccessKeyId=1...2
940
+ # # Create/put key (method 'PUT'):
941
+ # bucket.put('my_cool_key') #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=q...D&Expires=1180943094&AWSAccessKeyId=1...2
942
+ # # Get key data (method 'GET'):
943
+ # bucket.get('logs/today/1.log', 1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=h...M%3D&Expires=1180820032&AWSAccessKeyId=1...2
944
+ # # Delete bucket (method 'DELETE'):
945
+ # bucket.delete(2.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=4...D&Expires=1180820032&AWSAccessKeyId=1...2
946
+ #
947
+ # RightAws::S3Generator::Key methods:
948
+ #
949
+ # # Create Key instance:
950
+ # key = RightAws::S3Generator::Key.new(bicket, 'my_cool_key') #=> #<RightAws::S3Generator::Key:0xb7b7394c>
951
+ # # Put key data (method 'PUT'):
952
+ # key.put #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=2...D&Expires=1180943302&AWSAccessKeyId=1...2
953
+ # # Get key data (method 'GET'):
954
+ # key.get #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=a...D&Expires=1180820032&AWSAccessKeyId=1...2
955
+ # # Head key (method 'HEAD'):
956
+ # key.head #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=b...D&Expires=1180820032&AWSAccessKeyId=1...2
957
+ # # Delete key (method 'DELETE'):
958
+ # key.delete #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=x...D&Expires=1180820032&AWSAccessKeyId=1...2
959
+ #
960
+ class S3Generator
961
+ attr_reader :interface
962
+
963
+ def initialize(aws_access_key_id, aws_secret_access_key, params={})
964
+ @interface = S3Interface.new(aws_access_key_id, aws_secret_access_key, params)
965
+ end
966
+
967
+ # Generate link to list all buckets
968
+ #
969
+ # s3.buckets(1.hour)
970
+ #
971
+ def buckets(expires=nil, headers={})
972
+ @interface.list_all_my_buckets_link(expires, headers)
973
+ end
974
+
975
+ # Create new S3LinkBucket instance and generate link to create it at S3.
976
+ #
977
+ # bucket= s3.bucket('my_owesome_bucket')
978
+ #
979
+ def bucket(name, expires=nil, headers={})
980
+ Bucket.create(self, name.to_s)
981
+ end
982
+
983
+ class Bucket
984
+ attr_reader :s3, :name
985
+
986
+ def to_s
987
+ @name
988
+ end
989
+ alias_method :full_name, :to_s
990
+
991
+ # Return a public link to bucket.
992
+ #
993
+ # bucket.public_link #=> 'https://s3.amazonaws.com:443/my_awesome_bucket'
994
+ #
995
+ def public_link
996
+ params = @s3.interface.params
997
+ "#{params[:protocol]}://#{params[:server]}:#{params[:port]}/#{full_name}"
998
+ end
999
+
1000
+ # Create new S3LinkBucket instance and generate creation link for it.
1001
+ def self.create(s3, name, expires=nil, headers={})
1002
+ new(s3, name.to_s)
1003
+ end
1004
+
1005
+ # Create new S3LinkBucket instance.
1006
+ def initialize(s3, name)
1007
+ @s3, @name = s3, name.to_s
1008
+ end
1009
+
1010
+ # Return a link to create this bucket.
1011
+ #
1012
+ def create_link(expires=nil, headers={})
1013
+ @s3.interface.create_bucket_link(@name, expires, headers)
1014
+ end
1015
+
1016
+ # Generate link to list keys.
1017
+ #
1018
+ # bucket.keys
1019
+ # bucket.keys('prefix'=>'logs')
1020
+ #
1021
+ def keys(options=nil, expires=nil, headers={})
1022
+ @s3.interface.list_bucket_link(@name, options, expires, headers)
1023
+ end
1024
+
1025
+ # Return a S3Generator::Key instance.
1026
+ #
1027
+ # bucket.key('my_cool_key').get #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=B...D&Expires=1180820032&AWSAccessKeyId=1...2
1028
+ # bucket.key('my_cool_key').delete #=> https://s3.amazonaws.com:443/my_awesome_bucket/my_cool_key?Signature=B...D&Expires=1180820098&AWSAccessKeyId=1...2
1029
+ #
1030
+ def key(name)
1031
+ Key.new(self, name)
1032
+ end
1033
+
1034
+ # Generates link to PUT key data.
1035
+ #
1036
+ # puts bucket.put('logs/today/1.log', 2.hour)
1037
+ #
1038
+ def put(key, meta_headers={}, expires=nil, headers={})
1039
+ meta = RightAws::S3::Key.add_meta_prefix(meta_headers)
1040
+ @s3.interface.put_link(@name, key.to_s, nil, expires, meta.merge(headers))
1041
+ end
1042
+
1043
+ # Generate link to GET key data.
1044
+ #
1045
+ # bucket.get('logs/today/1.log', 1.hour)
1046
+ #
1047
+ def get(key, expires=nil, headers={})
1048
+ @s3.interface.get_link(@name, key.to_s, expires, headers)
1049
+ end
1050
+
1051
+ # Generate link to delete bucket.
1052
+ #
1053
+ # bucket.delete(2.hour)
1054
+ #
1055
+ def delete(expires=nil, headers={})
1056
+ @s3.interface.delete_bucket_link(@name, expires, headers)
1057
+ end
1058
+ end
1059
+
1060
+
1061
+ class Key
1062
+ attr_reader :bucket, :name
1063
+
1064
+ def to_s
1065
+ @name
1066
+ end
1067
+
1068
+ # Return a full S# name (bucket/key).
1069
+ #
1070
+ # key.full_name #=> 'my_awesome_bucket/cool_key'
1071
+ #
1072
+ def full_name(separator='/')
1073
+ "#{@bucket.to_s}#{separator}#{@name}"
1074
+ end
1075
+
1076
+ # Return a public link to key.
1077
+ #
1078
+ # key.public_link #=> 'https://s3.amazonaws.com:443/my_awesome_bucket/cool_key'
1079
+ #
1080
+ def public_link
1081
+ params = @bucket.s3.interface.params
1082
+ "#{params[:protocol]}://#{params[:server]}:#{params[:port]}/#{full_name('/')}"
1083
+ end
1084
+
1085
+ def initialize(bucket, name, meta_headers={})
1086
+ @bucket = bucket
1087
+ @name = name.to_s
1088
+ @meta_headers = meta_headers
1089
+ raise 'Key name can not be empty.' if @name.blank?
1090
+ end
1091
+
1092
+ # Generate link to PUT key data.
1093
+ #
1094
+ # puts bucket.put('logs/today/1.log', '123', 2.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=B...D&Expires=1180820032&AWSAccessKeyId=1...2
1095
+ #
1096
+ def put(expires=nil, headers={})
1097
+ @bucket.put(@name.to_s, @meta_headers, expires, headers)
1098
+ end
1099
+
1100
+ # Generate link to GET key data.
1101
+ #
1102
+ # bucket.get('logs/today/1.log', 1.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=h...M%3D&Expires=1180820032&AWSAccessKeyId=1...2
1103
+ #
1104
+ def get(expires=nil, headers={})
1105
+ @bucket.s3.interface.get_link(@bucket.to_s, @name, expires, headers)
1106
+ end
1107
+
1108
+ # Generate link to delete key.
1109
+ #
1110
+ # bucket.delete(2.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=4...D&Expires=1180820032&AWSAccessKeyId=1...2
1111
+ #
1112
+ def delete(expires=nil, headers={})
1113
+ @bucket.s3.interface.delete_link(@bucket.to_s, @name, expires, headers)
1114
+ end
1115
+
1116
+ # Generate link to head key.
1117
+ #
1118
+ # bucket.head(2.hour) #=> https://s3.amazonaws.com:443/my_awesome_bucket/logs%2Ftoday%2F1.log?Signature=4...D&Expires=1180820032&AWSAccessKeyId=1...2
1119
+ #
1120
+ def head(expires=nil, headers={})
1121
+ @bucket.s3.interface.head_link(@bucket.to_s, @name, expires, headers)
1122
+ end
1123
+ end
1124
+ end
1125
+
1126
+ end