tinystruct-tomcat-server
An embedded Tomcat server module for the tinystruct framework. It starts an embedded Tomcat (11.x), wires tinystruct's dispatcher as a Filter/Servlet, and serves dynamic actions via the q parameter as well as static assets from the working directory.
Features
- Embedded Tomcat 11.x (Jakarta Servlet 6.1)
- Tinystruct-powered request routing via
/?q=... - Static file serving from project root
- Server-Sent Events (SSE) support (including MCP SSE)
- Simple CLI bootstrap with configurable server port and proxy settings
Requirements
- Java 17+
- Maven 3.8+
Build
mvnw clean package
Artifacts:
target/tinystruct-tomcat-server-<version>-jar-with-dependencies.jar- Dependencies copied to
lib/(via maven-dependency-plugin)
Run
You can run via the provided dispatcher scripts (recommended) or manually with java.
Using dispatcher scripts
The bin/dispatcher (Unix) and bin/dispatcher.cmd (Windows) scripts bootstrap tinystruct actions from the CLI.
- Unix/macOS:
bin/dispatcher start --import org.tinystruct.system.TomcatServer --server-port 8080
- Windows (PowerShell or cmd):
bin\dispatcher.cmd start --import org.tinystruct.system.TomcatServer --server-port 8080
Flags you can pass through the CLI (examples):
--server-port 7777--http.proxyHost host --http.proxyPort 8080--https.proxyHost host --https.proxyPort 8443
When the server starts, it attempts to open the default browser at http://localhost:<port>.
Run manually with Java
After building the jar-with-dependencies:
java -cp target/tinystruct-tomcat-server-1.0.0-jar-with-dependencies.jar;lib/* org.tinystruct.application.Dispatcher start --import org.tinystruct.system.TomcatServer --server-port 8080
Note: On Unix-based shells, replace ; with : in the classpath.
How it works
- Entry point:
org.tinystruct.system.TomcatServer(startaction) - Embedded Tomcat is configured with a default servlet for static assets and a
Filter(DefaultHandler) that:- Initializes tinystruct
ApplicationManager - Routes requests using the
qparameter (e.g.,/?q=say/Hello) or serves a default page configured via settings - Supports SSE when
Accept: text/event-streamis present
- Initializes tinystruct
Core classes:
org.tinystruct.system.TomcatServerorg.tinystruct.system.TomcatServer.DefaultHandlerorg.tinystruct.http.servlet.RequestBuilderorg.tinystruct.http.servlet.ResponseBuilder
Configuration
Tinystruct Settings are read at startup. You can set these via your runtime environment or tinystruct configuration files. Relevant keys include:
-
default.file.encoding(e.g.,UTF-8) -
language(defaults tozh_CNunless overridden) -
system.directory(defaults to the current working directory) -
default.url_rewrite(enabledto use clean URLs; otherwise falls back to/?q=) -
default.home.page(default action whenqis missing; e.g.,say/Praise the Lord.) -
default.error.page(action to route errors; e.g.,error) -
default.error.process(boolean; when false, forwards todefault.error.page) -
ssl.enabled(boolean; toggles protocol in generated host URLs)
Proxy (optional via CLI context):
-
--http.proxyHost,--http.proxyPort -
--https.proxyHost,--https.proxyPort
Request routing
- Static files: served from the current working directory by the default servlet.
- Dynamic actions:
/?q=<namespace>/<action>handled by tinystruct. Example:http://localhost:8080/?q=say/Hello
- Language override:
?lang=en_US(applies if supported and different from currentlanguagesetting)
SSE (Server-Sent Events)
To initiate an SSE stream, send requests with Accept: text/event-stream and a q pointing to an SSE-capable tinystruct action.
For MCP SSE, q must equal the MCP endpoint (see MCPSpecification.Endpoints.SSE). The server selects MCPPushManager vs SSEPushManager automatically.
Development
- Source:
src/main/java - Tests:
src/test/java
Useful Maven commands:
mvnw -q -DskipTests package
mvnw test
License
Apache License 2.0. See LICENSE-2.0.txt.
Coordinates
<dependency>
<groupId>org.tinystruct</groupId>
<artifactId>tinystruct-tomcat-server</artifactId>
<version>1.0.4</version>
<version>1.0.3</version>
</dependency>
Support
- Website:
https://tinystruct.org - Repository SCM:
https://github.com/tinystruct/tinystruct
0 commit comments