Documentation
¶
Overview ¶
Package pwsession resolves per-browser state for a request, on whichever transport carries it.
It is the third of the four layers requirement:alternate-http-backend-readiness names. Almost none of a session is transport-shaped: the slot declarations, the backend registry, the keyring, the cookie policy, the lifetime arithmetic and the expiry sweep are all the same whichever server answered. What each transport supplies is one frame that hands the resolved manager a carrier, which is session.Carrier and is already shared.
So Setup is here and the frame is not. pw installs manager.Middleware and pwfast installs pwfast.Session, and both drive one manager built from one reading of the configuration — which matters more than it sounds: two implementations of when a token rotates are two chances to leave a session valid that should have ended.
Nothing here imports a transport, apart from net/http's SameSite enum, which is a spelling of an attribute rather than a transport.
Index ¶
- func Backends() []string
- func Close(context.Context) error
- func CookiePolicy(config sessionconfig.SessionConfig) (session.CookieOptions, error)
- func Keyring(config sessionconfig.SessionKeyringConfig) (*session.Keyring, error)
- func Manager() *session.Manager
- func NewRegistry(extra ...func(*session.Registry) error) (*session.Registry, error)
- func OpenBackend(ctx context.Context, config sessionconfig.SessionConfig, resources Resources) (session.Backend, error)
- func Options(config sessionconfig.SessionConfig, ...) (session.Options, error)
- func ParseSameSite(value string) (http.SameSite, error)
- func Prune() func(context.Context, time.Time, int) (int64, error)
- func RegisterBackend(name string, factory BackendFactory)
- func RegisterStore[T any](key string, placement session.Placement, options ...session.SlotOption)
- func Replace(manager *session.Manager, closer func(context.Context) error, ...)
- func Setup(ctx context.Context) (*session.Manager, error)
- func ValidateDevelopmentMode(name string) error
- type BackendFactory
- type Resources
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Backends ¶
func Backends() []string
Backends lists the registered backend names in order. It is what the startup summary and error messages report.
func CookiePolicy ¶
func CookiePolicy(config sessionconfig.SessionConfig) (session.CookieOptions, error)
CookiePolicy resolves the validated browser cookie policy of the session middleware. The cookie backend and the session manager share it, so both halves of a session travel under one policy.
func Keyring ¶
func Keyring(config sessionconfig.SessionKeyringConfig) (*session.Keyring, error)
Keyring reads the secret that protects everything the browser carries.
One secret serves both protections a slot can carry: session.ReadOnly signs and session.Private seals, and session.Keyring derives a purpose-separated subkey per mode. It is therefore required unless every declared slot is session.Shared, which protects nothing, or session.RequestScope, which never leaves process memory.
The secret itself never reaches an error message or a log.
func Manager ¶
Manager returns the manager the last Setup installed, or nil when session storage is disabled.
It is how popcornweb/plugin/auth reaches Rotate and Destroy: the framework resolves the session at SlotSession and authentication drives it at SlotAuthentication, which is why the manager travels forward and the login does not travel back.
func NewRegistry ¶
NewRegistry builds the registry of everything declared through RegisterStore, plus the slots the caller adds.
The framework half of a login is one such slot, so plugin/auth passes its own declaration here rather than being privileged in storage.
func OpenBackend ¶
func OpenBackend(ctx context.Context, config sessionconfig.SessionConfig, resources Resources) (session.Backend, error)
OpenBackend opens the backend named by config.Backend.
A host calls this instead of importing a storage plugin, so adding a backend changes no host and links nothing into an application that did not ask for it.
func Options ¶
func Options(config sessionconfig.SessionConfig, lifetime sessionconfig.SessionLifetimeConfig) (session.Options, error)
Options maps the two bindings onto what the session package enforces. The placement and the cookie policy come from session; every duration comes from [auth.session], because an expiry states how long a proof of identity stays good and the store holding the bytes has no basis to make it.
func ParseSameSite ¶
ParseSameSite reads the configured attribute, which the startup validation also needs: "none" without Secure is a cookie no browser accepts, and that is refused before a port is bound rather than at the first response.
func Prune ¶
Prune returns the expiry sweep of the configured backend, or nil for a backend whose server or browser forgets records on its own.
func RegisterBackend ¶
func RegisterBackend(name string, factory BackendFactory)
RegisterBackend registers factory under name. A storage plugin calls it from init, so a blank import is what puts a backend in a binary:
import _ "github.com/shibukawa/popcornweb/sessionstore/redis"
Cookie and the two development intent modes are built in. They add no storage dependency, so pw registers them here and they need no import.
A duplicate or empty name panics: two backends answering one configuration value is a build mistake, not a runtime condition.
func RegisterStore ¶
RegisterStore declares one piece of per-browser state, as a Go type with a placement, and is the only place either is stated.
pw.RegisterStore[Cart]("cart", session.Private)
cart, ok := session.Load[Cart](ctx)
The placement states what the client may do with the value and where its bytes live: session.Shared is a plain cookie the front end reads and writes, session.ReadOnly a signed one it may read, session.Private is sealed and moves from a cookie to the configured backend at the login rotation, session.ServerOnly is sealed and always on the server because it must stay revocable, and session.RequestScope lives in process memory for one request and is never persisted. The deployment is left with one choice, which server backend session.backend names.
One example per placement, in the same order: a display-density toggle the front end flips is session.Shared; the locale the server chose and the front end may read is session.ReadOnly; a cart an anonymous visitor starts and a logged-in user keeps is session.Private; a stored secret the client must never hold even sealed — the refresh token taken at login — or a draft that outgrows the cookie budget is session.ServerOnly; and the scope set a bearer token resolves to against the authentication database — read fresh on every request precisely so a revocation is seen immediately — is session.RequestScope. A preference that should follow the account across browsers is not session state at all: a session names one browser and dies at logout, so that belongs in the application's own database.
How long the value lives is the second, independent question. Stating nothing ties it to the session. session.ExpiresAfter ends it earlier, which is what a rotating secret or a short admission window wants. session.OutlivesSession exempts it from a sign-out, which is what a display language wants, and is available only to the two cookie-placed values because a record cannot outlive its own destruction.
Call it from main, after every package init has run, exactly as RegisterConfig requires: the declarations must be complete before the first request decodes anything.
A duplicate Go type and a duplicate key are each a panic at startup rather than a silent replacement, on the same grounds as RegisterBackend.
func Replace ¶
func Replace(manager *session.Manager, closer func(context.Context) error, prune func(context.Context, time.Time, int) (int64, error))
Replace installs the resolved session state and releases what it replaces.
It is exported because Close is a runtime's shutdown step rather than this package's, and because a test that builds a manager by hand has to be able to put the process back.
func Setup ¶
Setup opens the configured storage and builds the manager, returning nil when the deployment disabled sessions.
It knows nothing about login. The durations it enforces are read from the [auth.session] binding, which exists only when an authentication plugin is linked; without one the session is bounded by the browser alone, which is what decision:session-lifetime-owned-by-auth accepts.
func ValidateDevelopmentMode ¶
Types ¶
type BackendFactory ¶
type BackendFactory func(context.Context, sessionconfig.SessionConfig, Resources) (session.Backend, error)
BackendFactory opens one storage backend from configuration. It reads only the keys of its own backend, opens and validates its own dependencies, and returns them with the store so the host can release them later.
Registration is a package init; opening happens here, at startup.
type Resources ¶
type Resources struct {
// DB is the pool of api:rdb-middleware, already pinned to the session
// connection group. It is nil when no database is configured, and also on
// an engine that bypasses database/sql; Executor is the surface that
// exists on every connection.
DB *sql.DB
// Executor is the statement surface of the session connection group,
// whichever kind of pool backs it. It is nil when no database is
// configured.
Executor sqlbind.SQLExecutor
// DBDriver is the driver scheme of the connection, for a backend whose
// SQL is dialect specific.
DBDriver string
}
Resources are the framework resources a session backend may borrow. A backend closes nothing it finds here: what it did not open, it does not own.
func DatabaseResources ¶
DatabaseResources opens what a session backend might want.
A project with no relational middleware gets an empty set rather than an error: whether a database is needed is the selected backend's question, and the rdb backend is the one that answers it. Resolving eagerly here would refuse a DynamoDB or Redis session for the absence of something it never reads.