WebUtil::FileHandler Class Reference

this class serves files from the file system based on a root location More...

#include <WebUtil.qm.dox.h>

Inheritance diagram for WebUtil::FileHandler:

Public Member Methods
	constructor (string new_file_root, string url_root='/', *hash< auto > opt)
	create the object optionally with the given HttpServer::AbstractAuthenticator More...
hash< HttpResponseInfo >	handleRequest (HttpServer::HttpListenerInterface listener, Qore::Socket s, hash< auto > cx, hash< auto > hdr, *data body)
	this method calls handleRequestImpl() to service the request, if handleRequestImpl() returns NOTHING, then it tries to automatically serve a matching template or files from the filesystem or serve the default resource if no resource can be matched More...
	logDebug (string fmt)
	default implementation is empty; this method is called with debug log messages; reimplement in subclasses to provide for logging
	logError (string fmt)
	default implementation is empty; this method is called with error log messages; reimplement in subclasses to provide for logging
	logInfo (string fmt)
	default implementation is empty; this method is called with informational log messages; reimplement in subclasses to provide for logging
*hash< HttpResponseInfo >	renderDirectory (hash< auto > cx, string path)
	this method is called when a directory should be rendered More...

Public Attributes
softint	chunk_size = Defaults.ChunkSize
	HTTP chunk size in bytes.
softint	chunked_threshold = Defaults.ChunkedThreshold
	minimum size in bytes for plain files to be sent with a chnked transfer
*string	default_target
	the default target if a URL cannot be satisfied
const	DefaultFileReadTimeout = 20s
	default read timeout for serving files
const	Defaults
	default configuration values
const	Dirlisting = ...
	dirlisting template
const	DirSep = Qore::DirSep
	directory separator character More...
softint	error_level = 0
	set for error info level More...
string	file_root
	root directory for serving files
softlist	indexes = (Defaults.IndexTemplate, Defaults.IndexFile)
	indexes for directories; handled in order of appearance
hash	template_extensions = Defaults.TemplateExtensions
	file extensions handled as templates
const	Unix = (PlatformOS != "Windows")
	flag for UNIX operating systems

Private Member Methods
hash< HttpResponseInfo >	fileError (hash< auto > cx, hash< auto > sh)
	this method returns a 400 "Bad Request" error code when a file should be served that's not a regular file More...
hash< auto >	getResponseHeadersForFile (string path, hash< auto > cx, hash< auto > request_hdr)
	this method returns a hash giving response headers with a default content type for the file to be served based on its extenion and can be subclassed to add headers to the response More...
AbstractStreamRequest	getStreamRequestImpl (HttpServer::HttpListenerInterface listener, Qore::Socket s, hash< auto > cx, hash< auto > hdr, *data body, InputStream stream, *hash< auto > respHdr)
	must return a AbstractStreamRequest object to stream the requested file with chunked transfer encoding
*hash< HttpResponseInfo >	handleRequestImpl (reference< hash< auto > > cx, hash< auto > hdr, *data body)
	this method is called by this class's handleRequest() before trying to service the request automatically based on file resources More...
hash< HttpResponseInfo >	sendFile (InputStream stream, *hash< auto > respHdr)
	returns a handler hash response with the data to be sent in a monolithic message
hash< HttpResponseInfo >	sendFileChunked (HttpServer::HttpListenerInterface listener, Qore::Socket s, hash< auto > cx, hash< auto > hdr, *data body, InputStream stream, *hash< auto > respHdr)
	returns a handler hash response with the file's data to be sent in a HTTP message with chunked transfer encoding
hash< HttpResponseInfo >	serverError (hash< auto > cx, hash< auto > ex)
	this method returns a 500 "Internal Server Error" error code when an exception occurs More...
StaticTemplateManager	stm ()
	static templates
*hash< HttpResponseInfo >	tryServeRequest (HttpServer::HttpListenerInterface listener, Qore::Socket s, hash< auto > cx, hash< auto > hdr, *data body)
	tries to serve the request from the filesystem
hash< HttpResponseInfo >	unhandledRequest (hash< auto > cx, hash< auto > hdr, *data body)
	this method returns a 404 "Not Found" error code to GET requests and a 501 "Not Implemented" error code to all other requests More...
