# class CGI::Session::FileStore

File-based session storage class.

Implements session storage as a flat file of 'key=value' values. This storage type only works directly with `String` values; the user is responsible for converting other types to Strings when storing and from Strings when retrieving.

### Public Class Methods

new(session, option={}) click to toggle source

Create a new `FileStore` instance.

This constructor is used internally by `CGI::Session`. The user does not generally need to call it directly.

`session` is the session for which this instance is being created. The session id must only contain alphanumeric characters; automatically generated session ids observe this requirement.

`option` is a hash of options for the initializer. The following options are recognised:

tmpdir

  the directory to use for storing the `FileStore` file. Defaults to `Dir::tmpdir` (generally “/tmp” on Unix systems).

prefix

  the prefix to add to the session id when generating the filename for this session's `FileStore` file. Defaults to “cgi_sid_”.

suffix

  the prefix to add to the session id when generating the filename for this session's `FileStore` file. Defaults to the empty string.

This session's `FileStore` file will be created if it does not exist, or opened if it does.

    # File lib/cgi/session.rb, line 375
    def initialize(session, option={})
      dir = option['tmpdir'] || Dir::tmpdir
      prefix = option['prefix'] || 'cgi_sid_'
      suffix = option['suffix'] || ''
      id = session.session_id
      require 'digest/md5'
      md5 = Digest::MD5.hexdigest(id)[0,16]
      @path = dir+"/"+prefix+md5+suffix
      if File::exist? @path
        @hash = nil
      else
        unless session.new_session
          raise CGI::Session::NoSession, "uninitialized session"
        end
        @hash = {}
      end
    end

### Public Instance Methods

close() click to toggle source

Update and close the session's `FileStore` file.

    # File lib/cgi/session.rb, line 435
    def close
      update
    end

delete() click to toggle source

Close and delete the session's `FileStore` file.

    # File lib/cgi/session.rb, line 440
    def delete
      File::unlink @path+".lock" rescue nil
      File::unlink @path+".new" rescue nil
      File::unlink @path rescue nil
    end

restore() click to toggle source

Restore session state from the session's `FileStore` file.

Returns the session state as a hash.

    # File lib/cgi/session.rb, line 396
    def restore
      unless @hash
        @hash = {}
        begin
          lockf = File.open(@path+".lock", "r")
          lockf.flock File::LOCK_SH
          f = File.open(@path, 'r')
          for line in f
            line.chomp!
            k, v = line.split('=',2)
            @hash[CGI::unescape(k)] = Marshal.restore(CGI::unescape(v))
          end
        ensure
          f&.close
          lockf&.close
        end
      end
      @hash
    end

update() click to toggle source

Save session state to the session's `FileStore` file.

    # File lib/cgi/session.rb, line 417
    def update
      return unless @hash
      begin
        lockf = File.open(@path+".lock", File::CREAT|File::RDWR, 0600)
        lockf.flock File::LOCK_EX
        f = File.open(@path+".new", File::CREAT|File::TRUNC|File::WRONLY, 0600)
        for k,v in @hash
          f.printf "%s=%s\n", CGI::escape(k), CGI::escape(String(Marshal.dump(v)))
        end
        f.close
        File.rename @path+".new", @path
      ensure
        f&.close
        lockf&.close
      end
    end