rs-zero 0.2.12

Rust-first microservice framework inspired by go-zero engineering practices
Documentation
# API DSL support

`rzcli api` supports a practical go-zero-style `.api` subset for Rust-first REST
generation. The compatibility target is input semantics and workflow
compatibility, not byte-for-byte goctl output.

## Supported syntax

```go
syntax = "v1"

import "common/types.api"

type Request {
    Name string `path:"name"`
}

type Response {
    Message string `json:"message"`
}

type EventMessage {
    Message string `json:"message"`
}

service hello-api {
    @handler PingHandler
    head /health

    @handler GreetHandler
    get /hello/:name(Request) returns (Response)
}

@server(
    group: admin
    prefix: /api/v1
    middleware: trace,auth
    jwt: Auth
)
service hello-api {
    @handler ProfileHandler
    get /profile returns (Response)
}

@server(
    group: stream
    prefix: /events
    sse: true
)
service hello-api {
    @handler EventsHandler
    get /feed returns (EventMessage)
}
```

Supported route methods: `get`, `post`, `put`, `delete`, `patch`, `head`.

Supported route forms:

- `get /ping`
- `get /ping returns (Response)`
- `get /ping(Request)`
- `get /ping(Request) returns (Response)`

Supported request field tags: `path`, `query`, `header`, `form`, `json`, `body`.

## Service blocks

A parsed root `.api` file can contain multiple `service <name> { ... }` blocks.
This is the recommended way to split public routes, JWT-protected routes,
prefix/group routes and SSE routes while keeping one generated Rust service.
All service blocks in one root spec must use the same service name; mixed service
names fail validation.

Each service block owns its own `@server` metadata:

- `group`: exported as the OpenAPI operation tag.
- `prefix`: applied to generated router paths and OpenAPI paths.
- `middleware`: parsed and preserved by formatter and OpenAPI metadata.
- `jwt`: enables generated JWT configuration and wraps only that service block's routes.
- `jwtTransition`: parsed and preserved; automatic dual-secret validation is not enabled yet.
- `sse: true`: marks every route in the block as an SSE streaming endpoint.

## CLI

```bash
rzcli api validate -f hello.api
rzcli api format -f hello.api -o hello.formatted.api
rzcli api openapi -f hello.api -o openapi.json
rzcli api gen -f hello.api -d ./target/generated
```

Generation refuses to overwrite existing files unless `--force` is passed. For
existing projects, `api gen --dry-run` shows the create/update/skip/conflict
plan before writing files.

## REST generation

`rzcli api gen` generates a Rust REST project with `handler` / `logic` layers,
DTOs, router, `main.rs`, config and metrics wiring.

Handler request extractors are selected from request tags:

- `path` -> `axum::extract::Path`.
- `query` or `form` -> `axum::extract::Query`.
- otherwise -> `axum::Json`.
- no route request -> no handler argument.

When any service block has `@server(jwt: Auth)`, the generated router takes an
`AuthConfig`. JWT middleware is applied per service block: routes in JWT blocks
are protected, and routes in public blocks are left public. Generated config
uses `[auth].jwt_secret` / `[auth].jwt_expires`, with `JWT_AUTH_SECRET` and
`JWT_AUTH_EXPIRES` taking precedence.

## SSE streaming generation

Routes inside `@server(sse: true)` blocks generate Axum SSE handlers instead of
`ApiResponse<T>` handlers. The generated handler returns `impl IntoResponse` and
uses `Sse::new(stream).keep_alive(...)`.

The generated logic method returns a `ReceiverStream<Result<Event, Infallible>>`
and uses `tokio::sync::mpsc` plus `tokio_stream::wrappers::ReceiverStream`:

- `mpsc::channel(16)` creates a bounded stream boundary.
- a spawned task sends `Event` values into the channel.
- `ReceiverStream::new(rx)` exposes the receiver as the SSE body stream.
- `returns (EventMessage)` means `EventMessage` is the `.api` response type used
  as the JSON event payload.
- an SSE route without `returns (...)` emits a starter `data("tick")` event.

Generated SSE projects add `tokio-stream = "0.1"` and enable Tokio `time`.
The emitted loop is a working starter skeleton; real services should replace the
default payload/tick loop with domain events, cancellation and backpressure rules.

## OpenAPI export

`rzcli api openapi` iterates every service block, applies each block's `prefix`
and `group`, exports `head` operations and maps SSE responses to
`text/event-stream`. Non-SSE responses use `application/json`.

## Current limits

- Full goctl grammar coverage is not promised.
- All service blocks in one root spec must share the same service name.
- Generated custom middleware chains from `@server(middleware: ...)` are not wired yet.
- `jwtTransition` is parsed and formatted, but automatic dual-secret validation is not generated yet.
- SSE skeletons are starter implementations; production stream lifecycle and domain events remain application logic.