Kaya: Writing Kaya web applications

Kaya has built-in support for web application development (using the standard CGI interface). Web applications are treated as event-driven applications, where the next function call is determined by the user's choice of link or form submission. Arbitrary state may be passed from stage to stage implementing a stateful application over the stateless HTTP connections, while strong encryption ensures that this state cannot be forged.

Development models

Kaya has two separate models of web application development: cgi and webapp.

The CGI model is designed for low-level CGI programming, rapid prototyping or testing, and small applications. However, there is no built-in support for structured HTML documents.

The webapp model is designed for larger scale web applications, and has several useful features such as form auto-filling, structured HTML generation, and easy support for web image generation via the optional Image module. Most of the tutorials here assume the use of the webapp model.

Architecture of a Kaya web application

The HTTP protocol is a 'stateless' protocol, and so any state that must be retained from request to request must be stored, either on the web server or by the user's web browser. Both are possible in Kaya, but the default is to store the state in the web browser. The application follows the following cycle:

Receive the HTTP request from the web browser via the CGI interface.
Check whether the request contains encrypted state information.
- If it does, decrypt and uncompress the state information, consisting of the state and a function to process that state.
- Otherwise, use the default function, which should create a fresh application state.
Run the function to process the state and construct the new page. This stage is carried out in different ways in the CGI and webapp models - see the respective tutorials for more information.
Actions that can be taken at this stage in the application are wrapped up as state and a processing function, compressed and encrypted, and placed into hidden form fields in the HTML.
Send the HTML back to the user's web browser as the HTTP response.
The user submits one of the forms, sending the state information back in a new request.

More information about this architecture is available in the architecture reference, including details of the form fields and Kaya functions used.

Important: GET and POST variables beginning with kaya_ should be considered reserved for use by the Kaya standard library, and not used by application authors.

State handling

Both models use the passing of a partial function reference (closure) from page to page to handle state. The function used to generate this varies between the two models, but the principle is the same. The following example from the webapp model calls the registerUser() function with a parameter of NormalUser.

data UserType = NormalUser | Administrator;

ElementTree registerUser(UserType utype) {
    // code to register a user here
}

ElementTree registrationForm() {
    // more code here
    form = addLocalForm(document);
    // add form fields here
    submit = addLocalControlInput(form,"Register User",
                                  registerUser@(),NormalUser);
    // more code here
}

The function is created in the first call to the application, and then run by the second call.

Configuration

A webconfig function may be used in both CGI and webapp programs. It will be called after global initialisation but before anything else, and can be used to control certain processing settings in Kaya (for example, maximum accepted POST size, the temporary directory for file uploads, and so on). Because it is run before user data is read, you cannot use anything depending on user data within it.

For more information, see the documentation for the WebCommon module.

Shutdown and clean up

From 0.5.1 onwards, webapps and CGI programs that need to clean up when they shut down (closing database connections, for example) may use a webshutdown function to do this. This function will run after all other functions in the webapp or CGI, unless the application crashes, is killed, or exits with the exit function. Any uncaught Exceptions in this function will cause it to end, but will not be displayed to the user.

File Security

Every kaya program contains internally a secret application key set during compiling and used for AES encryption of values. It is trivial for someone able to read the program to retrieve the secret key and forge requests, potentially allowing them to call any function in your program with any parameters. You must therefore ensure that no-one is able to read your application binary. If you are using Apache's suexec to run CGI (recommended) then making the application binary user-readable only.

In general, you should apply the same precautions to a kaya application binary as you would to a config file or script that contained a password.

If you download precompiled web applications from the internet, or suspect that your application secret key has been compromised, you can change the secret key without needing to recompile using the kaya-rekey program (called rekey in 0.2.x versions of Kaya) - simply do kaya-rekey webapp.cgi to make a new key. If you are packaging Kaya webapps, strongly consider making your install script call kaya-rekey itself.

In Kaya 0.2.7 and later, web applications may use an external secret key instead. This allows applications to be installed safely in common directories (provided the application is written to use external secret keys, of course). If using an external application secret key, then you obviously need to keep the file containing the external key secure.

More details

The tutorials in this section give additional information about various aspects of Kaya programming.

Depending on what web applications you are writing, you may find a more detailed description of the state handling architecture useful.

Extras

You can download 'Powered by Kaya' logos for use in your webapps from our Extras section.