Промежуточное ПО экспресс-сессии "Перевод"

Express

предисловие: Недавно использованныйexpress-sessionMiddleware, некоторые параметры не очень понятны при просмотре и использовании, перевод документа занял некоторое время.

Самыми запутанными среди часто используемых настроек являются атрибуты resave и saveUnintialized.Относительно этих двух атрибутов ссылка взята из обновления сообщества CNODE.понятное объяснение:

resave: означает, что файл cookie сеанса сбрасывается для каждого запроса. Если срок действия файла cookie истекает через 10 минут, каждый запрос будет установлен еще на 10 минут.
saveUninitialized: означает, что независимо от того, есть файл cookie сеанса или нет, файл cookie сеанса устанавливается для каждого запроса и по умолчанию помечен как connect.sid.

Далее текст:

Installation

это пропускnpm registryгодный к употреблениюNode.jsмодуль. используйте следующееnpm installкоманду для завершения установки.

$ npm install express-session

API

var session = require('express-session');

sessions(options)

Создайте промежуточное программное обеспечение сеанса с заданными параметрами.

Уведомление: В файле cookie хранится только идентификатор сеанса, а не сами данные сеанса. Данные сеанса хранятся на стороне сервера.

Уведомление: Начиная с версии 1.5.0 этот модуль больше не требуетсяcookie-parserпромежуточное ПО для запуска. Этот модуль теперь читает и записывает файлы cookie непосредственно в req/res. Когда этот модуль и cookie-парсерsecretИспользование cookie-parser может вызвать проблемы при несогласованности.

предупреждать: хранилище сеансов на стороне сервера по умолчанию, MemoryStore,специальноНе предназначен для производственных сред. В большинстве случаев он может вызвать утечку памяти, не масштабируется за пределы одного процесса и предназначен для отладки и разработки.

Список мест хранения см.Совместимое хранилище сеансов

Options

экспресс-сеанс получает следующие параметры в объекте опций

cookie

Объект настроек для файла cookie идентификатора сеанса. По умолчанию{ path: '/', httpOnly: true, secure: false, maxAge: null }.

Дополнительные настройки для следующих параметров помещаются в объект cookie.

cookie.domain

Укажите домен для атрибута Set-Cookie. По умолчанию домен не установлен, и большинство клиентов будут рассматривать файл cookie как применимый только к текущему домену.

cookie.expires

Укажите объект Date для Expires в свойстве Set-Cookie. По умолчанию срок действия не установлен, большинство клиентов будут рассматривать это как «непостоянный файл cookie» и удалять файл cookie в таких сценариях, как выход из приложения браузера.

Уведомление: Если в объекте параметров установлены оба параметра expires и maxAge, будет использоваться последнее свойство, определенное в объекте.

УведомлениеПараметр :expires не следует устанавливать напрямую, вместо этого следует использовать только параметр maxAge.

cookie.httpOnly

Укажите логическое значение для HttpOnly в атрибуте Set-Cookie. При значении true атрибут HttpOnly устанавливается, в противном случае он не устанавливается. По умолчанию установлено свойство HttpOnly.

Уведомление: будьте осторожны при установке этого значения в true , так как клиенты, совместимые с протоколом, не позволят JavaScript просматривать файлы cookie в document.cookie .

cookie.maxAge

Указывает числовое значение (в миллисекундах), используемое при оценке Expires в свойстве Set-Cookie. Это делается путем взятия текущего времени сервера и добавления к нему миллисекунд maxAge для расчета даты и времени Expires. maxAge не установлен по умолчанию.

Уведомление: Если в объекте параметров установлены оба параметра expires и maxAge, будет использоваться последнее свойство, определенное в объекте.

cookie.path

Укажите значение Path для свойства Set-Cookie. По умолчанию это значение установлено на'/', который является корневым путем в домене.

cookie.sameSite

Укажите логическое или строковое значение для SameSite в атрибуте Set-Cookie. в,

  • trueАтрибуту SameSite будет присвоено значение Strict для строгого применения одного и того же сайта.
  • falseНе будет атрибута SameSite.
  • 'lax'Для атрибута SameSite задано значение Lax, что упрощает принудительное использование одного и того же сайта.
  • 'strict'Для атрибута SameSite установлено значение Strict для строгого применения одного и того же сайта.

Более подробную информацию о различных обязательных уровнях можно найти в мелком шрифте.tools.I ETF.org/HTML/draft-…

Уведомление: это свойство не было полностью стандартизировано и может измениться в будущем. Это означает, что многие клиенты могут игнорировать это свойство, пока полностью его не поймут.

cookie.secure

Укажите логическое значение для Secure в свойстве Set-Cookie. При значении true свойство Secure устанавливается, в противном случае — нет. Свойство Secure по умолчанию не задано.

