0
# Quarkus Reactive Routes Deployment
1

2
A deployment artifact for the Quarkus Reactive Routes extension that enables declarative, non-blocking HTTP endpoint creation using @Route annotations. This module provides build-time processing and code generation for reactive HTTP routing in Quarkus applications.
3

4
## Package Information
5

6
- **Package Name**: quarkus-reactive-routes-deployment
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: io.quarkus
10
- **Artifact ID**: quarkus-reactive-routes-deployment
11
- **Installation**: Maven dependency in Quarkus extension development projects
12

13
## Maven Dependency
14

15
```xml
16
<dependency>
17
    <groupId>io.quarkus</groupId>
18
    <artifactId>quarkus-reactive-routes-deployment</artifactId>
19
    <version>3.26.2</version>
20
</dependency>
21
```
22

23
## Core Imports
24

25
```java
26
// Core deployment classes
27
import io.quarkus.vertx.web.deployment.ReactiveRoutesProcessor;
28
import io.quarkus.vertx.web.deployment.ReactiveRoutesMethodsProcessor;
29
import io.quarkus.vertx.web.deployment.AnnotatedRouteHandlerBuildItem;
30
import io.quarkus.vertx.web.deployment.AnnotatedRouteFilterBuildItem;
31
import io.quarkus.vertx.web.deployment.HandlerDescriptor;
32
import io.quarkus.vertx.web.deployment.DotNames;
33
import io.quarkus.vertx.web.deployment.Methods;
34

35
// Jandex annotation processing
36
import org.jboss.jandex.AnnotationInstance;
37
import org.jboss.jandex.MethodInfo;
38
import org.jboss.jandex.Type;
39
import org.jboss.jandex.DotName;
40
import org.jboss.jandex.IndexView;
41
import org.jboss.jandex.MethodParameterInfo;
42

43
// Quarkus build system
44
import io.quarkus.arc.processor.BeanInfo;
45
import io.quarkus.builder.item.MultiBuildItem;
46
import io.quarkus.deployment.annotations.BuildStep;
47
import io.quarkus.deployment.annotations.BuildProducer;
48
import io.quarkus.deployment.annotations.Record;
49
import io.quarkus.deployment.annotations.ExecutionTime;
50

51
// Reactive types
52
import io.smallrye.mutiny.Uni;
53
import io.smallrye.mutiny.Multi;
54

55
// Vert.x types
56
import io.vertx.core.buffer.Buffer;
57
import io.vertx.core.http.HttpServerRequest;
58
import io.vertx.core.http.HttpServerResponse;
59
import io.vertx.ext.web.RoutingContext;
60

61
// Build items
62
import io.quarkus.deployment.builditem.FeatureBuildItem;
63
import io.quarkus.vertx.http.deployment.FilterBuildItem;
64
import io.quarkus.vertx.http.deployment.RouteBuildItem;
65
```
66

67
## Basic Usage
68

69
This is a build-time extension module that processes @Route annotations and generates runtime routing code. It's not used directly in application code but rather consumed by the Quarkus build pipeline when processing reactive routes.
70

71
```java
72
// In a Quarkus extension processor
73
@BuildStep
74
void processCustomRoutes(
75
    List<AnnotatedRouteHandlerBuildItem> routeHandlers,
76
    BuildProducer<RouteBuildItem> routes) {
77
    
78
    for (AnnotatedRouteHandlerBuildItem handler : routeHandlers) {
79
        // Process route handler build items
80
        BeanInfo bean = handler.getBean();
81
        MethodInfo method = handler.getMethod();
82
        List<AnnotationInstance> routes = handler.getRoutes();
83
        // Custom processing logic...
84
    }
85
}
86
```
87

88
## Architecture
89

90
The deployment module follows Quarkus's build-time processing architecture:
91

92
- **Build Processors**: ReactiveRoutesProcessor and ReactiveRoutesMethodsProcessor scan for route annotations and validate route methods
93
- **Build Items**: AnnotatedRouteHandlerBuildItem and AnnotatedRouteFilterBuildItem represent discovered route handlers and filters
94
- **Code Generation**: Uses Gizmo to generate efficient bytecode for route handlers at build time
95
- **Integration**: Produces RouteBuildItem and FilterBuildItem for integration with Quarkus HTTP infrastructure
96

97
The processor transforms declarative @Route annotations into optimized runtime code, eliminating reflection overhead and enabling native compilation.
98

99
## Capabilities
100

101
### Build Processors
102

