{"id":47978740,"url":"https://github.com/zoobz-io/rocco","last_synced_at":"2026-04-04T10:59:39.584Z","repository":{"id":319900329,"uuid":"1079967247","full_name":"zoobz-io/rocco","owner":"zoobz-io","description":"Type-safe HTTP framework for Go with automatic OpenAPI generation","archived":false,"fork":false,"pushed_at":"2026-03-29T19:20:59.000Z","size":17499,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T10:59:38.719Z","etag":null,"topics":["framework","go","golang","http","openapi","rest-api","zoobzio"],"latest_commit_sha":null,"homepage":"https://rocco.zoobz.io","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/zoobz-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","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":"2025-10-20T16:59:57.000Z","updated_at":"2026-03-28T00:31:43.000Z","dependencies_parsed_at":"2026-01-28T19:00:56.026Z","dependency_job_id":null,"html_url":"https://github.com/zoobz-io/rocco","commit_stats":null,"previous_names":["zoobzio/rocco","zoobz-io/rocco"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/zoobz-io/rocco","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoobz-io%2Frocco","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoobz-io%2Frocco/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoobz-io%2Frocco/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoobz-io%2Frocco/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zoobz-io","download_url":"https://codeload.github.com/zoobz-io/rocco/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoobz-io%2Frocco/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31397056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: 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":["framework","go","golang","http","openapi","rest-api","zoobzio"],"created_at":"2026-04-04T10:59:37.758Z","updated_at":"2026-04-04T10:59:39.557Z","avatar_url":"https://github.com/zoobz-io.png","language":"Go","readme":"# rocco\n\n[![CI Status](https://github.com/zoobz-io/rocco/workflows/CI/badge.svg)](https://github.com/zoobz-io/rocco/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/zoobz-io/rocco/graph/badge.svg?branch=main)](https://codecov.io/gh/zoobz-io/rocco)\n[![Go Report Card](https://goreportcard.com/badge/github.com/zoobz-io/rocco)](https://goreportcard.com/report/github.com/zoobz-io/rocco)\n[![CodeQL](https://github.com/zoobz-io/rocco/workflows/CodeQL/badge.svg)](https://github.com/zoobz-io/rocco/security/code-scanning)\n[![Go Reference](https://pkg.go.dev/badge/github.com/zoobz-io/rocco.svg)](https://pkg.go.dev/github.com/zoobz-io/rocco)\n[![License](https://img.shields.io/github/license/zoobz-io/rocco)](LICENSE)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/zoobz-io/rocco)](go.mod)\n[![Release](https://img.shields.io/github/v/release/rocco)](https://github.com/zoobz-io/rocco/releases)\n\nType-safe HTTP framework for Go with automatic OpenAPI generation.\n\nDefine your request and response types, wire up handlers, and get a fully-documented API with validation baked in.\n\n## Types Become Endpoints\n\n```go\ntype CreateUserInput struct {\n    Name  string `json:\"name\" validate:\"required,min=2\"`\n    Email string `json:\"email\" validate:\"required,email\"`\n}\n\ntype UserOutput struct {\n    ID    string `json:\"id\"`\n    Name  string `json:\"name\"`\n    Email string `json:\"email\"`\n}\n\nhandler := rocco.NewHandler[CreateUserInput, UserOutput](\n    \"create-user\", \"POST\", \"/users\",\n    func(req *rocco.Request[CreateUserInput]) (UserOutput, error) {\n        return UserOutput{\n            ID:    \"usr_123\",\n            Name:  req.Body.Name,\n            Email: req.Body.Email,\n        }, nil\n    },\n).WithErrors(rocco.ErrBadRequest, rocco.ErrConflict)\n```\n\nYour types define the contract. Rocco handles validation, serialization, error responses, and OpenAPI schema generation — all derived from the same source of truth.\n\n## Install\n\n```bash\ngo get github.com/zoobz-io/rocco\n```\n\nRequires Go 1.24+.\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    \"github.com/zoobz-io/openapi\"\n    \"github.com/zoobz-io/rocco\"\n)\n\ntype CreateUserInput struct {\n    Name  string `json:\"name\" validate:\"required,min=2\"`\n    Email string `json:\"email\" validate:\"required,email\"`\n}\n\ntype UserOutput struct {\n    ID    string `json:\"id\"`\n    Name  string `json:\"name\"`\n    Email string `json:\"email\"`\n}\n\nfunc main() {\n    engine := rocco.NewEngine()\n\n    // Configure OpenAPI metadata\n    engine.WithOpenAPIInfo(openapi.Info{\n        Title:   \"User API\",\n        Version: \"1.0.0\",\n    })\n\n    handler := rocco.NewHandler[CreateUserInput, UserOutput](\n        \"create-user\", \"POST\", \"/users\",\n        func(req *rocco.Request[CreateUserInput]) (UserOutput, error) {\n            return UserOutput{\n                ID:    \"usr_123\",\n                Name:  req.Body.Name,\n                Email: req.Body.Email,\n            }, nil\n        },\n    ).\n        WithSummary(\"Create a new user\").\n        WithTags(\"users\").\n        WithSuccessStatus(201).\n        WithErrors(rocco.ErrBadRequest, rocco.ErrUnprocessableEntity)\n\n    engine.WithHandlers(handler)\n\n    // OpenAPI spec at /openapi, interactive docs at /docs\n    fmt.Println(\"Server listening on :8080\")\n    engine.Start(rocco.HostAll, 8080)\n}\n```\n\n## Capabilities\n\n| Feature            | Description                                         | Docs                                      |\n| ------------------ | --------------------------------------------------- | ----------------------------------------- |\n| Type-Safe Handlers | Generic handlers with compile-time type checking    | [Handlers](docs/3.guides/1.handlers.md)   |\n| Server-Sent Events | Built-in SSE support for real-time streaming        | [Streaming](docs/3.guides/6.streaming.md) |\n| Automatic OpenAPI  | Generate OpenAPI 3.1.0 specs from your types        | [OpenAPI](docs/3.guides/4.openapi.md)     |\n| Request Validation | Struct tag validation with detailed error responses | [Concepts](docs/2.learn/2.concepts.md)    |\n| Sentinel Errors    | Typed HTTP errors with OpenAPI schema generation    | [Errors](docs/3.guides/2.errors.md)       |\n| Lifecycle Events   | Observable signals for logging, metrics, tracing    | [Events](docs/5.reference/3.events.md)    |\n\n## Why rocco?\n\n- **Type-safe** — Generic handlers catch errors at compile time, not runtime\n- **Self-documenting** — OpenAPI specs generated from the same types that validate requests\n- **Explicit** — No magic, no hidden behaviors, no struct tag DSLs for routing\n- **Chi-powered** — Built on the battle-tested Chi router with full middleware compatibility\n- **Observable** — Lifecycle events via [capitan](https://github.com/zoobz-io/capitan) for metrics and tracing\n- **Streaming-native** — First-class SSE support with typed event streams\n\n## Contract-First by Default\n\nRocco enables a pattern: **define types once, derive everything else**.\n\nYour request and response structs become the single source of truth. From them, rocco derives validation rules, OpenAPI schemas, error contracts, and documentation.\n\n**Define a type:**\n\n```go\ntype CreateOrderInput struct {\n    CustomerID string  `json:\"customer_id\" validate:\"required,uuid4\" description:\"Customer UUID\"`\n    Items      []Item  `json:\"items\" validate:\"required,min=1\" description:\"Order line items\"`\n    Total      float64 `json:\"total\" validate:\"required,gt=0\" description:\"Order total in USD\"`\n}\n```\n\n**Get an OpenAPI schema:**\n\n```yaml\nCreateOrderInput:\n  type: object\n  required: [customer_id, items, total]\n  properties:\n    customer_id:\n      type: string\n      format: uuid\n      description: Customer UUID\n    items:\n      type: array\n      minItems: 1\n      description: Order line items\n      items:\n        $ref: '#/components/schemas/Item'\n    total:\n      type: number\n      exclusiveMinimum: 0\n      description: Order total in USD\n```\n\n**Get consistent validation errors:**\n\n```json\n{\n  \"code\": \"VALIDATION_FAILED\",\n  \"message\": \"validation failed\",\n  \"details\": {\n    \"fields\": [\n      {\"field\": \"customer_id\", \"message\": \"must be a valid UUID\"},\n      {\"field\": \"total\", \"message\": \"must be greater than 0\"}\n    ]\n  }\n}\n```\n\nNo separate schema files. No manual sync between code and docs. The types ARE the contract.\n\n## Documentation\n\n- [Overview](docs/1.overview.md) — Design philosophy and architecture\n\n### Learn\n\n- [Quickstart](docs/2.learn/1.quickstart.md) — Get started in minutes\n- [Concepts](docs/2.learn/2.concepts.md) — Handlers, requests, validation, errors\n- [Architecture](docs/2.learn/3.architecture.md) — Internal design and components\n\n### Guides\n\n- [Handlers](docs/3.guides/1.handlers.md) — Request/response handlers and streaming\n- [Errors](docs/3.guides/2.errors.md) — Sentinel errors and custom error types\n- [Authentication](docs/3.guides/3.authentication.md) — Identity extraction and middleware\n- [OpenAPI](docs/3.guides/4.openapi.md) — Schema generation and customization\n- [Best Practices](docs/3.guides/5.best-practices.md) — Patterns and recommendations\n- [Streaming](docs/3.guides/6.streaming.md) — Server-Sent Events\n\n### Cookbook\n\n- [CRUD API](docs/4.cookbook/1.crud-api.md) — Complete REST API example\n- [Authentication](docs/4.cookbook/2.authentication.md) — JWT and session patterns\n- [Observability](docs/4.cookbook/3.observability.md) — Logging, metrics, tracing\n- [Realtime](docs/4.cookbook/4.realtime.md) — SSE patterns and use cases\n\n### Reference\n\n- [API](docs/5.reference/1.api.md) — Complete function documentation\n- [Errors](docs/5.reference/2.errors.md) — All sentinel errors and detail types\n- [Events](docs/5.reference/3.events.md) — Lifecycle signals and field keys\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoobz-io%2Frocco","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzoobz-io%2Frocco","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoobz-io%2Frocco/lists"}