fix(ws): skip gzip ResponseWriter wrap on WebSocket upgrades

.dockerignore

@@ -1,11 +1,16 @@
 # Version control
 .git
 .gitignore
+.claude/
+.cursor/
+.github/
+.vscode/
 
 # Build artifacts
 bin/
 dist/
 build/
+temp/
 *.exe
 *.dll
 *.so

.github/workflows/test.yml

@@ -16,7 +16,7 @@ permissions:
 jobs:
   units:
     runs-on: "${{ github.repository_owner == 'erpc' && 'blacksmith-8vcpu-ubuntu-2404' || 'ubuntu-24.04' }}"
-    timeout-minutes: 20
+    timeout-minutes: 30
     steps:
       - name: Harden the runner (Audit all outbound calls)
         uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2

.github/workflows/xray.yml

@@ -0,0 +1,58 @@
+name: xray
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review]
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  xray-on-pr:
+    if: github.event_name == 'pull_request' && github.event.pull_request.draft == false && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
+        with:
+          egress-policy: audit
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+        with:
+          fetch-depth: 0
+      - uses: xray-pr/xray-pr@489e56199b92f696dbc3757964dffd2503ec68e2 # v0.2.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          openrouter_api_key: ${{ secrets.OPENROUTER_API_KEY }}
+          languages: go
+
+  xray-on-command:
+    if: |
+      github.event_name == 'issue_comment' &&
+      github.event.issue.pull_request &&
+      contains(fromJSON('["OWNER", "MEMBER"]'), github.event.comment.author_association) &&
+      contains(github.event.comment.body, '/xray')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
+        with:
+          egress-policy: audit
+      - name: Get PR head SHA
+        id: pr-info
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          SHA=$(gh api repos/${{ github.repository }}/pulls/${{ github.event.issue.number }} --jq '.head.sha')
+          echo "sha=$SHA" >> $GITHUB_OUTPUT
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
+        with:
+          ref: ${{ steps.pr-info.outputs.sha }}
+          fetch-depth: 0
+      - uses: xray-pr/xray-pr@489e56199b92f696dbc3757964dffd2503ec68e2 # v0.2.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          openrouter_api_key: ${{ secrets.OPENROUTER_API_KEY }}
+          languages: go

