класс CGI::Session

Родитель:: Объект

Обзор

Этот файл предоставляет класс CGI::Session, который обеспечивает поддержку сессий для скриптов CGI. Сессия — это последовательность HTTP-запросов и ответов, связанных вместе и ассоциированных с одним клиентом. Информация, связанная с сессией, хранится на сервере между запросами. Идентификатор сессии передаётся между клиентом и сервером с каждым запросом и ответом, прозрачно для пользователя. Это добавляет информацию о состоянии в протокол HTTP-запросов/ответов, который изначально бессостоятелен.

Жизненный цикл

Экземпляр CGI::Session создаётся из объекта CGI. По умолчанию этот экземпляр CGI::Session начнёт новую сессию, если её нет в данный момент, или продолжит текущую сессию для этого клиента, если она существует. Опция new_session может быть использована для того, чтобы всегда или никогда не создавать новую сессию. Подробнее см. в new().

delete() удаляет сессию из хранилища сессий. Однако она не удаляет идентификатор сессии с клиента. Если клиент отправляет другой запрос с тем же идентификатором, это приведёт к началу новой сессии с идентификатором старой сессии.

Установка и получение данных сессии.

Класс Session связывает данные с сессией в виде пар ключ-значение. Эти данные можно установить и получить, обращаясь к экземпляру Session по индексу с помощью '[]', практически так же, как и для хэшей (хотя другие методы хэшей не поддерживаются).

Когда обработка сессии завершена для запроса, сессия должна быть закрыта с помощью метода close(). Это сохранит состояние сессии в постоянное хранилище. Если вы хотите сохранить состояние сессии в постоянном хранилище, не завершая обработку сессии для этого запроса, вызовите метод update().

Хранение состояния сессии

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

CGI::Session::FileStore: хранит данные как обычный текст в плоском файле. Работает только с данными типа String. Это тип хранилища по умолчанию.
CGI::Session::MemoryStore: хранит данные в кэше памяти. Данные сохраняются только до тех пор, пока существует текущая экземпляр интерпретатора Ruby.
CGI::Session::PStore: хранит данные в сериализованном формате. Предоставляется файлом cgi/session/pstore.rb. Поддерживает данные любого типа, а также блокировку файлов и поддержку транзакций.

Пользовательские типы хранилищ также могут быть созданы путём определения класса с указанными методами:

new(session, options)
restore  # returns hash of session data.
update
close
delete

Изменение типа хранилища в середине сессии не работает. Обратите особое внимание, что по умолчанию файлы данных сессии FileStore и PStore имеют одинаковое имя. Если ваше приложение переключается с одного на другой без обеспечения того, что имена файлов будут разными, а клиенты всё ещё имеют старые сессии, оставшиеся в cookie, тогда всё сломается!

Поддержание идентификатора сессии.

Большая часть состояния сессии сохраняется на сервере. Однако идентификатор сессии должен передаваться вперёд и назад между клиентом и сервером, чтобы поддерживать ссылку на это состояние сессии.

Самый простой способ сделать это — с помощью cookie. Класс CGI::Session предоставляет прозрачную поддержку обмена идентификатором сессии через cookie, если клиент поддерживает cookie.

Если у клиента отключены cookie, идентификатор сессии должен быть включён в качестве параметра всех запросов, отправляемых клиентом на сервер. Класс CGI::Session в сочетании с классом CGI прозрачно добавит идентификатор сессии в качестве скрытого поля ввода во все формы, сгенерированные с помощью метода HTML-генерации CGI#form(). Встроенная поддержка других механизмов, таких как переписывание URL, не предоставляется. Вызывающий код отвечает за извлечение идентификатора сессии из атрибута #session_id и ручное кодирование его в URL и добавление в качестве скрытого ввода в HTML-формы, созданные другими механизмами. Также срок действия сессии не обрабатывается автоматически.

Примеры использования

Установка имени пользователя

require 'cgi'
require 'cgi/session'
require 'cgi/session/pstore'     # provides CGI::Session::PStore

cgi = CGI.new("html4")

session = CGI::Session.new(cgi,
    'database_manager' => CGI::Session::PStore,  # use PStore
    'session_key' => '_rb_sess_id',              # custom session key
    'session_expires' => Time.now + 30 * 60,     # 30 minute timeout
    'prefix' => 'pstore_sid_')                   # PStore option
if cgi.has_key?('user_name') and cgi['user_name'] != ''
    # coerce to String: cgi[] returns the
    # string-like CGI::QueryExtension::Value
    session['user_name'] = cgi['user_name'].to_s
elsif !session['user_name']
    session['user_name'] = "guest"
end
session.close

Безопасное создание новой сессии

require 'cgi'
require 'cgi/session'

cgi = CGI.new("html4")

# We make sure to delete an old session if one exists,
# not just to free resources, but to prevent the session
# from being maliciously hijacked later on.
begin
    session = CGI::Session.new(cgi, 'new_session' => false)
    session.delete
rescue ArgumentError  # if no old session
end
session = CGI::Session.new(cgi, 'new_session' => true)
session.close

Атрибуты

new_session[R]

Идентификатор этого сеанса.

session_id[R]

Идентификатор этого сеанса.

Методы публичного класса

new(request, option={}) Показать исходный код

