Class Poco::OSP::Web::WebServerDispatcher

File Information

Library: OSP/Web
Package: Web
Header: Poco/OSP/Web/WebServerDispatcher.h

Description

A WebServerDispatcher is some sort of meta HTTPRequestHandlerFactory. It groups together several other HTTPRequestHandlerFactory instances and distributes requests to them according to the registered request handler extension points (see the WebServerExtensionPoint class).

Inheritance

Direct Base Classes: Poco::OSP::Service

All Base Classes: Poco::OSP::Service, Poco::RefCountedObject

Member Summary

Member Functions: addCustomResponseHeaders, addFilter, addVirtualPath, authService, authorize, authorizeBasic, authorizeBearer, authorizeSession, cleanPath, enableCORS, findFilter, findResource, formatMessage, getCachedResource, handleCORS, handleRequest, htmlize, isA, jsonize, listVirtualPaths, logRequest, mapPath, normalizePath, onBundleStopping, parseAuthMethods, removeBundle, removeFilter, removeVirtualPath, sendBadRequest, sendForbidden, sendFound, sendHTMLResponse, sendInternalError, sendJSONResponse, sendMethodNotAllowed, sendNotAuthorized, sendNotFound, sendResource, sendResponse, sessionManager, shouldCompressMediaType, threadPool, tokenValidator, type, uncacheBundleResources, virtualPathMappings

Inherited Functions: duplicate, isA, referenceCount, release, type

Nested Classes

struct Config

struct PathCORS

struct PathInfo

struct PathSecurity

Security attributes for a registered path.

struct RequestHandledEvent

struct VirtualPath

A VirtualPath struct is used to specify a path mapping for a bundle.

Types Aliases

PathInfoMap

using PathInfoMap = std::map < std::string, PathInfo >;

PathMap

using PathMap = std::map < std::string, VirtualPath >;

PatternVec

using PatternVec = std::vector < VirtualPath >;

Enumerations

AuthMethod

AUTH_BASIC = 1

HTTP Basic authentication

AUTH_SESSION = 2

Session-based authentication

AUTH_BEARER = 4

Bearer token-based authentication (OAuth 2.0)

AUTH_ALL = AUTH_BASIC | AUTH_SESSION | AUTH_BEARER

Options

CONF_OPT_COMPRESS_RESPONSES = 0x01

Compress responses using gzip content encoding.

CONF_OPT_CACHE_RESOURCES = 0x02

Enable in-memory caching of bundle resources.

CONF_OPT_ADD_AUTH_HEADER = 0x04

Add X-OSP-Authorized-User header to authenticated requests.

CONF_OPT_ADD_SIGNATURE = 0x08

Add server signature to generated HTML error responses.

CONF_OPT_LOG_FULL_REQUEST = 0x10

Enable full logging of request and response headers.

CONF_OPT_ENABLE_CORS = 0x20

Globally enable or disable CORS handling.

ResponseFormat

RESPONSE_FORMAT_HTML = 1

HTML-formatted error page

RESPONSE_FORMAT_JSON = 2

JSON-formatted error page

SpecializationMode

A bundle that registers a resource mapping or request handler for a certain path can specify whether other bundles can register subdirectories of this directory.

SM_NONE = 0

No one can register subdirectories

SM_OWNER = 1

Only the owner bundle can register subdirectories

SM_ALL = 2

Everyone can register subdirectories

Constructors

WebServerDispatcher

explicit WebServerDispatcher(
const Config & config
);

Creates the WebServerDispatcher.

Destructor

~WebServerDispatcher

virtual ~WebServerDispatcher();

Destroys the WebServerDispatcher.

Member Functions

addFilter

void addFilter(
    const std::string & mediaType,
    WebFilterFactoryPtr pFilterFactory,
    const WebFilter::Args & args
);

Adds a filter factory for the given media type.

Throws a Poco::ExistsException if a filter already exists for the given mediaType.

addVirtualPath

void addVirtualPath(
const VirtualPath & virtualPath
);

Adds the given VirtualPath to the path mapping table.

Throws an ExistsException if a mapping for the given path already exists.

