session.h File Reference

Signed client-side session cookie API. More...

#include <cwist/net/http/http.h>
#include <cwist/sys/app/app.h>
#include <cwist/query.h>
#include <stdbool.h>

Include dependency graph for session.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct cwist_session	cwist_session_t
	Opaque session handle attached to a request.

Functions
int	cwist_app_use_session (cwist_app *app, const char *secret)
	Initialize session handling for an app with a signing secret.
void	cwist_app_set_session_name (cwist_app *app, const char *name)
	Set session cookie name. Defaults to "cwist_session".
void	cwist_app_set_session_max_age (cwist_app *app, int seconds)
	Set session cookie max-age in seconds. Defaults to 86400 (1 day).
cwist_session_t *	cwist_session_start (cwist_app *app, cwist_http_request *req, cwist_http_response *res)
	Load or create a session for the current request.
const char *	cwist_session_get (cwist_session_t *session, const char *key)
	Get a session value by key.
int	cwist_session_set (cwist_session_t *session, const char *key, const char *value)
	Set a session value. Value is copied.
void	cwist_session_delete (cwist_session_t *session, const char *key)
	Delete a session key.
int	cwist_session_commit (cwist_session_t *session, cwist_http_response *res)
	Persist the session to the response cookie.
void	cwist_session_invalidate (cwist_session_t *session)
	Mark the session for destruction (clears cookie on commit).
void	cwist_session_destroy (cwist_session_t *session)
	Destroy a session handle and its data.
cwist_middleware_func	cwist_mw_session (cwist_app *app)
	Session middleware factory.

Detailed Description

Signed client-side session cookie API.

Definition in file session.h.

Typedef Documentation

cwist_session_t

typedef struct cwist_session cwist_session_t

Opaque session handle attached to a request.

Definition at line 21 of file session.h.

Function Documentation

cwist_app_set_session_max_age()

void cwist_app_set_session_max_age	(	cwist_app *	app,
		int	seconds
	)

Set session cookie max-age in seconds. Defaults to 86400 (1 day).

Set session cookie max-age in seconds. Defaults to 86400 (1 day).

Parameters

app	Application to configure.
seconds	Cookie max age in seconds; must be > 0.

Definition at line 274 of file session.c.

References cap, and cwist_app::session_max_age.

cwist_app_set_session_name()

void cwist_app_set_session_name	(	cwist_app *	app,
		const char *	name
	)

Set session cookie name. Defaults to "cwist_session".

Set session cookie name. Defaults to "cwist_session".

Parameters

app	Application to configure.
name	Cookie name; copied internally.

Definition at line 259 of file session.c.

References cwist_free(), cwist_strdup(), and cwist_app::session_name.

cwist_app_use_session()

int cwist_app_use_session	(	cwist_app *	app,
		const char *	secret
	)

Initialize session handling for an app with a signing secret.

If secret is NULL, a random secret is generated. The secret is copied.

Parameters

app	Application context.
secret	HMAC-SHA256 secret (at least 32 bytes recommended).

Returns

0 on success, -1 on failure.

Initialize session handling for an app with a signing secret.

Parameters

app	Application to configure; must not be NULL.
secret	HMAC secret, or NULL/empty to generate one.

Returns

0 on success.

Return values

-1	if app is NULL or the secret could not be set.

Definition at line 239 of file session.c.

References cap, cwist_free(), CWIST_SESSION_DEFAULT_MAX_AGE, CWIST_SESSION_DEFAULT_NAME, cwist_strdup(), cwist_app::session_max_age, cwist_app::session_name, and cwist_app::session_secret.

Referenced by cwist_mw_session(), and cwist_session_start().

cwist_mw_session()

cwist_middleware_func cwist_mw_session

(

cwist_app *

app

)

Session middleware factory.

Session middleware factory.

Parameters

app	Application the middleware serves.

Returns

Middleware function that starts and commits sessions per request.

Definition at line 556 of file session.c.

References cap, cwist_app_use_session(), CWIST_UNUSED, and cwist_app::session_secret.

cwist_session_commit()

int cwist_session_commit	(	cwist_session_t *	session,
		cwist_http_response *	res
	)

Persist the session to the response cookie.

The session middleware calls this automatically after the handler. If you are not using the middleware, call it before sending the response.

Definition at line 477 of file session.c.

References cap, cwist_cookie_delete(), cwist_cookie_set(), cwist_free(), cwist_query_map_foreach(), cwist_cookie_options::http_only, cwist_cookie_options::max_age_seconds, cwist_cookie_options::path, and cwist_cookie_options::same_site.

cwist_session_delete()

void cwist_session_delete	(	cwist_session_t *	session,
		const char *	key
	)

Delete a session key.

Delete a session key.

Parameters

session	Session to update.
key	Key to remove.

Definition at line 443 of file session.c.

References cwist_query_map_delete().

cwist_session_destroy()

void cwist_session_destroy

(

cwist_session_t *

session

)

Destroy a session handle and its data.

Destroy a session handle and its data.

Parameters

session

Session to destroy; not usable afterwards.

Definition at line 464 of file session.c.

References cwist_free(), and cwist_query_map_destroy().

Referenced by cwist_http_request_destroy().

cwist_session_get()

const char * cwist_session_get	(	cwist_session_t *	session,
		const char *	key
	)

Get a session value by key.

Returns

Pointer to value, or NULL if missing.

Parameters

session	Session returned by cwist_session_start().
key	Key to look up.

Returns

Value string, or NULL if session/key is NULL or the key is not set. The returned pointer is owned by the session.

Definition at line 414 of file session.c.

References cap, and cwist_query_map_get().

cwist_session_invalidate()

void cwist_session_invalidate

(

cwist_session_t *

session

)

Mark the session for destruction (clears cookie on commit).

Mark the session for destruction (clears cookie on commit).

Parameters

session

Session to invalidate.

Definition at line 454 of file session.c.

cwist_session_set()

int cwist_session_set	(	cwist_session_t *	session,
		const char *	key,
		const char *	value
	)

Set a session value. Value is copied.

Returns

0 on success, -1 on failure.

Set a session value. Value is copied.

Parameters

session	Session to update.
key	Key to set; must not be NULL.
value	Value string, or NULL to store "".

Returns

0 on success.

Return values

-1	if session, its data, or key is NULL.

Definition at line 428 of file session.c.

References cwist_query_map_set().

cwist_session_start()

cwist_session_t * cwist_session_start	(	cwist_app *	app,
		cwist_http_request *	req,
		cwist_http_response *	res
	)

Load or create a session for the current request.

Usually called automatically by the session middleware. Handlers can call this if they need session access without the middleware.

Load or create a session for the current request.

Parameters

app	Application holding session configuration.
req	Request to attach the session to.
res	Response used for cookie parsing context.

Returns

New empty or loaded session on success, NULL on invalid arguments or allocation failure. Caller must free with cwist_session_destroy().

Definition at line 366 of file session.c.

References cap, cwist_alloc(), cwist_app_use_session(), cwist_cookie_get(), cwist_cookie_parse(), cwist_free(), cwist_http_header_get(), cwist_query_map_create(), cwist_query_map_destroy(), cwist_strdup(), cwist_http_request::headers, cwist_http_request::session, cwist_app::session_name, and cwist_app::session_secret.