DocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Bun

Node.js module

https

The 'node:https' module extends http to support secure TLS/SSL connections. It provides https.createServer and https.request methods for serving and consuming encrypted HTTPS traffic.

Works in Bun

APIs are implemented, but the Agent is not always used yet, which might affect connection pooling and other Agent features.

  • class Agent

    An Agent object for HTTPS similar to http.Agent. See request for more information.

    • readonly freeSockets: ReadOnlyDict<Socket[]>

      An object which contains arrays of sockets currently awaiting use by the agent when keepAlive is enabled. Do not modify.

      Sockets in the freeSockets list will be automatically destroyed and removed from the array on 'timeout'.

    • maxFreeSockets: number

      By default set to 256. For agents with keepAlive enabled, this sets the maximum number of sockets that will be left open in the free state.

    • maxSockets: number

      By default set to Infinity. Determines how many concurrent sockets the agent can have open per origin. Origin is the returned value of agent.getName().

    • maxTotalSockets: number

      By default set to Infinity. Determines how many concurrent sockets the agent can have open. Unlike maxSockets, this parameter applies across all origins.

    • readonly requests: ReadOnlyDict<IncomingMessage[]>

      An object which contains queues of requests that have not yet been assigned to sockets. Do not modify.

    • readonly sockets: ReadOnlyDict<Socket[]>

      An object which contains arrays of sockets currently in use by the agent. Do not modify.

    • static captureRejections: boolean

      Value: boolean

      Change the default captureRejections option on all new EventEmitter objects.

    • readonly static captureRejectionSymbol: typeof captureRejectionSymbol

      Value: Symbol.for('nodejs.rejection')

      See how to write a custom rejection handler.

    • static defaultMaxListeners: number

      By default, a maximum of 10 listeners can be registered for any single event. This limit can be changed for individual EventEmitter instances using the emitter.setMaxListeners(n) method. To change the default for allEventEmitter instances, the events.defaultMaxListeners property can be used. If this value is not a positive number, a RangeError is thrown.

      Take caution when setting the events.defaultMaxListeners because the change affects all EventEmitter instances, including those created before the change is made. However, calling emitter.setMaxListeners(n) still has precedence over events.defaultMaxListeners.

      This is not a hard limit. The EventEmitter instance will allow more listeners to be added but will output a trace warning to stderr indicating that a "possible EventEmitter memory leak" has been detected. For any single EventEmitter, the emitter.getMaxListeners() and emitter.setMaxListeners() methods can be used to temporarily avoid this warning:

      import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
  // do stuff
  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});

      The --trace-warnings command-line flag can be used to display the stack trace for such warnings.

      The emitted warning can be inspected with process.on('warning') and will have the additional emitter, type, and count properties, referring to the event emitter instance, the event's name and the number of attached listeners, respectively. Its name property is set to 'MaxListenersExceededWarning'.

    • readonly static errorMonitor: typeof errorMonitor

      This symbol shall be used to install a listener for only monitoring 'error' events. Listeners installed using this symbol are called before the regular 'error' listeners are called.

      Installing a listener using this symbol does not change the behavior once an 'error' event is emitted. Therefore, the process will still crash if no regular 'error' listener is installed.

    • error: Error,
      event: string | symbol,
      ...args: AnyRest
      ): void;
    • eventName: string | symbol,
      listener: (...args: any[]) => void
      ): this;

      Alias for emitter.on(eventName, listener).

    • destroy(): void;

      Destroy any sockets that are currently in use by the agent.

      It is usually not necessary to do this. However, if using an agent with keepAlive enabled, then it is best to explicitly shut down the agent when it is no longer needed. Otherwise, sockets might stay open for quite a long time before the server terminates them.

    • emit<K>(
      eventName: string | symbol,
      ...args: AnyRest
      ): boolean;

      Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

      Returns true if the event had listeners, false otherwise.

      import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
    • eventNames(): string | symbol[];

      Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or Symbols.

      import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
    • getMaxListeners(): number;

      Returns the current max listener value for the EventEmitter which is either set by emitter.setMaxListeners(n) or defaults to EventEmitter.defaultMaxListeners.

    • eventName: string | symbol,
      listener?: Function
      ): number;

      Returns the number of listeners listening for the event named eventName. If listener is provided, it will return how many times the listener is found in the list of the listeners of the event.

      @param eventName

      The name of the event being listened for

      @param listener

      The event handler function

    • eventName: string | symbol
      ): Function[];

      Returns a copy of the array of listeners for the event named eventName.

      server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]
    • off<K>(
      eventName: string | symbol,
      listener: (...args: any[]) => void
      ): this;

      Alias for emitter.removeListener().

    • on<K>(
      eventName: string | symbol,
      listener: (...args: any[]) => void
      ): this;

      Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

      server.on('connection', (stream) => {
  console.log('someone connected!');
});

      Returns a reference to the EventEmitter, so that calls can be chained.

      By default, event listeners are invoked in the order they are added. The emitter.prependListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

      import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
      @param eventName

      The name of the event.

      @param listener

      The callback function

    • once<K>(
      eventName: string | symbol,
      listener: (...args: any[]) => void
      ): this;

      Adds a one-time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

      server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

      Returns a reference to the EventEmitter, so that calls can be chained.

      By default, event listeners are invoked in the order they are added. The emitter.prependOnceListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

      import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
      @param eventName

      The name of the event.

      @param listener

      The callback function

    • eventName: string | symbol,
      listener: (...args: any[]) => void
      ): this;

      Adds the listener function to the beginning of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

      server.prependListener('connection', (stream) => {
  console.log('someone connected!');
});

      Returns a reference to the EventEmitter, so that calls can be chained.

      @param eventName

      The name of the event.

      @param listener

      The callback function

    • eventName: string | symbol,
      listener: (...args: any[]) => void
      ): this;

      Adds a one-timelistener function for the event named eventName to the beginning of the listeners array. The next time eventName is triggered, this listener is removed, and then invoked.

      server.prependOnceListener('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

      Returns a reference to the EventEmitter, so that calls can be chained.

      @param eventName

      The name of the event.

      @param listener

      The callback function

    • eventName: string | symbol
      ): Function[];

      Returns a copy of the array of listeners for the event named eventName, including any wrappers (such as those created by .once()).

      import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');
    • eventName?: string | symbol
      ): this;

      Removes all listeners, or those of the specified eventName.

      It is bad practice to remove listeners added elsewhere in the code, particularly when the EventEmitter instance was created by some other component or module (e.g. sockets or file streams).

      Returns a reference to the EventEmitter, so that calls can be chained.

    • eventName: string | symbol,
      listener: (...args: any[]) => void
      ): this;

      Removes the specified listener from the listener array for the event named eventName.

      const callback = (stream) => {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

      removeListener() will remove, at most, one instance of a listener from the listener array. If any single listener has been added multiple times to the listener array for the specified eventName, then removeListener() must be called multiple times to remove each instance.

      Once an event is emitted, all listeners attached to it at the time of emitting are called in order. This implies that any removeListener() or removeAllListeners() calls after emitting and before the last listener finishes execution will not remove them fromemit() in progress. Subsequent events behave as expected.

      import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

      Because listeners are managed using an internal array, calling this will change the position indices of any listener registered after the listener being removed. This will not impact the order in which listeners are called, but it means that any copies of the listener array as returned by the emitter.listeners() method will need to be recreated.

      When a single function has been added as a handler multiple times for a single event (as in the example below), removeListener() will remove the most recently added instance. In the example the once('ping') listener is removed:

      import { EventEmitter } from 'node:events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

      Returns a reference to the EventEmitter, so that calls can be chained.

    • n: number
      ): this;

      By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default that helps finding memory leaks. The emitter.setMaxListeners() method allows the limit to be modified for this specific EventEmitter instance. The value can be set to Infinity (or 0) to indicate an unlimited number of listeners.

      Returns a reference to the EventEmitter, so that calls can be chained.

    • signal: AbortSignal,
      resource: (event: Event) => void
      ): Disposable;

      Listens once to the abort event on the provided signal.

      Listening to the abort event on abort signals is unsafe and may lead to resource leaks since another third party with the signal can call e.stopImmediatePropagation(). Unfortunately Node.js cannot change this since it would violate the web standard. Additionally, the original API makes it easy to forget to remove listeners.

      This API allows safely using AbortSignals in Node.js APIs by solving these two issues by listening to the event such that stopImmediatePropagation does not prevent the listener from running.

      Returns a disposable so that it may be unsubscribed from more easily.

      import { addAbortListener } from 'node:events';

function example(signal) {
  let disposable;
  try {
    signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
    disposable = addAbortListener(signal, (e) => {
      // Do something when signal is aborted.
    });
  } finally {
    disposable?.[Symbol.dispose]();
  }
}
      @returns

      Disposable that removes the abort listener.

    • emitter: EventEmitter<DefaultEventMap> | EventTarget,
      name: string | symbol
      ): Function[];

      Returns a copy of the array of listeners for the event named eventName.

      For EventEmitters this behaves exactly the same as calling .listeners on the emitter.

      For EventTargets this is the only way to get the event listeners for the event target. This is useful for debugging and diagnostic purposes.

      import { getEventListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  const listener = () => console.log('Events are fun');
  ee.on('foo', listener);
  console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
}
{
  const et = new EventTarget();
  const listener = () => console.log('Events are fun');
  et.addEventListener('foo', listener);
  console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
}
    • emitter: EventEmitter<DefaultEventMap> | EventTarget
      ): number;

      Returns the currently set max amount of listeners.

      For EventEmitters this behaves exactly the same as calling .getMaxListeners on the emitter.

      For EventTargets this is the only way to get the max event listeners for the event target. If the number of event handlers on a single EventTarget exceeds the max set, the EventTarget will print a warning.

      import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  console.log(getMaxListeners(ee)); // 10
  setMaxListeners(11, ee);
  console.log(getMaxListeners(ee)); // 11
}
{
  const et = new EventTarget();
  console.log(getMaxListeners(et)); // 10
  setMaxListeners(11, et);
  console.log(getMaxListeners(et)); // 11
}
    • static on(
      emitter: EventEmitter,
      eventName: string | symbol,
      options?: StaticEventEmitterIteratorOptions
      ): AsyncIterator<any[]>;
      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
});

