Mercurial > hg > nginx-site

comparison xml/en/docs/njs/njs_api.xml @ 2175:cd4889fdcfa4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Moved njs HTTP and Stream API to a separate page.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 05 Jun 2018 18:22:00 +0300
parents
children 95b406f1f347
comparison
equal deleted inserted replaced
2174:3b782a679237 2175:cd4889fdcfa4
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="njs API"
10 link="/en/docs/njs/njs_api.html"
11 lang="en"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 <link doc="../njs_about.xml">njs</link> provides objects, methods and properties
18 for extending nginx functionality.
19 </para>
20
21 </section>
22
23
24 <section id="http" name="HTTP">
25
26 <para>
27 The <literal>HTTP</literal> objects are available only in the
28 <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module.
29 </para>
30
31
32 <section id="http_request" name="Request">
33
34 <para>
35 <list type="tag">
36
37 <tag-name><literal>req.uri</literal></tag-name>
38 <tag-desc>
39 current URI in a request, read-only
40 </tag-desc>
41
42 <tag-name><literal>req.method</literal></tag-name>
43 <tag-desc>
44 request method, read-only
45 </tag-desc>
46
47 <tag-name><literal>req.httpVersion</literal></tag-name>
48 <tag-desc>
49 HTTP version, read-only
50 </tag-desc>
51
52 <tag-name><literal>req.remoteAddress</literal></tag-name>
53 <tag-desc>
54 client address, read-only
55 </tag-desc>
56
57 <tag-name><literal>req.headers{}</literal></tag-name>
58 <tag-desc>
59 request headers object, read-only.
60 <para>
61 For example, the <literal>Header-Name</literal> header
62 can be accessed with the syntax <literal>headers['Header-Name']</literal>
63 or <literal>headers.Header_name</literal>
64 </para>
65 </tag-desc>
66
67 <tag-name><literal>req.args{}</literal></tag-name>
68 <tag-desc>
69 request arguments object, read-only
70 </tag-desc>
71
72 <tag-name><literal>request.variables{}</literal></tag-name>
73 <tag-desc>
74 nginx variables object, read-only
75 </tag-desc>
76
77 <tag-name><literal>req.response</literal></tag-name>
78 <tag-desc>
79 the <link id="http_response">response</link> object (0.2.0), read-only
80 </tag-desc>
81
82 <tag-name><literal>req.log(<value>string</value>)</literal></tag-name>
83 <tag-desc>
84 writes a <literal>string</literal> to the error log
85 on the <literal>info</literal> level of logging
86 </tag-desc>
87
88 <tag-name><literal>req.warn(<value>string</value>)</literal></tag-name>
89 <tag-desc>
90 writes a <literal>string</literal> to the error log
91 on the <literal>warning</literal> level of logging (0.2.0)
92 </tag-desc>
93
94 <tag-name><literal>req.error(<value>string</value>)</literal></tag-name>
95 <tag-desc>
96 writes a <literal>string</literal> to the error log
97 on the <literal>error</literal> level of logging (0.2.0)
98 </tag-desc>
99
100 <tag-name id="subrequest"><literal>req.subrequest(<value>uri</value>[,
101 <value>options</value>[, <value>callback</value>]])</literal></tag-name>
102 <tag-desc>
103 creates a subrequest with the given <literal>uri</literal> and
104 <literal>options</literal>, and installs
105 an optional completion <literal>callback</literal> (0.2.0).
106
107 <para>
108 If <literal>options</literal> is a string, then it
109 holds the subrequest arguments string.
110 Otherwise, <literal>options</literal> is expected to be
111 an object with the following keys:
112
113 <list type="tag">
114 <tag-name><literal>args</literal></tag-name>
115 <tag-desc>
116 arguments string
117 </tag-desc>
118
119 <tag-name><literal>body</literal></tag-name>
120 <tag-desc>
121 request body
122 </tag-desc>
123
124 <tag-name><literal>method</literal></tag-name>
125 <tag-desc>
126 HTTP method
127 </tag-desc>
128 </list>
129 </para>
130
131 <para>
132 The completion <literal>callback</literal>
133 receives a <link id="http_reply_object">reply</link> object.
134 </para>
135 </tag-desc>
136
137 </list>
138 </para>
139
140 </section>
141
142
143 <section id="http_response" name="Response">
144
145 <para>
146 <list type="tag">
147
148 <tag-name><literal>res.status</literal></tag-name>
149 <tag-desc>
150 response status, writable
151 </tag-desc>
152
153 <tag-name><literal>res.headers{}</literal></tag-name>
154 <tag-desc>
155 response headers object
156 </tag-desc>
157
158 <tag-name><literal>res.contentType</literal></tag-name>
159 <tag-desc>
160 the response <header>Content-Type</header> header field value, writable
161 </tag-desc>
162
163 <tag-name><literal>res.contentLength</literal></tag-name>
164 <tag-desc>
165 the response <header>Content-Length</header> header field value, writable
166 </tag-desc>
167
168 <tag-name><literal>res.sendHeader()</literal></tag-name>
169 <tag-desc>
170 sends the HTTP header to the client
171 </tag-desc>
172
173 <tag-name><literal>res.send(<value>string</value>)</literal></tag-name>
174 <tag-desc>
175 sends a part of the response body to the client
176 </tag-desc>
177
178 <tag-name><literal>res.finish()</literal></tag-name>
179 <tag-desc>
180 finishes sending a response to the client
181 </tag-desc>
182
183 <tag-name><literal>res.return(status[, string])</literal></tag-name>
184 <tag-desc>
185 sends
186 the entire response with the specified <literal>status</literal> to the client
187 (0.2.0)
188 <para>
189 It is possible to specify either a redirect URL
190 (for codes 301, 302, 303, 307, and 308)
191 or the response body text (for other codes) as the second argument
192 </para>
193 </tag-desc>
194
195 </list>
196 </para>
197
198 </section>
199
200
201 <section id="http_reply" name="Reply">
202
203 <para>
204 <list type="tag">
205
206 <tag-name><literal>reply.uri</literal></tag-name>
207 <tag-desc>
208 current URI in a reply, read-only
209 </tag-desc>
210
211 <tag-name><literal>reply.method</literal></tag-name>
212 <tag-desc>
213 reply method, read-only
214 </tag-desc>
215
216 <tag-name><literal>reply.status</literal></tag-name>
217 <tag-desc>
218 reply status, writable
219 </tag-desc>
220
221 <tag-name><literal>reply.contentType</literal></tag-name>
222 <tag-desc>
223 the response <header>Content-Type</header> header field value, writable
224 </tag-desc>
225
226 <tag-name><literal>reply.contentLength</literal></tag-name>
227 <tag-desc>
228 the response <header>Content-Length</header> header field value, writable
229 </tag-desc>
230
231 <tag-name><literal>reply.headers{}</literal></tag-name>
232 <tag-desc>
233 reply headers object, read-only
234 </tag-desc>
235
236 </list>
237 </para>
238
239 <para>
240 Additionally, the <literal>reply</literal> object has
241 the following properties:
242
243 <list type="tag">
244
245 <tag-name><literal>reply.body</literal></tag-name>
246 <tag-desc>
247 holds the subrequest response body
248 </tag-desc>
249
250 <tag-name><literal>reply.parent</literal></tag-name>
251 <tag-desc>
252 references the parent request object
253 </tag-desc>
254
255 </list>
256 </para>
257
258 </section>
259
260 </section>
261
262
263 <section id="stream" name="Stream">
264
265 <para>
266 The <literal>stream</literal> objects are available only in the
267 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>
268 module.
269 </para>
270
271
272 <section id="stream_session" name="Session">
273
274 <para>
275 <list type="tag">
276
277 <tag-name><literal>s.remoteAddress</literal></tag-name>
278 <tag-desc>
279 client address, read-only
280 </tag-desc>
281
282 <tag-name><literal>s.eof</literal></tag-name>
283 <tag-desc>
284 a boolean read-only property, true if the current buffer is the last buffer
285 </tag-desc>
286
287 <tag-name><literal>s.fromUpstream</literal></tag-name>
288 <tag-desc>
289 a boolean read-only property,
290 true if the current buffer is from the upstream server to the client
291 </tag-desc>
292
293 <tag-name><literal>s.buffer</literal></tag-name>
294 <tag-desc>
295 the current buffer, writable
296 </tag-desc>
297
298 <tag-name><literal>s.variables{}</literal></tag-name>
299 <tag-desc>
300 nginx variables object, read-only
301 </tag-desc>
302
303 <tag-name><literal>s.OK</literal></tag-name>
304 <tag-desc>
305 the <literal>OK</literal> return code
306 </tag-desc>
307
308 <tag-name><literal>s.DECLINED</literal></tag-name>
309 <tag-desc>
310 the <literal>DECLINED</literal> return code
311 </tag-desc>
312
313 <tag-name><literal>s.AGAIN</literal></tag-name>
314 <tag-desc>
315 the <literal>AGAIN</literal> return code
316 </tag-desc>
317
318 <tag-name><literal>s.ERROR</literal></tag-name>
319 <tag-desc>
320 the <literal>ERROR</literal> return code
321 </tag-desc>
322
323 <tag-name><literal>s.ABORT</literal></tag-name>
324 <tag-desc>
325 the <literal>ABORT</literal> return code
326 </tag-desc>
327
328 <tag-name><literal>s.log(<value>string</value>)</literal></tag-name>
329 <tag-desc>
330 writes a sent <value>string</value> to the error log
331 on the <literal>info</literal> level of logging
332 </tag-desc>
333
334 <tag-name><literal>s.warn(<value>string</value>)</literal></tag-name>
335 <tag-desc>
336 writes a sent <literal>string</literal> to the error log
337 on the <literal>warning</literal> level of logging (0.2.0)
338 </tag-desc>
339
340 <tag-name><literal>s.error(<value>string</value>)</literal></tag-name>
341 <tag-desc>
342 writes a sent <literal>string</literal> to the error log
343 on the <literal>error</literal> level of logging (0.2.0)
344 </tag-desc>
345
346 </list>
347 </para>
348
349 </section>
350
351 </section>
352
353
354 </article>