sessions

Documentation

Index

• type CookieConfig
• type CookieOption
  • func WithDomain(domain string) CookieOption
  • func WithHttpOnly(b bool) CookieOption
  • func WithName(name string) CookieOption
  • func WithPartitioned(b bool) CookieOption
  • func WithPath(path string) CookieOption
  • func WithSameSite(s http.SameSite) CookieOption
  • func WithSecure(b bool) CookieOption
• type CookieResponseWriter
  • func (crw *CookieResponseWriter) SetCookie()
  • func (crw *CookieResponseWriter) Write(b []byte) (int, error)
  • func (crw *CookieResponseWriter) WriteHeader(code int)
• type Encoder
  • func NewGobEncoder() Encoder
• type ErrHandler
• type GobEncoder
  • func (e *GobEncoder) Marshal(data any) ([]byte, error)
  • func (e *GobEncoder) Unmarshal(encoded []byte, dest any) error
• type Session
• type SessionManager
  • func NewSessionManager(opts ...SessionManagerOption) *SessionManager
  • func (sm *SessionManager) Commit(ctx context.Context, session *Session) error
  • func (sm *SessionManager) CookieSessions(opts ...CookieOption) quicky.MiddlewareFunc
  • func (sm *SessionManager) DeleteManySessions(ctx context.Context, sessionIds ...string) error
  • func (sm *SessionManager) DeleteSession(ctx context.Context, sessionId string) error
  • func (sm *SessionManager) DeleteValue(ctx context.Context, key string)
  • func (sm *SessionManager) Destroy(ctx context.Context)
  • func (sm *SessionManager) GetSession(ctx context.Context, sessionId string) (session *Session, ok bool, err error)
  • func (sm *SessionManager) GetValue(ctx context.Context, key string) any
  • func (sm *SessionManager) NewSession() *Session
  • func (sm *SessionManager) Rotate(ctx context.Context)
  • func (sm *SessionManager) SetSession(ctx context.Context, session *Session) error
  • func (sm *SessionManager) SetValue(ctx context.Context, key string, value any)
  • func (sm *SessionManager) Stop()
• type SessionManagerOption
  • func WithContextKey(key string) SessionManagerOption
  • func WithEncoder(encoder Encoder) SessionManagerOption
  • func WithErrHandler(errHandler ErrHandler) SessionManagerOption
  • func WithIdleTimeout(d time.Duration) SessionManagerOption
  • func WithLifetime(d time.Duration) SessionManagerOption
  • func WithRotateThreshold(d time.Duration) SessionManagerOption
  • func WithStore(store SessionStore) SessionManagerOption
• type SessionStatus
• type SessionStore

Types

type CookieConfig

type CookieConfig struct {
	Name        string
	Domain      string
	Path        string
	HttpOnly    bool
	Secure      bool
	SameSite    http.SameSite
	Partitioned bool
}

CookieConfig holds the configured cookie settings for the session cookie middleware.

type CookieOption

type CookieOption func(*CookieConfig)

CookieOption represents a functional option for configuring Cookies.

func WithDomain

func WithDomain(domain string) CookieOption

WithDomain sets the cookie domain.

func WithHttpOnly

func WithHttpOnly(b bool) CookieOption

WithHttpOnly sets the HttpOnly flag on the cookie.

func WithName

func WithName(name string) CookieOption

WithName sets the cookie name.

func WithPartitioned

func WithPartitioned(b bool) CookieOption

WithPartitioned sets the Partitioned attribute on the cookie.

func WithPath

func WithPath(path string) CookieOption

WithPath sets the cookie path.

func WithSameSite

func WithSameSite(s http.SameSite) CookieOption

WithSameSite sets the SameSite attribute on the cookie.

func WithSecure

func WithSecure(b bool) CookieOption

WithSecure sets the Secure flag on the cookie.

type CookieResponseWriter

type CookieResponseWriter struct {
	http.ResponseWriter
	// contains filtered or unexported fields
}

CookieResponseWriter wraps http.ResponseWriter to manage session cookies, state, and lifecycle during the request.

