bug#30154: [PATCH] web: Add http-patch.

bug#30154: [PATCH] web: Add http-patch.

[Arun Isaac]

* module/web/client.scm (http-patch): New HTTP verb.
* doc/ref/web.texi (Web Client): Document it.
---
 doc/ref/web.texi      |  1 +
 module/web/client.scm | 12 ++++++++++++
 2 files changed, 13 insertions(+)

diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index 07da5b64b..7f119ba99 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -1467,6 +1467,7 @@ GnuTLS-Guile}, for more information.
 @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-patch uri arg...
 @deffnx {Scheme Procedure} http-delete uri arg...
 @deffnx {Scheme Procedure} http-trace uri arg...
 @deffnx {Scheme Procedure} http-options uri arg...
diff --git a/module/web/client.scm b/module/web/client.scm
index c13117dd2..24278d772 100644
--- a/module/web/client.scm
+++ b/module/web/client.scm
@@ -51,6 +51,7 @@
             http-head
             http-post
             http-put
+            http-patch
             http-delete
             http-trace
             http-options))
@@ -461,6 +462,17 @@ arguments that are accepted by this function.
 
 Returns two values: the resulting response, and the response body.")
 
+(define-http-verb http-patch
+  'PATCH
+  "Make partial changes to the resource at the given URI using the HTTP
+\"PATCH\" method.
+
+This function is similar to ‘http-get’, except it uses the \"PATCH\"
+method.  See ‘http-get’ 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-delete
   'DELETE
   "Delete data at the given URI using the HTTP \"DELETE\" method.
-- 
2.15.1

bug#30154: [PATCH] web: Add http-patch.

[Mark H Weaver]

Hi Arun,

Arun Isaac <arunisaac@systemreboot.net> writes:
> * module/web/client.scm (http-patch): New HTTP verb.

I hadn't heard of the PATCH method in HTTP, so I looked into it a bit.
It's not listed as a valid method verb in either RFC 7231 (from 2014) or
RFC 2616 (from 1999).  However, I do see it mentioned briefly in the
"Changes from RFC 2068" section of RFC 2616, which states:

   The PATCH, LINK, UNLINK methods were defined but not commonly
   implemented in previous versions of this specification. See RFC 2068.

Since PATCH was removed from HTTP over 18 years ago, and is clearly not
valid HTTP/1.1, I wonder if it makes sense to add this.  Do you have a
use case where you need it?

      Mark

bug#30154: [PATCH] web: Add http-patch.

[Arun Isaac]

Mark H Weaver <mhw@netris.org> writes:

> Since PATCH was removed from HTTP over 18 years ago, and is clearly not
> valid HTTP/1.1, I wonder if it makes sense to add this.

> Do you have a use case where you need it?

Yes, I was using the PowerDNS HTTP API, and some of their API requests
need the PATCH method.

https://doc.powerdns.com/md/httpapi/api_spec/

If you think it's not a good idea to include http-patch in guile, maybe
we can export define-http-verb and/or request so that it is easy for
users to create their own custom HTTP methods. WDYT?

bug#30154: [PATCH] web: Add http-patch.

[Mark H Weaver]

Arun Isaac <arunisaac@systemreboot.net> writes:

> Mark H Weaver <mhw@netris.org> writes:
>
>> Since PATCH was removed from HTTP over 18 years ago, and is clearly not
>> valid HTTP/1.1, I wonder if it makes sense to add this.
>
>> Do you have a use case where you need it?
>
> Yes, I was using the PowerDNS HTTP API, and some of their API requests
> need the PATCH method.
>
> https://doc.powerdns.com/md/httpapi/api_spec/
>
> If you think it's not a good idea to include http-patch in guile, maybe
> we can export define-http-verb and/or request so that it is easy for
> users to create their own custom HTTP methods. WDYT?

I would prefer to export the 'request' procedure from (web client),
although it should probably be exported as a different name, maybe
'http-request'.  Would that work for you?

       Mark

bug#30154: [PATCH] web: Add http-patch.

[Arun Isaac]

Mark H Weaver <mhw@netris.org> writes:

>> If you think it's not a good idea to include http-patch in guile, maybe
>> we can export define-http-verb and/or request so that it is easy for
>> users to create their own custom HTTP methods. WDYT?
>
> I would prefer to export the 'request' procedure from (web client),
> although it should probably be exported as a different name, maybe
> 'http-request'.  Would that work for you?

Yes, exporting 'request' alone would serve my purpose, although
'define-http-verb' would make my script much shorter. But, I'll leave it
to your judgement. Should I send a new patch exporting 'request' alone?

I have also submitted one more patch
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=30076 related to the web
client, and required for the same PowerDNS API client that I am working
on. It's a very simple patch. And, it would be nice if you could review
it as well.

Thanks.

bug#30154: [PATCH] web: Add http-patch.

[Ludovic Courtès]

Hello,

Arun Isaac <arunisaac@systemreboot.net> skribis:

> Mark H Weaver <mhw@netris.org> writes:
>
>>> If you think it's not a good idea to include http-patch in guile, maybe
>>> we can export define-http-verb and/or request so that it is easy for
>>> users to create their own custom HTTP methods. WDYT?
>>
>> I would prefer to export the 'request' procedure from (web client),
>> although it should probably be exported as a different name, maybe
>> 'http-request'.  Would that work for you?
>
> Yes, exporting 'request' alone would serve my purpose, although
> 'define-http-verb' would make my script much shorter. But, I'll leave it
> to your judgement. Should I send a new patch exporting 'request' alone?

Could you do that?  The ‘request’ procedure can simply be made public
and otherwise left unchanged, but we’d need a docstring and an entry in
the manual.  Can you take a look?

I’ll happily apply the patch afterwards, and I promise you won’t have to
wait as much as you did so far!  :-)

