ngx_http_js_module

ngx_http_js_module 모듈은 njs(JavaScript 언어의 하위 집합)에서 위치와 변수 핸들러를 구현하는 데 사용합니다.

예제 구성

이 예제는 0.4.0 이후로 작동합니다.

http {
    js_import http.js;

    js_set $foo     http.foo;
    js_set $summary http.summary;
    js_set $hash    http.hash;

    resolver 10.0.0.1;

    server {
        listen 8000;

        location / {
            add_header X-Foo $foo;
            js_content http.baz;
        }

        location = /summary {
            return 200 $summary;
        }

        location = /hello {
            js_content http.hello;
        }

        # since 0.7.0
        location = /fetch {
            js_content                   http.fetch;
            js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
        }

        # since 0.7.0
        location = /crypto {
            add_header Hash $hash;
            return     200;
        }
    }
}

http.js 파일:

function foo(r) {
    r.log("hello from foo() handler");
    return "foo";
}

function summary(r) {
    var a, s, h;

    s = "JS summary\n\n";

    s += "Method: " + r.method + "\n";
    s += "HTTP version: " + r.httpVersion + "\n";
    s += "Host: " + r.headersIn.host + "\n";
    s += "Remote Address: " + r.remoteAddress + "\n";
    s += "URI: " + r.uri + "\n";

    s += "Headers:\n";
    for (h in r.headersIn) {
        s += "  header '" + h + "' is '" + r.headersIn[h] + "'\n";
    }

    s += "Args:\n";
    for (a in r.args) {
        s += "  arg '" + a + "' is '" + r.args[a] + "'\n";
    }

    return s;
}

function baz(r) {
    r.status = 200;
    r.headersOut.foo = 1234;
    r.headersOut['Content-Type'] = "text/plain; charset=utf-8";
    r.headersOut['Content-Length'] = 15;
    r.sendHeader();
    r.send("nginx");
    r.send("java");
    r.send("script");

    r.finish();
}

function hello(r) {
    r.return(200, "Hello world!");
}

// since 0.7.0
async function fetch(r) {
    let results = await Promise.all([ngx.fetch('https://nginx.org/'),
                                     ngx.fetch('https://nginx.org/en/')]);

    r.return(200, JSON.stringify(results, undefined, 4));
}

// since 0.7.0
async function hash(r) {
    let hash = await crypto.subtle.digest('SHA-512', r.headersIn.host);
    r.setReturnValue(Buffer.from(hash).toString('hex'));
}

export default {foo, summary, baz, hello, fetch, hash};

Directives

Syntax:  js_body_filter function | module.function [buffer_type=string | buffer];
Default: —
Context: location, limit_except
This directive appeared in version 0.5.2.

njs 함수를 응답 본문 필터로 설정합니다. filter 함수는 다음과 같은 인수를 포함하여 응답 본문의 각 데이터 청크에 호출됩니다.

r

HTTP 요청 객체

data

수신되는 데이터 청크는 buffer_type 값에 따라 문자열이 되거나 버퍼가 될 수 있습니다. 기본값은 문자열입니다.

flags

다음의 속성이 있는 객체:

last

부울 값이고, 데이터가 마지막 버퍼일 경우 true입니다.

filter 함수는 r.sendBuffer()를 호출하여 입력 데이터 청크의 수정된 버전을 다음 본문 필터에 전달할 수 있습니다. 예를 들어 응답 본문에서 모든 소문자를 변환하는 방법은 다음과 같습니다.

function filter(r, data, flags) {
    r.sendBuffer(data.toLowerCase(), flags);
}

필터링을 중단하려면(다음 데이터 청크는 js_body_filter를 호출하지 않고 클라이언트에 전달) r.done()을 사용합니다.

filter 함수가 응답 본문의 길이를 변경하면, js_header_filter에서 “Content-Length” 응답 헤더가 있을 시 이를 삭제하여 청크로 나뉜 전송 인코딩을 적용해야 합니다.

js_body_filter 핸들러가 그 결과를 즉시 반환하므로 동기식 작업만 지원합니다. 따라서 r.subrequest(), setTimeout()과 같은 비동기식 작업은 지원되지 않습니다.

Syntax:  js_content function | module.function;
Default: —
Context: location, limit_except

