router

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Nov 19, 2025 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ErrCodeRequired      = shared.ErrCodeRequired
	ErrCodeInvalidType   = shared.ErrCodeInvalidType
	ErrCodeInvalidFormat = shared.ErrCodeInvalidFormat
	ErrCodeMinLength     = shared.ErrCodeMinLength
	ErrCodeMaxLength     = shared.ErrCodeMaxLength
	ErrCodeMinValue      = shared.ErrCodeMinValue
	ErrCodeMaxValue      = shared.ErrCodeMaxValue
	ErrCodePattern       = shared.ErrCodePattern
	ErrCodeEnum          = shared.ErrCodeEnum
	ErrCodeMinItems      = shared.ErrCodeMinItems
	ErrCodeMaxItems      = shared.ErrCodeMaxItems
	ErrCodeUniqueItems   = shared.ErrCodeUniqueItems
)

Re-export validation error codes

View Source 
const ManagerKey = shared.RouterKey

ManagerKey is the DI key for the router service.

View Source 
const ParamsContextKey = "forge:params"

ParamsContextKey is used to store route params in request context Exported so di.NewContext can use the same key.

Variables

View Source 
var (
	NewHTTPError  = errors.NewHTTPError
	BadRequest    = errors.BadRequest
	Unauthorized  = errors.Unauthorized
	Forbidden     = errors.Forbidden
	NotFound      = errors.NotFound
	InternalError = errors.InternalError
)
View Source 
var (
	NewValidationErrors        = shared.NewValidationErrors
	NewValidationErrorResponse = shared.NewValidationErrorResponse
)

Re-export validation functions

Functions

func FormatValidationError 

func FormatValidationError(err error) (int, []byte)

FormatValidationError formats validation errors for HTTP response.

func GetTypeName 

func GetTypeName(t reflect.Type) string

GetTypeName returns a qualified type name for schema references.

func ValidateQueryParams 

func ValidateQueryParams(r *http.Request, schemaType any) error

ValidateQueryParams validates query parameters against a struct schema.

func ValidateRequestBody 

func ValidateRequestBody(r *http.Request, schema *Schema) error

ValidateRequestBody validates the request body against a schema.

Types

type AsyncAPIChannel 

type AsyncAPIChannel = shared.AsyncAPIChannel

Type aliases for AsyncAPI types.

type AsyncAPIChannelBindings 

type AsyncAPIChannelBindings = shared.AsyncAPIChannelBindings

Type aliases for AsyncAPI types.

type AsyncAPIChannelReference 

type AsyncAPIChannelReference = shared.AsyncAPIChannelReference

Type aliases for AsyncAPI types.

type AsyncAPIComponents 

type AsyncAPIComponents = shared.AsyncAPIComponents

Type aliases for AsyncAPI types.

type AsyncAPIConfig 

type AsyncAPIConfig = shared.AsyncAPIConfig

Type aliases for AsyncAPI types.

type AsyncAPIInfo 

type AsyncAPIInfo = shared.AsyncAPIInfo

Type aliases for AsyncAPI types.

type AsyncAPIMessage 

type AsyncAPIMessage = shared.AsyncAPIMessage

Type aliases for AsyncAPI types.

type AsyncAPIMessageReference 

type AsyncAPIMessageReference = shared.AsyncAPIMessageReference

Type aliases for AsyncAPI types.

type AsyncAPIOperation 

type AsyncAPIOperation = shared.AsyncAPIOperation

Type aliases for AsyncAPI types.

type AsyncAPIOperationBindings 

type AsyncAPIOperationBindings = shared.AsyncAPIOperationBindings

Type aliases for AsyncAPI types.

type AsyncAPIParameter 

type AsyncAPIParameter = shared.AsyncAPIParameter

type AsyncAPIServer 

type AsyncAPIServer = shared.AsyncAPIServer

Type aliases for AsyncAPI types.

type AsyncAPISpec 

type AsyncAPISpec = shared.AsyncAPISpec

Type aliases for AsyncAPI types.

type AsyncAPITag 

type AsyncAPITag = shared.AsyncAPITag

Type aliases for AsyncAPI types.

type BunRouterAdapter 

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

BunRouterAdapter wraps uptrace/bunrouter.

func (*BunRouterAdapter) Close 

func (a *BunRouterAdapter) Close() error

Close cleans up resources.

func (*BunRouterAdapter) Handle 

func (a *BunRouterAdapter) Handle(method, path string, handler http.Handler)

Handle registers a route.

func (*BunRouterAdapter) Mount 

func (a *BunRouterAdapter) Mount(path string, handler http.Handler)

Mount registers a sub-handler.

func (*BunRouterAdapter) ServeHTTP 

func (a *BunRouterAdapter) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP dispatches requests.

type CallbackConfig 

