2 * DEBUG: section 04 Error Generation
3 * AUTHOR: Duane Wessels
5 * SQUID Web Proxy Cache http://www.squid-cache.org/
6 * ----------------------------------------------------------
8 * Squid is the result of efforts by numerous individuals from
9 * the Internet community; see the CONTRIBUTORS file for full
10 * details. Many organizations have provided support for Squid's
11 * development; see the SPONSORS file for full details. Squid is
12 * Copyrighted (C) 2001 by the Regents of the University of
13 * California; see the COPYRIGHT file for full details. Squid
14 * incorporates software developed and/or copyrighted by other
15 * sources; see the CREDITS file for full details.
17 * This program is free software; you can redistribute it and/or modify
18 * it under the terms of the GNU General Public License as published by
19 * the Free Software Foundation; either version 2 of the License, or
20 * (at your option) any later version.
22 * This program is distributed in the hope that it will be useful,
23 * but WITHOUT ANY WARRANTY; without even the implied warranty of
24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 * GNU General Public License for more details.
27 * You should have received a copy of the GNU General Public License
28 * along with this program; if not, write to the Free Software
29 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
31 * Copyright (c) 2003, Robert Collins <robertc@squid-cache.org>
34 #ifndef SQUID_ERRORPAGE_H
35 #define SQUID_ERRORPAGE_H
38 #include "comm/forward.h"
39 #include "err_detail_type.h"
41 #include "http/StatusCode.h"
42 #include "ip/Address.h"
43 #include "SquidString.h"
44 /* auth/UserRequest.h is empty unless USE_AUTH is defined */
45 #include "auth/UserRequest.h"
47 #include "ssl/ErrorDetail.h"
51 \defgroup ErrorPageAPI Error Pages API
53 \section ErrorPageStringCodes Error Page % codes for text insertion.
57 B - URL with FTP %2f hack x
58 c - Squid error code x
59 d - seconds elapsed since request received x
63 f - FTP request line x
65 g - FTP server message x
67 H - server host name x
68 i - client IP address x
69 I - server IP address x
70 l - HREF link for CSS stylesheet inclusion x
71 L - HREF link for more info/contact x
73 m - Error message returned by auth helper x
74 o - Message returned external acl helper x
77 R - Full HTTP Request x
78 S - squid signature from ERR_SIGNATURE x
79 s - caching proxy software with version x
82 U - URL without password x
83 u - URL with password x
84 w - cachemgr email address x
85 W - error data (to be included in the mailto links)
87 z - dns server error message x
88 Z - Preformatted error message x
96 /// \ingroup ErrorPageAPI
100 ErrorState(err_type type
, Http::StatusCode
, HttpRequest
* request
);
101 ErrorState(); // not implemented.
104 /// Creates a general request forwarding error with the right http_status.
105 static ErrorState
*NewForwarding(err_type type
, HttpRequest
*request
);
108 * Allocates and initializes an error response
110 HttpReply
*BuildHttpReply(void);
112 /// set error type-specific detail code
113 void detailError(int dCode
) {detailCode
= dCode
;}
117 * Locates error page template to be used for this error
118 * and constructs the HTML page content from it.
120 MemBuf
*BuildContent(void);
123 * Convert the given template string into textual output
125 * \param text The string to be converted
126 * \param allowRecursion Whether to convert codes which output may contain codes
128 MemBuf
*ConvertText(const char *text
, bool allowRecursion
);
131 * Generates the Location: header value for a deny_info error page
132 * to be used for this error.
134 void DenyInfoLocation(const char *name
, HttpRequest
*request
, MemBuf
&result
);
137 * Map the Error page and deny_info template % codes into textual output.
139 * Several of the codes produce blocks of non-URL compatible results.
140 * When processing the deny_info location URL they will be skipped.
142 * \param token The token following % which need to be converted
143 * \param building_deny_info_url Perform special deny_info actions, such as URL-encoding and token skipping.
144 * \ allowRecursion True if the codes which do recursions should converted
146 const char *Convert(char token
, bool building_deny_info_url
, bool allowRecursion
);
149 * CacheManager / Debug dump of the ErrorState object.
150 * Writes output into the given MemBuf.
151 \retval 0 successful completion.
153 int Dump(MemBuf
* mb
);
159 Http::StatusCode httpStatus
;
161 Auth::UserRequest::Pointer auth_user_request
;
163 HttpRequest
*request
;
167 String dnsError
; ///< DNS lookup error message
170 Ip::Address src_addr
;
176 wordlist
*server_msg
;
184 char *err_msg
; /* Preformatted error message from the cache */
187 Ssl::ErrorDetail
*detail
;
189 /// type-specific detail about the transaction error;
190 /// overwrites xerrno; overwritten by detail, if any.
193 CBDATA_CLASS2(ErrorState
);
197 \ingroup ErrorPageAPI
199 * This function finds the error messages formats, and stores
200 * them in error_text[]
203 * error_text[] - is modified
205 void errorInitialize(void);
207 /// \ingroup ErrorPageAPI
208 void errorClean(void);
211 * \ingroup ErrorPageAPI
213 * This function generates a error page from the info contained
214 * by err and then sends it to the client.
215 * The callback function errorSendComplete() is called after
216 * the page has been written to the client (clientConn).
217 * errorSendComplete() deallocates err. We need to add
218 * err to the cbdata because comm_write() requires it
219 * for all callback data pointers.
221 \note normally errorSend() should only be called from
222 * routines in ssl.c and pass.c, where we don't have any
223 * StoreEntry's. In client_side.c we must allocate a StoreEntry
224 * for errors and use errorAppendEntry() to account for
225 * persistent/pipeline connections.
227 \param clientConn socket where page object is to be written
228 \param err This object is destroyed after use in this function.
230 void errorSend(const Comm::ConnectionPointer
&conn
, ErrorState
*err
);
233 \ingroup ErrorPageAPI
235 * This function generates a error page from the info contained
236 * by err and then stores the text in the specified store
238 * This function should only be called by "server
239 * side routines" which need to communicate errors to the
240 * client side. It should also be called from client_side.c
241 * because we now support persistent connections, and
242 * cannot assume that we can immediately write to the socket
246 \param err This object is destroyed after use in this function.
248 void errorAppendEntry(StoreEntry
*entry
, ErrorState
*err
);
250 /// \ingroup ErrorPageAPI
251 err_type
errorReservePageId(const char *page_name
);
253 const char *errorPageName(int pageId
); ///< error ID to string
256 \ingroup ErrorPageAPI
258 * loads text templates used for error pages and details;
259 * supports translation of templates
264 TemplateFile(const char *name
, const err_type code
);
265 virtual ~TemplateFile() {}
267 /// return true if the data loaded from disk without any problem
268 bool loaded() const {return wasLoaded
;}
271 * Load the page_name template from a file which probably exist at:
272 * (a) admin specified custom directory (error_directory)
273 * (b) default language translation directory (error_default_language)
274 * (c) English sub-directory where errors should ALWAYS exist
279 * Load an error template for a given HTTP request. This function examines the
280 * Accept-Language header and select the first available template. If the default
281 * template selected (eg because of a "Accept-Language: *"), or not available
282 * template found this function return false.
284 bool loadFor(const HttpRequest
*request
);
287 * Load the file given by "path". It uses the "parse()" method.
288 * On success return true and sets the "defined" member
290 bool loadFromFile(const char *path
);
292 /// The language used for the template
293 const char *language() {return errLanguage
.termedBuf();}
295 bool silent
; ///< Whether to print error messages on cache.log file or not. It is user defined.
298 /// Used to parse (if parsing required) the template data .
299 virtual bool parse(const char *buf
, int len
, bool eof
) = 0;
302 * Try to load the "page_name" template for a given language "lang"
303 * from squid errors directory
304 \return true on success false otherwise
306 bool tryLoadTemplate(const char *lang
);
308 bool wasLoaded
; ///< True if the template data read from disk without any problem
309 String errLanguage
; ///< The error language of the template.
310 String templateName
; ///< The name of the template
311 err_type templateCode
; ///< The internal code for this template.
315 * Parses the Accept-Language header value and return one language item on
317 * Will ignore any whitespace, q-values, and detectably invalid language
318 * codes in the header.
320 * \param hdr is the Accept-Language header value
321 * \param lang a buffer to store parsed language code in
322 * \param langlen the length of the lang buffer
323 * \param pos is used to store the offset state of parsing. Must be "0" on first call.
324 * Will be altered to point at the start of next field-value.
325 * \return true if something looking like a language token has been placed in lang, false otherwise
327 bool strHdrAcptLangGetItem(const String
&hdr
, char *lang
, int langLen
, size_t &pos
);
329 #endif /* SQUID_ERRORPAGE_H */