0
# Transport Support
1
2
Spring Boot GraphQL Starter supports multiple transport protocols for GraphQL communication: HTTP, WebSocket, Server-Sent Events (SSE), and RSocket. Each transport is automatically configured and optimized for different use cases.
3
4
## HTTP Transport
5
6
Standard HTTP POST requests for queries and mutations.
7
8
### Configuration
9
10
```properties
11
# HTTP endpoint configuration
12
spring.graphql.http.path=/graphql
13
```
14
15
### Usage Example
16
17
```java
18
// HTTP client example
19
POST /graphql
20
Content-Type: application/json
21
Authorization: Bearer <token>
22
23
{
24
"query": "query GetBooks($limit: Int) { books(limit: $limit) { id title author } }",
25
"variables": { "limit": 10 },
26
"operationName": "GetBooks"
27
}
28
```
29
30
## WebSocket Transport
31
32
GraphQL over WebSocket protocol for real-time subscriptions and bidirectional communication.
33
34
### Configuration
35
36
```java { .api }
37
// WebSocket configuration
38
spring.graphql.websocket.path=/graphql-ws
39
spring.graphql.websocket.connection-init-timeout=30s
40
spring.graphql.websocket.keep-alive=15s
41
```
42
43
### Auto-Configuration
44
45
```java { .api }
46
@Bean
47
@ConditionalOnMissingBean
48
public GraphQlWebSocketHandler graphQlWebSocketHandler(
49
WebGraphQlHandler webGraphQlHandler,
50
GraphQlProperties properties,
51
HttpMessageConverters converters
52
) {
53
return new GraphQlWebSocketHandler(
54
webGraphQlHandler,
55
getJsonConverter(converters),
56
properties.getWebsocket().getConnectionInitTimeout(),
57
properties.getWebsocket().getKeepAlive()
58
);
59
}
60
```
61
62
### Subscription Example
63
64
```java
65
@Controller
66
public class BookSubscriptionController {
67
68
@SubscriptionMapping
69
public Flux<BookEvent> bookUpdates() {
70
return bookEventPublisher.getUpdates()
71
.map(this::toGraphQLEvent);
72
}
73
74
@SubscriptionMapping
75
public Flux<BookEvent> booksByAuthor(@Argument String authorId) {
76
return bookEventPublisher.getUpdatesByAuthor(authorId);
77
}
78
}
79
```
80
81
## Server-Sent Events (SSE)
82
83
HTTP-based streaming for GraphQL subscriptions using Server-Sent Events.
84
85
### Configuration
86
87
```java { .api }
88
// SSE configuration
89
spring.graphql.http.sse.keep-alive=30s
90
spring.graphql.http.sse.timeout=60s
91
```
92
93
### Auto-Configuration
94
95
```java { .api }
96
@Bean
97
@ConditionalOnMissingBean
98
public GraphQlSseHandler graphQlSseHandler(
99
WebGraphQlHandler webGraphQlHandler,
100
GraphQlProperties properties
101
) {
102
return new GraphQlSseHandler(
103
webGraphQlHandler,
104
properties.getHttp().getSse().getTimeout(),
105
properties.getHttp().getSse().getKeepAlive()
106
);
107
}
108
```
109
110
### Client Usage
111
112
```javascript
113
// JavaScript SSE client
114
const eventSource = new EventSource('/graphql?query=subscription{bookUpdates{id title}}');
115
eventSource.onmessage = function(event) {
116
const data = JSON.parse(event.data);
117
console.log('Book update:', data);
118
};
119
```
120
121
## RSocket Transport
122
123
GraphQL over RSocket for reactive, bidirectional, multiplexed communication.
124
125
### Configuration
126
127
```java { .api }
128
// RSocket configuration
129
spring.graphql.rsocket.mapping=graphql
130
spring.rsocket.server.port=7000
131
```
132
133
### Auto-Configuration Classes
134
135
```java { .api }
136
@AutoConfiguration(after = GraphQlAutoConfiguration.class)
137
@ConditionalOnClass({ GraphQL.class, RSocketRequester.class })
138
@ConditionalOnBean(GraphQlSource.class)
139
public class GraphQlRSocketAutoConfiguration {
140
141
@Bean
142
@ConditionalOnMissingBean
143
public RSocketGraphQlHandler rSocketGraphQlHandler(WebGraphQlHandler handler) {
144
return new RSocketGraphQlHandler(handler, Arrays.asList(MediaType.APPLICATION_JSON));
145
}
146
}
147
```
148
149
### RSocket Handler Setup
150
151
```java { .api }
152
@Controller
153
public class RSocketGraphQlController {
154
155
@MessageMapping("graphql.query")
156
public Mono<Book> getBook(String query) {
157
return graphQlService.executeQuery(query)
158
.map(result -> (Book) result.getData());
159
}
160
161
@MessageMapping("graphql.subscription")
162
public Flux<BookEvent> bookStream(String subscription) {
163
return graphQlService.executeSubscription(subscription)
164
.map(result -> (BookEvent) result.getData());
165
}
166
}
167
```
168
169
## Transport Selection
170
171
### Automatic Transport Detection
172
173
The starter automatically configures appropriate transports based on:
174
175
```java { .api }
176
// Servlet-based applications
177
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
178
// -> HTTP, WebSocket, SSE
179
180
// Reactive applications
181
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.REACTIVE)
182
// -> Reactive HTTP, Reactive WebSocket, Reactive SSE
183
184
// RSocket applications
185
@ConditionalOnClass(RSocketRequester.class)
186
// -> RSocket transport
187
```
188
189
### Transport-Specific Features
190
191
#### HTTP Features
192
- Request batching
193
- Caching headers
194
- CORS support
195
- Multipart file uploads
196
197
#### WebSocket Features
198
- Connection pooling
199
- Automatic reconnection
200
- Subscription multiplexing
201
- Custom connection params
202
203
#### SSE Features
204
- Automatic keep-alive
205
- Connection timeout handling
206
- Browser compatibility
207
- Fallback support
208
209
#### RSocket Features
210
- Reactive streams
211
- Request-response patterns
212
- Request-stream patterns
213
- Fire-and-forget patterns
214
215
## Performance Optimization
216
217
### Connection Management
218
219
```java { .api }
220
// WebSocket connection limits
221
server.netty.max-connections=1000
222
223
// SSE timeout configuration
224
spring.graphql.http.sse.timeout=5m
225
spring.graphql.http.sse.keep-alive=30s
226
227
// RSocket connection pooling
228
spring.rsocket.server.transport=tcp
229
spring.rsocket.server.port=7000
230
```
231
232
### Batching Support
233
234
```java
235
// HTTP request batching
236
POST /graphql
237
Content-Type: application/json
238
239
[
240
{"query": "query GetBooks { books { id title } }"},
241
{"query": "query GetAuthors { authors { id name } }"}
242
]
243
```
244
245
## Error Handling
246
247
### Transport-Specific Error Responses
248
249
```java { .api }
250
@Component
251
public class TransportErrorHandler implements DataFetcherExceptionResolver {
252
253
@Override
254
public Mono<List<GraphQLError>> resolveException(DataFetcherExceptionResolverEnvironment env) {
255
Throwable exception = env.getException();
256
257
if (exception instanceof WebSocketConnectionException) {
258
return Mono.just(List.of(
259
GraphqlErrorBuilder.newError(env)
260
.message("WebSocket connection failed")
261
.extensions(Map.of("transport", "websocket"))
262
.build()
263
));
264
}
265
266
return Mono.empty();
267
}
268
}
269
```
270
271
## Security Considerations
272
273
### Transport-Specific Security
274
275
```java { .api }
276
// HTTP security
277
spring.security.require-ssl=true
278
279
// WebSocket security
280
spring.graphql.websocket.allowed-origins=https://example.com
281
282
// RSocket security
283
spring.rsocket.server.ssl.enabled=true
284
spring.rsocket.server.ssl.key-store=classpath:keystore.p12
285
```