type CallbackConfig struct {
	Name       string
	Expression string // Callback URL expression (e.g., "{$request.body#/callbackUrl}")
	Operations map[string]*CallbackOperation
}

CallbackConfig defines a callback (webhook) for an operation.

func NewCompletionCallbackConfig 

func NewCompletionCallbackConfig(callbackURLExpression string, resultSchema any) CallbackConfig

NewCompletionCallbackConfig creates a callback config for async operation completion.

func NewEventCallbackConfig 

func NewEventCallbackConfig(callbackURLExpression string, eventSchema any) CallbackConfig

NewEventCallbackConfig creates a callback config for event notifications.

func NewStatusCallbackConfig 

func NewStatusCallbackConfig(callbackURLExpression string, statusSchema any) CallbackConfig

NewStatusCallbackConfig creates a callback config for status updates.

type CallbackOperation 

type CallbackOperation struct {
	Summary     string
	Description string
	RequestBody *RequestBody
	Responses   map[string]*Response
}

CallbackOperation defines an operation that will be called back.

func NewCallbackOperation 

func NewCallbackOperation(summary, description string) *CallbackOperation

NewCallbackOperation creates a new callback operation.

func (*CallbackOperation) WithCallbackRequestBody 

func (co *CallbackOperation) WithCallbackRequestBody(description string, schema any) *CallbackOperation

WithCallbackRequestBody sets the request body for a callback operation.

func (*CallbackOperation) WithCallbackResponse 

func (co *CallbackOperation) WithCallbackResponse(statusCode int, description string) *CallbackOperation

WithCallbackResponse adds a response to a callback operation.

type Components 

type Components = shared.Components

Components holds reusable objects for the API spec.

type Connection 

type Connection interface {
	// ID returns unique connection ID
	ID() string

	// Read reads a message from the connection
	Read() ([]byte, error)

	// ReadJSON reads JSON from the connection
	ReadJSON(v any) error

	// Write sends a message to the connection
	Write(data []byte) error

	// WriteJSON sends JSON to the connection
	WriteJSON(v any) error

	// Close closes the connection
	Close() error

	// Context returns the connection context
	Context() context.Context

	// RemoteAddr returns the remote address
	RemoteAddr() string

	// LocalAddr returns the local address
	LocalAddr() string
}

Connection represents a WebSocket connection.

type Contact 

type Contact = shared.Contact

Contact represents contact information.

type Context 

type Context = shared.Context

type Controller 

type Controller interface {
	// Name returns the controller identifier
	Name() string

	// Routes registers routes on the router
	Routes(r Router) error
}

Controller organizes related routes.

type ControllerWithDependencies 

type ControllerWithDependencies interface {
	Controller
	Dependencies() []string
}

ControllerWithDependencies declares dependencies for ordering.

type ControllerWithMiddleware 

type ControllerWithMiddleware interface {
	Controller
	Middleware() []Middleware
}

ControllerWithMiddleware applies middleware to all routes.

type ControllerWithPrefix 

type ControllerWithPrefix interface {
	Controller
	Prefix() string
}

ControllerWithPrefix sets a path prefix for all routes.

type ControllerWithTags 

type ControllerWithTags interface {
	Controller
	Tags() []string
}

ControllerWithTags adds metadata tags to all routes.

type Discriminator 

type Discriminator = shared.Discriminator

Discriminator supports polymorphism.

type DiscriminatorConfig 

type DiscriminatorConfig struct {
	PropertyName string
	Mapping      map[string]string
}

DiscriminatorConfig defines discriminator for polymorphic types.

type Encoding 

type Encoding = shared.Encoding

Encoding defines encoding for a property.

type ErrorHandler 

type ErrorHandler = shared.ErrorHandler

ErrorHandler handles errors from handlers.

func NewDefaultErrorHandler 

func NewDefaultErrorHandler(l Logger) ErrorHandler

NewDefaultErrorHandler creates a default error handler.

type Example 

type Example = shared.Example

Example provides an example value.

type Extension 

type Extension interface {
	// Name returns the unique name of the extension
	Name() string

	// Version returns the semantic version of the extension
	Version() string

	// Description returns a human-readable description
	Description() string

	// Start starts the extension.
	// This is called after all extensions have been registered and the DI container has started.
	Start(ctx context.Context) error

	// Stop stops the extension gracefully.
	// Extensions are stopped in reverse dependency order.
	Stop(ctx context.Context) error

	// Health checks if the extension is healthy.
	// This is called periodically by the health check system.
	// Return nil if healthy, error otherwise.
	Health(ctx context.Context) error

	// Dependencies returns the names of extensions this extension depends on.
	// The app will ensure dependencies are started before this extension.
	Dependencies() []string
}

Extension represents an official Forge extension that can be registered with an App. Extensions have full access to the framework and are first-party, trusted components.

