2 * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
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.
9 /* DEBUG: section 04 Error Generation */
11 #ifndef SQUID_ERRORPAGE_H
12 #define SQUID_ERRORPAGE_H
15 #include "comm/forward.h"
16 #include "err_detail_type.h"
18 #include "http/StatusCode.h"
19 #include "ip/Address.h"
20 #include "SquidString.h"
21 /* auth/UserRequest.h is empty unless USE_AUTH is defined */
22 #include "auth/UserRequest.h"
24 #include "ssl/ErrorDetail.h"
27 /// error page callback
28 typedef void ERCB(int fd
, void *, size_t);
31 \defgroup ErrorPageAPI Error Pages API
33 \section ErrorPageStringCodes Error Page % codes for text insertion.
37 B - URL with FTP %2f hack x
38 c - Squid error code x
39 d - seconds elapsed since request received x
43 f - FTP request line x
45 g - FTP server message x
47 H - server host name x
48 i - client IP address x
49 I - server IP address x
50 l - HREF link for CSS stylesheet inclusion x
51 L - HREF link for more info/contact x
53 m - Error message returned by auth helper x
54 o - Message returned external acl helper x
57 R - Full HTTP Request x
58 S - squid signature from ERR_SIGNATURE x
59 s - caching proxy software with version x
62 U - URL without password x
63 u - URL with password x
64 w - cachemgr email address x
65 W - error data (to be included in the mailto links)
67 z - dns server error message x
68 Z - Preformatted error message x
76 /// \ingroup ErrorPageAPI
79 CBDATA_CLASS(ErrorState
);
82 ErrorState(err_type type
, Http::StatusCode
, HttpRequest
* request
);
83 ErrorState(); // not implemented.
86 /// Creates a general request forwarding error with the right http_status.
87 static ErrorState
*NewForwarding(err_type type
, HttpRequest
*request
);
90 * Allocates and initializes an error response
92 HttpReply
*BuildHttpReply(void);
94 /// set error type-specific detail code
95 void detailError(int dCode
) {detailCode
= dCode
;}
99 * Locates error page template to be used for this error
100 * and constructs the HTML page content from it.
102 MemBuf
*BuildContent(void);
105 * Convert the given template string into textual output
107 * \param text The string to be converted
108 * \param allowRecursion Whether to convert codes which output may contain codes
110 MemBuf
*ConvertText(const char *text
, bool allowRecursion
);
113 * Generates the Location: header value for a deny_info error page
114 * to be used for this error.
116 void DenyInfoLocation(const char *name
, HttpRequest
*request
, MemBuf
&result
);
119 * Map the Error page and deny_info template % codes into textual output.
121 * Several of the codes produce blocks of non-URL compatible results.
122 * When processing the deny_info location URL they will be skipped.
124 * \param token The token following % which need to be converted
125 * \param building_deny_info_url Perform special deny_info actions, such as URL-encoding and token skipping.
126 * \ allowRecursion True if the codes which do recursions should converted
128 const char *Convert(char token
, bool building_deny_info_url
, bool allowRecursion
);
131 * CacheManager / Debug dump of the ErrorState object.
132 * Writes output into the given MemBuf.
133 \retval 0 successful completion.
135 int Dump(MemBuf
* mb
);
141 Http::StatusCode httpStatus
;
143 Auth::UserRequest::Pointer auth_user_request
;
145 HttpRequest
*request
;
149 String dnsError
; ///< DNS lookup error message
152 Ip::Address src_addr
;
158 wordlist
*server_msg
;
166 char *err_msg
; /* Preformatted error message from the cache */
169 Ssl::ErrorDetail
*detail
;
171 /// type-specific detail about the transaction error;
172 /// overwrites xerrno; overwritten by detail, if any.
177 \ingroup ErrorPageAPI
179 * This function finds the error messages formats, and stores
180 * them in error_text[]
183 * error_text[] - is modified
185 void errorInitialize(void);
187 /// \ingroup ErrorPageAPI
188 void errorClean(void);
191 * \ingroup ErrorPageAPI
193 * This function generates a error page from the info contained
194 * by err and then sends it to the client.
195 * The callback function errorSendComplete() is called after
196 * the page has been written to the client (clientConn).
197 * errorSendComplete() deallocates err. We need to add
198 * err to the cbdata because comm_write() requires it
199 * for all callback data pointers.
201 \note normally errorSend() should only be called from
202 * routines in ssl.c and pass.c, where we don't have any
203 * StoreEntry's. In client_side.c we must allocate a StoreEntry
204 * for errors and use errorAppendEntry() to account for
205 * persistent/pipeline connections.
207 \param clientConn socket where page object is to be written
208 \param err This object is destroyed after use in this function.
210 void errorSend(const Comm::ConnectionPointer
&conn
, ErrorState
*err
);
213 \ingroup ErrorPageAPI
215 * This function generates a error page from the info contained
216 * by err and then stores the text in the specified store
218 * This function should only be called by "server
219 * side routines" which need to communicate errors to the
220 * client side. It should also be called from client_side.c
221 * because we now support persistent connections, and
222 * cannot assume that we can immediately write to the socket
226 \param err This object is destroyed after use in this function.
228 void errorAppendEntry(StoreEntry
*entry
, ErrorState
*err
);
230 /// \ingroup ErrorPageAPI
231 err_type
errorReservePageId(const char *page_name
);
233 const char *errorPageName(int pageId
); ///< error ID to string
236 \ingroup ErrorPageAPI
238 * loads text templates used for error pages and details;
239 * supports translation of templates
244 TemplateFile(const char *name
, const err_type code
);
245 virtual ~TemplateFile() {}
247 /// return true if the data loaded from disk without any problem
248 bool loaded() const {return wasLoaded
;}
251 * Load the page_name template from a file which probably exist at:
252 * (a) admin specified custom directory (error_directory)
253 * (b) default language translation directory (error_default_language)
254 * (c) English sub-directory where errors should ALWAYS exist
259 * Load an error template for a given HTTP request. This function examines the
260 * Accept-Language header and select the first available template. If the default
261 * template selected (eg because of a "Accept-Language: *"), or not available
262 * template found this function return false.
264 bool loadFor(const HttpRequest
*request
);
267 * Load the file given by "path". It uses the "parse()" method.
268 * On success return true and sets the "defined" member
270 bool loadFromFile(const char *path
);
272 /// The language used for the template
273 const char *language() {return errLanguage
.termedBuf();}
275 bool silent
; ///< Whether to print error messages on cache.log file or not. It is user defined.
278 /// Used to parse (if parsing required) the template data .
279 virtual bool parse(const char *buf
, int len
, bool eof
) = 0;
282 * Try to load the "page_name" template for a given language "lang"
283 * from squid errors directory
284 \return true on success false otherwise
286 bool tryLoadTemplate(const char *lang
);
288 bool wasLoaded
; ///< True if the template data read from disk without any problem
289 String errLanguage
; ///< The error language of the template.
290 String templateName
; ///< The name of the template
291 err_type templateCode
; ///< The internal code for this template.
295 * Parses the Accept-Language header value and return one language item on
297 * Will ignore any whitespace, q-values, and detectably invalid language
298 * codes in the header.
300 * \param hdr is the Accept-Language header value
301 * \param lang a buffer to store parsed language code in
302 * \param langlen the length of the lang buffer
303 * \param pos is used to store the offset state of parsing. Must be "0" on first call.
304 * Will be altered to point at the start of next field-value.
305 * \return true if something looking like a language token has been placed in lang, false otherwise
307 bool strHdrAcptLangGetItem(const String
&hdr
, char *lang
, int langLen
, size_t &pos
);
309 #endif /* SQUID_ERRORPAGE_H */