Private Member Methods inherited from WebUtil::TemplateFileManager
RWLock	rwl ()
	read-write lock for managing template access
	constructor (int parse_opts=StaticTextTemplateBase::DefaultProgramOptions, *code pgm_setup)
	creates the object with optional Program options More...
	purge (string tname)
	this method can be called when a resource is requested that no longer exists in case a template is stored for a file that was deleted
hash< HttpResponseInfo >	render (string tname, string path, date mtime, hash< auto > ctx, int code=200, *hash< auto > hdr)
	explicitly renders the given template with the given path and context argument More...

Additional Inherited Members
Private Attributes inherited from WebUtil::TemplateFileManager
int	po
	parse options used on the program
*code	psetup
	code to perform Program initialization when creating a new Program object (inport API, etc)
hash< string, AbstractTemplate >	th
	hash for template storage

Detailed Description

this class serves files from the file system based on a root location

Member Function Documentation

constructor()

WebUtil::FileHandler::constructor	(	string	new_file_root,
		string	url_root = '/',
		*hash< auto >	opt
	)

create the object optionally with the given HttpServer::AbstractAuthenticator

Parameters

new_file_root	the filesystem root directory for serving files
url_root	the root part of the URL path without the leading "/"
opt	an optional with one or more of the following option keys: default_target: the default relative path to use if a request cannot be satisfied po: the Program parse options for the template file programs psetup: an optional closure or call reference taking a single Program argument to be called when initializing template programs to set up a custom template API, etc auth: the authentication object to use to authenticate connections (see HttpServer::AbstractAuthenticator); if no HttpServer::AbstractAuthenticator object is passed, then by default no authentication will be required error_level: the level of error reporting (0, 1, or 2) chunked_threshold: the minimum size for sending files with a chunked transfer encoding chunk_size: the HTTP chunk size for sending files with chunked transfer encoding

fileError()

hash< HttpResponseInfo > WebUtil::FileHandler::fileError ( hash< auto >  cx, hash< auto >  sh  )

private

this method returns a 400 "Bad Request" error code when a file should be served that's not a regular file

this method is called when a file cannot be served because it's not a regular file; reimplement this method in subclasses to customize error handling

getResponseHeadersForFile()

hash< auto > WebUtil::FileHandler::getResponseHeadersForFile ( string  path, hash< auto >  cx, hash< auto >  request_hdr  )

private

this method returns a hash giving response headers with a default content type for the file to be served based on its extenion and can be subclassed to add headers to the response

This method is called before a file is sent to get additional headers to include in response; reimplement this method in subclasses to add response headers. This method must return the content type for the file being served.

Parameters

path	filepath
cx	original request cx hash
request_hdr	original request headers

Returns

a hash giving response headers with a default content type for the file to be served based on its extenion and can be subclassed to add headers to the response

handleRequest()

hash< HttpResponseInfo > WebUtil::FileHandler::handleRequest	(	HttpServer::HttpListenerInterface	listener,
		Qore::Socket	s,
		hash< auto >	cx,
		hash< auto >	hdr,
		*data	body
	)

this method calls handleRequestImpl() to service the request, if handleRequestImpl() returns NOTHING, then it tries to automatically serve a matching template or files from the filesystem or serve the default resource if no resource can be matched

Parameters

listener	the listener handling the request
s	the socket object for the connection
cx	call context hash; this hash will have the following keys: socket: the bind address used to bind the listener ("socket-info" provides more detailed information) socket-info: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo()) peer-info: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo()) url: a hash of broken-down URL information (as returned from Qore::parse_url()) id: the unique HTTP connection ID ssl: True if the request was encrypted with HTTPS, False if not listener-id: the HTTP server listener ID (see HttpServer::HttpServer::getListenerInfo()) user: the current RBAC username (if any)
hdr	incoming header hash; all keys will be converted to lower-case, additionally the following keys will be present: method: the HTTP method received (ie "GET", "POST", etc) path: the HTTP path given in the request, after processing by Qore::decode_url() http_version: the HTTP version number in the request (either "1.0" or "1.1")
body	message body, if any

Returns

a hash with the following keys:

• "code": the HTTP return code (see HttpServer::HttpCodes)
• "body": the message body to return in the response
• "close": (optional) set this key to True if the connection should be unconditionally closed when the handler returns
• "hdr": (optional) set this key to a hash of extra header information to be returned with the response

The following keys are added to the cx argument when calling handleRequestImpl():

• resource_path: the relative path without any query arguments and with the URL root stripped off (if the request was matched by the URL root, otherwise this will be the request path with any URI query arguments removed)
• url_root: the root URL
• file_root: the root directory for serving files
• isregex: if the url_root string is a regular expression or not (this is always False when this class is used)
• hdr: this is added to the cx argument directly from the hdr argument, however it also includes the "params" key which holds the URI query parameters as returned in the params key from HttpServer::parse_uri_query()

If handleRequestImpl() returns NOTHING and the requested path cannot be matched and served, then unhandledRequest() is called to handle the error

handleRequestImpl()

*hash< HttpResponseInfo > WebUtil::FileHandler::handleRequestImpl ( reference< hash< auto > >  cx, hash< auto >  hdr, *data  body  )

private

this method is called by this class's handleRequest() before trying to service the request automatically based on file resources

Parameters

cx	call context hash; this hash will have the following keys: socket: the bind address used to bind the listener ("socket-info" provides more detailed information) socket-info: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo()) peer-info: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo()) url: a hash of broken-down URL information (as returned from Qore::parse_url()) id: the unique HTTP connection ID ssl: True if the request was encrypted with HTTPS, False if not listener-id: the HTTP server listener ID (see HttpServer::HttpServer::getListenerInfo()) user: the current RBAC username (if any) resource_path: the relative path without any query arguments and with the URL root stripped off (if the request was matched by the URL root, otherwise this will be the request path with any URI query arguments removed) url_root: the root URL file_root: the root directory for serving files isregex: if the url_root string is a regular expression or not (this is always False when this class is used) hdr: this is a copy of the hdr argument, however it also includes the "params" key which holds the URI query parameters as returned in the params key from HttpServer::parse_uri_query()
hdr	incoming header hash; all keys will be converted to lower-case, additionally the following keys will be present: method: the HTTP method received (ie "GET", "POST", etc) path: the HTTP path given in the request, after processing by Qore::decode_url() http_version: the HTTP version number in the request (either "1.0" or "1.1") params: holds the URI query parameters as returned in the params key from HttpServer::parse_uri_query()
body	message body, if any

Returns

a hash with the following keys:

• "code": the HTTP return code (see HttpServer::HttpCodes)
• "body": the message body to return in the response
• "close": (optional) set this key to True if the connection should be unconditionally closed when the handler returns
• "hdr": (optional) set this key to a hash of extra header information to be returned with the response

Note

• this method has the following additional keys in the cx hash: resource_path, url_root, and isregex
• the default implementation simply returns NOTHING all requests; reimplement this method in a subclass to provide the required functionality

renderDirectory()

*hash< HttpResponseInfo > WebUtil::FileHandler::renderDirectory	(	hash< auto >	cx,
		string	path
	)

this method is called when a directory should be rendered

if this method returns NOTHING then any default_target will be used, so to turn off directory rendering, subclass this class and have the reimplemented method return NOTHING

serverError()

hash< HttpResponseInfo > WebUtil::FileHandler::serverError ( hash< auto >  cx, hash< auto >  ex  )

private

this method returns a 500 "Internal Server Error" error code when an exception occurs

this method is called when an exception occurs; reimplement this method in subclasses to customize error handling

unhandledRequest()

hash< HttpResponseInfo > WebUtil::FileHandler::unhandledRequest ( hash< auto >  cx, hash< auto >  hdr, *data  body  )

private

this method returns a 404 "Not Found" error code to GET requests and a 501 "Not Implemented" error code to all other requests

this method is called when a request cannot be handled; reimplement this method in subclasses to customize unhandled request error handling

Member Data Documentation

DirSep

const WebUtil::FileHandler::DirSep = Qore::DirSep

directory separator character

actually defined in Qore, exported here for backwards-compatibility

See also

Qore::DirSep

error_level

softint WebUtil::FileHandler::error_level = 0

set for error info level

The following are valid error levels:

• 0: no details
• 1: error summary info
• 2: complete error details including stack trace (can expose internal implementation details)