Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Changes In Branch httpd-docs-move Excluding Merge-Ins
This is equivalent to a diff from b14633aa2f to 54eb35fc91
2018-08-28
| ||
04:26 | And fixes placed on a branch for Sean to look at. Approved. Now integrating. check-in: 671d1f47a3 user: aku tags: pooryorick | |
03:29 | Series of documentation fixes for problems caught by the experimental doctools parser written as large Marpa/Tcl example. - Removed many superfluous closing brackets. Some converted to proper [rb] markup. - Removed bad cross-references introduced by [c6b17331c9d12697] several years ago. - Removed several bad [para]graph markers placed before the first item of the enclosing list. Regenerated the embedded docs. check-in: 3c9d4bcd85 user: aku tags: pooryorick | |
03:19 | httpd: Renamed doc include files to follow the overall practice of naming them `.inc`. Closed-Leaf check-in: 54eb35fc91 user: aku tags: pooryorick, httpd-docs-move | |
2018-08-27
| ||
20:31 | cron manpage: Fixed millisecond typo. <D> check-in: b14633aa2f user: aku tags: pooryorick | |
20:28 | Fixes to cron manpage. Regenerated embedded docs. check-in: 61102fe7dc user: aku tags: pooryorick | |
Added modules/httpd/build/content.inc.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | [section {Class ::httpd::content}] The httpd module includes several ready to use implementations of content mixins for common use cases. Options are passed in to the [cmd add_uri] method of the server. [section {Class ::httpd::content.cgi}] An implementation to relay requests to process which will accept post data streamed in vie stdin, and sent a reply streamed to stdout. [list_begin definitions] [call method cgi_info] Mandatory method to be replaced by the end user. If needed, activates the process to proxy, and then returns a list of three values: [arg exec] - The arguments to send to exec to fire off the responding process, minus the stdin/stdout redirection. [list_end] [section {Class ::httpd::content.file}] An implementation to deliver files from the local file system. [list_begin definitions] [call option [cmd path]] The root directory on the local file system to be exposed via http. [call option [cmd prefix]] The prefix of the URI portion to ignore when calculating relative file paths. [list_end] [section {Class ::httpd::content.proxy}] An implementation to relay requests to another HTTP server, and relay the results back across the request channel. [list_begin definitions] [call method proxy_info] Mandatory method to be replaced by the end user. If needed, activates the process to proxy, and then returns a list of three values: [arg proxyhost] - The hostname where the proxy is located [arg proxyport] - The port to connect to [arg proxyscript] - A pre-amble block of text to send prior to the mirrored request [list_end] [section {Class ::httpd::content.scgi}] An implementation to relay requests to a server listening on a socket expecting SCGI encoded requests, and relay the results back across the request channel. [list_begin definitions] [call method scgi_info] Mandatory method to be replaced by the end user. If needed, activates the process to proxy, and then returns a list of three values: [arg scgihost] - The hostname where the scgi listener is located [arg scgiport] - The port to connect to [arg scgiscript] - The contents of the [arg SCRIPT_NAME] header to be sent [list_end] [section {Class ::httpd::content.websocket}] A placeholder for a future implementation to manage requests that can expect to be promoted to a Websocket. Currently it is an empty class. [section {SCGI Server Functions}] The HTTP module also provides an SCGI server implementation, as well as an HTTP implementation. To use the SCGI functions, create an object of the [cmd http::server.scgi] class instead of the [cmd http::server] class. [section {Class ::httpd::reply.scgi}] An modified [cmd http::reply] implementation that understands how to deal with netstring encoded headers. [section {Class ::httpd::server.scgi}] A modified [cmd http::server] which is tailored to replying to request according to the SCGI standard instead of the HTTP standard. |
Deleted modules/httpd/build/content.man.
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
Added modules/httpd/build/reply.inc.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 | [section {Class ::httpd::reply}] A class which shephards a request through the process of generating a reply. The socket associated with the reply is available at all times as the [arg chan] variable. The process of generating a reply begins with an [cmd httpd::server] generating a [cmd http::class] object, mixing in a set of behaviors and then invoking the reply object's [cmd dispatch] method. In normal operations the [cmd dispatch] method: [list_begin enumerated] [enum] Invokes the [cmd reset] method for the object to populate default headers. [enum] Invokes the [cmd HttpHeaders] method to stream the MIME headers out of the socket [enum] Invokes the [cmd {request parse}] method to convert the stream of MIME headers into a dict that can be read via the [cmd request] method. [enum] Stores the raw stream of MIME headers in the [arg rawrequest] variable of the object. [enum] Invokes the [cmd content] method for the object, generating an call to the [cmd error] method if an exception is raised. [enum] Invokes the [cmd output] method for the object [list_end] [para] [section {Reply Method Ensembles}] The [cmd http::reply] class and its derivatives maintain several variables as dictionaries internally. Access to these dictionaries is managed through a dedicated ensemble. The ensemble implements most of the same behaviors as the [cmd dict] command. Each ensemble implements the following methods above, beyond, or modifying standard dicts: [list_begin definitions] [call method [cmd ENSEMBLE::add] [arg field] [arg element]] Add [arg element] to a list stored in [arg field], but only if it is not already present om the list. [call method [cmd ENSEMBLE::dump]] Return the current contents of the data structure as a key/value list. [call method [cmd ENSEMBLE::get] [arg field]] Return the value of the field [arg field], or an empty string if it does not exist. [call method [cmd ENSEMBLE::reset]] Return a key/value list of the default contents for this data structure. [call method [cmd ENSEMBLE::remove] [arg field] [arg element]] Remove all instances of [arg element] from the list stored in [arg field]. [call method [cmd ENSEMBLE::replace] [arg keyvaluelist]] Replace the internal dict with the contents of [arg keyvaluelist] [call method [cmd ENSEMBLE::reset]] Replace the internal dict with the default state. [call method [cmd ENSEMBLE::set] [arg field] [arg value]] Set the value of [arg field] to [arg value]. [list_end] [section {Reply Method Ensemble: http_info}] Manages HTTP headers passed in by the server. Ensemble Methods: [list_begin definitions] [call method [cmd http_info::netstring]] Return the contents of this data structure as a netstring encoded block. [list_end] [section {Reply Method Ensemble: request}] Managed data from MIME headers of the request. [list_begin definitions] [call method [cmd request::parse] [arg string]] Replace the contents of the data structure with information encoded in a MIME formatted block of text ([arg string]). [list_end] [section {Reply Method Ensemble: reply}] Manage the headers sent in the reply. [list_begin definitions] [call method [cmd reply::output]] Return the contents of this data structure as a MIME encoded block appropriate for an HTTP response. [list_end] [section {Reply Methods}] [list_begin definitions] [call method [cmd close]] Terminate the transaction, and close the socket. [call method [cmd HttpHeaders] [arg sock] [arg ?debug?]] Stream MIME headers from the socket [arg sock], stopping at an empty line. Returns the stream as a block of text. [call method [cmd dispatch] [arg newsock] [arg datastate]] Take over control of the socket [arg newsock], and store that as the [arg chan] variable for the object. This method runs through all of the steps of reading HTTP headers, generating content, and closing the connection. (See class writetup). [call method [cmd error] [arg code] [arg ?message?] [arg ?errorInfo?]] Generate an error message of the specified [arg code], and display the [arg message] as the reason for the exception. [arg errorInfo] is passed in from calls, but how or if it should be displayed is a prerogative of the developer. [call method [cmd content]] Generate the content for the reply. This method is intended to be replaced by the mixin. Developers have the option of streaming output to a buffer via the [cmd puts] method of the reply, or simply populating the [arg reply_body] variable of the object. The information returned by the [cmd content] method is not interpreted in any way. If an exception is thrown (via the [cmd error] command in Tcl, for example) the caller will auto-generate a 500 {Internal Error} message. A typical implementation of [cmd content] look like: [example { tool::define ::test::content.file { superclass ::httpd::content.file # Return a file # Note: this is using the content.file mixin which looks for the reply_file variable # and will auto-compute the Content-Type method content {} { my reset set doc_root [my http_info get doc_root] my variable reply_file set reply_file [file join $doc_root index.html] } } tool::define ::test::content.time { # return the current system time method content {} { my variable reply_body my reply set Content-Type text/plain set reply_body [clock seconds] } } tool::define ::test::content.echo { method content {} { my variable reply_body my reply set Content-Type [my request get CONTENT_TYPE] set reply_body [my PostData [my request get CONTENT_LENGTH]] } } tool::define ::test::content.form_handler { method content {} { set form [my FormData] my reply set Content-Type {text/html; charset=UTF-8} my puts [my html header {My Dynamic Page}] my puts "<BODY>" my puts "You Sent<p>" my puts "<TABLE>" foreach {f v} $form { my puts "<TR><TH>$f</TH><TD><verbatim>$v</verbatim></TD>" } my puts "</TABLE><p>" my puts "Send some info:<p>" my puts "<FORM action=/[my http_info get REQUEST_PATH] method POST>" my puts "<TABLE>" foreach field {name rank serial_number} { set line "<TR><TH>$field</TH><TD><input name=\"$field\" " if {[dict exists $form $field]} { append line " value=\"[dict get $form $field]\""" } append line " /></TD></TR>" my puts $line } my puts "</TABLE>" my puts [my html footer] } } }] [call method [cmd EncodeStatus] [arg status]] Formulate a standard HTTP status header from he string provided. [call method FormData] For GET requests, converts the QUERY_DATA header into a key/value list. For POST requests, reads the Post data and converts that information to a key/value list for application/x-www-form-urlencoded posts. For multipart posts, it composites all of the MIME headers of the post to a singular key/value list, and provides MIME_* information as computed by the [cmd mime] package, including the MIME_TOKEN, which can be fed back into the mime package to read out the contents. [call method MimeParse [arg mimetext]] Converts a block of mime encoded text to a key/value list. If an exception is encountered, the method will generate its own call to the [cmd error] method, and immediately invoke the [cmd output] method to produce an error code and close the connection. [call method [cmd DoOutput]] Generates the the HTTP reply, and streams that reply back across [arg chan]. [call method PostData [arg length]] Stream [arg length] bytes from the [arg chan] socket, but only of the request is a POST or PUSH. Returns an empty string otherwise. [call method [cmd puts] [arg string]] Appends the value of [arg string] to the end of [arg reply_body], as well as a trailing newline character. [call method [cmd reset]] Clear the contents of the [arg reply_body] variable, and reset all headers in the [cmd reply] structure back to the defaults for this object. [call method [cmd timeOutCheck]] Called from the [cmd http::server] object which spawned this reply. Checks to see if too much time has elapsed while waiting for data or generating a reply, and issues a timeout error to the request if it has, as well as destroy the object and close the [arg chan] socket. [call method [cmd timestamp]] Return the current system time in the format: [example {%a, %d %b %Y %T %Z}] [call method [cmd TransferComplete] [arg args]] Intended to be invoked from [cmd {chan copy}] as a callback. This closes every channel fed to it on the command line, and then destroys the object. [example { ### # Output the body ### chan configure $sock -translation binary -blocking 0 -buffering full -buffersize 4096 chan configure $chan -translation binary -blocking 0 -buffering full -buffersize 4096 if {$length} { ### # Send any POST/PUT/etc content ### chan copy $sock $chan -size $SIZE -command [info coroutine] yield } catch {close $sock} chan flush $chan }] [call method [cmd Url_Decode] [arg string]] De-httpizes a string. [list_end] |
Deleted modules/httpd/build/reply.man.
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
Added modules/httpd/build/server.inc.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 | [section {Class ::httpd::server}] This class is the root object of the webserver. It is responsible for opening the socket and providing the initial connection negotiation. [list_begin definitions] [call constructor ?port [opt port]? ?myaddr [opt ipaddr]|all? ?server_string [opt string]? ?server_name [opt string]?] Build a new server object. [opt port] is the port to listen on [call method [cmd add_uri] [arg pattern] [arg dict]] Set the hander for a URI pattern. Information given in the [arg dict] is stored in the data structure the [cmd dispatch] method uses. If a field called [arg mixin] is given, that class will be mixed into the reply object immediately after construction. [call method [cmd connect] [arg sock] [arg ip] [arg port]] Reply to an open socket. This method builds a coroutine to manage the remainder of the connection. The coroutine's operations are driven by the [cmd Connect] method. [call method [cmd Connect] [arg uuid] [arg sock] [arg ip]] This method reads HTTP headers, and then consults the [cmd dispatch] method to determine if the request is valid, and/or what kind of reply to generate. Under normal cases, an object of class [cmd ::http::reply] is created. Fields the server are looking for in particular are: class: A class to use instead of the server's own [arg reply_class] mixin: A class to be mixed into the new object after construction. All other fields are passed along to the [cmd http_info] structure of the reply object. After the class is created and the mixin is mixed in, the server invokes the reply objects [cmd dispatch] method. This action passes control of the socket to the reply object. The reply object manages the rest of the transaction, including closing the socket. [call method [cmd counter] [arg which]] Increment an internal counter. [call method [cmd CheckTimeout]] Check open connections for a time out event. [call method [cmd dispatch] [arg header_dict]] Given a key/value list of information, return a data structure describing how the server should reply. [call method [cmd log] [arg args]] Log an event. The input for args is free form. This method is intended to be replaced by the user, and is a noop for a stock http::server object. [call method [cmd port_listening]] Return the actual port that httpd is listening on. [call method [cmd PrefixNormalize] [arg prefix]] For the stock version, trim trailing /'s and *'s from a prefix. This method can be replaced by the end user to perform any other transformations needed for the application. [call method [cmd start]] Open the socket listener. [call method [cmd stop]] Shut off the socket listener, and destroy any pending replies. [call method [cmd template] [arg page]] Return a template for the string [arg page] [call method [cmd TemplateSearch] [arg page]] Perform a search for the template that best matches [arg page]. This can include local file searches, in-memory structures, or even database lookups. The stock implementation simply looks for files with a .tml or .html extension in the [opt doc_root] directory. [call method [cmd Validate_Connection] [arg sock] [arg ip]] Given a socket and an ip address, return true if this connection should be terminated, or false if it should be allowed to continue. The stock implementation always returns 0. This is intended for applications to be able to implement black lists and/or provide security based on IP address. [list_end] |
Deleted modules/httpd/build/server.man.
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
Changes to modules/httpd/httpd.man.
︙ | ︙ | |||
49 50 51 52 53 54 55 | my puts </BODY></HTML> } } ::docserver::server create HTTPD port 8015 myaddr 127.0.0.1 HTTPD add_uri /* [list mixin reply.hello] }] | | | | | 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 | my puts </BODY></HTML> } } ::docserver::server create HTTPD port 8015 myaddr 127.0.0.1 HTTPD add_uri /* [list mixin reply.hello] }] [include build/server.inc] [include build/reply.inc] [include build/content.inc] [section AUTHORS] Sean Woods [vset CATEGORY network] [include ../doctools2base/include/feedback.inc] [manpage_end] |