[Guile-commits] 35/58: web: Export http-request.

[Andy Wingo]

wingo pushed a commit to branch lightning
in repository guile.

commit e40b5b54ff996e098ca16a8125c0e325b7de8558
Author: Arun Isaac <address@hidden>
Date:   Thu Jun 21 22:57:18 2018 +0530

    web: Export http-request.
    
    * module/web/client.scm (request): Rename to http-request, add a
    docstring, and export it.
    (http-get, http-head, http-post, http-put, http-delete, http-trace,
    http-options): Update docstring.
    * doc/ref/web.texi (Web Client): Document http-request.
    
    Signed-off-by: Ludovic Courtès <address@hidden>
---
 doc/ref/web.texi      |  41 ++++++++-----
 module/web/client.scm | 159 +++++++++++++++++++++++++-------------------------
 2 files changed, 107 insertions(+), 93 deletions(-)

diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index 07da5b6..c8fc488 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.
address@hidden Copyright (C) 2010, 2011, 2012, 2013, 2015 Free Software 
Foundation, Inc.
address@hidden 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
 
address@hidden {Scheme Procedure} http-get uri arg...
address@hidden {Scheme Procedure} http-head uri arg...
address@hidden {Scheme Procedure} http-post uri arg...
address@hidden {Scheme Procedure} http-put uri arg...
address@hidden {Scheme Procedure} http-delete uri arg...
address@hidden {Scheme Procedure} http-trace uri arg...
address@hidden {Scheme Procedure} http-options uri arg...
address@hidden@deffn {Scheme Procedure} http-request @var{uri} @address@hidden
 
 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
address@hidden #: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
 
address@hidden {Scheme Procedure} http-get @var{uri} @address@hidden
address@hidden {Scheme Procedure} http-head @var{uri} @address@hidden
address@hidden {Scheme Procedure} http-post @var{uri} @address@hidden
address@hidden {Scheme Procedure} http-put @var{uri} @address@hidden
address@hidden {Scheme Procedure} http-delete @var{uri} @address@hidden
address@hidden {Scheme Procedure} http-trace @var{uri} @address@hidden
address@hidden {Scheme Procedure} http-options @var{uri} @address@hidden
+Connect to the server corresponding to @var{uri} and make a request over
+HTTP, using the appropriate method (@code{GET}, @code{HEAD},
address@hidden, 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.
address@hidden, for full documentation on the various keyword
+arguments.
+
address@hidden 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 c13117d..75719e1 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.")