Request context [v2]

The request context is materialized by the RequestContext class.

Description

As its name says, it is used to know in which context an operation is asked. For instance, the readDir method of a file system might need the user, or it might have a special behaviour for some headers in the request. It is also used by the HTTP/WebDAV methods (PROPFIND, PROPPATCH, etc...) to send a response to the user, because it carries the response object.

Creation

This object is created by the server when a request is received. It can also be created through its static create(...) method and its static createExternal(...) method. The static create(...) method will create a RequestContext as a request/response carrier. The static createExternal(...) method will create a RequestContext as an external request (from outside of the HTTP interface), which allow a script to use the file systems as if it was a request, but without the response object. This last static method allow to define the user, the headers and the url of the (external) request. If no user is specified, it will use a custom super-admin user, which the isAdministrator value equals to true.

Implementation

class RequestContextHeaders
{
    contentLength : number
    isSource : boolean
    depth : number
    host : string

    find(name : string, defaultValue : string = null) : string;
    findBestAccept(defaultType : string = 'xml') : string;
}

interface RequestedResource
{
    path : Path
    uri : string
}

interface RequestContextExternalOptions
{
    headers ?: { [name : string] : string }
    url ?: string
    user ?: IUser
}

export class RequestContext
{
    requested : RequestedResource
    headers : RequestContextHeaders
    server : WebDAVServer
    user : IUser
    
    getResource(callback : ReturnCallback<Resource>)
    getResource(path : Path | string, callback : ReturnCallback<Resource>);

    getResourceSync(path ?: Path | string) : Resource;

    fullUri(uri : string = null);

    prefixUri();
}

export class ExternalRequestContext extends RequestContext
{
    static create(server : WebDAVServer) : ExternalRequestContext
    static create(server : WebDAVServer, callback : (error : Error, ctx : ExternalRequestContext) => void) : ExternalRequestContext
    static create(server : WebDAVServer, options : RequestContextExternalOptions) : ExternalRequestContext
    static create(server : WebDAVServer, options : RequestContextExternalOptions, callback : (error : Error, ctx : ExternalRequestContext) => void) : ExternalRequestContext;
}

export class HTTPRequestContext extends RequestContext
{
    responseBody : string
    request : http.IncomingMessage
    response : http.ServerResponse
    exit : () => void

    static create(server : WebDAVServer, request : http.IncomingMessage, response : http.ServerResponse, callback : (error : Error, ctx : HTTPRequestContext) => void);

    noBodyExpected(callback : () => void);

    checkIfHeader(resource : Resource, callback : () => void)
    checkIfHeader(fs : FileSystem, path : Path, callback : () => void);

    askForAuthentication(checkForUser : boolean, callback : (error : Error) => void);

    writeBody(xmlObject : XMLElement | object);
    
    setCode(code : number, message ?: string);
    static defaultStatusCode(error : Error) : number;
    setCodeFromError(error : Error) : boolean;
}