Serving or using static content

Document updated on Jan 28, 2021

The krakend-static-live plugin allows you to fetch and serve static content in two different use cases. When the plugin is used as an http server handler, 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 executor, the KrakenD endpoints use static content as if it were a backend.

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 also called live 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.

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": 2,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "github_com/devopsfaith/krakend/transport/http/server/handler": {
            "name": ["krakend-static-live", "another-plugin-maybe" ],
            "krakend-static-live": {
                "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 "github.com/devopsfaith/krakend/transport/http/client/executor". Your backend section needs the following entry:

{
    "extra_config": {
        "github.com/devopsfaith/krakend/transport/http/client/executor": {
            "name": "krakend-static-live",
            "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": {
                "github.com/devopsfaith/krakend/transport/http/client/executor": {
                    "name": "krakend-static-live",
                    "path": "/var/log/application/"
                }
            }
        }
    ]
}

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": {
                "github.com/devopsfaith/krakend/transport/http/client/executor": {
                    "name": "krakend-static-live",
                    "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.