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   (** File sources *)
 138 type file_source =
 139   | FileSrc of string           (** filename *)
 140   | InChanSrc of in_channel     (** input channel *)
 141
 142   (** {2 Exceptions} *)
 143
 144   (** invalid header encountered *)
 145 exception Invalid_header of string
 146
 147   (** invalid header name encountered *)
 148 exception Invalid_header_name of string
 149
 150   (** invalid header value encountered *)
 151 exception Invalid_header_value of string
 152
 153   (** unsupported or invalid HTTP version encountered *)
 154 exception Invalid_HTTP_version of string
 155
 156   (** unsupported or invalid HTTP method encountered *)
 157 exception Invalid_HTTP_method of string
 158
 159   (** invalid HTTP status code integer representation encountered *)
 160 exception Invalid_code of int
 161
 162   (** invalid URL encountered *)
 163 exception Malformed_URL of string
 164
 165   (** invalid query string encountered *)
 166 exception Malformed_query of string
 167
 168   (** invalid query string part encountered, arguments are parameter name and
 169   parameter value *)
 170 exception Malformed_query_part of string * string
 171
 172   (** invalid request URI encountered *)
 173 exception Malformed_request_URI of string
 174
 175   (** malformed request received *)
 176 exception Malformed_request of string
 177
 178   (** malformed response received, argument is response's first line *)
 179 exception Malformed_response of string
 180
 181   (** a parameter you were looking for was not found *)
 182 exception Param_not_found of string
 183
 184   (** invalid HTTP status line encountered *)
 185 exception Invalid_status_line of string
 186
 187   (** an header you were looking for was not found *)
 188 exception Header_not_found of string
 189
 190   (** raisable by callback functions to make main daemon quit, this is the only
 191   'clean' way to make start functions return *)
 192 exception Quit
 193
 194   (** {2 OO representation of HTTP messages} *)
 195
 196   (** HTTP generic messages. See {! Http_message.message} *)
 197 class type message = object
 198
 199     method version: version option
 200     method setVersion: version -> unit
 201
 202     method body: string
 203     method setBody: string -> unit
 204     method bodyBuf: Buffer.t
 205     method setBodyBuf: Buffer.t -> unit
 206     method addBody: string -> unit
 207     method addBodyBuf: Buffer.t -> unit
 208
 209     method addHeader: name:string -> value:string -> unit
 210     method addHeaders: (string * string) list -> unit
 211     method replaceHeader: name:string -> value:string -> unit
 212     method replaceHeaders: (string * string) list -> unit
 213     method removeHeader: name:string -> unit
 214     method hasHeader: name:string -> bool
 215     method header: name:string -> string
 216     method headers: (string * string) list
 217
 218     method clientSockaddr: Unix.sockaddr
 219     method clientAddr: string
 220     method clientPort: int
 221
 222     method serverSockaddr: Unix.sockaddr
 223     method serverAddr: string
 224     method serverPort: int
 225
 226     method toString: string
 227     method serialize: out_channel -> unit
 228
 229   end
 230
 231   (** HTTP requests *)
 232 class type request = object
 233
 234       (** an HTTP request is a flavour of HTTP message *)
 235     inherit message
 236
 237       (** @return request method *)
 238     method meth: meth
 239
 240       (** @return requested URI (including query string, fragment, ...) *)
 241     method uri: string
 242
 243       (** @return requested path *)
 244     method path: string
 245
 246       (** lookup a given parameter
 247       @param meth if given restrict the lookup area (e.g. if meth = POST than
 248       only parameters received via POST are searched), if not given both GET and
 249       POST parameter are searched in an unspecified order (actually the
 250       implementation prefers POST parameters but this is not granted, you've
 251       been warned)
 252       @param name name of the parameter to lookup
 253       @return value associated to parameter name
 254       @raise Param_not_found if parameter name was not found *)
 255     method param: ?meth:meth -> string -> string
 256
 257       (** like param above but return a list of values associated to given
 258       parameter (a parameter could be defined indeed more than once: passed more
 259       than once in a query string or passed both insider the url (the GET way)
 260       and inside message body (the POST way)) *)
 261     method paramAll: ?meth:meth -> string -> string list
 262
 263       (** @return the list of all received parameters *)
 264     method params: (string * string) list
 265
 266       (** @return the list of all parameters received via GET *)
 267     method params_GET: (string * string) list
 268
 269       (** @return the list of all parameter received via POST *)
 270     method params_POST: (string * string) list
 271
 272   end
 273
 274   (** HTTP responses *)
 275 class type response = object
 276
 277     inherit message
 278
 279       (** @return response code *)
 280     method code: int
 281
 282       (** set response code *)
 283     method setCode: int -> unit
 284
 285       (** @return response status, see {! Http_types.status} *)
 286     method status: status
 287
 288       (** set response status *)
 289     method setStatus: status -> unit
 290
 291       (** @return reason string *)
 292     method reason: string
 293
 294       (** set reason string *)
 295     method setReason: string -> unit
 296
 297       (** @return status line *)
 298     method statusLine: string
 299
 300       (** set status line
 301       @raise Invalid_status_line if an invalid HTTP status line was passed *)
 302     method setStatusLine: string -> unit
 303
 304       (** response is an informational one *)
 305     method isInformational: bool
 306
 307       (** response is a success one *)
 308     method isSuccess: bool
 309
 310       (** response is a redirection one *)
 311     method isRedirection: bool
 312
 313       (** response is a client error one *)
 314     method isClientError: bool
 315
 316       (** response is a server error one *)
 317     method isServerError: bool
 318
 319       (** response is either a client error or a server error response *)
 320     method isError: bool
 321
 322       (** add basic headers to response, see {! Http_daemon.send_basic_headers}
 323       *)
 324     method addBasicHeaders: unit
 325
 326       (** facilities to access some frequently used headers *)
 327
 328       (** @return Content-Type header value *)
 329     method contentType: string
 330
 331       (** set Content-Type header value *)
 332     method setContentType: string -> unit
 333
 334       (** @return Content-Encoding header value *)
 335     method contentEncoding: string
 336
 337       (** set Content-Encoding header value *)
 338     method setContentEncoding: string -> unit
 339
 340       (** @return Date header value *)
 341     method date: string
 342
 343       (** set Date header value *)
 344     method setDate: string -> unit
 345
 346       (** @return Expires header value *)
 347     method expires: string
 348
 349       (** set Expires header value *)
 350     method setExpires: string -> unit
 351
 352       (** @return Server header value *)
 353     method server: string
 354
 355       (** set Server header value *)
 356     method setServer: string -> unit
 357
 358   end
 359
 360   (** {2 OO representation of other HTTP "entities"} *)
 361
 362   (** an HTTP connection from a client to a server *)
 363 class type connection =
 364   object
 365       (** @return next request object, may block if client hasn't submitted any
 366       request yet, may be None if client request was ill-formed *)
 367     method getRequest: request option
 368
 369       (** respond to client sending it a response *)
 370     method respond_with: response -> unit
 371
 372       (** close connection to client. Warning: this object can't be used any
 373       longer after this method has been called *)
 374     method close: unit
 375   end
 376
 377   (** an HTTP daemon *)
 378 class type daemon =
 379   object
 380       (** @return a connection to a client, may block if no client has connected
 381       yet *)
 382     method accept: connection
 383
 384       (** shortcut method, blocks until a client has submit a request and
 385       return a pair request * connection *)
 386     method getRequest: request * connection
 387   end
 388