The kmj-http packages provides the ability to make arbitrary HTTP requests.

The runtime provides this library through the luaL_newlib auxiliary library function, so all fields can be assumed to be functions.

This field contains an alias for the function contained in the send field, where the first argument is always set to GET. Refer to the documentation for the send field for further information.

This field contains an alias for the function contained in the send field, where the first argument is always set to POST. Refer to the documentation for the send field for further information.

This field contains an alias for the function contained in the send field, where the first argument is always set to DELETE. Refer to the documentation for the send field for further information.

This field contains an alias for the function contained in the send field, where the first argument is always set to PATCH. Refer to the documentation for the send field for further information.

This field contains an alias for the function contained in the send field, where the first argument is always set to PUT. Refer to the documentation for the send field for further information.

This field contains a function allowing you to make HTTP requests.

send(method: string, url: string, options: table|nil = nil, requestBody: any = nil): (responseBody: any)

1. The first argument should be any valid HTTP method verb. If you're using one of the aliases above, this argument will be implicitly set.
2. The second argument, or first if using an alias and so on, should contain the target URL for the request.
3. The third argument may contain a table of options, described below, altering aspects about the request and how the response should be interpreted.
4. The fourth argument may contain the body of the request. This data may be remapped according to changes made to the options argument.

1. The first return value will contain the body of the response data. Status code and response headers can be retrieved through a callback specified in the options table.

Below are possible the fields that may be part of the options table provided to the third argument or the send function.

The timeout field may contain a number the indicates the amount of milliseconds that the request may take to complete before it is aborted. Specifying a value less than 1 will be considered infinite. The default value, implied by omitting this field or explicitly setting it to nil, is 0.

The type field may contain a string that determines the expected format of response body, if the actual format is incompatible the return value will be nil. The default value, implied by omitting this field or explicitly setting it to nil, is "".

Below is a table containing supported type values:

Because I have absolutely zero intention of providing any sort of proper XML handling for the sanity of everyone involved in the project, the details on how XML documents are decoded is described in the following blob of text:

Elements are translated to Lua tables, they are always ensured to have a field named name containing the name of the element type as a string. If a namespace is specified, an additional ns field is present containing the full namespace URI string. If the element has children, they are decoded into a field named elems containing a sequential table with element tables. If the element has a text value, it is decoded into a field named value. Children and values are mutually exclusive. If the element has attributes, they are decoded into a field called attrs in the element table, containing a sequential table of tables with following format; Attributes are represented as a table that will always have a name field containing the name of the attribute and a field called value containing its value. If the attribute has a namespace, an additional ns field is present containing the full namespace URI string.

If any of that was unclear you have three options:

1. Propose a better description.
2. Refer to the XML handling in the forex Sense.
3. Use literally any other encoding, please be nicer to yourself.

The requestHeaders field may contain a key/value table describes headers to be sent in your request. Both the field names and field values should be strings, header names are case insensitive.

The value of the Content-Type header affects how the fourth argument, requestBody, to the send function is interpreted.

If the type of requestBody is a string, it will be sent as a raw octet stream buffer, unless the Content-Type value starts with text/, in which case it will be handled to a UTF-8 string and reencoded as necessary.

If requestBody is a table, it will be JSON encoded if Content-Type is set to application/json, otherwise it will be encoded as a form, the format of which depends on whether the Content-Type header is set to application/x-www-form-urlencoded or multipart/form-data. If the Content-Type isn't set to any of these well-known values, the value of requestBody will be discarded.

The application/x-www-form-urlencoded formatting expects a pure string key/string value pair table as the value of requestBody, and while multipart/form-data also accepts this, the value can also be set to a table containing the following values.

The responseHeaders field may contain a function that receives the HTTP status code and response headers before the body has been processed.

callback(statusCode: number, responseHeaders: table): ()

1. The first argument will contain the HTTP status code.
2. The second argument will contain a table containing the response headers in a similar format as the requestHeaders options field. Header names are normalised to lowercase to allow for easy indexing.

This callback does not expect any return values. In the future this callback may gain the ability to interrupt the processing of the body, so please DO NOT return anything.