3 2957b0a4 2021-10-13 op [![Clojars Project](https://img.shields.io/clojars/v/com.omarpolo/gemini.svg)](https://clojars.org/com.omarpolo/gemini)
5 a7994c56 2021-10-13 op A Clojure library to make Gemini requests that exposes some low-level
6 a7994c56 2021-10-13 op API to handle network requests.
11 83c817b4 2021-10-13 op Import the library for e.g. with:
14 1d126b15 2021-10-13 op user=> (require '[gemini.core :as gemini])
17 83c817b4 2021-10-13 op ### Documentation
19 2c7df1b2 2021-10-15 op `fetch` makes a Gemini request. The request needs to be closed
20 2c7df1b2 2021-10-15 op afterwards using `close`.
22 2c7df1b2 2021-10-15 op Takes a map with the following keys (only `:request` is mandatory):
24 2c7df1b2 2021-10-15 op - `:proxy`: a map of `:host` and `:port`, identifies the server to
25 2c7df1b2 2021-10-15 op send the requests to. This allows to use a gemini server as a
26 2c7df1b2 2021-10-15 op proxy, it doesn't do any other kind of proxying (e.g. SOCK5.)
27 2c7df1b2 2021-10-15 op - `:request` the URI (as string) to require.
28 2c7df1b2 2021-10-15 op - `:follow-redirects?` if `false` or `nil` don't follow redirects, if
29 2c7df1b2 2021-10-15 op `true` follow up to 5 redirects, or the number of redirects to
32 2c7df1b2 2021-10-15 op Returns a map with `:error` key if an error occur or with the
33 2c7df1b2 2021-10-15 op following fields if it succeeds:
35 2c7df1b2 2021-10-15 op - `:uri`: the URI of the request. May be different from the
36 2c7df1b2 2021-10-15 op requested one if `:follow-redirects?` was specified.
37 2c7df1b2 2021-10-15 op - `:request`: the object backing the request.
38 2c7df1b2 2021-10-15 op - `:code` and `:meta` are the parsed header response.
39 2c7df1b2 2021-10-15 op - `:body` an instance of a `BufferedReader`. Note: closing the body
40 bdb683b8 2021-10-15 op is not enough, always call `clase` on the returned map.
41 2c7df1b2 2021-10-15 op - `:redirected?` true if a redirect was followed.
44 2c7df1b2 2021-10-15 op user=> (gemini/fetch {:request "gemini://gemini.circumlunar.space"
45 2c7df1b2 2021-10-15 op :follow-redirects? true})
46 2c7df1b2 2021-10-15 op {:uri "gemini://gemini.circumlunar.space/",
48 2c7df1b2 2021-10-15 op #object[com.omarpolo.gemini.Request 0x6fa9ec6f "com.omarpolo.gemini.Request@6fa9ec6f"],
50 2c7df1b2 2021-10-15 op :meta "text/gemini",
52 2c7df1b2 2021-10-15 op #object[java.io.BufferedReader 0x18a8d9e0 "java.io.BufferedReader@18a8d9e0"],
53 2c7df1b2 2021-10-15 op :redirected? true}
56 83c817b4 2021-10-13 op `body-as-string!` reads all the response into a string and returns it.
57 83c817b4 2021-10-13 op It also closes the request automatically.
60 e655d71e 2021-10-15 op user=> (-> {:request "gemini://gemini.circumlunar.space/"}
62 1d126b15 2021-10-13 op gemini/body-as-string!)
63 1d126b15 2021-10-13 op "# Project Gemini\n\n## Overview\n\nGemini is a new internet protocol which..."
66 2c7df1b2 2021-10-15 op `close` closes a request. It needs to be called after every request.
69 9e7f2805 2021-10-15 op user=> (let [req (gemini/fetch {,,,})]
70 83c817b4 2021-10-13 op (when-not (:error req)
71 e4f66724 2021-10-13 op ;; do something with req
73 e4f66724 2021-10-13 op (gemini/close req)))
76 83c817b4 2021-10-13 op `with-request` is a macro like `with-open` to making connection
77 83c817b4 2021-10-13 op easily. It automatically closes the request and evaluates the body
78 83c817b4 2021-10-13 op only when the request is successful, otherwise throws an exception.
81 2c7df1b2 2021-10-15 op user=> (gemini/with-request [req {:request "gemini://gemini.circumlunar.space/"}]
86 83c817b4 2021-10-13 op ## Streaming content
88 83c817b4 2021-10-13 op The `:body` keyword in the returned map is an instance of a Java
89 83c817b4 2021-10-13 op BufferedReader, so streaming content is easy.
91 83c817b4 2021-10-13 op However, `body-as-string!` needs to materialise the full reply, so in
92 83c817b4 2021-10-13 op case of a streaming request it will never return!
95 83c817b4 2021-10-13 op ## text/gemini
97 83c817b4 2021-10-13 op This library only implements the network part of Gemini, it doesn't
98 83c817b4 2021-10-13 op try to handle any kind of content. To handle text/gemini you can use
99 83c817b4 2021-10-13 op e.g. the [gemtext][gemtext] library:
102 83c817b4 2021-10-13 op user=> (require '[gemtext.core :as gemtext])
104 a8e8ae45 2021-10-15 op user=> (gemini/with-request [req {:request "gemini://gemini.circumlunar.space/"}]
105 83c817b4 2021-10-13 op (gemtext/parse (:body req)))
106 83c817b4 2021-10-13 op [[:header-1 "Project Gemini"]
108 83c817b4 2021-10-13 op [:header-2 "Overview"]
110 83c817b4 2021-10-13 op [:text "Gemini is a new internet protocol which:"]
114 0ccdb5e9 2021-10-13 op The [gemtext][gemtext] library supports streaming via the
115 0ccdb5e9 2021-10-13 op `gemtext.core/parse` transducer:
118 a8e8ae45 2021-10-15 op user=> (gemini/with-request [req {:request "gemini://gemini.circumlunar.space/"}]
119 0ccdb5e9 2021-10-13 op (transduce gemtext/parser conj [] (line-seq (:body req))))
124 83c817b4 2021-10-13 op [gemtext]: https://github.com/omar-polo/gemtext