hyperserve

package module
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2025 License: MIT Imports: 7 Imported by: 0

README

HyperServe

HyperServe lets humans and AI assistants co-manage the same production-grade Go services. A zero-dependency, high-performance core ships with native Model Context Protocol (MCP) control surfaces and hardened defaults so you can automate safely from laptop to regulated environments.

Features

  • 🧱 Project Scaffold - Generate secure, MCP-ready services via hyperserve-init
  • 🚀 Minimal Dependencies - Only 1 dependency (golang.org/x/time)
  • 🤖 MCP Support - Built-in Model Context Protocol for AI assistants
  • 🔌 WebSocket Support - Real-time bidirectional communication
  • 🛡️ Security Middleware - Hardened headers, auth, and rate limiting ready to enable
  • 📊 Observable - Metrics, health checks, and structured logging
  • ⚡ High Performance - Optimized for throughput and low latency
  • 🔧 Battle-tested HTTP/2 - Leverages Go's excellent standard library

Quick Start

srv, _ := hyperserve.NewServer()
srv.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintln(w, "Hello, World!")
})
srv.Run()

Scaffold a New Service

go install github.com/osauer/hyperserve/cmd/hyperserve-init@latest
hyperserve-init --module github.com/acme/payments
cd payments
go run ./cmd/server

Flags include --name (display name), --out (output directory), --with-mcp=false to opt out of MCP, and --local-replace for working against a local HyperServe checkout during development.

Installation

go get github.com/osauer/hyperserve

MCP (Model Context Protocol)

HyperServe includes native MCP support, enabling AI assistants to:

  • Execute tools and access resources
  • Connect via HTTP or Server-Sent Events (SSE)
  • Discover capabilities automatically

Enable MCP with environment variables:

HS_MCP_ENABLED=true
HS_MCP_SERVER_NAME=MyServer
HS_MCP_SERVER_VERSION=1.0.0

Or programmatically:

srv, _ := hyperserve.NewServer(
    hyperserve.WithMCPSupport("MyServer", "1.0.0"),
    hyperserve.WithMCPBuiltinTools(true),
    hyperserve.WithMCPBuiltinResources(true),
)
Common Middleware

NewServer wires in recovery, request logging, and metrics collectors. Security middleware (headers, auth, rate limiting) can be enabled per route:

srv, _ := hyperserve.NewServer()
srv.AddMiddleware("/api", hyperserve.RateLimitMiddleware(srv))
srv.AddMiddlewareStack("/web", hyperserve.SecureWeb(srv.Options))

Examples

See the examples directory for comprehensive examples including:

  • Basic HTTP server
  • WebSocket implementation
  • MCP integration
  • Authentication and RBAC
  • Enterprise features
  • Best practices

Documentation

Contributing

See CONTRIBUTING.md for guidelines on contributing.

License

MIT License - see LICENSE for details.

Documentation

Index

Constants

View Source 
const (
	ErrorCodeParseError     = pkgjsonrpc.ErrorCodeParseError
	ErrorCodeInvalidRequest = pkgjsonrpc.ErrorCodeInvalidRequest
	ErrorCodeMethodNotFound = pkgjsonrpc.ErrorCodeMethodNotFound
	ErrorCodeInvalidParams  = pkgjsonrpc.ErrorCodeInvalidParams
	ErrorCodeInternalError  = pkgjsonrpc.ErrorCodeInternalError
)
View Source 
const (
	DiscoveryPublic        = pkgserver.DiscoveryPublic
	DiscoveryCount         = pkgserver.DiscoveryCount
	DiscoveryAuthenticated = pkgserver.DiscoveryAuthenticated
	DiscoveryNone          = pkgserver.DiscoveryNone
)
View Source 
const (
	GlobalMiddlewareRoute        = pkgserver.GlobalMiddlewareRoute
	TextMessage                  = pkgserver.TextMessage
	BinaryMessage                = pkgserver.BinaryMessage
	CloseMessage                 = pkgserver.CloseMessage
	PingMessage                  = pkgserver.PingMessage
	PongMessage                  = pkgserver.PongMessage
	CloseNormalClosure           = pkgserver.CloseNormalClosure
	CloseGoingAway               = pkgserver.CloseGoingAway
	CloseProtocolError           = pkgserver.CloseProtocolError
	CloseUnsupportedData         = pkgserver.CloseUnsupportedData
	CloseNoStatusReceived        = pkgserver.CloseNoStatusReceived
	CloseAbnormalClosure         = pkgserver.CloseAbnormalClosure
	CloseInvalidFramePayloadData = pkgserver.CloseInvalidFramePayloadData
	ClosePolicyViolation         = pkgserver.ClosePolicyViolation
	CloseMessageTooBig           = pkgserver.CloseMessageTooBig
	CloseMandatoryExtension      = pkgserver.CloseMandatoryExtension
	CloseInternalServerError     = pkgserver.CloseInternalServerError
	CloseServiceRestart          = pkgserver.CloseServiceRestart
	CloseTryAgainLater           = pkgserver.CloseTryAgainLater
	CloseTLSHandshake            = pkgserver.CloseTLSHandshake
	MCPVersion                   = pkgserver.MCPVersion
	HTTPTransport                = pkgserver.HTTPTransport
	StdioTransport               = pkgserver.StdioTransport
	LevelDebug                   = pkgserver.LevelDebug
	LevelInfo                    = pkgserver.LevelInfo
	LevelWarn                    = pkgserver.LevelWarn
	LevelError                   = pkgserver.LevelError
)
View Source 
const (
	// JSONRPCVersion is re-exported from pkg/jsonrpc for backwards compatibility.
	JSONRPCVersion = pkgjsonrpc.Version
)