Extensions follow a standard lifecycle:

  1. Register(app) - Register services with DI container
  2. Start(ctx) - Start the extension
  3. Health(ctx) - Check extension health (called periodically)
  4. Stop(ctx) - Stop the extension (called during graceful shutdown)

type ExternalDocs 

type ExternalDocs = shared.ExternalDocs

ExternalDocs points to external documentation.

type ExternalDocsDef 

type ExternalDocsDef struct {
	Description string
	URL         string
}

ExternalDocsDef defines external documentation.

type GroupConfig 

type GroupConfig struct {
	Middleware []Middleware
	Tags       []string
	Metadata   map[string]any
}

GroupConfig holds route group configuration.

type GroupOption 

type GroupOption interface {
	Apply(*GroupConfig)
}

GroupOption configures a route group.

func WithGroupAuth 

func WithGroupAuth(providerNames ...string) GroupOption

WithGroupAuth adds authentication to all routes in a group. Multiple providers create an OR condition.

Example: 

api := router.Group("/api", forge.WithGroupAuth("jwt"))

func WithGroupAuthAnd 

func WithGroupAuthAnd(providerNames ...string) GroupOption

WithGroupAuthAnd requires all providers to succeed for all routes in the group.

func WithGroupMetadata 

func WithGroupMetadata(key string, value any) GroupOption

func WithGroupMiddleware 

func WithGroupMiddleware(mw ...Middleware) GroupOption

Group option constructors.

func WithGroupRequiredScopes 

func WithGroupRequiredScopes(scopes ...string) GroupOption

WithGroupRequiredScopes sets required scopes for all routes in a group.

func WithGroupTags 

func WithGroupTags(tags ...string) GroupOption

type HTTPChannelBinding 

type HTTPChannelBinding = shared.HTTPChannelBinding

Type aliases for AsyncAPI types.

type HTTPError 

type HTTPError = errors.HTTPError

Re-export HTTP error types and constructors for backward compatibility.

type Handler added in v0.5.0 

type Handler func(ctx Context) error

Handler is a forge handler function that takes a Context and returns an error This is the preferred handler pattern for forge applications.

type HandlerPattern 

type HandlerPattern int

HandlerPattern indicates the handler signature. 

const (
	PatternStandard    HandlerPattern = iota // func(w, r)
	PatternContext                           // func(ctx) error
	PatternOpinionated                       // func(ctx, req) (resp, error)
	PatternService                           // func(ctx, svc) error
	PatternCombined                          // func(ctx, svc, req) (resp, error)
)
type Header = shared.Header

Header describes a single header parameter.

type Info 

type Info = shared.Info

Info provides metadata about the API.

type License 

type License = shared.License

License represents license information. 

type Link = shared.Link

Link represents a possible design-time link for a response.

type Logger 

type Logger = logger.Logger

type MediaType 

type MediaType = shared.MediaType

MediaType provides schema and examples for a media type.

type Middleware 

type Middleware func(next Handler) Handler

Middleware wraps forge handlers (new pattern) This is the preferred middleware pattern for forge applications.

func Chain 

func Chain(middlewares ...Middleware) Middleware

Chain combines multiple middleware into a single middleware Middleware are applied in the order they are provided The first middleware in the list wraps the outermost, last wraps the innermost.

func CreateValidationMiddleware 

func CreateValidationMiddleware(validator *SchemaValidator) Middleware

CreateValidationMiddleware creates a middleware that validates requests against schemas.

type MiddlewareFunc 

type MiddlewareFunc func(w http.ResponseWriter, r *http.Request, next http.Handler)

MiddlewareFunc is a convenience type for middleware functions that want to explicitly call the next handler Note: This is a legacy type for http.Handler based middleware For new code, use Middleware directly (func(next Handler) Handler).

func (MiddlewareFunc) ToMiddleware 

func (f MiddlewareFunc) ToMiddleware(container di.Container) Middleware

ToMiddleware converts a MiddlewareFunc to a Middleware This requires a container to create forge contexts.

type OAuthFlow 

type OAuthFlow = shared.OAuthFlow

OAuthFlow defines a single OAuth 2.0 flow.

type OAuthFlows 

type OAuthFlows = shared.OAuthFlows

OAuthFlows defines OAuth 2.0 flows.

type OpenAPIConfig 

type OpenAPIConfig = shared.OpenAPIConfig

OpenAPIConfig configures OpenAPI 3.1.0 generation.

type OpenAPIServer 

type OpenAPIServer = shared.OpenAPIServer

OpenAPIServer represents a server in the OpenAPI spec.

type OpenAPISpec 

type OpenAPISpec = shared.OpenAPISpec

OpenAPISpec represents the complete OpenAPI 3.1.0 specification.

type OpenAPITag 

type OpenAPITag = shared.OpenAPITag

