Relative expiration times

[technoweenie]

The Batch API and git-lfs-authenticate ssh call both can optionally return an expires_at marking when an authentication token expires. The client uses this hint to know if it should attempt the request, or get a fresh token. However, this causes problems for users with incorrect times.

Proposal: Introduce expires_in, which returns the number of seconds the token is valid. This should take precedence over an existing expires_at property.

[ttaylorr]

I think this is a great call, I'm definitely for adding this to the API. I've been wondering this morning about how we should implement this in the client. I have a few thoughts:

1. Expand both APIs to include the following type signature:

type T struct {
        // ...
        ExpiresAt time.Time
        ExpiresIn time.Duration
}

func (t *T) IsExpiredWithin(d time.Duration) bool { ... }

Which would definitely work, I'm just not sure I like exposing both ExpiresAt and ExpiresIn as public fields. That could be good, but I'm not sure where a caller would need to care.

2. Another thought is that we could have a new function:

package tools

func ParseExpiresAtOrIn(r io.Reader) (time.Duration, error) { ... }

Which would work and simplifies the signature of both API types, but also introduces a new function and an additional parse step.

At a broader scope, I like this change because we don't have to break existing APIs, and we can deprecate the expires_at property at a later, major version bump of the API.

[technoweenie]

ParseExpiresAtOrIn(r io.Reader): What is io.Reader in this scenario? I'm totally fine with adding both a new public property to a json-decoded struct, since it will be a public property of the API.

[ttaylorr]

ParseExpiresAtOrIn(r io.Reader): What is io.Reader in this scenario?

I think in this case it'd be a reader that dispenses JSON, so that we could feed it to encoding/json.NewDecoder().

Either way, I'm fine with just adding a new property to each API's type.