Class: Aws::S3::PresignedPost

Inherits:
Object
  • Object
show all
Defined in:
gems/aws-sdk-s3/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.

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').
  ('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.

<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.

<% @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.

<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.

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.

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.

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:

post = Aws::S3::PresignedPost.new(creds, region, bucket).
  key('/fixed/key').
  (foo: 'bar')

post.fields['x-amz-meta-foo']
#=> '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 Files\directory1\file.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.

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

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):



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 235

def initialize(credentials, bucket_region, bucket_name, options = {})
  @credentials = credentials.credentials
  @bucket_region = bucket_region
  @bucket_name = bucket_name
  @accelerate = !!options.delete(:use_accelerate_endpoint)
  options.delete(:url) if @accelerate # resource methods pass url
  @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

#urlString (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.



257
258
259
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 257

def url
  @url
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:



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

define_field(:acl, starts_with: true)

#acl_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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)


273
274
275
276
277
278
279
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 273

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:



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

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

#cache_control_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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:



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

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

#content_disposition_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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:



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

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

#content_encoding_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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)


416
417
418
419
420
421
422
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 416

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:



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

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

#content_type_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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:



402
403
404
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 402

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

#expires_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



409
410
411
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 409

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

#fieldsHash

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.



261
262
263
264
265
266
267
268
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 261

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. You 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:



310
311
312
313
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 310

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:



319
320
321
322
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 319

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)


495
496
497
498
499
500
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 495

def (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:



506
507
508
509
510
511
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 506

def (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)


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

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)


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

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:



550
551
552
553
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 550

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:



564
565
566
567
568
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 564

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:



573
574
575
576
# File 'gems/aws-sdk-s3/lib/aws-sdk-s3/presigned_post.rb', line 573

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)


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

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)


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

define_field(:success_action_redirect, starts_with: true)

#success_action_redirect_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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)


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

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.



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

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