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