Variables

View Source 
var (
	ErrNotWebSocket = pkgserver.ErrNotWebSocket
	ErrBadHandshake = pkgserver.ErrBadHandshake
)

Functions

func CheckOriginWithAllowedList added in v0.21.0 

func CheckOriginWithAllowedList(origins []string) func(*http.Request) bool

func DefaultCheckOrigin added in v0.21.0 

func DefaultCheckOrigin(r *http.Request) bool

func DefaultLogger added in v0.21.0 

func DefaultLogger() *slog.Logger

func EnsureTrailingSlash 

func EnsureTrailingSlash(dir string) string

func GetVersionInfo added in v0.9.7 

func GetVersionInfo() string

func HealthCheckHandler 

func HealthCheckHandler(w http.ResponseWriter, r *http.Request)

func IsCloseError added in v0.10.0 

func IsCloseError(err error, codes ...int) bool

func IsUnexpectedCloseError added in v0.10.0 

func IsUnexpectedCloseError(err error, expectedCodes ...int) bool

func PanicHandler 

func PanicHandler(w http.ResponseWriter, r *http.Request)

func RecoveryMiddleware 

func RecoveryMiddleware(next http.Handler) http.HandlerFunc

func RequestLoggerMiddleware 

func RequestLoggerMiddleware(next http.Handler) http.HandlerFunc

func ResponseTimeMiddleware 

func ResponseTimeMiddleware(next http.Handler) http.HandlerFunc

func SetDefaultLogger added in v0.21.0 

func SetDefaultLogger(l *slog.Logger)

func TraceMiddleware 

func TraceMiddleware(next http.Handler) http.HandlerFunc

Types

type AuthTokenInjector added in v0.20.1 

type AuthTokenInjector = pkgserver.AuthTokenInjector

func NewAuthTokenInjector added in v0.20.1 

func NewAuthTokenInjector(provider func(context.Context) (string, error)) *AuthTokenInjector

type CORSOptions added in v0.20.1 

type CORSOptions = pkgserver.CORSOptions

type Conn added in v0.10.0 

type Conn = pkgserver.Conn

type DiscoveryPolicy added in v0.18.0 

type DiscoveryPolicy = pkgserver.DiscoveryPolicy

type InterceptableRequest added in v0.20.1 

type InterceptableRequest = pkgserver.InterceptableRequest

type InterceptableResponse added in v0.20.1 

type InterceptableResponse = pkgserver.InterceptableResponse

type Interceptor added in v0.20.1 

type Interceptor = pkgserver.Interceptor

type InterceptorChain added in v0.20.1 

type InterceptorChain = pkgserver.InterceptorChain

func NewInterceptorChain added in v0.20.1 

func NewInterceptorChain() *InterceptorChain

type InterceptorResponse added in v0.20.1 

type InterceptorResponse = pkgserver.InterceptorResponse

type JSONRPCEngine 

type JSONRPCEngine = pkgjsonrpc.Engine

JSONRPCEngine re-exports pkg/jsonrpc.Engine.

func NewJSONRPCEngine 

func NewJSONRPCEngine() *JSONRPCEngine

NewJSONRPCEngine preserves the public API while delegating to pkg/jsonrpc.

