Skip to main content

gtm-proxy

Purpose and Production Relevance​

gtm-proxy is the public edge service for Crimoo tracking and API routing. It terminates or participates in HTTPS handling, resolves dynamic certificates by SNI, routes dashboard API traffic to node-api, routes customer-domain API traffic to the management/fabric app, serves or proxies custom loader behavior, and publishes normal tracking events to Pub/Sub.

Production relevance: core production edge proxy.

Stack and Main Dependencies​

  • Java 21.
  • Spring Boot/WebFlux.
  • Netty HTTP and TLS primitives.
  • Google Pub/Sub.
  • Google Secret Manager.
  • Micrometer and Prometheus.
  • BouncyCastle for PEM/certificate handling.

Important files and folders:

  • gtm-proxy/src/main/java/com/crimoo/proxy/application
  • gtm-proxy/src/main/java/com/crimoo/proxy/domain
  • gtm-proxy/src/main/java/com/crimoo/proxy/infrastructure
  • gtm-proxy/pom.xml
  • gtm-proxy/Dockerfile
  • gtm-proxy/docker-compose.yml

Business Responsibilities​

gtm-proxy protects the customer-facing tracking path and decides what every incoming request means:

  • Reject direct IP and bot/scanner traffic.
  • Serve ACME challenges when required.
  • Route api.crimoo.com /api/* requests to node-api.
  • Route customer-domain /api/* requests to the management/fabric service.
  • Serve custom loader JavaScript or proxied GTM script when enabled.
  • Restore GA4 bypass paths and query parameters.
  • Detect preview/debug requests and proxy them synchronously.
  • Publish normal events asynchronously to Pub/Sub.
  • Refresh first-party cookies when needed.
  • Resolve SSL certificates dynamically by SNI.

Technical Architecture and Entry Points​

High-level routing:

The most important concept: normal tracking should be fast and asynchronous, but preview/debug needs direct synchronous behavior for GTM tooling.

Key Data Flows and Service Integrations​

Dashboard API Routing​

Requests to api.crimoo.com are forwarded to node-api. This is why Angular production points to https://api.crimoo.com even though the proxy is the public entry point.

Customer Tracking​

Customer-domain events are route-resolved by host/domain. For normal requests, the proxy publishes to Pub/Sub and returns 202 Accepted quickly.

Preview/Debug​

Preview requests are identified through preview headers, cookies, query params, internal request headers, or preview route type. They are proxied directly to the GTM container so the browser/debugger receives the real response.

Dynamic SSL​

For custom domains, SNI resolution fetches certificate data from node-api, parses PEM, builds a Netty SslContext, and caches it.

Rules:

  • Positive cert cache: about 1 hour.
  • Negative cache: short TTL for domains without certs.
  • Transient errors should not be cached as missing certificates.
  • Blocking certificate fetches must not run on Netty event-loop threads.

GA4 Bypass and Custom Loader​

The proxy can serve obfuscated loader paths and restore obfuscated GA4 paths/queries. This helps first-party tracking avoid common blocking patterns.

Read:

Environment, Deploy, and Runtime Notes​

Common commands:

cd gtm-proxy
mvn test
mvn package
docker compose up --build

Important runtime dependencies:

  • node-api for route/config/certificate lookup and API forwarding.
  • gtm-fabric or management app for customer-domain /api/* behavior.
  • Pub/Sub topic for tagging events.
  • Certificate data persisted through node-api.

Debugging Checklist​

  • For 403 responses, check direct IP requests and CORS origin rules for api.crimoo.com.
  • For 404 responses, check route registry, host normalization, inactive/missing domain, and bot filtering.
  • For 503 responses, check inactive route, custom loader disabled, or unavailable backend.
  • For dashboard API failures, check api.crimoo.com host routing, upstream node-api URL, and CORS headers.
  • For missing events, check async publish result, Pub/Sub credentials/topic, and fabric subscription.
  • For preview failure, check preview indicators, route type, container port, and sync proxy target.
  • For SSL failures, check SNI host, certificate fetch endpoint, cache state, PEM parse errors, and reload endpoint.

Tests or Validation Commands​

cd gtm-proxy
mvn test
mvn package

Manual smoke tests:

  • Request https://api.crimoo.com/api/auth/me and confirm it reaches node-api.
  • Send a normal /g/collect request and confirm 202.
  • Send a preview-marked request and confirm synchronous behavior.
  • Request a custom loader path for a GTM with custom loader enabled.
  • Force an SSL reload for a custom domain in a safe environment.

Mastery Checklist​

  • Given any host/path/header combination, predict the proxy route decision.
  • Explain why normal events publish async and why preview cannot.
  • Explain dynamic SNI certificate lookup and why thread isolation matters.
  • Debug CORS at the proxy layer without duplicating upstream headers.
  • Know how route cache, cert cache, and node-api config interact.