update readme

Author: jumblerg

README.md

@@ -1,25 +1,55 @@
 # boot-bucket
 
-Boot task `spew` for spewing output files into an s3 bucket.
+a boot task for spewing files into an S3 bucket.
 
 [](dependency)
 ```clojure
 [tailrecursion/boot-bucket "1.1.0"] ;; latest release
 ```
 [](/dependency)
 
-## Overview
+## overview
 
-This task uploads any files whose filenames or hashes differ from those in the
-targeted s3 bucket, then decorates them with boot metadata so they may be
+the `spew` task uploads any files whose filenames or hashes differ from those in
+the targeted S3 bucket, then decorates them with boot metadata so they may be
 identified by subsequent tasks (see [boot-front](https://github.com/tailrecursion/boot-front)).
 
-Also optionally allows S3 metadata to be set so that HTTP headers can be
-configured on a per-file basis for files served by S3/Cloudfront.
+the uploaded files may also themselves be adorned with AWS metadata on a per-
+file basis to configure HTTP headers in S3 and cloundfront.
 
-## Usage
+## canned access control lists (ACLs)
 
-Excerpt of a build.boot file using boot-bucket with boot-front for deployment.
+in a departure from previous releases, as of `2.0.0`, boot-bucket defaults to
+the `:private` canned ACL, which should be changed to `:public-read` when
+serving files from an S3 bucket.  alternately, any of the following canned ACL
+keywords may be specified to the `access-control` parameter:
+
+```
+:private (default)
+:log-delivery-write        
+:bucket-owner-read         
+:bucket-owner-full-control 
+:authenticated-read        
+:public-read         
+:public-read-write
+```
+
+custom acls are currently unsupported, but pull requests are most welcome.
+
+## metadata
+both user and system metadata may be passed to the `metadata` parameter in the
+same map to modify the http headers served up by S3. these are supported on a
+per-file basis of the form `{"<filename>" {:<meta-key> "meta-value"}}`. an
+example is shown below:
+
+```
+{"index.html.js" {:content-encoding "gzip"}}
+```
+
+## usage
+
+the following is an excerpt of a `build.boot' file using boot-bucket together
+with [boot-front][1] for deployments:
 
 ```clojure
 (require
@@ -62,68 +92,42 @@ Excerpt of a build.boot file using boot-bucket with boot-front for deployment.
 (task-options!
   serve {:port 3001}
   sift  {:include #{#"index.html.out/" #"<app-ns>/"} :invert true}
-  spew  {:access-key (System/getenv "<AWS_ACCESS_KEY_ENV_VAR>")
-         :secret-key (System/getenv "<AWS_SECRET_KEY_ENV_VAR>")}
+  spew  {:access-control :public-read
+	       :access-key     (System/getenv "<AWS_ACCESS_KEY_ENV_VAR>")
+         :secret-key     (System/getenv "<AWS_SECRET_KEY_ENV_VAR>")}
   burst {:access-key (System/getenv "<AWS_ACCESS_KEY_ENV_VAR>")
          :secret-key (System/getenv "<AWS_SECRET_KEY_ENV_VAR>")})
 ```
 
-## Public read ACL on all files
-
-**All files are set to public read upon upload.**
+# aot gzipping
 
-This is so that the files can be served over HTTP either directly from S3 or
-through Cloudfront.
-
-This suits the primary use-case - compiling an SPA through CLJS.
-
-If you have a different need that requires private uploads, you'll need to
-submit a pull request with some conditional logic around
-`tailrecursion.boot-bucket.client/with-public-read!`
-
-## s3 metadata
-
-S3 supports two kinds of metadata, system and user. These are served by S3 as
-headers over HTTP.
-
-`spew` supports providing a map of path/metadata where metadata is a map of k/v
-pairs.
-
-Internally the boot task normalizes user/system metadata so that the correct fns
-in the AWS SDK are called, based on the metadata key name.
-
-### Example: AOT gzipping
-
-We can set the `Content-Encoding` header to `gzip` for a large file such as
-`index.html.js` that we [already compressed in an earlier task](https://github.com/martinklepsch/boot-gzip).
+the `Content-Encoding` header may be set to `"gzip"` for a large file such as
+an `index.html.js` artifact that was compressed upstream by another task like
+[boot-gzip][2]:
 
 ```clojure
 (spew
- :access-key ; ...
- :secret-key ; ...
- :metadata {"index.html.js" {:content-encoding "gzip"}})
+ :access-key     "<aws-access-key>"
+ :secret-key     "<aws-secret-key>"
+ :access-control :public-read
+ :metadata       {"index.html.js" {:content-encoding "gzip"}})
 ```
 
-Gzipping compiled CLJS output is pretty important as core/goog can weigh in at
-multiple MB and compression can drop this file size by 80%+.
-
-In fact, it's possible for compiled CLJS to weigh in at 10MB+ and compress to
-under 2MB - but at this point Cloudfront will no longer apply compression due to
-platform limitations.
+note that it's often important to zip CLJS output as core/goog can weigh in at
+multiple MB and compression can drop this file size by 80%+. in fact, it's
+possible for compiled CLJS to weigh in at 10MB+ and compress to under 2MB - but
+at this point Cloudfront will no longer apply compression due to platform
+limitations. pre-gzipping files and setting the correct metadata headers in this
+way has several benefits:
 
-Pre-gzipping files and setting the correct metadata headers in this way has
-several benefits:
+- achieve compressed files without cloudfront (e.g. serving site from S3)
+- avoid the 1MB min/10MB max limits for on-the-fly compression in cloudfront
+- reduce S3 resources needed in upload and storage
+- minor performance benefits as cloudfront does not need to apply compression
 
-- Achieve compressed files without Cloudfront (e.g. serving site from S3)
-- Avoid the 1MB min/10MB max limits for on-the-fly compression in Cloudfront
-- Reduce S3 resources needed in upload and storage
-- Minor performance benefits as Cloudfront does not need to apply compression
-
-Note that Cloudfront will not apply on-the-fly compression to any file with the
+note that cloudfront will not apply on-the-fly compression to any file with the
 `Content-Encoding` header set, so be careful to only set it on files that have
 been gzipped during deployment.
 
-## Parallel file uploading
-
-By default `spew` will upload all files sequentially, but can be configured to
-parallel uploads through the `-p` flag or `:parallel?` task config.
+[1]: http://github.com/tailrecursion/boot-front
+[2]: https://github.com/martinklepsch/boot-gzip