/usr/lib/ocaml/nethttpd/nethttpd_types.mli is in libnethttpd-ocaml-dev 3.7.3-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 | (* $Id: nethttpd_types.mli 1410 2010-02-14 19:44:28Z gerd $
*
*)
(*
* Copyright 2005 Baretta s.r.l. and Gerd Stolpmann
*
* This file is part of Nethttpd.
*
* Nethttpd is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* Nethttpd is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with WDialog; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*)
(** Type definitions for the HTTP daemon
*
* {b Contents}
*
* - {!Nethttpd_types.exceptions}
* - {!Nethttpd_types.environment}
* - {!Nethttpd_types.service}
* - {!Nethttpd_types.helpers}
*)
(** Many types can also be found in the [Nethttp] module (part of netstring).
* Furthermore, [Netcgi_env] and [Netcgi_types] are of interest (part of cgi).
*)
(** {1:exceptions Exceptions} *)
open Nethttp
exception Standard_response of http_status * http_header option * string option
(** Some HTTP containers allow you to raise this exception. The standard
* response corresponding to [http_status] is sent back to the client.
* If the third argument exists, an entry into the error log
* is written.
*)
(**********************************************************************)
(** {1:environment Environment} *)
type output_state =
[ `Start
| `Sending
| `End
]
val string_of_output_state : output_state -> string
(** Debugging *)
(** An extension of [cgi_environment] for use with the daemon. The methods
* retrieving the socket addresses are virtual.
*)
class type virtual v_extended_environment =
object
inherit Netcgi.cgi_environment
method virtual server_socket_addr : Unix.sockaddr
method virtual remote_socket_addr : Unix.sockaddr
(** These are always the physical IP addresses and ports of the two endpoints
* of the current connection.
*)
method cgi_request_uri : string
(** The full request URI. Identical to the CGI property "REQUEST_URI" *)
method log_props : (string * string) list -> unit
(** Remember this version of [cgi_properties] as the one sent to the
[config_log_access] function
*)
method input_channel : Netchannels.in_obj_channel
(** The input channel for reading the body of the request *)
method input_body_size : int64
(** so far known, or 0L *)
method request_body_rejected : bool
(** so far known, or false *)
method send_file : Unix.file_descr -> int64 -> unit
(** Sends the output header with a file as body. The file must already be open,
* and positioned where the transmission begins. The number is the length
* of the transmission.
*
* This method may return immediately when it is possible to open the file, and
* to set the kernel up for file transmission. Otherwise a [Unix_error] is
* raised. It is also allowed that this method blocks until the file is actually
* transmitted.
*
* It is not allowed to print to the output channel and to call [send_file].
* Only one transmission method must be invoked.
*)
method virtual output_state : output_state ref
(** Reflects the state of the output generation:
- [`Start]: Nothing is generated yet
- [`Sending]: Output is already being sent
- [`End]: The response (for a single request) has been fully sent
*)
end
(** Same as [v_extended_environment], but no virtual methods
*)
class type extended_environment =
object
inherit v_extended_environment
method server_socket_addr : Unix.sockaddr
method remote_socket_addr : Unix.sockaddr
method output_state : output_state ref
end
(** {2 Construction of environments} *)
class virtual empty_environment :
object
inherit v_extended_environment
val mutable config : Netcgi.config
val mutable protocol : Nethttp.protocol
val mutable in_header : http_header
val mutable out_header : http_header
val mutable properties : (string * string) list
val mutable in_channel : Netchannels.in_obj_channel
val mutable out_channel : Netchannels.out_obj_channel
end
(** This class implements an environment with defined internal containers.
* These containers are empty, but fully functional.
* The following methods are empty and should be redefined:
* - [send_output_header]
* - [send_file]
* - [log_error]
* - [log_props]
*
* The virtual methods, of course, must be defined!
*)
class redirected_environment :
?in_header : http_header ->
?properties : (string * string) list ->
?in_channel : Netchannels.in_obj_channel ->
extended_environment ->
extended_environment
(** This class overlays the input-side containers of an existing environment.
* The output-side containers ([out_header], and [out_channel])
* are physically identical with the existing environment.
*
* If one of the argument is not passed on class instantiation, the corresponding
* overlay container is initialized with the current value of the passed
* environment. As exception of this rule, the input channel is initialized with
* an empty input channel.
*)
(** {2 Auxiliary Functions for Environments} *)
val output_static_response : #extended_environment ->
http_status -> http_header option -> string -> unit
(** Outputs the string argument as response body, together with the given status and
* the header (optional). Response header fields are set as follows:
* - The [Content-Length] is set to the length of the string.
* - The [Content-Type] is set to "text/html" unless given by the header.
*
* If the header is not passed, the header of the environment is taken. If the header
* argument exists, however, it overrides the header of the environment.
*)
val output_file_response : #extended_environment ->
http_status -> http_header option ->
string -> int64 -> int64 -> unit
(** Outputs the contents of a file as response body, together with the given status and
* the header (optional). The string is the file name. The first int64 number is
* the position in the file where to start, and the second number is the length
* of the body. Response header fields are set as follows:
* - The [Content-Length] is set to the length of the string.
* - The [Content-Type] is set to "text/html" unless given by the header.
*
* Note that [Content-Range] is not set automatically, even if the file is only
* partially transferred.
*
* If the header is not passed, the header of the environment is taken. If the header
* argument exists, however, it overrides the header of the environment.
*
* The function raises [Sys_error] when the file cannot be read.
*)
(** {1 Generating error responses, logging} *)
class type request_info =
object
method server_socket_addr : Unix.sockaddr
(** The socket address of this server. May raise [Not_found] if
there is no such address *)
method remote_socket_addr : Unix.sockaddr
(** The socket address of the client. May raise [Not_found] if
there is no such address *)
method request_method : string
(** The method like [GET]. May raise [Not_found] *)
method request_uri : string
(** The URI of the client request. This is often without the
server designation, i.e. just [/path?query].
May raise [Not_found] *)
method input_header : Nethttp.http_header
(** The request header. May raise [Not_found] *)
method cgi_properties : (string * string) list
(** The distilled CGI properties *)
method input_body_size : int64
(** The size of the input body. May raise [Not_found] *)
end
class type full_info =
object
inherit request_info
method response_status_code : int
(** The HTTP status code to response *)
method request_body_rejected : bool
(** Whether the request body was rejected *)
method output_header : Nethttp.http_header
(** The response header *)
method output_body_size : int64
(** The size of the output body. *)
end
class create_full_info : response_status_code:int ->
request_body_rejected:bool ->
output_header:Nethttp.http_header ->
output_body_size:int64 ->
request_info -> full_info
(** Creates a [full_info] object by adding to a [request_info] object *)
class type error_response_params =
object
inherit request_info
method response_status_code : int
(** The HTTP status code to response *)
method error_message : string
(** The error message explaining the detail that went wrong *)
end
class type min_config =
object
method config_error_response : error_response_params -> string
method config_log_error : request_info -> string -> unit
end
(** Minimal configuration needed for [output_std_response] *)
val output_std_response : #min_config -> #extended_environment ->
http_status -> http_header option -> string option -> unit
(** Outputs a "standard response" for the [http_status]. The string argument
* is an optional entry into the error log.
*
* If the header is not passed, an empty header is taken. If the header argument
* exists, this header is taken. The header of the environment is never taken.
*)
(**********************************************************************)
(** {1:service Service Providers}
*
* Service providers are defined using the three class types:
* - [http_service]: The service provider as such. When a HTTP header has been
* received, and the service provider is invoked, it returns an object
* fitting to the next class type, [http_service_receiver]. This object
* is tagged with [`Accept_body]; at this point there are also alternate ways
* of processing, see below.
* - [http_service_receiver]: The task of this object is to receive the request
* body. When the body has been completely received, the object is notified,
* and returns a third object of type [http_service_generator].
* - [http_service_generator]: The task of this object is to generate the
* response.
*
* An implementor is free to define only one class that satisfies all three
* class types at once. However, this is only an option.
*
* The three objects reflect three stages of HTTP processing. The stages have
* made explicit to allow the implementor of services to intercept the points
* in time when the processing of the next stage begins. Furthermore, in multi-threaded
* environments it is allowed that the stages are performed in the contexts of
* different threads.
*
* In addition to the three-stage model there also several faster paths of
* processing:
* - [`Reject_body] can be used to refuse the acceptance of the request body when
* it is already clear that an error response is sent back. This path skips
* the stage [http_service_receiver].
* - [`Static] can be used to send a constant string back (only to be used
* when the string needs not to be computed)
* - [`File] can be used to send the contents of a file back (only to be used
* when the file already exists)
*)
exception Redirect_request of string * http_header
(** The "early" redirect is only allowed in stage 1 of HTTP processing.
* The string argument is the new URI path of the request. The header can also
* be exchanged except the fields that are needed to decode the request
* body. It is not possible to change the method.
*)
exception Redirect_response of string * http_header
(** The "late" redirect is only allowed in stage 3 of HTTP processing.
* The string argument is the new URI path of the request. The header can also
* be exchanged except the fields that are needed to decode the request
* body. {b The method is always changed to [GET].}
*)
class type http_service_generator =
object
method generate_response : extended_environment -> unit
(** Third stage of HTTP processing:
* This method is called when the HTTP request has been completely received,
* and the response is going to be generated. This method can again be called
* from a different thread than the previous stages. It is allowed to spend
* any necessary time to compute the response.
*
* When the method returns, the request processing is finished. No more data
* is allowed to be written to the output channel past this moment.
*
* The method may raise [Standard_response] to generate one of the
* standard messages.
*)
end
class type http_service_receiver =
object
method process_body : extended_environment -> http_service_generator
(** Second stage of HTTP processing:
* This method is called when the body is expected to be arriving. Note that
* the main difference to [process_header] is that this method can be
* called from a different thread. It is allowed (and expected) that this method
* blocks while reading the input. Of course, the input and output
* channels of the environment are unlocked, and can be used.
*
* When the method returns, the request processing continues with stage 3.
* Any body data not read is dropped.
*
* It is allowed that this method generates a response (or part of it),
* although this should be better done in stage 3.
*
* The method may raise [Standard_response] to generate one of the
* standard messages.
*
* One way of implementing this method is to instantiate [Netcgi.std_activation].
*)
end
type http_service_reaction =
[ `Accept_body of http_service_receiver
| `Reject_body of http_service_generator
| `Static of http_status * http_header option * string
| `File of http_status * http_header option * string * int64 * int64
| `Std_response of http_status * http_header option * string option
]
(** Indicates the immediate reaction upon an arriving HTTP header:
* - [`Accept_body] is the regular way of processing requests. If necessary,
* the client is told to continue sending the rest of the request.
* - [`Reject_body] can be used when the body of the request is not needed,
* and the response will be negative.
* - [`Static] means to send the header and a constant string back as response.
* The header is taken from the environment if not explicitly passed,
* Note: The [Content-Length] header is automatically added. The [Content-Type]
* defaults to "text/html".
* - [`File] is similar to this, but the data come from a file. The file
* is specified by an absolute pathname. The range of the file is given
* by the start position and the length of the range.
* The header is taken from the environment if not explicitly passed,
* Note: The [Content-Length] header is automatically added. The [Content-Type]
* defaults to "text/html".
* - [`Std_response] is similar to [`Static], however the body is the standard
* text for the status code. If the header is omitted, it is taken as empty.
* The third argument is an optional entry into the error log.
* Note: The [Content-Length] header is automatically added. The [Content-Type]
* defaults to "text/html".
*)
class type ['a] http_service =
object
method name : string
(** The name of the type of the service provider *)
method def_term :'a
(** The definition term *)
method print : Format.formatter -> unit
(** Outputs the definition term to a formatter *)
method process_header : extended_environment -> http_service_reaction
(** First stage of HTTP processing:
* This method is called when the HTTP header has been received. This method
* must return quickly without blocking the thread how to go on. For example,
* this could look as follows:
* - Check whether the client is allowed to access this resource. If this
* can be done immediately, it should be done now. (If an external service
* must be queried, the check must not be done now, but deferred to the
* second or third stage.) If the access is denied, an error response can
* be sent back using [`Static], [`File], or, if computed, using [`Reject_body].
* - Check whether the request is delegated to another service provider
* (e.g. lookup by hostname, by port number, or by URI). In this case,
* the result of this [process_header] call is simply the result of the
* [process_header] call of the other service provider.
* - If this service provider generates the contents, there are mainly two
* types of reaction. If the contents are stored in a file, one can simply
* return [`File]. Otherwise, return [`Accept_body] to continue with the
* second stage. Note that even if no body is expected to arrive, one must
* go through the second stage, and drop any unexpected body.
*
* The argument of this function is the Netcgi environment. The header is
* complete, including the request method. One cannot access the input and
* output channels at this stage of processing.
*)
end
(**********************************************************************)
(** {1:helpers Helpers} *)
val update_alist : ('a * 'b) list -> ('a * 'b) list -> ('a * 'b) list
(** [update_alist updl l]: Returns the alist with all elements of [updl]
* and all elements of [l] that are not member of [updl].
*)
|