Class: Aws::S3::PresignedPost

Inherits:
Object
  • Object
show all
Defined in:
lib/aws-sdk-s3/presigned_post.rb

Overview

Note:

Normally you do not need to construct a PresignedPost yourself. See Bucket#presigned_post and Object#presigned_post.

## Basic Usage

To generate a presigned post, you need AWS credentials, the region your bucket is in, and the name of your bucket. You can apply constraints to the post object as options to #initialize or by calling methods such as #key and #content_length_range.

The following two examples are equivalent.

“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket, 

key: '/uploaded/object/key',
content_length_range: 0..1024,
acl: 'public-read',
metadata: {
  'original-filename' => '${filename'
}

}) post.fields #=> { … }

post = Aws::S3::PresignedPost.new(creds, region, bucket).

key('/uploaded/object/key').
content_length_range(0..1024).
acl('public-read').
metadata('original-filename' => '$filename').
fields

#=> { … } “‘

## HTML Forms

You can use a {PresignedPost} object to build an HTML form. It is recommended to use some helper to build the form tag and input tags that properly escapes values.

### Form Tag

To upload a file to Amazon S3 using a browser, you need to create a post form. The {#url} method returns the value you should use as the form action.

“‘erb <form action=“<%= @post.url %>” method=“post” enctype=“multipart/form-data”>

...

</form> “‘

The follow attributes must be set on the form:

  • ‘action` - This must be the {#url}.

  • ‘method` - This must be `post`.

  • ‘enctype` - This must be `multipart/form-data`.

### Form Fields

The {#fields} method returns a hash of form fields to render inside the form. Typically these are rendered as hidden input fields.

“‘erb <% @post.fields.each do |name, value| %>

<input type="hidden" name="<%= name %>" value="<%= value %>"/>

<% end %> “‘

Lastly, the form must have a file field with the name ‘file`.

“‘erb <input type=“file” name=“file”/> “`

## Post Policy

When you construct a {PresignedPost}, you must specify every form field name that will be posted by the browser. If you omit a form field sent by the browser, Amazon S3 will reject the request. You can specify accepted form field values three ways:

  • Specify exactly what the value must be.

  • Specify what value the field starts with.

  • Specify the field may have any value.

### Field Equals

You can specify that a form field must be a certain value. Simply pass an option like ‘:content_type` to the constructor, or call the associated method.

“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket). post.content_type(’text/plain’) “‘

If any of the given values are changed by the user in the form, then Amazon S3 will reject the POST request.

### Field Starts With

You can specify prefix values for many of the POST form fields. To specify a required prefix, use the ‘:<fieldname>_starts_with` option or call the associated `#<field_name>_starts_with` method.

“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket, {

key_starts_with: '/images/',
content_type_starts_with: 'image/',
# ...

}) “‘

When using starts with, the form must contain a field where the user can specify the value. The {PresignedPost} will not add a value for these fields.

### Any Field Value

To white-list a form field to send any value, you can name that field with ‘:allow_any` or {#allow_any}.

“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket, {

key: 'object-key',
allow_any: ['Filename'],
# ...

}) “‘

### Metadata

You can add rules for metadata fields using ‘:metadata`, {#metadata}, `:metadata_starts_with` and {#metadata_starts_with}. Unlike other form fields, you pass a hash value to these options/methods:

“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket).

key('/fixed/key').
metadata(foo: 'bar')

post.fields #=> ‘bar’ “‘

### The ‘${filename}` Variable

The string ‘${filename}` is automatically replaced with the name of the file provided by the user and is recognized by all form fields. It is not supported with `starts_with` conditions.

If the browser or client provides a full or partial path to the file, only the text following the last slash (/) or backslash () will be used (e.g., “C:Program Filesdirectory1file.txt” will be interpreted as “file.txt”). If no file or file name is provided, the variable is replaced with an empty string.

In the following example, we use ‘${filename}` to store the original filename in the `x-amz-meta-` hash with the uploaded object.

“‘ruby post = Aws::S3::PresignedPost.new(creds, region, bucket, {

key: '/fixed/key',
metadata: {
  'original-filename': '${filename}'
}

}) “‘

Instance Attribute Summary collapse

Fields collapse

Server-Side Encryption Fields collapse

Server-Side Encryption with Customer-Provided Key Fields collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(credentials, bucket_region, bucket_name, options = {}) ⇒ PresignedPost

Returns a new instance of PresignedPost.

Parameters:

  • credentials (Credentials) —

    Security credentials for signing the post policy.

  • bucket_region (String) —

    Region of the target bucket.

  • bucket_name (String) —

    Name of the target bucket.

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 211

