How wundergraph/graphql-go-tools works
Project type and purpose
• This is an open-source GraphQL Router / API Gateway framework written in Go.
• It’s a modular library (not a monolithic application) that you use to parse, validate, normalize, plan, and execute GraphQL operations—supporting Federation, Subscriptions (WS & SSE), custom DataSources, and more.
• It ships two major engine versions (v1 in maintenance; v2 actively developed), an execution helpers module, examples (e.g. federation gateway), test apps, and CI/CD pipelines.
File-structure analysis
– Top-level modules:
• /v2: the core v2 GraphQL engine (lexer, parser, ast, normalization, validation, planning, resolve).
• /execution: helpers to wire engine into request handlers.
• /pkg: shared packages (ast, parser, visitor, codegen, federation, subscription, http handler, etc.) used by both v1 and v2.
• /testapps: small demo apps (chat, kafka_pubsub) showing integration.
• CI: .github/workflows, Makefile, Go workspace (go.work).
– Architectural patterns:
• Layered pipeline: lexical analysis → AST construction → AST transforms (merge, normalization) → validation → planning → execution.
• Strategy pattern for DataSources (static, HTTP JSON, GraphQL, pub/sub, WASM, NATS, Kafka).
• Modular federation support (SDL merge, entity stitching, gateway poller).
• HTTP server abstraction with middleware, WebSocket & SSE support.
• Separate “v2” module to allow major rewrites side by side with v1.
Insights from README
– Distinct packages expose clear responsibilities (ast, astparser, astprinter, astvalidation, astnormalization, engine/plan, engine/resolve, subscription, http, playground).
– Execution module builds on the engine to simplify request handling.
– Examples show a federation gateway pulling configurations, polling sources, serving over HTTP/WS.
– Emphasis on high-throughput, low-GC, pluggable DataSources, OpenTelemetry, Prometheus.
a. Main components:
1. Client Layer: HTTP/GraphQL clients (REST clients, playground UI, websockets).
2. HTTP Server & Transport:
– HTTP handler (/pkg/http)
– WebSocket / SSE handler (/pkg/subscription and /pkg/http/ws)
– Middleware (authentication, complexity, tracing)
3. GraphQL Request Pipeline:
– Lexer (lexer/)
– Parser (astparser/)
– AST (ast/)
– AST Transform & Merge (asttransform/, federation/sdlmerge/)
– AST Normalization (astnormalization/)
– AST Validation (astvalidation/)
4. Planner & Execution Engine:
– Plan builder (engine/plan/)
– Resolver & Executor (engine/resolve/)
– Execution helpers (execution/)
5. DataSources (engine/datasource, execution/datasource):
– REST, HTTP JSON, GraphQL upstream, static, NATS/Kafka, MQTT, WASM, pipeline
6. Federation Gateway (examples/federation):
– Metadata poller, schema merge, entity resolvers
7. External Systems:
– Upstream APIs, databases, message buses, S3 (config store)
8. Tooling & Examples:
– Example apps (testapps/)
– Playground UI (playground/)
9. Packaging & CI/CD:
– go.work, Makefile, GitHub Actions
b. Relationships & interactions:
• Client → HTTP Server → GraphQL Pipeline → Planner → Executor → DataSource → External systems → back to executor → response writer → Client.
• Middleware intercepts HTTP requests/responses for auth, tracing, metrics.
• Execution module configures engine with DataSource factories & field mappings.
c. Architectural patterns & principles:
• Pipeline (chain of responsibility) for AST transformation.
• Strategy pattern for pluggable DataSource implementations.
• Modular separation (packages for AST, planning, execution).
• Versioning via Go workspace (v1 vs v2 modules).
• Example-driven integration (federation example, testapps).
• CI/CD gating and release automation (.github/workflows).
d. Key technologies & libraries:
• Go modules & workspace (go.work).
• gqlgen used in examples for GraphQL server scaffolding.
• WebSocket & SSE protocols for subscriptions.
• xxhash for cache key generation.
• Prometheus & OpenTelemetry hooks (in Cosmo Router).
• WASM execution via wasm_datasource.