URLs

Overview

Onion basic unit for path dispatching is the handler. There is a root handler that is the first one to be called. Each handler can:

• Process the request
• Consume part of the path and call another handler
• Do not process the request

Process the request

At the end of each path tree there will be processors that depending on input will return some data to the http client. It can be contents of a file, the processed json or a templated html. Normally as developer you have to center on developing this requests processors.

Consume part of the path and call another handler

Each petition has a request path. The full original path is stores in the full path (onion_request_get_fullpath). But the layout of your path tree may need to consume the begining of the fullpath and call another handler. To ease the task of this subhandler, we have a consumed version of the fullpath called the path (onion_request_get_path).

Normally developers should focus on the consumed path, to ease modularity. As an example the exportlocal handler uses the path, as you can set it to listen on any url (/static/, or /s/ or /), but whats important for the exportlocal is just whats remains after that location.

For example, as being consumed:

Full path: /private/static/myfile.gpg:

+----------------------------+-----------------+---------------------+
| Path                       | Consumes        | Handler             |
+----------------------------+-----------------+---------------------+
| private/static/myfile.gpg  | private/        | Auth handler        |
+----------------------------+-----------------+---------------------+
| static/myfile.gpg          | static/         | url handler         |
+----------------------------+-----------------+---------------------+
| myfile.gpg                 | myfile.gpg      | export local file   |
+----------------------------+-----------------+---------------------+

1. Checks valid authorization/authentication for user, if he/she has access to the resources.
2. An url handler checks it want to access the static part of private data.
3. An exportlocal file handler returns the contents of that file.

There is an special case that it consumes nothing, but acts as a gateway to another handler.

Do not process the request

Handlers when called can decide, based on whatever reason (path, server name, a header, time of the day...) to process or not a petition, if processed OCS_PROCESSED should be returned. If not OCS_NOT_PROCESSED. There are more options: OCS_INTERNAL_ERROR, OCS_NOT_IMPLEMENTED, OCS_WEBSOCKET and OCS_FORBIDDEN.

If not processed (OCS_NOT_PROCESSED), the next handler will try to process it. After any handler developers can set the next to process with onion_handler_add. If no handler can process it, there is a default handler that returns a 404 not found.

URL handlers.

There is a builtin very practical handler, the url handler. It follows the ideas from Django dispatcher: developer can set a regex for the path, and a handler for it. Also another url handler can be set to keep consuming the path, until a final handler really processes the petition.

For example:

onion_url *root=onion_root_url(o);
onion_url *user=onion_url_new();
// Fill user urls

onion_url_add(root, "^static", onion_handler_export_local_new("."));
onion_url_add_url(root, "^user", user);