link: A vinculação dinâmica de aplicações com o Nginx

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 e 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

Habilite o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_link_func_module.so;

Este documento descreve o nginx-module-link v3.2.6 lançado em 12 de agosto de 2026.

Handlers de funções nativas em C/C++ para o NGINX — carregue bibliotecas compartilhadas e encaminhe requisições diretamente para código compilado, sem overhead de IPC.

Visão geral

O ngx_http_link_func faz a ponte entre o NGINX e aplicações nativas em C/C++ por meio de vinculação dinâmica. Bibliotecas compartilhadas (arquivos .so) são carregadas na inicialização do servidor, e as requisições HTTP são despachadas diretamente para funções C exportadas em execução dentro do processo worker do NGINX.

Isso significa que seu código C tem acesso direto aos internos do NGINX — cabeçalhos de requisição, argumentos de URI, corpo da requisição, memória compartilhada — e pode escrever respostas sem serialização, sockets ou trocas de contexto.

Recursos

Despacho de funções nativas — encaminhe qualquer location para uma função C exportada
Memória compartilhada e cache — cache baseado em rbtree entre workers com bloqueio por mutex
Offloading para thread pool — suporte a threads AIO para operações bloqueantes
Integração com subrequest — encadeie com auth_request para fluxos de autenticação
Carregamento remoto de bibliotecas — baixe arquivos .so de URLs HTTP/HTTPS na inicialização
Hooks de ciclo de vida — callbacks de init e exit do ciclo para gerenciamento de recursos
Propriedades por server — passe valores de configuração do nginx.conf para o seu código

Início rápido

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";
        }
    }
}

Sua aplicação (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");
}

Compilar e implantar:

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

Diretivas

`ngx_link_func_shm_size`

Contexto: main | Padrão: nenhum

Define o tamanho da zona de memória compartilhada para cache entre workers e compartilhamento de dados.

ngx_link_func_shm_size 10m;

`ngx_link_func_lib`

Contexto: server | Padrão: nenhum

Carrega uma biblioteca compartilhada para o bloco server. Vários blocos server podem carregar a mesma biblioteca para compartilhar memória.

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

`ngx_link_func_call`

Contexto: location | Padrão: nenhum

Encaminha requisições para uma função C exportada por nome.

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

`ngx_link_func_add_prop`

Contexto: server | Padrão: nenhum

Passa propriedades de chave-valor para a aplicação, acessíveis via ngx_link_func_get_prop().

ngx_link_func_add_prop "api_key" "secret123";

`ngx_link_func_download_link_lib`

Contexto: server | Padrão: nenhum

Baixa uma biblioteca compartilhada de uma URL remota na inicialização. Suporta cabeçalhos HTTP opcionais para autenticação.

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

Contexto: server | Padrão: nenhum

Define o certificado CA para downloads de bibliotecas via HTTPS.

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

`ngx_link_func_add_req_header`

Contexto: location | Padrão: nenhum

Adiciona um cabeçalho de requisição, normalmente usado para passar variáveis do NGINX para subrequests.

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

`ngx_link_func_subrequest`

Contexto: location | Padrão: nenhum

Configura o roteamento de subrequest. Requer o NGINX compilado com --with-http_auth_request_module.

location /protected {
    ngx_link_func_subrequest "/auth";
}

API da aplicação

Inclua <ngx_link_func_module.h> na sua aplicação. O header fornece a API C completa.

Hooks de ciclo de vida

Estes nomes de função reservados são chamados automaticamente pelo NGINX:

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

Contexto da requisição

Todo handler recebe ngx_link_func_ctx_t *ctx com:

Campo	Tipo	Descrição
`req_args`	`char *`	String de consulta bruta da URI
`req_body`	`u_char *`	Corpo da requisição
`req_body_len`	`size_t`	Comprimento do corpo da requisição
`shared_mem`	`void *`	Ponteiro para memória compartilhada

Funções

Função	Descrição
Resposta
`ngx_link_func_write_resp(ctx, status, status_line, content_type, body, len)`	Escreve a resposta HTTP
`ngx_link_func_write_resp_l(ctx, status, status_line, sl_len, ct, ct_len, body, len)`	Escreve a resposta (comprimentos explícitos)
Dados da requisição
`ngx_link_func_get_uri(ctx, &str)`	Obtém a URI da requisição
`ngx_link_func_get_remote_addr(ctx)`	Obtém o endereço remoto do cliente
`ngx_link_func_get_header(ctx, key, keylen)`	Obtém o cabeçalho da requisição por nome
`ngx_link_func_get_query_param(ctx, key)`	Obtém o parâmetro de consulta por chave
`ngx_link_func_get_prop(ctx, key, keylen)`	Obtém a propriedade do server
Cabeçalhos
`ngx_link_func_add_header_in(ctx, key, klen, val, vlen)`	Adiciona cabeçalho de entrada
`ngx_link_func_add_header_out(ctx, key, klen, val, vlen)`	Adiciona cabeçalho de saída
Memória
`ngx_link_func_palloc(ctx, size)`	Aloca do pool do NGINX
`ngx_link_func_pcalloc(ctx, size)`	Aloca zerado do pool do NGINX
`ngx_link_func_strdup(ctx, src)`	Duplica string do pool
Memória compartilhada
`ngx_link_func_shm_alloc(shm, size)`	Aloca memória compartilhada
`ngx_link_func_shm_free(shm, ptr)`	Libera memória compartilhada
`ngx_link_func_shmtx_lock(shm)`	Adquire mutex
`ngx_link_func_shmtx_unlock(shm)`	Libera mutex
`ngx_link_func_shmtx_trylock(shm)`	Tenta adquirir mutex
Cache
`ngx_link_func_cache_get(shm, key)`	Obtém valor em cache
`ngx_link_func_cache_put(shm, key, value)`	Armazena valor em cache
`ngx_link_func_cache_new(shm, key, size)`	Aloca e armazena em cache
`ngx_link_func_cache_remove(shm, key)`	Remove do cache
Logging
`ngx_link_func_log_debug/info/warn/err(ctx, msg)`	Registra mensagem
`ngx_link_func_log(level, ctx, fmt, ...)`	Registra mensagem formatada

Constantes de Content Type

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

Retorne APENAS o Markdown traduzido.