tinystruct-netty-http-server

A Netty-based HTTP server and HTTP proxy module for the tinystruct framework. It provides:

• Netty-powered HTTP server (org.tinystruct.system.NettyHttpServer) with static file serving, JWT-aware request handling, SSE support, and tinystruct action routing.
• Simple HTTP reverse proxy (org.tinystruct.system.HttpProxyServer).

Requirements

• Java 17+
• Maven 3.8+
• OS: Windows, macOS, Linux

Build

mvnw -q -DskipTests package

Artifacts:

• Application JARs under target/
• Helper scripts under bin/ (dispatcher, dispatcher.cmd)
• Libraries under lib/

Quick start

Start the HTTP server on port 8080 and open the browser automatically:

• Unix/macOS:

bin/dispatcher start --import org.tinystruct.system.NettyHttpServer --server-port 8080

• Windows PowerShell:

bin\dispatcher.cmd start --import org.tinystruct.system.NettyHttpServer --server-port 8080

Then visit http://localhost:8080.

Running the HTTP proxy

Forward traffic from local port 81 to a remote server (default localhost:80):

• Unix/macOS:

bin/dispatcher start --import org.tinystruct.system.HttpProxyServer --server-port 81 --remote-server-host example.com --remote-server-port 80

• Windows PowerShell:

bin\dispatcher.cmd start --import org.tinystruct.system.HttpProxyServer --server-port 81 --remote-server-host example.com --remote-server-port 80

If --remote-server-port 443 is specified, a self-signed SSL context is created for inbound TLS.

Configuration

Edit src/main/resources/application.properties (values can also be overridden via CLI where supported):

• default.file.encoding: Default file.encoding (e.g., UTF-8)
• default.home.page: Default action when no route is provided (e.g., say/Praise the Lord!)
• default.reload.mode: Enable/disable reload mode
• default.date.format: Date format pattern
• default.error.process: Enable custom error processing
• default.error.page: Action to render on error
• default.http.max_content_length: Max request size in bytes
• system.directory: Working directory (defaults to user.dir)
• logging.enabled: Enable Netty channel logging (true/false)
• logging.level: TRACE, DEBUG, INFO, WARN, ERROR
• jwt.secret: Secret for JWT verification when Authorization: Bearer is provided
• ssl.enabled: When true, HttpRequestHandler treats connections as secure for URL building

Database placeholders (optional): driver, database.url, database.user, database.password, database.connections.max (H2/MySQL/sqlite/SQLServer supported via tinystruct integrations).

Messaging/SSE:

• SSE endpoint support via text/event-stream Accept header; integrates with tinystruct ApplicationManager
• MCP (Message Channel Protocol) support via MCPPushManager when route equals MCPSpecification.Endpoints.SSE

CLI options

Netty HTTP server (org.tinystruct.system.NettyHttpServer):

• --server-port : Port to listen on (default 8080)
• --http.proxyHost , --http.proxyPort
• --https.proxyHost , --https.proxyPort
• --logging.enabled <true|false>
• --logging.level <TRACE|DEBUG|INFO|WARN|ERROR>

HTTP proxy (org.tinystruct.system.HttpProxyServer):

• --server-port : Local listen port (default 81)
• --remote-server-host : Upstream host (default localhost)
• --remote-server-port : Upstream port (default 80; 443 enables self-signed TLS)

Static files

Static files are served by org.tinystruct.handler.HttpStaticFileHandler. Place assets under your working directory; configure system.directory if needed.

Routing and actions

Requests are routed through tinystruct’s ApplicationManager using the query (e.g., /say/Hello or /?q=say/Hello when default.url_rewrite is not enabled). The default home action is controlled by default.home.page.

Logging

Enable Netty pipeline logging via configuration or CLI:

bin/dispatcher start --import org.tinystruct.system.NettyHttpServer --logging.enabled true --logging.level INFO

Development tips

• JWT: Set jwt.secret to validate Bearer tokens; unauthenticated requests without a token are allowed by default.
• Sessions: A JSESSIONID cookie is set when absent; session id comes from tinystruct context.
• CORS/Headers: Customize in HttpRequestHandler if needed.

License

Apache License 2.0. See LICENSE-2.0.txt.