basis/furnace/sessions/sessions-docs.factor

   1 USING: calendar furnace.db help.markup help.syntax kernel
   2 words.symbol ;
   3 IN: furnace.sessions
   4
   5 HELP: <sessions>
   6 { $values
   7      { "responder" "a responder" }
   8      { "responder'" "a new responder" }
   9 }
  10 { $description "Wraps a responder in a session manager responder." } ;
  11
  12 HELP: schange
  13 { $values { "key" symbol } { "quot" { $quotation ( old -- new ) } } }
  14 { $description "Applies the quotation to the old value of the session variable, and assigns the resulting value back to the variable." } ;
  15
  16 HELP: sget
  17 { $values { "key" symbol } { "value" object } }
  18 { $description "Outputs the value of a session variable." } ;
  19
  20 HELP: sset
  21 { $values { "value" object } { "key" symbol } }
  22 { $description "Sets the value of a session variable." } ;
  23
  24 ARTICLE: "furnace.sessions.config" "Session manager configuration"
  25 "The " { $link sessions } " tuple has two slots which contain configuration parameters:"
  26 { $slots
  27     { "verify?" { "If set to a true value, the client IP address and user agent of each session is tracked, and checked every time a client attempts to re-establish a session. While this does not offer any real security, it can thwart unskilled packet-sniffing attacks. On by default." } }
  28     { "timeout" { "A " { $link duration } " storing the maximum time that inactive sessions will be stored on the server. The default timeout is 20 minutes. Note that for sessions to actually expire, you must start a thread to do so; see the " { $vocab-link "furnace.alloy" } " vocabulary for an easy way of doing this." } }
  29 } ;
  30
  31 ARTICLE: "furnace.sessions.serialize" "Session state serialization"
  32 "Session variable values are serialized to the database using the " { $link "serialize" } " library."
  33 $nl
  34 "This means that there are three restrictions on the values stored in the session:"
  35 { $list
  36     "Continuations cannot be stored at all."
  37     { "Object identity is not preserved between serialization and deserialization. That is, if an object is stored with " { $link sset } " and later retrieved with " { $link sget } ", the retrieved value will be " { $link = } " to the original, but not necessarily " { $link eq? } "." }
  38     { "All objects reachable from the value passed to " { $link sset } " are serialized, so large structures should not be stored in the session state, and neither should anything that can reference the global namespace. Large structures should be persisted in the database directly instead, using " { $vocab-link "db.tuples" } "." }
  39 } ;
  40
  41 ARTICLE: "furnace.sessions" "Furnace sessions"
  42 "The " { $vocab-link "furnace.sessions" } " vocabulary implements session management, which allows state to be maintained between HTTP requests. The session state is stored on the server; the client receives an opaque ID which is saved in a cookie (for GET requests) or a hidden form field (for POST requests)."
  43 $nl
  44 "To use session management, wrap your responder in an session manager:"
  45 { $subsections <sessions> }
  46 "The sessions responder must be wrapped inside a database persistence responder (" { $link <db-persistence> } "). The " { $vocab-link "furnace.alloy" } " vocabulary combines all of these responders into one."
  47 $nl
  48 "Reading and writing session variables from a request:"
  49 { $subsections
  50     sget
  51     sset
  52     schange
  53 }
  54 "Additional topics:"
  55 { $subsections
  56     "furnace.sessions.config"
  57     "furnace.sessions.serialize"
  58 } ;
  59
  60 ABOUT: "furnace.sessions"