​
Template Expressions Overview

Template Expressions are a robust mechanism for accessing information related to requests, responses, and other key aspects of the router’s operation. They enable conditional feature activation and allow for extracting and configuring values dynamically. A common use case involves conditionally blocking mutations:

security:
  block_mutations:
    enabled: true
    condition: "request.header.Get('x-block-mutation') == 'yes'"

In this example, the condition is evaluated each time a request is made. Template Expressions provide access to request details, including headers, URLs, and query parameters. However, not all fields are consistently available throughout the request lifecycle. For instance, authentication data becomes accessible only after successful authentication.

During the build process, the router validates expressions. If an expression is invalid or does not return the expected type (such as a boolean or string), an error message is generated to ensure clarity and correctness.

​
Template Language

The expressions are based on the expr-lang template language. This language is characterized by its:

  • Safety – Expressions are evaluated securely.

  • Speed – The language is optimized for performance.

  • Side-effect-free operation – Expressions are read-only and do not alter state.

To modify configurations or manipulate requests and responses, implementing a custom module is recommended.

​
Naming Conventions

  • Fields: Use camelCase (e.g., request.auth.claims).

  • Methods: Use PascalCase (e.g., request.header.Get("Content-Type")).

  • Utility Functions: camelCase (e.g. trim) for the full list see here.

​
Expression Context

​
Request Object

The request object is a read-only entity that provides details about the incoming client request. It is accessible at all times during the lifecycle of the request.

Available Fields:

  • request.method

  • request.url.host

  • request.url.path

  • request.url.port

  • request.trace.sampled

  • request.error

​
Header Access:

  • request.header.Get('Content-Type') – Header retrieval is case-insensitive.

​
Example expressions

request.url.query.foo == 'bar' && request.Method = 'POST'
request.header.Get('x-block-mutation') == 'yes'

​
Body Object

The body object holds information related to the request body. However, if used in telemetry attribute expressions, it will be empty because the router hasn’t read the body at that stage of processing yet.

To optimize performance, the raw request body (raw.body) is only included in the expression context if at least one expression explicitly references it.

Available Fields:

  • request.body.raw

​
Example expressions

This example returns the raw body only when an error occurs, which is useful for debugging when used in access log expressions.

request.error != nil ? request.body.raw : ''

​
Authentication Object

The auth object contains authentication-related information for the request. It becomes available after authentication is complete.

Available Fields:

  • request.auth

  • request.auth.isAuthenticated

  • request.auth.type

  • request.auth.claims

  • request.auth.scopes

​
Example expressions

'read:miscellaneous' in request.auth.scopes
request.auth.isAuthenticated

​
Additional Notes

  • A Request for Comments (RFC) is open for feedback on the complete API specification. Future implementations will be driven by customer requirements.

  • The Expr language project offers a playground for testing and developing custom expressions, simplifying the process of constructing and validating expressions.

​
Where Can Template Expressions Be Used?

Template Expressions are not a generalized concept within router configuration. This functionality is selectively introduced in areas where it enhances the router’s capabilities. You find the supported configuration values on the router configuration documentation page.

If you find a need to enable dynamic configuration, please let us know. Your feedback helps guide future enhancements and feature development.

Was this page helpful?