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
```