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
<dependency>
<groupId>org.tinystruct</groupId>
<artifactId>tinystruct-netty-http-server</artifactId>
<version>1.0.3</version>
</dependency>
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,
HttpRequestHandlertreats 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-streamAccept header; integrates with tinystructApplicationManager - MCP (Message Channel Protocol) support via
MCPPushManagerwhen route equalsMCPSpecification.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.secretto validate Bearer tokens; unauthenticated requests without a token are allowed by default. - Sessions: A
JSESSIONIDcookie is set when absent; session id comes from tinystruct context. - CORS/Headers: Customize in
HttpRequestHandlerif needed.
License
Apache License 2.0. See LICENSE-2.0.txt.
0 commit comments