Add parameter block-when-referrer-not-parsable to plugin referer-restriction

[mueckl]

Description

I want to block request with an invalid referer-header.

At the moment not parsable referrers are treated like empty referrer values.
see

https://github.com/apache/apisix/blame/dca582e3bd49665531509c51880dcb6a131601df/apisix/plugins/referer-restriction.lua#L114

I want to configure that empty referrers are ok (with an additional black- or white-list), but malformed / malicious referrers-strings are blocked

[Baoyuantop]

Thanks for the detailed report @mueckl.

Current Behavior

Currently, when the Referer header is present but unparsable (e.g. www.yy.com without a scheme), parse_uri returns nil and the plugin treats it exactly the same as a missing Referer — both are controlled by the single bypass_missing flag. This means there's no way to allow requests with no Referer while blocking requests with a malformed one.

This is by design (code, tests, and docs are consistent), but it does limit flexibility for security-conscious use cases like yours.

Proposed Solution

Introduce a new optional boolean parameter, e.g. bypass_malformed (naming open for discussion):

• When not set (default): malformed referrers follow bypass_missing behavior — fully backward compatible, no behavior change for existing users.
• When set to true: malformed referrers are allowed through, regardless of bypass_missing.
• When set to false: malformed referrers are blocked, even if bypass_missing is true. This is the behavior you're looking for.

Example configuration:

{
    "referer-restriction": {
        "bypass_missing": true,
        "bypass_malformed": false,
        "whitelist": ["*.example.com"]
    }
}

This would allow requests without a Referer header, while blocking requests with an unparsable/malicious Referer.

Open Questions

• Naming: bypass_malformed, block_unparsable_referer, or something else? Suggestions welcome.
• Default value strategy: defaulting to nil (fall back to bypass_missing) preserves backward compatibility cleanly. Any concerns?

Feedback and alternative ideas are welcome. This should be a fairly self-contained change (schema, access logic, tests, docs), so it could also be a good first contribution if anyone in the community wants to pick it up.

[mueckl]

@Baoyuantop Thank you for the professional rework of my feature request.

Here's my opinion to the open questions:

• naming : bypass_malformed is my favorite. It fits well with the existing naming convention
• default strategy: Backward compatibility should be maintained, which is ensured by your proposal

[Baoyuantop]

We welcome code contributions for this feature, and we will assist with the code review.