A <Client> can be understood as a state machine. As requests are dispatched,\nprocessed, and drained, the client moves through a well-defined set of states\nuntil it is eventually destroyed. This document describes those states and the\ntransitions between them.
The <Client> class is not literally implemented as a state machine, so the\nactual execution may deviate slightly from what is described here. Treat this\nguide as a conceptual model for reasoning about a client's behavior rather than\nas a formal specification.
<Client> begins in the idle state with no socket connection and no\nqueued requests.\n<Client> to the pending state, where\nrequests can be queued before they are processed.client.close() or client.destroy() moves the <Client>\nto the destroyed state. Because there are no queued requests in this\nstate, close transitions straight to destroyed.<Client> into the processing.busy sub-state, which returns to\nprocessing.running once drainComplete fires.<Client> back to\nthe pending state. If no requests are queued before the socket times\nout, the <Client> transitions to idle.<Client> still has queued requests, the\n<Client> transitions to processing.closing, where it completes all\noutstanding requests before firing done.<Client> gracefully to destroyed.<Client> from processing to\ndestroyed, aborting any queued requests.<Client> is no longer functional.A state diagram representing a <Client> instance:
stateDiagram-v2\n [*] --> idle\n idle --> pending : connect\n idle --> destroyed : destroy/close\n\n pending --> idle : timeout\n pending --> destroyed : destroy\n\n state close_fork <<fork>>\n pending --> close_fork : close\n close_fork --> processing\n close_fork --> destroyed\n\n pending --> processing : process\n\n processing --> pending : keepalive\n processing --> destroyed : done\n processing --> destroyed : destroy\n\n destroyed --> [*]\n\n state processing {\n [*] --> running\n running --> closing : close\n running --> busy : needDrain\n busy --> running : drainComplete\n running --> [*] : keepalive\n closing --> [*] : done\n }\nidle is the initial state of a <Client> instance. Although an origin is\nrequired to construct a <Client>, the underlying socket connection is not\nestablished until a request is queued through client.dispatch(). Calling\nclient.dispatch() directly, or through one of its higher-level wrappers\n(client.connect(), client.pipeline(), client.request(),\nclient.stream(), or client.upgrade()), moves the <Client> from idle to pending, and then usually directly on to processing.
Calling client.close() or client.destroy() in this state moves the\n<Client> straight to destroyed, since there are no queued requests.
pending signifies a connected but non-processing <Client>. On entering this\nstate, the <Client> establishes a socket connection and emits the 'connect' event, signalling that a connection to the origin supplied at\nconstruction time has been established. The internal queue starts empty, and\nrequests can begin queueing.
Calling client.close() with queued requests moves the <Client> to the processing state; without queued requests it moves to destroyed.
Calling client.destroy() moves the <Client> directly to destroyed,\nregardless of any queued requests.
processing is itself a sub-state machine that initializes to the\nprocessing.running sub-state. client.dispatch(), client.close(),\nand client.destroy() can all be called while the <Client> is in this\nstate. client.dispatch() queues additional requests while existing ones\ncontinue to be processed, client.close() moves the <Client> to the processing.closing sub-state, and client.destroy() moves it to\ndestroyed.
In processing.running, queued requests are processed in FIFO order. If a\nrequest body requires draining, needDrain moves the <Client> to the processing.busy sub-state. The close transition moves the <Client> to the processing.closing sub-state. When all queued requests have completed and\nneither client.close() nor client.destroy() has been called, the\nkeepalive transition moves the <Client> back to the pending state. There\nthe <Client> waits for the socket connection to time out; once it does, the\n<Client> returns to the idle state.
This sub-state is entered only when a request body is a <stream.Readable> that\nrequires draining. The <Client> cannot process additional requests while in\nthis state and waits until the current request body has been fully drained\nbefore returning to processing.running.
This sub-state is entered only when a <Client> has queued requests and client.close() is called. The <Client> continues to process requests as\nusual, except that no additional requests may be queued. Once all queued\nrequests have been processed, done fires and the <Client> moves gracefully to destroyed without an error.
destroyed is the final state of a <Client> instance. Once in this state, the\n<Client> is no longer functional, and calling any further <Client> method\nrejects or fails with a <ClientDestroyedError>.