router

package module
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 5, 2025 License: MIT Imports: 22 Imported by: 1

README

go-router

A lightweight, generic HTTP router interface for Go that enables framework-agnostic HTTP handling with built-in adapters. This package provides an abstraction for routing, making it easy to switch between different HTTP router implementations.

Installation

go get github.com/goliatone/go-router

Overview

go-router provides a common interface for HTTP routing that can be implemented by different HTTP frameworks. Currently includes a Fiber and HTTPRouter with plans to support more frameworks.

Usage

Basic Example with Fiber
package main

import (
    "github.com/goliatone/go-router"
    "github.com/gofiber/fiber/v2"
)

func main() {
    // Create new Fiber adapter
    app := router.NewFiberAdapter()

    // Add middleware
    app.Router().Use(func(c router.Context) error {
        c.SetHeader("Content-Type", "application/json")
        return c.Next()
    })

    // Add routes
    app.Router().Get("/hello", func(c router.Context) error {
        return c.JSON(200, map[string]string{"message": "Hello World!"})
    })

    // Start server
    app.Serve(":3000")
}
Route Groups
api := app.Router().Group("/api")
{
    api.Post("/users", createUser(store)).Name("user.create")
    api.Get("/users", listUsers(store)).Name("user.list")
    api.Get("/users/:id", getUser(store)).Name("user.get")
    api.Put("/users/:id", updateUser(store)).Name("user.update")
    api.Delete("/users/:id", deleteUser(store)).Name("user.delete")
}
Builder
api := app.Router().Group("/api")

builder := router.NewRouteBuilder(api)

users := builder.Group("/users")
{
    users.NewRoute().
        POST().
        Path("/").
        Description("Create a new user").
        Tags("User").
        Handler(createUser(store)).
        Name("user.create")

    users.NewRoute().
        GET().
        Path("/").
        Description("List all users").
        Tags("User").
        Handler(listUsers(store)).
        Name("user.list")

    users.NewRoute().
        GET().
        Path("/:id").
        Description("Get user by ID").
        Tags("User").
        Handler(getUser(store)).
        Name("user.get")

    users.NewRoute().
        PUT().
        Path("/:id").
        Description("Update user by ID").
        Tags("User").
        Handler(updateUser(store)).
        Name("user.update")

    users.NewRoute().
        DELETE().
        Path("/:id").
        Description("Delete user by ID").
        Tags("User").
        Handler(deleteUser(store)).
        Name("user.delete")

    users.BuildAll()
}

API Reference

Server Interface
type Server[T any] interface {
    Router() Router[T]
    WrapHandler(HandlerFunc) interface{}
    WrappedRouter() T
    Serve(address string) error
    Shutdown(ctx context.Context) error
}
Router Interface
type Router[T any] interface {
    Handle(method HTTPMethod, path string, handler ...HandlerFunc) RouteInfo
    Group(prefix string) Router[T]
    Use(args ...any) Router[T]
    Get(path string, handler HandlerFunc) RouteInfo
    Post(path string, handler HandlerFunc) RouteInfo
    Put(path string, handler HandlerFunc) RouteInfo
    Delete(path string, handler HandlerFunc) RouteInfo
    Patch(path string, handler HandlerFunc) RouteInfo
}
Context Interface
type Context interface {
    Method() string
    Path() string
    Param(name string) string
    Query(name string) string
    Queries() map[string]string
    Status(code int) Context
    Send(body []byte) error
    JSON(code int, v interface{}) error
    NoContent(code int) error
    Bind(interface{}) error
    Context() context.Context
    SetContext(context.Context)
    Header(string) string
    SetHeader(string, string)
    Next() error
}

License

MIT

Documentation

Index

Constants

View Source 
const (
	HeaderAuthorization = "Authorization"
	HeaderContentType   = "Content-Type"
)
View Source 
const ErrorHandlerConfigKey = "error_handler_config"

