Sessions

Cookie-based sessions via req.session.

Enabling sessions

bxsapp.use( boxExpressSession() )

Once registered, every request gets a session — a new one is created and a session cookie set if the request didn't already carry one.

Reading and writing session data

bxsapp.get( "/visit-count", ( req, res ) => {
    req.session.views = ( req.session.views ?: 0 ) + 1
    res.json( { views: req.session.views, sessionID: req.sessionID } )
} )

req.session is a plain struct — read and write it directly. It's persisted server-side and keyed by req.sessionID, which is also readable directly for logging or debugging.

Ending a session

bxsapp.get( "/logout", ( req, res ) => {
    req.destroySession()
    res.json( { loggedOut: true } )
} )

req.destroySession() clears the stored session data and expires the session cookie on the client (Max-Age=0) — the next request starts a fresh session.

Durable sessions (boxExpressCacheStore)

The default session store is an in-memory ConcurrentHashMap on the Session instance — fine for one process, gone on restart, and not shared across a cluster. boxExpressCacheStore() is a ready-made store backed by BoxLang's own cache() service instead:

bxsapp.use( boxExpressSession( { store: boxExpressCacheStore( "sessions" ) } ) )

The named cache ("sessions" here) has to already be registered in boxlang.json — this doesn't create one, it just talks to it. Point that cache's objectStore at "JDBCStore" and session data lands in a real SQL table instead of memory, surviving a restart and shared across every process pointed at the same database:

json — boxlang.json"caches": {
  "default": { "provider": "BoxCacheProvider" },
  "sessions": {
    "provider": "BoxCacheProvider",
    "properties": {
      "objectStore": "JDBCStore",
      "datasource": "sessionDB",
      "table": "boxlang_sessions",
      "autoCreate": false
    }
  }
}

See Configuration for the full datasource block. Two separate things worth knowing, found by actually running it against a real database rather than trusting the docs:

• Keep "default" in the caches block alongside your own entry — overriding caches replaces it wholesale, and BoxLang's own query engine depends on a "default" cache existing somewhere in it.

The session cookie

The session cookie is named connect.sid, matching Express's own default — familiar if you're coming from Node. It's set with HttpOnly by default, the same as res.cookie().