Requests and responses as maps, and the functions that send them.
The client is java.net.http on the JVM, node:http in Node and fetch in a browser. A request moves no more bytes than its purpose needs.
Requests and responses as maps, and the functions that send them. The client is java.net.http on the JVM, node:http in Node and fetch in a browser. A request moves no more bytes than its purpose needs.
(authorization credentials)The Authorization header for credentials, or nil for no credentials.
The credentials are a map, or a function of no arguments that gives
one. The map has :username and :password for basic authentication, or
:token for a bearer token. The password and the token can be hidden
texts, so that a map of credentials doesn't show them when it's
printed.
The header has the password or the token, so it's a hidden text too, and a request map with it doesn't show it when printed.
The Authorization header for `credentials`, or nil for no credentials. The `credentials` are a map, or a function of no arguments that gives one. The map has :username and :password for basic authentication, or :token for a bearer token. The password and the token can be hidden texts, so that a map of credentials doesn't show them when it's printed. The header has the password or the token, so it's a hidden text too, and a request map with it doesn't show it when printed.
(digest! url algorithms)(digest! url
algorithms
{:keys [headers timeout-seconds allow-pred]
:or {timeout-seconds 600}
:as opts})GET url with opts, and give the digests of its body by the
MessageDigest algorithms, e.g. SHA-384.
The result has the :status and the :url. For a 200, it also has the :digests, which map each algorithm to the bytes of its digest. The body streams through the digests, and none of it is kept, so it can be a large media file.
The opts are these:
GET `url` with `opts`, and give the digests of its body by the MessageDigest `algorithms`, e.g. SHA-384. The result has the :status and the :url. For a 200, it also has the :digests, which map each algorithm to the bytes of its digest. The body streams through the digests, and none of it is kept, so it can be a large media file. The `opts` are these: - :headers of the request - :allow-pred and :user-agent, as send! takes them, but with url/public? as the :allow-pred by default - :timeout-seconds, the limit of the whole exchange, 600 by default
(facts response)What the response tells about its file, as far as it tells it.
The facts have these keys:
What the `response` tells about its file, as far as it tells it. The facts have these keys: - :status, :url and :permanent-url, as in the response - :redirects, each a map of :status, :url and :cors, with the URL that answered with it - :location, the Location of a redirect that wasn't followed - :type, the media type, in lower case and without its parameters - :length, what Content-Length gives - :range, the Content-Range, as a map of :start, :end and :total - :encoding, :etag and :last-modified, from their headers - :cors, the origins that Access-Control-Allow-Origin allows to read the answer, with all its values joined, as a browser joins them - :filtered?, as in the response
(failure e)The exception e of a request that failed, as data: its :reason, and
the :type, :url and :status that it holds. The reason of a typed
exception is its own message, written for a person, and else it has the
messages of the causes.
The exception `e` of a request that failed, as data: its :reason, and the :type, :url and :status that it holds. The reason of a typed exception is its own message, written for a person, and else it has the messages of the causes.
(fetch! url)(fetch! url {:keys [send] :or {send send!} :as opts})GET the document at url with opts and give the response with the
body as text (or in ClojureScript a promise of it).
The response also has :etag and :last-modified when the server gives them. It has :not-before when the server says how long to wait.
The opts are these:
GET the document at `url` with `opts` and give the response with the body as text (or in ClojureScript a promise of it). The response also has :etag and :last-modified when the server gives them. It has :not-before when the server says how long to wait. The `opts` are these: - :etag and :last-modified from an earlier response. They go as If-None-Match and If-Modified-Since, and a 304 then comes back with no body. - :credentials, as authorization takes them - :accept, the Accept header, */* by default - :timeout-seconds, :max-bytes, :max-redirects, :allow-pred and :user-agent, as send! takes them, but with url/public? as the :allow-pred by default - :max-wait-seconds, as headers/not-before takes it - :send, the function that sends the request, send! by default
(fetch-request url)(fetch-request
url
{:keys [etag last-modified credentials accept] :or {accept "*/*"} :as opts})The request for the document at url with opts, the options of
fetch!.
A user name and a password in url are the credentials when opts
give none, and the request goes to the URL without them. The request
goes only to the public internet unless opts give an :allow-pred.
The request for the document at `url` with `opts`, the options of fetch!. A user name and a password in `url` are the credentials when `opts` give none, and the request goes to the URL without them. The request goes only to the public internet unless `opts` give an :allow-pred.
(fetcher url)(fetcher url {:keys [headers send] :or {send send!} :as opts})A function that fetches the bytes of the file at url by range with
opts.
The function takes a start and an end (excluded) and gives a map of :bytes, :start and :total (or in ClojureScript a promise of it). The total is the size of the file when the answer tells it. A server that ignores ranges sends the file from its start, and the map is then :whole?. A range past the end of the file gives no bytes. An answer that's a failure throws ::failed with the :status.
The opts are these:
A function that fetches the bytes of the file at `url` by range with `opts`. The function takes a start and an end (excluded) and gives a map of :bytes, :start and :total (or in ClojureScript a promise of it). The total is the size of the file when the answer tells it. A server that ignores ranges sends the file from its start, and the map is then :whole?. A range past the end of the file gives no bytes. An answer that's a failure throws ::failed with the :status. The `opts` are these: - :headers of the requests - :timeout-seconds, :max-bytes, :max-redirects, :allow-pred and :user-agent, as send! takes them, but with url/public? as the :allow-pred by default - :send, the function that sends each request, send! by default
(form-request url fields)(form-request url fields {:keys [headers] :as opts})The request that posts the form fields to url, with the opts
below, e.g. to an OAuth token endpoint.
The fields are a map or pairs of names and values, as
url/query-string takes them. The body is a hidden text, since a form
often holds a secret such as an OAuth code. The opts are the :headers
to add, and the options of send!, as with-options takes them, e.g.
:max-redirects 0 to keep a form from following a redirect.
The request that posts the form `fields` to `url`, with the `opts` below, e.g. to an OAuth token endpoint. The `fields` are a map or pairs of names and values, as url/query-string takes them. The body is a hidden text, since a form often holds a secret such as an OAuth code. The `opts` are the :headers to add, and the options of send!, as with-options takes them, e.g. :max-redirects 0 to keep a form from following a redirect.
(json-request url x)(json-request url x {:keys [headers] :as opts})The request that posts the value x to url as JSON, written by
json/write-json, with the opts of form-request.
The request that posts the value `x` to `url` as JSON, written by json/write-json, with the `opts` of form-request.
(probe! url)(probe! url {:keys [headers send] :or {send send!} :as opts})Ask the server about the file at url with opts and give the facts
(or in ClojureScript a promise of them). No more than two bytes of the
file move.
The result is a map of :head and :get with the facts of a HEAD request and of a request for the first two bytes. The facts of a request that failed are its exception under :error, as failure gives it.
The opts are these:
Ask the server about the file at `url` with `opts` and give the facts (or in ClojureScript a promise of them). No more than two bytes of the file move. The result is a map of :head and :get with the facts of a HEAD request and of a request for the first two bytes. The facts of a request that failed are its exception under :error, as failure gives it. The `opts` are these: - :headers of both requests, e.g. an Origin to learn about CORS - :timeout-seconds, :max-bytes, :max-redirects, :allow-pred and :user-agent, as send! takes them, but with url/public? as the :allow-pred by default - :send, the function that sends each request, send! by default
(revealed {:keys [headers] :as request})The request with the text of each hidden header and of a hidden body,
as the server needs them.
The headers Authorization and Cookie are hidden, and so is the body of a request with a secret. Another client needs their texts, and a request that's revealed shows its credentials when it's printed.
The `request` with the text of each hidden header and of a hidden body, as the server needs them. The headers Authorization and Cookie are hidden, and so is the body of a request with a secret. Another client needs their texts, and a request that's revealed shows its credentials when it's printed.
(send! {:keys [method headers timeout-seconds allow-pred as]
:or {timeout-seconds 30 allow-pred (constantly true)}
:as request})Send the request and give the response (or in ClojureScript a promise
of it).
The request is a map of :method, :url, :headers and :body. It's a GET unless :method names another, and its headers and body can be hidden texts. It can also have these keys:
The response is a map of :status, the final :url, :headers and :body. The body has gzip undone and text decoded by its charset. A 206 also has the :content-range as a map of :start, :end and :total. In a browser, :filtered? marks a response whose headers CORS hides. With a :sink, a response of status 200 to 299 has no :body but the number of bytes that the sink :received, within the same limits.
Outside a browser it follows the redirects itself and asks :allow-pred about each. It never follows one from https to http, and credentials stay behind when a redirect leaves the origin. The response then lists the :redirects and has a :permanent-url if the first ones were permanent. A browser follows its own, unless :max-redirects is 0, which gives a redirect as a response with the status 0.
It throws ::timeout or ::too-large past a limit and ::refused when :allow-pred refuses a URL. A request that reaches no server throws ::unresolved when the name of the host doesn't resolve, ::unreachable when the host can't be reached and ::tls when the secure connection fails, e.g. over an expired certificate. A browser tells none of these apart, but gives ::unreachable when it knows that the device is offline.
Send the `request` and give the response (or in ClojureScript a promise of it). The request is a map of :method, :url, :headers and :body. It's a GET unless :method names another, and its headers and body can be hidden texts. It can also have these keys: - :as :bytes, for a body of bytes rather than text, or :as :json, for the value of a JSON body as json/read-json reads it, nil when it isn't JSON - :timeout-seconds, the limit of the whole exchange (30 by default) - :max-bytes, the limit of the body (100 MB by default or nil for none) - :truncate?, true to cut a body that's larger than :max-bytes rather than throw, e.g. to read the start of a large page, and the response then has :truncated? - :range, the first and the last byte to ask for (a nil last byte asks for the rest) - :allow-pred, a predicate of each URL, e.g. url/public? - :user-agent, the User-Agent outside a browser unless the :headers name one - :max-redirects, how many redirects to follow (5 by default, and 0 for none) - :sink, to take the body of a success in pieces rather than hold it, e.g. to write a large file: a function of the bytes of each piece, which in ClojureScript can give a promise to wait for, an OutputStream on the JVM, or a writable stream in Node The response is a map of :status, the final :url, :headers and :body. The body has gzip undone and text decoded by its charset. A 206 also has the :content-range as a map of :start, :end and :total. In a browser, :filtered? marks a response whose headers CORS hides. With a :sink, a response of status 200 to 299 has no :body but the number of bytes that the sink :received, within the same limits. Outside a browser it follows the redirects itself and asks :allow-pred about each. It never follows one from https to http, and credentials stay behind when a redirect leaves the origin. The response then lists the :redirects and has a :permanent-url if the first ones were permanent. A browser follows its own, unless :max-redirects is 0, which gives a redirect as a response with the status 0. It throws ::timeout or ::too-large past a limit and ::refused when :allow-pred refuses a URL. A request that reaches no server throws ::unresolved when the name of the host doesn't resolve, ::unreachable when the host can't be reached and ::tls when the secure connection fails, e.g. over an expired certificate. A browser tells none of these apart, but gives ::unreachable when it knows that the device is offline.
(send-public! request)Send the request but only to a host on the public internet. On the
JVM and in Node the host of each redirect must be public too.
It sends no request to the network of the app or of its device and throws ::refused instead (or in ClojureScript rejects with it).
Send the `request` but only to a host on the public internet. On the JVM and in Node the host of each redirect must be public too. It sends no request to the network of the app or of its device and throws ::refused instead (or in ClojureScript rejects with it).
(timeout? e)Whether the exception e of a request, or one of its causes, is a
timeout: ::timeout, or the timeout of the platform's client.
Whether the exception `e` of a request, or one of its causes, is a timeout: ::timeout, or the timeout of the platform's client.
(try-send! send request)(try-send! send request opts)Send the request with send, a function such as send!, and give a
map of the response as the :value, or of the exception as the :error
where send throws. The opts are the :timeout-seconds, :max-bytes,
:allow-pred, :user-agent and :max-redirects to put in the request.
The map comes in a future on the JVM and in a promise in ClojureScript, so several requests can be under way at once.
Send the `request` with `send`, a function such as send!, and give a map of the response as the :value, or of the exception as the :error where `send` throws. The `opts` are the :timeout-seconds, :max-bytes, :allow-pred, :user-agent and :max-redirects to put in the request. The map comes in a future on the JVM and in a promise in ClojureScript, so several requests can be under way at once.
The User-Agent of a request outside a browser, unless the request names another.
The User-Agent of a request outside a browser, unless the request names another.
(with-options request opts)The request with the :timeout-seconds, :max-bytes, :allow-pred,
:user-agent, :max-redirects and :truncate? that opts give, for a
function that sends with the options of send!.
The `request` with the :timeout-seconds, :max-bytes, :allow-pred, :user-agent, :max-redirects and :truncate? that `opts` give, for a function that sends with the options of send!.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |