KrakenD Enterprise 2.0 released! Read the Release notes »

Documentation

Recent changes

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.

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.

Place an index.html in each directory you don’t want directory listing. The html output when browsing directories 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 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.

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/assets",
                "path": "./../../"
            }
        }
    }
}

Notice the two different configurations of this plugin:

  • prefix: This is the beginning of all URLs that are resolved using this plugin. All matching URLs won’t be passed to the router. Make sure you are not overwriting valid endpoints.
  • path: The path in the filesystem containing the static files. Relative to the working dir or absolute.

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:

  • path: The path in the filesystem containing the static files. Relative to the working dir or absolute.

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.

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.

We use cookies to understand how you use our site and to improve your overall experience. By continuing to use our site, you accept our Privacy Policy. More information