File Upload

Appweb has an integrated file upload filter that accepts and processes file upload requests. The Appweb upload filter intercepts uploaded files, saves them to disk and passes details about the uploaded file to the request handler for processing.

File upload uses multi-part mime encoding to transport files over HTTP POST requests. This is specified in the IETF standard RFC 2388.

Overview

Because uploaded files can be very large, Appweb uses specialized handling for the receipt, storage and processing of uploaded files. When an upload request is received, Appweb will accept and store the uploaded file before starting the request handler to respond to the request. The request handler does not directly receive the uploaded file. Rather, Appweb passes the name of the temporary file holding the uploaded file. Appweb expects that the handler will process, copy or move the temporary file before completing the request. Once the handler has completed, Appweb will remove any remaining upload temporary files.

Enabling File Upload

To enable the upload filter, you need to add it to the request pipeline via the AddInputFiler directive. For example:

<Route /upload-uri>
    AddInputFilter uploadFilter
    UploadDir /tmp
    UploadAutoDelete on
</Route>

It is good practice to define the uploadFilter within a qualifying route. This minimizes the security attack surface.

Appweb Upload Directives

There are three other appweb.conf directives that relate specifically to upload filter.

• LimitUpload — This specifies the maximum size an uploaded file may be.
• UploadDir — This specifies the directory to hold uploaded files.
• UploadAutoDelete — This specifies if the uploaded files should be automatically deleted from the upload directory after the handler has completed processing the request.

Upload File Details

Once a file is uploaded, the Appweb handler responsible for processing the request will receive details about uploaded files via the request parameters. Different request handlers expose these request parameters in different ways.

ESP Uploads

ESP provides direct access to the internal Appweb uploaded files structure. Each uploaded file is described by a HttpUploadFile structure. These structures are stored in an MprHash table indexed by their HTML file upload ID.

The HttpUploadFile structure is defined as:

typedef HttpUploadFile {
    cchar *filename;        /* Local (temp) name of the file */
    cchar *clientFilename;  /* Client side name of the file */
    cchar *contentType;     /* Content type */
    ssize size;             /* Uploaded file size */
} HttpUploadFile;

You can access uploaded files via:

HttpConn        *conn;
HttpUploadFile  *file;
MprKey          *kp;
conn = getConn();
for (ITERATE_KEY_DATA(conn->rx->files, kp, file)) {
    render("FILENAME %s\n", file->filename);
    render("CLIENT_NAME %s\n", file->clientFilename);
    render("TYPE %s\n", file->contentType);
    render("SIZE %d\n", file->size);
}

Ejscript Uploads

Ejscript stores uploaded files in the request.files property. Files is an object hash of files indexed by the HTML ID. Each file is represented by an instance of the UploadFile class.

Alternative Upload Technique

File upload using POST requests is one way to upload files. Another is to use the HTTP PUT method. This uploads a file without encoding and can offer higher performance. The HTTP DELETE method can then be used to delete files from the server.

CGI Upload

CGI provides them to applications via environment variables that start with FILE_. The variables end with an ID which is a sequential index for the file beginning at 0 for the first file.

• FILE_CLIENT_FILENAME_ID — the client specified filename
• FILE_CONTENT_TYPE_ID — the file mime content type
• FILE_FILENAME_ID — the local temporary filename containing the data
• FILE_SIZE_ID — the size of the uploaded file

PHP Uploads

PHP has its own file upload handler and should not be confused with the higher performing Appweb upload filter. If you wish to use the PHP upload mechanism, you must disable the upload filter for your PHP requests. Do this by removing the AddInputFilter uploadFilter in the appweb.conf configuration file.

If you wish to use the Appweb upload filter with PHP, you will see environment variables in the _POST collection. The naming is the same as that for the CGI handler described above.