rpcgen

Rpcgen

Upstream: https://github.com/vmkteam/rpcgen

Генерирует типизированные клиенты из SMD (Service Mapping Description) zenrpc-сервера. Связанный инструмент — rpcdiff (diff OpenRPC schema для breaking-changes в CI).

Tool-зависимость:

tool github.com/vmkteam/rpcgen/v2/cmd/rpcgen

Языки и API

gen.GoClient, gen.TSClient, gen.PHPClient, gen.SwiftClient, gen.KotlinClient, gen.DartClient, gen.OpenRPC(name, url).

CLI — через -lang <go|typescript|php|swift|kotlin|dart>, источник -url (SMD endpoint) или -file smd.json, вывод -o. Полный список флагов — rpcgen --help.

vmkteam-паттерн: on-the-fly handler

Сервер раздаёт клиенты с собственных endpoint'ов через rpcgen.Handler:

a.echo.Any("/v1/rpc/api.ts",   appkit.EchoHandlerFunc(rpcgen.Handler(gen.TSClient(typeMapper))))
a.echo.Any("/v1/rpc/api.go",   appkit.EchoHandlerFunc(rpcgen.Handler(gen.GoClient(golang.Settings{Package: appName}))))
a.echo.Any("/v1/rpc/api.swift",     appkit.EchoHandlerFunc(rpcgen.Handler(gen.SwiftClient(swift.Settings{Class: "API", TypeMapper: swiftTypeMapper}))))
a.echo.Any("/v1/rpc/networking.swift", appkit.EchoHandlerFunc(rpcgen.Handler(gen.SwiftClient(swift.Settings{IsProtocol: true, TypeMapper: swiftTypeMapper}))))
a.echo.Any("/v1/rpc/api.kt",        appkit.EchoHandlerFunc(rpcgen.Handler(gen.KotlinClient(kotlin.Settings{Class: "Api", PackageAPI: "com.example.api", TypeMapper: kotlinTypeMapper}))))
a.echo.Any("/v1/rpc/networking.kt", appkit.EchoHandlerFunc(rpcgen.Handler(gen.KotlinClient(kotlin.Settings{Class: "Api", PackageAPI: "com.example.api", IsProtocol: true}))))
a.echo.Any("/v1/rpc/openrpc.json",  appkit.EchoHandlerFunc(rpcgen.Handler(gen.OpenRPC("service", rpcUrl))))

• IsProtocol: true для Swift/Kotlin → protocol/interface вместо class/data class
• TypeMapper func(schema, current) string — переопределение типов per-язык

Makefile-цели (vmkteam-конвенция)

go-client:
	rpcgen -lang go -url http://localhost:$(PORT)/rpc/ -o ./pkg/client/$(NAME)/

type-script-client: generate
	rpcgen -lang typescript -url http://localhost:$(PORT)/rpc/ -o ../frontend/src/api/factory.generated.ts
	rpcgen -lang typescript -url http://localhost:$(PORT)/vt/ -o ../frontend/src/api/vt.generated.ts

Gotchas

• TS: после генерации добавить // @ts-nocheck на 3-ю строку (после /* eslint-disable */), иначе frontend не собирается
• Go-клиенты импортируются как project/pkg/client/<service>, инициализация svc.New("http://host/rpc/")
• rpcdiff old.json new.json — сравнение OpenRPC schema, полезно перед деплоем
• Клиент сервиса из того же модуля (CLI, SDK) — тоже pkg/client/<service>/, не рядом с потребителем

Известные баги (rpcgen ≤ v2.5.7)

Убрать раздел, когда исправят upstream: #42.

• Go-клиент теряет ошибку сервера. Для кодов, описанных в //zenrpc:<код>, сгенерированный метод заменяет *zenrpc.Error пакетной переменной ErrSvcMethodNNN с текстом из комментария: message и data ответа теряются, errors.As их не достанет. Сравнение errors.Is(err, client.ErrSvcMethodNNN) работает. Нужна подсказка из data (причина, hint) — http.RoundTripper клиента читает тело ответа с ошибкой, сохраняет error.data и возвращает тело дальше (образец — hubsrv pkg/cli/client.go).

Маркер

// Code generated by rpcgen; DO NOT EDIT.