for await (const event of on(ee, 'foo')) {
  // The execution of this inner block is synchronous and it
  // processes one event at a time (even with await). Do not use
  // if concurrent execution is required.
  console.log(event); // prints ['bar'] [42]
}
// Unreachable here

      Returns an AsyncIterator that iterates eventName events. It will throw if the EventEmitter emits 'error'. It removes all listeners when exiting the loop. The value returned by each iteration is an array composed of the emitted event arguments.

      An AbortSignal can be used to cancel waiting on events:

      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ac = new AbortController();

(async () => {
  const ee = new EventEmitter();

  // Emit later on
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // The execution of this inner block is synchronous and it
    // processes one event at a time (even with await). Do not use
    // if concurrent execution is required.
    console.log(event); // prints ['bar'] [42]
  }
  // Unreachable here
})();

process.nextTick(() => ac.abort());

      Use the close option to specify an array of event names that will end the iteration:

      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
  ee.emit('close');
});

for await (const event of on(ee, 'foo', { close: ['close'] })) {
  console.log(event); // prints ['bar'] [42]
}
// the loop will exit after 'close' is emitted
console.log('done'); // prints 'done'
      @returns

      An AsyncIterator that iterates eventName events emitted by the emitter

      static on(
      emitter: EventTarget,
      eventName: string,
      options?: StaticEventEmitterIteratorOptions
      ): AsyncIterator<any[]>;
      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
});

for await (const event of on(ee, 'foo')) {
  // The execution of this inner block is synchronous and it
  // processes one event at a time (even with await). Do not use
  // if concurrent execution is required.
  console.log(event); // prints ['bar'] [42]
}
// Unreachable here

      Returns an AsyncIterator that iterates eventName events. It will throw if the EventEmitter emits 'error'. It removes all listeners when exiting the loop. The value returned by each iteration is an array composed of the emitted event arguments.

      An AbortSignal can be used to cancel waiting on events:

      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ac = new AbortController();

(async () => {
  const ee = new EventEmitter();

  // Emit later on
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // The execution of this inner block is synchronous and it
    // processes one event at a time (even with await). Do not use
    // if concurrent execution is required.
    console.log(event); // prints ['bar'] [42]
  }
  // Unreachable here
})();

process.nextTick(() => ac.abort());

      Use the close option to specify an array of event names that will end the iteration:

      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
  ee.emit('close');
});

for await (const event of on(ee, 'foo', { close: ['close'] })) {
  console.log(event); // prints ['bar'] [42]
}
// the loop will exit after 'close' is emitted
console.log('done'); // prints 'done'
      @returns

      An AsyncIterator that iterates eventName events emitted by the emitter

    • static once(
      emitter: EventEmitter,
      eventName: string | symbol,
      options?: StaticEventEmitterOptions
      ): Promise<any[]>;

      Creates a Promise that is fulfilled when the EventEmitter emits the given event or that is rejected if the EventEmitter emits 'error' while waiting. The Promise will resolve with an array of all the arguments emitted to the given event.

      This method is intentionally generic and works with the web platform EventTarget interface, which has no special'error' event semantics and does not listen to the 'error' event.

      import { once, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

process.nextTick(() => {
  ee.emit('myevent', 42);
});

const [value] = await once(ee, 'myevent');
console.log(value);

const err = new Error('kaboom');
process.nextTick(() => {
  ee.emit('error', err);
});

try {
  await once(ee, 'myevent');
} catch (err) {
  console.error('error happened', err);
}

      The special handling of the 'error' event is only used when events.once() is used to wait for another event. If events.once() is used to wait for the 'error' event itself, then it is treated as any other kind of event without special handling:

      import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();

once(ee, 'error')
  .then(([err]) => console.log('ok', err.message))
  .catch((err) => console.error('error', err.message));

ee.emit('error', new Error('boom'));

// Prints: ok boom

      An AbortSignal can be used to cancel waiting for the event:

      import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();
const ac = new AbortController();

async function foo(emitter, event, signal) {
  try {
    await once(emitter, event, { signal });
    console.log('event emitted!');
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
    } else {
      console.error('There was an error', error.message);
    }
  }
}

foo(ee, 'foo', ac.signal);
ac.abort(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!
      static once(
      emitter: EventTarget,
      eventName: string,
      options?: StaticEventEmitterOptions
      ): Promise<any[]>;

      Creates a Promise that is fulfilled when the EventEmitter emits the given event or that is rejected if the EventEmitter emits 'error' while waiting. The Promise will resolve with an array of all the arguments emitted to the given event.

      This method is intentionally generic and works with the web platform EventTarget interface, which has no special'error' event semantics and does not listen to the 'error' event.

      import { once, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

process.nextTick(() => {
  ee.emit('myevent', 42);
});

const [value] = await once(ee, 'myevent');
console.log(value);

const err = new Error('kaboom');
process.nextTick(() => {
  ee.emit('error', err);
});

try {
  await once(ee, 'myevent');
} catch (err) {
  console.error('error happened', err);
}

      The special handling of the 'error' event is only used when events.once() is used to wait for another event. If events.once() is used to wait for the 'error' event itself, then it is treated as any other kind of event without special handling:

      import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();

once(ee, 'error')
  .then(([err]) => console.log('ok', err.message))
  .catch((err) => console.error('error', err.message));

ee.emit('error', new Error('boom'));

// Prints: ok boom

      An AbortSignal can be used to cancel waiting for the event:

      import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();
const ac = new AbortController();

async function foo(emitter, event, signal) {
  try {
    await once(emitter, event, { signal });
    console.log('event emitted!');
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
    } else {
      console.error('There was an error', error.message);
    }
  }
}

foo(ee, 'foo', ac.signal);
ac.abort(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!
    • n?: number,
      ...eventTargets: EventEmitter<DefaultEventMap> | EventTarget[]
      ): void;
      import { setMaxListeners, EventEmitter } from 'node:events';

const target = new EventTarget();
const emitter = new EventEmitter();

setMaxListeners(5, target, emitter);
      @param n

      A non-negative number. The maximum number of listeners per EventTarget event.

      @param eventTargets

      Zero or more {EventTarget} or {EventEmitter} instances. If none are specified, n is set as the default max for all newly created {EventTarget} and {EventEmitter} objects.

  • class Server<Request extends typeof http.IncomingMessage = typeof http.IncomingMessage, Response extends typeof http.ServerResponse = typeof http.ServerResponse>

    See http.Server for more information.

    • connections: number
    • headersTimeout: number

      Limit the amount of time the parser will wait to receive the complete HTTP headers.

      If the timeout expires, the server responds with status 408 without forwarding the request to the request listener and then closes the connection.

      It must be set to a non-zero value (e.g. 120 seconds) to protect against potential Denial-of-Service attacks in case the server is deployed without a reverse proxy in front.

    • keepAliveTimeout: number

      The number of milliseconds of inactivity a server needs to wait for additional incoming data, after it has finished writing the last response, before a socket will be destroyed. If the server receives new data before the keep-alive timeout has fired, it will reset the regular inactivity timeout, i.e., server.timeout.

      A value of 0 will disable the keep-alive timeout behavior on incoming connections. A value of 0 makes the http server behave similarly to Node.js versions prior to 8.0.0, which did not have a keep-alive timeout.

      The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections.

    • readonly listening: boolean

      Indicates whether or not the server is listening for connections.

    • maxConnections: number

      Set this property to reject connections when the server's connection count gets high.

      It is not recommended to use this option once a socket has been sent to a child with child_process.fork().

    • maxHeadersCount: null | number

      Limits maximum incoming headers count. If set to 0, no limit will be applied.

    • maxRequestsPerSocket: null | number

      The maximum number of requests socket can handle before closing keep alive connection.

      A value of 0 will disable the limit.

      When the limit is reached it will set the Connection header value to close, but will not actually close the connection, subsequent requests sent after the limit is reached will get 503 Service Unavailable as a response.

    • requestTimeout: number

      Sets the timeout value in milliseconds for receiving the entire request from the client.

      If the timeout expires, the server responds with status 408 without forwarding the request to the request listener and then closes the connection.

      It must be set to a non-zero value (e.g. 120 seconds) to protect against potential Denial-of-Service attacks in case the server is deployed without a reverse proxy in front.

    • timeout: number

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

      A value of 0 will disable the timeout behavior on incoming connections.

      The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections.

    • static captureRejections: boolean

      Value: boolean

      Change the default captureRejections option on all new EventEmitter objects.

    • readonly static captureRejectionSymbol: typeof captureRejectionSymbol

      Value: Symbol.for('nodejs.rejection')

      See how to write a custom rejection handler.

    • static defaultMaxListeners: number

      By default, a maximum of 10 listeners can be registered for any single event. This limit can be changed for individual EventEmitter instances using the emitter.setMaxListeners(n) method. To change the default for allEventEmitter instances, the events.defaultMaxListeners property can be used. If this value is not a positive number, a RangeError is thrown.

      Take caution when setting the events.defaultMaxListeners because the change affects all EventEmitter instances, including those created before the change is made. However, calling emitter.setMaxListeners(n) still has precedence over events.defaultMaxListeners.

      This is not a hard limit. The EventEmitter instance will allow more listeners to be added but will output a trace warning to stderr indicating that a "possible EventEmitter memory leak" has been detected. For any single EventEmitter, the emitter.getMaxListeners() and emitter.setMaxListeners() methods can be used to temporarily avoid this warning:

      import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
  // do stuff
  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});

      The --trace-warnings command-line flag can be used to display the stack trace for such warnings.

      The emitted warning can be inspected with process.on('warning') and will have the additional emitter, type, and count properties, referring to the event emitter instance, the event's name and the number of attached listeners, respectively. Its name property is set to 'MaxListenersExceededWarning'.

    • readonly static errorMonitor: typeof errorMonitor

      This symbol shall be used to install a listener for only monitoring 'error' events. Listeners installed using this symbol are called before the regular 'error' listeners are called.

      Installing a listener using this symbol does not change the behavior once an 'error' event is emitted. Therefore, the process will still crash if no regular 'error' listener is installed.

    • [Symbol.asyncDispose](): Promise<void>;

      Calls () and returns a promise that fulfills when the server has closed.

    • error: Error,
      event: string | symbol,
      ...args: AnyRest
      ): void;
    • hostname: string,
      context: SecureContextOptions | SecureContext
      ): void;

      The server.addContext() method adds a secure context that will be used if the client request's SNI name matches the supplied hostname (or wildcard).

      When there are multiple matching contexts, the most recently added one is used.

      @param hostname

      A SNI host name or wildcard (e.g. '*')

      @param context

      An object containing any of the possible properties from the createSecureContext options arguments (e.g. key, cert, ca, etc), or a TLS context object created with createSecureContext itself.

    • event: string,
      listener: (...args: any[]) => void
      ): this;

      events.EventEmitter

      1. tlsClientError
      2. newSession
      3. OCSPRequest
      4. resumeSession
      5. secureConnection
      6. keylog
      event: 'keylog',
      listener: (line: Buffer, tlsSocket: TLSSocket) => void
      ): this;

      events.EventEmitter

      1. close
      2. connection
      3. error
      4. listening
      5. drop
      event: 'newSession',
      listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void
      ): this;

      events.EventEmitter

      1. close
      2. connection
      3. error
      4. listening
      5. drop
      event: 'OCSPRequest',
      listener: (certificate: Buffer, issuer: Buffer, callback: (err: null | Error, resp: Buffer) => void) => void
      ): this;

      events.EventEmitter

      1. close
      2. connection
      3. error
      4. listening
      5. drop
      event: 'resumeSession',
      listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void
      ): this;

      events.EventEmitter

      1. close
      2. connection
      3. error
      4. listening
      5. drop
      event: 'secureConnection',
      listener: (tlsSocket: TLSSocket) => void
      ): this;

      events.EventEmitter

      1. close
      2. connection
      3. error
      4. listening
      5. drop
      event: 'tlsClientError',
      listener: (err: Error, tlsSocket: TLSSocket) => void
      ): this;

      events.EventEmitter

      1. tlsClientError
      2. newSession
      3. OCSPRequest
      4. resumeSession
      5. secureConnection
      6. keylog
      event: 'close',
      listener: () => void
      ): this;
      event: 'connection',
      listener: (socket: Duplex) => void
      ): this;
      event: 'error',
      listener: (err: Error) => void
      ): this;
      event: 'listening',
      listener: () => void
      ): this;
      event: 'checkContinue',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'checkExpectation',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'clientError',
      listener: (err: Error, socket: Duplex) => void
      ): this;
      event: 'connect',
      listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void
      ): this;
      event: 'request',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'upgrade',
      listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void
      ): this;
    • address(): null | string | AddressInfo;

      Returns the bound address, the address family name, and port of the server as reported by the operating system if listening on an IP socket (useful to find which port was assigned when getting an OS-assigned address):{ port: 12346, family: 'IPv4', address: '127.0.0.1' }.

      For a server listening on a pipe or Unix domain socket, the name is returned as a string.

      const server = net.createServer((socket) => {
  socket.end('goodbye\n');
}).on('error', (err) => {
  // Handle errors here.
  throw err;
});

