Documentation
¶
Overview ¶
Package api is the unified entrypoint and factory for REST, gRPC, and GraphQL transports.
Capabilities wired today: REST timeouts + HTTPStatus errors, gRPC health/recovery/GRPCStatus, GraphQL schema injection with complexity/depth limits + OTel spans, WebSocket hub (rooms + upgrade auth), RBAC middleware, multi-key rate limiting, pkg/api/openapi document helpers from route metadata, and Echo↔stdlib bridges.
GraphQL defaults (complexity 200, depth 15, OTel on) live in pkg/api/graphql; override via graphql.NewHandlerWithConfig when mounting outside this factory.
Usage:
server, err := api.New(api.Config{Protocol: api.ProtocolREST, Port: "8080"})
For GraphQL, supply an ExecutableSchema (typically from gqlgen codegen):
server, err := api.New(api.Config{
Protocol: api.ProtocolGraphQL,
Port: "8080",
GraphQLSchema: generated.NewExecutableSchema(...),
})
Index ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var ( ErrForbidden = errors.Forbidden("forbidden", nil) ErrNotFound = errors.NotFound("not found", nil) ErrInvalidArgument = errors.InvalidArgument("invalid argument", nil) ErrRateLimited = errors.ResourceExhausted("rate limit exceeded", nil) )
Domain sentinel errors for the API package. HTTP/gRPC status mapping is handled by pkg/errors.HTTPStatus / GRPCStatus.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Protocol Protocol `env:"API_PROTOCOL" env-default:"rest"`
Port string `env:"PORT" env-default:"8080"`
// GraphQLSchema is required when Protocol is ProtocolGraphQL.
// Typically produced by gqlgen codegen (ExecutableSchema).
GraphQLSchema graphql.ExecutableSchema
// GraphQLPath is the HTTP path for the GraphQL endpoint (default "/query").
GraphQLPath string
// GraphQLPlaygroundPath, when non-empty, mounts the GraphQL playground at that path.
GraphQLPlaygroundPath string
}
Config for the unified API Server.
func LoadConfig ¶
LoadConfig loads api.Config via pkg/config (env / optional .env) and validates it. Note: GraphQLSchema cannot be loaded from env and must be set by the caller.
type InstrumentedServer ¶
type InstrumentedServer struct {
// contains filtered or unexported fields
}
InstrumentedServer wraps Server with logging and tracing
func NewInstrumentedServer ¶
func NewInstrumentedServer(next Server) *InstrumentedServer
func (*InstrumentedServer) Shutdown ¶
func (s *InstrumentedServer) Shutdown(ctx context.Context) error
func (*InstrumentedServer) Start ¶
func (s *InstrumentedServer) Start() error
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package client provides generic clients for communicating with external services.
|
Package client provides generic clients for communicating with external services. |
|
grpc
Package grpc provides a generic gRPC client wrapper with Observability and Resilience.
|
Package grpc provides a generic gRPC client wrapper with Observability and Resilience. |
|
rest
Package rest provides a generic REST client wrapper with Observability and Resilience.
|
Package rest provides a generic REST client wrapper with Observability and Resilience. |
|
Package graphql wraps gqlgen to build an HTTP GraphQL handler with operation logging, OpenTelemetry spans, complexity/depth limits, and introspection control.
|
Package graphql wraps gqlgen to build an HTTP GraphQL handler with operation logging, OpenTelemetry spans, complexity/depth limits, and introspection control. |
|
Package grpc provides a gRPC server with OpenTelemetry, unary/stream recovery, AppError→gRPC status mapping (via pkg/errors.GRPCStatus) for unary and stream RPCs, AuthInterceptor / StreamAuthInterceptor (bearer metadata), reflection, and standard health checking (grpc.health.v1).
|
Package grpc provides a gRPC server with OpenTelemetry, unary/stream recovery, AppError→gRPC status mapping (via pkg/errors.GRPCStatus) for unary and stream RPCs, AuthInterceptor / StreamAuthInterceptor (bearer metadata), reflection, and standard health checking (grpc.health.v1). |
|
Package middleware provides HTTP middleware for auth context, RBAC RequirePermission, rate limiting (IP / user / API-key keys), security headers, CORS, CSRF, circuit breaker, cache, and audit.
|
Package middleware provides HTTP middleware for auth context, RBAC RequirePermission, rate limiting (IP / user / API-key keys), security headers, CORS, CSRF, circuit breaker, cache, and audit. |
|
Package openapi provides OpenAPI 3.x document helpers generated from route metadata, plus Echo↔net/http adapter bridge utilities.
|
Package openapi provides OpenAPI 3.x document helpers generated from route metadata, plus Echo↔net/http adapter bridge utilities. |
|
Package ratelimit provides API-level rate limiting middleware and strategies.
|
Package ratelimit provides API-level rate limiting middleware and strategies. |
|
adapters/redis
Package redis provides a Redis-backed distributed rate limiter.
|
Package redis provides a Redis-backed distributed rate limiter. |
|
Package rbac provides an in-memory Role-Based Access Control enforcer with wildcard permissions and SmartRWMutex-guarded policy updates.
|
Package rbac provides an in-memory Role-Based Access Control enforcer with wildcard permissions and SmartRWMutex-guarded policy updates. |
|
Package rest provides an Echo-based HTTP server with timeouts, request logging, and centralized error handling via pkg/errors.HTTPStatus.
|
Package rest provides an Echo-based HTTP server with timeouts, request logging, and centralized error handling via pkg/errors.HTTPStatus. |
|
Package websocket implements a Hub/Client WebSocket fan-out with origin allowlisting, graceful Shutdown, concurrency-safe broadcast (SmartRWMutex), named rooms (JoinRoom / LeaveRoom / BroadcastToRoom), and optional upgrade-time Authenticate hook on Config.
|
Package websocket implements a Hub/Client WebSocket fan-out with origin allowlisting, graceful Shutdown, concurrency-safe broadcast (SmartRWMutex), named rooms (JoinRoom / LeaveRoom / BroadcastToRoom), and optional upgrade-time Authenticate hook on Config. |
Click to show internal directories.
Click to hide internal directories.