Уведомление: будьте осторожны, устанавливая для этого значения значение true, поскольку клиенты, соответствующие протоколу, не будут отправлять файлы cookie обратно на сервер, если браузер не установит HTTPS-соединение.

Пожалуйста, обрати вниманиеsecure: trueявляется рекомендуемым вариантом. Однако для этого требуется веб-сайт с поддержкой HTTPS, который необходим для безопасных файлов cookie. Если установлен безопасный режим и вы получаете доступ к своему сайту через HTTP, файл cookie не будет установлен. Если вы используете node.js за прокси и устанавливаетеsecure: true, вам нужно установить «доверительный прокси» в экспресс:

var app = express()
app.set('trust proxy', 1) // trust first proxy
app.use(session({
  secret: 'keyboard cat',
  resave: false,
  saveUninitialized: true,
  cookie: { secure: true }
}))

Чтобы использовать безопасные файлы cookie в производственной среде, а также разрешить тестирование в среде разработки, нижеследующее основано на явномNODE_ENVПример с включенным параметром:

var app = express()
var sess = {
  secret: 'keyboard cat',
  cookie: {}
}
 
if (app.get('env') === 'production') {
  app.set('trust proxy', 1) // trust first proxy
  sess.cookie.secure = true // serve secure cookies
}
 
app.use(session(sess))

Для параметра cookie.secure также можно установить специальное значение."auto"чтобы этот параметр автоматически соответствовал безопасности установленного соединения. Используйте этот параметр с осторожностью, если сайт можно использовать как для HTTP, так и для HTTPS, потому что после установки атрибута HTTPS файла cookie файл cookie больше не будет виден для HTTP. Это полезно, когда «доверенный прокси-сервер» Express правильно настроен для упрощения разработки и производственной настройки.

genid

Функция для вызова для создания нового идентификатора сеанса. Предоставьте функцию, которая возвращает строку, которая будет использоваться в качестве идентификатора сеанса. Если вы хотите использовать какое-либо значение, добавленное к req при генерации идентификатора, функция получила req в качестве первого аргумента.

По умолчанию используетсяuid-safeбиблиотека для генерации функций ID.

Уведомление: Будьте осторожны, генерируйте уникальные идентификаторы, чтобы ваши сеансы не конфликтовали.

app.use(session({
  genid: function(req) {
    return genuuid() // use UUIDs for session IDs
  },
  secret: 'keyboard cat'
}))
name

Имя файла cookie с идентификатором сеанса, установленным в ответе (и считанным из запроса).

По умолчанию"connect.sid".

Уведомление: Если у вас есть несколько приложений, работающих на одном и том же имени хоста (только имя, т. е. localhost или 127.0.0.1; разные протоколы (схема) и порты (порт) не называют разные имена хостов), то вам нужно хранить файл cookie сеанса отдельно от друг друга. Самый простой способ — установить разные имена для каждого приложения.

proxy

Доверяйте обратному прокси-серверу при установке безопасных файлов cookie (через"X-Forwarded-Proto"голова).

По умолчаниюundefined.

  • trueвыражать"X-Forwarded-Proto"заголовок будет использоваться.
  • falseУказывает, что все заголовки игнорируются и соединение считается безопасным только при наличии прямого соединения TLS/SSL.
  • undefinedУказывает на использование «доверительного прокси» из Express.
resave

Принудительно сохраняет сеанс обратно в хранилище сеансов, даже если сеанс ни разу не изменялся во время запроса. В зависимости от вашего хранилища это может быть необходимо, но это может также создать состояние гонки, когда клиент отправляет два параллельных запроса на ваш сервер, и изменения, сделанные в сеансе одним запросом A, могут закончиться в другом запросе B Переопределить, даже если запрос B не вносил никаких изменений (это поведение зависит от используемого вами хранилища сеансов).

Значение по умолчанию — true, но значение по умолчанию устарело, поскольку оно будет изменено в будущем. Пожалуйста, изучите этот параметр и выберите вариант, который подходит для вашего варианта использования. В общем, вы захотите выбрать false.

Как узнать, необходим ли этот параметр для моего хранилища сеансов? Лучший способ — проверить свой магазин, чтобы узнать, реализует ли он сенсорный метод. Если это так, вы можете безопасно установить для сохранения значение false. Если он не реализует сенсорный метод и в вашем магазине установлена ​​дата истечения срока действия в сохраненных сеансах, вам может потребоваться установитьresave: false.

rolling

Принудительно устанавливает файл cookie идентификатора сеанса для каждого ответа. истечение сбрасывается до исходного maxAge, сбрасывая обратный отсчет срока действия.

Значение по умолчанию неверно.