// Grab an arbitrary unused port.
server.listen(() => {
  console.log('opened server on', server.address());
});

      server.address() returns null before the 'listening' event has been emitted or after calling server.close().

    • callback?: (err?: Error) => void
      ): this;

      Stops the server from accepting new connections and keeps existing connections. This function is asynchronous, the server is finally closed when all connections are ended and the server emits a 'close' event. The optional callback will be called once the 'close' event occurs. Unlike that event, it will be called with an Error as its only argument if the server was not open when it was closed.

      @param callback

      Called when the server is closed.

    • Closes all connections connected to this server.

    • Closes all connections connected to this server which are not sending a request or waiting for a response.

    • event: string,
      ...args: any[]
      ): boolean;

      Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

      Returns true if the event had listeners, false otherwise.

      import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
      event: 'keylog',
      line: Buffer,
      tlsSocket: TLSSocket
      ): boolean;
      event: 'newSession',
      sessionId: Buffer,
      sessionData: Buffer,
      callback: (err: Error, resp: Buffer) => void
      ): boolean;
      event: 'OCSPRequest',
      certificate: Buffer,
      issuer: Buffer,
      callback: (err: null | Error, resp: Buffer) => void
      ): boolean;
      event: 'resumeSession',
      sessionId: Buffer,
      callback: (err: Error, sessionData: Buffer) => void
      ): boolean;
      event: 'secureConnection',
      tlsSocket: TLSSocket
      ): boolean;
      event: 'tlsClientError',
      err: Error,
      tlsSocket: TLSSocket
      ): boolean;
      event: 'close'
      ): boolean;
      event: 'connection',
      socket: Duplex
      ): boolean;
      event: 'error',
      err: Error
      ): boolean;
      event: 'listening'
      ): boolean;
      event: 'checkContinue',
      req: InstanceType<Request>,
      res: InstanceType<Response>
      ): boolean;
      event: 'checkExpectation',
      req: InstanceType<Request>,
      res: InstanceType<Response>
      ): boolean;
      event: 'clientError',
      err: Error,
      socket: Duplex
      ): boolean;
      event: 'connect',
      req: InstanceType<Request>,
      socket: Duplex,
      head: Buffer
      ): boolean;
      event: 'request',
      req: InstanceType<Request>,
      res: InstanceType<Response>
      ): boolean;
      event: 'upgrade',
      req: InstanceType<Request>,
      socket: Duplex,
      head: Buffer
      ): boolean;
    • eventNames(): string | symbol[];

      Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or Symbols.

      import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
    • cb: (error: null | Error, count: number) => void
      ): this;

      Asynchronously get the number of concurrent connections on the server. Works when sockets were sent to forks.

      Callback should take two arguments err and count.

    • getMaxListeners(): number;

      Returns the current max listener value for the EventEmitter which is either set by emitter.setMaxListeners(n) or defaults to EventEmitter.defaultMaxListeners.

    • Returns the session ticket keys.

      See Session Resumption for more information.

      @returns

      A 48-byte buffer containing the session ticket keys.

    • port?: number,
      hostname?: string,
      backlog?: number,
      listeningListener?: () => void
      ): this;

      Start a server listening for connections. A net.Server can be a TCP or an IPC server depending on what it listens to.

      Possible signatures:

      • server.listen(handle[, backlog][, callback])
      • server.listen(options[, callback])
      • server.listen(path[, backlog][, callback]) for IPC servers
      • server.listen([port[, host[, backlog]]][, callback]) for TCP servers

      This function is asynchronous. When the server starts listening, the 'listening' event will be emitted. The last parameter callbackwill be added as a listener for the 'listening' event.

      All listen() methods can take a backlog parameter to specify the maximum length of the queue of pending connections. The actual length will be determined by the OS through sysctl settings such as tcp_max_syn_backlog and somaxconn on Linux. The default value of this parameter is 511 (not 512).

      All Socket are set to SO_REUSEADDR (see socket(7) for details).

      The server.listen() method can be called again if and only if there was an error during the first server.listen() call or server.close() has been called. Otherwise, an ERR_SERVER_ALREADY_LISTEN error will be thrown.

      One of the most common errors raised when listening is EADDRINUSE. This happens when another server is already listening on the requestedport/path/handle. One way to handle this would be to retry after a certain amount of time:

      server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
      port?: number,
      hostname?: string,
      listeningListener?: () => void
      ): this;

      Start a server listening for connections. A net.Server can be a TCP or an IPC server depending on what it listens to.

      Possible signatures:

      • server.listen(handle[, backlog][, callback])
      • server.listen(options[, callback])
      • server.listen(path[, backlog][, callback]) for IPC servers
      • server.listen([port[, host[, backlog]]][, callback]) for TCP servers

      This function is asynchronous. When the server starts listening, the 'listening' event will be emitted. The last parameter callbackwill be added as a listener for the 'listening' event.

      All listen() methods can take a backlog parameter to specify the maximum length of the queue of pending connections. The actual length will be determined by the OS through sysctl settings such as tcp_max_syn_backlog and somaxconn on Linux. The default value of this parameter is 511 (not 512).

      All Socket are set to SO_REUSEADDR (see socket(7) for details).

      The server.listen() method can be called again if and only if there was an error during the first server.listen() call or server.close() has been called. Otherwise, an ERR_SERVER_ALREADY_LISTEN error will be thrown.

      One of the most common errors raised when listening is EADDRINUSE. This happens when another server is already listening on the requestedport/path/handle. One way to handle this would be to retry after a certain amount of time:

      server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
      port?: number,
      backlog?: number,
      listeningListener?: () => void
      ): this;

      Start a server listening for connections. A net.Server can be a TCP or an IPC server depending on what it listens to.

      Possible signatures:

      • server.listen(handle[, backlog][, callback])
      • server.listen(options[, callback])
      • server.listen(path[, backlog][, callback]) for IPC servers
      • server.listen([port[, host[, backlog]]][, callback]) for TCP servers

      This function is asynchronous. When the server starts listening, the 'listening' event will be emitted. The last parameter callbackwill be added as a listener for the 'listening' event.

      All listen() methods can take a backlog parameter to specify the maximum length of the queue of pending connections. The actual length will be determined by the OS through sysctl settings such as tcp_max_syn_backlog and somaxconn on Linux. The default value of this parameter is 511 (not 512).

      All Socket are set to SO_REUSEADDR (see socket(7) for details).

      The server.listen() method can be called again if and only if there was an error during the first server.listen() call or server.close() has been called. Otherwise, an ERR_SERVER_ALREADY_LISTEN error will be thrown.

      One of the most common errors raised when listening is EADDRINUSE. This happens when another server is already listening on the requestedport/path/handle. One way to handle this would be to retry after a certain amount of time:

      server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
      port?: number,
      listeningListener?: () => void
      ): this;

      Start a server listening for connections. A net.Server can be a TCP or an IPC server depending on what it listens to.

      Possible signatures:

      • server.listen(handle[, backlog][, callback])
      • server.listen(options[, callback])
      • server.listen(path[, backlog][, callback]) for IPC servers
      • server.listen([port[, host[, backlog]]][, callback]) for TCP servers

      This function is asynchronous. When the server starts listening, the 'listening' event will be emitted. The last parameter callbackwill be added as a listener for the 'listening' event.

      All listen() methods can take a backlog parameter to specify the maximum length of the queue of pending connections. The actual length will be determined by the OS through sysctl settings such as tcp_max_syn_backlog and somaxconn on Linux. The default value of this parameter is 511 (not 512).

      All Socket are set to SO_REUSEADDR (see socket(7) for details).

      The server.listen() method can be called again if and only if there was an error during the first server.listen() call or server.close() has been called. Otherwise, an ERR_SERVER_ALREADY_LISTEN error will be thrown.

      One of the most common errors raised when listening is EADDRINUSE. This happens when another server is already listening on the requestedport/path/handle. One way to handle this would be to retry after a certain amount of time:

      server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
      path: string,
      backlog?: number,
      listeningListener?: () => void
      ): this;

      Start a server listening for connections. A net.Server can be a TCP or an IPC server depending on what it listens to.

      Possible signatures:

      • server.listen(handle[, backlog][, callback])
      • server.listen(options[, callback])
      • server.listen(path[, backlog][, callback]) for IPC servers
      • server.listen([port[, host[, backlog]]][, callback]) for TCP servers

      This function is asynchronous. When the server starts listening, the 'listening' event will be emitted. The last parameter callbackwill be added as a listener for the 'listening' event.

      All listen() methods can take a backlog parameter to specify the maximum length of the queue of pending connections. The actual length will be determined by the OS through sysctl settings such as tcp_max_syn_backlog and somaxconn on Linux. The default value of this parameter is 511 (not 512).

      All Socket are set to SO_REUSEADDR (see socket(7) for details).

      The server.listen() method can be called again if and only if there was an error during the first server.listen() call or server.close() has been called. Otherwise, an ERR_SERVER_ALREADY_LISTEN error will be thrown.

      One of the most common errors raised when listening is EADDRINUSE. This happens when another server is already listening on the requestedport/path/handle. One way to handle this would be to retry after a certain amount of time:

      server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
      path: string,
      listeningListener?: () => void
      ): this;

      Start a server listening for connections. A net.Server can be a TCP or an IPC server depending on what it listens to.

      Possible signatures:

      • server.listen(handle[, backlog][, callback])
      • server.listen(options[, callback])
      • server.listen(path[, backlog][, callback]) for IPC servers
      • server.listen([port[, host[, backlog]]][, callback]) for TCP servers

      This function is asynchronous. When the server starts listening, the 'listening' event will be emitted. The last parameter callbackwill be added as a listener for the 'listening' event.

      All listen() methods can take a backlog parameter to specify the maximum length of the queue of pending connections. The actual length will be determined by the OS through sysctl settings such as tcp_max_syn_backlog and somaxconn on Linux. The default value of this parameter is 511 (not 512).

      All Socket are set to SO_REUSEADDR (see socket(7) for details).

      The server.listen() method can be called again if and only if there was an error during the first server.listen() call or server.close() has been called. Otherwise, an ERR_SERVER_ALREADY_LISTEN error will be thrown.

      One of the most common errors raised when listening is EADDRINUSE. This happens when another server is already listening on the requestedport/path/handle. One way to handle this would be to retry after a certain amount of time:

      server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
      options: ListenOptions,
      listeningListener?: () => void
      ): this;

      Start a server listening for connections. A net.Server can be a TCP or an IPC server depending on what it listens to.

      Possible signatures:

      • server.listen(handle[, backlog][, callback])
      • server.listen(options[, callback])
      • server.listen(path[, backlog][, callback]) for IPC servers
      • server.listen([port[, host[, backlog]]][, callback]) for TCP servers

      This function is asynchronous. When the server starts listening, the 'listening' event will be emitted. The last parameter callbackwill be added as a listener for the 'listening' event.

      All listen() methods can take a backlog parameter to specify the maximum length of the queue of pending connections. The actual length will be determined by the OS through sysctl settings such as tcp_max_syn_backlog and somaxconn on Linux. The default value of this parameter is 511 (not 512).

      All Socket are set to SO_REUSEADDR (see socket(7) for details).

      The server.listen() method can be called again if and only if there was an error during the first server.listen() call or server.close() has been called. Otherwise, an ERR_SERVER_ALREADY_LISTEN error will be thrown.

      One of the most common errors raised when listening is EADDRINUSE. This happens when another server is already listening on the requestedport/path/handle. One way to handle this would be to retry after a certain amount of time:

      server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
      handle: any,
      backlog?: number,
      listeningListener?: () => void
      ): this;

      Start a server listening for connections. A net.Server can be a TCP or an IPC server depending on what it listens to.

      Possible signatures:

      • server.listen(handle[, backlog][, callback])
      • server.listen(options[, callback])
      • server.listen(path[, backlog][, callback]) for IPC servers
      • server.listen([port[, host[, backlog]]][, callback]) for TCP servers

      This function is asynchronous. When the server starts listening, the 'listening' event will be emitted. The last parameter callbackwill be added as a listener for the 'listening' event.

      All listen() methods can take a backlog parameter to specify the maximum length of the queue of pending connections. The actual length will be determined by the OS through sysctl settings such as tcp_max_syn_backlog and somaxconn on Linux. The default value of this parameter is 511 (not 512).

      All Socket are set to SO_REUSEADDR (see socket(7) for details).

      The server.listen() method can be called again if and only if there was an error during the first server.listen() call or server.close() has been called. Otherwise, an ERR_SERVER_ALREADY_LISTEN error will be thrown.

      One of the most common errors raised when listening is EADDRINUSE. This happens when another server is already listening on the requestedport/path/handle. One way to handle this would be to retry after a certain amount of time:

      server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
      handle: any,
      listeningListener?: () => void
      ): this;

      Start a server listening for connections. A net.Server can be a TCP or an IPC server depending on what it listens to.

      Possible signatures:

      • server.listen(handle[, backlog][, callback])
      • server.listen(options[, callback])
      • server.listen(path[, backlog][, callback]) for IPC servers
      • server.listen([port[, host[, backlog]]][, callback]) for TCP servers

      This function is asynchronous. When the server starts listening, the 'listening' event will be emitted. The last parameter callbackwill be added as a listener for the 'listening' event.

      All listen() methods can take a backlog parameter to specify the maximum length of the queue of pending connections. The actual length will be determined by the OS through sysctl settings such as tcp_max_syn_backlog and somaxconn on Linux. The default value of this parameter is 511 (not 512).

      All Socket are set to SO_REUSEADDR (see socket(7) for details).

      The server.listen() method can be called again if and only if there was an error during the first server.listen() call or server.close() has been called. Otherwise, an ERR_SERVER_ALREADY_LISTEN error will be thrown.

      One of the most common errors raised when listening is EADDRINUSE. This happens when another server is already listening on the requestedport/path/handle. One way to handle this would be to retry after a certain amount of time:

      server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
    • eventName: string | symbol,
      listener?: Function
      ): number;

      Returns the number of listeners listening for the event named eventName. If listener is provided, it will return how many times the listener is found in the list of the listeners of the event.

      @param eventName

      The name of the event being listened for

      @param listener

      The event handler function

    • eventName: string | symbol
      ): Function[];

      Returns a copy of the array of listeners for the event named eventName.

      server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]
    • off<K>(
      eventName: string | symbol,
      listener: (...args: any[]) => void
      ): this;

      Alias for emitter.removeListener().

    • event: string,
      listener: (...args: any[]) => void
      ): this;

      Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

      server.on('connection', (stream) => {
  console.log('someone connected!');
});

      Returns a reference to the EventEmitter, so that calls can be chained.

      By default, event listeners are invoked in the order they are added. The emitter.prependListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

      import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
      @param listener

      The callback function

      event: 'keylog',
      listener: (line: Buffer, tlsSocket: TLSSocket) => void
      ): this;
      event: 'newSession',
      listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void
      ): this;
      event: 'OCSPRequest',
      listener: (certificate: Buffer, issuer: Buffer, callback: (err: null | Error, resp: Buffer) => void) => void
      ): this;
      event: 'resumeSession',
      listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void
      ): this;
      event: 'secureConnection',
      listener: (tlsSocket: TLSSocket) => void
      ): this;
      event: 'tlsClientError',
      listener: (err: Error, tlsSocket: TLSSocket) => void
      ): this;
      event: 'close',
      listener: () => void
      ): this;
      event: 'connection',
      listener: (socket: Duplex) => void
      ): this;
      event: 'error',
      listener: (err: Error) => void
      ): this;
      event: 'listening',
      listener: () => void
      ): this;
      event: 'checkContinue',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'checkExpectation',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'clientError',
      listener: (err: Error, socket: Duplex) => void
      ): this;
      event: 'connect',
      listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void
      ): this;
      event: 'request',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'upgrade',
      listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void
      ): this;
    • event: string,
      listener: (...args: any[]) => void
      ): this;

      Adds a one-time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

      server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

      Returns a reference to the EventEmitter, so that calls can be chained.

      By default, event listeners are invoked in the order they are added. The emitter.prependOnceListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

      import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
      @param listener

      The callback function

      event: 'keylog',
      listener: (line: Buffer, tlsSocket: TLSSocket) => void
      ): this;
      event: 'newSession',
      listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void
      ): this;
      event: 'OCSPRequest',
      listener: (certificate: Buffer, issuer: Buffer, callback: (err: null | Error, resp: Buffer) => void) => void
      ): this;
      event: 'resumeSession',
      listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void
      ): this;
      event: 'secureConnection',
      listener: (tlsSocket: TLSSocket) => void
      ): this;
      event: 'tlsClientError',
      listener: (err: Error, tlsSocket: TLSSocket) => void
      ): this;
      event: 'close',
      listener: () => void
      ): this;
      event: 'connection',
      listener: (socket: Duplex) => void
      ): this;
      event: 'error',
      listener: (err: Error) => void
      ): this;
      event: 'listening',
      listener: () => void
      ): this;
      event: 'checkContinue',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'checkExpectation',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'clientError',
      listener: (err: Error, socket: Duplex) => void
      ): this;
      event: 'connect',
      listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void
      ): this;
      event: 'request',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'upgrade',
      listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void
      ): this;
    • event: string,
      listener: (...args: any[]) => void
      ): this;

      Adds the listener function to the beginning of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

      server.prependListener('connection', (stream) => {
  console.log('someone connected!');
});

      Returns a reference to the EventEmitter, so that calls can be chained.

      @param listener

      The callback function

      event: 'keylog',
      listener: (line: Buffer, tlsSocket: TLSSocket) => void
      ): this;
      event: 'newSession',
      listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void
      ): this;
      event: 'OCSPRequest',
      listener: (certificate: Buffer, issuer: Buffer, callback: (err: null | Error, resp: Buffer) => void) => void
      ): this;
      event: 'resumeSession',
      listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void
      ): this;
      event: 'secureConnection',
      listener: (tlsSocket: TLSSocket) => void
      ): this;
      event: 'tlsClientError',
      listener: (err: Error, tlsSocket: TLSSocket) => void
      ): this;
      event: 'close',
      listener: () => void
      ): this;
      event: 'connection',
      listener: (socket: Duplex) => void
      ): this;
      event: 'error',
      listener: (err: Error) => void
      ): this;
      event: 'listening',
      listener: () => void
      ): this;
      event: 'checkContinue',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'checkExpectation',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'clientError',
      listener: (err: Error, socket: Duplex) => void
      ): this;
      event: 'connect',
      listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void
      ): this;
      event: 'request',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'upgrade',
      listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void
      ): this;
    • event: string,
      listener: (...args: any[]) => void
      ): this;

      Adds a one-timelistener function for the event named eventName to the beginning of the listeners array. The next time eventName is triggered, this listener is removed, and then invoked.

      server.prependOnceListener('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

      Returns a reference to the EventEmitter, so that calls can be chained.

      @param listener

      The callback function

      event: 'keylog',
      listener: (line: Buffer, tlsSocket: TLSSocket) => void
      ): this;
      event: 'newSession',
      listener: (sessionId: Buffer, sessionData: Buffer, callback: (err: Error, resp: Buffer) => void) => void
      ): this;
      event: 'OCSPRequest',
      listener: (certificate: Buffer, issuer: Buffer, callback: (err: null | Error, resp: Buffer) => void) => void
      ): this;
      event: 'resumeSession',
      listener: (sessionId: Buffer, callback: (err: Error, sessionData: Buffer) => void) => void
      ): this;
      event: 'secureConnection',
      listener: (tlsSocket: TLSSocket) => void
      ): this;
      event: 'tlsClientError',
      listener: (err: Error, tlsSocket: TLSSocket) => void
      ): this;
      event: 'close',
      listener: () => void
      ): this;
      event: 'connection',
      listener: (socket: Duplex) => void
      ): this;
      event: 'error',
      listener: (err: Error) => void
      ): this;
      event: 'listening',
      listener: () => void
      ): this;
      event: 'checkContinue',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'checkExpectation',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'clientError',
      listener: (err: Error, socket: Duplex) => void
      ): this;
      event: 'connect',
      listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void
      ): this;
      event: 'request',
      listener: RequestListener<Request, Response>
      ): this;
      event: 'upgrade',
      listener: (req: InstanceType<Request>, socket: Duplex, head: Buffer) => void
      ): this;
    • eventName: string | symbol
      ): Function[];

      Returns a copy of the array of listeners for the event named eventName, including any wrappers (such as those created by .once()).

      import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');
    • ref(): this;

      Opposite of unref(), calling ref() on a previously unrefed server will not let the program exit if it's the only server left (the default behavior). If the server is refed calling ref() again will have no effect.

    • eventName?: string | symbol
      ): this;

      Removes all listeners, or those of the specified eventName.

      It is bad practice to remove listeners added elsewhere in the code, particularly when the EventEmitter instance was created by some other component or module (e.g. sockets or file streams).

      Returns a reference to the EventEmitter, so that calls can be chained.

    • eventName: string | symbol,
      listener: (...args: any[]) => void
      ): this;

      Removes the specified listener from the listener array for the event named eventName.

      const callback = (stream) => {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

      removeListener() will remove, at most, one instance of a listener from the listener array. If any single listener has been added multiple times to the listener array for the specified eventName, then removeListener() must be called multiple times to remove each instance.

      Once an event is emitted, all listeners attached to it at the time of emitting are called in order. This implies that any removeListener() or removeAllListeners() calls after emitting and before the last listener finishes execution will not remove them fromemit() in progress. Subsequent events behave as expected.

      import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

      Because listeners are managed using an internal array, calling this will change the position indices of any listener registered after the listener being removed. This will not impact the order in which listeners are called, but it means that any copies of the listener array as returned by the emitter.listeners() method will need to be recreated.

      When a single function has been added as a handler multiple times for a single event (as in the example below), removeListener() will remove the most recently added instance. In the example the once('ping') listener is removed:

      import { EventEmitter } from 'node:events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

      Returns a reference to the EventEmitter, so that calls can be chained.

    • n: number
      ): this;

      By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default that helps finding memory leaks. The emitter.setMaxListeners() method allows the limit to be modified for this specific EventEmitter instance. The value can be set to Infinity (or 0) to indicate an unlimited number of listeners.

      Returns a reference to the EventEmitter, so that calls can be chained.

    • options: SecureContextOptions
      ): void;

      The server.setSecureContext() method replaces the secure context of an existing server. Existing connections to the server are not interrupted.

      @param options

      An object containing any of the possible properties from the createSecureContext options arguments (e.g. key, cert, ca, etc).

    • keys: Buffer
      ): void;

      Sets the session ticket keys.

      Changes to the ticket keys are effective only for future server connections. Existing or currently pending server connections will use the previous keys.

      See Session Resumption for more information.

      @param keys

      A 48-byte buffer containing the session ticket keys.

    • msecs?: number,
      callback?: (socket: Socket) => void
      ): this;

      Sets the timeout value for sockets, and emits a 'timeout' event on the Server object, passing the socket as an argument, if a timeout occurs.

      If there is a 'timeout' event listener on the Server object, then it will be called with the timed-out socket as an argument.

      By default, the Server does not timeout sockets. However, if a callback is assigned to the Server's 'timeout' event, timeouts must be handled explicitly.

      callback: (socket: Socket) => void
      ): this;

      Sets the timeout value for sockets, and emits a 'timeout' event on the Server object, passing the socket as an argument, if a timeout occurs.

      If there is a 'timeout' event listener on the Server object, then it will be called with the timed-out socket as an argument.

      By default, the Server does not timeout sockets. However, if a callback is assigned to the Server's 'timeout' event, timeouts must be handled explicitly.

    • unref(): this;

      Calling unref() on a server will allow the program to exit if this is the only active server in the event system. If the server is already unrefed callingunref() again will have no effect.

    • signal: AbortSignal,
      resource: (event: Event) => void
      ): Disposable;

      Listens once to the abort event on the provided signal.

      Listening to the abort event on abort signals is unsafe and may lead to resource leaks since another third party with the signal can call e.stopImmediatePropagation(). Unfortunately Node.js cannot change this since it would violate the web standard. Additionally, the original API makes it easy to forget to remove listeners.

      This API allows safely using AbortSignals in Node.js APIs by solving these two issues by listening to the event such that stopImmediatePropagation does not prevent the listener from running.

      Returns a disposable so that it may be unsubscribed from more easily.

      import { addAbortListener } from 'node:events';

