helm/DEVEL/ocaml-http/http_types.ml

   1
   2 (*
   3   OCaml HTTP - do it yourself (fully OCaml) HTTP daemon
   4
   5   Copyright (C) <2002> 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   (** informational HTTP status, see RFC2616 *)
  58 type informational_substatus =
  59   [ `Continue
  60   | `Switching_protocols
  61   ]
  62
  63   (** success HTTP status, see RFC2616 *)
  64 type success_substatus =
  65   [ `OK
  66   | `Created
  67   | `Accepted
  68   | `Non_authoritative_information
  69   | `No_content
  70   | `Reset_content
  71   | `Partial_content
  72   ]
  73
  74   (** redirection HTTP status, see RFC2616 *)
  75 type redirection_substatus =
  76   [ `Multiple_choices
  77   | `Moved_permanently
  78   | `Found
  79   | `See_other
  80   | `Not_modified
  81   | `Use_proxy
  82   | `Temporary_redirect
  83   ]
  84
  85   (** client error HTTP status, see RFC2616 *)
  86 type client_error_substatus =
  87   [ `Bad_request
  88   | `Unauthorized
  89   | `Payment_required
  90   | `Forbidden
  91   | `Not_found
  92   | `Method_not_allowed
  93   | `Not_acceptable
  94   | `Proxy_authentication_required
  95   | `Request_time_out
  96   | `Conflict
  97   | `Gone
  98   | `Length_required
  99   | `Precondition_failed
 100   | `Request_entity_too_large
 101   | `Request_URI_too_large
 102   | `Unsupported_media_type
 103   | `Requested_range_not_satisfiable
 104   | `Expectation_failed
 105   ]
 106
 107   (** server error HTTP status, see RFC2616 *)
 108 type server_error_substatus =
 109   [ `Internal_server_error
 110   | `Not_implemented
 111   | `Bad_gateway
 112   | `Service_unavailable
 113   | `Gateway_time_out
 114   | `HTTP_version_not_supported
 115   ]
 116
 117 type informational_status = [ `Informational of informational_substatus ]
 118 type success_status = [ `Success of success_substatus ]
 119 type redirection_status = [ `Redirection of redirection_substatus ]
 120 type client_error_status = [ `Client_error of client_error_substatus ]
 121 type server_error_status = [ `Server_error of server_error_substatus ]
 122
 123 type error_status =
 124   [ client_error_status
 125   | server_error_status
 126   ]
 127
 128   (** HTTP status *)
 129 type status =
 130   [ informational_status
 131   | success_status
 132   | redirection_status
 133   | client_error_status
 134   | server_error_status
 135   ]
 136
 137   (** {2 Exceptions} *)
 138
 139   (** invalid header encountered *)
 140 exception Invalid_header of string
 141
 142   (** invalid header name encountered *)
 143 exception Invalid_header_name of string
 144
 145   (** invalid header value encountered *)
 146 exception Invalid_header_value of string
 147
 148   (** unsupported or invalid HTTP version encountered *)
 149 exception Invalid_HTTP_version of string
 150
 151   (** unsupported or invalid HTTP method encountered *)
 152 exception Invalid_HTTP_method of string
 153
 154   (** invalid HTTP status code integer representation encountered *)
 155 exception Invalid_code of int
 156
 157   (** invalid URL encountered *)
 158 exception Malformed_URL of string
 159
 160   (** invalid query string encountered *)
 161 exception Malformed_query of string
 162
 163   (** invalid query string part encountered, arguments are parameter name and
 164   parameter value *)
 165 exception Malformed_query_part of string * string
 166
 167   (** invalid request URI encountered *)
 168 exception Malformed_request_URI of string
 169
 170   (** malformed request received *)
 171 exception Malformed_request of string
 172
 173   (** a parameter you were looking for was not found *)
 174 exception Param_not_found of string
 175
 176   (** invalid HTTP status line encountered *)
 177 exception Invalid_status_line of string
 178
 179   (** an header you were looking for was not found *)
 180 exception Header_not_found of string
 181
 182   (** raisable by callback functions to make main daemon quit, this is the only
 183   'clean' way to make start functions return *)
 184 exception Quit
 185
 186   (** {2 OO representation of HTTP messages} *)
 187
 188   (** HTTP generic messages. See {! Http_message.message} *)
 189 class type message = object
 190
 191     method version: version option
 192     method setVersion: version -> unit
 193
 194     method body: string
 195     method setBody: string -> unit
 196     method bodyBuf: Buffer.t
 197     method setBodyBuf: Buffer.t -> unit
 198     method addBody: string -> unit
 199     method addBodyBuf: Buffer.t -> unit
 200
 201     method addHeader: name:string -> value:string -> unit
 202     method addHeaders: (string * string) list -> unit
 203     method replaceHeader: name:string -> value:string -> unit
 204     method replaceHeaders: (string * string) list -> unit
 205     method removeHeader: name:string -> unit
 206     method hasHeader: name:string -> bool
 207     method header: name:string -> string
 208     method headers: (string * string) list
 209
 210     method clientSockaddr: Unix.sockaddr
 211     method clientAddr: string
 212     method clientPort: int
 213
 214     method serverSockaddr: Unix.sockaddr
 215     method serverAddr: string
 216     method serverPort: int
 217
 218     method toString: string
 219     method serialize: out_channel -> unit
 220
 221   end
 222
 223   (** HTTP requests *)
 224 class type request = object
 225
 226       (** an HTTP request is a flavour of HTTP message *)
 227     inherit message
 228
 229       (** @return request method *)
 230     method meth: meth
 231
 232       (** @return requested URI (including query string, fragment, ...) *)
 233     method uri: string
 234
 235       (** @return requested path *)
 236     method path: string
 237
 238       (** lookup a given parameter
 239       @param meth if given restrict the lookup area (e.g. if meth = POST than
 240       only parameters received via POST are searched), if not given both GET and
 241       POST parameter are searched in an unspecified order (actually the
 242       implementation prefers POST parameters but this is not granted, you've
 243       been warned)
 244       @param name name of the parameter to lookup
 245       @return value associated to parameter name
 246       @raise Param_not_found if parameter name was not found *)
 247     method param: ?meth:meth -> string -> string
 248
 249       (** like param above but return a list of values associated to given
 250       parameter (a parameter could be defined indeed more than once: passed more
 251       than once in a query string or passed both insider the url (the GET way)
 252       and inside message body (the POST way)) *)
 253     method paramAll: ?meth:meth -> string -> string list
 254
 255       (** @return the list of all received parameters *)
 256     method params: (string * string) list
 257
 258       (** @return the list of all parameters received via GET *)
 259     method params_GET: (string * string) list
 260
 261       (** @return the list of all parameter received via POST *)
 262     method params_POST: (string * string) list
 263
 264   end
 265
 266   (** HTTP responses *)
 267 class type response = object
 268
 269     inherit message
 270
 271       (** @return response code *)
 272     method code: int
 273
 274       (** set response code *)
 275     method setCode: int -> unit
 276
 277       (** @return response status, see {! Http_types.status} *)
 278     method status: status
 279
 280       (** set response status *)
 281     method setStatus: status -> unit
 282
 283       (** @return reason string *)
 284     method reason: string
 285
 286       (** set reason string *)
 287     method setReason: string -> unit
 288
 289       (** @return status line *)
 290     method statusLine: string
 291
 292       (** set status line
 293       @raise Invalid_status_line if an invalid HTTP status line was passed *)
 294     method setStatusLine: string -> unit
 295
 296       (** response is an informational one *)
 297     method isInformational: bool
 298
 299       (** response is a success one *)
 300     method isSuccess: bool
 301
 302       (** response is a redirection one *)
 303     method isRedirection: bool
 304
 305       (** response is a client error one *)
 306     method isClientError: bool
 307
 308       (** response is a server error one *)
 309     method isServerError: bool
 310
 311       (** response is either a client error or a server error response *)
 312     method isError: bool
 313
 314       (** add basic headers to response, see {! Http_daemon.send_basic_headers}
 315       *)
 316     method addBasicHeaders: unit
 317
 318       (** facilities to access some frequently used headers *)
 319
 320       (** @return Content-Type header value *)
 321     method contentType: string
 322
 323       (** set Content-Type header value *)
 324     method setContentType: string -> unit
 325
 326       (** @return Content-Encoding header value *)
 327     method contentEncoding: string
 328
 329       (** set Content-Encoding header value *)
 330     method setContentEncoding: string -> unit
 331
 332       (** @return Date header value *)
 333     method date: string
 334
 335       (** set Date header value *)
 336     method setDate: string -> unit
 337
 338       (** @return Expires header value *)
 339     method expires: string
 340
 341       (** set Expires header value *)
 342     method setExpires: string -> unit
 343
 344       (** @return Server header value *)
 345     method server: string
 346
 347       (** set Server header value *)
 348     method setServer: string -> unit
 349
 350   end
 351
 352   (** {2 OO representation of other HTTP "entities"} *)
 353
 354   (** an HTTP connection from a client to a server *)
 355 class type connection =
 356   object
 357       (** @return next request object, may block if client hasn't submitted any
 358       request yet, may be None if client request was ill-formed *)
 359     method getRequest: request option
 360
 361       (** respond to client sending it a response *)
 362     method respond_with: response -> unit
 363
 364       (** close connection to client. Warning: this object can't be used any
 365       longer after this method has been called *)
 366     method close: unit
 367   end
 368
 369   (** an HTTP daemon *)
 370 class type daemon =
 371   object
 372       (** @return a connection to a client, may block if no client has connected
 373       yet *)
 374     method accept: connection
 375
 376       (** shortcut method, blocks until a client has submit a request and
 377       return a pair request * connection *)
 378     method getRequest: request * connection
 379   end
 380