103
Main build processors that handle route annotation discovery, validation, and code generation during Quarkus build pipeline execution.
104

105
```java { .api }
106
class ReactiveRoutesProcessor {
107
    @BuildStep
108
    FeatureBuildItem feature();
109
    
110
    @BuildStep
111
    void unremovableBeans(BuildProducer<UnremovableBeanBuildItem> unremovableBeans);
112
    
113
    @BuildStep
114
    void validateBeanDeployment(
115
        BeanArchiveIndexBuildItem beanArchive,
116
        ValidationPhaseBuildItem validationPhase,
117
        TransformedAnnotationsBuildItem transformedAnnotations,
118
        BuildProducer<AnnotatedRouteHandlerBuildItem> routeHandlerBusinessMethods,
119
        BuildProducer<AnnotatedRouteFilterBuildItem> routeFilterBusinessMethods,
120
        BuildProducer<ValidationErrorBuildItem> errors,
121
        VertxHttpBuildTimeConfig httpBuildTimeConfig);
122
    
123
    @BuildStep
124
    @Record(value = ExecutionTime.STATIC_INIT)
125
    void replaceDefaultAuthFailureHandler(
126
        VertxWebRecorder recorder,
127
        Capabilities capabilities,
128
        BuildProducer<FilterBuildItem> filterBuildItemBuildProducer);
129
    
130
    @BuildStep
131
    @Record(ExecutionTime.RUNTIME_INIT)
132
    void addAdditionalRoutes(
133
        VertxWebRecorder recorder,
134
        List<AnnotatedRouteHandlerBuildItem> routeHandlerBusinessMethods,
135
        List<AnnotatedRouteFilterBuildItem> routeFilterBusinessMethods,
136
        BuildProducer<GeneratedClassBuildItem> generatedClass,
137
        BuildProducer<GeneratedResourceBuildItem> generatedResource,
138
        BuildProducer<ReflectiveClassBuildItem> reflectiveClasses,
139
        BuildProducer<ReflectiveHierarchyBuildItem> reflectiveHierarchy,
140
        BodyHandlerBuildItem bodyHandler,
141
        BuildProducer<RouteBuildItem> routeProducer,
142
        BuildProducer<FilterBuildItem> filterProducer,
143
        List<RequireBodyHandlerBuildItem> bodyHandlerRequired,
144
        BeanArchiveIndexBuildItem beanArchive,
145
        TransformedAnnotationsBuildItem transformedAnnotations,
146
        ShutdownContextBuildItem shutdown,
147
        LaunchModeBuildItem launchMode,
148
        BuildProducer<RouteDescriptionBuildItem> descriptions,
149
        Capabilities capabilities,
150
        Optional<BeanValidationAnnotationsBuildItem> beanValidationAnnotations,
151
        List<ApplicationClassPredicateBuildItem> predicates);
152
    
153
    @BuildStep
154
    AutoAddScopeBuildItem autoAddScope();
155
}
156

157
class ReactiveRoutesMethodsProcessor {
158
    @BuildStep
159
    ExecutionModelAnnotationsAllowedBuildItem reactiveRoutesMethods();
160
}
161
```
162

163
### Build Items
164

165
Build items represent discovered route handlers and filters that can be consumed by other build processors.
166

167
```java { .api }
168
class AnnotatedRouteHandlerBuildItem extends MultiBuildItem {
169
    AnnotatedRouteHandlerBuildItem(
170
        BeanInfo bean,
171
        MethodInfo method,
172
        List<AnnotationInstance> routes,
173
        AnnotationInstance routeBase);
174
    
175
    AnnotatedRouteHandlerBuildItem(
176
        BeanInfo bean,
177
        MethodInfo method,
178
        List<AnnotationInstance> routes,
179
        AnnotationInstance routeBase,
180
        boolean blocking,
181
        HttpCompression compression,
182
        boolean alwaysAuthenticateRoute);
183
    
184
    BeanInfo getBean();
185
    MethodInfo getMethod();
186
    List<AnnotationInstance> getRoutes();
187
    AnnotationInstance getRouteBase();
188
    boolean isBlocking();
189
    boolean shouldAlwaysAuthenticateRoute();
190
    HttpCompression getCompression();
191
}
192

193
public final class AnnotatedRouteFilterBuildItem extends MultiBuildItem {
194
    public AnnotatedRouteFilterBuildItem(
195
        BeanInfo bean,
196
        MethodInfo method,
197
        AnnotationInstance routeFilter);
198
    
199
    public BeanInfo getBean();
200
    public MethodInfo getMethod();
201
    public AnnotationInstance getRouteFilter();
202
}
203
```
204

