{"id":37187003,"url":"https://github.com/osauer/hyperserve","last_synced_at":"2026-05-24T09:02:20.258Z","repository":{"id":302249170,"uuid":"884660617","full_name":"osauer/hyperserve","owner":"osauer","description":"A lightweight, high-performance HTTP server framework for Go with builtin AI support. This is a hybrid engineering project, human with 🤖","archived":false,"fork":false,"pushed_at":"2025-10-19T12:16:55.000Z","size":105890,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-19T20:18:14.424Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osauer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-07T06:48:17.000Z","updated_at":"2025-10-19T12:16:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"6985b3c2-0a94-4903-8320-2c85a7453841","html_url":"https://github.com/osauer/hyperserve","commit_stats":null,"previous_names":["osauer/hyperserve"],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/osauer/hyperserve","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osauer%2Fhyperserve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osauer%2Fhyperserve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osauer%2Fhyperserve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osauer%2Fhyperserve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osauer","download_url":"https://codeload.github.com/osauer/hyperserve/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osauer%2Fhyperserve/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28436181,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T21:32:52.117Z","status":"ssl_error","status_checked_at":"2026-01-14T21:32:33.442Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T21:43:14.637Z","updated_at":"2026-05-24T09:02:20.251Z","avatar_url":"https://github.com/osauer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperServe\n\n[![CI](https://github.com/osauer/hyperserve/actions/workflows/ci.yml/badge.svg)](https://github.com/osauer/hyperserve/actions/workflows/ci.yml)\n[![Latest release](https://img.shields.io/github/v/release/osauer/hyperserve?label=release\u0026sort=semver)](https://github.com/osauer/hyperserve/releases/latest)\n[![Go version](https://img.shields.io/github/go-mod/go-version/osauer/hyperserve)](go.mod)\n[![Go reference](https://pkg.go.dev/badge/github.com/osauer/hyperserve.svg)](https://pkg.go.dev/github.com/osauer/hyperserve)\n[![License: MIT](https://img.shields.io/github/license/osauer/hyperserve)](LICENSE)\n\nA Go HTTP framework with built-in MCP (Model Context Protocol) support. The runtime\nhas one transitive dependency: `golang.org/x/time`. (The `go.mod` `tool` directive\npulls in `golang.org/x/tools` for the modernize check gate; those are build-time\nonly and don't ship in your binary.)\n\nThe point: a small `net/http`-shaped server that ships an MCP control plane in the\nsame binary, so AI assistants can introspect and operate the server without an\nout-of-process bridge.\n\n## Quick Start\n\n```go\nimport (\n    \"fmt\"\n    \"net/http\"\n\n    server \"github.com/osauer/hyperserve/pkg/server\"\n)\n\nfunc main() {\n    srv, _ := server.NewServer()\n\n    srv.HandleFunc(\"/\", func(w http.ResponseWriter, r *http.Request) {\n        fmt.Fprintln(w, \"Hello, World!\")\n    })\n\n    srv.Run()\n}\n```\n\n## Install\n\n```bash\ngo get github.com/osauer/hyperserve/pkg/server\n```\n\n## What's in the box\n\n- HTTP server built on `net/http`, with grouping, middleware chain, and graceful shutdown.\n- Method-aware route registration (`srv.GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`)\n  on top of stdlib 1.22+ pattern syntax — wrong-method requests get an automatic 405.\n- MCP server (HTTP, SSE, stdio transports) with discovery endpoints, namespace support,\n  resource templates, and live resource subscriptions.\n- WebSocket implementation (RFC 6455).\n- JSON-RPC 2.0 engine reused by MCP.\n- Middleware: recovery, request logging, metrics, CORS, security headers, rate limiting, auth.\n- Static file serving sandboxed via `os.Root`.\n- Deferred-init lifecycle: serve `/healthz` immediately while bootstrap work runs in the background.\n- **Request binding + validation** with struct-tag rules\n  (`required,min,max,len,email,url,oneof`) and structured `*ValidationError`\n  for per-field 400 responses. Use `server.JSONHandler[In, Out]` for typed\n  bind + validate + respond in one line, or drop to `server.Bind` /\n  `BindJSON` / `BindQuery` / `BindForm` for finer control. No external\n  dependencies. See [examples/binding](./examples/binding/).\n\n## Scaffold a new service\n\n```bash\ngo install github.com/osauer/hyperserve/cmd/hyperserve-init@latest\nhyperserve-init --module github.com/acme/payments\ncd payments\ngo run ./cmd/server\n```\n\nFlags: `--name` (display name), `--out` (output directory), `--with-mcp=false` to opt\nout of MCP, `--local-replace` to develop against a local checkout.\n\n## MCP\n\n```bash\nHS_MCP_ENABLED=true\nHS_MCP_SERVER_NAME=MyServer\nHS_MCP_SERVER_VERSION=1.0.0\nHS_MCP_PROTOCOL_VERSION=2025-11-25\n```\n\nOr programmatically:\n\n```go\nsrv, _ := server.NewServer(\n    server.WithMCPSupport(\"MyServer\", \"1.0.0\"),\n    server.WithMCPBuiltinTools(true),\n    server.WithMCPBuiltinResources(true),\n)\n```\n\nBuilt-in MCP tools and resources are off by default; you opt in per server.\nCustom MCP integrations can register tools, static resources, resource\ntemplates, and subscribable resource templates for SSE/stdio update\nnotifications.\n\n## Request binding \u0026 validation\n\nParse a JSON body, query string, or form into a typed struct, then validate\nagainst struct-tag rules. Zero external dependencies; the rules cover the\nchecks that show up in 90% of input-handling code.\n\nThe fastest path is `server.JSONHandler`, which wraps bind + validate +\nrespond around a typed business function. The handler shrinks to the one\nline of logic that actually changes per endpoint:\n\n```go\ntype CreateUser struct {\n    Name  string `json:\"name\"  validate:\"required,min=2,max=64\"`\n    Email string `json:\"email\" validate:\"required,email\"`\n    Age   int    `json:\"age\"   validate:\"required,min=13,max=120\"`\n    Role  string `json:\"role\"  validate:\"required,oneof=admin user guest\"`\n}\n\nsrv.POST(\"/users\", server.JSONHandler(\n    func(ctx context.Context, in CreateUser) (User, error) {\n        return createUser(ctx, in)\n    },\n))\n```\n\n`JSONHandler` decodes the body, runs `validate:\"...\"` rules, calls your\nfunction with `r.Context()`, then JSON-encodes the result with 200. A\n`*server.ValidationError` becomes a per-field 400 envelope; an error\nimplementing `HTTPStatus() int` (e.g. `server.NewStatusError(404, \"…\")`)\nsets its own status; everything else is a 500. Returning `struct{}` or a\nnil pointer writes 204.\n\nWhen you need more control — custom headers, streaming, a non-JSON body —\ndrop to the lower-level binders:\n\n```go\nsrv.HandleFunc(\"/users\", func(w http.ResponseWriter, r *http.Request) {\n    var u CreateUser\n    if err := server.BindJSON(r, \u0026u); err != nil {\n        var verr *server.ValidationError\n        if errors.As(err, \u0026verr) {\n            // verr.Fields is []*FieldError — render however you want.\n        }\n        http.Error(w, err.Error(), http.StatusBadRequest)\n        return\n    }\n    // u is valid; carry on.\n})\n```\n\nAvailable rules: `required, min, max, len, email, url, oneof`.\n\nEntry points:\n\n- `server.JSONHandler[In, Out](fn)` — typed wrapper: bind + validate + respond.\n- `server.JSONEcho[T]()` — shorthand for validate-and-pass-through (webhook acks, dev stubs).\n- `server.Bind(r, dst)` — picks JSON / form / query by `Content-Type`.\n- `server.BindJSON(r, dst)` — JSON with `DisallowUnknownFields` and a 1 MiB body cap.\n- `server.BindQuery(r, dst)` — URL query parameters (slices via repeated keys).\n- `server.BindForm(r, dst)` — `application/x-www-form-urlencoded` or `multipart/form-data`.\n- `server.Validate(dst)` — run rules without binding.\n\nSee [examples/binding](./examples/binding/) for both shapes side-by-side.\n\n## Middleware\n\n`NewServer` wires recovery, request logging, and metrics. Apply security stacks per route:\n\n```go\nsrv, _ := server.NewServer()\nsrv.AddMiddleware(\"/api\", server.RateLimitMiddleware(srv))\nsrv.AddMiddlewareStack(\"/web\", server.SecureWeb(srv.Options))\n```\n\n## Deferred initialization\n\nServe `/healthz` immediately, return 503 for application routes, flip to ready once\nbootstrap (and any `WithOnReady` hooks) succeed:\n\n```go\nsrv, _ := server.NewServer(\n    server.WithDeferredInit(func(ctx context.Context, app *server.Server) error {\n        return warmCaches(ctx)\n    }),\n    server.WithOnReady(func(ctx context.Context, app *server.Server) error {\n        app.HandleFunc(\"/api/users\", usersHandler)\n        return nil\n    }),\n)\n```\n\nUse `WithDeferredInitStopOnFailure(false)` to keep the listener up after a bootstrap\nfailure, then call `CompleteDeferredInit(ctx, nil)` once the issue is resolved.\n\nSee [examples/deferred-init](./examples/deferred-init/).\n\n## Examples\n\n[examples/](./examples) covers HTTP, WebSocket, MCP (HTTP/SSE/stdio/discovery/extensions),\nauth + RBAC, htmx, and static file serving. Each example is a self-contained\n`go run .` target.\n\n## Documentation\n\n- [Roadmap](./docs/ROADMAP.md) — what's planned and why.\n- [Architecture](./ARCHITECTURE.md)\n- [API reference](https://pkg.go.dev/github.com/osauer/hyperserve)\n- [MCP guide](./docs/MCP_GUIDE.md)\n- [WebSocket guide](./docs/WEBSOCKET_GUIDE.md)\n- [Production guide](./docs/PRODUCTION.md) — TLS, reverse proxy, CDN gotchas, MCP threat model.\n- [Scaffolding guide](./docs/SCAFFOLDING.md)\n- [Contributing](./CONTRIBUTING.md) — local CI gate + code map.\n- [Security policy](./SECURITY.md)\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosauer%2Fhyperserve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosauer%2Fhyperserve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosauer%2Fhyperserve/lists"}