Skip to content

AmxxEasyHttp

AmxxEasyHttp is a module for amxmodx which provides an easy to use API for HTTP, HTTPS and FTP requests.

ModuleCounter-Strike 1.6v1.5.0Views:1

Description

AmxxEasyHttp is a module for amxmodx which provides an easy to use API for HTTP, HTTPS and FTP requests.

Example

Here is a short example which shows some features of AmxxEasyHttp:

C++
public http_get()
{
    ezhttp_get("https://httpbin.org/get", "http_complete")
}

public http_get_with_data()
{
    new dat[1];
    dat[0] = 1337;

    ezhttp_get(
        .url = "https://httpbin.org/get", 
        .on_complete = "http_complete_with_data", 
        .data = dat, 
        .data_len = sizeof(dat)
    );

    // OR like that. Prefer the second variant if you use options
    new EzHttpOptions:options = ezhttp_create_options()
    ezhttp_option_set_user_data(options, dat, sizeof(dat))

    ezhttp_get(
        .url = "https://httpbin.org/get", 
        .on_complete = "http_complete_with_data", 
        .options_id = options
    );
}

public http_complete_with_data(EzHttpRequest:request_id, const data[])
{
    server_print("data[0]: %d", data[0]);
}

public http_post()
{
    new EzHttpOptions:options_id = ezhttp_create_options()
    ezhttp_option_set_header(options_id, "Content-Type", "text/plain")
    ezhttp_option_set_body(options_id, "Hello!")

    ezhttp_post("https://httpbin.org/post", "http_complete", options_id)
}

public http_complete(EzHttpRequest:request_id)
{
    if (ezhttp_get_error_code(request_id) != EZH_OK)
    {
        new error[64]
        ezhttp_get_error_message(request_id, error, charsmax(error))
        server_print("Response error: %s", error);
        return
    }

    new data[512]
    ezhttp_get_data(request_id, data, charsmax(data))
    server_print("Response data: %s", data)

    // large data cannot be read completely by ezhttp_get_data because of amxmodx's maximum array size limitation, 
    // so you can save the whole response to a file
    ezhttp_save_data_to_file(request_id, fmt("addons/amxmodx/response_%d.json", request_id))
}

// ezhttp_create_options() now uses auto_destroy = true by default.
// The handle is cleaned up automatically after the last request using it finishes.
// If you want to keep the same options handle alive for later reuse, create it like this:
//
// new EzHttpOptions:reusable = ezhttp_create_options(.auto_destroy = false)
// ...
// ezhttp_destroy_options(reusable)

// --------------------------------------------------------------------

public ftp_upload()
{
    ezhttp_ftp_upload(
        .user = "user", 
        .password = "password", 
        .host = "127.0.0.1", 
        .remote_file = "wads/cstrike_1.wad", 
        .local_file = "cstrike.wad", 
        .on_complete = "ftp_upload_complete"
    )

    ezhttp_ftp_upload2(
        .uri = "ftp://user:password@127.0.0.1/wads/cstrike_2.wad", 
        .local_file = "cstrike.wad", 
        .on_complete = "ftp_upload_complete",
        .security = EZH_SECURE_EXPLICIT
    )
}

public ftp_upload_complete(EzHttpRequest:request_id)
{
    new EzHttpErrorCode:error_code = ezhttp_get_error_code(request_id)
    new uploaded_kb = ezhttp_get_downloaded_bytes(request_id) / 1024
    new Float:elapsed_sec = ezhttp_get_elapsed(request_id)

    server_print("FTP upload complete. Error: %d. Uploaded: %d kb. Elapsed: %f sec", error_code, uploaded_kb, elapsed_sec)
}

public ftp_download_by_mask()
{
    ezhttp_ftp_download2(
        .uri = "ftp://user:password@127.0.0.1/demos/hltv_demo_*.dem",
        .local_file = "addons/amxmodx/data/demos/",
        .on_complete = "ftp_download_complete"
    )
}

Features

  • Non blocking mode
  • Custom headers
  • Url encoded parameters
  • Url encoded POST values
  • Basic authentication
  • Connection and request timeout specification
  • Cookie support
  • Proxy support
  • OpenSSL and WinSSL support for HTTPS requests
  • FTP/FTPES download and upload support
  • FTP wildcard download support
  • Built-in JSON support
  • HTTP keep-alive support

Advanced features

Behavior at the end of the map

By default, when you change map, all requests are interrupted. The callback functions are called with error code EZH_REQUEST_CANCELLED. An alternative is to specify the option ezhttp_option_set_plugin_end_behaviour(options_id, EZH_FORGET_REQUEST), in which case the request will not be interrupted at the end of the map (but the callback will not be called).

