Class resty.session
Session library provides HTTP session management capabilities for OpenResty based applications, libraries and proxies.
Session
session.info:set (key, value) | Set a value in session information store. |
session.info:get (key) | Get a value from session information store. |
session.info:save () | Save information. |
resty.session:set (key, value) | Set a value in session. |
resty.session:get (key) | Get a value from session. |
resty.session:open () | Open a session. |
resty.session:save () | Save the session. |
resty.session:touch () | Touch the session. |
resty.session:refresh () | Refresh the session. |
resty.session:logout () | Logout the session. |
resty.session:destroy () | Destroy the session. |
resty.session:close () | Close the session. |
instance:hide () | Hide the session. |
Constructors
resty.session.configuration | Session configuration. |
module.init ([configuration]) | Initialize the session library. |
module.new ([configuration]) | Create a new session. |
module.open ([configuration]) | Open a session. |
module.start ([configuration]) | Start a session and refresh it as needed. |
module.logout ([configuration]) | Logout a session. |
module.destroy ([configuration]) | Destroy a session. |
Session
- session.info:set (key, value)
-
Set a value in session information store.
Parameters:
- session.info:get (key)
-
Get a value from session information store.
Parameters:
- key
string
key
Returns:
-
value
- key
string
- session.info:save ()
-
Save information.
Only updates backend storage. Does not send a new cookie.
Returns:
- true or nil ok
- string error message
- resty.session:set (key, value)
-
Set a value in session.
Parameters:
- resty.session:get (key)
-
Get a value from session.
Parameters:
- key
string
key
Returns:
-
value
- key
string
- resty.session:open ()
-
Open a session.
This can be used to open a session. It will either return an existing session or a new session.
Returns:
- true or nil ok
- string error message
- resty.session:save ()
-
Save the session.
Saves the session data and issues a new session cookie with a new session id. When
remember
is enabled, it will also issue a new persistent cookie and possibly save the data in backend store.Returns:
- true or nil ok
- string error message
- resty.session:touch ()
-
Touch the session.
Updates idling offset of the session by sending an updated session cookie. It only sends the client cookie and never calls any backend session store APIs. Normally the session:refresh is used to call this indirectly.
Returns:
- true or nil ok
- string error message
- resty.session:refresh ()
-
Refresh the session.
Either saves the session (creating a new session id) or touches the session depending on whether the rolling timeout is getting closer. The touch has a threshold, by default one minute, so it may be skipped in some cases.
Returns:
- true or nil ok
- string error message
- resty.session:logout ()
-
Logout the session.
Logout either destroys the session or just clears the data for the current audience, and saves it (logging out from the current audience).
Returns:
- true or nil ok
- string error message
- resty.session:destroy ()
-
Destroy the session.
Destroy the session and clear the cookies.
Returns:
- true or nil ok
- string error message
- resty.session:close ()
-
Close the session.
Just closes the session instance so that it cannot be used anymore.
Returns:
- true or nil ok
- string error message
- instance:hide ()
-
Hide the session.
Modifies the request headers by removing the session related cookies. This is useful when you use the session library on a proxy server and don’t want the session cookies to be forwarded to the upstream service.
Returns:
-
true or nil
ok
Constructors
- resty.session.configuration
-
Session configuration.
Fields:
- secret
Secret used for the key derivation. The secret is hashed with SHA-256 before using it. E.g.
"RaJKp8UQW1"
. - secret_fallbacks
Array of secrets that can be used as alternative secrets (when doing key rotation), E.g.
{ "6RfrAYYzYq", "MkbTkkyF9C" }
. - ikm
Initial key material (or ikm) can be specified directly (without using a secret) with exactly 32 bytes of data, e.g.
"5ixIW4QVMk0dPtoIhn41Eh1I9enP2060"
- ikm_fallbacks
Array of initial key materials that can be used as alternative keys (when doing key rotation), E.g.
{ "QvPtlPKxOKdP5MCu1oI3lOEXIVuDckp7" }
. - cookie_prefix
Cookie prefix, use
nil
,"__Host-"
or"__Secure-"
(defaults tonil
) - cookie_name
Session cookie name, e.g.
"session"
(defaults to"session"
) - cookie_path
Cookie path, e.g.
"/"
(defaults to"/"
) - cookie_domain
Cookie domain, e.g.
"example.com"
(defaults tonil
) - cookie_http_only
Mark cookie HTTP only, use
true
orfalse
(defaults totrue
) - cookie_secure
Mark cookie secure, use
nil
,true
orfalse
(defaults tonil
) - cookie_priority
Cookie priority, use
nil
,"Low"
,"Medium"
, or"High"
(defaults tonil
) - cookie_same_site
Cookie same-site policy, use
nil
,"Lax"
,"Strict"
, or"None"
(defaults to"Lax"
) - cookie_same_party
Mark cookie with same party flag, use
nil
,true
, orfalse
(default:nil
) - cookie_partitioned
Mark cookie with partitioned flag, use
nil
,true
, orfalse
(default:nil
) - remember
Enable or disable persistent sessions, use
nil
,true
, orfalse
(defaults tofalse
) - remember_cookie_name
Persistent session cookie name, e.g.
"remember"
(defaults to"remember"
) - audience
Session audience, e.g.
"my-application"
(defaults to"default"
) - subject
Session subject, e.g.
"john.doe@example.com"
(defaults tonil
) - stale_ttl
When session is saved a new session is created, stale ttl specifies how long the old one can still be used, e.g.
10
(defaults to10
) (in seconds) - idling_timeout
Idling timeout specifies how long the session can be inactive until it is considered invalid, e.g.
900
(defaults to900
, or 15 minutes) (in seconds) - rolling_timeout
Rolling timeout specifies how long the session can be used until it needs to be renewed, e.g.
3600
(defaults to3600
, or an hour) (in seconds) - absolute_timeout
Absolute timeout limits how long the session can be renewed, until re-authentication is required, e.g.
86400
(defaults to86400
, or a day) (in seconds) - remember_timeout
Remember timeout specifies how long the persistent session is considered valid, e.g.
604800
(defaults to604800
, or a week) (in seconds) - touch_threshold
Touch threshold controls how frequently or infrequently the session:refresh touches the cookie, e.g.
60
(defaults to60
, or a minute) (in seconds) - compression_threshold
Compression threshold controls when the data is deflated, e.g.
1024
(defaults to1024
, or a kilobyte) (in bytes) - storage
Storage is responsible of storing session data, use
nil
(data is stored in cookie), dshm, file, memcached, mysql, postgres, redis, redis-cluster, redis-sentinel, or shm, or give a name of custom module ("custom.session.storage"
), or a table that implements session storage interface (defaults tonil
) - dshm
Configuration for dshm storage, e.g.
{ prefix = "sessions" }
- file
Configuration for file storage, e.g.
{ path = "/tmp", suffix = "session" }
- memcached
Configuration for memcached storage, e.g.
{ prefix = "sessions" }
- mysql
Configuration for MySQL / MariaDB storage, e.g.
{ database = "sessions" }
- postgres
Configuration for Postgres storage, e.g.
{ database = "sessions" }
- redis
Configuration for Redis / Redis Sentinel / Redis Cluster storages, e.g.
{ prefix = "sessions" }
- shm
Configuration for shared memory storage, e.g.
{ zone = "sessions" }
- secret
Secret used for the key derivation. The secret is hashed with SHA-256 before using it. E.g.
- module.init ([configuration])
-
Initialize the session library.
This function can be called on init or
init_worker
phases on OpenResty to set global default configuration to all session instances created by this library.Parameters:
- configuration table session configuration overrides (optional)
Usage:
require "resty.session".init({ audience = "my-application", })
- module.new ([configuration])
-
Create a new session.
This creates a new session instance.
Parameters:
- configuration table session configuration overrides (optional)
Returns:
-
table
session instance
Usage:
local session = require "resty.session".new() -- OR local session = require "resty.session".new({ audience = "my-application", })
- module.open ([configuration])
-
Open a session.
This can be used to open a session, and it will either return an existing session or a new session.
Parameters:
- configuration table session configuration overrides (optional)
Returns:
- table session instance
- string information why session could not be opened
-
boolean
true
, if session existed, otherwisefalse
Usage:
local session = require "resty.session".open() -- OR local session, err, exists = require "resty.session".open({ audience = "my-application", })
- module.start ([configuration])
-
Start a session and refresh it as needed.
This can be used to start a session, and it will either return an existing session or a new session. In case there is an existing session, the session will be refreshed as well (as needed).
Parameters:
- configuration table session configuration overrides (optional)
Returns:
- table session instance
- string information why session could not be logged out
-
boolean
true
, if session existed, otherwisefalse
-
boolean
true
, if session was refreshed, otherwisefalse
Usage:
local session = require "resty.session".start() -- OR local session, err, exists, refreshed = require "resty.session".start() audience = "my-application", })
- module.logout ([configuration])
-
Logout a session.
It logouts from a specific audience.
A single session cookie may be shared between multiple audiences (or applications), thus there is a need to be able to logout from just a single audience while keeping the session for the other audiences.
When there is only a single audience, then this can be considered equal to session.destroy.
When the last audience is logged out, the cookie will be destroyed as well and invalidated on a client.
Parameters:
- configuration table session configuration overrides (optional)
Returns:
-
boolean
true
session exists for an audience and was logged out successfully, otherwisefalse
- string information why the session could not be logged out
-
boolean
true
if session existed, otherwisefalse
-
boolean
true
if session was logged out, otherwisefalse
Usage:
require "resty.session".logout() -- OR local ok, err, exists, logged_out = require "resty.session".logout({ audience = "my-application", })
- module.destroy ([configuration])
-
Destroy a session.
It destroys the whole session and clears the cookies.
Parameters:
- configuration table session configuration overrides (optional)
Returns:
-
boolean
true
session exists and was destroyed successfully, otherwisenil
- string information why session could not be destroyed
-
boolean
true
if session existed, otherwisefalse
-
boolean
true
if session was destroyed, otherwisefalse
Usage:
require "resty.session".destroy() -- OR local ok, err, exists = require "resty.session".destroy({ cookie_name = "auth", })