*CREDENTIALS* is the source of the Amazon Access Key and Secret Key for authenticated requests. Any object that has methods for the ACCESS-KEY and SECRET-KEY generic functions may be used.

If *CREDENTIALS* is a cons, it is treated as a list, and the first element of the list is taken as the access key and the second element of the list is taken as the secret key.

The default value of *CREDENTIALS* is NIL, which will signal an error. You must set *CREDENTIALS* to something that follows the credentials generic function protocol to use ZS3.

All ZS3 functions that involve authenticated requests take an optional :CREDENTIALS keyword parameter. This parameter is bound to *CREDENTIALS* for the duration of the function call.

The following illustrates how to implement a credentials object that gets the access and secret key from external environment variables.

  (defclass environment-credentials () ())

  (defmethod access-key ((credentials environment-credentials))
    (declare (ignore credentials))
    (getenv "AWS_ACCESS_KEY"))

  (defmethod secret-key ((credentials environment-credentials))
    (declare (ignore credentials))
    (getenv "AWS_SECRET_KEY"))

  (setf *credentials* (make-instance 'environment-credentials))

Returns the access key for credentials.

Returns the secret key for credentials.

Loads credentials on demand from pathname. The file named by pathname should be a text file with the access key on the first line and the secret key on the second line.

It can be used like so:

  (setf *credentials* (file-credentials "/etc/s3.conf"))

Returns a vector of all bucket objects. Bucket object attributes are accessible via NAME and CREATION-DATE.

Returns the creation date of bucket-object, which must be a bucket object, as a universal time.

Returns the string name of object, which must be a key object or bucket object.

Returns a vector of all key objects in bucket with names that start with the string prefix. If no prefix is specified, returns all keys. Keys in the vector are in alphabetical order by name. Key object attributes are accessible via NAME, SIZE, ETAG, LAST-MODIFIED, and OWNER.

This function is built on QUERY-BUCKET and may involve multiple requests if a bucket has more than 1000 keys.

Returns true if bucket exists.

Creates a bucket named name.

If provided, access-policy should be one of the following:

• :PRIVATE - bucket owner is granted :FULL-CONTROL; this is the default behavior if no access policy is provided
• :PUBLIC-READ - all users, regardless of authentication, can query the bucket's contents
• :PUBLIC-READ-WRITE - all users, regardless of authentication, can query the bucket's contents and create new objects in the bucket
• :AUTHENTICATED-READ - authenticated Amazon AWS users can query the bucket

For more information about access policies, see Canned Access Policies in the Amazon S3 developer documentation.

If public is true, it has the same effect as providing an access-policy of :PUBLIC-READ. An error is signaled if both public and access-policy are provided.

If location is "EU", the bucket will be created in Europe. See Bucket Configuration Options in the Amazon S3 developer documentation for more information about location constraints.

Deletes bucket. Signals a BUCKET-NOT-EMPTY error if the bucket is not empty, or a NO-SUCH-BUCKET error if there is no bucket with the given name.

Returns the location specified when creating a bucket, or NIL if no location was specified.

Query bucket for key information. Returns a response object that has the result of the query. Response attributes are accessible via BUCKET-NAME, PREFIX, MARKER, DELIMITER, TRUNCATEDP, KEYS, and COMMON-PREFIXES.

Amazon might return fewer key objects than actually match the query parameters, based on max-keys or the result limit of 1000 key objects. In that case, TRUNCATEDP for response is true, and CONTINUE-BUCKET-QUERY can be used with response be used to get successive responses for the query parameters.

When prefix is supplied, only key objects with names that start with prefix will be returned in response.

When marker is supplied, only key objects with names occurring lexically after marker will be returned in response.

When max-keys is supplied, it places an inclusive upper limit on the number of key objects returned in response. Note that Amazon currently limits responses to at most 1000 key objects even if max-keys is greater than 1000.

When delimiter is supplied, key objects that have the delimiter string after prefix in their names are not returned in the KEYS attribute of the response, but are instead accumulated into the COMMON-PREFIXES attribute of the response. For example:

  * (all-keys "zs3-demo")
  => #(#<KEY "a" 4>
       #<KEY "b/1" 4>
       #<KEY "b/2" 4>
       #<KEY "b/3" 4>
       #<KEY "c/10" 4>
       #<KEY "c/20" 4>
       #<KEY "c/30" 4>)

  * (setf *response* (query-bucket "zs3-demo" :delimiter "/"))
  => #<BUCKET-LISTING "zs3-demo">

  * (values (keys *response*) (common-prefixes *response*))
  => #(#<KEY "a" 4>),
     #("b/"
       "c/")

  * (setf *response* (query-bucket "zs3-demo" :delimiter "/" :prefix "b/"))
  => #<BUCKET-LISTING "zs3-demo">

  * (values (keys *response*) (common-prefixes *response*))
  => #(#<KEY "b/1" 4>
       #<KEY "b/2" 4>
       #<KEY "b/3" 4>),
     #()

For more information about bucket queries, see GET Bucket in the Amazon S3 developer documentation.

If response is a truncated response from a previous call to QUERY-BUCKET, continue-bucket-query returns the result of resuming the query at the truncation point. When there are no more results, continue-bucket-query returns NIL.

Returns the name of the bucket used in the call to QUERY-BUCKET that produced response.

Returns the vector of key objects in response. Key object attributes are accessible via NAME, SIZE, ETAG, LAST-MODIFIED, and OWNER.

Returns a vector of common prefix strings, based on the delimiter argument of the QUERY-BUCKET call that produced response.

Returns the prefix given to the QUERY-BUCKET call that produced response. If present, all keys in response have prefix-string as a prefix.

Returns the marker given to the QUERY-BUCKET call that produced response. If present, it lexically precedes all key names in the response.

Returns the delimiter used in the QUERY-BUCKET call that produced response.

Returns true if response is truncated; that is, if there is more data to retrieve for a given QUERY-BUCKET query. CONTINUE-BUCKET-QUERY may be used to fetch more data.

Returns a universal time representing the last modified time of key-object.

Returns the etag for key-object.

Returns the size, in octets, of key-object.

Returns the owner of key-object, or NIL if no owner information is available.

Fetch the object referenced by bucket and key. The secondary value of all successful requests is an alist of Drakma-style response HTTP headers.

If output is :VECTOR (the default), the object's octets are returned in a vector.

If output is :STRING, the object's octets are converted to a string using the encoding specified by string-external-format, which defaults to :UTF-8. See External formats in the FLEXI-STREAMS documentation for supported values for the string external format. Note that, even when output is :STRING, the start and end arguments operate on the object's underlying octets, not the string representation in a particular encoding. It's possible to produce a subsequence of the object's octets that are not valid in the desired encoding.

If output is a string or pathname, the object's octets are saved to a file identified by the string or pathname. The if-exists argument is passed to WITH-OPEN-FILE to control the behavior when the output file already exists. It defaults to :SUPERSEDE.

start marks the first index fetched from the object's data. end specifies the index after the last octet fetched. If start is NIL, it defaults to 0. If end is nil, it defaults to the total length of the object. If both start and end are provided, start must be less than or equal to end.

when-modified-since and unless-modified-since are optional. If when-modified-since is provided, the result will be the normal object value if the object has been modified since the provided universal time, NIL otherwise. The logic is reversed for unless-modified-since.

when-etag-matches and unless-etag-matches are optional. If when-etag-matches is provided, the result will be the normal object value if the object's etag matches the provided string, NIL otherwise. The logic is reversed for unless-etag-matches.

get-vector is a convenience interface to GET-OBJECT. It is equivalent to calling:

  (get-object bucket key :output :vector ...)

get-string is a convenience interface to GET-OBJECT. It is equivalent to calling:

  (get-object bucket key :output :string :string-external-format external-format ...)

get-file is a convenience interface to GET-OBJECT. It is equivalent to calling:

  (get-object bucket key :output file ...)

Stores the octets of object in the location identified by bucket and key.

If object is an octet vector, it is stored directly.

If object is a string, it is converted to an octet vector using string-external-format, which defaults to :UTF-8, then stored. See External formats in the FLEXI-STREAMS documentation for supported values for the string external format.

If object is a pathname, its contents are loaded in memory as an octet vector and stored.

If provided, access-policy should be one of the following:

• :PRIVATE - object owner is granted :FULL-CONTROL; this is the default behavior if no access policy is provided
• :PUBLIC-READ - all users, regardless of authentication, can read the object
• :AUTHENTICATED-READ - authenticated Amazon AWS users can read the object

For more information about access policies, see Canned Access Policies in the Amazon S3 developer documentation.

If public is true, it has the same effect as providing an access-policy of :PUBLIC-READ. An error is signaled if both public and access-policy are provided.

If provided, metadata should be an alist of Amazon metadata to set on the object. When the object is fetched again, the metadata will be returned in HTTP headers prefixed with "x-amz-meta-".

The cache-control, content-encoding, content-disposition, content-type, and expires values are all used to set HTTP properties of the object that are returned with subsequent GET or HEAD requests. If content-type is not set, it defaults to "binary/octet-stream". The others default to NIL. If expires is provided, it should be a universal time.

put-vector is a convenience interface to PUT-OBJECT. It is similar to calling:

  (put-object vector bucket key ...)

If one of start or end is provided, they are used as bounding index designators on the string, and only a subsequence is used.

put-string is a convenience interface to PUT-OBJECT. It is similar to calling:

  (put-object string bucket key :string-external-format external-format ...)

If one of start or end is supplied, they are used as bounding index designators on the string, and only a substring is used.

put-file is a convenience interface to PUT-OBJECT. It is almost equivalent to calling:

  (put-object (pathname file) bucket key ...)

If key is T, the FILE-NAMESTRING of the file is used as the key instead of key.

If one of start or end is supplied, only a subset of the file is used. If start is not NIL, start octets starting from the beginning of the file are skipped. If end is not NIL, octets in the file at and after end are ignored. An error of type CL:END-OF-FILE is signaled if end is provided and the file size is less than end.

put-stream is similar to to PUT-OBJECT. It has the same effect as collecting octets from stream into a vector and using:

  (put-object vector bucket key ...)

If start is not NIL, start octets starting from the current position in the stream are skipped before collecting.

If end is NIL, octets are collected until the end of the stream is reached.

If end is not NIL, collecting octets stops just before reaching end in the stream. An error of type CL:END-OF-FILE is signaled if the stream ends prematurely.

Copies the object identified by from-bucket and from-key to a new location identified by to-bucket and to-key. If to-bucket is NIL, from-bucket is used as the target. If to-key is nil, from-key is used as the target. An error is signaled if both to-bucket and to-key are NIL.

access-policy and public have the same effect on the target object as in PUT-OBJECT.

The precondition arguments when-etag-matches, unless-etag-matches, when-modified-since, and unless-modified-since work the same way they do in GET-OBJECT, but with one difference: if precondition-errors is true, an PRECONDITION-FAILED error is signaled when a precondition does not hold, instead of returning NIL.

If metadata is explicitly provided, it follows the same behavior as with PUT-OBJECT. Passing NIL means that the new object has no metadata. Otherwise, the metadata is copied from the original object.

Deletes the object identified by bucket and key.

If bucket is a valid bucket for which you have delete access granted, S3 will always return a success response, even if key does not reference an existing object.

Deletes keys, which should be a sequence of keys, from bucket.

Deletes all objects in bucket and returns the count of objects deleted.

Returns the metadata for the object identified by bucket and key, or NIL if there is no metadata. For example:

  * (put-string "Hadjaha!" "zs3-demo" "hadjaha.txt" :metadata (parameters-alist :language "Swedish"))
  => #<RESPONSE 200 "OK" {1003BD2841}>    

  * (object-metadata "zs3-demo" "hadjaha.txt")
  => ((:LANGUAGE . "Swedish"))

Returns the owner and grant list for a resource as multiple values.

Sets the owner and grant list of a resource.

Returns a grant object that represents a permission (one of :READ, :WRITE, :READ-ACL, :WRITE-ACL, or :FULL-CONTROL) for the grantee to. For example:

  * (grant :full-control :to (acl-email "bob@example.com"))
  => #<GRANT :FULL-CONTROL to "bob@example.com">

  * (grant :read :to *all-users*)
  => #<GRANT :READ to "AllUsers">

It can be used to create or modify a grant list for use with PUT-ACL.

Returns true if a and b are equivalent ACL-related objects (person, group, email, or grant).

This acl-group includes all users, including unauthenticated clients.

This acl-group object includes only users that have an Amazon Web Services account.

This acl-group object includes the S3 system user that creates logfile objects. See also ENABLE-LOGGING-TO.

Returns an acl-email object, which can be used as a grantee for GRANT.

Returns an acl-person object for use as a resource owner (for PUT-ACL) or as a grantee (for GRANT). id must be a string representing the person's Amazon AWS canonical ID; for information about getting the canonical ID, see the Access Control Lists in the Amazon S3 developer documentation. If display-name is provided, it is used only for printing the object in Lisp; it is ignored when passed to S3.

Returns the acl-person object associated with the current credentials.

This data requires a S3 request, but the result is always the same per credentials and is cached.

Makes a resource publicly accessible, i.e. readable by the *ALL-USERS* group.

Removes public access to a resource, i.e. removes all access grants for the *ALL-USERS* group.

Adds the necessary permission grants to bucket to allow S3 to write logfile objects into it.

Changes the access control list of bucket to remove all grants for the *LOG-DELIVERY* group.

Enables logging of all requests involving bucket. Logfile objects are created in target-bucket and each logfile's key starts with target-prefix.

When a new logfile is created, its list of access control grants is extended with target-grants, if any.

If target-bucket does not have the necessary grants to allow logging, the grants are implicitly added by calling ENABLE-LOGGING-TO.

Disables logging for bucket.

If logging is enabled for bucket, returns the target bucket, target prefix, and target grants as multiple values.

When true, requests to S3 are sent via HTTPS. The default is NIL.

Returns an encoded HTML POST form policy and its signature as multiple values. The policy can be used to conditionally allow any user to put objects into S3.

expires must be a universal time after which the policy is no longer accepted.

conditions must be a list of conditions that the posted form fields must satisfy. Each condition is a list of a condition keyword, a form field name, and the form field value. For example, the following are all valid conditions:

• (:starts-with "key" "uploads/")
• (:eq "bucket" "user-uploads")
• (:eq "acl" "public-read")
• (:range "content-length-range" 1 10000)

These conditions are converted into a post policy description, base64-encoded, and returned as policy. The signature is returned as signature. These values can then be embedded in an HTML form and used to allow direct browser uploads.

For example, if policy is "YSBwYXRlbnRseSBmYWtlIHBvbGljeQ==" and the policy signature is "ZmFrZSBzaWduYXR1cmU=", you could construct a form like this:

<form action="http://user-uploads.s3.amazonaws.com/" method="post" enctype="multipart/form-data">
<input type="input" name="key" value="uploads/fun.jpg">
<input type=hidden name="acl" value="public-read">
<input type=hidden name="AWSAccessKeyId" value="8675309JGT9876430310">
<input type=hidden name="Policy" value="YSBwYXRlbnRseSBmYWtlIHBvbGljeQ==">
<input type=hidden name='Signature' value="ZmFrZSBzaWduYXR1cmU=">
<input name='file' type='file'>
<input type=submit value='Submit'>
</form>

For full, detailed documentation of browser-based POST uploads and policy documents, see Browser-Based Uploads Using POST in the Amazon S3 developer documentation.

Submits a HTTP HEAD request for the resource identified by bucket and optionally key. Returns the Drakma headers, HTTP status code, and HTTP phrase as multiple values.

When parameters is supplied, it should be an alist of keys and values to pass as GET request parameters. For example:

  * (head :bucket "zs3-demo" :parameters (parameters-alist :max-keys 0))
  => ((:X-AMZ-ID-2  . "...")
      (:X-AMZ-REQUEST-ID . "...")
      (:DATE . "Sat, 27 Sep 2008 19:00:35 GMT")
      (:CONTENT-TYPE . "application/xml")
      (:TRANSFER-ENCODING . "chunked")
      (:SERVER . "AmazonS3")
      (:CONNECTION . "close")),
      200,
      "OK"

Creates an URL that allows temporary access to a resource regardless of its ACL.

If neither bucket nor key is specified, the top-level bucket listing is accessible. If key is not specified, listing the keys of bucket is accessible. If both bucket and key are specified, the object specified by bucket and key is accessible.

expires is required, and should be the integer universal time after which the URL is no longer valid.

vhost controls the construction of the url. If vhost is nil, the constructed URL refers to the bucket, if present, as part of the path. If vhost is :AMAZON, the bucket name is used as a prefix to the Amazon hostname. If vhost is :FULL, the bucket name becomes the full hostname of the url. For example:

  * (authorized-url :bucket "foo" :key "bar" :vhost nil)
  => "http://s3.amazonaws.com/foo/bar?..."

  * (authorized-url :bucket "foo" :key "bar" :vhost :amazon)
  => "http://foo.s3.amazonaws.com/bar?..."

  * (authorized-url :bucket "foo.example.com" :key "bar" :vhost :full)
  =>  "http://foo.example.com/bar?..."

If ssl is true, the URL has "https" as the scheme, otherwise it has "http".

If sub-resource is specified, it is used as part of the query string to access a specific sub-resource. Example Amazon sub-resources include "acl" for access to the ACL, "location" for location information, and "logging" for logging information. For more information about the various sub-resources, see the Amazon S3 developer documentation.

Returns an URL that can be used to reference a resource. See AUTHORIZED-URL for more info.

Returns a vector of type (simple-array (unsigned-byte 8) (*)) initialized with octets.

Returns a universal time that represents the current time incremented by delta seconds. It's useful for passing as the :EXPIRES parameter to functions like PUT-OBJECT and AUTHORIZED-URL.

Like NOW+, but decrements the current time instead of incrementing it.

Returns the etag of pathname. This can be useful for the conditional arguments :WHEN-ETAG-MATCHES and :UNLESS-ETAG-MATCHES in GET-OBJECT and COPY-OBJECT.

Returns an alist based on all keyword arguments passed to the function. Keywords are converted to their lowercase symbol name and values are converted to strings. For example:

  * (parameters-alist :name "Bob" :age 21)
  => (("name" . "Bob") ("age" . "21"))

This can be used to construct Amazon metadata alists for PUT-OBJECT and COPY-OBJECT, or request parameters in HEAD.

Clear ZS3's internal cache of redirections.

Most ZS3 requests are submitted against the Amazon S3 endpoint "s3.amazonaws.com". Some requests, however, are permanently redirected by S3 to new endpoints. ZS3 maintains an internal cache of permanent redirects, but it's possible for that cache to get out of sync if external processes alter the bucket structure

For example, if the bucket "eu.zs3" is created with a EU location constraint, S3 will respond to requests to that bucket with a permanent redirect to "eu.zs3.s3.amazonaws.com", and ZS3 will cache that redirect information. But if the bucket is deleted and recreated by a third party, the redirect might no longer be necessary.

Returns a list of all distributions.

Creates and returns a new distribution object that will cache objects from the bucket named by bucket-name.

If cnames is provided, it is taken as a designator for a list of additional domain names that can be used to access the distribution.

If enabled is NIL, the distribution is initially created in a disabled state. The default value is is T.

If comment is provided, it becomes part of the newly created distribution.

Deletes distribution. Distributions must be disabled before deletion; see DISABLE.

Queries Amazon for the latest information regarding distribution and destructively modifies the instance with the new information. Returns its argument.

Enables distribution.

Disables distribution.

Adds cname to the CNAMEs of distribution, if necessary.

Removes cname from the CNAMEs of distribution.

Sets the comment of distribution to comment.

Returns a list of distributions that have bucket-name as the origin bucket.

All errors signaled as a result of a CloudFront request error are subtypes of distribution-error.

Distributions must be fully disabled before they are deleted. If they have not been disabled, or the status of the distribution is still "InProgress", distribution-not-disabled is signaled.

A CNAME may only appear on one distribution. If you attempt to add a CNAME to a distribution that is already present on some other distribution, cname-already-exists is signaled.

If creating a new distribution via CREATE-DISTRIBUTION would exceed the account limit of total distributions, too-many-distributions is signaled.

Returns a string describing the status of distribution. The status is either "InProgress", meaning that the distribution's configuration has not fully propagated through the CloudFront system, or "Deployed".

Returns the origin bucket for distribution. It is different from a normal ZS3 bucket name, because it has ".s3.amazonaws.com" as a suffix.

Returns the domain name through which CloudFront-enabled access to a resource may be made.

Returns a list of CNAMEs associated with distribution.

Returns true if distribution is enabled, NIL otherwise.

Initiates the invalidation of resources identified by paths in distribution. paths should consist of key names that correspond to objects in the distribution's S3 bucket.

The invalidation object reports on the status of the invalidation request. It can be queried with STATUS and refreshed with REFRESH.

* (invalidate-paths distribution '("/css/site.css" "/js/site.js"))
#<INVALIDATION "I1HJC711OFAVKO" [InProgress]>
* (progn (sleep 300) (refresh *))
#<INVALIDATION "I1HJC711OFAVKO" [Completed]>