link: Die Anwendungs-dynamische Verknüpfung mit Nginx

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

RedHat Enterprise Linux 7, 8, 9 und 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 und Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 and Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-link

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-link

Aktivieren Sie das Modul, indem Sie Folgendes oben in /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_link_func_module.so;

Dieses Dokument beschreibt nginx-module-link v3.2.6 veröffentlicht am 12. Aug. 2026.

Native C/C++-Funktionshandler für NGINX — laden Sie Shared Libraries und leiten Sie Anfragen direkt an kompilierten Code weiter, ohne IPC-Overhead.

Übersicht

ngx_http_link_func überbrückt NGINX und native C/C++-Anwendungen durch dynamische Verknüpfung. Shared Libraries (.so-Dateien) werden beim Serverstart geladen, und HTTP-Anfragen werden direkt an exportierte C-Funktionen weitergeleitet, die innerhalb des NGINX-Worker-Prozesses ausgeführt werden.

Das bedeutet, dass Ihr C-Code direkten Zugriff auf NGINX-Interna hat — Anfrage-Header, URI-Argumente, Anfrage-Body, Shared Memory — und Antworten ohne Serialisierung, Sockets oder Kontextwechsel schreiben kann.

Funktionen

Native Funktionsweiterleitung — leiten Sie jeden Location an eine exportierte C-Funktion weiter
Shared Memory und Cache — Worker-übergreifender rbtree-basierter Cache mit Mutex-Sperren
Thread-Pool-Offloading — AIO-Thread-Unterstützung für blockierende Operationen
Subrequest-Integration — Verkettung mit auth_request für Authentifizierungsabläufe
Remote-Library-Laden — Abrufen von .so-Dateien von HTTP/HTTPS-URLs beim Start
Lifecycle-Hooks — Init- und Exit-Cycle-Callbacks für Ressourcenverwaltung
Per-Server-Eigenschaften — Übergeben Sie Konfigurationswerte aus nginx.conf an Ihren Code

Schnellstart

nginx.conf:

http {
    # Optional: shared memory for cross-worker cache
    ngx_link_func_shm_size 1m;

    server {
        listen 8080;

        # Load your compiled application
        ngx_link_func_lib "/opt/myapp/libhandlers.so";

        # Pass config values to your application
        ngx_link_func_add_prop "db_host" "localhost:5432";

        location /api/greeting {
            ngx_link_func_call "handle_greeting";
        }

        location /api/users {
            ngx_link_func_call "handle_users";
        }
    }
}

Ihre Anwendung (handlers.c):

#include <ngx_link_func_module.h>

void ngx_link_func_init_cycle(ngx_link_func_cycle_t *cycle) {
    ngx_link_func_cyc_log(info, cycle, "%s", "Application started");
}

void handle_greeting(ngx_link_func_ctx_t *ctx) {
    ngx_link_func_write_resp(
        ctx, 200, "200 OK",
        ngx_link_func_content_type_json,
        "{\"message\":\"Hello from C\"}", 25
    );
}

void handle_users(ngx_link_func_ctx_t *ctx) {
    const char *token = ngx_link_func_get_query_param(ctx, "token");

    if (!token) {
        ngx_link_func_write_resp(
            ctx, 401, "401 Unauthorized",
            ngx_link_func_content_type_plaintext,
            "Missing token", 13
        );
        return;
    }

    // Process authenticated request...
    ngx_link_func_write_resp(
        ctx, 200, "200 OK",
        ngx_link_func_content_type_json,
        "{\"users\":[]}", 12
    );
}

void ngx_link_func_exit_cycle(ngx_link_func_cycle_t *cycle) {
    ngx_link_func_cyc_log(info, cycle, "%s", "Application shutting down");
}

Erstellen und Bereitstellen:

gcc -shared -o libhandlers.so -fPIC handlers.c
sudo cp libhandlers.so /opt/myapp/
sudo nginx -s reload

Direktiven

`ngx_link_func_shm_size`

Kontext: main | Standard: none

Legt die Größe der Shared-Memory-Zone für Worker-übergreifenden Cache und Datenfreigabe fest.

ngx_link_func_shm_size 10m;

`ngx_link_func_lib`

Kontext: server | Standard: none

Lädt eine Shared Library für den Server-Block. Mehrere Server-Blöcke können dieselbe Library laden, um Speicher gemeinsam zu nutzen.

ngx_link_func_lib "/opt/myapp/libhandlers.so";

`ngx_link_func_call`

Kontext: location | Standard: none

Leitet Anfragen an eine exportierte C-Funktion nach Namen weiter.

location /api/data {
    ngx_link_func_call "handle_data";
}

`ngx_link_func_add_prop`

Kontext: server | Standard: none

Übergibt Key-Value-Eigenschaften an die Anwendung, zugänglich über ngx_link_func_get_prop().

ngx_link_func_add_prop "api_key" "secret123";

`ngx_link_func_download_link_lib`

Kontext: server | Standard: none

Lädt eine Shared Library beim Start von einer Remote-URL herunter. Unterstützt optionale HTTP-Header für die Authentifizierung.

