@spec create_session(map(), Keyword.t()) ::
  {:ok, MscmpSystSession.Types.session_name()} | {:error, MscmpSystError.t()}

Creates a new session returning the session name for future reference.

Using a starting set of data and a expiration period, creates a new Session record. The return value is either a success tuple including the generated name of the session record or an error tuple explaining the failure.

Currently, the Session name is an automatically generated random 96 bytes run through base 64 encoding.

Parameters

• session_data - the initial Session Data to use in creating the new Session record in the database. Currently the expectation is that this value will be any arbitrary Map. This parameter is required.

• opts - a Keyword List of optional parameters. The available parameters are:

  • session_name - a binary to use for the session name rather than letting the system create a random session name. The default behavior is for the system to set the session name using generate_session_name/0.

  • expires_after - the number of seconds for which the session will be considered valid. The default value for this setting is 3,600 seconds (1 hour).

Examples

Creating a new Session with the default expiration time.

iex> {:ok, session_name} =
...>   MscmpSystSession.create_session(%{test: "test"})
iex> is_binary(session_name)
truecopy

@spec delete_session(MscmpSystSession.Types.session_name()) ::
  :ok | {:ok, :not_found} | {:error, MscmpSystError.t()}

Deletes the named Session record from the database.

This is the de facto method for terminating a session.

Unlike the other functions in this module which treat expired Session records as though they've not been found, deleting an expired Session is permitted and will return the same value as deleting an unexpired Session record.

Parameters

• session_name - the Session Name that was generated by create_session/2 at Session create time. This argument is required.

Examples

Deleting a Session record.

iex> MscmpSystSession.delete_session("example_delete_session")
:okcopy

Attempting to delete a nonexistent Session returns the not found value.

iex> MscmpSystSession.delete_session("nonexistent_session")
{:ok, :not_found}copy

@spec generate_session_name() :: MscmpSystSession.Types.session_name()

Generates a random Session Name using the current formulation for automatic session name generation.

Currently generated Session Names are strings of 16 random characters using a mixed case, alphanumeric character set.

Examples

Generating a random name.

iex> session_name = MscmpSystSession.generate_session_name()
iex> String.length(session_name) == 16
truecopy

@spec get_session(MscmpSystSession.Types.session_name(), Keyword.t()) ::
  {:ok, MscmpSystSession.Types.session_data()}
  | {:ok, :not_found}
  | {:error, MscmpSystError.t()}

Retrieves the Session Data for the named Session and resets the Session Expiration.

It should be noted that reading a Session will also refresh the expiration of that Session's expiration date.

Trying to retrieve the Session data of an already expired Session results in a not found tuple being returned ({:ok, :not_found}).

Parameters

• session_name - the Session Name that was generated by create_session/2 at Session create time. This argument is required.

• opts - a Keyword List of optional parameters. The available parameters are:

  • expires_after - the number of seconds for which the session will be considered valid. The default value for this setting is 3,600 seconds (1 hour).

Examples

Retrieving a Session and setting the renewed expiration date/time to 30 minutes from retrieval time.

iex> {:ok, %{}} = MscmpSystSession.get_session("example_session", expires_after: 1800)copy

Attempting to retrieve an expired Session returns the not found value.

iex> MscmpSystSession.get_session("example_expired_session")
{:ok, :not_found}copy

@spec purge_expired_sessions(Keyword.t()) :: :ok | {:error, MscmpSystError.t()}

Purges the database of previously expired Session records.

The intention of this function is for it to be called on a periodic, scheduled basis in order to keep the system clean of expired Sessions. The expectations are that the purge process may take some time. Currently, 4 minutes are allotted for the running of the process prior to timing out, so a schedule more aggressive than once every 5 minutes is not advised.

Parameters

• opts - a Keyword List of optional parameters. The available parameters are:

  • db_timeout - the number of seconds to allow the database DELETE query to run before timing out the transaction. The default value is 300 (5 minutes).

@spec refresh_session_expiration(MscmpSystSession.Types.session_name(), Keyword.t()) ::
  :ok | {:ok, :not_found} | {:error, MscmpSystError.t()}

Refreshes the Session expiration date/time of the identified record.

The function only returns its success status absent any data.

Do note that all other interactions with the Session will also refresh the Session expiration date/time so in many cases there is no need to call this function explicitly. Typically you'd only call this function if you've had interaction with the user, but not needed to access the session for some time.

Trying to refresh the expiration date/time of an already expired Session will be treated as a "not found" record.

Parameters

• session_name - the Session Name that was generated by create_session/2 at Session create time. This argument is required.

• opts - a Keyword List of optional parameters. The available parameters are:

  • expires_after - the number of seconds for which the session will be considered valid. The default value for this setting is 3,600 seconds (1 hour).

Examples

Refreshing a Session expiration date/time to 30 minutes from refresh time.

iex> MscmpSystSession.refresh_session_expiration("example_session", expires_after: 1800)
:okcopy

Attempting to refresh an already expired Session returns the not found value.

iex> MscmpSystSession.refresh_session_expiration("example_expired_session")
{:ok, :not_found}copy

@spec update_session(
  MscmpSystSession.Types.session_name(),
  MscmpSystSession.Types.session_data(),
  Keyword.t()
) :: :ok | {:ok, :not_found} | {:error, MscmpSystError.t()}

Replaces the Session Data of the named Session record with the Session Data provided.

As with other kinds of interactions with the Session, updating the Session data will also update the expiration date/time.

Attempting to update the Session Data of an already expired Session will be treated as attempting to update a not found record.

Parameters

• session_name - the Session Name that was generated by create_session/2 at Session create time. This argument is required.

• session_data - the updated Session Data which replaces the existing Session Data. Currently the expectation is that this value will be any arbitrary Map. This argument is required.

• opts - a Keyword List of optional parameters. The available parameters are:

  • expires_after - the number of seconds for which the session will be considered valid. The default value for this setting is 3,600 seconds (1 hour).

Examples

Updating a Session with new data and resetting the expiration date/time to 30 minutes from update time.

iex> MscmpSystSession.update_session("example_update_session", %{updated_key: "updated_value"},
...>   expires_after: 1800)
:ok
iex> MscmpSystSession.get_session("example_update_session")
{:ok, %{"updated_key" => "updated_value"}}copy

Attempting to update an already expired Session returns the not found value.

iex> MscmpSystSession.update_session("example_expired_session", %{updated_key: "updated_value"})
{:ok, :not_found}copy