basis/http/http-docs.factor

   1 USING: calendar help.markup help.syntax kernel math present
   2 strings urls ;
   3 IN: http
   4
   5 HELP: <request>
   6 { $values { "request" request } }
   7 { $description "Creates an empty request containing default headers." } ;
   8
   9 HELP: request
  10 { $description "An HTTP request."
  11 $nl
  12 "Instances contain the following slots:"
  13 { $slots
  14     { "method" { "The HTTP method as a " { $link string } ". The most frequently-used HTTP methods are " { $snippet "GET" } ", " { $snippet "HEAD" } " and " { $snippet "POST" } "." } }
  15     { "url" { "The " { $link url } " being requested" } }
  16     { "proxy-url" { "The proxy " { $link url } " to use, or " { $link f } " for no proxy. If not " { $link f } ", the url will additionally be " { $link derive-url } "'d from the " { $link "http.proxy-variables" } ". The proxy is used if the result has at least the " { $slot "host" } " slot set." } }
  17     { "version" { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
  18     { "header" { "An assoc of HTTP header values. See " { $link "http.headers" } } }
  19     { "post-data" { "See " { $link "http.post-data" } } }
  20     { "cookies" { "A sequence of HTTP cookies. See " { $link "http.cookies" } } }
  21     { "redirects" { "Number of redirects to attempt before throwing an error. Default is " { $snippet "max-redirects" } "." } }
  22 } } ;
  23
  24 HELP: <response>
  25 { $values { "response" response } }
  26 { $description "Creates an empty response containing default headers." } ;
  27
  28 HELP: response
  29 { $class-description "An HTTP response."
  30 $nl
  31 "Instances contain the following slots:"
  32 { $slots
  33     { "version" { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
  34     { "code" { "HTTP status code, an " { $link integer } ". Examples are 200 for success, 404 for file not found, and so on." } }
  35     { "message" { "HTTP status message, only displayed to the user. If the status code is 200, the status message might be “Success”, for example." } }
  36     { "header" { "An assoc of HTTP header values. See " { $link "http.headers" } } }
  37     { "cookies" { "A sequence of HTTP cookies. See " { $link "http.cookies" } } }
  38     { "content-type" { "an HTTP content type" } }
  39     { "content-charset" { "an encoding name" } }
  40     { "content-encoding" { "an encoding descriptor. See " { $link "io.encodings" } } }
  41     { "body" { "an HTTP response body" } }
  42 } } ;
  43
  44 HELP: <raw-response>
  45 { $values { "response" raw-response } }
  46 { $description "Creates an empty raw response." } ;
  47
  48 HELP: raw-response
  49 { $class-description "A minimal HTTP response used by webapps which need full control over all output sent to the client. Most webapps can use " { $link response } " instead."
  50 $nl
  51 "Instances contain the following slots:"
  52 { $slots
  53     { "version" { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
  54     { "code" { "HTTP status code, an " { $link integer } ". Examples are 200 for success, 404 for file not found, and so on." } }
  55     { "message" { "HTTP status message, only displayed to the user. If the status code is 200, the status message might be “Success”, for example." } }
  56     { "body" { "an HTTP response body" } }
  57 } } ;
  58
  59 HELP: <cookie>
  60 { $values { "value" object } { "name" string } { "cookie" cookie } }
  61 { $description "Creates a cookie with the specified name and value. The value can be any object supported by the " { $link present } " word." } ;
  62
  63 HELP: cookie
  64 { $class-description
  65 "An HTTP cookie."
  66 $nl
  67 "Instances contain a number of slots which correspond exactly to the fields of a cookie in the cookie specification:"
  68 { $slots
  69     { "name" { "The cookie name, a " { $link string } } }
  70     { "value" { "The cookie value, an object supported by " { $link present } } }
  71     { "comment" { "A " { $link string } } }
  72     { "path" { "The pathname prefix where the cookie is valid, a " { $link string } } }
  73     { "domain" { "The domain name where the cookie is valid, a " { $link string } } }
  74     { "expires" { "The expiry time, a " { $link timestamp } " or " { $link f } " for a session cookie" } }
  75     { "max-age" { "The expiry duration, a " { $link duration } " or " { $link f } " for a session cookie" } }
  76     { "http-only" { "If set to a true value, JavaScript code cannot see the cookie" } }
  77     { "secure" { "If set to a true value, the cookie is only sent for " { $snippet "https" } " protocol connections" } }
  78 }
  79 "Only one of " { $snippet "expires" } " and " { $snippet "max-age" } " can be set; the latter is preferred and is supported by all modern browsers." } ;
  80
  81 HELP: delete-cookie
  82 { $values { "request/response" "a " { $link request } " or a " { $link response } } { "name" string } }
  83 { $description "Deletes a cookie from a request or response." }
  84 { $side-effects "request/response" } ;
  85
  86 HELP: get-cookie
  87 { $values { "request/response" "a " { $link request } " or a " { $link response } } { "name" string } { "cookie/f" { $maybe cookie } } }
  88 { $description "Gets a named cookie from a request or response." } ;
  89
  90 HELP: put-cookie
  91 { $values { "request/response" "a " { $link request } " or a " { $link response } } { "cookie" cookie } }
  92 { $description "Stores a cookie in a request or response." }
  93 { $side-effects "request/response" } ;
  94
  95 HELP: <post-data>
  96 { $values { "content-type" "a MIME type string" } { "post-data" post-data } }
  97 { $description "Creates a new " { $link post-data } "." } ;
  98
  99 HELP: header
 100 { $values { "request/response" "a " { $link request } " or a " { $link response } } { "key" string } { "value" string } }
 101 { $description "Obtains an HTTP header value from a request or response." } ;
 102
 103 HELP: post-data
 104 { $class-description "HTTP POST data passed in a POST request."
 105 $nl
 106 "Instances contain the following slots:"
 107 { $slots
 108     { "data" { "The POST data. This can be in a higher-level form, such as an assoc of POST parameters, a string, or an XML document" } }
 109     { "params" { "Parameters passed in the POST request." } }
 110     { "content-type" { "A MIME type" } }
 111     { "content-encoding" { "Encoding used for the POST data" } }
 112 } } ;
 113
 114 HELP: set-header
 115 { $values { "request/response" "a " { $link request } " or a " { $link response } } { "value" object } { "key" string } }
 116 { $description "Stores a value into the HTTP header of a request or response. The value can be any object supported by " { $link present } "." }
 117 { $notes "This word always returns the same object that was input. This allows for a “pipeline” coding style, where several header parameters are set in a row." }
 118 { $side-effects "request/response" } ;
 119
 120 HELP: set-basic-auth
 121 { $values { "request" request } { "username" string } { "password" string } }
 122 { $description "Sets the " { $snippet "Authorization" } " header of " { $snippet "request" } " to perform HTTP Basic authentication with the given " { $snippet "username" } " and " { $snippet "password" } "." }
 123 { $notes "This word always returns the same object that was input. This allows for a “pipeline” coding style, where several header parameters are set in a row." }
 124 { $side-effects "request" } ;
 125
 126 HELP: set-proxy-basic-auth
 127 { $values { "request" request } { "username" string } { "password" string } }
 128 { $description "Sets the " { $snippet "Proxy-Authorization" } " header of " { $snippet "request" } " to perform HTTP Basic authentication with the given " { $snippet "username" } " and " { $snippet "password" } "." }
 129 { $notes "This word always returns the same object that was input. This allows for a “pipeline” coding style, where several header parameters are set in a row." }
 130 { $side-effects "request" } ;
 131
 132 ARTICLE: "http.cookies" "HTTP cookies"
 133 "Every " { $link request } " and " { $link response } " instance can contain cookies."
 134 $nl
 135 "The " { $vocab-link "furnace.sessions" } " vocabulary implements session management using cookies, thus the most common use case can be taken care of without working with cookies directly."
 136 $nl
 137 "The class of cookies:"
 138 { $subsections cookie }
 139 "Creating cookies:"
 140 { $subsections <cookie> }
 141 "Getting, adding, and deleting cookies in " { $link request } " and " { $link response } " objects:"
 142 { $subsections
 143     get-cookie
 144     put-cookie
 145     delete-cookie
 146 } ;
 147
 148 ARTICLE: "http.headers" "HTTP headers"
 149 "Every " { $link request } " and " { $link response } " has a set of HTTP headers stored in the " { $slot "header" } " slot. Header names are normalized to lower-case when a request or response is being parsed."
 150 { $subsections
 151     header
 152     set-header
 153 } ;
 154
 155 ARTICLE: "http.post-data" "HTTP post data"
 156 "Every " { $link request } " where the " { $slot "method" } " slot is " { $snippet "POST" } " can contain post data."
 157 { $subsections
 158     post-data
 159     <post-data>
 160 } ;
 161
 162 ARTICLE: "http.requests" "HTTP requests"
 163 "HTTP requests:"
 164 { $subsections
 165     request
 166     <request>
 167 }
 168 "Requests can contain form submissions:"
 169 { $subsections "http.post-data" } ;
 170
 171 ARTICLE: "http.responses" "HTTP responses"
 172 "HTTP responses:"
 173 { $subsections
 174     response
 175     <response>
 176 }
 177 "Raw responses only contain a status line, with no header. They are used by webapps which need full control over the HTTP response, for example " { $vocab-link "http.server.cgi" } ":"
 178 { $subsections
 179     raw-response
 180     <raw-response>
 181 } ;
 182
 183 ARTICLE: "http" "HTTP protocol objects"
 184 "The " { $vocab-link "http" } " vocabulary contains data types shared by " { $vocab-link "http.client" } " and " { $vocab-link "http.server" } "."
 185 $nl
 186 "The HTTP client sends an HTTP request to the server and receives an HTTP response back. The HTTP server receives HTTP requests from clients and sends HTTP responses back."
 187 { $subsections
 188     "http.requests"
 189     "http.responses"
 190 }
 191 "Both requests and responses support some common functionality:"
 192 { $subsections
 193     "http.headers"
 194     "http.cookies"
 195 }
 196 { $see-also "urls" } ;
 197
 198 ARTICLE: "http.proxy-variables" "HTTP(S) proxy variables"
 199 { $heading "Proxy Variables" }
 200 "The http and https proxies can be configured per request, or with Factor's dynamic variables, or with the system's environment variables (searched from left to right) :"
 201 { $table
 202 { "variable" "Factor dynamic" "environment #1" "environment #2" }
 203 { "HTTP" { $snippet "\"http.proxy\"" } "http_proxy" "HTTP_PROXY" }
 204 { "HTTPS" { $snippet "\"https.proxy\"" } "https_proxy" "HTTPS_PROXY" }
 205 { "no proxy" { $snippet "\"no_proxy\"" } "no_proxy" "NO_PROXY" }
 206 }
 207 "When making an http request, if the target host is not matched by the no_proxy list, the " { $vocab-link "http.client" } " will fill the missing components of the " { $slot "proxy-url" } " slot of the " { $link request } " from the value of these variables. If the filled result is not valid, an error is thrown."
 208 { $notes "The dynamic variables are keyed by strings. This allows to use Factor's command line support to define them (see in the examples below)." }
 209
 210 { $heading "no_proxy" }
 211 "The no_proxy list must be a string containing of comma-separated list of IP addresses (eg " { $snippet "127.0.0.1" } "), hostnames (eg " { $snippet "bar.private" } ") or domain suffixes (eg " { $snippet ".private" } "). A match happens when a value of the list is the same or a suffix of the target for each full subdomain."
 212 { $example
 213     "USING: http.client http.client.private namespaces prettyprint ;"
 214     "\"bar.private\" \"no_proxy\" ["
 215          "\"bar.private\" <get-request> no-proxy? ."
 216     "] with-variable"
 217     "\"bar.private\" \"no_proxy\" ["
 218          "\"baz.bar.private\" <get-request> no-proxy? ."
 219     "] with-variable"
 220     "\"bar.private\" \"no_proxy\" ["
 221          "\"foobar.private\" <get-request> no-proxy? ."
 222     "] with-variable"
 223     "\".private\" \"no_proxy\" ["
 224          "\"foobar.private\" <get-request> no-proxy? ."
 225     "] with-variable"
 226 "t
 227 t
 228 f
 229 t"
 230 }
 231
 232 { $examples
 233 {
 234 { $subheading "At factor startup:" }
 235 { $list
 236 "$ ./factor -http.proxy=http://localhost:3128"
 237 "$ http_proxy=\"http://localhost:3128\" ./factor"
 238 "$ HTTP_PROXY=\"http://localhost:3128\" ./factor"
 239 }
 240
 241 { $subheading "Using variables:" }
 242 { $example "USE: namespaces \"http://localhost:3128\" \"http.proxy\" set ! or set-global" "" }
 243 { $example "USE: namespaces \"http://localhost:3128\" \"http.proxy\" [ ] with-variable" "" }
 244
 245 { $subheading "Manually making the request:" }
 246 { $example "USING: http http.client urls ; URL\" http://localhost:3128\" <request> proxy-url<<" "" }
 247
 248 { $subheading "Full example:" }
 249 "$ no_proxy=\"localhost,127.0.0.1,.private\" http_proxy=\"http://proxy.private:3128\" https_proxy=\"http://proxysec.private:3128\" ./factor"
 250 }
 251 }
 252 ;
 253
 254 ABOUT: "http"