Class: Refile::S3

Inherits:
Object
  • Object
show all
Extended by:
BackendMacros
Defined in:
lib/refile/s3.rb,
lib/refile/s3/version.rb

Overview

A refile backend which stores files in Amazon S3

Examples:

backend = Refile::Backend::S3.new(
  access_key_id: "xyz",
  secret_access_key: "abcd1234",
  region: "sa-east-1",
  bucket: "my-bucket",
  prefix: "files"
)
file = backend.upload(StringIO.new("hello"))
backend.read(file.id) # => "hello"

Constant Summary collapse

VERSION = 
"0.1.0"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(access_key_id:, secret_access_key:, region:, bucket:, max_size: nil, prefix: nil, hasher: Refile::RandomHasher.new, **s3_options) ⇒ S3

Sets up an S3 backend with the given credentials.

Parameters:

  • access_key_id (String)
  • secret_access_key (String)
  • region (String) —

    The AWS region to connect to

  • bucket (String) —

    The name of the bucket where files will be stored

  • prefix (String) (defaults to: nil) —

    A prefix to add to all files. Prefixes on S3 are kind of like folders.

  • max_size (Integer, nil) (defaults to: nil) —

    The maximum size of an uploaded file

  • hasher (#hash) (defaults to: Refile::RandomHasher.new) —

    A hasher which is used to generate ids from files

  • s3_options (Hash) —

    Additional options to initialize S3 with

See Also:



36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/refile/s3.rb', line 36

def initialize(access_key_id:, secret_access_key:, region:, bucket:, max_size: nil, prefix: nil, hasher: Refile::RandomHasher.new, **s3_options)
  @access_key_id = access_key_id
  @secret_access_key = secret_access_key
  @s3_options = { access_key_id: access_key_id, secret_access_key: secret_access_key, region: region }.merge s3_options
  @s3 = Aws::S3::Resource.new @s3_options
  @bucket_name = bucket
  @bucket = @s3.bucket @bucket_name
  @hasher = hasher
  @prefix = prefix
  @max_size = max_size
end

Instance Attribute Details

#access_key_id ⇒ Object (readonly)

Returns the value of attribute access_key_id.



22
23
24
 
# File 'lib/refile/s3.rb', line 22

def access_key_id
  @access_key_id
end

#max_size ⇒ Object (readonly)

Returns the value of attribute max_size.



22
23
24
 
# File 'lib/refile/s3.rb', line 22

def max_size
  @max_size
end

Instance Method Details

#clear!(confirm = nil) ⇒ void

This method returns an undefined value.

Remove all files in this backend. You must confirm the deletion by passing the symbol ‘:confirm` as an argument to this method.

Examples:

backend.clear!(:confirm)

Parameters:

  • confirm (:confirm) (defaults to: nil) —

    Pass the symbol ‘:confirm` to confirm deletion.

Raises:

  • (Refile::Confirm) —

    Unless the ‘:confirm` symbol has been passed.



129
130
131
132
 
# File 'lib/refile/s3.rb', line 129

def clear!(confirm = nil)
  raise Refile::Confirm unless confirm == :confirm
  @bucket.objects(prefix: @prefix).delete
end

#delete ⇒ void

This method returns an undefined value.

Delete a file from this backend

Parameters:

  • id (Sring) —

    The id of the file



80
81
82
 
# File 'lib/refile/s3.rb', line 80

verify_id def delete(id)
  object(id).delete
end

#exists? ⇒ Boolean

Return whether the file with the given id exists in this backend.

Parameters:

  • id (Sring) —

    The id of the file

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/refile/s3.rb', line 117

verify_id def exists?(id)
  object(id).exists?
end

#get ⇒ Refile::File

Get a file from this backend.

Note that this method will always return a File object, even if a file with the given id does not exist in this backend. Use FileSystem#exists? to check if the file actually exists.

Parameters:

  • id (Sring) —

    The id of the file

Returns:

  • (Refile::File) —

    The retrieved file



72
73
74
 
# File 'lib/refile/s3.rb', line 72

verify_id def get(id)
  Refile::File.new(self, id)
end

#open ⇒ IO

Return an IO object for the uploaded file which can be used to read its content.

Parameters:

  • id (Sring) —

    The id of the file

Returns:

  • (IO) —

    An IO object containing the file contents



89
90
91
 
# File 'lib/refile/s3.rb', line 89

verify_id def open(id)
  Kernel.open(object(id).presigned_url(:get))
end

#presign ⇒ Refile::Signature

Return a presign signature which can be used to upload a file into this backend directly.

Returns:

  • (Refile::Signature) 


138
139
140
141
142
143
 
# File 'lib/refile/s3.rb', line 138

def presign
  id = RandomHasher.new.hash
  signature = @bucket.presigned_post(key: [*@prefix, id].join("/"))
  signature.content_length_range(0..@max_size) if @max_size
  Signature.new(as: "file", id: id, url: signature.url.to_s, fields: signature.fields)
end

#read ⇒ String

Return the entire contents of the uploaded file as a String.

Parameters:

  • id (String) —

    The id of the file

Returns:

  • (String) —

    The file’s contents



97
98
99
100
101
 
# File 'lib/refile/s3.rb', line 97

verify_id def read(id)
  object(id).get.body.read
rescue Aws::S3::Errors::NoSuchKey
  nil
end

#size ⇒ Integer

Return the size in bytes of the uploaded file.

Parameters:

  • id (Sring) —

    The id of the file

Returns:

  • (Integer) —

    The file’s size



107
108
109
110
111
 
# File 'lib/refile/s3.rb', line 107

verify_id def size(id)
  object(id).get.content_length
rescue Aws::S3::Errors::NoSuchKey
  nil
end

#upload ⇒ Refile::File

Upload a file into this backend

Parameters:

  • uploadable (IO) —

    An uploadable IO-like object.

Returns:

  • (Refile::File) —

    The uploaded file



52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/refile/s3.rb', line 52

verify_uploadable def upload(uploadable)
  id = @hasher.hash(uploadable)

  if uploadable.is_a?(Refile::File) and uploadable.backend.is_a?(S3) and uploadable.backend.access_key_id == access_key_id
    object(id).copy_from(copy_source: [@bucket_name, uploadable.backend.object(uploadable.id).key].join("/"))
  else
    object(id).put(body: uploadable, content_length: uploadable.size)
  end

  Refile::File.new(self, id)
end