OpenAPITag represents a tag in the OpenAPI spec.

type Operation 

type Operation = shared.Operation

Operation describes a single API operation on a path.

type Parameter 

type Parameter = shared.Parameter

Parameter describes a single operation parameter.

type ParameterDef 

type ParameterDef struct {
	Name        string
	In          string
	Description string
	Required    bool
	Example     any
}

ParameterDef defines a parameter.

type PathItem 

type PathItem = shared.PathItem

PathItem describes operations available on a single path.

type PathParam 

type PathParam struct {
	Name        string
	Description string
	Schema      *Schema
}

PathParam represents a parsed path parameter.

type PureMiddleware added in v0.5.0 

type PureMiddleware func(http.Handler) http.Handler

PureMiddleware wraps HTTP handlers.

func FromMiddleware added in v0.5.0 

func FromMiddleware(m Middleware) PureMiddleware

FromMiddleware converts a Middleware to PureMiddleware This is a convenience wrapper that requires container and errorHandler For use cases where container is not available, use ToPureMiddleware directly.

func ToPureMiddleware added in v0.5.0 

func ToPureMiddleware(m Middleware, container di.Container, errorHandler ErrorHandler) PureMiddleware

ToPureMiddleware converts a Middleware (forge middleware) to a PureMiddleware (http middleware) This allows forge middlewares to work with http.Handler based systems.

func (PureMiddleware) ToMiddleware added in v0.5.0 

func (m PureMiddleware) ToMiddleware() Middleware

ToMiddleware converts a ForgeMiddleware to a legacy Middleware This allows forge middlewares to work with the existing router.

type RequestBody 

type RequestBody = shared.RequestBody

RequestBody describes a single request body.

type RequestBodyDef 

type RequestBodyDef struct {
	Description string
	Required    bool
	Example     any
}

RequestBodyDef defines a request body.

type RequestComponents 

type RequestComponents struct {
	PathParams   []Parameter
	QueryParams  []Parameter
	HeaderParams []Parameter
	BodySchema   *Schema
	HasBody      bool
	IsMultipart  bool // true if the schema contains file uploads or form:"" tags
}

RequestComponents holds all components of a request extracted from a unified schema.

type Response 

type Response = shared.Response

Response describes a single response from an API operation.

type ResponseDef 

type ResponseDef struct {
	Description string
	Example     any
}

ResponseDef defines a response.

type ResponseSchemaDef 

type ResponseSchemaDef struct {
	Description string
	Schema      any
}

ResponseSchemaDef defines a response schema.

type RouteConfig 

type RouteConfig struct {
	Name        string
	Summary     string
	Description string
	Tags        []string
	Middleware  []Middleware
	Timeout     time.Duration
	Metadata    map[string]any
	Extensions  map[string]Extension

	// OpenAPI metadata
	OperationID string
	Deprecated  bool
}

RouteConfig holds route configuration.

type RouteExtension 

type RouteExtension interface {
	Name() string
	Validate() error
}

RouteExtension represents a route-level extension (e.g., OpenAPI, custom validation) Note: This is different from app-level Extension which manages app components.

type RouteInfo 

type RouteInfo struct {
	Name        string
	Method      string
	Path        string
	Pattern     string
	Handler     any
	Middleware  []Middleware
	Tags        []string
	Metadata    map[string]any
	Extensions  map[string]Extension
	Summary     string
	Description string
}

RouteInfo provides route information for inspection.

type RouteOption 

type RouteOption interface {
	Apply(*RouteConfig)
}

RouteOption configures a route.

func WithAcceptedResponse 

func WithAcceptedResponse() RouteOption

WithAcceptedResponse creates a 202 Accepted response for async operations.

func WithAsyncAPIBinding 

func WithAsyncAPIBinding(bindingType string, binding any) RouteOption

WithAsyncAPIBinding adds protocol-specific bindings bindingType: "ws" or "http" or "server" or "channel" or "operation" or "message" binding: the binding object (e.g., WebSocketChannelBinding, HTTPServerBinding)

func WithAsyncAPIChannelDescription 

func WithAsyncAPIChannelDescription(description string) RouteOption

WithAsyncAPIChannelDescription sets the channel description.

func WithAsyncAPIChannelName 

func WithAsyncAPIChannelName(name string) RouteOption

WithAsyncAPIChannelName sets a custom channel name (overrides path-based naming).

func WithAsyncAPIChannelSummary 

func WithAsyncAPIChannelSummary(summary string) RouteOption

WithAsyncAPIChannelSummary sets the channel summary.

func WithAsyncAPIExternalDocs 

func WithAsyncAPIExternalDocs(url, description string) RouteOption

WithAsyncAPIExternalDocs adds external documentation link.

func WithAsyncAPIOperationID 

func WithAsyncAPIOperationID(id string) RouteOption

