diff --git a/doc/api/http.markdown b/doc/api/http.markdown index a1b1a598db..624b9a9506 100644 --- a/doc/api/http.markdown +++ b/doc/api/http.markdown @@ -56,8 +56,8 @@ This is an [EventEmitter][] with the following events: Emitted each time there is a request. Note that there may be multiple requests per connection (in the case of keep-alive connections). - `request` is an instance of `http.IncomingMessage` and `response` is - an instance of `http.ServerResponse` + `request` is an instance of [http.IncomingMessage][] and `response` is +an instance of [http.ServerResponse][]. ### Event: 'connection' @@ -83,7 +83,7 @@ Emitted each time a request with an http Expect: 100-continue is received. If this event isn't listened for, the server will automatically respond with a 100 Continue as appropriate. -Handling this event involves calling `response.writeContinue` if the client +Handling this event involves calling [response.writeContinue()][] if the client should continue to send the request body, or generating an appropriate HTTP response (e.g., 400 Bad Request) if the client should not continue to send the request body. @@ -233,7 +233,7 @@ The response implements the [Writable Stream][] interface. This is an `function () { }` Indicates that the underlying connection was terminated before -`response.end()` was called or able to flush. +[response.end()][] was called or able to flush. ### response.writeContinue() @@ -255,9 +255,9 @@ Example: 'Content-Type': 'text/plain' }); This method must only be called once on a message and it must -be called before `response.end()` is called. +be called before [response.end()][] is called. -If you call `response.write()` or `response.end()` before calling this, the +If you call [response.write()][] or [response.end()][] before calling this, the implicit/mutable headers will be calculated and call this function for you. Note: that Content-Length is given in bytes not characters. The above example @@ -284,9 +284,9 @@ sockets. ### response.statusCode -When using implicit headers (not calling `response.writeHead()` explicitly), this property -controls the status code that will be sent to the client when the headers get -flushed. +When using implicit headers (not calling [response.writeHead()][] explicitly), +this property controls the status code that will be sent to the client when +the headers get flushed. Example: @@ -342,8 +342,8 @@ Example: ### response.write(chunk, [encoding]) -If this method is called and `response.writeHead()` has not been called, it will -switch to implicit header mode and flush the implicit headers. +If this method is called and [response.writeHead()][] has not been called, +it will switch to implicit header mode and flush the implicit headers. This sends a chunk of the response body. This method may be called multiple times to provide successive parts of the body. @@ -424,7 +424,7 @@ Options: - `false`: opts out of connection pooling with an Agent, defaults request to `Connection: close`. -`http.request()` returns an instance of the `http.ClientRequest` +`http.request()` returns an instance of the [http.ClientRequest][] class. The `ClientRequest` instance is a writable stream. If one needs to upload a file with a POST request, then write to the `ClientRequest` object. @@ -556,7 +556,7 @@ data chunk or when closing the connection. To get the response, add a listener for `'response'` to the request object. `'response'` will be emitted from the request object when the response headers have been received. The `'response'` event is executed with one -argument which is an instance of `http.IncomingMessage`. +argument which is an instance of [http.IncomingMessage][]. During the `'response'` event, one can add listeners to the response object; particularly to listen for the `'data'` event. @@ -581,7 +581,7 @@ The request implements the [Writable Stream][] interface. This is an `function (response) { }` Emitted when a response is received to this request. This event is emitted only -once. The `response` argument will be an instance of `http.IncomingMessage`. +once. The `response` argument will be an instance of [http.IncomingMessage][]. Options: @@ -760,9 +760,10 @@ Once a socket is assigned to this request and is connected ## http.IncomingMessage -An `IncomingMessage` object is created by `http.Server` or `http.ClientRequest` -and passed as the first argument to the `'request'` and `'response'` event -respectively. It may be used to access response status, headers and data. +An `IncomingMessage` object is created by [http.Server][] or +[http.ClientRequest][] and passed as the first argument to the `'request'` +and `'response'` event respectively. It may be used to access response status, +headers and data. It implements the [Readable Stream][] interface, as well as the following additional events, methods, and properties. @@ -813,14 +814,14 @@ Calls `message.connection.setTimeout(msecs, callback)`. ### message.method -**Only valid for request obtained from `http.Server`.** +**Only valid for request obtained from [http.Server][].** The request method as a string. Read only. Example: `'GET'`, `'DELETE'`. ### message.url -**Only valid for request obtained from `http.Server`.** +**Only valid for request obtained from [http.Server][].** Request URL string. This contains only the URL that is present in the actual HTTP request. If the request is: @@ -867,21 +868,29 @@ request.connection.getPeerCertificate() to obtain the client's authentication details. -[Agent]: #http_class_http_agent ['checkContinue']: #http_event_checkcontinue +['listening']: net.html#net_event_listening +[Agent]: #http_class_http_agent [Buffer]: buffer.html#buffer_buffer [EventEmitter]: events.html#events_class_events_eventemitter +[Readable Stream]: stream.html#stream_readable_stream +[Writable Stream]: stream.html#stream_writable_stream [global Agent]: #http_http_globalagent +[http.ClientRequest]: #http_class_http_clientrequest +[http.IncomingMessage]: #http_http_incomingmessage +[http.ServerResponse]: #http_class_http_serverresponse +[http.Server]: #http_class_http_server +[http.request()]: #http_http_request_options_callback [http.request()]: #http_http_request_options_callback -[http.IncomingMessage]: #http_class_http_incomingmessage -['listening']: net.html#net_event_listening [net.Server.close()]: net.html#net_server_close_callback [net.Server.listen(path)]: net.html#net_server_listen_path_callback [net.Server.listen(port)]: net.html#net_server_listen_port_host_backlog_callback -[Readable Stream]: stream.html#stream_readable_stream +[response.end()]: #http_response_end_data_encoding +[response.write()]: #http_response_write_chunk_encoding +[response.writeContinue()]: #http_response_writecontinue +[response.writeHead()]: #http_response_writehead_statuscode_reasonphrase_headers [socket.setKeepAlive()]: net.html#net_socket_setkeepalive_enable_initialdelay [socket.setNoDelay()]: net.html#net_socket_setnodelay_nodelay [socket.setTimeout()]: net.html#net_socket_settimeout_timeout_callback [stream.setEncoding()]: stream.html#stream_stream_setencoding_encoding [url.parse()]: url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost -[Writable Stream]: stream.html#stream_writable_stream