basis/http/server/server-docs.factor

   1 USING: assocs continuations help.markup help.syntax http http.server.requests
   2 io.servers kernel math strings urls vocabs.refresh ;
   3 USE: html.forms ! needed for $link in param
   4 IN: http.server
   5
   6 HELP: trivial-responder
   7 { $class-description "The class of trivial responders, which output the same response for every request. New instances are created by calling " { $link <trivial-responder> } "." } ;
   8
   9 HELP: <trivial-responder>
  10 { $values { "response" response } { "trivial-responder" trivial-responder } }
  11 { $description "Creates a new trivial responder which outputs the same response for every request." } ;
  12
  13 HELP: benchmark?
  14 { $var-description "If set to a true value, the HTTP server will log the time taken to process each request." } ;
  15
  16 HELP: call-responder
  17 { $values
  18      { "path" "a sequence of strings" } { "responder" "a responder" }
  19      { "response" response } }
  20 { $description "Calls a responder." } ;
  21
  22 HELP: call-responder*
  23 { $values
  24      { "path" "a sequence of strings" } { "responder" "a responder" }
  25      { "response" response } }
  26 { $contract "Processes an HTTP request and returns a response." }
  27 { $notes "When this word is called, various dynamic variables are set; see " { $link "http.server.requests" } "." } ;
  28
  29 HELP: development?
  30 { $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." } ;
  31
  32 HELP: main-responder
  33 { $var-description "The responder which will handle HTTP requests." } ;
  34
  35 HELP: post-request?
  36 { $values { "?" boolean } }
  37 { $description "Outputs if the current request is a POST request.s" } ;
  38
  39 HELP: responder-nesting
  40 { $description "A sequence of " { $snippet "{ path responder }" } " pairs." } ;
  41
  42 HELP: handle-client-error
  43 { $values { "error" error } }
  44 { $description "Handles an error that may have occurred during the processing of a request. The rules are: 1) if the error is caused by an empty request line, it is silenced because it is a redundant dummy request issued by certain browsers. 2) if the error is a " { $link request-error } " then it is logged and the client is served a 400 Bad Request. 3) all other errors are thrown upwards." } ;
  45
  46 HELP: http-server
  47 { $class-description "The class of HTTP servers. New instances are created by calling " { $link <http-server> } "." } ;
  48
  49 HELP: <http-server>
  50 { $values { "server" http-server } }
  51 { $description "Creates a new HTTP server with default parameters." } ;
  52
  53 HELP: httpd
  54 { $values { "port" integer } { "http-server" http-server } }
  55 { $description "Starts an HTTP server on the specified port number." }
  56 { $notes "For more flexibility, use " { $link <http-server> } " and fill in the tuple slots before calling " { $link start-server } "." } ;
  57
  58 HELP: http-insomniac
  59 { $description "Starts a thread which rotates the logs and e-mails a summary of HTTP requests every 24 hours. See " { $link "logging.insomniac" } "." } ;
  60
  61 HELP: request-params
  62 { $values { "request" request } { "assoc" assoc } }
  63 { $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)." } ;
  64
  65 HELP: param
  66 { $values
  67      { "name" string }
  68      { "value" string }
  69 }
  70 { $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)." }
  71 { $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." } ;
  72
  73 HELP: params
  74 { $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)." }
  75 { $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." } ;
  76
  77 ARTICLE: "http.server.requests" "HTTP request variables"
  78 "The following variables are set by the HTTP server at the beginning of a request. Responder implementations may access these variables."
  79 { $subsections
  80     request
  81     url
  82     responder-nesting
  83     params
  84 }
  85 "Utility words:"
  86 { $subsections
  87     post-request?
  88     param
  89     set-param
  90     request-params
  91 }
  92 "Additional variables may be set by vocabularies such as " { $vocab-link "html.forms" } " and " { $vocab-link "furnace.sessions" } "." ;
  93
  94 ARTICLE: "http.server.responders" "HTTP server responders"
  95 "Responders process requests and output " { $link "http.responses" } ". To implement a responder, define a new class and implement a method on the following generic word:"
  96 { $subsections call-responder* }
  97 "The HTTP server dispatches requests to a main responder:"
  98 { $subsections main-responder }
  99 "The main responder may in turn dispatch it a subordinate dispatcher, and so on. To call a subordinate responder, use the following word:"
 100 { $subsections call-responder }
 101 "A simple implementation of a responder which always outputs the same response:"
 102 { $subsections
 103     trivial-responder
 104     <trivial-responder>
 105 }
 106 "Writing new responders by hand is rarely necessary, because in most cases it is easier to use " { $vocab-link "furnace.actions" } " instead."
 107 { $vocab-subsection "Furnace actions" "furnace.actions" } ;
 108
 109 ARTICLE: "http.server.variables" "HTTP server variables"
 110 "The following global variables control the behavior of the HTTP server. Both are off by default."
 111 { $subsections
 112     development?
 113     benchmark?
 114 } ;
 115
 116 ARTICLE: "http.server" "HTTP server"
 117 "The " { $vocab-link "http.server" } " vocabulary implements an HTTP and HTTPS server on top of " { $vocab-link "io.servers" } "."
 118 { $subsections
 119     "http.server.responders"
 120     "http.server.requests"
 121 }
 122 "Various types of responders are defined in other vocabularies:"
 123 { $subsections
 124     "http.server.dispatchers"
 125     "http.server.filters"
 126 }
 127 "Useful canned responses:"
 128 { $subsections
 129     "http.server.responses"
 130     "http.server.redirection"
 131 }
 132 "Configuration:"
 133 { $subsections
 134     "http.server.variables"
 135     "http.server.remapping"
 136 }
 137 "Features:"
 138 { $subsections
 139     "http.server.static"
 140     "http.server.cgi"
 141 }
 142 "The " { $vocab-link "furnace" } " framework implements high-level abstractions which make developing web applications much easier than writing responders by hand." ;
 143
 144 ABOUT: "http.server"