WithAsyncAPIOperationID sets a custom operation ID for AsyncAPI.

func WithAsyncAPISecurity 

func WithAsyncAPISecurity(requirements map[string][]string) RouteOption

WithAsyncAPISecurity adds security requirements to the operation.

func WithAsyncAPITags 

func WithAsyncAPITags(tags ...string) RouteOption

WithAsyncAPITags adds tags to the AsyncAPI operation.

func WithAuth 

func WithAuth(providerNames ...string) RouteOption

WithAuth adds authentication to a route using one or more providers. Multiple providers create an OR condition - any one succeeding allows access.

Example: 

router.GET("/protected", handler,
    forge.WithAuth("api-key", "jwt"),
)

func WithAuthAnd 

func WithAuthAnd(providerNames ...string) RouteOption

WithAuthAnd requires ALL specified providers to succeed (AND condition). This is useful for multi-factor authentication or combining auth methods.

Example: 

router.GET("/high-security", handler,
    forge.WithAuthAnd("api-key", "mfa"),
)

func WithBatchResponse 

func WithBatchResponse(itemType any, statusCode int) RouteOption

WithBatchResponse creates a response for batch operations.

func WithCallback 

func WithCallback(config CallbackConfig) RouteOption

WithCallback adds a callback definition to a route.

func WithCorrelationID 

func WithCorrelationID(location, description string) RouteOption

WithCorrelationID adds correlation ID configuration for request-reply patterns location: runtime expression like "$message.header#/correlationId" description: description of the correlation ID

func WithCreatedResponse 

func WithCreatedResponse(resourceType any) RouteOption

WithCreatedResponse creates a 201 Created response with Location header.

func WithDeprecated 

func WithDeprecated() RouteOption

func WithDescription 

func WithDescription(desc string) RouteOption

func WithDiscriminator 

func WithDiscriminator(config DiscriminatorConfig) RouteOption

WithDiscriminator adds discriminator support for polymorphic schemas.

func WithErrorResponses 

func WithErrorResponses() RouteOption

WithErrorResponses adds standard HTTP error responses to a route Includes 400, 401, 403, 404, 500.

func WithExtension 

func WithExtension(name string, ext Extension) RouteOption

func WithExternalDocs 

func WithExternalDocs(description, url string) RouteOption

WithExternalDocs adds external documentation link.

func WithFileUploadResponse 

func WithFileUploadResponse(statusCode int) RouteOption

WithFileUploadResponse creates a response for file upload success.

func WithHeaderSchema 

func WithHeaderSchema(schemaType any) RouteOption

WithHeaderSchema sets the header parameters schema for OpenAPI generation schemaType should be a struct with header tags.

func WithListResponse 

func WithListResponse(itemType any, statusCode int) RouteOption

WithListResponse creates a simple list response (array of items).

func WithMessageContentType 

func WithMessageContentType(contentType string) RouteOption

WithMessageContentType sets the content type for messages Default is "application/json".

func WithMessageExample 

func WithMessageExample(direction, name string, example any) RouteOption

WithMessageExample adds a single message example.

func WithMessageExamples 

func WithMessageExamples(direction string, examples map[string]any) RouteOption

WithMessageExamples adds message examples for send/receive direction: "send" or "receive" examples: map of example name to example value

func WithMessageHeaders 

func WithMessageHeaders(headersSchema any) RouteOption

WithMessageHeaders defines headers schema for messages headersSchema: Go type with header:"name" tags.

func WithMetadata 

func WithMetadata(key string, value any) RouteOption

func WithMiddleware 

func WithMiddleware(mw ...Middleware) RouteOption

func WithName 

func WithName(name string) RouteOption

Route option constructors.

func WithNoContentResponse 

func WithNoContentResponse() RouteOption

WithNoContentResponse creates a 204 No Content response.

func WithOperationID 

func WithOperationID(id string) RouteOption

func WithPaginatedResponse 

func WithPaginatedResponse(itemType any, statusCode int) RouteOption

WithPaginatedResponse creates a route option for paginated list responses itemType should be a pointer to the item struct type.

func WithParameter 

func WithParameter(name, in, description string, required bool, example any) RouteOption

WithParameter adds a parameter definition.

func WithQuerySchema 

func WithQuerySchema(schemaType any) RouteOption

WithQuerySchema sets the query parameters schema for OpenAPI generation schemaType should be a struct with query tags.

func WithRequestBody 

func WithRequestBody(description string, required bool, example any) RouteOption

WithRequestBody adds request body documentation.

func WithRequestBodySchema 

func WithRequestBodySchema(schemaOrType any) RouteOption

WithRequestBodySchema sets only the request body schema for OpenAPI generation Use this for explicit body-only schemas, or when you need separate schemas for different parts of the request. schemaOrType can be either: - A pointer to a struct instance for automatic schema generation - A *Schema for manual schema specification.