function example(signal) {
  let disposable;
  try {
    signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
    disposable = addAbortListener(signal, (e) => {
      // Do something when signal is aborted.
    });
  } finally {
    disposable?.[Symbol.dispose]();
  }
}
      @returns

      Disposable that removes the abort listener.

    • emitter: EventEmitter<DefaultEventMap> | EventTarget,
      name: string | symbol
      ): Function[];

      Returns a copy of the array of listeners for the event named eventName.

      For EventEmitters this behaves exactly the same as calling .listeners on the emitter.

      For EventTargets this is the only way to get the event listeners for the event target. This is useful for debugging and diagnostic purposes.

      import { getEventListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  const listener = () => console.log('Events are fun');
  ee.on('foo', listener);
  console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
}
{
  const et = new EventTarget();
  const listener = () => console.log('Events are fun');
  et.addEventListener('foo', listener);
  console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
}
    • emitter: EventEmitter<DefaultEventMap> | EventTarget
      ): number;

      Returns the currently set max amount of listeners.

      For EventEmitters this behaves exactly the same as calling .getMaxListeners on the emitter.

      For EventTargets this is the only way to get the max event listeners for the event target. If the number of event handlers on a single EventTarget exceeds the max set, the EventTarget will print a warning.

      import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  console.log(getMaxListeners(ee)); // 10
  setMaxListeners(11, ee);
  console.log(getMaxListeners(ee)); // 11
}
{
  const et = new EventTarget();
  console.log(getMaxListeners(et)); // 10
  setMaxListeners(11, et);
  console.log(getMaxListeners(et)); // 11
}
    • static on(
      emitter: EventEmitter,
      eventName: string | symbol,
      options?: StaticEventEmitterIteratorOptions
      ): AsyncIterator<any[]>;
      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
});

