# 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:

  - configuration table session configuration overrides (optional)

  ### Usage:

      require "resty.session".init({
        audience = "my-application",
      })

session:new ([configuration])
  Creates 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",
      })

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:

  - configuration table session configuration overrides (optional)

  ### 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:

  - configuration table session configuration overrides (optional)

  ### 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:

  - configuration table session configuration overrides (optional)

  ### 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:

  - configuration table session configuration overrides (optional)

  ### 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