Skip to content

feat: build apisix-runtime with ngx_http_ffi_client #481

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shreemaan-abhishek merged 6 commits into from
Aug 6, 2026
Merged

feat: build apisix-runtime with ngx_http_ffi_client #481

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bb13a2c
feat: build apisix-runtime with ngx_http_ffi_client
shreemaan-abhishek Aug 5, 2026
74ead74
fix: keep the ngx_http_ffi_client token out of the build trace
shreemaan-abhishek Aug 5, 2026
1f18875
ci: fail a release build that has no ngx_http_ffi_client token
shreemaan-abhishek Aug 5, 2026
49a866f
build: require ngx_http_ffi_client instead of building without it
shreemaan-abhishek Aug 5, 2026
738ae33
build: pin ngx_http_ffi_client to a version tag
shreemaan-abhishek Aug 5, 2026
a29cb57
build: clone ngx_http_ffi_client like every other module
shreemaan-abhishek Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,18 @@ ls output/
apisix-runtime_1.0.0-0~ubuntu20.04_amd64.deb
```

### ngx_http_ffi_client

`ngx_http_ffi_client` is the C HTTP client the AI plugins use for outbound LLM
requests. The version is pinned by `ngx_http_ffi_client_ver` in
`build-apisix-runtime.sh`, as it is for every other module. Set it to build
against a different tag or branch:

```sh
ngx_http_ffi_client_ver=v0.2.0 \
make package type=deb app=apisix-runtime version=1.0.0
```

Comment on lines +109 to +120

@coderabbitai coderabbitai Bot Aug 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

files=$(fd -t f . | rg '(^|/)(Makefile|Dockerfile[^/]*|.*\.(mk|yml|yaml))$' || true)

if [ -n "$files" ]; then
    while IFS= read -r file; do
        rg -n -C 6 \
          'ngx_http_ffi_client_ver|build-apisix-runtime\.sh|--build-arg|ARG |ENV ' \
          "$file" || true
    done <<< "$files"
fi

Repository: api7/apisix-build-tools

Length of output: 2067

🏁 Script executed:

set -euo pipefail
for path in Makefile build-apisix-runtime.sh Dockerfile; do
  url="https://raw.githubusercontent.com/api7/apisix-build-tools/master/$path"
  echo "=== $path ==="
  curl -fsSL "$url" 2>/dev/null | rg -n -C 8 \
    'ngx_http_ffi_client_ver|build-apisix-runtime\.sh|--build-arg|ARG |ENV ' || true
done

Repository: api7/apisix-build-tools

Length of output: 2038

🌐 Web query:

api7 apisix-build-tools ngx_http_ffi_client_ver build-apisix-runtime.sh Makefile

💡 Result:

The components you listed are part of the core build infrastructure for Apache APISIX, maintained primarily within the api7/apisix-build-tools repository. This ecosystem is designed to automate the complex process of compiling and packaging custom OpenResty distributions specifically optimized for APISIX [1][2]. 1. api7/apisix-build-tools: This is the primary repository containing the scripts and utilities required to package and release APISIX distributions, including the specialized apisix-base and apisix-runtime variants [1][2]. 2. build-apisix-runtime.sh: This is a core shell script in the build-tools repository used to compile the apisix-runtime variant [3]. Unlike the standard OpenResty, this runtime is optimized for production, featuring advanced cryptographic support (such as OpenSSL 3.x and FIPS compliance) and specific compiler flags (cc-opt/ld-opt) to enable APISIX-specific functionality like memory safety and performance tuning [3][2][4]. 3. ngx_http_ffi_client_ver: While you noted this identifier, it appears to be a misinterpretation of FFI (Foreign Function Interface) naming conventions commonly found in OpenResty modules [5][6]. In the context of APISIX and OpenResty, FFI is widely used (via libraries like lua-resty-ffi) to bridge Lua with high-performance languages (e.g., Rust, Go) for gRPC clients, SSL/TLS certificate verification, and other performance-critical tasks [6][7][8]. 4. Makefile: In this build system, the Makefile (and the underlying build scripts) orchestrates the compilation of Nginx and various essential modules, including apisix-nginx-module, lua-var-nginx-module, and wasm-nginx-module [9][3][2]. It handles the configuration of the OpenResty environment, ensuring all dependencies and paths are correctly set for the specific APISIX installation [9][2]. In summary, these tools form the foundation for maintaining the "FFI-heavy" architecture of APISIX, allowing it to leverage high-performance external modules while remaining compatible with the OpenResty/Nginx core [2][10].

Citations:

🌐 Web query:

site:github.com/api7/apisix-build-tools/blob Makefile ngx_http_ffi_client_ver

💡 Result:

There is no standard or widely documented variable or entity named ngx_http_ffi_client_ver in public Nginx, OpenResty, or Apache APISIX source code or build documentation [1][2][3][4][5][6]. Based on the available technical records, the term likely does not exist in the official Nginx/OpenResty ecosystem. Build scripts for related projects, such as the api7/apisix-build-tools repository, use various version variables to manage dependencies (e.g., ngx_multi_upstream_module_ver, apisix_nginx_module_ver, lua_resty_events_ver) during the build and configuration process [2][4]. It is possible that ngx_http_ffi_client_ver is a custom, project-specific, or typo-derived variable within a private or local build environment, as it does not appear in the authoritative open-source repositories for these technologies [1][2][4].

Citations:

🌐 Web query:

site:github.com/api7/apisix-build-tools "ngx_http_ffi_client_ver"

💡 Result:

The term ngx_http_ffi_client_ver does not appear as a standard public API or documented constant within NGINX or OpenResty. It is likely a misinterpreted or internal-only reference related to custom builds or specific third-party module integrations within the Apache APISIX ecosystem [1][2]. In the context of the apisix-build-tools repository, users often encounter errors related to "client restriction" or requirements to build a custom "APISIX-OpenResty" (often referred to as apisix-base) [2]. This is typically required to support specific features like dynamic SSL client certificate verification, which relies on FFI (Foreign Function Interface) calls introduced in modules like lua-nginx-module to interact with OpenSSL [3][4]. If you are encountering this in a build script or error message, it is likely a result of: 1. Custom C compiler flags (-D...) used during the OpenResty/NGINX build process, which inject custom macros into the binary [5][6][7]. 2. A specific requirement for the APISIX client-control plugin, which depends on features (such as dynamic SSL verification) that are not present in standard, pre-packaged OpenResty distributions and must be enabled by compiling a custom runtime [3][2]. To resolve issues related to missing FFI functionality for APISIX, you generally need to build the apisix-base package using the official build tools provided by the APISIX community, which include the necessary patches and module integrations [1][2].

Citations:

🌐 Web query:

site:github.com/api7/apisix-build-tools "build-apisix-runtime.sh" "make package"

💡 Result:

The command "make package" is used in the context of the apisix-build-tools repository to generate installable packages (deb, rpm, or apk) for various Apache APISIX components, including the apisix-runtime [1][2]. The "build-apisix-runtime.sh" script is a internal component used by the Makefile process, not a command typically invoked directly with "make package" as an argument [3][4]. To package the APISIX runtime, you should use the make command at the root of the apisix-build-tools repository with the appropriate parameters [1][2]. Examples: For an RPM package (CentOS 7): make package type=rpm app=apisix-runtime version=1.0.0 image_base=centos image_tag=7 For a DEB package (Ubuntu 20.04): make package type=deb app=apisix-runtime version=1.0.0 The makefile orchestrates the build process, calling scripts like build-apisix-runtime.sh internally to handle compilation and packaging tasks [4]. Direct execution of build-apisix-runtime.sh is generally for debugging or custom build scenarios and does not support a "make package" subcommand [3].

Citations:

🌐 Web query:

https://raw.githubusercontent.com/api7/apisix-build-tools/master/Makefile ngx_http_ffi_client_ver

💡 Result:

The term ngx_http_ffi_client_ver does not appear as a standard identifier in the official api7/apisix-build-tools Makefile or its associated build scripts [1][2][3][4]. The apisix-build-tools project uses a set of shell scripts (such as build-apisix-base.sh and build-apisix-runtime.sh) to configure and compile OpenResty for APISIX [1][2][3]. These scripts manage module versions and build flags using variables like APISIX_BASE_VER, APISIX_RUNTIME_VER, and various module-specific version variables (e.g., lua_resty_events_ver) [2][3][5]. It is possible that ngx_http_ffi_client_ver is a misremembered or non-existent identifier, or perhaps a custom variable added in a specific, non-public, or older fork. If you are looking for OpenResty FFI (Foreign Function Interface) related identifiers, the openresty/lua-nginx-module codebase uses various FFI functions prefixed with ngx_http_lua_ffi_ (e.g., ngx_http_lua_ffi_ssl_ciphers or ngx_http_lua_ffi_ssl_get_client_hello_ext_present), but these are part of the Nginx module source code rather than the APISIX build tools' Makefile [6][7][8].

Citations:

🌐 Web query:

https://raw.githubusercontent.com/api7/apisix-build-tools/master/build-apisix-runtime.sh ngx_http_ffi_client_ver

💡 Result:

The term ngx_http_ffi_client_ver does not appear as a standard identifier, variable, or API call within the referenced apisix-build-tools scripts or broader OpenResty/APISIX ecosystems [1][2][3]. It is highly likely that this is either a typo or a misremembered variable name, as the build scripts typically define module versions using patterns like ${module_name}ver (e.g., apisix_nginx_module_ver) [1][2]. In the context of OpenResty and APISIX development, FFI (Foreign Function Interface) is commonly used to bridge Lua and C/C++ [4][5]. While there are various FFI-related functions for handling SSL/TLS client certificate verification (often named with prefixes like ngx_http_lua_kong_ffi... or related to the lua-nginx-module FFI interface) [6][7], there is no established technical identifier matching ngx_http_ffi_client_ver [6][4][7]. If you are investigating build-tool configurations for APISIX, you may be thinking of: 1. A specific module version variable defined in the scripts, such as apisix_nginx_module_ver or similar [1][2]. 2. Internal OpenResty FFI APIs used for SSL verification, which typically do not contain "client_ver" in their names [6][7]. If this was intended to refer to a specific software version check, it is recommended to verify the exact spelling against the target build script repository.

Citations:

🌐 Web query:

https://raw.githubusercontent.com/api7/apisix-build-tools/master/README.md ngx_http_ffi_client_ver

💡 Result:

The term "ngx_http_ffi_client_ver" does not refer to a standard, widely documented feature or configuration parameter in the apisix-build-tools repository or the broader OpenResty/APISIX ecosystem. The apisix-build-tools repository is primarily used for managing the build process, dependencies, and packaging of APISIX and its base OpenResty distributions (apisix-base and apisix-runtime) [1][2][3]. Its configuration files, such as build-apisix-base.sh and build-apisix-runtime.sh, handle version management for components like OpenResty, OpenSSL, and various Nginx modules, but they do not contain a parameter or variable named ngx_http_ffi_client_ver [4][5]. In the context of Nginx and OpenResty, FFI (Foreign Function Interface) is commonly used to call C functions from Lua, often prefixed with ngx_http_lua_ffi_ to denote Lua-Nginx module FFI interfaces [6][7][8]. While various FFI functions exist for SSL/TLS and upstream management, there is no evidence of an interface or variable designated as ngx_http_ffi_client_ver [9][6][7][10][8]. It is possible that this string is a typo or a custom, internal variable name not reflected in public documentation or the main codebase.

Citations:

🌐 Web query:

site:github.com/api7/apisix-build-tools "v0.1.0" "ffi" "client"

💡 Result:

There is no widely recognized, specific software component identified as a v0.1.0 FFI (Foreign Function Interface) client in authoritative technical documentation or the searched repositories [1][2][3]. While the term FFI is commonly used in contexts involving the APISIX build tools—specifically regarding how various Nginx modules or language-specific bindings interact with C-based components—the version v0.1.0 does not map to a standalone entity labeled as a "ffi client" [4][5][3]. In the scope of the api7/apisix-build-tools repository, v0.1.0 has been associated with specific module releases, such as the wasm-nginx-module [3]. It is possible that "v0.1.0 ffi client" refers to an early-stage or internal library associated with FFI-based integration (such as gRPC or Wasm modules) within the APISIX ecosystem, but no official documentation exists to define it as a singular, public-facing client tool [3][6].

Citations:

🌐 Web query:

site:github.com/api7/apisix-build-tools "ngx_http_ffi_client" OR "ffi_client"

💡 Result:

The term ngx_http_ffi_client does not refer to a standard or widely recognized component in the mainline Nginx or OpenResty ecosystem. Based on available technical evidence, it is likely a misinterpretation or a highly specific, non-standard naming convention used within internal or experimental modules, possibly related to projects using lua-resty-ffi [1][2]. Contextual findings: 1. lua-resty-ffi: This is a well-known project that provides an efficient, generic API for hybrid programming in OpenResty, allowing integration with languages like Go, Python, Rust, and others [1][2]. It defines various FFI (Foreign Function Interface) APIs for communication between OpenResty (Lua) and external runtime tasks, such as ngx_http_lua_ffi_task_poll and ngx_http_lua_ffi_respond [1]. 2. Nginx Client Modules: Mainline Nginx uses ngx_http_request_t and related structures for internal HTTP handling [3]. While experimental modules or downstream forks (like Angie) may include their own ngx_http_client APIs for managing requests, these are distinct from the FFI-based integration patterns [3]. 3. Apache APISIX: Build tools for Apache APISIX often compile custom OpenResty versions (sometimes referred to as apisix-base or apisix-runtime) that include various third-party modules (e.g., grpc-client-nginx-module) [4][5]. These modules facilitate complex interactions but do not typically expose a component literally named ngx_http_ffi_client [4]. If you are encountering this term in a specific codebase, it is likely a local or library-specific identifier for an FFI-based client implementation [1][6]. Check the specific module documentation or header files within that project for the exact definition.

Citations:

Forward ngx_http_ffi_client_ver through packaging.

ngx_http_ffi_client_ver is not defined or consumed by the Makefile or build-apisix-runtime.sh, so this command cannot select v0.2.0. Add support for the variable or remove the example.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 109 - 120, Make the documented
ngx_http_ffi_client_ver override functional by defining and forwarding it
through the packaging flow, including build-apisix-runtime.sh and the relevant
Makefile target or variable propagation. Ensure the supplied tag or branch
reaches the ngx_http_ffi_client build; otherwise remove the override example
from the README.

## Details

- `Makefile` the entrance of the packager
Expand Down
25 changes: 25 additions & 0 deletions build-apisix-runtime.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,12 @@ fi
wasm_nginx_module_ver="0.7.0"
lua_var_nginx_module_ver="v0.5.3"
lua_resty_events_ver="0.2.0"
ngx_http_ffi_client_ver=${ngx_http_ffi_client_ver:-"v0.1.0"}
if [[ ! "$ngx_http_ffi_client_ver" =~ ^[A-Za-z0-9._/-]+$ ]]; then
echo "ERROR: invalid ngx_http_ffi_client_ver: $ngx_http_ffi_client_ver" >&2
exit 1
fi
ngx_http_ffi_client_dir="ngx_http_ffi_client-${ngx_http_ffi_client_ver}"
Comment thread
shreemaan-abhishek marked this conversation as resolved.


install_openssl_3(){
Expand Down Expand Up @@ -134,6 +140,14 @@ else
lua-var-nginx-module-${lua_var_nginx_module_ver}
fi

if [ "$repo" == ngx_http_ffi_client ]; then
cp -r "$prev_workdir" "./$ngx_http_ffi_client_dir"
else
git clone --depth=1 -b "$ngx_http_ffi_client_ver" \
https://github.com/api7/ngx_http_ffi_client.git \
"$ngx_http_ffi_client_dir"
fi

cd ngx_multi_upstream_module-${ngx_multi_upstream_module_ver} || exit 1
./patch.sh ../openresty-${OPENRESTY_VERSION}
cd ..
Expand Down Expand Up @@ -165,6 +179,11 @@ else
fi


# ngx_http_ffi_client compiles against lua-nginx-module's public API, which it
# reaches through the bundled copy rather than a separate checkout.
ngx_lua_bundle_dir=$(find bundle -maxdepth 1 -type d -name 'ngx_lua-*' | head -n 1)
export NGX_HTTP_LUA_MODULE_DIR="$PWD/$ngx_lua_bundle_dir"

./configure --prefix="$OR_PREFIX" \
--with-cc-opt="-DAPISIX_RUNTIME_VER=$runtime_version $cc_opt" \
--with-ld-opt="-Wl,-rpath,$OR_PREFIX/wasmtime-c-api/lib $ld_opt" \
Expand All @@ -177,6 +196,7 @@ fi
--add-module=../wasm-nginx-module-${wasm_nginx_module_ver} \
--add-module=../lua-var-nginx-module-${lua_var_nginx_module_ver} \
--add-module=../lua-resty-events-${lua_resty_events_ver} \
--add-module=../${ngx_http_ffi_client_dir} \
--with-poll_module \
--with-pcre-jit \
--without-http_rds_json_module \
Expand Down Expand Up @@ -220,6 +240,11 @@ sudo install -d "$OR_PREFIX"/lualib/resty/events/compat/
sudo install -m 644 lualib/resty/events/compat/*.lua "$OR_PREFIX"/lualib/resty/events/compat/
cd ..

# the C module needs its FFI bindings on the runtime's lua_package_path
sudo install -d "$OR_PREFIX"/lualib/resty/
sudo install -m 644 "$ngx_http_ffi_client_dir"/lib/resty/ngx_http_ffi_client.lua \
"$OR_PREFIX"/lualib/resty/

cd "apisix-nginx-module-${apisix_nginx_module_ver}" || exit 1
sudo OPENRESTY_PREFIX="$OR_PREFIX" make install
cd ..
Expand Down
Loading