mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 20:00:19 +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 -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual. @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. @c See the file guile.texi for copying conditions.
@node Web @node Web
@ -1463,24 +1463,18 @@ how to install the GnuTLS bindings for Guile,, gnutls-guile,
GnuTLS-Guile}, for more information. GnuTLS-Guile}, for more information.
@end deffn @end deffn
@deffn {Scheme Procedure} http-get uri arg... @anchor{http-request}@deffn {Scheme Procedure} http-request @var{uri} @var{arg}@dots{}
@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 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 The following keyword arguments allow you to modify the requests in
optional sequence of keyword arguments. These keyword arguments allow various ways, for example attaching a body to the request, or setting
you to modify the requests in various ways, for example attaching a body specific headers. The following table lists the keyword arguments and
to the request, or setting specific headers. The following table lists their default values.
the keyword arguments and their default values.
@table @code @table @code
@item #:method 'GET
@item #:body #f @item #:body #f
@item #:port (open-socket-for-uri @var{uri})] @item #:port (open-socket-for-uri @var{uri})]
@item #:version '(1 . 1) @item #:version '(1 . 1)
@ -1518,6 +1512,25 @@ body as a string, bytevector, #f value, or as a port (if
@var{streaming?} is true). @var{streaming?} is true).
@end deffn @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 @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 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 number of requests in parallel, it's better to build an event-driven URL

159
module/web/client.scm
View file

@ -1,6 +1,6 @@
;;; Web client ;;; 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 ;; This library is free software; you can redistribute it and/or
;; modify it under the terms of the GNU Lesser General Public ;; modify it under the terms of the GNU Lesser General Public
@ -47,6 +47,7 @@
#:prefix rnrs-ports:) #:prefix rnrs-ports:)
#:export (current-http-proxy #:export (current-http-proxy
open-socket-for-uri open-socket-for-uri
http-request
http-get http-get
http-head http-head
http-post http-post
@ -331,25 +332,50 @@ as is the case by default with a request returned by `build-request'."
(else (else
(error "unexpected body type" body)))) (error "unexpected body type" body))))
;; We could expose this to user code if there is demand. (define* (http-request uri #:key
(define* (request uri #:key (body #f)
(body #f) (port (open-socket-for-uri uri))
(port (open-socket-for-uri uri)) (method 'GET)
(method 'GET) (version '(1 . 1))
(version '(1 . 1)) (keep-alive? #f)
(keep-alive? #f) (headers '())
(headers '()) (decode-body? #t)
(decode-body? #t) (streaming? #f)
(streaming? #f) (request
(request (build-request
(build-request (ensure-uri-reference uri)
(ensure-uri-reference uri) #:method method
#:method method #:version version
#:version version #:headers (if keep-alive?
#:headers (if keep-alive? headers
headers (cons '(connection close) headers))
(cons '(connection close) headers)) #:port port)))
#: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)) (call-with-values (lambda () (sanitize-request request body))
(lambda (request body) (lambda (request body)
(let ((request (write-request request port))) (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) (decode-response-body response body)
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-syntax-rule (define-http-verb http-verb method doc)
(define* (http-verb uri #:key (define* (http-verb uri #:key
(body #f) (body #f)
@ -422,20 +412,31 @@ true)."
(decode-body? #t) (decode-body? #t)
(streaming? #f)) (streaming? #f))
doc doc
(request uri (http-request uri
#:body body #:method method #:body body #:method method
#:port port #:version version #:keep-alive? keep-alive? #:port port #:version version #:keep-alive? keep-alive?
#:headers headers #:decode-body? decode-body? #:headers headers #:decode-body? decode-body?
#:streaming? streaming?))) #: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 (define-http-verb http-head
'HEAD 'HEAD
"Fetch message headers for the given URI using the HTTP \"HEAD\" "Fetch message headers for the given URI using the HTTP \"HEAD\"
method. method.
This function is similar to ‘http-get’, except it uses the \"HEAD\" This function invokes ‘http-request’, with the \"HEAD\" method. See
method. See ‘http-get’ for full documentation on the various keyword ‘http-request’ for full documentation on the various keyword arguments
arguments that are accepted by this function. that are accepted by this function.
Returns two values: the resulting response, and ‘#f’. Responses to HEAD 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 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
"Post data to the given URI using the HTTP \"POST\" method. "Post data to the given URI using the HTTP \"POST\" method.
This function is similar to ‘http-get’, except it uses the \"POST\" This function invokes ‘http-request’, with the \"POST\" method. See
method. See ‘http-get’ for full documentation on the various keyword ‘http-request’ for full documentation on the various keyword arguments
arguments that are accepted by this function. that are accepted by this function.
Returns two values: the resulting response, and the response body.") 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
"Put data at the given URI using the HTTP \"PUT\" method. "Put data at the given URI using the HTTP \"PUT\" method.
This function is similar to ‘http-get’, except it uses the \"PUT\" This function invokes ‘http-request’, with the \"PUT\" method. See
method. See ‘http-get’ for full documentation on the various keyword ‘http-request’ for full documentation on the various keyword arguments
arguments that are accepted by this function. that are accepted by this function.
Returns two values: the resulting response, and the response body.") 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
"Delete data at the given URI using the HTTP \"DELETE\" method. "Delete data at the given URI using the HTTP \"DELETE\" method.
This function is similar to ‘http-get’, except it uses the \"DELETE\" This function invokes ‘http-request’, with the \"DELETE\" method. See
method. See ‘http-get’ for full documentation on the various keyword ‘http-request’ for full documentation on the various keyword arguments
arguments that are accepted by this function. that are accepted by this function.
Returns two values: the resulting response, and the response body.") 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 'TRACE
"Send an HTTP \"TRACE\" request. "Send an HTTP \"TRACE\" request.
This function is similar to ‘http-get’, except it uses the \"TRACE\" This function invokes ‘http-request’, with the \"TRACE\" method. See
method. See ‘http-get’ for full documentation on the various keyword ‘http-request’ for full documentation on the various keyword arguments
arguments that are accepted by this function. that are accepted by this function.
Returns two values: the resulting response, and the response body.") 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\" "Query characteristics of an HTTP resource using the HTTP \"OPTIONS\"
method. method.
This function is similar to ‘http-get’, except it uses the \"OPTIONS\" This function invokes ‘http-request’, with the \"OPTIONS\" method. See
method. See ‘http-get’ for full documentation on the various keyword ‘http-request’ for full documentation on the various keyword arguments
arguments that are accepted by this function. that are accepted by this function.
Returns two values: the resulting response, and the response body.") Returns two values: the resulting response, and the response body.")