def initialize(credentials, bucket_region, bucket_name, options = {})
  @credentials = credentials.credentials
  @bucket_region = bucket_region
  @bucket_name = bucket_name
  @url = options.delete(:url) || bucket_url
  @fields = {}
  @key_set = false
  @signature_expiration = Time.now + 3600
  @conditions = [{ 'bucket' => @bucket_name }]
  options.each do |option_name, option_value|
    case option_name
    when :allow_any then allow_any(option_value)
    when :signature_expiration then @signature_expiration = option_value
    else send("#{option_name}", option_value)
    end
  end
end

Instance Attribute Details

#url ⇒ String (readonly)

Returns The URL to post a file upload to. This should be the form action.

Returns:

  • (String) —

    The URL to post a file upload to. This should be the form action.



231
232
233
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 231

def url
  @url
end

Class Method Details

.define_field(field, *args) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 256

def self.define_field(field, *args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  field_name = args.last || field.to_s

  define_method("#{field}") do |value|
    with(field_name, value)
  end

  if options[:starts_with]
    define_method("#{field}_starts_with") do |value|
      starts_with(field_name, value)
    end
  end
end

Instance Method Details

#acl(canned_acl) ⇒ self

Specify the cannedl ACL (access control list) for the object. May be one of the following values:

* `private`
* `public-read`
* `public-read-write`
* `authenticated-read`
* `bucket-owner-read`
* `bucket-owner-full-control`

Parameters:

  • canned_acl (String)

Returns:

  • (self)

See Also:



317
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 317

define_field(:acl, starts_with: true)

#acl_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



317
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 317

define_field(:acl, starts_with: true)

#allow_any(*field_names) ⇒ self

A list of form fields to white-list with any value.

Parameters:

  • field_names (Sting, Array<String>)

Returns:

  • (self) 


247
248
249
250
251
252
253
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 247

def allow_any(*field_names)
  field_names.flatten.each do |field_name|
    @key_set = true if field_name.to_s == 'key'
    starts_with(field_name, '')
  end
  self
end

#cache_control(value) ⇒ self

Specify caching behavior along the request/reply chain.

Parameters:

  • value (String)

Returns:

  • (self)

See Also:



329
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 329

define_field(:cache_control, 'Cache-Control', starts_with: true)

#cache_control_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



329
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 329

define_field(:cache_control, 'Cache-Control', starts_with: true)

#content_disposition(value) ⇒ self

Specifies presentational information for the object.

Parameters:

  • value (String)

Returns:

  • (self)

See Also:



354
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 354

define_field(:content_disposition, 'Content-Disposition', starts_with: true)

#content_disposition_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



354
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 354

define_field(:content_disposition, 'Content-Disposition', starts_with: true)

#content_encoding(value) ⇒ self

Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

Parameters:

  • value (String)

Returns:

  • (self)

See Also:



368
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 368

define_field(:content_encoding, 'Content-Encoding', starts_with: true)

#content_encoding_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



368
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 368

define_field(:content_encoding, 'Content-Encoding', starts_with: true)

#content_length_range(byte_range) ⇒ self

The minimum and maximum allowable size for the uploaded content.

Parameters:

  • byte_range (Range<Integer>)

Returns:

  • (self) 


390
391
392
393
394
395
396
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 390

def content_length_range(byte_range)
  min = byte_range.begin
  max = byte_range.end
  max -= 1 if byte_range.exclude_end?
  @conditions << ['content-length-range', min, max]
  self
end

#content_type(value) ⇒ self

A standard MIME type describing the format of the contents.

Parameters:

  • value (String)

Returns:

  • (self)

See Also:



342
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 342

define_field(:content_type, 'Content-Type', starts_with: true)

#content_type_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



342
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 342

define_field(:content_type, 'Content-Type', starts_with: true)

#expires(time) ⇒ self

Note:

This does not affect the expiration of the presigned post signature.

The date and time at which the object is no longer cacheable.

Parameters:

  • time (Time)

Returns:

  • (self)

See Also:



376
377
378
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 376

def expires(time)
  with('Expires', time.httpdate)
end

#expires_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



383
384
385
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 383

def expires_starts_with(prefix)
  starts_with('Expires', prefix)
end

#fields ⇒ Hash

Returns A hash of fields to render in an HTML form as hidden input fields.

Returns:

  • (Hash) —

    A hash of fields to render in an HTML form as hidden input fields.



235
236
237
238
239
240
241
242
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 235

def fields
  check_required_values!
  datetime = Time.now.utc.strftime("%Y%m%dT%H%M%SZ")
  fields = @fields.dup
  fields.update('policy' => policy(datetime))
  fields.update(signature_fields(datetime))
  fields.update('x-amz-signature' => signature(datetime, fields['policy']))
end

#key(key) ⇒ self

The key to use for the uploaded object. Use can use ‘$filename` as a variable in the key. This will be replaced with the name of the file as provided by the user.

For example, if the key is given as ‘/user/betty/$filename` and the file uploaded is named `lolcatz.jpg`, the resultant key will be `/user/betty/lolcatz.jpg`.

Parameters:

  • key (String)

Returns:

  • (self)

See Also:



284
285
286
287
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 284

def key(key)
  @key_set = true
  with('key', key)
end

#key_starts_with(prefix) ⇒ self

Specify a prefix the uploaded

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



293
294
295
296
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 293

def key_starts_with(prefix)
  @key_set = true
  starts_with('key', prefix)
end

#metadata(hash) ⇒ self

Metadata hash to store with the uploaded object. Hash keys will be prefixed with “x-amz-meta-”.

Parameters:

  • hash (Hash<String,String>)

Returns:

  • (self) 


469
470
471
472
473
474
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 469

def metadata(hash)
  hash.each do |key, value|
    with("x-amz-meta-#{key}", value)
  end
  self
end

#metadata_starts_with(hash) ⇒ self

Specify allowable prefix for each key in the metadata hash.

Parameters:

  • hash (Hash<String,String>)

Returns:

  • (self)

See Also:



480
481
482
483
484
485
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 480

def metadata_starts_with(hash)
  hash.each do |key, value|
    starts_with("x-amz-meta-#{key}", value)
  end
  self
end

#server_side_encryption(value) ⇒ self

Specifies a server-side encryption algorithm to use when Amazon S3 creates an object. Valid values include:

  • ‘aws:kms`

  • ‘AES256`

Parameters:

  • value (String)

Returns:

  • (self) 


500
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 500

define_field(:server_side_encryption, 'x-amz-server-side-encryption')

#server_side_encryption_aws_kms_key_id(value) ⇒ self

If #server_side_encryption is called with the value of ‘aws:kms`, this method specifies the ID of the AWS Key Management Service (KMS) master encryption key to use for the object.

Parameters:

  • value (String)

Returns:

  • (self) 


508
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 508

define_field(:server_side_encryption_aws_kms_key_id, 'x-amz-server-side-encryption-aws-kms-key-id')

#server_side_encryption_customer_algorithm(value) ⇒ self

Specifies the algorithm to use to when encrypting the object. Must be set to ‘AES256` when using customer-provided encryption keys. Must also call #server_side_encryption_customer_key.

Parameters:

  • value (String)

Returns:

  • (self)

See Also:



521
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 521

define_field(:server_side_encryption_customer_algorithm, 'x-amz-server-side-encryption-customer-algorithm')

#server_side_encryption_customer_key(value) ⇒ self

Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key.

You must also call #server_side_encryption_customer_algorithm.

Parameters:

  • value (String)

Returns:

  • (self)

See Also:



532
533
534
535
536
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 532

def server_side_encryption_customer_key(value)
  field_name = 'x-amz-server-side-encryption-customer-key'
  with(field_name, base64(value))
  with(field_name + '-MD5', base64(OpenSSL::Digest::MD5.digest(value)))
end

#server_side_encryption_customer_key_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



541
542
543
544
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 541

def server_side_encryption_customer_key_starts_with(prefix)
  field_name = 'x-amz-server-side-encryption-customer-key'
  starts_with(field_name, prefix)
end

#storage_class(value) ⇒ self

Storage class to use for storing the object. Defaults to ‘STANDARD`. Must be one of:

  • ‘STANDARD`

  • ‘REDUCED_REDUNDANCY`

You cannot specify ‘GLACIER` as the storage class. To transition objects to the GLACIER storage class you can use lifecycle configuration.

Parameters:

  • value (String) —

    Storage class to use for storing the

Returns:

  • (self) 


447
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 447

define_field(:storage_class, 'x-amz-storage-class')

#success_action_redirect(value) ⇒ self

The URL to which the client is redirected upon successful upload. If #success_action_redirect is not specified, Amazon S3 returns the empty document type specified by #success_action_status.

If Amazon S3 cannot interpret the URL, it acts as if the field is not present. If the upload fails, Amazon S3 displays an error and does not redirect the user to a URL.

Parameters:

  • value (String)

Returns:

  • (self) 


415
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 415

define_field(:success_action_redirect, starts_with: true)

#success_action_redirect_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



415
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 415

define_field(:success_action_redirect, starts_with: true)

#success_action_status(value) ⇒ self

The status code returned to the client upon successful upload if #success_action_redirect is not specified.

Accepts the values ‘200`, `201`, or `204` (default).

If the value is set to 200 or 204, Amazon S3 returns an empty document with a 200 or 204 status code. If the value is set to 201, Amazon S3 returns an XML document with a 201 status code.

If the value is not set or if it is set to an invalid value, Amazon S3 returns an empty document with a 204 status code.

Parameters:

  • value (String) —

    The status code returned to the client upon

Returns:

  • (self) 


433
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 433

define_field(:success_action_status)

#website_redirect_location(value) ⇒ self

If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores this value in the object metadata.

The value must be prefixed by, “/”, “http://” or “https://”. The length of the value is limited to 2K.

Parameters:

  • value (String)

Returns:

  • (self)

See Also:



463
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 463

define_field(:website_redirect_location, 'x-amz-website-redirect-location')