Variables

View Source 
var LoggerEnabled = false

Functions

func DefaultFiberOptions 

func DefaultFiberOptions(app *fiber.App) *fiber.App

func DefaultHTTPRouterOptions 

func DefaultHTTPRouterOptions(router *httprouter.Router) *httprouter.Router

func GetContextValue added in v0.0.2 

func GetContextValue[T any](c Context, key string, def T) T

GetContextValue functions for type assertion

func LogError added in v0.0.2 

func LogError(logger Logger, err *RouterError, c Context)

LogError logs the error with context information

func ServeOpenAPI added in v0.0.2 

func ServeOpenAPI[T any](router Router[T], renderer OpenApiMetaGenerator, opts ...OpenAPIOption)

Types

type BaseRouter added in v0.0.3 

type BaseRouter struct {
	// contains filtered or unexported fields
}

Common fields for both FiberRouter and HTTPRouter

func (*BaseRouter) PrintRoutes added in v0.0.3 

func (br *BaseRouter) PrintRoutes()

func (*BaseRouter) Routes added in v0.0.3 

func (br *BaseRouter) Routes() []RouteDefinition

type Context 

type Context interface {
	RequestContext
	ResponseWriter
	ContextStore
	// Body parsing
	Bind(any) error // TODO: Myabe rename to ParseBody

	// Context methods
	Context() context.Context
	SetContext(context.Context)
	Next() error
}

Context represents a generic HTTP context

func NewFiberContext 

func NewFiberContext(c *fiber.Ctx) Context

func NewHTTPRouterContext 

func NewHTTPRouterContext(w http.ResponseWriter, r *http.Request, ps httprouter.Params) Context

type ContextStore added in v0.0.2 

type ContextStore interface {
	Set(key string, value any)
	Get(key string, def any) any
	GetString(key string, def string) string
	GetInt(key string, def int) int
	GetBool(key string, def bool) bool
}

ContextStore is a request scoped, in-memoroy store to pass data between middleware/handlers in the same request in a fremework agnostic way. If you need persistence between requests use Store e.g. for authentication middleware.

func NewContextStore added in v0.0.2 

func NewContextStore() ContextStore

type ErrorHandlerConfig added in v0.0.2 

type ErrorHandlerConfig struct {
	// Include stack traces in non-production environments
	IncludeStack bool
	// Custom error mapping functions
	ErrorMappers []ErrorMapper
	// Logger interface for error logging
	Logger Logger
	// Environment (development, production, etc.)
	Environment string

	GetRequestID func(c Context) string

	GetStackTrace func() []string
}

ErrorHandlerConfig allows customization of error handling behavior

func DefaultErrorHandlerConfig added in v0.0.2 

func DefaultErrorHandlerConfig() ErrorHandlerConfig

DefaultErrorHandlerConfig provides sensible defaults

type ErrorHandlerOption added in v0.0.2 

type ErrorHandlerOption func(*ErrorHandlerConfig)

ErrorHandlerOption defines a function that can modify ErrorHandlerConfig

func WithEnvironment added in v0.0.2 

func WithEnvironment(env string) ErrorHandlerOption

WithEnvironment sets the environment for error handling

func WithErrorMapper added in v0.0.2 

func WithErrorMapper(mapper ErrorMapper) ErrorHandlerOption

WithErrorMapper adds additional error mappers

func WithGetStackTrace added in v0.0.2 

func WithGetStackTrace(stacker func() []string) ErrorHandlerOption

WithGetStackTrace adds additional error mappers

func WithLogger added in v0.0.2 

func WithLogger(logger Logger) ErrorHandlerOption

WithLogger sets the logger for error handling

func WithStackTrace added in v0.0.2 

func WithStackTrace(include bool) ErrorHandlerOption

WithStackTrace enables or disables stack traces

type ErrorMapper added in v0.0.2 

type ErrorMapper func(error) *RouterError

