steve
/
factor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Document furnace.sessions

db4
Slava Pestov 2008-11-14 22:51:53 -06:00
parent 5c914ff054
commit b9afd25245
3 changed files with 100 additions and 70 deletions

54
basis/furnace/furnace-docs.factor
View File

@ -155,7 +155,31 @@ HELP: with-exit-continuation
}
{ $description "" } ;
ARTICLE: "furnace" "Furnace web framework"
ARTICLE: "furnace.persistence" "Furnace persistence layer"
{ $subsection "furnace.db" }
"Server-side state:"
{ $subsection "furnace.sessions" }
{ $subsection "furnace.conversations" }
{ $subsection "furnace.asides" }
{ $subsection "furnace.presentation" } ;
ARTICLE: "furnace.presentation" "Furnace presentation layer"
"HTML components:"
{ $subsection "html.components" }
{ $subsection "html.forms" }
"Content templates:"
{ $subsection "html.templates" }
{ $subsection "html.templates.chloe" }
{ $subsection "html.templates.fhtml" }
{ $subsection "furnace.boilerplate" }
"Other types of content:"
{ $subsection "furnace.syndication" }
{ $subsection "furnace.json" } ;
ARTICLE: "furnace.load-balancing" "Load balancing and fail-over with Furnace"
"The Furnace session manager persists sessions to a database. This means that HTTP requests can be transparently distributed between multiple Factor HTTP server instances, running the same web app on top of the same database, as long as the web applications do not use mutable global state, such as global variables. The Furnace framework itself does not use any mutable global state." ;
ARTICLE: "furnace" "Furnace framework"
"The " { $vocab-link "furnace" } " vocabulary implements a full-featured web framework on top of the " { $link "http.server" } ". Some of its features include:"
{ $list
"Session management capable of load-balancing and fail-over"
@ -166,24 +190,18 @@ ARTICLE: "furnace" "Furnace web framework"
}
"Major functionality:"
{ $subsection "furnace.actions" }
"Server-side state:"
{ $subsection "furnace.db" }
{ $subsection "furnace.sessions" }
{ $subsection "furnace.conversations" }
{ $subsection "furnace.asides" }
"HTML components:"
{ $subsection "html.components" }
{ $subsection "html.forms" }
"Content templates:"
{ $subsection "html.templates" }
{ $subsection "html.templates.chloe" }
{ $subsection "html.templates.fhtml" }
{ $subsection "furnace.boilerplate" }
"Utilities:"
{ $subsection "furnace.alloy" }
{ $subsection "furnace.syndication" }
{ $subsection "furnace.json" }
{ $subsection "furnace.persistence" }
{ $subsection "furnace.presentation" }
{ $subsection "furnace.load-balancing" }
"Utilities:"
{ $subsection "furnace.referrer" }
{ $subsection "furnace.redirection" }
{ $subsection "furnace.referrer" } ;
"Related frameworks:"
{ $subsection "db" }
{ $subsection "xml" }
{ $subsection "http.server" }
{ $subsection "logging" }
{ $subsection "urls" } ;
ABOUT: "furnace"

66
basis/furnace/sessions/sessions-docs.factor
View File

