session-storage-memcache

Memcache session storage

Memcache session storage for remix/session. Use this package when app servers need to share session state through Memcache.

Installation

npm

npm install remix

Memcache storage uses TCP sockets and requires a Node.js runtime.

API Reference

createMemcacheSessionStorage

Create a Memcache-backed session storage instance.

server · string · required

Memcache server address in the format host:port (e.g., '127.0.0.1:11211')

options · MemcacheSessionStorageOptions

Configuration options

MemcacheSessionStorageOptions

keyPrefix · string

Prefix for all Memcache keys. Defaults to 'remix:session:'.

ttlSeconds · number

Time-to-live in seconds for sessions. Defaults to 0 (no expiration).

useUnknownIds · boolean

Whether to reuse unknown session IDs sent by the client. Defaults to false.

Returns

storage · SessionStorage

A SessionStorage instance backed by Memcache

Usage Examples

Basic Setup

Connect to Memcache and create session storage:

import { createMemcacheSessionStorage } from 'remix/session-storage-memcache'

let sessionStorage = createMemcacheSessionStorage('127.0.0.1:11211', {
  keyPrefix: 'myapp:session:',
  ttlSeconds: 60 * 60 * 24 * 7, // 7 days
})

With Session Middleware

Use with session middleware for automatic session management:

import { createMemcacheSessionStorage } from 'remix/session-storage-memcache'
import { session } from 'remix/session-middleware'
import { createRouter } from 'remix/fetch-router'
import { createCookie } from 'remix/cookie'

let sessionStorage = createMemcacheSessionStorage('127.0.0.1:11211', {
  keyPrefix: 'myapp:session:',
  ttlSeconds: 60 * 60 * 24 * 7,
})

let sessionCookie = createCookie('session', {
  secrets: [process.env.SESSION_SECRET!],
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax',
  maxAge: 60 * 60 * 24 * 7,
})

let router = createRouter({
  middleware: [
    session({
      storage: sessionStorage,
      cookie: sessionCookie,
    }),
  ],
})

Manual Session Management

Manage sessions manually:

import { createMemcacheSessionStorage } from 'remix/session-storage-memcache'
import { createSession } from 'remix/session'

let sessionStorage = createMemcacheSessionStorage('127.0.0.1:11211')

// Create a new session
let session = createSession()
session.set('userId', '123')
session.set('username', 'alice')

// Commit to Memcache
await sessionStorage.commitSession(session)

// Read from Memcache
let loadedSession = await sessionStorage.readSession(session.id)
console.log(loadedSession.get('userId')) // '123'

// Destroy session
await sessionStorage.destroySession(session)

Production Configuration

Use environment variables for production:

import { createMemcacheSessionStorage } from 'remix/session-storage-memcache'

let sessionStorage = createMemcacheSessionStorage(
  process.env.MEMCACHE_SERVER || '127.0.0.1:11211',
  {
    keyPrefix: 'prod:session:',
    ttlSeconds: 60 * 60 * 24 * 30, // 30 days
  }
)

Multiple Memcache Servers

For multiple servers, you’ll need to handle connection pooling at a higher level. The storage connects to one server at a time:

import { createMemcacheSessionStorage } from 'remix/session-storage-memcache'

// Connect to primary server
let primaryStorage = createMemcacheSessionStorage('memcache1.example.com:11211', {
  keyPrefix: 'session:',
})

// Fallback to secondary if primary fails
let secondaryStorage = createMemcacheSessionStorage('memcache2.example.com:11211', {
  keyPrefix: 'session:',
})

Session Expiration

Set appropriate TTL to prevent unlimited session growth:

import { createMemcacheSessionStorage } from 'remix/session-storage-memcache'

let sessionStorage = createMemcacheSessionStorage('127.0.0.1:11211', {
  // Short TTL for sensitive sessions
  ttlSeconds: 60 * 15, // 15 minutes
})

Key Prefixes for Isolation

Use key prefixes to isolate sessions from different applications:

import { createMemcacheSessionStorage } from 'remix/session-storage-memcache'

// App 1
let app1Storage = createMemcacheSessionStorage('127.0.0.1:11211', {
  keyPrefix: 'app1:session:',
})

// App 2
let app2Storage = createMemcacheSessionStorage('127.0.0.1:11211', {
  keyPrefix: 'app2:session:',
})

Environment Variables

Store Memcache configuration in environment variables:

.env

MEMCACHE_SERVER=127.0.0.1:11211
SESSION_SECRET=your-secret-key

Best Practices

• Always set a TTL to prevent unlimited session growth
• Use meaningful key prefixes to organize sessions
• Handle connection errors gracefully
• Set appropriate maxAge on session cookies to match TTL
• Monitor Memcache memory usage and evictions
• Use multiple Memcache servers for redundancy
• Consider Memcache memory limits when sizing sessions

Performance Considerations

• Memcache is very fast for session storage
• Network latency is the primary bottleneck
• Memcache uses LRU eviction when memory is full
• Monitor cache hit rates to ensure adequate memory
• Consider using connection pooling for high-traffic apps

Limitations

• Requires Node.js (uses TCP sockets)
• Sessions may be evicted if Memcache runs out of memory
• No persistence - sessions are lost if Memcache restarts
• Single server connection per storage instance

Related Documentation

Session

Core session API and management

Session Middleware

Automatic session management middleware