func NewJSONRPCEngineWithLogger added in v0.21.0 

func NewJSONRPCEngineWithLogger(log *slog.Logger) *JSONRPCEngine

NewJSONRPCEngineWithLogger allows callers to override the logger used by the engine.

type JSONRPCError 

type JSONRPCError = pkgjsonrpc.ErrorDetails

JSONRPCError re-exports pkg/jsonrpc.ErrorDetails.

type JSONRPCMethodHandler 

type JSONRPCMethodHandler = pkgjsonrpc.MethodHandler

JSONRPCMethodHandler re-exports pkg/jsonrpc.MethodHandler.

type JSONRPCRequest 

type JSONRPCRequest = pkgjsonrpc.Request

JSONRPCRequest re-exports pkg/jsonrpc.Request.

type JSONRPCResponse 

type JSONRPCResponse = pkgjsonrpc.Response

JSONRPCResponse re-exports pkg/jsonrpc.Response.

type LoggingCapability 

type LoggingCapability = pkgserver.LoggingCapability

type MCPCapabilities 

type MCPCapabilities = pkgserver.MCPCapabilities

type MCPClientInfo 

type MCPClientInfo = pkgserver.MCPClientInfo

type MCPDiscoveryInfo added in v0.17.0 

type MCPDiscoveryInfo = pkgserver.MCPDiscoveryInfo

type MCPExtension added in v0.11.0 

type MCPExtension = pkgserver.MCPExtension

func ExampleECommerceExtension added in v0.11.0 

func ExampleECommerceExtension() MCPExtension

type MCPExtensionBuilder added in v0.11.0 

type MCPExtensionBuilder = pkgserver.MCPExtensionBuilder

func NewMCPExtension added in v0.11.0 

func NewMCPExtension(name string) *MCPExtensionBuilder

type MCPHandler 

type MCPHandler = pkgserver.MCPHandler

func NewMCPHandler 

func NewMCPHandler(serverInfo MCPServerInfo) *MCPHandler

type MCPInitializeParams 

type MCPInitializeParams = pkgserver.MCPInitializeParams

type MCPInitializeResult 

type MCPInitializeResult = pkgserver.MCPInitializeResult

type MCPMetrics added in v0.9.2 

type MCPMetrics = pkgserver.MCPMetrics

type MCPNamespace added in v0.15.0 

type MCPNamespace = pkgserver.MCPNamespace

type MCPNamespaceConfig added in v0.15.0 

type MCPNamespaceConfig = pkgserver.MCPNamespaceConfig

func WithNamespaceResources added in v0.15.0 

func WithNamespaceResources(resources ...MCPResource) MCPNamespaceConfig

func WithNamespaceTools added in v0.15.0 

func WithNamespaceTools(tools ...MCPTool) MCPNamespaceConfig

type MCPResource 

type MCPResource = pkgserver.MCPResource

type MCPResourceContent 

type MCPResourceContent = pkgserver.MCPResourceContent

type MCPResourceInfo 

type MCPResourceInfo = pkgserver.MCPResourceInfo

type MCPResourceReadParams 

type MCPResourceReadParams = pkgserver.MCPResourceReadParams

type MCPServerInfo 

type MCPServerInfo = pkgserver.MCPServerInfo

type MCPTool 

type MCPTool = pkgserver.MCPTool

type MCPToolCallParams 

type MCPToolCallParams = pkgserver.MCPToolCallParams

type MCPToolInfo 

type MCPToolInfo = pkgserver.MCPToolInfo

type MCPToolResult 

type MCPToolResult = pkgserver.MCPToolResult

type MCPToolWithContext added in v0.9.2 

type MCPToolWithContext = pkgserver.MCPToolWithContext

type MCPTransport 

type MCPTransport = pkgserver.MCPTransport

type MCPTransportConfig 

type MCPTransportConfig = pkgserver.MCPTransportConfig

func MCPDev added in v0.11.0 

func MCPDev() MCPTransportConfig

func MCPObservability added in v0.11.0 

func MCPObservability() MCPTransportConfig

func MCPOverHTTP 

func MCPOverHTTP(endpoint string) MCPTransportConfig

func MCPOverStdio 

func MCPOverStdio() MCPTransportConfig

type MCPTransportType 

type MCPTransportType = pkgserver.MCPTransportType

type MiddlewareFunc 

type MiddlewareFunc = pkgserver.MiddlewareFunc