@ -1,45 +1,55 @@
USING: help.markup help.syntax io.streams.string quotations strings ;
USING: help.markup help.syntax io.streams.string quotations strings calendar serialize kernel furnace.db words kernel ;
IN: furnace.sessions
HELP: <sessions>
{ $values
{ "responder" null }
{ "responder'" null }
{ "responder" "a responder" }
{ "responder'" "a new responder" }
}
{ $description "" } ;
HELP: init-session*
{ $values
{ "responder" null }
}
{ $description "" } ;
{ $description "Wraps a responder in a session manager responder." } ;
HELP: schange
{ $values
{ "key" null } { "quot" quotation }
}
{ $description "" } ;
{ $values { "key" symbol } { "quot" "a quotation with stack effect " { $snippet "( old -- new )" } } }
{ $description "Applies the quotation to the old value of the session variable, and assigns the resulting value back to the variable." } ;
HELP: sget
{ $values
{ "key" null }
{ "value" null }
}
{ $description "" } ;
{ $values { "key" symbol } { "value" object } }
{ $description "Outputs the value of a session variable." } ;
HELP: sset
{ $values
{ "value" null } { "key" null }
}
{ $description "" } ;
{ $values { "value" object } { "key" symbol } }
{ $description "Sets the value of a session variable." } ;
ARTICLE: "furnace.sessions.config" "Session manager configuration"
"The " { $link sessions } " tuple has two slots which contain configuration parameters:"
{ $table
{ { $slot "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." } }
{ { $slot "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." } }
} ;
ARTICLE: "furnace.sessions.serialize" "Session state serialization"
;
"Session variable values are serialized to the database using the " { $link "serialize" } " library."
$nl
"This means that there are three restrictions on the values stored in the session:"
{ $list
"Continuations cannot be stored at all."
{ "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? } "." }
{ "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" } "." }
} ;
ARTICLE: "furnace.sessions" "Furnace sessions"
{ $vocab-link "furnace.sessions" }
;
"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)."
$nl
"To use session management, wrap your responder in an session manager:"
{ $subsection <sessions> }
"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."
$nl
"Reading and writing session variables from a request:"
{ $subsection sget }
{ $subsection sset }
{ $subsection schange }
"Additional topics:"
{ $subsection "furnace.sessions.config" }
{ $subsection "furnace.sessions.serialize" } ;
ABOUT: "furnace.sessions"

50
basis/furnace/syndication/syndication-docs.factor
View File

@ -1,29 +1,23 @@
USING: help.markup help.syntax io.streams.string kernel sequences strings urls ;
USING: help.markup help.syntax io.streams.string kernel sequences strings urls syndication ;
IN: furnace.syndication
HELP: <feed-action>
{ $values
{ "action" null }
}
{ $description "" } ;
HELP: <feed-content>
{ $values
{ "body" null }
{ "response" null }
}
{ $description "" } ;
{ $values { "action" feed-action } }
{ $description "Creates a new Atom feed action." } ;
HELP: >entry
{ $values
{ "object" object }
{ "entry" null }
{ "entry" entry }
}
{ $description "" } ;
{ $contract "Converts an object into an Atom feed entry. The default implementation constructs an entry by calling "
{ $link feed-entry-title } ", "
{ $link feed-entry-description } ", "
{ $link feed-entry-date } ", and "
{ $link feed-entry-url } "." } ;
HELP: feed-action
{ $description "" } ;
{ $class-description "The class of feed actions. Contains several slots, documented in " { $link "furnace.syndication.config" } "." } ;
HELP: feed-entry-date
{ $values
@ -53,15 +47,23 @@ HELP: feed-entry-url
}
{ $description "" } ;
HELP: process-entries
{ $values
{ "seq" sequence }
{ "seq'" sequence }
}
{ $description "" } ;
ARTICLE: "furnace.syndication.config" "Configuring Atom feed actions"
ARTICLE: "furnace.syndication" "Furnace Atom syndication support"
{ $vocab-link "furnace.syndication" }
;
ARTICLE: "furnace.syndication.protocol" "Atom feed entry protocol"
"An Atom feed action takes a sequence of objects and converts them into Atom feed entries. The objects must implement a protocol consisting of either a single generic word:"
{ $subsection >entry }
"Or a series of generic words, called by the default implementation of " { $link >entry } ":"
{ $subsection feed-entry-title }
{ $subsection feed-entry-description }
{ $subsection feed-entry-date }
{ $subsection feed-entry-url } ;
ARTICLE: "furnace.syndication" "Furnace Atom syndication support"
"The " { $vocab-link "furnace.syndication" } " vocabulary builds on the " { $link "syndication" } " library by providing easy support for generating Atom feeds from " { $link "furnace.actions" } "."
{ $subsection <feed-action> }
{ $subsection "furnace.syndication.config" }
{ $subsection "furnace.syndication.protocol" } ;
ABOUT: "furnace.syndication"