revamp the Headers API

1. Move common methods of AccountHeaders, ContainerHeaders,
   ObjectHeaders into a base type Headers.

2. Fold Headers into RequestOptions to remove one of the two optional
   arguments on request methods. The new Headers.ToOpts() method
   offers a nice experience for users passing Headers to request
   methods.

   The Update() methods keep the explicit Headers argument since the
   Headers argument is not optional there.

   The only downside is that we lose a bit of type-safety because
   RequestOptions takes any Headers instance, so e.g. ContainerHeaders
   could be passed to Object.Upload(). I believe the benefits outweigh
   this problem.

1 files changed, 65 insertions, 11 deletions

diff --git a/headers.go b/headers.go
index 7a6ec16..88c1a63 100644
--- a/headers.go
+++ b/headers.go
@@ -23,7 +23,56 @@ import (
 	"net/textproto"
 )
 
-func headersToHTTP(h map[string]string) http.Header {
+//Headers represents a set of request headers or response headers.
+//
+//Users will typically use one of the subtypes (AccountHeaders,
+//ContainerHeaders, ObjectHeaders) instead, which provide type-safe access to
+//well-known headers. The http.Header-like interface on this type can be used
+//read and write arbitary headers. For example, the following calls are
+//equivalent:
+//
+//	h := make(AccountHeaders)
+//	h.Headers.Set("X-Account-Meta-Quota-Bytes", "1048576")
+//	h.BytesUsedQuota().Set(1048576)
+//
+type Headers map[string]string
+
+//Clear sets the value for the specified header to the empty string. When the
+//Headers instance is then sent to the server with Update(), the server will
+//delete the value for that header; cf. Del().
+func (h Headers) Clear(key string) {
+	h[textproto.CanonicalMIMEHeaderKey(key)] = ""
+}
+
+//Del deletes a key from the Headers instance. When the Headers instance is
+//then sent to the server with Update(), a key which has been deleted with
+//Del() will remain unchanged on the server.
+//
+//For most writable attributes, a key which has been deleted with Del() will
+//remain unchanged on the server. To remove the key on the server, use Clear()
+//instead.
+//
+//For object metadata (but not other object attributes), deleting a key will
+//cause that key to be deleted on the server. Del() is identical to Clear() in
+//this case.
+func (h Headers) Del(key string) {
+	delete(h, textproto.CanonicalMIMEHeaderKey(key))
+}
+
+//Get returns the value for the specified header.
+func (h Headers) Get(key string) string {
+	return h[textproto.CanonicalMIMEHeaderKey(key)]
+}
+
+//Set sets a new value for the specified header. Any existing value will be
+//overwritten.
+func (h Headers) Set(key, value string) {
+	h[textproto.CanonicalMIMEHeaderKey(key)] = value
+}
+
+//ToHTTP converts this Headers instance into the equivalent http.Header
+//instance. The return value is guaranteed to be non-nil.
+func (h Headers) ToHTTP() http.Header {
 	dest := make(http.Header, len(h))
 	for k, v := range h {
 		dest.Set(k, v)
@@ -31,19 +80,24 @@ func headersToHTTP(h map[string]string) http.Header {
 	return dest
 }
 
-func headersFromHTTP(src http.Header) map[string]string {
-	h := make(map[string]string, len(src))
+//ToOpts wraps this Headers instance into a RequestOpts instance, so that it
+//can be passed to Schwift's various request methods.
+//
+//	hdr := NewObjectHeaders()
+//	hdr.ContentType().Set("image/png")
+//	hdr.Metadata().Set("color", "blue")
+//	obj.Upload(content, hdr.ToOpts())
+//
+func (h Headers) ToOpts() *RequestOptions {
+	return &RequestOptions{Headers: h}
+}
+
+func headersFromHTTP(src http.Header) Headers {
+	h := make(Headers, len(src))
 	for k, v := range src {
 		if len(v) > 0 {
-			h[textproto.CanonicalMIMEHeaderKey(k)] = v[0]
+			h.Set(k, v[0])
 		}
 	}
 	return h
 }
-
-type headerInterface interface {
-	Clear(string)
-	Del(string)
-	Get(string) string
-	Set(string, string)
-}