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, 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.

tinystruct/tinystruct-netty-http-server

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Languages

Packages