DEV Community

Alone Star
Alone Star

Posted on

LightESB HTTP Listener and Request Routing: Undertow + HttpRequestSrv Deep Dive

#api #architecture #backend #networking

Metadata

  • Applicable Version: HttpRequestSrv@v1.0.0
  • Publish Date: 2026-04-08
  • Article Type: Technical Deep Dive
  • Related Service: HttpRequestSrv@v1.0.0@http-request-route.xml

When a service needs to expose HTTP APIs in LightESB, the route XML itself is only half of the picture.

The other half is the runtime listener switch: HTTP.Listener.

This article explains how HTTP.Listener, server.port, and Undertow endpoints work together by using HttpRequestSrv as a concrete example.

Why HTTP.Listener Matters

In LightESB, Undertow component registration is controlled by configuration:

  • HTTP.Listener=true: register Undertow and expose HTTP routes
  • HTTP.Listener=false: skip Undertow registration
  • server.port: runtime listening port for route endpoints

From HttpRequestSrv/v1.0.0/common.config.properties:

server.port=18083
HTTP.Listener=true
system.components=undertowhttp
Enter fullscreen mode Exit fullscreen mode

This design lets teams decide whether a service is externally reachable without modifying route XML files.

Route Entry Design in HttpRequestSrv

HttpRequestSrv defines two Undertow entries:

<from uri="undertow:http://0.0.0.0:{{server.port}}/api/httprequest/test?httpMethodRestrict=POST" />
...
<from uri="undertow:http://0.0.0.0:{{server.port}}/api/test?httpMethodRestrict=POST"/>
Enter fullscreen mode Exit fullscreen mode

Key points:

  • 0.0.0.0 listens on all NICs
  • {{server.port}} injects environment-level port
  • httpMethodRestrict=POST ensures method-level guard at the endpoint

This is a clean pattern for API entry routes: reject invalid methods early and keep business processors focused.

Request Flow: Listener -> Route -> Downstream Call

The first route acts as both inbound listener and outbound requester:

  1. Receive external request on /api/httprequest/test
  2. Log request start with servicelog
  3. Forward to local endpoint http://0.0.0.0:18083/api/test
  4. Log completion and return response

Core segment:

<to uri="servicelog:info?message=开始处理HTTP请求&amp;showBody=true&amp;maxBodyLength=500"/>
<to uri="http://0.0.0.0:18083/api/test?httpMethod=POST&amp;contentType=application/json&amp;bridgeEndpoint=true&amp;connectTimeout=5000&amp;socketTimeout=30000"/>
<to uri="servicelog:info?message=HTTP请求完成&amp;showBody=true&amp;maxBodyLength=5000"/>
Enter fullscreen mode Exit fullscreen mode

The second route handles /api/test and returns a fixed JSON payload for quick verification.

Minimal Validation with cURL 

curl -X POST "http://localhost:18083/api/httprequest/test" \
  -H "Content-Type: application/json" \
  -d "{\"orderId\":\"A1001\",\"amount\":199.9}"
Enter fullscreen mode Exit fullscreen mode

Expected behavior:

  • request enters http-request-route
  • route forwards to /api/test
  • response body returns {"message": "HTTP Response Test"}
  • request logs are visible through servicelog

Common Failures and How to Diagnose

1) API not reachable

Check:

  1. HTTP.Listener is true
  2. server.port is valid and not occupied
  3. startup logs include Undertow registration success

2) Port conflict

  • another process already binds the same port
  • release lifecycle did not clean previous context on hot reload

3) 405 or route miss

  • method is not in httpMethodRestrict
  • request path does not match route URI exactly

Practical Recommendations

  • Keep listener behavior configurable through properties, not hard-coded
  • Start with strict httpMethodRestrict to reduce invalid traffic
  • Add jsonResponseProcessor when multilingual JSON output is required
  • Keep one service-level log at route entry for observability and incident triage

Related Reading

Top comments (0)