205
### Handler Description
206

207
Describes request handlers for code generation, including return types, validation requirements, and payload analysis.
208

209
```java { .api }
210
class HandlerDescriptor {
211
    HandlerDescriptor(
212
        MethodInfo method,
213
        BeanValidationAnnotationsBuildItem bvAnnotations,
214
        boolean failureHandler,
215
        String[] producedTypes);
216
    
217
    Type getReturnType();
218
    boolean isReturningUni();
219
    boolean isReturningMulti();
220
    boolean isReturningCompletionStage();
221
    String getFirstContentType();
222
    boolean requireValidation();
223
    boolean isProducedResponseValidated();
224
    Type getPayloadType();
225
    boolean isPayloadString();
226
    boolean isPayloadBuffer();
227
    boolean isPayloadMutinyBuffer();
228
    boolean isFailureHandler();
229
}
230
```
231

232
### Type Constants
233

234
Annotation and type name constants used during build-time processing for efficient type checking and matching.
235

236
```java { .api }
237
class DotNames {
238
    // Reactive types
239
    static final DotName UNI;
240
    static final DotName MULTI;
241
    static final DotName COMPLETION_STAGE;
242
    
243
    // Buffer types
244
    static final DotName BUFFER;
245
    static final DotName MUTINY_BUFFER;
246
    
247
    // HTTP types
248
    static final DotName HTTP_SERVER_REQUEST;
249
    static final DotName HTTP_SERVER_RESPONSE;
250
    static final DotName MUTINY_HTTP_SERVER_REQUEST;
251
    static final DotName MUTINY_HTTP_SERVER_RESPONSE;
252
    
253
    // Routing types
254
    static final DotName ROUTING_CONTEXT;
255
    static final DotName ROUTING_EXCHANGE;
256
    
257
    // Route annotations
258
    static final DotName ROUTE;
259
    static final DotName ROUTES;
260
    static final DotName ROUTE_BASE;
261
    static final DotName ROUTE_FILTER;
262
    
263
    // Parameter annotations
264
    static final DotName BODY;
265
    static final DotName HEADER;
266
    static final DotName PARAM;
267
    
268
    // JSON types
269
    static final DotName JSON_OBJECT;
270
    static final DotName JSON_ARRAY;
271
    
272
    // Execution annotations
273
    static final DotName BLOCKING;
274
    static final DotName RUN_ON_VIRTUAL_THREAD;
275
    
276
    // Compression annotations
277
    static final DotName COMPRESSED;
278
    static final DotName UNCOMPRESSED;
279
    
280
    // Collection and exception types
281
    static final DotName LIST;
282
    static final DotName EXCEPTION;
283
    static final DotName THROWABLE;
284
}
285
```
286

287
### Bytecode Generation Utilities
288

289
Utility methods and constants for generating efficient bytecode using Gizmo during build-time processing.
290

291
```java { .api }
292
class Methods {
293
    // HTTP method descriptors
294
    static final MethodDesc REQUEST;
295
    static final MethodDesc RESPONSE;
296
    static final MethodDesc GET_BODY;
297
    static final MethodDesc GET_BODY_AS_STRING;
298
    static final MethodDesc GET_BODY_AS_JSON;
299
    static final MethodDesc GET_BODY_AS_JSON_ARRAY;
300
    static final MethodDesc REQUEST_GET_PARAM;
301
    static final MethodDesc REQUEST_GET_HEADER;
302
    
303
    // Reactive method descriptors
304
    static final MethodDesc UNI_SUBSCRIBE;
305
    static final MethodDesc UNI_SUBSCRIBE_WITH;
306
    static final MethodDesc MULTI_SUBSCRIBE_VOID;
307
    static final MethodDesc MULTI_SUBSCRIBE_STRING;
308
    static final MethodDesc MULTI_SUBSCRIBE_BUFFER;
309
    static final MethodDesc MULTI_SUBSCRIBE_MUTINY_BUFFER;
310
    static final MethodDesc MULTI_SUBSCRIBE_OBJECT;
311
    
312
    // CDI method descriptors
313
    static final MethodDesc ARC_CONTAINER;
314
    static final MethodDesc ARC_CONTAINER_GET_ACTIVE_CONTEXT;
315
    static final MethodDesc ARC_CONTAINER_BEAN;
316
    static final MethodDesc BEAN_GET_SCOPE;
317
    static final MethodDesc CONTEXT_GET;
318
    static final MethodDesc CONTEXT_GET_IF_PRESENT;
319
    
320
    // Validation method descriptors
321
    static final MethodDesc VALIDATOR_VALIDATE;
322
    static final MethodDesc VALIDATION_GET_VALIDATOR;
323
    static final MethodDesc VALIDATION_HANDLE_VIOLATION;
324
    
325
    // Utility methods
326
    static boolean isNoContent(HandlerDescriptor descriptor);
327
    static Expr createNpeItemIsNull(BlockCreator bc);
328
    static MethodDesc getEndMethodForContentType(HandlerDescriptor descriptor);
329
    static void setContentTypeToJson(Var response, BlockCreator b0);
330
    static Var validateProducedItem(
331
        Var response,
332
        BlockCreator b0,
333
        Var res,
334
        Expr this_,
335
        FieldDesc validatorField);
336
}
337
```
338