handleRequest

void handleRequest(
    Poco::Net::HTTPServerRequest & request,
    Poco::Net::HTTPServerResponse & response,
    bool secure
);

Handles the given request. Secure specifies whether the request has been sent over a secure (HTTPS) connection.

isA

virtual bool isA(
const std::type_info & otherType
) const;

See also: Poco::OSP::Service::isA()

listVirtualPaths

void listVirtualPaths(
PathInfoMap & paths
) const;

Returns a map containing all virtual paths (key) that are not patterns and not marked as hidden, and their descriptions (value).

parseAuthMethods

static int parseAuthMethods(
const std::string & methods
);

Parses a comma-separated list of authentication method names and returns a value with the corresponding AuthMethod flags set.

removeBundle

void removeBundle(
Bundle::ConstPtr pBundle
);

Removes all mappings from the given bundle.

removeFilter

void removeFilter(
const std::string & mediaType
);

Removes the filter for the given mediaType.

removeVirtualPath

void removeVirtualPath(
const std::string & virtualPath
);

Removes a path mapping from the path mapping table.

Throws a NotFoundException if the given path does not exist.

threadPool

Poco::ThreadPool & threadPool();

Returns the thread pool for use by Poco::Net::HTTPServer.

type

virtual const std::type_info & type() const;

See also: Poco::OSP::Service::type()

uncacheBundleResources

void uncacheBundleResources(
Bundle::ConstPtr pBundle
);

Removes all cached resources from the given bundle form the cache.

virtualPathMappings

void virtualPathMappings(
PathMap & mappings
) const;

Returns all path mappings. This member function creates a full copy of the internal path map.

addCustomResponseHeaders

void addCustomResponseHeaders(
Poco::Net::HTTPServerResponse & response
);

Adds any configured custom response headers.

authService

Poco::OSP::Auth::AuthService::Ptr authService() const;

Returns a pointer to the auth service, if it is available, or null otherwise.

authorize

bool authorize(
    Poco::Net::HTTPServerRequest & request,
    const VirtualPath & vPath,
    std::string & username
) const;

Authorizes the request.

authorizeBasic

bool authorizeBasic(
    Poco::Net::HTTPServerRequest & request,
    const std::string & creds,
    const VirtualPath & vPath,
    std::string & username
) const;

Authorizes the request using a HTTP Basic Authentication.

authorizeBearer

bool authorizeBearer(
    Poco::Net::HTTPServerRequest & request,
    const std::string & token,
    const VirtualPath & vPath,
    std::string & username,
    std::string & scope
) const;

Authorizes the request using bearer token-based authentication.

authorizeSession

bool authorizeSession(
    Poco::Net::HTTPServerRequest & request,
    const VirtualPath & vPath,
    std::string & username
) const;

Authorizes the request using a session-based authentication.

cleanPath

static bool cleanPath(
std::string & path
);

Removes unnecessary characters (such as trailing dots) from the path and checks for illegal or dangerous characters.

Returns true if the path is okay, false otherwise.

enableCORS

bool enableCORS(
    const Poco::Net::HTTPServerRequest & request,
    Poco::Net::HTTPServerResponse & response,
    const VirtualPath & vPath
) const;

Adds CORS headers on the response if required.

findFilter

WebFilterPtr findFilter(
const std::string & mediaType
);

Returns a WebFilter instance for the given mediaType, or a null pointer if no WebFilterFactory has been registered for the given mediaType.

findResource

std::istream * findResource(
    Bundle::ConstPtr pBundle,
    const std::string & base,
    const std::string & res,
    const std::string & index,
    std::string & mediaType,
    std::string & resolvedPath,
    bool canCache
) const;

Returns a resource stream for the given path, or a null pointer if no matching resource exists.

formatMessage

std::string formatMessage(
    const std::string & messageId,
    const std::string & arg1 = std::string (),
    const std::string & arg2 = std::string ()
);

Reads a message from the bundle.properties resource and replaces placeholders $1 and $2 with arg1 and arg2, respectively.

getCachedResource