func (*CookieResponseWriter) SetCookie

func (crw *CookieResponseWriter) SetCookie()

SetCookie uses the internal session state of the CookieResponseWriter to set the http Cookie on the response.

func (*CookieResponseWriter) Write

func (crw *CookieResponseWriter) Write(b []byte) (int, error)

Write runs the session commit logic once to catch and persist any changes before writing the response.

func (*CookieResponseWriter) WriteHeader

func (crw *CookieResponseWriter) WriteHeader(code int)

WriteHeader runs the session commit logic once to catch and persist any changes before writing the status.

type Encoder

type Encoder interface {
	Marshal(data any) ([]byte, error)
	Unmarshal(encoded []byte, dest any) error
}

Encoder specifies the contract that the SessionManager expects for data encoding for agnostic store persistence.

func NewGobEncoder

func NewGobEncoder() Encoder

NewGobEncoder returns a new instance of a gob encoder.

type ErrHandler

type ErrHandler func(w http.ResponseWriter, r *http.Request, err error)

ErrHandler handles internal SessionManager errors.

type GobEncoder

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

GobEncoder providers a gob based Encoder.

func (*GobEncoder) Marshal

func (e *GobEncoder) Marshal(data any) ([]byte, error)

Marshal returns the given data as a gob encoded byte slice.

func (*GobEncoder) Unmarshal

func (e *GobEncoder) Unmarshal(encoded []byte, dest any) error

Unmarshal decodes the given gob encoded byte slice into the given destination pointer.

type Session

type Session struct {
	Id       string
	Data     map[string]any
	Status   SessionStatus
	Initial  bool
	Lifetime time.Time
	Expiry   time.Time
	// contains filtered or unexported fields
}

Session represents a session with an ID, data, and status.

type SessionManager

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

SessionManager manages session lifecycles using a SessionStore backend.

func NewSessionManager

func NewSessionManager(opts ...SessionManagerOption) *SessionManager

NewSessionManager creates a new instance of a SessionManager with the given config options or defaults.

Configure:

• WithContextKey: context key to be used when adding the session to the request context (default: random)
• WithErrHandler: error handler used for internal error handling (default: log and return InternalServerError)
• WithEncoder: encoding to be used to serialise session data before persisting (default: GobEncoder)
• WithStore: store to be used for persisting session data (default: memorystore.MemoryStore)
• WithLifetime: absolute session expiry (default: 24 hours)
• WithIdleTimeout: optional duration of inactivity before session expires (default: none)
• WithRotateThreshold: threshold (minutes remaining) before StatusShouldRotate flag applied (default: 2 minutes)

func (*SessionManager) Commit

func (sm *SessionManager) Commit(ctx context.Context, session *Session) error

Commit pushes all changes made to the session into the SessionStore. If no changes were made and an idle timeout is configured, the expiry will be incremented automatically.

func (*SessionManager) CookieSessions

func (sm *SessionManager) CookieSessions(opts ...CookieOption) quicky.MiddlewareFunc

CookieSessions returns a middleware to handle the full lifecycle of a session per request.

• Sessions are retrieved or created if a session cookie does not exist.
• Sessions are added to the request context for further use and change.
• Session changes are automatically commited to the session store prior to writing the response.
• Session cookies are automatically set based on the session state.

func (*SessionManager) DeleteManySessions

func (sm *SessionManager) DeleteManySessions(ctx context.Context, sessionIds ...string) error

DeleteManySessions removes all sessions associated with the given session IDs from the store if any exist.

func (*SessionManager) DeleteSession

func (sm *SessionManager) DeleteSession(ctx context.Context, sessionId string) error

DeleteSession removes the session associated with the given session ID from the store if it exists.

func (*SessionManager) DeleteValue

func (sm *SessionManager) DeleteValue(ctx context.Context, key string)

DeleteValue removes the value assoicated with the given key from the session data if a session exists.

func (*SessionManager) Destroy

func (sm *SessionManager) Destroy(ctx context.Context)

