Proposal for a stateful data structure

[mcrumm]

Related to #7, a proposal to persist the URL struct through the signing process:

Guss.URL

This module defines a Guss.URL struct and the main functions
for composing signed URLs.

Object fields

These fields contain storage object information:

• bucket - the storage bucket name as a binary
• objectname - the storage object name as a binary
• method - the request method as an atom, example: :put, default: :get
• host - the requested host as a binary, default: "storage.googleapis.com"

Header fields

These fields contain content metadata:

• content_md5 - the MD5 digest value in Base64
• content_type - the content type as a binary, example: "text/plain", default: "application/octet-stream"
• extensions - canonical extension headers as a keyword, example: [acl: :public_read, meta: [project: [name: "Guss"]]]

Signature fields

• expires - the timestamp when the signature expires, defaults to one hour in the future
• signed - internal structure for composing the signed URL
• state - the signature state

The signature state is used to track the signature process. It starts as
:unset but is changed to :set (via sign/2). Its final result is
:signed (via sign_url/2).

Guss.Signature

Fields

• uri - the signed URL as a URI
• headers - the request headers composed in the signature as a map, example: %{"x-goog-acl" => "public-read", "x-goog-meta-project-name" => "Guss"}
• private - internal data as a map

Functions

Guss.URL.sign/2

Sets the URL signing credentials to the given account.

It sets the signature state to :set (if not already :set) and raises Guss.URL.AlreadySignedError if it was already :signed.

If you also want to sign the URL, use sign_url/1 after this or use sign_url/2.

Guss.URL.sign_url/2

Signs the URL (via Guss.Signature.generate/2).

It sets the signature state to :signed and raises Guss.AlreadySignedError if the URL has already been signed.

Once the URL has been signed, the signed values can be accessed at url.signed.uri and url.signed.headers