Directives

How it works

Parsing pipeline. For every HTTP request eRPC runs three steps. First, ApplyDirectiveDefaults copies any directiveDefaults config block into the request struct (lowest priority). Second, SetAllowClientDirectiveMatcher stores a pre-compiled matcher function from the project-level allowClientDirectives pattern (compiled once at project registration via NewWildcardMatcher). Third, EnrichFromHttp scans all registered header and query names, skipping any directive whose query-param key is rejected by the matcher. If no directives are present it returns immediately after extracting User-Agent — zero allocations, zero locks. When directive inputs are present the struct is cloned before mutation so batch sub-requests that share the same pointer do not race.

Precedence from lowest to highest: directiveDefaults config → HTTP header → URL query parameter. A query-param value always wins over the same header, which always wins over config. ApplyDirectiveDefaults is idempotent — once r.directives is non-nil every subsequent call is a no-op, so per-request overrides can never be clobbered by a second config pass. Source: common/request.go:563-676 (opens in a new tab).

Boolean parsing rule. For every boolean directive header the only truthy value is the exact string "true" (case-insensitive, whitespace stripped). "1" and "yes" are not truthy. X-ERPC-Force-Trace is handled by the tracing subsystem separately and accepts all three. Always use "true" to avoid this asymmetry. Confirmed: common/request_test.go:406-427 (opens in a new tab).

directiveDefaults placement. Settable at projects[].networks[].directiveDefaults (per network) or projects[].networks[].failsafe.directiveDefaults (failsafe scope). Every *bool field has three states: nil (omitted — request field stays at Go zero false), pointer to false (explicitly written), pointer to true. The nil check in ApplyDirectiveDefaults is a "was this field set?" guard, not a multi-level inheritance chain.

gRPC path. EnrichFromHttp is never called on the gRPC path. gRPC callers receive only directiveDefaults; per-request header overrides are not available. Source: erpc/request_processor.go:35-67 (opens in a new tab).

Config schema

Config struct: common/config.go:2105-2152 (opens in a new tab). Applied by ApplyDirectiveDefaults at common/request.go:563-676 (opens in a new tab).

Complete directive registry

server.executionHeaders — response diagnostic header mode

Worked examples

All patterns below are distilled from real production fleets; comments explain the non-obvious choices.

1. Global network defaults: retryEmpty on, retryPending explicitly off. Production fleets set retryEmpty: true at networkDefaults so every network retries null/empty upstream responses (e.g., a not-yet-indexed block) without per-network config. retryPending: false is explicit because the struct's stale "true by default" comment causes confusion — production configs state it clearly:

networkDefaults:  directiveDefaults:    # Retry null/empty results globally — covers block-availability races    # on eth_getLogs, eth_getBlockByNumber, eth_getTransactionReceipt.    retryEmpty: true    # retryPending default is false despite stale struct comment;    # pin it explicitly so intent is clear to future maintainers.    retryPending: false

2. Non-standard chain: relax tagged-block enforcement. zkSync Era and similar ZK-rollups can legitimately return null for certain block tags, so they disable enforceNonNullTaggedBlocks per-network while inheriting all other defaults:

networks:  - evm:      chainId: 324  # zkSync Era mainnet    directiveDefaults:      # zkSync can return null for certain block tags — don't treat as error      enforceNonNullTaggedBlocks: false

3. Indexer workload — full receipt integrity. When backfilling a chain for an indexer you want to catch any upstream that sends partial or misordered receipts. Configure the network's integrity block so every call on that network is validated automatically, and keep the kept enforcement directives on at directiveDefaults:

directiveDefaults:  retryEmpty: true  # tx-receipt polling — only enable per-indexer-network, not globally  retryPending: true  enforceHighestBlock: true  enforceNonNullTaggedBlocks: true

4. Per-request upstream pinning. A dApp wants to read its own just-submitted transaction from the same upstream it used to broadcast, bypassing the normal load-balanced pool. Send the header at call time — no config change needed:

POST /1/main HTTP/1.1
X-ERPC-Use-Upstream: alchemy-mainnet
X-ERPC-Retry-Pending: true

The upstream selector supports wildcards and tags: "alchemy-*", "alchemy-mainnet|quicknode-*", "family:archival" (tag match), "!drpc" (exclude one by ID).

5. Per-call cache bypass for fresh data. A price-feed service needs uncached eth_call results on every tick. Send X-ERPC-Skip-Cache-Read: true per request; write-back still fires so the next caller gets the fresh value from cache:

POST /1/main HTTP/1.1
X-ERPC-Skip-Cache-Read: true

To bypass only the in-memory tier and keep Redis warm reads: X-ERPC-Skip-Cache-Read: memory*.

6. Skipping consensus for internal tooling. A monitoring script wants low-latency reads and trusts a single upstream. Bypass the consensus quorum for that call:

POST /1/main HTTP/1.1
X-ERPC-Skip-Consensus: true

Retry, hedge, circuit-breaker, and timeout still apply — only the dispute/agreement step is skipped.

Request/response behavior