Destroy marks the current session for deletion on the context. Once flagged as destroyed, the session is no longer usable.

func (*SessionManager) GetSession

func (sm *SessionManager) GetSession(ctx context.Context, sessionId string) (session *Session, ok bool, err error)

GetSession retrieves a session by id if it exists.

func (*SessionManager) GetValue

func (sm *SessionManager) GetValue(ctx context.Context, key string) any

GetValue returns the value associated with the given key from the session data if it exists.

func (*SessionManager) NewSession

func (sm *SessionManager) NewSession() *Session

NewSession returns a new unique instance of a Session. The returned Session is not added to the SessionStore and must be commited before the request lifecycle completes.

func (*SessionManager) Rotate

func (sm *SessionManager) Rotate(ctx context.Context)

Rotate marks the session for rotation if a session exists on the context.

func (*SessionManager) SetSession

func (sm *SessionManager) SetSession(ctx context.Context, session *Session) error

SetSession updates the Session expiry automatically and adds it to the store, or updates if it already exists.

func (*SessionManager) SetValue

func (sm *SessionManager) SetValue(ctx context.Context, key string, value any)

SetValue adds the key value pair to the session data if a session exists.

func (*SessionManager) Stop

func (sm *SessionManager) Stop()

Stop releases any resources allocated by the SessionManager. Automatically calls Stop on the underlying SessionStore.

type SessionManagerOption

type SessionManagerOption func(*SessionManager)

SessionManagerOption provides a functional way to configure the SessionManager on construction.

func WithContextKey

func WithContextKey(key string) SessionManagerOption

WithContextKey sets the context key to be used when setting the session into the request context. Defaults to a randomly generated string. Blank strings will be ignored and the default used.

func WithEncoder

func WithEncoder(encoder Encoder) SessionManagerOption

WithEncoder sets the encoder used to serialise data prior to storage. Defaults to a GobEncoder. Nil values will be ignored and the default used.

func WithErrHandler

func WithErrHandler(errHandler ErrHandler) SessionManagerOption

WithErrHandler sets the error handler to be used to handle internal errors gracefully. Defaults to a handler that logs the error and returns a generic InternalServerError to the client.

func WithIdleTimeout

func WithIdleTimeout(d time.Duration) SessionManagerOption

WithIdleTimeout sets an optional idle timeout for a session to be force expired at if not used within the duration. No default set. Values less than or equal to zero will be ignored.

func WithLifetime

func WithLifetime(d time.Duration) SessionManagerOption

WithLifetime sets the absolute expiry for a session to be force expired at if not rotated. Defaults to 24 hours. Values less than or equal to zero are ignored.

func WithRotateThreshold

func WithRotateThreshold(d time.Duration) SessionManagerOption

WithRotateThreshold sets the threshold the SessionManager uses to set the StatusShouldRotate flag on the session. Defaults to 2 minutes remaining on the existing session. Values less than or equal to zero will be ignored.

func WithStore

func WithStore(store SessionStore) SessionManagerOption

WithStore sets the SessionStore to be used to persist session data. Defaults to a memorystore.MemoryStore. Nil values will be ignored and the defaul used.

type SessionStatus

type SessionStatus int

const (
	StatusUnchanged SessionStatus = iota
	StatusChanged
	StatusDestroy
	StatusShouldRotate
	StatusRotate
)

type SessionStore

type SessionStore interface {
	// Get returns the encoded session data associated with the given key from the store if it exists.
	Get(ctx context.Context, key string) (data []byte, ok bool, err error)

	// Set adds the session data to the store or overwrites it if the key already exists.
	Set(ctx context.Context, key string, data []byte, ttl time.Duration) error

	// Delete removes the session data associated with the given key from the store if it exists.
	Delete(ctx context.Context, key string) error

	// DeleteMany removes all session data associated with the given keys from the store if any exist.
	DeleteMany(ctx context.Context, keys ...string) error

	// Stop releases any resources allocated by the store.
	Stop()
}

SessionStore specifies the contract that the SessionManager expects for persistent session storage.