func AuthMiddleware 

func AuthMiddleware(options *ServerOptions) MiddlewareFunc

func ChaosMiddleware 

func ChaosMiddleware(options *ServerOptions) MiddlewareFunc

func HeadersMiddleware 

func HeadersMiddleware(options *ServerOptions) MiddlewareFunc

func MetricsMiddleware 

func MetricsMiddleware(srv *Server) MiddlewareFunc

func RateLimitMiddleware 

func RateLimitMiddleware(srv *Server) MiddlewareFunc

type MiddlewareRegistry 

type MiddlewareRegistry = pkgserver.MiddlewareRegistry

func NewMiddlewareRegistry 

func NewMiddlewareRegistry(globalMiddleware MiddlewareStack) *MiddlewareRegistry

type MiddlewareStack 

type MiddlewareStack = pkgserver.MiddlewareStack

func DefaultMiddleware 

func DefaultMiddleware(srv *Server) MiddlewareStack

func FileServer 

func FileServer(options *ServerOptions) MiddlewareStack

func SecureAPI 

func SecureAPI(srv *Server) MiddlewareStack

func SecureWeb 

func SecureWeb(options *ServerOptions) MiddlewareStack

type PoolConfig added in v0.20.1 

type PoolConfig = pkgwebsocket.PoolConfig

func DefaultPoolConfig added in v0.20.1 

func DefaultPoolConfig() PoolConfig

type PoolStats added in v0.20.1 

type PoolStats = pkgwebsocket.PoolStats

type PromptsCapability 

type PromptsCapability = pkgserver.PromptsCapability

type RateLimit added in v0.21.0 

type RateLimit = pkgserver.RateLimit

type RateLimitInterceptor added in v0.20.1 

type RateLimitInterceptor = pkgserver.RateLimitInterceptor

func NewRateLimitInterceptor added in v0.20.1 

func NewRateLimitInterceptor(limiter RateLimiter) *RateLimitInterceptor

type RateLimiter added in v0.20.1 

type RateLimiter = pkgserver.RateLimiter

type RequestLogger added in v0.20.1 

type RequestLogger = pkgserver.RequestLogger

func NewRequestLogger added in v0.20.1 

func NewRequestLogger(logger func(format string, args ...interface{})) *RequestLogger

type ResourceBuilder added in v0.11.0 

type ResourceBuilder = pkgserver.ResourceBuilder

func NewResource added in v0.11.0 

func NewResource(uri string) *ResourceBuilder

type ResourcesCapability 

type ResourcesCapability = pkgserver.ResourcesCapability

type ResponseTransformer added in v0.20.1 

type ResponseTransformer = pkgserver.ResponseTransformer

func NewResponseTransformer added in v0.20.1 

func NewResponseTransformer(transformer func([]byte, string) ([]byte, error)) *ResponseTransformer

type SSECapability added in v0.16.0 

type SSECapability = pkgserver.SSECapability

type SSEMessage 

type SSEMessage = pkgserver.SSEMessage

func NewSSEMessage 

func NewSSEMessage(data any) *SSEMessage

type SamplingCapability 

type SamplingCapability = pkgserver.SamplingCapability

type Server 

type Server = pkgserver.Server

func NewServer 

func NewServer(opts ...ServerOptionFunc) (*Server, error)

type ServerOptionFunc 

type ServerOptionFunc = pkgserver.ServerOptionFunc

func WithAddr 

func WithAddr(addr string) ServerOptionFunc

func WithAuthTokenValidator 

func WithAuthTokenValidator(validator func(string) (bool, error)) ServerOptionFunc

func WithCORS added in v0.20.1 

func WithCORS(opts *CORSOptions) ServerOptionFunc

func WithCSPWebWorkerSupport added in v0.9.6 

func WithCSPWebWorkerSupport() ServerOptionFunc

func WithDebugMode added in v0.11.0 

func WithDebugMode() ServerOptionFunc

func WithEncryptedClientHello 

func WithEncryptedClientHello(echKeys ...[]byte) ServerOptionFunc

func WithFIPSMode 

func WithFIPSMode() ServerOptionFunc

func WithHardenedMode 

func WithHardenedMode() ServerOptionFunc

func WithHealthServer 

func WithHealthServer() ServerOptionFunc

func WithIdleTimeout added in v0.13.0 

func WithIdleTimeout(timeout time.Duration) ServerOptionFunc

func WithLogger 

func WithLogger(l *slog.Logger) ServerOptionFunc

