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 핸들러는 한 개의 인수, 즉 요청 객체를 받습니다.