0
# Spring Boot Starter RSocket
1
2
Spring Boot starter for building RSocket clients and servers. RSocket is a binary protocol for use on byte stream transports such as TCP, WebSockets, and Aeron. This starter provides comprehensive auto-configuration for RSocket infrastructure, making it easy to build reactive, real-time applications with bidirectional communication.
3
4
## Package Information
5
6
- **Package Name**: spring-boot-starter-rsocket
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to `build.gradle` or `pom.xml`
10
11
```gradle
12
dependencies {
13
implementation 'org.springframework.boot:spring-boot-starter-rsocket'
14
}
15
```
16
17
```xml
18
<dependency>
19
<groupId>org.springframework.boot</groupId>
20
<artifactId>spring-boot-starter-rsocket</artifactId>
21
</dependency>
22
```
23
24
## Core Imports
25
26
```java
27
import org.springframework.messaging.rsocket.RSocketRequester;
28
import org.springframework.messaging.rsocket.RSocketStrategies;
29
import org.springframework.messaging.handler.annotation.MessageMapping;
30
import org.springframework.boot.rsocket.server.RSocketServerCustomizer;
31
import org.springframework.boot.autoconfigure.rsocket.RSocketStrategiesCustomizer;
32
import org.springframework.boot.rsocket.context.LocalRSocketServerPort; // Deprecated
33
import org.springframework.boot.rsocket.context.RSocketServerInitializedEvent;
34
import org.springframework.boot.test.rsocket.server.LocalRSocketServerPort; // Replacement since 2.7.0
35
```
36
37
## Basic Usage
38
39
### Client Configuration
40
41
```java
42
@Service
43
public class MyRSocketClient {
44
45
private final RSocketRequester.Builder requesterBuilder;
46
47
public MyRSocketClient(RSocketRequester.Builder requesterBuilder) {
48
this.requesterBuilder = requesterBuilder;
49
}
50
51
public Mono<String> callServer() {
52
return requesterBuilder
53
.tcp("localhost", 9898)
54
.route("hello")
55
.data("World")
56
.retrieveMono(String.class);
57
}
58
}
59
```
60
61
### Server Configuration
62
63
```java
64
@Controller
65
public class MyRSocketController {
66
67
@MessageMapping("hello")
68
public Mono<String> hello(String name) {
69
return Mono.just("Hello, " + name + "!");
70
}
71
}
72
```
73
74
```yaml
75
# application.yml
76
spring:
77
rsocket:
78
server:
79
port: 9898
80
transport: tcp
81
```
82
83
## Architecture
84
85
The starter provides several key layers:
86
87
- **Auto-Configuration**: Automatically configures RSocket infrastructure based on classpath and properties
88
- **Strategy Layer**: RSocketStrategies for codec configuration and message handling
89
- **Server Infrastructure**: Embedded RSocket server or WebSocket integration with WebFlux
90
- **Client Infrastructure**: RSocketRequester builder for creating client connections
91
- **Messaging Integration**: Spring messaging annotations and handlers for RSocket endpoints
92
- **Customization Points**: Multiple customizer interfaces for fine-tuning configuration
93
94
## Capabilities
95
96
### Auto-Configuration
97
98
Automatic configuration of RSocket infrastructure including codecs, servers, clients, and messaging handlers. Provides sensible defaults while enabling extensive customization through properties and customizer beans.
99
100
```java { .api }
101
// Auto-configuration classes registered automatically
102
@AutoConfiguration(after = JacksonAutoConfiguration.class)
103
@ConditionalOnClass({ io.rsocket.RSocket.class, RSocketStrategies.class, PooledByteBufAllocator.class })
104
class RSocketStrategiesAutoConfiguration {
105
@Bean
106
@ConditionalOnMissingBean
107
RSocketStrategies rSocketStrategies(ObjectProvider<RSocketStrategiesCustomizer> customizers);
108
}
109
110
@AutoConfiguration(after = RSocketStrategiesAutoConfiguration.class)
111
@ConditionalOnClass({ RSocketServer.class, RSocketStrategies.class, HttpServer.class, TcpServerTransport.class })
112
@ConditionalOnBean(RSocketMessageHandler.class)
113
@EnableConfigurationProperties(RSocketProperties.class)
114
class RSocketServerAutoConfiguration {
115
// Server configuration classes
116
}
117
118
@AutoConfiguration(after = RSocketStrategiesAutoConfiguration.class)
119
@ConditionalOnClass({ RSocketRequester.class, io.rsocket.RSocket.class, HttpServer.class, TcpServerTransport.class })
120
class RSocketRequesterAutoConfiguration {
121
@Bean
122
@Scope("prototype")
123
@ConditionalOnMissingBean
124
RSocketRequester.Builder rSocketRequesterBuilder(RSocketStrategies strategies, ObjectProvider<RSocketConnectorConfigurer> connectorConfigurers);
125
}
126
127
@AutoConfiguration(after = RSocketStrategiesAutoConfiguration.class)
128
@ConditionalOnClass({ RSocketRequester.class, io.rsocket.RSocket.class, TcpServerTransport.class })
129
class RSocketMessagingAutoConfiguration {
130
@Bean
131
@ConditionalOnMissingBean
132
RSocketMessageHandler messageHandler(RSocketStrategies rSocketStrategies, ObjectProvider<RSocketMessageHandlerCustomizer> customizers);
133
}
134
```
135
136
[Auto-Configuration](./auto-configuration.md)
137
138
### Server Configuration
139
140
RSocket server setup supporting both standalone TCP/WebSocket servers and WebSocket endpoints integrated with Spring WebFlux applications.
141
142
```java { .api }
143
// Server configuration properties
144
@ConfigurationProperties("spring.rsocket.server")
145
class RSocketProperties.Server {
146
Integer port;
147
InetAddress address;
148
RSocketServer.Transport transport; // TCP, WEBSOCKET
149
String mappingPath;
150
DataSize fragmentSize;
151
Ssl ssl;
152
}
153
```
154
155
[Server Configuration](./server-configuration.md)
156
157
### Client Configuration
158
159
RSocket client configuration with RSocketRequester builder for establishing connections and making requests to RSocket servers.
160
161
```java { .api }
162
@Bean
163
@Scope("prototype")
164
@ConditionalOnMissingBean
165
RSocketRequester.Builder rSocketRequesterBuilder(
166
RSocketStrategies strategies,
167
ObjectProvider<RSocketConnectorConfigurer> connectorConfigurers
168
);
169
```
170
171
[Client Configuration](./client-configuration.md)
172
173
### Message Handling
174
175
Spring messaging integration enabling @MessageMapping annotations and bidirectional communication patterns in RSocket controllers.
176
177
```java { .api }
178
@Bean
179
@ConditionalOnMissingBean
180
RSocketMessageHandler messageHandler(
181
RSocketStrategies rSocketStrategies,
182
ObjectProvider<RSocketMessageHandlerCustomizer> customizers
183
);
184
```
185
186
[Message Handling](./message-handling.md)
187
188
### Codec Configuration
189
190
Encoding and decoding configuration for RSocket payloads, with built-in support for JSON and CBOR formats via Jackson integration.
191
192
```java { .api }
193
@Bean
194
@ConditionalOnMissingBean
195
RSocketStrategies rSocketStrategies(
196
ObjectProvider<RSocketStrategiesCustomizer> customizers
197
);
198
```
199
200
[Codec Configuration](./codec-configuration.md)
201
202
## Configuration Properties
203
204
All RSocket configuration is available under the `spring.rsocket` prefix:
205
206
```yaml
207
spring:
208
rsocket:
209
server:
210
port: 9898 # Server port
211
address: 0.0.0.0 # Bind address
212
transport: tcp # TCP or WEBSOCKET
213
mapping-path: "/rsocket" # WebSocket path
214
fragment-size: 64KB # Frame fragmentation
215
ssl:
216
enabled: true # SSL configuration
217
```
218
219
## Types
220
221
```java { .api }
222
// Core server interface
223
interface RSocketServer {
224
void start() throws RSocketServerException;
225
void stop() throws RSocketServerException;
226
InetSocketAddress address();
227
228
enum Transport { TCP, WEBSOCKET }
229
}
230
231
// Server factory interface
232
@FunctionalInterface
233
interface RSocketServerFactory {
234
RSocketServer create(SocketAcceptor socketAcceptor);
235
}
236
237
// Configurable server factory interface
238
interface ConfigurableRSocketServerFactory extends RSocketServerFactory {
239
void setPort(int port);
240
void setAddress(InetAddress address);
241
void setTransport(RSocketServer.Transport transport);
242
}
243
244
// Server bootstrap for lifecycle management
245
class RSocketServerBootstrap implements SmartLifecycle {
246
RSocketServerBootstrap(RSocketServerFactory serverFactory, SocketAcceptor socketAcceptor);
247
void start();
248
void stop();
249
boolean isRunning();
250
}
251
252
// Server initialization event
253
class RSocketServerInitializedEvent extends ApplicationEvent {
254
RSocketServerInitializedEvent(RSocketServer server);
255
RSocketServer getServer();
256
}
257
258
// Port injection annotation (deprecated since 2.7.0)
259
@Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE })
260
@Retention(RetentionPolicy.RUNTIME)
261
@Documented
262
@Value("${local.rsocket.server.port}")
263
@Deprecated
264
@interface LocalRSocketServerPort {
265
}
266
267
// Server exceptions
268
class RSocketServerException extends RuntimeException {
269
RSocketServerException(String message, Throwable cause);
270
}
271
272
// Customization interfaces
273
@FunctionalInterface
274
interface RSocketStrategiesCustomizer {
275
void customize(RSocketStrategies.Builder strategies);
276
}
277
278
@FunctionalInterface
279
interface RSocketMessageHandlerCustomizer {
280
void customize(RSocketMessageHandler messageHandler);
281
}
282
283
@FunctionalInterface
284
interface RSocketServerCustomizer {
285
void customize(RSocketServer server);
286
}
287
288
// RSocket connector configurer interface
289
@FunctionalInterface
290
interface RSocketConnectorConfigurer {
291
void configure(RSocketConnector.RSocketConnectorBuilder builder);
292
}
293
294
// Configuration properties
295
@ConfigurationProperties("spring.rsocket")
296
class RSocketProperties {
297
Server server;
298
299
static class Server {
300
Integer port;
301
InetAddress address;
302
RSocketServer.Transport transport;
303
String mappingPath;
304
DataSize fragmentSize;
305
Ssl ssl;
306
}
307
}
308
```