for await (const event of on(ee, 'foo')) {
  // The execution of this inner block is synchronous and it
  // processes one event at a time (even with await). Do not use
  // if concurrent execution is required.
  console.log(event); // prints ['bar'] [42]
}
// Unreachable here

      Returns an AsyncIterator that iterates eventName events. It will throw if the EventEmitter emits 'error'. It removes all listeners when exiting the loop. The value returned by each iteration is an array composed of the emitted event arguments.

      An AbortSignal can be used to cancel waiting on events:

      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ac = new AbortController();

(async () => {
  const ee = new EventEmitter();

  // Emit later on
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // The execution of this inner block is synchronous and it
    // processes one event at a time (even with await). Do not use
    // if concurrent execution is required.
    console.log(event); // prints ['bar'] [42]
  }
  // Unreachable here
})();

process.nextTick(() => ac.abort());

      Use the close option to specify an array of event names that will end the iteration:

      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
  ee.emit('close');
});

for await (const event of on(ee, 'foo', { close: ['close'] })) {
  console.log(event); // prints ['bar'] [42]
}
// the loop will exit after 'close' is emitted
console.log('done'); // prints 'done'
      @returns

      An AsyncIterator that iterates eventName events emitted by the emitter

      static on(
      emitter: EventTarget,
      eventName: string,
      options?: StaticEventEmitterIteratorOptions
      ): AsyncIterator<any[]>;
      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
});

