News KrakenD CE v2.8 released with improved Lua and OpenTelemetry

You are viewing a previous version of KrakenD Enterprise Edition (v2.2), go to the latest version

Document updated on Oct 25, 2022

Load static content from disk

The static-filesystem plugin allows you to fetch and serve static content in two different use cases. When the plugin is used as an http-server, the static content is for your end-users, giving them CSS, JS, images, or JSON files, to name a few examples. On the other side, when the plugin is used as an http-client, the KrakenD endpoints use static content as if it were a backend. You can use it to mock data.

There are different implications and considerations to use one or the other approach. See below each case.

The plugin is very lightweight, simple, and it uses only the standard lib. It’s called filesystem because the static file is changed whenever the content updates in the filesystem. If you need caching its contents, consider adding a CDN in front of KrakenD.

From a content management perspective, you have to place the static content in the filesystem where KrakenD runs. The plugin returns the interpreted mime-type for each content type.

Directory listing

When the user requests a directory (no specific file), KrakenD shows the directory contents.

Place an index.html in each directory you don’t want directory listing

KrakenD will follow symlinks pointing out of the directory tree, which can be dangerous. Access to hidden files and directories is also enabled, meaning that directories or files starting with a period (such as .git or .htpasswd) could expose sensitive information. Remove those files.

The html output when browsing directories without an index.html looks like this:

<pre>
<a href="file1.json">file1.json</a>
<a href="file2.css">file2.css</a>
<a href="directory/">directory/</a>
</pre>

Serving static content to end-users

When the plugin is used as an HTTP server handler, it works similarly to a regular web server; it loads content from the disk and presents it to the users.

The plugin is executed before the gateway’s router layer enters the scene, as it happens in all server handler plugins. The implications of this statement are that if a path contains the defined prefix it won’t hit any KrakenD endpoint later, unless you add that endpoint in the skip section. The plugin simply takes all incoming requests and checks if the URL matches the defined URL prefix. When it does, it returns any static content found in the filesystem.

Whether a matching URL prefix ends up retrieving a file in the filesystem or not, the request finishes the journey here anyway. It won’t be passed to the router layer to serve endpoint content, thus no passing to the defined endpoints.

Notice the two different configurations of this plugin

Configuration as HTTP server handler

The configuration requires the following entry at the root level:

{
    "version": 3,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "plugin/http-server": {
            "name": ["static-filesystem", "another-plugin-maybe" ],
            "static-filesystem": {
                "prefix": "/media",
                "path": "./../../assets",
                "skip": [
                    "/media/ignore/this/directory",
                    "/media/file.json"
                ],
            }
        }
    }
}
Fields of Static Filesystem
* required fields

path * string
The folder in the filesystem containing the static files. Relative to the working dir where KrakenD config is (e.g.: ./assets) or absolute (e.g.: /var/www/assets).
Example: "./static/"
prefix * string
This is the beginning (prefix) of all URLs that are resolved using this plugin. All matching URLs won’t be passed to the router, meaning that they are not considered endpoints. Make sure you are not overwriting valid endpoints. When the prefix is /, then all traffic is served as static and you must declare a prefix under skip (e.g.: /api) to match endpoints.
Example: "/media/assets"
skip array
An array with all the prefix URLs that despite they could match with the prefix, you don’t want to treat them as static content and pass them to the router.
Example: ["/media/ignore/this/directory","/media/file.json"]

Serving static content to KrakenD itself

When the plugin is used as an HTTP client executor, fetching the static content does not happen until the matching endpoint is called. In this scenario, the returned static content is to be consumed by KrakenD. The endpoint’s configuration decides if the content ends up returning to the end-user “as is” (using no-op), or if the content is part of larger response and needs to be parsed in conjunction with other backends’ response (e.g: json encoding).

Configuration as HTTP client executor

The plugin needs to be included using the extra_config namespace "plugin/http-client". Your backend section needs the following entry:

{
    "extra_config": {
        "plugin/http-client": {
            "name": "static-filesystem",
            "path": "./../../"
        }
    }
}

There is only one setting that you need to set:

Fields of "plugin/static-filesystem"
* required fields

path * string
The folder in the filesystem containing the static files. Relative to the working dir where KrakenD config is (e.g.: ./assets) or absolute (e.g.: /var/www/assets).
Example: "./static/"

Example without manipulation

The following example shows an endpoint that could reply to a request like /logs/2020-09-09/errors and return a log file in the filesystem without manipulation (“as is”).

{
    "endpoint": "/logs/{date}/{file}",
    "output_encoding": "no-op",
    "backend": [
        {
            "url_pattern": "/{date}-{file}.log",
            "host": ["http://this-host-is-not-used-but-field-is-mandatory"],
            "encoding": "no-op",
            "extra_config": {
                "plugin/http-client": {
                    "name": "static-filesystem",
                    "path": "/var/log/application/"
                }
            }
        }
    ]
}

Notice that the url_pattern constructs the filename using data from the user request, and the path in this example.

Example with data manipulation

In the following example we can see a KrakenD endpoint fetching and aggregating data from two different endpoints. The first backend entry is an API that returns content in XML format, and the second, a raw JSON file static-service.json stored in the disk.

KrakenD will parse both backends and return both calls aggregated in the endpoint. With this example, we have built a temporary service until it’s actually coded.

{
    "endpoint": "/user/{id}",
    "backend": [
        {
            "url_pattern": "/user/data/{id}",
            "encoding": "xml",
            "host": ["http://some-service"]
        },
        {
            "url_pattern": "/static-service.json",
            "encoding": "json",
            "host": ["http://this-host-is-not-used-but-field-is-mandatory"],
            "extra_config": {
                "plugin/http-client": {
                    "name": "static-filesystem",
                    "path": "./"
                }
            }
        }
    ]
}

Advanced usage

For more advance uses of the static plugin and enabling more sources other than loading from the filesystem, there are more customizable plugins available. These plugins need customization and delivered on request. Ask support if you have special needs for static content delivery.

Scarf

Unresolved issues?

The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.

See all support channels