Mercurial > hg > nginx-site

comparison xml/ru/docs/njs/reference.xml @ 2246:32ba43abf9cd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Renamed njs API, njs Changes.
author Yaroslav Zhuravlev <yar@nginx.com>
date Mon, 24 Sep 2018 19:24:04 +0300
parents xml/ru/docs/njs/njs_api.xml@467aef18bf12
children 65c6c1ee3c78
comparison
equal deleted inserted replaced
2245:87a0e2c73a25 2246:32ba43abf9cd
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8
9 <article name="Справочник"
10 link="/ru/docs/njs/reference.html"
11 lang="ru"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 <link doc="index.xml">njs</link> предоставляет объекты, методы и свойства
18 для расширения функциональности nginx.
19 </para>
20
21 </section>
22
23
24 <section id="http" name="HTTP">
25
26 <para>
27 Объект <literal>HTTP</literal> доступен только в
28 модуле <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link>.
29 Все строки в объекте <literal>HTTP</literal> являются
30 <link id="strings">байтовыми строками</link>.
31 </para>
32
33
34 <section id="http_request" name="Запрос">
35
36 <para>
37 <list type="tag">
38
39 <tag-name><literal>r.args{}</literal></tag-name>
40 <tag-desc>
41 объект аргументов запроса, только чтение
42 </tag-desc>
43
44 <tag-name><literal>r.error(<value>строка</value>)</literal></tag-name>
45 <tag-desc>
46 записывает <literal>строку</literal> в лог-файл ошибок
47 на уровне лога <literal>error</literal>
48 </tag-desc>
49
50 <tag-name><literal>r.finish()</literal></tag-name>
51 <tag-desc>
52 завершает отправку ответа клиенту
53 </tag-desc>
54
55 <tag-name><literal>r.headersIn{}</literal></tag-name>
56 <tag-desc>
57 объект исходящих заголовков, только чтение.
58 <para>
59 Например, доступ к заголовку <literal>Header-Name</literal>
60 можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal>
61 или <literal>headers.Header_name</literal>
62 </para>
63 </tag-desc>
64
65 <tag-name><literal>r.headersOut{}</literal></tag-name>
66 <tag-desc>
67 объект исходящих заголовков, доступно для записи.
68 <para>
69 Например, доступ к заголовку <literal>Header-Name</literal>
70 можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal>
71 или <literal>headers.Header_name</literal>
72 </para>
73 </tag-desc>
74
75 <tag-name><literal>r.httpVersion</literal></tag-name>
76 <tag-desc>
77 версия HTTP, только чтение
78 </tag-desc>
79
80 <tag-name><literal>r.log(<value>строка</value>)</literal></tag-name>
81 <tag-desc>
82 записывает <literal>строку</literal> в лог-файл ошибок
83 на уровне лога <literal>info</literal>
84 </tag-desc>
85
86 <tag-name><literal>r.method</literal></tag-name>
87 <tag-desc>
88 HTTP метод, только чтение
89 </tag-desc>
90
91 <tag-name><literal>r.parent</literal></tag-name>
92 <tag-desc>
93 ссылается на родительский объект запроса
94 </tag-desc>
95
96 <tag-name><literal>r.remoteAddress</literal></tag-name>
97 <tag-desc>
98 адрес клиента, только чтение
99 </tag-desc>
100
101 <tag-name><literal>r.requestBody</literal></tag-name>
102 <tag-desc>
103 хранит тело запроса, только чтение
104 </tag-desc>
105
106 <tag-name><literal>r.responseBody</literal></tag-name>
107 <tag-desc>
108 хранит тело ответа <link id="subrequest">подзапроса</link>, только чтение
109 </tag-desc>
110
111 <tag-name><literal>r.return(код[, строка])</literal></tag-name>
112 <tag-desc>
113 отправляет
114 клиенту полный ответ с указанным <literal>кодом</literal>
115 <para>
116 Можно задать или URL перенаправления
117 (для кодов 301, 302, 303, 307 и 308),
118 или текст тела ответа (для остальных кодов) в качестве второго аргумента
119 </para>
120 </tag-desc>
121
122 <tag-name><literal>r.send(<value>строка</value>)</literal></tag-name>
123 <tag-desc>
124 отправляет часть тела ответа клиенту
125 </tag-desc>
126
127 <tag-name><literal>r.sendHeader()</literal></tag-name>
128 <tag-desc>
129 отправляет заголовок HTTP клиенту
130 </tag-desc>
131
132 <tag-name><literal>r.status</literal></tag-name>
133 <tag-desc>
134 статус, доступно для записи
135 </tag-desc>
136
137 <tag-name><literal>req.variables{}</literal></tag-name>
138 <tag-desc>
139 объект переменных nginx, только чтение
140 </tag-desc>
141
142 <tag-name><literal>r.warn(<value>строка</value>)</literal></tag-name>
143 <tag-desc>
144 записывает <literal>строку</literal> в лог-файл ошибок
145 на уровне лога <literal>warning</literal>
146 </tag-desc>
147
148 <tag-name><literal>r.uri</literal></tag-name>
149 <tag-desc>
150 текущий URI, только чтение
151 </tag-desc>
152
153 <tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[,
154 <value>options</value>[, <value>callback</value>]])</literal></tag-name>
155 <tag-desc>
156 создаёт подзапрос с заданными <literal>uri</literal> и
157 <literal>options</literal> и
158 устанавливает необязательный <literal>callback</literal> завершения.
159
160 <para>
161 Если <literal>options</literal> является строкой, то в ней
162 содержится срока аргументов подзапроса.
163 В противном случае ожидается, что <literal>options</literal> является объектом
164 со следующими ключами:
165
166 <list type="tag">
167 <tag-name><literal>args</literal></tag-name>
168 <tag-desc>
169 строка с аргументами
170 </tag-desc>
171
172 <tag-name><literal>body</literal></tag-name>
173 <tag-desc>
174 тело запроса
175 </tag-desc>
176
177 <tag-name><literal>method</literal></tag-name>
178 <tag-desc
179 >метод HTTP
180 </tag-desc>
181
182 </list>
183 </para>
184
185 <para>
186 <literal>callback</literal> получает
187 объект ответа подзапроса с методами и свойствами,
188 идентичными родительскому объекту запроса.
189 </para>
190 </tag-desc>
191
192 </list>
193 </para>
194
195 </section>
196
197 </section>
198
199
200 <section id="stream" name="Stream">
201
202 <para>
203 Объект <literal>stream</literal> доступен только в
204 модуле
205 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>.
206 Все строки в объекте <literal>stream</literal> являются
207 <link id="strings">байтовыми строками</link>.
208 </para>
209
210
211 <section id="stream_session" name="Сессия">
212
213 <para>
214 <list type="tag">
215
216 <tag-name><literal>s.remoteAddress</literal></tag-name>
217 <tag-desc>
218 адрес клиента, только чтение
219 </tag-desc>
220
221 <tag-name><literal>s.eof</literal></tag-name>
222 <tag-desc>
223 логическое свойство,
224 true, если текущий буфер является последним буфером,
225 только чтение
226 </tag-desc>
227
228 <tag-name><literal>s.fromUpstream</literal></tag-name>
229 <tag-desc>
230 логическое свойство,
231 true, если текущий буфер является буфером от проксируемого сервера к клиенту,
232 только чтение
233 </tag-desc>
234
235 <tag-name><literal>s.buffer</literal></tag-name>
236 <tag-desc>
237 текущий буфер, доступен для записи
238 </tag-desc>
239
240 <tag-name><literal>s.variables{}</literal></tag-name>
241 <tag-desc>
242 объект переменных nginx, только чтение
243 </tag-desc>
244
245 <tag-name><literal>s.OK</literal></tag-name>
246 <tag-desc>
247 код <literal>OK</literal>
248 </tag-desc>
249
250 <tag-name><literal>s.DECLINED</literal></tag-name>
251 <tag-desc>
252 код <literal>DECLINED</literal>
253 </tag-desc>
254
255 <tag-name><literal>s.AGAIN</literal></tag-name>
256 <tag-desc>
257 код <literal>AGAIN</literal>
258 </tag-desc>
259
260 <tag-name><literal>s.ERROR</literal></tag-name>
261 <tag-desc>
262 код <literal>ERROR</literal>
263 </tag-desc>
264
265 <tag-name><literal>s.ABORT</literal></tag-name>
266 <tag-desc>
267 код <literal>ABORT</literal>
268 </tag-desc>
269
270 <tag-name><literal>s.log(<value>строка</value>)</literal></tag-name>
271 <tag-desc>
272 записывает отправленную <value>строку</value> в лог-файл ошибок
273 на уровне лога <literal>info</literal>
274 </tag-desc>
275
276 <tag-name><literal>s.warn(<value>строка</value>)</literal></tag-name>
277 <tag-desc>
278 записывает отправленную <literal>строку</literal> в лог-файл ошибок
279 на уровне лога <literal>warning</literal>
280 </tag-desc>
281
282 <tag-name><literal>s.error(<value>строка</value>)</literal></tag-name>
283 <tag-desc>
284 записывает отправленную <literal>строку</literal> в лог-файл ошибок
285 на уровне лога <literal>error</literal>
286 </tag-desc>
287
288 </list>
289 </para>
290
291 </section>
292
293 </section>
294
295
296 <section id="example" name="Примеры">
297
298
299 <section id="example_urldecode" name="Декодирование URL">
300
301 <para>
302 <example>
303 js_include urldecode.js;
304
305 js_set $decoded_foo decoded_foo;
306 </example>
307 </para>
308
309 <para>
310 Файл <path>urldecode.js</path>:
311 <example>
312 function decoded_foo(r) {
313 return decodeURIComponent(r.args.foo);
314 }
315 </example>
316 </para>
317
318 </section>
319
320
321 <section id="example_urlencode" name="Кодирование URL">
322
323 <para>
324 <example>
325 js_include urlencode.js;
326
327 js_set $encoded_foo encoded_foo;
328 ...
329
330 location / {
331 proxy_pass http://example.com?foo=$encoded_foo;
332 }
333 </example>
334 </para>
335
336 <para>
337 Файл <path>urlencode.js</path>:
338 <example>
339 function encoded_foo(r) {
340 return encodeURIComponent('foo &amp; bar?');
341 }
342 </example>
343 </para>
344
345 </section>
346
347
348 <section id="example_fast_response" name="Возврат самого быстрого ответа от прокси">
349
350 <para>
351 <example>
352 js_include fastresponse.js;
353
354 location /start {
355 js_content content;
356 }
357
358 location /foo {
359 proxy_pass http://backend1;
360 }
361
362 location /bar {
363 proxy_pass http://backend2;
364 }
365 </example>
366 </para>
367
368 <para>
369 Файл <path>fastresponse.js</path>:
370 <example>
371 function content(r) {
372 var n = 0;
373
374 function done(res) {
375 if (n++ == 0) {
376 r.return(res.status, res.responseBody);
377 }
378 }
379
380 r.subrequest('/foo', r.variables.args, done);
381 r.subrequest('/bar', r.variables.args, done);TBD
382 }
383 </example>
384 </para>
385
386 </section>
387
388
389 <section id="example_jwt" name="Создание HS JWT">
390
391 <para>
392 <example>
393 js_include hs_jwt.js;
394
395 js_set $jwt jwt;
396 </example>
397 </para>
398
399 <para>
400 Файл <path>hs_jwt.js</path>:
401 <example>
402 function create_hs256_jwt(claims, key, valid) {
403 var header = { "typ" : "JWT", "alg" : "HS256", "exp" : Date.now() + valid };
404
405 var s = JSON.stringify(header).toBytes().toString('base64url') + '.'
406 + JSON.stringify(claims).toBytes().toString('base64url');
407
408 var h = require('crypto').createHmac('sha256', key);
409
410 return s + '.' + h.update(s).digest().toString('base64url');
411 }
412
413 function jwt(r) {
414 var claims = {
415 "iss" : "nginx",
416 "sub" : "alice",
417 "foo" : 123,
418 "bar" : "qq",
419 "zyx" : false
420 };
421
422 return create_hs256_jwt(claims, 'foo', 600);
423 }
424 </example>
425 </para>
426
427 </section>
428
429
430 <section id="example_subrequest" name="Доступ к API при помощи подзапроса">
431
432 <para>
433 <example>
434 js_include subrequest.js;
435
436 keyval_zone zone=foo:10m;
437 ...
438
439 location /keyval {
440 js_content set_keyval;
441 }
442
443 location /version {
444 js_content version;
445 }
446
447 location /api {
448 api write=on;
449 }
450 </example>
451 </para>
452
453 <para>
454 Файл <path>subrequest.js</path>:
455 <example>
456 function set_keyval(r) {
457 r.subrequest('/api/3/http/keyvals/foo',
458 { method: 'POST',
459 body: JSON.stringify({ foo: 789, bar: "ss dd 00" })},
460
461 function(res) {
462 if (res.status >= 300) {
463 r.return(res.status, res.responseBody);
464 return;
465 }
466 r.return(500);
467 });
468 }
469
470 function version(r) {
471 r.subrequest('/api/3/nginx', { method: 'GET' }, function(res) {
472 if (res.status != 200) {
473 r.return(res.status);
474 return;
475 }
476
477 var json = JSON.parse(res.responseBody);
478 r.return(200, json.version);
479 });
480 }
481 </example>
482 </para>
483
484 </section>
485
486
487 <section id="example_secure_link" name="Создание хэша secure_link">
488
489 <para>
490 <example>
491 js_include hash.js;
492
493 js_set $new_foo create_secure_link;
494 ...
495
496 location / {
497 secure_link $cookie_foo;
498 secure_link_md5 "$uri mykey";
499 ...
500 }
501
502 location @login {
503 add_header Set-Cookie "foo=$new_foo; Max-Age=60";
504 return 302 /;
505 }
506 </example>
507 </para>
508
509 <para>
510 Файл <path>hash.js</path>:
511 <example>
512 function create_secure_link(r) {
513 return require('crypto').createHash('md5')
514 .update(r.uri).update(" mykey")
515 .digest('base64url');
516 }
517 </example>
518 </para>
519
520 </section>
521
522 </section>
523
524 </article>
525