func WithRequestContentTypes 

func WithRequestContentTypes(types ...string) RouteOption

WithRequestContentTypes specifies the content types for request body.

func WithRequestExample 

func WithRequestExample(name string, example any) RouteOption

WithRequestExample adds an example for the request body.

func WithRequestSchema 

func WithRequestSchema(schemaOrType any) RouteOption

WithRequestSchema sets the unified request schema for OpenAPI generation This is the recommended approach for new code.

The struct fields are classified based on tags: - path:"paramName" - Path parameter - query:"paramName" - Query parameter - header:"HeaderName" - Header parameter - body:"" or json:"fieldName" - Request body field

Example: 

type CreateUserRequest struct {
    TenantID string `path:"tenantId" description:"Tenant ID" format:"uuid"`
    DryRun   bool   `query:"dryRun" description:"Preview mode"`
    APIKey   string `header:"X-API-Key" description:"API Key"`
    Name     string `json:"name" body:"" description:"User name" minLength:"1"`
    Email    string `json:"email" body:"" description:"Email" format:"email"`
}

If the struct has no path/query/header tags, it's treated as body-only for backward compatibility with existing code.

func WithRequiredAuth 

func WithRequiredAuth(providerName string, scopes ...string) RouteOption

WithRequiredAuth adds authentication with required scopes/permissions. The specified provider must succeed AND the auth context must have all required scopes.

Example: 

router.POST("/admin/users", handler,
    forge.WithRequiredAuth("jwt", "write:users", "admin"),
)

func WithResponse 

func WithResponse(code int, description string, example any) RouteOption

WithResponse adds a response definition to the route.

func WithResponseContentTypes 

func WithResponseContentTypes(types ...string) RouteOption

WithResponseContentTypes specifies the content types for response body.

func WithResponseExample 

func WithResponseExample(statusCode int, name string, example any) RouteOption

WithResponseExample adds an example for a specific response status code.

func WithResponseSchema 

func WithResponseSchema(statusCode int, description string, schemaOrType any) RouteOption

WithResponseSchema sets the response schema for OpenAPI generation statusCode is the HTTP status code (e.g., 200, 201) schemaOrType can be either: - A pointer to a struct instance for automatic schema generation - A *Schema for manual schema specification.

func WithSSEMessage 

func WithSSEMessage(eventName string, schema any) RouteOption

WithSSEMessage defines a single message schema for SSE endpoints eventName: the SSE event name (e.g., "message", "update", "notification") schema: the message schema

func WithSSEMessages 

func WithSSEMessages(messageSchemas map[string]any) RouteOption

WithSSEMessages defines message schemas for SSE endpoints messageSchemas: map of event names to their schemas SSE is receive-only (server -> client), so action is always "receive".

func WithSchemaRef 

func WithSchemaRef(name string, schema any) RouteOption

WithSchemaRef adds a schema reference to components.

func WithSecurity 

func WithSecurity(schemes ...string) RouteOption

WithSecurity sets security requirements for a route.

func WithServerProtocol 

func WithServerProtocol(serverNames ...string) RouteOption

WithServerProtocol specifies which servers this operation should be available on serverNames: list of server names from AsyncAPIConfig.Servers.

func WithStandardRESTResponses 

func WithStandardRESTResponses(resourceType any) RouteOption

WithStandardRESTResponses adds standard REST CRUD responses for a resource Includes 200 (GET/list), 201 (POST), 204 (DELETE), 400, 404, 500.

func WithStrictValidation 

func WithStrictValidation() RouteOption

WithStrictValidation enables strict validation (validates both request and response).

func WithSummary 

func WithSummary(summary string) RouteOption

func WithTags 

func WithTags(tags ...string) RouteOption

func WithTimeout 

func WithTimeout(d time.Duration) RouteOption

func WithValidation 

func WithValidation(enabled bool) RouteOption

WithValidation adds validation middleware to a route.

func WithValidationErrorResponse 

func WithValidationErrorResponse() RouteOption

WithValidationErrorResponse adds a 422 Unprocessable Entity response for validation errors.

func WithWebSocketMessages 

func WithWebSocketMessages(sendSchema, receiveSchema any) RouteOption

WithWebSocketMessages defines send/receive message schemas for WebSocket endpoints sendSchema: messages that the client sends to the server (action: send) receiveSchema: messages that the server sends to the client (action: receive).

func WithWebTransport 

func WithWebTransport(config WebTransportConfig) RouteOption

WithWebTransport enables WebTransport support with the given configuration.

func WithWebTransportDatagrams 

func WithWebTransportDatagrams(enabled bool) RouteOption

WithWebTransportDatagrams enables datagram support for WebTransport.

func WithWebTransportStreams 

func WithWebTransportStreams(maxBidi, maxUni int64) RouteOption

