A context object holding all the information relevant to the current request.

A single HttpApplication object can serve multiple requests, but each request is given a HttpContext holding together all the parts of the request.

This HttpContext is used throughout the request lifecycle and different parts of the application - being available in controllers, middleware, request handlers, error handlers and more.

Constructor

new (request:HttpRequest, response:HttpResponse, ?appInjector:Injector, ?session:UFHttpSession, ?auth:UFAuthHandler, ?urlFilters:Array<UFUrlFilter>, ?relativeContentDir:String)

Create a HttpContext object using the supplied objects.

For creating a context for each platform see createContext and createNodeJSContext.

During the constructor, several items are initiated:

  • All of the parameters passed to the constructor are used.
  • this.actionContext is setup with a new ActionContext.
  • this.injector is setup, either as a child of the supplied appInjector, or as a brand new injector.
  • If the session is not supplied, an attempt will be made to inject a UFHttpSession. If that fails, a VoidSession will be used.
  • If the auth handler is not supplied, an attempt will be made to inject a UFAuthHandler. If that fails, a NobodyAuthHandler will be used.
  • Most of the parts of our context are mapped into the request injector. See the documentation of this.injector for more details.

Parameters:

request

(required) The current HttpRequest.

response

(required) The current HttpResponse.

appInjector

(optional) The HttpApplication.injector, which will be the parent injector for our request injector.

session

(optional) An existing session to be used. If not supplied one will be injected.

auth

(optional) An existing authentication handler to be used. If not supplied, one will be injected.

urlFilters

(optional) The URL Filters to use on the current request. If null, no filters will be used.

relativeContentDir

(optional) The path to the content directory, relative to the script directory. The default is "uf-content".

Fields

read only actionContext:ActionContext

The ActionContext used in processing the request.

This holds information about which action the current request is taking, and what result it returned. See ActionContext for more details.

There is one ActionContext for each HttpContext, and it is created during the HttpContext constructor.

read only auth:UFAuthHandler

The current auth handler.

If this is not set during the constructor, then a UFAuthHandler will be injected. If that fails, a NobodyAuthHandler will be used.

completion:EnumFlags<RequestCompletion>

The completion progress of the current request. Setting these values will affect the flow of the request.

For example, if a middleware restores a response from a cached entry matching the current request, it may want to skip the RequestHandler and any ResponseMiddleware:

// Skip remaining request middleware, and the request handler (this will then skip to the response middleware)
ctx.completion.set( CRequestMiddlewareComplete );
ctx.completion.set( CRequestHandlerComplete );

Another example is if you have a controller or some code that writes directly to the output, not the response object, in which case you want to skip the log, flush, middleware etc. (This is the case with the dbadmin tool.)

ctx.completion.set( CRequestHandlerComplete );
ctx.completion.set( CResponseMiddlewareComplete );
ctx.completion.set( CLogComplete );
ctx.completion.set( CFlushComplete );

These values are updated by HttpApplication and various middleware and handlers, or you can update them manually.

read only contentDirectory:String

Get the path of the content directory.

This is a directory that ufront has write-access to, and should preferably not be available for general Http access.

It can be used to store sessions, log files, cache, uploaded files etc.

The value is essentially ${request.scriptDirectory}/$relativeContentDir/, where relativeContentDir is the value that was supplied to the constructor.

If using ufront.application.UfrontApplication, this value can be set with the contentDirectory setting in your ufront.web.Configuration initialization settings.

The trailing slash is always included.

read only currentUser:Null<UFAuthUser>

The current user.

This is a shortcut for auth.currentUser, but with extra null checking.

read only currentUserID:Null<String>

The current user ID.

This is a shortcut for auth.currentUser.id, but with extra null checking.

read only injector:Injector

An dependency injector for the current request.

By default, mappings are provided for the following classes:

When used in a HttpApplication, each call to execute will set the application's injector as this context's parent injector. This means all mappings at the application level will be available in the request injector too.

messages:Array<Message>

A collection of messages that were traced during this request.