339
## Processing Flow
340

341
1. **Discovery Phase**: Scan all CDI beans for @Route, @Routes, and @RouteFilter annotations
342
2. **Validation Phase**: Validate route method signatures, parameter types, and annotations
343
3. **Code Generation Phase**: Generate optimized bytecode for route handlers using Gizmo
344
4. **Integration Phase**: Produce build items for integration with Quarkus HTTP infrastructure
345
5. **Registration Phase**: Register generated handlers and filters with Vert.x router
346

347
## Error Handling
348

349
The processor validates route methods and produces detailed error messages for:
350
- Invalid method signatures
351
- Unsupported parameter types
352
- Missing required annotations
353
- Conflicting route definitions
354
- Invalid return types for reactive methods
355

356
## Performance Considerations
357

358
- Build-time code generation eliminates reflection overhead
359
- Generated handlers are optimized for specific route signatures
360
- Native image compilation friendly (no runtime reflection)
361
- Efficient parameter injection without runtime type checking
362
- CDI integration optimized for different bean scopes
363

364
## Integration Points
365

366
This deployment module integrates with:
367
- **Quarkus HTTP**: Produces RouteBuildItem and FilterBuildItem
368
- **Vert.x Web**: Generates handlers compatible with Vert.x routing
369
- **CDI/Arc**: Handles bean lifecycle and dependency injection
370
- **Bean Validation**: Optional integration for request/response validation
371
- **Security**: Integration with Quarkus security annotations
372
- **Jackson**: JSON serialization/deserialization support
373

374
## Supported Features
375

376
- **HTTP Methods**: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
377
- **Path Parameters**: URL path parameters with @Param
378
- **Query Parameters**: Request parameters with @Param
379
- **Headers**: HTTP headers with @Header
380
- **Request Body**: JSON, String, Buffer with @Body
381
- **Return Types**: Synchronous, Uni, Multi, CompletionStage
382
- **Content Types**: JSON, SSE, NDJSON, plain text
383
- **Security**: @RolesAllowed, @Authenticated, @PermissionsAllowed
384
- **Validation**: Bean validation with @Valid
385
- **Compression**: HTTP response compression
386
- **Virtual Threads**: @RunOnVirtualThread support
387
- **Blocking Operations**: @Blocking annotation
388
- **Failure Handling**: Exception handlers with failure routes
389
- **Route Filters**: Pre/post processing filters
390

391
## Types
392

393
### Core Quarkus Build Types
394

