feat(demo): entity caching demo subgraphs, cache-demo runner, and test subgraphs

Extracted from jensneuse/entity-caching-v2 (PR #2777) — demo layer, stacked on
the composition+proto PR.

- cachegraph / cachegraph_ext / viewer: demo subgraphs exercising the caching
  directives (mutable data store, latency injector, auth profiles)
- cmd/cache-demo: standalone cache-only runner (ports 4012-4014)
- pkg/subgraphs/cachetest: the six deterministic subgraphs consumed by the
  router-tests entity_caching suite (articles, articlesmeta, details,
  inventory, items, viewer)
- graph-cache-only.yaml + config-cache-only.json + Makefile compose targets

Builds and tests green against the base router (no router changes required).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: 2 people

demo/Makefile

@@ -44,6 +44,9 @@ plugin-build-ci: plugin-build-ci-go-binary plugin-build-ci-bun-binary
 	cp -a pkg/subgraphs/projects/bin/* ../router/plugins/projects/bin/
 	cp -a pkg/subgraphs/courses/bin/* ../router/plugins/courses/bin/
 
+compose-cache:
+	$(wgc_router_ci) compose -i ./graph-cache-only.yaml -o ./config-cache-only.json
+
 standalone-compose:
 	$(wgc_router) compose -i ./graph-with-standalone.yaml -o ./configWithStandalone.json
 	pnpx prettier ./configWithStandalone.json -w
@@ -57,3 +60,11 @@ build-manifest:
 
 build-manifest-integration:
 	python3 build_manifest.py --router-config ./config.json --out ../router-tests/testenv/testdata/manifest --cleanup
+
+generate-cachetest:
+	cd pkg/subgraphs/cachetest/items && go run github.com/99designs/gqlgen generate
+	cd pkg/subgraphs/cachetest/details && go run github.com/99designs/gqlgen generate
+	cd pkg/subgraphs/cachetest/inventory && go run github.com/99designs/gqlgen generate
+	cd pkg/subgraphs/cachetest/viewer && go run github.com/99designs/gqlgen generate
+	cd pkg/subgraphs/cachetest/articles && go run github.com/99designs/gqlgen generate
+	cd pkg/subgraphs/cachetest/articlesmeta && go run github.com/99designs/gqlgen generate

demo/cmd/all/main.go

@@ -20,6 +20,9 @@ var (
 	mood                    = flag.Int("mood", 4008, "Port for mood subgraph")
 	countries               = flag.Int("countries", 4009, "Port for countries subgraph")
 	productsFeatureSubgraph = flag.Int("products_fg", 4010, "Port for products feature subgraph")
+	cacheGraph              = flag.Int("cachegraph", 4012, "Port for cachegraph subgraph")
+	cacheGraphExt           = flag.Int("cachegraph_ext", 4013, "Port for cachegraph-ext subgraph")
+	viewerSubgraph          = flag.Int("viewer", 4014, "Port for viewer subgraph")
 )
 
 func main() {
@@ -35,6 +38,9 @@ func main() {
 			Mood:         *mood,
 			Countries:    *countries,
 			ProductsFG:   *productsFeatureSubgraph,
+			CacheGraph:    *cacheGraph,
+			CacheGraphExt: *cacheGraphExt,
+			Viewer:        *viewerSubgraph,
 		},
 		EnableDebug: *debug,
 		GetPubSubName: func(name string) string {

demo/cmd/cache-demo/main.go

@@ -0,0 +1,55 @@
+// cache-demo runs only the cache-related subgraphs without requiring NATS.
+package main
+
+import (
+	"log"
+	"net/http"
+	"strconv"
+
+	"github.com/99designs/gqlgen/graphql"
+	"github.com/99designs/gqlgen/graphql/handler"
+	"github.com/99designs/gqlgen/graphql/handler/transport"
+	"github.com/99designs/gqlgen/graphql/playground"
+	"golang.org/x/sync/errgroup"
+
+	"github.com/wundergraph/cosmo/demo/pkg/injector"
+	"github.com/wundergraph/cosmo/demo/pkg/subgraphs/cachegraph"
+	"github.com/wundergraph/cosmo/demo/pkg/subgraphs/cachegraph_ext"
+	"github.com/wundergraph/cosmo/demo/pkg/subgraphs/viewer"
+)
+
+func main() {
+	servers := []*http.Server{
+		gqlServer("cachegraph", 4012, cachegraph.NewSchema()),
+		gqlServer("cachegraph-ext", 4013, cachegraph_ext.NewSchema()),
+		viewerServer(4014),
+	}
+
+	log.Println("Cache demo subgraphs starting (no NATS required):")
+	log.Println("  cachegraph:     http://localhost:4012/")
+	log.Println("  cachegraph-ext: http://localhost:4013/")
+	log.Println("  viewer:         http://localhost:4014/")
+
+	g := new(errgroup.Group)
+	for _, srv := range servers {
+		g.Go(srv.ListenAndServe)
+	}
+	log.Fatal(g.Wait())
+}
+
+func gqlServer(name string, port int, schema graphql.ExecutableSchema) *http.Server {
+	srv := handler.New(schema)
+	srv.AddTransport(transport.POST{})
+	srv.AddTransport(transport.GET{})
+	mux := http.NewServeMux()
+	mux.Handle("/", playground.Handler(name, "/graphql"))
+	mux.Handle("/graphql", srv)
+	return &http.Server{Addr: ":" + strconv.Itoa(port), Handler: injector.Latency(injector.HTTP(mux))}
+}
+
+func viewerServer(port int) *http.Server {
+	mux := http.NewServeMux()
+	mux.Handle("/", playground.Handler("viewer", "/graphql"))
+	mux.Handle("/graphql", viewer.NewHandler())
+	return &http.Server{Addr: ":" + strconv.Itoa(port), Handler: injector.Latency(injector.HTTP(mux))}
+}

demo/config-cache-only.json

@@ -9,6 +9,7 @@ require (
 	github.com/nats-io/nats.go v1.35.0
 	github.com/ravilushqa/otelgqlgen v0.13.1
 	github.com/rs/cors v1.11.0
+	github.com/stretchr/testify v1.11.1
 	github.com/vektah/gqlparser/v2 v2.5.30
 	github.com/wundergraph/cosmo/router v0.0.0-20260330183556-dc4388d100a4
 	github.com/wundergraph/cosmo/router-tests v0.0.0-20260330183556-dc4388d100a4
@@ -128,7 +129,6 @@ require (
 	github.com/sosodev/duration v1.3.1 // indirect
 	github.com/spf13/cast v1.7.1 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
-	github.com/stretchr/testify v1.11.1 // indirect
 	github.com/tidwall/gjson v1.18.0 // indirect
 	github.com/tidwall/match v1.1.1 // indirect
 	github.com/tidwall/pretty v1.2.1 // indirect

demo/go.mod

@@ -0,0 +1,14 @@
+version: 1
+subgraphs:
+  - name: cachegraph
+    routing_url: http://localhost:4012/graphql
+    schema:
+      file: ./pkg/subgraphs/cachegraph/subgraph/schema.graphqls
+  - name: cachegraph-ext
+    routing_url: http://localhost:4013/graphql
+    schema:
+      file: ./pkg/subgraphs/cachegraph_ext/subgraph/schema.graphqls
+  - name: viewer
+    routing_url: http://localhost:4014/graphql
+    schema:
+      file: ./pkg/subgraphs/viewer/subgraph/schema.graphqls

demo/graph-cache-only.yaml

@@ -40,6 +40,10 @@ subgraphs:
     routing_url: http://localhost:4009/graphql
     schema:
       file: ./pkg/subgraphs/countries/subgraph/schema.graphqls
+  - name: cachegraph
+    routing_url: http://localhost:4012/graphql
+    schema:
+      file: ./pkg/subgraphs/cachegraph/subgraph/schema.graphqls
   - name: employeeupdated
     schema:
       file: ./pkg/subgraphs/employeeupdated/subgraph/schema.graphqls

demo/graph.yaml

@@ -0,0 +1,29 @@
+package injector
+
+import (
+	"log"
+	"net/http"
+	"strconv"
+	"time"
+)
+
+// ArtificialLatencyHeader lets the playground or any client inject fake latency
+// into a demo subgraph response. Value is milliseconds as an integer, bounded
+// at 10000. Intended for demos where local subgraphs are too fast to make
+// caching benefits visible.
+const ArtificialLatencyHeader = "X-Artificial-Latency"
+
+// Latency wraps a handler and sleeps for the number of milliseconds specified
+// in the X-Artificial-Latency request header before passing the request down.
+// Invalid values are silently ignored.
+func Latency(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if v := r.Header.Get(ArtificialLatencyHeader); v != "" {
+			if ms, err := strconv.Atoi(v); err == nil && ms > 0 && ms <= 10000 {
+				log.Printf("[latency] %s %s sleep %dms prefix=%q", r.Method, r.Host, ms, r.Header.Get("X-WG-Cache-Key-Prefix"))
+				time.Sleep(time.Duration(ms) * time.Millisecond)
+			}
+		}
+		next.ServeHTTP(w, r)
+	})
+}

demo/pkg/injector/latency.go

@@ -0,0 +1,12 @@
+package cachegraph
+
+import (
+	"github.com/99designs/gqlgen/graphql"
+
+	"github.com/wundergraph/cosmo/demo/pkg/subgraphs/cachegraph/subgraph"
+	"github.com/wundergraph/cosmo/demo/pkg/subgraphs/cachegraph/subgraph/generated"
+)
+
+func NewSchema() graphql.ExecutableSchema {
+	return generated.NewExecutableSchema(generated.Config{Resolvers: subgraph.NewResolver()})
+}

demo/pkg/subgraphs/cachegraph/cachegraph.go

@@ -0,0 +1,2 @@
+//go:generate go run github.com/99designs/gqlgen generate
+package cachegraph