Request queue

The module uses up to 6 threads to execute requests, so there is no guarantee that requests will be executed in the order in which they were sent. If you need to execute requests sequentially, you can create a queue with new EzHttpQueue:queue_id = ezhttp_create_queue() and then set the ezhttp_option_set_queue(options_id, queue_id) option for all requests that need to be executed within that queue.

Building

Building AmxxEasyHttp requires CMake 3.18+ and GCC or MSVC compiler with C++17 support. Tested compilers are:

  • GCC 9.4.0
  • MSVC 2019

Building the library is done using CMake. You can run the CMake GUI to configure the library or use the command line:

Text
mkdir Release
cd Release
cmake .. -DCMAKE_BUILD_TYPE=Release
make easy_http

Building with Docker

You can use Docker to build AmxxEasyHttp for Linux. Create the image once with the command:

Text
docker build -t amxx-ezhttp-builder .

Run the Docker container to build the module:

Text
docker run --rm -v .:/ezhttp amxx-ezhttp-builder

Dependencies

To update the Linux dependencies:

  1. In AmxxEasyHttpDeps: bump versions.env, then push a tag. Its workflow publishes a release with amxx-ezhttp-deps-linux-i386.tar.gz and its SHA256.
  2. Here: set DEPS_TAG and DEPS_SHA256 in .github/deps.lock to that release.

Changelog

  1. v1.5.0current

    Changes: • Added passing custom data to a request via the data/data_len arguments of ezhttp_get/post/put/patch/delete, delivered to the completion callback (thanks @jonathan-up) • Added the ezhttp_version cvar (thanks @GLoOoccK) • FTP: URL normalization, wildcard download (download several files matching a mask, e.g. ftp://user:pass@host/demos/hltv_demo_*.dem), and automatic creation of local directories on download (thanks @wilianmaique) • Reworked the request lifecycle on map change, with trace logging and the ezhttp_trace_log cvar to toggle it (thanks @wilianmaique) • ezhttp_create_options gained an auto_destroy parameter (default true): set it to false to reuse the same options across multiple requests, and destroy them manually with ezhttp_destroy_options (thanks @wilianmaique) • Requests submitted with a non-existent queue are now rejected (return id 0) instead of silently falling back to the main queue (thanks @wilianmaique) • Added binary data support (application/octet-stream): new natives ezhttp_option_set_body_binary, ezhttp_option_append_body_binary and ezhttp_get_data_binary; embedded null bytes are preserved Build: • Added a Dockerfile for building the module (thanks @psycrow101) • Added noexecstack flags for glibc 2.41+ compatibility Requirements for linux: • GLIBC 2.19 or higher

  2. v1.4.0

    • Added support for PUT, PATCH, DELETE requests • Added support for HTTP keep-alive Requirements for linux: • GLIBC 2.19 or higher

  3. v1.3.0

    • Fixed crash occurring at simultaneous completion of several requests (most often it happened when changing the map) • Updated dependencies to the latest versions (cpr 1.10.5, curl 8.5.0, zlib 1.3, c-ares 1.25.0 (linux), openssl 1.1.1w (linux)) Requirements for linux: • GLIBC 2.19 or higher

  4. v1.2.0

    • Added built-in json support Requirements for linux: • GLIBC 2.19 or higher

  5. v1.1.1

    • Dependency on gcc-multilib removed Requirements for linux: • GLIBC 2.19 or higher

  6. v1.1.0

    • Added ezhttp_option_append_body native • Added queues for execution requests sequentially • Added customizable behavior of incomplete queries at the end of the map • Fixed crash at ReHLDS server startup • Fixed that the callback function was not called at the end of the map, if the request did not have time to be executed Requirements for linux: • GLIBC 2.19 or higher • gcc-multilib

  7. v1.0.1

    • Fix deletion of the uploading file when canceling ftp uploading Requirements for linux: • GLIBC 2.19 or higher • gcc-multilib

  8. v1.0.0

    First release. Requirements for linux: • GLIBC 2.19 or higher • gcc-multilib

Related

What is BMOD? BMOD lets amxx programmers use an alternative physics engine (Bullet). A few videos for illustration: https://youtube.com/watch?v=Nn26KkoIGNY https://youtube.com/watch?v=CUmNRsVro1U https://youtube.com/watch?v=vUCIKGlyDBQ https://youtube.com/watch?v=fAJlHJehlI8…

The module is a wrapper around the libcurl library. It supports SSL and allows transfers in non-blocking mode. Functions: All natives do exactly what their C counterparts do, except for some: the function starts a transfer, and when it completes, the callback callbackComplite…