## Basic download
ngx_link_func_download_link_lib "https://repo.example.com/libapp.so" "/opt/myapp/libapp.so";

## With authentication headers
ngx_link_func_download_link_lib "https://repo.example.com/libapp.so"
    "Authorization:Bearer TOKEN\r\n"
    "/opt/myapp/libapp.so";

`ngx_link_func_ca_cert`

Kontext: server | Standard: none

Legt das CA-Zertifikat für HTTPS-Library-Downloads fest.

ngx_link_func_ca_cert "/etc/ssl/certs/ca-certificates.crt";

`ngx_link_func_add_req_header`

Kontext: location | Standard: none

Fügt einen Anfrage-Header hinzu, typischerweise verwendet, um NGINX-Variablen an Subrequests zu übergeben.

ngx_link_func_add_req_header "X-Real-IP" "$remote_addr";

`ngx_link_func_subrequest`

Kontext: location | Standard: none

Konfiguriert das Subrequest-Routing. Erfordert NGINX kompiliert mit --with-http_auth_request_module.

location /protected {
    ngx_link_func_subrequest "/auth";
}

Anwendungs-API

Binden Sie <ngx_link_func_module.h> in Ihre Anwendung ein. Der Header stellt die vollständige C-API bereit.

Lifecycle-Hooks

Diese reservierten Funktionsnamen werden automatisch von NGINX aufgerufen:

void ngx_link_func_init_cycle(ngx_link_func_cycle_t *cycle);  // On startup
void ngx_link_func_exit_cycle(ngx_link_func_cycle_t *cycle);  // On shutdown/reload

Anfrage-Kontext

Jeder Handler erhält ngx_link_func_ctx_t *ctx mit:

Feld	Typ	Beschreibung
`req_args`	`char *`	Roher URI-Query-String
`req_body`	`u_char *`	Anfrage-Body
`req_body_len`	`size_t`	Länge des Anfrage-Bodys
`shared_mem`	`void *`	Shared-Memory-Zeiger

Funktionen

Funktion	Beschreibung
Antwort
`ngx_link_func_write_resp(ctx, status, status_line, content_type, body, len)`	HTTP-Antwort schreiben
`ngx_link_func_write_resp_l(ctx, status, status_line, sl_len, ct, ct_len, body, len)`	Antwort schreiben (explizite Längen)
Anfragedaten
`ngx_link_func_get_uri(ctx, &str)`	Anfrage-URI abrufen
`ngx_link_func_get_remote_addr(ctx)`	Remote-Adresse des Clients abrufen
`ngx_link_func_get_header(ctx, key, keylen)`	Anfrage-Header nach Namen abrufen
`ngx_link_func_get_query_param(ctx, key)`	Query-Parameter nach Schlüssel abrufen
`ngx_link_func_get_prop(ctx, key, keylen)`	Server-Eigenschaft abrufen
Header
`ngx_link_func_add_header_in(ctx, key, klen, val, vlen)`	Eingabe-Header hinzufügen
`ngx_link_func_add_header_out(ctx, key, klen, val, vlen)`	Ausgabe-Header hinzufügen
Speicher
`ngx_link_func_palloc(ctx, size)`	Aus NGINX-Pool zuweisen
`ngx_link_func_pcalloc(ctx, size)`	Genullt aus NGINX-Pool zuweisen
`ngx_link_func_strdup(ctx, src)`	String aus Pool duplizieren
Shared Memory
`ngx_link_func_shm_alloc(shm, size)`	Shared Memory zuweisen
`ngx_link_func_shm_free(shm, ptr)`	Shared Memory freigeben
`ngx_link_func_shmtx_lock(shm)`	Mutex erwerben
`ngx_link_func_shmtx_unlock(shm)`	Mutex freigeben
`ngx_link_func_shmtx_trylock(shm)`	Versuchen, Mutex zu erwerben
Cache
`ngx_link_func_cache_get(shm, key)`	Gecachten Wert abrufen
`ngx_link_func_cache_put(shm, key, value)`	Gecachten Wert speichern
`ngx_link_func_cache_new(shm, key, size)`	Zuweisen und cachen
`ngx_link_func_cache_remove(shm, key)`	Aus Cache entfernen
Protokollierung
`ngx_link_func_log_debug/info/warn/err(ctx, msg)`	Nachricht protokollieren
`ngx_link_func_log(level, ctx, fmt, ...)`	Formatierte Nachricht protokollieren

Content-Type-Konstanten

ngx_link_func_content_type_plaintext  // "text/plain"
ngx_link_func_content_type_html       // "text/html; charset=utf-8"
ngx_link_func_content_type_json       // "application/json"
ngx_link_func_content_type_jsonp      // "application/javascript"
ngx_link_func_content_type_xformencoded // "application/x-www-form-urlencoded"

Linux

gcc -shared -o libmyapp.so -fPIC myapp.c

macOS

clang -dynamiclib -o libmyapp.dylib -fPIC myapp.c -Wl,-undefined,dynamic_lookup ```

Geben Sie NUR das übersetzte Markdown zurück.