WithWebTransportStreams sets the maximum number of streams.

func WithWebhook 

func WithWebhook(name string, operation *CallbackOperation) RouteOption

WithWebhook adds a webhook definition to the OpenAPI spec Webhooks are documented at the API level, not per-route.

type Router 

type Router interface {
	// HTTP Methods - register routes
	GET(path string, handler any, opts ...RouteOption) error
	POST(path string, handler any, opts ...RouteOption) error
	PUT(path string, handler any, opts ...RouteOption) error
	DELETE(path string, handler any, opts ...RouteOption) error
	PATCH(path string, handler any, opts ...RouteOption) error
	OPTIONS(path string, handler any, opts ...RouteOption) error
	HEAD(path string, handler any, opts ...RouteOption) error

	// Grouping - organize routes
	Group(prefix string, opts ...GroupOption) Router

	// Middleware - wrap handlers
	Use(middleware ...Middleware)

	// Controller registration
	RegisterController(controller Controller) error

	// Lifecycle
	Start(ctx context.Context) error
	Stop(ctx context.Context) error

	// HTTP serving
	ServeHTTP(w http.ResponseWriter, r *http.Request)
	Handler() http.Handler

	// Inspection
	Routes() []RouteInfo
	RouteByName(name string) (RouteInfo, bool)
	RoutesByTag(tag string) []RouteInfo
	RoutesByMetadata(key string, value any) []RouteInfo

	// OpenAPI
	OpenAPISpec() *OpenAPISpec

	// AsyncAPI
	AsyncAPISpec() *AsyncAPISpec

	// Streaming
	WebSocket(path string, handler WebSocketHandler, opts ...RouteOption) error
	EventStream(path string, handler SSEHandler, opts ...RouteOption) error

	// WebTransport
	WebTransport(path string, handler WebTransportHandler, opts ...RouteOption) error
	EnableWebTransport(config WebTransportConfig) error
	StartHTTP3(addr string, tlsConfig *tls.Config) error
	StopHTTP3() error
}

Router provides HTTP routing with multiple backend support.

func GetRouter added in v0.5.0 

func GetRouter(container shared.Container) (Router, error)

GetRouter resolves the router from the container This is a convenience function for resolving the router service.

func NewRouter 

func NewRouter(opts ...RouterOption) Router

NewRouter creates a new router with options.

type RouterAdapter 

type RouterAdapter = shared.RouterAdapter

RouterAdapter wraps a routing backend.

func NewBunRouterAdapter 

func NewBunRouterAdapter() RouterAdapter

NewBunRouterAdapter creates a BunRouter adapter (default).

type RouterOption 

type RouterOption interface {
	Apply(*routerConfig)
}

RouterOption configures the router.

func WithAdapter 

func WithAdapter(adapter RouterAdapter) RouterOption

Router option constructors.

func WithAsyncAPI 

func WithAsyncAPI(config AsyncAPIConfig) RouterOption

WithAsyncAPI enables AsyncAPI 3.0.0 spec generation.

func WithContainer 

func WithContainer(container di.Container) RouterOption

func WithErrorHandler 

func WithErrorHandler(handler ErrorHandler) RouterOption

func WithHealth 

func WithHealth(config shared.HealthConfig) RouterOption

WithHealth enables health checks.

func WithLogger 

func WithLogger(logger Logger) RouterOption

func WithMetrics 

func WithMetrics(config shared.MetricsConfig) RouterOption

WithMetrics enables metrics collection.

func WithOpenAPI 

func WithOpenAPI(config OpenAPIConfig) RouterOption

WithOpenAPI enables OpenAPI 3.1.0 spec generation.

func WithRecovery 

func WithRecovery() RouterOption

type SSEHandler 

type SSEHandler func(ctx Context, stream Stream) error

SSEHandler handles Server-Sent Events.

type Schema 

type Schema = shared.Schema

Schema represents a JSON Schema (OpenAPI 3.1.0 uses JSON Schema 2020-12).

func GetSchemaFromType 

func GetSchemaFromType(t reflect.Type) *Schema

GetSchemaFromType is a helper to get schema from a type.

type SchemaValidator 

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

SchemaValidator validates data against JSON schemas.

func NewSchemaValidator 

func NewSchemaValidator() *SchemaValidator

NewSchemaValidator creates a new schema validator.

func (*SchemaValidator) RegisterSchema 

func (v *SchemaValidator) RegisterSchema(name string, schema *Schema)

RegisterSchema registers a schema with a name.

func (*SchemaValidator) ValidateRequest 

func (v *SchemaValidator) ValidateRequest(schema *Schema, data any) error

ValidateRequest validates request data against a schema.

func (*SchemaValidator) ValidateResponse 

func (v *SchemaValidator) ValidateResponse(schema *Schema, data any) error