Request headers — canonical truthy value. Every boolean directive header requires "true" (any case, optional surrounding whitespace). "1" and "yes" evaluate to false and silently have no effect. Exception: X-ERPC-Force-Trace (tracing subsystem, not a directive) accepts "true", "1", or "yes". Always use "true".

Directive-adjacent request inputs (not in the directive registry):

Response headers always emitted (every HTTP response, not controlled by executionHeaders):

Execution diagnostic headers (controlled by server.executionHeaders; single responses get the per-response set, batch responses get ONE aggregated set — counters summed across sub-calls, X-ERPC-Duration = slowest sub-call, no X-ERPC-Upstream):

Example X-ERPC-Upstreams value: alchemy=primary:success:50ms:won;quicknode=hedge:timeout:5000ms;drpc=consensus_slot:exec_revert:20ms.

reason precedence when several apply to one attempt: consensus_slot > hedge > sweep > retry > primary — the outermost fan-out cause wins, so an attempt that hedged or retried inside a consensus participant slot still reads consensus_slot (the attempt record's IsHedge/IsRetry fields preserve the inner mechanics).

Cost / billing headers (opt-in via server.costHeaders: true; emitted on single AND batch responses; omitted on early errors that never routed a call):

Example: X-ERPC-Calls: 5 · X-ERPC-Billable: 4 · X-ERPC-Cache: PARTIAL:2 · X-ERPC-Credits: alchemy:eth_call=52;quicknode:eth_getLogs=40 · X-ERPC-Credits-Total: 92.

Cost-header gotchas: emitted only for routed requests — early parse/auth errors get none (there is no routed call to account for). Pricing is the vendor's logic (common.CreditUnitsProvider.CreditUnits(req, upstreamCfg); nothing is hard-coded in the eRPC layer). A timed-out attempt still accrues credits — it dialed the vendor — while skipped/breaker_open attempts provably never left the process and cost 0. Vendors without pricing cost a flat 1 credit per request unless opted out (creditUnits: {"*": 0}). Source: writeCostHeaders in erpc/http_server.go (opens in a new tab), attemptCreditUnits in upstream/upstream.go (opens in a new tab), tests in erpc/http_server_cost_test.go (opens in a new tab) and upstream/credit_units_test.go (opens in a new tab).

Error shapes produced by directive checks. Failed validation directives return ErrEndpointContentValidation. A UseUpstream selector that matches no upstream returns ErrUpstreamsExhausted (wrapping ErrUpstreamNotAllowed per candidate) — there is no distinct "selector matched nothing" error code.

Best practices

• Start with enforceHighestBlock: true — it is on by default and catches the most common upstream data-quality issues with negligible overhead.
• Raise the network's integrity level only for indexing workloads — higher levels (e.g. bloom recomputation, log-field checks) are CPU-intensive and penalize latency for general-purpose proxy traffic. Use X-ERPC-Integrity to opt a single request into a higher level.
• Use retryEmpty: true for block-polling calls but verify EmptyResultMaxAttempts is set appropriately; unbounded retries on a degraded upstream can exhaust the timeout budget.
• Never set retryPending: true globally — it converts every pending-tx lookup into a polling loop. Pin it per request (X-ERPC-Retry-Pending: true) or to a dedicated network for transaction-tracking flows.
• Pin useUpstream at config via directiveDefaults for known-good archival nodes rather than relying on callers to send the header — this prevents a misconfigured client from silently routing archival calls to full nodes.
• Always send "true", never "1" or "yes", for X-ERPC-* boolean directive headers.
• On gRPC, per-request overrides are not available. Wire all desired defaults into directiveDefaults in config; EnrichFromHttp is never called on the gRPC path.
• Lock down client directives on public-facing projects with allowClientDirectives: "!skip-cache-read & !use-upstream" to prevent clients from bypassing your cache or pinning to specific upstreams while still allowing integrity directives.

Edge cases & gotchas

1. RetryPending default is false, not true. The struct comment at common/request.go:125 ("true by default") is stale. No SetDefaults entry exists. Must be explicitly enabled via directiveDefaults.retryPending: true or X-ERPC-Retry-Pending: true.
2. X-ERPC-Use-Upstream header is NOT trimmed; query IS. A header with leading/trailing spaces will not match any upstream. Source: common/request.go:741 (opens in a new tab) vs :812 (opens in a new tab).
3. "1" and "yes" are NOT truthy for directive headers. Only "true" (any case). This differs from X-ERPC-Force-Trace. Source: common/request_test.go:406-427 (opens in a new tab).
4. UseUpstream failure produces ErrUpstreamsExhausted, not a selector-specific error. Operators must parse the error message text to diagnose selector mismatches. Source: common/errors.go:1432-1440 (opens in a new tab).
5. X-ERPC-Skip-Consensus: false actively disables consensus bypass. Sending the header with the value "false" is NOT the same as omitting the header. A header value "false" parses to false and overrides a directiveDefaults.skipConsensus: true config entry — the consensus branch then runs normally. Omitting the header leaves SkipConsensus at its config-default value. Tested: common/request_test.go:409 (opens in a new tab), erpc/skip_consensus_directive_test.go:125-153 (opens in a new tab).
6. EnforceGetLogsBlockRange cannot be overridden per-request via HTTP. SetDefaults copies DirectiveDefaults values into Evm.Integrity; the architecture layer reads from the network config struct, not the per-request directive. Source: common/defaults.go:1957-1964 (opens in a new tab).
7. Batch responses emit ONE aggregated X-ERPC-* header set. Counters sum across sub-calls, X-ERPC-Cache becomes PARTIAL:<n> when mixed, X-ERPC-Duration is the slowest sub-call, the trace caps at 50 segments (X-ERPC-Upstreams-Truncated carries the overflow count), and the single-winner X-ERPC-Upstream is not emitted. Per-sub-call attribution still needs the per-response id fields in the body.
8. executionHeaders: summary removes only X-ERPC-Upstreams. All counter and metadata headers still emit. Use "off" to suppress everything.
9. Selector-scoped served-tip partitions are capped. Beyond maxServedTipPartitions per network, no partition is created and the stateless fallback is used silently — no error. Source: erpc/networks.go:429 (opens in a new tab).
10. nil *bool in DirectiveDefaultsConfig ≠ false *bool. Nil means "not set — skip"; a *false pointer means "explicitly disable". Only non-nil pointers are applied in ApplyDirectiveDefaults. Source: common/request.go:570-580 (opens in a new tab).
11. allowClientDirectives filters HTTP-supplied directives only. Config-set directiveDefaults always apply regardless of the filter. The pattern is pre-compiled at project registration via NewWildcardMatcher and evaluated against each directive's query-param key (e.g. skip-cache-read, use-upstream). nil = all allowed; "" = none allowed; "!skip-cache-read & !use-upstream" = all except those two. Does not filter X-ERPC-Force-Trace (processed before project resolution). Source: isDirectiveAllowed method on NormalizedRequest in common/request.go, NewWildcardMatcher in common/matcher.go, AllowClientDirectives in common/config.go. See projects config.

Observability

Directives have no dedicated Prometheus metrics; their effects appear in existing counters.

Trace / log. X-ERPC-Force-Trace: true (or force-trace query param) forces OTel sampler to record the span regardless of sampling rate (attribute erpc.force_trace = true). Source: common/tracing_util.go:89-100 (opens in a new tab). Request.Lock / Request.RLock detail spans are emitted inside directive mutations (common/request.go:924-934 (opens in a new tab)). At trace level, applied request directives is logged with Interface("directives", ...) after every EnrichFromHttp call. Source: erpc/http_server.go:659 (opens in a new tab).

Source code entry points

• common/request.go:116-215 (opens in a new tab) — RequestDirectives struct: all directive fields + library-only fields
• common/request.go:563-676 (opens in a new tab) — ApplyDirectiveDefaults: idempotency guard, nil-check per *bool field, copy-from-config
• common/request.go:702-893 (opens in a new tab) — EnrichFromHttp: fast-path scan, clone-on-write, all header + query parsers
• common/config.go:2105-2175 (opens in a new tab) — DirectiveDefaultsConfig struct; skipCacheRead custom YAML/JSON unmarshal
• common/defaults.go:1454-1471 (opens in a new tab) — DirectiveDefaultsConfig.SetDefaults: three true defaults (enforceHighestBlock, enforceGetLogsBlockRange, enforceNonNullTaggedBlocks)
• erpc/http_server.go:1081-1272 (opens in a new tab) — executionHeadersMode, setResponseHeaders, writeCounterHeaders, writeResponseMetadataHeaders, writeUpstreamTraceHeaders
• erpc/network_executor.go:179-188 (opens in a new tab) — SkipConsensus branch
• erpc/network_executor.go:374-462 (opens in a new tab) — shouldRetryWithReason: RetryEmpty / RetryPending checks and EmptyResultMaxAttempts cap
• erpc/networks.go:374-441 (opens in a new tab) — selector-scoped served-tip: requestSelector, servedTipPartitionFor, partition cap
• upstream/upstream.go:1505-1548 (opens in a new tab) — shouldSkip: UseUpstream selector check via UpstreamMatchesSelector
• common/matcher.go:34-112 (opens in a new tab) — WildcardMatch, MatchesSelector, UpstreamMatchesSelector
• erpc/skip_consensus_directive_test.go (opens in a new tab) — end-to-end SkipConsensus tests
• common/request_test.go:391-541 (opens in a new tab) — unit tests for boolean parse rules, header/query precedence, ValidateTransactionsRoot override

Related pages

• Auth — credential headers (X-ERPC-Secret-Token, Authorization, X-Siwe-*) parsed separately before directives.
• Rate limiters — caps total request volume; important when retryEmpty/retryPending loops could multiply upstream calls.
• Consensus — the branch that skipConsensus bypasses.
• Selection policies — controls which upstreams are eligible before useUpstream further restricts the set.
• Matcher syntax — the WildcardMatch grammar used by useUpstream and skipCacheRead patterns.
• Survive provider outages — a use case that combines retryEmpty, enforceHighestBlock, and useUpstream.