tinystruct-patterns

# tinystruct Development Patterns Architecture and implementation patterns for building modules with the **tinystruct** Java framework – a lightweight, high-performance framework that treats CLI and HTTP as equal citizens, requiring no `main()` method and minimal configuration. ## Core Principle **CLI and HTTP are equal citizens.** A transport-neutral `@Action` uses `Mode.DEFAULT` (or omits `mode`) and has no HTTP-only dependencies. Such an action can run from both a terminal and a web browser. `Mode.DEFAULT` removes the transport restriction; it does not make an HTTP-dependent method CLI-compatible. `Request` and `Response` parameters come from HTTP context attributes and remain null when those attributes are absent, as in an ordinary CLI invocation. Keep shared logic independent of HTTP objects, sessions, and uploads, and call it from transport-specific entry points when needed. This "dual-mode" capability is the core design philosophy of tinystruct. An action with a transport-specific mode (`Mode.CLI`, `Mode.HTTP_GET`, `Mode.HTTP_POST`, ...) is deliberately bound to that transport: the framework rejects it from the other one with "The action is not allowed to be executed." ## Primary Development Tool: `bin/dispatcher` **`bin/dispatcher` is the default, highest-priority tool for developing, running, testing, and debugging a tinystruct application — reach for it before an IDE run configuration, a hand-written `main()`, curl, or a browser.** Because transport-neutral `@Action` methods are dual-mode by design, `bin/dispatcher` lets you exercise routing, argument binding, and business logic directly from the terminal, with the fastest possible feedback loop and no server/browser required. Actions bound to an HTTP method (`Mode.HTTP_POST`, `Mode.HTTP_GET`, ...) cannot be reached from `bin/dispatcher`; test those through an HTTP client against the running server. ```bash # Run a CLI-compatible @Action directly to verify a new action # (the class must be imported; see --import or default.import.applications in application.properties) bin/dispatcher greet/James --import com.example.MyService bin/dispatcher echo --words "Praise the Lord" # Start the HTTP server when you need the web-facing counterpart bin/dispatcher start --import org.tinystruct.system.HttpServer # Import additional Application/MCP classes for the current run # (one --import per class; a comma-separated list fails with ClassNotFoundException) bin/dispatcher start --import org.tinystruct.system.HttpServer --import com.example.MyService # Discover what's available bin/dispatcher --help bin/dispatcher --version ``` Default to this workflow: implement a transport-neutral `@Action`, run it immediately via `bin/dispatcher <action>` to confirm it behaves correctly in CLI mode, and only start the HTTP server (also via `bin/dispatcher start ...`) once you need to verify the web-facing path (e.g. `mode = Mode.HTTP_POST`, sessions, file uploads). For HTTP-only actions skip the CLI step and test them over HTTP; for `Mode.CLI` actions no server is needed. Never hardcode a `main(String[] args)` as an app's entry point — `bin/dispatcher` (or `bin/dispatcher.cmd` on Windows) is the one entry point for every module. ### Generating `bin/dispatcher` and `bin/dispatcher.cmd` Every tinystruct project needs its launcher in `bin/`. **The framework generates it — never write it by hand, and never copy it from another project or substitute a `main()`.** `ApplicationManager.init()` writes the launcher for the current operating system into `bin/` under the working directory whenever it is missing, from templates inside the tinystruct jar, with that jar's version filled in. Line endings and the executable bit are already right. **1. Find the tinystruct version** the project builds against: the `<tinystruct.version>` property or the `org.tinystruct:tinystruct` dependency in `pom.xml`. The jar must be reachable, in `~/.m2/repository/org/tinystruct/tinystruct/<version>/` (run `mvn dependency:resolve` if it is not) or in the project's `lib/`. **2. From the project root, run the framework once:** ```bash java -cp ~/.m2/repository/org/tinystruct/tinystruct/<version>/tinystruct-<version>.jar \ org.tinystruct.system.Dispatcher --version ``` Replace `<version>` with the version found in step 1. On Windows use `%USERPROFILE%\.m2\repository\org\tinystruct\tinystruct\<version>\tinystruct-<version>.jar` and the same class. This creates **only the script for the OS you ran it on**, and only if it is not already there: | Run on | Creates | |---|---| | Linux, macOS | `bin/dispatcher` (executable, LF) | | Windows | `bin\dispatcher.cmd` (CRLF) | **3. Verify.** From the project root run `bin/dispatcher --version` (Windows: `bin\dispatcher.cmd --version`). It prints `Dispatcher (cli) (built on tinystruct-<version>)`, and the `VERSION` inside the script equals the jar's version. Then `bin/dispatcher --help` lists the commands and every imported action. Show the user the file you created. **4. Get both scripts by running step 2 on each OS**, or let a teammate or CI on the other OS run it and commit the result. Commit both, so a checkout on either OS works. Do not try to fake the other OS with `-Dos.name=…`: on Windows it fails (`UnsupportedOperationException` from `setPosixFilePermissions`) and leaves an empty `bin/dispatcher`. Recommended `.gitattributes`, so a checkout does not corrupt the line endings: ``` bin/dispatcher text eol=lf bin/dispatcher.cmd text eol=crlf ``` **Upgrading tinystruct:** change the version in `pom.xml`, delete the old script, and repeat step 2 with the new jar. Alternatively `bin/dispatcher update` checks Maven Central for the latest release, upgrades the project's dependency and regenerates the script with force; it needs the network, edits the `pom.xml`, and goes to the *latest* version, not a chosen one. **It also happens implicitly.** Any code that reaches `ApplicationManager.init()` (the dispatcher itself, or `ApplicationManager.install(app, config)` in a unit test) creates the script in the *current directory* if it is missing. If unit tests scatter `bin/dispatcher.cmd` into module directories, run them from the build directory: in the surefire configuration set `<workingDirectory>${project.build.directory}</workingDirectory>`. **What the scripts do**, which explains most problems: - Run them **from the project root**: the shell script takes the current directory as the root, the `.cmd` takes the parent of `bin/`. - The classpath is `target/classes`, `lib/*.jar`, `WEB-INF/lib/*`, `WEB-INF/classes` and the tinystruct jar (from `lib/`, else `~/.m2`), then they run `org.tinystruct.system.Dispatcher` with your arguments. - On the first run, if `mvnw` / `mvnw.cmd` is missing, they extract the Maven Wrapper into the project root (`unzip` on Unix, PowerShell on Windows). Tell the user this happens; the files can be committed or ignored. - Only the shell script treats `-D…` and `-X…` arguments as JVM options. **Gotchas:** - **On Windows use `bin\dispatcher.cmd`.** The shell script joins the classpath with `:`, so under Git Bash/MSYS it fails with `ClassNotFoundException: org.tinystruct.system.Dispatcher`. Use WSL, or the `.cmd`. - **Only the tinystruct jar is on the classpath.** The framework no longer ships a fat jar by default, so your other modules, JDBC drivers and libraries (jjwt, lettuce, …) must be in `lib/`: `mvn dependency:copy-dependencies -DoutputDirectory=lib` (and git-ignore `lib/`). In a multi-module build, keep the launcher in the directory that holds `target/classes` and `lib/`, and copy the sibling modules' jars into that `lib/`; running it from a module whose siblings are not on its classpath fails with `NoClassDefFoundError`. - **Load applications with `--import` or configuration.** One `--import` per class (`--import a.A,b.B` fails; write `--import a.A --import b.B`), or list them once in `application.properties`: `default.import.applications=a.A;b.B` (`;`-separated). - **`JAVA_HOME` must be set** for the `.cmd`; it stops with an error otherwise. - **`bin/` sits directly under the directory that holds `target/classes` and `lib/`.** The `.cmd` treats the parent of `bin/` as the root, so a `bin/` nested in the wrong directory puts the wrong classpath in front of `Dispatcher`. ## When to Activate ### When to Use - Running, testing, or debugging any transport-neutral or `Mode.CLI` `@Action` via `bin/dispatcher` — this is the default way to work with a tinystruct app, before reaching for HTTP or an IDE run configuration. HTTP-only actions are tested over HTTP instead. - Setting up a project that has no `bin/dispatcher` / `bin/dispatcher.cmd` — have the framework generate it (see "Generating `bin/dispatcher` and `bin/dispatcher.cmd`"). - Creating new `Application` modules by extending `AbstractApplication`. - Defining routes and command-line actions using `@Action`. - Handling per-request state via `Context`. - Performing JSON serialization using the native `Builder` and `Builders` components. - Working with database persistence via `AbstractData` POJOs. - Generating POJOs from database tables using the `generate` command, with an XML mapping file or annotations (`--mapping annotation`). - Implementing Server-Sent Events (SSE) for real-time push. - Handling file uploads via multipart data. - Making outbound HTTP requests with `URLRequest` and `HTTPHandler`. - Configuring database connections or system settings in `application.properties`. - Debugging routing conflicts (Actions) or CLI argument parsing. ## How It Works The tinystruct framework treats any method annotated with `@Action` as a routable endpoint. Without a `mode`, dispatch is not restricted to one transport, but its parameters and implementation still need to support that environment. Ordinary CLI calls do not supply HTTP `Request` or `Response` objects. With `mode = Mode.CLI` or an HTTP mode such as `Mode.HTTP_POST`, dispatch is restricted to that transport. Applications are created by extending `AbstractApplication`, which provides core lifecycle hooks like `init()` and access to the request `Context`. Routing is handled by the `ActionRegistry`, which automatically maps path segments to method arguments and injects dependencies. For data-only services, the native `Builder` and `Builders` components should be used for JSON serialization to maintain a zero-dependency footprint. The database layer uses `AbstractData` POJOs mapped to tables with `@Table`/`@Column` annotations or XML mapping files for CRUD operations without external ORM libraries. Missing tables can be created automatically with `database.autocreate=true`. ## Examples ### Basic Application (MyService) ```java public class MyService extends AbstractApplication { @Override public void init() { this.setTemplateRequired(false); // Disable .view lookup for data/API apps } @Override public String version() { return "1.0.0"; } @Action("greet") public String greet() { return "Hello from tinystruct!"; } // Path parameter: GET /?q=greet/James OR bin/dispatcher greet/James @Action("greet") public String greet(String name) { return "Hello, " + name + "!"; } } ``` ### HTTP Mode Disambiguation (login) The limits below are example application policy measured in UTF-16 code units, not tinystruct defaults. Align them with your authentication service. Reject blank credentials without trimming or otherwise changing the values passed to authentication. ```java @Action(value = "login", mode = Mode.HTTP_POST) public String doLogin(Request<?, ?> request) throws ApplicationException { String username = request.getParameter("username"); String password = request.getParameter("password"); final int maxUsernameLength = 256; final int maxPasswordLength = 1024; if (username == null || password == null || username.length() > maxUsernameLength || password.length() > maxPasswordLength || username.isBlank() || password.isBlank()) { throw new ApplicationException("Invalid credentials"); } // AuthService is your application's own class, not part of tinystruct String userId = AuthService.getInstance().authenticate(username, password); // null on failure if (userId == null) { throw new ApplicationException("Invalid credentials"); } // Only touch the session after a successful authentication request.getSession().setAttribute("userId", userId); return "Logged in"; } ``` ### Native JSON Data Handling (Builder + Builders) ```java import org.tinystruct.data.component.Builder; import org.tinystruct.data.component.Builders; @Action("api/data") public String getData() throws ApplicationException { Builders dataList = new Builders(); Builder item = new Builder(); item.put("id", 1); item.put("name", "James"); dataList.add(item); Builder response = new Builder(); response.put("status", "success"); response.put("data", dataList); return response.toString(); // {"status":"success","data":[{"id":1,"name":"James"}]} } ``` ### SSE (Server-Sent Events) ```java import org.tinystruct.http.SSEPushManager; @Action("sse/connect") public String connect() { return "{\"type\":\"connect\",\"message\":\"Connected to SSE\"}"; } // Push to a specific client String sessionId = getContext().getId(); Builder msg = new Builder(); msg.put("text", "Hello, user!"); SSEPushManager.getInstance().push(sessionId, msg); // Broadcast to all // Broadcast to all SSEPushManager.getInstance().broadcast(msg); ``` ### File Upload ```java import org.tinystruct.data.FileEntity; @Action(value = "upload", mode = Mode.HTTP_POST) public String upload(Request<?, ?> request) throws ApplicationException { List<FileEntity> files = request.getAttachments(); if (files != null) { for (FileEntity file : files) { System.out.println("Uploaded: " + file.getFilename()); } } return "Upload OK"; } ``` ### Database Metadata Operations `DatabaseOperator` provides direct access to connection-level catalog, schema, and metadata: ```java import org.tinystruct.data.DatabaseOperator; DatabaseOperator operator = new DatabaseOperator(); try { String catalog = operator.getCatalog(); String schema = operator.getSchema(); java.sql.DatabaseMetaData metaData = operator.getMetaData(); System.out.println("Using catalog: " + catalog + ", schema: " + schema); } finally { operator.close(); } ``` ## MCP Server and Tools Integration tinystruct provides native support for the Model Context Protocol (MCP) starting with SDK version **`1.7.0`**. The MCP APIs (e.g., `org.tinystruct.mcp.MCPTool`, `org.tinystruct.mcp.MCPServer`, `org.tinystruct.mcp.MCPException`) are included directly in the core dependency: ```xml <dependency> <groupId>org.tinystruct</groupId> <artifactId>tinystruct</artifactId> <version>1.7.37</version> </dependency> ``` > **SECURITY WARNING (Prompt Injection):** > Tool return values are fed directly back into the AI model's context window. You **MUST** validate and sanitize all caller-supplied arguments before including them in the tool's return string. Failure to sanitize inputs can allow an attacker to inject adversarial instructions (Prompt Injection) that override the model's behavior. Always validate length, character sets, and nullity. **To create an MCP Tool:** 1. Extend `org.tinystruct.mcp.MCPTool`. 2. Annotate operations with `@Action` and declare parameters using `@Argument` within the `arguments` array. 3. Accept parameters as explicit method arguments matching the keys in `@Argument`. (Do **not** use `getContext().getAttribute(...)` for tool arguments). ```java import org.tinystruct.mcp.MCPTool; import org.tinystruct.mcp.MCPException; import org.tinystruct.system.annotation.Action; import org.tinystruct.system.annotation.Argument; public class MyCustomTool extends MCPTool { public MyCustomTool() { super("custom", "A custom tool for demonstrating MCP"); } @Action( value = "custom/hello", description = "Say hello to someone", arguments = {