Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/binary-person/rammerhead/llms.txt

Use this file to discover all available pages before exploring further.

Session stores are responsible for creating, retrieving, persisting, and expiring RammerheadSession objects. All stores implement the RammerheadSessionAbstractStore interface. Choose RammerheadSessionFileCache for production deployments that need sessions to survive restarts, and RammerheadSessionMemoryStore for development or stateless environments.

​
RammerheadSessionAbstractStore

The abstract base class that all session stores extend. It cannot be instantiated directly. Concrete stores must implement keys, has, get, add, delete, and addSerializedSession.

​
Methods

​
attachToProxy

store.attachToProxy(proxy, removeExistingSessions?)
Wires the store to a RammerheadProxy instance by setting proxy.openSessions = this. Call this once after constructing both the proxy and the store.
​
proxy
RammerheadProxy
required
The proxy instance to attach to.
​
removeExistingSessions
boolean
default:"true"
When true, all sessions currently tracked by proxy.openSessions are closed before the store takes over.

​
keys

store.keys()
​
returns
string[]
Array of all session IDs currently tracked by the store.

​
has

store.has(id)
​
id
string
required
Session ID to check.
​
returns
boolean
true if the session exists in the store.

​
get

store.get(id, updateActiveTimestamp?)
Retrieves a session by ID.
​
id
string
required
Session ID to retrieve.
​
updateActiveTimestamp
boolean
default:"true"
When true, calls session.updateLastUsed() before returning.
​
returns
RammerheadSession | undefined
The session, or undefined if it does not exist.

​
add

store.add(id)
Creates a new session with the given ID and adds it to the store.
​
id
string
required
Unique ID for the new session.
​
returns
RammerheadSession
The newly created session.

​
delete

store.delete(id)
Removes a session from the store.
​
id
string
required
ID of the session to remove.
​
returns
boolean
true if the session existed and was deleted.

​
addSerializedSession

store.addSerializedSession(id, serializedSession)
Deserializes and imports a session that was previously exported with session.serializeSession().
​
id
string
required
ID to assign to the imported session.
​
serializedSession
string
required
JSON string from RammerheadSession.serializeSession().

​
close

store.close()
Optional lifecycle method. RammerheadSessionFileCache overrides this to flush in-memory sessions to disk before shutdown. RammerheadSessionMemoryStore does not implement it.

​
RammerheadSessionFileCache

Extends RammerheadSessionAbstractStore with disk persistence. Active sessions are kept in a memory cache for fast access. Idle sessions are serialized to .rhfsession files on disk and reloaded on demand. A background interval periodically removes sessions that exceed staleTimeout or maxToLive. This is the recommended store for production deployments.

​
Constructor

const store = new RammerheadSessionFileCache(options);
​
saveDirectory
string
default:"'<package_root>/sessions'"
Directory where session files are stored. The directory must already exist.
​
logger
RammerheadLogging
default:"new RammerheadLogging({ logLevel: 'disabled' })"
Logger instance for store operations.
​
cacheTimeout
number
default:"1200000"
Milliseconds of inactivity after which an in-memory session is flushed to disk. Default is 20 minutes (1000 * 60 * 20).
​
cacheCheckInterval
number
default:"600000"
How often (in milliseconds) the background interval checks for sessions to flush. Default is 10 minutes (1000 * 60 * 10).
​
deleteUnused
boolean
default:"true"
When true, sessions that were never used (i.e. lastUsed === createdAt) are deleted instead of being written to disk during a cache flush.
​
deleteCorruptedSessions
boolean
default:"true"
When true, session files that fail JSON parsing are automatically deleted and a warning is logged. This happens when Node exits abruptly while writing a session file.
​
staleCleanupOptions
object | null
Configuration for the background stale-session cleanup. Set to null to disable stale cleanup entirely. The class constructor defaults to staleTimeout: 1 day, maxToLive: 4 days, staleCheckInterval: 1 hour. The built-in server (src/config.js) overrides these to staleTimeout: 3 days, maxToLive: null, staleCheckInterval: 6 hours.

​
RammerheadSessionMemoryStore

Extends RammerheadSessionAbstractStore with a purely in-memory Map. All sessions are lost when the process exits. A background interval removes sessions that exceed staleTimeout or maxToLive. Use RammerheadSessionMemoryStore during development, in single-request test environments, or when session persistence is explicitly not required.

​
Constructor

const store = new RammerheadSessionMemoryStore(options);
​
logger
RammerheadLogging
default:"new RammerheadLogging({ logLevel: 'disabled' })"
Logger instance for store operations.
​
staleTimeout
number | null
default:"1800000"
Milliseconds of inactivity after which a session is deleted. Default is 30 minutes (1000 * 60 * 30). Set to null to disable.
​
maxToLive
number | null
default:"14400000"
Maximum session lifetime in milliseconds regardless of activity. Default is 4 hours (1000 * 60 * 60 * 4). Set to null to disable.
​
cleanupInterval
number
default:"60000"
How often (in milliseconds) the background cleanup interval runs. Default is 1 minute.

​
Usage examples

const {
  RammerheadProxy,
  RammerheadSessionFileCache,
  RammerheadLogging
} = require('rammerhead');
const { randomUUID } = require('crypto');

const logger = new RammerheadLogging({ logLevel: 'info' });
const proxy = new RammerheadProxy({ port: 8080, crossDomainPort: 8081, logger });

const store = new RammerheadSessionFileCache({
  saveDirectory: './sessions',
  logger,
  cacheTimeout: 1000 * 60 * 15,       // flush after 15 min inactivity
  staleCleanupOptions: {
    staleTimeout: 1000 * 60 * 60 * 12, // delete after 12 h inactivity
    maxToLive: 1000 * 60 * 60 * 72,    // delete after 3 days
    staleCheckInterval: 1000 * 60 * 30  // check every 30 min
  }
});

store.attachToProxy(proxy);

// Create a session
const id = randomUUID();
const session = store.add(id);

// Later in a request handler
const existing = store.get(id);

// Export and re-import a session
const json = existing.serializeSession();
store.addSerializedSession('imported-id', json);
Always call store.close() (or ensure Node’s process exit handlers do so) when using RammerheadSessionFileCache in production. This triggers a final flush of in-memory sessions to disk so no session data is lost on graceful shutdown.

Build docs developers (and LLMs) love

Get started for freeTalk to us