helm/DEVEL/ocaml-http/http_types.ml

   1
   2 (*
   3   OCaml HTTP - do it yourself (fully OCaml) HTTP daemon
   4
   5   Copyright (C) <2002-2004> Stefano Zacchiroli <zack@cs.unibo.it>
   6
   7   This program is free software; you can redistribute it and/or modify
   8   it under the terms of the GNU General Public License as published by
   9   the Free Software Foundation; either version 2 of the License, or
  10   (at your option) any later version.
  11
  12   This program is distributed in the hope that it will be useful,
  13   but WITHOUT ANY WARRANTY; without even the implied warranty of
  14   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15   GNU General Public License for more details.
  16
  17   You should have received a copy of the GNU General Public License
  18   along with this program; if not, write to the Free Software
  19   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  20 *)
  21
  22 (** Type definitions *)
  23
  24   (** HTTP version, actually only 1.0 and 1.1 are supported. Note that
  25   'supported' here means only 'accepted inside a HTTP request line', no
  26   different behaviours are actually implemented depending on HTTP version *)
  27 type version =
  28   [ `HTTP_1_0
  29   | `HTTP_1_1
  30   ]
  31
  32   (** HTTP method, actually only GET and POST methods are supported *)
  33 type meth =
  34   [ `GET
  35   | `POST
  36   ]
  37
  38   (** Daemon behaviour wrt request handling. `Single mode use a single process
  39   to handle all requests, no request is served until a previous one has been
  40   fully served. `Fork mode fork a new process for each request, the new process
  41   will execute the callback function and then exit. `Thread mode create a new
  42   thread for each request, the new thread will execute the callback function and
  43   then exit, threads can communicate using standard OCaml Thread library. *)
  44 type daemon_mode = [ `Single | `Fork | `Thread ]
  45
  46   (** A TCP server is a function taking an address on which bind and listen for
  47   connections, an optional timeout after which abort client connections and a
  48   callback function which in turn takes an input and an output channel as
  49   arguments. After receiving this argument a TCP server sits and waits for
  50   connection, on each connection it apply the callback function to channels
  51   connected to client. *)
  52 type tcp_server =
  53   sockaddr:Unix.sockaddr -> timeout:int option ->
  54   (in_channel -> out_channel -> unit) ->
  55     unit
  56
  57   (** authentication information *)
  58 type auth_info =
  59   [ `Basic of string * string (* username, password *)
  60 (*   | `Digest of ...  (* TODO digest authentication *) *)
  61   ]
  62
  63   (** informational HTTP status, see RFC2616 *)
  64 type informational_substatus =
  65   [ `Continue
  66   | `Switching_protocols
  67   ]
  68
  69   (** success HTTP status, see RFC2616 *)
  70 type success_substatus =
  71   [ `OK
  72   | `Created
  73   | `Accepted
  74   | `Non_authoritative_information
  75   | `No_content
  76   | `Reset_content
  77   | `Partial_content
  78   ]
  79
  80   (** redirection HTTP status, see RFC2616 *)
  81 type redirection_substatus =
  82   [ `Multiple_choices
  83   | `Moved_permanently
  84   | `Found
  85   | `See_other
  86   | `Not_modified
  87   | `Use_proxy
  88   | `Temporary_redirect
  89   ]
  90
  91   (** client error HTTP status, see RFC2616 *)
  92 type client_error_substatus =
  93   [ `Bad_request
  94   | `Unauthorized
  95   | `Payment_required
  96   | `Forbidden
  97   | `Not_found
  98   | `Method_not_allowed
  99   | `Not_acceptable
 100   | `Proxy_authentication_required
 101   | `Request_time_out
 102   | `Conflict
 103   | `Gone
 104   | `Length_required
 105   | `Precondition_failed
 106   | `Request_entity_too_large
 107   | `Request_URI_too_large
 108   | `Unsupported_media_type
 109   | `Requested_range_not_satisfiable
 110   | `Expectation_failed
 111   ]
 112
 113   (** server error HTTP status, see RFC2616 *)
 114 type server_error_substatus =
 115   [ `Internal_server_error
 116   | `Not_implemented
 117   | `Bad_gateway
 118   | `Service_unavailable
 119   | `Gateway_time_out
 120   | `HTTP_version_not_supported
 121   ]
 122
 123 type informational_status = [ `Informational of informational_substatus ]
 124 type success_status = [ `Success of success_substatus ]
 125 type redirection_status = [ `Redirection of redirection_substatus ]
 126 type client_error_status = [ `Client_error of client_error_substatus ]
 127 type server_error_status = [ `Server_error of server_error_substatus ]
 128
 129 type error_status =
 130   [ client_error_status
 131   | server_error_status
 132   ]
 133
 134   (** HTTP status *)
 135 type status =
 136   [ informational_status
 137   | success_status
 138   | redirection_status
 139   | client_error_status
 140   | server_error_status
 141   ]
 142
 143 type status_code = [ `Code of int | `Status of status ]
 144
 145   (** File sources *)
 146 type file_source =
 147   | FileSrc of string           (** filename *)
 148   | InChanSrc of in_channel     (** input channel *)
 149
 150   (** {2 Exceptions} *)
 151
 152   (** invalid header encountered *)
 153 exception Invalid_header of string
 154
 155   (** invalid header name encountered *)
 156 exception Invalid_header_name of string
 157
 158   (** invalid header value encountered *)
 159 exception Invalid_header_value of string
 160
 161   (** unsupported or invalid HTTP version encountered *)
 162 exception Invalid_HTTP_version of string
 163
 164   (** unsupported or invalid HTTP method encountered *)
 165 exception Invalid_HTTP_method of string
 166
 167   (** invalid HTTP status code integer representation encountered *)
 168 exception Invalid_code of int
 169
 170   (** invalid URL encountered *)
 171 exception Malformed_URL of string
 172
 173   (** invalid query string encountered *)
 174 exception Malformed_query of string
 175
 176   (** invalid query string part encountered, arguments are parameter name and
 177   parameter value *)
 178 exception Malformed_query_part of string * string
 179
 180   (** invalid request URI encountered *)
 181 exception Malformed_request_URI of string
 182
 183   (** malformed request received *)
 184 exception Malformed_request of string
 185
 186   (** malformed response received, argument is response's first line *)
 187 exception Malformed_response of string
 188
 189   (** a parameter you were looking for was not found *)
 190 exception Param_not_found of string
 191
 192   (** invalid HTTP status line encountered *)
 193 exception Invalid_status_line of string
 194
 195   (** an header you were looking for was not found *)
 196 exception Header_not_found of string
 197
 198   (** raisable by callbacks to make main daemon quit, this is the only
 199   'clean' way to make start functions return *)
 200 exception Quit
 201
 202   (** raisable by callbacks to force a 401 (unauthorized) HTTP answer.
 203   * This exception should be raised _before_ sending any data over given out
 204   * channel.
 205   * @param realm authentication realm (usually needed to prompt user) *)
 206 exception Unauthorized of string
 207
 208   (** {2 OO representation of HTTP messages} *)
 209
 210   (** HTTP generic messages. See {! Http_message.message} *)
 211 class type message = object
 212
 213     method version: version option
 214     method setVersion: version -> unit
 215
 216     method body: string
 217     method setBody: string -> unit
 218     method bodyBuf: Buffer.t
 219     method setBodyBuf: Buffer.t -> unit
 220     method addBody: string -> unit
 221     method addBodyBuf: Buffer.t -> unit
 222
 223     method addHeader: name:string -> value:string -> unit
 224     method addHeaders: (string * string) list -> unit
 225     method replaceHeader: name:string -> value:string -> unit
 226     method replaceHeaders: (string * string) list -> unit
 227     method removeHeader: name:string -> unit
 228     method hasHeader: name:string -> bool
 229     method header: name:string -> string
 230     method headers: (string * string) list
 231
 232     method clientSockaddr: Unix.sockaddr
 233     method clientAddr: string
 234     method clientPort: int
 235
 236     method serverSockaddr: Unix.sockaddr
 237     method serverAddr: string
 238     method serverPort: int
 239
 240     method toString: string
 241     method serialize: out_channel -> unit
 242
 243   end
 244
 245   (** HTTP requests *)
 246 class type request = object
 247
 248       (** an HTTP request is a flavour of HTTP message *)
 249     inherit message
 250
 251       (** @return request method *)
 252     method meth: meth
 253
 254       (** @return requested URI (including query string, fragment, ...) *)
 255     method uri: string
 256
 257       (** @return requested path *)
 258     method path: string
 259
 260       (** lookup a given parameter
 261       @param meth if given restrict the lookup area (e.g. if meth = POST than
 262       only parameters received via POST are searched), if not given both GET and
 263       POST parameter are searched in an unspecified order (actually the
 264       implementation prefers POST parameters but this is not granted, you've
 265       been warned)
 266       @param name name of the parameter to lookup
 267       @return value associated to parameter name
 268       @raise Param_not_found if parameter name was not found *)
 269     method param: ?meth:meth -> string -> string
 270
 271       (** like param above but return a list of values associated to given
 272       parameter (a parameter could be defined indeed more than once: passed more
 273       than once in a query string or passed both insider the url (the GET way)
 274       and inside message body (the POST way)) *)
 275     method paramAll: ?meth:meth -> string -> string list
 276
 277       (** @return the list of all received parameters *)
 278     method params: (string * string) list
 279
 280       (** @return the list of all parameters received via GET *)
 281     method params_GET: (string * string) list
 282
 283       (** @return the list of all parameter received via POST *)
 284     method params_POST: (string * string) list
 285
 286       (** @return authorization information, if given by the client *)
 287     method authorization: auth_info option
 288
 289   end
 290
 291   (** HTTP responses *)
 292 class type response = object
 293
 294     inherit message
 295
 296       (** @return response code *)
 297     method code: int
 298
 299       (** set response code *)
 300     method setCode: int -> unit
 301
 302       (** @return response status, see {! Http_types.status} *)
 303     method status: status
 304
 305       (** set response status *)
 306     method setStatus: status -> unit
 307
 308       (** @return reason string *)
 309     method reason: string
 310
 311       (** set reason string *)
 312     method setReason: string -> unit
 313
 314       (** @return status line *)
 315     method statusLine: string
 316
 317       (** set status line
 318       @raise Invalid_status_line if an invalid HTTP status line was passed *)
 319     method setStatusLine: string -> unit
 320
 321       (** response is an informational one *)
 322     method isInformational: bool
 323
 324       (** response is a success one *)
 325     method isSuccess: bool
 326
 327       (** response is a redirection one *)
 328     method isRedirection: bool
 329
 330       (** response is a client error one *)
 331     method isClientError: bool
 332
 333       (** response is a server error one *)
 334     method isServerError: bool
 335
 336       (** response is either a client error or a server error response *)
 337     method isError: bool
 338
 339       (** add basic headers to response, see {! Http_daemon.send_basic_headers}
 340       *)
 341     method addBasicHeaders: unit
 342
 343       (** facilities to access some frequently used headers *)
 344
 345       (** @return Content-Type header value *)
 346     method contentType: string
 347
 348       (** set Content-Type header value *)
 349     method setContentType: string -> unit
 350
 351       (** @return Content-Encoding header value *)
 352     method contentEncoding: string
 353
 354       (** set Content-Encoding header value *)
 355     method setContentEncoding: string -> unit
 356
 357       (** @return Date header value *)
 358     method date: string
 359
 360       (** set Date header value *)
 361     method setDate: string -> unit
 362
 363       (** @return Expires header value *)
 364     method expires: string
 365
 366       (** set Expires header value *)
 367     method setExpires: string -> unit
 368
 369       (** @return Server header value *)
 370     method server: string
 371
 372       (** set Server header value *)
 373     method setServer: string -> unit
 374
 375   end
 376
 377   (** {2 OO representation of other HTTP "entities"} *)
 378
 379   (** an HTTP connection from a client to a server *)
 380 class type connection =
 381   object
 382       (** @return next request object, may block if client hasn't submitted any
 383       request yet, may be None if client request was ill-formed *)
 384     method getRequest: request option
 385
 386       (** respond to client sending it a response *)
 387     method respond_with: response -> unit
 388
 389       (** close connection to client. Warning: this object can't be used any
 390       longer after this method has been called *)
 391     method close: unit
 392   end
 393
 394   (** an HTTP daemon *)
 395 class type daemon =
 396   object
 397       (** @return a connection to a client, may block if no client has connected
 398       yet *)
 399     method accept: connection
 400
 401       (** shortcut method, blocks until a client has submit a request and
 402       return a pair request * connection *)
 403     method getRequest: request * connection
 404   end
 405