diff --git a/doc/ref/web.texi b/doc/ref/web.texi index 07da5b64b..c8fc488b7 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, 2013, 2015 Free Software Foundation, Inc. +@c Copyright (C) 2010, 2011, 2012, 2013, 2015, 2018 Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @node Web @@ -1463,24 +1463,18 @@ how to install the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}, for more information. @end deffn -@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... +@anchor{http-request}@deffn {Scheme Procedure} http-request @var{uri} @var{arg}@dots{} Connect to the server corresponding to @var{uri} and make a request over -HTTP, using the appropriate method (@code{GET}, @code{HEAD}, etc.). +HTTP, using @var{method} (@code{GET}, @code{HEAD}, @code{POST}, 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. +The following 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 #:method 'GET @item #:body #f @item #:port (open-socket-for-uri @var{uri})] @item #:version '(1 . 1) @@ -1518,6 +1512,25 @@ body as a string, bytevector, #f value, or as a port (if @var{streaming?} is true). @end deffn +@deffn {Scheme Procedure} http-get @var{uri} @var{arg}@dots{} +@deffnx {Scheme Procedure} http-head @var{uri} @var{arg}@dots{} +@deffnx {Scheme Procedure} http-post @var{uri} @var{arg}@dots{} +@deffnx {Scheme Procedure} http-put @var{uri} @var{arg}@dots{} +@deffnx {Scheme Procedure} http-delete @var{uri} @var{arg}@dots{} +@deffnx {Scheme Procedure} http-trace @var{uri} @var{arg}@dots{} +@deffnx {Scheme Procedure} http-options @var{uri} @var{arg}@dots{} +Connect to the server corresponding to @var{uri} and make a request over +HTTP, using the appropriate method (@code{GET}, @code{HEAD}, +@code{POST}, etc.). + +These procedures are variants of @code{http-request} specialized with a +specific @var{method} argument, and have the same prototype: a URI +followed by an optional sequence of keyword arguments. +@xref{http-request}, for full documentation on the various keyword +arguments. + +@end deffn + @code{http-get} is useful for making one-off requests to web sites. If you are writing a web spider or some other client that needs to handle a number of requests in parallel, it's better to build an event-driven URL diff --git a/module/web/client.scm b/module/web/client.scm index c13117dd2..75719e1d1 100644 --- a/module/web/client.scm +++ b/module/web/client.scm @@ -1,6 +1,6 @@ ;;; Web client -;; Copyright (C) 2011, 2012, 2013, 2014, 2015, 2016, 2017 Free Software Foundation, Inc. +;; Copyright (C) 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 Free Software Foundation, Inc. ;; This library is free software; you can redistribute it and/or ;; modify it under the terms of the GNU Lesser General Public @@ -47,6 +47,7 @@ #:prefix rnrs-ports:) #:export (current-http-proxy open-socket-for-uri + http-request http-get http-head http-post @@ -331,25 +332,50 @@ as is the case by default with a request returned by `build-request'." (else (error "unexpected body type" body)))) -;; We could expose this to user code if there is demand. -(define* (request uri #:key - (body #f) - (port (open-socket-for-uri uri)) - (method 'GET) - (version '(1 . 1)) - (keep-alive? #f) - (headers '()) - (decode-body? #t) - (streaming? #f) - (request - (build-request - (ensure-uri-reference uri) - #:method method - #:version version - #:headers (if keep-alive? - headers - (cons '(connection close) headers)) - #:port port))) +(define* (http-request uri #:key + (body #f) + (port (open-socket-for-uri uri)) + (method 'GET) + (version '(1 . 1)) + (keep-alive? #f) + (headers '()) + (decode-body? #t) + (streaming? #f) + (request + (build-request + (ensure-uri-reference uri) + #:method method + #:version version + #:headers (if keep-alive? + headers + (cons '(connection close) headers)) + #:port port))) + "Connect to the server corresponding to URI and ask for the resource, +using METHOD, defaulting to ‘GET’. If you already have a port open, +pass it as PORT. The port will be closed at the end of the request +unless KEEP-ALIVE? is true. Any extra headers in the alist HEADERS will +be added to the request. + +If BODY is not ‘#f’, a message body will also be sent with the HTTP +request. If BODY is a string, it is encoded according to the +content-type in HEADERS, defaulting to UTF-8. Otherwise BODY should be +a bytevector, or ‘#f’ for no body. Although it's allowed to send a +message body along with any request, usually only POST and PUT requests +have bodies. See ‘http-put’ and ‘http-post’ documentation, for more. + +If 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 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 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 STREAMING? is +true)." (call-with-values (lambda () (sanitize-request request body)) (lambda (request body) (let ((request (write-request request port))) @@ -376,42 +402,6 @@ as is the case by default with a request returned by `build-request'." (decode-response-body response body) body)))))))))) -(define* (http-get uri #:key - (body #f) - (port (open-socket-for-uri uri)) - (version '(1 . 1)) (keep-alive? #f) - (headers '()) (decode-body? #t) (streaming? #f)) - "Connect to the server corresponding to URI and ask for the -resource, using the ‘GET’ method. If you already have a port open, -pass it as PORT. The port will be closed at the end of the -request unless KEEP-ALIVE? is true. Any extra headers in the -alist HEADERS will be added to the request. - -If BODY is not ‘#f’, a message body will also be sent with the HTTP -request. If BODY is a string, it is encoded according to the -content-type in HEADERS, defaulting to UTF-8. Otherwise BODY should be -a bytevector, or ‘#f’ for no body. Although it's allowed to send a -message body along with any request, usually only POST and PUT requests -have bodies. See ‘http-put’ and ‘http-post’ documentation, for more. - -If 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 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 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 STREAMING? is -true)." - (request uri #:method 'GET #:body body - #:port port #:version version #:keep-alive? keep-alive? - #:headers headers #:decode-body? decode-body? - #:streaming? streaming?)) - (define-syntax-rule (define-http-verb http-verb method doc) (define* (http-verb uri #:key (body #f) @@ -422,20 +412,31 @@ true)." (decode-body? #t) (streaming? #f)) doc - (request uri - #:body body #:method method - #:port port #:version version #:keep-alive? keep-alive? - #:headers headers #:decode-body? decode-body? - #:streaming? streaming?))) + (http-request uri + #:body body #:method method + #:port port #:version version #:keep-alive? keep-alive? + #:headers headers #:decode-body? decode-body? + #:streaming? streaming?))) + +(define-http-verb http-get + 'GET + "Fetch message headers for the given URI using the HTTP \"GET\" +method. + +This function invokes ‘http-request’, with the \"GET\" method. See +‘http-request’ for full documentation on the various keyword arguments +that are accepted by this function. + +Returns two values: the resulting response, and the response body.") (define-http-verb http-head 'HEAD "Fetch message headers for the given URI using the HTTP \"HEAD\" method. -This function is similar to ‘http-get’, except it uses the \"HEAD\" -method. See ‘http-get’ for full documentation on the various keyword -arguments that are accepted by this function. +This function invokes ‘http-request’, with the \"HEAD\" method. See +‘http-request’ for full documentation on the various keyword arguments +that are accepted by this function. Returns two values: the resulting response, and ‘#f’. Responses to HEAD requests do not have a body. The second value is only returned so that @@ -445,9 +446,9 @@ other procedures can treat all of the http-foo verbs identically.") 'POST "Post data to the given URI using the HTTP \"POST\" method. -This function is similar to ‘http-get’, except it uses the \"POST\" -method. See ‘http-get’ for full documentation on the various keyword -arguments that are accepted by this function. +This function invokes ‘http-request’, with the \"POST\" method. See +‘http-request’ for full documentation on the various keyword arguments +that are accepted by this function. Returns two values: the resulting response, and the response body.") @@ -455,9 +456,9 @@ Returns two values: the resulting response, and the response body.") 'PUT "Put data at the given URI using the HTTP \"PUT\" method. -This function is similar to ‘http-get’, except it uses the \"PUT\" -method. See ‘http-get’ for full documentation on the various keyword -arguments that are accepted by this function. +This function invokes ‘http-request’, with the \"PUT\" method. See +‘http-request’ for full documentation on the various keyword arguments +that are accepted by this function. Returns two values: the resulting response, and the response body.") @@ -465,9 +466,9 @@ Returns two values: the resulting response, and the response body.") 'DELETE "Delete data at the given URI using the HTTP \"DELETE\" method. -This function is similar to ‘http-get’, except it uses the \"DELETE\" -method. See ‘http-get’ for full documentation on the various keyword -arguments that are accepted by this function. +This function invokes ‘http-request’, with the \"DELETE\" method. See +‘http-request’ for full documentation on the various keyword arguments +that are accepted by this function. Returns two values: the resulting response, and the response body.") @@ -475,9 +476,9 @@ Returns two values: the resulting response, and the response body.") 'TRACE "Send an HTTP \"TRACE\" request. -This function is similar to ‘http-get’, except it uses the \"TRACE\" -method. See ‘http-get’ for full documentation on the various keyword -arguments that are accepted by this function. +This function invokes ‘http-request’, with the \"TRACE\" method. See +‘http-request’ for full documentation on the various keyword arguments +that are accepted by this function. Returns two values: the resulting response, and the response body.") @@ -486,8 +487,8 @@ Returns two values: the resulting response, and the response body.") "Query characteristics of an HTTP resource using the HTTP \"OPTIONS\" method. -This function is similar to ‘http-get’, except it uses the \"OPTIONS\" -method. See ‘http-get’ for full documentation on the various keyword -arguments that are accepted by this function. +This function invokes ‘http-request’, with the \"OPTIONS\" method. See +‘http-request’ for full documentation on the various keyword arguments +that are accepted by this function. Returns two values: the resulting response, and the response body.")