dlozeve / bqn-curl

BQN HTTP library, from libcurl FFI bindings

BQN HTTP library

FFI bindings to libcurl for BQN.

Configuration

Set the location of the libcurl.so library in config.bqn.

Usage

Simple API

Only GET and POST requests are implemented at this time.

⟨Get,Post⟩←•Import"curl.bqn"

Simple GET requests:

r←Get"https://httpbin.org/get"

You can pass headers as a left argument:

r←⟨"Content-Type: application/json"⟩Get"https://httpbin.org/get"

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.

r←⟨"Content-Type: application/json"⟩Post"https://httpbin.org/post"‿"{""key"": ""value""}"

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 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:

⟨
  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

Running tests

Run a local httpbin.org instance with Docker:

docker run -p 8080:80 kennethreitz/httpbin

The tests can be run with bqn tests.bqn.