From d7714c3f1ff7bfceed2c6fdbcbfb098e6119f797 Mon Sep 17 00:00:00 2001 From: Dmitry Volyntsev Date: Fri, 8 May 2020 12:02:32 +0000 Subject: [PATCH] Added description for API methods. --- nginx/ts/ngx_http_js_module.d.ts | 129 ++++++++++++++++++++++++----- nginx/ts/ngx_stream_js_module.d.ts | 70 +++++++++++++--- 2 files changed, 166 insertions(+), 33 deletions(-) diff --git a/nginx/ts/ngx_http_js_module.d.ts b/nginx/ts/ngx_http_js_module.d.ts index 92940fff..4e5c1281 100644 --- a/nginx/ts/ngx_http_js_module.d.ts +++ b/nginx/ts/ngx_http_js_module.d.ts @@ -233,48 +233,135 @@ interface NginxVariables { } interface NginxSubrequestOptions { + /** + * Arguments string, by default an empty string is used. + */ + args?: NjsStringLike, + /** + * Request body, by default the request body of the parent request object is used. + */ + body?: NjsStringLike, + /** + * HTTP method, by default the GET method is used. + */ method?: "GET" | "POST" | "OPTIONS" | "HEAD" | "PROPFIND" | "PUT" | "MKCOL" | "DELETE" | "COPY" | "MOVE" | "PROPPATCH" | "LOCK" | "PATCH" | "TRACE", - args?: NjsStringLike, - body?: NjsStringLike, + /** + * if true, the created subrequest is a detached subrequest. + * Responses to detached subrequests are ignored. + */ detached?: boolean } interface NginxHTTPRequest { - // properties + /** + * Request arguments object. + */ readonly args: NginxHTTPArgs; + /** + * Writes a string to the error log on the error level of logging. + * @param message Message to log. + */ + error(message: NjsStringLike): void; + /** + * Finishes sending a response to the client. + */ + finish(): void; + /** + * Incoming headers object. + */ readonly headersIn: NginxHeadersIn; + /** + * Outgoing headers object. + */ readonly headersOut: NginxHeadersOut; + /** + * HTTP protocol version. + */ readonly httpVersion: NjsByteString; + /** + * Performs an internal redirect to the specified uri. + * If the uri starts with the “@” prefix, it is considered a named location. + * The actual redirect happens after the handler execution is completed. + * @param uri Location to redirect to. + */ + internalRedirect(uri: NjsStringLike): void; + /** + * Writes a string to the error log on the info level of logging. + * @param message Message to log. + */ + log(message: NjsStringLike): void; + /** + * HTTP method. + */ readonly method: NjsByteString; + /** + * Parent for subrequest object. + */ readonly parent?: NginxHTTPRequest; + /** + * Client address. + */ readonly remoteAddress: NjsByteString; + /** + * Client request body if it has not been written to a temporary file. + * To ensure that the client request body is in memory, its size should be + * limited by client_max_body_size, and a sufficient buffer size should be set + * using client_body_buffer_size. The property is available only in the js_content directive. + */ readonly requestBody?: NjsByteString; + /** + * Subrequest response body. The size of response body is limited by + * the subrequest_output_buffer_size directive. + */ readonly responseBody?: NjsByteString; - readonly uri: NjsByteString; - readonly variables: NginxVariables; - - // control - status: number; - sendHeader(): void; - send(part: NjsStringLike): void; + /** + * Sends the entire response with the specified status to the client. + * It is possible to specify either a redirect URL (for codes 301, 302, 303, 307, and 308) + * or the response body text (for other codes) as the second argument. + * @param status Respose status code. + * @param body Respose body. + */ return(status: number, body?: NjsStringLike): void; - internalRedirect(location: NjsStringLike): void; - finish(): void; - - // Promise version + /** + * Sends the HTTP headers to the client. + */ + send(part: NjsStringLike): void; + /** + * Sends the HTTP headers to the client. + */ + sendHeader(): void; + /** + * Respose status code. + */ + status: number; + /** + * Creates a subrequest with the given uri and options. + * A subrequest shares its input headers with the client request. + * To send headers different from original headers to a proxied server, + * the proxy_set_header directive can be used. To send a completely new + * set of headers to a proxied server, the proxy_pass_request_headers directive can be used. + * @param uri Subrequest location. + * @param options Subrequest options. + * @param callback Completion callback. + */ subrequest(uri: NjsStringLike, options?: NginxSubrequestOptions | string): Promise; - // Long callback version subrequest(uri: NjsStringLike, options: NginxSubrequestOptions | string, callback:(reply:NginxHTTPRequest) => void): void; - // Short callback version subrequest(uri: NjsStringLike, callback:(reply:NginxHTTPRequest) => void): void; - // Detached version subrequest(uri: NjsStringLike, options: NginxSubrequestOptions): void; - - // logging - error(message: NjsStringLike): void; + /** + * Current URI in request, normalized. + */ + readonly uri: NjsByteString; + /** + * nginx variables object. + */ + readonly variables: NginxVariables; + /** + * Writes a string to the error log on the warn level of logging. + * @param message Message to log. + */ warn(message: NjsStringLike): void; - log(message: NjsStringLike): void; } diff --git a/nginx/ts/ngx_stream_js_module.d.ts b/nginx/ts/ngx_stream_js_module.d.ts index 27b10643..47799ba2 100644 --- a/nginx/ts/ngx_stream_js_module.d.ts +++ b/nginx/ts/ngx_stream_js_module.d.ts @@ -70,33 +70,79 @@ interface NginxStreamVariables { } interface NginxStreamCallbackFlags { + /** + * True if data is a last buffer. + */ last: boolean } interface NginxStreamSendOptions { + /** + * True if data is a last buffer. + */ last?: boolean + /** + * True if the buffer should have the flush flag. + */ flush?: boolean } interface NginxStreamRequest { - // properties - readonly remoteAddress: NjsByteString; - readonly variables: NginxStreamVariables; - - // control + /** + * Successfully finalizes the phase handler. + */ allow(): void; + /** + * Finalizes the phase handler and passes control to the next handler. + */ decline(): void; + /** + * Finalizes the phase handler with the access error code. + */ deny(): void; + /** + * Successfully finalizes the current phase handler + * or finalizes it with the specified numeric code. + * @param code Finalization code. + */ done(code?: number): void; - + /** + * Writes a string to the error log on the error level of logging. + * @param message Message to log. + */ + error(message: NjsStringLike): void; + /** + * Writes a string to the error log on the info level of logging. + * @param message Message to log. + */ + log(message: NjsStringLike): void; + /** + * Unregisters the callback set by on() method. + */ + off(event: "upload" | "download"): void; + /** + * Registers a callback for the specified event. + */ on(event: "upload" | "download", callback:(data:NjsByteString, flags: NginxStreamCallbackFlags) => void): void; - off(event: "upload" | "download"): void; - + /** + * Client address. + */ + readonly remoteAddress: NjsByteString; + /** + * Sends the data to the client. + * @param data Data to send. + * @param options Object used to override nginx buffer flags derived from + * an incoming data chunk buffer. + */ send(data: NjsStringLike, options?: NginxStreamSendOptions): void; - - // logging - error(message: NjsStringLike): void; + /** + * nginx variables object. + */ + readonly variables: NginxStreamVariables; + /** + * Writes a string to the error log on the warn level of logging. + * @param message Message to log. + */ warn(message: NjsStringLike): void; - log(message: NjsStringLike): void; } -- 2.47.3