for await (const event of on(ee, 'foo')) {
  // The execution of this inner block is synchronous and it
  // processes one event at a time (even with await). Do not use
  // if concurrent execution is required.
  console.log(event); // prints ['bar'] [42]
}
// Unreachable here

      Returns an AsyncIterator that iterates eventName events. It will throw if the EventEmitter emits 'error'. It removes all listeners when exiting the loop. The value returned by each iteration is an array composed of the emitted event arguments.

      An AbortSignal can be used to cancel waiting on events:

      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ac = new AbortController();

(async () => {
  const ee = new EventEmitter();

  // Emit later on
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // The execution of this inner block is synchronous and it
    // processes one event at a time (even with await). Do not use
    // if concurrent execution is required.
    console.log(event); // prints ['bar'] [42]
  }
  // Unreachable here
})();

process.nextTick(() => ac.abort());

      Use the close option to specify an array of event names that will end the iteration:

      import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
  ee.emit('close');
});

for await (const event of on(ee, 'foo', { close: ['close'] })) {
  console.log(event); // prints ['bar'] [42]
}
// the loop will exit after 'close' is emitted
console.log('done'); // prints 'done'
      @returns

      An AsyncIterator that iterates eventName events emitted by the emitter

    • static once(
      emitter: EventEmitter,
      eventName: string | symbol,
      options?: StaticEventEmitterOptions
      ): Promise<any[]>;

      Creates a Promise that is fulfilled when the EventEmitter emits the given event or that is rejected if the EventEmitter emits 'error' while waiting. The Promise will resolve with an array of all the arguments emitted to the given event.

      This method is intentionally generic and works with the web platform EventTarget interface, which has no special'error' event semantics and does not listen to the 'error' event.

      import { once, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

process.nextTick(() => {
  ee.emit('myevent', 42);
});

const [value] = await once(ee, 'myevent');
console.log(value);

const err = new Error('kaboom');
process.nextTick(() => {
  ee.emit('error', err);
});

try {
  await once(ee, 'myevent');
} catch (err) {
  console.error('error happened', err);
}

      The special handling of the 'error' event is only used when events.once() is used to wait for another event. If events.once() is used to wait for the 'error' event itself, then it is treated as any other kind of event without special handling:

      import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();

once(ee, 'error')
  .then(([err]) => console.log('ok', err.message))
  .catch((err) => console.error('error', err.message));

ee.emit('error', new Error('boom'));

// Prints: ok boom

      An AbortSignal can be used to cancel waiting for the event:

      import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();
const ac = new AbortController();

async function foo(emitter, event, signal) {
  try {
    await once(emitter, event, { signal });
    console.log('event emitted!');
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
    } else {
      console.error('There was an error', error.message);
    }
  }
}

foo(ee, 'foo', ac.signal);
ac.abort(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!
      static once(
      emitter: EventTarget,
      eventName: string,
      options?: StaticEventEmitterOptions
      ): Promise<any[]>;

      Creates a Promise that is fulfilled when the EventEmitter emits the given event or that is rejected if the EventEmitter emits 'error' while waiting. The Promise will resolve with an array of all the arguments emitted to the given event.

      This method is intentionally generic and works with the web platform EventTarget interface, which has no special'error' event semantics and does not listen to the 'error' event.

      import { once, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

process.nextTick(() => {
  ee.emit('myevent', 42);
});

const [value] = await once(ee, 'myevent');
console.log(value);

const err = new Error('kaboom');
process.nextTick(() => {
  ee.emit('error', err);
});

try {
  await once(ee, 'myevent');
} catch (err) {
  console.error('error happened', err);
}

      The special handling of the 'error' event is only used when events.once() is used to wait for another event. If events.once() is used to wait for the 'error' event itself, then it is treated as any other kind of event without special handling:

      import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();

once(ee, 'error')
  .then(([err]) => console.log('ok', err.message))
  .catch((err) => console.error('error', err.message));

ee.emit('error', new Error('boom'));

// Prints: ok boom

      An AbortSignal can be used to cancel waiting for the event:

      import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();
const ac = new AbortController();

async function foo(emitter, event, signal) {
  try {
    await once(emitter, event, { signal });
    console.log('event emitted!');
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
    } else {
      console.error('There was an error', error.message);
    }
  }
}

foo(ee, 'foo', ac.signal);
ac.abort(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!
    • n?: number,
      ...eventTargets: EventEmitter<DefaultEventMap> | EventTarget[]
      ): void;
      import { setMaxListeners, EventEmitter } from 'node:events';

const target = new EventTarget();
const emitter = new EventEmitter();

setMaxListeners(5, target, emitter);
      @param n

      A non-negative number. The maximum number of listeners per EventTarget event.

      @param eventTargets

      Zero or more {EventTarget} or {EventEmitter} instances. If none are specified, n is set as the default max for all newly created {EventTarget} and {EventEmitter} objects.

  • function createServer<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse>(
    requestListener?: RequestListener<Request, Response>
    ): Server<Request, Response>;
    // curl -k https://localhost:8000/
import https from 'node:https';
import fs from 'node:fs';

const options = {
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);

    Or

    import https from 'node:https';
import fs from 'node:fs';

const options = {
  pfx: fs.readFileSync('test/fixtures/test_cert.pfx'),
  passphrase: 'sample',
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);
    @param requestListener

    A listener to be added to the 'request' event.

    function createServer<Request extends typeof IncomingMessage = typeof IncomingMessage, Response extends typeof ServerResponse = typeof ServerResponse>(
    options: ServerOptions<Request, Response>,
    requestListener?: RequestListener<Request, Response>
    ): Server<Request, Response>;
    // curl -k https://localhost:8000/
import https from 'node:https';
import fs from 'node:fs';

const options = {
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);

    Or

    import https from 'node:https';
import fs from 'node:fs';

const options = {
  pfx: fs.readFileSync('test/fixtures/test_cert.pfx'),
  passphrase: 'sample',
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);
    @param options

    Accepts options from createServer, createSecureContext and createServer.

    @param requestListener

    A listener to be added to the 'request' event.

  • function get(
    options: string | URL | RequestOptions,
    callback?: (res: IncomingMessage) => void

    Like http.get() but for HTTPS.

    options can be an object, a string, or a URL object. If options is a string, it is automatically parsed with new URL(). If it is a URL object, it will be automatically converted to an ordinary options object.

    import https from 'node:https';

https.get('https://encrypted.google.com/', (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });

}).on('error', (e) => {
  console.error(e);
});
    @param options

    Accepts the same options as request, with the method always set to GET.

    function get(
    url: string | URL,
    options: RequestOptions,
    callback?: (res: IncomingMessage) => void

    Like http.get() but for HTTPS.

    options can be an object, a string, or a URL object. If options is a string, it is automatically parsed with new URL(). If it is a URL object, it will be automatically converted to an ordinary options object.

    import https from 'node:https';

https.get('https://encrypted.google.com/', (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });

}).on('error', (e) => {
  console.error(e);
});
    @param options

    Accepts the same options as request, with the method always set to GET.

  • function request(
    options: string | URL | RequestOptions,
    callback?: (res: IncomingMessage) => void

    Makes a request to a secure web server.

    The following additional options from tls.connect() are also accepted: ca, cert, ciphers, clientCertEngine, crl, dhparam, ecdhCurve, honorCipherOrder, key, passphrase, pfx, rejectUnauthorized, secureOptions, secureProtocol, servername, sessionIdContext, highWaterMark.

    options can be an object, a string, or a URL object. If options is a string, it is automatically parsed with new URL(). If it is a URL object, it will be automatically converted to an ordinary options object.

    https.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.

    import https from 'node:https';

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
};

