basis/http/server/server-docs.factor

   1 USING: help.markup help.syntax io.streams.string quotations strings urls
   2 http vocabs.refresh math io.servers.connection assocs ;
   3 IN: http.server
   4
   5 HELP: trivial-responder
   6 { $description "The class of trivial responders, which output the same response for every request. New instances are created by calling " { $link <trivial-responder> } "." } ;
   7
   8 HELP: <trivial-responder>
   9 { $values { "response" response } { "trivial-responder" trivial-responder } }
  10 { $description "Creates a new trivial responder which outputs the same response for every request." } ;
  11
  12 HELP: benchmark?
  13 { $var-description "If set to a true value, the HTTP server will log the time taken to process each request." } ;
  14
  15 HELP: call-responder
  16 { $values
  17      { "path" "a sequence of strings" } { "responder" "a responder" }
  18      { "response" response } }
  19 { $description "Calls a responder." } ;
  20
  21 HELP: call-responder*
  22 { $values
  23      { "path" "a sequence of strings" } { "responder" "a responder" }
  24      { "response" response } }
  25 { $contract "Processes an HTTP request and returns a response." }
  26 { $notes "When this word is called, various dynamic variables are set; see " { $link "http.server.requests" } "." } ;
  27
  28 HELP: development?
  29 { $var-description "If set to a true value, the HTTP server will call " { $link refresh-all } " on each request, and error pages will contain stack traces." } ;
  30
  31 HELP: main-responder
  32 { $var-description "The responder which will handle HTTP requests." } ;
  33
  34 HELP: post-request?
  35 { $values { "?" "a boolean" } }
  36 { $description "Outputs if the current request is a POST request.s" } ;
  37
  38 HELP: responder-nesting
  39 { $description "A sequence of " { $snippet "{ path responder }" } " pairs." } ;
  40
  41 HELP: http-server
  42 { $class-description "The class of HTTP servers. New instances are created by calling " { $link <http-server> } "." } ;
  43
  44 HELP: <http-server>
  45 { $values { "server" http-server } }
  46 { $description "Creates a new HTTP server with default parameters." } ;
  47
  48 HELP: httpd
  49 { $values { "port" integer } }
  50 { $description "Starts an HTTP server on the specified port number." }
  51 { $notes "For more flexibility, use " { $link <http-server> } " and fill in the tuple slots before calling " { $link start-server } "." } ;
  52
  53 HELP: http-insomniac
  54 { $description "Starts a thread which rotates the logs and e-mails a summary of HTTP requests every 24 hours. See " { $link "logging.insomniac" } "." } ;
  55
  56 HELP: request-params
  57 { $values { "request" request } { "assoc" assoc } }
  58 { $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)." } ;
  59
  60 HELP: param
  61 { $values
  62      { "name" string }
  63      { "value" string }
  64 }
  65 { $description "Outputs the value of a query parameter (if the current request is a GET or HEAD request) or a POST parameter (if the current request is a POST request)." }
  66 { $notes "Instead of using this word, it is better to use " { $vocab-link "furnace.actions" } " and the associated validation machinery, which allows you to access values using " { $link "html.forms.values" } " words." } ;
  67
  68 HELP: params
  69 { $var-description "A variable holding an assoc of query parameters (if the current request is a GET or HEAD request) or POST parameters (if the current request is a POST request)." }
  70 { $notes "Instead of using this word, it is better to use " { $vocab-link "furnace.actions" } " and the associated validation machinery, which allows you to access values using " { $link "html.forms.values" } " words." } ;
  71
  72 ARTICLE: "http.server.requests" "HTTP request variables"
  73 "The following variables are set by the HTTP server at the beginning of a request."
  74 { $subsection request }
  75 { $subsection url }
  76 { $subsection post-request? }
  77 { $subsection responder-nesting }
  78 { $subsection params }
  79 "Utility words:"
  80 { $subsection param }
  81 { $subsection set-param }
  82 { $subsection request-params }
  83 "Additional vocabularies may be set by vocabularies such as " { $vocab-link "html.forms" } " and " { $vocab-link "furnace.sessions" } "." ;
  84
  85 ARTICLE: "http.server.responders" "HTTP server responders"
  86 "The HTTP server dispatches requests to a main responder:"
  87 { $subsection main-responder }
  88 "The main responder may in turn dispatch it a subordinate dispatcher, and so on."
  89 $nl
  90 "Responders process requests and output " { $link "http.responses" } "; concretely are instances of classes which implement a generic word:"
  91 { $subsection call-responder* }
  92 "To actually call a subordinate responder, use the following word instead:"
  93 { $subsection call-responder }
  94 "A simple implementation of a responder which always outputs the same response:"
  95 { $subsection trivial-responder }
  96 { $subsection <trivial-responder> }
  97 { $vocab-subsection "Furnace actions" "furnace.actions" }
  98 "In particular, writing new responders by hand is rarely necessary, because in most cases it is easier to use " { $vocab-link "furnace.actions" } " instead." ;
  99
 100 ARTICLE: "http.server.variables" "HTTP server variables"
 101 "The following global variables control the behavior of the HTTP server. Both are off by default."
 102 { $subsection development? }
 103 { $subsection benchmark? } ;
 104
 105 ARTICLE: "http.server" "HTTP server"
 106 "The " { $vocab-link "http.server" } " vocabulary implements an HTTP and HTTPS server on top of " { $vocab-link "io.servers.connection" } "."
 107 { $subsection "http.server.responders" }
 108 { $subsection "http.server.requests" }
 109 "Various types of responders are defined in other vocabularies:"
 110 { $subsection "http.server.dispatchers" }
 111 { $subsection "http.server.filters" }
 112 "Useful canned responses:"
 113 { $subsection "http.server.responses" }
 114 { $subsection "http.server.redirection" }
 115 "Configuration:"
 116 { $subsection "http.server.variables" }
 117 { $subsection "http.server.remapping" }
 118 "Features:"
 119 { $subsection "http.server.static" }
 120 { $subsection "http.server.cgi" }
 121 "The " { $vocab-link "furnace" } " framework implements high-level abstractions which make developing web applications much easier than writing responders by hand." ;
 122
 123 ABOUT: "http.server"