njs 함수를 위치 내용 핸들러로 설정합니다. 0.4.0 이상에서 모듈 함수를 참조할 수 있습니다.

Syntax:  js_fetch_ciphers ciphers;
Default: js_fetch_ciphers HIGH:!aNULL:!MD5;
Context: http, server, location
This directive appeared in version 0.7.0.

Fetch API를 사용하여 HTTPS 요청에 대해 활성화된 암호를 지정합니다. 이 암호는 OpenSSL 라이브러리에서 이해하는 형식으로 지정합니다.

전체 목록은 “openssl ciphers” 명령을 사용하여 확인할 수 있습니다.

Syntax:  js_fetch_protocols [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;
Context: http, server, location
This directive appeared in version 0.7.0.

Fetch API를 사용하여 HTTPS 요청에 대한 지정된 프로토콜을 활성화합니다.

Syntax:  js_fetch_trusted_certificate file;
Default: —
Context: http, server, location
This directive appeared in version 0.7.0.

Fetch API로 HTTPS 인증서를 인증하는 데 사용한 PEM 형식으로 신뢰할 수 있는 CA 인증서와 함께 file을 지정합니다.

Syntax:  js_fetch_verify_depth number;
Default: js_fetch_verify_depth 100;
Context: http, server, location
This directive appeared in version 0.7.0.

Fetch API로 HTTPS 서버 인증서 체인에 인증 깊이를 설정합니다.

Syntax:  js_header_filter function | module.function;
Default: —
Context: location, limit_except
This directive appeared in version 0.5.1.

njs 함수를 응답 헤더 필터로 설정합니다. 이 명령을 사용하면 응답 헤더의 임의의 헤더 필드를 변경할 수 있습니다.

Syntax:  js_import module.js | export_name from module.js;
Default: —
Context: http
This directive appeared in version 0.4.0.

njs에서 위치와 변수 핸들러를 구현하는 모듈을 가져옵니다. export_name을 네임스페이스로 사용하여 모듈 함수에 액세스합니다. export_name을 지정하지 않으면 모듈 이름을 네임스페이스로 사용합니다.

js_import http.js;

여기에서는 내보내기에 액세스하는 동안 모듈 이름 http를 사용합니다. 가져온 모듈이 foo()를 내보낼 경우, http.foo를 사용하여 이를 참조합니다.

여러 js_import 명령을 지정할 수 있습니다.

Syntax:	js_include file;
Default: —
Context: http

njs에서 위치와 변수 핸들러를 구현하는 파일을 지정합니다.

이 명령은 0.4.0 이후로 사용 중단되므로 대신 js_import 명령을 사용해야 합니다.

Syntax:  js_path path;
Default: —
Context: http
This directive appeared in version 0.3.0.

njs 모듈에 추가 경로를 설정합니다.

Syntax:  js_set $variable function | module.function;
Default: —
Context: http

지정된 variable에 njs 함수를 설정합니다. 0.4.0 이상에서 모듈 함수를 참조할 수 있습니다.

특정 요청에 대해 처음으로 변수를 참조했을 때 이 함수를 호출합니다. 정확한 시점은 변수를 참조하는 단계에 따라 달라집니다. 이는 변수 평가와 관련이 없는 일부 로직을 실행하는 데 사용할 수 있습니다. 예를 들어 변수를 log_format 명령에서만 참조한다면 로그 단계 전까지는 핸들러가 실행되지 않습니다. 이 핸들러는 요청을 해제하기 직전에 약간의 정리를 하는 데 사용합니다.

js_set 핸들러는 그 결과를 즉시 반환하므로 동기식 작업만 지원합니다. 따라서 r.subrequest(), setTimeout()과 같은 비동기식 작업은 지원되지 않습니다.

Syntax:  js_var $variable [value];
Default: —
Context: http
This directive appeared in version 0.5.3.

쓰기 가능한 변수를 선언합니다. 이 값에는 텍스트, 변수 및 그 두 가지의 조합을 포함할 수 있습니다. set 명령으로 생성된 변수와 달리, 이 변수는 리디렉션 이후에 덮어쓰지 않습니다.

요청 인수

각 HTTP njs 핸들러는 한 개의 인수, 즉 요청 객체를 받습니다.