lsevero/clj-curl

curl for clojure

clj-curl

curl for clojure using JNA, because we love curl.

But... why?

Clojure definitely has excellent libraries to handle http connections like clj-http and other things, however, none of them are complete as curl. There is a very good reason why curl has been ported for almost every programming language there is, because curl is just awesome. Curl supports a lot of protocols, like HTTP(S), FTP(S), SFTP, IMAP(S), POP3(S), TFTP, SMB, SCP, RTMP, TELNET and more, check out protocols list for the full list. The curl's easy API is really easy. This sentence is not redundant as it appear, curl easy API is easy to use even with pure C, and it is so simple and well done that can be easily ported to other programming languages.

This library tries to be as close as possible to the C API. In case of doubts go to the examples folder and the official libcurl docs.

Usage

For obvious reasons, this project needs libcurl to be installed in your system.

The usage of this library is basically the same as the libcurl in C. Everything is mutable, so be careful. This library is just about exposing the C api to the clojure world, without adding a lot of abstractions to make things easier or doing stuff the '''clojure way'''. Just create a curl handler wrapped in a function without exposing the curl's state to your applications and you should be fine.

Deprecated functions like curl_formadd will not be added here, you could implement them yourself, however if you see the official docs saying to not use a function, do yourself a favor and do not use it.

Handlers? What are they??

libcurl depends A LOT in C callbacks to do stuff (mostly reading and writing). The way that the JNA creates a '''c callback''' is creating a class that implements the Callback interface which you should define the contents of the inherited callback function. I've created some handlers to perform some more basic and common stuff, like reading/writing from memory and reading/writing from/to files. Every place that the C API asks for a C callback you should instantiate one of the Handler classes and pass its instance as a argument to setopt. Please check the examples folder to see how to use and import them. They are gen-class java classes, so you should import them always with the import clause, not require.

Also, besides this java handlers you could use the libc fwrite and fread to read and write to/from files, that is not recommended by the official docs because the WRITEDATA/READDATA shows some random crashes on windows. On other systems you should be fine.

Docs

Three things that you should now before using this library:

• You should use the handlers defined in clj-curl.Handlers instead of C Callbacks, or define your own
• You can use plain clojure vectors instead of curl_slists when using setopt
• Deprecated functions like curl_formadd will not be added here

Besides that, there is nothing much to doc here, because we are just exposing the C curl API. 99% of the time you will be setting some options to setopt, passing some handlers to read/write data and exec a perform. The real useful docs are the official ones found at official docs, check out the examples folder and should be easy enough to read a C program and port it to the clojure interface.

TODO list

• low level file descriptor functions for multi (I don't think someone will ever use one of them in a high level language like clojure though)

License

Copyright © 2019

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0.

This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version, with the GNU Classpath Exception which is available at https://www.gnu.org/software/classpath/license.html.

clj-curl's Issues

How should I be getting symbols?

This is maybe a naiive question, but how is the library expecting me to call symbols?

For instance I want to turn on SSL

As per the libcurl docs: https://curl.se/libcurl/c/CURLOPT_USE_SSL.html

          (curl-easy/setopt curl
                            curl-opts/use-ssl 
                            /*CURLUSESSL_TRY*/)

But I'm not quite sure how I'm expected to fill in that last value :)

What I ended up doing is going into curl.h find the enum it's listed under
https://github.com/curl/curl/blob/master/include/curl/curl.h#L875
So looks like it should be a 1 ..

The first time I ran it I got a CURLE_BAD_FUNCTION_ARGUMENT - but seems like it's working now

I see in opts you are also using the numerical values directly. Here it reads
https://github.com/lsevero/clj-curl/blob/master/src/clj_curl/opts.clj#L580

(def ^:const use-ssl 119)

But I'm not sure where the 119 comes from though

I guess my big picture question is.. am I doing this right? Should users be looking up enum values in the curl header?

My expectation was that these symbols were mapped somewhere to Clojure static vars. I can see there are a ton of them so maybe it was too annoying to copy them all

https://curl.se/libcurl/c/symbols-in-versions.html

In any case, thank you for the easy to use library :) I really appreciate it