X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/32299e49e83b941082bee348c993630bb455a324..990b11c53f8da2a6c14e1190bc4e76939db32d07:/doc/ref/web.texi diff --git a/doc/ref/web.texi b/doc/ref/web.texi index 161a28d59..0f69089d0 100644 --- a/doc/ref/web.texi +++ b/doc/ref/web.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 2010, 2011, 2012 Free Software Foundation, Inc. +@c Copyright (C) 2010, 2011, 2012, 2013 Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @node Web @@ -209,10 +209,11 @@ access to them. @deffn {Scheme Procedure} build-uri scheme [#:userinfo=@code{#f}] [#:host=@code{#f}] @ [#:port=@code{#f}] [#:path=@code{""}] [#:query=@code{#f}] @ [#:fragment=@code{#f}] [#:validate?=@code{#t}] -Construct a URI object. @var{scheme} should be a symbol, and the rest -of the fields are either strings or @code{#f}. If @var{validate?} is -true, also run some consistency checks to make sure that the constructed -URI is valid. +Construct a URI object. @var{scheme} should be a symbol, @var{port} +either a positive, exact integer or @code{#f}, and the rest of the +fields are either strings or @code{#f}. If @var{validate?} is true, +also run some consistency checks to make sure that the constructed URI +is valid. @end deffn @deffn {Scheme Procedure} uri? x @@ -224,8 +225,8 @@ URI is valid. @deffnx {Scheme Procedure} uri-query uri @deffnx {Scheme Procedure} uri-fragment uri A predicate and field accessors for the URI record type. The URI scheme -will be a symbol, and the rest either strings or @code{#f} if not -present. +will be a symbol, the port either a positive, exact integer or @code{#f}, +and the rest either strings or @code{#f} if not present. @end deffn @deffn {Scheme Procedure} string->uri string @@ -431,8 +432,8 @@ from @code{header-writer}. @end deffn @deffn {Scheme Procedure} read-headers port -Read the headers of an HTTP message from @var{port}, returning the -headers as an ordered alist. +Read the headers of an HTTP message from @var{port}, returning them +as an ordered alist. @end deffn @deffn {Scheme Procedure} write-headers headers port @@ -1314,6 +1315,16 @@ Note also, though, that responses to @code{HEAD} requests must also not have a body. @end deffn +@deffn {Scheme Procedure} response-body-port r [#:decode?=#t] [#:keep-alive?=#t] +Return an input port from which the body of @var{r} can be read. The encoding +of the returned port is set according to @var{r}'s @code{content-type} header, +when it's textual, except if @var{decode?} is @code{#f}. Return @code{#f} +when no body is available. + +When @var{keep-alive?} is @code{#f}, closing the returned port also closes +@var{r}'s response port. +@end deffn + @deffn {Scheme Procedure} read-response-body r Read the response body from @var{r}, as a bytevector. Returns @code{#f} if there was no response body. @@ -1360,6 +1371,12 @@ headers. Return the given response header, or @var{default} if none was present. @end deffn +@deffn {Scheme Procedure} text-content-type? @var{type} +Return @code{#t} if @var{type}, a symbol as returned by +@code{response-content-type}, represents a textual type such as +@code{text/plain}. +@end deffn + @node Web Client @subsection Web Client @@ -1368,18 +1385,62 @@ Return the given response header, or @var{default} if none was present. the lower-level HTTP, request, and response modules. @deffn {Scheme Procedure} open-socket-for-uri uri +Return an open input/output port for a connection to URI. @end deffn -@deffn {Scheme Procedure} http-get uri [#:port=(open-socket-for-uri uri)] [#:version='(1 . 1)] [#:keep-alive?=#f] [#:extra-headers='()] [#:decode-body?=#t] -Connect to the server corresponding to @var{uri} and ask for the -resource, using the @code{GET} method. If you already have a port open, -pass it as @var{port}. The port will be closed at the end of the -request unless @var{keep-alive?} is true. Any extra headers in the -alist @var{extra-headers} will be added to the request. +@deffn {Scheme Procedure} http-get uri arg... +@deffnx {Scheme Procedure} http-head uri arg... +@deffnx {Scheme Procedure} http-post uri arg... +@deffnx {Scheme Procedure} http-put uri arg... +@deffnx {Scheme Procedure} http-delete uri arg... +@deffnx {Scheme Procedure} http-trace uri arg... +@deffnx {Scheme Procedure} http-options uri arg... + +Connect to the server corresponding to @var{uri} and make a request over +HTTP, using the appropriate method (@code{GET}, @code{HEAD}, etc.). + +All of these procedures have the same prototype: a URI followed by an +optional sequence of keyword arguments. These keyword arguments allow +you to modify the requests in various ways, for example attaching a body +to the request, or setting specific headers. The following table lists +the keyword arguments and their default values. + +@table @code +@item #:body #f +@item #:port (open-socket-for-uri @var{uri})] +@item #:version '(1 . 1) +@item #:keep-alive? #f +@item #:headers '() +@item #:decode-body? #t +@item #:streaming? #f +@end table + +If you already have a port open, pass it as @var{port}. Otherwise, a +connection will be opened to the server corresponding to @var{uri}. Any +extra headers in the alist @var{headers} will be added to the request. + +If @var{body} is not #f, a message body will also be sent with the HTTP +request. If @var{body} is a string, it is encoded according to the +content-type in @var{headers}, defaulting to UTF-8. Otherwise +@var{body} should be a bytevector, or @code{#f} for no body. Although a +message body may be sent with any request, usually only @code{POST} and +@code{PUT} requests have bodies. If @var{decode-body?} is true, as is the default, the body of the response will be decoded to string, if it is a textual content-type. Otherwise it will be returned as a bytevector. + +However, if @var{streaming?} is true, instead of eagerly reading the +response body from the server, this function only reads off the headers. +The response body will be returned as a port on which the data may be +read. + +Unless @var{keep-alive?} is true, the port will be closed after the full +response body has been read. + +Returns two values: the response read from the server, and the response +body as a string, bytevector, #f value, or as a port (if +@var{streaming?} is true). @end deffn @code{http-get} is useful for making one-off requests to web sites. If @@ -1390,10 +1451,6 @@ fetcher, similar in structure to the web server (@pxref{Web Server}). Another option, good but not as performant, would be to use threads, possibly via par-map or futures. -More helper procedures for the other common HTTP verbs would be a good -addition to this module. Send your code to -@email{guile-user@@gnu.org}. - @node Web Server @subsection Web Server @@ -1470,17 +1527,17 @@ the server socket. A user may define a server implementation with the following form: -@deffn {Scheme Procedure} define-server-impl name open read write close +@deffn {Scheme Syntax} define-server-impl name open read write close Make a @code{} object with the hooks @var{open}, @var{read}, @var{write}, and @var{close}, and bind it to the symbol @var{name} in the current module. @end deffn @deffn {Scheme Procedure} lookup-server-impl impl -Look up a server implementation. If @var{impl} is a server -implementation already, it is returned directly. If it is a symbol, the +Look up a server implementation. If @var{impl} is a server +implementation already, it is returned directly. If it is a symbol, the binding named @var{impl} in the @code{(web server @var{impl})} module is -looked up. Otherwise an error is signaled. +looked up. Otherwise an error is signaled. Currently a server implementation is a somewhat opaque type, useful only for passing to other procedures in this module, like @code{read-client}. @@ -1494,7 +1551,7 @@ any access to the impl objects. @deffn {Scheme Procedure} open-server impl open-params Open a server for the given implementation. Return one value, the new -server object. The implementation's @code{open} procedure is applied to +server object. The implementation's @code{open} procedure is applied to @var{open-params}, which should be a list. @end deffn @@ -1502,7 +1559,7 @@ server object. The implementation's @code{open} procedure is applied to Read a new client from @var{server}, by applying the implementation's @code{read} procedure to the server. If successful, return three values: an object corresponding to the client, a request object, and the -request body. If any exception occurs, return @code{#f} for all three +request body. If any exception occurs, return @code{#f} for all three values. @end deffn @@ -1513,9 +1570,9 @@ The response and response body are produced by calling the given @var{handler} with @var{request} and @var{body} as arguments. The elements of @var{state} are also passed to @var{handler} as -arguments, and may be returned as additional values. The new +arguments, and may be returned as additional values. The new @var{state}, collected from the @var{handler}'s return values, is then -returned as a list. The idea is that a server loop receives a handler +returned as a list. The idea is that a server loop receives a handler from the user, along with whatever state values the user is interested in, allowing the user's handler to explicitly manage its state. @end deffn @@ -1526,20 +1583,20 @@ given request. As a convenience to web handler authors, @var{response} may be given as an alist of headers, in which case it is used to construct a default -response. Ensures that the response version corresponds to the request -version. If @var{body} is a string, encodes the string to a bytevector, -in an encoding appropriate for @var{response}. Adds a +response. Ensures that the response version corresponds to the request +version. If @var{body} is a string, encodes the string to a bytevector, +in an encoding appropriate for @var{response}. Adds a @code{content-length} and @code{content-type} header, as necessary. If @var{body} is a procedure, it is called with a port as an argument, -and the output collected as a bytevector. In the future we might try to +and the output collected as a bytevector. In the future we might try to instead use a compressing, chunk-encoded port, and call this procedure -later, in the write-client procedure. Authors are advised not to rely on +later, in the write-client procedure. Authors are advised not to rely on the procedure being called at any particular time. @end deffn @deffn {Scheme Procedure} write-client impl server client response body -Write an HTTP response and body to @var{client}. If the server and +Write an HTTP response and body to @var{client}. If the server and client support persistent connections, it is the implementation's responsibility to keep track of the client thereafter, presumably by attaching it to the @var{server} argument somehow. @@ -1572,7 +1629,7 @@ before sending back to the client. Additional arguments to @var{handler} are taken from @var{state}. Additional return values are accumulated into a new @var{state}, which -will be used for subsequent requests. In this way a handler can +will be used for subsequent requests. In this way a handler can explicitly manage its state. @end deffn