On‐the‐Fly filters

Sometimes you may want to run specific filters on a feed without having to define it in the config file. With On-the-Fly Filters enabled, you can specify these filters in URL query parameters to any endpoint to dynamically affect the behavior of an endpoint.

Thanks to @tillcash for suggesting this feature.

How to use On-the-Fly Filters?

On endpoints with on-the-fly filters enabled, you can append filters as extra queries to the endpoint.

For example, /endpoint.xml?keep_only=Show%20HN&limit=10 will first run the filters defined in the configuration, then filter the entries to keep only those containing keyword "Show HN", and afterwards limit the result to at most 10 entries. It would be equivalent to having the two filters defined in config file:

  filters:
    - keep_only: Show HN
    - limit: 10

All normal filters can be used as on-the-fly filters. But since on-the-fly filters takes on their config from query parameters, only simple configs are supported. In other words, it doesn't work for complex filter whose config is not a simple string or integer.

How to enable On-the-Fly Filters?

If you launch rss-funnel server without specifying a config file, e.g. rss-funnel server, then an endpoint with dynamic source and on-the-fly filter enabled will be created by default on /otf. If you use Docker or use environment to configure the app, DO NOT specify the RSS_FUNNEL_CONFIG environment variable.

Otherwise, if you have a config file, such endpoint will not be created automatically. However, you can easily create such endpoint in the config file as follows:

endpoints:
  - path: /otf
    on_the_fly_filters: true
    filters: []

In fact, you can enable On-the-Fly filters on any existing endpoints by specifying the on_the_fly_filters: true in your endpoint config like this:

endpoints:
  - path: /hacker-news.xml
    on_the_fly_filters: true
    source: https://news.ycombinator.com/rss
    filters:
      - full_text: {}

In that case, any On-the-Fly Filters will be run after the filters defined in the config file.

Filters with blank config

Some filters, like full_text or simplify_html may use a blank config. To specify these as on-the-fly filters, the query parameter should take no value.

Here's an example: /otf?source=https://news.ycombinator.com/rss&limit=10&full_text&discard=crypto

The ordering of On-the-Fly Filters

The application order of On-the-Fly Filters is consistent with the order the filters are specified in the url query. In other words, there is no reordering of the On-the-Fly Filters.