const req = https.request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.on('error', (e) => {
  console.error(e);
});
req.end();

    Example using options from tls.connect():

    const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
};
options.agent = new https.Agent(options);

const req = https.request(options, (res) => {
  // ...
});

    Alternatively, opt out of connection pooling by not using an Agent.

    const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
  agent: false,
};

const req = https.request(options, (res) => {
  // ...
});

    Example using a URL as options:

    const options = new URL('https://abc:xyz@example.com');

const req = https.request(options, (res) => {
  // ...
});

    Example pinning on certificate fingerprint, or the public key (similar topin-sha256):

    import tls from 'node:tls';
import https from 'node:https';
import crypto from 'node:crypto';

function sha256(s) {
  return crypto.createHash('sha256').update(s).digest('base64');
}
const options = {
  hostname: 'github.com',
  port: 443,
  path: '/',
  method: 'GET',
  checkServerIdentity: function(host, cert) {
    // Make sure the certificate is issued to the host we are connected to
    const err = tls.checkServerIdentity(host, cert);
    if (err) {
      return err;
    }

    // Pin the public key, similar to HPKP pin-sha256 pinning
    const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';
    if (sha256(cert.pubkey) !== pubkey256) {
      const msg = 'Certificate verification error: ' +
        `The public key of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // Pin the exact certificate, rather than the pub key
    const cert256 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' +
      'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16';
    if (cert.fingerprint256 !== cert256) {
      const msg = 'Certificate verification error: ' +
        `The certificate of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // This loop is informational only.
    // Print the certificate and public key fingerprints of all certs in the
    // chain. Its common to pin the public key of the issuer on the public
    // internet, while pinning the public key of the service in sensitive
    // environments.
    do {
      console.log('Subject Common Name:', cert.subject.CN);
      console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);

      hash = crypto.createHash('sha256');
      console.log('  Public key ping-sha256:', sha256(cert.pubkey));

      lastprint256 = cert.fingerprint256;
      cert = cert.issuerCertificate;
    } while (cert.fingerprint256 !== lastprint256);

  },
};

options.agent = new https.Agent(options);
const req = https.request(options, (res) => {
  console.log('All OK. Server matched our pinned cert or public key');
  console.log('statusCode:', res.statusCode);
  // Print the HPKP values
  console.log('headers:', res.headers['public-key-pins']);

  res.on('data', (d) => {});
});

req.on('error', (e) => {
  console.error(e.message);
});
req.end();

    Outputs for example:

    Subject Common Name: github.com
  Certificate SHA256 fingerprint: 25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16
  Public key ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=
Subject Common Name: DigiCert SHA2 Extended Validation Server CA
  Certificate SHA256 fingerprint: 40:3E:06:2A:26:53:05:91:13:28:5B:AF:80:A0:D4:AE:42:2C:84:8C:9F:78:FA:D0:1F:C9:4B:C5:B8:7F:EF:1A
  Public key ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=
Subject Common Name: DigiCert High Assurance EV Root CA
  Certificate SHA256 fingerprint: 74:31:E5:F4:C3:C1:CE:46:90:77:4F:0B:61:E0:54:40:88:3B:A9:A0:1E:D0:0B:A6:AB:D7:80:6E:D3:B1:18:CF
  Public key ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18=
All OK. Server matched our pinned cert or public key
statusCode: 200
headers: max-age=0; pin-sha256="WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="; pin-sha256="RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=";
pin-sha256="k2v657xBsOVe1PQRwOsHsw3bsGT2VzIqz5K+59sNQws="; pin-sha256="K87oWBWM9UZfyddvDfoxL+8lpNyoUB2ptGtn0fv6G2Q="; pin-sha256="IQBnNBEiFuhj+8x6X8XLgh01V9Ic5/V3IRQLNFFc7v4=";
pin-sha256="iie1VXtL7HzAMF+/PVPR9xzT80kQxdZeJ+zduCB3uj0="; pin-sha256="LvRiGEjRqfzurezaWuj8Wie2gyHMrW5Q06LspMnox7A="; includeSubDomains
    @param options

    Accepts all options from request, with some differences in default values:

    function request(
    url: string | URL,
    options: RequestOptions,
    callback?: (res: IncomingMessage) => void

    Makes a request to a secure web server.

    The following additional options from tls.connect() are also accepted: ca, cert, ciphers, clientCertEngine, crl, dhparam, ecdhCurve, honorCipherOrder, key, passphrase, pfx, rejectUnauthorized, secureOptions, secureProtocol, servername, sessionIdContext, highWaterMark.

    options can be an object, a string, or a URL object. If options is a string, it is automatically parsed with new URL(). If it is a URL object, it will be automatically converted to an ordinary options object.

    https.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.

    import https from 'node:https';

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
};

const req = https.request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.on('error', (e) => {
  console.error(e);
});
req.end();

    Example using options from tls.connect():

    const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
};
options.agent = new https.Agent(options);

const req = https.request(options, (res) => {
  // ...
});

    Alternatively, opt out of connection pooling by not using an Agent.

    const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
  agent: false,
};

const req = https.request(options, (res) => {
  // ...
});

    Example using a URL as options:

    const options = new URL('https://abc:xyz@example.com');

const req = https.request(options, (res) => {
  // ...
});

    Example pinning on certificate fingerprint, or the public key (similar topin-sha256):

    import tls from 'node:tls';
import https from 'node:https';
import crypto from 'node:crypto';

function sha256(s) {
  return crypto.createHash('sha256').update(s).digest('base64');
}
const options = {
  hostname: 'github.com',
  port: 443,
  path: '/',
  method: 'GET',
  checkServerIdentity: function(host, cert) {
    // Make sure the certificate is issued to the host we are connected to
    const err = tls.checkServerIdentity(host, cert);
    if (err) {
      return err;
    }

    // Pin the public key, similar to HPKP pin-sha256 pinning
    const pubkey256 = 'pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=';
    if (sha256(cert.pubkey) !== pubkey256) {
      const msg = 'Certificate verification error: ' +
        `The public key of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // Pin the exact certificate, rather than the pub key
    const cert256 = '25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:' +
      'D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16';
    if (cert.fingerprint256 !== cert256) {
      const msg = 'Certificate verification error: ' +
        `The certificate of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // This loop is informational only.
    // Print the certificate and public key fingerprints of all certs in the
    // chain. Its common to pin the public key of the issuer on the public
    // internet, while pinning the public key of the service in sensitive
    // environments.
    do {
      console.log('Subject Common Name:', cert.subject.CN);
      console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);

      hash = crypto.createHash('sha256');
      console.log('  Public key ping-sha256:', sha256(cert.pubkey));

      lastprint256 = cert.fingerprint256;
      cert = cert.issuerCertificate;
    } while (cert.fingerprint256 !== lastprint256);

  },
};

options.agent = new https.Agent(options);
const req = https.request(options, (res) => {
  console.log('All OK. Server matched our pinned cert or public key');
  console.log('statusCode:', res.statusCode);
  // Print the HPKP values
  console.log('headers:', res.headers['public-key-pins']);

  res.on('data', (d) => {});
});

req.on('error', (e) => {
  console.error(e.message);
});
req.end();

    Outputs for example:

    Subject Common Name: github.com
  Certificate SHA256 fingerprint: 25:FE:39:32:D9:63:8C:8A:FC:A1:9A:29:87:D8:3E:4C:1D:98:DB:71:E4:1A:48:03:98:EA:22:6A:BD:8B:93:16
  Public key ping-sha256: pL1+qb9HTMRZJmuC/bB/ZI9d302BYrrqiVuRyW+DGrU=
Subject Common Name: DigiCert SHA2 Extended Validation Server CA
  Certificate SHA256 fingerprint: 40:3E:06:2A:26:53:05:91:13:28:5B:AF:80:A0:D4:AE:42:2C:84:8C:9F:78:FA:D0:1F:C9:4B:C5:B8:7F:EF:1A
  Public key ping-sha256: RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=
Subject Common Name: DigiCert High Assurance EV Root CA
  Certificate SHA256 fingerprint: 74:31:E5:F4:C3:C1:CE:46:90:77:4F:0B:61:E0:54:40:88:3B:A9:A0:1E:D0:0B:A6:AB:D7:80:6E:D3:B1:18:CF
  Public key ping-sha256: WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18=
All OK. Server matched our pinned cert or public key
statusCode: 200
headers: max-age=0; pin-sha256="WoiWRyIOVNa9ihaBciRSC7XHjliYS9VwUGOIud4PB18="; pin-sha256="RRM1dGqnDFsCJXBTHky16vi1obOlCgFFn/yOhI/y+ho=";
pin-sha256="k2v657xBsOVe1PQRwOsHsw3bsGT2VzIqz5K+59sNQws="; pin-sha256="K87oWBWM9UZfyddvDfoxL+8lpNyoUB2ptGtn0fv6G2Q="; pin-sha256="IQBnNBEiFuhj+8x6X8XLgh01V9Ic5/V3IRQLNFFc7v4=";
pin-sha256="iie1VXtL7HzAMF+/PVPR9xzT80kQxdZeJ+zduCB3uj0="; pin-sha256="LvRiGEjRqfzurezaWuj8Wie2gyHMrW5Q06LspMnox7A="; includeSubDomains
    @param options

    Accepts all options from request, with some differences in default values:

