Trickster Documentation

Collapsed Forwarding is a feature used to prevent multiple simultaneous requests for the same object from overwhelming an upstream origin during a cache miss or revalidation attempt. Instead of every user triggering a new request to the origin, Trickster ensures only a single request is performed for a specific object.

Trickster supports two modes:

1. Basic Collapsed Forwarding (Default): When a cache miss occurs, all subsequent requests for that same object are placed on a 'waitlist'. Once the first request successfully populates the cache, all waitlisted requests are served from the newly cached object.
2. Progressive Collapsed Forwarding (PCF): An improvement that eliminates the waitlist. It serves simultaneous requests concurrently while the object is still being downloaded from the origin (similar to 'read-while-write'). This minimizes Time to First Byte (TTFB) for popular objects, which is particularly beneficial for low-latency streaming like DASH or HLS video delivery.

A Rule consists of required parts to define what to inspect and where to go, and optional parts to refine the inspection.

Required Parts

• input_source: The part of the Request to inspect.
• input_type: The data type of the source.
• operation: The logic applied to the input.
• next_route: The Backend Name for the default route if no cases match. (Alternatively, use redirect_url to issue a 302).
• redirect_url: A fully-qualified URL for a 302 redirect in the default case. (Alternatively, use next_route).

Optional Parts

• input_key: Case-sensitive lookup key (required for header or param sources).
• input_encoding: Encoding to decode before the operation (e.g., base64).
• input_index: If > -1, the source is split and the value is extracted from this index.
• input-delimiter: The delimiter used for splitting when input_index is used (defaults to ' ').
• ingress_req_rewriter: Name of a rewriter to run before rule execution.
• egress_req_rewriter: Name of a rewriter to run after rule execution.
• nomatch_req_rewriter: Name of a rewriter to run after execution if no cases matched.
• max_rule_executions: Limit on rule chaining depth (default: 16). If exceeded, returns a 400 status code.

Trickster supports four CORS modes to control how Access-Control-* response headers are handled. When using preserve or merge modes, Trickster automatically includes the request's Origin header in the cache key to ensure origin-specific responses are not served to the wrong origin.

Note on Legacy Behavior: If no cors block is provided for a backend or path, Trickster defaults to setting Access-Control-Allow-Origin to * while leaving other CORS headers unchanged.

The listeners map defines how Trickster accepts incoming connections. Trickster automatically defines three default entries: default, metrics, and mgmt.

Backends are mapped to listeners using the listener_name field. If listener_name is omitted in a backend configuration, it defaults to the default listener.

Important Constraints:

• Backends cannot use the reserved mgmt or metrics listeners.
• A user-defined listener with no mapped backend will not start and will trigger a warning.
• A TLS port is only enabled if at least one backend mapped to that listener provides a valid frontend certificate and key in its tls section.
• If a listener's network settings (address/port) change during a reload, Trickster drains the old listener before starting the new one (default drain period is 30 seconds).

listeners:
  default:
    address: ""
    port: 8480
    tls_address: ""
    tls_port: 8483
    connections_limit: 0
    read_header_timeout: 10s
  private_api:
    protocol: http
    address: 127.0.0.1
    port: 9080

backends:
  default:
    listener_name: default
    provider: prometheus
    origin_url: http://prometheus:9090
  private:
    listener_name: private_api
    provider: reverseproxy
    origin_url: http://private-origin

The Time Series Merge mechanism is used for High Availability (HA) or Federation of time series data.

High Availability (HA)

Set the replica_group option to the same value on physical backends that are HA replicas of the same logical shard. TSM will coalesce these replicas, using the configured pool order to resolve overlapping points and using later replicas to fill gaps.

Federation

For non-overlapping data, Trickster automatically selects a merge strategy per query by inspecting the outermost PromQL aggregation operator (e.g., sum, avg, max).

Key Rules:

• Replica Grouping: If replica_group is omitted, it defaults to the backend name. Explicitly set it for HA pools using non-idempotent aggregations like sum, count, or avg to prevent double-counting.
• Boundary: When a TSM pool member is itself an ALB, set replica_group on that nested ALB. Trickster uses the wrapper as the replica-group boundary.
• Fallback: For request paths that are not mergeable, TSM dispatches the request directly to the first live pool target.
• Injected Labels: Labels used for routing/metadata are automatically stripped before merging to ensure series from different backends hash identically.

backends:
  prom01a:
    provider: prometheus
    replica_group: prom01
    origin_url: http://prom01a.example.com:9090

  prom01b:
    provider: prometheus
    replica_group: prom01
    origin_url: http://prom01b.example.com:9090

  prom-alb-01:
    provider: alb
    alb:
      mechanism: tsm
      pool:
        - prom01a
        - prom01b

Trickster accelerates ClickHouse queries that return time series data (typically used in dashboards) by using the Time Series Delta Proxy Cache. This mechanism minimizes the number and time range of queries sent to the upstream ClickHouse server by caching time series results and normalizing time ranges.

Supported Clients

• Grafana: Tested with the ClickHouse DataSource Plugin for Grafana (v1.9.3) using the $timeSeries macro.
• Go SDK: Supports clickhouse-go/v2.
  • HTTP Protocol: Queries made via clickhouse.OpenDB are proxied and cached.
  • Native Binary Protocol: Supported via transparent proxying (OPC).

Cacheable Query Requirements

To be cacheable as a time series, the first column expression in the main or any subquery must follow one of these two formats to allow Trickster to derive the timestamp column and the step size:

#### Grafana Plugin Format 
```sql
SELECT intDiv(toUInt32(time_col, 60) * 60) [* 1000] [as] [alias]

ClickHouse Time Grouping Function

SELECT toStartOf[Period](time_col) [as] [alias]