// Package session defines the authenticated session-cache contract used by the
// gateway hot path.
package session

import (
	"context"
	"errors"
)

var (
	// ErrNotFound reports that SessionCache does not currently contain the
	// requested device session identifier.
	ErrNotFound = errors.New("session cache record not found")
)

// Cache resolves authenticated device-session state from the gateway hot-path
// cache.
type Cache interface {
	// Lookup returns the cached record for deviceSessionID. Implementations must
	// wrap ErrNotFound when the cache does not contain the requested record.
	Lookup(ctx context.Context, deviceSessionID string) (Record, error)
}

// SnapshotStore stores mutable session record snapshots inside one gateway
// process and exposes the same read contract as Cache for the hot path.
type SnapshotStore interface {
	Cache

	// Upsert stores record under record.DeviceSessionID, replacing any previous
	// snapshot for that session.
	Upsert(record Record) error

	// Delete removes the local snapshot for deviceSessionID when it exists.
	Delete(deviceSessionID string)
}

// Status identifies the cached lifecycle state of a device session.
type Status string

const (
	// StatusActive reports that the cached device session may continue through
	// later authenticated gateway checks.
	StatusActive Status = "active"

	// StatusRevoked reports that the cached device session has been revoked and
	// must be rejected before later auth steps run.
	StatusRevoked Status = "revoked"
)

// Record is the minimum authenticated session state required by the gateway
// before signature verification begins.
type Record struct {
	// DeviceSessionID is the stable device-session identifier resolved from the
	// hot-path cache.
	DeviceSessionID string

	// UserID is the authenticated user identity bound to DeviceSessionID.
	UserID string

	// ClientPublicKey is the standard base64-encoded raw Ed25519 public key
	// material used for request-signature verification.
	ClientPublicKey string

	// Status reports whether the cached session is active or revoked.
	Status Status

	// RevokedAtMS optionally records when the device session was revoked.
	RevokedAtMS *int64
}

// IsKnown reports whether s is one of the session states supported by the
// gateway.
func (s Status) IsKnown() bool {
	switch s {
	case StatusActive, StatusRevoked:
		return true
	default:
		return false
	}
}