|
| 1 | +# What's New in tinystruct 1.7.29 |
| 2 | + |
| 3 | +This document highlights the new features, security enhancements, performance improvements, and changes introduced in tinystruct version 1.7.29. |
| 4 | + |
| 5 | +> See also: [What's New in 1.7.23](whats-new-1.7.23.md) for earlier features including automated POJO generation and native `LocalDateTime` support. |
| 6 | +
|
| 7 | +--- |
| 8 | + |
| 9 | +## Highlights of 1.7.29 |
| 10 | + |
| 11 | +- **Asymmetric RSA & Configurable JWT Security**: Support for RSA public/private key pairs and flexible configuration via `application.properties`. |
| 12 | +- **Advanced HTTP Server Security & Host Filtering**: Host header restriction via `server.name`, robust path traversal prevention, environment-based error masking, and secure cookie handling. |
| 13 | +- **Decoupled Architecture & Domain Independence**: Removed hardcoded server domain dependencies from `HttpServer` and `SSEPushManager` for seamless multi-domain, containerized, and local development. |
| 14 | +- **Model Context Protocol (MCP) & AI Enhancements**: Support for overloaded tool methods, schema merging, idle session watchdogs, automatic cleanup, and enhanced error resiliency. |
| 15 | +- **Modern ANSI Console Logging & StackWalker Caller Tracing**: Color-coded console log formatting with zero-overhead, precise caller location resolution. |
| 16 | +- **Configurable HTTP Client Timeouts**: Connect and read timeout configurations on `URLRequest` and `HTTPHandler`. |
| 17 | +- **Dependency Upgrades**: Latest minor/patch updates for SQLite JDBC (3.53.2.1), JUnit Jupiter (6.1.1), JNA (5.19.1), and Apache Kafka (4.3.1). |
| 18 | + |
| 19 | +--- |
| 20 | + |
| 21 | +## Major New Features & Enhancements |
| 22 | + |
| 23 | +### 1. Asymmetric RSA & Configurable JWT Security |
| 24 | + |
| 25 | +The `JWTManager` now supports both symmetric HMAC keys and asymmetric RSA public/private key pairs, enabling enterprise-grade authentication topologies (e.g., signing tokens on an auth server with a private key and validating them on resource servers with a public key). |
| 26 | + |
| 27 | +#### RSA Key Pair Support in `JWTManager`: |
| 28 | +```java |
| 29 | +JWTManager jwtManager = new JWTManager(); |
| 30 | + |
| 31 | +// Sign using RSA Private Key (Base64 PKCS#8) |
| 32 | +jwtManager.withPrivateKey(base64PrivateKey); |
| 33 | +String token = jwtManager.createToken(builder); |
| 34 | + |
| 35 | +// Verify using RSA Public Key (Base64 X.509) |
| 36 | +jwtManager.withPublicKey(base64PublicKey); |
| 37 | +Map<String, Object> claims = jwtManager.verify(token); |
| 38 | +``` |
| 39 | + |
| 40 | +#### Declarative Configuration in `application.properties`: |
| 41 | +The built-in HTTP server automatically reads JWT configuration for Bearer token validation: |
| 42 | + |
| 43 | +```properties |
| 44 | +# Verify with RSA Public Key (Base64 X.509 format) |
| 45 | +jwt.key.public=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQE... |
| 46 | + |
| 47 | +# Or verify with HMAC Secret |
| 48 | +jwt.secret=your-256-bit-secret-key-here |
| 49 | +jwt.secret.format=plain # 'plain' or 'base64' (default) |
| 50 | + |
| 51 | +# Optional JWT validation timezone |
| 52 | +jwt.timezone=UTC |
| 53 | +``` |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +### 2. HTTP Server Security Controls & Host Filtering |
| 58 | + |
| 59 | +#### Host Header Validation (`server.name`): |
| 60 | +Prevent HTTP Host header attacks by restricting incoming requests to configured domain names or hostnames. |
| 61 | + |
| 62 | +```properties |
| 63 | +# Restrict requests to specified Host headers (comma-separated). Leave empty to allow all. |
| 64 | +server.name=localhost:8080, api.example.com, example.com |
| 65 | +``` |
| 66 | + |
| 67 | +#### Path Traversal Protection: |
| 68 | +Static resource resolution in `HttpServer` and `Dispatcher` has been fortified using `Path.normalize()` against base directory bounds checks to prevent unauthorized file access across all operating systems. |
| 69 | + |
| 70 | +#### Secure Cookies & Environment-Aware Error Responses: |
| 71 | +- Automatic `Secure` cookie flag assignment for HTTPS requests. |
| 72 | +- Server error messages automatically mask internal exception details in `production` while providing diagnostic information when `system.environment=development`. |
| 73 | + |
| 74 | +--- |
| 75 | + |
| 76 | +### 3. Model Context Protocol (MCP) & AI Integration Advancements |
| 77 | + |
| 78 | +The Model Context Protocol (MCP) implementation received substantial upgrades for enterprise AI tool exposure: |
| 79 | + |
| 80 | +- **Overloaded Tool Methods**: `MCPServer` now supports overloaded methods with identical action paths by merging input schemas and routing parameters dynamically. |
| 81 | +- **Session Watchdog & Idle Cleanup**: Integrated ping handler, keep-alive watchdog, and automatic session cleanup for disconnected AI clients. |
| 82 | +- **Direct POJO Registration**: Expose any POJO or service directly to AI models without having to inherit from `MCPTool`. |
| 83 | + |
| 84 | +```java |
| 85 | +public class CustomMCPServer extends MCPServer { |
| 86 | + @Override |
| 87 | + public void init() { |
| 88 | + super.init(); |
| 89 | + // Register any plain object directly |
| 90 | + this.registerTool(new CalculatorService()); |
| 91 | + } |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +--- |
| 96 | + |
| 97 | +### 4. ANSI Console Logging with StackWalker Tracing |
| 98 | + |
| 99 | +Logging has been upgraded with a high-performance programmatic formatter: |
| 100 | +- **ANSI Color Coding**: Distinct visual levels (INFO, WARNING, SEVERE, DEBUG). |
| 101 | +- **Precise Caller Tracing**: Utilizes Java 9+ `StackWalker` for zero-overhead, accurate source class, method name, and line number resolution. |
| 102 | +- **Default INFO Level**: Standard logging enabled by default with clean formatting. |
| 103 | + |
| 104 | +--- |
| 105 | + |
| 106 | +### 5. Configurable HTTP Client Timeouts & Browser Automation |
| 107 | + |
| 108 | +- **`URLRequest` & `HTTPHandler` Timeouts**: Added explicit `connectTimeout` and `readTimeout` methods. |
| 109 | + ```java |
| 110 | + URLRequest request = new URLRequest(new URL("https://api.example.com/data")) |
| 111 | + .setConnectTimeout(5000) // 5 seconds |
| 112 | + .setReadTimeout(10000); // 10 seconds |
| 113 | + ``` |
| 114 | +- **Open-Browser Integration**: Configure the HTTP server to automatically open the default browser on launch via `server.openbrowser=true` and `server.openbrowser.command`. |
| 115 | + |
| 116 | +--- |
| 117 | + |
| 118 | +### 6. Dependency Upgrades |
| 119 | + |
| 120 | +| Library | Previous Version | New Version (1.7.29) | |
| 121 | +|---|---|---| |
| 122 | +| **SQLite JDBC** | 3.45.1.0 | `3.53.2.1` | |
| 123 | +| **JUnit Jupiter** | 5.10.2 | `6.1.1` | |
| 124 | +| **JNA** | 5.14.0 | `5.19.1` | |
| 125 | +| **Apache Kafka** | 3.7.0 | `4.3.1` | |
| 126 | +| **Maven Assembly Plugin** | 2.2-beta-5 | `3.7.1` | |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | +## Migration Guide |
| 131 | + |
| 132 | +### Updating to 1.7.29 |
| 133 | + |
| 134 | +Update your `pom.xml` dependency to version `1.7.29`: |
| 135 | + |
| 136 | +```xml |
| 137 | +<dependency> |
| 138 | + <groupId>org.tinystruct</groupId> |
| 139 | + <artifactId>tinystruct</artifactId> |
| 140 | + <version>1.7.29</version> |
| 141 | +</dependency> |
| 142 | +``` |
| 143 | + |
| 144 | +#### JWT Secret Configuration |
| 145 | +If you use plain text secrets in `application.properties`, specify `jwt.secret.format=plain`: |
| 146 | + |
| 147 | +```properties |
| 148 | +jwt.secret=my-plain-text-secret-key |
| 149 | +jwt.secret.format=plain |
| 150 | +``` |
| 151 | + |
| 152 | +--- |
| 153 | + |
| 154 | +## Community and Resources |
| 155 | + |
| 156 | +- **GitHub Repository**: <https://github.com/tinystruct/tinystruct> |
| 157 | +- **Official Documentation**: <https://tinystruct.org> |
| 158 | +- **Examples**: <https://github.com/tinystruct/tinystruct-examples> |
| 159 | +- **Project Archetype**: <https://github.com/tinystruct/tinystruct-archetype> |
0 commit comments