Package fitbit: Log signatures on failure.

[kraftakt.git] / fitbit / fitbit.go

diff --git a/fitbit/fitbit.go b/fitbit/fitbit.go
index 8a07fb7..9466b12 100644 (file)
--- a/fitbit/fitbit.go
+++ b/fitbit/fitbit.go
@@ -1,3 +1,4 @@
+// Package fitbit implements functions to interact with the Fitbit API.
 package fitbit
 
 import (
@@ -5,6 +6,7 @@ import (
        "crypto/hmac"
        "crypto/sha1"
        "encoding/base64"
+       "encoding/hex"
        "encoding/json"
        "fmt"
        "io/ioutil"
@@ -34,10 +36,14 @@ func oauthConfig() *oauth2.Config {
        }
 }
 
+// AuthURL returns the URL of the Fitbit consent screen. Users are redirected
+// there to approve Fitbit minting an OAuth2 token for us.
 func AuthURL(ctx context.Context, u *app.User) string {
        return oauthConfig().AuthCodeURL(u.Sign("Fitbit"), oauth2.AccessTypeOffline)
 }
 
+// ParseToken parses the request of the user being redirected back from the
+// consent screen. The parsed token is stored in u using SetToken().
 func ParseToken(ctx context.Context, r *http.Request, u *app.User) error {
        if state := r.FormValue("state"); state != u.Sign("Fitbit") {
                return fmt.Errorf("invalid state parameter: %q", state)
@@ -51,6 +57,9 @@ func ParseToken(ctx context.Context, r *http.Request, u *app.User) error {
        return u.SetToken(ctx, "Fitbit", tok)
 }
 
+// CheckSignature validates that rawSig is a valid signature of payload. This
+// is used by the Fitbit API to ansure that the receiver can verify that the
+// sender has access to the OAuth2 client secret.
 func CheckSignature(ctx context.Context, payload []byte, rawSig string) bool {
        signatureGot, err := base64.StdEncoding.DecodeString(rawSig)
        if err != nil {
@@ -62,6 +71,12 @@ func CheckSignature(ctx context.Context, payload []byte, rawSig string) bool {
        mac.Write(payload)
        signatureWant := mac.Sum(nil)
 
+       if !hmac.Equal(signatureGot, signatureWant) {
+               log.Debugf(ctx, "CheckSignature(): got %q, want %q",
+                       hex.EncodeToString(signatureGot),
+                       hex.EncodeToString(signatureWant))
+       }
+
        return hmac.Equal(signatureGot, signatureWant)
 }
 
@@ -160,6 +175,9 @@ func NewClient(ctx context.Context, fitbitUserID string, u *app.User) (*Client,
        }, nil
 }
 
+// ActivitySummary returns the daily activity summary.
+//
+// See https://dev.fitbit.com/build/reference/web-api/activity/#get-daily-activity-summary for details.
 func (c *Client) ActivitySummary(ctx context.Context, date string) (*ActivitySummary, error) {
        url := fmt.Sprintf("https://api.fitbit.com/1/user/%s/activities/date/%s.json",
                c.fitbitUserID, date)
@@ -170,7 +188,10 @@ func (c *Client) ActivitySummary(ctx context.Context, date string) (*ActivitySum
        }
        defer res.Body.Close()
 
-       data, _ := ioutil.ReadAll(res.Body)
+       data, err := ioutil.ReadAll(res.Body)
+       if err != nil {
+               return nil, err
+       }
        log.Debugf(ctx, "GET %s -> %s", url, data)
 
        var summary ActivitySummary
@@ -185,11 +206,17 @@ func (c *Client) subscriberID(collection string) string {
        return fmt.Sprintf("%s:%s", c.appUser.ID, collection)
 }
 
+// UserFromSubscriberID parses the user ID from the subscriber ID and calls
+// app.UserByID() with the user ID.
 func UserFromSubscriberID(ctx context.Context, subscriberID string) (*app.User, error) {
        uid := strings.Split(subscriberID, ":")[0]
        return app.UserByID(ctx, uid)
 }
 
+// Subscribe subscribes to one collection of the user. It uses a per-collection
+// subscription ID so that we can subscribe to more than one collection.
+//
+// See https://dev.fitbit.com/build/reference/web-api/subscriptions/#adding-a-subscription for details.
 func (c *Client) Subscribe(ctx context.Context, collection string) error {
        url := fmt.Sprintf("https://api.fitbit.com/1/user/%s/%s/apiSubscriptions/%s.json",
                c.fitbitUserID, collection, c.subscriberID(collection))
@@ -241,6 +268,10 @@ func (c *Client) unsubscribe(ctx context.Context, userID, collection, subscripti
        return nil
 }
 
+// UnsubscribeAll gets a list of all subscriptions we have with the user's
+// account and deletes all found subscriptions.
+//
+// See https://dev.fitbit.com/build/reference/web-api/subscriptions/#deleting-a-subscription for details.
 func (c *Client) UnsubscribeAll(ctx context.Context) error {
        var errs appengine.MultiError
 
@@ -264,6 +295,8 @@ func (c *Client) UnsubscribeAll(ctx context.Context) error {
        return nil
 }
 
+// ListSubscriptions returns a list of all subscriptions for a given collection
+// the OAuth2 client has to a user's account.
 func (c *Client) ListSubscriptions(ctx context.Context, collection string) ([]Subscription, error) {
        url := fmt.Sprintf("https://api.fitbit.com/1/user/%s/%s/apiSubscriptions.json", c.fitbitUserID, collection)
        res, err := c.client.Get(url)
@@ -316,21 +349,25 @@ func (c *Client) ListSubscriptions(ctx context.Context, collection string) ([]Su
        }
 
        for _, err := range errs {
-               log.Warningf(ctx, err)
+               log.Warningf(ctx, "%v", err)
        }
 
        return ret, nil
 }
 
+// DeleteToken deletes the Fitbit OAuth2 token.
 func (c *Client) DeleteToken(ctx context.Context) error {
        return c.appUser.DeleteToken(ctx, "Fitbit")
 }
 
+// Provile contains data about the user.
+// It only contains the subset of fields required by Kraftakt.
 type Profile struct {
        Name     string
        Timezone *time.Location
 }
 
+// Profile returns the profile information of the user.
 func (c *Client) Profile(ctx context.Context) (*Profile, error) {
        res, err := c.client.Get("https://api.fitbit.com/1/user/-/profile.json")
        if err != nil {