https://kore.io

Kore routing

2018-04-25

Like most web frameworks Kore has a built-in router.

In Kore, this consists you creating a map of paths and their respective callback functions called a page handler. This map exists in the Kore configuration for your application and is attached to a specific domain. The page handler is called for each request to the defined path on the requested domain no matter what method is used.

If Kore does not find a match it returns a 404.

Example: For domain kore.io call index_page for each request to '/'.

domain kore.io {
	static / index_page
}

Kore defines two types of page handlers, a static one, and a dynamic one. The static type tells it to match the path entirely, a plain string comparison if you will. The dynamic one should be a regular expression to which the requested path is matched against.

Example: In the configuration for this blog, we will find the following dynamic rules.

domain blog.kore.io {
	dynamic ^/posts/[a-z1-9\-]+$	post_render	referer_log
	dynamic ^/drafts/[a-z1-9\-]+$	draft_render	author
}

With the above configuration, a request to /post/title would go to the post_render function while /draft/title will go to draft_render.

The first match always wins.

Authentication

So what are those additional right-most arguments in the previous example?

Good question! Those are optional authentication blocks. They instruct Kore that before allowing access to that handler the request should be run through the defined authentication method. If the authentication function returns KORE_RESULT_ERROR, the request is denied and Kore automatically sends a 403 or a redirect to some configured page.

For example, take a look at the author authentication block for this blog system. This authentication block protects any request to the drafts handler.

authentication author {
	authentication_type		cookie
	authentication_validator	v_session
	authentication_value		blog_token
	authentication_uri		/login/
}

The above authentication block instructs Kore to find a cookie called blog_token in the request and call the v_session validator on it. If that validator returns KORE_RESULT_ERROR redirect the request back to /login/.

Slapping the author authentication block on any page handler that should be covered by the login automatically makes this a reality.

Parameters

Following Kore its secure-by-default approach, request parameters are not parsed or accessible to the application until the application itself explicitly asks for them.

An application must define which parameters are allowed for with method, on which path and what validator they must pass before being made available. If validation fails the parameter is simply filtered out and any attempts to read it will fail.

Parameter validation in Kore is not optional.

Using this blog again as an example lets take a look how the params block for the /login/ handler is configured.

params post /login/ {
	validate user v_user
	validate passphrase v_any
}

Deconstructing the above, we tell Kore that for POST requests to /login/ it will validate the user parameter using v_user and the passphrase parameter using the v_any validator. If these validations fail the parameters are, as mentioned earlier, filtered out from the request.

Validators

I have been talking about validators a lot now in the past few sections. But how are they defined and what do they look like?

A validator in Kore is defined as either a regular expression or a callback to a function that returns KORE_RESULT_OK or KORE_RESULT_ERROR. To continue using this blog as an example lets take a look at how the validators we mentioned earlier are defined.

validator v_any regex ^.*$
validator v_session function auth_session
validator v_user function auth_user_exists

The v_any validator is a regular expression.

The v_session validator will call the C function auth_session to verify the request blog_token cookie.

The v_user validator will call the C function auth_user_exists to verify the incoming username actually exists in our configuration.

More

So this the Kore routing system in a nutshell. It covers routing paths to page handlers, authentication of paths and parameter validation. In the next post, I will talk about how to actually obtain request parameters from your application and more.

For a detailed view of all configuration options see the Kore example configuration here. You may also find the source code for this blog by clicking the kore-blog link in the bottom left.

.joris

kore-blog v0.2