README
¶
Package endpoint
Пакет endpoint предоставляет инструменты для создания gRPC-обработчиков с автоматической сериализацией JSON,
валидацией запросов, middleware-цепочками и интеграцией метрик/логирования. Реализует паттерн "Endpoint" для изоляции
бизнес-логики от транспортного слоя.
Types
Wrapper
Основная структура для создания цепочек обработки запросов. Объединяет:
- Маппинг параметров
- Middleware (логирование, метрики, восстановление после паник)
- Сериализацию/валидацию JSON
Methods:
NewWrapper(paramMappers []ParamMapper, bodyExtractor RequestBodyExtractor, bodyMapper ResponseBodyMapper) Wrapper
Создает конфигурацию для обработчиков.
Параметры:
paramMappers– правила извлечения параметров из контекста/метаданныхbodyExtractor– десериализация и валидация тела запросаbodyMapper– сериализация ответа
(m Wrapper) Endpoint(f any) grpc.HandlerFunc
Преобразует пользовательскую функцию в gRPC-обработчик.
Функция f может содержать параметры:
context.Contextgrpc.AuthData(метаданные аутентификации)- Пользовательский тип (десериализуется из JSON-тела)
(m Wrapper) WithMiddlewares(middlewares ...grpc.Middleware) Wrapper
Добавляет middleware в цепочку обработки.
Caller
Внутренняя структура для вызова пользовательских обработчиков. Автоматически:
- Извлекает параметры
- Вызывает middleware
- Обрабатывает ошибки
Methods:
NewCaller(f any,bodyExtractor RequestBodyExtractor, bodyMapper ResponseBodyMapper, paramMappers map[string]ParamMapper) (*Caller, error)
Создает экземпляр Caller для функции-обработчика.
(h *Caller) Handle(ctx context.Context, message *isp.Message) (*isp.Message, error)
Вызывает функцию-обработчик, передавая ей аргументы, извлеченные из запроса.
JsonRequestExtractor
Реализация интерфейса RequestBodyExtractor для работы с JSON. Валидирует данные с помощью объекта, реализующего
интерфейс Validator.
Methods:
(j JsonRequestExtractor) Extract(ctx context.Context, message *isp.Message, reqBodyType reflect.Type) (reflect.Value, error)
Десериализует и валидирует JSON-тело запроса через Validator.
JsonResponseMapper
Сериализует ответ обработчика в JSON-тело gRPC-сообщения.
Methods:
(j JsonResponseMapper) Map(result any) (*isp.Message, error)
Конвертирует результат обработчика в gRPC-сообщение в формате JSON.
Functions
DefaultWrapper(logger log.Logger, restMiddlewares ...grpc.Middleware) Wrapper
Создает предварительно настроенную обертку (Wrapper) для gRPC-обработчиков с базовыми middleware и параметрами.
Упрощает создание эндпоинтов, включая валидацию, логирование, метрики и обработку ошибок "из коробки".
Стандартные middleware:
RequestId– добавляет в контекст requestId, который берет из заголовка x-request-id. Генерирует новый, если не находит.Metrics– собирает метрики: время выполнения, статусы, размеры тел.Tracing– интеграция с трейсингом (OpenTelemetry).ErrorHandler– перехватывает и обрабатывает ошибки. Ошибки типаGrpcErrorвозвращают структурированный ответ. Остальные ошибки логируются и возвращаются как Internal Server Error с gRPC-кодом 13.Recovery– предотвращает падение сервера при панике в обработчике, преобразуя ее в ошибку.
Usage
Default usage flow
package main
import (
"context"
"log"
"github.com/txix-open/isp-kit/grpc"
"github.com/txix-open/isp-kit/grpc/endpoint"
log2 "github.com/txix-open/isp-kit/log"
"github.com/txix-open/isp-kit/shutdown"
)
type getUserRequest struct {
Id string
}
type user struct {
Id string
Name string
}
func getUser(ctx context.Context, authData grpc.AuthData, req getUserRequest) (*user, error) {
appId, _ := authData.ApplicationId()
log.Printf("Request from app with id %d", appId)
/* put here business logic */
return &user{Id: req.Id, Name: "Alice"}, nil
}
func main() {
logger, err := log2.New()
if err != nil {
log.Fatal(err)
}
mux := grpc.NewMux()
wrapper := endpoint.DefaultWrapper(logger)
mux.Handle("/get_user", wrapper.Endpoint(getUser))
srv := grpc.DefaultServer()
srv.Upgrade(mux)
shutdown.On(func() { /* waiting for SIGINT & SIGTERM signals */
log.Println("shutting down...")
srv.Shutdown()
log.Println("shutdown completed")
})
err = srv.ListenAndServe(":8080")
if err != nil {
log.Fatal(err)
}
}
Documentation
¶
Overview ¶
Package endpoint provides a higher-level abstraction for building gRPC handlers. It enables reflection-based function wrapping with automatic request/response marshaling, parameter injection, and middleware support.
The package integrates with the ISP kit framework's logging, metrics, and validation systems for comprehensive observability and error handling.
Index ¶
- func ErrorHandler(logger log.Logger) grpc.Middleware
- func Metrics(storage MetricStorage) grpc.Middleware
- func Recovery() grpc.Middleware
- func RequestId() grpc.Middleware
- type Caller
- type GrpcError
- type JsonRequestExtractor
- type JsonResponseMapper
- type MetricStorage
- type ParamBuilder
- type ParamMapper
- type RequestBodyExtractor
- type ResponseBodyMapper
- type Validator
- type Wrapper
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ErrorHandler ¶
func ErrorHandler(logger log.Logger) grpc.Middleware
ErrorHandler creates a middleware that handles errors from downstream handlers. Logs errors at appropriate levels, enriches them with Sentry context, and converts custom GrpcError types to gRPC status errors. Returns a generic "internal service error" for unknown error types to prevent information leakage.
func Metrics ¶
func Metrics(storage MetricStorage) grpc.Middleware
Metrics creates a middleware that collects metrics for gRPC server requests. Records request duration, request/response body sizes, and response status codes. The endpoint name is extracted from the ProxyMethodNameHeader in request metadata.
func Recovery ¶
func Recovery() grpc.Middleware
Recovery creates a middleware that catches panics and converts them to errors. Prevents gRPC server crashes from handler panics by recovering and returning the error.
func RequestId ¶
func RequestId() grpc.Middleware
RequestId creates a middleware that manages request IDs for tracing. Extracts the request ID from incoming metadata, generates a new one if absent, and injects it into the context for downstream use.
Types ¶
type Caller ¶
type Caller struct {
// contains filtered or unexported fields
}
Caller wraps a function for gRPC invocation using reflection. It analyzes the function signature, injects dependencies, and handles request/response marshaling automatically.
func NewCaller ¶
func NewCaller( f any, bodyExtractor RequestBodyExtractor, bodyMapper ResponseBodyMapper, paramMappers map[string]ParamMapper, ) (*Caller, error)
NewCaller creates a new Caller for the specified function. Analyzes the function signature to determine parameter types and return values. Returns an error if the input is not a function or if parameter types cannot be resolved.
type GrpcError ¶
type GrpcError interface {
GrpcStatusError() error
}
GrpcError is an interface for errors that can be converted to gRPC status errors. Implementations should return a gRPC status error with appropriate details.
type JsonRequestExtractor ¶
type JsonRequestExtractor struct {
Validator Validator
}
JsonRequestExtractor extracts and validates JSON request bodies from gRPC messages. Unmarshals the message body into the target type and validates it using the configured validator.
func (JsonRequestExtractor) Extract ¶
func (j JsonRequestExtractor) Extract(ctx context.Context, message *isp.Message, reqBodyType reflect.Type) (reflect.Value, error)
Extract unmarshals the message body as JSON and validates it. Returns a reflect.Value of the created instance or an error if unmarshaling or validation fails. Business validation errors are returned as apierrors.BusinessError with code 400.
type JsonResponseMapper ¶
type JsonResponseMapper struct{}
JsonResponseMapper maps handler results to gRPC messages with JSON-encoded bodies. Implements the ResponseBodyMapper interface.
type MetricStorage ¶
type MetricStorage interface {
// ObserveDuration records the duration of a request for the given method.
ObserveDuration(method string, duration time.Duration)
// ObserveRequestBodySize records the size of the request body.
ObserveRequestBodySize(method string, size int)
// ObserveResponseBodySize records the size of the response body.
ObserveResponseBodySize(method string, size int)
// CountStatusCode increments the counter for the given endpoint and status code.
CountStatusCode(endpoint string, code codes.Code)
}
MetricStorage defines the interface for collecting gRPC server metrics. Implementations should record request durations, payload sizes, and response codes.
type ParamBuilder ¶
ParamBuilder defines a function that builds a parameter value from context and message. Used by ParamMapper to inject dependencies like context, auth data, etc.
type ParamMapper ¶
type ParamMapper struct {
// Type is the string representation of the parameter type.
Type string
// Builder is the function that creates the parameter value.
Builder ParamBuilder
}
ParamMapper maps a parameter type string to a builder function. Used to inject dependencies into handler functions automatically.
func AuthDataParam ¶
func AuthDataParam() ParamMapper
AuthDataParam creates a ParamMapper for injecting grpc.AuthData into handlers. Extracts authentication and authorization information from the incoming request metadata. Returns an error if metadata is not present in the context.
func ContextParam ¶
func ContextParam() ParamMapper
ContextParam creates a ParamMapper for injecting context.Context into handlers. The context is passed through from the incoming gRPC request context.
type RequestBodyExtractor ¶
type RequestBodyExtractor interface {
// Extract unmarshals the message body into an instance of reqBodyType.
// Returns the reflect.Value of the created instance and any unmarshaling or validation errors.
Extract(ctx context.Context, message *isp.Message, reqBodyType reflect.Type) (reflect.Value, error)
}
RequestBodyExtractor defines the interface for extracting request bodies from gRPC messages. Implementations should unmarshal the message body into the target type and return a reflect.Value.
type ResponseBodyMapper ¶
type ResponseBodyMapper interface {
// Map converts a handler result into a gRPC message.
// Returns the message and any marshaling errors.
Map(result any) (*isp.Message, error)
}
ResponseBodyMapper defines the interface for mapping handler results to gRPC messages. Implementations should marshal the result into a gRPC message body.
type Validator ¶
type Validator interface {
// Validate checks if the value is valid.
// Returns true if valid, false otherwise, along with a map of field names to error messages.
Validate(value any) (bool, map[string]string)
}
Validator defines the interface for request validation. Implementations should validate a value and return whether it's valid along with field-specific error details.
type Wrapper ¶
type Wrapper struct {
ParamMappers map[string]ParamMapper
BodyExtractor RequestBodyExtractor
BodyMapper ResponseBodyMapper
Middlewares []grpc.Middleware
}
Wrapper is a high-level handler factory that wraps functions with middleware and automatic request/response handling. It uses reflection to analyze function signatures and inject dependencies like context and auth data.
func DefaultWrapper ¶
func DefaultWrapper(logger log.Logger, restMiddlewares ...grpc.Middleware) Wrapper
DefaultWrapper creates a Wrapper with pre-configured middleware for observability. Includes request ID propagation, metrics collection, distributed tracing, error handling, and panic recovery. Uses JSON for request extraction and response mapping. Accepts additional middleware to be appended after the default ones.
func NewWrapper ¶
func NewWrapper( paramMappers []ParamMapper, bodyExtractor RequestBodyExtractor, bodyMapper ResponseBodyMapper, ) Wrapper
NewWrapper creates a new Wrapper with the specified configuration. Accepts variadic paramMappers, a body extractor, and a body mapper.
func (Wrapper) Endpoint ¶
func (m Wrapper) Endpoint(f any) grpc.HandlerFunc
Endpoint wraps a function to create a gRPC HandlerFunc. The function is analyzed via reflection to determine parameter types and return values. Middleware is applied in reverse order (last added, first executed). Panics if the function signature is invalid or cannot be wrapped.
func (Wrapper) WithMiddlewares ¶
func (m Wrapper) WithMiddlewares(middlewares ...grpc.Middleware) Wrapper
WithMiddlewares returns a new Wrapper with additional middleware appended. The original Wrapper is not modified.
Source Files
Directories