Class session

Session library provides HTTP session management capabilities for OpenResty based applications, libraries and proxies.

Functions

session_instance:open () Opens session

This can be used to open a session.

Tables

session.configuration Session configuration options

Methods

session:init ([configuration]) Initializes session library
session:new ([configuration]) Creates new session
session:open ([configuration]) Opens session

This can be used to open a session.
session:start ([configuration]) Starts the session and refreshes it as needed

This can be used to start a session.
session:logout ([configuration]) Logouts session

It logouts from a specific audience.
session:destroy ([configuration]) Destroys session


Functions

Methods
session_instance:open ()
Opens session

This can be used to open a session. It will either return an existing session or a new session.

Returns:

  1. true or nil session instance
  2. string information why session could not be opened

Tables

session.configuration
Session configuration options

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 to nil)
  • 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 to nil)
  • cookie_http_only Mark cookie HTTP only, use true or false (defaults to true)
  • cookie_secure Mark cookie secure, use nil, true or false (defaults to nil)
  • cookie_priority Cookie priority, use nil, "Low", "Medium", or "High" (defaults to nil)
  • 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, or false (default: nil)
  • cookie_partitioned Mark cookie with partitioned flag, use nil, true, or false (default: nil)
  • remember Enable or disable persistent sessions, use nil, true, or false (defaults to false)
  • 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 to nil)
  • 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 to 10) (in seconds)
  • idling_timeout Idling timeout specifies how long the session can be inactive until it is considered invalid, e.g. 900 (defaults to 900, 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 to 3600, 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 to 86400, or a day) (in seconds)
  • remember_timeout Remember timeout specifies how long the persistent session is considered valid, e.g. 604800 (defaults to 604800, or a week) (in seconds)
  • 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 to nil)
  • 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" }

Methods

session:init ([configuration])
Initializes 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:

Usage:

    require "resty.session".init({
  audience = "my-application",
})
session:new ([configuration])
Creates new session This creates a new session instance.

Parameters:

Returns:

    table session instance

Usage:

    local session = require "resty.session".new()
-- OR
local session = require "resty.session".new({
  audience = "my-application",
})
session:open ([configuration])
Opens session

This can be used to open a session. It will either return an existing session or a new session.

Parameters:

Returns:

  1. table session instance
  2. string information why session could not be opened
  3. boolean true, if session existed, otherwise false

Usage:

    local session = require "resty.session".open()
-- OR
local session, err, exists = require "resty.session".open({
  audience = "my-application",
})
session:start ([configuration])
Starts the session and refreshes it as needed

This can be used to start a session. 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:

Returns:

  1. table session instance
  2. string information why session could not be logged out
  3. boolean true, if session existed, otherwise false
  4. boolean true, if session was refreshed, otherwise false

Usage:

    local session = require "resty.session".start()
-- OR
local session, err, exists, refreshed = require "resty.session".start()
  audience = "my-application",
})
session:logout ([configuration])
Logouts 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:

Returns:

  1. boolean true session exists for an audience and was logged out successfully, otherwise false
  2. string information why the session could not be logged out
  3. boolean true if session existed, otherwise false
  4. boolean true if session was logged out, otherwise false

Usage:

    require "resty.session".logout()
-- OR
local ok, err, exists, logged_out = require "resty.session".logout({
  audience = "my-application",
})
session:destroy ([configuration])
Destroys session It destroys the whole session and clears the cookies.

Parameters:

Returns:

  1. boolean true session exists and was destroyed successfully, otherwise nil
  2. string information why session could not be destroyed
  3. boolean true if session existed, otherwise false
  4. boolean true if session was destroyed, otherwise false

Usage:

    require "resty.session".destroy()
-- OR
local ok, err, exists = require "resty.session".destroy({
  cookie_name = "auth",
})
generated by LDoc 1.4.6 Last updated 2022-12-16 00:35:34