Documentation

To write your first Route, we need a Rewrite Rule. Let’s start with a simple one:

A Rewrite Rule requires the directive RewriteRule followed by a pattern ^/tribestream$ to match the incoming request URL, a substitution https://tribestream.io to rewrite the request if matched, and finally one or more flags in square brackets [P, NE] to modify the behavior. The ^ and $ characters delimit the beginning and the end of the pattern to be matched.

Assuming that TAG is running in http://localhost:8080, this rule will match all the incoming requests to TAG to the URL http://localhost:8080/tribestream and Proxy to the substitute address https://tribestream.io due to the [P] flag.

A Route can have multiple Rewrite Rules and TAG can hold multiple Routes. The order in which these Routes and Rules are defined is important since TAG evaluates the rule set in order until a pattern is matched and a behavior applied at runtime. If no corresponding rule is matched, the request will be performed against the TAG server itself.

Another important consideration about Routes and Rewrite Rules is that they fall through, meaning that all rules of all routes are evaluated until a termination flag is found and the engine stop processing the rule set. Termination flags are behaviors that require the request to be handled immediately, like [P] when we want to Proxy, [R] if we want to Redirect or [F] if we want to Forbid the resource.

Also, once a substitution has occurred, the rules that follow are matched against the substituted value.

Consider the following Route:

Requests coming in as simple -http://localhost:8080/tribestream will ignore the first rule and of course match the second rule and also proxy the request to https://tribestream.io.

The pattern portion of a Rewrite Rule is a Perl compatible regular expression. With that in mind, we can enhance the power of the rules we write:

This rule matches any pattern and proxy the request to https://tribestream.io.

Some hints on the syntax of regular expressions:

This is no way a complete representation of the regular expression vocabulary but should be enough to cover the most common cases. Is not this document goal to provide a comprehensive detailed reference to regular expressions. We recommend to check the following resources for additional information:

A Back-reference allows you to capture values in the RewriteRule pattern to use later on the substitution part in the form of $1, $2 until $n. Back-references are created whenever you use parentheses in the pattern expression.

This rule will match any address that starts with /my-api and will capture the rest of the address in the back-reference $1 to use in the substitution address after http://my-api.biz.

So assuming that a request is sent to TAG to the URL http://localhost:8080/my-api/my-service then the resulting proxy call will be executed at the address http://my-api.biz/my-service.

The behavior of a Rewrite Rule can be modified by applying one or more flags at the end of the rule. One of the most common use cases in the TAG is to Proxy an incoming request to another resource using the [P] flag:

You can forbid access to a resource with the [F] forbidden flag:

You can force a 410 - Gone status to a resource with the [G] gone flag:

You can Redirect to another resource with the [R] redirect flag:

Ignore case when matching pattern with the [NC] flag:

TAG implements when possible the same behavior of each flag as documented in Apache Rewrite Flags. There are some exceptions. Please check the differences here.