heal: Add ListBucketsHeal object API (#3563)

ListBucketsHeal will list which buckets that need to be healed:
  * ListBucketsHeal() (buckets []BucketInfo, err error)

pkg/madmin/API.md

@@ -171,8 +171,8 @@ __Example__
             log.Fatalln(err)
             return
         }
-        if object.HealInfo != nil {
-            switch healInfo := *object.HealInfo; healInfo.Status {
+        if object.HealObjectInfo != nil {
+            switch healInfo := *object.HealObjectInfo; healInfo.Status {
             case madmin.CanHeal:
                 fmt.Println(object.Key, " can be healed.")
             case madmin.QuorumUnavailable:
@@ -185,6 +185,34 @@ __Example__
     }
 ```
 
+<a name="ListBucketsList"></a>
+### ListBucketsList() error
+If successful returns information on the list of buckets that need healing.
+
+__Example__
+
+``` go
+    // List buckets that need healing 
+    healBucketsList, err := madmClnt.ListBucketsHeal()
+    if err != nil {
+        fmt.Println(err)
+        return
+    }
+    for bucket := range healBucketsList {
+        if bucket.HealBucketInfo != nil {
+            switch healInfo := *object.HealBucketInfo; healInfo.Status {
+            case madmin.CanHeal:
+                fmt.Println(bucket.Key, " can be healed.")
+            case madmin.QuorumUnavailable:
+                fmt.Println(bucket.Key, " can't be healed until quorum is available.")
+            case madmin.Corrupted:
+                fmt.Println(bucket.Key, " can't be healed, not enough information.")
+            }
+        }
+        fmt.Println("bucket: ", bucket)
+    }
+```
+
 <a name="HealBucket"></a>
 ### HealBucket(bucket string, isDryRun bool) error
 If bucket is successfully healed returns nil, otherwise returns error indicating the reason for failure. If isDryRun is true, then the bucket is not healed, but heal bucket request is validated by the server. e.g, if the bucket exists, if bucket name is valid etc.

pkg/madmin/examples/heal-buckets-list.go

@@ -0,0 +1,60 @@
+// +build ignore
+
+package main
+
+/*
+ * Minio Cloud Storage, (C) 2017 Minio, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/minio/minio/pkg/madmin"
+)
+
+func main() {
+
+	// Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY are
+	// dummy values, please replace them with original values.
+
+	// API requests are secure (HTTPS) if secure=true and insecure (HTTPS) otherwise.
+	// New returns an Minio Admin client object.
+	madmClnt, err := madmin.New("your-minio.example.com:9000", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", true)
+	if err != nil {
+		log.Fatalln(err)
+	}
+
+	// List buckets that need healing
+	healBucketsList, err := madmClnt.ListBucketsHeal()
+	if err != nil {
+		log.Fatalln(err)
+	}
+
+	for _, bucket := range healBucketsList {
+		if bucket.HealBucketInfo != nil {
+			switch healInfo := *bucket.HealBucketInfo; healInfo.Status {
+			case madmin.CanHeal:
+				fmt.Println(bucket.Name, " can be healed.")
+			case madmin.QuorumUnavailable:
+				fmt.Println(bucket.Name, " can't be healed until quorum is available.")
+			case madmin.Corrupted:
+				fmt.Println(bucket.Name, " can't be healed, not enough information.")
+			}
+		}
+		fmt.Println("bucket: ", bucket)
+	}
+}

pkg/madmin/heal-commands.go

@@ -63,20 +63,65 @@ type commonPrefix struct {
 	Prefix string
 }
 
+// Owner - bucket owner/principal
+type Owner struct {
+	ID          string
+	DisplayName string
+}
+
+// Bucket container for bucket metadata
+type Bucket struct {
+	Name         string
+	CreationDate string // time string of format "2006-01-02T15:04:05.000Z"
+
+	HealBucketInfo *HealBucketInfo `xml:"HealBucketInfo,omitempty"`
+}
+
+// ListBucketsHealResponse - format for list buckets response
+type ListBucketsHealResponse struct {
+	XMLName xml.Name `xml:"http://s3.amazonaws.com/doc/2006-03-01/ ListAllMyBucketsResult" json:"-"`
+
+	Owner Owner
+
+	// Container for one or more buckets.
+	Buckets struct {
+		Buckets []Bucket `xml:"Bucket"`
+	} // Buckets are nested
+}
+
 // HealStatus - represents different states of healing an object could be in.
 type healStatus int
 
 const (
+	// Healthy - Object that is already healthy
+	Healthy healStatus = iota
 	// CanHeal - Object can be healed
-	CanHeal healStatus = iota
+	CanHeal
 	// Corrupted - Object can't be healed
 	Corrupted
 	// QuorumUnavailable - Object can't be healed until read quorum is available
 	QuorumUnavailable
 )
 
-// HealInfo - represents healing related information of an object.
-type HealInfo struct {
+// HealBucketInfo - represents healing related information of a bucket.
+type HealBucketInfo struct {
+	Status healStatus
+}
+
+// BucketInfo - represents bucket metadata.
+type BucketInfo struct {
+	// Name of the bucket.
+	Name string
+
+	// Date and time when the bucket was created.
+	Created time.Time
+
+	// Healing information
+	HealBucketInfo *HealBucketInfo `xml:"HealBucketInfo,omitempty"`
+}
+
+// HealObjectInfo - represents healing related information of an object.
+type HealObjectInfo struct {
 	Status              healStatus
 	MissingDataCount    int
 	MissingPartityCount int
@@ -108,8 +153,8 @@ type ObjectInfo struct {
 	StorageClass string `json:"storageClass"`
 
 	// Error
-	Err      error     `json:"-"`
-	HealInfo *HealInfo `json:"healInfo,omitempty"`
+	Err            error           `json:"-"`
+	HealObjectInfo *HealObjectInfo `json:"healObjectInfo,omitempty"`
 }
 
 type healQueryKey string
@@ -143,7 +188,7 @@ func (adm *AdminClient) listObjectsHeal(bucket, prefix, delimiter, marker string
 	queryVal := mkHealQueryVal(bucket, prefix, marker, delimiter, maxKeyStr)
 
 	hdrs := make(http.Header)
-	hdrs.Set(minioAdminOpHeader, "list")
+	hdrs.Set(minioAdminOpHeader, "list-objects")
 
 	reqData := requestData{
 		queryValues:   queryVal,
@@ -240,6 +285,58 @@ func (adm *AdminClient) ListObjectsHeal(bucket, prefix string, recursive bool, d
 	return objectStatCh, nil
 }
 
+const timeFormatAMZLong = "2006-01-02T15:04:05.000Z" // Reply date format with nanosecond precision.
+
+// ListBucketsHeal - issues heal bucket list API request
+func (adm *AdminClient) ListBucketsHeal() ([]BucketInfo, error) {
+	queryVal := url.Values{}
+	queryVal.Set("heal", "")
+
+	hdrs := make(http.Header)
+	hdrs.Set(minioAdminOpHeader, "list-buckets")
+
+	reqData := requestData{
+		queryValues:   queryVal,
+		customHeaders: hdrs,
+	}
+
+	// Execute GET on /?heal to list objects needing heal.
+	resp, err := adm.executeMethod("GET", reqData)
+
+	defer closeResponse(resp)
+	if err != nil {
+		return []BucketInfo{}, err
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return []BucketInfo{}, errors.New("Got HTTP Status: " + resp.Status)
+	}
+
+	var listBucketsHealResult ListBucketsHealResponse
+
+	err = xml.NewDecoder(resp.Body).Decode(&listBucketsHealResult)
+	if err != nil {
+		return []BucketInfo{}, err
+	}
+
+	var bucketsToBeHealed []BucketInfo
+
+	for _, bucket := range listBucketsHealResult.Buckets.Buckets {
+		creationDate, err := time.Parse(timeFormatAMZLong, bucket.CreationDate)
+		if err != nil {
+			return []BucketInfo{}, err
+		}
+		bucketsToBeHealed = append(bucketsToBeHealed,
+			BucketInfo{
+				Name:           bucket.Name,
+				Created:        creationDate,
+				HealBucketInfo: bucket.HealBucketInfo,
+			})
+	}
+
+	return bucketsToBeHealed, nil
+}
+
 // HealBucket - Heal the given bucket
 func (adm *AdminClient) HealBucket(bucket string, dryrun bool) error {
 	// Construct query params.