Document furnace
Slava Pestov
parent
e9a42b9bde
commit
b917e1f051
basis/furnace
|
|
@ -1,136 +1,129 @@
|
|||
USING: assocs help.markup help.syntax kernel
|
||||
quotations sequences strings urls ;
|
||||
quotations sequences strings urls xml.data http ;
|
||||
IN: furnace
|
||||
|
||||
HELP: adjust-redirect-url
|
||||
{ $values { "url" url } { "url'" url } }
|
||||
{ $description "" } ;
|
||||
{ $description "Adjusts a redirection URL by filtering the URL's query parameters through the " { $link modify-redirect-query } " generic word on every responder involved in handling the current request." } ;
|
||||
|
||||
HELP: adjust-url
|
||||
{ $values { "url" url } { "url'" url } }
|
||||
{ $description "" } ;
|
||||
|
||||
HELP: base-path
|
||||
{ $values { "string" string } { "pair" "a pair with shape " { $snippet "{ path responder }" } } }
|
||||
{ $description "" } ;
|
||||
{ $description "Adjusts a link URL by filtering the URL's query parameters through the " { $link modify-query } " generic word on every responder involved in handling the current request." } ;
|
||||
|
||||
HELP: client-state
|
||||
{ $values { "key" string } { "value/f" { $maybe string } } }
|
||||
{ $description "" } ;
|
||||
{ $description "Looks up a cookie (if the current request is a GET or HEAD request) or a POST parameter (if the current request is a POST request)." }
|
||||
{ $notes "This word is used by session management, conversation scope and asides." } ;
|
||||
|
||||
HELP: each-responder
|
||||
{ $values { "quot" "a " { $link quotation } " with stack effect " { $snippet "( responder -- )" } } }
|
||||
{ $description "" } ;
|
||||
|
||||
HELP: exit-with
|
||||
{ $values
|
||||
{ "value" null }
|
||||
}
|
||||
{ $description "" } ;
|
||||
{ $values { "quot" { $quotation "( responder -- )" } } }
|
||||
{ $description "Applies the quotation to each responder involved in processing the current request." } ;
|
||||
|
||||
HELP: hidden-form-field
|
||||
{ $values
|
||||
{ "value" null } { "name" null }
|
||||
}
|
||||
{ $description "" } ;
|
||||
{ $values { "value" string } { "name" string } }
|
||||
{ $description "Renders an HTML hidden form field tag." }
|
||||
{ $notes "This word is used by session management, conversation scope and asides." }
|
||||
{ $examples
|
||||
{ $example
|
||||
"USING: furnace io ;"
|
||||
"\"bar\" \"foo\" hidden-form-field nl"
|
||||
"<input type='hidden' name='foo' value='bar'/>"
|
||||
}
|
||||
} ;
|
||||
|
||||
HELP: link-attr
|
||||
{ $values
|
||||
{ "tag" null } { "responder" null }
|
||||
}
|
||||
{ $description "" } ;
|
||||
{ $values { "tag" tag } { "responder" "a responder" } }
|
||||
{ $contract "Modifies an XHTML " { $snippet "a" } " tag." }
|
||||
{ $notes "This word is called by " { $link "html.templates.chloe.tags.form" } "." }
|
||||
{ $examples "Conversation scope adds attributes to link tags." } ;
|
||||
|
||||
HELP: modify-form
|
||||
{ $values
|
||||
{ "responder" null }
|
||||
}
|
||||
{ $description "" } ;
|
||||
{ $values { "responder" "a responder" } }
|
||||
{ $contract "Emits hidden form fields using " { $link hidden-form-field } "." }
|
||||
{ $notes "This word is called by " { $link "html.templates.chloe.tags.form" } "." }
|
||||
{ $examples "Session management, conversation scope and asides use hidden form fields to pass state." } ;
|
||||
|
||||
HELP: modify-query
|
||||
{ $values
|
||||
{ "query" null } { "responder" null }
|
||||
{ "query'" null }
|
||||
}
|
||||
{ $description "" } ;
|
||||
{ $values { "query" assoc } { "responder" "a responder" } { "query'" assoc } }
|
||||
{ $contract "Modifies the query parameters of a URL destined to be displayed as a link." }
|
||||
{ $notes "This word is called by " { $link "html.templates.chloe.tags.form" } "." }
|
||||
{ $examples "Asides add query parameters to URLs." } ;
|
||||
|
||||
HELP: modify-redirect-query
|
||||
{ $values
|
||||
{ "query" null } { "responder" null }
|
||||
{ "query'" null }
|
||||
}
|
||||
{ $description "" } ;
|
||||
|
||||
HELP: nested-forms-key
|
||||
{ $description "" } ;
|
||||
{ $values { "query" assoc } { "responder" "a responder" } { "query'" assoc } }
|
||||
{ $contract "Modifies the query parameters of a URL destined to be used with a redirect." }
|
||||
{ $notes "This word is called by " { $link "furnace.redirection" } "." }
|
||||
{ $examples "Conversation scope and asides add query parameters to redirect URLs." } ;
|
||||
|
||||
HELP: nested-responders
|
||||
{ $values
|
||||
|
||||
{ "seq" sequence }
|
||||
}
|
||||
{ $description "" } ;
|
||||
|
||||
HELP: post-client-state
|
||||
{ $values
|
||||
{ "key" null } { "request" null }
|
||||
{ "value/f" null }
|
||||
}
|
||||
{ $values { "seq" "a sequence of responders" } }
|
||||
{ $description "" } ;
|
||||
|
||||
HELP: referrer
|
||||
{ $values
|
||||
|
||||
{ "referrer/f" null }
|
||||
}
|
||||
{ $description "" } ;
|
||||
{ $values { "referrer/f" { $maybe string } } }
|
||||
{ $description "Outputs the current request's referrer URL." } ;
|
||||
|
||||
HELP: request-params
|
||||
{ $values
|
||||
{ "request" null }
|
||||
{ "assoc" assoc }
|
||||
}
|
||||
{ $description "" } ;
|
||||
{ $values { "request" request } { "assoc" assoc } }
|
||||
{ $description "Outputs the query parameters (if the current request is a GET or HEAD request) or the POST parameters (if the current request is a POST request)." } ;
|
||||
|
||||
HELP: resolve-base-path
|
||||
{ $values
|
||||
{ "string" string }
|
||||
{ "string'" string }
|
||||
}
|
||||
{ $values { "string" string } { "string'" string } }
|
||||
{ $description "" } ;
|
||||
|
||||
HELP: resolve-template-path
|
||||
{ $values
|
||||
{ "pair" null }
|
||||
{ "path" "a pathname string" }
|
||||
}
|
||||
{ $values { "pair" "a pair with shape " { $snippet "{ class string }" } } { "path" "a pathname string" } }
|
||||
{ $description "" } ;
|
||||
|
||||
HELP: same-host?
|
||||
{ $values
|
||||
{ "url" url }
|
||||
{ "?" "a boolean" }
|
||||
}
|
||||
{ $description "" } ;
|
||||
{ $values { "url" url } { "?" "a boolean" } }
|
||||
{ $description "Tests if the given URL is located on the same host as the URL of the current request." } ;
|
||||
|
||||
HELP: user-agent
|
||||
{ $values
|
||||
|
||||
{ "user-agent" null }
|
||||
}
|
||||
{ $description "" } ;
|
||||
{ $values { "user-agent" { $maybe string } } }
|
||||
{ $description "Outputs the user agent reported by the client for the current request." } ;
|
||||
|
||||
HELP: vocab-path
|
||||
{ $values
|
||||
{ "vocab" "a vocabulary specifier" }
|
||||
{ "path" "a pathname string" }
|
||||
}
|
||||
{ $values { "vocab" "a vocabulary specifier" } { "path" "a pathname string" } }
|
||||
{ $description "" } ;
|
||||
|
||||
HELP: exit-with
|
||||
{ $values { "value" object } }
|
||||
{ $description "Exits from an outer " { $link with-exit-continuation } "." } ;
|
||||
|
||||
HELP: with-exit-continuation
|
||||
{ $values
|
||||
{ "quot" quotation }
|
||||
}
|
||||
{ $description "" } ;
|
||||
{ $values { "quot" { $quotation { "( -- value )" } } } { "value" "a value returned by the quotation or an " { $link exit-with } " invocation" } }
|
||||
{ $description "Runs a quotation with the " { $link exit-continuation } " variable bound. Calling " { $link exit-with } " in the quotation will immediately return." }
|
||||
{ $notes "Furnace actions and authentication realms wrap their execution in this combinator, allowing form validation failures and login requests, respectively, to immediately return an HTTP response to the client without running any more responder code." } ;
|
||||
|
||||
ARTICLE: "furnace.extension-points" "Furnace extension points"
|
||||
"Furnace features such as session management, conversation scope and asides need to modify URLs in links and redirects, and insert hidden form fields, to implement state on top of the setateless HTTP protocol. In order to decouple the server-side state management code from the HTML templating code, a series of hooks are used."
|
||||
$nl
|
||||
"Responders can implement methods on the following generic words:"
|
||||
{ $subsection modify-query }
|
||||
{ $subsection modify-redirect-query }
|
||||
{ $subsection link-attr }
|
||||
{ $subsection modify-form }
|
||||
"Presentation-level code can call the following words:"
|
||||
{ $subsection adjust-url }
|
||||
{ $subsection adjust-redirect-url } ;
|
||||
|
||||
ARTICLE: "furnace.misc" "Miscellaneous Furnace features"
|
||||
"Inspecting the chain of responders handling the current request:"
|
||||
{ $subsection nested-responders }
|
||||
{ $subsection each-responder }
|
||||
{ $subsection resolve-base-path }
|
||||
"Vocabulary root-relative resources:"
|
||||
{ $subsection vocab-path }
|
||||
{ $subsection resolve-template-path }
|
||||
"Early return from a responder:"
|
||||
{ $subsection with-exit-continuation }
|
||||
{ $subsection exit-with }
|
||||
"Other useful words:"
|
||||
{ $subsection hidden-form-field }
|
||||
{ $subsection request-params }
|
||||
{ $subsection client-state }
|
||||
{ $subsection user-agent } ;
|
||||
|
||||
ARTICLE: "furnace.persistence" "Furnace persistence layer"
|
||||
{ $subsection "furnace.db" }
|
||||
|
|
@ -175,6 +168,8 @@ ARTICLE: "furnace" "Furnace framework"
|
|||
"Utilities:"
|
||||
{ $subsection "furnace.referrer" }
|
||||
{ $subsection "furnace.redirection" }
|
||||
{ $subsection "furnace.extension-points" }
|
||||
{ $subsection "furnace.misc" }
|
||||
"Related frameworks:"
|
||||
{ $subsection "db" }
|
||||
{ $subsection "xml" }
|
||||
|
|
|
|||
|
|
@ -125,7 +125,7 @@ SYMBOL: exit-continuation
|
|||
: exit-with ( value -- )
|
||||
exit-continuation get continue-with ;
|
||||
|
||||
: with-exit-continuation ( quot -- )
|
||||
: with-exit-continuation ( quot -- value )
|
||||
'[ exit-continuation set @ ] callcc1 exit-continuation off ;
|
||||
|
||||
USE: vocabs.loader
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
USING: help.markup help.syntax io.streams.string ;
|
||||
USING: help.markup help.syntax io.streams.string
|
||||
furnace ;
|
||||
IN: furnace.referrer
|
||||
|
||||
HELP: <check-form-submissions>
|
||||
|
|
@ -10,6 +11,9 @@ HELP: <check-form-submissions>
|
|||
|
||||
ARTICLE: "furnace.referrer" "Form submission referrer checking"
|
||||
"The " { $vocab-link "furnace.referrer" } " implements a simple security measure which can be used to thwart cross-site scripting attacks."
|
||||
{ $subsection <check-form-submissions> } ;
|
||||
{ $subsection <check-form-submissions> }
|
||||
"Explicit referrer checking:"
|
||||
{ $subsection referrer }
|
||||
{ $subsection same-host? } ;
|
||||
|
||||
ABOUT: "furnace.referrer"
|
||||
|
|
|
|||
Loading…
Reference in New Issue