basis/http/http-docs.factor

   1 USING: assocs help.markup help.syntax io.streams.string sequences strings present math kernel byte-arrays urls
   2 calendar ;
   3 IN: http
   4
   5 HELP: <request>
   6 { $values { "request" request } }
   7 { $description "Creates an empty request." } ;
   8
   9 HELP: request
  10 { $description "An HTTP request."
  11 $nl
  12 "Instances contain the following slots:"
  13 { $table
  14     { { $slot "method" } { "The HTTP method as a " { $link string } ". The most frequently-used HTTP methods are " { $snippet "GET" } ", " { $snippet "HEAD" } " and " { $snippet "POST" } "." } }
  15     { { $slot "url" } { "The " { $link url } " being requested" } }
  16     { { $slot "version" } { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
  17     { { $slot "header" } { "An assoc of HTTP header values. See " { $link "http.headers" } } }
  18     { { $slot "post-data" } { "See " { $link "http.post-data" } } }
  19     { { $slot "cookies" } { "A sequence of HTTP cookies. See " { $link "http.cookies" } } }
  20 } } ;
  21
  22 HELP: <response>
  23 { $values { "response" response } }
  24 { $description "Creates an empty response." } ;
  25
  26 HELP: response
  27 { $class-description "An HTTP response."
  28 $nl
  29 "Instances contain the following slots:"
  30 { $table
  31     { { $slot "version" } { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
  32     { { $slot "code" } { "HTTP status code, an " { $link integer } ". Examples are 200 for success, 404 for file not found, and so on." } }
  33     { { $slot "message" } { "HTTP status message, only displayed to the user. If the status code is 200, the status message might be “Success”, for example." } }
  34     { { $slot "header" } { "An assoc of HTTP header values. See " { $link "http.headers" } } }
  35     { { $slot "cookies" } { "A sequence of HTTP cookies. See " { $link "http.cookies" } } }
  36     { { $slot "content-type" } { "an HTTP content type" } }
  37     { { $slot "content-charset" } { "an encoding descriptor. See " { $link "io.encodings" } } }
  38     { { $slot "body" } { "an HTTP response body" } }
  39 } } ;
  40
  41 HELP: <raw-response>
  42 { $values { "response" raw-response } }
  43 { $description "Creates an empty raw response." } ;
  44
  45 HELP: raw-response
  46 { $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."
  47 $nl
  48 "Instances contain the following slots:"
  49 { $table
  50     { { $slot "version" } { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
  51     { { $slot "code" } { "HTTP status code, an " { $link integer } ". Examples are 200 for success, 404 for file not found, and so on." } }
  52     { { $slot "message" } { "HTTP status message, only displayed to the user. If the status code is 200, the status message might be “Success”, for example." } }
  53     { { $slot "body" } { "an HTTP response body" } }
  54 } } ;
  55
  56 HELP: <cookie>
  57 { $values { "value" object } { "name" string } { "cookie" cookie } }
  58 { $description "Creates a cookie with the specified name and value. The value can be any object supported by the " { $link present } " word." } ;
  59
  60 HELP: cookie
  61 { $class-description
  62 "An HTTP cookie."
  63 $nl
  64 "Instances contain a number of slots which correspond exactly to the fields of a cookie in the cookie specification:"
  65 { $table
  66     { { $slot "name" } { "The cookie name, a " { $link string } } }
  67     { { $slot "value" } { "The cookie value, an object supported by " { $link present } } }
  68     { { $slot "comment" } { "A " { $link string } } }
  69     { { $slot "path" } { "The pathname prefix where the cookie is valid, a " { $link string } } }
  70     { { $slot "domain" } { "The domain name where the cookie is valid, a " { $link string } } }
  71     { { $slot "expires" } { "The expiry time, a " { $link timestamp } " or " { $link f } " for a session cookie" } }
  72     { { $slot "max-age" } { "The expiry duration, a " { $link duration } " or " { $link f } " for a session cookie" } }
  73     { { $slot "http-only" } { "If set to a true value, JavaScript code cannot see the cookie" } }
  74     { { $slot "secure" } { "If set to a true value, the cookie is only sent for " { $snippet "https" } " protocol connections" } }
  75 }
  76 "Only one of " { $snippet "expires" } " and " { $snippet "max-age" } " can be set; the latter is preferred and is supported by all modern browsers." } ;
  77
  78 HELP: delete-cookie
  79 { $values { "request/response" "a " { $link request } " or a " { $link response } } { "name" string } }
  80 { $description "Deletes a cookie from a request or response." }
  81 { $side-effects "request/response" } ;
  82
  83 HELP: get-cookie
  84 { $values { "request/response" "a " { $link request } " or a " { $link response } } { "name" string } { "cookie/f" { $maybe cookie } } }
  85 { $description "Gets a named cookie from a request or response." } ;
  86
  87 HELP: put-cookie
  88 { $values { "request/response" "a " { $link request } " or a " { $link response } } { "cookie" cookie } }
  89 { $description "Stores a cookie in a request or response." }
  90 { $side-effects "request/response" } ;
  91
  92 HELP: <post-data>
  93 { $values { "content-type" "a MIME type string" } { "post-data" post-data } }
  94 { $description "Creates a new " { $link post-data } "." } ;
  95
  96 HELP: header
  97 { $values { "request/response" "a " { $link request } " or a " { $link response } } { "key" string } { "value" string } }
  98 { $description "Obtains an HTTP header value from a request or response." } ;
  99
 100 HELP: post-data
 101 { $class-description "HTTP POST data passed in a POST request."
 102 $nl
 103 "Instances contain the following slots:"
 104 { $table
 105     { { $slot "raw" } { "The raw bytes of the POST data" } }
 106     { { $slot "content" } { "The POST data. This can be in a higher-level form, such as an assoc of POST parameters, a string, or an XML document" } }
 107     { { $slot "content-type" } "A MIME type" }
 108 } } ;
 109
 110 HELP: set-header
 111 { $values { "request/response" "a " { $link request } " or a " { $link response } } { "value" object } { "key" string } }
 112 { $description "Stores a value into the HTTP header of a request or response. The value can be any object supported by " { $link present } "." }
 113 { $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." }
 114 { $side-effects "request/response" } ;
 115
 116 HELP: set-basic-auth
 117 { $values { "request" request } { "username" string } { "password" string } }
 118 { $description "Sets the " { $snippet "Authorization" } " header of " { $snippet "request" } " to perform HTTP Basic authentication with the given " { $snippet "username" } " and " { $snippet "password" } "." }
 119 { $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." }
 120 { $side-effects "request" } ;
 121
 122 ARTICLE: "http.cookies" "HTTP cookies"
 123 "Every " { $link request } " and " { $link response } " instance can contain cookies."
 124 $nl
 125 "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."
 126 $nl
 127 "The class of cookies:"
 128 { $subsection cookie }
 129 "Creating cookies:"
 130 { $subsection <cookie> }
 131 "Getting, adding, and deleting cookies in " { $link request } " and " { $link response } " objects:"
 132 { $subsection get-cookie }
 133 { $subsection put-cookie }
 134 { $subsection delete-cookie } ;
 135
 136 ARTICLE: "http.headers" "HTTP headers"
 137 "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."
 138 { $subsection header }
 139 { $subsection set-header } ;
 140
 141 ARTICLE: "http.post-data" "HTTP post data"
 142 "Every " { $link request } " where the " { $slot "method" } " slot is " { $snippet "POST" } " can contain post data."
 143 { $subsection post-data }
 144 { $subsection <post-data> } ;
 145
 146 ARTICLE: "http.requests" "HTTP requests"
 147 "HTTP requests:"
 148 { $subsection request }
 149 { $subsection <request> }
 150 "Requests can contain form submissions:"
 151 { $subsection "http.post-data" } ;
 152
 153 ARTICLE: "http.responses" "HTTP responses"
 154 "HTTP responses:"
 155 { $subsection response }
 156 { $subsection <response> }
 157 "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" } ":"
 158 { $subsection raw-response }
 159 { $subsection <raw-response> } ;
 160
 161 ARTICLE: "http" "HTTP protocol objects"
 162 "The " { $vocab-link "http" } " vocabulary contains data types shared by " { $vocab-link "http.client" } " and " { $vocab-link "http.server" } "."
 163 $nl
 164 "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."
 165 { $subsection "http.requests" }
 166 { $subsection "http.responses" }
 167 "Both requests and responses support some common functionality:"
 168 { $subsection "http.headers" }
 169 { $subsection "http.cookies" }
 170 { $see-also "urls" } ;
 171
 172 ABOUT: "http"