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

/*
 * Copyright (C) 1996-2025 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.

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