func WithLoglevel 

func WithLoglevel(level slog.Level) ServerOptionFunc

func WithMCPBuiltinResources added in v0.9.3 

func WithMCPBuiltinResources(enabled bool) ServerOptionFunc

func WithMCPBuiltinTools added in v0.9.3 

func WithMCPBuiltinTools(enabled bool) ServerOptionFunc

func WithMCPDiscoveryFilter added in v0.18.0 

func WithMCPDiscoveryFilter(filter func(string, *http.Request) bool) ServerOptionFunc

func WithMCPDiscoveryPolicy added in v0.18.0 

func WithMCPDiscoveryPolicy(policy pkgserver.DiscoveryPolicy) ServerOptionFunc

func WithMCPEndpoint 

func WithMCPEndpoint(endpoint string) ServerOptionFunc

func WithMCPFileToolRoot 

func WithMCPFileToolRoot(rootDir string) ServerOptionFunc

func WithMCPNamespace added in v0.15.0 

func WithMCPNamespace(name string, configs ...MCPNamespaceConfig) ServerOptionFunc

func WithMCPResourcesDisabled 

func WithMCPResourcesDisabled() ServerOptionFunc

func WithMCPServerInfo 

func WithMCPServerInfo(name, version string) ServerOptionFunc

func WithMCPSupport 

func WithMCPSupport(name, version string, configs ...MCPTransportConfig) ServerOptionFunc

func WithMCPToolsDisabled 

func WithMCPToolsDisabled() ServerOptionFunc

func WithOnShutdown added in v0.20.1 

func WithOnShutdown(hook func(context.Context) error) ServerOptionFunc

func WithRateLimit 

func WithRateLimit(limit RateLimit, burst int) ServerOptionFunc

func WithReadHeaderTimeout added in v0.13.0 

func WithReadHeaderTimeout(timeout time.Duration) ServerOptionFunc

func WithReadTimeout added in v0.13.0 

func WithReadTimeout(timeout time.Duration) ServerOptionFunc

func WithSuppressBanner added in v0.20.1 

func WithSuppressBanner(suppress bool) ServerOptionFunc

func WithTLS 

func WithTLS(certFile, keyFile string) ServerOptionFunc

func WithTemplateDir 

func WithTemplateDir(dir string) ServerOptionFunc

func WithTimeouts 

func WithTimeouts(readTimeout, writeTimeout, idleTimeout time.Duration) ServerOptionFunc

func WithWriteTimeout added in v0.13.0 

func WithWriteTimeout(timeout time.Duration) ServerOptionFunc

type ServerOptions 

type ServerOptions = pkgserver.ServerOptions

func NewServerOptions 

func NewServerOptions() *ServerOptions

type SimpleResource added in v0.11.0 

type SimpleResource = pkgserver.SimpleResource

type SimpleTool added in v0.11.0 

type SimpleTool = pkgserver.SimpleTool

type ToolBuilder added in v0.11.0 

type ToolBuilder = pkgserver.ToolBuilder

func NewTool added in v0.11.0 

func NewTool(name string) *ToolBuilder

type ToolsCapability 

type ToolsCapability = pkgserver.ToolsCapability

type Upgrader added in v0.10.0 

type Upgrader = pkgserver.Upgrader

func WebSocketUpgrader added in v0.21.0 

func WebSocketUpgrader(srv *Server) *Upgrader

type WebSocketPool added in v0.20.1 

type WebSocketPool = pkgwebsocket.WebSocketPool

func NewWebSocketPool added in v0.20.1 

func NewWebSocketPool(config PoolConfig) *WebSocketPool

Source Files

View all Source files

Directories

Path Synopsis
cmd
example-server command
hyperserve-init command
server command
go module
internal
responsewriter
Package responsewriter provides utilities for wrapping http.ResponseWriter while preserving optional interfaces like Hijacker, Flusher, and ReaderFrom.
 Package responsewriter provides utilities for wrapping http.ResponseWriter while preserving optional interfaces like Hijacker, Flusher, and ReaderFrom.
scaffold
ws
Package ws provides low-level WebSocket protocol implementation.
 Package ws provides low-level WebSocket protocol implementation.
pkg
jsonrpc
server
Package hyperserve provides comprehensive MCP (Model Context Protocol) built-in tools and resources.
 Package hyperserve provides comprehensive MCP (Model Context Protocol) built-in tools and resources.
websocket
spec
conformance command

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.