This provides GraphQL routing via http (queries/mutations only), and via the Atom-based WebSocket protocol (all). This project will probably become a part of the Clue project, which provides a GraphQL client for the above protocols.

libraryDependencies += "edu.gemini" %% "lucuma-graphql-routes-sangria" % <version> // Sangria
libraryDependencies += "edu.gemini" %% "lucuma-graphql-routes-grackle" % <version> // Grackle

The HttpRoutes provided by this library will delegate GraphQL operation to a GraphQLService which is computed on a per-request basis. This allows the application to select a different schema based on credentials in the request, for example.

So first, write a method that constructs a GraphQLService based on the incoming Authorization header (if any).

def mkService(auth: Option[Authorization]): F[Option[GraphQLService[F]]] =
  // Yield None to deny access (403 Forbidden), or a GraphQLService if it's
  // ok to service the request.

There are two constructors for GraphQLService, depending on the back end you're using.

new SangriaGraphQLService[F](mySchema, userData, exceptionHandler) // Sangria
new GrackleGraphQLService[F](myMapping) // Grackle

Next construct the HttpRoutes, passing the method defined above.

Routes.forService(mkService) // HttpRoutes[F]

The resulting HttpRoutes will serve the following endpoints:

• Root / "graphql" using the Serving over HTTP specification.
• Root / "ws" using the GraphQL over WebSocket Protocol specification.
• Root / "playground.html" serving the GraphQL Playground HTML application.

The "graphql", "ws", and "playground.html" segments are defaults; you can specify different values when you call Routes.forService.

This library uses otel4s for OpenTelemetry tracing. A Tracer[F] must be in scope when constructing routes. Each operation produces a graphql span with graphql.document, graphql.operation.type, and graphql.operation.name semconv attributes.

Trace context propagation differs by transport:

• HTTP (queries/mutations): The standard traceparent HTTP header is propagated automatically by the http4s otel4s middleware in the calling application.
• WebSocket subscriptions: The WebSocket endpoint uses the graphql-transport-ws protocol. If the client includes a W3C traceparent in the extensions field of the subscribe message, this library extracts it and re-parents the server span on the client's remote trace context, enabling end-to-end distributed tracing per subscription operation.