read only request:HttpRequest

The current HttpRequest.

read only response:HttpResponse

The current HttpResponse.

read only session:UFHttpSession

The current session.

If this is not set during the constructor, then a UFHttpSession will be injected. If that fails, a VoidSession will be used.

read only sessionID:Null<String>

The current session ID.

This is a shortcut for session.id, but with extra null checking.

read only urlFilters:Array<UFUrlFilter>

The URL filters to be used for this.getRequestUri() and this.generateUri().

This value is set during the constructor.

If you wish to change the filters after the request has begun, it is recommended you use this.setUrlFilters(). This will ensure that the uri for getRequestUri is not cached with the old filters.

Methods

commitSession ():Surprise<Noise, Error>

Commit the session data, if there is any.

Returns:

A future letting you know when the session commit has been completed succesfully, or if an error was encountered.

generateUri (uri:String, ?isPhysical:Bool):String

Takes a normalized ("clean") URI and applies filters to make it work with the server environment.

For example, if you use PathInfoUrlFilter this could turn /home/ into index.n?path=/home/.

This is useful so your code contains the simple URIs, but at runtime they are transformed into the correct form depending on the environment.

getRequestUri ():String

Gets the filtered request URI.

It uses the supplied HttpRequest.uri, but applies any of our this.urlFilters to transform the raw URI into a normalized state.

For example, if you use PathInfoUrlFilter to filter index.n?path=/home/, this would return the normalized URI /home/.

setUrlFilters (filters:Array<UFUrlFilter>):Void

Sets the URL filters.

It is recommended to keep the URL filters stable through a request, so try to set them as early as possible. They can be set during the constructor.

inline ufError (msg:Dynamic, ?pos:PosInfos):Void

Create a Error message on the current request.

Similar to ufTrace, except that the message is noted to be a Error, which may be displayed differently by the tracing module.

Please note this does not throw or catch errors, it merely outputs a message to the log and marks that message as an error. It may be sensible to use it in your error handling code, but not as your error handling code.

inline ufLog (msg:Dynamic, ?pos:PosInfos):Void

Create a Log message on the current request.

Similar to ufTrace, except that the message is noted to be a Log, which may be displayed differently by the tracing module.

inline ufTrace (msg:Dynamic, ?pos:PosInfos):Void

A trace statement that will be associated with this HttpContext

Because of the static nature of Haxe's trace (it always uses haxe.Log.trace, and that does not have access to information about our request), it can be hard to differentiate which traces belong to which requests.

A workaround is to call HttpContext's ufTrace(), store our messages here, and output them at the end of the request. You can call httpContext.ufTrace(someValue) just like you would any other trace, and the traces will be displayed as normal at the end of the request.

Inline shortcuts are provided from ufront.web.Controller and ufront.api.UFApi so that you can call ufTrace() and it points to this method.

inline ufWarn (msg:Dynamic, ?pos:PosInfos):Void

Create a Warning message on the current request.

Similar to ufTrace, except that the message is noted to be a Warning, which may be displayed differently by the tracing module.

Static methods

staticcreateContext (?request:HttpRequest, ?response:HttpResponse, ?appInjector:Injector, ?session:UFHttpSession, ?auth:UFAuthHandler, ?urlFilters:Array<UFUrlFilter>, ?relativeContentDir:String):HttpContext

Available on js-client, neko, php

Create a HttpContext for the current environment.

If request and response are not supplied, they will created. The rest of the parameters are passed directly to the HttpContext constructor.

On NodeJS please use HttpContext.createNodeJsContext() instead.

staticcreateNodeJsContext (req:Request, res:Response, ?appInjector:Injector, ?session:UFHttpSession, ?auth:UFAuthHandler, ?urlFilters:Array<UFUrlFilter>, ?relativeContentDir:String):HttpContext

Available on js-node

Create a HttpContext for the NodeJS environment, using the express haxelib.

The native express-js request and response objects must be supplied.

The rest of the parameters are passed directly to the HttpContext constructor.