Уведомление: если для этого параметра установлено значение true, а для параметра saveUninitialized установлено значение false, в ответах с неинициализированными сеансами не будут устанавливаться файлы cookie.

saveUninitialized

Принудительное сохранение неинициализированного сеанса обратно в хранилище. Когда сеанс новый, но не был изменен, мы говорим, что он не инициализирован. Выбор значения false полезен для реализации сеансов входа в систему, так как он уменьшает использование хранилища сервера и подчиняется правилу запроса разрешения перед установкой файлов cookie. Выбор значения false также помогает в условиях гонки, когда клиент делает параллельный запрос без обратного вызова.

Значение по умолчанию — true, но значение по умолчанию устарело, поскольку оно будет изменено в будущем. Пожалуйста, изучите этот параметр и выберите вариант, который подходит для вашего варианта использования.

Уведомление: Если вы используете сеанс в сочетании с PassportJS, PassportJS добавит пустой объект Passport в сеанс для пользователя после аутентификации пользователя, что будет рассматриваться как модификация сеанса, что приведет к сохранению сеанса.Это было исправлено в PassportJS 0.3.0.

secret

Обязательный параметр

Это секрет, используемый для подписи файла cookie идентификатора сеанса. Это может быть строка одного секрета или массив из нескольких секретов. Если предоставлен набор секретов, только первый элемент будет использоваться для подписи файла cookie идентификатора сеанса, все элементы будут учитываться при проверке подписи запроса.

store

Экземпляр хранилища сеансов по умолчанию представляет собой новый экземпляр MemoryStore.

unset

Контролирует результат отмены req.session (путем удаления, установки значения null и т. д.).

По умолчанию'keep'

  • 'destroy'Указывает, что сеанс будет уничтожен (удален) после завершения ответа.
  • 'keep'Указывает, что сессия в магазине будет сохранена, но изменения, сделанные во время запроса, будут проигнорированы и не сохранены.

req.session

Чтобы сохранить или получить доступ к данным сеанса, просто используйте атрибут запроса req.session, который (обычно) сериализуется хранилищем как сеанс, поэтому, как правило, вложенные объекты также приемлемы. В следующем примере показан счетчик просмотров, основанный на конкретном пользователе:

// Use the session middleware
app.use(session({ secret: 'keyboard cat', cookie: { maxAge: 60000 }}))
 
// Access the session as req.session
app.get('/', function(req, res, next) {
  if (req.session.views) {
    req.session.views++
    res.setHeader('Content-Type', 'text/html')
    res.write('<p>views: ' + req.session.views + '</p>')
    res.write('<p>expires in: ' + (req.session.cookie.maxAge / 1000) + 's</p>')
    res.end()
  } else {
    req.session.views = 1
    res.end('welcome to the session demo. refresh!')
  }
})

Session.regenerate(callback)

Чтобы восстановить сеанс, просто вызовите этот метод. После завершения новый SID и экземпляр Session будут инициализированы в req.session и будет вызван обратный вызов.

req.session.regenerate(function(err) {
  // will have a new session here
})

Session.destroy(callback)

Уничтожьте сеанс и отключите свойство req.session. обратный вызов будет вызван после завершения.

req.session.destroy(function(err) {
  // cannot access session here
})

Session.reload(callback)

Перезагрузите данные сеанса из хранилища и повторно заполните объект req.session. обратный вызов будет вызван после завершения.

req.session.reload(function(err) {
  // session updated
})

Session.save(callback)

Сохраните сеанс обратно в хранилище, заменив содержимое хранилища содержимым в памяти (хотя хранилище может выполнять и другие действия — подробное описание его поведения см. в документации к хранилищу).

Этот метод автоматически вызывается в конце ответа HTTP, если данные сеанса изменяются (хотя это поведение можно изменить с помощью различных параметров в конструкторе промежуточного программного обеспечения). Поэтому, как правило, этот метод не нужно вызывать вручную.

Существуют ситуации, когда вызов этого метода был бы полезен, например, перенаправления, долгоживущие запросы или веб-сокеты.

req.session.save(function(err) {
  // session saved
})

Session.touch(callback)

Обновите свойство .maxAge. Обычно этот метод не нужно вызывать, потому что промежуточное программное обеспечение сеанса делает это за вас.

req.session.id

Каждая сессия имеет уникальный идентификатор, связанный с ней. Это свойство является псевдонимом для req.sessionID и не может быть изменено. Это свойство было добавлено, чтобы сделать идентификатор сеанса доступным из объекта сеанса.

req.session.cookie

Каждый сеанс сопровождается уникальным файлом cookie. Это позволяет вам изменить файл cookie сеанса для каждого посетителя. Например, мы можем установить для req.session.cookie.expires значение false, чтобы файл cookie сохранялся только на время действия пользовательского агента.

