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.

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"
                ],
            }
        }
    }
}

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:

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.