HTTP

HTTP server and client implementation

The node:http module provides HTTP server and client functionality.

Import

import http from 'node:http';
// or
const http = require('node:http');

Class: http.Server

This class is used to create an HTTP server.

Creating a Server

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World\n');
});

server.listen(3000, () => {
  console.log('Server running at http://localhost:3000/');
});

Events

Event: ‘request’

• request
• response

Emitted each time there is a request.

server.on('request', (req, res) => {
  console.log('Request received:', req.url);
});

Event: ‘connection’

• socket

Emitted when a new TCP stream is established.

Event: ‘close’

Emitted when the server closes.

Event: ‘clientError’

• exception
• socket

Emitted when a client connection emits an error.

server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});

Methods

server.listen([port][, host][, callback])

• port
• host
• callback

Start the HTTP server listening for connections.

server.close([callback])

• callback

Stops the server from accepting new connections.

server.setTimeout([msecs][, callback])

• msecs Default: 120000 (2 minutes)
• callback

Sets the timeout value for sockets.

Properties

server.timeout

• Type: Default: 0 (no timeout)

The number of milliseconds of inactivity before a socket is presumed to have timed out.

server.keepAliveTimeout

• Type: Default: 5000 (5 seconds)

The number of milliseconds of inactivity a server needs to wait for additional incoming data.

server.maxHeadersCount

• Type: Default: 2000

Limits maximum incoming headers count.

Class: http.IncomingMessage

An IncomingMessage object is created by http.Server or http.ClientRequest and represents the request (on server) or response (on client).

Properties

message.headers

• Type:

The request/response headers object.

console.log(request.headers);
// {
//   'content-type': 'text/plain',
//   'host': 'example.com'
// }

message.method

• Type:

The request method (only valid for requests received by server).

console.log(request.method); // 'GET', 'POST', etc.

message.url

• Type:

Request URL string (only valid for requests received by server).

console.log(request.url); // '/path?query=value'

message.statusCode

• Type:

The 3-digit HTTP response status code (only valid for response from ClientRequest).

message.statusMessage

• Type:

The HTTP response status message (only valid for response from ClientRequest).

Methods

message.setTimeout(msecs[, callback])

• msecs
• callback

Calls message.socket.setTimeout(msecs, callback).

Class: http.ServerResponse

This object is created internally by an HTTP server and passed as the second parameter to the 'request' event.

Methods

response.writeHead(statusCode[, statusMessage][, headers])

• statusCode
• statusMessage
• headers

Sends a response header to the request.

response.writeHead(200, {
  'Content-Type': 'text/html',
  'Content-Length': Buffer.byteLength(body)
});

response.write(chunk[, encoding][, callback])

• chunk
• encoding
• callback
• Returns:

Sends a chunk of the response body.

response.write('Hello ');
response.write('World');

response.end([data[, encoding]][, callback])

• data
• encoding
• callback

Signals that all response headers and body have been sent.

response.end('Done!');

response.setHeader(name, value)

• name
• value

Sets a single header value.

response.setHeader('Content-Type', 'application/json');

response.getHeader(name)

• name
• Returns:

Reads out a header that’s already been queued but not sent.

response.removeHeader(name)

• name

Removes a header that’s queued for implicit sending.

Properties

response.statusCode

• Type: Default: 200

The HTTP status code to send.

response.statusCode = 404;

response.statusMessage

• Type:

The HTTP status message to send.

Class: http.ClientRequest

This object is created internally and returned from http.request().

Events

Event: ‘response’

• response

Emitted when a response is received to this request.

request.on('response', (response) => {
  console.log('STATUS:', response.statusCode);
});

Event: ‘socket’

• socket

Emitted after a socket is assigned to this request.

Methods

request.write(chunk[, encoding][, callback])

• chunk
• encoding
• callback

Sends a chunk of the request body.

request.end([data[, encoding]][, callback])

• data
• encoding
• callback

Finishes sending the request.

const postData = JSON.stringify({ key: 'value' });
request.write(postData);
request.end();

request.setHeader(name, value)

• name
• value

Sets a single header value for the request.

request.setTimeout(timeout[, callback])

• timeout
• callback

Once a socket is assigned and is connected, socket.setTimeout() will be called.

HTTP Methods

http.get(url[, options][, callback])

• url
• options
• callback
• Returns:

Convenience method for making GET requests.

http.get('http://example.com/', (res) => {
  console.log('STATUS:', res.statusCode);
  res.on('data', (chunk) => {
    console.log('BODY:', chunk);
  });
}).on('error', (e) => {
  console.error('ERROR:', e.message);
});

http.request(url[, options][, callback])

• url
• options
  • method Default: 'GET'
  • host Default: 'localhost'
  • port Default: 80
  • path Default: '/'
  • headers
• callback
• Returns:

Makes an HTTP request.

const options = {
  hostname: 'example.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  }
};

const req = http.request(options, (res) => {
  console.log('STATUS:', res.statusCode);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log('BODY:', chunk);
  });
});

req.on('error', (e) => {
  console.error('Problem with request:', e.message);
});

req.write(JSON.stringify({ key: 'value' }));
req.end();

HTTP Status Codes

Common Status Codes

• 200 - OK
• 201 - Created
• 204 - No Content
• 301 - Moved Permanently
• 302 - Found
• 304 - Not Modified
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 500 - Internal Server Error
• 502 - Bad Gateway
• 503 - Service Unavailable

Using Status Codes

const http = require('node:http');

const server = http.createServer((req, res) => {
  if (req.url === '/') {
    res.statusCode = 200;
    res.setHeader('Content-Type', 'text/plain');
    res.end('OK');
  } else {
    res.statusCode = 404;
    res.setHeader('Content-Type', 'text/plain');
    res.end('Not Found');
  }
});

Working with Headers

Request Headers

server.on('request', (req, res) => {
  console.log(req.headers['user-agent']);
  console.log(req.headers['content-type']);
  console.log(req.headers.host);
});

Response Headers

res.setHeader('Content-Type', 'application/json');
res.setHeader('X-Custom-Header', 'value');
res.setHeader('Set-Cookie', ['cookie1=value1', 'cookie2=value2']);

Example: Simple Web Server

import http from 'node:http';
import fs from 'node:fs';

const server = http.createServer((req, res) => {
  if (req.method === 'GET' && req.url === '/') {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    fs.createReadStream('index.html').pipe(res);
  } else if (req.method === 'POST' && req.url === '/api/data') {
    let body = '';
    req.on('data', chunk => {
      body += chunk.toString();
    });
    req.on('end', () => {
      const data = JSON.parse(body);
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ received: data }));
    });
  } else {
    res.writeHead(404, { 'Content-Type': 'text/plain' });
    res.end('404 Not Found');
  }
});

server.listen(3000);

Example: HTTP Client

import http from 'node:http';

const options = {
  hostname: 'api.example.com',
  port: 80,
  path: '/data',
  method: 'GET',
  headers: {
    'Accept': 'application/json'
  }
};

const req = http.request(options, (res) => {
  let data = '';
  
  res.on('data', (chunk) => {
    data += chunk;
  });
  
  res.on('end', () => {
    console.log(JSON.parse(data));
  });
});

req.on('error', (error) => {
  console.error('Error:', error);
});

req.end();