session

type Config struct {
	// Prefix is the app prefix; tokens are "<Prefix>s_<body>".
	Prefix string
	// Store persists sessions.
	Store Store
	// IdleTTL expires a session unused for this long. Default 30 days. Never
	// means no idle expiry.
	IdleTTL time.Duration
	// MaxTTL expires a session this long after creation regardless of use.
	// Default 90 days. Never means no max expiry.
	MaxTTL time.Duration
	// RotateAfter replaces the token on the first use after this age.
	// Default 1 hour. Never means never rotate.
	RotateAfter time.Duration
	// Grace keeps the previous token valid this long after the rotation
	// while the new token is unused, and this long after the new token's
	// first use once it is used, so requests already in flight from other
	// tabs still succeed. Default 60s. Must be bounded: Never is rejected.
	// The new token reaches the client only with the response of the request
	// that rotated, so Grace must exceed the slowest authenticated handler of
	// the application; a client that aborts a rotating request before the
	// response arrives costs the user a login.
	Grace time.Duration
	// TouchEvery bounds how often LastUsedAt is written: a request that
	// changes nothing else skips the write while the stored value is younger
	// than this. Default 1 minute. Never is rejected, and so is a value not
	// shorter than IdleTTL, which would expire sessions in active use, or
	// shorter than one second, which would write on every request and make
	// concurrent requests on one session fail on the optimistic lock.
	TouchEvery time.Duration
}

type Manager struct {
	// contains filtered or unexported fields
}

type Record struct {
	Session
	TokenHash    []byte
	PreviousHash []byte
	Revision     int64
}

type Session struct {
	ID         string
	Subject    string
	CreatedAt  time.Time
	LastUsedAt time.Time
	RotatedAt  time.Time
	// FirstUsedAt is when the current token was first presented, zero until
	// then.
	FirstUsedAt time.Time
	// ExpiresAt is CreatedAt plus MaxTTL, zero when MaxTTL is Never.
	ExpiresAt time.Time
}

type Store interface {
	Insert(ctx context.Context, r Record) error
	// FindByHash returns the record whose current token hash or previous
	// token hash equals hash: the Manager decides whether a previous hash is
	// still accepted. ez.ENOTFOUND when there is none.
	FindByHash(ctx context.Context, hash []byte) (Record, error)
	// Update writes every mutable column of r (token hash, previous hash,
	// first used, last used, rotated and expires at) to the
	// session r.ID whose revision is still r.Revision, and sets its revision
	// to r.Revision+1, in one conditional write (UPDATE ... SET revision =
	// r.Revision+1 WHERE id = ? AND revision = ?). A request whose read is
	// stale therefore cannot overwrite a concurrent write, whether that
	// write rotated the token or only recorded its first use. Returns
	// ez.ENOTFOUND when no row matched: the session changed or is gone.
	Update(ctx context.Context, r Record) error
	// Delete removes the session id whatever its revision; a session that is
	// already gone is not an error. Revoke uses it: an explicit revocation
	// wins over any concurrent use.
	Delete(ctx context.Context, id string) error
	// DeleteRevision removes the session id only while its revision is still
	// revision, in one conditional write (DELETE ... WHERE id = ? AND
	// revision = ?). Resolve uses it to delete an expired or reused
	// session, so a request whose read is stale cannot delete a session that a
	// concurrent request has just used. A custom Store must implement it as
	// one atomic compare-and-delete, never as a read followed by Delete.
	// Returns ez.ENOTFOUND when no row matched: the session changed or is
	// gone.
	DeleteRevision(ctx context.Context, id string, revision int64) error
	DeleteBySubject(ctx context.Context, subject string) error
	// DeleteExpired removes every session whose ExpiresAt is set and not
	// after now and, when idleBefore is not zero, every session whose
	// LastUsedAt is not after idleBefore, whatever its revision. A session
	// with a zero ExpiresAt (MaxTTL Never) never matches the first rule.
	// Sweep uses it. Returns how many sessions it removed.
	DeleteExpired(ctx context.Context, now, idleBefore time.Time) (int64, error)
}