ErrorMapper is a function that can map specific error types to RouterError

type ErrorResponse added in v0.0.2 

type ErrorResponse struct {
	Error struct {
		Type       string            `json:"type"`
		Message    string            `json:"message"`
		Code       int               `json:"code"`
		RequestID  string            `json:"request_id,omitempty"`
		Stack      []string          `json:"stack,omitempty"`
		Metadata   map[string]any    `json:"metadata,omitempty"`
		Validation []ValidationError `json:"validation,omitempty"`
	} `json:"error"`
}

ErrorResponse represents the structure of error responses

func PrepareErrorResponse added in v0.0.2 

func PrepareErrorResponse(err *RouterError, config ErrorHandlerConfig) ErrorResponse

type ErrorType added in v0.0.2 

type ErrorType string

Error Types 

const (
	ErrorTypeValidation       ErrorType = "VALIDATION_ERROR"
	ErrorTypeMiddleware       ErrorType = "MIDDLEWARE_ERROR"
	ErrorTypeRouting          ErrorType = "ROUTING_ERROR"
	ErrorTypeHandler          ErrorType = "HANDLER_ERROR"
	ErrorTypeInternal         ErrorType = "INTERNAL_ERROR"
	ErrorTypeUnauthorized     ErrorType = "UNAUTHORIZED"
	ErrorTypeForbidden        ErrorType = "FORBIDDEN"
	ErrorTypeNotFound         ErrorType = "NOT_FOUND"
	ErrorTypeBadRequest       ErrorType = "BAD_REQUEST"
	ErrorTypeConflict         ErrorType = "CONFLICT"
	ErrorTypeTooManyRequests  ErrorType = "TOO_MANY_REQUESTS"
	ErrorTypeMethodNotAllowed ErrorType = "METHOD_NOT_ALLOWED"
)

type FiberAdapter 

type FiberAdapter struct {
	// contains filtered or unexported fields
}

func (*FiberAdapter) Router 

func (a *FiberAdapter) Router() Router[*fiber.App]

func (*FiberAdapter) Serve 

func (a *FiberAdapter) Serve(address string) error

func (*FiberAdapter) Shutdown 

func (a *FiberAdapter) Shutdown(ctx context.Context) error

func (*FiberAdapter) WrapHandler 

func (a *FiberAdapter) WrapHandler(h HandlerFunc) interface{}

func (*FiberAdapter) WrappedRouter 

func (a *FiberAdapter) WrappedRouter() *fiber.App

type FiberRouter 

type FiberRouter struct {
	BaseRouter
	// contains filtered or unexported fields
}

func (*FiberRouter) Delete 