Cookie.maxAge

req.session.cookie.maxAge вернет оставшееся время в миллисекундах, мы также можем переназначить новое значение, чтобы соответствующим образом настроить свойство .expires. Следующий код эквивалентен:

var hour = 3600000
req.session.cookie.expires = new Date(Date.now() + hour)
req.session.cookie.maxAge = hour

Например, если для параметра maxAge задано значение 60000 (одна минута), через 30 секунд он вернет значение 30000. Зная, что текущий запрос выполнен, вызов req.session.touch() в это время сбросит req.session.maxAge в исходное состояние. Первоначальный значение.

req.session.cookie.maxAge // => 30000

req.sessionID

Чтобы получить идентификатор загруженного сеанса, обратитесь к свойству запроса req.sessionID. Это значение доступно только для чтения при загрузке или создании сеанса.

Session Store Implementation

Каждое хранилище сеансов должно быть EventEmitter и реализовывать определенные методы. Следующие методы являются обязательными, рекомендуемыми и необязательными.

  • Обязательные методы — это методы, которые этот модуль всегда будет вызывать в хранилище.
  • Рекомендуемый метод — это метод, который этот модуль будет вызывать в хранилище, если он доступен.
  • Необязательные методы — это методы, которые этот модуль вообще не будет вызывать.

Пример реализации см.connect-redisсклад.

store.all(callback)

по желанию

Этот необязательный метод используется для получения всех сеансов в хранилище в виде массива. Метод обратного вызова следует использовать какcallback(error, sessions).

store.destroy(sid, callback)

обязательный

Этот обязательный метод уничтожает (удаляет) сеанс в хранилище на основе заданного идентификатора сеанса. После удаления сеанса функция обратного вызова должна использоваться какcallback(error).

store.clear(callback)

по желанию

Этот необязательный метод используется для удаления всех сеансов в хранилище. После того, как хранилище опустеет, функция обратного вызова должна использоваться какcallback(error).

store.length(callback)

по желанию

Этот необязательный метод используется для получения количества всех сеансов в хранилище. Функция обратного вызова должна использоваться какcallback(error, len).

store.get(sid, callback)

обязательный

Этот обязательный метод извлекает сеанс из хранилища на основе заданного идентификатора сеанса. Функция обратного вызова должна использоваться какcallback(error, session).

Параметр сеанса в функции обратного вызова сеанса должен быть объектом сеанса, если сеанс был найден, в противном случае он должен быть нулевым или неопределенным, если сеанс не найден (и не было ошибки). когдаerror.code === 'ENOENT'вести себя какcallback(null, null), это частный случай.

store.set(sid, session, callback)

обязательный

Этот обязательный метод сохраняет сеанс в хранилище на основе заданного идентификатора сеанса и объекта сеанса. После того, как сессия сохранена в хранилище, функция обратного вызова должна использоваться какcallback(error).

store.touch(sid, session, callback)

рекомендовать

Рекомендуемый метод «прикасается» к данному объекту сеанса на основе заданного идентификатора сеанса и объекта сеанса. После того, как сеанс «тронут», функция обратного вызова должна использоваться какcallback(error).

Этот метод в основном используется магазином для автоматического удаления простаивающих сеансов, и этот метод используется, чтобы сигнализировать магазину, что данный сеанс активен, возможно, сбрасывая таймер простоя.

Compatible Session Stores

Следующие модули реализуют хранилище сеансов, совместимое с этим модулем. Пожалуйста, поднимите PULL REQUEST, чтобы добавить другие модули :)

Здесь перечислены только две реализации магазина, см. подробнееоригинальный документ

connect-db2: Хранилище сеансов на основе IBM DB2, созданное с использованием модуля ibm_db.

connect-mongo: хранилище сеансов на основе SQL Server.

Example

Простой пример использования экспресс-сессии для хранения посещений страниц для пользователей:

var express = require('express')
var parseurl = require('parseurl')
var session = require('express-session')
 
var app = express()
 
app.use(session({
  secret: 'keyboard cat',
  resave: false,
  saveUninitialized: true
}))
 
app.use(function (req, res, next) {
  if (!req.session.views) {
    req.session.views = {}
  }
 
  // get the url pathname
  var pathname = parseurl(req).pathname
 
  // count the views
  req.session.views[pathname] = (req.session.views[pathname] || 0) + 1
 
  next()
})
 
app.get('/foo', function (req, res, next) {
  res.send('you viewed this page ' + req.session.views['/foo'] + ' times')
})
 
app.get('/bar', function (req, res, next) {
  res.send('you viewed this page ' + req.session.views['/bar'] + ' times')
})

License

MIT

Keywords

none

Категории