# File lib/cgi/session.rb, line 248
def initialize(request, option={})
  @new_session = false
  session_key = option['session_key'] || '_session_id'
  session_id = option['session_id']
  unless session_id
    if option['new_session']
      session_id = create_new_id
      @new_session = true
    end
  end
  unless session_id
    if request.key?(session_key)
      session_id = request[session_key]
      session_id = session_id.read if session_id.respond_to?(:read)
    end
    unless session_id
      session_id, = request.cookies[session_key]
    end
    unless session_id
      unless option.fetch('new_session', true)
        raise ArgumentError, "session_key `%s' should be supplied"%session_key
      end
      session_id = create_new_id
      @new_session = true
    end
  end
  @session_id = session_id
  dbman = option['database_manager'] || FileStore
  begin
    @dbman = dbman::new(self, option)
  rescue NoSession
    unless option.fetch('new_session', true)
      raise ArgumentError, "invalid session_id `%s'"%session_id
    end
    session_id = @session_id = create_new_id unless session_id
    @new_session=true
    retry
  end
  request.instance_eval do
    @output_hidden = {session_key => session_id} unless option['no_hidden']
    @output_cookies =  [
      Cookie::new("name" => session_key,
      "value" => session_id,
      "expires" => option['session_expires'],
      "domain" => option['session_domain'],
      "secure" => option['session_secure'],
      "path" =>
      if option['session_path']
        option['session_path']
      elsif ENV["SCRIPT_NAME"]
        File::dirname(ENV["SCRIPT_NAME"])
      else
      ""
      end)
    ] unless option['no_cookies']
  end
  @dbprot = [@dbman]
  ObjectSpace::define_finalizer(self, Session::callback(@dbprot))
end

Создает новый объект CGI::Session для request.

request является экземпляром класса CGI (см. cgi.rb). option — это хеш параметров для инициализации экземпляра CGI::Session. Признаются следующие параметры:

session_key: имя параметра, используемого для идентификатора сеанса. По умолчанию — '_session_id'.
#session_id: идентификатор сеанса для использования. Если не указан, извлекается из параметра session_key запроса или автоматически генерируется для нового сеанса.
#new_session: если true, принудительно создать новый сеанс. Если не установлено, новый сеанс создается только если текущий отсутствует. Если false, новый сеанс никогда не создается, и если текущего сеанса нет, а параметр session_id не задан, генерируется исключение ArgumentError.
database_manager: имя класса, обеспечивающего хранение данных сеанса. Встроена поддержка FileStore (по умолчанию), MemoryStore, и PStore (из cgi/session/pstore.rb). Подробнее см. документацию по этим классам.

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

session_expires: время истечения текущего сеанса, как объект Time. Если не задано, сеанс завершится при закрытии браузера пользователя.
session_domain: домен хоста, для которого этот сеанс действителен. Если не задано, по умолчанию — хост сервера.
session_secure: если true, этот сеанс будет работать только по HTTPS.
session_path: путь, для которого действует этот сеанс. По умолчанию — директория скрипта CGI.

option также передается инициализатору класса хранения сеансов; см. документацию по каждому классу хранения сеансов для поддерживаемых параметров.

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

ПРЕДУПРЕЖДЕНИЕ поля output_hidden окружены тегом <fieldset> в HTML 4, что не скрыто во многих браузерах; вы можете отключить использование fieldset'ов с помощью кода, подобного следующему (см. blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-list/37805)

cgi = CGI.new("html4")
class << cgi
    undef_method :fieldset
end

Методы публичного экземпляра

[](key) Показать исходный код

# File lib/cgi/session.rb, line 309
def [](key)
  @data ||= @dbman.restore
  @data[key]
end

Получить данные сеанса для ключа key.

[]=(key, val) Показать исходный код

# File lib/cgi/session.rb, line 315
def []=(key, val)
  @write_lock ||= true
  @data ||= @dbman.restore
  @data[key] = val
end

Установить данные сеанса для ключа key.

close() Показать исходный код

# File lib/cgi/session.rb, line 329
def close
  @dbman.close
  @dbprot.clear
end

Сохранить данные сеанса на сервере и закрыть хранилище сеанса. Для некоторых типов хранилищ сеансов это пустая операция.

delete() Показать исходный код

# File lib/cgi/session.rb, line 338
def delete
  @dbman.delete
  @dbprot.clear
end

Удалить сеанс из хранилища. Также закрывает хранилище.

Обратите внимание, что данные сеанса не удаляются автоматически при истечении сеанса.

update() Показать исходный код

# File lib/cgi/session.rb, line 323
def update
  @dbman.update
end

Сохранить данные сеанса на сервере. Для некоторых типов хранилищ сеансов это пустая операция.

Методы закрытого экземпляра

create_new_id() Показать исходный код

# File lib/cgi/session.rb, line 171
def create_new_id
  require 'securerandom'
  begin
    # by OpenSSL, or system provided entropy pool
    session_id = SecureRandom.hex(16)
  rescue NotImplementedError
    # never happens on modern systems
    require 'digest'
    d = Digest('SHA512').new
    now = Time::now
    d.update(now.to_s)
    d.update(String(now.usec))
    d.update(String(rand(0)))
    d.update(String($$))
    d.update('foobar')
    session_id = d.hexdigest[0, 32]
  end
  session_id
end

Создать новый идентификатор сеанса.

Идентификатор сеанса — это безопасное случайное число, генерируемое SecureRandom, если возможно, в противном случае — хэш SHA512, основанный на времени, случайном числе и константе. Эта функция используется для автоматически генерируемых идентификаторов сеанса.

Ruby Core © 1993–2017 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.