session

Documentation

Overview

Package session provides server-side session authentication for the Gas ecosystem. It implements gas.Authenticator, gas.PrincipalRevoker, and gas.Service.

Index

• func New(opts ...Option) ...
• type Config
  • func DefaultConfig() *Config
  • func (c *Config) Validate() error
• type Option
  • func WithConfig(cfg *Config) Option
• type Provider
• type Service
  • func (s *Service) Authenticate(ctx context.Context, r *http.Request) (gas.Principal, error)
  • func (s *Service) ClearCookie(w http.ResponseWriter)
  • func (s *Service) Close() error
  • func (s *Service) Create(ctx context.Context, subject string, meta gas.BasePrincipalMetadata, ...) (*Session, error)
  • func (s *Service) Init() error
  • func (s *Service) Name() string
  • func (s *Service) Revoke(ctx context.Context, principal gas.Principal) error
  • func (s *Service) RevokeAll(ctx context.Context, subject string) error
  • func (s *Service) RevokeAllByScheme(ctx context.Context, subject, scheme string) error
  • func (s *Service) SetCookie(w http.ResponseWriter, session *Session)
• type Session
• type Settings

Functions

func New

func New(opts ...Option) func(gas.DatabaseProvider, gas.Logger, gas.MigrationManager, gas.ConfigProvider) *Service

New captures options and returns a DI-injectable constructor.

Types

type Config

type Config struct {
	env.WithGasEnv

	Session Settings
}

Config holds session service settings.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks the Config for correctness.

type Option

type Option func(*Service)

Option configures a Service.

func WithConfig

func WithConfig(cfg *Config) Option

WithConfig sets a custom configuration, skipping auto-bind from ConfigProvider.

type Provider

type Provider interface {
	// Authenticate reads a session ID from the configured cookie, looks it up
	// in the database, validates expiry, and optionally extends the TTL.
	Authenticate(ctx context.Context, r *http.Request) (gas.Principal, error)
	// Revoke deletes a session by the principal's credential ID.
	Revoke(ctx context.Context, principal gas.Principal) error
	// RevokeAll deletes all sessions for the given subject.
	RevokeAll(ctx context.Context, subject string) error
	// RevokeAllByScheme delegates to RevokeAll if the scheme is "session",
	// otherwise it is a no-op.
	RevokeAllByScheme(ctx context.Context, subject, scheme string) error
	// Create generates a cryptographically random session ID, stores the session
	// in the database, and returns it. The caller is responsible for calling
	// SetCookie afterward. The *http.Request is used to capture IP and user agent.
	Create(ctx context.Context, subject string, meta gas.BasePrincipalMetadata, r *http.Request) (*Session, error)
	// SetCookie writes the session cookie to the response.
	SetCookie(w http.ResponseWriter, session *Session)
	// ClearCookie writes an expired cookie to the response, effectively removing it.
	ClearCookie(w http.ResponseWriter)
}

Provider is an interface for managing session-based authentication and authorization.

type Service

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

Service is a session authenticator implementing gas.Authenticator, gas.PrincipalRevoker, and gas.Service.

func (*Service) Authenticate

func (s *Service) Authenticate(ctx context.Context, r *http.Request) (gas.Principal, error)

Authenticate reads a session ID from the configured cookie, looks it up in the database, validates expiry, and optionally extends the TTL.

func (*Service) ClearCookie

func (s *Service) ClearCookie(w http.ResponseWriter)

ClearCookie writes an expired cookie to the response, effectively removing it.

func (*Service) Close

func (s *Service) Close() error

Close stops the background cleanup goroutine.

func (*Service) Create

func (s *Service) Create(ctx context.Context, subject string, meta gas.BasePrincipalMetadata, r *http.Request) (*Session, error)

Create generates a cryptographically random session ID, stores the session in the database, and returns it. The caller is responsible for calling SetCookie afterward. The *http.Request is used to capture IP and user agent.

func (*Service) Init

func (s *Service) Init() error

Init validates configuration, initializes the store, and starts the background cleanup goroutine.

func (*Service) Name

func (s *Service) Name() string

Name returns the service identifier.

func (*Service) Revoke

func (s *Service) Revoke(ctx context.Context, principal gas.Principal) error

Revoke deletes a session by the principal's credential ID.

func (*Service) RevokeAll

func (s *Service) RevokeAll(ctx context.Context, subject string) error

RevokeAll deletes all sessions for the given subject.

func (*Service) RevokeAllByScheme

func (s *Service) RevokeAllByScheme(ctx context.Context, subject, scheme string) error

RevokeAllByScheme delegates to RevokeAll if the scheme is "session", otherwise it is a no-op.

func (*Service) SetCookie

func (s *Service) SetCookie(w http.ResponseWriter, session *Session)

SetCookie writes the session cookie to the response.

type Session

type Session struct {
	CreatedAt  time.Time
	ExpiresAt  time.Time
	LastActive time.Time
	Metadata   gas.BasePrincipalMetadata
	ID         string
	Subject    string
	IPAddress  string
	UserAgent  string
}

Session represents a user session with associated metadata, identifiers, and timestamps.

type Settings

type Settings struct {
	CookieName      string
	CookiePath      string
	CookieDomain    string
	CookieSameSite  http.SameSite
	SessionTTL      time.Duration
	CleanupInterval time.Duration
	CleanupTimeout  time.Duration
	CookieSecure    bool
	CookieHTTPOnly  bool
	ExtendOnAccess  bool
}

Settings represents the session configuration values.