* BQN HTTP library

FFI bindings to [[https://curl.se/libcurl/][libcurl]] for [[https://mlochbaum.github.io/BQN/][BQN]].

** Configuration

Set the location of the =libcurl.so= library in [[./config.bqn][config.bqn]].

** Usage

*** Simple API

Only GET and POST requests are implemented at this time.

#+begin_src bqn
⟨Get,Post⟩←•Import"curl.bqn"
#+end_src

Simple GET requests:
#+begin_src bqn
r←Get"https://httpbin.org/get"
#+end_src

You can pass headers as a left argument:
#+begin_src bqn
r←⟨"Content-Type: application/json"⟩Get"https://httpbin.org/get"
#+end_src

Arguments, port number, etc, can be included in the URL.

For POST requests, pass data as an additional string parameter. It
will not be converted or encoded in any way.
#+begin_src bqn
r←⟨"Content-Type: application/json"⟩Post"https://httpbin.org/post"‿"{""key"": ""value""}"
#+end_src

*** Response objects

The response object is a namespace with the following elements:
- ~code~: the response code.
- ~headers~: the response headers as a single string, separated by newlines.
- ~content~: the response content, as raw bytes.
- ~time~: the time the request took, in seconds.
- ~redirectCount~: the number of redirects.

If your endpoint returns text, you can use ~FromBytes~ from
[[https://github.com/mlochbaum/bqn-libs/blob/master/strings.bqn][bqn-libs/strings.bqn]] to decode UTF-8.

*** Advanced API

For more fine-grained control on request parameters, you can use the
advanced API, which closely mirrors the libcurl API structure.

A session object is created with ~OpenSession~, and can be reused to
speed up successive requests by reusing an existing connection.

Create a request by modifying the session object. Each of the
functions take the session as their right argument, and configuration
data as their left argument. They modify the session in-place, but
also return it so that they can be chained easily.

- ~url SetURL session~: the request URL.
- ~headers SetHeaders session~: the request headers, as a list of strings.
- ~SetVerbose session~: log verbose request data to standard output.
- ~n SetTimeout session~ and ~n SetTimeoutms timeout~: the request timeout, in seconds or in milliseconds.
- ~data SetData session~: use a POST request and set the data to send, as a string.

Finally, perform the actual request with ~Perform~, returning the
response object as above.

The session object can then be reused for subsequent requests,
modifying request parameters as needed. It can be reset to its default
configuration using ~ResetSession~, while preserving open connections
and caches.

A session is terminated, and its memory freed, with ~CloseSession~.

Full example:
#+begin_src bqn
⟨
  OpenSession,CloseSession,
  SetURL,SetHeaders,SetTimeoutms,
  Perform,
⟩←•Import"curl.bqn"

session←⟨"User-Agent: myapp"⟩SetHeaders OpenSession @
r1←Perform "https://httpbin.org/status/418"SetURL session
•Show r1.code
r2←Perform 500 SetTimeoutms "https://httpbin.org/ip"SetURL session
•Out r2.content

CloseSession session
#+end_src

** Running tests

Run a local [[https://httpbin.org/][httpbin.org]] instance with Docker:
#+begin_src sh
docker run -p 8080:80 kennethreitz/httpbin
#+end_src

The tests can be run with =bqn tests.bqn=.