HTTP client (#3483)

Author: andreyaksenov

.gitignore

@@ -15,6 +15,7 @@ _theme/tarantool/static/design.css.map
 .idea
 rocks
 .vscode/
+doc/code_snippets/.rocks
 
 # Crowdin API key
 apikey.txt

doc/code_snippets/README.md

@@ -0,0 +1,51 @@
+# Tarantool code examples
+
+The `doc/code_snippets` folder of a Tarantool documentation repository contains runnable code examples that show how to work with various Tarantool modules. Code from these examples is [referenced](#referencing-code-snippets) in corresponding documentation sections. 
+
+## Prerequisites
+
+First, install the [tt CLI utility](https://www.tarantool.io/en/doc/latest/reference/tooling/tt_cli/).
+Then, go to the `doc/code_snippets` folder and install the following libraries:
+
+- Install [luatest](https://github.com/tarantool/luatest):
+    ```shell
+    tt rocks install luatest
+    ```
+
+- Install [luarapidxml](https://github.com/tarantool/luarapidxml):
+    ```shell
+    tt rocks install luarapidxml
+    ```
+
+
+
+## Running and testing examples
+
+To test all the examples, go to the `doc/code_snippets` folder and execute the `luatest` command:
+
+```shell
+.rocks/bin/luatest
+```
+
+To run a specific example with tests, use the `luatest` command with the `-c` option, for example:
+
+```shell
+.rocks/bin/luatest -c test/http_client/get_test.lua
+```
+
+You can also run the `httpbin` service locally using Docker:
+
+```shell
+docker run -p 80:80 kennethreitz/httpbin
+```
+
+In this case, replace `https://httpbin.org` links with `http://127.0.0.1` to test the examples.
+
+
+## Referencing code snippets
+To display a specific source file in a topic, use the `literalinclude` directive as follows:
+```
+..  literalinclude:: /code_snippets/test/http_client/post_json_test.lua
+    :language: lua
+    :lines: 1-6
+```

doc/code_snippets/test/http_client/get_add_cookie_test.lua

@@ -0,0 +1,13 @@
+local http_client = require('http.client').new()
+local response = http_client:get('https://httpbin.org/cookies', {
+    headers = {
+        ['Cookie'] = 'session_id=abc123; csrftoken=u32t4o;',
+    }
+})
+print(response.body)
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_cookie = function()
+    luatest.assert_equals(response:decode()['cookies']['session_id'], 'abc123')
+end

doc/code_snippets/test/http_client/get_add_header_test.lua

@@ -0,0 +1,15 @@
+local http_client = require('http.client').new()
+local response = http_client:get('https://httpbin.org/headers', {
+    headers = {
+        ['User-Agent'] = 'Tarantool HTTP client',
+        ['Authorization'] = 'Bearer abc123'
+    }
+})
+print('Authorization: '..response:decode()['headers']['Authorization'])
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_header = function()
+    luatest.assert_equals(response:decode()['headers']['User-Agent'], 'Tarantool HTTP client')
+    luatest.assert_equals(response:decode()['headers']['Authorization'], 'Bearer abc123')
+end

doc/code_snippets/test/http_client/get_add_query_params_test.lua

@@ -0,0 +1,11 @@
+local http_client = require('http.client').new()
+local response = http_client:get('https://httpbin.org/get', {
+    params = { page = 1 },
+})
+print('URL: '..response.url)
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_url_with_params = function()
+    luatest.assert_equals(response:decode()['url'], 'https://httpbin.org/get?page=1')
+end

doc/code_snippets/test/http_client/get_cookies_test.lua

@@ -0,0 +1,9 @@
+local http_client = require('http.client').new()
+local response = http_client:get('https://httpbin.org/cookies/set?session_id=abc123&csrftoken=u32t4o&', {follow_location = false})
+print("'session_id' cookie value: "..response.cookies['session_id'][1])
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_cookie = function()
+    luatest.assert_equals(response.cookies['session_id'][1], 'abc123')
+end

doc/code_snippets/test/http_client/get_gzip_test.lua

@@ -0,0 +1,9 @@
+local http_client = require('http.client').new()
+local response = http_client:get('https://httpbin.org/gzip', {accept_encoding = "br, gzip, deflate"})
+print('Is response gzipped: '..tostring(response:decode()['gzipped']))
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_status = function()
+    luatest.assert_equals(response:decode()['gzipped'], true)
+end

doc/code_snippets/test/http_client/get_header_test.lua

@@ -0,0 +1,9 @@
+local http_client = require('http.client').new()
+local response = http_client:get('https://httpbin.org/etag/7c876b7e')
+print('ETag header value: '..response.headers['etag'])
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_etag_header = function()
+    luatest.assert_equals(response.headers['etag'], '7c876b7e')
+end

doc/code_snippets/test/http_client/get_json_test.lua

@@ -0,0 +1,10 @@
+local http_client = require('http.client').new()
+local response = http_client:get('https://httpbin.org/json')
+local document = response:decode()
+print("'title' value: "..document['slideshow']['title'])
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_json = function()
+    luatest.assert_equals(document['slideshow']['title'], 'Sample Slide Show')
+end

doc/code_snippets/test/http_client/get_stream_test.lua

@@ -0,0 +1,19 @@
+local http_client = require('http.client').new()
+local json = require('json')
+
+local io = http_client:get('https://httpbin.org/stream/5', {chunked = true})
+local chunk_ids = ''
+while data ~= '' do
+    local data = io:read('\n')
+    if data == '' then break end
+    local decoded_data = json.decode(data)
+    chunk_ids = chunk_ids..decoded_data['id']..' '
+end
+print('IDs of received chunks: '..chunk_ids)
+io:finish()
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_chunk_ids = function()
+    luatest.assert_equals(chunk_ids, '0 1 2 3 4 ')
+end

doc/code_snippets/test/http_client/get_test.lua

@@ -0,0 +1,9 @@
+local http_client = require('http.client').new()
+local response = http_client:get('https://httpbin.org/get')
+print('Status: '..response.status..' '.. response.reason)
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_status = function()
+    luatest.assert_equals(response.status, 200)
+end

doc/code_snippets/test/http_client/get_xml_test.lua

@@ -0,0 +1,18 @@
+local http_client = require('http.client').new()
+local xml = require("luarapidxml")
+
+http_client.decoders = {
+    ['application/xml'] = function(body, _content_type)
+        return xml.decode(body)
+    end,
+}
+
+local response = http_client:get('https://httpbin.org/xml')
+local document = response:decode()
+print("'title' value: "..document['attr']['title'])
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_json = function()
+    luatest.assert_equals(document['attr']['title'], 'Sample Slide Show')
+end

doc/code_snippets/test/http_client/post_form_params_test.lua

@@ -0,0 +1,11 @@
+local http_client = require('http.client').new()
+local response = http_client:post('https://httpbin.org/anything', nil, {
+    params = { user_id = 123, user_name = 'John Smith' },
+})
+print('User ID: '..response:decode()['form']['user_id'])
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_form_data = function()
+    luatest.assert_equals(response:decode()['form'], {user_id = "123", user_name = "John Smith"})
+end

doc/code_snippets/test/http_client/post_json_test.lua

@@ -0,0 +1,12 @@
+local http_client = require('http.client').new()
+local response = http_client:post('https://httpbin.org/anything', {
+    user_id = 123,
+    user_name = 'John Smith'
+})
+print('Posted data: '..response:decode()['data'])
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_json = function()
+    luatest.assert_equals(response:decode()['data'], '{"user_id":123,"user_name":"John Smith"}')
+end

doc/code_snippets/test/http_client/post_stream_test.lua

@@ -0,0 +1,16 @@
+local http_client = require('http.client').new()
+local json = require('json')
+
+local io = http_client:post('https://httpbin.org/anything', nil, {chunked = true})
+io:write('Data part 1')
+io:write('Data part 2')
+io:finish()
+response = io:read('\r\n')
+decoded_data = json.decode(response)
+print('Posted data: '..decoded_data['data'])
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_posted_data = function()
+    luatest.assert_equals(decoded_data['data'], 'Data part 1Data part 2')
+end

doc/code_snippets/test/http_client/post_yaml_test.lua

@@ -0,0 +1,20 @@
+local http_client = require('http.client').new()
+local response = http_client:post('https://httpbin.org/anything', {
+    user_id = 123,
+    user_name = 'John Smith'
+}, {
+    headers = {
+        ['Content-Type'] = 'application/yaml',
+    }
+})
+print('Posted data:\n'..response:decode()['data'])
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_yaml = function()
+    luatest.assert_equals(response:decode()['data'], "---\
+user_id: 123\
+user_name: John Smith\
+...\
+")
+end

doc/code_snippets/test/http_client/request_test.lua

@@ -0,0 +1,9 @@
+local http_client = require('http.client').new()
+local response = http_client:request('GET', 'https://httpbin.org/get')
+print('Status: '..response.status..' '.. response.reason)
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_returns_status = function()
+    luatest.assert_equals(response.status, 200)
+end