====== kmj-http ======

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

The runtime provides this library through the [[https://www.lua.org/manual/5.4/manual.html#luaL_newlib|luaL_newlib]] auxiliary library function, so all fields can be assumed to be functions.

===== get =====

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.

===== post =====

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.

===== delete =====

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.

===== patch =====

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.

===== put =====

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.

===== send =====

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

==== Syntax ====

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

==== Arguments ====

  - 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.
  - The second argument, or first if using an alias and so on, should contain the target URL for the request.
  - The third argument may contain a table of options, described below, altering aspects about the request and how the response should be interpreted.
  - The fourth argument may contain the body of the request. This data may be remapped according to changes made to the options argument.

==== Returns ====

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

===== Options =====

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

==== timeout ====

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''.

==== type ====

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:

^  Type  ^ Behaviour ^
|  ''%%""%%'' or ''%%"string"%%''  | Will interpret the response body a string in whatever encoding the server provided and convert it to a UTF-8 string. |
|  ''%%"buffer"%%''  | Will interpret the response body as a raw octet stream, regardless of typing the server provided. |
|  ''%%"json"%%''  | Will attempt to interpret the response body as JSON encoded data and return the appropriate Lua type. |
|  ''%%"xml"%%''  | Will attempt to interpret the response body as an XML document and return it as a deconstructed Lua table. |

=== Formatting of the XML Lua tables ===

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:

  - Propose a better description.
  - Refer to the [[https://patchii.net/flashii/komeiji-senses/src/commit/c97e0a151d71c9fc4242c30975598257269ce7ff/forex/ecb.lua#L11|XML handling in the forex Sense]].
  - Use literally any other encoding, please be nicer to yourself.

==== requestHeaders ====

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.

=== Content-Type header behaviour ===

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.

^  Field  ^  Type  ^ Description ^
|  ''filename''  |  ''string'' or ''nil''  | Used as a the filename in the Content-Disposition header for this parameter. |
|  ''path''  |  ''string'' or ''nil''  | Literal filesystem path to a file to use as the value, ''value'' field is ignored if this is specified. |
|  ''value''  |  ''string'' or ''nil''  | Buffer string used as the value. When specifying the form field value as a string instead of this table, the string is handled as UTF-8, this field does not do that. |
|  ''headers''  |  ''table'' or ''nil''  | Follows the same format as the ''requestHeaders'' table, but for individual form fields. |

==== responseHeaders ====

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

=== Syntax ===

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

=== Arguments ===

  - The first argument will contain the HTTP status code.
  - 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.

=== Return values ===

//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.//