[thirdparty/squid.git] / doc / Programming-Guide / 05_TypicalRequestFlow.dox

/*
 * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */

/**
\page 05_TypicalRequestFlow Flow of a Typical Request

\par
\li	A client connection is accepted by the client-side socket
	support and parsed, or is directly created via
	clientBeginRequest().

\li	The access controls are checked.  The client-side-request builds
	an ACL state data structure and registers a callback function
	for notification when access control checking is completed.

\li	After the access controls have been verified, the request
	may be redirected.

\li	The client-side-request is forwarded up the client stream
	to GetMoreData() which looks for the requested object in the
	cache, and or Vary: versions of the same. If is a cache hit,
	then the client-side registers its interest in the
	StoreEntry. Otherwise, Squid needs to forward the request,
	perhaps with an If-Modified-Since header.

\li	The request-forwarding process begins with protoDispatch().
	This function begins the peer selection procedure, which
	may involve sending ICP queries and receiving ICP replies.
	The peer selection procedure also involves checking
	configuration options such as \em never_direct and
	\em always_direct.

\li	When the ICP replies (if any) have been processed, we end
	up at protoStart().  This function calls an appropriate
	protocol-specific function for forwarding the request.
	Here we will assume it is an HTTP request.

\li	The HTTP module first opens a connection to the origin
	server or cache peer.  If there is no idle persistent socket
	available, a new connection request is given to the Network
	Communication module with a callback function.  The
	comm.c routines may try establishing a connection
	multiple times before giving up.

\li	When a TCP connection has been established, HTTP builds a
	request buffer and submits it for writing on the socket.
	It then registers a read handler to receive and process
	the HTTP reply.

\li	As the reply is initially received, the HTTP reply headers
	are parsed and placed into a reply data structure.  As
	reply data is read, it is appended to the StoreEntry.
	Every time data is appended to the StoreEntry, the
	client-side is notified of the new data via a callback
	function. The rate at which reading occurs is regulated by
	the delay pools routines, via the deferred read mechanism.

\li	As the client-side is notified of new data, it copies the
	data from the StoreEntry and submits it for writing on the
	client socket.

\li	As data is appended to the StoreEntry, and the client(s)
	read it, the data may be submitted for writing to disk.

\li	When the HTTP module finishes reading the reply from the
	upstream server, it marks the StoreEntry as "complete".
	The server socket is either closed or given to the persistent
	connection pool for future use.

\li	When the client-side has written all of the object data,
	it unregisters itself from the StoreEntry.  At the
	same time it either waits for another request from the
	client, or closes the client connection.

*/
Commit	Line	Data
f2a134b9	1	/*
b8ae064d	2	* Copyright (C) 1996-2023 The Squid Software Foundation and contributors
f2a134b9 AJ	3	*
	4	* Squid software is distributed under GPLv2+ license and includes
	5	* contributions from numerous individuals and organizations.
	6	* Please see the COPYING and CONTRIBUTORS files for details.
	7	*/
	8
8b651fb3	9	/**
	10	\page 05_TypicalRequestFlow Flow of a Typical Request
	11
	12	\par
	13	\li A client connection is accepted by the client-side socket
	14	support and parsed, or is directly created via
	15	clientBeginRequest().
	16
	17	\li The access controls are checked. The client-side-request builds
	18	an ACL state data structure and registers a callback function
	19	for notification when access control checking is completed.
	20
	21	\li After the access controls have been verified, the request
9603207d	22	may be redirected.
8b651fb3	23
8b651fb3	24	\li The client-side-request is forwarded up the client stream
9603207d	25	to GetMoreData() which looks for the requested object in the
	26	cache, and or Vary: versions of the same. If is a cache hit,
	27	then the client-side registers its interest in the
8b651fb3	28	StoreEntry. Otherwise, Squid needs to forward the request,
	29	perhaps with an If-Modified-Since header.
	30
	31	\li The request-forwarding process begins with protoDispatch().
	32	This function begins the peer selection procedure, which
	33	may involve sending ICP queries and receiving ICP replies.
	34	The peer selection procedure also involves checking
	35	configuration options such as \em never_direct and
	36	\em always_direct.
	37
	38	\li When the ICP replies (if any) have been processed, we end
	39	up at protoStart(). This function calls an appropriate
	40	protocol-specific function for forwarding the request.
	41	Here we will assume it is an HTTP request.
	42
	43	\li The HTTP module first opens a connection to the origin
	44	server or cache peer. If there is no idle persistent socket
	45	available, a new connection request is given to the Network
	46	Communication module with a callback function. The
	47	comm.c routines may try establishing a connection
	48	multiple times before giving up.
	49
	50	\li When a TCP connection has been established, HTTP builds a
	51	request buffer and submits it for writing on the socket.
	52	It then registers a read handler to receive and process
	53	the HTTP reply.
	54
	55	\li As the reply is initially received, the HTTP reply headers
	56	are parsed and placed into a reply data structure. As
	57	reply data is read, it is appended to the StoreEntry.
	58	Every time data is appended to the StoreEntry, the
	59	client-side is notified of the new data via a callback
	60	function. The rate at which reading occurs is regulated by
	61	the delay pools routines, via the deferred read mechanism.
	62
	63	\li As the client-side is notified of new data, it copies the
	64	data from the StoreEntry and submits it for writing on the
	65	client socket.
	66
	67	\li As data is appended to the StoreEntry, and the client(s)
	68	read it, the data may be submitted for writing to disk.
	69
	70	\li When the HTTP module finishes reading the reply from the
	71	upstream server, it marks the StoreEntry as "complete".
	72	The server socket is either closed or given to the persistent
	73	connection pool for future use.
	74
	75	\li When the client-side has written all of the object data,
	76	it unregisters itself from the StoreEntry. At the
	77	same time it either waits for another request from the
	78	client, or closes the client connection.
	79
	80	*/