mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 03:40:34 +02:00
Code Activity

web: Export http-request.

Browse source 
* 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 <ludo@gnu.org>
This commit is contained in:
Arun Isaac 2018-06-21 22:57:18 +05:30 • committed by Andy Wingo
parent 25c719b412
commit e40b5b54ff
2 changed files with 107 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

41
doc/ref/web.texi
View file

@ -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

117
module/web/client.scm
View file

@ -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,8 +332,7 @@ 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
(define* (http-request uri #:key
(body #f)
(port (open-socket-for-uri uri))
(method 'GET)
@ -350,6 +350,32 @@ as is the case by default with a request returned by `build-request'."
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
(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.")