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 (start action)
• Embedded Tomcat is configured with a default servlet for static assets and a Filter (DefaultHandler) that:
  • Initializes tinystruct ApplicationManager
  • Routes requests using the q parameter (e.g., /?q=say/Hello) or serves a default page configured via settings
  • Supports SSE when Accept: text/event-stream is present

Core classes:

• org.tinystruct.system.TomcatServer
• org.tinystruct.system.TomcatServer.DefaultHandler
• org.tinystruct.http.servlet.RequestBuilder
• org.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 to zh_CN unless overridden)
• system.directory (defaults to the current working directory)
• default.url_rewrite (enabled to use clean URLs; otherwise falls back to /?q=)
• default.home.page (default action when q is missing; e.g., say/Praise the Lord.)
• default.error.page (action to route errors; e.g., error)
• default.error.process (boolean; when false, forwards to default.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 current language setting)

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

Group: org.tinystruct Artifact: tinystruct-tomcat-server Version: 1.0.0

Support

• Website: https://tinystruct.org
• Repository SCM: https://github.com/tinystruct/tinystruct