Type definitions

  • interface AgentOptions

    • allowPartialTrustChain?: boolean

      Treat intermediate (non-self-signed) certificates in the trust CA certificate list as trusted.

    • ALPNCallback?: (arg: { protocols: string[]; servername: string }) => undefined | string

      If set, this will be called when a client opens a connection using the ALPN extension. One argument will be passed to the callback: an object containing servername and protocols fields, respectively containing the server name from the SNI extension (if any) and an array of ALPN protocol name strings. The callback must return either one of the strings listed in protocols, which will be returned to the client as the selected ALPN protocol, or undefined, to reject the connection with a fatal alert. If a string is returned that does not match one of the client's ALPN protocols, an error will be thrown. This option cannot be used with the ALPNProtocols option, and setting both options will throw an error.

    • ALPNProtocols?: Uint8Array<ArrayBufferLike> | string[] | Uint8Array<ArrayBufferLike>[]

      An array of strings or a Buffer naming possible ALPN protocols. (Protocols should be ordered by their priority.)

    • ca?: string | Buffer<ArrayBufferLike> | string | Buffer<ArrayBufferLike>[]

      Optionally override the trusted CA certificates. Default is to trust the well-known CAs curated by Mozilla. Mozilla's CAs are completely replaced when CAs are explicitly specified using this option.

    • cert?: string | Buffer<ArrayBufferLike> | string | Buffer<ArrayBufferLike>[]

      Cert chains in PEM format. One cert chain should be provided per private key. Each cert chain should consist of the PEM formatted certificate for a provided private key, followed by the PEM formatted intermediate certificates (if any), in order, and not including the root CA (the root CA must be pre-known to the peer, see ca). When providing multiple cert chains, they do not have to be in the same order as their private keys in key. If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail.

    • checkServerIdentity?: (hostname: string, cert: PeerCertificate) => undefined | Error
    • ciphers?: string

      Cipher suite specification, replacing the default. For more information, see modifying the default cipher suite. Permitted ciphers can be obtained via tls.getCiphers(). Cipher names must be uppercased in order for OpenSSL to accept them.

    • crl?: string | Buffer<ArrayBufferLike> | string | Buffer<ArrayBufferLike>[]

      PEM formatted CRLs (Certificate Revocation Lists).

    • dhparam?: string | Buffer<ArrayBufferLike>

      'auto' or custom Diffie-Hellman parameters, required for non-ECDHE perfect forward secrecy. If omitted or invalid, the parameters are silently discarded and DHE ciphers will not be available. ECDHE-based perfect forward secrecy will still be available.

    • ecdhCurve?: string

      A string describing a named curve or a colon separated list of curve NIDs or names, for example P-521:P-384:P-256, to use for ECDH key agreement. Set to auto to select the curve automatically. Use crypto.getCurves() to obtain a list of available curve names. On recent releases, openssl ecparam -list_curves will also display the name and description of each available elliptic curve. Default: tls.DEFAULT_ECDH_CURVE.

    • enableTrace?: boolean

      When enabled, TLS packet trace information is written to stderr. This can be used to debug TLS connection problems.

    • family?: number
    • hints?: number
    • honorCipherOrder?: boolean

      Attempt to use the server's cipher suite preferences instead of the client's. When true, causes SSL_OP_CIPHER_SERVER_PREFERENCE to be set in secureOptions

    • host?: string
    • keepAlive?: boolean

      Keep sockets around in a pool to be used by other requests in the future. Default = false

    • keepAliveMsecs?: number

      When using HTTP KeepAlive, how often to send TCP KeepAlive packets over sockets being kept alive. Default = 1000. Only relevant if keepAlive is set to true.

    • key?: string | Buffer<ArrayBufferLike> | string | Buffer<ArrayBufferLike> | KeyObject[]

      Private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted keys will be decrypted with options.passphrase. Multiple keys using different algorithms can be provided either as an array of unencrypted key strings or buffers, or an array of objects in the form {pem: <string|buffer>[, passphrase: <string>]}. The object form can only occur in an array. object.passphrase is optional. Encrypted keys will be decrypted with object.passphrase if provided, or options.passphrase if it is not.

    • localAddress?: string
    • localPort?: number
    • maxFreeSockets?: number

      Maximum number of sockets to leave open in a free state. Only relevant if keepAlive is set to true. Default = 256.

    • maxSockets?: number

      Maximum number of sockets to allow per host. Default for Node 0.10 is 5, default for Node 0.12 is Infinity

    • maxTotalSockets?: number

      Maximum number of sockets allowed for all hosts in total. Each request will use a new socket until the maximum is reached. Default: Infinity.

    • maxVersion?: SecureVersion

      Optionally set the maximum TLS version to allow. One of 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', or 'TLSv1'. Cannot be specified along with the secureProtocol option, use one or the other. Default: 'TLSv1.3', unless changed using CLI options. Using --tls-max-v1.2 sets the default to 'TLSv1.2'. Using --tls-max-v1.3 sets the default to 'TLSv1.3'. If multiple of the options are provided, the highest maximum is used.

    • minDHSize?: number
    • minVersion?: SecureVersion

      Optionally set the minimum TLS version to allow. One of 'TLSv1.3', 'TLSv1.2', 'TLSv1.1', or 'TLSv1'. Cannot be specified along with the secureProtocol option, use one or the other. It is not recommended to use less than TLSv1.2, but it may be required for interoperability. Default: 'TLSv1.2', unless changed using CLI options. Using --tls-v1.0 sets the default to 'TLSv1'. Using --tls-v1.1 sets the default to 'TLSv1.1'. Using --tls-min-v1.3 sets the default to 'TLSv1.3'. If multiple of the options are provided, the lowest minimum is used.

    • noDelay?: boolean
    • passphrase?: string

      Shared passphrase used for a single private key and/or a PFX.

    • path?: string
    • pfx?: string | Buffer<ArrayBufferLike> | string | Buffer<ArrayBufferLike> | PxfObject[]

      PFX or PKCS12 encoded private key and certificate chain. pfx is an alternative to providing key and cert individually. PFX is usually encrypted, if it is, passphrase will be used to decrypt it. Multiple PFX can be provided either as an array of unencrypted PFX buffers, or an array of objects in the form {buf: <string|buffer>[, passphrase: <string>]}. The object form can only occur in an array. object.passphrase is optional. Encrypted PFX will be decrypted with object.passphrase if provided, or options.passphrase if it is not.

    • port?: number
    • rejectUnauthorized?: boolean

      If true the server will reject any connection which is not authorized with the list of supplied CAs. This option only has an effect if requestCert is true.

    • requestCert?: boolean

      If true the server will request a certificate from clients that connect and attempt to verify that certificate. Defaults to false.

    • scheduling?: 'fifo' | 'lifo'

      Scheduling strategy to apply when picking the next free socket to use.

    • secureContext?: SecureContext

      An optional TLS context object from tls.createSecureContext()

    • secureOptions?: number

      Optionally affect the OpenSSL protocol behavior, which is not usually necessary. This should be used carefully if at all! Value is a numeric bitmask of the SSL_OP_* options from OpenSSL Options

    • secureProtocol?: string

      Legacy mechanism to select the TLS protocol version to use, it does not support independent control of the minimum and maximum version, and does not support limiting the protocol to TLSv1.3. Use minVersion and maxVersion instead. The possible values are listed as SSL_METHODS, use the function names as strings. For example, use 'TLSv1_1_method' to force TLS version 1.1, or 'TLS_method' to allow any TLS protocol version up to TLSv1.3. It is not recommended to use TLS versions less than 1.2, but it may be required for interoperability. Default: none, see minVersion.

    • servername?: string
    • session?: Buffer<ArrayBufferLike>
    • sessionIdContext?: string

      Opaque identifier used by servers to ensure session state is not shared between applications. Unused by clients.

    • sessionTimeout?: number

      The number of seconds after which a TLS session created by the server will no longer be resumable. See Session Resumption for more information. Default: 300.

    • sigalgs?: string

      Colon-separated list of supported signature algorithms. The list can contain digest algorithms (SHA256, MD5 etc.), public key algorithms (RSA-PSS, ECDSA etc.), combination of both (e.g 'RSA+SHA384') or TLS v1.3 scheme names (e.g. rsa_pss_pss_sha512).

    • SNICallback?: (servername: string, cb: (err: null | Error, ctx?: SecureContext) => void) => void

      SNICallback(servername, cb) <Function> A function that will be called if the client supports SNI TLS extension. Two arguments will be passed when called: servername and cb. SNICallback should invoke cb(null, ctx), where ctx is a SecureContext instance. (tls.createSecureContext(...) can be used to get a proper SecureContext.) If SNICallback wasn't provided the default callback with high-level API will be used (see below).

    • ticketKeys?: Buffer<ArrayBufferLike>

      48-bytes of cryptographically strong pseudo-random data. See Session Resumption for more information.

    • timeout?: number

      Socket timeout in milliseconds. This will set the timeout after the socket is connected.

    • hint: null | string

      When negotiating TLS-PSK (pre-shared keys), this function is called with optional identity hint provided by the server or null in case of TLS 1.3 where hint was removed. It will be necessary to provide a custom tls.checkServerIdentity() for the connection as the default one will try to check hostname/IP of the server against the certificate but that's not applicable for PSK because there won't be a certificate present. More information can be found in the RFC 4279.

      @param hint

      message sent from the server to help client decide which identity to use during negotiation. Always null if TLS 1.3 is used.

      @returns

      Return null to stop the negotiation process. psk must be compatible with the selected cipher's digest. identity must use UTF-8 encoding.

  • type RequestOptions = http.RequestOptions & tls.SecureContextOptions & { checkServerIdentity: (hostname: string, cert: tls.DetailedPeerCertificate) => Error | undefined; rejectUnauthorized: boolean; servername: string }
  • type ServerOptions<Request extends typeof http.IncomingMessage = typeof http.IncomingMessage, Response extends typeof http.ServerResponse = typeof http.ServerResponse> = tls.SecureContextOptions & tls.TlsOptions & http.ServerOptions<Request, Response>