Thanks,
Ludo’.

bug#30154: [PATCH] web: Add http-patch.

[Arun Isaac]

>> Yes, exporting 'request' alone would serve my purpose, although
>> 'define-http-verb' would make my script much shorter. But, I'll leave it
>> to your judgement. Should I send a new patch exporting 'request' alone?
>
> Could you do that?  The ‘request’ procedure can simply be made public
> and otherwise left unchanged, but we’d need a docstring and an entry in
> the manual.  Can you take a look?

Yes, I'll send you a patch within a few days.

> I’ll happily apply the patch afterwards, and I promise you won’t have to
> wait as much as you did so far!  :-)

I am generally quite patient with patch review, but yes, this one did
take too long. :-)

bug#30154: [PATCH] web: Export http-request.

[Arun Isaac]

* 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.
---
 doc/ref/web.texi      |  40 ++++++++-----
 module/web/client.scm | 157 +++++++++++++++++++++++++-------------------------
 2 files changed, 106 insertions(+), 91 deletions(-)

diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index 07da5b64b..329912d33 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -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 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.).
+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,26 @@ body as a string, bytevector, #f value, or as a port (if
 @var{streaming?} is true).
 @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...
+
+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.  See
+@ref{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..102e2b724 100644
--- a/module/web/client.scm
+++ b/module/web/client.scm
@@ -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.")
-- 
2.15.1

bug#30154: [PATCH] web: Export http-request.

[Ludovic Courtès]

[-- Attachment #1: Type: text/plain, Size: 406 bytes --]

Hello Arun,

Arun Isaac <arunisaac@systemreboot.net> skribis:

> * 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.

Awesome!  Applied with the tiny changes below.

Thank you,
Ludo’.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 2391 bytes --]

diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index e99907fe3..62b25d889 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
@@ -1467,7 +1467,7 @@ how to install the GnuTLS bindings for Guile,, gnutls-guile,
 GnuTLS-Guile}, for more information.
 @end deffn
 
-@anchor{http-request}@deffn {Scheme Procedure} http-request 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 @var{method} (@code{GET}, @code{HEAD}, @code{POST}, etc.).
@@ -1516,22 +1516,21 @@ body as a string, bytevector, #f value, or as a port (if
 @var{streaming?} is true).
 @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...
-
+@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.  See
-@ref{http-request} for full documentation on the various keyword
+followed by an optional sequence of keyword arguments.
+@xref{http-request}, for full documentation on the various keyword
 arguments.
 
 @end deffn