mm-springboot

Spring Boot Starter for MetaMessage - structured data exchange protocol.

Features

• Wire Binary HTTP Converter (application/x-metamessage) - High-performance binary encoding/decoding
• JSONC HTTP Converter (application/jsonc) - Human-readable format with comments support
• @MMParam Annotation - Easy parameter binding for Controller methods
• DataBinder Converter - Auto-convert JSONC strings to objects in Spring DataBinder
• Auto-configuration - Zero-config setup, works out of the box

Quick Start

1. Add Dependency

// Gradle Kotlin DSL
implementation("com.github.metamessage:mm-springboot:0.1.0")

For now, you can use JitPack:

repositories {
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    implementation("com.github.metamessage:mm-springboot:0.1.0")
}

2. Define Your Model

import io.github.metamessage.MM
import io.github.metamessage.ir.ValueType

@MM(desc = "User entity")
class User(
    @MM(desc = "User name", type = ValueType.STRING)
    var name: String = "",

    @MM(type = ValueType.INT32, desc = "User age")
    var age: Int = 0
)

3. Use in Controller

@RestController
class UserController {

    // Wire binary request/response
    @PostMapping("/api/users", consumes = ["application/x-metamessage"], produces = ["application/x-metamessage"])
    fun createUser(@RequestBody user: User): User {
        return user
    }

    // JSONC request/response
    @PostMapping("/api/users/jsonc", consumes = ["application/jsonc"], produces = ["application/jsonc"])
    fun createUserJsonc(@RequestBody user: User): User {
        return user
    }

    // @MMParam annotation
    @PostMapping("/api/users/param")
    fun createWithParam(@MMParam @RequestBody user: User): User {
        return user
    }
}

Configuration

metamessage:
  enabled: true
  wire-converter-enabled: true    # Wire binary converter
  jsonc-converter-enabled: true   # JSONC converter
  argument-resolver-enabled: true  # @MMParam resolver
  converter-enabled: true        # DataBinder converter
  wire-order: -1                  # Converter priority (lower = higher priority)
  jsonc-order: 0

Examples

See the examples/kotlin directory for a complete Spring Boot application example.

Running the Example

cd examples/kotlin
./gradlew bootRun

Example Endpoints

Method	Endpoint	Content-Type	Description
POST	/api/users	application/x-metamessage	Create user (Wire binary)
GET	/api/users/{id}	application/x-metamessage	Get user (Wire binary)
POST	/api/users/jsonc	application/jsonc	Create user (JSONC)
GET	/api/users/jsonc/{id}	application/jsonc	Get user (JSONC)
POST	/api/users/param	application/x-metamessage	Create user with @MMParam
POST	/api/users/profile	application/x-metamessage	Create user profile (nested)

Example JSONC Request

{
    // mm: desc=User name
    "name": "Alice",
    // mm: type=i32; desc=User age
    "age": 30
}

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Spring Boot Application                   │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐    ┌──────────────────────────────────┐  │
│  │  Controller  │───▶│  MetaMessageArgumentResolver     │  │
│  └──────────────┘    └──────────────────────────────────┘  │
│                              │                               │
│  ┌──────────────┐            ▼                               │
│  │  HttpMessage │    ┌──────────────────────────────────┐  │
│  │  Converters  │◀──▶│     MetaMessageCodec             │  │
│  └──────────────┘    └──────────────────────────────────┘  │
│                              │                               │
│                              ▼                               │
│                     ┌──────────────────┐                    │
│                     │  mm-kt Library   │                    │
│                     │  (metamessage)    │                    │
│                     └──────────────────┘                    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Dependencies

• Kotlin 1.9.22+
• Spring Boot 3.2.5+
• Java 17+

License

MIT