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}'
}

}) “‘

Constant Summary collapse

@@allowed_fields = 
[]

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



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 243

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
      if @@allowed_fields.include?(option_name)
        send("#{option_name}", option_value)
      else
        raise ArgumentError, "Unsupported option: #{option_name}"
      end
    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.



270
271
272
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 270

def url
  @url
end

Class Method Details

.define_field(field, *args, &block) ⇒ 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. 



295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 295

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

  if block_given?
    define_method("#{field}", block)
  else
    define_method("#{field}") do |value|
      with(field_name, value)
    end

    if options[:starts_with]
      @@allowed_fields << "#{field}_starts_with".to_sym
      define_method("#{field}_starts_with") do |value|
        starts_with(field_name, value)
      end
    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:



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

define_field(:acl, starts_with: true)

#acl_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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) 


286
287
288
289
290
291
292
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 286

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:



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

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

#cache_control_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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:



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

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

#content_disposition_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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:



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

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

#content_encoding_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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) 


440
441
442
443
444
445
446
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 440

define_field(:content_length_range) do |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:



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

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

#content_type_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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:



424
425
426
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 424

define_field(:expires) do |time|
  with('Expires', time.httpdate)
end

#expires_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

define_field(:expires_starts_with) do |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.



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

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:



330
331
332
333
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 330

define_field(:key) do |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:



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

define_field(:key_starts_with) do |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) 


520
521
522
523
524
525
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 520

define_field(:metadata) do |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:



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

define_field(:metadata_starts_with) do |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) 


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

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) 


560
561
562
563
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 560

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:



576
577
578
579
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 576

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:



591
592
593
594
595
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 591

define_field(:server_side_encryption_customer_key) do |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:



601
602
603
604
 
# File 'lib/aws-sdk-s3/presigned_post.rb', line 601

define_field(:server_side_encryption_customer_key_starts_with) do |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) 


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

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) 


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

define_field(:success_action_redirect, starts_with: true)

#success_action_redirect_starts_with(prefix) ⇒ self

Parameters:

  • prefix (String)

Returns:

  • (self)

See Also:



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

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) 


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

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:



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

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