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.

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:

HttpStream      *stream;
HttpUploadFile  *file;
MprKey          *kp;
stream = getStream();
for (ITERATE_KEY_DATA(stream->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);
}

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 access to the uploaded files 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.