ValidateResponse validates response data against a schema.

type SecurityRequirement 

type SecurityRequirement = shared.SecurityRequirement

SecurityRequirement lists required security schemes.

type SecurityScheme 

type SecurityScheme = shared.SecurityScheme

SecurityScheme defines a security scheme.

type Stream 

type Stream interface {
	// Send sends an event to the stream
	Send(event string, data []byte) error

	// SendJSON sends JSON event to the stream
	SendJSON(event string, v any) error

	// Flush flushes any buffered data
	Flush() error

	// Close closes the stream
	Close() error

	// Context returns the stream context
	Context() context.Context

	// SetRetry sets the retry timeout for SSE
	SetRetry(milliseconds int) error

	// SendComment sends a comment (keeps connection alive)
	SendComment(comment string) error
}

Stream represents a Server-Sent Events stream.

type StreamConfig 

type StreamConfig struct {
	// WebSocket configuration
	ReadBufferSize    int
	WriteBufferSize   int
	EnableCompression bool

	// SSE configuration
	RetryInterval int // milliseconds
	KeepAlive     bool

	// WebTransport configuration
	EnableWebTransport      bool
	MaxBidiStreams          int64
	MaxUniStreams           int64
	MaxDatagramFrameSize    int64
	EnableDatagrams         bool
	StreamReceiveWindow     uint64
	ConnectionReceiveWindow uint64
	WebTransportKeepAlive   int // milliseconds
	WebTransportMaxIdle     int // milliseconds
}

StreamConfig configures streaming behavior.

func DefaultStreamConfig 

func DefaultStreamConfig() StreamConfig

DefaultStreamConfig returns default streaming configuration.

type ValidationError 

type ValidationError = shared.ValidationError

Re-export validation types from shared to maintain backward compatibility

type ValidationErrorResponse 

type ValidationErrorResponse = shared.ValidationErrorResponse

type ValidationErrors 

type ValidationErrors = shared.ValidationErrors

type WebSocketChannelBinding 

type WebSocketChannelBinding = shared.WebSocketChannelBinding

Type aliases for AsyncAPI types.

type WebSocketHandler 

type WebSocketHandler func(ctx Context, conn Connection) error

WebSocketHandler handles WebSocket connections.

type WebTransportConfig 

type WebTransportConfig struct {
	// Maximum bidirectional streams
	MaxBidiStreams int64

	// Maximum unidirectional streams
	MaxUniStreams int64

	// Maximum datagram frame size
	MaxDatagramFrameSize int64

	// Enable datagram support
	EnableDatagrams bool

	// Stream receive window
	StreamReceiveWindow uint64

	// Connection receive window
	ConnectionReceiveWindow uint64

	// Keep alive interval
	KeepAliveInterval int // milliseconds

	// Max idle timeout
	MaxIdleTimeout int // milliseconds
}

WebTransportConfig configures WebTransport behavior.

func DefaultWebTransportConfig 

func DefaultWebTransportConfig() WebTransportConfig

DefaultWebTransportConfig returns default WebTransport configuration.

type WebTransportHandler 

type WebTransportHandler func(ctx Context, session WebTransportSession) error

WebTransportHandler handles WebTransport sessions.

type WebTransportSession 

type WebTransportSession interface {
	// ID returns unique session ID
	ID() string

	// OpenStream opens a new bidirectional stream
	OpenStream() (WebTransportStream, error)

	// OpenUniStream opens a new unidirectional stream
	OpenUniStream() (WebTransportStream, error)

	// AcceptStream accepts an incoming bidirectional stream
	AcceptStream(ctx context.Context) (WebTransportStream, error)

	// AcceptUniStream accepts an incoming unidirectional stream
	AcceptUniStream(ctx context.Context) (WebTransportStream, error)

	// ReceiveDatagram receives a datagram
	ReceiveDatagram(ctx context.Context) ([]byte, error)

	// SendDatagram sends a datagram
	SendDatagram(data []byte) error

	// Close closes the session
	Close() error

	// Context returns the session context
	Context() context.Context

	// RemoteAddr returns the remote address
	RemoteAddr() string

	// LocalAddr returns the local address
	LocalAddr() string
}

WebTransportSession represents a WebTransport session.

type WebTransportStream 

type WebTransportStream interface {
	io.ReadWriteCloser

	// StreamID returns the stream ID
	StreamID() uint64

	// Read reads data from the stream
	Read(p []byte) (n int, err error)

	// Write writes data to the stream
	Write(p []byte) (n int, err error)

	// ReadJSON reads JSON from the stream
	ReadJSON(v any) error

	// WriteJSON writes JSON to the stream
	WriteJSON(v any) error

	// Close closes the stream
	Close() error
}

WebTransportStream represents a WebTransport stream.

Source Files

View all Source files

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.