Mercurial > hg > nginx-site
comparison xml/en/docs/njs/njs_api.xml @ 2175:cd4889fdcfa4
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> |