Hostgrid Rules

Rules allow you to customize how requests and responses are handled as traffic passes through Hostgrid.

A rule is made up of conditions that determine when it should run, and actions that define what should happen when those conditions are met.

Rules are evaluated for every incoming request, making them a flexible way to control routing, modify requests or responses, and implement custom behavior without changing your upstream application.

You can think of a rule as an if–then statement:

If a request matches certain conditions, then perform one or more actions.

For example:

• If the request path begins with /blog/, rewrite the request before forwarding it.
• If the request contains a specific header, add additional request headers.
• If the request matches a maintenance path, return a static response without contacting the upstream.

Rules allow you to customize traffic handling without deploying changes to your application.

Every rule consists of two parts:

• Matchers — define when a rule should run.
• Handlers — define what happens when the rule matches.

When a request reaches Hostgrid:

1. The request arrives on the custom domain.
2. Hostgrid evaluates rules in their configured order.
3. Every matching rule is executed.
4. Each matching rule runs its handlers in order.
5. The request is forwarded to the upstream unless a handler returns a response directly.

Unlike traditional firewall-style rule systems, Hostgrid does not stop after the first matching rule.

Multiple rules can match the same request and all of them will execute sequentially.

Rules are evaluated from top to bottom.

Rules positioned earlier in the list execute before rules below them.

For example:

1. Add Authentication Header
2. Remove Authentication Header for Public API
3. Add Response Headers

A request to:

/api/public/status

would execute:

1. Add Authentication Header
2. Remove Authentication Header
3. Add Response Headers

Because all matching rules execute, later rules can modify changes made by earlier rules.

Carefully consider rule ordering when multiple rules affect the same request.

Matchers determine whether a rule applies to an incoming request.

A rule can contain one or more matchers.

Supported matcher types include:

Path, Header and Query matchers support comparison the following operators:

• is equal to
• is not equal to
• begins with
• ends with
• contains
• does not contain
• unknown (always match)

When multiple matchers are added to the same rule, they use AND logic.

Every matcher must evaluate to true before the rule executes.

For example:

Matcher 1

Path begins with /premium/

Matcher 2

Header:
Premium-User = true

Only requests that satisfy both conditions will match the rule.

Below is an example of the a sample rule config in the UI:

Handlers define the actions that occur when a rule matches. A single rule can contain multiple handlers.

Handlers execute in the order they are configured.

Available handlers include:

For example, a rule could:

1. Rewrite the request path.
2. Add a request header.
3. Add security headers to the response.

All three handlers execute in sequence.

Rules can be configured at two different levels.

Upstream rules belong to an upstream.

They apply to every domain connected to that upstream.

This is useful for behavior that should remain consistent across all customer domains.

Examples include:

• Adding security headers
• Authentication headers
• Global URL rewrites

Domain rules belong to an individual custom domain.

They only affect requests for that specific domain.

Examples include:

• Customer-specific redirects
• Custom maintenance pages
• Domain-specific response headers

If both upstream and domain rules exist, Hostgrid evaluates them in the following order:

Incoming Request
        │
        ▼
Upstream Rules
        │
        ▼
Domain Rules
        │
        ▼
Forward Request to Upstream

This allows global behavior to be defined once while still supporting per-domain customization.

Rules can be created from either an upstream or a domain.

1. Open your Upstream or Domain.
2. Select the Rules tab.
3. Click Create Rule.
4. Enter a descriptive name.
5. Configure one or more matchers.
6. Add one or more handlers.
7. Save the rule.

New rules are added to the bottom of the list by default.

You can change execution order by dragging rules into a different position.

Earlier rules execute before later rules.

Rules can be used for many common scenarios, including:

• Redirecting old URLs
• Serving custom maintenance pages
• Rewriting application routes
• Adding security headers
• Injecting request headers
• Modifying upstream responses
• Returning static content for specific routes
• Creating customer-specific routing behavior

Because rules are evaluated before requests reach your application, many routing and customization tasks can be implemented without changing application code.

Each rule has an enabled or disabled state.

Disabled rules remain in your configuration but are skipped during request processing.

This makes it easy to temporarily disable behavior without deleting the rule.

• Use descriptive rule names.
• Keep related rules together.
• Remember that multiple matching rules execute.
• Consider the cumulative effect of handlers.
• Place more specific rules before broader ones when ordering matters.
• Use the Static Response handler when a request should terminate immediately.
• Test changes after modifying rule order.