connect2axum 0.1.0

Runtime helpers for generated REST and WebSocket wrappers over ConnectRPC services
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# connect2axum [![Crate](https://img.shields.io/crates/v/connect2axum)](https://crates.io/crates/connect2axum) [![Docs](https://docs.rs/connect2axum/badge.svg)](https://docs.rs/connect2axum) [![Build](https://github.com/nu11ptr/connect2axum/workflows/CI/badge.svg)](https://github.com/nu11ptr/connect2axum/actions) [![License](https://img.shields.io/crates/l/connect2axum)](https://github.com/nu11ptr/connect2axum/blob/main/LICENSE)

Generate REST and/or WebSocket endpoint wrappers over ConnectRPC services.
Additionally, generate OpenAPI docs for REST endpoints and AsyncAPI docs for
WebSocket endpoints.

## Install

```sh
cargo install --locked connect2axum-codegen
```

This installs:

- `protoc-gen-connect2rest`
- `protoc-gen-connect2ws`
- `protoc-gen-connect2openapi`
- `protoc-gen-connect2asyncapi`

## Plugin Options

Options are passed as comma-separated `name=value` pairs in `buf.gen.yaml`.

```yaml
plugins:
  - local: protoc-gen-connect2rest
    out: src/generated/connect2axum
    opt:
      - buffa_module=crate::proto
      - connect_module=crate::connect
  - local: protoc-gen-connect2ws
    out: src/generated/connect2axum
    opt:
      - buffa_module=crate::proto
      - connect_module=crate::connect
  - local: protoc-gen-connect2openapi
    out: src/generated/openapi
    strategy: all
    opt:
      - config=connect2openapi.yaml
  - local: protoc-gen-connect2asyncapi
    out: src/generated/asyncapi
    strategy: all
    opt:
      - config=connect2asyncapi.yaml
```

### Active Options

| Option | Default | Used By | Purpose |
| --- | --- | --- | --- |
| `buffa_module` | `crate::proto` | REST, WS | Rust module root where Buffa generated messages are available. |
| `connect_module` | `crate::connect` | REST, WS | Rust module root where Connect Rust generated service traits are available. |
| `runtime_module` | `::connect2axum` | REST, WS | Rust path to the runtime helper crate/module. |
| `streaming_content_type` | `application/x-ndjson` | REST | REST streaming response content type. |
| `value_suffix` | `__` | REST, WS | Suffix for generated local bindings to avoid collisions with request fields. |
| `type_suffix` | `__` | REST | Suffix for generated DTO type names. |
| `body_message_suffix` | `Body` | REST | Suffix for generated body DTOs. |
| `query_message_suffix` | `Query` | REST | Suffix for generated query DTOs. |

### OpenAPI Generator

`protoc-gen-connect2openapi` wraps grpc-gateway's
`protoc-gen-openapiv3`, then patches the generated document for connect2axum
REST behavior. It supports `output`, `config`, `openapiv3_bin`,
`openapiv3_opt`, and `streaming_content_type` plugin options.

See [docs/openapi-generator.md](docs/openapi-generator.md) for config format
and backend details.

### AsyncAPI Generator

`protoc-gen-connect2asyncapi` emits AsyncAPI v3.1 JSON for the JSON WebSocket
routes generated by `protoc-gen-connect2ws`. It supports `output`, `config`,
`server_url`, and `default_content_type` plugin options.

See [docs/asyncapi-generator.md](docs/asyncapi-generator.md) for document shape
and config details.

### WebSocket Notes

`protoc-gen-connect2ws` only generates JSON WebSocket routes for streaming RPCs.
Unary RPCs stay REST/Connect-only. Client and bidirectional request streams end
with an empty text frame so the socket can remain open for any response frames.