Skip to content

Latest commit

 

History

History
109 lines (66 loc) · 3.73 KB

s3.md

File metadata and controls

109 lines (66 loc) · 3.73 KB
Raw

S3 Bucket Resource

This custom resource type allows you to store and retrieve files from an Amazon S3 bucket.

Installation

In your app's root directory, type npm install dpd-s3 into the command line. This should create a dpd-s3 directory in your app's node_modules directory.

See Installing Modules for details.

Configuration

Before you can use the S3 Bucket resource, you must set the three properties on its "Config" page:

  • bucket: The name of your S3 Bucket
  • key: The security key of your S3 Bucket
  • secret: The secret key of your S3 Bucket

Usage

Upload

There are two ways to upload files. Both ways require HTTP access; you cannot upload files with dpd.js.

Direct upload

Send a POST request to the url where you want to upload the file, including the file name. Set the Content-Type header to that of the file you are uploading and pass the file's content in the request body.

It will return a 200 OK if the upload was successful. If there was an error, it will return the error directly from S3. This is usually in XML; see Amazon's S3 documentation for information.

POST /my-bucket/README.txt
Content-Type: text/plain
Hello, world!

200 OK
Multipart upload

You can upload files directly from a browser using the multipart/form-data type and the <input type="file" /> tag:

<form action="/installer-downloads" enctype="multipart/form-data" method="post">
	<input type="file" name="upload" multiple="multiple" />
	<button type="submit">Upload</button>
</form>

To send a multipart request manually, send a POST request to the url where you want to upload the file, not including the file name. The Content-Type header must be multipart/form-data. Set the request body according to the multipart/form-data standard.

If the upload was successful and there is a Referer header on the request (e.g. if it was submitted as a form from a browser), the response will redirect to the referer. Otherwise, it will return 200 OK. If there was an error, it will return the error directly from S3. This is usually in XML; see Amazon's S3 documentation for information.

Retreiving files

To download a file, send a GET request to the url where the file exists.

GET /my-bucket/README.txt

200 OK
Content-Type: text/plain
Hello, world!

Deleting files

To delete a file, send a DELETE request to the url where the file exists.

DELETE /my-bucket/README.txt

200 OK

This can also be done with dpd.js:

dpd.mybucket.del('README.txt', function(response, error) {
	// Do something
});

Events

The S3 Bucket Resource has three events:

  • On Upload: Executed before a file is uploaded to S3.
  • On Get: Executed before a file is downloaded from S3.
  • On Delete: Executed before a file is deleted.

Event API

url

The URL of the request. Does not include the resource's name; if the request URL is /my-bucket/README.txt, the url property will be /README.txt.

fileSize

Only available in On Upload. The size of the file, in bytes.

	// On Upload
	// Set a limit on file size
	if (fileSize > 1024*1024*1024) { // 1GB
		cancel("File is too big; limit is 1GB");
	}

fileName

Only available in On Upload. The name of the file that is being uploaded.

	// On Upload
	dpd.uploads.post({ filename: fileName, creator: me.id }, function() {})