hyperserve

HyperServe

HyperServe is a small, net/http-shaped Go server with an in-process Model Context Protocol (MCP) control plane and an RFC 6455 WebSocket implementation for servers and outbound clients.

The shipped module has one external dependency, golang.org/x/time. Developer tooling lives in the separate tools/go.mod graph and does not enter applications that import HyperServe.

Install

go get github.com/osauer/hyperserve@latest

Public packages:

HTTP quick start

package main

import (
    "fmt"
    "net/http"

    "github.com/osauer/hyperserve/pkg/server"
)

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

HyperServe provides method-aware routes, middleware, graceful shutdown, sandboxed static files, request binding and validation, and deferred startup. It stays close to standard-library handler shapes.

Outbound WebSocket client

websocket.Dial supports ws and wss, context cancellation throughout the opening handshake, TLS verification, bounded redirects, custom headers, subprotocol negotiation, and a 1 MiB default read limit. Client frames are masked on the wire as required by RFC 6455.

package relay

import (
    "context"
    "net/http"
    "time"

    "github.com/osauer/hyperserve/pkg/websocket"
)

func exchange(ctx context.Context, relayURL, token string) error {
    dialCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
    defer cancel()

    conn, resp, err := websocket.Dial(dialCtx, relayURL, &websocket.DialOptions{
        HTTPHeader:  http.Header{"Authorization": {"Bearer " + token}},
        Subprotocols: []string{"relay.v1"},
    })
    if err != nil {
        _ = resp // non-nil when the peer returned an HTTP response
        return err
    }
    defer conn.Close()

    if err := conn.Write(ctx, websocket.TextMessage, []byte("online")); err != nil {
        return err
    }
    messageType, payload, err := conn.Read(ctx)
    _ = messageType
    _ = payload
    return err
}

Read and Write accept contexts and support one concurrent reader plus one concurrent writer. Canceling either operation closes a potentially partial connection. ReadMessage, WriteMessage, and deadline setters remain available for lower-level use. CloseWithStatus sends an explicit close code and reason; Close sends normal closure. Compression and other WebSocket extensions are not negotiated.

WebSocket server

upgrader := websocket.Upgrader{
    AllowedOrigins: []string{"https://app.example.com"},
    MaxMessageSize: 512 << 10,
}

srv.GET("/ws", func(w http.ResponseWriter, r *http.Request) {
    conn, err := upgrader.Upgrade(w, r, nil)
    if err != nil {
        return
    }
    defer conn.Close()

    messageType, payload, err := conn.ReadMessage()
    if err == nil {
        err = conn.WriteMessage(messageType, payload)
    }
    _ = err
})

The upgrader defaults to same-origin browser requests. Configure AllowedOrigins or CheckOrigin deliberately for cross-origin clients. See the WebSocket guide for handshake, limits, and deployment details.

MCP

Enable MCP programmatically:

srv, _ := server.NewServer(
    server.WithMCPSupport("payments", "1.0.0"),
    server.WithMCPBuiltinTools(true),
    server.WithMCPBuiltinResources(true),
)

The unified MCP handler supports HTTP, SSE, and stdio transports, discovery, namespaces, resource templates, and live resource subscriptions. Built-in tools and resources are off by default. See the MCP guide.

Binding and validation

server.JSONHandler, BindJSON, BindQuery, BindForm, and Validate cover typed request input without another dependency. Supported validation rules are required, min, max, len, email, url, and oneof.

type CreateUser struct {
    Email string `json:"email" validate:"required,email"`
}

srv.POST("/users", server.JSONHandler(
    func(ctx context.Context, in CreateUser) (User, error) {
        return createUser(ctx, in)
    },
))

See examples/binding for typed and lower-level forms.

Scaffold a service

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

Use --with-mcp=false to omit MCP and --local-replace when developing against a local HyperServe checkout.

Development

make check
make test-race
make fuzz-smoke

make check runs formatting, vet, Staticcheck, govulncheck, Go 1.27 modernization, standalone example checks, and canonical example builds. See CONTRIBUTING.md for the complete workflow.

Documentation

• Architecture
• API stability
• Production guide
• WebSocket guide
• MCP guide
• Examples
• Security policy

MIT — see LICENSE.