Overview

Lightweight HTTP reverse proxy for content-based request filtering and routing

What is fltr?

fltr is a lightweight HTTP reverse proxy that routes requests by inspecting the contents. It examines the Searchable Content: the request body, and selected headers and query parameters, and matches it against the Block Rules.

Requests with no matches, i.e. allowed requests, are forwarded to the Allow Upstream. Blocked requests are either proxied to the Block Upstream if it is configured, or they are discarded.

It preserves the method, ordinary end-to-end headers, and body, but drops the incoming URL path. See HTTP behavior for the full forwarding rules.

flowchart LR
    R(<b>📦 Request</b>) --> BR(<b>📋 Block Rules</b>)
    BR -- No Rules match ---> A(<b>✅ Allowed</b>)
    BR -- Any Rule matches ---> B(<b>❌ Blocked</b>)

    classDef blue fill:#4287ff1F,stroke:#4287ff
    classDef green fill:#00c7531F,stroke:#00c753
    classDef red fill:#ff1a471F,stroke:#ff1a47
    class BR blue
    class A green
    class B red

Why was fltr created?

fltr was built for a chatty service that sent status updates to a ntfy topic, with no option to select which specific messages to omit. Some were frequent but of little value, while important updates got buried. fltr was written to sit between the service and ntfy and drop the unwanted messages on the way.

Why should I use fltr?

• Content-based filtering: fltr looks at the Searchable Content, not just the URL.
• Simple rules: Block Rules are a JSON object of named term lists. A rule matches when every term appears in the Searchable Content, and matching is case-insensitive by default.
• Allowed or Blocked: requests that match no rule go to the Allow Upstream; blocked requests go to the Block Upstream when configured, or they are discarded.
• (Almost) transparent forwarding: fltr preserves the method, end-to-end headers, body, and query parameters, strips hop-by-hop headers, and drops the incoming URL path.
• Lightweight: fltr ships as one Go binary and a small container image.
• Open source: fltr is licensed under the AGPL-3.0.

Where to go next

Getting started

• Getting started: install fltr, run it, and send your first request

Other Guides

• Docker: images, tags, compose setup
• Troubleshooting: common failures and fixes
• FAQ: recurring questions about matching and forwarding

Reference

• How it works: startup, matching, and routing
• Environment variables: every environment variable and its defaults
• Block Rules: file format and matching semantics
• HTTP behavior: status codes, headers, and path handling
• Glossary: the terms fltr uses

Internals

• Development: project layout, testing, building, and releases