.maestrorc.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://maestro.goldsky.com/maestrorc/schema",
+  "agent": {
+    "model": "opus",
+    "effort": "high"
+  },
+  "planning": {
+    "enabled": true
+  },
+  "security": {
+    "trusted_author_associations": ["OWNER", "MEMBER", "COLLABORATOR"]
+  },
+  "sandbox": {
+    "setup_commands": {
+      "post_clone": [
+        "GO_VERSION=$(grep -m1 '^toolchain go' go.mod | sed 's/.*go//'); GO_VERSION=${GO_VERSION:-$(grep -m1 '^go [0-9]' go.mod | awk '{print $2}')}; echo \"Installing Go ${GO_VERSION} from go.mod\" && curl -fsSL \"https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz\" | tar -C /usr/local -xz && ln -sf /usr/local/go/bin/go /usr/local/bin/go && ln -sf /usr/local/go/bin/gofmt /usr/local/bin/gofmt",
+        "PNPM_VERSION=$(jq -r .packageManager package.json | cut -d@ -f2); echo \"Activating pnpm ${PNPM_VERSION} from package.json packageManager\" && corepack enable && corepack prepare \"pnpm@${PNPM_VERSION}\" --activate",
+        "go mod download",
+        "pnpm install --frozen-lockfile --ignore-scripts"
+      ]
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1,49 @@
+# AGENTS.md — eRPC
+
+Pointer file for cross-tool AI coding agents (Maestro, Codex, Cursor,
+Claude Code). The canonical project rules live in
+[`.cursor/rules/erpc.md`](.cursor/rules/erpc.md) — read that file first;
+it applies to all agents, not just Cursor.
+
+This file only repeats the bare minimum needed to bootstrap.
+
+## Project
+
+- **eRPC** — fault-tolerant EVM RPC proxy with re-org-aware permanent caching.
+- Go server (`cmd/erpc`) + TypeScript packages under `typescript/` (`@erpc-cloud/config`, `@erpc-cloud/cli`).
+- Module: `github.com/erpc/erpc`. Docs: <https://docs.erpc.cloud/>.
+
+## Bootstrap commands
+
+```bash
+make setup           # go mod tidy
+pnpm install --ignore-scripts   # JS workspace (skip postinstall, matches CI)
+
+make fmt             # format Go (also Biome for TS via pnpm)
+make build           # build the eRPC server
+make test-fast       # parallel-sharded unit tests (daily-driver)
+make test            # full suite with -race (slow, run before merge / CI runs this)
+make test-race       # race detector on a slimmer scope
+```
+
+Single test: `LOG_LEVEL=trace go test -run <pattern> ./...`
+
+## PR expectations
+
+- One logical change per PR.
+- `make fmt` clean.
+- `make test-fast` green locally; `make test` (race) green in CI.
+- Brief test plan in the description.
+
+## Hard rules from `.cursor/rules/erpc.md`
+
+These bite hard if missed; read the cursor rules for the full version:
+
+- **Test logger init:** every test file that logs must include
+  `func init() { util.ConfigureTestLogger() }`.
+- **Gock setup order:** set up *all* gock mocks **before** initializing any
+  network components. Always `util.ResetGock()` + `defer util.ResetGock()`.
+- **Logging:** zerolog only (`log.Logger` from `github.com/rs/zerolog/log`).
+- **Errors:** wrap with context (`fmt.Errorf("...: %w", err)`).
+- **Don't** change the public `erpc.yaml` schema without version markers + docs.
+- **Don't** disable failing tests — fix the root cause or surface it in the PR.

Makefile

@@ -4,13 +4,14 @@ help:
 	@echo "Usage: make [command]"
 	@echo
 	@echo "Commands:"
-	@echo " build                         Build the eRPC server"
+	@echo " build                         Build the eRPC server + simulator"
 	@echo " fmt                           Format source code"
 	@echo " test                          Run unit tests"
 	@echo
 	@echo " run-k6                        Run k6 tests"
 	@echo " run-pprof                     Run the eRPC server with pprof"
 	@echo " run-fake-rpcs                 Run fake RPCs"
+	@echo " run-simulator                 Run the eRPC traffic simulator (http://127.0.0.1:8080)"
 	@echo " up                            Up docker services"
 	@echo " down                          Down docker services"
 	@echo " fmt                           Format source code"
@@ -45,6 +46,11 @@ run-k6-evm-historical-randomized:
 build:
 	@CGO_ENABLED=0 go build -ldflags="-w -s" -o ./bin/erpc-server ./cmd/erpc/main.go
 	@CGO_ENABLED=0 go build -ldflags="-w -s" -tags pprof -o ./bin/erpc-server-pprof ./cmd/erpc/*.go
+	@CGO_ENABLED=0 go build -ldflags="-w -s" -o ./bin/erpc-simulator ./cmd/erpc-simulator
+
+.PHONY: run-simulator
+run-simulator:
+	@go run ./cmd/erpc-simulator
 
 .PHONY: test
 test:

README.md

@@ -77,6 +77,36 @@ This setup is ideal for development and testing purposes. For production environ
 
 ---
 
+### CLI Commands
+
+eRPC provides several CLI commands beyond the default server start:
+
+#### `erpc validate <config-file>`
+
+Validate a configuration file (TS, JS, or YAML) and report any errors, warnings, or notices. Useful in CI pipelines to catch misconfigurations before deployment.
+
+```bash
+erpc validate erpc.yaml
+erpc validate erpc.ts
+```
+
+#### `erpc dump <config-file>`
+
+Parse a configuration file and output the fully resolved configuration with all eRPC defaults applied. Supports YAML and JSON output. This is useful for inspecting what your final config looks like after eRPC fills in all default values (retry policies, timeouts, selection policies, etc.).
+
+```bash
+# Output as YAML (default)
+erpc dump erpc.yaml
+
+# Output as JSON
+erpc dump --format json erpc.ts
+
+# Compare two configs (e.g. before/after a migration)
+diff <(erpc dump old-config.yaml) <(erpc dump new-config.yaml)
+```
+
+---
+
 ### Local Development
 
 1. **Clone this repository:**

architecture/evm/block_ref.go

@@ -75,10 +75,10 @@ func ExtractBlockReferenceFromRequest(ctx context.Context, r *common.NormalizedR
 				// In case of "*" since it means any block, we can still augment it from response ref, because during cache.Get()
 				// we'll be using reverse index (i.e. ignoring ref), but after reorg invalidation is added a specific block ref is useful.
 				//
-				// TODO An ideal version stores the data for all eth_getBlockByNumber(latest) and eth_getBlockByNumber(blockNumber),
-				// and eth_getBlockByNumber(blockHash) where blockNumber/blockHash are the actual values returned in the response.
-				// So that if user gets the latest block, then cache is populated for when they provide that specific block as well.
-				// When implementing that feature remember that CacheHash() must be calculated separately for each number/hash combo.
+				// For moving-tag requests ("latest", "finalized", "safe"), the
+				// cache layer calls ResolveCacheBlockRef instead, which resolves
+				// the tag to a concrete block number so each tip advance gets
+				// its own cache key.
 				blockRef = br
 			}
 			if bn > 0 {
@@ -114,6 +114,93 @@ func ExtractBlockReferenceFromRequest(ctx context.Context, r *common.NormalizedR
 	return blockRef, blockNumber, nil
 }
 
+// ResolveCacheBlockRef returns the block reference the cache layer should use
+// when keying an eth_getBlockByNumber("latest") response (and other moving
+// tags). Regular ExtractBlockReferenceFromRequest preserves the literal tag
+// string ("latest") as blockRef so the cache hits on repeat tag queries —
+// but that makes every request within the TTL window return the same pinned
+// response regardless of chain progression (see the bug fixed alongside this
+// helper: stale "latest" responses served from cache until TTL expiry, with
+// enforceHighestBlock explicitly skipping cached responses).
+//
+// This helper substitutes the tag with a concrete block number so each tip
+// advance is a distinct cache key: on WRITE we use the response's own block
+// number (definitive answer for what the cached payload represents); on READ
+// we consult the network's tip tracker (EvmHighestLatestBlockNumber, which
+// aggregates max over upstream pollers and the cross-pod shared counter) to
+// decide which block we'd be asking for *right now*. Within a single tip
+// the key is stable and concurrent "latest" queries coalesce onto one cached
+// entry; across tip advances the key changes and the next request forwards
+// upstream.
+//
+// The function does NOT mutate the request's EvmBlockRef — the original
+// "latest" tag is preserved on the request so downstream finality computation
+// and other tag-aware logic keeps working.
+//
+// Fallback: if the tag can't be resolved to a concrete block number (no
+// response, no network attached to the request, or the tracker hasn't seen
+// a block yet), the original tag is returned and the cache key stays
+// tag-literal — same as prior behaviour. That path should be rare in
+// production since every normal HTTP request has a Network and an upstream
+// response by the SET stage.
+func ResolveCacheBlockRef(ctx context.Context, req *common.NormalizedRequest, resp *common.NormalizedResponse) (string, int64, error) {
+	blockRef, blockNumber, err := ExtractBlockReferenceFromRequest(ctx, req)
+	if err != nil {
+		return blockRef, blockNumber, err
+	}
+
+	// Only rewrite moving tip-bound tags. Numeric refs, block-hash refs, "*",
+	// and slower-moving tags like "earliest" are already correct.
+	if blockRef != "latest" && blockRef != "finalized" && blockRef != "safe" {
+		return blockRef, blockNumber, nil
+	}
+
+	// WRITE path: prefer the response's own block number, which is the
+	// definitive answer for what payload we're about to cache.
+	if resp != nil {
+		if _, respBN, rerr := ExtractBlockReferenceFromResponse(ctx, resp); rerr == nil && respBN > 0 {
+			hex, herr := common.NormalizeHex(respBN)
+			if herr == nil {
+				return hex, respBN, nil
+			}
+		}
+	}
+
+	// READ path (and WRITE fallback): consult the network's aggregated view
+	// of the tag's current value. Guarded against panics because this helper
+	// is purely an optimization — if the network state isn't reachable for
+	// any reason (partially-constructed Network in a test, nil upstream
+	// registry, transient initialization race), we fall back to the tag-
+	// literal blockRef and retain the previous behaviour rather than
+	// aborting a live cache operation.
+	net := req.Network()
+	if net == nil {
+		return blockRef, blockNumber, nil
+	}
+	var num int64
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				num = 0
+			}
+		}()
+		switch blockRef {
+		case "latest":
+			num = net.EvmHighestLatestBlockNumber(ctx)
+		case "finalized", "safe":
+			num = net.EvmHighestFinalizedBlockNumber(ctx)
+		}
+	}()
+	if num > 0 {
+		hex, herr := common.NormalizeHex(num)
+		if herr == nil {
+			return hex, num, nil
+		}
+	}
+
+	return blockRef, blockNumber, nil
+}
+
 func ExtractBlockReferenceFromResponse(ctx context.Context, r *common.NormalizedResponse) (string, int64, error) {
 	ctx, span := common.StartDetailSpan(ctx, "Evm.ExtractBlockReferenceFromResponse")
 	defer span.End()