link: Die Anwendungs-Dynamikverknüpfung mit Nginx

Erfordert den Pro-Plan (oder höher) des GetPageSpeed NGINX Extras-Abonnements.

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 und 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 am Anfang von /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. August 2026.

Native C/C++-Funktionshandler für NGINX — laden Sie gemeinsame Bibliotheken und leiten Sie Anfragen direkt an kompilierten Code weiter, mit null IPC-Overhead.

Überblick

ngx_http_link_func verbindet NGINX und native C/C++-Anwendungen durch dynamische Verknüpfung. Gemeinsame Bibliotheken (.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, gemeinsamen Speicher — und Antworten ohne Serialisierung, Sockets oder Kontextwechsel schreiben kann.

Funktionen

Native Funktionsverteilung — leiten Sie jeden Standort an eine exportierte C-Funktion weiter
Gemeinsamer Speicher und Cache — rbtree-basierter Cache über mehrere Worker mit Mutex-Sperre
Thread-Pool-Auslagerung — AIO-Thread-Unterstützung für blockierende Operationen
Subrequest-Integration — Verkettung mit auth_request für Authentifizierungsabläufe
Remote-Bibliotheksladen — .so-Dateien von HTTP/HTTPS-URLs beim Start abrufen
Lebenszyklus-Hooks — Init- und Exit-Zyklus-Callbacks für Ressourcenverwaltung
Pro-Server-Eigenschaften — Konfigurationswerte von nginx.conf an Ihren Code übergeben

Schnellstart

nginx.conf:

http {
    # Optional: Gemeinsamer Speicher für den Cache über mehrere Worker
    ngx_link_func_shm_size 1m;

    server {
        listen 8080;

        # Laden Sie Ihre kompilierte Anwendung
        ngx_link_func_lib "/opt/myapp/libhandlers.so";

        # Übergeben Sie Konfigurationswerte an Ihre Anwendung
        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", "Anwendung gestartet");
}

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\":\"Hallo aus 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,
            "Token fehlt", 13
        );
        return;
    }

    // Authentifizierte Anfrage verarbeiten...
    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", "Anwendung wird beendet");
}

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: keine

Legt die Größe des gemeinsamen Speicherbereichs für den Cache und die Datenaustausch über mehrere Worker fest.

ngx_link_func_shm_size 10m;

`ngx_link_func_lib`

Kontext: server | Standard: keine

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

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

`ngx_link_func_call`

Kontext: location | Standard: keine

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: keine

Übergibt Schlüssel-Wert-Eigenschaften an die Anwendung, zugreifbar über ngx_link_func_get_prop().

ngx_link_func_add_prop "api_key" "secret123";

`ngx_link_func_download_link_lib`

Kontext: server | Standard: keine

Lädt eine gemeinsame Bibliothek von einer entfernten URL beim Start herunter. Unterstützt optionale HTTP-Header für die Authentifizierung.

# Einfacher Download
ngx_link_func_download_link_lib "https://repo.example.com/libapp.so" "/opt/myapp/libapp.so";

# Mit Authentifizierungs-Headern
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: keine

Setzt das CA-Zertifikat für HTTPS-Bibliotheks-Downloads.

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

`ngx_link_func_add_req_header`

Kontext: location | Standard: keine

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: keine

Konfiguriert die Subrequest-Weiterleitung. Erfordert NGINX, kompiliert mit --with-http_auth_request_module.

location /protected {
    ngx_link_func_subrequest "/auth";
}

Anwendungs-API

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

Lebenszyklus-Hooks

Diese reservierten Funktionsnamen werden automatisch von NGINX aufgerufen:

void ngx_link_func_init_cycle(ngx_link_func_cycle_t *cycle);  // Beim Start
void ngx_link_func_exit_cycle(ngx_link_func_cycle_t *cycle);  // Beim Herunterfahren/Neuladen

Anfrage-Kontext

Jeder Handler empfängt ngx_link_func_ctx_t *ctx mit:

Feld	Typ	Beschreibung
`req_args`	`char *`	Roher URI-Abfragetext
`req_body`	`u_char *`	Anfrage-Body
`req_body_len`	`size_t`	Länge des Anfrage-Bodys
`shared_mem`	`void *`	Zeiger auf gemeinsamen Speicher

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)`	Client-Remote-Adresse abrufen
`ngx_link_func_get_header(ctx, key, keylen)`	Anfrage-Header nach Namen abrufen
`ngx_link_func_get_query_param(ctx, key)`	Abfrageparameter 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 dem NGINX-Pool allokieren
`ngx_link_func_pcalloc(ctx, size)`	Nullinitialisiert aus dem NGINX-Pool allokieren
`ngx_link_func_strdup(ctx, src)`	Zeichenkette aus dem Pool duplizieren
Gemeinsamer Speicher
`ngx_link_func_shm_alloc(shm, size)`	Gemeinsamen Speicher allokieren
`ngx_link_func_shm_free(shm, ptr)`	Gemeinsamen Speicher 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)`	Allokieren und cachen
`ngx_link_func_cache_remove(shm, key)`	Aus dem 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

Inhaltstyp-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 ```