func (r *FiberRouter) Delete(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

func (*FiberRouter) Get 

func (r *FiberRouter) Get(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

func (*FiberRouter) GetPrefix added in v0.0.3 

func (r *FiberRouter) GetPrefix() string

func (*FiberRouter) Group 

func (r *FiberRouter) Group(prefix string) Router[*fiber.App]

func (*FiberRouter) Handle 

func (r *FiberRouter) Handle(method HTTPMethod, pathStr string, handler HandlerFunc, m ...MiddlewareFunc) RouteInfo

func (*FiberRouter) Patch 

func (r *FiberRouter) Patch(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

func (*FiberRouter) Post 

func (r *FiberRouter) Post(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

func (*FiberRouter) PrintRoutes added in v0.0.2 

func (r *FiberRouter) PrintRoutes()

func (*FiberRouter) Put 

func (r *FiberRouter) Put(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

func (*FiberRouter) Use 

func (r *FiberRouter) Use(m ...MiddlewareFunc) Router[*fiber.App]

type HTTPMethod 

type HTTPMethod string

HTTPMethod represents HTTP request methods 

const (
	GET    HTTPMethod = "GET"
	POST   HTTPMethod = "POST"
	PUT    HTTPMethod = "PUT"
	DELETE HTTPMethod = "DELETE"
	PATCH  HTTPMethod = "PATCH"
)

type HTTPRouter 

type HTTPRouter struct {
	BaseRouter
	// contains filtered or unexported fields
}

HTTPRouter implements Router for httprouter

func (*HTTPRouter) Delete 

func (r *HTTPRouter) Delete(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

func (*HTTPRouter) Get 

func (r *HTTPRouter) Get(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

func (*HTTPRouter) GetPrefix added in v0.0.3 

func (r *HTTPRouter) GetPrefix() string

func (*HTTPRouter) Group 

func (r *HTTPRouter) Group(prefix string) Router[*httprouter.Router]

func (*HTTPRouter) Handle 

func (r *HTTPRouter) Handle(method HTTPMethod, pathStr string, handler HandlerFunc, m ...MiddlewareFunc) RouteInfo

func (*HTTPRouter) Patch 

func (r *HTTPRouter) Patch(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

func (*HTTPRouter) Post 

func (r *HTTPRouter) Post(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

func (*HTTPRouter) PrintRoutes added in v0.0.2 

func (r *HTTPRouter) PrintRoutes()

func (*HTTPRouter) Put 

func (r *HTTPRouter) Put(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

func (*HTTPRouter) Use 

func (r *HTTPRouter) Use(m ...MiddlewareFunc) Router[*httprouter.Router]

type HTTPServer 

type HTTPServer struct {
	// contains filtered or unexported fields
}

func (*HTTPServer) Router 

func (a *HTTPServer) Router() Router[*httprouter.Router]

func (*HTTPServer) Serve 

func (a *HTTPServer) Serve(address string) error

func (*HTTPServer) Shutdown 

func (a *HTTPServer) Shutdown(ctx context.Context) error

func (*HTTPServer) WrapHandler 

func (a *HTTPServer) WrapHandler(h HandlerFunc) interface{}

func (*HTTPServer) WrappedRouter 

func (a *HTTPServer) WrappedRouter() *httprouter.Router

type HandlerFunc 

type HandlerFunc func(Context) error

func WrapHandler added in v0.0.2 

func WrapHandler(handler func(Context) error) HandlerFunc

WrapHandler function to wrap handlers that return error

func (HandlerFunc) AsMiddlware added in v0.0.2 

func (h HandlerFunc) AsMiddlware() MiddlewareFunc

type Logger added in v0.0.2 

type Logger interface {
	Debug(format string, args ...any)
	Info(format string, args ...any)
	Error(format string, args ...any)
}

type MetadataAggregator added in v0.0.3 

type MetadataAggregator struct {

	////
	Paths      map[string]any
	Schemas    map[string]any
	Tags       []any
	Components map[string]any
	// contains filtered or unexported fields
}

MetadataAggregator collects and merges metadata from multiple providers

func NewMetadataAggregator added in v0.0.3 

func NewMetadataAggregator() *MetadataAggregator

NewMetadataAggregator creates a new aggregator

func (*MetadataAggregator) AddProvider added in v0.0.3 

func (ma *MetadataAggregator) AddProvider(provider MetadataProvider)

AddProvider adds a metadata provider to the aggregator

func (*MetadataAggregator) AddProviders added in v0.0.3 

func (ma *MetadataAggregator) AddProviders(providers ...MetadataProvider)

AddProviders adds multiple metadata providers to the aggregator

func (*MetadataAggregator) Compile added in v0.0.3 

func (ma *MetadataAggregator) Compile()

GenerateOpenAPI generates a complete OpenAPI specification from all providers

func (*MetadataAggregator) GenerateOpenAPI added in v0.0.3 

func (ma *MetadataAggregator) GenerateOpenAPI() map[string]any

func (*MetadataAggregator) SetTags added in v0.0.3 

func (ma *MetadataAggregator) SetTags(tags []string)

SetTags sets global tags that will be added to all operations

type MetadataProvider added in v0.0.3 

type MetadataProvider interface {
	GetMetadata() ResourceMetadata
}

MetadataProvider interface for components that can provide API metadata

type MiddlewareFunc added in v0.0.2 

type MiddlewareFunc func(HandlerFunc) HandlerFunc

func MiddlewareFromFiber added in v0.0.3 

func MiddlewareFromFiber(userFiberMw func(*fiber.Ctx) error) MiddlewareFunc

MiddlewareFromFiber adapts a user-provided Fiber middleware to your router's chain, preserving c.Next() semantics by spinning up a sub-Fiber app for each request.

func MiddlewareFromHTTP added in v0.0.2 

func MiddlewareFromHTTP(mw func(next http.Handler) http.Handler) MiddlewareFunc

MiddlewareFromHTTP that transforms a standard Go HTTP middleware which takes and returns http.Handler, into a MiddlewareFunc suitable for use with our router. This function essentially adapts the http.Handler pattern to the HandlerFunc (Context) error interface

func ToMiddleware added in v0.0.2 

func ToMiddleware(h HandlerFunc) MiddlewareFunc

ToMiddleware function to wrap handlers and run them as a middleware

func WithErrorHandlerMiddleware added in v0.0.2 

func WithErrorHandlerMiddleware(opts ...ErrorHandlerOption) MiddlewareFunc

WithErrorHandlerMiddleware creates a middleware that handles errors for all routes in a group

type NamedHandler added in v0.0.2 

type NamedHandler struct {
	Name    string
	Handler HandlerFunc
}

NamedHandler is a handler with a name for debugging/printing

type OpenAPIFieldContact added in v0.0.2 

type OpenAPIFieldContact struct {
	Email string
	Name  string
	URL   string
}

type OpenAPIOption added in v0.0.2 

type OpenAPIOption func(*openAPIConfig)

func WithDocsPath added in v0.0.2 

func WithDocsPath(path string) OpenAPIOption

func WithOpenAPIPath added in v0.0.2 

func WithOpenAPIPath(path string) OpenAPIOption

func WithTitle added in v0.0.2 

func WithTitle(title string) OpenAPIOption

type OpenAPIRenderer added in v0.0.2 

type OpenAPIRenderer struct {
	Title       string
	Version     string
	Description string
	Contact     OpenAPIFieldContact
	Routes      []RouteDefinition
	Paths       map[string]any
	Tags        []any
	Components  map[string]any
	// contains filtered or unexported fields
}

func (*OpenAPIRenderer) AppenRouteInfo added in v0.0.3 

func (o *OpenAPIRenderer) AppenRouteInfo(routes []RouteDefinition)

AppenRouteInfo updates the renderer with route information

func (*OpenAPIRenderer) GenerateOpenAPI added in v0.0.2 

func (o *OpenAPIRenderer) GenerateOpenAPI() map[string]any

func (*OpenAPIRenderer) WithMetadataProviders added in v0.0.3 

func (o *OpenAPIRenderer) WithMetadataProviders(providers ...OpenApiMetaGenerator) *OpenAPIRenderer

type OpenApiMetaGenerator added in v0.0.3 

type OpenApiMetaGenerator interface {
	GenerateOpenAPI() map[string]any
}

type Parameter added in v0.0.2 

type Parameter struct {
	Name        string         `json:"name"`
	In          string         `json:"in"` // query, path, header, cookie
	Required    bool           `json:"required"`
	Description string         `json:"description,omitempty"`
	Schema      map[string]any `json:"schema,omitempty"`
	Example     any            `json:"example,omitempty"`
}

Parameter unifies the parameter definitions

type PrefixedRouter added in v0.0.3 

type PrefixedRouter interface {
	GetPrefix() string
}

TODO: Maybe incorporate into Router[T]

type PropertyInfo added in v0.0.3 

type PropertyInfo struct {
	Type        string                  `json:"type"`
	Format      string                  `json:"format,omitempty"`
	Description string                  `json:"description,omitempty"`
	Required    bool                    `json:"required"`
	Nullable    bool                    `json:"nullable"`
	ReadOnly    bool                    `json:"read_only"`
	WriteOnly   bool                    `json:"write_only"`
	Example     any                     `json:"example,omitempty"`
	Properties  map[string]PropertyInfo `json:"properties,omitempty"` // For nested objects
	Items       *PropertyInfo           `json:"items,omitempty"`      // For arrays
}

type RequestBody added in v0.0.2 

type RequestBody struct {
	Description string         `json:"description,omitempty"`
	Required    bool           `json:"required"`
	Content     map[string]any `json:"content,omitempty"`
}

RequestBody unifies the request body definitions

type RequestContext added in v0.0.2 

type RequestContext interface {
	Method() string
	Path() string

	Param(name string, defaultValue string) string
	ParamsInt(key string, defaultValue int) int

	Query(name string, defaultValue string) string
	QueryInt(name string, defaultValue int) int
	Queries() map[string]string

	Body() []byte
}

type ResourceMetadata added in v0.0.3 

type ResourceMetadata struct {
	// Resource identifiers
	Name        string   `json:"name"`
	PluralName  string   `json:"plural_name"`
	Description string   `json:"description"`
	Tags        []string `json:"tags"`

	// Routes metadata
	Routes []RouteDefinition `json:"routes"`

	// Schema information
	Schema SchemaMetadata `json:"schema"`
}

ResourceMetadata represents collected metadata about an API resource

type Response added in v0.0.2 

type Response struct {
	Code        int            `json:"code"`
	Description string         `json:"description"`
	Headers     map[string]any `json:"headers,omitempty"`
	Content     map[string]any `json:"content,omitempty"`
}

Response unifies the response definitions

type ResponseWriter added in v0.0.2 

type ResponseWriter interface {
	Status(code int) ResponseWriter
	Send(body []byte) error
	JSON(code int, v any) error
	// NoContent for status codes that shouldn't have response bodies (204, 205, 304).
	NoContent(code int) error
	Header(string) string
	SetHeader(string, string) ResponseWriter
}

type Route added in v0.0.2 

type Route[T any] struct {
	// contains filtered or unexported fields
}

func (*Route[T]) Build added in v0.0.2 

func (r *Route[T]) Build() error

func (*Route[T]) DELETE added in v0.0.2 

func (r *Route[T]) DELETE() *Route[T]

func (*Route[T]) Description added in v0.0.2 

func (r *Route[T]) Description(description string) *Route[T]

func (*Route[T]) GET added in v0.0.2 

func (r *Route[T]) GET() *Route[T]

func (*Route[T]) Handler added in v0.0.2 

func (r *Route[T]) Handler(handler HandlerFunc) *Route[T]

func (*Route[T]) Method added in v0.0.2 

func (r *Route[T]) Method(method HTTPMethod) *Route[T]

func (*Route[T]) Middleware added in v0.0.2 

func (r *Route[T]) Middleware(middleware ...MiddlewareFunc) *Route[T]

func (*Route[T]) Name added in v0.0.2 

func (r *Route[T]) Name(name string) *Route[T]

func (*Route[T]) PATCH added in v0.0.2 

func (r *Route[T]) PATCH() *Route[T]

func (*Route[T]) POST added in v0.0.2 

func (r *Route[T]) POST() *Route[T]

func (*Route[T]) PUT added in v0.0.2 

func (r *Route[T]) PUT() *Route[T]

func (*Route[T]) Parameter added in v0.0.2 

func (r *Route[T]) Parameter(name, in string, required bool, schema map[string]any) *Route[T]

func (*Route[T]) Path added in v0.0.2 

func (r *Route[T]) Path(path string) *Route[T]

func (*Route[T]) RequestBody added in v0.0.2 

func (r *Route[T]) RequestBody(desc string, required bool, content map[string]any) *Route[T]

func (*Route[T]) Response added in v0.0.2 

func (r *Route[T]) Response(code int, desc string, content map[string]any) *Route[T]

func (*Route[T]) Responses added in v0.0.2 

func (r *Route[T]) Responses(responses []Response) *Route[T]

func (*Route[T]) Summary added in v0.0.2 

func (r *Route[T]) Summary(summary string) *Route[T]

func (*Route[T]) Tags added in v0.0.2 

func (r *Route[T]) Tags(tags ...string) *Route[T]

type RouteBuilder added in v0.0.2 

type RouteBuilder[T any] struct {
	// contains filtered or unexported fields
}

func NewRouteBuilder added in v0.0.2 

func NewRouteBuilder[T any](router Router[T]) *RouteBuilder[T]

func (*RouteBuilder[T]) BuildAll added in v0.0.2 

func (b *RouteBuilder[T]) BuildAll() error

func (*RouteBuilder[T]) GetMetadata added in v0.0.3 

func (b *RouteBuilder[T]) GetMetadata() []RouteDefinition

func (*RouteBuilder[T]) Group added in v0.0.2 

func (b *RouteBuilder[T]) Group(prefix string) *RouteBuilder[T]

Group creates a new RouteBuilder with a prefix path

func (*RouteBuilder[T]) NewRoute added in v0.0.2 

func (b *RouteBuilder[T]) NewRoute() *Route[T]

NewRoute starts the configuration of a new route

type RouteDefinition added in v0.0.2 

type RouteDefinition struct {
	// Core routing
	Method   HTTPMethod     `json:"method"`
	Path     string         `json:"path"`
	Name     string         `json:"name"`
	Handlers []NamedHandler `json:"-"` // Runtime only, not exported to JSON

	// metadata e.g. OpenAPI
	Summary     string       `json:"summary,omitempty"`
	Description string       `json:"description,omitempty"`
	Tags        []string     `json:"tags,omitempty"`
	Parameters  []Parameter  `json:"parameters,omitempty"`
	RequestBody *RequestBody `json:"request_body,omitempty"`
	Responses   []Response   `json:"responses,omitempty"`
}

RouteDefinition represents all metadata about a route, combining both runtime routing information and metadata

func NewRouteDefinition added in v0.0.3 

func NewRouteDefinition() *RouteDefinition

func (*RouteDefinition) AddParameter added in v0.0.2 

func (r *RouteDefinition) AddParameter(name, in string, required bool, schema map[string]any) RouteInfo

func (*RouteDefinition) AddResponse added in v0.0.2 

func (r *RouteDefinition) AddResponse(code int, desc string, content map[string]any) RouteInfo

func (*RouteDefinition) AddTags added in v0.0.3 

func (r *RouteDefinition) AddTags(t ...string) RouteInfo

func (*RouteDefinition) SetDescription added in v0.0.3 

func (r *RouteDefinition) SetDescription(d string) RouteInfo

func (*RouteDefinition) SetName added in v0.0.3 

func (r *RouteDefinition) SetName(n string) RouteInfo

func (*RouteDefinition) SetRequestBody added in v0.0.2 

func (r *RouteDefinition) SetRequestBody(desc string, required bool, content map[string]any) RouteInfo

func (*RouteDefinition) SetSummary added in v0.0.3 

func (r *RouteDefinition) SetSummary(s string) RouteInfo

type RouteInfo 

type RouteInfo interface {
	SetName(string) RouteInfo
	SetDescription(string) RouteInfo
	SetSummary(s string) RouteInfo
	AddTags(...string) RouteInfo
	AddParameter(name, in string, required bool, schema map[string]any) RouteInfo
	SetRequestBody(desc string, required bool, content map[string]any) RouteInfo
	AddResponse(code int, desc string, content map[string]any) RouteInfo
}

type Router 

type Router[T any] interface {
	Handle(method HTTPMethod, path string, handler HandlerFunc, middlewares ...MiddlewareFunc) RouteInfo
	Group(prefix string) Router[T]
	Use(m ...MiddlewareFunc) Router[T]
	Get(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo
	Post(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo
	Put(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo
	Delete(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo
	Patch(path string, handler HandlerFunc, mw ...MiddlewareFunc) RouteInfo

	// TODO: Move to a different interface e.g. MetaRouter
	// For debugging: Print a table of routes and their middleware chain
	Routes() []RouteDefinition // New method to retrieve registered routes
	PrintRoutes()
}

Router represents a generic router interface

type RouterError added in v0.0.2 

type RouterError struct {
	Type      ErrorType
	Code      int
	Message   string
	Internal  error
	Metadata  map[string]any
	RequestID string
}

RouterError represents a custom error type for the router package

func MapToRouterError added in v0.0.2 

func MapToRouterError(err error, mappers []ErrorMapper) *RouterError

MapToRouterError converts any error to RouterError

func NewBadRequestError added in v0.0.2 

func NewBadRequestError(message string) *RouterError

NewBadRequestError for generic bad requests outside of validation context

func NewConflictError added in v0.0.2 

func NewConflictError(message string) *RouterError

NewConflictError for requests that could not be completed due to a conflict

func NewForbiddenError added in v0.0.2 

func NewForbiddenError(message string) *RouterError

func NewInternalError added in v0.0.2 

func NewInternalError(err error, message string) *RouterError

func NewMethodNotAllowedError added in v0.0.2 

func NewMethodNotAllowedError(message string) *RouterError

NewMethodNotAllowedError for requests that use an unallowed HTTP method

func NewNotFoundError added in v0.0.2 

func NewNotFoundError(message string) *RouterError

func NewTooManyRequestsError added in v0.0.2 

func NewTooManyRequestsError(message string) *RouterError

NewTooManyRequestsError for rate-limiting scenarios

func NewUnauthorizedError added in v0.0.2 

func NewUnauthorizedError(message string) *RouterError

func NewValidationError added in v0.0.2 

func NewValidationError(message string, validationErrs []ValidationError) *RouterError

NewValidationError

func (*RouterError) Error added in v0.0.2 

func (e *RouterError) Error() string

func (*RouterError) Unwrap added in v0.0.2 

func (e *RouterError) Unwrap() error

func (*RouterError) WithMetadata added in v0.0.2 

func (e *RouterError) WithMetadata(meta map[string]any) *RouterError

type SchemaMetadata added in v0.0.3 

type SchemaMetadata struct {
	Properties  map[string]PropertyInfo `json:"properties"`
	Required    []string                `json:"required"`
	Description string                  `json:"description"`
}

func ExtractSchemaFromType added in v0.0.3 

func ExtractSchemaFromType(t reflect.Type) SchemaMetadata

ExtractSchemaFromType generates SchemaMetadata from a Go type using reflection

type Server 

type Server[T any] interface {
	Router() Router[T]
	WrapHandler(HandlerFunc) any
	WrappedRouter() T
	Serve(address string) error
	Shutdown(ctx context.Context) error
}

Server represents a generic server interface

func NewFiberAdapter 

func NewFiberAdapter(opts ...func(*fiber.App) *fiber.App) Server[*fiber.App]

func NewHTTPServer 

func NewHTTPServer(opts ...func(*httprouter.Router) *httprouter.Router) Server[*httprouter.Router]

type ValidationError added in v0.0.2 

type ValidationError struct {
	Field   string `json:"field"`
	Message string `json:"message"`
}

ValidationError represents a validation error for a specific field

func (*ValidationError) Error added in v0.0.2 

func (v *ValidationError) Error() string

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.