Repository files navigation

unixsocket-http is a Clojure library to handle HTTP communication overUNIX domain sockets. This kind of I/O is notably used by theDockerdaemon which was the main driver to create this library.

Use theunixsocket-http.core namespace to access HTTP functionality witha similar API asclj-http.

(require '[unixsocket-http.core:as uhttp])(defclient (uhttp/client"unix:///var/run/docker.sock"))

To provide a common API towards TCP sockets, they are also supported:

(defclient (uhttp/client"tcp://127.0.0.1:6537"))

Note that this project does not have the ambition to replicate all of clj-http'sfunctionality. The main use case is communication with Docker which willnaturally restrict the feature set implemented.

Once you have a client, you can send requests:

(uhttp/get client"/_ping");; {:status 200,;;  :headers;;  {"api-version" "1.40",;;   "server" "Docker/19.03.2 (linux)",;;   "content-type" "text/plain; charset=utf-8",;;   "content-length" "2",;;   "docker-experimental" "false",;;   "pragma" "no-cache",;;   "date" "Thu, 09 Apr 2020 15:20:06 GMT",;;   "ostype" "linux",;;   "cache-control" "no-cache, no-store, must-revalidate"},;;  :body "OK"}

All HTTP functions take an options map as their last parameter that can be usedto supply additional data or alter the request/response behaviour.

Query parameters can be passed using:query-params, and a body can besupplied as eitherInputStream orString using the:body key.

(uhttp/post  client"/images/create"  {:query-params {:fromImage"node:alpine",:repo"testnode",:tag"latest"}});; {:status 200,;;  :headers;;  {"api-version" "1.40",;;   "content-type" "application/json",;;   "date" "Thu, 09 Apr 2020 15:27:11 GMT",;;   "docker-experimental" "false",;;   "ostype" "linux",;;   "server" "Docker/19.03.2 (linux)",;;   "transfer-encoding" "chunked"},;;  :body;;  "{\"status\":\"Pulling from library/node\",\"id\":\"latest\"}\r\n..."}

As this is supported by some APIs, you can pass a query parameter multiple timesby supplying a collection instead of value. For example,{:x [1 2 3]} turnsinto?x=1&x=2&x=3.

Use:as :stream in the options map to make:body anjava.io.InputStream toconsume from. Alternatively, use:as :socket to get access to the underlyingjava.net.Socket for bidirectional communication.

Always make sure to callclose on the resources obtained this way, otherwiseyou'll run into connection leaks.

By default, HTTP status codes ≥ 400 will cause an exception(clojure.lang.ExceptionInfo) to be thrown. You can access the underlyingresponse viaex-data.

Note that the:body will not be present if you are expecting a streamingresponse, unless you explicitly set:throw-entire-message? totrue.

If you want to prevent the client from throwing exceptions, and you'd rather getthe response no matter what, you can set:throw-exceptions? tofalse.

You can create a client with anhttps://... URL, which will prompt it to useTLS to perform any requests. Usually, the relevant certificates should bepresent in your Java keystore and the underlyingOkHttpClient will pick themup automatically when verifying the connection.

Formutual TLS (mTLS) or pointers on how to tackle TLS setup manually, checkout therespective documentation.

This library can be used with GraalVM'snative-image tool tocreate native Clojure executables. The necessary configuration files are alreadybundled with this library and should be picked up automatically.

MIT LicenseCopyright (c) 2020-2021 Yannick SchererPermission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.