395
```java { .api }
396
// Build items
397
abstract class MultiBuildItem {}
398

399
// Build producers for generating build items
400
interface BuildProducer<T> {
401
    void produce(T item);
402
}
403

404
// Jandex annotation and type model
405
interface AnnotationInstance {
406
    DotName name();
407
    AnnotationValue value();
408
    AnnotationValue value(String name);
409
    AnnotationValue valueWithDefault(IndexView index, String name);
410
    String toString(boolean simple);
411
}
412

413
interface MethodInfo {
414
    String name();
415
    Type returnType();
416
    List<Type> parameterTypes();
417
    List<MethodParameterInfo> parameters();
418
    int parametersCount();
419
    ClassInfo declaringClass();
420
    List<AnnotationInstance> annotations();
421
    boolean hasDeclaredAnnotation(DotName name);
422
    boolean isSynthetic();
423
    int flags();
424
}
425

426
interface BeanInfo {
427
    ClassInfo getTarget();
428
    String getIdentifier();
429
    Class<?> getScope();
430
    ClassInfo getImplClazz();
431
    ClassInfo getBeanClass();
432
}
433

434
interface Type {
435
    DotName name();
436
    Kind kind();
437
    ParameterizedType asParameterizedType();
438
    
439
    enum Kind {
440
        CLASS, PARAMETERIZED_TYPE, VOID
441
    }
442
}
443

444
// Bytecode generation types
445
interface BlockCreator {
446
    LocalVar localVar(String name, Expr value);
447
    Expr invokeInterface(MethodDesc method, Expr... args);
448
    Expr invokeStatic(MethodDesc method, Expr... args);
449
    Expr invokeVirtual(MethodDesc method, Expr instance, Expr... args);
450
    void ifNull(Expr condition, Consumer<BlockCreator> thenBlock);
451
    void ifNotNull(Expr condition, Consumer<BlockCreator> thenBlock);
452
    void ifElse(Expr condition, Consumer<BlockCreator> thenBlock, Consumer<BlockCreator> elseBlock);
453
    void set(Var variable, Expr value);
454
    void return_();
455
}
456

457
interface Expr {
458
    boolean isVoid();
459
    ClassDesc getType();
460
}
461

462
interface Var extends Expr {
463
    FieldVar field(FieldDesc field);
464
}
465

466
// HTTP and validation types
467
enum HttpCompression {
468
    UNDEFINED, ON, OFF
469
}
470

471
// Build-time configuration
472
interface VertxHttpBuildTimeConfig {
473
    AuthConfig auth();
474
    
475
    interface AuthConfig {
476
        boolean proactive();
477
    }
478
}
479

480
// Additional Gizmo2 bytecode generation types used in Methods class
481
interface InterfaceMethodDesc extends MethodDesc {}
482

483
final class MethodTypeDesc {
484
    static MethodTypeDesc of(ClassDesc returnType, ClassDesc... paramTypes);
485
}
486

487
final class FieldDesc {
488
    static FieldDesc of(ClassDesc owner, String name, ClassDesc type);
489
}
490

491
final class ConstructorDesc {
492
    static ConstructorDesc of(Class<?> owner, Class<?>... paramTypes);
493
}
494

495
interface UniSubscribe {}
496
interface Cancellable {}
497

498
// Multi support runtime classes
499
class MultiSupport {}
500
class MultiSseSupport {}  
501
class MultiNdjsonSupport {}
502
class MultiJsonArraySupport {}
503
class ValidationSupport {}
504
class RouteHandlers {}
505
```
506

507
### Parameter Injection Types
508

509
```java { .api }
510
interface ParameterInjector {
511
    boolean matches(Type paramType, Set<AnnotationInstance> paramAnnotations, IndexView index);
512
    Route.HandlerType getTargetHandlerType();
513
    void validate(BeanInfo bean, MethodInfo method, AnnotationInstance routeInstance, 
514
                 Type paramType, Set<AnnotationInstance> paramAnnotations);
515
    Expr getValue(MethodParameterInfo methodParam, Set<AnnotationInstance> annotations,
516
                 Var routingContext, BlockCreator bc, 
517
                 BuildProducer<ReflectiveHierarchyBuildItem> reflectiveHierarchy);
518
    
519
    static Builder builder() { return new Builder(); }
520
    
521
    class Builder {
522
        Builder matchType(DotName className);
523
        Builder matchType(Type type);
524
        Builder matchOptionalOf(DotName className);
525
        Builder matchListOf(DotName className);
526
        Builder skipType(DotName className);
527
        Builder requireAnnotations(DotName... names);
528
        Builder valueProvider(ValueProvider provider);
529
        Builder targetHandlerType(Route.HandlerType handlerType);
530
        Builder validate(ParamValidator validator);
531
        Builder canEndResponse();
532
        ParameterInjector build();
533
    }
534
}
535

536
@FunctionalInterface
537
interface ValueProvider {
538
    Expr get(MethodParameterInfo methodParam, Set<AnnotationInstance> annotations, 
539
            Var routingContext, BlockCreator bc, 
540
            BuildProducer<ReflectiveHierarchyBuildItem> reflectiveHierarchy);
541
}
542

543
@FunctionalInterface
544
interface ParamValidator {
545
    void validate(BeanInfo bean, MethodInfo method, AnnotationInstance routeAnnotation, 
546
                 Type paramType, Set<AnnotationInstance> paramAnnotations);
547
}
548

549
@FunctionalInterface
550
interface TriPredicate<A, B, C> {
551
    boolean test(A a, B b, C c);
552
}
553
```