Sessions

Not only does Jaguar supports [sessions] out-of-the-box, it also does the parsing and updating of the session data for you auto-magically.

An object of type [Session][Doc::Session] holds session data for a particular request. This object for current request can be accessed through [session][Doc::Context::session] member of [Context][Doc::Context] object.

Getting the Session object of current request:

  server.get('/api/add/:item', (ctx) async {
    final Session session = await ctx.session;
    // ...
  });

main() async {
  final server = new Jaguar();
  server.get('/api/add/:item', (ctx) async {
    final Session session = await ctx.req.session;
    final String newItem = ctx.pathParams.item;

    final List<String> items = (session['items'] ?? '').split(',');

    // Add item to shopping cart stored on session
    if (!items.contains(newItem)) {
      items.add(newItem);
      session['items'] = items.join(',');
    }

    return Response.redirect('/');
  });
  server.get('/api/remove/:item', (ctx) async {
    final Session session = await ctx.req.session;
    final String newItem = ctx.pathParams.item;

    final List<String> items = (session['items'] ?? '').split(',');

    // Remove item from shopping cart stored on session
    if (items.contains(newItem)) {
      items.remove(newItem);
      session['items'] = items.join(',');
    }

    return Response.redirect('/');
  });
  await server.serve();
}

Example projects

1. Simple example using vanilla Sessions

What's next?

TODO

Session provides a way to persist and store data about a particular set of requests and share that data across those requests. Typical use cases are:

1. Store information about user logged-in to the application
2. Store items added to shopping cart in retail application

Session data consists of key-value string pairs.

Session storage

On HTTP request

The session data can either be stored in request cookies or headers itself. This is simpler to get going and doesn't need any backend database.

On the server

Alternatively, session identifier can be stored on request cookies or headers, while the actual session data is stored in Dart Map or a database (ex: MongoDb, PostgreSQL, Reddis, etc).

SessionManager

SessionManager is responsible for:

1. Parsing session identifier & information from the HTTP request
2. Writing session identifier & information to HTTP response
3. Loading and storing session data from session store

Parsing and writing response

Parsing

parseRequest parses the request and obtains the session information provided the Request object. Usually called before route handler execution, authenticator and authorizer, so that parsed data is available for further use.

Writing response

writeResponse writes session information to the provided Response object. Usually called at the end of the route chain.

Managing session

This section explains how to create, update and delete a session.

Creating session

createSession creates a new session with given session data. Might delete the existing session if it had any.

Update session

updateSession updates the existing session by adding the provided key-value pair to the output session information.

Delete session

deleteSession deletes the existing session.

Accessing session values

InValue

InValues are read-only key-value session data that are parsed from the request. InValues can be accessed using getInValue method or inValues member.

Out value

OutValues is the new session data that will be written to the response. OutValues can be accessed using outValues member.