std::istream * getCachedResource(
    Bundle::ConstPtr pBundle,
    const std::string & path,
    bool canCache
) const;

Returns a resource stream for the given path, or a null pointer if no matching resource exists. If caching is enabled both globally and for the specific resource, attempts to cache the resource.

handleCORS

bool handleCORS(
    const Poco::Net::HTTPServerRequest & request,
    Poco::Net::HTTPServerResponse & response,
    const VirtualPath & vPath
) const;

Handles CORS preflight requests and headers.

htmlize

static std::string htmlize(
const std::string & str
);

Returns a HTML-ized version of the given string.

jsonize

static std::string jsonize(
const std::string & str
);

Returns a JSON-ized (escaped) version of the given string.

logRequest

void logRequest(
    const Poco::Net::HTTPServerRequest & request,
    const Poco::Net::HTTPServerResponse & response,
    const std::string & username,
    Poco::Clock::ClockDiff duration
);

Logs the HTTP request.

mapPath

const VirtualPath & mapPath(
const std::string & path,
const std::string & method
) const;

Maps a URI to a VirtualPath.

Throws a NotFoundException if no suitable mapping can be found.

normalizePath

static std::string normalizePath(
const std::string & path
);

Creates normalized path for internal storage. The normalized path always starts and ends with a slash.

onBundleStopping

void onBundleStopping(
const void * pSender,
BundleEvent & ev
);

When a bundle is stopped, all of its request handlers and mappings are automatically disabled.

sendBadRequest

void sendBadRequest(
    Poco::Net::HTTPServerRequest & request,
    const std::string & message,
    ResponseFormat format = RESPONSE_FORMAT_HTML
);

Sends a 404 Not Found error response.

sendForbidden

void sendForbidden(
    Poco::Net::HTTPServerRequest & request,
    const std::string & path,
    ResponseFormat format = RESPONSE_FORMAT_HTML
);

Sends a 403 Forbidden error response.

sendFound

void sendFound(
    Poco::Net::HTTPServerRequest & request,
    const std::string & path,
    ResponseFormat format = RESPONSE_FORMAT_HTML
);

Sends a 302 Found response.

sendHTMLResponse

void sendHTMLResponse(
    Poco::Net::HTTPServerRequest & request,
    Poco::Net::HTTPResponse::HTTPStatus status,
    const std::string & message
);

Sends a standard status/error response in HTML format.

sendInternalError

void sendInternalError(
    Poco::Net::HTTPServerRequest & request,
    const std::string & message,
    ResponseFormat format = RESPONSE_FORMAT_HTML
);

Sends a 500 Internal Server Error response.

sendJSONResponse

void sendJSONResponse(
    Poco::Net::HTTPServerRequest & request,
    Poco::Net::HTTPResponse::HTTPStatus status,
    const std::string & message
);

Sends a standard status/error response in JSON format.

sendMethodNotAllowed

void sendMethodNotAllowed(
    Poco::Net::HTTPServerRequest & request,
    const std::string & message,
    ResponseFormat format = RESPONSE_FORMAT_HTML
);

Sends a 405 Method Not Allowed error response.

sendNotAuthorized

void sendNotAuthorized(
    Poco::Net::HTTPServerRequest & request,
    const std::string & path,
    ResponseFormat format = RESPONSE_FORMAT_HTML
);

Sends a 401 Unauthorized error response.

sendNotFound

void sendNotFound(
    Poco::Net::HTTPServerRequest & request,
    const std::string & path,
    ResponseFormat format = RESPONSE_FORMAT_HTML
);

Sends a 404 Not Found error response.

sendResource

void sendResource(
    Poco::Net::HTTPServerRequest & request,
    const std::string & path,
    const std::string & vpath,
    const std::string & resPath,
    const std::string & resBase,
    const std::string & index,
    Bundle::ConstPtr pBundle,
    bool canCache
);

Sends a bundle resource as response.

Variables

SERVICE_NAME

static const std::string SERVICE_NAME;

requestHandled

Poco::BasicEvent < const RequestHandledEvent > requestHandled;

Fired after a request has been handled and the response has been sent.

Can be used for computing metrics.