SXAPI Core : session manager

The session manager is a core component allow you to keep persistant information between client and API server using a session mechanism.
This component comes with various transport type (cookie, token or bearer) for transfering the session identifier from and to the consumer.
You can use various storage backend (mysql, (postgres, couchbase, memory, memcache or redis) to persist session context across request and micro-services instances.

Configuration

To enable this component in you API, you must add a session property in the main section of your configuration file, The coresponding value should be an object with configuration parameters.
If session property is not defined, or set to false ("session" : false), no session context will be defined and your API will be stateless unless your resources used a buildin mecanism for user context persistance.

Config parameters

Param	Mandatory	Type	default	Description
duration	no	int	3600	time in second for a session length. Could be used by transport (ex: cookie) or backend (ex: mysql) to control session duration. If this time is exceed, session will return an error response. Used in conjunction with stop field property in mysql backend or cookie duration in cookie transport type.
auto_create	no	bool	false	If transport type could not find a session ID, create a new session transparently
transport	no	obj	null	An object describing the transport type used to get and set session ID. See transport section
backend	no	obj	null	An object describing the backend type used to store and retrive session context. See backend section

Config Sample

session:
  duration: 3600
  auto_create: true
  transport:
    type: cookie
    ...
  backend:
    type: memory
    ...

Transport type

In you transport section, you must have a property type coresponding to a supported type. Available transport types are cookie, token or bearer

transport using `token`

Token transport allow you to retrive the session ID by reading an http param. You can call your API endpoint's using ?token=xxx and this transport type will extract the xxx session ID and pass it to the backend.
This transport type is very light. Client is in charge of storing the session ID. Choose carefully your param name to avoid naming conflict with your API endpoints.

Token config parameters

Param	Mandatory	Type	default	Description
type	yes	string	token	Must be `token` for this transport type
param	no	string	_token	Name of the http parameter transporting session ID

Token config sample

session:
  transport:
    type: token
    param: sid

transport using `cookie`

Cookie transport allow you to get the session ID by reading the session ID from an http cookie. You can call you api's endpoint using a browser cookie and this session transport type will be able to get the session ID and pass it to the configured backend to find the coresponding session.
This transport type is statefull as it create the cookie when required. Client is not in charge of persisting the session ID and giving it to the http Object used to send request to our API. Choose carefully your cookie_name name to avoid naming conflict with other domain cookies.

Param	Mandatory	Type	default	Description
type	yes	string	cookie	Must be `cookie` for this transport type
cookie_name	no	string	sxapi-sess	name of the cookie to find or define
cookie_options	no	object	{}	option used for creation a cookie. See cookies documentation

session:
  transport:
    type: cookie
    cookie_name: sxapi-sess
    cookie_options: 
      ...

transport using `bearer`

Bearer transport allow you to get the session ID by reading it from a Authentification: Bearer <token> http header. session token is also transmitted to the client using the same header. This transport type is stateless as client is in charge of storing and sending the session ID.

Bearer config parameters

Param	Mandatory	Type	default	Description
type	yes	string	bearer	Must be `bearer` for this transport type

Bearer config sample

session:
  transport:
    type: bearer

Backend type

In you backend section, you must have a property named type and coresponding to a supported backend type. Available backend types are mysql, postgres, couchbase, memory, memcache or redis

backend using `mysql`

This backend type use mysql resource to persist session context across executions.

mysql config parameters

Param	Mandatory	Type	default	Description
type	yes	string	mysql	Must be `mysql` for this backend type
resource	yes	string		ID of the mysql resource see resource for configuration.
table	yes	string		table name used for session storage
sid_field	yes	string		name of the field containing the session ID
fields	no	object		an object with special field list
fields.ip	no	string		name of the field containing the session IP
fields.start	no	string		name of the field containing the session start time
fields.stop	no	string		name of the field containing the session end time (defined with duration and used for expiration control)

mysql config sample

session:
  backend:
    type: mysql
    resource: mysql-sample
    table: sessions
    sid_field: token_sess
    fields:
      ip: ip_sess
      start: start_sess
      stop: stop_sess

backend using `postgres`

This backend type use postgres resource to persist session context across executions.

postgres config parameters

Param	Mandatory	Type	default	Description
type	yes	string	postgres	Must be `postgres` for this backend type
resource	yes	string		ID of the postgres resource see resource for configuration.
table	yes	string		table name used for session storage
sid_field	yes	string		name of the field containing the session ID
fields	no	object		an object with special field list
fields.ip	no	string		name of the field containing the session IP
fields.start	no	string		name of the field containing the session start time
fields.stop	no	string		name of the field containing the session end time (defined with duration and used for expiration control)

postgres config sample

session:
  backend:
    type: postgres
    resource: postgres-sample
    table: sessions
    sid_field: token_sess
    fields:
      ip: ip_sess
      start: start_sess
      stop: stop_sess

backend using `couchbase`

This backend type use couchbase resource to persist session context across executions.

couchbase config parameters

Param	Mandatory	Type	default	Description
type	yes	string	couchbase	Must be `couchbase` for this backend type
resource	yes	string		ID of the couchbase resource see resource for configuration.
key_ns	yes	string		the key namespace for this kind of document. used as a key prefix
fields	no	object		an object with special field list
fields.token	no	string		name of the field containing the session token
fields.ip	no	string		name of the field containing the session IP
fields.start	no	string		name of the field containing the session start time
fields.stop	no	string		name of the field containing the session end time (defined with duration and used for expiration control)

couchbase config sample

session:
  backend:
    type: couchbase
    resource: couchbase-sample
    key_ns: 'sess::'
    fields:
      token: token
      ip: ipAdress
      start: startDate
      stop: stopDate

backend using `memory`

This backend type use application memory space to persist session context across executions.

memory config parameters

Param	Mandatory	Type	default	Description
type	yes	string	memory	Must be `memory` for this backend type
sid_field	no	string	sid	name of the field containing the session ID
fields	no	object		an object with special field list
fields.ip	no	string		name of the field containing the session IP
fields.start	no	string		name of the field containing the session start time
fields.stop	no	string		name of the field containing the session end time (defined with duration and used for expiration control)

memory config sample

session:
  backend:
    type: memory
    sid_field: sessionID
    fields:
      ip: ipAdress
      start: startDate
      stop: stopDate

backend using `memcache`

This backend type use memcache resource to persist session context across executions.

memcache config parameters

Param	Mandatory	Type	default	Description
type	yes	string	memcache	Must be `memcache` for this backend type
resource	yes	string		ID of the memcache resource see resource for configuration.
sid_field	yes	string		name of the field containing the session ID
fields	no	object		an object with special field list
fields.ip	no	string		name of the field containing the session IP
fields.start	no	string		name of the field containing the session start time
fields.stop	no	string		name of the field containing the session end time (defined with duration and used for expiration control)

memcache config sample

session:
  backend:
    type: memcache
    resource: memcache-sample
    sid_field: token
    fields:
      stop: stopDate

backend using `redis`

This backend type use redis resource to persist session context across executions.

redis config parameters

Param	Mandatory	Type	default	Description
type	yes	string	redis	Must be `redis` for this backend type
resource	yes	string		ID of the redis resource see resource for configuration.
sid_field	yes	string		name of the field containing the session ID
fields	no	object		an object with special field list
fields.ip	no	string		name of the field containing the session IP
fields.start	no	string		name of the field containing the session start time
fields.stop	no	string		name of the field containing the session end time (defined with duration and used for expiration control)

redis config sample

session:
  backend:
    type: redis
    resource: redis-sample
    sid_field: token
    fields:
      stop: stopDate